agentus 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.4.3",
+ "version": "0.4.5",
  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
  "license": "Apache-2.0",
  "repository": {
@@ -30,7 +30,8 @@
  "dependencies": {
   "@agentclientprotocol/sdk": "1.5.1",
   "tsx": "^4.19.0",
-  "ws": "^8.22.0"
+  "ws": "^8.22.0",
+  "yaml": "^2.9.1"
  },
  "workspaces": [
   "packages/*"

package/packages/server/mock/agent.mjs

@@ -416,18 +416,39 @@ const agent = () => ({
     // per-turn slow mode: long stream so QA can drop the socket mid-turn (AC6)
     const slow = /\[slow\]/.test(text) ? Math.max(SLOW, 900) : SLOW;
 
+    // `[hold:<ms>]` — a turn that is IN FLIGHT but SILENT for that long (issue #24's heartbeat
+    // fixture). No frames at all, so 「有任务在跑 + 没有动静」 is exactly the state the ticker must
+    // speak on — and the state a `[slow]` stream can never reproduce (it emits every 900 ms).
+    const hold = Number((/\[hold:(\d+)\]/.exec(text) || [])[1] || 0);
+    if (hold > 0) await sleep(Math.min(180_000, hold));
+
     // `[status]` — the agent-status carrier from issue #18, exactly as hermes' `make_status_cb` sends
     // it: an EMPTY thought chunk whose `_meta.hermes` holds the sentence. Sent mid-turn on purpose, so a
     // sweep can prove the line appears while the turn runs and is gone when it ends, and that NOTHING
     // of it reaches the stored transcript.
-    if (/\[status\]/.test(text)) {
-      setTimeout(() => {
-        void send(agent._conn, sessionId, {
-          sessionUpdate: "agent_thought_chunk",
-          _meta: { hermes: { kind: "status", statusKind: "lifecycle", text: "👁️ Hindsight — recalled 8 memories" } },
-          content: { type: "text", text: "" },
-        }).catch(() => undefined);
-      }, Math.min(slow * 2, 1200));
+    // `[status]` / `[status:<kind>]` / `[status:<kind>#<n>]` — the carrier above, with the kind and a
+    // repeat count the sweeps need: a compaction is NOT one frame (start, then heartbeats, then done),
+    // and the cockpit must fold the heartbeats into the row they belong to instead of stacking rows.
+    const statusM = /\[status(?::([a-z_]+))?(?:#(\d+))?\]/.exec(text);
+    if (statusM) {
+      const kind = statusM[1] ?? "lifecycle";
+      const times = Math.min(Number(statusM[2] ?? 1), 8);
+      const line = kind === "lifecycle"
+        ? "👁️ Hindsight — recalled 8 memories"
+        : kind === "compacting"
+          ? (times > 1 ? "🗜️ Compacting context — still summarizing earlier conversation..." : "🗜️ Compacting context — summarizing earlier conversation...")
+          : kind === "compacted"
+            ? "✓ Context compaction complete — continuing turn..."
+            : `⚠️ mock ${kind} status`;
+      for (let i = 0; i < times; i++) {
+        setTimeout(() => {
+          void send(agent._conn, sessionId, {
+            sessionUpdate: "agent_thought_chunk",
+            _meta: { hermes: { kind: "status", statusKind: kind, text: line } },
+            content: { type: "text", text: "" },
+          }).catch(() => undefined);
+        }, Math.min(slow * 2, 1200) + i * 350);
+      }
     }
 
     // `[blank]` — the SAME carrier with its `_meta` stripped, i.e. the shape a status line takes when

package/packages/server/package.json

@@ -11,7 +11,8 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "1.5.1",
     "@agentus/shared": "*",
-    "ws": "^8.22.0"
+    "ws": "^8.22.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/packages/server/src/acp/session-manager.ts

@@ -1888,7 +1888,18 @@ export class SessionManager {
     }
     const statusText = statusLineOf(u);
     if (statusText) {
-      this.#emit({ t: "status", sessionId: live.info.id, text: statusText, statusKind: statusKindOf(u) });
+      const statusKind = statusKindOf(u);
+      const category = noteCategoryOf(statusText, statusKind);
+      if (category) {
+        // 落库（操作者 2026-10-18 选的 A 档）：刷新页面、重连、换设备之后，这行还在。
+        // 折叠在 store 里做（见 Store.appendNote），因为「压缩开始 → 心跳 → 完成」和每回合的
+        // 一次回忆都必须收敛成一行 —— 客户端折只治屏幕噪音，库里照样长心跳。
+        const row = this.#store.appendNote(live.info.id, { category, text: statusText });
+        this.#emit({ t: "message", message: row });
+      } else {
+        // 剩下的（provider 等待的倒计时、租约闲聊）本来就是一秒就作废的呼吸声：只走 live 通道。
+        this.#emit({ t: "status", sessionId: live.info.id, text: statusText, statusKind });
+      }
       return;
     }
     let msg: Parameters<Store["appendMessage"]>[0] | null = null;
@@ -2590,6 +2601,27 @@ function statusKindOf(u: Record<string, unknown>): string | undefined {
   return typeof kind === "string" && kind ? kind : undefined;
 }
 
+/** 哪些状态行值得留档（操作者 2026-10-18 选的是 A 档）。
+ *
+ *  Hermes 发来的「状态行」是一根混在一起的管子：`status_output.py:102` 把所有东西都标成
+ *  `lifecycle`，只有警告是 `warn`。所以分类只能看**文本**，而这些字符串是从 fork 里抄来的
+ *  真实文案（`conversation_compression.py` 的 `🗜️ Compacting context` / `✓ Context compaction
+ *  complete` / `📦 Pre-API compression:`，`memory_manager.describe_recall` 的 `recalled N memories`）：
+ *
+ *   · memory     —— 「这一轮记忆召回了什么」，每回合都会发生，事后有意义；
+ *   · compaction —— 「上下文压过」，一行就够（记住它压缩过，不需要记住它压了 12 次心跳）；
+ *   · warn       —— 稀有，且几乎总是"要人看一眼"的东西。
+ *
+ *  provider 等待（`⏳ waiting on … 15s waiting for the first stream chunk`，十来秒一条倒计时）和
+ *  「Session is free; loading the latest transcript...」这类租约闲聊返回 null：它们描述的是"此刻
+ *  网络的呼吸"，一秒后就作废，落库只会把会话记录变成心跳日志。 */
+export function noteCategoryOf(text: string, statusKind?: string): "memory" | "compaction" | "warn" | null {
+  if (statusKind === "warn") return "warn";
+  if (/Compacting context|Context compaction complete|compression:|compacting ~/i.test(text)) return "compaction";
+  if (/recalled (?:relevant memory|1 memory|\d+ memories)/i.test(text)) return "memory";
+  return null;
+}
+
 function buildPromptBlocks(text: string, attachments: PromptAttachment[]): unknown[] {
   const blocks: unknown[] = [];
   const body = text.trim();

package/packages/server/src/dashscope.ts

@@ -233,3 +233,85 @@ export function openDashscopeStream(opts: {
     started,
   };
 }
+
+/**
+ * 语音总结: one message in, a few spoken sentences out.
+ *
+ * Same door as batch ASR (`{compat}/chat/completions`) with the audio block swapped for text, so
+ * the operator's existing voice endpoint and key are enough — there is no second model to
+ * configure and no agent, no session and no history involved.
+ *
+ * The input is capped at `maxChars × 20` characters (30k ≈ 15k tokens is already the ceiling for a
+ * 30-second listen): a 200 KB pasted log must not turn a long press into a bill.
+ */
+export async function summarizeForSpeech(opts: {
+  text: string;
+  maxChars: number;
+  prompt: string;
+  model: string;
+  timeoutSec: number;
+  /** Where to send it. Absent = the voice endpoint (settings → 语音), which is the old, always-on
+   *  route. Present = the SESSION's own provider (see speech/route.ts) — the operator asked for the
+   *  summary to be billed to whatever model he is actually talking to, not to a second vendor. */
+  endpoint?: { baseUrl: string; apiKey: string };
+}): Promise<{ text: string; truncated: boolean; ms: number }> {
+  const { key, compat } = opts.endpoint
+    ? { key: opts.endpoint.apiKey, compat: opts.endpoint.baseUrl.replace(/\/+$/, "") }
+    : creds();
+  const v = getSettings().voice;
+  const limit = Math.max(400, opts.maxChars * 20);
+  const body = opts.text.trim();
+  const truncated = body.length > limit;
+  const input = truncated ? `${body.slice(0, limit)}\n…（后面还有 ${body.length - limit} 字没发）` : body;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), Math.max(5, opts.timeoutSec) * 1000);
+  const started = Date.now();
+  try {
+    const res = await fetch(`${compat}/chat/completions`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+      body: JSON.stringify({
+        model: opts.model || (opts.endpoint ? "" : "qwen-flash"),
+        messages: [
+          { role: "system", content: opts.prompt.replace(/\{maxChars\}/g, String(opts.maxChars)) },
+          { role: "user", content: input },
+        ],
+        // No temperature knob: this surface is not a playground, and the default has produced
+        // the steadiest length compliance. `max_tokens` guards against a chatty model — and it
+        // must leave room for REASONING tokens, which count against the same budget: measured on
+        // deepseek-v4-flash, a 480-token cap was spent entirely on reasoning_content and the
+        // visible answer came back empty with finish_reason=length. 1200 is the floor that makes a
+        // reasoning model answer; for a plain one it is only a ceiling nobody reaches.
+        max_tokens: Math.max(1200, opts.maxChars * 6),
+      }),
+      signal: ac.signal,
+    });
+    if (!res.ok) {
+      const detail = (await res.text().catch(() => "")).slice(0, 200);
+      throw new DashscopeError(`chat/completions ${res.status}: ${detail}`, "upstream");
+    }
+    const data = (await res.json()) as {
+      choices?: { message?: { content?: string; reasoning_content?: string }; finish_reason?: string }[];
+    };
+    const choice = data?.choices?.[0];
+    const out = String(choice?.message?.content ?? "").trim();
+    if (!out) {
+      // Say WHICH silence this was. An empty `content` with a fat `reasoning_content` and
+      // finish_reason=length means the budget went to thinking, not that the model refused.
+      const thought = String(choice?.message?.reasoning_content ?? "").length;
+      const why = choice?.finish_reason === "length"
+        ? `预算被推理吃光了（reasoning ${thought} 字，finish_reason=length）—— 调大字数上限，或换一个非推理模型`
+        : `模型返回空内容（finish_reason=${choice?.finish_reason ?? "?"}）`;
+      throw new DashscopeError(why, "upstream");
+    }
+    void v;
+    return { text: out, truncated, ms: Date.now() - started };
+  } catch (e) {
+    if ((e as Error).name === "AbortError") {
+      throw new DashscopeError(`summary timed out after ${opts.timeoutSec}s`, "timeout");
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/packages/server/src/index.ts

@@ -2,27 +2,29 @@
 // The browser never talks to CLI subprocesses directly (design.md §1).
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomUUID, X509Certificate } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import path from "node:path";
 import fs from "node:fs";
 import { WebSocketServer, WebSocket } from "ws";
-import { Store } from "./store/store.js";
+import { Store, textOf } from "./store/store.js";
+import { routeForModel, type SpeechRoute } from "./speech/route.js";
 import { exportFilename, renderJson, renderMarkdown, type ExportSessionHeader } from "./store/export.js";
 import { IMAGE_UNSUPPORTED, SessionManager, SessionUnavailable } from "./acp/session-manager.js";
 import { describeAcpError } from "./acp/errors.js";
 import { BACKENDS } from "./acp/backends.js";
-import { classifyError, checkedHealth, coerceRow, inspectRow, planFor, rowWarnings, seedRows, startupCheck } from "./acp/registry.js";
+import { HERMES_DEFAULT_HOME, classifyError, checkedHealth, coerceRow, inspectRow, planFor, rowWarnings, seedRows, startupCheck } from "./acp/registry.js";
 import { ChangedOnDiskError, FsError, listDirs, readTextFile, statFile, writeTextFile } from "./fs.js";
 import { terms } from "./term.js";
 import { VoiceError, listVoiceModels, setHotwordSource, synthesize, transcribe, voiceCapabilities } from "./voice.js";
 import { dictationContext, hotwordsFor, vocabularyOf } from "./hotwords.js";
-import { openDashscopeStream } from "./dashscope.js";
+import { openDashscopeStream, summarizeForSpeech } from "./dashscope.js";
 import {
+  SUMMARY_CHARS_RANGE, SUMMARY_MODEL_DEFAULT, SUMMARY_PROMPT_DEFAULT,
   agentSettings, getSettings, initSettings, observerSettings, planHintSettings, publicSettings,
-  saveAgent, saveCall, saveObserver, savePrefs, saveSettings, saveTheme,
+  saveAgent, saveCall, saveObserver, savePrefs, saveSettings, saveSummary, saveTheme, summarySettings,
 } from "./settings.js";
 import { ObserverHub } from "./observer/hub.js";
 import * as auth from "./auth.js";
@@ -101,6 +103,19 @@ const APK_FILE = process.env.AGENTUS_APK
     path.join(DATA_DIR, "agentus-companion.apk"),
   ].find((p) => fs.existsSync(p))
   ?? path.resolve(HERE, "../../../android/artifacts/agentus-companion.apk");
+// The root CA this instance's HTTPS is signed by, served to logged-in operators so a phone can
+// trust the tunnel's self-signed cert once instead of tapping through a warning forever. Same
+// reasoning as the APK: an artifact you install on a device belongs behind the operator login, and
+// a page that invites you to install a TRUST ANCHOR especially so. Public half only — `ca.key` is
+// never read here, and the file this points at holds the certificate alone.
+// Candidates: an explicit pin (a Caddy/safe-nat root lives outside any checkout), then the data
+// dir for a self-contained install, then the Caddy default. Absent is not fatal: the card says so.
+const CA_FILE = process.env.AGENTUS_CA_FILE
+  ?? [
+    path.join(DATA_DIR, "tls", "ca.pem"),
+    path.join(homedir(), ".config", "caddy", "tls", "ca.pem"),
+  ].find((p) => fs.existsSync(p))
+  ?? path.join(DATA_DIR, "tls", "ca.pem");
 // `agentus --where` (bin/agentus.mjs) asks the ONE place that decides these paths to say
 // what it decided, then exits — before any listener, store or subprocess exists. Print and
 // exit here rather than re-deriving the same rules in the CLI: "where is my data" must not
@@ -248,6 +263,21 @@ hub = new ObserverHub({
     };
     pick();
   },
+  // 工作播报 的作用域与生命周期 (issues #23/#24, 2026-10-18).
+  // `watching` is the SAME presence the notification rules use: 「他在看哪个会话」 has one answer in
+  // this process, and a second, quieter definition of it is how a feature starts talking about the
+  // wrong session. `notify` is a `const` declared below — this closure only ever runs from an event
+  // handler, never during construction.
+  watching: (id) => notify.operatorWatching(id),
+  // The reaped-observer fix: a `system` session the idle reaper took no longer accepts prompts, and
+  // trusting its id forever is what made the brief say 「播报失败：no such session」 until a restart.
+  // `hasSession` (not `list()`) on purpose: `list()` is the RAIL's view and excludes system sessions,
+  // so asking it about an observer answers 「no」 every single time — which would re-spawn a fresh
+  // observer on every turn and throw away the context continuity the whole design is for.
+  alive: (id) => mgr.hasSession(id),
+  // 切走即关 / 关掉收听即关: closing the PROCESS is the point — an idle observer is a whole ACP
+  // runtime, and the reaper's five minutes are five minutes of paying for nothing.
+  disposeSession: (id) => mgr.closeSession(id),
   emit,
 });
 
@@ -269,7 +299,12 @@ const notify = new NotifyCenter({
   // The page reporting which session it is showing is also the idle reaper's clock: opening a slot
   // (and staying in it) counts as USED, so switching away gives it a full threshold instead of
   // reaping it on the next tick because its last MESSAGE was days ago.
-  onFocus: (sessionId: string) => mgr.touch(sessionId),
+  // ...and it is also the 工作播报 scope switch (issue #23): the observer follows the session on
+  // screen, and the previous one is CLOSED rather than left warming. Two consumers, one fact.
+  onFocus: (sessionId: string) => {
+    mgr.touch(sessionId);
+    hub?.focusChanged(sessionId);
+  },
   // Username+password pairing: the phone types the same login the browser uses. The check and
   // its rate limit stay here, in auth.ts, so a phone cannot have a laxer door than the UI.
   credentials: (username, password, ip) => {
@@ -286,6 +321,11 @@ const notify = new NotifyCenter({
   },
 });
 
+// The beat starts here, and not at construction: `tick()` reads `notify`'s presence, and a timer
+// started before that `const` exists would be the one thing in this file able to throw a TDZ error
+// at runtime. 15s is finer than the smallest beat the menu offers (1 minute).
+hub?.start();
+
 // One row per interaction. A notification button carries an opaque actionId plus the ref the
 // publisher attached; the cockpit is the only place that knows what it means. Adding a new
 // interaction is therefore a case here (or a new ref.type), never an app rebuild.
@@ -760,6 +800,57 @@ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
       return res.end("Agentus: authentication required\n");
     }
 
+    // ---- the root CA, behind the operator login too -------------------------------------
+    // `GET /api/tls`         what the cert is (subject, validity, SHA-256 fingerprint) so the
+    //                        settings card can show it before you download anything;
+    // `GET /api/tls/ca.crt`  the DER the phone/Mac installs. DER + `application/x-x509-ca-cert`
+    //                        is what makes iOS/macOS open the *profile install* flow on a plain
+    //                        tap — serve it as text/plain or octet-stream and iOS just shows text.
+    // Nothing here reads a key: this is the certificate, which is public material by design.
+    if (url.pathname === "/api/tls" || url.pathname === "/api/tls/ca.crt") {
+      if (!auth.authenticate(req.headers, url)) return send(res, 401, { error: "login required" });
+      if (!fs.existsSync(CA_FILE)) return send(res, 404, { error: "no ca configured", path: CA_FILE });
+      let cert: X509Certificate;
+      try { cert = new X509Certificate(fs.readFileSync(CA_FILE)); }
+      catch (e) { return send(res, 500, { error: `ca is not a certificate: ${(e as Error).message}` }); }
+      if (url.pathname === "/api/tls/ca.crt") {
+        res.writeHead(200, {
+          "content-type": "application/x-x509-ca-cert",
+          "content-length": String(cert.raw.length),
+          "content-disposition": 'attachment; filename="agentus-ca.crt"',
+          "cache-control": "no-store",
+        });
+        return res.end(cert.raw);
+      }
+      return send(res, 200, {
+        ok: true,
+        hasCA: true,
+        subject: cert.subject.replace(/\n/g, ", "),
+        issuer: cert.issuer.replace(/\n/g, ", "),
+        notBefore: cert.validFrom,
+        notAfter: cert.validTo,
+        fingerprint256: cert.fingerprint256,
+        bytes: cert.raw.length,
+        selfSigned: cert.subject === cert.issuer,
+      });
+    }
+
+    // ---- 工作播报 diagnostics (issues #23/#24) ------------------------------------------
+    // What the hub is watching and what it spawned. Operator-only, read-only, no secrets: this is
+    // the answer to 「它有没有在看这个会话 / 观察员还活着吗」 that used to require reading logs.
+    if (url.pathname === "/api/observer" && req.method === "GET") {
+      if (!auth.authenticate(req.headers, url)) return send(res, 401, { error: "login required" });
+      const o = getSettings().observer;
+      return send(res, 200, {
+        enabled: o.enabled,
+        intervalSec: o.intervalSec,
+        throttleSec: o.throttleSec,
+        observers: hub?.observerIds() ?? [],
+        watches: hub?.debug() ?? [],
+        ticks: hub?.ticks() ?? 0,
+      });
+    }
+
     // ---- the phone's onboarding page + the APK, both behind the operator login ----------
     // The pairing code lives on this page, so it is NOT public: an unauthenticated visitor is
     // sent to the login screen (the SPA at /) and comes back with a session cookie.
@@ -1190,7 +1281,12 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         if (body.prefs && typeof body.prefs === "object") savePrefs(body.prefs as Record<string, unknown>);
         if (body.agent && typeof body.agent === "object") saveAgent(body.agent as Record<string, unknown>);
         if (body.observer && typeof body.observer === "object") saveObserver(body.observer as Record<string, unknown>);
-        if (!body.voice && !body.theme && !body.call && !body.prefs && !body.agent && !body.observer) saveSettings(body);
+        // Turning the speaker off (or the observer off) must stop the COST, not just the voice:
+        // the observer is a whole ACP process, and waiting for the idle reaper to take it is five
+        // minutes of paying for a feature the operator just switched off (issue #23 §3.2).
+        if (body.prefs || body.observer) hub?.onPolicyChanged();
+        if (body.summary && typeof body.summary === "object") saveSummary(body.summary as Record<string, unknown>);
+        if (!body.voice && !body.theme && !body.call && !body.prefs && !body.agent && !body.observer && !body.summary) saveSettings(body);
         return send(res, 200, publicSettings());
       } catch (e) {
         return send(res, 400, { error: String((e as Error)?.message ?? e) });
@@ -1302,11 +1398,15 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         // here used to kill the whole server (QA#19, unhandled rejection)
         if (mgr.hasSession(id)) {
           await mgr.closeSession(id);
+          // 工作播报 (#23): a closed session's observer and its watch entry have no future. Before
+          // this, `forget()` had zero call sites and the map only grew.
+          hub?.forget(id);
           return send(res, 200, { closed: id });
         }
         // not live: either a cold slot the operator wants gone, or an unknown id.
         // Purging is what makes the rail's "on disk · N" list manageable (M4).
         if (store.deleteSession(id)) {
+          hub?.forget(id);
           emit(sessionsEvent());
           return send(res, 200, { purged: id });
         }
@@ -1319,6 +1419,7 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         // had no way to make it.
         try {
           const info = await mgr.setArchived(id, true);
+          hub?.forget(id);
           emit(sessionsEvent());
           return send(res, 200, info);
         } catch (e) {
@@ -1477,6 +1578,86 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
           return send(res, 409, { error: msg });
         }
       }
+      if (req.method === "POST" && sub === "/speech-summary") {
+        /** The endpoint this session's OWN model lives on. Read per request: the operator can
+         *  switch the model from the toolbar and the next long press must follow it. */
+        const sessionRoute = (): { route: SpeechRoute | null; why: string } => {
+          const row = store.getSession(id);
+          if (!row) return { route: null, why: "会话不在库里" };
+          const be = store.listBackends().find((b) => b.id === row.backend);
+          const models = (row.models ?? {}) as { currentModelId?: string | null };
+          // The provider keys live in this box's agent home, which is a property of the runtime —
+          // not of the vendor that happens to be driving this session. A backend that owns no home
+          // (mock, qoder) therefore still resolves a `deepseek:…` model through the Hermes home.
+          const home = (be ? planFor(be).home : null) ?? HERMES_DEFAULT_HOME;
+          return routeForModel(models.currentModelId ?? null, home);
+        };
+        // 语音总结 (the message speaker's long press): ONE stored message, made listenable.
+        //
+        // No agent, no fork, no history: the text goes to the voice endpoint's chat surface, the
+        // same one ASR already posts to. The BODY of the message is read from the store by key —
+        // the browser does not get to say what reaches the model, and the server's copy is what the
+        // operator actually saw on screen.
+        const cfg = summarySettings();
+        if (!cfg.enabled) return send(res, 409, { error: "语音总结已关闭（设置 → 语音总结）", code: "disabled" });
+        const body = await readJson(req);
+        const key = String(body.key ?? "").trim();
+        if (!key) return send(res, 400, { error: "key is required" });
+        const row = store.messageByKey(id, key);
+        if (!row) return send(res, 404, { error: `no such message: ${key}` });
+        // 字数档 (issue from the operator, 2026-10-18): the message speaker's long press offers
+        // 100/150/200 字 next to 「按设置」. The count is the ONE thing that varies per call, and it
+        // rides the prompt's existing `{maxChars}` placeholder — so this is the only place it has to
+        // be honoured. Clamped to the same range the settings page validates, so a crafted body
+        // cannot ask for a 10k-character invoice.
+        const asked = Math.round(Number(body.maxChars));
+        const [clo, chi] = SUMMARY_CHARS_RANGE;
+        const maxChars = Number.isFinite(asked) && asked >= clo && asked <= chi ? asked : cfg.maxChars;
+        // Judge "short enough to just read" on what would actually be SPOKEN: voice.ts drops code
+        // blocks, and a 20-line diff must not count as a long message worth a model call.
+        const spoken = textOf(row.payload).replace(/```[\s\S]*?```/g, " ").replace(/\s+/g, " ").trim();
+        if (!spoken) return send(res, 409, { error: "这条消息没有可以念的文字", code: "empty" });
+        if (spoken.length <= maxChars) {
+          return send(res, 200, { ok: true, via: "verbatim", text: spoken, chars: spoken.length, ms: 0, maxChars });
+        }
+        try {
+          // The operator's rule: bill this to the model he is already talking to. The voice
+          // endpoint stays as the fallback (and is the whole route when followSession is off).
+          const own = cfg.followSession ? sessionRoute() : { route: null, why: "" };
+          const model = own.route?.model || cfg.model || SUMMARY_MODEL_DEFAULT;
+          const r = await summarizeForSpeech({
+            text: spoken,
+            maxChars,
+            prompt: cfg.prompt.trim() || SUMMARY_PROMPT_DEFAULT,
+            model,
+            timeoutSec: cfg.timeoutSec,
+            endpoint: own.route ? { baseUrl: own.route.baseUrl, apiKey: own.route.apiKey } : undefined,
+          });
+          // Newlines are the one thing the model keeps ignoring: 「不要换行」 in the prompt is a
+          // request, so the answer is normalised here — the note clamps to two lines and the TTS
+          // chunker reads sentence by sentence, and a stray blank line costs both of them.
+          const text = r.text.replace(/\s*\n+\s*/g, " ").replace(/\s{2,}/g, " ").trim();
+          return send(res, 200, {
+            ok: true, via: "model", text, chars: text.length,
+            // echo the bucket: the note prints 「约 150 字」 and a summary that silently used the
+            // configured number would make the menu look broken
+            maxChars,
+            ms: r.ms, truncated: r.truncated, model,
+            // which account this call was billed to — the note prints it, and a fallback that
+            // silently used the OTHER provider would be a lie about the cost
+            route: own.route ? "session" : "voice",
+            provider: own.route?.provider ?? "dashscope",
+            routeNote: own.route ? own.route.source : own.why,
+          });
+        } catch (e) {
+          // 409 = nothing is configured, 504 = we gave up waiting, 502 = the endpoint said no.
+          // None of them may be papered over with the original text: a fallback that looks like a
+          // summary is worse than an honest failure the UI can offer to retry.
+          const err = e as { code?: string; message?: string };
+          const status = err.code === "not_configured" ? 409 : err.code === "timeout" ? 504 : 502;
+          return send(res, status, { error: String(err.message ?? e), code: err.code ?? "upstream" });
+        }
+      }
       if (req.method === "POST" && sub === "/fork") {
         try {
           // forking a cold session resumes it first (the call has to reach a live agent)