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

> Normative command envelope, command set, and Probe-side validation rules.

# Gateway to Probe Command Contract v0

## Scope

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

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

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

### v0 Command Set

Probe MUST support these v0 command types:

* `Allocate`
* `BindWorkload`
* `StartSession`
* `AttachChannel`
* `DetachChannel`
* `UpdateDesiredState`
* `Checkpoint`
* `Drain`
* `Terminate`
* `RevokeLease`

### 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. `lease_epoch` matches the currently valid lease.
2. `desired_version` is not older than the local known version.
3. `deadline` has not expired.
4. `command_id` has not already been completed for the same effective intent.
5. `approval_ref` exists when the action requires platform-level approval.
6. Requested channels and modes are declared in Probe capability.

### 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": "2026-03-24T12:00:30Z",
  "reason": "scheduler_trigger",
  "approval_ref": null,
  "snapshot_ref": null,
  "payload": {
    "workspace_id": "ws-001",
    "agent_id": "codex",
    "trigger": "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": "2026-03-24T12:01:00Z",
  "reason": "manual_attach",
  "payload": {
    "channel_type": "ssh_remote",
    "target": "vscode",
    "remote_mode": "ide_primary"
  }
}
```

## Error & Recovery

* Stale `lease_epoch`: Probe MUST reject the command and fence execution.
* Older `desired_version`: Probe MUST reject as stale intent.
* Expired `deadline`: Probe MUST reject without side effects.
* Unsupported `channel_type` or `remote_mode`: Probe MUST reject as capability mismatch.
* Duplicate `command_id`: Probe MUST treat as idempotent replay and avoid duplicate mutation.

## 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: `draft`

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.

## Related Pages

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