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

# Gateway to Probe Command Contract v0

> Executable v0 command envelope, minimal command set, and current Probe-side validation rules.

# Gateway to Probe Command Contract v0

## Scope

Defines the current executable v0 command contract that Gateway uses to send authorized intents to Probe in AIOS.

This page covers the common command envelope, the current executable v0 command set, payload expectations, Probe-side validation, and the boundary between platform commands and DevBox-internal coding-tool activity.

This is an executable freeze for the currently implemented subset. It does not reserve or promise additional future command types beyond what is listed here.

## Terminology

* **Gateway**: the sole control-plane authority for desired state, routing intent, approval, and lifecycle decisions.
* **Probe**: the host-side data-plane runtime that executes authorized commands against local Worker Sandbox and channel resources.
* **Lease epoch**: the fencing token that invalidates stale commands.
* **Desired version**: monotonically increasing desired-state revision issued by Gateway.

## Normative Spec

### Command Principles

Gateway-issued commands MUST follow these rules in v0:

1. Gateway is the only authoritative command source.
2. Every command MUST be constrained by `lease_epoch`.
3. Probe MUST execute authorized intent only and MUST NOT invent new desired state.
4. Probe MUST treat `command_id` as an idempotency key.

### Common Command Envelope

All Gateway-to-Probe commands MUST include:

* `command_id`
* `command_type`
* `resource_id`
* `session_id`
* `desired_version`
* `lease_epoch`
* `deadline_unix`
* `reason`
* `payload`

Optional fields:

* `approval_ref`
* `snapshot_ref`
* `retry_count`

### Field Rules

* `command_id` MUST be unique for idempotent execution tracking.
* `command_type` MUST be one of the supported v0 command enums.
* `resource_id` MUST identify the local runtime target such as DevBox, Worker Sandbox, or runtime unit.
* `desired_version` MUST be used by Probe to reject stale desired-state mutations.
* `lease_epoch` MUST be used for fencing stale commands.
* `deadline_unix` MUST be enforced by Probe; expired commands MUST NOT execute.
* `approval_ref` MAY appear for platform-level risky actions, but MUST NOT be used for DevBox-internal Codex, Claude Code, or OpenCode command approval.
* `retry_count` MAY be attached by Gateway as metadata for bounded recovery continuity and MUST NOT be treated as caller-owned policy input.

### Current Executable v0 Command Set

Probe currently supports this executable v0 command set:

* `StartSession`
* `StopSession`
* `AttachChannel`
* `DetachChannel`
* `ReportHealth`

### Channel Command Rules

* `AttachChannel` and `DetachChannel` MUST only target top-level channel types `ssh_remote` or `dialog`.
* When `channel_type=ssh_remote`, `remote_mode` MUST be present and MUST be either `ide_primary` or `terminal_fallback`.
* `dialog.target` MAY be any supported v0 target such as `codex`, `claude_code`, `opencode`, `wechat`, or `telegram`.

### Probe Validation Rules

Before execution, Probe MUST validate:

1. `command_id`, `session_id`, and `command_type` are present.
2. `deadline_unix` has not expired when provided.
3. `approval_ref` exists when the current command type requires platform-level approval.
4. `lease_epoch` is not older than the currently valid lease when leaseguard validation is applied.
5. `desired_version` is not older than the local known desired version when leaseguard validation is applied.

Capability-matching and broader idempotency semantics remain intended architecture direction, but are not yet fully enforced by the current executable validation path.

### Approval and Authority Boundary

* Platform-level risky actions MAY require `approval_ref`.
* DevBox-internal coding-tool commands remain outside AIOS secondary approval.
* Scheduler-triggered execution MUST still materialize through this contract before Probe acts.

## Examples

```json theme={null}
{
  "command_id": "cmd-001",
  "command_type": "StartSession",
  "resource_id": "devbox-001",
  "session_id": "sess-001",
  "desired_version": 3,
  "lease_epoch": 12,
  "deadline_unix": 1774353630,
  "reason": "scheduler_trigger",
  "approval_ref": null,
  "snapshot_ref": null,
  "workspace_id": "ws-001",
  "agent_id": "codex",
  "payload": {
    "reason": "manual"
  }
}
```

```json theme={null}
{
  "command_id": "cmd-002",
  "command_type": "AttachChannel",
  "resource_id": "devbox-001",
  "session_id": "sess-001",
  "desired_version": 4,
  "lease_epoch": 12,
  "deadline_unix": 1774353660,
  "reason": "manual_attach",
  "payload": {
    "channel_id": "dialog:codex",
    "route_key": "dialog.codex",
    "reason": "manual_attach"
  }
}
```

## Error & Recovery

* Expired `deadline_unix`: Probe MUST reject without side effects.
* Stale `lease_epoch`: Probe MUST reject as stale lease when leaseguard validation is active.
* Older `desired_version`: Probe MUST reject as stale desired intent when leaseguard validation is active.
* Missing required envelope fields: Probe MUST reject as invalid command.

## Security & Audit

* Commands MUST be auditable through metadata with `command_id`, `reason`, `lease_epoch`, and correlation fields.
* Gateway remains the sole authority for desired state and approval decisions.
* Probe validation is local enforcement, not policy authorship.
* Commands MUST NOT be used to backdoor approval for DevBox-internal coding-tool operations.

## Status

Current status: `active`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-24-gateway-to-probe-command-contract-v0-draft.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p0-freeze-result-accepted.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md`

## Changelog

* 2026-03-24: Initial formal v0 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.

## 相关页面

* [Probe to Gateway Event Contract v0](/agent-platform/contracts/probe-to-gateway-event-v0/index)
* [Probe Architecture v0](/agent-platform/architecture/probe-architecture/index)
* [Scheduler v0](/agent-platform/operations/scheduler-v0/index)