跳转到主要内容

​
Probe Capability Contract v0

​
Scope

Defines the minimum capability payload that a Probe must report to Gateway for registration, compatibility checks, scheduling decisions, and health gating. This contract is normative for v0 and follows P0/P1 freeze decisions.

​
Terminology

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

​
Normative Spec

​
Required Fields

Probe capability payload MUST include:
  • 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

For v0, Probe SHOULD declare support for:
  • codex
  • claude_code
  • opencode

​
Health Requirements

health MUST expose at least:
  • overall probe status
  • channel-level status for ssh_remote and dialog
  • runtime health summary
Allowed status values: healthy, degraded, unhealthy.

​
Compatibility Rule

Gateway MUST validate schema_version and reject unsupported versions. Gateway MUST gate scheduling against capability and health constraints.

​
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 report itself MUST be auditable via metadata events.
  • Probe capability MUST NOT imply control-plane authority.
  • Gateway remains the sole decision authority for scheduling/policy.

​
Status

Current status: draft Source discussions:
  • 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.

​
相关页面