mixdog 0.9.1 → 0.9.3

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -0,0 +1,49 @@
+// Shared pre-dispatch deny — single source of truth for the remaining
+// control-plane / role scoping rejects. Called by BOTH the eager dispatch
+// path (startEagerTool) and the serial dispatch path (executeTool body).
+// Returns null when the call is allowed to proceed; otherwise returns the
+// Error string the serial path would emit. The eager caller ignores the
+// message body and just treats non-null as "do not start eager".
+//
+// This is NOT a permission gate — runtime permission enforcement was removed
+// (every tool call is trusted). What remains is architectural scoping:
+// agent workers are sandboxed to code/research tools. They must never reach
+// owner/host control surfaces: session management, the ENTIRE channels module
+// (Discord messaging, schedules, webhook/config, channel-bridge toggle,
+// command injection), or host input injection. Explicit name list (no imports)
+// keeps this hot-path gate dependency-free; add new owner/channel tools here.
+import { isAgentOwner } from '../../agent-owner.mjs';
+
+const WORKER_DENIED_TOOLS = new Set([
+    // session control-plane — unified into the single `agent` tool
+    // (type=spawn|send|close|list). Denying the one name blocks all worker
+    // session control.
+    'agent',
+    // channels module (owner/Discord-facing)
+    'reply', 'react', 'edit_message', 'download_attachment', 'fetch',
+    'schedule_status', 'trigger_schedule', 'schedule_control',
+    'activate_channel_bridge', 'reload_config', 'inject_command',
+    // host input injection
+    'inject_input',
+]);
+
+function _preDispatchDeny(call, toolKind, sessionRef) {
+    const name = call?.name;
+    if (typeof name !== 'string' || !name) return null;
+    const _agentOwned = sessionRef?.scope?.startsWith?.('agent:')
+        || isAgentOwner(sessionRef);
+    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
+    if (_agentOwned && _controlPlaneTool) {
+        return `Error: control-plane tool "${name}" is Lead-only and not available to agent workers.`;
+    }
+    const noToolAgent = sessionRef?.agent === 'cycle1-agent' || sessionRef?.agent === 'cycle2-agent';
+    if (noToolAgent) {
+        return `Error: tool "${name}" is not available in agent "${sessionRef.agent}". Re-emit the answer as pipe-separated text per the agent's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
+    }
+    return null;
+}
+
+/** Exported for smoke tests — same runtime deny as the agent loop. */
+export function preDispatchDenyForSession(sessionRef, call, toolKind = 'builtin') {
+    return _preDispatchDeny(call, toolKind, sessionRef);
+}

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

@@ -0,0 +1,63 @@
+// Steering-message normalization/merge helpers extracted from loop.mjs.
+// Merges queued steering entries into a single content payload + display text.
+
+export function steeringContentText(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 normalizeSteeringEntry(entry) {
+    if (typeof entry === 'string') {
+        const text = entry.trim();
+        return text ? { content: text, text } : null;
+    }
+    if (!entry || typeof entry !== 'object') return null;
+    const content = Object.prototype.hasOwnProperty.call(entry, 'content') ? entry.content : entry;
+    const text = typeof entry.text === 'string' ? entry.text.trim() : steeringContentText(content).trim();
+    if (Array.isArray(content)) return content.length > 0 ? { content, text } : null;
+    if (typeof content === 'string') {
+        const value = content.trim();
+        return value ? { content: value, text: text || value } : null;
+    }
+    const fallback = steeringContentText(content).trim();
+    return fallback ? { content: fallback, text: text || fallback } : null;
+}
+
+export function mergeSteeringEntries(entries) {
+    const normalized = (Array.isArray(entries) ? entries : [])
+        .map(normalizeSteeringEntry)
+        .filter(Boolean);
+    if (normalized.length === 0) return null;
+    const displayText = normalized.map((entry) => entry.text || steeringContentText(entry.content))
+        .filter((text) => String(text || '').trim())
+        .join('\n');
+    if (normalized.every((entry) => typeof entry.content === 'string')) {
+        return {
+            content: normalized.map((entry) => entry.content).filter(Boolean).join('\n'),
+            text: displayText,
+            count: normalized.length,
+        };
+    }
+    const parts = [];
+    for (const entry of normalized) {
+        if (typeof entry.content === 'string') {
+            if (entry.content.trim()) parts.push({ type: 'text', text: entry.content });
+        } else if (Array.isArray(entry.content)) {
+            parts.push(...entry.content);
+        } else {
+            const text = steeringContentText(entry.content);
+            if (text.trim()) parts.push({ type: 'text', text });
+        }
+        parts.push({ type: 'text', text: '\n' });
+    }
+    while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
+    return { content: parts, text: displayText || steeringContentText(parts), count: normalized.length };
+}

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

@@ -0,0 +1,100 @@
+// Stored tool-call argument compaction/restoration, extracted from loop.mjs.
+// Long body/command args are truncated with a sha256-tagged head/tail preview
+// when persisted into assistant history; the FULL body of a single call can be
+// restored on retry (e.g. a failed edit) so the model sees the original patch.
+import { createHash } from 'crypto';
+
+const STORED_TOOL_ARG_BODY_KEY_RE = /^(?:content|old_string|new_string|patch|rewrite)$/i;
+const STORED_TOOL_ARG_LONG_KEY_RE = /^(?:command|script)$/i;
+const STORED_TOOL_ARG_BODY_LIMIT = 2_000;
+const STORED_TOOL_ARG_LONG_LIMIT = 8_000;
+const STORED_TOOL_ARG_PREVIEW_HEAD = 360;
+const STORED_TOOL_ARG_PREVIEW_TAIL = 160;
+
+function compactStoredToolArgString(value, key = '') {
+    if (typeof value !== 'string') return value;
+    const isBody = STORED_TOOL_ARG_BODY_KEY_RE.test(key);
+    const isLong = isBody || STORED_TOOL_ARG_LONG_KEY_RE.test(key);
+    const limit = isBody ? STORED_TOOL_ARG_BODY_LIMIT : (isLong ? STORED_TOOL_ARG_LONG_LIMIT : Infinity);
+    if (value.length <= limit) return value;
+    const hash = createHash('sha256').update(value).digest('hex').slice(0, 16);
+    const head = value.slice(0, STORED_TOOL_ARG_PREVIEW_HEAD).replace(/\r\n/g, '\n');
+    const tail = value.slice(-STORED_TOOL_ARG_PREVIEW_TAIL).replace(/\r\n/g, '\n');
+    return `[mixdog compacted ${key || 'string'}: ${value.length} chars, sha256:${hash}]\n${head}\n... [middle omitted from stored tool-call args] ...\n${tail}`;
+}
+
+function compactStoredToolArgValue(value, key = '', depth = 0) {
+    if (value === null || value === undefined) return value;
+    if (typeof value === 'string') return compactStoredToolArgString(value, key);
+    if (typeof value !== 'object') return value;
+    if (depth >= 6) return Array.isArray(value) ? `[${value.length} items]` : '{...}';
+    if (Array.isArray(value)) {
+        return value.map((item) => compactStoredToolArgValue(item, key, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = compactStoredToolArgValue(v, k, depth + 1);
+    }
+    return out;
+}
+
+export function compactToolCallsForHistory(calls) {
+    if (!Array.isArray(calls)) return calls;
+    return calls.map((call) => {
+        if (!call || typeof call !== 'object') return call;
+        return {
+            ...call,
+            arguments: compactStoredToolArgValue(call.arguments),
+        };
+    });
+}
+
+// Restore the FULL body of ONE tool call inside a history assistant message
+// whose toolCalls were compacted at push time. Used for a failed edit call so
+// the model sees the original patch/old_string on retry instead of a
+// `[mixdog compacted …]` placeholder it cannot act on. Must run BEFORE the
+// message is first transmitted so it never mutates an already-cached prefix
+// (the prompt cache is content-prefix matched).
+//
+// Only the compactable body/long keys (patch, old_string, new_string, content,
+// rewrite, command, script) are restored, and at ANY depth — compaction is
+// recursive (compactStoredToolArgValue), so batch shapes like edits[].old_string
+// or writes[].content carry nested compacted bodies too. Every other field
+// (e.g. `path`, which a tool may mutate in place during execution) is taken from
+// the compacted snapshot captured at push time, before any mutation. The
+// compacted args tree is built fresh by compactToolCallsForHistory and is not
+// shared with originalCalls, so rebuilding it here is safe.
+export function restoreToolCallBodyForId(assistantMsg, originalCalls, callId) {
+    if (!assistantMsg || !Array.isArray(assistantMsg.toolCalls) || !callId) return;
+    if (!Array.isArray(originalCalls)) return;
+    const tc = assistantMsg.toolCalls.find((t) => t && t.id === callId);
+    const orig = originalCalls.find((c) => c && c.id === callId);
+    if (!tc || !orig) return;
+    if (!tc.arguments || typeof tc.arguments !== 'object'
+        || !orig.arguments || typeof orig.arguments !== 'object') return;
+    tc.arguments = _restoreCompactedBodies(tc.arguments, orig.arguments, '');
+}
+
+// Recursively rebuild a compacted args tree: replace ONLY compactable body/long
+// string fields (matched by key at any depth) with their full originals, and
+// keep every other field from the compacted snapshot. tcVal and origVal share
+// the same structure (compaction only shortens body strings), so the walk
+// descends them in parallel; a missing or non-object origVal falls back to the
+// compacted value rather than throwing.
+function _restoreCompactedBodies(tcVal, origVal, key) {
+    if ((STORED_TOOL_ARG_BODY_KEY_RE.test(key) || STORED_TOOL_ARG_LONG_KEY_RE.test(key))
+        && typeof origVal === 'string') {
+        return origVal;
+    }
+    if (Array.isArray(tcVal) && Array.isArray(origVal)) {
+        return tcVal.map((item, i) => _restoreCompactedBodies(item, origVal[i], key));
+    }
+    if (tcVal && typeof tcVal === 'object' && origVal && typeof origVal === 'object') {
+        const out = {};
+        for (const k of Object.keys(tcVal)) {
+            out[k] = (k in origVal) ? _restoreCompactedBodies(tcVal[k], origVal[k], k) : tcVal[k];
+        }
+        return out;
+    }
+    return tcVal;
+}

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

@@ -0,0 +1,52 @@
+// Tool-name classification + intra-turn signature helpers, extracted from
+// loop.mjs. These drive cross-turn read dedup, scoped caching, shell routing,
+// and duplicate-call detection. Strips the MCP prefix so direct calls and
+// MCP-wrapped calls share the same cache.
+import { createHash } from 'crypto';
+
+export const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
+
+export function _stripMcpPrefix(name) {
+    return typeof name === 'string' && name.startsWith(MCP_TOOL_PREFIX)
+        ? name.slice(MCP_TOOL_PREFIX.length) : name;
+}
+export function _isReadTool(name) {
+    return _stripMcpPrefix(name) === 'read';
+}
+export function _isMutationTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'apply_patch';
+}
+export const SCOPED_CACHEABLE_TOOLS = new Set([
+    'code_graph',
+    'grep',
+    'list',
+    'glob',
+]);
+export function _isScopedCacheableTool(name) {
+    const n = _stripMcpPrefix(name);
+    return SCOPED_CACHEABLE_TOOLS.has(n);
+}
+export function _isShellTool(name) {
+    const n = _stripMcpPrefix(name);
+    return n === 'shell' || n === 'bash_session';
+}
+
+// Canonical signature for intra-turn duplicate detection. Sorting keys
+// produces a stable hash regardless of arg-object key order. Anything
+// non-serializable falls back to String(args) — still deterministic for
+// the model's typical structured-arg shape.
+export function _canonicalArgs(args) {
+    if (args == null || typeof args !== 'object') {
+        try { return JSON.stringify(args); } catch { return String(args); }
+    }
+    try {
+        const keys = Object.keys(args).sort();
+        const sorted = {};
+        for (const k of keys) sorted[k] = args[k];
+        return JSON.stringify(sorted);
+    } catch { return String(args); }
+}
+export function _intraTurnSig(name, args) {
+    return createHash('sha256').update(`${name}:${_canonicalArgs(args)}`).digest('hex').slice(0, 16);
+}

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;
+}