跳转到主要内容

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

​
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

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

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

​
相关页面