agentus 0.3.8 → 0.4.0

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

@@ -0,0 +1,327 @@
+// 工作播报 (issue #16): ONE long-lived observer agent per watched session, driven by the cockpit.
+//
+// WHY AN AGENT AND NOT A TEMPLATE
+// The cockpit could say 「回合结束了」 by itself — that is exactly what #11's plan title does, and it
+// stays as the fallback. What it cannot do is NOTICE: 「第三步失败了，它在重试同一条命令」 is a
+// judgement about a transcript, and a string template that tries to make that judgement is a
+// summariser nobody can debug. So the cockpit hires a reader: a normal ACP session with its own
+// transcript, spawned once, kept alive, and asked one line per event (「看看进展」). Because it is
+// long-lived its context carries over — the second brief costs a line, not the whole story — and
+// because its facts come from the cockpit CLI (`$AGENTUS_COCKPIT_BIN`, issue #15) the trigger line
+// never has to carry data that could be wrong.
+//
+// WHAT THIS MODULE IS ALLOWED TO KNOW
+// Nothing about agents' internals. It reads ServerEvents off the same emitter the browser reads,
+// decides "is this worth a voice", and (for two event kinds) formats the line ITSELF with no model
+// call at all: an approval waiting and a plan step closing are facts, and paying a model to restate a
+// fact is how a cockpit becomes expensive and vague.
+//
+// THE OBSERVER IS A SYSTEM SESSION
+// Its working directory is a scratch directory of its own (`<home>/observers/<sid>`), never the
+// observed session's cwd: an observer runs a full agent runtime with file and shell tools, and it
+// should no more be able to write into the project than a log shipper should. `system: true` keeps it
+// out of the rail and out of the cockpit CLI's scope (see SessionManager.list). It is spawned ONCE
+// and reused; the idle reaper may put it to sleep like any slot, and `ensure()` wakes it.
+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 { OBSERVER_PROMPT_DEFAULT } from "../settings.js";
+
+/** Spoken lines are short on purpose: they are heard once, in the middle of other work. */
+export const BRIEF_MAX = 120;
+
+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;
+  /** 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. */
+  prompt(sessionId: string, text: string): Promise<void>;
+  /** Resolve once a freshly spawned session can accept a prompt (its handshake finished). */
+  waitReady(sessionId: string, timeoutMs?: number): Promise<void>;
+  /** The title a session is known by (for the trigger line and the prompt header). */
+  titleOf(sessionId: string): string | null;
+  /** Which backend the observed session runs on (used when the observer follows it). */
+  backendOf(sessionId: string): BackendId | null;
+  /** #11's one-line task title for a session — the zero-cost fallback when no observer can speak. */
+  planTitleOf?(sessionId: string): string | null;
+  /** Close (or just forget) an observer whose observed session is gone. */
+  disposeSession?(observerId: string): Promise<void>;
+  /** Best-effort: move a session into a read-only mode if the backend offers one. */
+  preferReadonly?(sessionId: string): void;
+  /** Base directory for per-observer scratch dirs. */
+  home: string;
+  emit(evt: ServerEvent): void;
+  now?(): number;
+}
+
+interface Watch {
+  /** The session being watched (the watch map is keyed by it too; kept for the observer's side). */
+  observedId: string;
+  /** Our observer session id, once one exists. */
+  observerId: string | null;
+  /** A spawn is in flight — do not start a second one. */
+  spawning: boolean;
+  /** When the last MODEL-backed brief went out (for the throttle). */
+  lastBriefAt: number;
+  /** The trigger is owed: an event arrived while a brief was still being produced. */
+  queued: boolean;
+  /** Text of the observer's current turn, accumulated from `message` frames. */
+  answer: string;
+  /** True while the observer is producing a brief. */
+  busy: boolean;
+  /** Plan step keys already announced, so an unchanged plan is not read out twice. */
+  announcedSteps: Set<string>;
+}
+
+const NOTHING = "（没有可播报的进展）";
+
+/** Cut a model's answer down to one spoken line: first non-empty line, no Markdown furniture, no
+ *  quotes, hard cap. A brief is read aloud, so anything resembling formatting is noise. */
+export function oneLine(text: string, max = BRIEF_MAX): string {
+  const first = text
+    .split(/\r?\n/)
+    .map((l) => l.replace(/^\s*(?:[-*#>\d.)\s]+)/, "").trim())
+    .find((l) => l.length > 0) ?? "";
+  const flat = first
+    .replace(/[*_`]/g, "")
+    .replace(/^["'「『]+|["'」』]+$/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+export class ObserverHub {
+  #deps: ObserverDeps;
+  #watch = new Map<string, Watch>();
+  /** Observer ids, so their own frames are never mistaken for the operator's sessions. */
+  #observers = new Set<string>();
+  #now: () => number;
+
+  constructor(deps: ObserverDeps) {
+    this.#deps = deps;
+    this.#now = deps.now ?? Date.now;
+  }
+
+  observerIds(): string[] {
+    return [...this.#observers];
+  }
+
+  isObserver(sessionId: string): boolean {
+    return this.#observers.has(sessionId);
+  }
+
+  /** Forget everything about a session (it was closed, archived or purged). The observer process is
+   *  the idle reaper's business; we only stop treating this pair as current. */
+  forget(sessionId: string): void {
+    const w = this.#watch.get(sessionId);
+    this.#watch.delete(sessionId);
+    if (w?.observerId) this.#observers.delete(w.observerId);
+  }
+
+  /** Every ServerEvent in the process passes through here (index.ts wires it in front of the
+   *  broadcast). Cheap by construction: a few kind checks per frame. */
+  onEvent(evt: ServerEvent): void {
+    if (evt.t === "message") {
+      // The observer's own answer, being assembled.
+      const sid = evt.message.sessionId;
+      // `message` frames for an observer carry the OBSERVER's id, while the watch entry is keyed by
+      // the OBSERVED session — so this is a lookup by observer id, not by key.
+      for (const watch of this.#watch.values()) {
+        if (watch.observerId !== sid) continue;
+        if (evt.message.kind === "agent") watch.answer += textOfPayload(evt.message.payload);
+      }
+      return;
+    }
+
+    if (evt.t === "turn-end") {
+      // An observer's own turn-end IS the brief's arrival — resolved by observer id, because the
+      // watch map is keyed by the OBSERVED session (looking the observer up in it finds nothing,
+      // which is how the first version turned every observer turn into another trigger).
+      if (this.#observers.has(evt.sessionId)) {
+        for (const w of this.#watch.values()) if (w.observerId === evt.sessionId) this.#finishBrief(w);
+        return;
+      }
+      void this.#maybeBrief(evt.sessionId, evt.error);
+      return;
+    }
+
+    if (evt.t === "permission") {
+      // A request waiting for an answer is the one thing never worth a model call: the fact is
+      // right here, and the operator may be away from the screen for a while.
+      if (!this.#speaking()) return;
+      const sid = evt.request.sessionId;
+      const title = evt.request.toolCallTitle?.trim();
+      this.#speak(sid, title ? `有请求等你确认：${title}` : "有个请求等你确认", "approval", 2);
+      return;
+    }
+
+    if (evt.t === "plan") {
+      if (!this.#speaking()) return;
+      const w = this.#watchFor(evt.sessionId);
+      const plan = evt.plan;
+      if (!plan) return;
+      for (const item of plan.items) {
+        if (item.status !== "completed") continue;
+        // PlanItem has no id: its content IS the identity (ACP replaces the whole list each frame).
+        const key = item.content;
+        if (w.announcedSteps.has(key)) continue;
+        w.announcedSteps.add(key);
+        // The FIRST completed step of a plan is worth a word; after that the rail is the place to
+        // read progress, and a voice per step would be a metronome.
+        if (w.announcedSteps.size === 1) {
+          this.#speak(evt.sessionId, `完成一步：${oneLine(item.content, 60)}`, "plan-step", 1);
+        }
+      }
+      return;
+    }
+  }
+
+  /** A turn ended on a session the operator owns: is it worth a brief? */
+  async #maybeBrief(sessionId: string, error?: string): Promise<void> {
+    if (!this.#speaking()) return;
+    if (this.#observers.has(sessionId)) return;
+    const w = this.#watchFor(sessionId);
+    const settings = this.#deps.settings();
+    if (!settings.enabled) {
+      // Degrade to the zero-cost line (#11's plan title) — the observer is off, but the operator
+      // still asked to be told what happened.
+      const title = this.#deps.titleOf(sessionId);
+      const planTitle = this.#deps.planTitleOf?.(sessionId) ?? null;
+      if (error) this.#speak(sessionId, `${title ?? "会话"} 出错了：${oneLine(error, 60)}`, "fallback", 1);
+      else if (planTitle) this.#speak(sessionId, `${title ?? "会话"} · ${planTitle}`, "fallback", 1);
+      return;
+    }
+    if (w.busy) {
+      // A brief is in flight: remember that another one is owed and let the current one finish,
+      // rather than interleaving two turns into one voice.
+      w.queued = true;
+      return;
+    }
+    const gap = settings.throttleSec * 1000;
+    if (gap > 0 && this.#now() - w.lastBriefAt < gap) return;
+
+    let observerId = w.observerId;
+    if (!observerId) {
+      if (w.spawning) {
+        w.queued = true;
+        return;
+      }
+      w.spawning = true;
+      // Busy from here: the observer's FIRST turn (persona + look) is itself a brief, and a second
+      // event arriving during the spawn must queue instead of starting a rival turn.
+      w.busy = true;
+      try {
+        observerId = await this.#spawnObserver(w);
+      } catch (e) {
+        w.spawning = false;
+        w.busy = false;
+        // Degrade rather than go silent: the operator asked for 工作播报 and a broken observer must
+        // not turn the feature off without telling them.
+        const planTitle = this.#deps.planTitleOf?.(sessionId) ?? null;
+        const title = this.#deps.titleOf(sessionId) ?? "会话";
+        this.#speak(
+          sessionId,
+          planTitle ? `${title} · ${planTitle}` : `${title} 的播报员没起来：${oneLine(String((e as Error)?.message ?? e), 50)}`,
+          "fallback",
+          1,
+        );
+        return;
+      }
+      w.spawning = false;
+      // `#spawnObserver` already registered the id and marked the watch busy: the first brief is
+      // produced by the prompt it sent, so there is nothing to send here.
+      return;
+    }
+
+    w.busy = true;
+    w.lastBriefAt = this.#now();
+    // The ONE thing an event passes the observer: that something happened. Everything else is read.
+    const why = error ? "这一轮报了错。" : "这一轮结束了。";
+    try {
+      await this.#deps.prompt(observerId, `${why}看一眼进展，按你的契约给一句播报。`);
+    } catch (e) {
+      w.busy = false;
+      this.#speak(sessionId, `播报失败：${oneLine(String((e as Error)?.message ?? e), 50)}`, "fallback", 1);
+    }
+  }
+
+  /** The observer answered: turn its text into the spoken line. */
+  #finishBrief(w: Watch): void {
+    const text = oneLine(w.answer);
+    w.answer = "";
+    w.busy = false;
+    if (text && text !== NOTHING) this.#speak(w.observedId, text, "brief", 1);
+    if (w.queued) {
+      w.queued = false;
+      void this.#maybeBrief(w.observedId);
+    }
+  }
+
+  async #spawnObserver(w: Watch): Promise<string> {
+    const observedId = w.observedId;
+    const settings = this.#deps.settings();
+    const backend = settings.backend ?? this.#deps.backendOf(observedId);
+    if (!backend) throw new Error("不知道该用哪个后端");
+    const dir = path.join(this.#deps.home, "observers", observedId);
+    fs.mkdirSync(dir, { recursive: true });
+    const title = this.#deps.titleOf(observedId) ?? observedId;
+    const id = await this.#deps.createSession(backend, dir, `观察员 · ${title}`);
+    // Registered BEFORE its first prompt: the turn it is about to run is a brief, and its frames must
+    // already be attributable to this pair (see the turn-end branch in onEvent).
+    w.observerId = id;
+    this.#observers.add(id);
+    // `create` returns before the handshake by design; an observer is spawned and prompted in the
+    // same breath, so wait for the one fact only the agent can give us.
+    await this.#deps.waitReady(id);
+    this.#deps.preferReadonly?.(id);
+    // The prompt is the operator's, plus the one fact the observer cannot read for itself: which
+    // session it is watching. Everything else it looks up.
+    const wording = settings.systemPrompt.trim() || OBSERVER_PROMPT_DEFAULT;
+    const system = `${wording}\n\n你负责的会话 id 是 ${observedId}（名字：${title}）。`;
+    // ACP has no "system prompt" call: the persona rides as the observer's first turn, and its own
+    // transcript keeps it. Everything after that is a one-line trigger.
+    await this.#deps.prompt(id, `${system}\n\n现在先看一眼这个会话的现状，给一句播报。`);
+    return id;
+  }
+
+  #watchFor(sessionId: string): Watch {
+    let w = this.#watch.get(sessionId);
+    if (!w) {
+      w = { observedId: sessionId, observerId: null, spawning: false, lastBriefAt: 0, queued: false, answer: "", busy: false, announcedSteps: new Set() };
+      this.#watch.set(sessionId, w);
+    }
+    return w;
+  }
+
+  #speaking(): boolean {
+    if (!this.#deps.speakEnabled()) return false;
+    return true;
+  }
+
+  #speak(sessionId: string, text: string, kind: "approval" | "plan-step" | "brief" | "fallback", priority: 1 | 2): void {
+    const clean = oneLine(text);
+    if (!clean) return;
+    this.#deps.emit({
+      t: "speak",
+      id: `${sessionId}:${kind}:${this.#now()}`,
+      sessionId,
+      text: clean,
+      kind,
+      priority,
+    });
+  }
+}
+
+/** The streamed text inside an `agent`/`thought` payload (ACP: `content.text`). */
+function textOfPayload(payload: unknown): string {
+  const c = (payload as { content?: unknown } | null)?.content;
+  if (c && typeof c === "object" && typeof (c as { text?: unknown }).text === "string") {
+    return (c as { text: string }).text;
+  }
+  const t = (payload as { text?: unknown } | null)?.text;
+  return typeof t === "string" ? t : "";
+}

package/packages/server/src/plan/plan.ts

@@ -19,6 +19,22 @@ import type { PlanItem } from "../../../shared/src/index.js";
 /** Studio caps its plan remark at 1000 chars; take the same bound rather than invent one. */
 export const MAX_EXPLANATION = 1000;
 
+/** How long the plan's `title` may be.
+ *
+ *  Forty is a NOTIFICATION's budget, not a document's: the body line it lands on already carries the
+ *  session name and the duration (`nameAndDetail`), and the collapsed row of a phone card is one
+ *  line. A writer that wants to say more writes a remark — `explanation` is the place for prose. */
+export const MAX_TITLE = 40;
+
+/** Coerce a writer's `title`. Collapsed whitespace, and `null` for anything that is not a real
+ *  string: an empty title must land as "no title", never as an empty line on the card. */
+export function clampTitle(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const s = raw.replace(/\s+/g, " ").trim();
+  if (!s) return null;
+  return s.length > MAX_TITLE ? s.slice(0, MAX_TITLE) : s;
+}
+
 export type PlanTerminal = "ended" | "interrupted" | "failed";
 export type PlanSource = "acp" | "mcp" | "server";
 

package/packages/server/src/settings.ts

@@ -18,6 +18,7 @@
 // masked value round-trips as null and keeps the stored secret.
 import fs from "node:fs";
 import path from "node:path";
+import type { BackendId } from "../../shared/src/index.js";
 import type { Store } from "./store/store.js";
 
 export interface VoiceSettings {
@@ -91,8 +92,13 @@ export interface CallSettings {
  *  the speed have to be the same on the phone as on the laptop, and a second tab disagreeing
  *  with the first is a bug, not a feature. */
 export interface PrefsSettings {
-  /** read a finished reply aloud without being asked */
+  /** read a finished reply aloud without being asked. Kept as a DERIVED mirror of `speakMode`:
+   *  the two used to be one switch, and a client that only knows this name must keep working. */
   autoRead: boolean;
+  /** WHAT gets read aloud (issue #16). "off" = nothing; "reply" = the finished reply, full text
+   *  (the old autoRead); "brief" = the cockpit's own one-line briefs (`t:"speak"`), which is what
+   *  a long answer needs — reading a whole reply aloud was the thing operators turned off. */
+  speakMode: SpeakMode;
   /** browser voiceURI ("" = pick the best for the language) */
   voiceURI: string;
   rate: number;
@@ -133,8 +139,11 @@ export interface PlanHintSettings {
   instruction: string;
 }
 
+export const SPEAK_MODES = ["off", "reply", "brief"] as const;
+export type SpeakMode = (typeof SPEAK_MODES)[number];
+
 export const PREFS_DEFAULT: PrefsSettings = {
-  autoRead: false, voiceURI: "", rate: 1, lang: "", serverTts: false, stt: "auto",
+  autoRead: false, speakMode: "off", voiceURI: "", rate: 1, lang: "", serverTts: false, stt: "auto",
   // On + every turn by default: the feature exists because the tool was there and nobody used it,
   // and 对齐 Studio means the block rides on every turn (see everyTurn's note). Both are visible
   // and switchable in 设置 — this is a default, not a lock.
@@ -142,7 +151,10 @@ export const PREFS_DEFAULT: PrefsSettings = {
 };
 
 export const CALL_DEFAULT: CallSettings = {
-  interruptMode: "voice", bargeSensitivity: 60, bargeMs: 300, silenceMs: 1200, minChars: 3,
+  /* 说完停顿 1.5s (was 1.2): the operator reads a pause as "it stopped listening" before 1.2 s,
+     and a long sentence with a breath in the middle got cut. Both ends of the range still let
+     the room decide — this is only where a fresh install starts. */
+  interruptMode: "voice", bargeSensitivity: 60, bargeMs: 300, silenceMs: 1500, minChars: 3,
 };
 
 export const INTERRUPT_MODES: InterruptMode[] = ["voice", "button"];
@@ -167,9 +179,18 @@ export interface AgentSettings {
    *  is a permanent memory floor (5 × ~137 MB RSS measured); with it, a cockpit left alone for a day
    *  comes back to nothing running. 0 = 不过期. */
   warmTtlHours: number;
+  /** 驾驶舱互发消息 (issue #15): may an agent hand a message to ANOTHER session through the cockpit
+   *  CLI (`agentus cockpit send`)? Off by default — two agents that can talk to each other without
+   *  being asked are a loop generator, and the operator pays for those tokens. Reading the cockpit
+   *  (`context`/`messages`/`plan`) is NOT gated: it cannot change anything, and it is what the
+   *  工作播报 observer runs on. */
+  cockpitSend: boolean;
 }
 
-export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5, warmSlots: 5, warmTtlHours: 24 };
+export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5, warmSlots: 5, warmTtlHours: 24, cockpitSend: false };
+
+/** The numeric half of `AgentSettings` — the keys the range-checked helpers may write. */
+type AgentNumberKey = "idleKillMin" | "warmSlots" | "warmTtlHours";
 
 /** What the settings page may offer: the ends of the number field. Server-side enforcement uses
  *  the same pair, so a hand-written request cannot store a nonsense value. */
@@ -180,6 +201,48 @@ export const AGENT_WARM_RANGE: [number, number] = [0, 20];
 /** 0 = 不过期; a week is the longest span worth offering on the page. */
 export const AGENT_WARM_TTL_RANGE: [number, number] = [0, 168];
 
+/** 观察智能体 (`工作播报`, issue #16): ONE long-lived ACP session per observed session, spawned by the
+ *  cockpit, in its own scratch directory, read-only, out of the rail. It is the thing that turns
+ *  「回合结束了」 into one sentence a person can listen to — it reads the cockpit through the CLI
+ *  (issue #15) instead of being handed a summary, because a summariser that is told what happened
+ *  cannot notice what the operator actually cares about.
+ *
+ *  Everything here is the operator's: the switch, which backend/model runs it (a cheap fast model is
+ *  the right answer), the wording it answers in, and the throttle. */
+export interface ObserverSettings {
+  /** 工作播报 on/off. Off = no observer is spawned at all and the speaker falls back to #11's
+   *  plan title (zero cost), then to nothing. */
+  enabled: boolean;
+  /** Which backend the observer runs on. null = same backend as the observed session (the default:
+   *  an install that only configured one agent should not have to configure a second one). */
+  backend: BackendId | null;
+  /** The observer's own wording. "" = the built-in template (which is also what the settings page
+   *  shows as the thing it will actually send). Sized like the plan hint's instruction: a few
+   *  sentences of house style, not a document — it rides on ONE turn per brief. */
+  systemPrompt: string;
+  /** Shortest gap between two MODEL-backed briefs for the same session, in seconds. Zero-cost
+   *  events (an approval is waiting, a step completed) never wait on it. Default 120: a brief per
+   *  turn is fine, a brief per token is a phone that never stops talking. */
+  throttleSec: number;
+}
+
+export const OBSERVER_PROMPT_MAX = 2000;
+export const OBSERVER_THROTTLE_RANGE: [number, number] = [0, 3600];
+
+/** What the observer is told, when the operator writes nothing. Two jobs in one paragraph: say who
+ *  it is watching and how to find out (the cockpit CLI — never trust the trigger line for facts), and
+ *  fix the output shape (one sentence, ≤60 characters, spoken aloud by a TTS voice). */
+export const OBSERVER_PROMPT_DEFAULT = [
+  "你是这个驾驶舱里某个会话的观察员。用 `$AGENTUS_COCKPIT_BIN session list` 看全景，",
+  "用 `session <id>` / `messages <id> --tail 20` / `plan <id>` 核实它正在做什么、卡在哪。",
+  "只陈述这些工具读到的事实，不猜、不补、不评价；工具没说的就当不知道。",
+  "输出一句中文播报，不超过 60 字，会被语音念出来：不要 Markdown、不要列表、不要引号、不要解释你在做什么。",
+].join("\n");
+
+export const OBSERVER_DEFAULT: ObserverSettings = {
+  enabled: false, backend: null, systemPrompt: "", throttleSec: 120,
+};
+
 /** The NUMERIC knobs. `interruptMode` is a two-way choice, not a slider, so it is deliberately
  *  outside both the range table and the loops that validate numbers. */
 export const CALL_NUMERIC = ["bargeSensitivity", "bargeMs", "silenceMs", "minChars"] as const;
@@ -214,6 +277,7 @@ export interface Settings {
   call: CallSettings;
   prefs: PrefsSettings;
   agent: AgentSettings;
+  observer: ObserverSettings;
   updatedAt: number;
 }
 
@@ -240,7 +304,8 @@ let db: Store | null = null;
 let legacyFile = "";
 let cache: Settings = {
   voice: { ...DEFAULTS }, theme: { ...THEME_DEFAULT }, call: { ...CALL_DEFAULT },
-  prefs: { ...PREFS_DEFAULT }, agent: { ...AGENT_DEFAULT }, updatedAt: 0,
+  prefs: { ...PREFS_DEFAULT }, agent: { ...AGENT_DEFAULT },
+  observer: { ...OBSERVER_DEFAULT }, updatedAt: 0,
 };
 /** keys that came from env/.env (shown as "auto-detected" and used when settings are empty) */
 let envCreds: { apiKey: string; baseUrl: string; source: string } | null = null;
@@ -305,6 +370,7 @@ export function initSettings(dataDir: string, store: Store): Settings {
     call: pickCall(stored.call),
     prefs: pickPrefs(stored.prefs),
     agent: pickAgent(stored.agent),
+    observer: pickObserver(stored.observer),
     updatedAt: Number((stored as Settings).updatedAt ?? 0),
   };
   // an unset baseUrl/apiKey bootstrap from the environment: the operator said the
@@ -342,7 +408,9 @@ function pickAgent(raw: unknown): AgentSettings {
   const out = { ...AGENT_DEFAULT };
   if (raw && typeof raw === "object") {
     const r = raw as Record<string, unknown>;
-    const take = (key: keyof AgentSettings, range: [number, number]): void => {
+    // Explicitly the NUMERIC keys: `AgentSettings` also carries `cockpitSend: boolean`, and a
+    // `keyof` assignment would have to satisfy both sides of the union.
+    const take = (key: AgentNumberKey, range: [number, number]): void => {
       const v = Number(r[key]);
       const [lo, hi] = range;
       if (Number.isFinite(v) && v >= lo && v <= hi) out[key] = v;
@@ -350,6 +418,27 @@ function pickAgent(raw: unknown): AgentSettings {
     take("idleKillMin", AGENT_IDLE_RANGE);
     take("warmSlots", AGENT_WARM_RANGE);
     take("warmTtlHours", AGENT_WARM_TTL_RANGE);
+    if (typeof r.cockpitSend === "boolean") out.cockpitSend = r.cockpitSend;
+  }
+  return out;
+}
+
+/** The observer's own section. Untrusted like the rest: an unknown backend id, a prompt over the
+ *  cap or a throttle outside the range falls back to the shipped default rather than throwing —
+ *  this section decides whether the cockpit spawns an agent to talk about another agent, and a
+ *  corrupt row must leave it in the SHIPPED state (off), not in a half-configured one. */
+function pickObserver(raw: unknown): ObserverSettings {
+  const out = { ...OBSERVER_DEFAULT };
+  if (raw && typeof raw === "object") {
+    const r = raw as Record<string, unknown>;
+    if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+    if (typeof r.backend === "string" && r.backend) out.backend = r.backend as BackendId;
+    if (typeof r.systemPrompt === "string" && r.systemPrompt.length <= OBSERVER_PROMPT_MAX) {
+      out.systemPrompt = r.systemPrompt;
+    }
+    const n = Number(r.throttleSec);
+    const [lo, hi] = OBSERVER_THROTTLE_RANGE;
+    if (Number.isFinite(n) && n >= lo && n <= hi) out.throttleSec = n;
   }
   return out;
 }
@@ -358,7 +447,12 @@ function pickPrefs(raw: unknown): PrefsSettings {
   const out = { ...PREFS_DEFAULT };
   if (raw && typeof raw === "object") {
     const r = raw as Record<string, unknown>;
-    if (typeof r.autoRead === "boolean") out.autoRead = r.autoRead;
+    // `speakMode` is the source of truth; `autoRead` is the pre-#16 name for its "reply" value. A
+    // stored section carries one or the other depending on which build wrote it last, so accept
+    // both and let the newer name win when both are present.
+    if (r.speakMode === "off" || r.speakMode === "reply" || r.speakMode === "brief") out.speakMode = r.speakMode;
+    else if (typeof r.autoRead === "boolean") out.speakMode = r.autoRead ? "reply" : "off";
+    out.autoRead = out.speakMode === "reply";
     if (typeof r.serverTts === "boolean") out.serverTts = r.serverTts;
     if (typeof r.voiceURI === "string" && r.voiceURI.length <= 200) out.voiceURI = r.voiceURI;
     if (typeof r.lang === "string" && (!r.lang || /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(r.lang))) out.lang = r.lang;
@@ -387,6 +481,7 @@ function persist(): void {
     db.setSetting("call", cache.call);
     db.setSetting("prefs", cache.prefs);
     db.setSetting("agent", cache.agent);
+    db.setSetting("observer", cache.observer);
   } catch (e) {
     console.error(`[agentus] cannot write settings: ${(e as Error).message}`);
   }
@@ -434,6 +529,11 @@ export function publicSettings(): Record<string, unknown> {
     agentIdleRange: AGENT_IDLE_RANGE,
     agentWarmRange: AGENT_WARM_RANGE,
     agentWarmTtlRange: AGENT_WARM_TTL_RANGE,
+    observer: cache.observer,
+    observerDefaults: OBSERVER_DEFAULT,
+    observerPromptDefault: OBSERVER_PROMPT_DEFAULT,
+    observerPromptMax: OBSERVER_PROMPT_MAX,
+    observerThrottleRange: OBSERVER_THROTTLE_RANGE,
     // the defaults, so the UI can offer "reset to Bailian defaults"
     defaults: { ...DEFAULTS, apiKey: undefined, baseUrl: undefined },
     updatedAt: cache.updatedAt,
@@ -554,6 +654,18 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
     if (!["auto", "browser", "stream", "server"].includes(v)) throw new Error(`invalid stt: ${JSON.stringify(patch.stt)}`);
     next.stt = v as PrefsSettings["stt"];
   }
+  // 三档（关 / 自动朗读 / 工作播报）. The old boolean still writes, so a cached page from before this
+  // change does something sensible instead of failing: autoRead:true = "reply", false = "off".
+  if ("speakMode" in patch) {
+    const v = String(patch.speakMode ?? "");
+    if (!SPEAK_MODES.includes(v as SpeakMode)) throw new Error(`invalid speakMode: ${JSON.stringify(patch.speakMode)}`);
+    next.speakMode = v as SpeakMode;
+    next.autoRead = v === "reply";
+  } else if ("autoRead" in patch) {
+    if (typeof patch.autoRead !== "boolean") throw new Error("invalid autoRead: expected true/false");
+    next.speakMode = patch.autoRead ? "reply" : "off";
+    next.autoRead = patch.autoRead;
+  }
   if ("planHint" in patch) {
     const h = patch.planHint;
     if (!h || typeof h !== "object") throw new Error("invalid planHint: expected an object");
@@ -589,7 +701,7 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
  *  text fields. */
 export function saveAgent(patch: Record<string, unknown>): Settings {
   const a = { ...cache.agent };
-  const set = (key: keyof AgentSettings, range: [number, number], unit: string, off: string): void => {
+  const set = (key: AgentNumberKey, range: [number, number], unit: string, off: string): void => {
     if (!(key in patch)) return;
     const raw = typeof patch[key] === "number" ? (patch[key] as number) : Number(patch[key]);
     const [lo, hi] = range;
@@ -601,6 +713,11 @@ export function saveAgent(patch: Record<string, unknown>): Settings {
   set("idleKillMin", AGENT_IDLE_RANGE, "minutes", "0 = off");
   set("warmSlots", AGENT_WARM_RANGE, "slots", "0 = off");
   set("warmTtlHours", AGENT_WARM_TTL_RANGE, "hours", "0 = never expires");
+  // A boolean next to three numbers: spelled out rather than forced through the numeric `set`.
+  if ("cockpitSend" in patch) {
+    if (typeof patch.cockpitSend !== "boolean") throw new Error("invalid cockpitSend: expected true or false");
+    a.cockpitSend = patch.cockpitSend;
+  }
   cache = { ...cache, agent: a, updatedAt: Date.now() };
   persist();
   return cache;
@@ -613,6 +730,47 @@ export function agentSettings(): AgentSettings {
   return cache.agent;
 }
 
+/** 观察智能体 knobs (issue #16). Read per event, like the plan hint: 工作播报 must be switchable
+ *  without restarting anything. */
+export function observerSettings(): ObserverSettings {
+  return cache.observer;
+}
+
+/** Save 观察智能体. Its own update, like the agent knobs, so a bad value in this section cannot
+ *  lock the operator out of the page that fixes it. */
+export function saveObserver(patch: Record<string, unknown>): Settings {
+  const o = { ...cache.observer };
+  if ("enabled" in patch) {
+    if (typeof patch.enabled !== "boolean") throw new Error("invalid enabled: expected true/false");
+    o.enabled = patch.enabled;
+  }
+  if ("backend" in patch) {
+    const v = patch.backend;
+    if (v === null || v === "") o.backend = null;
+    else if (typeof v === "string" && v.length <= 40) o.backend = v as BackendId;
+    else throw new Error(`invalid backend: ${JSON.stringify(v).slice(0, 40)}`);
+  }
+  if ("systemPrompt" in patch) {
+    const v = String(patch.systemPrompt ?? "");
+    if (v.length > OBSERVER_PROMPT_MAX) {
+      throw new Error(`invalid systemPrompt: longer than ${OBSERVER_PROMPT_MAX} characters`);
+    }
+    // Whitespace-only means "use the built-in template", the same rule the plan hint uses.
+    o.systemPrompt = v.trim() ? v : "";
+  }
+  if ("throttleSec" in patch) {
+    const n = Number(patch.throttleSec);
+    const [lo, hi] = OBSERVER_THROTTLE_RANGE;
+    if (!Number.isFinite(n) || n < lo || n > hi) {
+      throw new Error(`invalid throttleSec: ${JSON.stringify(patch.throttleSec)} (expected ${lo}…${hi} seconds)`);
+    }
+    o.throttleSec = Math.round(n);
+  }
+  cache = { ...cache, observer: o, updatedAt: Date.now() };
+  persist();
+  return cache;
+}
+
 /** The plan-hint knobs. Read on EVERY prompt (not cached here), so the switch in 设置 takes effect
  *  on the operator's very next turn — no restart, no session to hibernate. */
 export function planHintSettings(): PlanHintSettings {