mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/session/loop/tool-exec.mjs

@@ -0,0 +1,239 @@
+// Tool dispatch/execution cluster, extracted from loop.mjs.
+// executeTool routes a single tool call (Skill/skills/mcp/code_graph/internal/
+// shell/apply_patch/builtin/external-adapter) through before/after hooks and the
+// scoped-cache outcome bookkeeping. No behavior change: bodies are verbatim from
+// loop.mjs, re-exported via the facade so existing importers keep working.
+import { executeMcpTool, isMcpTool, mcpToolHasField } from '../../mcp/client.mjs';
+import { executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool, isExternalAdapterTool } from '../../tools/builtin.mjs';
+import { executeBashSessionTool } from '../../tools/bash-session.mjs';
+import { executePatchTool } from '../../tools/patch.mjs';
+import { executeInternalTool, isInternalTool } from '../../internal-tools.mjs';
+import { normalizeToolEnvelope, makeToolEnvelope } from '../tool-envelope.mjs';
+import { getSessionAbortSignal, enqueuePendingMessage } from '../manager.mjs';
+import { createScopedCacheOutcome } from '../cache/scoped-cache-outcome.mjs';
+import { modelVisibleToolCompletionMessage } from '../../../../shared/tool-execution-contract.mjs';
+import { _isScopedCacheableTool } from './tool-classify.mjs';
+import {
+    buildSkillsListResponse,
+    viewSkill,
+    resolveToolResultAfterHook,
+    extractBashSessionId,
+    buildAgentBashSessionArgs,
+    resolvePreToolAskApproval,
+} from './tool-helpers.mjs';
+
+let codeGraphRuntimePromise = null;
+async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
+    codeGraphRuntimePromise ??= import('../../tools/code-graph.mjs');
+    const mod = await codeGraphRuntimePromise;
+    if (typeof mod.executeCodeGraphTool !== 'function') throw new Error('code_graph runtime is not available');
+    return mod.executeCodeGraphTool(name, args, cwd, signal, options);
+}
+
+export function _scopedCacheOutcomeForCall(sessionRef, toolCallId, toolName, callerSessionId, executeOpts = {}) {
+    if (executeOpts.scopedCacheOutcome) {
+        if (sessionRef && toolCallId) {
+            // instanceof guard: a session revived from disk (JSON round-trip) turns
+            // this Map into a plain object `{}` — truthy, but without Map methods.
+            if (!(sessionRef._scopedCacheOutcomeByCallId instanceof Map)) sessionRef._scopedCacheOutcomeByCallId = new Map();
+            sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, executeOpts.scopedCacheOutcome);
+        }
+        return executeOpts.scopedCacheOutcome;
+    }
+    if (!callerSessionId || !toolCallId || !_isScopedCacheableTool(toolName)) return null;
+    const outcome = createScopedCacheOutcome();
+    if (sessionRef) {
+        if (!(sessionRef._scopedCacheOutcomeByCallId instanceof Map)) sessionRef._scopedCacheOutcomeByCallId = new Map();
+        sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, outcome);
+    }
+    return outcome;
+}
+
+export async function executeTool(name, args, cwd, callerSessionId, sessionRef, executeOpts = {}) {
+    const scopedCacheOutcome = _scopedCacheOutcomeForCall(
+        sessionRef,
+        executeOpts.toolCallId,
+        name,
+        callerSessionId,
+        executeOpts,
+    );
+    const toolOpts = scopedCacheOutcome
+        ? { ...executeOpts, scopedCacheOutcome }
+        : executeOpts;
+    const notificationSessionId = String(executeOpts.notifySessionId || sessionRef?.ownerSessionId || callerSessionId || '').trim();
+    const notifyFn = typeof executeOpts.notifyFn === 'function'
+        ? executeOpts.notifyFn
+        : (text, meta = {}) => {
+            if (!notificationSessionId) return;
+            try {
+                const visible = modelVisibleToolCompletionMessage(text, meta);
+                if (visible) enqueuePendingMessage(notificationSessionId, visible);
+            } catch { /* best effort */ }
+        };
+    const completionToolOpts = {
+        ...toolOpts,
+        sessionId: callerSessionId,
+        callerSessionId: notificationSessionId || callerSessionId,
+        routingSessionId: callerSessionId,
+        clientHostPid: sessionRef?.clientHostPid,
+        notifyFn,
+    };
+    const beforeToolHook = typeof executeOpts.beforeToolHook === 'function'
+        ? executeOpts.beforeToolHook
+        : sessionRef?.beforeToolHook;
+    const toolApprovalHook = typeof executeOpts.toolApprovalHook === 'function'
+        ? executeOpts.toolApprovalHook
+        : sessionRef?.toolApprovalHook;
+    if (beforeToolHook) {
+        try {
+            const decision = await beforeToolHook({
+                name,
+                args,
+                cwd,
+                sessionId: callerSessionId,
+                toolCallId: executeOpts.toolCallId || null,
+            });
+            const action = String(decision?.action || decision?.decision || '').toLowerCase();
+            if (action === 'deny' || action === 'block') {
+                const reason = decision?.reason ? `: ${decision.reason}` : '';
+                return `Error: tool "${name}" denied by hook${reason}`;
+            }
+            if (action === 'ask') {
+                const askReason = String(decision?.reason || 'approval requested by hook').trim();
+                const askOutcome = await resolvePreToolAskApproval({
+                    toolName: name,
+                    args,
+                    cwd,
+                    sessionId: callerSessionId,
+                    toolCallId: executeOpts.toolCallId || null,
+                    askReason,
+                    toolApprovalHook,
+                });
+                if (askOutcome.denial) return askOutcome.denial;
+                const approval = askOutcome.approval;
+                if (approval && typeof approval === 'object' && approval.args && typeof approval.args === 'object' && !Array.isArray(approval.args)) {
+                    args = approval.args;
+                }
+            }
+            if ((action === 'modify' || action === 'rewrite') && decision?.args && typeof decision.args === 'object' && !Array.isArray(decision.args)) {
+                args = decision.args;
+            }
+        } catch {
+            // Hooks are policy extensions. A broken hook must not wedge the agent loop.
+        }
+    }
+    const afterToolHook = typeof executeOpts.afterToolHook === 'function'
+        ? executeOpts.afterToolHook
+        : sessionRef?.afterToolHook;
+    const __result = await (async () => {
+    if (name === 'Skill') {
+        return viewSkill(cwd, args?.name);
+    }
+    if (name === 'skills_list') {
+        return buildSkillsListResponse(cwd);
+    }
+    if (name === 'skill_view') {
+        return viewSkill(cwd, args?.name);
+    }
+    if (isMcpTool(name)) {
+        // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
+        // (bash / grep / read / list / glob etc.) but the worker session's
+        // cwd was previously dropped here. Inject cwd only when the tool's
+        // inputSchema declares the field — schemas without it would reject
+        // an unknown argument.
+        const needsCwdInjection = cwd
+            && mcpToolHasField(name, 'cwd')
+            && (args == null || args.cwd == null);
+        const finalArgs = needsCwdInjection ? { ...(args || {}), cwd } : args;
+        return executeMcpTool(name, finalArgs);
+    }
+    if (name === 'code_graph') {
+        // cwd chain: args.cwd (caller-explicit) → session cwd → undefined (handler throws)
+        const graphCwd = (typeof args?.cwd === 'string' && args.cwd.trim()) ? args.cwd.trim() : cwd;
+        return executeCodeGraphToolLazy(name, args, graphCwd, null, toolOpts);
+    }
+    if (isInternalTool(name)) {
+        // callerSessionId propagates into server.mjs dispatchTool so that
+        // dispatchAiWrapped can detect and reject recursive calls from a
+        // hidden-role session (recall/search/explore → self).
+        return executeInternalTool(name, args, {
+            callerSessionId,
+            callerCwd: cwd,
+            clientHostPid: sessionRef?.clientHostPid,
+            signal: executeOpts.signal,
+            routingSessionId: callerSessionId,
+            notifyFn,
+        });
+    }
+    if (name === 'shell') {
+        const routedArgs = buildAgentBashSessionArgs(args, sessionRef);
+        if (!routedArgs) {
+            // clientHostPid scopes background shell-jobs to the dispatching
+            // terminal's claude.exe pid (agent sessions store it on sessionRef);
+            // without it resolveJobOwnerHostPid falls back to the daemon-global env.
+            return executeBuiltinTool(name, args, cwd, completionToolOpts);
+        }
+        // Thread the session's AbortSignal so agent type=close can interrupt the
+        // persistent child process. getSessionAbortSignal is imported from
+        // manager.mjs; callerSessionId identifies the controller.
+        let _bashAbortSignal = null;
+        try { _bashAbortSignal = getSessionAbortSignal(callerSessionId); } catch { /* ignore */ }
+        const result = await executeBashSessionTool('bash_session', routedArgs, cwd, {
+            sessionId: callerSessionId,
+            abortSignal: _bashAbortSignal,
+        });
+        const bashSid = extractBashSessionId(result);
+        if (bashSid) {
+            sessionRef.implicitBashSessionId = bashSid;
+            // Track all persistent bash sessions for bulk teardown on close.
+            if (sessionRef.allBashSessionIds) {
+                if (!sessionRef.allBashSessionIds.includes(bashSid)) {
+                    sessionRef.allBashSessionIds.push(bashSid);
+                }
+            } else {
+                sessionRef.allBashSessionIds = [bashSid];
+            }
+        }
+        return result;
+    }
+    if (name === 'apply_patch') {
+        const patchArgs = typeof args === 'string' ? { patch: args } : args;
+        return executePatchTool(name, patchArgs, cwd, { sessionId: callerSessionId, toolCallId: executeOpts.toolCallId || null });
+    }
+    if (isBuiltinTool(name)) {
+        // clientHostPid threaded for the same per-terminal job-scope reason as
+        // the bash branch above (see resolveJobOwnerHostPid).
+        return executeBuiltinTool(name, args, cwd, completionToolOpts);
+    }
+    if (isExternalAdapterTool(name)) {
+        // Foreign-CLI tool names (StrReplace/Write/bash variants) adapt to a
+        // native execution inside executeBuiltinTool's default: case; on a
+        // shape mismatch it falls back to the redirect guidance message.
+        return executeBuiltinTool(name, args, cwd, completionToolOpts);
+    }
+    return formatUnknownBuiltinToolMessage(name, args, 'tool');
+    })();
+    if (typeof afterToolHook === 'function') {
+        try {
+            const hookResult = await afterToolHook({
+                name,
+                args,
+                cwd,
+                sessionId: callerSessionId,
+                toolCallId: executeOpts.toolCallId || null,
+                result: __result,
+            });
+            // Envelope-aware hook override: a PostToolUse hook may override the
+            // model-VISIBLE tool output (the envelope's `result` / stub), but it
+            // must NEVER drop the `newMessages` channel. Split first, apply the
+            // override to `result` only, then re-wrap so newMessages survive.
+            const { result: __res, newMessages: __nm } = normalizeToolEnvelope(__result);
+            const __overridden = resolveToolResultAfterHook(__res, hookResult);
+            if (__nm.length) return makeToolEnvelope(__overridden, __nm);
+            return __overridden;
+        } catch {
+            // PostToolUse hooks are best-effort; never let one break the tool result.
+        }
+    }
+    return __result;
+}

package/src/runtime/agent/orchestrator/session/loop/tool-helpers.mjs

@@ -0,0 +1,218 @@
+// Miscellaneous tool helpers extracted from loop.mjs: eager-dispatch check,
+// message-array change detect, tool-kind classification, skills, hook overrides,
+// native tool-search payload parsing, bash-session routing, and approval.
+import { isMcpTool } from '../../mcp/client.mjs';
+import { isBuiltinTool } from '../../tools/builtin.mjs';
+import { isInternalTool } from '../../internal-tools.mjs';
+import { collectSkillsCached, loadSkillResource, buildSkillToolEnvelope } from '../../context/collect.mjs';
+import { isAgentOwner } from '../../agent-owner.mjs';
+
+// Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
+// to execute during SSE parsing so tool work overlaps with the rest of the
+// stream. Writes, bash, MCP and skills stay serial after send() returns.
+export function isEagerDispatchable(name, tools) {
+    if (!Array.isArray(tools)) return false;
+    const def = tools.find(t => t?.name === name);
+    return def?.annotations?.readOnlyHint === true;
+}
+export function messagesArrayChanged(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after)) return before !== after;
+    if (before.length !== after.length) return true;
+    for (let i = 0; i < before.length; i += 1) {
+        if (before[i] !== after[i]) return true;
+    }
+    return false;
+}
+
+const SKILL_TOOL_NAMES = new Set(['Skill', 'skills_list', 'skill_view']);
+const SPECIAL_TOOL_NAMES = new Set(['bash_session', 'apply_patch', 'code_graph']);
+const BASH_SESSION_HEADER_RE = /\[session: ([^\]\r\n]+)\]/;
+
+export function getToolKind(name) {
+    if (SKILL_TOOL_NAMES.has(name)) return 'skill';
+    if (SPECIAL_TOOL_NAMES.has(name)) return 'builtin';
+    if (isMcpTool(name)) return 'mcp';
+    if (isInternalTool(name)) return 'internal';
+    if (isBuiltinTool(name)) return 'builtin';
+    return 'builtin';
+}
+export function buildSkillsListResponse(cwd) {
+    const skills = collectSkillsCached(cwd);
+    const entries = skills.map(s => ({ name: s.name, description: s.description || '' }));
+    return JSON.stringify({ skills: entries });
+}
+export function viewSkill(cwd, name) {
+    if (!name) return 'Error: skill name is required';
+    const res = loadSkillResource(name, cwd);
+    if (!res) return `Error: skill "${name}" not found`;
+    // Return the general tool envelope: the model-visible tool_result is the
+    // short stub (`Loaded skill: <name>`) and the full SKILL.md body is
+    // delivered ONCE as a separate injected role:'user' message (newMessages).
+    return buildSkillToolEnvelope(name, res.content, res.dir);
+}
+
+/** Normalize PostToolUse hook override values (legacy MCP text envelopes only). */
+export function normalizeHookUpdatedToolOutput(value) {
+    if (typeof value === 'string') return value;
+    if (value == null) return '';
+    if (typeof value === 'object' && Array.isArray(value.content)) {
+        const hasNonText = value.content.some((c) => c && typeof c === 'object' && c.type && c.type !== 'text');
+        if (hasNonText) return value;
+        return value.content
+            .map((c) => (c?.type === 'text' ? c.text || '' : JSON.stringify(c)))
+            .join('\n');
+    }
+    return value;
+}
+
+export function resolveToolResultAfterHook(originalResult, hookResult) {
+    if (!hookResult || typeof hookResult !== 'object' || hookResult.updatedToolOutput === undefined) {
+        return originalResult;
+    }
+    const updated = normalizeHookUpdatedToolOutput(hookResult.updatedToolOutput);
+    return updated === undefined ? originalResult : updated;
+}
+
+export function parseNativeToolSearchPayload(toolName, result) {
+    if (toolName !== 'tool_search' || typeof result !== 'string') return null;
+    try {
+        const parsed = JSON.parse(result);
+        const native = parsed?.nativeToolSearch;
+        if (!native || typeof native !== 'object') return null;
+        const rawToolReferences = Array.isArray(native.toolReferences) ? native.toolReferences : [];
+        const toolReferences = rawToolReferences
+            .filter((name) => typeof name === 'string')
+            .map((name) => name.trim())
+            .filter(Boolean);
+        const rawOpenaiTools = Array.isArray(native.openaiTools) ? native.openaiTools : [];
+        const openaiTools = rawOpenaiTools.filter((tool) => (
+            tool
+            && typeof tool === 'object'
+            && !Array.isArray(tool)
+            && typeof tool.name === 'string'
+            && tool.name.trim()
+            && (tool.type === undefined || typeof tool.type === 'string')
+        ));
+        if (!toolReferences.length && !openaiTools.length) return null;
+        const baseSummary = typeof native.summary === 'string' && native.summary
+            ? native.summary
+            : `Loaded deferred tools: ${toolReferences.join(', ') || openaiTools.map((tool) => tool.name).filter(Boolean).join(', ')}`;
+        const selectedTools = parsed?.selected?.tools;
+        const missing = Array.isArray(selectedTools?.missing)
+            ? selectedTools.missing.map((name) => String(name || '').trim()).filter(Boolean)
+            : [];
+        const blocked = Array.isArray(selectedTools?.blocked)
+            ? selectedTools.blocked
+                .map((entry) => {
+                    if (entry && typeof entry === 'object') {
+                        const name = String(entry.name || '').trim();
+                        if (!name) return '';
+                        const reason = String(entry.reason || '').trim();
+                        return reason ? `${name} (${reason})` : name;
+                    }
+                    return String(entry || '').trim();
+                })
+                .filter(Boolean)
+            : [];
+        const extraLines = [];
+        if (missing.length) extraLines.push(`missing: ${missing.join(', ')}`);
+        if (blocked.length) extraLines.push(`blocked: ${blocked.join(', ')}`);
+        const summary = extraLines.length ? `${baseSummary}\n${extraLines.join('; ')}` : baseSummary;
+        return {
+            toolReferences,
+            openaiTools,
+            summary,
+        };
+    } catch {
+        return null;
+    }
+}
+export function extractBashSessionId(result) {
+    if (typeof result !== 'string') return null;
+    const match = BASH_SESSION_HEADER_RE.exec(result);
+    return match ? match[1] : null;
+}
+
+export function buildAgentBashSessionArgs(args, sessionRef) {
+    if (!isAgentOwner(sessionRef)) return null;
+    // run_in_background is a detached one-shot job, incompatible with the
+    // persistent bash session. Fall through to the background-job path
+    // (executeBuiltinTool -> startBackgroundShellJob) so the worker gets a
+    // task_id that task control can resolve — otherwise the persistent
+    // session returns a [session: ...] header and task control reports "task not found".
+    if (args?.run_in_background === true) return null;
+    const routedArgs = { ...(args || {}) };
+    const explicitSessionId = typeof routedArgs.session_id === 'string' && routedArgs.session_id.trim()
+        ? routedArgs.session_id.trim()
+        : null;
+    const wantsPersistent = routedArgs.persistent === true || !!explicitSessionId;
+    if (!wantsPersistent) return null;
+    if (!explicitSessionId && sessionRef?.implicitBashSessionId) {
+        routedArgs.session_id = sessionRef.implicitBashSessionId;
+    } else if (explicitSessionId) {
+        routedArgs.session_id = explicitSessionId;
+    }
+    delete routedArgs.persistent;
+    return routedArgs;
+}
+
+export function formatMissingToolApprovalUiDenial(toolName, askReason) {
+    const reason = String(askReason || 'approval requested by hook').trim();
+    const name = String(toolName || 'tool');
+    return `Error: tool "${name}" denied by hook: approval required but no approval UI is available${reason ? ` (${reason})` : ''}`;
+}
+
+/**
+ * Resolve PreToolUse `{ action: 'ask' }` against an optional approval callback.
+ * Returns `{ denial }` when the tool must not run; otherwise `{ approval }`.
+ */
+export async function resolvePreToolAskApproval({
+    toolName,
+    args,
+    cwd,
+    sessionId,
+    toolCallId,
+    askReason,
+    toolApprovalHook,
+}) {
+    const name = String(toolName || 'tool');
+    const reason = String(askReason || 'approval requested by hook').trim();
+    if (typeof toolApprovalHook !== 'function') {
+        return { denial: formatMissingToolApprovalUiDenial(name, reason) };
+    }
+    let approval;
+    try {
+        approval = await toolApprovalHook({
+            name,
+            args,
+            cwd,
+            sessionId,
+            toolCallId: toolCallId || null,
+            reason,
+        });
+    } catch (error) {
+        const detail = error?.message || String(error || 'approval failed');
+        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
+    }
+    if (!approvalGranted(approval)) {
+        const detail = approvalReason(approval, reason || 'not approved');
+        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
+    }
+    return { approval };
+}
+
+export function approvalGranted(value) {
+    if (value === true) return true;
+    if (!value || typeof value !== 'object') return false;
+    if (value.approved === true || value.allow === true || value.allowed === true) return true;
+    const decision = String(value.decision || value.action || value.result || '').trim().toLowerCase();
+    return decision === 'approve' || decision === 'approved' || decision === 'allow' || decision === 'yes';
+}
+
+export function approvalReason(value, fallback = '') {
+    if (value && typeof value === 'object') {
+        const reason = String(value.reason || value.message || '').trim();
+        if (reason) return reason;
+    }
+    return fallback;
+}

package/src/runtime/agent/orchestrator/session/loop/transcript-repair.mjs

@@ -0,0 +1,101 @@
+// Pre-provider transcript pairing repair, extracted from loop.mjs.
+// Anthropic 400-rejects when an assistant message ends with tool_use blocks and
+// the next message isn't tool results for those exact ids. abort/timeout/error
+// races in the loop body can leave a dangling assistant tool_use at the tail;
+// strip any trailing/orphaned tool_use|tool_result so provider.send sees a
+// valid transcript instead of leaking the 400 to the user.
+import { sanitizeToolPairs } from '../context-utils.mjs';
+
+// Transcript pairing guard. Anthropic 400-rejects when an assistant message
+// ends with tool_use blocks and the next message isn't tool results for
+// those exact ids. abort/timeout/error race in the loop body can leave a
+// dangling assistant tool_use at the tail (e.g. the structure_probe loop
+// running 12 deep then aborting between push-assistant and push-tool).
+// Strip any trailing assistant tool_use that has no matching tool result
+// so provider.send sees a valid transcript instead of leaking the 400 to
+// the user. Repair runs every iteration but is a no-op on healthy paths.
+function _ensureTranscriptPairing(msgs, sessionId) {
+    // Walk backwards to find the last assistant message that emitted
+    // tool_use, then validate that every id has a matching tool result
+    // inside the CONTIGUOUS tool-message block immediately following it.
+    // Earlier guard splice'd the entire tail — which silently deleted any
+    // user prompt appended after the dangling assistant by manager.mjs:
+    // when the guard fired with shape
+    //     [..., assistant{a,b}, tool{a}, user{new prompt}]
+    // the splice removed user{new prompt} along with the orphan suffix.
+    // Fix: remove only assistant + the contiguous tool block; preserve
+    // anything past it (user / system / next assistant) untouched.
+    let popped = 0;
+    while (msgs.length > 0) {
+        let lastAssistantIdx = -1;
+        for (let i = msgs.length - 1; i >= 0; i--) {
+            const m = msgs[i];
+            if (m?.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
+                lastAssistantIdx = i;
+                break;
+            }
+        }
+        if (lastAssistantIdx === -1) break;
+        // Collect the contiguous tool messages directly after this assistant.
+        // Anything past that block is unrelated (next user prompt, system
+        // marker, etc.) and must survive the repair.
+        let toolBlockEnd = lastAssistantIdx + 1;
+        while (toolBlockEnd < msgs.length && msgs[toolBlockEnd]?.role === 'tool') {
+            toolBlockEnd += 1;
+        }
+        const toolBlock = msgs.slice(lastAssistantIdx + 1, toolBlockEnd);
+        const ids = msgs[lastAssistantIdx].toolCalls.map(c => c.id);
+        const matched = ids.every(id => toolBlock.some(m => m.toolCallId === id));
+        if (matched) break;
+        const removed = toolBlockEnd - lastAssistantIdx;
+        msgs.splice(lastAssistantIdx, removed);
+        popped += removed;
+    }
+    // Second sweep — catch dangling tool results that survived the
+    // contiguous-block splice. Anthropic strict spec requires every
+    // tool result to sit in a contiguous block right after the
+    // assistant whose toolCalls produced it; a `[..., assistant{a,b},
+    // tool{a}, user, tool{b}]` shape leaves tool{b} orphaned even
+    // after assistant + tool{a} are repaired by the loop above.
+    // Walk back from each tool message to the nearest non-tool
+    // ancestor; if it is not an assistant whose toolCalls include
+    // this id, drop the orphan.
+    for (let i = msgs.length - 1; i >= 0; i--) {
+        const m = msgs[i];
+        if (m?.role !== 'tool') continue;
+        if (!m.toolCallId) {
+            msgs.splice(i, 1);
+            popped += 1;
+            continue;
+        }
+        let prevIdx = i - 1;
+        while (prevIdx >= 0 && msgs[prevIdx]?.role === 'tool') prevIdx--;
+        const anchor = prevIdx >= 0 ? msgs[prevIdx] : null;
+        const anchorOk = anchor?.role === 'assistant'
+            && Array.isArray(anchor.toolCalls)
+            && anchor.toolCalls.some(c => c.id === m.toolCallId);
+        if (!anchorOk) {
+            msgs.splice(i, 1);
+            popped += 1;
+        }
+    }
+    if (popped > 0 && sessionId) {
+        try { process.stderr.write(`[transcript-repair] sess=${sessionId} popped=${popped} dangling assistant tool_use\n`); } catch {}
+    }
+}
+
+/**
+ * Pre-provider transcript repair for the agent loop. Reattach valid tool
+ * results (non-destructive) before any destructive orphan pairing cleanup.
+ * Mutates `messages` in place to preserve the session array reference.
+ */
+export function repairTranscriptBeforeProviderSend(messages, sessionId = null) {
+    if (!Array.isArray(messages)) return messages;
+    const sanitized = sanitizeToolPairs(messages);
+    if (sanitized !== messages) {
+        messages.length = 0;
+        messages.push(...sanitized);
+    }
+    _ensureTranscriptPairing(messages, sessionId);
+    return messages;
+}

package/src/runtime/agent/orchestrator/session/loop/usage.mjs

@@ -0,0 +1,35 @@
+// Usage accumulation helpers extracted from loop.mjs.
+// Normalize a provider usage payload into the canonical token/cost shape and
+// fold successive deltas into a running total across loop iterations.
+
+export function normalizeUsage(usage) {
+    if (!usage) return null;
+    const costUsd = Number(usage.costUsd);
+    return {
+        inputTokens: usage.inputTokens || 0,
+        outputTokens: usage.outputTokens || 0,
+        cachedTokens: usage.cachedTokens || 0,
+        cacheWriteTokens: usage.cacheWriteTokens || 0,
+        promptTokens: usage.promptTokens || 0,
+        ...(Number.isFinite(costUsd) ? { costUsd } : {}),
+        raw: usage.raw,
+    };
+}
+
+export function addUsage(total, usage) {
+    const delta = normalizeUsage(usage);
+    if (!delta) return total;
+    if (!total) return { ...delta };
+    const next = {
+        ...total,
+        inputTokens: (total.inputTokens || 0) + delta.inputTokens,
+        outputTokens: (total.outputTokens || 0) + delta.outputTokens,
+        cachedTokens: (total.cachedTokens || 0) + delta.cachedTokens,
+        cacheWriteTokens: (total.cacheWriteTokens || 0) + delta.cacheWriteTokens,
+        promptTokens: (total.promptTokens || 0) + delta.promptTokens,
+    };
+    if (delta.costUsd != null || total.costUsd != null) {
+        next.costUsd = (total.costUsd || 0) + (delta.costUsd || 0);
+    }
+    return next;
+}