@nanoagent/kernel 0.0.0

package/dist/index.js

@@ -0,0 +1,1136 @@
+import { randomUUID } from 'node:crypto';
+import { bedrock } from '@ai-sdk/amazon-bedrock';
+import { anthropic } from '@ai-sdk/anthropic';
+import { azure } from '@ai-sdk/azure';
+import { baseten } from '@ai-sdk/baseten';
+import { cerebras } from '@ai-sdk/cerebras';
+import { cohere } from '@ai-sdk/cohere';
+import { deepinfra } from '@ai-sdk/deepinfra';
+import { deepseek } from '@ai-sdk/deepseek';
+import { fireworks } from '@ai-sdk/fireworks';
+import { google } from '@ai-sdk/google';
+import { vertex } from '@ai-sdk/google-vertex';
+import { groq } from '@ai-sdk/groq';
+import { mistral } from '@ai-sdk/mistral';
+import { openai } from '@ai-sdk/openai';
+import { perplexity } from '@ai-sdk/perplexity';
+import { togetherai } from '@ai-sdk/togetherai';
+import { vercel } from '@ai-sdk/vercel';
+import { xai } from '@ai-sdk/xai';
+import { Effect } from 'effect';
+import { jsonSchema, streamText } from 'ai';
+const DEFAULT_MODEL_PROVIDERS = {
+    openai,
+    anthropic,
+    azure,
+    baseten,
+    cerebras,
+    cohere,
+    deepinfra,
+    deepseek,
+    fireworks,
+    google,
+    gemini: google,
+    vertex,
+    'google-vertex': vertex,
+    groq,
+    grok: xai,
+    mistral,
+    perplexity,
+    together: togetherai,
+    togetherai,
+    bedrock,
+    'amazon-bedrock': bedrock,
+    vercel,
+    xai
+};
+function normalizeModelProviders(modelProviders) {
+    return Object.fromEntries(Object.entries(modelProviders ?? {})
+        .map(([provider, modelProvider]) => [
+        provider.trim().toLowerCase(),
+        modelProvider
+    ])
+        .filter(([provider]) => provider));
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            name: error.name,
+            stack: error.stack
+        };
+    }
+    return { message: String(error) };
+}
+function fromAgentResult(evaluate) {
+    return Effect.flatMap(Effect.try({
+        try: evaluate,
+        catch: toError
+    }), result => Effect.isEffect(result)
+        ? result
+        : Effect.tryPromise({
+            try: () => Promise.resolve(result),
+            catch: toError
+        }));
+}
+function runMiddleware({ input, middleware, terminal }) {
+    const operation = (middleware ?? []).reduceRight((next, current) => input => fromAgentResult(() => current({
+        input,
+        next: nextInput => Effect.runPromise(next(nextInput))
+    })), input => fromAgentResult(() => terminal(input)));
+    return operation(input);
+}
+function checkNotAborted(signal) {
+    if (!signal?.aborted) {
+        return Effect.void;
+    }
+    return Effect.fail(signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Agent run aborted.'));
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function durationMs(startCreatedAt, endCreatedAt) {
+    return Date.parse(endCreatedAt) - Date.parse(startCreatedAt);
+}
+function cloneUnknown(value) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        if (Array.isArray(value)) {
+            return value.map(item => cloneUnknown(item));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype === Object.prototype || prototype === null) {
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneUnknown(entry)]));
+        }
+        return value;
+    }
+}
+function cloneModelResult(modelResult) {
+    return {
+        ...modelResult,
+        response: {
+            ...modelResult.response,
+            messages: [...modelResult.response.messages]
+        }
+    };
+}
+function cloneTurn(turn) {
+    return {
+        turnId: turn.turnId,
+        turn: turn.turn,
+        modelArgs: turn.modelArgs ? cloneUnknown(turn.modelArgs) : undefined,
+        modelResult: turn.modelResult
+            ? cloneModelResult(turn.modelResult)
+            : undefined,
+        toolCalls: {
+            pending: turn.toolCalls.pending.map(cloneToolCall),
+            inFlight: turn.toolCalls.inFlight.map(cloneToolCall),
+            completed: [...turn.toolCalls.completed]
+        }
+    };
+}
+function cloneToolCall(toolCall) {
+    return {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: cloneUnknown(toolCall.input)
+    };
+}
+function deepFreeze(value, seen = new WeakSet()) {
+    if (typeof value !== 'object' || value === null) {
+        return value;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) &&
+        prototype !== Object.prototype &&
+        prototype !== null) {
+        return value;
+    }
+    if (seen.has(value)) {
+        return value;
+    }
+    seen.add(value);
+    for (const property of Reflect.ownKeys(value)) {
+        deepFreeze(value[property], seen);
+    }
+    return Object.freeze(value);
+}
+function isSkip(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        value.type === 'skip');
+}
+function toModelTools(tools) {
+    return Object.fromEntries(Object.entries(tools).map(([toolName, toolConfig]) => {
+        const { execute: _execute, ...definition } = toolConfig;
+        if (isRawJsonSchema(definition.inputSchema)) {
+            definition.inputSchema = jsonSchema(definition.inputSchema);
+        }
+        return [toolName, definition];
+    }));
+}
+function isRawJsonSchema(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        'type' in value &&
+        !('validate' in value));
+}
+function resolveModel({ model, modelProviders }) {
+    const [rawProvider, ...modelParts] = model.split('/');
+    const modelName = modelParts.join('/').trim();
+    const provider = rawProvider?.trim().toLowerCase();
+    if (!provider || !modelName) {
+        return Effect.fail(new Error(`Invalid model "${model}". Expected "<provider>/<model-name>".`));
+    }
+    const modelProvider = modelProviders[provider];
+    if (!modelProvider) {
+        return Effect.fail(new Error(`Unsupported model provider "${provider}". Supported providers: ${Object.keys(modelProviders).join(', ')}.`));
+    }
+    return Effect.try({
+        try: () => modelProvider(modelName),
+        catch: toError
+    });
+}
+async function buildModelResult(result) {
+    const [response, finishReason, totalUsage, text, reasoning, reasoningText, sources, warnings, providerMetadata] = await Promise.all([
+        result.response,
+        result.finishReason,
+        result.totalUsage,
+        result.text,
+        result.reasoning,
+        result.reasoningText,
+        result.sources,
+        result.warnings,
+        result.providerMetadata
+    ]);
+    return {
+        finishReason,
+        response,
+        totalUsage,
+        text,
+        reasoning,
+        reasoningText,
+        sources,
+        warnings,
+        providerMetadata
+    };
+}
+function makeBaseArgs(state) {
+    const readonlyState = deepFreeze(cloneUnknown(state));
+    return {
+        context: readonlyState.context,
+        state: readonlyState,
+        runId: state.runId
+    };
+}
+function emptyToolCalls() {
+    return { pending: [], inFlight: [], completed: [] };
+}
+function persistSnapshot({ events, previousRevision, saveState, state }) {
+    const snapshottedState = {
+        ...state,
+        revision: previousRevision + 1,
+        updatedAt: nowIso()
+    };
+    const snapshottedEvents = events.map(event => 'revision' in event
+        ? { ...event, revision: snapshottedState.revision }
+        : event);
+    return Effect.gen(function* () {
+        if (saveState) {
+            yield* fromAgentResult(() => saveState({
+                state: cloneUnknown(snapshottedState),
+                events: snapshottedEvents
+            }));
+        }
+        return {
+            events: snapshottedEvents,
+            state: snapshottedState
+        };
+    });
+}
+function withRunning(state, phase) {
+    return {
+        ...state,
+        status: { type: 'running', phase }
+    };
+}
+function recoverablePhase(state) {
+    if (state.status.type === 'running' || state.status.type === 'paused') {
+        return state.status.phase;
+    }
+    if (state.status.type === 'failed') {
+        return state.status.phase;
+    }
+    return 'run_started';
+}
+function applyContext({ snapshot, hookResult }) {
+    if (hookResult?.context !== undefined) {
+        return {
+            ...snapshot,
+            context: hookResult.context
+        };
+    }
+    return snapshot;
+}
+async function snapshotPause({ pause, snapshotter, snapshot }) {
+    if (snapshot.status.type !== 'running') {
+        throw new Error('Cannot pause a run that is not running.');
+    }
+    const createdAt = nowIso();
+    const phase = snapshot.status.phase;
+    return snapshotter({
+        ...snapshot,
+        status: {
+            type: 'paused',
+            phase,
+            reason: pause.reason,
+            metadata: pause.metadata,
+            createdAt
+        }
+    }, [
+        {
+            type: 'pause',
+            runId: snapshot.runId,
+            revision: snapshot.revision,
+            createdAt,
+            phase,
+            turn: snapshot.currentTurn
+                ? cloneTurn(snapshot.currentTurn)
+                : undefined,
+            reason: pause.reason,
+            metadata: pause.metadata
+        }
+    ]);
+}
+function executeToolCall({ context, toolCall, messages, signal, tools }) {
+    const execute = tools[toolCall.toolName]?.execute;
+    if (!execute) {
+        return Effect.fail(new Error(`Tool "${toolCall.toolName}" is not executable.`));
+    }
+    const response = {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        input: toolCall.input
+    };
+    return Effect.match(Effect.tryPromise({
+        try: async () => {
+            const output = await execute(toolCall.input, {
+                toolCallId: toolCall.toolCallId,
+                messages,
+                abortSignal: signal,
+                experimental_context: context
+            });
+            if (typeof output !== 'object' ||
+                output === null ||
+                !(Symbol.asyncIterator in output)) {
+                return output;
+            }
+            let finalOutput;
+            for await (const chunk of output) {
+                finalOutput = chunk;
+            }
+            return finalOutput;
+        },
+        catch: toError
+    }), {
+        onFailure: error => ({ ...response, error }),
+        onSuccess: output => ({ ...response, output })
+    });
+}
+export async function* runAgent(options) {
+    const tools = options.tools ?? {};
+    const modelProviders = {
+        ...DEFAULT_MODEL_PROVIDERS,
+        ...normalizeModelProviders(options.modelProviders)
+    };
+    let snapshot = 'status' in options.state
+        ? cloneUnknown(options.state)
+        : {
+            runId: options.state.runId ?? randomUUID(),
+            revision: 0,
+            status: { type: 'running', phase: 'run_started' },
+            context: options.state.context,
+            turns: [],
+            updatedAt: nowIso()
+        };
+    const hooks = options.hooks;
+    const runCreatedAt = snapshot.updatedAt;
+    // Caller-emitted finish from any hook. The main loop consumes this and
+    // transitions to status.completed at the next checkpoint.
+    let pendingFinish;
+    let pendingContinue = false;
+    async function* emitEvents(events) {
+        for (const event of events) {
+            if (event.type === 'pause') {
+                await Effect.runPromise(fromAgentResult(() => hooks.onPause?.({
+                    ...makeBaseArgs(snapshot),
+                    createdAt: event.createdAt,
+                    phase: event.phase,
+                    turn: event.turn,
+                    reason: event.reason,
+                    metadata: event.metadata
+                })));
+            }
+            else if (event.type === 'model_restarted') {
+                await Effect.runPromise(fromAgentResult(() => hooks.onModelRestarted?.({
+                    ...makeBaseArgs(snapshot),
+                    createdAt: event.createdAt,
+                    turn: event.turn
+                })));
+            }
+            yield event;
+        }
+    }
+    const snapshotState = async (nextSnapshot, events) => {
+        const snapshotted = await Effect.runPromise(persistSnapshot({
+            events,
+            previousRevision: snapshot.revision,
+            saveState: options.saveState,
+            state: nextSnapshot
+        }));
+        snapshot = snapshotted.state;
+        return snapshotted.events;
+    };
+    function isPaused() {
+        return snapshot.status.type === 'paused';
+    }
+    function phaseEvent(type) {
+        if (type === 'run_started') {
+            return {
+                type,
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt: nowIso()
+            };
+        }
+        if (!snapshot.currentTurn) {
+            throw new Error(`Cannot emit ${type} without a current turn.`);
+        }
+        return {
+            type,
+            runId: snapshot.runId,
+            revision: snapshot.revision,
+            createdAt: nowIso(),
+            turn: cloneTurn(snapshot.currentTurn)
+        };
+    }
+    async function applyHookResult(hookResult, options = {}) {
+        const hasContextUpdate = hookResult?.context !== undefined;
+        snapshot = applyContext({ snapshot, hookResult });
+        const control = hookResult?.control;
+        if (control?.type === 'pause') {
+            const onPause = options.onPause ??
+                ((pause) => snapshotPause({
+                    snapshotter: snapshotState,
+                    pause,
+                    snapshot
+                }));
+            return {
+                events: await onPause(control)
+            };
+        }
+        if (control?.type === 'finish' && options.onFinish !== 'ignore') {
+            pendingFinish = {
+                source: 'caller',
+                reason: control.reason,
+                metadata: control.metadata
+            };
+            return { events: [] };
+        }
+        if (control?.type === 'continue' && options.onContinue !== 'ignore') {
+            pendingContinue = true;
+            return { events: [] };
+        }
+        if (hasContextUpdate && options.persistContext) {
+            return { events: await snapshotState(snapshot, []) };
+        }
+        return { value: hookResult?.value };
+    }
+    async function prepareStartedTurn(prefixEvents = []) {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn) {
+            throw new Error('Cannot prepare turn without a current turn.');
+        }
+        const preparedHook = await Effect.runPromise(fromAgentResult(() => hooks.onTurnPrepared({
+            ...makeBaseArgs(snapshot),
+            createdAt: nowIso(),
+            turn: cloneTurn(currentTurn)
+        })));
+        const preparedResult = await applyHookResult(preparedHook);
+        if (preparedResult.events) {
+            return { events: [...prefixEvents, ...preparedResult.events] };
+        }
+        if (!preparedResult.value) {
+            throw new Error('onTurnPrepared must return a turn configuration.');
+        }
+        const { model: preparedModel, ...streamTextOptions } = preparedResult.value;
+        const modelArgs = {
+            ...streamTextOptions,
+            model: preparedModel,
+            toolNames: Object.keys(tools)
+        };
+        const preparedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'turn_prepared' },
+            currentTurn: {
+                ...snapshot.currentTurn,
+                modelArgs
+            }
+        };
+        snapshot = preparedSnapshot;
+        return {
+            events: [
+                ...prefixEvents,
+                ...(await snapshotState(preparedSnapshot, [
+                    phaseEvent('turn_prepared')
+                ]))
+            ]
+        };
+    }
+    async function prepareTurn(turnNumber) {
+        const turnId = randomUUID();
+        const turnCreatedAt = nowIso();
+        const startedTurn = {
+            turnId,
+            turn: turnNumber,
+            toolCalls: emptyToolCalls()
+        };
+        const turnStartedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'turn_started' },
+            currentTurn: startedTurn
+        };
+        snapshot = turnStartedSnapshot;
+        const turnStartedEvents = await snapshotState(turnStartedSnapshot, [
+            phaseEvent('turn_started')
+        ]);
+        const turnStartedHook = await Effect.runPromise(fromAgentResult(() => hooks.onTurnStarted?.({
+            ...makeBaseArgs(snapshot),
+            createdAt: turnCreatedAt,
+            turn: cloneTurn(startedTurn)
+        })));
+        const turnStartedResult = await applyHookResult(turnStartedHook, {
+            persistContext: true
+        });
+        if ((isPaused() || pendingFinish) && turnStartedResult.events) {
+            return { events: [...turnStartedEvents, ...turnStartedResult.events] };
+        }
+        return prepareStartedTurn(turnStartedEvents);
+    }
+    async function* runModel() {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn?.modelArgs) {
+            throw new Error('Cannot run model without a prepared turn.');
+        }
+        const modelArgs = {
+            ...currentTurn.modelArgs,
+            toolNames: [...currentTurn.modelArgs.toolNames]
+        };
+        const modelStartedAt = nowIso();
+        const wasResumingFromModelStarted = snapshot.status.type === 'running' &&
+            snapshot.status.phase === 'model_started';
+        const modelStartedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'model_started' }
+        };
+        snapshot = modelStartedSnapshot;
+        const startedEvents = wasResumingFromModelStarted
+            ? [
+                {
+                    type: 'model_restarted',
+                    runId: snapshot.runId,
+                    createdAt: nowIso(),
+                    turn: cloneTurn(currentTurn)
+                }
+            ]
+            : await snapshotState(modelStartedSnapshot, [phaseEvent('model_started')]);
+        yield* emitEvents(startedEvents);
+        const modelStartedHook = await Effect.runPromise(fromAgentResult(() => hooks.onModelStarted?.({
+            ...makeBaseArgs(snapshot),
+            args: modelArgs,
+            createdAt: modelStartedAt,
+            turn: cloneTurn(currentTurn)
+        })));
+        const modelStartedResult = await applyHookResult(modelStartedHook, {
+            persistContext: true
+        });
+        if ((isPaused() || pendingFinish) && modelStartedResult.events) {
+            yield* emitEvents(modelStartedResult.events);
+            return;
+        }
+        const streamEvents = [];
+        const callModelResult = await Effect.runPromise(runMiddleware({
+            input: {
+                ...makeBaseArgs(snapshot),
+                args: modelArgs,
+                createdAt: modelStartedAt,
+                turn: cloneTurn(currentTurn)
+            },
+            middleware: options.middleware?.callModel,
+            terminal: async (input) => {
+                const { model: modelName, toolNames: _toolNames, ...streamTextOptions } = input.args;
+                const model = await Effect.runPromise(resolveModel({ model: modelName, modelProviders }));
+                const rawResult = await Effect.runPromise(Effect.try({
+                    try: () => streamText({
+                        ...streamTextOptions,
+                        model,
+                        tools: toModelTools(tools),
+                        abortSignal: options.signal
+                    }),
+                    catch: toError
+                }));
+                const attemptStreamEvents = [];
+                for await (const part of rawResult.fullStream) {
+                    await Effect.runPromise(checkNotAborted(options.signal));
+                    attemptStreamEvents.push({
+                        type: 'stream_part',
+                        runId: snapshot.runId,
+                        turnId: currentTurn.turnId,
+                        turn: currentTurn.turn,
+                        createdAt: nowIso(),
+                        part
+                    });
+                }
+                const modelResult = cloneModelResult(await buildModelResult(rawResult));
+                const pendingToolCalls = modelResult.finishReason === 'tool-calls'
+                    ? (await Effect.runPromise(Effect.tryPromise({
+                        try: () => rawResult.toolCalls,
+                        catch: toError
+                    }))).map(cloneToolCall)
+                    : [];
+                const completedAt = nowIso();
+                streamEvents.push(...attemptStreamEvents);
+                return {
+                    args: {
+                        ...input.args,
+                        toolNames: [...input.args.toolNames]
+                    },
+                    duration: durationMs(input.createdAt, completedAt),
+                    pendingToolCalls,
+                    rawResult,
+                    result: modelResult
+                };
+            }
+        }));
+        const completedAt = nowIso();
+        for (const event of streamEvents) {
+            await Effect.runPromise(fromAgentResult(() => hooks.onStreamUpdate?.({
+                ...makeBaseArgs(snapshot),
+                createdAt: event.createdAt,
+                part: event.part,
+                turn: cloneTurn(currentTurn)
+            })));
+            yield* emitEvents([event]);
+        }
+        const modelCompletedHook = await Effect.runPromise(fromAgentResult(() => hooks.onModelCompleted?.({
+            ...makeBaseArgs(snapshot),
+            args: callModelResult.args,
+            createdAt: completedAt,
+            duration: callModelResult.duration,
+            result: cloneModelResult(callModelResult.result),
+            rawResult: callModelResult.rawResult,
+            turn: cloneTurn({
+                ...currentTurn,
+                modelArgs: callModelResult.args
+            })
+        })));
+        const modelCompletedResult = await applyHookResult(modelCompletedHook);
+        if (modelCompletedResult.events) {
+            yield* emitEvents(modelCompletedResult.events);
+            return;
+        }
+        const nextTurn = {
+            ...currentTurn,
+            modelArgs: callModelResult.args,
+            modelResult: callModelResult.result,
+            toolCalls: {
+                pending: callModelResult.pendingToolCalls,
+                inFlight: [],
+                completed: []
+            }
+        };
+        const modelCompletedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'model_completed' },
+            currentTurn: nextTurn
+        };
+        snapshot = modelCompletedSnapshot;
+        yield* emitEvents(await snapshotState(modelCompletedSnapshot, [
+            {
+                type: 'model_completed',
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt: completedAt,
+                duration: callModelResult.duration,
+                args: callModelResult.args,
+                result: cloneModelResult(callModelResult.result),
+                turn: cloneTurn(nextTurn)
+            }
+        ]));
+    }
+    async function* prepareToolCalls() {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn?.modelResult) {
+            throw new Error('Cannot prepare tool calls without model result.');
+        }
+        const modelResult = currentTurn.modelResult;
+        const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onToolCallsStarted?.({
+            ...makeBaseArgs(snapshot),
+            createdAt: nowIso(),
+            result: cloneModelResult(modelResult),
+            toolCalls: deepFreeze(currentTurn.toolCalls.pending.map(cloneToolCall)),
+            turn: cloneTurn(currentTurn)
+        })));
+        const hook = await applyHookResult(hookResult);
+        if (hook.events) {
+            yield* emitEvents(hook.events);
+            return;
+        }
+        const preparedToolCalls = (hook.value ?? currentTurn.toolCalls.pending).map(cloneToolCall);
+        const nextTurn = {
+            ...currentTurn,
+            toolCalls: {
+                pending: preparedToolCalls,
+                inFlight: [],
+                completed: []
+            }
+        };
+        const nextSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'tool_calls_started' },
+            currentTurn: nextTurn
+        };
+        snapshot = nextSnapshot;
+        yield* emitEvents(await snapshotState(nextSnapshot, [phaseEvent('tool_calls_started')]));
+    }
+    async function* prepareEachToolCall() {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn) {
+            throw new Error('Cannot start tool calls without a current turn.');
+        }
+        const accepted = [];
+        const completed = [
+            ...currentTurn.toolCalls.completed
+        ];
+        const pendingToolCalls = currentTurn.toolCalls.pending;
+        for (const [index, originalToolCall] of pendingToolCalls.entries()) {
+            const hookToolCall = deepFreeze(cloneToolCall(originalToolCall));
+            const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onToolCallStarted?.({
+                ...makeBaseArgs(snapshot),
+                createdAt: nowIso(),
+                toolCall: hookToolCall,
+                toolCallId: hookToolCall.toolCallId,
+                toolName: hookToolCall.toolName,
+                input: hookToolCall.input,
+                turn: cloneTurn(snapshot.currentTurn)
+            })));
+            const hook = await applyHookResult(hookResult, {
+                onPause: pause => {
+                    snapshot = {
+                        ...snapshot,
+                        status: { type: 'running', phase: 'tool_calls_started' },
+                        currentTurn: {
+                            ...snapshot.currentTurn,
+                            toolCalls: {
+                                pending: [
+                                    ...accepted,
+                                    originalToolCall,
+                                    ...pendingToolCalls.slice(index + 1)
+                                ],
+                                inFlight: [],
+                                completed: [...completed]
+                            }
+                        }
+                    };
+                    return snapshotPause({
+                        snapshotter: snapshotState,
+                        pause,
+                        snapshot
+                    });
+                }
+            });
+            if (hook.events) {
+                yield* emitEvents(hook.events);
+                return;
+            }
+            if (isSkip(hook.value)) {
+                completed.push({
+                    ...hook.value.result,
+                    toolCallId: originalToolCall.toolCallId,
+                    toolName: originalToolCall.toolName
+                });
+            }
+            else {
+                accepted.push(cloneToolCall(hook.value ?? originalToolCall));
+            }
+            const startedSnapshot = {
+                ...snapshot,
+                status: { type: 'running', phase: 'tool_call_started' },
+                currentTurn: {
+                    ...snapshot.currentTurn,
+                    toolCalls: {
+                        pending: [...accepted],
+                        inFlight: [],
+                        completed: [...completed]
+                    }
+                }
+            };
+            snapshot = startedSnapshot;
+            yield* emitEvents(await snapshotState(startedSnapshot, [phaseEvent('tool_call_started')]));
+        }
+    }
+    async function* executePreparedTools() {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn?.modelArgs) {
+            throw new Error('Cannot execute tools without tool snapshot.');
+        }
+        const launchedToolCalls = currentTurn.toolCalls.pending.map(cloneToolCall);
+        const toolMessages = 'messages' in currentTurn.modelArgs && currentTurn.modelArgs.messages
+            ? currentTurn.modelArgs.messages
+            : Array.isArray(currentTurn.modelArgs.prompt)
+                ? currentTurn.modelArgs.prompt
+                : [];
+        const launchedSnapshot = {
+            ...snapshot,
+            status: {
+                type: 'running',
+                phase: snapshot.status.type === 'running'
+                    ? snapshot.status.phase
+                    : 'tool_call_started'
+            },
+            currentTurn: {
+                ...currentTurn,
+                toolCalls: {
+                    pending: [],
+                    inFlight: launchedToolCalls,
+                    completed: [...currentTurn.toolCalls.completed]
+                }
+            }
+        };
+        snapshot = launchedSnapshot;
+        yield* emitEvents(await snapshotState(launchedSnapshot, []));
+        const startedAtByToolCall = new Map(launchedToolCalls.map(toolCall => [toolCall.toolCallId, nowIso()]));
+        const results = await Effect.runPromise(Effect.all(launchedToolCalls.map(toolCall => runMiddleware({
+            input: {
+                context: snapshot.context,
+                messages: toolMessages,
+                ...(options.signal ? { signal: options.signal } : {}),
+                toolCall: cloneToolCall(toolCall),
+                tools
+            },
+            middleware: options.middleware?.callTool,
+            terminal: executeToolCall
+        })), { concurrency: 'unbounded' }));
+        for (const response of results) {
+            await Effect.runPromise(checkNotAborted(options.signal));
+            const completedAt = nowIso();
+            const responseResult = response.error !== undefined
+                ? { error: response.error }
+                : { output: response.output };
+            const duration = durationMs(startedAtByToolCall.get(response.toolCallId) ?? completedAt, completedAt);
+            const turnAfterResponse = {
+                ...snapshot.currentTurn,
+                toolCalls: {
+                    pending: [],
+                    inFlight: snapshot.currentTurn.toolCalls.inFlight.filter(toolCall => toolCall.toolCallId !== response.toolCallId),
+                    completed: [...snapshot.currentTurn.toolCalls.completed, response]
+                }
+            };
+            const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onToolCallCompleted?.({
+                ...makeBaseArgs(snapshot),
+                createdAt: completedAt,
+                duration,
+                toolCallId: response.toolCallId,
+                toolName: response.toolName,
+                input: response.input,
+                turn: cloneTurn(turnAfterResponse),
+                ...responseResult
+            })));
+            const hook = await applyHookResult(hookResult);
+            if (hook.events) {
+                yield* emitEvents(hook.events);
+                return;
+            }
+            const completedSnapshot = {
+                ...snapshot,
+                status: { type: 'running', phase: 'tool_call_completed' },
+                currentTurn: turnAfterResponse
+            };
+            const completionEvent = {
+                type: 'tool_call_completed',
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt: completedAt,
+                duration,
+                turn: cloneTurn(turnAfterResponse),
+                toolCallId: response.toolCallId,
+                toolName: response.toolName,
+                input: response.input,
+                ...responseResult
+            };
+            snapshot = completedSnapshot;
+            yield* emitEvents(await snapshotState(completedSnapshot, [completionEvent]));
+        }
+    }
+    async function* completeToolCalls() {
+        const currentTurn = snapshot.currentTurn;
+        const modelResult = currentTurn?.modelResult;
+        if (!currentTurn || !modelResult) {
+            throw new Error('Cannot complete tool calls without model result.');
+        }
+        const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onToolCallsCompleted?.({
+            ...makeBaseArgs(snapshot),
+            createdAt: nowIso(),
+            result: cloneModelResult(modelResult),
+            toolCalls: currentTurn.toolCalls.completed,
+            turn: cloneTurn(currentTurn)
+        })));
+        const hook = await applyHookResult(hookResult);
+        if (hook.events) {
+            yield* emitEvents(hook.events);
+            return;
+        }
+        const completedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'tool_calls_completed' }
+        };
+        snapshot = completedSnapshot;
+        yield* emitEvents(await snapshotState(completedSnapshot, [
+            phaseEvent('tool_calls_completed')
+        ]));
+    }
+    async function* completeTurn() {
+        const currentTurn = snapshot.currentTurn;
+        if (!currentTurn?.modelResult) {
+            throw new Error('Cannot complete turn without model result.');
+        }
+        const completedAt = nowIso();
+        const duration = 0;
+        const completedTurn = cloneTurn(currentTurn);
+        // Record the turn before running the post-completion hook. The turn
+        // happened; hook decisions (pause, finish, continue) shouldn't undo it.
+        const completedSnapshot = {
+            ...snapshot,
+            status: { type: 'running', phase: 'turn_completed' },
+            turns: [...snapshot.turns, completedTurn],
+            currentTurn: undefined
+        };
+        snapshot = completedSnapshot;
+        yield* emitEvents(await snapshotState(completedSnapshot, [
+            {
+                type: 'turn_completed',
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt: completedAt,
+                duration,
+                turn: cloneTurn(completedTurn)
+            }
+        ]));
+        const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onTurnCompleted?.({
+            ...makeBaseArgs(snapshot),
+            createdAt: completedAt,
+            duration,
+            turn: cloneTurn(completedTurn)
+        })));
+        const hook = await applyHookResult(hookResult);
+        if (hook.events) {
+            yield* emitEvents(hook.events);
+            return;
+        }
+    }
+    async function* completeRun({ source, reason, metadata }) {
+        const completedAt = nowIso();
+        const duration = durationMs(runCreatedAt, completedAt);
+        const turns = snapshot.turns.map(cloneTurn);
+        const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onRunCompleted?.({
+            ...makeBaseArgs(snapshot),
+            createdAt: completedAt,
+            duration,
+            turns: turns.map(cloneTurn)
+        })));
+        // Inside completeRun, finish is meaningless — we're already finishing.
+        // Pause is still honored.
+        const hook = await applyHookResult(hookResult, {
+            onFinish: 'ignore',
+            onContinue: 'ignore'
+        });
+        if (hook.events) {
+            yield* emitEvents(hook.events);
+            return;
+        }
+        const completedSnapshot = {
+            ...snapshot,
+            status: {
+                type: 'completed',
+                source,
+                reason,
+                metadata,
+                createdAt: completedAt
+            }
+        };
+        snapshot = completedSnapshot;
+        yield* emitEvents(await snapshotState(completedSnapshot, [
+            {
+                type: 'run_completed',
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt: completedAt,
+                duration,
+                turns: turns.map(cloneTurn),
+                source,
+                reason,
+                metadata
+            }
+        ]));
+    }
+    async function failRun(error) {
+        const createdAt = nowIso();
+        const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onRunFailed?.({
+            ...makeBaseArgs(snapshot),
+            createdAt,
+            error
+        })));
+        snapshot = applyContext({ snapshot, hookResult });
+        const failure = serializeError(error);
+        const phase = recoverablePhase(snapshot);
+        const failedSnapshot = {
+            ...snapshot,
+            status: { type: 'failed', phase, error: failure, createdAt }
+        };
+        snapshot = failedSnapshot;
+        return snapshotState(failedSnapshot, [
+            {
+                type: 'run_failed',
+                runId: snapshot.runId,
+                revision: snapshot.revision,
+                createdAt,
+                phase,
+                error: failure
+            }
+        ]);
+    }
+    try {
+        await Effect.runPromise(checkNotAborted(options.signal));
+        if (snapshot.status.type === 'paused' ||
+            snapshot.status.type === 'failed') {
+            const phase = snapshot.status.phase;
+            const resumedSnapshot = withRunning(snapshot, phase);
+            snapshot = resumedSnapshot;
+            yield* emitEvents(await snapshotState(resumedSnapshot, []));
+        }
+        if (snapshot.revision === 0 &&
+            snapshot.status.type === 'running' &&
+            snapshot.status.phase === 'run_started') {
+            const runStartedAt = nowIso();
+            const hookResult = await Effect.runPromise(fromAgentResult(() => hooks.onRunStarted?.({
+                ...makeBaseArgs(snapshot),
+                createdAt: runStartedAt
+            })));
+            const hook = await applyHookResult(hookResult);
+            if (hook.events) {
+                yield* emitEvents(hook.events);
+                return;
+            }
+            yield* emitEvents(await snapshotState(snapshot, [phaseEvent('run_started')]));
+        }
+        while (snapshot.status.type === 'running') {
+            await Effect.runPromise(checkNotAborted(options.signal));
+            if (isPaused()) {
+                return;
+            }
+            if (pendingFinish) {
+                const request = pendingFinish;
+                pendingFinish = undefined;
+                yield* completeRun(request);
+                continue;
+            }
+            const phase = snapshot.status
+                .phase;
+            switch (phase) {
+                case 'run_started':
+                case 'turn_completed': {
+                    if (phase === 'turn_completed') {
+                        const lastTurn = snapshot.turns.at(-1);
+                        if (!lastTurn?.modelResult) {
+                            throw new Error('Invalid state: turn_completed without a recorded turn.');
+                        }
+                        if (lastTurn.turn >= options.maxTurns) {
+                            yield* completeRun({
+                                source: 'max_turns',
+                                metadata: { maxTurns: options.maxTurns }
+                            });
+                            continue;
+                        }
+                        if (pendingContinue) {
+                            pendingContinue = false;
+                        }
+                        else if (lastTurn.toolCalls.completed.length === 0) {
+                            yield* completeRun({ source: 'model_done' });
+                            continue;
+                        }
+                    }
+                    const nextTurnNumber = snapshot.turns.length + 1;
+                    const prepared = await prepareTurn(nextTurnNumber);
+                    yield* emitEvents(prepared.events);
+                    continue;
+                }
+                case 'turn_started': {
+                    const prepared = await prepareStartedTurn();
+                    yield* emitEvents(prepared.events);
+                    continue;
+                }
+                case 'turn_prepared':
+                case 'model_started':
+                    yield* runModel();
+                    continue;
+                case 'model_completed':
+                    if ((snapshot.currentTurn?.toolCalls.pending.length ?? 0) === 0) {
+                        yield* completeTurn();
+                    }
+                    else {
+                        yield* prepareToolCalls();
+                    }
+                    continue;
+                case 'tool_calls_started':
+                    yield* prepareEachToolCall();
+                    continue;
+                case 'tool_call_started':
+                    if ((snapshot.currentTurn?.toolCalls.pending.length ?? 0) > 0) {
+                        yield* executePreparedTools();
+                    }
+                    else {
+                        yield* completeToolCalls();
+                    }
+                    continue;
+                case 'tool_call_completed':
+                    if ((snapshot.currentTurn?.toolCalls.inFlight.length ?? 0) > 0) {
+                        throw new Error('Cannot safely resume while tool calls are in flight.');
+                    }
+                    yield* completeToolCalls();
+                    continue;
+                case 'tool_calls_completed':
+                    yield* completeTurn();
+                    continue;
+            }
+        }
+    }
+    catch (error) {
+        if (options.signal?.aborted) {
+            throw error;
+        }
+        yield* emitEvents(await failRun(error));
+        throw error;
+    }
+}