mixdog 0.9.2 → 0.9.4

package/src/tui/engine/notification-plan.mjs

@@ -0,0 +1,76 @@
+/**
+ * src/tui/engine/notification-plan.mjs - pure runtime.onNotification delivery plan.
+ *
+ * Extracted from engine.mjs (no behavior change). These are stateless helpers
+ * that decide how a runtime notification envelope should be delivered to the
+ * TUI store (dedupe key + display/model routing). No closures over engine state.
+ */
+import {
+  isStatusOnlyAgentCompletionNotification,
+  parseAgentJob,
+  parseAgentResultEnvelope,
+  parseBackgroundTaskEnvelope,
+  parseSyntheticAgentMessage,
+} from './agent-envelope.mjs';
+import { shortTextFingerprint } from './queue-helpers.mjs';
+import { modelVisibleToolCompletionMessage } from '../../runtime/shared/tool-execution-contract.mjs';
+
+export function notificationQueueKey(event, text, parsed) {
+  const meta = event?.meta && typeof event.meta === 'object' ? event.meta : {};
+  const synthetic = parseSyntheticAgentMessage(text);
+  if (synthetic?.name === 'agent' && String(synthetic.args?.type || '').toLowerCase() === 'result') {
+    const taskId = String(synthetic.args?.task_id || '').trim();
+    const executionId = String(meta.execution_id || '').trim();
+    const tag = String(synthetic.args?.tag || '').trim();
+    const resultId = taskId
+      ? `task:${taskId}`
+      : executionId
+        ? `exec:${executionId}`
+        : tag
+          ? `tag:${tag}:${shortTextFingerprint(synthetic.result || text)}`
+          : '';
+    const agent = String(synthetic.args?.agent || '').trim();
+    if (resultId || agent) return ['agent-result', resultId, agent].filter(Boolean).join(':');
+  }
+  const id = String(meta.execution_id || parsed?.taskId || '').trim();
+  if (!id) return '';
+  const type = String(meta.type || '').trim();
+  const status = String(meta.status || parsed?.status || '').trim();
+  const fallbackKind = String(text || '').split('\n', 1)[0]?.trim() || 'notification';
+  // Distinguish a body-carrying completion from a header-only preview that
+  // shares the same id/type/status. An early agent preview can arrive before
+  // the session is persisted (no result body); the canonical notification that
+  // follows DOES carry the body. Without this dimension the bodyless preview
+  // would claim the dedupe key and suppress the real result. A blank-line gap
+  // separates the task header block from the result body in the envelope.
+  const hasBody = /\n\s*\n[\s\S]*\S/.test(String(text || '')) ? 'b1' : 'b0';
+  return [id, type || fallbackKind, status, hasBody].filter(Boolean).join(':');
+}
+
+export function isExecutionNotification(event, text, parsed) {
+  const meta = event?.meta && typeof event.meta === 'object' ? event.meta : {};
+  if (meta.execution_id || meta.execution_surface) return true;
+  if (parseAgentResultEnvelope(text)) return true;
+  if (parseBackgroundTaskEnvelope(text)) return true;
+  return Boolean(parsed?.taskId && /^(?:agent task:|task_id:)/mi.test(String(text || '')));
+}
+
+/** Pure delivery plan for runtime.onNotification execution envelopes (tests + handler). */
+export function resolveTuiRuntimeNotificationDelivery(event, text) {
+  const trimmed = String(text ?? '').trim();
+  if (!trimmed) return { action: 'ignore' };
+  const parsed = parseAgentJob(trimmed);
+  const meta = event?.meta && typeof event.meta === 'object' ? event.meta : {};
+  if (!isExecutionNotification(event, trimmed, parsed)) {
+    return { action: 'enqueue', displayText: trimmed, modelContent: trimmed };
+  }
+  if (isStatusOnlyAgentCompletionNotification(trimmed)) {
+    return { action: 'status-only', displayText: trimmed, modelContent: '' };
+  }
+  const modelContent = modelVisibleToolCompletionMessage(trimmed, meta);
+  return {
+    action: 'execution-ui',
+    displayText: trimmed,
+    modelContent,
+  };
+}

package/src/tui/engine/queue-helpers.mjs

@@ -0,0 +1,161 @@
+/**
+ * src/tui/engine/queue-helpers.mjs - pure helpers for the prompt/notification
+ * queue: priority ordering, entry visibility/editability, prompt content
+ * flattening, session activity timestamps, and batch merging. Extracted from
+ * engine.mjs.
+ */
+import {
+  agentJobResultText,
+  parseAgentJob,
+  parseSyntheticAgentMessage,
+} from './agent-envelope.mjs';
+
+const QUEUE_PRIORITY = { now: 0, next: 1, later: 2 };
+
+export function queuePriorityValue(value) {
+  return QUEUE_PRIORITY[String(value || 'next')] ?? QUEUE_PRIORITY.next;
+}
+
+export function defaultQueuePriority(mode) {
+  // Queue priority defaults:
+  // - user/bashed prompt input defaults to `next`, so it can be attached at the
+  //   next model-send boundary while a turn is active.
+  // - task notifications default to `later`, unless the caller explicitly marks
+  //   them urgent (e.g. interactive shell stall/completion).
+  return mode === 'task-notification' ? 'later' : 'next';
+}
+
+export function isQueuedEntryEditable(entry) {
+  const mode = entry?.mode || 'prompt';
+  return mode !== 'task-notification' && mode !== 'pending-resume';
+}
+
+export function isQueuedEntryVisible(entry) {
+  // state.queued drives the user-command wait list above the prompt. Background
+  // task completions stay in the internal pending queue, but should never look
+  // like commands typed by the user while they wait to be drained.
+  const mode = entry?.mode || 'prompt';
+  if (mode === 'pending-resume') return false;
+  return isQueuedEntryEditable(entry);
+}
+
+export function isSlashQueuedEntry(entry) {
+  if (entry?.skipSlashCommands) return false;
+  const text = promptContentText(entry?.content ?? entry?.text ?? '');
+  return text.trim().startsWith('/');
+}
+
+export function firstQueueLine(text) {
+  return String(text || '').split('\n').map((line) => line.trim()).find(Boolean) || '';
+}
+
+export function shortTextFingerprint(text) {
+  const value = String(text || '').trim();
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+export function notificationDisplayText(text) {
+  const parsed = parseAgentJob(text);
+  const result = agentJobResultText(text, parsed);
+  const synthetic = parseSyntheticAgentMessage(text);
+  return firstQueueLine(synthetic?.result || result || text) || 'agent notification';
+}
+
+export function promptContentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((part) => {
+      if (typeof part === 'string') return part;
+      if (part?.type === 'text') return part.text || '';
+      if (part?.type === 'image') return '[Image]';
+      return part?.text || '';
+    }).filter(Boolean).join('\n');
+  }
+  return String(content ?? '');
+}
+
+export function timestampMs(value) {
+  if (value == null || value === '') return 0;
+  const n = Number(value);
+  if (Number.isFinite(n) && n > 0) return n;
+  const parsed = Date.parse(String(value));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+
+export function hasModelVisibleConversation(session) {
+  const messages = Array.isArray(session?.messages) ? session.messages : [];
+  return messages.some((message) => {
+    const role = message?.role;
+    if (role !== 'user' && role !== 'assistant' && role !== 'tool') return false;
+    const text = promptContentText(message.content).trim();
+    if (role === 'user' && text.startsWith('<system-reminder>')) return false;
+    if (role === 'assistant' && text === '.' && !Array.isArray(message.toolCalls)) return false;
+    return !!text || role === 'assistant' || role === 'tool';
+  });
+}
+
+export function sessionActivityTimestamp(session, fallback = 0) {
+  if (!hasModelVisibleConversation(session)) return 0;
+  return timestampMs(session?.lastUsedAt)
+    || timestampMs(session?.updatedAt)
+    || timestampMs(fallback);
+}
+
+export function promptDisplayText(content, options = {}) {
+  if (typeof options.displayText === 'string') return options.displayText;
+  return promptContentText(content);
+}
+
+export function mergePromptContents(entries) {
+  const batch = Array.isArray(entries) ? entries : [];
+  if (batch.every((entry) => typeof entry?.content === 'string')) {
+    return batch.map((entry) => entry.content).filter((text) => String(text || '').trim()).join('\n');
+  }
+  const parts = [];
+  for (const entry of batch) {
+    const content = entry?.content;
+    if (typeof content === 'string') {
+      if (content.trim()) parts.push({ type: 'text', text: content });
+    } else if (Array.isArray(content)) {
+      parts.push(...content);
+    }
+    parts.push({ type: 'text', text: '\n' });
+  }
+  while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
+  return parts.length === 1 && parts[0]?.type === 'text' ? parts[0].text : parts;
+}
+
+export function mergePastedImages(entries) {
+  const out = {};
+  for (const entry of entries || []) {
+    const images = entry?.pastedImages;
+    if (!images || typeof images !== 'object') continue;
+    for (const [id, image] of Object.entries(images)) {
+      if (image) out[id] = image;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function mergePastedTexts(entries) {
+  const out = {};
+  for (const entry of entries || []) {
+    const texts = entry?.pastedTexts;
+    if (!texts || typeof texts !== 'object') continue;
+    for (const [id, text] of Object.entries(texts)) {
+      if (text) out[id] = text;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function callCommitCallbacks(entries) {
+  for (const entry of entries || []) {
+    try { entry?.onCommitted?.(); } catch {}
+  }
+}

package/src/tui/engine/render-timing.mjs

@@ -0,0 +1,17 @@
+/**
+ * src/tui/engine/render-timing.mjs - render-throttle timing helper.
+ *
+ * Extracted from engine.mjs (no behavior change).
+ *
+ * Ink renders through a maxFps throttle (120fps in index.jsx, ≈8.3ms). A plain
+ * setImmediate only yields to the event loop; if Ink already painted within the
+ * current throttle window, the next paint may still be queued and our following
+ * transcript mutation can coalesce into the same visible frame. Wait just past
+ * one render window when we intentionally split transcript commits for visual
+ * stability (preamble frame → tool-card frame).
+ */
+export const RENDER_THROTTLE_FLUSH_MS = 12;
+
+export const yieldToRenderer = () => new Promise((resolve) => {
+  setTimeout(resolve, RENDER_THROTTLE_FLUSH_MS);
+});

package/src/tui/engine/session-stats.mjs

@@ -0,0 +1,46 @@
+/**
+ * src/tui/engine/session-stats.mjs - session-usage accumulator.
+ *
+ * Inlined (not imported from ui/statusline.mjs) so the engine has no static
+ * dependency on the vendored statusline closure. Extracted from engine.mjs.
+ */
+export function createSessionStats() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cachedTokens: 0,
+    cacheWriteTokens: 0,
+    promptTokens: 0,
+    latestInputTokens: 0,
+    latestOutputTokens: 0,
+    latestCachedTokens: 0,
+    latestCacheWriteTokens: 0,
+    latestPromptTokens: 0,
+    currentContextTokens: 0,
+    costUsd: 0,
+    turns: 0,
+  };
+}
+
+function num(v) { const n = Number(v); return Number.isFinite(n) ? n : 0; }
+
+export function applyUsageDelta(stats, delta = {}) {
+  if (!stats || !delta) return stats;
+  const inputTokens = num(delta.deltaInput);
+  const outputTokens = num(delta.deltaOutput);
+  const cachedTokens = num(delta.deltaCachedRead);
+  const cacheWriteTokens = num(delta.deltaCacheWrite);
+  const promptTokens = num(delta.deltaPrompt);
+  stats.inputTokens += inputTokens;
+  stats.outputTokens += outputTokens;
+  stats.cachedTokens += cachedTokens;
+  stats.cacheWriteTokens += cacheWriteTokens;
+  stats.promptTokens += promptTokens;
+  stats.latestInputTokens = inputTokens;
+  stats.latestOutputTokens = outputTokens;
+  stats.latestCachedTokens = cachedTokens;
+  stats.latestCacheWriteTokens = cacheWriteTokens;
+  stats.latestPromptTokens = promptTokens;
+  stats.costUsd += num(delta.costUsd);
+  return stats;
+}

package/src/tui/engine/tool-approval.mjs

@@ -0,0 +1,94 @@
+/**
+ * src/tui/engine/tool-approval.mjs — tool-approval queue plumbing extracted
+ * from createEngineSession (engine.mjs) as a dependency-injection factory.
+ *
+ * These handlers drive a small FIFO of hook approval requests and reflect the
+ * active one into store state (state.toolApproval). They need live session
+ * state, so the closure identifiers (state/set/nextId/disposed/timeout) are
+ * threaded through the factory argument via getters — never stale snapshots.
+ * Every body is the original engine.mjs logic verbatim.
+ */
+export function createToolApproval({ getState, set, nextId, getDisposed, timeoutMs }) {
+  const toolApprovalQueue = [];
+  let activeToolApproval = null;
+
+  function normalizeToolApprovalRequest(input = {}, id = nextId()) {
+    const now = Date.now();
+    const requestTimeoutMs = timeoutMs;
+    return {
+      id,
+      name: String(input?.name || input?.tool_name || 'tool'),
+      args: input?.args ?? input?.tool_input ?? null,
+      cwd: input?.cwd || null,
+      sessionId: input?.sessionId || input?.session_id || null,
+      toolCallId: input?.toolCallId || input?.tool_use_id || null,
+      reason: String(input?.reason || input?.message || 'approval requested by hook').trim(),
+      requestedAt: now,
+      timeoutMs: requestTimeoutMs,
+      expiresAt: now + requestTimeoutMs,
+    };
+  }
+  function presentNextToolApproval() {
+    if (activeToolApproval || getDisposed()) return;
+    const entry = toolApprovalQueue.shift();
+    if (!entry) {
+      if (getState().toolApproval) set({ toolApproval: null });
+      return;
+    }
+    activeToolApproval = entry;
+    entry.timer = setTimeout(() => {
+      finishToolApproval(entry.id, false, 'approval timed out');
+    }, entry.request.timeoutMs);
+    entry.timer.unref?.();
+    set({ toolApproval: entry.request });
+  }
+  function finishToolApproval(id, approved, reason = '') {
+    const targetId = String(id || '');
+    if (activeToolApproval && activeToolApproval.id === targetId) {
+      const entry = activeToolApproval;
+      activeToolApproval = null;
+      if (entry.timer) clearTimeout(entry.timer);
+      set({ toolApproval: null });
+      try { entry.resolve({ approved: approved === true, reason: String(reason || '') }); } catch {}
+      presentNextToolApproval();
+      return true;
+    }
+    const index = toolApprovalQueue.findIndex((entry) => entry.id === targetId);
+    if (index >= 0) {
+      const [entry] = toolApprovalQueue.splice(index, 1);
+      if (entry?.timer) clearTimeout(entry.timer);
+      try { entry.resolve({ approved: approved === true, reason: String(reason || '') }); } catch {}
+      return true;
+    }
+    return false;
+  }
+  function denyAllToolApprovals(reason = 'approval cancelled') {
+    if (activeToolApproval) {
+      const entry = activeToolApproval;
+      activeToolApproval = null;
+      if (entry.timer) clearTimeout(entry.timer);
+      try { entry.resolve({ approved: false, reason }); } catch {}
+    }
+    while (toolApprovalQueue.length > 0) {
+      const entry = toolApprovalQueue.shift();
+      if (entry?.timer) clearTimeout(entry.timer);
+      try { entry.resolve({ approved: false, reason }); } catch {}
+    }
+    if (getState().toolApproval) set({ toolApproval: null });
+  }
+  function requestToolApproval(input = {}) {
+    if (getDisposed()) return Promise.resolve({ approved: false, reason: 'runtime disposed' });
+    return new Promise((resolve) => {
+      const id = nextId();
+      toolApprovalQueue.push({ id, request: normalizeToolApprovalRequest(input, id), resolve, timer: null });
+      presentNextToolApproval();
+    });
+  }
+
+  return {
+    presentNextToolApproval,
+    finishToolApproval,
+    denyAllToolApprovals,
+    requestToolApproval,
+  };
+}

package/src/tui/engine/tool-call-fields.mjs

@@ -0,0 +1,23 @@
+/**
+ * src/tui/engine/tool-call-fields.mjs - accessors for the varied tool-call /
+ * tool-result id/name/arg shapes across providers. Extracted from engine.mjs.
+ */
+export function toolCallId(call) {
+  return call?.id ?? call?.toolCallId ?? call?.tool_call_id ?? call?.call_id;
+}
+
+export function toolResultCallId(message) {
+  return message?.toolCallId
+    ?? message?.tool_call_id
+    ?? message?.tool_use_id
+    ?? message?.call_id
+    ?? message?.id;
+}
+
+export function toolCallName(call) {
+  return call?.name ?? call?.function?.name ?? call?.toolName ?? call?.tool_name ?? 'tool';
+}
+
+export function toolCallArgs(call) {
+  return call?.arguments ?? call?.args ?? call?.input ?? call?.function?.arguments;
+}

package/src/tui/engine/tool-card-results.mjs

@@ -0,0 +1,234 @@
+/**
+ * src/tui/engine/tool-card-results.mjs — the tool-card result state machine
+ * (patchToolCardResult + flushToolResults) extracted from createEngineSession
+ * (engine.mjs) as a dependency-injection factory.
+ *
+ * These handlers own the per-turn accounting that reflects tool results into
+ * store items: aggregate cards, non-aggregate/legacy agent-job cards, grouped
+ * fallbacks, and the finalize/cancelled sweeps. They mutate live session state,
+ * so state/set/patchItem/markToolCallDone/updateAgentJobCard are threaded via
+ * the factory argument (getters/callbacks) — never stale snapshots. Every body
+ * is the original engine.mjs logic verbatim.
+ */
+import { summarizeToolResult } from '../../runtime/shared/tool-surface.mjs';
+import { toolResultText, toolErrorDisplay, toolGroupedDisplayFallback } from './tool-result-text.mjs';
+import { toolResultCallId } from './tool-call-fields.mjs';
+import { parseAgentJob, agentArgsWithResultMetadata, toolResultStatus, isErrorToolStatus } from './agent-envelope.mjs';
+import {
+  withCancelledResultMarker,
+  groupedToolResultText,
+  aggregateRawResult,
+  aggregateSummaries,
+  assignAggregateSummaryOrder,
+} from './tool-result-status.mjs';
+import { formatAggregateDetail } from '../../runtime/shared/tool-surface.mjs';
+
+export function createToolCardResults({
+  getState,
+  set,
+  patchItem,
+  markToolCallDone,
+  updateAgentJobCard,
+  agentStatusState,
+}) {
+  function patchToolCardResult(card, message, toolGroups, done) {
+    if (!card || card.done) return false;
+    const callId = toolResultCallId(message) || card.callId;
+    if (callId && done.has(callId)) return false;
+    // Any resolving call clears its active-summary entry (keyed by the same
+    // callKey used at markToolCallActive; card.callId holds it for both branches).
+    markToolCallDone(card.callId);
+    // A result for this card arrived (possibly before its deferred push delay
+    // elapsed) — surface the card now so the patch below has a live item and the
+    // fast tool paints a completed card directly, no pending placeholder stage.
+    // ensureVisible flushes this card AND every earlier-created still-deferred
+    // card in order, so transcript order always matches call order.
+    (card.aggregate?.ensureVisible || card.ensureVisible)?.();
+    const rawText = toolResultText(message?.content);
+    const isError = message?.isError === true || message?.toolKind === 'error' || /^\s*\[?error/i.test(rawText) || isErrorToolStatus(toolResultStatus(rawText));
+    const text = isError ? toolErrorDisplay(rawText, card?.name || 'tool') : rawText;
+
+    // Aggregate card handling — collect semantic summaries per call
+    const aggregate = card.aggregate;
+    if (aggregate && card.itemId === aggregate.itemId) {
+      const callRec = callId ? aggregate.calls.get(callId) : null;
+      if (!callRec) return false;
+      if (callRec.resolved) {
+        card.done = true;
+        if (callId) done.add(callId);
+        return false;
+      }
+      callRec.summary = !isError ? summarizeToolResult(callRec.name, callRec.args, rawText, isError) : null;
+      assignAggregateSummaryOrder(aggregate, callRec);
+      callRec.isError = isError;
+      callRec.resultText = text;
+      callRec.resolved = true;
+      const allCalls = [...aggregate.calls.values()];
+      const completed = allCalls.filter((r) => r.resolved).length;
+      const errors = allCalls.filter((r) => r.isError).length;
+      // Collapsed detail carries the merged per-call count summary
+      // ("512 lines, 6 matches, 3 files") so the finished card answers "how
+      // much" without ctrl+o. Failures keep a bare 'N Ok · N Failed' status so
+      // an error stays visible while collapsed.
+      const succeeded = completed - errors;
+      const detailText = errors > 0
+        ? (succeeded > 0 ? `${succeeded} Ok · ${errors} Failed` : `${errors} Failed`)
+        : formatAggregateDetail(aggregateSummaries(aggregate));
+      const currentItem = getState().items.find((it) => it.id === card.itemId);
+      const earlyCompleted = allCalls.filter((r) => r.resolved || r.completedEarly).length;
+      const visualCompleted = Math.max(completed, earlyCompleted, Math.min(allCalls.length, Number(currentItem?.completedCount || 0)));
+      const rawResult = aggregateRawResult(allCalls);
+      // The numbered+labelled raw (rawResult) is preserved for ctrl+o expansion.
+      const displayDetail = detailText;
+      patchItem(card.itemId, {
+        result: displayDetail,
+        text: displayDetail,
+        rawResult: rawResult || null,
+        isError: errors > 0,
+        errorCount: errors,
+        count: allCalls.length,
+        completedCount: visualCompleted,
+        completedAt: Number(currentItem?.completedAt) || Date.now(),
+      });
+      card.done = true;
+      if (callId) done.add(callId);
+      return true;
+    }
+
+    // Non-aggregate (legacy agent-job cards, etc.)
+    const group = toolGroups.get(card.itemId) || { count: 1, completed: 0, errors: 0, results: [] };
+    group.completed = Math.min(group.count, group.completed + 1);
+    group.errors += isError ? 1 : 0;
+    group.results.push({ text, isError });
+    toolGroups.set(card.itemId, group);
+    const resultText = groupedToolResultText(group);
+    const displayResult = toolGroupedDisplayFallback(resultText, text, rawText);
+    const patch = {
+      result: displayResult,
+      text: displayResult,
+      isError: group.errors > 0,
+      errorCount: group.errors,
+      count: group.count,
+      completedCount: group.completed,
+      completedAt: Date.now(),
+    };
+    if (group.count <= 1) {
+      const body = String(text || rawText || '').trim();
+      if (body) patch.rawResult = text || rawText;
+      const parsedAgent = parseAgentJob(rawText);
+      if (parsedAgent) {
+        patch.args = agentArgsWithResultMetadata(getState().items.find((it) => it.id === card.itemId)?.args, parsedAgent);
+        set(agentStatusState({ force: true }));
+      }
+    }
+    patchItem(card.itemId, patch);
+    if (group.count <= 1) updateAgentJobCard(card.itemId, rawText, isError);
+    card.done = true;
+    if (callId) done.add(callId);
+    return true;
+  }
+
+  const flushToolResults = (messages, toolCards, cardByCallId, toolGroups, done, { finalize = false, cancelled = false } = {}) => {
+    const results = [];
+    for (const m of messages || []) {
+      if (!m || m.role !== 'tool') continue;
+      const callId = toolResultCallId(m);
+      results.push({ message: m, callId, used: false });
+      if (!callId || done.has(callId)) continue;
+      const card = cardByCallId.get(callId);
+      if (patchToolCardResult(card, m, toolGroups, done)) {
+        results[results.length - 1].used = true;
+      }
+    }
+
+    const openCards = (toolCards || []).filter((card) => !card.done);
+    if (openCards.length === 0) return;
+
+    const unusedResults = results.filter((result) => !result.used);
+    const fallbackResults = unusedResults.slice(-openCards.length);
+    for (let i = 0; i < fallbackResults.length; i++) {
+      const card = openCards[i];
+      const result = fallbackResults[i];
+      if (!card || !result || card.done) continue;
+      if (patchToolCardResult(card, result.message, toolGroups, done)) {
+        if (result.callId) done.add(result.callId);
+        result.used = true;
+      }
+    }
+
+    if (!finalize) return;
+    for (const card of toolCards || []) {
+      if (card.done) continue;
+      // Finalize must surface any still-deferred card before patching its result
+      // so the completed/cancelled card is never silently dropped.
+      (card.aggregate?.ensureVisible || card.ensureVisible)?.();
+      // Aggregate finalize — mark any remaining calls as done
+      const aggregate = card.aggregate;
+      if (aggregate && card.itemId === aggregate.itemId) {
+        const allCalls = [...aggregate.calls.values()];
+        // Never let a call that truly never resolved be presented as a real
+        // completion. Stamp it resolved so completedCount reflects an honest
+        // (if degenerate) accounting instead of manufacturing success out of
+        // a call that never came back. A record already marked completedEarly
+        // (via __earlyNotify) already carries a real isError/resultText/summary
+        // from its actual result — preserve those; only blank-fill for calls
+        // truly never heard from (no completedEarly, no resolved).
+        for (const rec of allCalls) {
+          if (rec.resolved) continue;
+          rec.resolved = true;
+          if (!rec.completedEarly) {
+            rec.isError = false;
+            rec.resultText = rec.resultText || '';
+          }
+        }
+        const completed = allCalls.filter((r) => r.resolved).length;
+        const totalCompleted = completed;
+        const errors = allCalls.filter((r) => r.isError).length;
+        const succeeded = completed - errors;
+        const rawResult = aggregateRawResult(allCalls);
+        // Collapsed detail carries the merged per-call count summary; failures
+        // keep a bare 'N Ok · N Failed' status. Raw is kept for ctrl+o.
+        let displayDetail = errors > 0
+          ? (succeeded > 0 ? `${succeeded} Ok · ${errors} Failed` : `${errors} Failed`)
+          : formatAggregateDetail(aggregateSummaries(aggregate));
+        if (cancelled) {
+          // Cancelled aggregates MUST keep the [status: cancelled] marker on the
+          // result so terminalStatus parsing resolves to 'cancelled'. Only normal
+          // completions drop the summary; cancelled ones prepend the marker.
+          const currentItem = getState().items.find((it) => it.id === card.itemId);
+          displayDetail = withCancelledResultMarker(displayDetail, currentItem);
+        }
+        patchItem(card.itemId, {
+          result: displayDetail,
+          text: displayDetail,
+          rawResult: rawResult || null,
+          isError: errors > 0,
+          errorCount: errors,
+          count: allCalls.length,
+          completedCount: totalCompleted,
+          completedAt: Date.now(),
+        });
+        for (const sibling of toolCards || []) {
+          if (sibling.itemId !== card.itemId) continue;
+          sibling.done = true;
+          if (sibling.callId) done.add(sibling.callId);
+        }
+        continue;
+      }
+      // Non-aggregate finalize
+      const group = toolGroups.get(card.itemId) || { count: 1, completed: 0, errors: 0, results: [] };
+      group.completed = Math.min(group.count, group.completed + 1);
+      toolGroups.set(card.itemId, group);
+      let resultText = groupedToolResultText(group);
+      if (cancelled) {
+        const currentItem = getState().items.find((it) => it.id === card.itemId);
+        resultText = withCancelledResultMarker(resultText, currentItem);
+      }
+      patchItem(card.itemId, { result: resultText, text: resultText, isError: group.errors > 0, errorCount: group.errors, count: group.count, completedCount: group.completed, completedAt: Date.now() });
+      card.done = true;
+      if (card.callId) done.add(card.callId);
+    }
+  };
+
+  return { patchToolCardResult, flushToolResults };
+}