@chatpanel/channels 0.1.0 → 0.3.3

package/README.md

@@ -27,6 +27,7 @@ Telegram getUpdates ─long-poll→ @chatpanel/channels ─POST /chat (bridge to
 |---|---|---|
 | `src/normalize.js` | platform message → one normalized shape | ✅ |
 | `src/pairing.js` | who may drive it, and their `reach` ceiling | ✅ |
+| `src/service.js` | connect · pair · status · disconnect — the contract a UI drives | ✅ |
 | `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 |
@@ -34,7 +35,7 @@ Telegram getUpdates ─long-poll→ @chatpanel/channels ─POST /chat (bridge to
 | `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
+The pure core is unit-testable without a bot or a bridge (`npm test` = 45 tests, incl. a
 real-socket SSE integration test).
 
 Conversations are **multi-turn**: each chat keeps a bounded, redacted history so a follow-up
@@ -42,22 +43,38 @@ Conversations are **multi-turn**: each chat keeps a bounded, redacted history so
 
 ## Run
 
+**Most people never touch this package directly.** The ChatPanel bridge hosts the same service
+in-process, and the extension drives it: **Settings → Channels**, paste the token @BotFather
+gives you, tap *Pair a phone*, open the link on the phone. Two steps, one paste, no terminal.
+That is the supported path, and it is what the security posture below was written for.
+
+What follows is the **headless** host — for a server, or for anyone who would rather run it
+themselves.
+
 ```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:
+3. Put the token in a file only you can read — it is a bearer credential, and an env var is
+   visible in `ps` and shell history:
 
 ```sh
-TELEGRAM_BOT_TOKEN=123:abc chatpanel-channels telegram
+umask 077 && printf %s '123:abc' > ~/.chatpanel/telegram-token
+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.
+4. With no phone paired yet, startup prints the link that pairs in one tap, and the code to
+   type if you are not on that phone:
+
+   ```
+   [chatpanel-channels] no phone is paired yet. Open this on your phone:
+       https://t.me/your_bot?start=481920
+     …or send  /pair 481920  to the bot (single use, expires in 10 minutes).
+   ```
+
+   (`CHANNELS_ALLOW=<chatId>` still pre-pairs without a code for scripted setups.)
 
 Chat commands: `/pair <code>`, `/new` (forget the conversation + fresh privacy vault), `/stop`, `/help`.
 
@@ -65,7 +82,8 @@ Chat commands: `/pair <code>`, `/new` (forget the conversation + fresh privacy v
 
 | var | default | meaning |
 |---|---|---|
-| `TELEGRAM_BOT_TOKEN` | — | BotFather token (required) |
+| `TELEGRAM_BOT_TOKEN_FILE` | `~/.chatpanel/telegram-token` | `0600` file holding the BotFather token (preferred) |
+| `TELEGRAM_BOT_TOKEN` | — | the token via env instead (compat; visible in `ps`/history) |
 | `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 |

package/bin/chatpanel-channels.js

@@ -1,10 +1,17 @@
 #!/usr/bin/env node
 // chatpanel-channels — run a messaging adapter that drives your local ChatPanel agent.
 //
+// This is the HEADLESS host. Most people never see it: the bridge hosts the same
+// `createChannelService` in-process and the ChatPanel extension drives it from Settings →
+// Channels, so connecting a bot is paste-a-token-and-tap-a-link rather than a terminal. This
+// exists for servers, and for anyone who would rather run it themselves.
+//
 //   chatpanel-channels telegram
 //
 // Env:
-//   TELEGRAM_BOT_TOKEN     BotFather token (required)                    [or BOT_TOKEN]
+//   TELEGRAM_BOT_TOKEN_FILE  path to a 0600 file holding the BotFather token (preferred)
+//   TELEGRAM_BOT_TOKEN       token via env (compat; visible in ps/history) [or BOT_TOKEN]
+//                            (default file if neither set: ~/.chatpanel/telegram-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)
@@ -13,57 +20,60 @@
 //   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 {}; }
-}
+import { bridgeBaseUrl, readBridgeToken, readBotToken, channelsHome, channelsDataDir } from '../src/config.js';
+import { createChannelService } from '../src/service.js';
 
 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 service = createChannelService({
+    home: channelsHome(),
+    dataDir: channelsDataDir(),
+    bridge: { baseUrl, token: await readBridgeToken() },
+  });
 
-  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 });
+  const settings = {
+    agent: process.env.CHANNELS_AGENT || undefined,
+    privacy: process.env.CHANNELS_PRIVACY || undefined,
+    tier: process.env.CHANNELS_PII_TIER || undefined,
+    system: process.env.CHANNELS_SYSTEM || undefined,
+  };
+  if (Object.values(settings).some(Boolean)) await service.update(settings);
 
-  // Bootstrap allow-list (prototype convenience). Each becomes a paired 'trusted' actor —
-  // explicitly, never silent enrollment. Prefer /pair codes for real use.
+  // Bootstrap allow-list (scripted setups). Each becomes a paired 'trusted' actor — explicitly,
+  // never silent enrollment. Everyone else pairs with a code or the one-tap link.
   for (const chatId of (process.env.CHANNELS_ALLOW || '').split(',').map((s) => s.trim()).filter(Boolean)) {
-    pairing.allow(`telegram:${chatId}`);
+    await service.allow(`telegram:${chatId}`);
   }
-  await savePairing();
 
-  const appender = await createEventLog({ file: path.join(dataDir, 'events.jsonl'), host: 'channel' });
+  // A token in the environment is a token in `ps` and in your shell history. Connecting it once
+  // verifies it with Telegram and moves it into a 0600 file, so the next start needs no env.
+  const { token: botToken, source } = await readBotToken();
+  if (!botToken) {
+    console.error('no bot token — write it to ~/.chatpanel/telegram-token (chmod 600), set TELEGRAM_BOT_TOKEN_FILE, or export TELEGRAM_BOT_TOKEN (from @BotFather)');
+    process.exit(1);
+  }
+  const started = source === 'env'
+    ? await service.connect({ token: botToken }).then((r) => ({ ok: true, ...r }), (e) => ({ ok: false, error: e.message }))
+    : await service.start();
+  if (!started.ok) { console.error(`[chatpanel-channels] ${started.error}`); process.exit(1); }
 
-  const controller = new AbortController();
-  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => controller.abort());
+  const status = await service.status();
+  console.log(`[chatpanel-channels] telegram @${status.bot?.username} → bridge ${baseUrl} (agent=${status.settings.agent}, privacy=${status.settings.privacy}, tier=${status.settings.tier})`);
 
-  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,
-  });
+  // TIME TO FIRST MESSAGE. With nothing paired the bot answers every message "get a code" and
+  // there is nowhere to get one, which reads as broken rather than as locked. The link pairs in
+  // one tap; the six digits are for reading off this screen onto a phone.
+  if (!status.paired.length) {
+    const { code, link } = await service.pair();
+    console.log(`[chatpanel-channels] no phone is paired yet. Open this on your phone:\n    ${link}\n  …or send  /pair ${code}  to the bot (single use, expires in 10 minutes).`);
+  }
+
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { service.stop().finally(() => process.exit(0)); });
+  await new Promise(() => {}); // the service owns the loop; stay alive until signalled
 }
 
 main().catch((e) => { console.error(e?.message || e); process.exit(1); });

package/index.js

@@ -16,3 +16,4 @@ 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';
+export { createChannelService, verifyBot, pairLink, DEFAULT_SETTINGS } from './src/service.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.3.3",
+  "description": "Drive ChatPanel agents from external messaging surfaces (Telegram, WhatsApp). One normalize\u2192invoke\u2192stream 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 \u2014 the same property as Claude Code Remote Control. Pure, dependency-free ESM.",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -11,6 +11,7 @@
     "./invoke.js": "./src/invoke.js",
     "./stream.js": "./src/stream.js",
     "./bridge.js": "./src/bridge.js",
+    "./service.js": "./src/service.js",
     "./eventlog.js": "./src/eventlog.js",
     "./adapters/telegram.js": "./src/adapters/telegram.js"
   },
@@ -29,7 +30,7 @@
     "start": "node bin/chatpanel-channels.js telegram"
   },
   "dependencies": {
-    "@chatpanel/events": "^0.21.0",
+    "@chatpanel/events": "^0.23.0",
     "@chatpanel/pii": "^0.3.0"
   },
   "keywords": [

package/src/adapters/telegram.js

@@ -5,7 +5,7 @@
 
 import { normalizeTelegram, actorId } from '../normalize.js';
 import {
-  buildInvocation, redactInbound, restoreOutbound, appendTurn,
+  buildInvocation, redactInbound, outboundText, appendTurn,
   appendInvoked, appendRedacted, appendEgress,
 } from '../invoke.js';
 import * as bridge from '../bridge.js';
@@ -18,7 +18,7 @@ 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)',
+  '/pair <code> — enroll this chat (ChatPanel → Settings → Channels)',
   '/new         — start fresh (forget this conversation + new privacy vault)',
   '/stop        — stop the current run',
   '/help        — this message',
@@ -29,6 +29,29 @@ const HELP = [
  * 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.
  */
+// What a turn driven from a phone can actually DO, told to the agent up front.
+//
+// Without this the agent plans as if it were sitting at a terminal: asked to create a note it
+// announced it would look for a notes folder, discovered writes were not enabled, said "let me
+// check what notes tools are available" — and stopped mid-thought, having done nothing and
+// explained nothing. The ceiling is real and enforced elsewhere (reach caps the toolset); the
+// agent simply had no way to know about it, so it spent a turn discovering it and left the
+// user staring at half a sentence.
+export function channelSystem(userSystem, reach) {
+  const limits = !reach || reach === 'any' ? '' : [
+    "You are answering a message sent from the user's PHONE, relayed to this machine.",
+    reach === 'device'
+      ? 'You cannot read files, run commands, browse the web, or change anything.'
+      : "You can READ files and search the user's ChatPanel history. You cannot write or edit "
+        + 'files, run shell commands, or browse the web — those are switched off for messages '
+        + 'from a phone, and no tool will grant them.',
+    'If a request needs something you cannot do, say so plainly in your FIRST reply and offer '
+      + 'what you can do instead. Never begin work you cannot finish.',
+    'Answers are read on a phone: be brief, and put the answer first.',
+  ].join(' ');
+  return [limits, userSystem].filter(Boolean).join('\n\n');
+}
+
 export function startTelegram({
   botToken,
   baseUrl,
@@ -37,7 +60,23 @@ export function startTelegram({
   savePairing = async () => {},
   appender,                    // createEventLog(...) or nullEventLog()
   agent = 'claude',
+  // Which transport answers, and with what. `bridge` runs a CLI agent on this machine;
+  // `gateway` reaches any destination the user configured there — an API provider or, via the
+  // gateway's own bridge backend, the same CLI agents. The adapter must not be able to tell
+  // which it has: both expose chat()/cancel() and fold into one reply state.
+  transport = bridge,
+  model = '',
+  provider = '',
   system = '',
+  // Read at the START OF EACH MESSAGE rather than captured when the loop starts.
+  //
+  // `chats` below holds every conversation's history AND its privacy vault, and it lives only
+  // as long as this loop. Settings used to be baked in at start, so changing the model — or
+  // the privacy mode, or anything else — had to stop and respawn the loop, which silently threw
+  // all of that away: the next message arrived as "a fresh session with no prior conversation",
+  // and PERSON_1 stopped meaning the same person. Switching which model answers is not a
+  // reason to forget what you were talking about.
+  route = null,
   redact = { tier: 'basic' },
   privacy = 'standard',
   logger = console,
@@ -85,19 +124,27 @@ export function startTelegram({
   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);
+    // `/start <code>` is what a t.me/<bot>?start=<code> link SENDS. Telegram turns the link
+    // into that first message, so tapping "Pair this phone" in ChatPanel enrolls in one tap —
+    // no six digits thumbed in from another screen. Bare /start is still the greeting.
+    const pairCode = name === 'pair' || (name === 'start' && args) ? args : '';
+    if (pairCode) {
+      const r = pairing.redeem(id, pairCode, { label: norm.from?.name || '' });
       await savePairing();
-      return void send(norm.chatId, r.ok ? `✅ paired (reach: ${r.reach}). Send me anything.` : `⛔ ${r.reason}`);
+      return void send(norm.chatId, r.ok
+        ? `✅ paired (reach: ${r.reach}). Send me anything — I'll run it on your machine.`
+        : `⛔ ${r.reason}`);
     }
+    if (name === 'help' || name === 'start') return void send(norm.chatId, HELP);
+    if (name === 'pair') return void send(norm.chatId, 'send /pair <code> — get the code in ChatPanel → Settings → Channels');
     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 });
+      const liveRoute = (route && route()) || {};
+      const ok = await (liveRoute.transport || transport).cancel(st.runId, { baseUrl: liveRoute.baseUrl || baseUrl, token: liveRoute.token || token });
       st.runId = null;
       return void send(norm.chatId, ok ? '⏹ stopped.' : 'nothing running.');
     }
@@ -134,16 +181,29 @@ export function startTelegram({
     // on the bridge renders all-but-last as history and the last as "answer this now".
     const messages = [...st.history, { role: 'user', content: redacted }];
 
+    // Whatever the settings say RIGHT NOW — see `route` above.
+    const live = (route && route()) || {};
+    const useTransport = live.transport || transport;
     try {
-      const finalState = await bridge.chat(
-        { agent, system, messages, images, options: { reach } },
+      const finalState = await useTransport.chat(
         {
-          baseUrl, token, signal,
+          agent: live.agent ?? agent,
+          model: live.model ?? model,
+          provider: live.provider ?? provider,
+          system: channelSystem(live.system ?? system, reach),
+          messages,
+          images,
+          options: { reach },
+        },
+        {
+          baseUrl: live.baseUrl || baseUrl, token: live.token || 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 });
+            if (state.runId) st.runId = state.runId;
+            // Driven by the folded STATE, not by an event's `type`: the bridge emits
+            // {type:'delta'} and the gateway emits OpenAI chunks, and this has to work on both.
+            // The `first !== shown` guard below makes a no-text event a no-op anyway.
+            if (replyId && (state.done || gate.ready())) {
+              const text = outboundText(state.text, st.vault, { privacy });
               const first = splitForTelegram(text || '…')[0];
               if (first && first !== shown) { shown = first; edit(norm.chatId, replyId, first).catch(() => {}); }
             }
@@ -152,7 +212,7 @@ export function startTelegram({
       );
       st.runId = null;
 
-      const restored = restoreOutbound(finalState.text, st.vault, { privacy });
+      const restored = outboundText(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]);
@@ -175,6 +235,16 @@ export function startTelegram({
     }
   }
 
+  // A sleep that gives up when the loop is asked to stop, so Ctrl-C is immediate rather than
+  // "immediate in up to five seconds".
+  const nap = (ms) => new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    let t;
+    const done = () => { clearTimeout(t); signal?.removeEventListener?.('abort', done); resolve(); };
+    t = setTimeout(done, ms);
+    signal?.addEventListener?.('abort', done, { once: true });
+  });
+
   async function loop() {
     let offset = 0;
     logger.log?.('[telegram] long-poll started (outbound-only; no inbound port).');
@@ -182,11 +252,26 @@ export function startTelegram({
       let updates;
       try {
         const res = await tg('getUpdates', { offset, timeout: 30, allowed_updates: ['message'] });
+        // Telegram REFUSES with a normal JSON body, not an HTTP error this code would throw
+        // on: a bad token answers {ok:false, 401} INSTANTLY, so `res.result || []` turned a
+        // wrong token into a silent hot loop — no message, no long-poll delay, and an API
+        // hammered hard enough to get rate-limited. The two refusals that actually happen
+        // during setup are named, because "nothing arrives" is the same symptom as "it works
+        // and nobody has texted you".
+        if (res && res.ok === false) {
+          const code = res.error_code;
+          const hint = code === 401 ? ' — check the bot token (@BotFather → /mybots → API token)'
+            : code === 409 ? ' — another chatpanel-channels (or another poller) is already reading this bot'
+              : '';
+          logger.error?.(`[telegram] getUpdates refused: ${res.description || `error_code ${code}`}${hint}`);
+          await nap(5000);
+          continue;
+        }
         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));
+        await nap(2000);
         continue;
       }
       for (const u of updates) {

package/src/config.js

@@ -3,7 +3,7 @@
 
 import os from 'node:os';
 import path from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } 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.
@@ -33,3 +33,31 @@ export async function readBridgeToken(env = process.env) {
   } 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`);
 }
+
+// The BotFather token is a bearer credential: whoever holds it can send AND receive as your bot,
+// i.e. read every message in the chat. So prefer a 0600 FILE (like the bridge token) over an env
+// var, which leaks into `ps`, shell history, and every child process's environment. Order:
+//   1. TELEGRAM_BOT_TOKEN_FILE (explicit path)
+//   2. ~/.chatpanel/telegram-token (default file)
+//   3. TELEGRAM_BOT_TOKEN / BOT_TOKEN (env — compat, with a warning)
+// Returns { token, source }; token is null when nothing is configured (caller errors cleanly).
+export async function readBotToken(env = process.env, { logger = console } = {}) {
+  const file = env.TELEGRAM_BOT_TOKEN_FILE || path.join(channelsHome(env), 'telegram-token');
+  try {
+    const raw = (await readFile(file, 'utf8')).trim();
+    if (raw) {
+      try {
+        const { mode } = await stat(file);
+        // Any group/other permission bit set on a file holding a bearer secret is worth flagging.
+        if (mode & 0o077) logger.warn?.(`[chatpanel-channels] ${file} is group/world-readable — run: chmod 600 ${file} (it holds your bot token).`);
+      } catch { /* stat is best-effort; a readable token still works */ }
+      return { token: raw, source: file };
+    }
+  } catch { /* no file → fall back to env */ }
+  const envTok = (env.TELEGRAM_BOT_TOKEN || env.BOT_TOKEN || '').trim();
+  if (envTok) {
+    logger.warn?.('[chatpanel-channels] reading the bot token from the environment — it is visible in `ps` and shell history. Prefer a 0600 file at ~/.chatpanel/telegram-token (or set TELEGRAM_BOT_TOKEN_FILE).');
+    return { token: envTok, source: 'env' };
+  }
+  return { token: null, source: null };
+}

package/src/gateway.js

@@ -0,0 +1,110 @@
+// Gateway backend: reach ANY configured destination — an API provider or a CLI agent —
+// through the ChatPanel gateway's OpenAI-compatible endpoint.
+//
+//   channel  →  POST http://127.0.0.1:4320/v1/chat/completions  { model, messages, stream }
+//
+// WHY THIS EXISTS ALONGSIDE bridge.js. The bridge runs CLI agents, and that is all it can
+// answer with — so a phone could only ever talk to Claude Code or Codex, never to the OpenAI,
+// Anthropic or local-model endpoints the same user already configured. Those live in the
+// gateway, which persists its `destinations` (0600, keys included) and routes a model id to
+// an API provider OR back to the bridge for an agent. So the gateway is the superset, and
+// pointing a channel at it is what makes "answer from my phone" work with every target the
+// user has rather than a subset.
+//
+// NO NEW SECRET. The alternative was teaching the bridge to hold provider API keys, which
+// would have put them on disk a second time, in a second format, with a second thing to
+// rotate. The gateway already holds them and already guards them; this borrows the routing
+// instead of copying the credentials.
+//
+// THE GATEWAY TOKEN. The /v1 data plane is open to local clients for API destinations —
+// but a destination that is an AGENT spawns a process on this machine, and since gateway
+// 0.9.0 that lane is closed to a caller that has not proved it runs as the user. The
+// service reads ~/.chatpanel/gateway-token (0600) and hands it here as `token`; sent as a
+// bearer, exactly as the bridge transport sends the bridge token. Absent → sent without,
+// which an older gateway accepts and a newer one refuses with a message naming the fix.
+
+import { parseSse, foldOpenAiEvent, initialState } from './stream.js';
+
+// Per-turn aborts, so /stop can cancel a gateway turn the way it cancels a bridge run. The
+// bridge hands out a run id for this; OpenAI's API has no such handle, so we mint one and
+// keep the controller behind it rather than leaving /stop silently broken on this transport.
+const inflight = new Map();
+
+/**
+ * Drive one turn against a gateway destination. Same shape as bridge.chat so the adapter does
+ * not know which transport it has: streams events to onEvent(ev, state) and returns the folded
+ * final state.
+ */
+export async function chat({ model = '', provider = '', system = '', messages = [], options = {} }, {
+  baseUrl, token = '', signal, onEvent = () => {},
+} = {}) {
+  const runId = `gw_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+  const ac = new AbortController();
+  inflight.set(runId, ac);
+  // The caller's signal (the poll loop shutting down) must still abort the turn.
+  const relay = () => ac.abort();
+  signal?.addEventListener?.('abort', relay, { once: true });
+
+  let state = initialState();
+  const emit = (ev) => { state = foldOpenAiEvent(state, ev); onEvent(ev, state); };
+  emit({ type: 'run', id: runId });
+
+  try {
+    const res = await fetch(`${String(baseUrl).replace(/\/$/, '')}/v1/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+        // ChatPanel's routing metadata goes in HEADERS, never in the request body. It rode the
+        // body first and NVIDIA answered "unsupported parameters": OpenAI-compatible providers
+        // validate the body strictly and reject unknown fields, while ignoring unknown headers.
+        // The gateway strips x-chatpanel-* before forwarding, so the provider never sees it.
+        ...(options?.reach ? { 'x-chatpanel-reach': options.reach } : {}),
+        // WHICH provider, not just which model. A model id is not a unique key — two providers
+        // can serve the same one — so without this the gateway picks whichever destination it
+        // lists first and the call goes out on a key the user never chose.
+        ...(provider ? { 'x-chatpanel-destination': provider } : {}),
+      },
+      body: JSON.stringify({
+        model,
+        stream: true,
+        messages: [
+          ...(system ? [{ role: 'system', content: system }] : []),
+          ...messages.map((m) => ({ role: m.role, content: String(m.content ?? '') })),
+        ],
+      }),
+      signal: ac.signal,
+    });
+    if (!res.ok || !res.body) {
+      const detail = await res.text().catch(() => '');
+      throw new Error(`gateway ${res.status}${detail ? `: ${detail.slice(0, 300)}` : ''}`);
+    }
+    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) emit(ev);
+    }
+    // OpenAI streams end with `data: [DONE]`, which is not JSON and is dropped by parseSse —
+    // so a stream that ended cleanly still has to be marked done here.
+    if (!state.done) state = { ...state, done: true };
+    return state;
+  } catch (e) {
+    if (ac.signal.aborted) return { ...state, done: true };
+    return { ...state, done: true, error: e?.message || String(e) };
+  } finally {
+    inflight.delete(runId);
+    signal?.removeEventListener?.('abort', relay);
+  }
+}
+
+/** Stop a run by the id emitted as the first {type:'run'} event. Best-effort, like the bridge's. */
+export async function cancel(runId) {
+  const ac = runId && inflight.get(runId);
+  if (!ac) return false;
+  ac.abort();
+  inflight.delete(runId);
+  return true;
+}

package/src/invoke.js

@@ -4,7 +4,7 @@
 // adapter owns the network, this owns the contract.
 
 import { validateInvocation } from '@chatpanel/events/capability.js';
-import { redactText, restoreText, redactionSummary } from '@chatpanel/pii';
+import { createVault, 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
@@ -67,6 +67,50 @@ export function restoreOutbound(text, vault, { privacy = 'standard' } = {}) {
   return privacy === 'strict' ? String(text ?? '') : restoreText(text ?? '', vault);
 }
 
+// A [[TYPE_n]] placeholder token; the capture is the entity TYPE.
+const TOKEN_MARKER_RE = /\[\[([A-Z][A-Z0-9]*)_\d+\]\]/g;
+
+// Hard credentials: catastrophic if they reach a third-party provider, and a user practically
+// never types their own into a chat — so we mask these on EVERY egress regardless of privacy
+// mode. Contact PII (EMAIL/PHONE/IP) is deliberately NOT here: re-masking it would gut standard
+// mode (the user could never read their own data back), so it follows the privacy mode instead.
+export const EGRESS_SECRET_TYPES = new Set(['SECRET', 'KEY', 'CARD', 'SSN']);
+
+/**
+ * EGRESS SCRUB. Inbound redaction only covers the user's typed message — but the agent can
+ * surface a NEW secret the vault never saw: a key/token/card it read from a file or a tool and
+ * echoed into the reply. The reply itself is an egress to a provider (Telegram/Meta) that is NOT
+ * end-to-end encrypted, so that fresh secret would transit in the clear. This runs a fresh
+ * detector pass into a THROWAWAY vault and permanently masks the hard-credential types to a
+ * readable '‹type redacted›' marker.
+ *
+ * Run this AFTER restore: at that point no real chat-vault tokens remain, so the single throwaway
+ * vault numbers cleanly (no [[TYPE_n]] collision) and non-secret detections can be re-expanded to
+ * the value the user is allowed to read. `restoreNonSecret:false` (strict mode) keeps everything
+ * tokenized so no real value — fresh or otherwise — is emitted.
+ */
+export function scrubEgress(text, { secretTypes = EGRESS_SECRET_TYPES, restoreNonSecret = true } = {}) {
+  if (text == null || text === '') return text ?? '';
+  const tv = createVault();
+  const masked = redactText(String(text), tv, { tier: 'basic' });
+  return masked.replace(TOKEN_MARKER_RE, (full, type) => {
+    if (secretTypes.has(type.toUpperCase())) return `‹${type.toLowerCase()} redacted›`;
+    return restoreNonSecret ? (tv.byToken.get(full) ?? full) : full;
+  });
+}
+
+/**
+ * The single outbound transform: what to actually SEND to the provider for one reply.
+ *  - 'standard': restore the user's own values (they read their own data back), THEN scrub — so
+ *    contact PII the user typed survives, but any hard credential the agent surfaced is masked.
+ *  - 'strict': keep the user's values as placeholders AND still mask fresh credentials, so
+ *    'strict' is never weaker than 'standard'.
+ */
+export function outboundText(text, vault, { privacy = 'standard' } = {}) {
+  const restored = restoreOutbound(text, vault, { privacy });
+  return scrubEgress(restored, { restoreNonSecret: privacy !== 'strict' });
+}
+
 // 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

package/src/pairing.js

@@ -8,12 +8,23 @@
 // 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';
+import { REACH } from '@chatpanel/events/reach.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.
+// A display name from a remote platform is untrusted text that lands in the owner's settings
+// screen: strip control characters and bidi overrides (which can make one name render as
+// another), collapse whitespace, and cap it. The UI escapes too — this is the other half.
+function cleanLabel(value) {
+  return String(value || '')
+    .replace(/[\u0000-\u001f\u007f\u200b-\u200f\u202a-\u202e\u2066-\u2069]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 48);
+}
+
 function sixDigits(randomInt) {
   return String(randomInt(0, 1_000_000)).padStart(6, '0');
 }
@@ -46,20 +57,24 @@ export function createPairingStore(state = {}, {
       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' } = {}) {
+    /** Phone-side: "/pair 123456". Burns the code and pairs the actor at 'trusted'.
+     *  `label` is whatever the platform calls the person (a Telegram first name or @handle) —
+     *  stored so the owner's screen can say WHICH phone it just enrolled. An opaque
+     *  'telegram:789795542' is not something anyone can recognise, and the whole point of the
+     *  list is deciding whether to revoke one. Display only: authorization is by actorId. */
+    redeem(actorId, code, { reach = 'trusted', label = '' } = {}) {
       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() });
+      paired.set(actorId, { reach, at: now(), label: cleanLabel(label) });
       return { ok: true, reach };
     },
     /** Bootstrap without a code — for an operator-supplied allow list. Explicit, not silent. */
-    allow(actorId, { reach = 'trusted' } = {}) {
+    allow(actorId, { reach = 'trusted', label = '' } = {}) {
       if (!REACH.includes(reach)) throw new Error(`unknown reach '${reach}'`);
-      paired.set(actorId, { reach, at: now() });
+      paired.set(actorId, { reach, at: now(), label: cleanLabel(label) });
     },
     revoke(actorId) { return paired.delete(actorId); },
     isPaired(actorId) { return paired.has(actorId); },

package/src/service.js

@@ -0,0 +1,328 @@
+// The channel SERVICE — connect · pair · status · disconnect, as one contract a UI can drive.
+//
+// The adapter is a loop. A *service* is what a person can actually operate: is it connected,
+// to which bot, who is paired, give me a code, stop it. That contract lives here rather than
+// inside whichever process happens to host the loop, because there is more than one host — the
+// bridge (always on, and what a non-technical user already has), the CLI (headless boxes), and
+// a desktop app later. Three hosts implementing "connect a bot" is three different security
+// postures for the same secret.
+//
+// It owns exactly the state a channel has:
+//   • the bot token — a 0600 file, read at start, NEVER returned by status();
+//   • the pairing store — who may drive an agent, and their reach ceiling;
+//   • the per-channel settings — which agent answers, and the privacy mode.
+//
+// It owns none of the transport around it: no HTTP, no auth, no UI. The host does that, which
+// is why this module needs no server and is testable with a stub fetch.
+
+import path from 'node:path';
+import { readFile, writeFile, mkdir, rm, stat } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { createPairingStore } from './pairing.js';
+import * as bridgeTransport from './bridge.js';
+import * as gateway from './gateway.js';
+
+// The gateway's fixed local port (see chatpanel-gateway: 4319 bridge / 4320 gateway).
+const DEFAULT_GATEWAY_URL = 'http://127.0.0.1:4320';
+import { createEventLog } from './eventlog.js';
+import { startTelegram } from './adapters/telegram.js';
+
+const TELEGRAM_API = 'https://api.telegram.org';
+// `agent` routes through the bridge (a CLI on this machine). `model` routes through the
+// gateway, which reaches every destination the user configured there — API providers AND, via
+// its own bridge backend, the same agents. They are mutually exclusive: update() clears one
+// when the other is set, because "which thing answers" is one choice, not two.
+export const DEFAULT_SETTINGS = Object.freeze({
+  agent: 'claude', model: '', provider: '', gatewayUrl: DEFAULT_GATEWAY_URL,
+  privacy: 'standard', tier: 'basic',
+});
+
+// Restart backoff. A long-poll that dies (network drop, laptop asleep, Telegram hiccup) must
+// come back on its own — a channel nobody is watching is exactly the one that must self-heal —
+// but a token that has been REVOKED would otherwise spin forever, so the wait grows.
+const RETRY_MS = [2_000, 5_000, 15_000, 60_000];
+
+const readJson = async (file, fallback) => {
+  try { return JSON.parse(await readFile(file, 'utf8')); } catch { return fallback; }
+};
+const writeJson = (file, value) => writeFile(file, JSON.stringify(value, null, 2), { mode: 0o600 });
+
+/**
+ * Ask Telegram who this token belongs to. This is the ONLY validation that matters at connect
+ * time: a typo'd token must fail in the settings screen, with a reason, rather than becoming a
+ * silent poll loop nobody sees the logs of.
+ */
+export async function verifyBot(botToken, { fetchImpl = fetch, signal } = {}) {
+  const res = await fetchImpl(`${TELEGRAM_API}/bot${String(botToken || '').trim()}/getMe`, { signal });
+  const body = await res.json().catch(() => null);
+  if (!body?.ok) {
+    const why = body?.description || `HTTP ${res.status}`;
+    throw new Error(/unauthorized/i.test(why) ? 'Telegram rejected that token — copy it again from @BotFather' : why);
+  }
+  return { id: body.result.id, username: body.result.username, name: body.result.first_name || '' };
+}
+
+/** The t.me link that pairs in one tap: Telegram turns it into "/start <code>" in the chat. */
+export const pairLink = (username, code) => `https://t.me/${username}?start=${code}`;
+
+export function createChannelService({
+  home,                          // ~/.chatpanel — where the token file lives
+  dataDir,                       // ~/.chatpanel/channels — pairing, config, event log
+  bridge,                        // { baseUrl, token } — how the adapter reaches the agent
+  logger = console,
+  fetchImpl = undefined,         // injected in tests
+  now = () => Date.now(),
+  // The adapter is injectable for the same reason fetchImpl is: the thing worth asserting
+  // about the loop is WHAT it is handed, and a real Telegram long-poll cannot be asked.
+  startAdapter = startTelegram,
+} = {}) {
+  const tokenFile = path.join(home, 'telegram-token');
+  const configFile = path.join(dataDir, 'config.json');
+  const pairingFile = path.join(dataDir, 'pairing.json');
+
+  let pairing = null; // created by load(), then kept — see the note there
+  let settings = { ...DEFAULT_SETTINGS };
+  let appender = null;
+  let bot = null;              // { id, username, name } once verified
+  let controller = null;       // aborts the running loop
+  let running = false;
+  let lastError = '';
+  let attempt = 0;
+  let stopped = true;          // deliberate stop — suppresses the restart
+
+  const savePairing = () => writeJson(pairingFile, pairing ? pairing.toJSON() : {});
+  const saveSettings = () => writeJson(configFile, settings);
+
+  async function readToken() {
+    try {
+      const t = (await readFile(tokenFile, 'utf8')).trim();
+      if (!t) return '';
+      try {
+        const { mode } = await stat(tokenFile);
+        if (mode & 0o077) logger.warn?.(`[channels] ${tokenFile} is group/world-readable — chmod 600 it (it holds your bot token).`);
+      } catch { /* best effort */ }
+      return t;
+    } catch { return ''; }
+  }
+
+  async function load() {
+    await mkdir(dataDir, { recursive: true });
+    // Built ONCE and never replaced. spawnLoop() hands this exact object to the adapter, which
+    // holds it for the life of a polling loop — so rebuilding it here (as every service call
+    // used to) broke pairing in both directions at once: `pair()` minted the code into a fresh
+    // store the adapter could not see, so every redeem answered "unknown or expired code" no
+    // matter how many codes you generated; and `savePairing()` serialises whichever store this
+    // variable currently points at, so a redeem that DID land would have been persisted from
+    // the wrong object. Two aliases of one thing is the bug — there is only ever one store.
+    if (!pairing) pairing = createPairingStore(await readJson(pairingFile, {}), { now });
+    settings = { ...DEFAULT_SETTINGS, ...(await readJson(configFile, {})) };
+    if (!appender) appender = await createEventLog({ file: path.join(dataDir, 'events.jsonl'), host: 'channel' });
+  }
+
+  // One supervised run of the loop. Resolves when the loop ends; schedules its own restart
+  // unless the stop was deliberate.
+  function spawnLoop(botToken) {
+    controller = new AbortController();
+    running = true;
+    // Resolved PER MESSAGE, not once at start. The loop owns every conversation's history and
+    // privacy vault, so restarting it to pick up a settings change threw away the thing the
+    // user came for. Now nothing needs a restart: the next message simply reads this.
+    // The gateway's own token, read when a turn needs it rather than once at startup: the
+    // gateway writes it on ITS first start, which may be after ours. Best effort — absent,
+    // the call goes without and the gateway's answer says what to do.
+    const gatewayToken = () => {
+      try { return readFileSync(path.join(home, 'gateway-token'), 'utf8').trim(); } catch { return ''; }
+    };
+    const route = () => {
+      const viaGateway = !!settings.model;
+      return {
+        transport: viaGateway ? gateway : bridgeTransport,
+        token: viaGateway ? gatewayToken() : bridge.token,
+        agent: viaGateway ? '' : settings.agent,
+        model: viaGateway ? settings.model : '',
+        provider: viaGateway ? (settings.provider || '') : '',
+        baseUrl: viaGateway ? (settings.gatewayUrl || DEFAULT_GATEWAY_URL) : bridge.baseUrl,
+        system: settings.system || '',
+        privacy: settings.privacy,
+      };
+    };
+    const done = startAdapter({
+      botToken,
+      route,
+      transport: route().transport,
+      model: route().model,
+      provider: route().provider,
+      baseUrl: route().baseUrl,
+      token: bridge.token,
+      pairing,
+      savePairing,
+      appender,
+      agent: settings.agent,
+      system: settings.system || '',
+      redact: { tier: settings.tier },
+      privacy: settings.privacy,
+      logger,
+      signal: controller.signal,
+    });
+    Promise.resolve(done)
+      .catch((e) => { lastError = e?.message || String(e); logger.warn?.(`[channels] telegram loop failed: ${lastError}`); })
+      .finally(() => {
+        running = false;
+        if (stopped) return;
+        const wait = RETRY_MS[Math.min(attempt++, RETRY_MS.length - 1)];
+        logger.warn?.(`[channels] telegram stopped unexpectedly — retrying in ${Math.round(wait / 1000)}s`);
+        setTimeout(() => { if (!stopped) spawnLoop(botToken); }, wait).unref?.();
+      });
+  }
+
+  async function start() {
+    if (running) return { ok: true, already: true };
+    await load();
+    const botToken = await readToken();
+    if (!botToken) return { ok: false, error: 'no bot token configured' };
+    if (settings.enabled === false) return { ok: false, error: 'channel is turned off' };
+    try {
+      bot = await verifyBot(botToken, { fetchImpl });
+    } catch (e) {
+      // A revoked or mistyped token must SAY so and stay stopped — a poll loop against a dead
+      // token is the failure that looks like "nobody has messaged me yet".
+      lastError = e?.message || String(e);
+      return { ok: false, error: lastError };
+    }
+    lastError = '';
+    attempt = 0;
+    stopped = false;
+    spawnLoop(botToken);
+    return { ok: true, bot };
+  }
+
+  return {
+    /** Start on host boot, but only if the user already connected one. Never throws. */
+    async startIfConfigured() {
+      await load();
+      if (!(await readToken()) || settings.enabled === false) return { ok: false, skipped: true };
+      return start().catch((e) => ({ ok: false, error: e?.message || String(e) }));
+    },
+
+    start,
+
+    /**
+     * Connect a bot: verify the token FIRST, then persist it 0600 and start. Verifying before
+     * writing means a typo never leaves a dead secret on disk.
+     */
+    async connect({ token: botToken, agent, privacy, tier } = {}) {
+      await load();
+      const verified = await verifyBot(botToken, { fetchImpl }); // throws with a readable reason
+      await writeFile(tokenFile, String(botToken).trim(), { mode: 0o600 });
+      settings = {
+        ...settings,
+        ...(agent ? { agent } : {}),
+        ...(privacy ? { privacy } : {}),
+        ...(tier ? { tier } : {}),
+        enabled: true,
+      };
+      await saveSettings();
+      await this.stop();
+      const r = await start();
+      if (!r.ok) throw new Error(r.error);
+      return { bot: verified, settings: { ...settings } };
+    },
+
+    /**
+     * Mint a one-time enrollment code and the link that redeems it in one tap. The code is the
+     * fallback for someone reading it off a screen; the link is the path most people take.
+     */
+    async pair({ ttlMs = 10 * 60_000 } = {}) {
+      await load();
+      if (!bot) throw new Error('connect a bot first');
+      const code = pairing.requestCode({ ttlMs });
+      await savePairing();
+      return { code, link: pairLink(bot.username, code), expiresAt: now() + ttlMs, bot: { ...bot } };
+    },
+
+    /**
+     * Pre-pair without a code — an operator allow-list for scripted setups. Explicit by
+     * design: there is no path here that enrolls a chat because it messaged you.
+     */
+    async allow(actorId, { reach = 'trusted' } = {}) {
+      await load();
+      pairing.allow(actorId, { reach });
+      await savePairing();
+      return { actorId, reach };
+    },
+
+    /** Revoke one phone. Takes effect on its NEXT message — nothing is cached per chat. */
+    async unpair(actorId) {
+      await load();
+      const removed = pairing.revoke(actorId);
+      await savePairing();
+      return { removed };
+    },
+
+    async update(patch = {}) {
+      await load();
+      const next = { ...settings };
+          for (const k of ['agent', 'model', 'provider', 'gatewayUrl', 'privacy', 'tier', 'system']) {
+        if (patch[k] != null) next[k] = patch[k];
+      }
+      // Picking one target unpicks the other. Without this a stale `model` would silently win
+      // over the agent the user just chose, and the screen would disagree with the machine.
+      if (patch.agent != null && patch.model == null) { next.model = ''; next.provider = ''; }
+      if (patch.model) next.agent = '';
+      settings = next;
+      await saveSettings();
+      // NO RESTART. The loop reads settings per message through `route`, and restarting it
+      // would discard every conversation's history and vault — which is exactly what made
+      // changing the model answer the next question with "this looks like a fresh session".
+      // The only change that still needs a restart is a new bot token, and connect() does that.
+      return { settings: { ...settings } };
+    },
+
+    /** Stop the loop. `forget` also deletes the token and every pairing — a real disconnect. */
+    async stop({ forget = false } = {}) {
+      stopped = true;
+      controller?.abort();
+      controller = null;
+      running = false;
+      if (forget) {
+        await load();
+        settings = { ...settings, enabled: false };
+        await saveSettings();
+        await rm(tokenFile, { force: true });
+        for (const p of pairing.list()) pairing.revoke(p.actorId);
+        await savePairing();
+        bot = null;
+      }
+      return { ok: true };
+    },
+
+    /**
+     * Everything a settings screen needs and nothing it must not have: no bot token, ever.
+     * `configured` says a token exists; `running` says the loop is actually polling.
+     */
+    async status() {
+      await load();
+      const configured = !!(await readToken());
+      return {
+        channel: 'telegram',
+        configured,
+        enabled: settings.enabled !== false,
+        running,
+        bot: bot ? { ...bot } : null,
+        error: lastError,
+        paired: pairing.list(),
+        settings: {
+          agent: settings.agent,
+          model: settings.model || '',
+          provider: settings.provider || '',
+          gatewayUrl: settings.gatewayUrl || DEFAULT_GATEWAY_URL,
+          privacy: settings.privacy,
+          tier: settings.tier,
+        },
+        // Which transport a message will actually take, so a screen can say so rather than
+        // inferring it from two fields and getting it wrong.
+        via: settings.model ? 'gateway' : 'bridge',
+      };
+    },
+  };
+}

package/src/stream.js

@@ -26,6 +26,26 @@ export function foldEvent(state, ev) {
   }
 }
 
+/**
+ * Fold one OpenAI-style chunk (what the gateway streams) into the same reply state, so a
+ * caller cannot tell which transport it has. Shares parseSse: `data: [DONE]` is not JSON and
+ * is dropped there, which is why the transport marks `done` itself when the stream ends.
+ */
+export function foldOpenAiEvent(state, ev) {
+  if (ev?.type === 'run') return { ...state, runId: ev.id || state.runId };
+  // An error can arrive as a streamed frame rather than an HTTP status.
+  if (ev?.error) return { ...state, done: true, error: ev.error.message || String(ev.error) };
+  const choice = ev?.choices?.[0];
+  let next = state;
+  const delta = choice?.delta?.content;
+  if (typeof delta === 'string' && delta) next = { ...next, text: next.text + delta };
+  // Non-streaming replies (a gateway destination that cannot stream) carry the whole message.
+  const whole = choice?.message?.content;
+  if (!next.text && typeof whole === 'string' && whole) next = { ...next, text: whole };
+  if (choice?.finish_reason) next = { ...next, done: true };
+  return next;
+}
+
 /**
  * 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.