agentus 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentus",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "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": {

package/packages/server/src/index.ts

@@ -30,6 +30,9 @@ import {
   modelUsage,
 } from "./settings.js";
 import { ObserverHub } from "./observer/hub.js";
+import {
+  SPEAK_INTERVAL_MAX, allSessionSpeak, clearSessionSpeak, initSessionSpeak, resolveSpeak, setSessionSpeak,
+} from "./session-speak.js";
 import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
 import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent, SessionInfo } from "../../shared/src/index.js";
@@ -273,7 +276,15 @@ hub = new ObserverHub({
   settings: observerSettings,
   // 工作播报 is the operator's third speaker position; in the other two the cockpit says nothing, so
   // no observer is spawned and no tokens are spent.
-  speakEnabled: () => getSettings().prefs.speakMode === "brief",
+  //
+  // Per SESSION since #68: the horn belongs to the conversation it was switched on in, and the
+  // global `prefs.speakMode` is only the DEFAULT for sessions that were never given their own value.
+  // Resolved in one place (`resolveSpeak`) so the horn, the hub and the diagnostic endpoint can
+  // never disagree about what a session is set to.
+  speakOf: (id) => resolveSpeak(id, {
+    mode: getSettings().prefs.speakMode,
+    intervalSec: getSettings().observer.intervalSec,
+  }),
   createSession: async (backend, cwd, title) => (await mgr.create(backend, cwd, title, { system: true })).id,
   prompt: (id, text) => mgr.prompt(id, text, []),
   waitReady: (id, ms) => mgr.awaitReady(id, ms).then(() => undefined),
@@ -304,6 +315,9 @@ hub = new ObserverHub({
   // 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),
+  // 播报的「他在看这个会话」是另一件事 (issue #69 §5): broadcasting exists so he can look AWAY, so it
+  // asks only whether this is the session he is on, not whether he touched the keyboard recently.
+  onSession: (id) => notify.operatorOnSession(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,
@@ -411,6 +425,8 @@ notify.onNotice((notice) => {
 // `settings` table: the UI owns them and env only bootstraps them (settings.ts). Read
 // before anything asks.
 initSettings(DATA_DIR, store);
+// 会话级喇叭档位 (issue #68) rides the same settings table under its own key.
+initSessionSpeak(store);
 // Dynamic hotwords are mined from the transcript — the store's business, not voice.ts's,
 // so the lookup is injected rather than imported.
 setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word));
@@ -1061,6 +1077,61 @@ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
       });
     }
 
+    // ---- 会话级喇叭档位 (issue #68) -------------------------------------------------------
+    // The horn in the corner belongs to the conversation it was switched on in: turning it on in one
+    // session used to make EVERY session start reading aloud. The global `prefs.speakMode` is now the
+    // DEFAULT layer — a session without its own row inherits it, which is the whole compatibility
+    // story (nothing changes for anyone who never touched a horn).
+    if (url.pathname === "/api/speak-modes" && req.method === "GET") {
+      if (!auth.authenticate(req.headers, url)) return send(res, 401, { error: "login required" });
+      const p = getSettings().prefs;
+      const o = getSettings().observer;
+      return send(res, 200, {
+        sessions: allSessionSpeak(),
+        defaults: { mode: p.speakMode, intervalSec: o.intervalSec },
+        // The observer is an ACP process that spends tokens, so a beat on it cannot fire while that
+        // section is off — the menu has to say so instead of showing a tickmark (#69 §1).
+        observerEnabled: o.enabled,
+      });
+    }
+    // 一个会话的档位：GET 解析，PUT 写会话行，DELETE 回到「跟全局默认走」。
+    const speakRoute = /^\/api\/sessions\/([\w.-]+)\/speak$/.exec(url.pathname);
+    if (speakRoute) {
+      if (!auth.authenticate(req.headers, url)) return send(res, 401, { error: "login required" });
+      const sid = speakRoute[1];
+      if (req.method === "GET") {
+        return send(res, 200, { speak: resolveSpeak(sid, { mode: getSettings().prefs.speakMode, intervalSec: getSettings().observer.intervalSec }) });
+      }
+      if (req.method === "PUT" || req.method === "POST") {
+        const body = await readJson(req);
+        const mode = String(body.mode ?? "");
+        if (mode !== "off" && mode !== "reply" && mode !== "brief") {
+          return send(res, 400, { error: `invalid mode: ${JSON.stringify(body.mode)}` });
+        }
+        const intervalSec = Number(body.intervalSec ?? 0);
+        if (!Number.isFinite(intervalSec) || intervalSec < 0 || intervalSec > SPEAK_INTERVAL_MAX) {
+          return send(res, 400, { error: `invalid intervalSec: ${JSON.stringify(body.intervalSec)}` });
+        }
+        const speak = setSessionSpeak(sid, mode, intervalSec);
+        // 档位离开 brief 就是收尾 (#69 §2): the observer is a whole ACP process, and waiting for the
+        // idle reaper would be five more minutes of paying for a feature that was just switched off.
+        hub?.onPolicyChanged();
+        return send(res, 200, {
+          speak,
+          resolved: resolveSpeak(sid, { mode: getSettings().prefs.speakMode, intervalSec: getSettings().observer.intervalSec }),
+        });
+      }
+      if (req.method === "DELETE") {
+        // 回到默认层。删掉这一行而不是写 off：写 off 会让它永远不再继承默认。
+        clearSessionSpeak(sid);
+        hub?.onPolicyChanged();
+        return send(res, 200, {
+          resolved: resolveSpeak(sid, { mode: getSettings().prefs.speakMode, intervalSec: getSettings().observer.intervalSec }),
+        });
+      }
+      return send(res, 405, { error: "method not allowed" });
+    }
+
     // ---- 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.
@@ -1503,7 +1574,12 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         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) });
+        // `field` rides along when the validator named one (#65): the page shows it under that input.
+        const field = (e as { field?: unknown })?.field;
+        return send(res, 400, {
+          error: String((e as Error)?.message ?? e),
+          ...(typeof field === "string" ? { field } : {}),
+        });
       }
     }
     // The model ids the configured endpoint really serves, for the settings dropdowns

package/packages/server/src/notify/center.ts

@@ -315,6 +315,21 @@ export class NotifyCenter {
     return this.presence.visible || Boolean(this.presence.call);
   }
 
+  /** Is this the session the operator is ON right now — sessionId + TTL only, with no 「page visible
+   *  / keyboard touched」 requirement (issue #69 §5).
+   *
+   *  `operatorWatching` above answers 「is he in front of the screen」, which is the right question for
+   *  a notification: do not make a sound at someone who is already looking. 工作播报 asks the opposite
+   *  question — it exists so that he can look AWAY and still hear progress — so reusing the
+   *  screen-presence test there meant the beat required him to sit and watch, and it stayed silent
+   *  exactly when it was needed. Same presence record, one TTL, two questions.
+   */
+  operatorOnSession(sessionId: string): boolean {
+    if (!sessionId) return false;
+    if (this.presence.sessionId !== sessionId) return false;
+    return Date.now() - this.presence.at < NotifyCenter.WATCH_TTL_MS;
+  }
+
   constructor(opts: NotifyCenterOptions) {
     this.dir = path.join(opts.dataDir, "notify");
     fs.mkdirSync(this.dir, { recursive: true });

package/packages/server/src/observer/hub.ts

@@ -40,6 +40,7 @@ import fs from "node:fs";
 import path from "node:path";
 import type { BackendId, ServerEvent } from "../../../shared/src/index.js";
 import type { ObserverSettings } from "../settings.js";
+import type { SpeakMode } from "../session-speak.js";
 import { OBSERVER_PROMPT_DEFAULT } from "../settings.js";
 
 /** Spoken lines are short on purpose: they are heard once, in the middle of other work. */
@@ -59,8 +60,12 @@ const TICK_MS = 15_000;
 export interface ObserverDeps {
   /** Live settings, read per event — the switch must work without a restart. */
   settings(): ObserverSettings;
-  /** Whether the operator's speaker is in 工作播报 mode. False = do not even try. */
-  speakEnabled(): boolean;
+  /** The speaker position that applies to ONE session (issue #68): a session the operator set up
+   *  itself wins, otherwise the global default. This replaced a single global `speakEnabled()`,
+   *  which was why turning the horn on in one session made every other session start talking. */
+  speakOf?(sessionId: string): { mode: SpeakMode; intervalSec: number };
+  /** Legacy fallback for hosts and unit tests that only know the global switch. */
+  speakEnabled?(): boolean;
   /** Spawn a SYSTEM session (out of the rail); returns our id for it. */
   createSession(backend: BackendId, cwd: string, title: string): Promise<string>;
   /** Send one line to a session. Never `interrupt`: an observer must not take the floor. */
@@ -77,9 +82,14 @@ export interface ObserverDeps {
   disposeSession?(observerId: string): Promise<void>;
   /** Best-effort: move a session into a read-only mode if the backend offers one. */
   preferReadonly?(sessionId: string): void;
-  /** Is the operator looking at THIS session right now (the notify centre's presence)? Absent = every
-   *  session counts, which is the #16 behaviour and what a unit test without a presence wants. */
+  /** Is the operator looking at THIS session right now — the NOTIFY centre's presence, which asks
+   *  「is he in front of the screen」. Absent = every session counts. */
   watching?(sessionId: string): boolean;
+  /** 播报的「这是他当前那个会话吗」(issue #69 §5): sessionId + TTL only, NO 「2 分钟内动过键鼠」.
+   *  工作播报 exists precisely so the operator can look away — reusing the notification's
+   *  screen-presence test for it made the beat require him to be watching, which defeats the feature.
+   *  Absent = fall back to `watching`, so an old host keeps working. */
+  onSession?(sessionId: string): boolean;
   /** Does this session still have a live ACP process? Absent = assume yes. This is the half of #23
    *  that turns a reaped observer into a recoverable one instead of a permanent 「播报失败」. */
   alive?(sessionId: string): boolean;
@@ -117,8 +127,23 @@ interface Watch {
   startedAt: number;
   /** Model-backed briefs spent on the CURRENT turn (the MAX_BRIEFS_PER_TURN counter). */
   briefsThisTurn: number;
+  /** Why the last beat skipped this watch (issue #69 §6): the beat used to be silent in every sense —
+   *  no sound, no log line, no field on the diagnostic endpoint, so 「它到底有没有在跑」 could only be
+   *  guessed at. Kept per watch and cheap (one small object). */
+  lastSkip: { reason: SkipReason; at: number } | null;
 }
 
+/** Every reason a beat can decline to speak. The names are the contract with `/api/observer`. */
+export type SkipReason =
+  | "disabled"        // the observer section itself is off
+  | "speaker-off"     // this session's speaker is not in 工作播报
+  | "no-beat"         // speaker is on 工作播报 but no interval was chosen
+  | "busy"            // a brief is already being produced
+  | "not-inflight"    // no turn running → nothing to report
+  | "not-current"     // not the session the operator is on
+  | "no-beat-yet"     // the interval has not elapsed
+  | "per-turn-cap";   // MAX_BRIEFS_PER_TURN reached
+
 const NOTHING = "（没有可播报的进展）";
 
 /** Cut a model's answer down to one spoken line: first non-empty line, no Markdown furniture, no
@@ -173,7 +198,11 @@ export class ObserverHub {
     return this.#ticks;
   }
 
-  debug(): { watched: string; observerId: string | null; inflight: boolean; busy: boolean; briefs: number; watching: boolean; quietMs: number }[] {
+  debug(): {
+    watched: string; observerId: string | null; inflight: boolean; busy: boolean; briefs: number;
+    watching: boolean; quietMs: number; mode: SpeakMode; intervalSec: number;
+    skip: SkipReason | null; skipAgoMs: number | null;
+  }[] {
     const now = this.#now();
     return [...this.#watch.values()].map((w) => ({
       watched: w.observedId,
@@ -183,6 +212,10 @@ export class ObserverHub {
       briefs: w.briefsThisTurn,
       watching: this.#watching(w.observedId),
       quietMs: now - w.lastActivityAt,
+      mode: this.#mode(w.observedId),
+      intervalSec: this.#beat(w.observedId),
+      skip: w.lastSkip?.reason ?? null,
+      skipAgoMs: w.lastSkip ? now - w.lastSkip.at : null,
     }));
   }
 
@@ -225,8 +258,12 @@ export class ObserverHub {
    *  Until #23 this was invisible — `speakEnabled()` only made the hub idle, while the observer
    *  process (a whole ACP runtime, ~137 MB) sat there for the reaper's five minutes. */
   onPolicyChanged(): void {
-    if (this.#deps.speakEnabled() && this.#deps.settings().enabled) return;
-    for (const w of [...this.#watch.values()]) void this.#dispose(w);
+    const enabled = this.#deps.settings().enabled;
+    for (const w of [...this.#watch.values()]) {
+      // The section itself off, or THIS session no longer on 工作播报 (issue #69 §2: leaving the
+      // 档位 must reap its observer instead of leaving an orphan behind for the idle reaper).
+      if (!enabled || this.#mode(w.observedId) !== "brief") void this.#dispose(w);
+    }
   }
 
   /** Every ServerEvent in the process passes through here (index.ts wires it in front of the
@@ -278,7 +315,7 @@ export class ObserverHub {
       // still delivers it (approvals are never suppressed by 「我在看」), so the voice follows the
       // same scope as everything else here. Flip this to `#speaking()` alone if 「后台审批也念出来」
       // turns out to be wanted.
-      if (!this.#speaking()) return;
+      if (!this.#speaking(evt.request.sessionId)) return;
       if (!this.#watching(evt.request.sessionId)) return;
       const sid = evt.request.sessionId;
       const title = evt.request.toolCallTitle?.trim();
@@ -287,7 +324,7 @@ export class ObserverHub {
     }
 
     if (evt.t === "plan") {
-      if (!this.#speaking()) return;
+      if (!this.#speaking(evt.sessionId)) return;
       const plan = evt.plan;
       if (!plan) return;
       // Zero-cost, but still an announcement: the rail is where you read progress on a session you
@@ -315,23 +352,30 @@ export class ObserverHub {
   tick(): void {
     this.#ticks++;
     const s = this.#deps.settings();
-    if (!s.enabled || s.intervalSec <= 0 || !this.#deps.speakEnabled()) return;
+    if (!s.enabled) return;                                      // the observer section itself is off
     const now = this.#now();
     for (const w of [...this.#watch.values()]) {
+      const mode = this.#mode(w.observedId);
+      if (mode !== "brief") { this.#skip(w, "speaker-off"); continue; }
+      const beat = this.#beat(w.observedId);
+      if (beat <= 0) { this.#skip(w, "no-beat"); continue; }
       this.#ensure(w);                                           // a dead observer is not 「busy」
-      if (w.busy || w.spawning) continue;                        // a brief is already on its way
-      if (!w.inflight) continue;                                 // no turn → nothing to report
-      if (!this.#watching(w.observedId)) continue;               // not the session on screen
-      if (now - w.lastBriefAt < s.intervalSec * 1000) continue;  // the beat
-      if (now - w.lastBriefAt < s.throttleSec * 1000) continue;  // the min-gap still guards
-      if (w.briefsThisTurn >= MAX_BRIEFS_PER_TURN) continue;     // the per-turn wall
+      if (w.busy || w.spawning) { this.#skip(w, "busy"); continue; }
+      if (!w.inflight) { this.#skip(w, "not-inflight"); continue; }
+      // #69 §5: the beat asks 「is this the session he is on」, NOT 「has he touched the keyboard in
+      // the last two minutes」 — asking the operator to sit and watch is the opposite of the feature.
+      if (!this.#onSession(w.observedId)) { this.#skip(w, "not-current"); continue; }
+      if (now - w.lastBriefAt < beat * 1000) { this.#skip(w, "no-beat-yet"); continue; }
+      // #69 §3: `throttleSec` is the de-duplicating gap for EVENT-driven briefs (see #maybeBrief).
+      // Applying it here as well meant 「每 1 分钟」 could never fire faster than 2 minutes.
+      if (w.briefsThisTurn >= MAX_BRIEFS_PER_TURN) { this.#skip(w, "per-turn-cap"); continue; }
       void this.#maybeBrief(w.observedId, undefined, "heartbeat");
     }
   }
 
   /** A turn ended (or a beat came due) on a session the operator owns: is it worth a brief? */
   async #maybeBrief(sessionId: string, error?: string, kind: "turn-end" | "heartbeat" = "turn-end"): Promise<void> {
-    if (!this.#speaking()) return;
+    if (!this.#speaking(sessionId)) return;
     if (this.#observers.has(sessionId)) return;
     if (!this.#watching(sessionId)) return;
     const w = this.#watchFor(sessionId);
@@ -362,8 +406,12 @@ export class ObserverHub {
       w.queuedKind = kind;
       return;
     }
+    // #69 §3: `throttleSec` de-duplicates EVENT-driven briefs (two turn-ends a second apart must not
+    // buy two model calls). A beat the operator picked himself was already spaced by `intervalSec`
+    // in tick(), and applying the gap a second time here is exactly what made 「每 1 分钟」 faster
+    // than every 2 minutes on the wire — the gate passed, then this line shut it again.
     const gap = settings.throttleSec * 1000;
-    if (gap > 0 && this.#now() - w.lastBriefAt < gap) return;
+    if (kind !== "heartbeat" && gap > 0 && this.#now() - w.lastBriefAt < gap) return;
 
     let observerId = w.observerId;
     if (!observerId) {
@@ -377,7 +425,6 @@ export class ObserverHub {
       // event arriving during the spawn must queue instead of starting a rival turn.
       w.busy = true;
       w.lastBriefAt = this.#now();
-      w.briefsThisTurn++;
       try {
         observerId = await this.#spawnObserver(w);
       } catch (e) {
@@ -403,7 +450,9 @@ export class ObserverHub {
 
     w.busy = true;
     w.lastBriefAt = this.#now();
-    w.briefsThisTurn++;
+    // `briefsThisTurn` is charged in #finishBrief, and only for a line that really went out (#69 §6):
+    // charging it here meant a sentinel answer （没有可播报的进展）or a degraded fallback still spent
+    // one of the MAX_BRIEFS_PER_TURN, so eight quiet answers could mute the rest of a long turn.
     // The ONE thing an event passes the observer: that something happened. Everything else is read.
     const why =
       kind === "heartbeat"
@@ -429,7 +478,10 @@ export class ObserverHub {
     const text = oneLine(w.answer);
     w.answer = "";
     w.busy = false;
-    if (text && text !== NOTHING) this.#speak(w.observedId, text, "brief", 1);
+    if (text && text !== NOTHING) {
+      this.#speak(w.observedId, text, "brief", 1);
+      w.briefsThisTurn++;                       // spent by a line the operator actually heard
+    }
     if (w.queued) {
       const kind = w.queuedKind;
       w.queued = false;
@@ -489,7 +541,7 @@ export class ObserverHub {
       w = {
         observedId: sessionId, observerId: null, spawning: false, lastBriefAt: 0, queued: false,
         queuedKind: "turn-end", answer: "", busy: false, announcedSteps: new Set(),
-        inflight: false, lastActivityAt: now, startedAt: now, briefsThisTurn: 0,
+        inflight: false, lastActivityAt: now, startedAt: now, briefsThisTurn: 0, lastSkip: null,
       };
       this.#watch.set(sessionId, w);
     }
@@ -508,9 +560,34 @@ export class ObserverHub {
     w.answer = "";
   }
 
-  #speaking(): boolean {
-    if (!this.#deps.speakEnabled()) return false;
-    return true;
+  /** 这个会话现在开着工作播报吗 (issue #68: per session, not one global switch). */
+  #speaking(sessionId: string): boolean {
+    return this.#mode(sessionId) === "brief";
+  }
+
+  /** The speaker position that applies to one session: the host resolves session row → global
+   *  default. `speakEnabled` is the single-switch fallback for hosts and tests that predate #68. */
+  #mode(sessionId: string): SpeakMode {
+    const fn = this.#deps.speakOf;
+    if (fn) return fn(sessionId).mode;
+    return this.#deps.speakEnabled?.() ? "brief" : "off";
+  }
+
+  /** The beat for one session, in seconds (0 = the operator did not ask for a beat). */
+  #beat(sessionId: string): number {
+    const fn = this.#deps.speakOf;
+    if (fn) return fn(sessionId).intervalSec;
+    return this.#deps.settings().intervalSec;
+  }
+
+  /** Broadcasting asks a weaker question than notifying (issue #69 §5). */
+  #onSession(sessionId: string): boolean {
+    const fn = this.#deps.onSession;
+    return fn ? fn(sessionId) : this.#watching(sessionId);
+  }
+
+  #skip(w: Watch, reason: SkipReason): void {
+    w.lastSkip = { reason, at: this.#now() };
   }
 
   /** Is the operator on THIS session? The scope gate of #23; no dep = no scope (tests, old hosts). */

package/packages/server/src/session-speak.ts

@@ -0,0 +1,89 @@
+// 会话级的「喇叭档位」(issue #68).
+//
+// 全局 `prefs.speakMode` 表达的是「我怎么工作」，所以它跟着人跨设备走（见 settings.ts 文件头）。
+// 但「我在盯这一个长任务，把它念出来」是**某一个会话**的意图 —— 一个会话打开喇叭，其它会话跟着
+// 一起念，正是 issue #68 报的行为。两层不冲突：全局是**默认层**，会话行一旦存在就覆盖它。
+//
+// 存储用 settings 表里的一行 JSON（key = "sessionSpeak"）：
+//   { "<sessionId>": { "mode": "off"|"reply"|"brief", "intervalSec": number, "at": number } }
+// 不新开表，因为这一层没有任何按条件查询的需求（一次全读，一次一行写），而 settings 表本来就在做
+// 「操作员配置」这件事；新表还要配迁移与清理。
+import type { Store } from "./store/store.js";
+
+export type SpeakMode = "off" | "reply" | "brief";
+
+export interface SessionSpeak {
+  mode: SpeakMode;
+  /** 只在 mode === "brief" 时有意义：每 N 秒报一次。 */
+  intervalSec: number;
+  at: number;
+}
+
+/** 存储层的粗校验上限；真正的可选档位由前端的喇叭菜单决定。 */
+export const SPEAK_INTERVAL_MAX = 3600;
+
+let db: Store | null = null;
+
+export function initSessionSpeak(store: Store): void {
+  db = store;
+}
+
+function pick(raw: unknown): SessionSpeak | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as Record<string, unknown>;
+  const mode = r.mode;
+  if (mode !== "off" && mode !== "reply" && mode !== "brief") return null;
+  const iv = Number(r.intervalSec);
+  const intervalSec = Number.isFinite(iv) && iv >= 0 && iv <= SPEAK_INTERVAL_MAX ? Math.round(iv) : 0;
+  const at = Number(r.at);
+  return { mode, intervalSec, at: Number.isFinite(at) ? at : 0 };
+}
+
+/** 所有会话自己的档位。**没有**这一行的会话 = 继承全局默认（这正是兼容性的全部内容）。 */
+export function allSessionSpeak(): Record<string, SessionSpeak> {
+  const raw = db?.getSetting("sessionSpeak");
+  const out: Record<string, SessionSpeak> = {};
+  if (!raw || typeof raw !== "object") return out;
+  for (const [id, v] of Object.entries(raw as Record<string, unknown>)) {
+    const s = pick(v);
+    if (s) out[id] = s;
+  }
+  return out;
+}
+
+export function sessionSpeakOf(sessionId: string): SessionSpeak | null {
+  if (!sessionId) return null;
+  return allSessionSpeak()[sessionId] ?? null;
+}
+
+export function setSessionSpeak(sessionId: string, mode: SpeakMode, intervalSec = 0): SessionSpeak {
+  const all = allSessionSpeak();
+  const next: SessionSpeak = {
+    mode,
+    intervalSec: mode === "brief" ? Math.min(SPEAK_INTERVAL_MAX, Math.max(0, Math.round(intervalSec))) : 0,
+    at: Date.now(),
+  };
+  all[sessionId] = next;
+  db?.setSetting("sessionSpeak", all);
+  return next;
+}
+
+/** 回到「跟全局默认走」。删掉这一行，**而不是**写一条 `off` —— 写 off 会让这个会话永远不再继承
+ *  默认层，下次操作员改全局默认时它还会是静音的，那就成了另一种「莫名其妙」。 */
+export function clearSessionSpeak(sessionId: string): void {
+  const all = allSessionSpeak();
+  if (!(sessionId in all)) return;
+  delete all[sessionId];
+  db?.setSetting("sessionSpeak", all);
+}
+
+/** 一个会话实际生效的档位：会话行优先，否则全局默认。
+ *  这是唯一一处把两层合成一个答案的地方 —— hub 的闸门、喇叭的显示、诊断端点都读它。 */
+export function resolveSpeak(
+  sessionId: string,
+  dflt: { mode: SpeakMode; intervalSec: number },
+): { mode: SpeakMode; intervalSec: number; source: "session" | "default" } {
+  const own = sessionSpeakOf(sessionId);
+  if (own) return { mode: own.mode, intervalSec: own.intervalSec, source: "session" };
+  return { mode: dflt.mode, intervalSec: dflt.intervalSec, source: "default" };
+}

package/packages/server/src/settings.ts

@@ -753,7 +753,12 @@ export function publicSettings(): Record<string, unknown> {
   };
 }
 
-/** Merge a partial update. `apiKey: null` keeps the stored key (the UI round-trips a
+/** A validation failure that names the field it rejected. */
+function fieldError(field: string, message: string): Error {
+  return Object.assign(new Error(message), { field });
+}
+
+/** Merge a partial update. `apiKey: *** keeps the stored key (the UI round-trips a
  *  mask, never the secret). Empty strings clear. Values are validated narrowly: this
  *  config reaches an external API with the operator's credentials. */
 export function saveSettings(patch: Record<string, unknown>): Settings {
@@ -781,7 +786,10 @@ export function saveSettings(patch: Record<string, unknown>): Settings {
     if (raw === null || raw === undefined) { /* keep */ }
     else if (typeof raw === "string" && (raw === "" || /^sk-[\w.-]{6,}$/.test(raw))) v.apiKey = raw;
     else if (typeof raw === "string" && raw.startsWith("••••")) { /* unchanged mask: keep */ }
-    else throw new Error("invalid apiKey (expected sk-…, or empty to clear)");
+    // `field` is what lets the page put this message under the box that caused it. A banner at the
+    // top of a long settings page is invisible from the bottom of it, which is how 「保存没反应」
+    // became the reported bug (#65) when the server had answered 400 with the exact reason.
+    else throw fieldError("voice.apiKey", "invalid apiKey (expected sk-…, or empty to clear)");
   }
   // a baseUrl typed as the compatible-mode URL still works: store the root for the
   // native endpoints and derive the compatible path from it