Skip to main content

​
Channel Adapter Contract v0

​
Scope

Defines the minimum AIOS v0 contract for Channel Adapter implementations that bridge external channels such as WeChat or Telegram into the canonical dialog model. This page covers adapter responsibility boundaries, capability declaration, canonical inbound events, canonical outbound actions, configuration mapping, and health reporting.

​
Terminology

  • Channel Adapter: the transport and protocol bridge between an external channel and the AIOS canonical dialog model.
  • Canonical inbound event: normalized event emitted from adapter into AIOS.
  • Canonical outbound action: normalized action received by adapter from AIOS.
  • Supported target: channel target values that the adapter knows how to translate.

​
Normative Spec

​
Adapter Boundary

Channel Adapter sits between the external channel transport and the AIOS canonical dialog model. The adapter MUST:
  1. receive external channel messages
  2. normalize them into canonical inbound events
  3. receive canonical outbound actions from AIOS
  4. translate them into channel-specific output
The adapter MUST NOT own:
  • scheduling
  • global route decisions
  • canonical session authority
  • cross-tenant policy
  • transcript persistence

​
Capability Declaration

Adapter capability payload MUST include:
  • adapter_id
  • adapter_version
  • supported_targets
  • supported_features
  • health

​
Required Message Fields

Canonical adapter event or action models MUST include:
  • channel_type
  • target
  • session_id
  • message_id when message-oriented
  • event_type
  • payload
  • timestamp
  • correlation_id

​
Canonical Inbound Event

Canonical inbound events SHOULD include:
  • workspace_id
  • agent_id
  • session_id
  • message_id
  • event_type
  • timestamp
  • correlation_id
  • payload
Allowed v0 inbound event types:
  • message
  • status
  • error
  • attachment_meta

​
Canonical Outbound Action

Allowed v0 outbound action types:
  • message
  • status
  • error
  • approval_request

​
Config Mapping Rule

Every adapter MUST be representable by the Channel Integration Page model and MUST map cleanly into these top-level groups:
  • auth
  • config
  • route
  • policy

​
Health Reporting

Adapter health model MUST expose at least:
  • health
  • last_error_code
  • last_seen_at
Probe MUST be able to map adapter health into:
  • ChannelStatusChanged
  • AdapterFault

​
Examples

​
Capability declaration

{
  "adapter_id": "wechat",
  "adapter_version": "1.0.0",
  "supported_targets": ["wechat"],
  "supported_features": ["text", "voice_to_text"],
  "health": "healthy"
}

​
Canonical inbound event

{
  "channel_type": "dialog",
  "target": "telegram",
  "workspace_id": "ws-001",
  "agent_id": "codex",
  "session_id": "sess-001",
  "message_id": "msg-001",
  "event_type": "message",
  "timestamp": "2026-03-24T12:00:00Z",
  "correlation_id": "corr-001",
  "payload": {
    "text": "hello"
  }
}

​
Canonical outbound action

{
  "channel_type": "dialog",
  "target": "wechat",
  "session_id": "sess-001",
  "event_type": "message",
  "payload": {
    "text": "job finished"
  }
}

​
Error & Recovery

  • Adapter transport failures MUST surface through health and fault events, not hidden retry loops.
  • Adapter replay or reconnect handling MUST preserve forward-only transcript boundaries.
  • Unsupported channel payloads SHOULD degrade to metadata-oriented error or attachment_meta events rather than inventing non-canonical event classes.

​
Security & Audit

  • Adapter implementations MUST not persist full dialog transcript bodies as a long-term store.
  • Adapter configuration and health state MUST be auditable through metadata.
  • Adapter reuse from external ecosystems MUST remain wrapped by AIOS canonical contracts.

​
Status

Current status: draft Source discussions:
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-channel-adapter-contract-v0-draft.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-dialog-channel-ecosystem-reuse-strategy-v0.md
  • docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md

​
Changelog

  • 2026-03-24: Initial formal channel adapter specification created from frozen discussion drafts.