agentus 0.3.5 → 0.3.6

package/package.json

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

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

@@ -36,7 +36,8 @@ import type {
   TurnTrace,
 } from "../../../shared/src/index.js";
 import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
-import type { PlanHintSettings } from "../settings.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.
@@ -100,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.
@@ -223,7 +229,7 @@ export class SessionManager {
   /** 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 = () => ({ on: true, everyTurn: false });
+  #planHint: () => PlanHintSettings = () => ({ ...PREFS_DEFAULT.planHint });
 
   constructor(store: Store, emit: Emitter) {
     this.#store = store;
@@ -911,7 +917,7 @@ export class SessionManager {
       const owed = Boolean(s.planReminderPending);
       s.planReminderPending = false;
       if (owed || hint.everyTurn) {
-        const reminder = this.#planReminder(s, !owed);
+        const reminder = this.#planReminder(s);
         if (reminder) blocks.push(reminder);
       }
     }
@@ -1252,19 +1258,27 @@ export class SessionManager {
    *  copy died with its process — this block is the only thing that tells it the plan exists
    *  (design-plan-service.md §7).
    *
-   *  `perTurn` = this is a mid-conversation nudge (the 每回合 setting), not the once-per-process
-   *  hand-over. It changes only what is worth SAYING: with no plan on the card there is nothing to
-   *  hand over and repeating the introduction every turn would be the noise the operator asked to
-   *  avoid, so a per-turn call with nothing to show returns null. Returns null too when a plan
-   *  exists but every step is closed — spending context to say "you are done" is worse than saying
-   *  nothing. */
-  #planReminder(s: LiveSession, perTurn = false): unknown | null {
+   *  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);
     const open = plan
       ? plan.items.filter((i) => i.status !== "completed" && i.status !== "cancelled")
       : [];
     if (plan && !open.length) return null;
-    if (!open.length && perTurn) 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),
@@ -1284,33 +1298,15 @@ export class SessionManager {
     }
 
     if (mcpDriven && open.length) {
-      body.push(
-        "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.",
-      );
+      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(
-        "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.",
-      );
+      body.push(custom ?? PLAN_GUIDANCE_INTRO);
     } else if (open.length) {
-      body.push(
-        "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.",
-      );
+      body.push(custom ?? PLAN_GUIDANCE_NATIVE);
     } else {
       // A native-frames backend with nothing to hand over: nothing worth saying.
       return null;

package/packages/server/src/settings.ts

@@ -110,21 +110,35 @@ export interface PrefsSettings {
   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 (a fresh process has no memory of the plan; a running one maintains
-   *  it itself, and re-sending it every turn costs context and invites re-deriving finished work). */
+   *  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 by default: the feature exists because the tool was there and nobody used it. 仅首条 is
-  // the conservative default — it is also what the cockpit did before this was configurable.
-  planHint: { on: true, everyTurn: false },
+  // 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 = {
@@ -356,6 +370,9 @@ function pickPrefs(raw: unknown): PrefsSettings {
       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;
@@ -550,6 +567,15 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
       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() };

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