跳转到主要内容

​
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

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

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

​
相关页面