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

# Channel Contract v0

> Canonical contract for ssh_remote and dialog channels.

# Channel Contract v0

## Scope

Defines the canonical channel contract for AIOS top-level channels in v0:

* `ssh_remote`
* `dialog`

This page specifies envelope fields, event classes, routing identity rules, and data-boundary constraints.

## Terminology

* **Top-level channels**: only `ssh_remote` and `dialog`.
* **Remote mode**: `ide_primary` or `terminal_fallback` under `ssh_remote`.
* **Target**: concrete endpoint/tool/channel target in `dialog` (e.g. codex/wechat/telegram).

## Normative Spec

### Channel Set

AIOS v0 MUST expose only two top-level channels:

1. `ssh_remote`
2. `dialog`

`ssh_remote` MUST include `remote_mode` and only allow:

* `ide_primary`
* `terminal_fallback`

### Dialog Event Set

`dialog` event types are fixed in v0:

* `message`
* `tool_call`
* `status`
* `error`

### Envelope (minimum)

All channel messages/events MUST include:

* `channel_type`
* `session_id`
* `stream_id`
* `seq`
* `timestamp`
* `correlation_id`
* `target`
* `event_type`
* `payload`

Recommended optional fields:

* `workspace_id`
* `agent_id`
* `message_id`
* `dedup_key`
* `resume_cursor`
* `status_code`
* `error_code`
* `retry_count`

### Routing Identity Rule

* Stable routing key MUST be `workspace_id + agent_id`.
* `session_id` is transport/session state only.

### Data Boundary Rule

* `dialog` and terminal content under `ssh_remote` are forward-only.
* Platform persistence is metadata-only.

## Examples

```json theme={null}
{
  "channel_type": "dialog",
  "session_id": "sess-001",
  "stream_id": "stream-001",
  "seq": 12,
  "timestamp": "2026-03-24T12:00:00Z",
  "correlation_id": "corr-001",
  "target": "wechat",
  "event_type": "message",
  "payload": {"text": "hello"}
}
```

```json theme={null}
{
  "channel_type": "ssh_remote",
  "session_id": "sess-002",
  "stream_id": "stream-009",
  "seq": 3,
  "timestamp": "2026-03-24T12:05:00Z",
  "correlation_id": "corr-002",
  "target": "vscode",
  "event_type": "status",
  "payload": {"remote_mode": "ide_primary"}
}
```

## Error & Recovery

* Invalid `channel_type` or `remote_mode`: reject.
* Missing required envelope fields: reject.
* Reconnect semantics for `dialog` MUST support at-least-once + receiver idempotency.
* `ide_primary` failures MAY downgrade to `terminal_fallback` with explicit reason code.

## Security & Audit

* All channel events MUST be traceable via `correlation_id`.
* No transcript persistence in platform storage.
* Gateway remains sole routing/policy authority.

## Status

Current status: `draft`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-24-channel-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 channel set, envelope, routing, and forward-only constraints.

## 相关页面

* [Probe Capability Contract v0](/agent-platform/contracts/probe-capability-v0/index)
* [Channel Adapter Contract v0](/agent-platform/contracts/channel-adapter-v0/index)
* [Dialog Ecosystem v0](/agent-platform/integrations/dialog-ecosystem/index)