> ## 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 Adapter Contract v0

> Canonical adapter boundary for external channels, inbound normalization, outbound actions, and health reporting.

# 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

```json theme={null}
{
  "adapter_id": "wechat",
  "adapter_version": "1.0.0",
  "supported_targets": ["wechat"],
  "supported_features": ["text", "voice_to_text"],
  "health": "healthy"
}
```

### Canonical inbound event

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

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

## Related Pages

* [Channel Contract v0](/en/agent-platform/contracts/channel-v0/index)
* [Channel Integration Page v0](/en/agent-platform/console/channel-integration-page/index)
* [Dialog Ecosystem v0](/en/agent-platform/integrations/dialog-ecosystem/index)