@yeaft/webchat-agent 0.1.762 → 0.1.766

package/unify/stats/tool-usage.js

@@ -0,0 +1,324 @@
+/**
+ * tool-usage.js — ToolUsageStats: per-tool call/error/latency counters
+ * with throttled persistence to ~/.yeaft/stats/tool-usage.json.
+ *
+ * Purpose: answer "which tools are defined but never called?" and
+ * "which tools dominate latency / error rate?" without dragging a
+ * full APM stack in. The engine emits `tool_exec` events containing
+ * `{name, durationMs, isError}` after every tool call — `record()` is
+ * the hook point.
+ *
+ * Storage shape (JSON file):
+ * ```
+ * {
+ *   schema: 1,
+ *   tools: {
+ *     "<name>": {
+ *       callCount: number,
+ *       errorCount: number,
+ *       totalDurationMs: number,
+ *       durations: number[],   // ring of last N durations for p50/p95
+ *       lastCalledAt: ISO8601 string,
+ *       lastError: string | null
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Persistence policy: write to a `.tmp` sibling then `rename()` so we
+ * never leave a half-written JSON on disk. Throttled — flush after
+ * every `flushEveryNRecords` records OR if `flushIntervalMs` has
+ * passed since the last write, whichever comes first. `flush()` is
+ * exposed for shutdown paths.
+ *
+ * Latency math: p50/p95 from a sorted copy of the durations ring.
+ * Small samples (< 100 per tool) are good enough for a "noticed this
+ * tool is slow" signal — not a billing-grade SLO.
+ */
+
+import { promises as fsp, existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const DEFAULT_RING_SIZE = 100;
+const DEFAULT_FLUSH_EVERY_N = 20;
+const DEFAULT_FLUSH_INTERVAL_MS = 30_000;
+const SCHEMA_VERSION = 1;
+
+function defaultStatsPath() {
+  return join(homedir(), '.yeaft', 'stats', 'tool-usage.json');
+}
+
+function emptyToolRecord() {
+  return {
+    callCount: 0,
+    errorCount: 0,
+    totalDurationMs: 0,
+    durations: [],
+    lastCalledAt: null,
+    lastError: null,
+  };
+}
+
+function percentile(sortedAsc, p) {
+  if (!Array.isArray(sortedAsc) || sortedAsc.length === 0) return 0;
+  const idx = Math.min(
+    sortedAsc.length - 1,
+    Math.max(0, Math.floor((p / 100) * sortedAsc.length))
+  );
+  return sortedAsc[idx];
+}
+
+export class ToolUsageStats {
+  /** @type {string} */
+  #path;
+  /** @type {Record<string, ReturnType<typeof emptyToolRecord>>} */
+  #tools;
+  /** @type {number} */
+  #ringSize;
+  /** @type {number} */
+  #flushEveryN;
+  /** @type {number} */
+  #flushIntervalMs;
+  /** @type {number} */
+  #recordsSinceFlush;
+  /** @type {number} */
+  #lastFlushAt;
+  /** @type {Promise<void> | null} */
+  #flushInFlight;
+
+  constructor({
+    path = defaultStatsPath(),
+    ringSize = DEFAULT_RING_SIZE,
+    flushEveryN = DEFAULT_FLUSH_EVERY_N,
+    flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS,
+  } = {}) {
+    this.#path = path;
+    this.#tools = Object.create(null);
+    this.#ringSize = ringSize;
+    this.#flushEveryN = flushEveryN;
+    this.#flushIntervalMs = flushIntervalMs;
+    this.#recordsSinceFlush = 0;
+    this.#lastFlushAt = 0;
+    this.#flushInFlight = null;
+  }
+
+  /**
+   * Synchronous load — best-effort. If the file doesn't exist or is
+   * corrupt, start fresh. Caller decides when to call this (usually
+   * once at session boot).
+   */
+  loadSync() {
+    try {
+      if (!existsSync(this.#path)) return;
+      const raw = readFileSync(this.#path, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && parsed.tools && typeof parsed.tools === 'object') {
+        for (const [name, rec] of Object.entries(parsed.tools)) {
+          if (!rec || typeof rec !== 'object') continue;
+          this.#tools[name] = {
+            callCount: Number(rec.callCount) || 0,
+            errorCount: Number(rec.errorCount) || 0,
+            totalDurationMs: Number(rec.totalDurationMs) || 0,
+            durations: Array.isArray(rec.durations) ? rec.durations.slice(-this.#ringSize) : [],
+            lastCalledAt: typeof rec.lastCalledAt === 'string' ? rec.lastCalledAt : null,
+            lastError: typeof rec.lastError === 'string' ? rec.lastError : null,
+          };
+        }
+      }
+    } catch {
+      // Best-effort: a corrupt file shouldn't crash the agent. Start fresh.
+    }
+  }
+
+  /**
+   * Async load — alternative to loadSync for code paths that prefer
+   * async I/O. Same best-effort semantics.
+   */
+  async load() {
+    try {
+      if (!existsSync(this.#path)) return;
+      const raw = await fsp.readFile(this.#path, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && parsed.tools && typeof parsed.tools === 'object') {
+        for (const [name, rec] of Object.entries(parsed.tools)) {
+          if (!rec || typeof rec !== 'object') continue;
+          this.#tools[name] = {
+            callCount: Number(rec.callCount) || 0,
+            errorCount: Number(rec.errorCount) || 0,
+            totalDurationMs: Number(rec.totalDurationMs) || 0,
+            durations: Array.isArray(rec.durations) ? rec.durations.slice(-this.#ringSize) : [],
+            lastCalledAt: typeof rec.lastCalledAt === 'string' ? rec.lastCalledAt : null,
+            lastError: typeof rec.lastError === 'string' ? rec.lastError : null,
+          };
+        }
+      }
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  /**
+   * Record a single tool execution. Updates in-memory counters and
+   * may trigger a throttled persist.
+   *
+   * @param {{ name: string, durationMs?: number, isError?: boolean, errorMessage?: string }} args
+   */
+  record({ name, durationMs = 0, isError = false, errorMessage = null } = {}) {
+    if (typeof name !== 'string' || !name) return;
+    const dur = Math.max(0, Number(durationMs) || 0);
+    let rec = this.#tools[name];
+    if (!rec) {
+      rec = emptyToolRecord();
+      this.#tools[name] = rec;
+    }
+    rec.callCount += 1;
+    rec.totalDurationMs += dur;
+    rec.durations.push(dur);
+    if (rec.durations.length > this.#ringSize) {
+      rec.durations.splice(0, rec.durations.length - this.#ringSize);
+    }
+    rec.lastCalledAt = new Date().toISOString();
+    if (isError) {
+      rec.errorCount += 1;
+      if (typeof errorMessage === 'string' && errorMessage) {
+        rec.lastError = errorMessage.slice(0, 500);
+      }
+    }
+    this.#recordsSinceFlush += 1;
+    this.#maybeFlush();
+  }
+
+  #maybeFlush() {
+    const now = Date.now();
+    const stale = now - this.#lastFlushAt >= this.#flushIntervalMs;
+    const overflow = this.#recordsSinceFlush >= this.#flushEveryN;
+    if (!stale && !overflow) return;
+    // If a write is already in flight, skip — the in-memory state is
+    // ahead of disk, but #recordsSinceFlush will trigger the next overflow.
+    if (this.#flushInFlight) return;
+    this.#startFlush();
+  }
+
+  /**
+   * Persist current state. Writes atomically via .tmp + rename.
+   *
+   * Coalesces with any in-flight throttled flush — first awaits it (the
+   * in-flight write captured a *snapshot* taken before this call, so it
+   * may not include the latest record), then schedules a fresh singleton
+   * flush so the on-disk state matches the in-memory state at the moment
+   * this method resolves. `#flushInFlight` is the only path that ever
+   * opens a writer on `${path}.tmp`, so two writers never race.
+   */
+  async flush() {
+    if (this.#flushInFlight) {
+      try { await this.#flushInFlight; } catch { /* swallow */ }
+    }
+    this.#startFlush();
+    try { await this.#flushInFlight; } catch { /* swallow */ }
+  }
+
+  #startFlush() {
+    this.#flushInFlight = this.#doFlush().catch(() => {
+      // Persisted-write failures are non-fatal: in-memory state is the
+      // source of truth for the current session.
+    }).finally(() => {
+      this.#flushInFlight = null;
+    });
+  }
+
+  async #doFlush() {
+    const payload = {
+      schema: SCHEMA_VERSION,
+      writtenAt: new Date().toISOString(),
+      tools: this.#tools,
+    };
+    const json = JSON.stringify(payload, null, 2);
+    // Capture the records-since-flush count at write-start. Any records
+    // that land during the async write must still count toward the next
+    // overflow trigger, so we subtract only what we actually persisted —
+    // not whatever value `#recordsSinceFlush` happens to be when rename
+    // returns.
+    const flushedCount = this.#recordsSinceFlush;
+    const dir = dirname(this.#path);
+    try {
+      await fsp.mkdir(dir, { recursive: true });
+    } catch {
+      // mkdir failure (perm denied, etc.) — abort silently.
+      return;
+    }
+    const tmpPath = `${this.#path}.tmp`;
+    try {
+      await fsp.writeFile(tmpPath, json, 'utf8');
+      await fsp.rename(tmpPath, this.#path);
+      this.#lastFlushAt = Date.now();
+      this.#recordsSinceFlush = Math.max(0, this.#recordsSinceFlush - flushedCount);
+    } catch {
+      // Try to clean the tmp file if it dangling.
+      try { await fsp.unlink(tmpPath); } catch { /* swallow */ }
+    }
+  }
+
+  /**
+   * Snapshot for CLI/UI rendering. Computes p50/p95/avg/errorRate per
+   * tool from the in-memory rings.
+   *
+   * @returns {Record<string, {callCount: number, errorCount: number, errorRate: number, avgMs: number, p50Ms: number, p95Ms: number, lastCalledAt: string|null, lastError: string|null}>}
+   */
+  snapshot() {
+    /** @type {Record<string, any>} */
+    const out = Object.create(null);
+    for (const [name, rec] of Object.entries(this.#tools)) {
+      const sorted = rec.durations.slice().sort((a, b) => a - b);
+      const avg = rec.callCount > 0 ? rec.totalDurationMs / rec.callCount : 0;
+      out[name] = {
+        callCount: rec.callCount,
+        errorCount: rec.errorCount,
+        errorRate: rec.callCount > 0 ? rec.errorCount / rec.callCount : 0,
+        avgMs: Math.round(avg),
+        p50Ms: Math.round(percentile(sorted, 50)),
+        p95Ms: Math.round(percentile(sorted, 95)),
+        lastCalledAt: rec.lastCalledAt,
+        lastError: rec.lastError,
+      };
+    }
+    return out;
+  }
+
+  /**
+   * From a list of registered tool names, return the ones that have
+   * NEVER been recorded (call count == 0 or absent). Useful for the
+   * `yeaft-stats --unused` CLI mode — surfaces dead/defined-but-unused
+   * tools.
+   *
+   * @param {string[]} registeredNames
+   * @returns {string[]}
+   */
+  getRegisteredButUncalled(registeredNames) {
+    if (!Array.isArray(registeredNames)) return [];
+    const out = [];
+    for (const name of registeredNames) {
+      const rec = this.#tools[name];
+      if (!rec || rec.callCount === 0) out.push(name);
+    }
+    return out.sort();
+  }
+
+  /** Path used for persistence — for tests / CLI display. */
+  get path() {
+    return this.#path;
+  }
+
+  /**
+   * Reset everything — clears in-memory counters and removes the file.
+   * Used by the `yeaft-stats --reset` CLI mode.
+   */
+  async reset() {
+    this.#tools = Object.create(null);
+    this.#recordsSinceFlush = 0;
+    this.#lastFlushAt = 0;
+    try { await fsp.unlink(this.#path); } catch { /* swallow */ }
+  }
+}
+
+export default ToolUsageStats;

package/unify/sub-agent/runner.js

@@ -181,25 +181,10 @@ export function startSubAgent(agent, deps = {}) {
  */
 async function driveSubAgent(agent, subEngine, vpPersona, deps) {
   const onEvent = typeof deps.onEvent === 'function' ? deps.onEvent : null;
-  // PR-4: lazy parent-feature lookup. The parent's web-bridge installs
-  // an accessor on its engine right after creating the per-turn arc;
-  // that accessor flows here as `deps.getCurrentFeatureId`. We read it
-  // at every emit (NOT once at spawn-time) so a feature that opens AFTER
-  // the sub-agent starts still tags later events. Returns null when the
-  // parent is not in a feature run, in which case we leave `featureId`
-  // unset on the forwarded event (NOT explicitly null) so the frontend
-  // sub-agent card renders in its anchor-based fallback position.
-  const getParentFeatureId = (typeof deps.getCurrentFeatureId === 'function')
-    ? deps.getCurrentFeatureId
-    : null;
-  const wrapEvt = (evt) => {
-    const base = { ...evt, agentId: agent.id, agentName: agent.name };
-    if (!getParentFeatureId) return base;
-    let fid = null;
-    try { fid = getParentFeatureId(); } catch { fid = null; }
-    if (fid && !base.featureId) base.featureId = fid;
-    return base;
-  };
+  // Sub-agent events are forwarded with agentId/agentName stamped on top of
+  // the raw engine event. (PR-4 parent-feature inheritance was removed
+  // 2026-05-13 along with the rest of the Feature system.)
+  const wrapEvt = (evt) => ({ ...evt, agentId: agent.id, agentName: agent.name });
 
   // Helper: append a user message and either start or resume.
   const dequeueNextUserPrompt = () => {

package/unify/templates/plan-instruction.md

@@ -0,0 +1,42 @@
+# Planning Mode
+
+You have just entered **planning mode** for the topic below. Do NOT start
+executing yet. Your job in this turn is to **think through the work and produce
+a concrete plan**, then hand it off to `TodoWrite` so the steps are tracked.
+
+## How to think
+
+1. **Restate the problem in one sentence** — what success looks like, in plain
+   language. Verify your understanding matches what the user actually asked.
+2. **Surface the real constraints**: what's fixed (deadlines, dependencies,
+   APIs), what's flexible, where you'd push back if the requirement is wrong.
+3. **Identify the unknowns**: list the 2–3 things you can't decide without
+   more information. If any unknown blocks the whole plan, call it out — the
+   first step should be to resolve it.
+4. **Choose an approach**, briefly compared against one alternative. Don't
+   over-engineer: pick the simplest thing that handles the stated scope.
+5. **Break it into 3–7 ordered steps**. Each step should be ≤ 1 unit of work
+   that you (or another VP) can actually do and verify.
+
+## Output shape
+
+Reply in two parts:
+
+**Part 1 — Plan (prose, short).** 5–10 lines covering the problem, the chosen
+approach, and the key risks. No filler. Skip if the topic is trivial.
+
+**Part 2 — Call `TodoWrite`.** Convert the ordered steps into a `todos[]`
+array. Status rule:
+- The first concrete step → `status: "in_progress"`.
+- All remaining steps → `status: "pending"`.
+- Use the **imperative** form for `content` ("Write failing test"), and the
+  **present-continuous** form for `activeForm` ("Writing failing test").
+
+**Do not execute the steps in this turn.** This turn ends after the `TodoWrite`
+call returns. On the next turn, the user (or you) will pick up the
+`in_progress` item and start work.
+
+## Tone
+
+Be honest about what you don't know. A 4-step plan that admits one unknown is
+worth more than a 12-step plan that pretends everything is decided.

package/unify/templates/tool-guidance.md

@@ -37,6 +37,28 @@
 - Do not retry the same command without changing something
 - If a file doesn't exist, check the path and search for alternatives
 
+## Multi-Step Task Tracking (TodoWrite)
+
+When the task you're about to do has **3+ meaningful steps**, the user
+gave you a **list** of things to do, or you're starting a **non-trivial
+multi-file change** — call `TodoWrite` **first** to lay out the
+checklist. The user sees the items tick off in real time as you work.
+
+How to use it:
+
+- First call: enumerate every step with status `"pending"`, mark
+  exactly one as `"in_progress"`.
+- Each subsequent call: rewrite the **full** list. Mark the
+  just-finished item `"completed"` and promote the next one to
+  `"in_progress"`.
+- At most **one** item may be `"in_progress"` at any time.
+- `content` is the imperative form (e.g. "Run tests"); `activeForm` is
+  the present-continuous form shown during execution (e.g. "Running
+  tests").
+
+Do **not** use TodoWrite for single trivial edits, single command runs,
+or pure conversational/question turns — the checklist becomes noise.
+
 <!-- lang:zh -->
 
 # 工具使用指引
@@ -75,3 +97,22 @@
 - 如果工具返回错误，在重试前仔细阅读错误信息
 - 不要在没有改变任何东西的情况下重试相同的命令
 - 如果文件不存在，检查路径并搜索替代方案
+
+## 多步骤任务追踪（TodoWrite）
+
+当你要做的事 **≥3 个有意义的步骤**、用户给了你一组任务、或者你即将开始
+**复杂的多文件改动**时——**先**调用 `TodoWrite` 列出待办清单。用户会
+实时看到这些条目被勾选。
+
+使用方式：
+
+- 第一次调用：枚举所有步骤，状态全部 `"pending"`，仅把一项标记为
+  `"in_progress"`。
+- 之后每次调用：重写**完整**清单——把刚完成的项改成 `"completed"`，下
+  一项改成 `"in_progress"`。
+- 任何时刻最多只能有 **一个** `"in_progress"`。
+- `content` 是命令式（如 "Run tests"）；`activeForm` 是执行中展示的进行
+  时（如 "Running tests"）。
+
+**不要**为单条琐碎修改、单次命令执行、纯对话/问题使用 TodoWrite——清单
+反而成了噪音。

package/unify/tools/index.js

@@ -43,22 +43,20 @@ import listAgents from './list-agents.js';
 // --- P1 Routing tools (task-334d) ---
 import routeForward from './route-forward.js';
 
-// --- P1 Feature tools ---
-import {
-  featureCreate,
-  featureUpdate,
-  featureList,
-  featureGet,
-  featureProgress,
-  featureMemory,
-  followupFeature,
-  updatePlan,
-  featureSummaryPost,
-} from './feature-tools.js';
+// --- P1 Progress tracking ---
+import todoWrite from './todo-write.js';
+import startPlan from './start-plan.js';
 
 // H2.f.4: thread tools (spawnThread/switchThread/listThreads/...) deleted.
 // The agent now runs in a single conversation; multi-thread orchestration
 // has been retired across the H2.f series.
+//
+// Feature tools (FeatureCreate/Update/List/Get/Progress/Memory + Followup
+// + UpdatePlan + feature_summary_post) and the FeatureArc auto-creation
+// system were removed in 2026-05-13 — they were defined but never used in
+// production, contributing ~2900 lines of dead code. The TodoWrite tool
+// above replaces them as the actual progress-tracking surface the LLM
+// uses for multi-step tasks.
 
 // --- P2 Auxiliary tools ---
 // task-333b L1 delete: ToolSearch and WriteStdin removed — the function-call
@@ -109,16 +107,9 @@ export const allTools = [
   // P1 Routing (task-334d)
   routeForward,
 
-  // P1 Feature
-  featureCreate,
-  featureUpdate,
-  featureList,
-  featureGet,
-  featureProgress,
-  featureMemory,
-  followupFeature,
-  updatePlan,
-  featureSummaryPost,
+  // P1 Progress tracking
+  todoWrite,
+  startPlan,
 
   // P2 Auxiliary
   jsRepl,

package/unify/tools/start-plan.js

@@ -0,0 +1,133 @@
+/**
+ * start-plan.js — StartPlan tool.
+ *
+ * Lightweight planning entry point inspired by Claude Code's plan mode.
+ * Unlike Claude Code, we do NOT swap tools or change conversation state —
+ * `StartPlan` is a regular tool. Its only job is to push a planning
+ * instruction back into the model's tool-result stream so the very next
+ * turn produces a structured plan plus a `TodoWrite` call.
+ *
+ * Design (locked 2026-05-13):
+ *   - Anyone can call it; the tool description tells the LLM when to.
+ *   - The instruction text comes from one of two places, in order:
+ *       1. The active VP's `planInstruction` frontmatter override
+ *          (threaded through ctx.vpPersona.planInstruction by the
+ *          engine; see engine.js #buildToolContext).
+ *       2. The default template `templates/plan-instruction.md`
+ *          loaded at module init by prompts.js.
+ *   - The caller may pass guiding fields (stuckAt, userProblem,
+ *     expectedScale, additionalContext) to help the model think — these
+ *     are echoed back in the tool result so the planning turn can read
+ *     them without re-asking the user.
+ *   - Output is plain text (the instruction + the echo). No side effects,
+ *     no persistence — the LLM's next turn does the actual planning and
+ *     calls TodoWrite to land structured steps.
+ *
+ * The expected integration is TodoWrite: after the planning turn the LLM
+ * issues a `TodoWrite` call enumerating the 1..N steps. The frontend
+ * already renders TodoWrite as a checkbox-style list, so the user sees
+ * the plan materialize without any new UI.
+ */
+
+import { defineTool } from './types.js';
+import { getDefaultPlanInstruction } from '../prompts.js';
+
+export default defineTool({
+  name: 'StartPlan',
+  description: `Enter planning mode for a non-trivial task. Use BEFORE you start working when the request needs multiple steps, has unclear scope, or the user said "make a plan" / "think through this first".
+
+This tool does NOT execute the work. It returns a planning instruction; on the next turn you should:
+1. Produce a short prose plan (problem, approach, risks).
+2. Call \`TodoWrite\` with the ordered steps. Mark the first concrete step "in_progress", the rest "pending".
+
+WHEN TO USE:
+- Multi-step implementation (3+ steps), refactor, or open-ended investigation.
+- User explicitly asks for a plan, a TODO list, or to "think through" the work.
+- You're about to start a large change and want a checkpoint before diving in.
+
+WHEN NOT TO USE:
+- Single trivial change, single command run, lookup-style question.
+- Mid-execution — once you're past the first step, use TodoWrite directly.
+
+The tool takes the topic plus optional guiding fields (stuckAt, userProblem, expectedScale, additionalContext) that help you think; they're echoed back verbatim, so don't repeat the full user request in \`topic\`.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        description: 'One-sentence statement of what is being planned (e.g. "Add dark-mode toggle to UnifyPage settings").',
+      },
+      userProblem: {
+        type: 'string',
+        description: 'Optional. The underlying problem the user is trying to solve (often broader than the immediate ask).',
+      },
+      stuckAt: {
+        type: 'string',
+        description: 'Optional. If you are blocked or unsure, the specific decision or unknown that needs resolving first.',
+      },
+      expectedScale: {
+        type: 'string',
+        description: 'Optional. Rough scope estimate — number of files touched, lines of code, time horizon, etc.',
+      },
+      additionalContext: {
+        type: 'string',
+        description: 'Optional. Any other facts that shape the plan (constraints, deadlines, related prior work).',
+      },
+    },
+    required: ['topic'],
+  },
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const topic = typeof input?.topic === 'string' ? input.topic.trim() : '';
+    if (!topic) {
+      // Plain-text error — same shape as the success path so the LLM
+      // doesn't need a JSON-vs-text branch to read this tool's output.
+      return 'Error: topic is required (one-sentence statement of what is being planned).';
+    }
+
+    // Resolve the planning instruction: per-VP override first, then default.
+    // `ctx.vpPersona.planInstruction` is wired by engine.js #buildToolContext;
+    // it's the empty string when the VP has no override, or when the call is
+    // not VP-scoped (test ctx, sub-agent ctx without persona). We tolerate
+    // both shapes and fall through to the default template silently.
+    const language = typeof ctx?.config?.language === 'string' ? ctx.config.language : 'en';
+    const vpOverride = typeof ctx?.vpPersona?.planInstruction === 'string'
+      ? ctx.vpPersona.planInstruction.trim()
+      : '';
+    const instruction = vpOverride || getDefaultPlanInstruction(language);
+
+    // Echo the optional guiding fields back so the planning turn has them
+    // without re-reading the user's original message. Skip empty strings.
+    const echoed = {};
+    for (const key of ['userProblem', 'stuckAt', 'expectedScale', 'additionalContext']) {
+      const v = typeof input?.[key] === 'string' ? input[key].trim() : '';
+      if (v) echoed[key] = v;
+    }
+
+    // Plain text is friendlier to the LLM than JSON for an instructional
+    // result. The shape: a tagged instruction block, then a compact
+    // YAML-ish echo of the guiding fields, then a one-line nudge to land
+    // the plan via TodoWrite.
+    const lines = [];
+    lines.push('<plan-instruction>');
+    lines.push(instruction);
+    lines.push('</plan-instruction>');
+    lines.push('');
+    lines.push('<topic>');
+    lines.push(topic);
+    lines.push('</topic>');
+    if (Object.keys(echoed).length > 0) {
+      lines.push('');
+      lines.push('<guiding-context>');
+      for (const [k, v] of Object.entries(echoed)) {
+        lines.push(`${k}: ${v}`);
+      }
+      lines.push('</guiding-context>');
+    }
+    lines.push('');
+    lines.push('Next: produce the plan as described above, then call `TodoWrite` to land the ordered steps. Do NOT start executing the steps in this turn.');
+
+    return lines.join('\n');
+  },
+});