Skip to content
NBS Workshop

Channels

Architecture & Code

Channels

How external transports reach LifeOSAI agents — inbound dispatch and the shared outbound message tool.

How external transports reach LifeOSAI agents. Use the Full screen button above, or open the channels diagram in a new tab ↗.

Channels System

Channels allow external transports to talk to LifeOSAI agents.

Current channel shape:

  • WhatsApp plugin
  • Telegram plugin
  • channel registry
  • channel session store
  • inbound dispatch
  • outbound message tool

The central outbound contract is the channel message tool. Claude Code receives it as mcp__channels__message. Pi Agent has an equivalent tool implementation under the runtime tools path.

Inbound Channel Flow

WhatsApp / Telegram inbound message
transport plugin
channel registry resolves company, agent, and session
channel dispatch builds system prompt and runtime options
runtime streams answer
stream sink sends reply through the transport
channel session metadata is persisted

The channel dispatcher is transport-agnostic. WhatsApp and Telegram provide their own stream sinks because their delivery behavior differs:

  • Telegram can update streamed messages more naturally.
  • WhatsApp usually buffers and sends a final message.

Channel To Company Orchestration

A channel message can either:

  • continue a direct channel conversation with an agent, or
  • create a wakeup for company work when the message maps to a company agent.

The wake context should carry channel metadata when source is channel:

  • channel chat id
  • sender phone or sender id
  • sender display name
  • inbound message text
  • channel alias

The runtime receives this as LIFEOSAI_* env so the agent can reason about the source without needing direct transport credentials.

Outbound Channel Tool

The outbound tool is intentionally shared across runtimes:

Agent runtime
mcp__channels__message or Pi channels tool
apps/api/src/channels/message-tool.ts
channel action runner
transport plugin
external chat

This keeps channel sending out of the model prompt and inside an audited tool path.

Agent Systems The full system below the UI in one doc.
Platform Service boundary, responsibilities, deployment, security, and the code map.
Orchestration Companies, agents, wakeups, runs and live events.
Agent Runtime The harness — runtime interface, invoker, env layers, run-scoped auth.
Architecture overview Back to the section map and the full system diagram.