@yeaft/webchat-agent 0.1.735 → 0.1.739

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.735",
+  "version": "0.1.739",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/tools/registry.js

@@ -41,6 +41,50 @@ import { DEFAULT_CONTEXT_WINDOW } from '../models.js';
 const TOOL_RESULT_CAP_RATIO = 0.10;
 const TOOL_RESULT_MIN_CAP = 8 * 1024;
 
+/**
+ * Per-tool execution timeout (ms).
+ *
+ * Without a timeout, a tool whose `execute()` ignores `signal` (or hangs on
+ * a network call that doesn't honor AbortSignal) blocks the engine
+ * generator's `await this.#toolRegistry.execute(...)` forever. The for-await
+ * in the bridge driver never advances → no further events emitted → no
+ * `turn_end` → typing dots hang → user sees the conversation "halt" with
+ * no terminal event. The bridge's 120s watchdog calls `vpAbort.abort()`
+ * but a tool that ignores signal also ignores the abort, so the abort
+ * does nothing.
+ *
+ * Fix: race the tool's promise against a timer. On timeout we throw a
+ * loud error — the engine's existing catch (engine.js: tool-execute path)
+ * emits `tool_end{isError:true}` and the loop continues normally. Loud
+ * failure beats silent stall.
+ *
+ * 90s is comfortably above the typical tool budget (most tools complete
+ * in <1s; bash and web-fetch can run tens of seconds; web-search is
+ * usually <10s) but well below the 120s bridge-level watchdog so the
+ * tool-level signal fires first and surfaces a useful per-tool diagnosis
+ * rather than an opaque "VP stalled" log.
+ *
+ * Override per-tool by setting `tool.timeoutMs` on the ToolDef. Set to
+ * 0 (or a negative number) to disable the timeout for that tool — only
+ * use this for legitimately long-running internal tools.
+ */
+export const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
+
+/**
+ * Error thrown when a tool's execute() exceeds its timeout. Carries the
+ * tool name + budget so the engine's catch path (and the resulting
+ * `tool_end{isError:true}` event) can surface a precise diagnostic to
+ * the user instead of a generic stall.
+ */
+export class ToolExecutionTimeoutError extends Error {
+  constructor(toolName, timeoutMs) {
+    super(`Tool "${toolName}" did not complete within ${timeoutMs}ms`);
+    this.name = 'ToolExecutionTimeoutError';
+    this.toolName = toolName;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 /**
  * Truncate a tool result if it exceeds the per-result cap. Non-string
  * outputs are JSON-stringified first (matching what engine.js eventually
@@ -76,6 +120,35 @@ export function truncateToolResultIfNeeded(output, { contextWindow, toolName })
   return head + marker;
 }
 
+/**
+ * Race a promise against a timer. If the promise resolves first, return its
+ * value. If the timer wins, throw {@link ToolExecutionTimeoutError}. The
+ * underlying tool promise is intentionally NOT cancelled — JS has no
+ * cooperative promise cancellation, so a tool that ignores `signal` will
+ * keep running in the background; we just stop waiting on it. The engine
+ * sees a clean error and the user sees `tool_end{isError:true}` instead
+ * of an indefinite hang.
+ *
+ * Internal helper — not exported. The default and overrides are managed
+ * via {@link DEFAULT_TOOL_TIMEOUT_MS} and `tool.timeoutMs`.
+ *
+ * @param {Promise<unknown>} promise
+ * @param {number} timeoutMs
+ * @param {string} toolName
+ * @returns {Promise<unknown>}
+ */
+function runWithTimeout(promise, timeoutMs, toolName) {
+  let timer = null;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new ToolExecutionTimeoutError(toolName, timeoutMs));
+    }, timeoutMs);
+  });
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
 export class ToolRegistry {
   /** @type {Map<string, import('./types.js').ToolDef>} */
   #tools = new Map();
@@ -174,7 +247,20 @@ export class ToolRegistry {
   async execute(name, input, ctx = {}) {
     const tool = this.#tools.get(name);
     if (!tool) throw new Error(`Unknown tool: ${name}`);
-    const output = await tool.execute(input, ctx);
+
+    // Per-tool timeout. A tool that ignores `signal` and never resolves
+    // would otherwise hang the engine's `await this.#toolRegistry.execute(...)`
+    // indefinitely — see DEFAULT_TOOL_TIMEOUT_MS docblock for the
+    // motivating "silent turn stall" failure. The race throws a typed
+    // error on timeout; the engine's existing catch turns it into
+    // `tool_end{isError:true}` and the loop continues.
+    const rawTimeout = Number.isFinite(tool.timeoutMs) ? tool.timeoutMs : DEFAULT_TOOL_TIMEOUT_MS;
+    const useTimeout = rawTimeout > 0;
+
+    const output = useTimeout
+      ? await runWithTimeout(tool.execute(input, ctx), rawTimeout, name)
+      : await tool.execute(input, ctx);
+
     return truncateToolResultIfNeeded(output, {
       contextWindow: ctx.contextWindow,
       toolName: name,

package/unify/tools/types.js

@@ -68,6 +68,7 @@
  *   isConcurrencySafe?: (input?: object) => boolean,
  *   isReadOnly?: (input?: object) => boolean,
  *   isDestructive?: (input?: object) => boolean,
+ *   timeoutMs?: number,
  * }} def
  * @returns {ToolDef}
  */
@@ -79,11 +80,12 @@ export function defineTool({
   isConcurrencySafe = () => false,
   isReadOnly = () => false,
   isDestructive = () => false,
+  timeoutMs,
 }) {
   if (!name) throw new Error('Tool must have a name');
   if (!execute) throw new Error(`Tool "${name}" must have an execute function`);
 
-  return {
+  const def = {
     name,
     description: description || `Tool: ${name}`,
     parameters: parameters || { type: 'object', properties: {} },
@@ -92,4 +94,11 @@ export function defineTool({
     isReadOnly,
     isDestructive,
   };
+  // Only attach `timeoutMs` when the tool author opts in. Leaving it
+  // unset means ToolRegistry.execute uses DEFAULT_TOOL_TIMEOUT_MS — set
+  // to <= 0 to disable the per-tool timeout entirely.
+  if (Number.isFinite(timeoutMs)) {
+    def.timeoutMs = timeoutMs;
+  }
+  return def;
 }

package/unify/web-bridge.js

@@ -50,8 +50,6 @@ import {
   compactHistory,
   trimSnapshotForBudget,
 } from './history-compact.js';
-import { createFeatureArc } from './feature-arc.js';
-import { getFeatureStore } from './tools/feature-tools.js';
 import { persistUnifyAttachments, attachmentsForPersistence } from './attachments.js';
 import { parseSeqFromId } from './conversation/persist.js';
 
@@ -194,6 +192,42 @@ export function broadcastLanguageChange(language) {
 /** Query timeout in ms — abort if LLM doesn't respond within this window */
 const QUERY_TIMEOUT_MS = 120_000;
 
+/**
+ * Secondary watchdog grace period (ms).
+ *
+ * After {@link QUERY_TIMEOUT_MS} of silence the per-VP `vpAbort` is fired.
+ * That's enough on its own when adapters / tools cooperate with the
+ * AbortSignal — the engine throws `AbortError`, runVpTurn's catch emits
+ * `result{stopped:true}`, the driver `finally` emits `vp_typing_end`, and
+ * the user is unstuck.
+ *
+ * If a tool ignores `signal` and never resolves, the engine generator's
+ * `await tool.execute(...)` is permanently blocked: the abort fires on a
+ * controller it never observes, and runVpTurn never returns. The same
+ * applies to an adapter `stream()` that ignores `signal` (e.g. a stuck
+ * SSE connection) or to tools that legitimately opt out of the per-tool
+ * timeout via `timeoutMs <= 0`. The per-tool timeout in
+ * {@link import('./tools/registry.js').DEFAULT_TOOL_TIMEOUT_MS}
+ * is the primary cure for the tool-ignore-signal case; this bridge-level
+ * escalation strictly extends it to cover the adapter and opt-out cases.
+ * Without a second-stage escalation the typing dots hang forever —
+ * exactly the "halts mid-execution with no turn_end" symptom.
+ *
+ * The driver loop wraps `await runVpTurn(...)` in a Promise.race against
+ * this grace-window timer. If runVpTurn doesn't return within
+ * QUERY_TIMEOUT_MS + ESCALATE_AFTER_ABORT_MS, the driver forces its
+ * `finally` block (vp_typing_end + group_message), emits a synthetic
+ * `result{stopped:true}` so the frontend leaves its in-flight state,
+ * and moves on. The hung tool promise leaks (JS lacks cooperative
+ * promise cancellation) but the user-facing turn is closed.
+ *
+ * 15s is wide enough that legitimate "abort took a moment to propagate"
+ * paths (network teardown, finally cleanup) finish first; tight enough
+ * that a truly stuck tool doesn't stretch the user-visible stall to
+ * minutes.
+ */
+const ESCALATE_AFTER_ABORT_MS = 15_000;
+
 /** Virtual conversationId for the Unify session */
 let unifyConversationId = null;
 
@@ -424,7 +458,7 @@ function ensureDriverRunning(groupId, vpId) {
       } catch { /* never crash WS pipeline */ }
 
       try {
-        await runVpTurn({
+        await runVpTurnWithEscalation({
           prompt,
           promptParts,
           groupId,
@@ -910,15 +944,18 @@ export function installUnifyRuntimeBridge(s) {
  */
 function handleEngineEvent(event, hctx) {
   hctx.resetQueryTimer();
-  // featureId may have just been published mid-turn by the FeatureArc
-  // (the arc's observeEvent runs before this dispatch); pull it fresh
-  // so the wire envelope tags every subsequent emit with the right id.
-  const featureId = typeof hctx.getFeatureId === 'function' ? hctx.getFeatureId() : null;
+  // 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,
-    ...(featureId ? { featureId } : {}),
+    ...(eventFeatureId ? { featureId: eventFeatureId } : {}),
   };
 
   switch (event.type) {
@@ -1672,6 +1709,94 @@ async function ensureSessionLoaded() {
   sendGroupSnapshotBroadcast();
 }
 
+/**
+ * Wrap {@link runVpTurn} with a hard escalation deadline.
+ *
+ * The first-line defense is the in-turn watchdog inside runVpTurn: at
+ * {@link QUERY_TIMEOUT_MS} of silence it calls `vpAbort.abort()`. When
+ * adapters and tools cooperate with AbortSignal that's enough — the
+ * engine throws AbortError, the catch handler emits `result{stopped:true}`,
+ * and the driver's `finally` emits `vp_typing_end`.
+ *
+ * This wrapper is the second-line defense for the "tool ignores signal"
+ * failure mode. If runVpTurn doesn't return within
+ * QUERY_TIMEOUT_MS + ESCALATE_AFTER_ABORT_MS we synthesize a clean exit:
+ * emit a synthetic `result{stopped:true}` so the frontend leaves its
+ * in-flight state, log loudly so operators know a tool is stuck, and
+ * resolve. The hung promise leaks (the engine generator is permanently
+ * blocked on a tool that ignores cancellation) but the user-facing turn
+ * is closed and the next message can flow. Resolving the wrapper is
+ * preferred over rejecting because the driver's catch already logs a
+ * warning — we want a single, unambiguous "watchdog escalated" line in
+ * the log instead of layered noise.
+ *
+ * Tool-level timeouts (see registry.js DEFAULT_TOOL_TIMEOUT_MS) are the
+ * real cure: this wrapper should rarely fire because no tool should be
+ * able to block longer than its budget. It exists as belt-and-suspenders
+ * for tools that legitimately disable timeouts (long-running internal
+ * helpers) or for adapter implementations that ignore signal.
+ */
+async function runVpTurnWithEscalation(args) {
+  const { groupId, vpId, turnId } = args;
+  const deadlineMs = QUERY_TIMEOUT_MS + ESCALATE_AFTER_ABORT_MS;
+  await raceWithEscalation(runVpTurn(args), {
+    deadlineMs,
+    onEscalate: () => {
+      console.error(
+        `[Unify] runVpTurn watchdog escalation: VP ${vpId} did not return ${deadlineMs}ms after enqueue — emitting synthetic stop and unblocking driver`,
+      );
+      try {
+        sendUnifyOutput(
+          { type: 'result', result_text: '', stopped: true },
+          { groupId, vpId, turnId },
+        );
+      } catch { /* never crash WS pipeline */ }
+    },
+  });
+}
+
+/**
+ * Race `inner` against a deadline timer. If `inner` resolves/rejects first,
+ * the timer is cleared and the result of `inner` is returned. If the timer
+ * wins, `onEscalate` is called and the wrapper resolves cleanly — the inner
+ * promise is left dangling (JS has no promise cancellation) but the caller
+ * is unblocked.
+ *
+ * `onEscalate` MUST be synchronous. We swallow synchronous throws so a
+ * torn-down WS pipeline can't crash the watchdog, but a Promise rejection
+ * from an async `onEscalate` would leak past this `catch`.
+ *
+ * Pure helper, no module-level state, exported as `__testRaceWithEscalation`
+ * so the contract can be unit-tested in isolation. Inner errors propagate
+ * (a tool that throws still surfaces through `runVpTurn`'s normal catch).
+ *
+ * @template T
+ * @param {Promise<T>} inner
+ * @param {{ deadlineMs: number, onEscalate: () => void }} opts
+ * @returns {Promise<T|void>}
+ */
+async function raceWithEscalation(inner, { deadlineMs, onEscalate }) {
+  let escalateTimer = null;
+  const escalation = new Promise((resolve) => {
+    escalateTimer = setTimeout(() => {
+      try { onEscalate(); } catch { /* never throw out of the watchdog */ }
+      resolve();
+    }, deadlineMs);
+    // `unref()` lets a pending escalation timer not hold the Node event
+    // loop open (e.g. during graceful shutdown). Browsers / non-Node
+    // runtimes don't expose it, hence the typeof guard. Node's own
+    // `Timeout.unref()` does not throw, so no try/catch is needed.
+    if (escalateTimer && typeof escalateTimer.unref === 'function') {
+      escalateTimer.unref();
+    }
+  });
+  try {
+    return await Promise.race([inner, escalation]);
+  } finally {
+    clearTimeout(escalateTimer);
+  }
+}
+
 /**
  * Run a single VP's turn: call engine.query() with the supplied prompt and
  * coordinator-bound router, stream events to the frontend, and append the
@@ -1697,11 +1822,6 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
   if (!prompt?.trim()) return;
 
   const envelope = { groupId, vpId, turnId };
-  // Arc is declared at outer-try scope so the catch / finally branches
-  // below can call `arc.finalize({status:'aborted'|'error'})` after a
-  // throw escaping the inner try. It's null until the inner try
-  // populates it; all catch-side calls guard with `arc?.finalize?.`.
-  let arc = null;
 
   try {
     if (session?.dreamScheduler) {
@@ -1727,12 +1847,6 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
       const assistantTextParts = [];
       const toolCallsAccum = [];
       const toolResultsAccum = [];
-      // PR-4 (review fix): hoist `vpEngine` so the `finally` can clear
-      // the per-turn featureId accessor on the SAME engine instance
-      // we installed it on — even if the VP was kicked or its group
-      // deleted mid-turn (both code paths call `vpEngines.delete(...)`).
-      // Calling `getOrCreateVpEngine` again from `finally` would
-      // resurrect a zombie engine for a VP that no longer exists.
       let vpEngine = null;
 
       // task-707: per-VP engine + persistent group coord. The coord is
@@ -1749,74 +1863,7 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
         envelope: inboundEnvelope,
       });
 
-      // ── Dual-track feature arc ──
-      // Track A (quick-response) runs concurrently against the same
-      // primary model with a non-looping single call; its preview is
-      // surfaced to the user immediately via `quick_preview` so they
-      // see *something* within ~1s. Three signals (Track A intent,
-      // ≥3 engine loops, key tool call) auto-create a Feature record
-      // and the wire envelope starts tagging emits with `featureId`,
-      // letting the frontend fold subsequent messages into a pill.
-      arc = createFeatureArc({
-        adapter: session?.adapter || null,
-        model: session?.config?.model || null,
-        featureStore: getFeatureStore(),
-        prompt,
-        vpId,
-        groupId: groupId || null,
-        turnId,
-        vpDisplayName: queryOpts?.vpPersona?.displayName || vpId,
-        language: session?.config?.language || 'en',
-        signal: vpAbort.signal,
-        emit: {
-          quickPreview: ({ intent, preview }) => {
-            sendUnifyEvent({
-              type: 'quick_preview',
-              intent,
-              preview,
-              vpId,
-              turnId,
-            }, envelope);
-          },
-          featureStarted: ({ featureId, title, trigger, toolName }) => {
-            sendUnifyEvent({
-              type: 'feature_started',
-              featureId,
-              title,
-              trigger,         // 'quick' | 'turns' | 'tool'
-              toolName: toolName || null,
-              vpId,
-              turnId,
-            }, { ...envelope, featureId });
-          },
-          featureCompleted: ({ featureId, summary, status }) => {
-            sendUnifyEvent({
-              type: 'feature_completed',
-              featureId,
-              summary,
-              status,            // 'completed' | 'aborted' | 'error'
-              vpId,
-              turnId,
-            }, { ...envelope, featureId });
-          },
-        },
-      });
-      // Fire-and-forget — Track A produces its preview / decision when
-      // ready; the main engine loop must not be held back waiting for it.
-      arc.startTrackA();
-
-      // PR-4: let sub-agents spawned during this turn inherit the
-      // parent's active featureId. Read lazily inside the engine's
-      // parentEngineDeps so a feature that opens AFTER a sub-agent
-      // spawns still tags the sub-agent's later events. Cleared in the
-      // `finally` below so a stale `arc` reference doesn't leak into
-      // the next turn.
       vpEngine = getOrCreateVpEngine(groupId, vpId);
-      if (typeof vpEngine.setCurrentFeatureIdAccessor === 'function') {
-        vpEngine.setCurrentFeatureIdAccessor(() => {
-          try { return arc?.getFeatureId?.() || null; } catch { return null; }
-        });
-      }
 
       const handlerCtx = {
         assistantTextParts,
@@ -1826,9 +1873,6 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
         groupId,
         vpId,
         turnId,
-        // Lets handleEngineEvent stamp the latest featureId on each
-        // outgoing envelope; the arc may publish it mid-turn.
-        getFeatureId: () => arc.getFeatureId(),
       };
       // Always trim the snapshot before passing to engine.query. This is
       // the second-line defense (history-compact only fires above 30K
@@ -1853,26 +1897,12 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
         ...queryOpts,
       })) {
         resetQueryTimer();
-        // Arc observes BEFORE dispatch so featureId (if just published)
-        // is available when handleEngineEvent stamps the envelope.
-        try { arc.observeEvent(event); } catch (err) {
-          console.warn('[FeatureArc] observe failed:', err?.message || err);
-        }
         handleEngineEvent(event, handlerCtx);
       }
 
       // Turn completed — atomically append this VP's output to shared history.
       appendTurnToHistory(prompt, assistantTextParts, toolCallsAccum, toolResultsAccum);
 
-      // Close the arc: if a feature was opened during the turn, run the
-      // summary call and write status='completed' back to FeatureStore.
-      // Awaited so the `feature_completed` event reaches the frontend
-      // before the final 'result' bubble (UI ordering matters: the pill
-      // should reach its done state before the turn is marked done).
-      try { await arc.finalize({ status: 'completed' }); } catch (err) {
-        console.warn('[FeatureArc] finalize failed:', err?.message || err);
-      }
-
       sendUnifyOutput({
         type: 'assistant',
         message: { content: [] },
@@ -1883,25 +1913,10 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
       }, envelope);
     } finally {
       if (queryTimer) clearTimeout(queryTimer);
-      // PR-4 (review fix): clear the accessor on the SAME engine
-      // instance we installed it on. Reusing the captured reference
-      // (instead of calling getOrCreateVpEngine again) avoids
-      // resurrecting a zombie engine if the VP/group was torn down
-      // mid-turn. `vpEngine` is null only when the install path threw
-      // before the engine lookup (very early failure) — in that case
-      // there's nothing to clear.
-      try {
-        if (vpEngine && typeof vpEngine.setCurrentFeatureIdAccessor === 'function') {
-          vpEngine.setCurrentFeatureIdAccessor(null);
-        }
-      } catch { /* best-effort */ }
     }
   } catch (err) {
     const isAbort = err && (err.name === 'AbortError' || err.name === 'LLMAbortError');
     if (isAbort) {
-      // Best-effort close: mark the feature aborted so the frontend pill
-      // settles into the right terminal state instead of staying active.
-      try { await arc?.finalize?.({ status: 'aborted' }); } catch { /* ignore */ }
       sendUnifyOutput({
         type: 'result',
         result_text: '',
@@ -1911,7 +1926,6 @@ async function runVpTurn({ prompt, promptParts = null, groupId, vpId, turnId, en
     }
 
     console.error('[Unify] query error:', err);
-    try { await arc?.finalize?.({ status: 'error' }); } catch { /* ignore */ }
 
     if (isPermissionErrorMsg(err.message)) {
       if (!_permissionDiagnosticSent) {
@@ -2322,6 +2336,13 @@ export function __testGetRegisteredThreadIds() {
   return currentAbortCtrl && !currentAbortCtrl.signal.aborted ? ['main'] : [];
 }
 
+/**
+ * Test-only: expose the bridge-level escalation helper. Lets tests verify
+ * the "tool ignored signal → wrapper escalates" contract without booting a
+ * full session. See `test/agent/unify/web-bridge-escalation.test.js`.
+ */
+export const __testRaceWithEscalation = raceWithEscalation;
+
 /**
  * Manual dream trigger from VP detail page.
  */

package/unify/feature-arc.js

@@ -1,437 +0,0 @@
-/**
- * feature-arc.js — Tracks a single VP turn's "is this heavy work?" arc.
- *
- * Design rationale
- * ----------------
- * The Unify group chat used to dump every tool call from every VP into
- * one scrolling feed, which made anything beyond a one-shot Q&A
- * unreadable. The fix is dual-layer:
- *
- *   group chat     → user prompt + a *pill* per heavy turn
- *                    (active: "🔧 [vp] doing X…", done: "✅ [vp] X — summary")
- *   detail panel   → the full unflattened timeline of whichever VP is
- *                    selected
- *
- * For pills to exist we need to know **which VP turns are heavy**. The
- * triage runs out of three signals (any-of):
- *
- *   1. Track A (quick-response) returned `intent: 'feature'`
- *   2. Track B (main engine) has cycled ≥ FEATURE_TURN_THRESHOLD loops
- *   3. Track B called any tool on KEY_TOOLS (work tools — bash, edits,
- *      sub-agent spawn, grep/find/glob — *not* pure read or web search)
- *
- * When any signal fires, this arc:
- *   - calls FeatureStore.create() with title := preview (or fallback)
- *   - stamps a `currentFeatureId` on the runVpTurn ctx so subsequent
- *     emits get featureId on their wire envelope
- *   - notifies the wire layer via a `feature_started` event so the
- *     frontend knows to fold prior messages into a pill
- *   - on turn close, runs a one-shot summarisation call against the
- *     accumulated assistant text, then writes status='completed' +
- *     result back through FeatureStore.update()
- *
- * The arc is **strictly additive** — it does not mutate engine state,
- * does not consume engine events the dispatcher needs, and silently
- * no-ops on any failure (logging only). A broken FeatureArc must never
- * break the user's turn.
- */
-
-import { runQuickResponse } from './quick-response.js';
-
-/**
- * Tools that strongly signal "doing real work". Single-file Read and
- * web search are intentionally excluded — they show up in trivial Q&A
- * (one quick lookup, one fact check) and would over-trigger the pill.
- *
- * Codebase grep/glob/find are *included* because they signal multi-file
- * investigation, which is exactly the "this got heavy" mode we want to
- * surface to the user.
- *
- * @type {Set<string>}
- */
-export const KEY_TOOLS = new Set([
-  'Bash',
-  'FileEdit',
-  'FileWrite',
-  'FileCreate',
-  'ApplyPatch',
-  'NotebookEdit',
-  'Agent',
-  'Grep',
-  'Glob',
-  'Find',
-  'JsRepl',
-]);
-
-/** Track-B loop count that on its own counts as "this got heavy". */
-export const FEATURE_TURN_THRESHOLD = 3;
-
-/** Cap title length we store on the Feature. */
-const TITLE_MAX = 60;
-/** Cap summary stored on completion. */
-const SUMMARY_MAX = 600;
-
-/**
- * Build a one-shot system prompt asking the LLM to summarise what it
- * just did in 1–3 sentences. Bilingual.
- *
- * @param {string} language
- */
-function buildSummarySystem(language = 'en') {
-  const isZh = String(language || '').toLowerCase().startsWith('zh');
-  if (isZh) {
-    return [
-      '你刚刚完成了一段工作。请用中文写一条 1–3 句的总结，告诉用户你做了什么、关键结果是什么。',
-      '只输出总结正文，不要 markdown，不要前缀（如「总结：」），不超过 600 字符。',
-    ].join('\n');
-  }
-  return [
-    'You just finished a piece of work. Write a 1–3 sentence summary in English describing what you did and the key outcome.',
-    'Output only the summary prose. No markdown, no leading label like "Summary:", at most 600 characters.',
-  ].join('\n');
-}
-
-/**
- * Drive one summary call. Fails-soft: returns '' on any error.
- *
- * @param {{
- *   adapter: object,
- *   model: string,
- *   prompt: string,           // user's original prompt — supplied as context
- *   assistantText: string,    // joined VP text output for this turn
- *   language?: string,
- *   signal?: AbortSignal,
- * }} args
- * @returns {Promise<string>}
- */
-async function runSummaryCall({ adapter, model, prompt, assistantText, language, signal }) {
-  if (!adapter || typeof adapter.stream !== 'function') return '';
-  if (!model) return '';
-  const text = (assistantText || '').trim();
-  if (!text) return '';
-  const system = buildSummarySystem(language);
-  // We feed the model BOTH the user request and what we said back, so
-  // a summary like "Looked at auth.js, found X, fixed it" is grounded.
-  const userMsg = [
-    'USER REQUEST:',
-    String(prompt || '').slice(0, 4000),
-    '',
-    'WHAT YOU DID / SAID:',
-    text.slice(0, 8000),
-  ].join('\n');
-  try {
-    const parts = [];
-    for await (const evt of adapter.stream({
-      model,
-      system,
-      messages: [{ role: 'user', content: userMsg }],
-      maxTokens: 400,
-      signal,
-    })) {
-      if (evt && evt.type === 'text_delta' && typeof evt.text === 'string') {
-        parts.push(evt.text);
-      } else if (evt && evt.type === 'error') {
-        return '';
-      }
-    }
-    return parts.join('').replace(/\s+/g, ' ').trim().slice(0, SUMMARY_MAX);
-  } catch {
-    return '';
-  }
-}
-
-/**
- * Make a feature title from preview / prompt. Strips trailing
- * punctuation and clamps length.
- */
-function makeTitle({ preview, prompt }) {
-  const src = (preview || prompt || '').replace(/\s+/g, ' ').trim();
-  if (!src) return '(untitled task)';
-  const clipped = src.slice(0, TITLE_MAX);
-  return clipped.replace(/[.!?。！？…]+$/u, '').trim() || clipped;
-}
-
-/**
- * @typedef {Object} FeatureArcEmits
- * @property {(payload:{intent:'quick'|'feature', preview:string})=>void}
- *           [quickPreview]    — Track A finished
- * @property {(payload:{featureId:string, title:string, trigger:'quick'|'turns'|'tool', toolName?:string})=>void}
- *           [featureStarted]  — auto-create fired, frontend should fold
- * @property {(payload:{featureId:string, summary:string, status:'completed'|'aborted'|'error'})=>void}
- *           [featureCompleted] — turn ended, pill becomes done state
- *
- * @typedef {Object} FeatureArcDeps
- * @property {object|null} adapter       — LLMAdapter (session.adapter)
- * @property {string|null} model         — primaryModel
- * @property {object|null} featureStore  — FeatureStore instance (singleton)
- * @property {string} prompt             — user prompt that opened the turn
- * @property {string} vpId
- * @property {string|null} groupId
- * @property {string} turnId
- * @property {string} [vpDisplayName]
- * @property {string} [language]
- * @property {AbortSignal} [signal]
- * @property {FeatureArcEmits} [emit]
- * @property {Set<string>} [keyTools]    — override for tests
- * @property {number} [turnThreshold]    — override for tests
- */
-
-/**
- * Create a per-VP-turn arc tracker. Caller MUST:
- *   - call `arc.startTrackA()` once at the very beginning of runVpTurn
- *     (returns a Promise that backgrounds; do NOT await)
- *   - call `arc.observeEvent(event)` for every engine event before
- *     dispatching it to the existing handleEngineEvent
- *   - call `arc.collectAssistantText(chunk)` whenever a text_delta is
- *     forwarded (lets us seed the summary call without re-aggregating)
- *   - call `await arc.finalize({status})` AFTER the engine query
- *     generator drains, before sending the final 'result'.
- *
- * The arc is opinionated about ordering: featureId is published only
- * once, the first time any signal fires. Subsequent fires are no-ops.
- *
- * @param {FeatureArcDeps} deps
- */
-export function createFeatureArc(deps = {}) {
-  const {
-    adapter = null,
-    model = null,
-    featureStore = null,
-    prompt = '',
-    vpId,
-    groupId = null,
-    turnId,
-    vpDisplayName,
-    language,
-    signal,
-    emit = {},
-    keyTools = KEY_TOOLS,
-    turnThreshold = FEATURE_TURN_THRESHOLD,
-  } = deps;
-
-  let trackAResult = null;            // {intent, preview} | null
-  let trackADone = false;
-  let featureId = null;
-  let featureTitle = null;
-  let assistantText = '';             // accumulated for summary call
-  let loopCount = 0;                  // 'turn_open'/'loop'/'reflection' increments
-  let _finalised = false;
-
-  /** Internal: try to fire the auto-create. Idempotent. */
-  function maybeCreateFeature(signalKind, extra = {}) {
-    // Race guard: Track A is fire-and-forget, so it can resolve AFTER
-    // the engine generator has drained and finalize() has already
-    // closed the arc. Without this guard a late Track A would publish
-    // `feature_started` *after* `feature_completed` (or worse, with
-    // no `feature_completed` at all), leaving a dangling-active pill
-    // on the frontend.
-    if (_finalised) return;
-    if (featureId) return;            // already created
-    if (!featureStore || typeof featureStore.create !== 'function') {
-      // No store — at least publish a synthetic id so the frontend can
-      // still render a pill. Use a deterministic prefix so it's obvious
-      // when something is wrong.
-      featureId = `feat-local-${turnId}`;
-    } else {
-      try {
-        // Use the FULL UUID / random-string. A previous version
-        // sliced to 8 chars (32 bits of entropy) — collisions in a
-        // multi-VP group ingest were observed because the
-        // Date.now()/random fallback's first chars are dominated by
-        // the ms-precision timestamp, so two VPs in the same
-        // millisecond would hash to the same 8-char prefix and the
-        // frontend's featureId-keyed map would silently overwrite.
-        const rand = globalThis.crypto?.randomUUID?.()
-          || (Date.now().toString(36) + Math.random().toString(36).slice(2));
-        const id = `feat-${rand}`;
-        const title = makeTitle({ preview: trackAResult?.preview, prompt });
-        featureTitle = title;
-        const record = {
-          id,
-          title,
-          description: prompt ? prompt.slice(0, 500) : '',
-          priority: 'medium',
-          status: 'in_progress',
-          parentId: null,
-          parentTaskId: null,
-          createdAt: Date.now(),
-          updatedAt: Date.now(),
-        };
-        if (groupId) {
-          record.groupId = groupId;
-          record.members = [vpId];
-          record.initiator = vpId;
-        }
-        featureStore.create(record);
-        featureId = id;
-      } catch (err) {
-        console.warn('[FeatureArc] create failed:', err?.message || err);
-        // Fallback: still publish a synthetic id so the UI gets a pill
-        // (matches the no-store branch above — a broken store should
-        // not silently disable the feature folding UX).
-        featureId = `feat-local-${turnId}`;
-        featureTitle = makeTitle({ preview: trackAResult?.preview, prompt });
-      }
-    }
-    if (typeof emit.featureStarted === 'function') {
-      try {
-        emit.featureStarted({
-          featureId,
-          title: featureTitle || makeTitle({ preview: trackAResult?.preview, prompt }),
-          trigger: signalKind,
-          toolName: extra.toolName,
-        });
-      } catch (err) {
-        console.warn('[FeatureArc] featureStarted emit failed:', err?.message || err);
-      }
-    }
-  }
-
-  /**
-   * Launch Track A in the background. Returns the promise so callers can
-   * await it during shutdown if they need to (tests). In the hot path
-   * runVpTurn fires-and-forgets.
-   */
-  async function startTrackA() {
-    try {
-      const result = await runQuickResponse({
-        adapter,
-        model,
-        prompt,
-        language,
-        vpDisplayName,
-        signal,
-      });
-      trackAResult = result;
-      trackADone = true;
-      if (result && typeof emit.quickPreview === 'function') {
-        try {
-          emit.quickPreview({ intent: result.intent, preview: result.preview });
-        } catch (err) {
-          console.warn('[FeatureArc] quickPreview emit failed:', err?.message || err);
-        }
-      }
-      if (result && result.intent === 'feature') {
-        maybeCreateFeature('quick');
-      }
-    } catch (err) {
-      // runQuickResponse already swallows most things; log + continue.
-      trackADone = true;
-      console.warn('[FeatureArc] Track A failed:', err?.message || err);
-    }
-  }
-
-  /**
-   * Observe one engine event, mutating internal counters and possibly
-   * firing the auto-create. Always called BEFORE the existing
-   * handleEngineEvent dispatch so the featureId is set in time for
-   * the wire envelope to pick it up.
-   *
-   * @param {{type:string, name?:string, text?:string}} event
-   */
-  function observeEvent(event) {
-    if (!event || typeof event !== 'object') return;
-    switch (event.type) {
-      // Only `loop` counts toward the heavy-turn threshold. The engine
-      // emits exactly one `turn_open` per turn (the bookkeeping marker
-      // that the turn started); `loop` is the per-iteration event.
-      // Counting both inflates by one and would cause
-      // FEATURE_TURN_THRESHOLD = 3 to fire after only 2 real loops.
-      case 'loop':
-        loopCount += 1;
-        if (loopCount >= turnThreshold) maybeCreateFeature('turns');
-        break;
-      case 'tool_call':
-        if (event.name && keyTools.has(event.name)) {
-          maybeCreateFeature('tool', { toolName: event.name });
-        }
-        break;
-      case 'text_delta':
-        if (typeof event.text === 'string') {
-          // Soft cap so a runaway VP doesn't balloon memory before
-          // summarisation. 50 KB is enough context for any 1–3 sentence
-          // summary.
-          if (assistantText.length < 50_000) {
-            assistantText += event.text;
-          }
-        }
-        break;
-      default:
-        break;
-    }
-  }
-
-  /**
-   * Run summary + FeatureStore.update. Idempotent. Caller passes a
-   * status hint so we know whether to write 'completed' / 'aborted' /
-   * 'error'.
-   *
-   * @param {{status?:'completed'|'aborted'|'error'}} [opts]
-   */
-  async function finalize(opts = {}) {
-    if (_finalised) return;
-    _finalised = true;
-    if (!featureId) return;           // never escalated; nothing to close
-
-    const status = opts.status || 'completed';
-    let summary = '';
-    if (status === 'completed') {
-      summary = await runSummaryCall({
-        adapter, model, prompt, assistantText, language, signal,
-      });
-    } else if (status === 'aborted') {
-      summary = '(turn aborted)';
-    } else {
-      summary = '(turn ended with error)';
-    }
-
-    if (!summary) {
-      // Fallback to a truncated tail of the assistant text so the pill
-      // is never a blank "✅ — ".
-      summary = (assistantText || '').replace(/\s+/g, ' ').trim().slice(0, 200) || '(no summary)';
-    }
-
-    // Skip the persistence call for synthetic ids — those exist
-    // precisely because the store was unavailable or threw on create,
-    // so any update against them would also throw on the unknown id
-    // (and the catch would silently swallow it). Wire emits still
-    // happen so the frontend gets a consistent close.
-    const isSynthetic = featureId.startsWith('feat-local-');
-    if (!isSynthetic && featureStore && typeof featureStore.update === 'function') {
-      try {
-        featureStore.update(featureId, {
-          status,
-          result: summary,
-        });
-      } catch (err) {
-        console.warn('[FeatureArc] update failed:', err?.message || err);
-      }
-    }
-
-    if (typeof emit.featureCompleted === 'function') {
-      try {
-        emit.featureCompleted({ featureId, summary, status });
-      } catch (err) {
-        console.warn('[FeatureArc] featureCompleted emit failed:', err?.message || err);
-      }
-    }
-  }
-
-  return {
-    startTrackA,
-    observeEvent,
-    finalize,
-    /** Mostly for tests / wire-tagging in the hot path. */
-    getFeatureId: () => featureId,
-    getTitle: () => featureTitle,
-    getTrackAResult: () => trackAResult,
-    isTrackADone: () => trackADone,
-    getLoopCount: () => loopCount,
-  };
-}
-
-// Test seams.
-export const __test = {
-  makeTitle,
-  buildSummarySystem,
-};

package/unify/quick-response.js

@@ -1,229 +0,0 @@
-/**
- * quick-response.js — Track A of the Unify dual-track turn.
- *
- * Purpose
- * -------
- * Run a single, non-looping LLM call against the user prompt that:
- *   1. classifies the turn as `quick` (one-shot reply) vs `feature`
- *      (heavy multi-step work that should be surfaced as a feature pill);
- *   2. emits a short `preview` sentence telling the user what the VP is
- *      about to do (e.g. "I'll grep the auth code, give me a sec").
- *
- * The result feeds the dual-track UI:
- *   - `intent === 'feature'` is one of the three signals that auto-create
- *     a Feature record, collapsing all subsequent VP output into a pill.
- *   - `preview` is rendered as an instant bubble under the user's message
- *     so the user sees something within ~1s, even if the main engine
- *     loop (Track B) takes longer.
- *
- * Properties
- * ----------
- * - **One LLM call**, no tools, no loop. The whole point is to be cheap
- *   and predictable. Uses the same `primaryModel` as the main engine
- *   per design ruling — there is no separate `fastModel` channel.
- * - **Retries once on parse/transport failure** then gives up silently.
- *   A failed Track A is fine: signals 2 (≥3 turns) and 3 (key tool)
- *   still pick up real heavy turns.
- * - **Hard timeout** of 8s wall-clock. Track B must not be held back
- *   waiting on Track A.
- *
- * Wire shape — what we emit to the frontend
- * -----------------------------------------
- * On success:
- *     { type: 'quick_preview', vpId, turnId, intent, preview }
- *
- * The preview is plain text, ≤ 140 chars, in the user's language.
- *
- * Failure mode
- * ------------
- * Returns `null`. Caller MUST tolerate this and not block on the result.
- */
-
-const QUICK_TIMEOUT_MS = 8000;
-const PREVIEW_MAX_CHARS = 140;
-const QUICK_MAX_TOKENS = 300;
-
-/**
- * Compose the system prompt that asks the LLM for a structured
- * intent + preview. Bilingual to match the rest of Unify.
- *
- * @param {{ language?: string, vpDisplayName?: string }} opts
- * @returns {string}
- */
-function buildQuickSystem({ language = 'en', vpDisplayName = 'assistant' } = {}) {
-  const isZh = String(language || '').toLowerCase().startsWith('zh');
-  if (isZh) {
-    return [
-      `你正在以「${vpDisplayName}」的身份做一次极简的"先回声"判断。这不是真正的回答，主回答会由另一条线并发产出。`,
-      '',
-      '只输出一行 JSON，不要 markdown、不要 ```、不要前后空行：',
-      '{"intent":"quick"|"feature","preview":"<不超过 80 个字符的中文，告诉用户你打算做什么>"}',
-      '',
-      'intent 规则：',
-      '- "quick"：用户是寒暄、问事实、要一句话答案，预计一次回复就够。',
-      '- "feature"：需要查代码 / 改文件 / 调 bash / 跑测试 / 多步推理，预计要折腾若干轮。',
-      '',
-      'preview 规则：',
-      '- 用第一人称简短陈述「我去做什么」，例如：「我去看看 auth 模块再回你」。',
-      '- 不要承诺结果，不要复述用户的话。',
-      '- 不要带表情、不要带 markdown。',
-    ].join('\n');
-  }
-  return [
-    `You are "${vpDisplayName}" giving a one-shot pre-reply. This is NOT the real answer; the real answer is being produced concurrently on another track.`,
-    '',
-    'Output ONE line of strict JSON, no markdown, no fences, no leading/trailing whitespace:',
-    '{"intent":"quick"|"feature","preview":"<at most 80 chars telling the user what you are about to do>"}',
-    '',
-    'intent rules:',
-    '- "quick": small talk / factual lookup / single-sentence answer.',
-    '- "feature": needs code reading, file edits, bash, tests, or multi-step reasoning.',
-    '',
-    'preview rules:',
-    '- First-person, short. Example: "Let me grep the auth module and get back to you."',
-    '- Do NOT promise outcomes. Do NOT echo the user.',
-    '- No emoji, no markdown.',
-  ].join('\n');
-}
-
-/**
- * Robust JSON extraction. Models occasionally wrap output in fences or
- * leading prose despite instructions; we accept any single JSON object
- * we can find.
- *
- * @param {string} raw
- * @returns {{intent:string, preview:string}|null}
- */
-function parseQuickJson(raw) {
-  if (typeof raw !== 'string') return null;
-  let s = raw.trim();
-  if (!s) return null;
-  // Strip ``` fences if present.
-  if (s.startsWith('```')) {
-    s = s.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
-  }
-  // First-pass direct parse.
-  let obj = null;
-  try { obj = JSON.parse(s); } catch { /* fall through */ }
-  // Second-pass: locate first `{` and last `}`.
-  if (!obj) {
-    const i = s.indexOf('{');
-    const j = s.lastIndexOf('}');
-    if (i >= 0 && j > i) {
-      try { obj = JSON.parse(s.slice(i, j + 1)); } catch { /* nope */ }
-    }
-  }
-  if (!obj || typeof obj !== 'object') return null;
-  const intent = obj.intent === 'feature' ? 'feature' : 'quick';
-  const previewRaw = typeof obj.preview === 'string' ? obj.preview : '';
-  const preview = previewRaw.replace(/\s+/g, ' ').trim().slice(0, PREVIEW_MAX_CHARS);
-  if (!preview) return null; // a preview-less response is useless
-  return { intent, preview };
-}
-
-/**
- * Drive the adapter once. Collects text deltas, returns the assembled
- * raw string. Throws on adapter error / abort / timeout.
- *
- * @param {object} adapter — LLMAdapter instance with .stream()
- * @param {object} args    — { model, system, messages, signal }
- * @returns {Promise<string>}
- */
-async function callOnce(adapter, args) {
-  const parts = [];
-  for await (const event of adapter.stream(args)) {
-    if (!event || typeof event !== 'object') continue;
-    if (event.type === 'text_delta' && typeof event.text === 'string') {
-      parts.push(event.text);
-    } else if (event.type === 'error') {
-      throw event.error || new Error('adapter stream error');
-    }
-    // tool_call / thinking_delta / usage / stop are ignored; we
-    // explicitly do not pass any tools to the adapter.
-  }
-  return parts.join('');
-}
-
-/**
- * Run Track A. One adapter call, retry-once on failure, hard 8s deadline.
- *
- * @param {{
- *   adapter: object,
- *   model: string,
- *   prompt: string,
- *   language?: string,
- *   vpDisplayName?: string,
- *   signal?: AbortSignal,
- * }} args
- * @returns {Promise<{intent:'quick'|'feature', preview:string}|null>}
- */
-export async function runQuickResponse({
-  adapter,
-  model,
-  prompt,
-  language,
-  vpDisplayName,
-  signal,
-} = {}) {
-  if (!adapter || typeof adapter.stream !== 'function') return null;
-  if (typeof prompt !== 'string' || !prompt.trim()) return null;
-  if (!model) return null;
-
-  // Composite signal: caller's abort OR our timeout, whichever fires first.
-  const ctrl = new AbortController();
-  const onCallerAbort = () => ctrl.abort();
-  if (signal) {
-    if (signal.aborted) return null;
-    signal.addEventListener('abort', onCallerAbort, { once: true });
-  }
-  const timer = setTimeout(() => ctrl.abort(), QUICK_TIMEOUT_MS);
-
-  const system = buildQuickSystem({ language, vpDisplayName });
-  const messages = [{ role: 'user', content: prompt }];
-  const callArgs = {
-    model,
-    system,
-    messages,
-    maxTokens: QUICK_MAX_TOKENS,
-    signal: ctrl.signal,
-  };
-
-  try {
-    // Attempt 1.
-    let raw = '';
-    try {
-      raw = await callOnce(adapter, callArgs);
-    } catch (err) {
-      // Abort or external error — exit silently. Don't retry on abort.
-      if (err && (err.name === 'AbortError' || err.name === 'LLMAbortError')) return null;
-      // Otherwise fall through to retry.
-      raw = '';
-    }
-    let parsed = raw ? parseQuickJson(raw) : null;
-
-    if (!parsed) {
-      // Attempt 2 (retry once). Reuse the same args; adapter is stateless.
-      if (ctrl.signal.aborted) return null;
-      try {
-        const raw2 = await callOnce(adapter, callArgs);
-        parsed = raw2 ? parseQuickJson(raw2) : null;
-      } catch {
-        parsed = null;
-      }
-    }
-
-    return parsed;
-  } finally {
-    clearTimeout(timer);
-    if (signal) signal.removeEventListener('abort', onCallerAbort);
-  }
-}
-
-// Test seams — exported so tests can exercise pure helpers without
-// spinning up an adapter.
-export const __test = {
-  parseQuickJson,
-  buildQuickSystem,
-  QUICK_TIMEOUT_MS,
-  PREVIEW_MAX_CHARS,
-};