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

# Probe Capability Contract v0

> Probe capability schema, compatibility, and validation rules.

# 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

```json theme={null}
{
  "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.

## 相关页面

* [Channel Contract v0](/agent-platform/contracts/channel-v0/index)
* [Gateway to Probe Command Contract v0](/agent-platform/contracts/gateway-to-probe-command-v0/index)
* [Probe to Gateway Event Contract v0](/agent-platform/contracts/probe-to-gateway-event-v0/index)