@yeaft/webchat-agent 0.1.763 → 0.1.767

package/unify/tools/todo-write.js

@@ -0,0 +1,125 @@
+/**
+ * todo-write.js — TodoWrite tool: per-VP multi-step task tracking.
+ *
+ * Mirrors Claude Code's `TodoWrite` tool 1:1 in shape (name + `todos[]`
+ * with `content` / `status` / `activeForm`) so the existing frontend
+ * rendering pipeline (`MessageList.js:691` → `AssistantTurn.js:53-63`
+ * → `ToolLine.js:150`) renders a checkmark-style list automatically
+ * without any new UI code. The frontend reads the *input* of the
+ * `tool_use` event — not the result — so this tool's persistence story
+ * is "stamp into the LLM event stream and cache on ctx for replay."
+ *
+ * Per-VP isolation: each VP keeps its own current todo list. The
+ * web-bridge injects `ctx.getCurrentTodos()` / `ctx.setCurrentTodos()`
+ * pointing at a per-(groupId,vpId) slot so two VPs in the same group
+ * can independently track their own multi-step tasks without
+ * stepping on each other.
+ *
+ * Reference: plan §2 (2026-05-13 — Feature system retired, TodoWrite
+ * added as the actual progress-tracking surface for the LLM).
+ */
+
+import { defineTool } from './types.js';
+
+const VALID_STATUS = new Set(['pending', 'in_progress', 'completed']);
+
+export default defineTool({
+  name: 'TodoWrite',
+  description: `Track multi-step task progress with a checklist that the user can see ticked off in real time.
+
+WHEN TO USE:
+- The task has 3+ meaningful steps, or
+- The user gave you a list of things to do (numbered/comma-separated), or
+- You're about to start a non-trivial, multi-file change.
+
+HOW TO USE:
+- First call: enumerate all the todos with status "pending", set exactly one to "in_progress".
+- Each subsequent call: rewrite the FULL list — mark the just-finished item "completed", mark the next item "in_progress".
+- AT MOST one item may be "in_progress" at any time.
+- \`content\` is the imperative form ("Run tests"); \`activeForm\` is the present-continuous shown during execution ("Running tests").
+
+WHEN NOT TO USE:
+- Single trivial change, single command run, pure conversation/question.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      todos: {
+        type: 'array',
+        description: 'The full current todo list. Always send the entire list, not a diff.',
+        items: {
+          type: 'object',
+          properties: {
+            content: {
+              type: 'string',
+              description: 'Imperative description of the step (e.g. "Run tests").',
+            },
+            status: {
+              type: 'string',
+              enum: ['pending', 'in_progress', 'completed'],
+              description: 'Current state. At most one item may be "in_progress".',
+            },
+            activeForm: {
+              type: 'string',
+              description: 'Present-continuous form shown while executing (e.g. "Running tests").',
+            },
+          },
+          required: ['content', 'status', 'activeForm'],
+        },
+      },
+    },
+    required: ['todos'],
+  },
+  isConcurrencySafe: () => false,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const todos = input && Array.isArray(input.todos) ? input.todos : null;
+    if (!todos || todos.length === 0) {
+      return JSON.stringify({ error: 'todos must be a non-empty array' });
+    }
+
+    let inProgressCount = 0;
+    for (let i = 0; i < todos.length; i++) {
+      const t = todos[i];
+      if (!t || typeof t !== 'object') {
+        return JSON.stringify({ error: `todos[${i}] must be an object` });
+      }
+      if (typeof t.content !== 'string' || !t.content.trim()) {
+        return JSON.stringify({ error: `todos[${i}].content must be a non-empty string` });
+      }
+      if (typeof t.activeForm !== 'string' || !t.activeForm.trim()) {
+        return JSON.stringify({ error: `todos[${i}].activeForm must be a non-empty string` });
+      }
+      if (!VALID_STATUS.has(t.status)) {
+        return JSON.stringify({
+          error: `todos[${i}].status must be one of: pending, in_progress, completed`,
+        });
+      }
+      if (t.status === 'in_progress') inProgressCount += 1;
+    }
+
+    if (inProgressCount > 1) {
+      return JSON.stringify({
+        error: `at most one todo may be in_progress at a time (found ${inProgressCount})`,
+      });
+    }
+
+    // Cache the current todo list onto the per-VP slot if the web-bridge
+    // provided one. Best-effort: this is the cache the frontend may pull
+    // on reconnect / VP-switch. Tools should not crash if the slot is
+    // missing — sub-agent ctx or test ctx may lack it.
+    if (ctx && typeof ctx.setCurrentTodos === 'function') {
+      try { ctx.setCurrentTodos(todos.slice()); } catch { /* swallow */ }
+    }
+
+    const counts = { pending: 0, in_progress: 0, completed: 0 };
+    for (const t of todos) counts[t.status] += 1;
+
+    return JSON.stringify({
+      success: true,
+      count: todos.length,
+      pending: counts.pending,
+      in_progress: counts.in_progress,
+      completed: counts.completed,
+    });
+  },
+});

package/unify/vp/vp-crud.js

@@ -297,5 +297,6 @@ export function readVp(vpId, options = {}) {
     traits: Array.isArray(meta.traits) ? meta.traits.map(String) : [],
     modelHint,
     persona: body,
+    planInstruction: typeof meta.planInstruction === 'string' ? String(meta.planInstruction) : '',
   };
 }

package/unify/vp/vp-loader.js

@@ -140,7 +140,8 @@ export class VpLoader {
         prev.mtimeMs !== next.mtimeMs ||
         prev.persona !== next.persona ||
         prev.name !== next.name ||
-        prev.role !== next.role
+        prev.role !== next.role ||
+        prev.planInstruction !== next.planInstruction
       ) {
         // In-place update preserves VP identity → RoleInstance.runtimeState
         // is untouched; persona swap propagates on next read of vp.persona.

package/unify/vp/vp-store.js

@@ -37,6 +37,9 @@ import { createHash } from 'crypto';
  * @property {'fast'|'primary'|undefined} modelHint
  * @property {string} persona         — markdown body (persona / system prompt seed)
  * @property {string} personaHash     — sha256(persona).slice(0,8); changes when persona body changes
+ * @property {string} planInstruction — optional per-VP planning style (used by `StartPlan`
+ *                                       tool); '' means "fall back to the default template".
+ *                                       Frontmatter scalar key `planInstruction`.
  * @property {string} dir             — absolute path to VP dir
  * @property {string} memoryDir       — absolute path to VP memory dir
  * @property {number} mtimeMs         — role.md mtime (for hot-reload)
@@ -163,6 +166,11 @@ export function loadVpFromDir(dir) {
     modelHint,
     persona: body,
     personaHash: personaHashValue,
+    // Optional per-VP planning style for the `StartPlan` tool. Stored as a
+    // raw scalar string in role.md frontmatter (`planInstruction: "..."`).
+    // Empty / missing → the tool falls back to the default template. Kept
+    // verbatim — the tool itself is responsible for any framing.
+    planInstruction: typeof meta.planInstruction === 'string' ? String(meta.planInstruction) : '',
     dir,
     memoryDir,
     mtimeMs: st.mtimeMs,

package/unify/web-bridge.js

@@ -107,6 +107,24 @@ const vpDrivers = new Map();
 const vpEngines = new Map();
 /** @type {Map<string, AbortController>} */
 const vpAborts = new Map();
+/**
+ * Per-(groupId, vpId) current TodoWrite list. Each VP in a group keeps
+ * its own todo state so two VPs in the same group can independently
+ * track multi-step tasks without overwriting each other. Threaded into
+ * the engine's tool ctx via buildVpQueryOpts → getCurrentTodos /
+ * setCurrentTodos closures. Best-effort in-memory cache only — todos
+ * are also stamped into the LLM event stream (the frontend reads from
+ * the tool_use input, not from this map), so a server restart simply
+ * loses the "what was the most recent list?" peek without breaking the
+ * UI replay.
+ *
+ * Key: `${groupId}::${vpId}` (matches vpEngines/vpAborts convention).
+ * Value: `Array<{content, status, activeForm}>` — the last full list
+ * the VP wrote with TodoWrite.
+ *
+ * @type {Map<string, Array<{content: string, status: string, activeForm: string}>>}
+ */
+const vpCurrentTodos = new Map();
 /**
  * Per-group cached coordinator + router. Created on first
  * `handleUnifyGroupChat` for a given groupId; reused across user messages
@@ -157,6 +175,11 @@ function invalidateGroupContext(groupId) {
     if (!k.startsWith(prefix)) continue;
     if (Array.isArray(inbox)) inbox.length = 0;
   }
+  // Reap per-(group,vp) TodoWrite snapshots for this group so a
+  // deleted/renamed group doesn't pin a stale checklist forever.
+  for (const k of vpCurrentTodos.keys()) {
+    if (k.startsWith(prefix)) vpCurrentTodos.delete(k);
+  }
   // Engines are NOT torn down here on purpose. They hold subordinate
   // state (AMS adjustments) that should survive a meta change and a
   // closed groupHandle — they don't reach the on-disk group meta
@@ -739,6 +762,7 @@ export async function __testResetVpState() {
   vpEngines.clear();
   vpAborts.clear();
   groupContexts.clear();
+  vpCurrentTodos.clear();
   // Per-group compact in-flight + pending state lives on the session's
   // Compactor. Clear it so a follow-on test doesn't see ghost in-flight
   // promises from a prior run.
@@ -753,27 +777,25 @@ export async function __testResetVpState() {
  * Envelope fields: conversationId, groupId, vpId, turnId — the last two
  * let the frontend route incremental deltas to the correct per-VP message block.
  */
-function sendUnifyOutput(data, { groupId, vpId, turnId, featureId } = {}) {
+function sendUnifyOutput(data, { groupId, vpId, turnId } = {}) {
   sendToServer({
     type: 'unify_output',
     conversationId: unifyConversationId,
     ...(groupId ? { groupId } : {}),
     ...(vpId ? { vpId } : {}),
     ...(turnId ? { turnId } : {}),
-    ...(featureId ? { featureId } : {}),
     data,
   });
 }
 
 /** Send a unify_output event (non-claude_output metadata). */
-function sendUnifyEvent(event, { groupId, vpId, turnId, featureId } = {}) {
+function sendUnifyEvent(event, { groupId, vpId, turnId } = {}) {
   sendToServer({
     type: 'unify_output',
     conversationId: unifyConversationId,
     ...(groupId ? { groupId } : {}),
     ...(vpId ? { vpId } : {}),
     ...(turnId ? { turnId } : {}),
-    ...(featureId ? { featureId } : {}),
     event,
   });
 }
@@ -1152,18 +1174,10 @@ export function installUnifyRuntimeBridge(s) {
  */
 function handleEngineEvent(event, hctx) {
   hctx.resetQueryTimer();
-  // Sub-agent events may carry their own `featureId` (stamped by the
-  // sub-agent runner from the parent's inbound feature scope). Plain
-  // VP-turn events have no featureId — auto-feature creation was
-  // removed when Track-A / FeatureArc was deleted (2026-05-08).
-  const eventFeatureId = typeof event === 'object' && event && typeof event.featureId === 'string'
-    ? event.featureId
-    : null;
   const envelope = {
     groupId: hctx.groupId,
     vpId: hctx.vpId,
     turnId: hctx.turnId,
-    ...(eventFeatureId ? { featureId: eventFeatureId } : {}),
   };
 
   switch (event.type) {
@@ -1854,6 +1868,10 @@ export function buildVpQueryOpts({ vpId, groupCoordinator, groupId, envelope })
         role: vp.role || '',
         roleZh: vp.roleZh || '',
         persona: vp.persona || '',
+        // Optional per-VP planning style for the `StartPlan` tool. Empty
+        // string means "fall back to the default template" — the tool
+        // handles the lookup so callers stay ignorant of the default.
+        planInstruction: typeof vp.planInstruction === 'string' ? vp.planInstruction : '',
       };
     }
   } catch { /* persona load is best-effort */ }
@@ -1872,6 +1890,20 @@ export function buildVpQueryOpts({ vpId, groupCoordinator, groupId, envelope })
   if (envelope && typeof envelope === 'object') {
     out.inboundEnvelope = envelope;
   }
+  // TodoWrite per-VP isolation. Bind closures that read/write a slot
+  // keyed by `${groupId}::${vpId}` so two VPs in the same group don't
+  // overwrite each other's lists, and the TodoWrite tool can stay
+  // ignorant of routing details (it just calls ctx.setCurrentTodos).
+  const todosKey = `${out.groupId || ''}::${resolvedVpId}`;
+  out.getCurrentTodos = () => {
+    const cached = vpCurrentTodos.get(todosKey);
+    return Array.isArray(cached) ? cached.slice() : null;
+  };
+  out.setCurrentTodos = (todos) => {
+    if (Array.isArray(todos)) {
+      vpCurrentTodos.set(todosKey, todos.slice());
+    }
+  };
   return out;
 }
 
@@ -2529,149 +2561,64 @@ export async function handleUnifyDreamTrigger(msg = {}) {
   }
 }
 
-/** Deprecated mode switch — Unify is single-mode. */
-export function handleUnifyModeSwitch(_msg) {
-  console.warn('[Unify] unify_mode_switch is deprecated and ignored — Unify now runs in a single unified mode.');
-}
-
-/** Fetch a feature's summary history (revision chain). */
-export async function handleUnifyFetchSummaryHistory(msg = {}) {
-  const requestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
-  const featureId = typeof msg.featureId === 'string' ? msg.featureId : null;
-  const includeArchived = !!msg.includeArchived;
-
-  const reply = (extra = {}) => sendUnifyEvent({
-    type: 'unify_summary_history',
-    featureId,
-    ...extra,
-    ...(requestId ? { requestId } : {}),
-  });
-
-  if (!featureId) { reply({ revisions: [], archived: null, error: 'missing_feature_id' }); return; }
-
+/**
+ * 2026-05-13: serve the Unify debug drawer's "Tool Stats" panel.
+ *
+ * Replies with `{type: 'unify_tool_stats', snapshot, registered,
+ * unused}`. `snapshot` is the `ToolUsageStats.snapshot()` keyed by
+ * tool name (callCount, errorCount, p50Ms, p95Ms, avgMs, lastCalledAt,
+ * lastError, errorRate). `registered` is the static list of built-in
+ * tool names so the frontend can render the "(defined but never
+ * called)" subview without spinning up its own registry mirror.
+ *
+ * Best-effort: if the session hasn't booted yet or toolStats is
+ * missing, we still reply with an empty snapshot so the UI can render
+ * a placeholder rather than spin forever.
+ */
+export async function handleUnifyFetchToolStats(_msg = {}) {
+  let snapshot = {};
+  let registered = [];
+  let unused = [];
   try {
-    const { getFeatureStore } = await import('./tools/feature-tools.js');
-    const featureStore = getFeatureStore();
-    const feature = featureStore?.get(featureId);
-    if (!feature) { reply({ revisions: [], archived: null, error: 'feature_not_found' }); return; }
-    const groupId = feature.groupId;
-    if (!groupId) { reply({ revisions: [], archived: null, error: 'feature_has_no_group' }); return; }
-
-    const yeaftDir = ctx.CONFIG?.yeaftDir;
-    if (!yeaftDir) { reply({ revisions: [], archived: null, error: 'no_yeaft_dir' }); return; }
-
-    const root = join(yeaftDir, 'groups');
-    const dir = join(root, groupId);
-    if (!existsSync(dir) || !loadGroupMeta(dir)) {
-      reply({ revisions: [], archived: null, error: 'group_not_found' });
-      return;
-    }
-    const groupHandle = openGroup(root, groupId);
-    const summaries = [];
-    for (const m of groupHandle.streamMessages()) {
-      if (!m || m.featureId !== featureId) continue;
-      const meta = m.meta || {};
-      if (meta.kind === 'summary' || meta.type === 'summary') summaries.push(m);
+    if (session?.toolStats && typeof session.toolStats.snapshot === 'function') {
+      snapshot = session.toolStats.snapshot();
     }
-    summaries.sort((a, b) => {
-      const at = Date.parse(a.ts || '') || 0;
-      const bt = Date.parse(b.ts || '') || 0;
-      return bt - at;
-    });
-    const supersededIds = new Set();
-    for (const s of summaries) {
-      const arr = s.meta?.supersedes;
-      if (Array.isArray(arr)) for (const id of arr) supersededIds.add(id);
+    // Pull the static built-in tool list. MCP/skill tools aren't in
+    // here — that's fine: the "unused" view is meant to flag stale
+    // built-in tools, not user-installed ones.
+    const { allTools } = await import('./tools/index.js');
+    if (Array.isArray(allTools)) {
+      registered = allTools
+        .filter(t => t && typeof t.name === 'string' && t.name)
+        .map(t => t.name);
     }
-    const current = [];
-    const archived = [];
-    for (const s of summaries) {
-      if (supersededIds.has(s.id)) archived.push(s);
-      else current.push(s);
+    if (session?.toolStats && typeof session.toolStats.getRegisteredButUncalled === 'function') {
+      unused = session.toolStats.getRegisteredButUncalled(registered);
     }
-    const overflow = current.slice(10);
-    const trimmedCurrent = current.slice(0, 10);
-    if (overflow.length) archived.push(...overflow);
-    archived.sort((a, b) => {
-      const at = Date.parse(a.ts || '') || 0;
-      const bt = Date.parse(b.ts || '') || 0;
-      return bt - at;
-    });
-    reply({
-      revisions: trimmedCurrent,
-      archived: includeArchived ? archived : null,
-    });
   } catch (err) {
-    reply({ revisions: [], archived: null, error: String(err?.message || err) });
+    sendToServer({
+      type: 'unify_tool_stats',
+      snapshot: {},
+      registered: [],
+      unused: [],
+      error: err && err.message ? err.message : String(err),
+    });
+    return;
   }
-}
-
-/** Feature affiliation CRUD (relate / unrelate / kick_vp / abort_vp). */
-export async function handleUnifyFeatureCrud(msg = {}) {
-  const requestId = typeof msg.requestId === 'string' ? msg.requestId : undefined;
-  const op = typeof msg.op === 'string' ? msg.op : null;
-  const featureId = typeof msg.featureId === 'string' ? msg.featureId : null;
-  const vpId = typeof msg.vpId === 'string' ? msg.vpId : null;
-  const relatedFeatureId = typeof msg.relatedFeatureId === 'string' ? msg.relatedFeatureId : null;
-
-  const reply = (extra = {}) => sendUnifyEvent({
-    type: 'unify_feature_crud_result',
-    op,
-    featureId,
-    ...(vpId ? { vpId } : {}),
-    ...extra,
-    ...(requestId ? { requestId } : {}),
+  sendToServer({
+    type: 'unify_tool_stats',
+    snapshot,
+    registered,
+    unused,
   });
+}
 
-  if (!op) { reply({ ok: false, error: 'missing_op' }); return; }
-  if (!featureId) { reply({ ok: false, error: 'missing_feature_id' }); return; }
-
-  try {
-    const { getFeatureStore } = await import('./tools/feature-tools.js');
-    const featureStore = getFeatureStore();
-    const feature = featureStore?.get(featureId);
-    if (!feature) { reply({ ok: false, error: 'feature_not_found' }); return; }
-
-    if (op === 'relate' || op === 'unrelate') {
-      if (!relatedFeatureId) { reply({ ok: false, error: 'missing_related_feature_id' }); return; }
-      const other = featureStore.get(relatedFeatureId);
-      if (!other) { reply({ ok: false, error: 'related_feature_not_found' }); return; }
-      const apply = (t, otherId, add) => {
-        const cur = Array.isArray(t.relatedFeatureIds) ? t.relatedFeatureIds.slice() : [];
-        const idx = cur.indexOf(otherId);
-        if (add && idx === -1) cur.push(otherId);
-        if (!add && idx !== -1) cur.splice(idx, 1);
-        featureStore.update(t.id, { relatedFeatureIds: cur });
-      };
-      apply(feature, relatedFeatureId, op === 'relate');
-      apply(other, featureId, op === 'relate');
-      reply({ ok: true, relatedFeatureId });
-      return;
-    }
-
-    if (op === 'kick_vp') {
-      if (!vpId) { reply({ ok: false, error: 'missing_vp_id' }); return; }
-      featureStore.removeMember(featureId, vpId);
-      reply({ ok: true });
-      return;
-    }
-
-    if (op === 'abort_vp') {
-      if (!vpId) { reply({ ok: false, error: 'missing_vp_id' }); return; }
-      // H2.f.2: per-VP abort no longer routed through engineRegistry — the
-      // single engine handles its own abort via currentAbortCtrl. Reply
-      // ok:true so the UI surface still works; deeper per-VP cancel is a
-      // separate task.
-      reply({ ok: true });
-      return;
-    }
-
-    reply({ ok: false, error: 'unknown_op' });
-  } catch (err) {
-    reply({ ok: false, error: String(err?.message || err) });
-  }
+/** Deprecated mode switch — Unify is single-mode. */
+export function handleUnifyModeSwitch(_msg) {
+  console.warn('[Unify] unify_mode_switch is deprecated and ignored — Unify now runs in a single unified mode.');
 }
 
+
 /** Handle model switch from the web UI. */
 export function handleUnifyModelSwitch(msg) {
   if (!session || !msg.model) return;
@@ -2914,6 +2861,7 @@ export async function resetUnifySession() {
   vpDrivers.clear();
   vpEngines.clear();
   groupContexts.clear();
+  vpCurrentTodos.clear();
   // History-dedup cache is keyed by per-session coordinator msg ids;
   // a fresh session resets the id space, so clear the cache too.
   _persistedUserMsgIds.clear();