feat(web): WebSocket channel with MCP tool proxy and structured annotations

[bobbymarko]

What this enables

Most agent interfaces are a single chat thread. The web channel opens up a richer pattern: browser UIs that wire multiple agent conversations to structured data, where each piece of data gets its own isolated AI session and the UI stays in control of state.

A concrete example of what you can build: a kanban-style task manager where each task card opens a dedicated agent conversation. The UI loads all tasks directly from a data source via invoke_tool — no agent round-trip, just a fast MCP call over the persistent WebSocket. When the user taps a card and starts chatting, the agent gets the task context injected into the message. As the agent researches (finding a phone number, a price, a contact), it emits [[CHANNEL_EVENT:brief:...]] annotations that flow back to the card as a live summary — without cluttering the chat transcript. Each card's conversation is scoped by contextId, so tasks never bleed into each other's history.

The channel is intentionally minimal: it handles auth, session routing, streaming, and tool proxying. Everything else — what the UI looks like, what MCP servers are connected, what context gets injected into messages — is the client's concern.

---

Summary

Adds a new web channel — a WebSocket-based channel that connects any browser-side app to a clisbot agent. Includes a generic MCP tool proxy so the UI can call tools directly, and a structured annotation mechanism so agents can push typed events to the client without leaking them into visible chat text.

What's included

New channel (src/channels/web/)

• WebSocket server with API-key auth (HTTP upgrade, ?key= query param)
• message — routes text to the configured agent; contextId (optional) scopes to a per-context conversation thread
• get_history — replays the agent's Claude Code session JSONL back to the client so the chat UI can restore history on reconnect
• invoke_tool — proxies any tools/call to a configured MCP server over stdio; the client can call databases, APIs, or anything MCP-accessible without going through the agent

mcp-client.ts — lightweight JSON-RPC 2.0 stdio MCP client

• Spawns an MCP server process, handles the initialize handshake, maps pending requests by ID
• Unwraps the content[0].text envelope so callers get plain JSON back
• Persistent per-server connection, lazy-initialized and reused across requests

history-reader.ts — reads Claude Code session JSONL files for history replay

• Strips client-injected context (everything before [USER_INPUT] marker)
• Strips [[CHANNEL_EVENT:...]] annotations from historical messages

Generic [[CHANNEL_EVENT:key:value]] annotations

• The agent can embed [[CHANNEL_EVENT:key:value]] anywhere in its reply
• The channel strips them from the visible text stream (handles partial markers mid-stream)
• Emits { type: "annotation", contextId, key, value } WS events
• Client apps define their own annotation keys — the channel has zero knowledge of their meaning

Config additions

• bots.web.mcpServers — map of server name → { command, args, env } spawn configs; only declared servers are accessible via invoke_tool
• bots.web.senderName — display name for the human sender (default "Owner")

WebSocket protocol

Client → server

{ "type": "message", "text": "...", "contextId": "optional-thread-id" }
{ "type": "get_history", "contextId": "..." }
{ "type": "invoke_tool", "server": "my-tools", "tool": "search", "args": { "q": "..." } }

Server → client

{ "type": "ready" }
{ "type": "chunk", "id": "wc1", "text": "partial agent response..." }
{ "type": "update", "id": "wc1", "text": "revised agent response..." }
{ "type": "done" }
{ "type": "tool_result", "server": "my-tools", "tool": "search", "result": {...} }
{ "type": "annotation", "contextId": "...", "key": "my-key", "value": "..." }
{ "type": "history", "contextId": "...", "messages": [{"role":"user","text":"..."},...] }
{ "type": "error", "message": "..." }

Example config

"bots": {
  "web": {
    "apiKey": "your-secret-key",
    "port": 3099,
    "senderName": "Alice",
    "mcpServers": {
      "my-tools": {
        "command": "python3",
        "args": ["/path/to/my-mcp-server.py"]
      }
    }
  }
}

🤖 Generated with Claude Code

[bobbymarko]

@longbkit I realize this is a pretty obscure use case of wanting to interact with Clisbot via a web interface. But I have found it to be a powerful unlock for expanding beyond the boundaries of what messaging apps support. On top of this I built my own todo app with each todo item being able to spawn its own conversation. I also built support for A2UI so my responses can have interactive visual components instead of being text. But if this is too specific, maybe we could build a federated channel plugin framework so others can add their own channels without having to add them to the codebase?