@chatpanel/bridge 0.10.41 → 0.11.0

package/src/channels/invoke.js

@@ -0,0 +1,172 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-channels/src/invoke.js (npm @chatpanel/channels).
+// Edit there, then run: npm run sync:channels
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve. Package imports are rewritten to the
+// vendored engines (src/pii, src/events) by the sync script.
+
+// 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 '../events/capability.js';
+import { createVault, redactText, restoreText, redactionSummary } from '../pii/index.js';
+
+// 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);
+}
+
+// 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
+// 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/channels/normalize.js

@@ -0,0 +1,58 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-channels/src/normalize.js (npm @chatpanel/channels).
+// Edit there, then run: npm run sync:channels
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve. Package imports are rewritten to the
+// vendored engines (src/pii, src/events) by the sync script.
+
+// 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/channels/pairing.js

@@ -0,0 +1,80 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-channels/src/pairing.js (npm @chatpanel/channels).
+// Edit there, then run: npm run sync:channels
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve. Package imports are rewritten to the
+// vendored engines (src/pii, src/events) by the sync script.
+
+// 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 '../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.
+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/channels/service.js

@@ -0,0 +1,270 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-channels/src/service.js (npm @chatpanel/channels).
+// Edit there, then run: npm run sync:channels
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve. Package imports are rewritten to the
+// vendored engines (src/pii, src/events) by the sync script.
+
+// 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 { createPairingStore } from './pairing.js';
+import { createEventLog } from './eventlog.js';
+import { startTelegram } from './adapters/telegram.js';
+
+const TELEGRAM_API = 'https://api.telegram.org';
+export const DEFAULT_SETTINGS = Object.freeze({ agent: 'claude', 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(),
+} = {}) {
+  const tokenFile = path.join(home, 'telegram-token');
+  const configFile = path.join(dataDir, 'config.json');
+  const pairingFile = path.join(dataDir, 'pairing.json');
+
+  let pairing = createPairingStore();
+  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.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 });
+    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;
+    const done = startTelegram({
+      botToken,
+      baseUrl: bridge.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', 'privacy', 'tier', 'system']) if (patch[k] != null) next[k] = patch[k];
+      settings = next;
+      await saveSettings();
+      // Settings are read when the loop starts, so a change only lands on a restart.
+      if (running) { await this.stop(); await start(); }
+      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, privacy: settings.privacy, tier: settings.tier },
+      };
+    },
+  };
+}

package/src/channels/stream.js

@@ -0,0 +1,86 @@
+// GENERATED — do not edit.
+// Source of truth: chatpanel-channels/src/stream.js (npm @chatpanel/channels).
+// Edit there, then run: npm run sync:channels
+//
+// Vendored rather than depended on: the bridge ships zero runtime dependencies so a
+// curl one-liner install cannot fail on someone's registry, and so the compiled
+// single-file binary has nothing to resolve. Package imports are rewritten to the
+// vendored engines (src/pii, src/events) by the sync script.
+
+// 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; },
+  };
+}