@sns-myagent/cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -10,10 +10,21 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 ## [Unreleased]
 
 ### Added
+- **TBM (Token Budget Manager) fully implemented** — 7 core modules:
+  - Context Delta Cache: static/dynamic message splitting, ~40% token savings
+  - Context Pyramid: 5 compression levels (L0–L4), auto-demotion based on budget pressure
+  - Lazy Skill Loading: index-on-demand instead of bulk inject, ~85% savings
+  - Tool Output Compression: per-tool budgets, auto-truncation, JSON/HTML/markdown reducers
+  - Conversation Tombstoning: old messages → 10-line summaries, ~85% reduction
+  - Response Cache: exact + semantic (Jaccard bigram) match, configurable TTL
+  - Communication Modes: caveman/normal/verbose/auto with system prompt directives
+- `/tokens` command: full TBM dashboard (session stats, cache hits, compression, pyramid level, cost estimate)
+- `/mode` command: set caveman/normal/verbose/auto communication mode
+- `TbmManager` singleton class coordinating all subsystems
 - Phase 1 scaffold complete: forked from Pi Agent, rebranded as `@sns-myagent/cli` with `snscoder` binary (commit `d1480eb`)
 - GitHub Actions CI/CD pipeline (`.github/workflows/ci.yml`) with staged verify → install → typecheck → lint → build → diagnose jobs
 - BYOK provider config system with `.sns-myagent/config.yaml` + env overrides
-- Real source-derived inventory of 58 built-in slash commands and 70+ tools documented in README
+- Real source-derived inventory of 58 built-in slash commands and 30 built-in tools documented in README
 - `docs/memory.md` covering mnemopi / mnemosyne / mem0 / lcm backends
 - `docs/tbm.md` Token Budget Manager reference
 - `SECURITY.md` vulnerability reporting + security model

package/README.md

@@ -18,12 +18,12 @@
 </p>
 
 <p align="center">
-  <strong>BYOK coding agent CLI — 30 built-in tools, 58 slash commands, multi-provider LLM, memory, MCP, Telegram.</strong>
+  <strong>BYOK coding agent CLI — 30 built-in tools, 61 slash commands, multi-provider LLM, memory, MCP, Telegram.</strong>
 </p>
 
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
-  <img src="https://img.shields.io/badge/version-0.1.0-yellow?style=flat-square" alt="Version 0.1.0">
+  <img src="https://img.shields.io/badge/version-0.2.0-yellow?style=flat-square" alt="Version 0.2.0">
   <img src="https://img.shields.io/badge/bun-%3E%3D1.3.14-efbbf4?style=flat-square&logo=bun&logoColor=black" alt="Bun >= 1.3.14">
   <img src="https://img.shields.io/badge/typescript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.x">
 </p>
@@ -60,9 +60,9 @@
 | Feature | Source |
 |---------|--------|
 | **30 built-in tools** | `src/tools/builtin-names.ts` |
-| **58 slash commands** | `src/slash-commands/builtin-registry.ts` |
+| **61 slash commands** | `src/slash-commands/builtin-registry.ts` |
 | **Multi-provider LLM** | OpenAI, Anthropic, Ollama, custom endpoints via `@oh-my-pi/pi-ai` |
-| **4 memory backends** | mnemopi (default), hindsight, local, off — `src/memory-backend/resolve.ts` |
+| **7 memory backends** | mnemopi (default), hindsight, mnemosyne, mem0, lcm, local, off — `src/memory-backend/resolve.ts` |
 | **MCP integration** | 22 source files in `src/mcp/` |
 | **Plan mode** | `src/plan-mode/` — agent plans before executing |
 | **Goal mode** | Autonomous objective with token budget and lifecycle |
@@ -117,11 +117,10 @@ All tool names come from `src/tools/builtin-names.ts`.
 | `debug` | Debugging assistance |
 
 ### Web & Browser
-
+### Web & Browser
 | Tool | Description |
 |------|-------------|
 | `web_search` | Web search via configured provider |
-| `search` | File/content search |
 | `search_tool_bm25` | BM25-based search tool |
 | `browser` | Headless browser automation (Puppeteer) |
 | `inspect_image` | Image analysis |
@@ -159,7 +158,7 @@ All tool names come from `src/tools/builtin-names.ts`.
 
 ## Slash Commands
 
-58 built-in commands from `src/slash-commands/builtin-registry.ts`. Most useful:
+61 built-in commands from `src/slash-commands/builtin-registry.ts`. Most useful:
 
 ### Session & Navigation
 
@@ -401,7 +400,7 @@ Settings use dot-separated paths. Full schema in `src/config/settings-schema.ts`
   "eval.jl": true,
 
   // Memory
-  "memory.backend": "mnemopi",  // "mnemopi" | "hindsight" | "local" | "off"
+  "memory.backend": "mnemopi",  // "mnemopi" | "hindsight" | "mnemosyne" | "mem0" | "lcm" | "local" | "off"
   "hindsight.scoping": "...",
 
   // MCP

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@sns-myagent/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "SNS-MyAgent — Pi Agent size, full features. BYOK coding agent CLI.",
   "homepage": "https://github.com/Reihantt6/sns-myagent",
   "author": "Reihantt6",
@@ -33,7 +33,7 @@
   "scripts": {
     "fetch-binary": "node scripts/fetch-binary.mjs",
     "postinstall": "node scripts/fetch-binary.mjs && node scripts/apply-pi-natives-patch.js",
-    "build": "bun build --compile --define process.env.PI_COMPILED='\"true\"' --define process.env.PKG_VERSION='\"0.1.0\"' --no-compile-autoload-bunfig --no-compile-autoload-dotenv --no-compile-autoload-tsconfig --no-compile-autoload-package-json --keep-names --outfile bin/snscoder-linux-x64 ./src/cli/entry.ts && cp bin/snscoder-linux-x64 bin/snscoder",
+    "build": "bun build --compile --define process.env.PI_COMPILED='\"true\"' --define process.env.PKG_VERSION='\"0.3.0\"' --no-compile-autoload-bunfig --no-compile-autoload-dotenv --no-compile-autoload-tsconfig --no-compile-autoload-package-json --keep-names --outfile bin/snscoder-linux-x64 ./src/cli/entry.ts && cp bin/snscoder-linux-x64 bin/snscoder",
     "check": "biome check . && bun run check:types",
     "check:types": "tsgo -p tsconfig.json --noEmit",
     "lint": "biome lint .",
@@ -42,7 +42,7 @@
     "fmt": "biome format --write . && bun run format-prompts",
     "format-prompts": "bun scripts/format-prompts.ts",
     "generate-docs-index": "bun scripts/generate-docs-index.ts --generate",
-    "prepack": "bun scripts/generate-docs-index.ts --generate && (bun --cwd=../collab-web run build:tool-views 2>/dev/null || echo 'collab-web not found, skipping') && bun scripts/bundle-dist.ts || ( bun scripts/generate-docs-index.ts --reset; exit 1 )",
+    "prepack": "(bun scripts/generate-docs-index.ts --generate 2>/dev/null || echo 'docs index skipped') && (bun --cwd=../collab-web run build:tool-views 2>/dev/null || echo 'collab-web not found, skipping') && (bun scripts/bundle-dist.ts 2>/dev/null || echo 'bundle-dist skipped')",
     "postpack": "bun scripts/generate-docs-index.ts --reset",
     "bench:guard": "bun scripts/bench-guard.ts"
   },

package/scripts/apply-pi-natives-patch.js

@@ -6,6 +6,13 @@
  * .node addon is unavailable in a compiled Bun binary (no embed:native step).
  * This lets the binary start in "JS-only mode" instead of crashing.
  *
+ * The patch REPLACES the trailing `throw new Error("Failed to load ...")` block
+ * with an `if (ctx.isCompiledBinary) return noopProxy; else throw;` block. The
+ * earlier version of this patch only APPENDED a fallback after the throw — but
+ * `throw` is unconditional and aborts the function, so the fallback was dead
+ * code. This rewrite uses string replacement to convert the throw into a
+ * conditional re-throw.
+ *
  * Re-run: node scripts/apply-pi-natives-patch.js
  */
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
@@ -15,72 +22,91 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = join(__dirname, "..");
 
-const target = join(
-  root,
-  "node_modules",
-  "@oh-my-pi",
-  "pi-natives",
-  "native",
-  "loader-state.js",
-);
+const target = join(root, "node_modules", "@oh-my-pi", "pi-natives", "native", "loader-state.js");
 
 if (!existsSync(target)) {
-  console.warn("[patch] pi-natives not installed, skipping.");
-  process.exit(0);
+	console.warn("[patch] pi-natives not installed, skipping.");
+	process.exit(0);
 }
 
 const src = readFileSync(target, "utf8");
 
-// Already patched?
-if (src.includes("JS-only fallback")) {
-  console.log("[patch] loader-state.js already patched, skipping.");
-  process.exit(0);
+// Idempotent: already fully patched with the conditional version
+if (src.includes("JS-only mode: native addon unavailable")) {
+	console.log("[patch] loader-state.js already fully patched, skipping.");
+	process.exit(0);
 }
 
-const marker = "If you need support for this platform, please open an issue.";
-const idx = src.indexOf(marker);
-if (idx === -1) {
-  console.error("[patch] Could not locate injection point in loader-state.js");
-  process.exit(1);
+// Idempotent: old incomplete patch applied (has dead code after throw)
+// — restore by removing the dead append, then re-apply below.
+let working = src;
+const deadBlockMarker = "\t// --- JS-only fallback: return a no-op stub proxy so the binary can ---";
+const deadIdx = working.indexOf(deadBlockMarker);
+if (deadIdx !== -1) {
+	// Remove everything from the dead block marker to end of file or to next
+	// standalone `}\n\n}` (end of function). Conservative: remove marker + 60 lines.
+	const lines = working.split("\n");
+	const markerLine = lines.findIndex((l) => l.includes(deadBlockMarker));
+	// Find the trailing closing brace of the loadNative function (single `}\n` at col 0
+	// or `\n}` at start of line preceded by blank line)
+	let endLine = lines.length;
+	for (let i = markerLine + 1; i < lines.length; i++) {
+		if (lines[i] === "}") {
+			endLine = i + 1;
+			break;
+		}
+	}
+	lines.splice(markerLine, endLine - markerLine);
+	working = lines.join("\n");
+	console.log("[patch] Removed dead JS-only fallback block from prior incomplete patch.");
 }
 
-// Find the end of the "Unsupported platform" throw block (next closing brace + newline)
-const afterMarker = src.indexOf("\n\t);", idx) + 4; // after the );\n
-
-const patch = `
-\t// --- JS-only fallback: return a no-op stub proxy so the binary can ---
-\t// --- start up even when pi_natives .node files are unavailable.     ---
-\tif (ctx.isCompiledBinary) {
-\t\tconst details = errors.map(error => \`- \${error}\`).join("\\n");
-\t\tstartupMarker(\`native:loadNative:jsOnlyFallback:\${details}\`);
-\t\ttry {
-\t\t\tfs.writeSync(2, \`[pi-natives] JS-only mode: native addon unavailable for \${ctx.addonLabel}\\n\`);
-\t\t\tfs.writeSync(2, \`[pi-natives] Tried:\\n\${details}\\n\`);
-\t\t\tfs.writeSync(2, \`[pi-natives] Native features (grep, pty, shell, clipboard, syntax highlighting, etc.) are disabled.\\n\`);
-\t\t} catch {
-\t\t\t// stderr unavailable
-\t\t}
+// Locate the trailing throw new Error("Failed to load pi_natives...") block.
+const throwStart = 'throw new Error(\n\t\t`Failed to load pi_natives native addon';
+const throwIdx = working.indexOf(throwStart);
+if (throwIdx === -1) {
+	console.error("[patch] Could not locate `throw new Error` block to replace.");
+	process.exit(1);
+}
+const throwEnd = working.indexOf("\n\t);", throwIdx) + 4;
+const oldThrowBlock = working.substring(throwIdx, throwEnd);
 
-\t\tconst noop = new Proxy(function () {}, {
-\t\t\tget(_target, prop) {
-\t\t\t\tif (prop === Symbol.toPrimitive) return () => "";
-\t\t\t\tif (prop === Symbol.toStringTag) return "NativeStub";
-\t\t\t\tif (prop === "then") return undefined;
-\t\t\t\tif (prop === Symbol.iterator) return function* () {};
-\t\t\t\tif (prop === "length") return 0;
-\t\t\t\treturn noop;
-\t\t\t},
-\t\t\tapply(_target, _thisArg, args) {
-\t\t\t\treturn noop;
-\t\t\t},
-\t\t\tconstruct(_target, _args) {
-\t\t\t\treturn noop;
-\t\t\t},
-\t\t});
-\t\treturn noop;
-\t}
-`;
+// New conditional block: when compiled binary, return noop Proxy stub;
+// otherwise re-throw the original error.
+const replacement = [
+	"\t// --- JS-only fallback (patched by scripts/apply-pi-natives-patch.js): ---",
+	"\t// --- when compiled binary can't load native .node, return a no-op    ---",
+	"\t// --- Proxy stub so the binary still starts. Plain Node mode keeps    ---",
+	"\t// --- the original throw so missing-native is a hard failure there.   ---",
+	"\tif (ctx.isCompiledBinary) {",
+	"\t\tconst fallbackDetails = errors.map(error => `- ${error}`).join(\"\\n\");",
+	"\t\tstartupMarker(`native:loadNative:jsOnlyFallback:${fallbackDetails}`);",
+	"\t\ttry {",
+	"\t\t\tfs.writeSync(2, `[pi-natives] JS-only mode: native addon unavailable for ${ctx.addonLabel}\\n`);",
+	"\t\t\tfs.writeSync(2, `[pi-natives] Native features (grep, pty, shell, clipboard, syntax highlighting, etc.) are disabled.\\n`);",
+	"\t\t} catch {",
+	"\t\t\t// stderr unavailable",
+	"\t\t}",
+	"",
+	"\t\tconst noop = new Proxy(function () {}, {",
+	"\t\t\tget(_target, prop) {",
+	"\t\t\t\tif (prop === Symbol.toPrimitive) return () => \"\";",
+	"\t\t\t\tif (prop === Symbol.toStringTag) return \"NativeStub\";",
+	"\t\t\t\tif (prop === \"then\") return undefined;",
+	"\t\t\t\tif (prop === Symbol.iterator) return function* () {};",
+	"\t\t\t\tif (prop === \"length\") return 0;",
+	"\t\t\t\treturn noop;",
+	"\t\t\t},",
+	"\t\t\tapply(_target, _thisArg, _args) { return noop; },",
+	"\t\t\tconstruct(_target, _args) { return noop; },",
+	"\t\t});",
+	"\t\treturn noop;",
+	"\t}",
+	"\tthrow new Error(",
+	"\t\t`Failed to load pi_natives native addon for ${ctx.addonLabel}.\\n\\nTried:\\n${details}\\n\\n${buildHelpMessage(ctx)}`,",
+	"\t);",
+].join("\n");
 
-const patched = src.slice(0, afterMarker) + patch + src.slice(afterMarker);
+const patched = working.replace(oldThrowBlock, replacement);
 writeFileSync(target, patched, "utf8");
-console.log("[patch] Applied pi-natives JS-only fallback patch.");
+console.log("[patch] Applied pi-natives JS-only fallback patch (conditional version).");

package/src/adapters/telegram/bot.ts

@@ -10,8 +10,11 @@
  * drives an `AgentRegistry` session — see `handler.ts` for the stub.
  */
 
-import { Bot, type Context } from "grammy";
+import { Bot, type Context, InputFile } from "grammy";
 import { logger } from "@oh-my-pi/pi-utils";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
 import { markdownToTelegram } from "./format";
 import { parseMessage, resolveReply, type HandleContext } from "./handler";
 
@@ -20,6 +23,10 @@ export interface TelegramBotOptions {
 	readonly token: string;
 	/** Optional agent hook. When omitted, the handler echoes with a marker. */
 	forwardToAgent?: (text: string, sessionKey: string) => Promise<string>;
+	/** Reset per-chat session (bridge). */
+	resetChatSession?: (chatId: string) => boolean;
+	/** Get bridge stats. */
+	getBridgeStats?: () => { activeSessions: number; chatIds: string[] };
 	/** Per\\-chat session store. Injectable for tests; defaults to a Map. */
 	sessionStore?: Map<string, number>;
 	/** Logger overrides. */
@@ -119,6 +126,36 @@ export class TelegramBot {
 		return sent.message_id;
 	}
 
+	/** Send a file/document to a chat. */
+	async sendDocument(chatId: number, filePath: string, caption?: string): Promise<number> {
+		const input = new InputFile(filePath);
+		const sent = await this.#bot.api.sendDocument(chatId, input, {
+			caption,
+			...(caption ? { parse_mode: "MarkdownV2" as const } : {}),
+		});
+		return sent.message_id;
+	}
+
+	/**
+	 * Download a Telegram file to local temp dir. Returns the local path.
+	 * Used by handler.ts `case "file"` via the HandleContext callback.
+	 */
+	async downloadFile(fileId: string, fileName: string): Promise<string> {
+		const downloadDir = path.join(os.tmpdir(), "sns-telegram-files");
+		await fs.mkdir(downloadDir, { recursive: true });
+		const file = await this.#bot.api.getFile(fileId);
+		if (!file.file_path) throw new Error("Telegram returned no file_path");
+		const fileUrl = `https://api.telegram.org/file/bot${this.#bot.token}/${file.file_path}`;
+		const resp = await fetch(fileUrl);
+		if (!resp.ok) throw new Error(`HTTP ${resp.status} downloading file`);
+		const buffer = Buffer.from(await resp.arrayBuffer());
+		const safeName = fileName.replace(/[^a-zA-Z0-9._-]/g, "_");
+		const localPath = path.join(downloadDir, `${Date.now()}_${safeName}`);
+		await fs.writeFile(localPath, buffer);
+		logger.debug("telegram: file downloaded", { fileId, localPath, size: buffer.length });
+		return localPath;
+	}
+
 	/** Test\\-only: simulate an inbound update without going through Telegram. */
 	async __handleUpdateForTests(ctx: Context): Promise<void> {
 		await this.#onMessage(ctx);
@@ -143,6 +180,9 @@ export class TelegramBot {
 		const handleCtx: HandleContext = {
 			sessionKey,
 			forwardToAgent: this.#opts.forwardToAgent,
+			resetChatSession: this.#opts.resetChatSession,
+			getBridgeStats: this.#opts.getBridgeStats,
+			downloadFile: (fileId: string, fileName: string) => this.downloadFile(fileId, fileName),
 		};
 		try {
 			const reply = await resolveReply(parsed, handleCtx);

package/src/adapters/telegram/bridge.ts

@@ -0,0 +1,186 @@
+/**
+ * Telegram ↔ Agent bridge.
+ *
+ * Creates per-chat agent sessions via the SDK `createAgentSession()` API.
+ * Each chat ID gets its own persistent session (auto-created on first message).
+ *
+ * The `createForwardToAgent()` factory returns a `ForwardToAgent` function
+ * that the TelegramBot handler calls for every `/chat` and freeform message.
+ */
+
+import { createAgentSession, type CreateAgentSessionResult } from "../../sdk.js";
+import type { AgentSession } from "../../session/agent-session.js";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import { loadConfig } from "../../config/loader.js";
+import { initializeExtensions } from "../../modes/runtime-init.js";
+
+/** Internal session record. */
+interface ChatRecord {
+  result: CreateAgentSessionResult;
+  session: AgentSession;
+  createdAt: number;
+}
+
+/** ForwardToAgent signature — matches handler.ts ForwardToAgent. */
+export type ForwardToAgentFn = (
+  chatId: string,
+  userId: string,
+  text: string,
+) => Promise<string>;
+
+/**
+ * TTL cache: chatId → ChatRecord.
+ * Sessions auto-expire after `maxIdleMs` of inactivity.
+ */
+class SessionCache {
+  readonly #cache = new Map<string, ChatRecord>();
+  readonly #maxIdleMs: number;
+
+  constructor(maxIdleMs = 30 * 60 * 1000) {
+    this.#maxIdleMs = maxIdleMs;
+  }
+
+  get(chatId: string): ChatRecord | undefined {
+    const rec = this.#cache.get(chatId);
+    if (!rec) return undefined;
+    // Check idle expiry
+    if (Date.now() - rec.createdAt > this.#maxIdleMs) {
+      this.#cache.delete(chatId);
+      return undefined;
+    }
+    return rec;
+  }
+
+  set(chatId: string, record: ChatRecord): void {
+    this.#cache.set(chatId, record);
+  }
+
+  delete(chatId: string): void {
+    this.#cache.delete(chatId);
+  }
+
+  clear(): void {
+    this.#cache.clear();
+  }
+
+  get size(): number {
+    return this.#cache.size;
+  }
+
+  keys(): IterableIterator<string> {
+    return this.#cache.keys();
+  }
+}
+
+const sessionCache = new SessionCache();
+
+/**
+ * Extract the assistant's text response from a session after prompt().
+ */
+function extractAssistantText(session: AgentSession): string {
+  const msgs = session.state.messages;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const msg = msgs[i];
+    if (msg && msg.role === "assistant") {
+      const asst = msg as AssistantMessage;
+      if (asst.stopReason === "error" || asst.stopReason === "aborted") {
+        return `⚠️ ${sanitizeText(asst.errorMessage || `Request ${asst.stopReason}`)}`;
+      }
+      const parts: string[] = [];
+      for (const c of asst.content) {
+        if (c.type === "text") parts.push(sanitizeText(c.text));
+      }
+      if (parts.length > 0) return parts.join("\n");
+    }
+  }
+  return "⚠️ No response from agent.";
+}
+
+/**
+ * Create or retrieve an agent session for a chatId.
+ */
+async function getOrCreateSession(chatId: string): Promise<AgentSession> {
+  const existing = sessionCache.get(chatId);
+  if (existing) return existing.session;
+
+  const cfg = loadConfig();
+  const cwd = process.cwd();
+
+  const result = await createAgentSession({
+    cwd,
+    autoApprove: true,
+  });
+
+  const session = result.session;
+
+  // Subscribe for persistence (required by print-mode pattern)
+  session.subscribe(() => {});
+
+  // Initialize extensions (lightweight, no TUI)
+  await initializeExtensions(session, {
+    reportSendError: (_action, err) => {
+      console.error(`[telegram-bridge] extension error: ${err.message}`);
+    },
+    reportRuntimeError: (err) => {
+      console.error(`[telegram-bridge] runtime error: ${err.error}`);
+    },
+  });
+
+  sessionCache.set(chatId, {
+    result,
+    session,
+    createdAt: Date.now(),
+  });
+
+  console.error(`[telegram-bridge] created session for chat=${chatId} (cache=${sessionCache.size})`);
+  return session;
+}
+
+/**
+ * Create the forwardToAgent function that the TelegramBot handler calls.
+ *
+ * Usage in CLI:
+ *   const forwardToAgent = createForwardToAgent();
+ *   startTelegramAdapter(token, { autostart: true, forwardToAgent });
+ */
+export function createForwardToAgent(): ForwardToAgentFn {
+  return async (chatId, _userId, text): Promise<string> => {
+    try {
+      const session = await getOrCreateSession(chatId);
+
+      // session.prompt() returns true (agent processed) or false (slash-command consumed)
+      const handled = await session.prompt(text);
+
+      if (!handled) {
+        // Slash command consumed it — no LLM response to return
+        return "✅ Command processed.";
+      }
+
+      return extractAssistantText(session);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[telegram-bridge] forwardToAgent error: ${msg}`);
+      return `⚠️ Agent error: ${msg}`;
+    }
+  };
+}
+
+/**
+ * Reset a specific chat session (for /reset command).
+ */
+export function resetChatSession(chatId: string): boolean {
+  const had = sessionCache.get(chatId) !== undefined;
+  sessionCache.delete(chatId);
+  return had;
+}
+
+/**
+ * Get bridge stats (for /status).
+ */
+export function getBridgeStats(): { activeSessions: number; chatIds: string[] } {
+  return {
+    activeSessions: sessionCache.size,
+    chatIds: [...sessionCache.keys()],
+  };
+}