> ## 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

> Executable v0 event envelope, minimum event types, and current ingestion rules.

# 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

```json theme={null}
{
  "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"
  }
}
```

```json theme={null}
{
  "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.

## 相关页面

* [Gateway to Probe Command Contract v0](/agent-platform/contracts/gateway-to-probe-command-v0/index)
* [Audit and Metadata Policy v0](/agent-platform/operations/audit-metadata-v0/index)
* [Self-heal Policy v0](/agent-platform/operations/self-heal-v0/index)