Skip to main content

​
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

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

​
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

{
  "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"
  }
}

{
  "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.