agentus 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.3.4",
+ "version": "0.3.6",
  "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": {
@@ -52,6 +52,10 @@
   "workspace-smoke": "node scripts/workspace-smoke.mjs",
   "voice-smoke": "node scripts/voice-smoke.mjs",
   "sentence-units": "tsx scripts/qa/sentence-units.mts",
+  "token-format": "tsx scripts/qa/token-format.mts",
+  "terminal-palette": "tsx scripts/qa/terminal-palette.mts",
+  "android-trust-merge": "node scripts/qa/android-trust-merge.mjs",
+  "plan-hint-sweep": "node scripts/qa/plan-hint-sweep.mjs",
   "plan-service-sweep": "node scripts/qa/plan-service-sweep.mjs",
   "plan-mcp-sweep": "node scripts/qa/plan-mcp-sweep.mjs",
   "plan-v2-sweep": "tsx scripts/qa/plan-v2-sweep.mts",

package/packages/server/src/acp/registry.ts

@@ -204,7 +204,17 @@ export interface BackendHandshake {
   /** agentCapabilities.sessionCapabilities.fork */
   fork: boolean | null;
   modes: { currentModeId: string | null; available: string[]; names?: Record<string, string> } | null;
-  configOptions: { id: string; name: string | null; currentValue: string | null }[];
+  /** The ACP `select`s, kept WHOLE rather than reduced to id/name/currentValue: the new-session
+   *  start page has no session to read configOptions from, so the controls it draws come from
+   *  here — and a control without its `options` is a button that cannot be turned. */
+  configOptions: {
+    id: string;
+    name: string | null;
+    currentValue: string | null;
+    type?: string | null;
+    category?: string | null;
+    options?: { value: string; name: string | null; description?: string | null }[] | null;
+  }[];
   models: { currentModelId: string | null; available: string[] } | null;
   /** slash commands the agent announced (session/update or newSession) */
   commands: string[];
@@ -621,6 +631,23 @@ export function handshakeFrom(
       id: o.id,
       name: o.name ?? null,
       currentValue: o.currentValue === undefined || o.currentValue === null ? null : String(o.currentValue),
+      // Passed through defensively like everything else here: the SDK types cover only part of what
+      // the wire carries, and a session's real control set differs per agent.
+      type: typeof (o as { type?: unknown }).type === "string" ? String((o as { type?: string }).type) : null,
+      category:
+        typeof (o as { category?: unknown }).category === "string"
+          ? String((o as { category?: string }).category)
+          : null,
+      options: Array.isArray((o as { options?: unknown }).options)
+        ? ((o as unknown as { options: { value?: unknown; name?: unknown; description?: unknown }[] }).options ?? []).map(
+            (opt) => ({
+              value: String(opt.value ?? ""),
+              name: opt.name === undefined || opt.name === null ? null : String(opt.name),
+              description:
+                opt.description === undefined || opt.description === null ? null : String(opt.description),
+            }),
+          )
+        : null,
     })),
     models,
     commands: (s.availableCommands ?? []).map((c) => c.name),

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

@@ -36,6 +36,8 @@ import type {
   TurnTrace,
 } from "../../../shared/src/index.js";
 import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
+import { PLAN_GUIDANCE_ACTIVE, PLAN_GUIDANCE_INTRO, PLAN_GUIDANCE_NATIVE } from "../../../shared/src/index.js";
+import { PREFS_DEFAULT, type PlanHintSettings } from "../settings.js";
 
 // Permission prompts must not hang a session forever (design.md §8-4).
 // Env-tunable so QA can exercise the timeout path in seconds instead of minutes.
@@ -99,6 +101,11 @@ function boundedDiff(path: string, oldText: string, newText: string): Permission
   };
 }
 
+// The built-in wording for the plan hint's GUIDANCE half lives in `shared` (PLAN_GUIDANCE_*), not
+// here: the settings page has to SHOW an operator exactly what "leave the box empty" sends, and a
+// second prose copy on the web side is a copy that drifts. Read the doc comment there for which
+// variant covers which case.
+
 // A title fork is a real model turn over a copy of the conversation: give it room, but never
 // let a stuck one hang the operator's click — the caller falls back to the derived name on
 // timeout. Env-tunable so a sweep can exercise the timeout path in seconds.
@@ -108,6 +115,14 @@ const TITLE_FORK_TIMEOUT_MS = Number(process.env.AGENTUS_TITLE_TIMEOUT_MS || 90_
 // (an agent that ignores session/cancel must not hang the operator's next sentence forever).
 const TURN_SETTLE_TIMEOUT_MS = Number(process.env.AGENTUS_SETTLE_TIMEOUT_MS || 15_000);
 
+/** How long a close/archive waits for a slot's in-flight handshake before killing it anyway.
+ *
+ *  `#stop` waits because the agent-side session id only exists once the handshake lands, and a row
+ *  closed without it can never be resumed (see `#stop`). The wait is bounded so a spawn that never
+ *  answers cannot hold the operator's click open forever: past this, the slot closes with whatever it
+ *  has — a broken agent is not made worse by a row we cannot wake. */
+const CLOSE_STARTUP_WAIT_MS = Number(process.env.AGENTUS_CLOSE_WAIT_MS || 30_000);
+
 /** A cold slot the agent cannot adopt, and why — the only two answers there are.
  *
  *  Resuming has to *ask* the agent: `session/load` is "do you still have this session?", and the
@@ -159,6 +174,14 @@ interface LiveSession {
    *  so a second interrupting utterance that already started its own turn is not mistaken for
    *  "the one I cancelled is still running". */
   turnSeq: number;
+  /** The spawn-time handshake, while it is still running.
+   *
+   *  `create()` no longer waits for it (that wait is what made 「新建会话」 feel broken), so the slot
+   *  exists — and can be closed, archived or reaped — before the agent has answered. This handle is
+   *  how the teardown waits for the one thing only the handshake can tell us: the agent-side session
+   *  id. Killing the child before it arrives leaves a row with `acpSessionId: null` that `resume()`
+   *  refuses forever (「was never handed to an agent」) — see `#stop`. */
+  startup?: Promise<void>;
   /** When the operator last USED this slot — he opened it, or his page reported it as the one on
    *  screen. In memory on purpose: this is the half of the idle rule that says "he was just here",
    *  and the store's message clock (which survives restarts) is the other half. Reading only the
@@ -203,12 +226,22 @@ export class SessionManager {
   #sessions = new Map<string, LiveSession>();
   #store: Store;
   #emit: Emitter;
+  /** How the operator wants the plan-tool hint injected into a prompt — read on EVERY prompt, like
+   *  the idle thresholds, because the requirement is that a change in 设置 applies to the very next
+   *  turn with no restart and no session to hibernate. */
+  #planHint: () => PlanHintSettings = () => ({ ...PREFS_DEFAULT.planHint });
 
   constructor(store: Store, emit: Emitter) {
     this.#store = store;
     this.#emit = emit;
   }
 
+  /** Wire the cockpit's plan-hint setting in. Optional on purpose: with no source wired the
+   *  manager behaves exactly as it did before the setting existed (on, 仅首条). */
+  setPlanHintSource(read: () => PlanHintSettings): void {
+    this.#planHint = read;
+  }
+
   list(): SessionInfo[] {
     // Most recently CHATTED first — the cockpit's left rail is a launch pad, not a log file, and
     // creation order is the wrong key for that: the session you talked to a minute ago is the
@@ -417,6 +450,33 @@ export class SessionManager {
     });
     child.on("exit", (code, sig) => this.#onChildExit(live, code, sig));
 
+    // The row is complete and already persisted with `status: "starting"` — hand it back to the
+    // caller NOW and let the handshake finish OFF the request. See `#startup`.
+    // Kept on the slot (not dropped with `void`) so a close during the window can wait for the
+    // agent-side id instead of orphaning the session — see `#stop`.
+    live.startup = this.#startup(live, backend, spec, cwd, spawnStarted);
+    void live.startup.catch(() => {}); // `#startup` reports failure on the slot; nobody is awaiting
+    return live.info;
+  }
+
+  /** The spawn-time handshake — `initialize` + `newSession` + the row's default permission mode.
+   *
+   *  Deliberately NOT awaited by `create()`. Holding the HTTP response open for the whole handshake
+   *  is what made 「新建会话」 feel broken: hermes boots a python process and answers in 10–40 s, the
+   *  page sat on a busy dialog with no progress to show and a 120 s timeout behind it (measured; the
+   *  old `state.ts` comment said so in as many words). The row is born `starting` — the rail can
+   *  draw it, the page can open it and file the first message — and when this resolves,
+   *  `#updateSession` broadcasts `ready`, which is also the signal the client drains that queued
+   *  first message on (`state.ts`, `case "session"`).
+   *
+   *  Failure is reported INSIDE the session, never to a caller that has long since answered: the
+   *  status goes `error` with `lastError` (the reason + the agent's stderr tail, delivered while the
+   *  slot is still in the live map so the frame carries it), then the slot is dropped and the row is
+   *  closed. That is what makes 「启动失败 → 因为什么 → 再试一次」 possible at all. */
+  async #startup(live: LiveSession, backend: BackendId, spec: BackendSpec, cwd: string, spawnStarted: number): Promise<void> {
+    const id = live.info.id;
+    const child = live.child;
+    if (!child) return; // the slot was torn down between `create()` returning and this line
     try {
       const conn = new ClientSideConnection(
         () => ({
@@ -458,18 +518,19 @@ export class SessionManager {
       // this method — that is exactly what keeps a per-session pick from being silently undone.
       await this.#applyDefaultMode(live);
       this.#updateSession(live);
-      return live.info;
     } catch (err) {
       child.kill("SIGKILL");
       live.info.status = "error";
       live.info.lastError = errMessage(err) + stderrTail(live);
-      this.#sessions.delete(id); // failed handshake => don't keep zombie session rows
+      // Announce the failure WHILE the slot is still live: `{t:"session"}` is the only frame that
+      // carries `lastError`, and the page needs it to say why nothing came up.
+      this.#updateSession(live);
+      this.#sessions.delete(id); // failed handshake => don't keep a zombie slot
       this.#store.upsertSession({ ...sessionRow(live.info), closedAt: Date.now() });
       this.#noteBackendCheck(String(backend), {
         ok: false, error: live.info.lastError, errorCode: classifyError(err),
         latencyMs: Date.now() - spawnStarted,
       });
-      throw err instanceof Error ? err : new Error(String(err));
     }
   }
 
@@ -841,10 +902,24 @@ export class SessionManager {
     if (!blocks.length) throw new Error("empty prompt");
     // The plan hand-over, owed once per agent process (§7): a restarted agent never knew about the
     // plan, and nothing else on this wire would tell it (ACP has no server->agent state channel).
-    if (s.planReminderPending) {
+    //
+    // It carries a second thing the agent cannot learn on its own: that this session HAS a plan
+    // tool. Its own description says "prefer this over any todo tool", but a runtime that keeps MCP
+    // tools in a lazy-loaded catalog (Hermes) never shows that text to the model unless the model
+    // goes looking — so the plan card stayed empty while the agent kept a todo list only its own
+    // process could see. The nudge therefore has to come from the wire; Studio does the same
+    // (its `task-plan-runs.ts` appends a template to the latest input every turn).
+    //
+    // Read per prompt, and only CONSUME the hand-over when it is actually injected: an operator who
+    // turns the hint off and later back on gets the plan hand-over then, rather than losing it.
+    const hint = this.#planHint();
+    if (hint.on) {
+      const owed = Boolean(s.planReminderPending);
       s.planReminderPending = false;
-      const reminder = this.#planReminder(s);
-      if (reminder) blocks.push(reminder);
+      if (owed || hint.everyTurn) {
+        const reminder = this.#planReminder(s);
+        if (reminder) blocks.push(reminder);
+      }
     }
     s.turnSeq += 1;
     s.busy = true;
@@ -1181,46 +1256,68 @@ export class SessionManager {
   /** The plan, handed to an agent that just (re)started, as an ACP `resource` content block: a
    *  stable URI plus the steps still owed. The card is fed by the plan OBJECT, but the AGENT's own
    *  copy died with its process — this block is the only thing that tells it the plan exists
-   *  (design-plan-service.md §7). Returns null when there is nothing to hand over: no plan at all,
-   *  or one whose steps are all closed (spending context to say "you are done" is worse than
-   *  saying nothing). */
+   *  (design-plan-service.md §7).
+   *
+   *  It is also the only thing that tells an agent the tool exists AT ALL — `update_plan`'s own
+   *  description says "prefer this over any todo tool", but a runtime that keeps MCP tools in a
+   *  lazy-loaded catalog (Hermes) never shows the model that text unless it goes looking first.
+   *  Everything here goes out on the wire, every turn when 每回合 is on, exactly like Studio's
+   *  `task-plan-runs.ts` (which appends its block to the latest input unconditionally).
+   *
+   *  The ONE case that says nothing: a plan that exists with every step closed. There is no
+   *  introduction worth repeating and no work to hand over — "you are done" costs context and buys
+   *  nothing. Note that "no plan yet" is NOT that case: it is the moment the nudge matters most,
+   *  because an agent that has not been told the tool exists will reach for its own todo list. */
   #planReminder(s: LiveSession): unknown | null {
+    // The operator's own wording, when they wrote one (设置 → 计划提示注入). Read per call, like the
+    // switches beside it, so an edit lands on the next turn with no restart. Emptiness is decided
+    // HERE rather than only at save time: a value written by an older build (or hand-edited into
+    // the DB) must not be able to inject a line of whitespace as if it were guidance.
+    const custom = this.#planHint().instruction.trim() || null;
     const plan = this.#store.getPlan(s.info.id);
-    if (!plan) return null;
-    const open = plan.items.filter((i) => i.status !== "completed" && i.status !== "cancelled");
-    if (!open.length) return null;
-    const lines = open.map((i) => `- [${i.status}] ${i.content}`).join("\n");
+    const open = plan
+      ? plan.items.filter((i) => i.status !== "completed" && i.status !== "cancelled")
+      : [];
+    if (plan && !open.length) return null;
+
     // How the agent keeps it current depends on which channel it actually has: an agent whose row
     // opted into native frames must use its own todo tool (those frames are what feed the card),
     // while an MCP-driven agent — which is every backend by default, Hermes included — was handed
     // `update_plan` in this very handshake, and its own todo tool does NOT reach the card.
     const mcpDriven = nativePlanSourceOf(this.#specFor(s.info.backend)) === "none";
-    const closing = mcpDriven
-      ? [
-          "Carry on with it, and keep it updated with the `update_plan` tool as you go — that list is",
-          "the ONLY one the cockpit shows the operator, so a built-in todo/checklist tool of yours will",
-          "not be seen there. Mark a step completed once its work is actually verified, and drop or",
-          "cancel what you are no longer doing. If you disagree with an item, change it rather than",
-          "quietly skipping it.",
-        ]
-      : [
-          "Carry on with it, and keep it updated with your own plan/todo tool as you go: mark a step",
-          "completed only once its work is actually verified, and drop or cancel what you are no",
-          "longer doing. If you disagree with an item, change it rather than quietly skipping it.",
-        ];
+    const body: string[] = [];
+
+    if (open.length) {
+      body.push(
+        "This session has an unfinished plan. It is kept by the cockpit and survives your",
+        "restarts; your own in-memory task list does not.",
+        "",
+        ...open.map((i) => `- [${i.status}] ${i.content}`),
+        "",
+      );
+    }
+
+    if (mcpDriven && open.length) {
+      body.push(custom ?? PLAN_GUIDANCE_ACTIVE);
+    } else if (mcpDriven) {
+      // No plan yet. This is the case the cockpit used to say NOTHING about — which is exactly why
+      // an agent reached for its own todo list and the card stayed empty: `update_plan`'s own
+      // description ("prefer this over any todo tool") lives on a tool a lazy-loaded MCP catalog
+      // never puts in front of the model. Keep it short; it rides on every first prompt.
+      body.push(custom ?? PLAN_GUIDANCE_INTRO);
+    } else if (open.length) {
+      body.push(custom ?? PLAN_GUIDANCE_NATIVE);
+    } else {
+      // A native-frames backend with nothing to hand over: nothing worth saying.
+      return null;
+    }
+
     return {
       type: "resource",
       resource: {
         uri: `agentus://plan/${s.info.id}`,
         mimeType: "text/plain",
-        text: [
-          "This session has an unfinished plan. It is kept by the cockpit and survives your",
-          "restarts; your own in-memory task list does not.",
-          "",
-          lines,
-          "",
-          ...closing,
-        ].join("\n"),
+        text: body.join("\n"),
       },
       // ACP reserves `_meta` for the client: tagging our own blocks is what lets us tell them from
       // the operator's words later (and strip them from anything we echo back).
@@ -1230,7 +1327,10 @@ export class SessionManager {
 
   async closeSession(sessionId: string): Promise<void> {
     const s = this.#need(sessionId);
-    this.#stop(s, "closed");
+    // Awaited, not fired and forgotten: the row has to be settled (and carry the agent-side id) by the
+    // time the DELETE that asked for this answers, or the page loads a slot the store still calls
+    // `starting`.
+    await this.#stop(s, "closed");
     this.#emitSessions();
   }
 
@@ -1245,7 +1345,7 @@ export class SessionManager {
     const live = this.#sessions.get(id);
     const row = this.#store.getSession(id);
     if (!row) throw new Error(`no such session: ${id}`);
-    if (on && live) this.#stop(live, "archived");
+    if (on && live) await this.#stop(live, "archived");
     this.#store.setArchived(id, on ? Date.now() : null);
     this.#emitSessions();
     return this.#sessions.get(id)?.info ?? this.#coldInfo(id);
@@ -1257,11 +1357,30 @@ export class SessionManager {
    *  `reaped` is its own status on purpose — 「它怎么变冷了」 has three different answers (I closed
    *  it / it crashed / the cockpit reclaimed it for being idle) and a rail that shows one word for
    *  all three teaches the operator to distrust the column. */
-  #stop(live: LiveSession, why: "closed" | "archived" | "reaped"): void {
+  async #stop(live: LiveSession, why: "closed" | "archived" | "reaped"): Promise<void> {
     this.#dropPending(live);
-    live.child?.kill("SIGTERM");
-    live.info.status = why === "reaped" ? "reaped" : "closed";
+    // A slot can be closed while its handshake is still in flight — `create()` no longer waits for it
+    // (see there). Killing the child on the spot was WRONG in a way the operator would eventually hit:
+    // the agent had already created a session, but the row was written with `acpSessionId: null`, and
+    // `resume()` refuses such a row outright (「was never handed to an agent」) — the slot became a
+    // transcript nobody could ever wake again. So let the startup land first: it is the only thing that
+    // knows the agent-side id, and the child it spawned is the one really there to kill.
+    //
+    // The slot stays in the live map for the duration, on purpose: the child IS alive and about to be
+    // `ready`, and calling it cold while it boots is the mirror-image lie (a cold row that wakes up by
+    // itself). The wait is bounded — see `CLOSE_STARTUP_WAIT_MS`.
+    if (live.startup && live.info.status === "starting") {
+      await Promise.race([
+        live.startup.catch(() => {}),
+        new Promise<void>((r) => { setTimeout(r, CLOSE_STARTUP_WAIT_MS).unref?.(); }),
+      ]);
+    }
+    // Applied LAST, and only over a non-terminal status: `#startup` writes `ready` when the handshake
+    // lands and `error` (with `lastError`) when it fails — and a handshake that failed on its own has a
+    // better answer than 「closed」, so it keeps it.
+    if (live.info.status !== "error") live.info.status = why === "reaped" ? "reaped" : "closed";
     live.info.pid = null;
+    live.child?.kill("SIGTERM");
     const row = this.#store.getSession(live.info.id);
     if (row) {
       this.#store.upsertSession({
@@ -1382,7 +1501,9 @@ export class SessionManager {
             `[agentus] idle reap: ${s.info.id} (${Math.round(age / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
           );
         }
-        this.#stop(s, "reaped");
+        // Fire and forget: the reaper skips `starting` slots, so there is no in-flight handshake to
+        // wait for here and nothing downstream needs the row settled in this tick.
+        void this.#stop(s, "reaped");
         reaped += 1;
       }
       // Only speak when something changed: a frame every tick would be noise on the socket (and on

package/packages/server/src/index.ts

@@ -19,7 +19,7 @@ import { terms } from "./term.js";
 import { VoiceError, listVoiceModels, setHotwordSource, synthesize, transcribe, voiceCapabilities } from "./voice.js";
 import { hotwordsFor, vocabularyOf } from "./hotwords.js";
 import { openDashscopeStream } from "./dashscope.js";
-import { agentSettings, initSettings, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
+import { agentSettings, initSettings, planHintSettings, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
 import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
 import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent } from "../../shared/src/index.js";
@@ -298,6 +298,9 @@ setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word)
       envWarmTtlMs != null ? envWarmTtlMs / 3_600_000 : agentSettings().warmTtlHours
     } h untouched (${envWarm != null || envWarmTtlMs != null ? "AGENTUS_WARM_*" : "settings.agent"}), 0 = off / never`,
   );
+  // The plan-tool hint: read per prompt, so the 设置 switch applies to the next turn with nothing
+  // to restart (the session's own plan card is what it fills).
+  mgr.setPlanHintSource(planHintSettings);
   mgr.startIdleReaper({
     idleMs: () => envIdleMs ?? agentSettings().idleKillMin * 60_000,
     warmSlots: () => envWarm ?? agentSettings().warmSlots,

package/packages/server/src/settings.ts

@@ -102,10 +102,43 @@ export interface PrefsSettings {
   serverTts: boolean;
   /** which recogniser to use, when the caller does not force one */
   stt: "auto" | "browser" | "stream" | "server";
+  /** Whether — and how often — the cockpit tells the agent about the plan MCP it was handed.
+   *  The tool's own description says "prefer this over any todo tool", but on a runtime that
+   *  keeps MCP tools in a lazy-loaded catalog the agent never reads it unless it goes looking,
+   *  so the session's plan card stays empty while the agent keeps a todo list nobody can see.
+   *  A per-turn nudge in the prompt is what closes that last mile; this is its switch. */
+  planHint: PlanHintSettings;
+}
+
+/** Longest operator-authored plan instruction we store and inject. Sized for a few sentences of
+ *  house rules, not a document — the block rides on the end of the operator's message every turn,
+ *  so its cost is paid per turn, not once. */
+export const PLAN_HINT_INSTRUCTION_MAX = 2000;
+
+export interface PlanHintSettings {
+  /** Inject the plan-tool hint at all. Off = the prompt carries the operator's words and
+   *  nothing else (some operators do not want anything appended to their message). */
+  on: boolean;
+  /** true = every turn (the agent is re-told as the plan moves); false = only the first prompt
+   *  of each agent process. Default true: this mirrors Studio, which appends its block to the
+   *  latest input on EVERY turn (services/task-plan-runs.ts) — the per-turn re-statement is the
+   *  part that makes an agent actually keep the card current, and an agent process can be
+   *  long-lived enough that "first prompt only" means "once this morning". */
+  everyTurn: boolean;
+  /** The operator's own wording for the appended instruction. Empty = the built-in text (which
+   *  names the tool, says why it beats a native todo, and how to find it when the runtime defers
+   *  MCP tools). This replaces only the GUIDANCE half — the per-turn plan STATUS (which steps are
+   *  still open) is generated from the card and stays authoritative, so an edit here can never
+   *  make the prompt disagree with what the operator sees. */
+  instruction: string;
 }
 
 export const PREFS_DEFAULT: PrefsSettings = {
   autoRead: false, 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.
+  planHint: { on: true, everyTurn: true, instruction: "" },
 };
 
 export const CALL_DEFAULT: CallSettings = {
@@ -332,6 +365,15 @@ function pickPrefs(raw: unknown): PrefsSettings {
     const rate = Number(r.rate);
     if (Number.isFinite(rate) && rate >= 0.5 && rate <= 2) out.rate = rate;
     if (r.stt === "auto" || r.stt === "browser" || r.stt === "stream" || r.stt === "server") out.stt = r.stt;
+    const h = r.planHint;
+    if (h && typeof h === "object") {
+      const hr = h as Record<string, unknown>;
+      if (typeof hr.on === "boolean") out.planHint.on = hr.on;
+      if (typeof hr.everyTurn === "boolean") out.planHint.everyTurn = hr.everyTurn;
+      if (typeof hr.instruction === "string" && hr.instruction.length <= PLAN_HINT_INSTRUCTION_MAX) {
+        out.planHint.instruction = hr.instruction;
+      }
+    }
   }
   return out;
 }
@@ -512,6 +554,30 @@ 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"];
   }
+  if ("planHint" in patch) {
+    const h = patch.planHint;
+    if (!h || typeof h !== "object") throw new Error("invalid planHint: expected an object");
+    const hr = h as Record<string, unknown>;
+    const nextHint = { ...next.planHint };
+    if ("on" in hr) {
+      if (typeof hr.on !== "boolean") throw new Error("invalid planHint.on: expected true/false");
+      nextHint.on = hr.on;
+    }
+    if ("everyTurn" in hr) {
+      if (typeof hr.everyTurn !== "boolean") throw new Error("invalid planHint.everyTurn: expected true/false");
+      nextHint.everyTurn = hr.everyTurn;
+    }
+    if ("instruction" in hr) {
+      if (typeof hr.instruction !== "string") throw new Error("invalid planHint.instruction: expected a string");
+      // Trimmed on the way in: whitespace-only means "use the built-in text", and storing it as the
+      // empty string keeps that one case one case.
+      if (hr.instruction.length > PLAN_HINT_INSTRUCTION_MAX) {
+        throw new Error(`invalid planHint.instruction: longer than ${PLAN_HINT_INSTRUCTION_MAX} characters`);
+      }
+      nextHint.instruction = hr.instruction.trim() ? hr.instruction : "";
+    }
+    next.planHint = nextHint;
+  }
   cache = { ...cache, prefs: next, updatedAt: Date.now() };
   persist();
   return cache;
@@ -547,6 +613,12 @@ export function agentSettings(): AgentSettings {
   return cache.agent;
 }
 
+/** 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 {
+  return cache.prefs.planHint;
+}
+
 /** Normalise the two URL shapes operators paste: MaaS root or .../compatible-mode/v1. */
 export function dashscopeUrls(baseUrl: string): { root: string; compat: string; ws: string } {
   const trimmed = baseUrl.replace(/\/+$/, "");

package/packages/shared/src/index.ts

@@ -273,6 +273,62 @@ export interface PlanSnapshot {
   updatedAt: number;
 }
 
+// ---- the built-in plan-hint wording ----
+//
+// It lives in `shared` because TWO sides need the same bytes: the server injects it
+// (`session-manager.ts#planReminder`) and the settings page has to be able to SHOW the operator
+// what "leave the box empty" actually sends. Keeping a prose copy on the web side would drift,
+// and a settings screen that paraphrases the thing it configures is a control that lies.
+//
+// Three variants, because what is worth saying depends on the channel the agent really has:
+//
+//  - `INTRO` — no plan on the session yet. The moment the nudge matters most: an agent that has
+//    not been told `update_plan` exists will reach for its own todo tool, which never reaches the
+//    cockpit's card. Explicitly teaches the deferred-tool lookup, because the tool's own
+//    description ("prefer this over any todo tool") is invisible until the model finds it.
+//  - `ACTIVE` — a plan exists with steps still open, on an MCP-driven backend.
+//  - `NATIVE` — a backend whose row opted into native plan frames: those frames are what feed the
+//    card, so its own todo tool IS the right instrument and `update_plan` is not mentioned.
+//
+// The per-turn plan STATUS (which steps are still open) is NOT part of these strings — the server
+// generates it from the card on every call, so an operator editing the hint text cannot make the
+// prompt disagree with what the cockpit displays.
+
+/** Injected when the session has no plan yet and the backend is MCP-driven. */
+export const PLAN_GUIDANCE_INTRO = [
+  "This session has an `update_plan` tool mounted on it (MCP server `agentus_plan`), and the",
+  "plan it holds is the one the operator sees — a todo list of your own is invisible there and",
+  "dies with your process. For anything with more than one step, publish the steps with",
+  "`update_plan` and update it as you go: mark a step completed only once its work is actually",
+  "verified, and drop or cancel what you are no longer doing. If `update_plan` is not in your",
+  "tool list it is deferred — search for `agentus_plan update_plan` to find it, then call it by",
+  "that exact name. A one-step request needs no plan.",
+].join("\n");
+
+/** Injected when the session HAS an open plan and the backend is MCP-driven. */
+export const PLAN_GUIDANCE_ACTIVE = [
+  "Carry on with it, and keep it updated with the `update_plan` tool as you go — that list is",
+  "the ONLY one the cockpit shows the operator, so a built-in todo/checklist tool of yours will",
+  "not be seen there. Mark a step completed once its work is actually verified, and drop or",
+  "cancel what you are no longer doing. If you disagree with an item, change it rather than",
+  "quietly skipping it.",
+].join("\n");
+
+/** Injected when the backend's row feeds the card from its OWN native plan frames. */
+export const PLAN_GUIDANCE_NATIVE = [
+  "Carry on with it, and keep it updated with your own plan/todo tool as you go: mark a step",
+  "completed only once its work is actually verified, and drop or cancel what you are no",
+  "longer doing. If you disagree with an item, change it rather than quietly skipping it.",
+].join("\n");
+
+/** The three built-ins with the case each one covers — so a surface can list them without
+ *  inventing its own labels (and without a second copy of the prose). */
+export const PLAN_GUIDANCE_VARIANTS: ReadonlyArray<{ id: string; when: string; text: string }> = [
+  { id: "intro", when: "该会话还没有计划（最要紧的一刻：不告诉它，它就会用自己的 todo）", text: PLAN_GUIDANCE_INTRO },
+  { id: "active", when: "已有未完成的计划，且 agent 是 MCP 驱动", text: PLAN_GUIDANCE_ACTIVE },
+  { id: "native", when: "该后端的计划卡由它自己的原生计划帧喂（不用 update_plan）", text: PLAN_GUIDANCE_NATIVE },
+];
+
 // ---- WS envelope (browser -> server) ----
 /** Media the operator attaches to a prompt. Images ride ACP as base64 blocks (that
  *  is the wire shape the protocol defines), text files are inlined as text with a