@amodalai/runtime 0.1.26 → 0.2.1

package/dist/src/agent/states/compacting.js

@@ -0,0 +1,260 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * COMPACTING state handler.
+ *
+ * Summarizes older conversation turns to free context space:
+ * 1. Keep the last N turns verbatim (active conversation)
+ * 2. Send older turns to a cheap model for structured summarization
+ * 3. Replace old turns with the summary
+ * 4. Circuit breaker: after N consecutive failures, give up and continue
+ *
+ * The summary is structured as a handoff document with sections for
+ * current state, original task, key data, actions taken, errors, and
+ * next steps. This preserves the information the agent needs to
+ * continue working without the full conversation history.
+ */
+import { SSEEventType } from '../../types.js';
+import { CompactionError } from '../../errors.js';
+import { estimateTokenCount } from '../token-estimate.js';
+/** Prefix for the summary message injected after compaction. */
+const COMPACTION_SUMMARY_PREFIX = '[Conversation Summary — older messages compacted]';
+/** Timeout for the compaction generateText call (30 seconds). */
+const COMPACTION_TIMEOUT_MS = 30_000;
+const COMPACTION_PROMPT = `Summarize this conversation as a structured handoff into these sections:
+
+1. **Current State** — what we're working on right now
+2. **Original Task** — what the user originally asked for
+3. **Key Data** — important values, IDs, file paths, or facts that must be preserved
+4. **Actions Taken** — tools called and what they returned (summarized, not verbatim)
+5. **Errors & Corrections** — what went wrong and what we tried instead
+6. **Next Steps** — what should happen next
+
+Keep each section under 500 tokens. Focus on information the agent needs to continue working. Omit sections that have no content.`;
+/**
+ * Handle the COMPACTING state.
+ *
+ * Splits messages into "old" (to be summarized) and "recent" (kept verbatim).
+ * Calls generateText with a cheap model to produce a structured summary.
+ * Replaces old messages with a single summary message.
+ */
+export async function handleCompacting(state, ctx) {
+    const effects = [];
+    const { keepRecentTurns, maxSummaryTokens, compactionCircuitBreaker } = ctx.config;
+    // Circuit breaker — if we've failed too many times, skip compaction
+    if (ctx.compactionFailures >= compactionCircuitBreaker) {
+        ctx.logger.warn('compaction_circuit_breaker', {
+            session: ctx.sessionId,
+            failures: ctx.compactionFailures,
+            threshold: compactionCircuitBreaker,
+        });
+        return {
+            next: { type: 'thinking', messages: state.messages },
+            effects,
+        };
+    }
+    // Split messages: keep last N turns verbatim, summarize the rest.
+    // A "turn" is a user message + assistant response (+ any tool results).
+    // We count from the end by counting user messages.
+    const splitIndex = findSplitIndex(state.messages, keepRecentTurns);
+    if (splitIndex <= 0) {
+        // Not enough messages to compact — nothing older than the recent window
+        ctx.logger.debug('compaction_skipped_too_few', {
+            session: ctx.sessionId,
+            messageCount: state.messages.length,
+            keepRecentTurns,
+        });
+        return {
+            next: { type: 'thinking', messages: state.messages },
+            effects,
+        };
+    }
+    const oldMessages = state.messages.slice(0, splitIndex);
+    const recentMessages = state.messages.slice(splitIndex);
+    const tokensBefore = state.estimatedTokens;
+    effects.push({
+        type: SSEEventType.CompactionStart,
+        estimated_tokens: tokensBefore,
+        threshold: ctx.config.compactThreshold,
+        timestamp: new Date().toISOString(),
+    });
+    ctx.logger.info('compaction_start', {
+        session: ctx.sessionId,
+        totalMessages: state.messages.length,
+        oldMessages: oldMessages.length,
+        recentMessages: recentMessages.length,
+        tokensBefore,
+    });
+    const summaryResult = await summarizeMessages(oldMessages, ctx, maxSummaryTokens);
+    if (!summaryResult.ok) {
+        ctx.compactionFailures++;
+        ctx.logger.error('compaction_failed', {
+            session: ctx.sessionId,
+            error: summaryResult.error.message,
+            failure: ctx.compactionFailures,
+            circuitBreakerAt: compactionCircuitBreaker,
+        });
+        // Continue without compaction — the agent can still work, just with
+        // a fuller context. Better than crashing the loop.
+        return {
+            next: { type: 'thinking', messages: state.messages },
+            effects,
+        };
+    }
+    // Build the compacted message list: summary + recent turns.
+    // Uses 'user' role so it's valid for Anthropic (which rejects system
+    // messages after user/assistant turns). The "[Conversation Summary]"
+    // prefix makes the provenance clear to the model.
+    const summaryMessage = {
+        role: 'user',
+        content: `${COMPACTION_SUMMARY_PREFIX}\n\n${summaryResult.value.text}`,
+    };
+    const compactedMessages = [summaryMessage, ...recentMessages];
+    // Update context
+    ctx.messages = compactedMessages;
+    ctx.compactionFailures = 0; // Reset circuit breaker on success
+    const tokensAfter = estimateTokenCount(compactedMessages, ctx.provider);
+    const compactionTokens = summaryResult.value.usage.inputTokens + summaryResult.value.usage.outputTokens;
+    ctx.logger.info('compaction_end', {
+        session: ctx.sessionId,
+        tokensBefore,
+        tokensAfter,
+        messagesBefore: state.messages.length,
+        messagesAfter: compactedMessages.length,
+    });
+    effects.push({
+        type: SSEEventType.CompactionEnd,
+        tokens_before: tokensBefore,
+        tokens_after: tokensAfter,
+        compaction_tokens: compactionTokens,
+        timestamp: new Date().toISOString(),
+    });
+    return {
+        next: { type: 'thinking', messages: compactedMessages },
+        effects,
+    };
+}
+/**
+ * Summarize old messages using generateText.
+ * Returns Result to avoid try/catch in the caller.
+ */
+async function summarizeMessages(messages, ctx, maxSummaryTokens) {
+    // Serialize old messages into a readable conversation format
+    const conversationText = messagesToText(messages);
+    // Per-call timeout composed with session abort signal — prevents a hung
+    // provider from blocking the loop until session-level abort.
+    const timeoutSignal = AbortSignal.timeout(COMPACTION_TIMEOUT_MS);
+    const combinedSignal = AbortSignal.any([ctx.signal, timeoutSignal]);
+    try {
+        const result = await ctx.provider.generateText({
+            messages: [
+                { role: 'user', content: `Here is a conversation to summarize:\n\n${conversationText}` },
+            ],
+            system: COMPACTION_PROMPT,
+            maxOutputTokens: maxSummaryTokens,
+            abortSignal: combinedSignal,
+        });
+        // Track compaction token usage
+        ctx.usage.inputTokens += result.usage.inputTokens;
+        ctx.usage.outputTokens += result.usage.outputTokens;
+        ctx.usage.totalTokens += result.usage.inputTokens + result.usage.outputTokens;
+        if (!result.text || result.text.trim().length === 0) {
+            return {
+                ok: false,
+                error: new CompactionError('Summarization returned empty text', {
+                    stage: 'summarize',
+                    context: { messageCount: messages.length },
+                }),
+            };
+        }
+        return {
+            ok: true,
+            value: {
+                text: result.text,
+                usage: { inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens },
+            },
+        };
+    }
+    catch (err) {
+        // Specific expected failure with specific handling (reason #3):
+        // Provider errors during compaction are non-fatal — the caller degrades
+        // gracefully by continuing without compaction.
+        return {
+            ok: false,
+            error: new CompactionError(`Summarization failed: ${err instanceof Error ? err.message : String(err)}`, { stage: 'summarize', cause: err, context: { messageCount: messages.length } }),
+        };
+    }
+}
+/**
+ * Convert messages to a readable text format for the summarizer.
+ */
+function messagesToText(messages) {
+    const lines = [];
+    for (const msg of messages) {
+        const role = msg.role.toUpperCase();
+        if (typeof msg.content === 'string') {
+            lines.push(`${role}: ${msg.content}`);
+            continue;
+        }
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const part of msg.content) {
+            if (!('type' in part))
+                continue;
+            if (part.type === 'text' && 'text' in part) {
+                lines.push(`${role}: ${part.text}`);
+            }
+            else if (part.type === 'tool-call' && 'toolName' in part) {
+                const args = 'input' in part ? JSON.stringify(part.input) : '{}';
+                lines.push(`${role} [tool_call: ${part.toolName}(${args})]`);
+            }
+            else if (part.type === 'tool-result' && 'output' in part) {
+                const output = extractToolResultText(part.output);
+                // Truncate long tool results for the summarizer — it doesn't need 20K
+                const truncated = output.length > 2_000
+                    ? output.slice(0, 2_000) + '... [truncated for summarization]'
+                    : output;
+                lines.push(`TOOL_RESULT: ${truncated}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Extract text from a tool result output field.
+ */
+function extractToolResultText(output) {
+    if (typeof output === 'string')
+        return output;
+    if (typeof output === 'object' && output !== null && 'value' in output) {
+        // `in` narrows to `object & Record<'value', unknown>` — safe to access
+        return String(output.value);
+    }
+    return JSON.stringify(output);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Find the index to split messages: everything before this index gets
+ * summarized, everything at or after is kept verbatim.
+ *
+ * Counts user messages from the end to find `keepTurns` turn boundaries.
+ */
+function findSplitIndex(messages, keepTurns) {
+    let userMessagesSeen = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user') {
+            userMessagesSeen++;
+            if (userMessagesSeen >= keepTurns) {
+                return i;
+            }
+        }
+    }
+    // Not enough turns to split — return 0 (don't compact)
+    return 0;
+}
+//# sourceMappingURL=compacting.js.map

package/dist/src/agent/states/compacting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compacting.js","sourceRoot":"","sources":["../../../../src/agent/states/compacting.ts"],"names":[],"mappings":"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"}

package/dist/src/agent/states/confirming.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ConfirmingState, AgentContext, TransitionResult } from '../loop-types.js';
+/**
+ * Handle the CONFIRMING state.
+ */
+export declare function handleConfirming(state: ConfirmingState, ctx: AgentContext): Promise<TransitionResult>;

package/dist/src/agent/states/confirming.js

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * CONFIRMING state handler.
+ *
+ * Waits for user confirmation on a tool call (via ctx.waitForConfirmation).
+ * - Approved → resume EXECUTING with the confirmed call
+ * - Denied → tell the model the tool call was denied, back to THINKING
+ */
+import { SSEEventType } from '../../types.js';
+/**
+ * Handle the CONFIRMING state.
+ */
+export async function handleConfirming(state, ctx) {
+    const effects = [];
+    ctx.logger.info('tool_confirmation_waiting', {
+        tool: state.call.toolName,
+        callId: state.call.toolCallId,
+        session: ctx.sessionId,
+    });
+    // Race confirmation against a timeout — don't hang forever if user never responds
+    const timeoutMs = ctx.config.confirmationTimeoutMs;
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve(false), timeoutMs);
+    });
+    const approved = await Promise.race([
+        ctx.waitForConfirmation(state.call.toolCallId),
+        timeoutPromise,
+    ]);
+    if (approved) {
+        ctx.logger.info('tool_confirmation_approved', {
+            tool: state.call.toolName,
+            callId: state.call.toolCallId,
+            session: ctx.sessionId,
+        });
+        // Mark this call as confirmed so EXECUTING does not re-route it back
+        // to CONFIRMING on the next pass (infinite-loop guard).
+        ctx.confirmedCallIds.add(state.call.toolCallId);
+        effects.push({
+            type: SSEEventType.Approved,
+            resource_type: 'tool_call',
+            preview_id: state.call.toolCallId,
+            timestamp: new Date().toISOString(),
+        });
+        return {
+            next: {
+                type: 'executing',
+                queue: state.remainingQueue,
+                current: state.call,
+                results: [],
+            },
+            effects,
+        };
+    }
+    // Denied — inject a tool result message telling the model
+    ctx.logger.info('tool_confirmation_denied', {
+        tool: state.call.toolName,
+        callId: state.call.toolCallId,
+        session: ctx.sessionId,
+    });
+    const denialMessage = {
+        role: 'tool',
+        content: [{
+                type: 'tool-result',
+                toolCallId: state.call.toolCallId,
+                toolName: state.call.toolName,
+                output: { type: 'text', value: 'Tool call denied by user. Do not retry this action without asking the user first.' },
+            }],
+    };
+    ctx.messages = [...ctx.messages, denialMessage];
+    return {
+        next: { type: 'thinking', messages: ctx.messages },
+        effects,
+    };
+}
+//# sourceMappingURL=confirming.js.map

package/dist/src/agent/states/confirming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirming.js","sourceRoot":"","sources":["../../../../src/agent/states/confirming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAQ5C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAsB,EACtB,GAAiB;IAEjB,MAAM,OAAO,GAAe,EAAE,CAAC;IAE/B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE;QAC3C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;QACzB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;QAC7B,OAAO,EAAE,GAAG,CAAC,SAAS;KACvB,CAAC,CAAC;IAEH,kFAAkF;IAClF,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,qBAAqB,CAAC;IACnD,MAAM,cAAc,GAAG,IAAI,OAAO,CAAQ,CAAC,OAAO,EAAE,EAAE;QACpD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;QAClC,GAAG,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;QAC9C,cAAc;KACf,CAAC,CAAC;IAEH,IAAI,QAAQ,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,EAAE;YAC5C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;YACzB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YAC7B,OAAO,EAAE,GAAG,CAAC,SAAS;SACvB,CAAC,CAAC;QAEH,qEAAqE;QACrE,wDAAwD;QACxD,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEhD,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,YAAY,CAAC,QAAQ;YAC3B,aAAa,EAAE,WAAW;YAC1B,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;YACjC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;QAEH,OAAO;YACL,IAAI,EAAE;gBACJ,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,KAAK,CAAC,cAAc;gBAC3B,OAAO,EAAE,KAAK,CAAC,IAAI;gBACnB,OAAO,EAAE,EAAE;aACZ;YACD,OAAO;SACR,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE;QAC1C,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;QACzB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;QAC7B,OAAO,EAAE,GAAG,CAAC,SAAS;KACvB,CAAC,CAAC;IAEH,MAAM,aAAa,GAA8B;QAC/C,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,aAAsB;gBAC5B,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU;gBACjC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;gBAC7B,MAAM,EAAE,EAAC,IAAI,EAAE,MAAe,EAAE,KAAK,EAAE,mFAAmF,EAAC;aAC5H,CAAC;KACH,CAAC;IAEF,GAAG,CAAC,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAEhD,OAAO;QACL,IAAI,EAAE,EAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAC;QAChD,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/src/agent/states/dispatching.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { DispatchingState, AgentContext, TransitionResult } from '../loop-types.js';
+/**
+ * Handle the DISPATCHING state — run a child agent loop.
+ *
+ * Creates a child AgentContext with:
+ * - Same provider, logger, signal, tenant, user, permission checker
+ * - Tool registry subset (only the requested tools, never dispatch_task)
+ * - Same buildToolContext factory (child shares parent's connections/stores)
+ * - Reduced maxTurns (default 10) and maxContextTokens
+ * - Fresh messages (dispatch prompt as user message)
+ * - Fresh usage counters (merged back to parent after completion)
+ */
+export declare function handleDispatching(state: DispatchingState, ctx: AgentContext): Promise<TransitionResult>;

package/dist/src/agent/states/dispatching.js

@@ -0,0 +1,285 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * DISPATCHING state handler.
+ *
+ * Spawns a child agent with a subset of tools and a specific prompt.
+ * The child runs its own runAgent() loop; each child event is wrapped
+ * as an SSESubagentEvent and yielded as an effect so the client can
+ * display real-time sub-agent activity.
+ *
+ * After the child completes, the handler builds a ToolResult from the
+ * child's text response and transitions back through the normal
+ * EXECUTING post-result flow (queue, compaction, thinking).
+ */
+import { SSEEventType } from '../../types.js';
+import { createToolRegistry } from '../../tools/registry.js';
+import { DEFAULT_LOOP_CONFIG } from '../loop-types.js';
+import { runAgent } from '../loop.js';
+import { nextAfterToolResult } from './executing.js';
+import { DEFAULT_CHILD_MAX_TURNS, DISPATCH_TOOL_NAME } from '../../tools/dispatch-tool.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_CHILD_MAX_CONTEXT_TOKENS = 100_000;
+const DEFAULT_CHILD_TIMEOUT_MS = 60_000;
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+/**
+ * Handle the DISPATCHING state — run a child agent loop.
+ *
+ * Creates a child AgentContext with:
+ * - Same provider, logger, signal, tenant, user, permission checker
+ * - Tool registry subset (only the requested tools, never dispatch_task)
+ * - Same buildToolContext factory (child shares parent's connections/stores)
+ * - Reduced maxTurns (default 10) and maxContextTokens
+ * - Fresh messages (dispatch prompt as user message)
+ * - Fresh usage counters (merged back to parent after completion)
+ */
+export async function handleDispatching(state, ctx) {
+    const { task, toolCallId } = state;
+    const effects = [];
+    const startedAt = Date.now();
+    ctx.logger.info('dispatch_start', {
+        session: ctx.sessionId,
+        agent: task.agentName,
+        tools: task.toolSubset,
+        maxTurns: task.maxTurns ?? DEFAULT_CHILD_MAX_TURNS,
+        parentToolCallId: toolCallId,
+    });
+    // Short-circuit: if the parent is already out of budget, don't bother
+    // spinning up a child only to have it run one doomed turn. The child
+    // would inherit maxSessionTokens=0, burn through its first streaming
+    // call, and stop on budget_exceeded anyway. Surface a clean error
+    // result to the parent instead.
+    if (ctx.maxSessionTokens !== undefined &&
+        ctx.usage.totalTokens >= ctx.maxSessionTokens) {
+        ctx.logger.warn('dispatch_skipped_budget_exhausted', {
+            session: ctx.sessionId,
+            agent: task.agentName,
+            totalTokens: ctx.usage.totalTokens,
+            maxSessionTokens: ctx.maxSessionTokens,
+            parentToolCallId: toolCallId,
+        });
+        const result = {
+            callId: toolCallId,
+            toolName: DISPATCH_TOOL_NAME,
+            status: 'error',
+            content: `Sub-agent dispatch skipped: session token budget (${ctx.maxSessionTokens}) already reached.`,
+        };
+        effects.push({
+            type: SSEEventType.ToolCallResult,
+            tool_id: toolCallId,
+            status: result.status,
+            duration_ms: Date.now() - startedAt,
+            error: result.content,
+            timestamp: new Date().toISOString(),
+        });
+        const executingState = {
+            type: 'executing',
+            current: { toolCallId, toolName: DISPATCH_TOOL_NAME, args: {} },
+            queue: state.queue,
+            results: state.results,
+        };
+        return nextAfterToolResult(executingState, result, effects, ctx);
+    }
+    // Build child tool registry from the parent's subset
+    const childRegistry = createToolRegistry();
+    const subsetTools = ctx.toolRegistry.subset(task.toolSubset);
+    for (const [name, def] of Object.entries(subsetTools)) {
+        childRegistry.register(name, def);
+    }
+    // Child-specific timeout — prevents a slow child from starving the parent.
+    // Combined with parent's signal so parent abort also stops child.
+    const childTimeoutMs = task.timeoutMs ?? DEFAULT_CHILD_TIMEOUT_MS;
+    const childSignal = AbortSignal.any([ctx.signal, AbortSignal.timeout(childTimeoutMs)]);
+    // Minimal system prompt for the child — the full parent prompt (skills,
+    // knowledge, connection docs) is unnecessary for a focused sub-task and
+    // wastes tokens. The child gets a task-scoped prompt with available tools.
+    const childToolNames = childRegistry.names();
+    const childSystemPrompt = buildChildSystemPrompt(task.agentName, task.prompt, childToolNames);
+    // Build child context
+    const childCtx = {
+        provider: ctx.provider,
+        toolRegistry: childRegistry,
+        permissionChecker: ctx.permissionChecker,
+        logger: ctx.logger,
+        signal: childSignal,
+        sessionId: ctx.sessionId,
+        user: ctx.user,
+        systemPrompt: childSystemPrompt,
+        messages: [],
+        usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+        turnCount: 0,
+        maxTurns: task.maxTurns ?? DEFAULT_CHILD_MAX_TURNS,
+        maxContextTokens: task.maxContextTokens ?? DEFAULT_CHILD_MAX_CONTEXT_TOKENS,
+        // Propagate parent's remaining token budget so a child can't blow through
+        // more than the parent had left. Child usage merges back into parent after
+        // the child completes, so the parent's next budget check catches any
+        // overshoot on subsequent turns regardless.
+        maxSessionTokens: ctx.maxSessionTokens !== undefined
+            ? Math.max(0, ctx.maxSessionTokens - ctx.usage.totalTokens)
+            : undefined,
+        config: { ...DEFAULT_LOOP_CONFIG },
+        compactionFailures: 0,
+        preExecutionCache: new Map(),
+        confirmedCallIds: new Set(),
+        disabledToolsUntilTurn: new Map(),
+        waitForConfirmation: ctx.waitForConfirmation,
+        buildToolContext: ctx.buildToolContext,
+    };
+    // Run child agent loop and translate events to SubagentEvents
+    let childResponse = '';
+    let childFailed = false;
+    try {
+        for await (const childEvent of runAgent({ messages: [{ role: 'user', content: task.prompt }], context: childCtx })) {
+            if (ctx.signal.aborted)
+                break;
+            // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- intentionally skip child-internal events (Init, Widget, etc.)
+            switch (childEvent.type) {
+                case SSEEventType.TextDelta:
+                    childResponse += childEvent.content;
+                    effects.push({
+                        type: SSEEventType.SubagentEvent,
+                        parent_tool_id: toolCallId,
+                        agent_name: task.agentName,
+                        event_type: 'thought',
+                        text: childEvent.content,
+                        timestamp: childEvent.timestamp,
+                    });
+                    break;
+                case SSEEventType.ToolCallStart:
+                    effects.push({
+                        type: SSEEventType.SubagentEvent,
+                        parent_tool_id: toolCallId,
+                        agent_name: task.agentName,
+                        event_type: 'tool_call_start',
+                        tool_name: childEvent.tool_name,
+                        tool_args: childEvent.parameters,
+                        timestamp: childEvent.timestamp,
+                    });
+                    break;
+                case SSEEventType.ToolCallResult:
+                    effects.push({
+                        type: SSEEventType.SubagentEvent,
+                        parent_tool_id: toolCallId,
+                        agent_name: task.agentName,
+                        event_type: 'tool_call_end',
+                        tool_name: undefined,
+                        result: childEvent.status === 'error' ? childEvent.error : undefined,
+                        timestamp: childEvent.timestamp,
+                    });
+                    break;
+                case SSEEventType.Error:
+                    effects.push({
+                        type: SSEEventType.SubagentEvent,
+                        parent_tool_id: toolCallId,
+                        agent_name: task.agentName,
+                        event_type: 'error',
+                        error: childEvent.message,
+                        timestamp: childEvent.timestamp,
+                    });
+                    break;
+                case SSEEventType.Done:
+                    effects.push({
+                        type: SSEEventType.SubagentEvent,
+                        parent_tool_id: toolCallId,
+                        agent_name: task.agentName,
+                        event_type: 'complete',
+                        timestamp: childEvent.timestamp,
+                    });
+                    break;
+                default:
+                    // Skip Init and other events — they're child-internal
+                    break;
+            }
+        }
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        ctx.logger.error('dispatch_child_error', {
+            session: ctx.sessionId,
+            agent: task.agentName,
+            error: errorMessage,
+            parentToolCallId: toolCallId,
+        });
+        effects.push({
+            type: SSEEventType.SubagentEvent,
+            parent_tool_id: toolCallId,
+            agent_name: task.agentName,
+            event_type: 'error',
+            error: errorMessage,
+            timestamp: new Date().toISOString(),
+        });
+        childResponse = `Sub-agent "${task.agentName}" failed: ${errorMessage}`;
+        childFailed = true;
+    }
+    // Merge child usage into parent
+    ctx.usage.inputTokens += childCtx.usage.inputTokens;
+    ctx.usage.outputTokens += childCtx.usage.outputTokens;
+    ctx.usage.totalTokens += childCtx.usage.totalTokens;
+    if (childCtx.usage.cachedInputTokens) {
+        ctx.usage.cachedInputTokens = (ctx.usage.cachedInputTokens ?? 0) + childCtx.usage.cachedInputTokens;
+    }
+    if (childCtx.usage.cacheCreationInputTokens) {
+        ctx.usage.cacheCreationInputTokens = (ctx.usage.cacheCreationInputTokens ?? 0) + childCtx.usage.cacheCreationInputTokens;
+    }
+    const duration = Date.now() - startedAt;
+    ctx.logger.info('dispatch_complete', {
+        session: ctx.sessionId,
+        agent: task.agentName,
+        childTurns: childCtx.turnCount,
+        childUsage: childCtx.usage,
+        responseLength: childResponse.length,
+        parentToolCallId: toolCallId,
+        duration,
+    });
+    // Build tool result from child response
+    const result = {
+        callId: toolCallId,
+        toolName: DISPATCH_TOOL_NAME,
+        status: childFailed ? 'error' : 'success',
+        content: childResponse || '(no response from sub-agent)',
+    };
+    // Emit ToolCallResult for the dispatch_task call
+    effects.push({
+        type: SSEEventType.ToolCallResult,
+        tool_id: toolCallId,
+        status: result.status,
+        duration_ms: duration,
+        ...(result.status === 'error' ? { error: result.content } : {}),
+        timestamp: new Date().toISOString(),
+    });
+    // Use the shared post-result transition logic from EXECUTING.
+    // This handles: append tool result message, continue queue, compaction check.
+    const executingState = {
+        type: 'executing',
+        current: { toolCallId, toolName: DISPATCH_TOOL_NAME, args: {} },
+        queue: state.queue,
+        results: state.results,
+    };
+    return nextAfterToolResult(executingState, result, effects, ctx);
+}
+// ---------------------------------------------------------------------------
+// Child system prompt
+// ---------------------------------------------------------------------------
+/**
+ * Build a minimal system prompt for the child agent.
+ *
+ * The full parent prompt (30K+ chars of skills, knowledge, connection docs)
+ * is wasteful for a focused sub-task. The child gets a concise, task-scoped
+ * prompt listing only its available tools.
+ */
+function buildChildSystemPrompt(agentName, taskPrompt, toolNames) {
+    const toolList = toolNames.length > 0
+        ? `\n\nAvailable tools: ${toolNames.join(', ')}`
+        : '';
+    return `You are "${agentName}", a sub-agent executing a delegated task. Complete the task and return a concise summary of your findings or actions.
+
+Do not ask clarifying questions — work with what you have. If you cannot complete the task, explain what went wrong.${toolList}`;
+}
+//# sourceMappingURL=dispatching.js.map