Channel

The Channel primitive abstracts communication surfaces — how humans (or other systems) reach the agent. CKP supports messaging platforms and event-driven ingress types (cron, queue, IMAP, and DB triggers) with four access control modes.

URI pattern: claw://local/channel/{name}

---

Schema

claw: "0.3.0"
kind: Channel
metadata:
  name: "team-slack"
  version: "1.0.0"
spec:
  type: "slack"                   # "telegram" | "discord" | "whatsapp" | "slack"
                                  # | "email" | "webhook" | "cli" | "voice" | "web"
                                  # | "lark" | "matrix" | "line" | "wechat" | "qq"
                                  # | "dingtalk" | "cron" | "queue" | "imap"
                                  # | "db-trigger" | "custom"

  transport: "websocket"          # "polling" | "webhook" | "websocket" | "stdio"

  auth:
    secret_ref: "SLACK_BOT_TOKEN"

  access_control:
    mode: "allowlist"             # "open" | "allowlist" | "pairing" | "role-based"
    allowed_ids:
      - "U01ABC123"
      - "U02DEF456"

  processing:
    max_message_length: 4096
    rate_limit:
      messages_per_minute: 30
      burst: 5
    typing_indicator: true
    read_receipts: true

  features:
    voice: false
    files: true
    reactions: true
    threads: true
    inline_images: true

  trigger:
    schedule: "0 */6 * * *"       # REQUIRED for type "cron"
    queue_name: "agent.events"    # REQUIRED for type "queue"
    mailbox: "INBOX"              # REQUIRED for type "imap"
    table: "orders"               # REQUIRED for type "db-trigger"
    events: ["INSERT", "UPDATE"] # OPTIONAL for type "db-trigger"
    max_parallel: 2               # OPTIONAL; default 1
    overlap_policy: "queue"       # OPTIONAL; "skip" | "queue" | "allow"

---

Key Fields

Field	Required	Description
type	Yes	Channel type. One of 16+ supported platform types.
transport	Yes	Transport mechanism: polling, webhook, websocket, or stdio.
auth	Yes	Authentication for the channel platform.
access_control	No	Who can interact with the agent via this channel.
processing	No	Message processing settings (length limits, rate limits, indicators).
features	No	Channel-specific capability flags.
trigger	No	Event-driven trigger settings for cron, queue, imap, and db-trigger.

---

Access Control Modes

Mode	Description	Required Field
open	Any user on the platform can interact.	—
allowlist	Only pre-approved user IDs can interact.	allowed_ids
pairing	Unknown users receive an approval code; admin approves.	pairing
role-based	Users are assigned roles with different permissions.	roles

For allowlist mode, allowed_ids is REQUIRED and roles MUST NOT be present. For role-based mode, roles is REQUIRED and allowed_ids MUST NOT be present. For pairing mode, the pairing block is REQUIRED. Using the wrong field for a mode is a validation error.

---

Event-Driven Trigger Fields

Field	Required	Description
schedule	REQUIRED for type: cron	Cron expression for periodic execution.
queue_name	REQUIRED for type: queue	Queue/topic name to consume from.
mailbox	REQUIRED for type: imap	IMAP mailbox name to watch.
table	REQUIRED for type: db-trigger	Database table to watch.
events	OPTIONAL for type: db-trigger	Event filters: INSERT, UPDATE, DELETE.
max_parallel	Optional	Max concurrent trigger runs for this channel (default: 1).
overlap_policy	Optional	When saturated: skip, queue, or allow (default: skip).

Roles (role-based mode)

Role	Permissions
admin	Full access: execute all tools/skills, approve actions, modify agent config via channel
user	Standard access: interact with agent, invoke skills, trigger tools (subject to Policy)
viewer	Read-only: can see agent responses but cannot trigger tools or skills

---

Validation Rules

• The type, transport, and auth fields are REQUIRED.
• For event-driven channel types (cron, queue, imap, db-trigger), trigger SHOULD be provided.
• If trigger.max_parallel is omitted, runtimes default to 1; if trigger.overlap_policy is omitted, runtimes default to skip.
• Access control field requirements are mode-specific (see table above). Mixing fields across modes is a validation error.
• When no Channel is declared in the manifest, the runtime SHOULD expose a default stdio-based CLI channel restricted to the local process owner.

---

Design Rationale

The Channel primitive unifies synchronous messaging channels and event-driven ingress under one schema. Instead of splitting chat adapters from scheduler/webhook connectors, CKP keeps a single declarative surface for all communication entry points.