​

Probe Capability Contract v0

​

Scope

​

Terminology

• Probe: host-side runtime controller for DevBox/Worker Sandbox lifecycle and channel/runtime status reporting.
• Gateway: sole control-plane authority.
• Capability: declared feature set and limits of a Probe instance.

​

Normative Spec

​

Required Fields

• schema_version
• probe_id
• adapter_versions
• supported_channels
• supported_remote_modes
• agent_adapters
• limits
• health
• last_heartbeat_at

​

Channel and Mode Constraints

• supported_channels MUST only include ssh_remote and/or dialog.
• supported_remote_modes MUST only include ide_primary and/or terminal_fallback.

​

Agent Adapter Declaration

• codex
• claude_code
• opencode

​

Health Requirements

• overall probe status
• channel-level status for ssh_remote and dialog
• runtime health summary

​

Compatibility Rule

​

Examples

{
  "schema_version": "probe-capability/v0",
  "probe_id": "probe-host-01",
  "adapter_versions": {
    "ssh_remote": "1.0.0",
    "dialog": "1.0.0",
    "codex": "0.9.2",
    "claude_code": "1.1.0",
    "opencode": "0.8.3"
  },
  "supported_channels": ["ssh_remote", "dialog"],
  "supported_remote_modes": ["ide_primary", "terminal_fallback"],
  "agent_adapters": ["codex", "claude_code", "opencode"],
  "limits": {
    "max_sessions": 32,
    "max_parallel_exec": 16,
    "max_ptys": 8,
    "max_dialog_streams": 16
  },
  "health": {
    "overall": "healthy",
    "ssh_remote": "healthy",
    "dialog": "healthy",
    "runtime": "healthy"
  },
  "last_heartbeat_at": "2026-03-24T12:00:00Z"
}

​

Error & Recovery

• Unsupported schema_version: reject registration/update.
• Missing required fields: reject with validation error.
• health.overall=unhealthy: Gateway SHOULD stop assigning new work.
• Heartbeat timeout: treat Probe as stale and trigger lease fencing.

​

Security & Audit

• Capability reports MUST be auditable via metadata events.
• Probe capability MUST NOT imply control-plane authority.
• Gateway remains sole authority for scheduling and policy.

​

Status

• docs/maintainers/conversation-records/agent-platform/2026-03-24-probe-capability-contract-v0-draft.md
• docs/maintainers/conversation-records/agent-platform/2026-03-24-p0-freeze-result-accepted.md

​

Changelog

• 2026-03-24: Initial skeleton created.
• 2026-03-24: Added normative v0 capability fields and validation rules.

​

Related Pages

• Channel Contract v0
• Gateway to Probe Command Contract v0
• Probe to Gateway Event Contract v0