@chatpanel/channels 0.1.0

package/LICENSE

@@ -0,0 +1,168 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+bridge, and related developer tools and services (https://chatpanel.net)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to
+distribute copies of the software.  Your license to distribute
+covers distributing the software with changes and new works
+permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright © 2026 ChatPanel (https://chatpanel.net)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any
+product that competes with the software or any product the
+licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality
+through different kinds of interfaces or for different technical
+platforms.  Applications can compete with services, libraries
+with plugins, frameworks with development tools, and so on,
+even if they're written in different programming languages
+or for different computer architectures.  Goods and services
+compete even when provided free of charge.  If you market a
+product as a practical substitute for the software or another
+product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does
+not compete, but the licensor or any of its affiliates brings
+your product into competition by providing a new version of
+the software or another product using the software, you may
+continue using versions of the software available under these
+terms beforehand to provide your competing product, but not
+any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product
+or service that the licensor or any of its affiliates has
+stopped providing, unless the licensor includes a plain-text
+line beginning with `Licensor Line of Business:` with the
+software that mentions that line of business.  For example:
+
+> Licensor Line of Business: ChatPanel — an AI browser side-panel, its local
+> bridge, and related developer tools and services (https://chatpanel.net)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of
+business developing the software or using the software
+to provide a product, the buyer can also enforce
+Noncompete for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law.  These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately.  If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+A **product** can be a good or service, or a combination
+of them.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+its affiliates.
+
+**Affiliates** means the other organizations that an
+organization has control over, is under the control of, or is
+under common control with.
+
+**Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies
+by vote, contract, or otherwise.  Control can be direct or
+indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,102 @@
+# @chatpanel/channels
+
+Drive your local ChatPanel agent from an external messaging surface — today **Telegram**,
+next **WhatsApp**. A phone message becomes an agent turn on your machine, streamed back to the
+chat, with PII redacted before anything leaves for the model and every run written to an audit
+log.
+
+Design doc: [`chatpanel/docs/feature-f7-remote-channels.md`](../chatpanel/docs/feature-f7-remote-channels.md).
+
+## Why this shape
+
+The Telegram adapter uses `getUpdates` long-poll, which is **outbound-only** — the same
+property as Claude Code Remote Control: your machine never opens an inbound port, works behind
+NAT, needs no tunnel or public IP. The only hop that reaches the agent is the bridge on
+`127.0.0.1:4319`, and it never leaves the box.
+
+```
+Telegram getUpdates ─long-poll→ @chatpanel/channels ─POST /chat (bridge token)→ chatpanel-bridge
+     ↑ editMessageText (throttled) ←── SSE delta/done ──────────────────────────────────┘
+                     │ normalize → pairing gate → pii.redact → capability(actor.kind:'channel')
+                     ▼ append capability.invoked / privacy.redacted / privacy.egress
+```
+
+## Layout
+
+| file | role | pure? |
+|---|---|---|
+| `src/normalize.js` | platform message → one normalized shape | ✅ |
+| `src/pairing.js` | who may drive it, and their `reach` ceiling | ✅ |
+| `src/invoke.js` | normalized → capability invocation + pii redact + audit events | ✅ |
+| `src/stream.js` | bridge SSE → folded reply (+ Telegram split/throttle) | ✅ |
+| `src/bridge.js` | POST `/chat` (SSE) + `/cancel` on the local bridge | net |
+| `src/eventlog.js` | append-only JSONL sink over `@chatpanel/events` appender | net |
+| `src/adapters/telegram.js` | `getUpdates` long-poll transport (the LOCAL shape) | net |
+| `bin/chatpanel-channels.js` | CLI that wires it together | — |
+
+The pure core is unit-testable without a bot or a bridge (`npm test` = 26 tests, incl. a
+real-socket SSE integration test).
+
+Conversations are **multi-turn**: each chat keeps a bounded, redacted history so a follow-up
+("…and the second one?") resolves against the prior answer. `/new` forgets it.
+
+## Run
+
+```sh
+npm install -g @chatpanel/channels   # or npx @chatpanel/channels telegram
+```
+
+1. Start the bridge once (it writes `~/.chatpanel/bridge-token`): `chatpanel-bridge`.
+2. Create a bot with [@BotFather](https://t.me/BotFather), copy its token.
+3. Run the adapter:
+
+```sh
+TELEGRAM_BOT_TOKEN=123:abc chatpanel-channels telegram
+```
+
+4. Message your bot. It will say *not paired*. Pair the chat:
+   - **Bootstrap (dev):** set `CHANNELS_ALLOW=<yourChatId>` before starting, or
+   - **Codes (real):** mint a one-time code (`pairing.requestCode()` — surfaced in the
+     extension) and send `/pair <code>` from the phone.
+
+Chat commands: `/pair <code>`, `/new` (forget the conversation + fresh privacy vault), `/stop`, `/help`.
+
+### Env
+
+| var | default | meaning |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | — | BotFather token (required) |
+| `CHANNELS_ALLOW` | — | comma list of chat ids to pre-pair (bootstrap) |
+| `CHANNELS_AGENT` | `claude` | bridge engine id (`claude`, `codex`, …) |
+| `CHANNELS_PRIVACY` | `standard` | `standard` restores real values for you · `strict` keeps `[[PERSON_1]]` in the reply |
+| `CHANNELS_PII_TIER` | `basic` | `basic` regex · `full` (needs a roster) also pseudonymizes people/orgs |
+| `CHATPANEL_BRIDGE_URL` | `http://127.0.0.1:4319` | bridge address |
+| `CHATPANEL_BRIDGE_TOKEN` | — | overrides the token file |
+
+## Security posture (read before shipping)
+
+This is the honest §7 of the design doc, made concrete:
+
+- **PII redaction on egress is on by default and mandatory.** Telegram bot traffic is **not**
+  end-to-end encrypted, so inbound text is redacted (`@chatpanel/pii`) before it reaches the
+  agent/model. `CHANNELS_PRIVACY=strict` additionally keeps placeholders in the *reply* so the
+  provider never sees a real value either.
+- **Pairing is authentication, not authorization.** A chat-id allowlist + a paired code proves
+  *who* sent a message. It does **not** bound *what* that message may do. Prompt-injection →
+  tool execution is the real risk, because the bridge `/chat` runs shell/filesystem tools.
+- **`reach` is carried but tool-scoping is the next layer** (not yet built). Until it lands,
+  run against a bridge whose agent is read-only / ask-mode for anything destructive. Do not
+  point a write-capable, auto-approving agent at an untrusted chat.
+- **Secrets:** the BotFather token and the bridge token are the crown jewels. The bridge token
+  is read `0600` from `~/.chatpanel`; keep the bot token out of shell history (use a file / a
+  keychain in a shipped build).
+
+Every run leaves `capability.invoked` / `privacy.redacted` / `privacy.egress` in
+`~/.chatpanel/channels/events.jsonl` — the audit trail neither Claude Code Remote nor Hermes
+has.
+
+## Status
+
+**Local (Telegram) shape: built.** The WhatsApp/Cloudflare relay shape and the
+per-actor tool-authorization policy are designed but not built — see the feature doc, §5 build
+order.

package/bin/chatpanel-channels.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// chatpanel-channels — run a messaging adapter that drives your local ChatPanel agent.
+//
+//   chatpanel-channels telegram
+//
+// Env:
+//   TELEGRAM_BOT_TOKEN     BotFather token (required)                    [or BOT_TOKEN]
+//   CHANNELS_ALLOW         comma list of chat ids to pre-pair (bootstrap; optional)
+//   CHANNELS_AGENT         bridge engine id (default: claude)
+//   CHANNELS_SYSTEM        system prompt for the agent (optional)
+//   CHANNELS_PRIVACY       'standard' (restore for you) | 'strict' (keep placeholders)
+//   CHANNELS_PII_TIER      'basic' (regex) | 'full' (needs a roster) — default basic
+//   CHATPANEL_BRIDGE_URL   default http://127.0.0.1:4319
+//   CHATPANEL_BRIDGE_TOKEN overrides ~/.chatpanel/bridge-token
+
+import path from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { bridgeBaseUrl, readBridgeToken, channelsDataDir } from '../src/config.js';
+import { createPairingStore } from '../src/pairing.js';
+import { createEventLog } from '../src/eventlog.js';
+import { startTelegram } from '../src/adapters/telegram.js';
+
+async function loadPairing(file) {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return {}; }
+}
+
+async function main() {
+  const cmd = process.argv[2] || 'telegram';
+  if (cmd === '--help' || cmd === '-h') { console.log('usage: chatpanel-channels telegram'); return; }
+  if (cmd !== 'telegram') { console.error(`unknown command '${cmd}'. try: chatpanel-channels telegram`); process.exit(1); }
+
+  const botToken = process.env.TELEGRAM_BOT_TOKEN || process.env.BOT_TOKEN;
+  if (!botToken) { console.error('set TELEGRAM_BOT_TOKEN (from @BotFather)'); process.exit(1); }
+
+  const baseUrl = bridgeBaseUrl();
+  const token = await readBridgeToken();
+  const dataDir = channelsDataDir();
+  await mkdir(dataDir, { recursive: true });
+
+  const pairingFile = path.join(dataDir, 'pairing.json');
+  const pairing = createPairingStore(await loadPairing(pairingFile));
+  const savePairing = () => writeFile(pairingFile, JSON.stringify(pairing.toJSON(), null, 2), { mode: 0o600 });
+
+  // Bootstrap allow-list (prototype convenience). Each becomes a paired 'trusted' actor —
+  // explicitly, never silent enrollment. Prefer /pair codes for real use.
+  for (const chatId of (process.env.CHANNELS_ALLOW || '').split(',').map((s) => s.trim()).filter(Boolean)) {
+    pairing.allow(`telegram:${chatId}`);
+  }
+  await savePairing();
+
+  const appender = await createEventLog({ file: path.join(dataDir, 'events.jsonl'), host: 'channel' });
+
+  const controller = new AbortController();
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => controller.abort());
+
+  const agent = process.env.CHANNELS_AGENT || 'claude';
+  const privacy = process.env.CHANNELS_PRIVACY || 'standard';
+  console.log(`[chatpanel-channels] telegram → bridge ${baseUrl} (agent=${agent}, privacy=${privacy}, tier=${process.env.CHANNELS_PII_TIER || 'basic'})`);
+  await startTelegram({
+    botToken, baseUrl, token, pairing, savePairing, appender,
+    agent,
+    system: process.env.CHANNELS_SYSTEM || '',
+    redact: { tier: process.env.CHANNELS_PII_TIER || 'basic' },
+    privacy,
+    signal: controller.signal,
+  });
+}
+
+main().catch((e) => { console.error(e?.message || e); process.exit(1); });

package/index.js

@@ -0,0 +1,18 @@
+// @chatpanel/channels — drive ChatPanel agents from external messaging surfaces.
+//
+// The pure core is platform-agnostic and unit-testable without a bot or a bridge:
+//   normalize.js  platform message  → one normalized shape
+//   pairing.js    who may drive it, and how far a request may travel (reach)
+//   invoke.js     normalized message → capability invocation + pii redaction + audit events
+//   stream.js     the bridge's SSE stream → a folded reply (+ Telegram splitting/throttling)
+// Adapters are dumb transport; the CLI (bin/) wires them together.
+//
+//   import { normalizeTelegram, createPairingStore, redactInbound } from '@chatpanel/channels';
+
+export * from './src/normalize.js';
+export * from './src/pairing.js';
+export * from './src/invoke.js';
+export * from './src/stream.js';
+export * as bridge from './src/bridge.js';
+export { createEventLog, nullEventLog } from './src/eventlog.js';
+export { startTelegram } from './src/adapters/telegram.js';

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@chatpanel/channels",
+  "version": "0.1.0",
+  "description": "Drive ChatPanel agents from external messaging surfaces (Telegram, WhatsApp). One normalize→invoke→stream core per platform, wired through @chatpanel/pii redaction and the @chatpanel/events audit log. The local Telegram shape is outbound-only (long-poll) and opens no inbound port — the same property as Claude Code Remote Control. Pure, dependency-free ESM.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./normalize.js": "./src/normalize.js",
+    "./pairing.js": "./src/pairing.js",
+    "./invoke.js": "./src/invoke.js",
+    "./stream.js": "./src/stream.js",
+    "./bridge.js": "./src/bridge.js",
+    "./eventlog.js": "./src/eventlog.js",
+    "./adapters/telegram.js": "./src/adapters/telegram.js"
+  },
+  "bin": {
+    "chatpanel-channels": "bin/chatpanel-channels.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "bin",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "start": "node bin/chatpanel-channels.js telegram"
+  },
+  "dependencies": {
+    "@chatpanel/events": "^0.21.0",
+    "@chatpanel/pii": "^0.3.0"
+  },
+  "keywords": [
+    "chatpanel",
+    "telegram",
+    "whatsapp",
+    "remote-control",
+    "agent",
+    "privacy",
+    "pii"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatpanel/chatpanel-channels.git"
+  },
+  "homepage": "https://chatpanel.net",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false
+}

package/src/adapters/telegram.js

@@ -0,0 +1,206 @@
+// Telegram adapter — the LOCAL shape (§3 of feature-f7). getUpdates long-poll is
+// OUTBOUND-ONLY, so this mirrors Claude Code Remote Control's key property: the machine never
+// opens an inbound port, works behind NAT, needs no tunnel. The adapter is dumb transport;
+// normalize → gate → redact → invoke → stream → restore is the shared core it drives.
+
+import { normalizeTelegram, actorId } from '../normalize.js';
+import {
+  buildInvocation, redactInbound, restoreOutbound, appendTurn,
+  appendInvoked, appendRedacted, appendEgress,
+} from '../invoke.js';
+import * as bridge from '../bridge.js';
+import { splitForTelegram, createGate } from '../stream.js';
+import { createVault } from '@chatpanel/pii';
+
+const TG_HOST = 'api.telegram.org';
+
+const HELP = [
+  'ChatPanel — drive your local agent from here.',
+  '',
+  'Send a message and I run it on your machine.',
+  '/pair <code> — enroll this chat (get the code in the ChatPanel extension)',
+  '/new         — start fresh (forget this conversation + new privacy vault)',
+  '/stop        — stop the current run',
+  '/help        — this message',
+].join('\n');
+
+/**
+ * Start the long-poll loop. Returns the loop promise; abort `signal` to stop it. Everything
+ * it needs is injected — a bot token, the bridge address+token, a pairing store, an event sink
+ * — so nothing here reads a secret or reaches for global state.
+ */
+export function startTelegram({
+  botToken,
+  baseUrl,
+  token,                       // bridge token
+  pairing,                     // createPairingStore(...)
+  savePairing = async () => {},
+  appender,                    // createEventLog(...) or nullEventLog()
+  agent = 'claude',
+  system = '',
+  redact = { tier: 'basic' },
+  privacy = 'standard',
+  logger = console,
+  signal,                      // AbortSignal to stop the whole loop
+}) {
+  const api = `https://${TG_HOST}/bot${botToken}`;
+  const fileApi = `https://${TG_HOST}/file/bot${botToken}`;
+  // Per-chat session: a persistent vault (stable placeholders across turns), the live run id
+  // (/stop), and the redacted conversation history (multi-turn context).
+  const chats = new Map(); // chatId -> { vault, runId, history }
+  const freshChat = () => ({ vault: createVault(), runId: null, history: [] });
+  const chatState = (id) => {
+    if (!chats.has(id)) chats.set(id, freshChat());
+    return chats.get(id);
+  };
+
+  async function tg(method, body) {
+    const res = await fetch(`${api}/${method}`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal,
+    });
+    return res.json();
+  }
+  const send = (chatId, text) => tg('sendMessage', { chat_id: chatId, text });
+  const edit = (chatId, messageId, text) => tg('editMessageText', { chat_id: chatId, message_id: messageId, text });
+
+  // Resolve Telegram photos to the { dataUrl } shape the bridge's engines expect (Claude Code
+  // writes them to temp files and reads them as vision). A failed fetch drops that one image
+  // rather than failing the whole turn.
+  async function toBridgeImages(photos) {
+    const out = [];
+    for (const p of photos || []) {
+      try {
+        const info = await tg('getFile', { file_id: p.fileId });
+        const fp = info?.result?.file_path;
+        if (!fp) continue;
+        const bin = await fetch(`${fileApi}/${fp}`, { signal });
+        const buf = Buffer.from(await bin.arrayBuffer());
+        const mime = /\.png$/i.test(fp) ? 'image/png' : /\.webp$/i.test(fp) ? 'image/webp' : 'image/jpeg';
+        out.push({ dataUrl: `data:${mime};base64,${buf.toString('base64')}` });
+      } catch (e) { logger.warn?.(`[telegram] image fetch failed: ${e?.message || e}`); }
+    }
+    return out;
+  }
+
+  async function handleCommand(norm) {
+    const id = actorId('telegram', norm.chatId);
+    const { name, args } = norm.command;
+    if (name === 'help' || name === 'start') return void send(norm.chatId, HELP);
+    if (name === 'pair') {
+      const r = pairing.redeem(id, args);
+      await savePairing();
+      return void send(norm.chatId, r.ok ? `✅ paired (reach: ${r.reach}). Send me anything.` : `⛔ ${r.reason}`);
+    }
+    if (name === 'new') {
+      chats.set(norm.chatId, freshChat());
+      return void send(norm.chatId, '🧹 fresh conversation.');
+    }
+    if (name === 'stop') {
+      const st = chatState(norm.chatId);
+      const ok = await bridge.cancel(st.runId, { baseUrl, token });
+      st.runId = null;
+      return void send(norm.chatId, ok ? '⏹ stopped.' : 'nothing running.');
+    }
+    return void send(norm.chatId, `unknown command /${name} — try /help`);
+  }
+
+  async function handleMessage(norm) {
+    const id = actorId('telegram', norm.chatId);
+    // AUTHENTICATION gate: an unpaired sender cannot drive anything. This proves WHO, not WHAT
+    // — tool scoping (reach → per-actor allowlist) is the next layer and lives above the bridge.
+    const reach = pairing.reachOf(id);
+    if (!reach) {
+      return void send(norm.chatId, '🔒 not paired. Get a code in the ChatPanel extension, then send: /pair <code>');
+    }
+    if (!norm.text && !norm.photos.length) return;
+    const st = chatState(norm.chatId);
+
+    // Contract + audit BEFORE anything leaves for the agent.
+    let invocation;
+    try { invocation = buildInvocation(norm); }
+    catch (e) { return void send(norm.chatId, `⚠️ ${e.message}`); }
+
+    const { redacted, counts } = redactInbound(norm.text, st.vault, redact);
+    await appendInvoked(appender, invocation);
+    await appendRedacted(appender, counts);
+
+    const images = await toBridgeImages(norm.photos);
+    const placeholder = await tg('sendMessage', { chat_id: norm.chatId, text: '…' });
+    const replyId = placeholder?.result?.message_id;
+    const gate = createGate(1200); // ~1 edit/sec, Telegram's ceiling for a chat
+    let shown = '';
+
+    // Replay prior turns as context; the new (redacted) message is the live one. buildCliPrompt
+    // on the bridge renders all-but-last as history and the last as "answer this now".
+    const messages = [...st.history, { role: 'user', content: redacted }];
+
+    try {
+      const finalState = await bridge.chat(
+        { agent, system, messages, images, options: { reach } },
+        {
+          baseUrl, token, signal,
+          onEvent: (ev, state) => {
+            if (ev.type === 'run') st.runId = state.runId;
+            // Throttled live edit: restore placeholders so the user watches real text stream in.
+            if ((ev.type === 'delta' || ev.type === 'done') && replyId && (ev.type === 'done' || gate.ready())) {
+              const text = restoreOutbound(state.text, st.vault, { privacy });
+              const first = splitForTelegram(text || '…')[0];
+              if (first && first !== shown) { shown = first; edit(norm.chatId, replyId, first).catch(() => {}); }
+            }
+          },
+        },
+      );
+      st.runId = null;
+
+      const restored = restoreOutbound(finalState.text, st.vault, { privacy });
+      const chunks = splitForTelegram(finalState.error ? `⚠️ ${finalState.error}` : (restored || '(no output)'));
+      if (replyId) await edit(norm.chatId, replyId, chunks[0]);
+      else await send(norm.chatId, chunks[0]);
+      for (const extra of chunks.slice(1)) await send(norm.chatId, extra);
+
+      // Remember the exchange for follow-ups — the REDACTED forms, so what we replay next turn
+      // never carries a real value and stays consistent with the vault. A failed turn (error /
+      // no text) records nothing, so history never implies an answer that didn't happen.
+      if (!finalState.error && finalState.text) st.history = appendTurn(st.history, redacted, finalState.text);
+
+      // Egress to Telegram, recorded: 'standard' restores real values (a third party sees
+      // them → redacted:false); 'strict' keeps placeholders (redacted:true). controlled:false
+      // either way — Telegram is not ours.
+      await appendEgress(appender, { host: TG_HOST, redacted: privacy === 'strict', controlled: false });
+    } catch (e) {
+      st.runId = null;
+      const msg = `⚠️ ${e?.message || e}`;
+      if (replyId) await edit(norm.chatId, replyId, msg).catch(() => {});
+      else await send(norm.chatId, msg).catch(() => {});
+    }
+  }
+
+  async function loop() {
+    let offset = 0;
+    logger.log?.('[telegram] long-poll started (outbound-only; no inbound port).');
+    while (!signal?.aborted) {
+      let updates;
+      try {
+        const res = await tg('getUpdates', { offset, timeout: 30, allowed_updates: ['message'] });
+        updates = res?.result || [];
+      } catch (e) {
+        if (signal?.aborted) break;
+        logger.warn?.(`[telegram] getUpdates failed: ${e?.message || e}; retrying in 2s`);
+        await new Promise((r) => setTimeout(r, 2000));
+        continue;
+      }
+      for (const u of updates) {
+        offset = u.update_id + 1;
+        const norm = normalizeTelegram(u);
+        if (!norm) continue;
+        // Fire-and-forget per message so one slow turn doesn't stall the poll; errors are
+        // caught so a single bad message never kills the loop.
+        const run = norm.command ? handleCommand(norm) : handleMessage(norm);
+        Promise.resolve(run).catch((e) => logger.error?.(`[telegram] handler error: ${e?.message || e}`));
+      }
+    }
+    logger.log?.('[telegram] stopped.');
+  }
+
+  return loop();
+}

package/src/bridge.js

@@ -0,0 +1,50 @@
+// The transport to the local agent: POST /chat (SSE) and POST /cancel on the bridge. The
+// bridge binds 127.0.0.1:4319 and runs Claude Code / Codex / etc. as CLIs — so this is the ONE
+// hop where the (already-redacted) conversation reaches the agent, and it never leaves the
+// machine. A channel adapter is a non-browser local client, so it presents the per-install
+// bridge token, exactly like any privileged caller.
+
+import { parseSse, foldEvent, initialState } from './stream.js';
+
+/**
+ * Drive one turn. Streams bridge events to onEvent(ev, state) as they arrive AND folds them
+ * into a final reply state it returns. `agent` is a bridge engine id ('claude','codex',…).
+ */
+export async function chat({ agent = 'claude', system = '', messages, images = [], options = {} }, {
+  baseUrl, token, signal, onEvent = () => {},
+} = {}) {
+  const res = await fetch(`${baseUrl}/chat`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+    body: JSON.stringify({ agent, system, messages, images, options }),
+    signal,
+  });
+  if (!res.ok || !res.body) {
+    const detail = await res.text().catch(() => '');
+    throw new Error(`bridge /chat ${res.status}${detail ? `: ${detail.slice(0, 300)}` : ''}`);
+  }
+  let state = initialState();
+  let buffer = '';
+  const decoder = new TextDecoder();
+  for await (const chunk of res.body) {
+    buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+    const { events, rest } = parseSse(buffer);
+    buffer = rest;
+    for (const ev of events) { state = foldEvent(state, ev); onEvent(ev, state); }
+  }
+  return state;
+}
+
+/** Stop a run by the id the bridge emitted as its first {type:'run'} event. Best-effort. */
+export async function cancel(runId, { baseUrl, token } = {}) {
+  if (!runId) return false;
+  try {
+    const res = await fetch(`${baseUrl}/cancel`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+      body: JSON.stringify({ id: runId }),
+    });
+    const out = await res.json().catch(() => ({}));
+    return !!out.cancelled;
+  } catch { return false; }
+}

package/src/config.js

@@ -0,0 +1,35 @@
+// Where things live and how the adapter authenticates. Kept tiny and in one place so a
+// deployment overrides everything with env, and so no secret is read anywhere but here.
+
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+// The bridge binds a FIXED 127.0.0.1:4319 (see chatpanel-bridge/src/server.js) so the
+// extension always finds it; the adapter is just another local client of the same port.
+export const DEFAULT_BRIDGE_URL = 'http://127.0.0.1:4319';
+
+export function bridgeBaseUrl(env = process.env) {
+  return (env.CHATPANEL_BRIDGE_URL || DEFAULT_BRIDGE_URL).replace(/\/+$/, '');
+}
+
+export function channelsHome(env = process.env) {
+  return env.CHATPANEL_HOME || path.join(os.homedir(), '.chatpanel');
+}
+
+export function channelsDataDir(env = process.env) {
+  return path.join(channelsHome(env), 'channels');
+}
+
+// The bridge writes ~/.chatpanel/bridge-token 0600 on first start. A channel adapter is a
+// non-browser local client, so — like any privileged caller — it presents this token instead
+// of an Origin header. Read it fresh each start; never cache a secret longer than needed.
+export async function readBridgeToken(env = process.env) {
+  if (env.CHATPANEL_BRIDGE_TOKEN) return env.CHATPANEL_BRIDGE_TOKEN.trim();
+  const p = path.join(channelsHome(env), 'bridge-token');
+  try {
+    const t = (await readFile(p, 'utf8')).trim();
+    if (t) return t;
+  } catch { /* fall through to a clear, actionable error */ }
+  throw new Error(`no bridge token — start chatpanel-bridge once (it writes ${p}), or set CHATPANEL_BRIDGE_TOKEN`);
+}

package/src/eventlog.js

@@ -0,0 +1,48 @@
+// A file-backed sink for the capability/privacy events a channel run produces — the audit
+// trail neither Claude Code Remote nor Hermes has. Events are metadata only (counts, ids;
+// never message content — see chatpanel-events/event.js), so this JSONL is safe to keep and
+// replicate. One line per event, append-only. seq is owned by the appender and recovered from
+// the file on restart so ordering survives a bounce.
+
+import { appendFile, readFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { createAppender } from '@chatpanel/events/event.js';
+
+async function nextSeq(file) {
+  try {
+    const txt = await readFile(file, 'utf8');
+    let max = -1;
+    for (const l of txt.split('\n')) {
+      if (!l) continue;
+      try { const e = JSON.parse(l); if (Number.isInteger(e.seq)) max = Math.max(max, e.seq); } catch { /* skip */ }
+    }
+    return max + 1;
+  } catch { return 0; }
+}
+
+export async function createEventLog({ file, host = 'channel' }) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const seq = await nextSeq(file);
+  const appender = createAppender({ host, seq, newId: () => globalThis.crypto.randomUUID() });
+  return {
+    host,
+    get seq() { return appender.seq; },
+    // Same signature as the raw appender, but persists. Returns the validated event.
+    async append(type, payload, causes = []) {
+      const e = appender.append(type, payload, causes);
+      await appendFile(file, JSON.stringify(e) + '\n');
+      return e;
+    },
+  };
+}
+
+// A no-op sink for the allow-list prototype or tests — same interface, writes nothing but
+// still builds + validates each event, so a bad payload fails loudly here too.
+export function nullEventLog({ host = 'channel' } = {}) {
+  const appender = createAppender({ host, seq: 0, newId: () => globalThis.crypto.randomUUID() });
+  return {
+    host,
+    get seq() { return appender.seq; },
+    async append(type, payload, causes = []) { return appender.append(type, payload, causes); },
+  };
+}

package/src/invoke.js

@@ -0,0 +1,119 @@
+// The invariant core: an inbound message becomes ONE capability invocation with
+// actor.kind:'channel', its text is redacted before it can leave for the agent, and both facts
+// are written to the event log. Everything here is pure given a vault + an appender — the
+// adapter owns the network, this owns the contract.
+
+import { validateInvocation } from '@chatpanel/events/capability.js';
+import { redactText, restoreText, redactionSummary } from '@chatpanel/pii';
+
+// One capability every channel message invokes: "run an agent turn on the user's behalf".
+// Effects are non-replayable — a turn runs shell/filesystem tools, so replaying it would
+// repeat side effects; that is exactly why validateInvocation demands an idempotencyKey.
+export const CHANNEL_CAPABILITY = 'channel.chat';
+export const CHANNEL_EFFECTS = 'non-replayable';
+
+/** Build + validate the invocation for one inbound message. Throws EventError on a bad shape. */
+export function buildInvocation({ platform, chatId, messageId }, causes = []) {
+  const id = `${platform}:${chatId}`;
+  const inv = {
+    capability: CHANNEL_CAPABILITY,
+    actor: { kind: 'channel', id },
+    scope: { kind: 'session', id },
+    causes,
+    effects: CHANNEL_EFFECTS,
+    // Same platform + chat + message = same turn. Retried delivery must not run it twice.
+    idempotencyKey: `${platform}:${chatId}:${messageId}`,
+  };
+  return validateInvocation(inv);
+}
+
+// Entries per entity type in a vault, so we can diff before/after and report how many NEW
+// values a turn redacted — never the values (privacy.redacted is counts-only, by contract).
+function countsByType(vault) {
+  const counts = {};
+  for (const t of redactionSummary(vault).types) counts[t.type] = t.count;
+  return counts;
+}
+
+/**
+ * Redact inbound text into the chat's vault. Returns the redacted text plus the per-turn
+ * counts delta (for a privacy.redacted event). The vault persists across turns, so PERSON_1
+ * means the same person every message.
+ *
+ * `tier:'basic'` (regex: emails, phones, cards, keys, IPs) is the safe default with no roster;
+ * pass `tier:'full'` + `entities` to also pseudonymize known people/orgs.
+ */
+export function redactInbound(text, vault, { tier = 'basic', entities = [], dictionary = [] } = {}) {
+  const before = countsByType(vault);
+  const redacted = redactText(text ?? '', vault, { tier, entities, dictionary });
+  const after = countsByType(vault);
+  const counts = {};
+  for (const type of Object.keys(after)) {
+    const d = after[type] - (before[type] || 0);
+    if (d > 0) counts[type] = d;
+  }
+  return { redacted, counts };
+}
+
+/**
+ * Restore the agent's reply for the user. Two honest modes:
+ *  - 'standard' (default): swap placeholders back to real values. The user reads their own
+ *    data on their own phone — but Telegram/Meta bot traffic is NOT end-to-end encrypted, so
+ *    the provider carries it in the clear. That is the accepted trade for a readable reply.
+ *  - 'strict': leave placeholders in the outbound message. The provider never sees a real
+ *    value; the user sees [[PERSON_1]]. Choose per deployment.
+ */
+export function restoreOutbound(text, vault, { privacy = 'standard' } = {}) {
+  return privacy === 'strict' ? String(text ?? '') : restoreText(text ?? '', vault);
+}
+
+// Conversation memory. The adapter keeps ONE array of REDACTED turns per chat and replays it
+// as context, so "…and the second one?" resolves against the prior answer. The bridge's
+// buildCliPrompt already renders all-but-last as a labelled history transcript and the last as
+// the live message — so multi-turn just works once the array is threaded through.
+//
+// We store the redacted user text and the agent's (already-placeholdered) reply — never real
+// values — so history is exactly as safe to hold as the event log, and the vault stays the one
+// source of truth for what PERSON_1 means. The window is bounded so a long chat can't grow the
+// prompt without end.
+export const DEFAULT_HISTORY_MESSAGES = 16;
+
+/**
+ * Append one exchange to a chat's history and return the new, bounded array (never mutates).
+ * `assistantText` is optional — a failed turn stores nothing, so history never implies the
+ * agent answered when it didn't.
+ */
+export function appendTurn(history, userText, assistantText, { maxMessages = DEFAULT_HISTORY_MESSAGES } = {}) {
+  const next = Array.isArray(history) ? history.slice() : [];
+  next.push({ role: 'user', content: String(userText ?? '') });
+  const reply = assistantText == null ? '' : String(assistantText);
+  if (reply) next.push({ role: 'assistant', content: reply });
+  // Keep only the last maxMessages, and never let the window open on an assistant turn — a
+  // transcript that starts with "Assistant:" reads as if the agent spoke first.
+  let windowed = maxMessages > 0 ? next.slice(-maxMessages) : next;
+  while (windowed.length && windowed[0].role === 'assistant') windowed = windowed.slice(1);
+  return windowed;
+}
+
+// Event builders — thin, so the adapter appends without knowing payload shapes. Each returns
+// whatever the appender's append() returns (a validated event, or a promise of one).
+export function appendInvoked(appender, invocation, causes = []) {
+  return appender.append('capability.invoked', {
+    capability: invocation.capability,
+    actor: invocation.actor,
+    scope: invocation.scope,
+    effects: invocation.effects,
+    idempotencyKey: invocation.idempotencyKey,
+  }, causes);
+}
+
+export function appendRedacted(appender, counts, causes = []) {
+  // Nothing redacted → nothing to record. An empty privacy.redacted still validates, but a
+  // log line that says "0 of nothing" is noise.
+  if (!counts || !Object.keys(counts).length) return null;
+  return appender.append('privacy.redacted', { counts }, causes);
+}
+
+export function appendEgress(appender, { host, redacted, controlled }, causes = []) {
+  return appender.append('privacy.egress', { host, redacted: !!redacted, controlled: !!controlled }, causes);
+}

package/src/normalize.js

@@ -0,0 +1,49 @@
+// Platform message → one normalized shape the invoke/stream core understands. PURE: no
+// network, no token — a Telegram update object in, a plain record out — so the whole gate
+// (pairing, redaction, command routing) is unit-testable without a bot.
+//
+// One shape for every platform is the same discipline capability.js keeps for actors: the
+// adapters are dumb transport, and everything above them speaks 'normalized message'.
+
+export const CHANNEL_ACTOR_KIND = 'channel';
+
+/** The actor id a paired surface invokes under: '<platform>:<chatId>'. Stable per chat. */
+export function actorId(platform, chatId) {
+  return `${platform}:${chatId}`;
+}
+
+// A leading "/word" is a command to US (pair/stop/new/help), not a prompt for the agent.
+// Telegram appends "@BotName" to commands in groups; strip it so "/stop@mybot" === "/stop".
+function parseCommand(text) {
+  const m = /^\/([a-zA-Z0-9_]+)(?:@\w+)?(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!m) return null;
+  return { name: m[1].toLowerCase(), args: (m[2] || '').trim() };
+}
+
+/**
+ * Normalize a Telegram getUpdates result item. Returns null for updates we don't act on
+ * (edited messages, channel posts, join/leave events) so the caller skips them uniformly.
+ * A photo's caption is treated as its text, matching how a person reads the message.
+ */
+export function normalizeTelegram(update) {
+  const msg = update?.message;
+  if (!msg || !msg.chat) return null;
+  const text = typeof msg.text === 'string' ? msg.text
+    : typeof msg.caption === 'string' ? msg.caption : '';
+  // Largest photo variant only — Telegram sends a size ladder, last is the biggest.
+  const photos = Array.isArray(msg.photo) && msg.photo.length
+    ? [{ fileId: msg.photo[msg.photo.length - 1].file_id }]
+    : [];
+  const command = text.startsWith('/') ? parseCommand(text) : null;
+  return {
+    platform: 'telegram',
+    chatId: String(msg.chat.id),
+    chatType: msg.chat.type || 'private',
+    messageId: String(msg.message_id),
+    from: { id: String(msg.from?.id ?? msg.chat.id), name: msg.from?.first_name || msg.from?.username || '' },
+    text,
+    command,
+    photos,
+    replyToMessageId: msg.reply_to_message ? String(msg.reply_to_message.message_id) : null,
+  };
+}

package/src/pairing.js

@@ -0,0 +1,71 @@
+// Pairing — who may drive an agent from a phone, and how far their requests may travel.
+//
+// This is the AUTHENTICATION half of §7: it proves WHO sent a message (Telegram authenticates
+// the sender's chat id; a one-time code makes enrollment deliberate, not silent). It says
+// nothing about WHAT a message may do — a paired-but-injected message is still injected, so
+// `reach` is a ceiling, never a licence. Tool authorization is the next layer up.
+//
+// Reach reuses the router's tiers verbatim (device < trusted < any), so "a paired phone is
+// trusted" means the exact same thing here as it does to the model router downstream.
+
+import { REACH } from '@chatpanel/events/router.js';
+
+export { REACH };
+
+// 6 digits: enough entropy for a short-lived, single-use enrollment code shown on a screen,
+// short enough to thumb into a phone. It is NOT a password — it expires and burns on first use.
+function sixDigits(randomInt) {
+  return String(randomInt(0, 1_000_000)).padStart(6, '0');
+}
+
+/**
+ * A pairing store over a plain-JSON state object, with clock and RNG injected so enrollment
+ * is deterministic in tests. Persistence is the caller's job: load the JSON at start, call
+ * toJSON() after a mutation, write it back — the same shape as pii's createVault/vaultToJSON.
+ *
+ *   state: { paired: { [actorId]: { reach, at } }, pending: { [code]: { at, ttlMs } } }
+ */
+export function createPairingStore(state = {}, {
+  now = () => Date.now(),
+  randomInt = (min, max) => min + Math.floor(Math.random() * (max - min)),
+} = {}) {
+  const paired = new Map(Object.entries(state.paired || {}));
+  const pending = new Map(Object.entries(state.pending || {}));
+
+  const prune = () => {
+    const t = now();
+    for (const [code, p] of pending) if (t - p.at > (p.ttlMs || 0)) pending.delete(code);
+  };
+
+  return {
+    /** Owner-side: mint a one-time code to read out to the phone. Shown in the extension/CLI. */
+    requestCode({ ttlMs = 10 * 60_000 } = {}) {
+      prune();
+      let code;
+      do { code = sixDigits(randomInt); } while (pending.has(code));
+      pending.set(code, { at: now(), ttlMs });
+      return code;
+    },
+    /** Phone-side: "/pair 123456". Burns the code and pairs the actor at 'trusted'. */
+    redeem(actorId, code, { reach = 'trusted' } = {}) {
+      prune();
+      const c = String(code || '').trim();
+      if (!pending.has(c)) return { ok: false, reason: 'unknown or expired code' };
+      if (!REACH.includes(reach)) return { ok: false, reason: `unknown reach '${reach}'` };
+      pending.delete(c);
+      paired.set(actorId, { reach, at: now() });
+      return { ok: true, reach };
+    },
+    /** Bootstrap without a code — for an operator-supplied allow list. Explicit, not silent. */
+    allow(actorId, { reach = 'trusted' } = {}) {
+      if (!REACH.includes(reach)) throw new Error(`unknown reach '${reach}'`);
+      paired.set(actorId, { reach, at: now() });
+    },
+    revoke(actorId) { return paired.delete(actorId); },
+    isPaired(actorId) { return paired.has(actorId); },
+    /** The reach ceiling for this actor, or null when it isn't paired (→ refuse the message). */
+    reachOf(actorId) { return paired.get(actorId)?.reach || null; },
+    list() { return [...paired.entries()].map(([id, v]) => ({ actorId: id, ...v })); },
+    toJSON() { return { paired: Object.fromEntries(paired), pending: Object.fromEntries(pending) }; },
+  };
+}

package/src/stream.js

@@ -0,0 +1,77 @@
+// The model's reply, assembled from the bridge's SSE stream — PURE so accumulation and the
+// token-restore boundary are testable without a socket. Per chatpanel-bridge /chat, the bridge
+// emits `data: <json>\n\n` frames of:
+//   {type:'run', id}       a cancel-by-name handle, emitted first
+//   {type:'workdir'|'status'|'reasoning'|'tool', ...}  progress a caller MAY show
+//   {type:'delta', text}   incremental assistant text
+//   {type:'done', text?}   text only when it wasn't streamed
+//   {type:'error', error}
+// We only need run/delta/done/error to build a reply.
+
+export function initialState() {
+  return { runId: null, text: '', status: '', error: null, done: false };
+}
+
+/** Fold one bridge event into the running reply. Returns a NEW state (never mutates). */
+export function foldEvent(state, ev) {
+  switch (ev?.type) {
+    case 'run': return { ...state, runId: ev.id || state.runId };
+    case 'delta': return { ...state, text: state.text + (ev.text || '') };
+    case 'status': return { ...state, status: ev.text || state.status };
+    // A `done` may carry the whole text (engines that don't stream). Only take it when we
+    // streamed nothing, or the reply doubles.
+    case 'done': return { ...state, done: true, text: (!state.text && ev.text) ? ev.text : state.text };
+    case 'error': return { ...state, done: true, error: ev.error || 'unknown error' };
+    default: return state;
+  }
+}
+
+/**
+ * Pull complete SSE events out of a growing buffer. Returns the parsed events and the
+ * UNCONSUMED tail (a partial frame still arriving), which the caller prepends next read.
+ */
+export function parseSse(buffer) {
+  const events = [];
+  let rest = String(buffer);
+  let idx;
+  while ((idx = rest.indexOf('\n\n')) >= 0) {
+    const raw = rest.slice(0, idx);
+    rest = rest.slice(idx + 2);
+    for (const line of raw.split('\n')) {
+      if (!line.startsWith('data:')) continue;
+      const json = line.slice(5).trim();
+      if (!json) continue;
+      try { events.push(JSON.parse(json)); } catch { /* skip a malformed frame */ }
+    }
+  }
+  return { events, rest };
+}
+
+// Telegram rejects a message body over 4096 chars. Split on paragraph, then line, then a hard
+// cut, so a long answer arrives as several messages instead of one API error.
+export function splitForTelegram(text, max = 4096) {
+  let s = String(text ?? '');
+  const out = [];
+  while (s.length > max) {
+    let cut = s.lastIndexOf('\n\n', max);
+    if (cut < max * 0.5) cut = s.lastIndexOf('\n', max);
+    if (cut < max * 0.5) cut = max;
+    out.push(s.slice(0, cut));
+    s = s.slice(cut).replace(/^\n+/, '');
+  }
+  if (s) out.push(s);
+  return out.length ? out : [''];
+}
+
+// A minimal time gate for throttling live edits — Telegram allows ~1 edit/sec to a chat.
+// `now` injected for tests. ready() returns true and advances only when `ms` has elapsed.
+export function createGate(ms, { now = () => Date.now() } = {}) {
+  // -Infinity, not 0, so the FIRST call always fires (replace the "…" placeholder promptly)
+  // regardless of the clock's magnitude — then throttle. With last=0 this only worked because
+  // the real Date.now() dwarfs `ms`; an injected test clock at t=0 exposed the latent bug.
+  let last = -Infinity;
+  return {
+    ready() { const t = now(); if (t - last >= ms) { last = t; return true; } return false; },
+    reset() { last = -Infinity; },
+  };
+}