Skip to main content

​
Probe to Gateway Event Contract v0

​
Scope

Defines the minimum append-only 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.

​
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
  • 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.
  • 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 phase transitions and reason.
  • LeaseHeartbeat MUST report current health and latest heartbeat time.
  • ChannelStatusChanged MUST report channel type, target when relevant, current status, and reason.
  • Recovery events MUST report at least action and retry_count, with reason or error_code where appropriate.
  • CapabilityReported SHOULD reference the active capability schema version.

​
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": "2026-03-24T12:00:00Z",
  "correlation_id": "corr-001",
  "causation_id": "cmd-001",
  "payload": {
    "previous_phase": "starting",
    "current_phase": "ready",
    "reason": "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": "2026-03-24T12:02:00Z",
  "correlation_id": "corr-002",
  "causation_id": "cmd-002",
  "payload": {
    "channel_type": "dialog",
    "status": "healthy",
    "target": "wechat",
    "reason": "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: draft 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.