@yeaft/webchat-agent 0.1.709 → 0.1.711

package/package.json

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

package/unify/feature-arc.js

@@ -0,0 +1,437 @@
+/**
+ * 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

@@ -0,0 +1,229 @@
+/**
+ * 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,
+};

package/unify/web-bridge.js

@@ -51,6 +51,8 @@ import {
   compactHistory,
   trimSnapshotForBudget,
 } from './history-compact.js';
+import { createFeatureArc } from './feature-arc.js';
+import { getFeatureStore } from './tools/feature-tools.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -492,25 +494,27 @@ 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 } = {}) {
+function sendUnifyOutput(data, { groupId, vpId, turnId, featureId } = {}) {
   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 } = {}) {
+function sendUnifyEvent(event, { groupId, vpId, turnId, featureId } = {}) {
   sendToServer({
     type: 'unify_output',
     conversationId: unifyConversationId,
     ...(groupId ? { groupId } : {}),
     ...(vpId ? { vpId } : {}),
     ...(turnId ? { turnId } : {}),
+    ...(featureId ? { featureId } : {}),
     event,
   });
 }
@@ -871,7 +875,16 @@ export function installUnifyRuntimeBridge(s) {
  */
 function handleEngineEvent(event, hctx) {
   hctx.resetQueryTimer();
-  const envelope = { groupId: hctx.groupId, vpId: hctx.vpId, turnId: hctx.turnId };
+  // 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;
+  const envelope = {
+    groupId: hctx.groupId,
+    vpId: hctx.vpId,
+    turnId: hctx.turnId,
+    ...(featureId ? { featureId } : {}),
+  };
 
   switch (event.type) {
     case 'text_delta':
@@ -1572,6 +1585,11 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
   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) {
@@ -1611,6 +1629,63 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
         groupId,
         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();
+
       const handlerCtx = {
         assistantTextParts,
         toolCallsAccum,
@@ -1619,6 +1694,9 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
         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
@@ -1635,12 +1713,26 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
         ...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: [] },
@@ -1655,6 +1747,9 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
   } 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: '',
@@ -1664,6 +1759,7 @@ async function runVpTurn({ prompt, groupId, vpId, turnId, envelope: inboundEnvel
     }
 
     console.error('[Unify] query error:', err);
+    try { await arc?.finalize?.({ status: 'error' }); } catch { /* ignore */ }
 
     if (isPermissionErrorMsg(err.message)) {
       if (!_permissionDiagnosticSent) {