跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Probe to Gateway Event Contract v0

​
Scope

Defines the current executable append-only v0 event contract that Probe uses to report lifecycle, lease, channel, recovery, and capability signals back to Gateway. The contract is metadata-centered and aligned with forward-only, no-transcript persistence rules. This page freezes the currently implemented event subset and envelope fields; it does not document hypothetical future fields as if they were already executable.

​
Terminology

  • Event: immutable metadata record emitted by Probe.
  • Monotonic sequence: Probe-local increasing event sequence used for ordering and deduplication.
  • Causation: upstream command or event that caused the current event.

​
Normative Spec

​
Event Principles

Probe-to-Gateway events MUST follow these rules in v0:
  1. Events are append-only.
  2. Delivery semantics are at-least-once.
  3. Gateway MUST support idempotent ingestion.
  4. Events MUST rely on metadata, not transcript persistence.

​
Common Event Envelope

All events MUST include:
  • event_id
  • event_type
  • session_id
  • resource_id
  • lease_epoch
  • monotonic_seq
  • timestamp_unix
  • correlation_id
  • causation_id
  • payload

​
Field Rules

  • event_id MUST be unique per event emission.
  • lease_epoch MUST allow Gateway to discard stale events.
  • monotonic_seq MUST increase monotonically per Probe event stream.
  • timestamp_unix MUST carry the emitted event timestamp in unix seconds.
  • correlation_id MUST support trace continuity across command, session, and channel flows.
  • causation_id SHOULD point to the originating command_id or prior event when applicable.

​
v0 Event Set

Probe MUST support these v0 event types:
  • PhaseChanged
  • LeaseHeartbeat
  • ChannelStatusChanged
  • RecoveryAttempted
  • RecoverySucceeded
  • RecoveryFailed
  • SnapshotReady
  • ResourcePressure
  • AdapterFault
  • CapabilityReported

​
Event Payload Requirements

  • PhaseChanged MUST report the current status and message.
  • LeaseHeartbeat MUST report current health via event payload status/message fields.
  • ChannelStatusChanged MUST report channel lifecycle through payload status/message fields.
  • Recovery events MUST report retry_count, with message or error_code where appropriate.
  • CapabilityReported SHOULD reference the active capability schema version through event payload message plus the capability report contract.

​
Multi-target Dialog Rule

For dialog-backed targets such as codex, claude_code, opencode, wechat, and telegram, Probe MUST use the same event schema and MUST NOT introduce target-specific persistence exceptions.

​
Examples

{
  "event_id": "evt-001",
  "event_type": "PhaseChanged",
  "session_id": "sess-001",
  "resource_id": "devbox-001",
  "lease_epoch": 12,
  "monotonic_seq": 100,
  "timestamp_unix": 1774353600,
  "correlation_id": "corr-001",
  "causation_id": "cmd-001",
  "payload": {
    "status": "ready",
    "message": "runtime_boot_ok"
  }
}

{
  "event_id": "evt-009",
  "event_type": "ChannelStatusChanged",
  "session_id": "sess-001",
  "resource_id": "devbox-001",
  "lease_epoch": 12,
  "monotonic_seq": 109,
  "timestamp_unix": 1774353720,
  "correlation_id": "corr-002",
  "causation_id": "cmd-002",
  "payload": {
    "status": "healthy",
    "message": "connected"
  }
}

​
Error & Recovery

  • Stale lease_epoch: Gateway MUST ignore or reject the event for state mutation purposes.
  • Duplicate event_id or replayed monotonic_seq: Gateway MUST ingest idempotently.
  • Missing required envelope fields: Gateway MUST reject as invalid event.
  • Probe recovery attempts MUST be surfaced through typed recovery events rather than silent local retries.

​
Security & Audit

  • Event ingestion is the canonical source for runtime audit breadcrumbs.
  • Events MUST remain metadata-only and MUST NOT carry persisted transcript bodies as payload substitutions.
  • correlation_id and causation_id MUST preserve cross-layer traceability.

​
Status

Current status: active Source discussions:
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-probe-to-gateway-event-contract-v0-draft.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-p0-freeze-result-accepted.md

​
Changelog

  • 2026-03-24: Initial formal v0 event contract created from frozen discussion draft.
  • 2026-04-02: Narrowed the page to the currently executable v0 subset so it can be validated by repository-local contract checks.

​
相关页面