@k2b/nessi 0.10.0-rc.0

package/nessi.js

@@ -0,0 +1,1250 @@
+// ============================================================================
+// nessi - Core Loop
+// ============================================================================
+import { aggregateFromTurns, buildLoopTiming, cloneUsage } from "./aggregates.js";
+import { appendAssistantContentBlock, buildAssistantMessageFromContent } from "./ai/shared/messages.js";
+import { toolToSpec } from "./tools.js";
+import { createLoopId, projectHistoricalToolResults, toErrorMessage, truncateToolResults, zeroUsage, } from "./utils.js";
+class PullCancelledError extends Error {
+    constructor() {
+        super("channel pull cancelled");
+        this.name = "PullCancelledError";
+    }
+}
+class ToolExecutionFailure extends Error {
+    issue;
+    constructor(issue) {
+        super(issue.message);
+        this.name = "ToolExecutionFailure";
+        this.issue = issue;
+    }
+}
+const createChannel = () => {
+    const queue = [];
+    const waiters = [];
+    return {
+        push(value) {
+            const waiter = waiters.shift();
+            if (waiter) {
+                waiter.cleanup?.();
+                waiter.resolve(value);
+            }
+            else
+                queue.push(value);
+        },
+        pull(signal) {
+            const queued = queue.shift();
+            if (queued !== undefined)
+                return Promise.resolve(queued);
+            if (signal?.aborted)
+                return Promise.reject(new PullCancelledError());
+            return new Promise((resolve, reject) => {
+                const waiter = { resolve, reject };
+                const cancel = () => {
+                    const index = waiters.indexOf(waiter);
+                    if (index >= 0)
+                        waiters.splice(index, 1);
+                    waiter.cleanup?.();
+                    reject(new PullCancelledError());
+                };
+                if (signal) {
+                    waiter.cleanup = () => signal.removeEventListener("abort", cancel);
+                    signal.addEventListener("abort", cancel, { once: true });
+                }
+                waiters.push(waiter);
+            });
+        },
+        drain() {
+            return queue.splice(0, queue.length);
+        },
+    };
+};
+// ----------------------------------------------------------------------------
+// Input normalization
+// ----------------------------------------------------------------------------
+const normalizeInput = (input) => {
+    if (typeof input === "string")
+        return { role: "user", content: [{ type: "text", text: input }] };
+    return {
+        role: "user",
+        content: input.map((part) => (typeof part === "string" ? { type: "text", text: part } : part)),
+    };
+};
+// ----------------------------------------------------------------------------
+// Debug and issue helpers
+// ----------------------------------------------------------------------------
+const formatDebugJson = (value, maxLength = 2400) => {
+    try {
+        const text = JSON.stringify(value, null, 2) ?? String(value);
+        if (text.length <= maxLength)
+            return text;
+        return `${text.slice(0, maxLength)}\n... truncated`;
+    }
+    catch {
+        return String(value);
+    }
+};
+const formatToolValidationError = (tool, args, error) => {
+    const issues = error.issues.length > 0
+        ? error.issues
+            .map((rawIssue, index) => {
+            const issue = rawIssue;
+            const path = Array.isArray(issue.path) && issue.path.length > 0 ? issue.path.join(".") : "(root)";
+            const code = typeof issue.code === "string" ? issue.code : "unknown";
+            const message = typeof issue.message === "string" ? issue.message : "Validation failed";
+            const expected = typeof issue.expected === "string" ? `, expected ${issue.expected}` : "";
+            const received = Object.prototype.hasOwnProperty.call(issue, "input")
+                ? `, received ${formatDebugJson(issue.input, 200).replace(/\s+/g, " ")}`
+                : "";
+            return `${index + 1}. ${path}: ${message} [${code}${expected}${received}]`;
+        })
+            .join("\n")
+        : "No detailed issues reported.";
+    return [
+        `Validation error for tool "${tool.def.name}"`,
+        "",
+        "Issues:",
+        issues,
+        "",
+        "Received args:",
+        formatDebugJson(args),
+        "",
+        "Expected input schema:",
+        formatDebugJson(toolToSpec(tool).inputSchema),
+    ].join("\n");
+};
+const createTurnId = (loopId, turnIndex, suffix = "turn") => `${loopId}:${suffix}:${turnIndex}`;
+const isToolStreamIssue = (issue) => issue.kind === "malformed_tool_call" || issue.kind === "cancelled_tool_call";
+const toolExecutionIssue = (reason, message, call) => ({
+    kind: "tool_execution_error",
+    reason,
+    message,
+    retryable: false,
+    callId: call.id,
+    name: call.name,
+});
+const toolTimeoutIssue = (call, timeoutMs) => ({
+    kind: "timeout",
+    scope: "tool",
+    message: `Tool "${call.name}" timed out after ${timeoutMs}ms.`,
+    retryable: false,
+    callId: call.id,
+    name: call.name,
+});
+const runtimeIssue = (error) => ({
+    kind: "runtime_error",
+    message: toErrorMessage(error),
+    retryable: false,
+});
+const issueToToolResult = (issue) => issue.message;
+const timeoutMsFor = (tool) => {
+    const timeoutMs = tool.def.timeoutMs;
+    return typeof timeoutMs === "number" && timeoutMs > 0 ? timeoutMs : undefined;
+};
+const withTimeout = async (run, timeoutMs, onTimeout) => {
+    if (!timeoutMs)
+        return { ok: true, value: await run() };
+    const timeoutController = new AbortController();
+    let timeout;
+    let timedOut = false;
+    try {
+        timeout = setTimeout(() => {
+            timedOut = true;
+            onTimeout();
+            timeoutController.abort();
+        }, timeoutMs);
+        return { ok: true, value: await run(timeoutController.signal) };
+    }
+    catch (error) {
+        if (timedOut && error instanceof PullCancelledError)
+            return { ok: false };
+        throw error;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+        timeoutController.abort();
+    }
+};
+class LoopAbortedError extends Error {
+    constructor() {
+        super("nessi loop aborted");
+        this.name = "LoopAbortedError";
+    }
+}
+const linkedAbortSignal = (signals) => {
+    const activeSignals = signals.filter((signal) => Boolean(signal));
+    const controller = new AbortController();
+    const listeners = [];
+    for (const signal of activeSignals) {
+        const abort = () => controller.abort(signal.reason);
+        if (signal.aborted) {
+            abort();
+            continue;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+        listeners.push(() => signal.removeEventListener("abort", abort));
+    }
+    return {
+        signal: controller.signal,
+        cleanup() {
+            for (const remove of listeners)
+                remove();
+        },
+    };
+};
+// ----------------------------------------------------------------------------
+// Aggregate reconstruction
+// ----------------------------------------------------------------------------
+const aggregateTurnsFromEntries = (entries) => {
+    const messages = entries.filter((entry) => entry.kind === "message").map((entry) => entry.message);
+    const lastAssistantIdx = messages.findLastIndex((message) => message.role === "assistant");
+    if (lastAssistantIdx < 0)
+        return [];
+    let start = 0;
+    for (let i = lastAssistantIdx - 1; i >= 0; i--) {
+        if (messages[i]?.role === "user") {
+            start = i + 1;
+            break;
+        }
+    }
+    const turns = [];
+    for (let i = start; i < messages.length; i++) {
+        const message = messages[i];
+        if (message?.role !== "assistant")
+            continue;
+        const toolCalls = message.content
+            .filter((block) => block.type === "tool_call")
+            .map((block) => ({
+            callId: block.id,
+            name: block.name,
+            args: block.args,
+        }));
+        const byId = new Map(toolCalls.map((toolCall) => [toolCall.callId, toolCall]));
+        for (let j = i + 1; j < messages.length; j++) {
+            const next = messages[j];
+            if (!next || next.role === "assistant" || next.role === "user")
+                break;
+            const toolCall = byId.get(next.callId);
+            if (toolCall) {
+                toolCall.result = next.result;
+                toolCall.isError = next.isError;
+            }
+        }
+        turns.push({
+            message,
+            usage: cloneUsage(message.usage),
+            stopReason: message.stopReason,
+            toolCalls,
+        });
+    }
+    return turns;
+};
+const canMergeDelta = (left, right) => left.agentId === right.agentId
+    && left.loopId === right.loopId
+    && left.turnId === right.turnId
+    && left.blockId === right.blockId;
+const coalesceOutboundEvents = async function* (source, options) {
+    const maxChars = typeof options.maxChars === "number" && options.maxChars > 0 ? options.maxChars : undefined;
+    const ms = typeof options.ms === "number" && options.ms > 0 ? options.ms : undefined;
+    if (!maxChars && !ms) {
+        yield* source;
+        return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let next = iterator.next();
+    let buffer;
+    let timer;
+    let timerSeq = 0;
+    const clearTimer = () => {
+        timer = undefined;
+        timerSeq++;
+    };
+    const startTimer = () => {
+        if (!ms || timer)
+            return;
+        const seq = ++timerSeq;
+        timer = new Promise((resolve) => setTimeout(() => resolve({ type: "timer", seq }), ms));
+    };
+    const flush = function* () {
+        if (!buffer)
+            return;
+        const event = buffer;
+        buffer = undefined;
+        clearTimer();
+        yield event;
+    };
+    while (true) {
+        const raced = await (timer
+            ? Promise.race([
+                next.then((result) => ({ type: "event", result })),
+                timer,
+            ])
+            : next.then((result) => ({ type: "event", result })));
+        if (raced.type === "timer") {
+            if (raced.seq !== timerSeq)
+                continue;
+            yield* flush();
+            continue;
+        }
+        const { result } = raced;
+        if (result.done) {
+            yield* flush();
+            return;
+        }
+        next = iterator.next();
+        const event = result.value;
+        if (event.type !== "block_delta") {
+            yield* flush();
+            yield event;
+            continue;
+        }
+        if (!buffer) {
+            buffer = event;
+            startTimer();
+        }
+        else if (canMergeDelta(buffer, event)) {
+            buffer = { ...buffer, delta: buffer.delta + event.delta };
+        }
+        else {
+            yield* flush();
+            buffer = event;
+            startTimer();
+        }
+        if (maxChars && buffer.delta.length >= maxChars) {
+            yield* flush();
+        }
+    }
+};
+// ----------------------------------------------------------------------------
+// nessi()
+// ----------------------------------------------------------------------------
+export const nessi = (options) => {
+    const { agentId = "main", loopId: requestedLoopId, input, provider, systemPrompt, tools = [], store, creditStore, compact, steering, maxTurns = Infinity, temperature, maxOutputTokens, disableReasoning, coalesce, maxToolResultChars, signal: externalSignal, } = options;
+    const channel = createChannel();
+    const deferredInbound = [];
+    const steerQueue = [];
+    const subscribers = [];
+    const abortController = new AbortController();
+    let lastUsage = zeroUsage();
+    const loopTurns = [];
+    const loopIssues = [];
+    const loopId = requestedLoopId?.trim() ? requestedLoopId : createLoopId();
+    const timing = {
+        generationMs: 0,
+        toolExecutionMs: 0,
+        actionWaitMs: 0,
+    };
+    const measureGeneration = async (run) => {
+        const startedAt = nowMs();
+        try {
+            return await run();
+        }
+        finally {
+            timing.generationMs += elapsedSince(startedAt);
+        }
+    };
+    const waitForActionResponse = async (startedAt, run) => {
+        try {
+            return await run();
+        }
+        finally {
+            if (startedAt !== undefined)
+                timing.actionWaitMs += elapsedSince(startedAt);
+        }
+    };
+    const recordToolExecution = (startedAt, actionWaitMsAtStart) => {
+        const elapsedMs = elapsedSince(startedAt);
+        const nestedActionWaitMs = Math.max(0, timing.actionWaitMs - actionWaitMsAtStart);
+        timing.toolExecutionMs += Math.max(0, elapsedMs - nestedActionWaitMs);
+    };
+    const snapshotAggregate = () => {
+        const aggregate = aggregateFromTurns(loopTurns, loopIssues);
+        return { ...aggregate, timing: snapshotTiming(timing, aggregate.usage) };
+    };
+    const loopEndEvent = (reason) => ({
+        type: "loop_end",
+        agentId,
+        loopId,
+        reason,
+        aggregate: snapshotAggregate(),
+    });
+    const recordIssue = (issue, turn) => {
+        loopIssues.push({ ...issue });
+        if (turn) {
+            turn.issues.push({ ...issue });
+            if (isToolStreamIssue(issue))
+                turn.toolIssues.push({ ...issue });
+        }
+    };
+    const issueEvent = (issue, turn) => ({
+        type: "issue",
+        agentId,
+        loopId,
+        issue,
+        ...(turn ? { turnId: turn.turnId, turnIndex: turn.turnIndex } : {}),
+    });
+    const recordAssistantTurn = (message, usage, toolCalls, issues = [], toolIssues = []) => {
+        const turn = {
+            message,
+            usage: cloneUsage(usage),
+            stopReason: message.stopReason,
+            toolCalls,
+            ...(issues.length > 0 ? { issues: issues.map((issue) => ({ ...issue })) } : {}),
+            ...(toolIssues.length > 0 ? { toolIssues: toolIssues.map((issue) => ({ ...issue })) } : {}),
+        };
+        loopTurns.push(turn);
+    };
+    const hasBufferedInbound = (match) => {
+        deferredInbound.push(...channel.drain());
+        return deferredInbound.some(match);
+    };
+    const pullMatching = async (match, localSignal) => {
+        while (true) {
+            const bufferedIdx = deferredInbound.findIndex(match);
+            if (bufferedIdx >= 0)
+                return deferredInbound.splice(bufferedIdx, 1)[0];
+            if (abortController.signal.aborted)
+                throw new LoopAbortedError();
+            const linked = linkedAbortSignal([abortController.signal, localSignal]);
+            let inbound;
+            try {
+                inbound = await channel.pull(linked.signal);
+            }
+            catch (error) {
+                if (error instanceof PullCancelledError && abortController.signal.aborted) {
+                    throw new LoopAbortedError();
+                }
+                throw error;
+            }
+            finally {
+                linked.cleanup();
+            }
+            if (match(inbound))
+                return inbound;
+            deferredInbound.push(inbound);
+        }
+    };
+    if (externalSignal) {
+        if (externalSignal.aborted)
+            abortController.abort();
+        else
+            externalSignal.addEventListener("abort", () => abortController.abort(), { once: true });
+    }
+    const signal = abortController.signal;
+    async function* applyPendingSteering() {
+        const pending = steerQueue.splice(0);
+        const supplied = await steering?.({ agentId, loopId, signal });
+        if (typeof supplied === "string")
+            pending.push(supplied);
+        else if (supplied)
+            pending.push(...supplied);
+        pending.push(...steerQueue.splice(0));
+        let applied = false;
+        for (const text of pending) {
+            if (!text.trim())
+                continue;
+            const steerMessage = { role: "user", content: [{ type: "text", text }] };
+            await store.append(steerMessage);
+            applied = true;
+            yield { type: "steer_applied", agentId, loopId, message: text };
+        }
+        return applied;
+    }
+    const names = tools.map((tool) => tool.def.name);
+    if (new Set(names).size !== names.length) {
+        const dup = names.find((name, index) => names.indexOf(name) !== index);
+        throw new Error(`Duplicate tool name: ${dup}`);
+    }
+    const toolMap = new Map(tools.map((tool) => [tool.def.name, tool]));
+    const isTerminalTool = (name) => Boolean(toolMap.get(name)?.def?.terminal);
+    const appendToolResult = async (callId, name, result, isError = false) => {
+        const msg = { role: "tool_result", callId, name, result, isError };
+        await store.append(msg);
+        return msg;
+    };
+    const appendSuccessfulToolResult = async (tool, call, input, output) => {
+        let historicalResult;
+        try {
+            const value = await tool.def.toHistoricalResult?.({ input, output, callId: call.id });
+            if (value !== undefined)
+                historicalResult = { originLoopId: loopId, value };
+        }
+        catch (error) {
+            const issue = {
+                kind: "tool_historical_result_error",
+                message: `Historical result projection failed for tool "${call.name}": ${toErrorMessage(error)}`,
+                retryable: false,
+                callId: call.id,
+                name: call.name,
+            };
+            await store.append({ role: "tool_result", callId: call.id, name: call.name, result: output, isError: false });
+            return issue;
+        }
+        await store.append({
+            role: "tool_result",
+            callId: call.id,
+            name: call.name,
+            result: output,
+            ...(historicalResult ? { historicalResult } : {}),
+            isError: false,
+        });
+        return undefined;
+    };
+    async function* failToolCall(tc, turnCtx, updateAggregateToolCall, issue, turnIssues) {
+        const result = issueToToolResult(issue);
+        await appendToolResult(tc.id, tc.name, result, true);
+        updateAggregateToolCall(tc.id, { result, isError: true });
+        recordIssue(issue, turnIssues);
+        yield issueEvent(issue, turnCtx);
+        yield {
+            type: "tool_execution_end",
+            agentId,
+            loopId,
+            ...turnCtx,
+            callId: tc.id,
+            name: tc.name,
+            result,
+            isError: true,
+        };
+    }
+    const nowMs = () => Date.now();
+    const elapsedSince = (startedAt) => Math.max(0, nowMs() - startedAt);
+    const snapshotTiming = (timing, usage) => buildLoopTiming({
+        wallMs: timing.loopStartedAt === undefined ? 0 : elapsedSince(timing.loopStartedAt),
+        generationMs: timing.generationMs,
+        toolExecutionMs: timing.toolExecutionMs,
+        actionWaitMs: timing.actionWaitMs,
+    }, usage);
+    async function* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues) {
+        const eventFields = { agentId, loopId, ...turnCtx };
+        yield { type: "tool_execution_start", ...eventFields, callId: tc.id, name: tc.name, args: tc.args };
+        const tool = toolMap.get(tc.name);
+        if (!tool) {
+            yield* failToolCall(tc, turnCtx, updateAggregateToolCall, toolExecutionIssue("unknown_tool", `Unknown tool: ${tc.name}`, tc), turnIssues);
+            return;
+        }
+        const inputResult = tool.def.inputSchema.safeParse(tc.args);
+        if (!inputResult.success) {
+            yield* failToolCall(tc, turnCtx, updateAggregateToolCall, toolExecutionIssue("input_validation_failed", formatToolValidationError(tool, tc.args, inputResult.error), tc), turnIssues);
+            return;
+        }
+        const validatedInput = inputResult.data;
+        updateAggregateToolCall(tc.id, { args: validatedInput });
+        const timeoutMs = timeoutMsFor(tool);
+        const timeoutIssue = () => toolTimeoutIssue(tc, timeoutMs ?? 0);
+        if (tool.kind === "client") {
+            const matchesToolResult = (event) => event.type === "tool_result" && event.callId === tc.id;
+            let actionWaitStartedAt;
+            if (!hasBufferedInbound(matchesToolResult)) {
+                actionWaitStartedAt = nowMs();
+                yield {
+                    type: "tool_action_request",
+                    ...eventFields,
+                    kind: "client_tool",
+                    callId: tc.id,
+                    name: tc.name,
+                    args: validatedInput,
+                };
+            }
+            const pulled = await waitForActionResponse(actionWaitStartedAt, () => withTimeout((signal) => pullMatching(matchesToolResult, signal), timeoutMs, () => { }));
+            if (!pulled.ok) {
+                const issue = timeoutIssue();
+                const result = issueToToolResult(issue);
+                await appendToolResult(tc.id, tc.name, result, true);
+                updateAggregateToolCall(tc.id, { result, isError: true });
+                recordIssue(issue, turnIssues);
+                yield issueEvent(issue, turnCtx);
+                yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result, isError: true };
+                return;
+            }
+            const output = pulled.value.result;
+            if (tool.def.outputSchema) {
+                const outputResult = tool.def.outputSchema.safeParse(output);
+                if (!outputResult.success) {
+                    const issue = toolExecutionIssue("output_validation_failed", `Output validation error for tool "${tc.name}": ${outputResult.error.message}`, tc);
+                    const result = issueToToolResult(issue);
+                    await appendToolResult(tc.id, tc.name, result, true);
+                    updateAggregateToolCall(tc.id, { result, isError: true });
+                    recordIssue(issue, turnIssues);
+                    yield issueEvent(issue, turnCtx);
+                    yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result, isError: true };
+                    return;
+                }
+            }
+            const historicalIssue = await appendSuccessfulToolResult(tool, tc, validatedInput, output);
+            updateAggregateToolCall(tc.id, { result: output });
+            if (historicalIssue) {
+                recordIssue(historicalIssue, turnIssues);
+                yield issueEvent(historicalIssue, turnCtx);
+            }
+            yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result: output };
+            return;
+        }
+        if (tool.def.needsApproval) {
+            const matchesApproval = (event) => event.type === "approval_response" && event.callId === tc.id;
+            let actionWaitStartedAt;
+            if (!hasBufferedInbound(matchesApproval)) {
+                actionWaitStartedAt = nowMs();
+                yield {
+                    type: "tool_action_request",
+                    ...eventFields,
+                    kind: "approval",
+                    callId: tc.id,
+                    name: tc.name,
+                    args: validatedInput,
+                };
+            }
+            const pulled = await waitForActionResponse(actionWaitStartedAt, () => withTimeout((signal) => pullMatching(matchesApproval, signal), timeoutMs, () => { }));
+            if (!pulled.ok) {
+                const issue = timeoutIssue();
+                const result = issueToToolResult(issue);
+                await appendToolResult(tc.id, tc.name, result, true);
+                updateAggregateToolCall(tc.id, { result, isError: true });
+                recordIssue(issue, turnIssues);
+                yield issueEvent(issue, turnCtx);
+                yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result, isError: true };
+                return;
+            }
+            if (!pulled.value.approved) {
+                const issue = toolExecutionIssue("approval_denied", "User denied this action", tc);
+                const result = issueToToolResult(issue);
+                await appendToolResult(tc.id, tc.name, result, true);
+                updateAggregateToolCall(tc.id, { result, isError: true });
+                recordIssue(issue, turnIssues);
+                yield issueEvent(issue, turnCtx);
+                yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result, isError: true };
+                return;
+            }
+        }
+        const toolAbort = new AbortController();
+        const abortTool = () => toolAbort.abort();
+        if (signal.aborted)
+            abortTool();
+        else
+            signal.addEventListener("abort", abortTool, { once: true });
+        let timeoutHandle;
+        const toolStartedAt = nowMs();
+        const actionWaitMsAtToolStart = timing.actionWaitMs;
+        let toolExecutionRecorded = false;
+        const finishToolExecution = () => {
+            if (toolExecutionRecorded)
+                return;
+            toolExecutionRecorded = true;
+            recordToolExecution(toolStartedAt, actionWaitMsAtToolStart);
+        };
+        try {
+            const approvalQueue = [];
+            const clientToolQueue = [];
+            let queueNotify = null;
+            let approvalCounter = 0;
+            let clientToolCounter = 0;
+            const ctx = {
+                signal: toolAbort.signal,
+                requestApproval(message) {
+                    return new Promise((resolve) => {
+                        const id = `${tc.id}-approval-${approvalCounter++}`;
+                        approvalQueue.push({ id, message, resolve });
+                        queueNotify?.();
+                    });
+                },
+                requestClientTool(name, args) {
+                    return new Promise((resolve, reject) => {
+                        const id = `${tc.id}-client-${clientToolCounter++}`;
+                        clientToolQueue.push({
+                            id,
+                            name,
+                            args,
+                            resolve: resolve,
+                            reject,
+                        });
+                        queueNotify?.();
+                    });
+                },
+            };
+            const resultPromise = tool.execute(validatedInput, ctx);
+            let timeout;
+            if (timeoutMs) {
+                timeout = new Promise((resolve) => {
+                    timeoutHandle = setTimeout(() => {
+                        toolAbort.abort();
+                        resolve({ kind: "timeout" });
+                    }, timeoutMs);
+                });
+            }
+            let result;
+            let done = false;
+            while (!done) {
+                const waitForQueue = new Promise((resolve) => {
+                    if (approvalQueue.length > 0 || clientToolQueue.length > 0)
+                        resolve({ kind: "queue" });
+                    else
+                        queueNotify = () => resolve({ kind: "queue" });
+                });
+                const settled = await Promise.race([
+                    resultPromise.then((value) => ({ kind: "done", result: value })),
+                    waitForQueue,
+                    ...(timeout ? [timeout] : []),
+                ]);
+                if (settled.kind === "timeout") {
+                    const issue = timeoutIssue();
+                    const timeoutResult = issueToToolResult(issue);
+                    await appendToolResult(tc.id, tc.name, timeoutResult, true);
+                    updateAggregateToolCall(tc.id, { result: timeoutResult, isError: true });
+                    recordIssue(issue, turnIssues);
+                    yield issueEvent(issue, turnCtx);
+                    finishToolExecution();
+                    yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result: timeoutResult, isError: true };
+                    return;
+                }
+                if (settled.kind === "done") {
+                    result = settled.result;
+                    done = true;
+                    continue;
+                }
+                while (approvalQueue.length > 0) {
+                    const req = approvalQueue.shift();
+                    const matchesCustomApproval = (event) => event.type === "approval_response" && event.callId === req.id;
+                    let actionWaitStartedAt;
+                    if (!hasBufferedInbound(matchesCustomApproval)) {
+                        actionWaitStartedAt = nowMs();
+                        yield {
+                            type: "tool_action_request",
+                            ...eventFields,
+                            kind: "custom_approval",
+                            callId: req.id,
+                            name: tc.name,
+                            args: validatedInput,
+                            message: req.message,
+                        };
+                    }
+                    const response = await waitForActionResponse(actionWaitStartedAt, () => withTimeout((signal) => pullMatching(matchesCustomApproval, signal), timeoutMs, () => toolAbort.abort()));
+                    if (!response.ok) {
+                        const issue = timeoutIssue();
+                        const timeoutResult = issueToToolResult(issue);
+                        await appendToolResult(tc.id, tc.name, timeoutResult, true);
+                        updateAggregateToolCall(tc.id, { result: timeoutResult, isError: true });
+                        recordIssue(issue, turnIssues);
+                        yield issueEvent(issue, turnCtx);
+                        finishToolExecution();
+                        yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result: timeoutResult, isError: true };
+                        return;
+                    }
+                    req.resolve(response.value.approved);
+                }
+                while (clientToolQueue.length > 0) {
+                    const req = clientToolQueue.shift();
+                    const bridgeTool = toolMap.get(req.name);
+                    let requestArgs = req.args;
+                    if (bridgeTool) {
+                        if (bridgeTool.kind !== "client") {
+                            req.reject(new ToolExecutionFailure(toolExecutionIssue("unknown_tool", `Client tool "${req.name}" is not registered as a client tool.`, { id: req.id, name: req.name })));
+                            continue;
+                        }
+                        const inputResult = bridgeTool.def.inputSchema.safeParse(req.args);
+                        if (!inputResult.success) {
+                            req.reject(new ToolExecutionFailure(toolExecutionIssue("input_validation_failed", formatToolValidationError(bridgeTool, req.args, inputResult.error), { id: req.id, name: req.name })));
+                            continue;
+                        }
+                        requestArgs = inputResult.data;
+                    }
+                    const matchesClientResult = (event) => event.type === "tool_result" && event.callId === req.id;
+                    let actionWaitStartedAt;
+                    if (!hasBufferedInbound(matchesClientResult)) {
+                        actionWaitStartedAt = nowMs();
+                        yield {
+                            type: "tool_action_request",
+                            ...eventFields,
+                            kind: "client_tool",
+                            callId: req.id,
+                            name: req.name,
+                            args: requestArgs,
+                        };
+                    }
+                    const response = await waitForActionResponse(actionWaitStartedAt, () => withTimeout((signal) => pullMatching(matchesClientResult, signal), timeoutMs, () => toolAbort.abort()));
+                    if (!response.ok) {
+                        const issue = timeoutIssue();
+                        const timeoutResult = issueToToolResult(issue);
+                        await appendToolResult(tc.id, tc.name, timeoutResult, true);
+                        updateAggregateToolCall(tc.id, { result: timeoutResult, isError: true });
+                        recordIssue(issue, turnIssues);
+                        yield issueEvent(issue, turnCtx);
+                        finishToolExecution();
+                        yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result: timeoutResult, isError: true };
+                        return;
+                    }
+                    let output = response.value.result;
+                    if (bridgeTool?.kind === "client" && bridgeTool.def.outputSchema) {
+                        const outputResult = bridgeTool.def.outputSchema.safeParse(output);
+                        if (!outputResult.success) {
+                            req.reject(new ToolExecutionFailure(toolExecutionIssue("output_validation_failed", `Output validation error for client tool "${req.name}": ${outputResult.error.message}`, { id: req.id, name: req.name })));
+                            continue;
+                        }
+                        output = outputResult.data;
+                    }
+                    req.resolve(output);
+                }
+                queueNotify = null;
+            }
+            if (tool.def.outputSchema) {
+                const outputResult = tool.def.outputSchema.safeParse(result);
+                if (!outputResult.success) {
+                    const issue = toolExecutionIssue("output_validation_failed", `Output validation error for tool "${tc.name}": ${outputResult.error.message}`, tc);
+                    const output = issueToToolResult(issue);
+                    await appendToolResult(tc.id, tc.name, output, true);
+                    updateAggregateToolCall(tc.id, { result: output, isError: true });
+                    recordIssue(issue, turnIssues);
+                    yield issueEvent(issue, turnCtx);
+                    finishToolExecution();
+                    yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result: output, isError: true };
+                    return;
+                }
+            }
+            const historicalIssue = await appendSuccessfulToolResult(tool, tc, validatedInput, result);
+            updateAggregateToolCall(tc.id, { result });
+            if (historicalIssue) {
+                recordIssue(historicalIssue, turnIssues);
+                yield issueEvent(historicalIssue, turnCtx);
+            }
+            finishToolExecution();
+            yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result };
+        }
+        catch (error) {
+            if (error instanceof LoopAbortedError || signal.aborted)
+                throw error;
+            const issue = error instanceof ToolExecutionFailure
+                ? error.issue
+                : toolExecutionIssue("execution_failed", toErrorMessage(error), tc);
+            const result = issueToToolResult(issue);
+            await appendToolResult(tc.id, tc.name, result, true);
+            updateAggregateToolCall(tc.id, { result, isError: true });
+            recordIssue(issue, turnIssues);
+            yield issueEvent(issue, turnCtx);
+            finishToolExecution();
+            yield { type: "tool_execution_end", ...eventFields, callId: tc.id, name: tc.name, result, isError: true };
+        }
+        finally {
+            finishToolExecution();
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            signal.removeEventListener("abort", abortTool);
+        }
+    }
+    const noopAggregateUpdate = () => { };
+    async function* runCompaction(operation) {
+        yield { type: "compaction_start", agentId, loopId };
+        try {
+            await operation;
+        }
+        finally {
+            yield { type: "compaction_end", agentId, loopId };
+        }
+    }
+    async function* resumePendingToolCalls(turnCtx) {
+        const entries = await store.load();
+        const seeded = aggregateTurnsFromEntries(entries);
+        loopTurns.splice(0, loopTurns.length, ...seeded);
+        let lastAssistantIdx = -1;
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const role = entries[i].message.role;
+            if (role === "user")
+                return;
+            if (role === "assistant") {
+                lastAssistantIdx = i;
+                break;
+            }
+        }
+        if (lastAssistantIdx < 0)
+            return;
+        const entry = entries[lastAssistantIdx];
+        if (entry.kind === "summary")
+            return;
+        const assistantMessage = entry.message;
+        const toolCallBlocks = assistantMessage.content.filter((block) => block.type === "tool_call");
+        if (toolCallBlocks.length === 0)
+            return;
+        const resolvedCallIds = new Set();
+        for (let i = lastAssistantIdx + 1; i < entries.length; i++) {
+            const message = entries[i].message;
+            if (message.role === "tool_result")
+                resolvedCallIds.add(message.callId);
+        }
+        const pending = toolCallBlocks.filter((block) => !resolvedCallIds.has(block.id));
+        if (pending.length === 0)
+            return;
+        const aggregateTurn = loopTurns.findLast((turn) => turn.message === assistantMessage);
+        const aggregateToolCallMap = new Map((aggregateTurn?.toolCalls ?? []).map((toolCall) => [toolCall.callId, toolCall]));
+        const updateAggregateToolCall = aggregateTurn
+            ? (callId, patch) => {
+                const aggregateToolCall = aggregateToolCallMap.get(callId);
+                if (aggregateToolCall)
+                    Object.assign(aggregateToolCall, patch);
+            }
+            : noopAggregateUpdate;
+        const turnIssues = { issues: [], toolIssues: [] };
+        yield { type: "turn_start", agentId, loopId, ...turnCtx, resumed: true };
+        for (const tc of pending) {
+            if (signal.aborted)
+                return;
+            yield* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues);
+        }
+        if (aggregateTurn && turnIssues.issues.length > 0) {
+            aggregateTurn.issues = [...(aggregateTurn.issues ?? []), ...turnIssues.issues.map((issue) => ({ ...issue }))];
+            aggregateTurn.toolIssues = [
+                ...(aggregateTurn.toolIssues ?? []),
+                ...turnIssues.toolIssues.map((issue) => ({ ...issue })),
+            ];
+        }
+        yield { type: "turn_end", agentId, loopId, ...turnCtx, message: assistantMessage };
+    }
+    async function* run() {
+        let providerTurn = 0;
+        let eventTurnIndex = 0;
+        let compactionRetried = false;
+        const providerTools = tools.map(toolToSpec);
+        const prepareProviderMessages = (sourceEntries) => {
+            const rawMessages = sourceEntries.map((entry) => entry.message);
+            const projectedMessages = projectHistoricalToolResults(rawMessages, loopId);
+            return typeof maxToolResultChars === "number"
+                ? truncateToolResults(projectedMessages, maxToolResultChars)
+                : projectedMessages;
+        };
+        timing.loopStartedAt = nowMs();
+        yield { type: "loop_start", agentId, loopId };
+        try {
+            if (input !== undefined) {
+                await store.append(normalizeInput(input));
+            }
+            else {
+                const resumeCtx = { turnId: createTurnId(loopId, eventTurnIndex, "resume"), turnIndex: eventTurnIndex };
+                let emittedResumeTurn = false;
+                for await (const event of resumePendingToolCalls(resumeCtx)) {
+                    emittedResumeTurn = true;
+                    yield event;
+                }
+                if (emittedResumeTurn)
+                    eventTurnIndex++;
+                if (signal.aborted) {
+                    yield loopEndEvent("aborted");
+                    return;
+                }
+            }
+            while (true) {
+                if (signal.aborted) {
+                    yield loopEndEvent("aborted");
+                    return;
+                }
+                if (creditStore) {
+                    const remaining = await creditStore.remaining();
+                    if (remaining <= 0) {
+                        yield loopEndEvent("no_credits");
+                        return;
+                    }
+                }
+                const steeringApplied = yield* applyPendingSteering();
+                if (steeringApplied) {
+                    providerTurn = 0;
+                    compactionRetried = false;
+                }
+                if (providerTurn >= maxTurns) {
+                    yield loopEndEvent("max_turns");
+                    return;
+                }
+                let entries = await store.load();
+                let messages = prepareProviderMessages(entries);
+                const contextWindow = provider.contextWindow;
+                const computeFillRatio = (providerMessages) => {
+                    if (typeof contextWindow !== "number" || contextWindow <= 0)
+                        return undefined;
+                    const estimatedTokens = Math.ceil(JSON.stringify({ systemPrompt, messages: providerMessages, tools: providerTools }).length / 4);
+                    const tokens = lastUsage.input > 0 ? Math.max(lastUsage.input, estimatedTokens) : estimatedTokens;
+                    return tokens / contextWindow;
+                };
+                if (compact && !compactionRetried) {
+                    const fillRatio = computeFillRatio(messages);
+                    const shouldForce = typeof fillRatio === "number" && fillRatio >= 0.85;
+                    const compaction = compact({
+                        entries,
+                        store,
+                        provider,
+                        usage: lastUsage,
+                        force: shouldForce,
+                        fillRatio,
+                    });
+                    if (compaction) {
+                        yield* runCompaction(compaction);
+                        entries = await store.load();
+                        messages = prepareProviderMessages(entries);
+                    }
+                }
+                const turnCtx = { turnId: createTurnId(loopId, eventTurnIndex), turnIndex: eventTurnIndex };
+                eventTurnIndex++;
+                yield { type: "turn_start", agentId, loopId, ...turnCtx };
+                let turnUsage = zeroUsage();
+                let turnUsageReported = false;
+                let stopReason = "stop";
+                const assistantBlocks = [];
+                const openBlocks = new Map();
+                const toolCalls = [];
+                const turnIssues = { issues: [], toolIssues: [] };
+                let hadContextOverflow = false;
+                let overflowRatio;
+                let providerFailure;
+                const eventFields = { agentId, loopId, ...turnCtx };
+                const makePartialMessage = (reason) => {
+                    const content = [...assistantBlocks];
+                    const pendingBlocks = [...openBlocks.entries()]
+                        .sort((left, right) => left[1].index - right[1].index)
+                        .map(([, block]) => block.kind === "thinking"
+                        ? { type: "thinking", thinking: block.text }
+                        : { type: "text", text: block.text });
+                    for (const block of pendingBlocks)
+                        appendAssistantContentBlock(content, block);
+                    return buildAssistantMessageFromContent(provider.model, content, turnUsage, reason);
+                };
+                try {
+                    const providerIterator = provider.stream({
+                        systemPrompt,
+                        messages,
+                        tools: providerTools,
+                        temperature,
+                        maxOutputTokens,
+                        disableReasoning,
+                        signal,
+                    })[Symbol.asyncIterator]();
+                    try {
+                        streamLoop: while (true) {
+                            const next = await measureGeneration(() => providerIterator.next());
+                            if (next.done)
+                                break;
+                            const event = next.value;
+                            if (signal.aborted)
+                                break;
+                            switch (event.type) {
+                                case "block_start":
+                                    if (event.kind === "text" || event.kind === "thinking") {
+                                        openBlocks.set(event.blockId, { index: event.index, kind: event.kind, text: "" });
+                                    }
+                                    yield { ...event, ...eventFields };
+                                    break;
+                                case "block_delta": {
+                                    const open = openBlocks.get(event.blockId);
+                                    if (open)
+                                        open.text += event.delta;
+                                    yield { ...event, ...eventFields };
+                                    break;
+                                }
+                                case "block_end":
+                                    openBlocks.delete(event.blockId);
+                                    appendAssistantContentBlock(assistantBlocks, event.block);
+                                    if (event.block.type === "tool_call") {
+                                        toolCalls.push(event.block);
+                                        stopReason = "tool_use";
+                                    }
+                                    yield { ...event, ...eventFields };
+                                    break;
+                                case "usage":
+                                    turnUsage = event.usage;
+                                    turnUsageReported = true;
+                                    stopReason = event.finishReason ?? stopReason;
+                                    yield { ...event, ...eventFields };
+                                    break;
+                                case "issue":
+                                    recordIssue(event.issue, turnIssues);
+                                    yield issueEvent(event.issue, turnCtx);
+                                    if (event.issue.kind === "provider_error" && event.issue.contextOverflow) {
+                                        hadContextOverflow = true;
+                                        overflowRatio = event.issue.overflowRatio;
+                                        break;
+                                    }
+                                    if (event.issue.kind === "provider_error"
+                                        || (event.issue.kind === "timeout" && event.issue.scope !== "tool")
+                                        || event.issue.kind === "runtime_error") {
+                                        providerFailure = event.issue;
+                                        break streamLoop;
+                                    }
+                                    break;
+                                default: {
+                                    const unsupported = event;
+                                    const issue = {
+                                        kind: "runtime_error",
+                                        message: `Unsupported provider event type: ${String(unsupported.type)}`,
+                                        retryable: false,
+                                    };
+                                    recordIssue(issue, turnIssues);
+                                    yield issueEvent(issue, turnCtx);
+                                    providerFailure = issue;
+                                    break streamLoop;
+                                }
+                            }
+                        }
+                    }
+                    finally {
+                        await providerIterator.return?.();
+                    }
+                }
+                catch (error) {
+                    if (signal.aborted) {
+                        const msg = makePartialMessage("interrupted");
+                        if (msg.content.length > 0) {
+                            await store.append(msg);
+                            recordAssistantTurn(msg, turnUsageReported ? turnUsage : undefined, toolCalls.map((toolCall) => ({ callId: toolCall.id, name: toolCall.name, args: toolCall.args })), turnIssues.issues, turnIssues.toolIssues);
+                            yield { type: "turn_end", agentId, loopId, ...turnCtx, message: msg };
+                        }
+                        yield loopEndEvent("aborted");
+                        return;
+                    }
+                    const issue = runtimeIssue(error);
+                    recordIssue(issue, turnIssues);
+                    yield issueEvent(issue, turnCtx);
+                    yield loopEndEvent("error");
+                    return;
+                }
+                if (hadContextOverflow) {
+                    if (compact && !compactionRetried) {
+                        const estimatedFillRatio = computeFillRatio(messages);
+                        const fillRatio = typeof overflowRatio === "number"
+                            ? Math.max(estimatedFillRatio ?? 0, overflowRatio)
+                            : estimatedFillRatio;
+                        const compaction = compact({
+                            entries,
+                            store,
+                            provider,
+                            usage: lastUsage,
+                            force: true,
+                            fillRatio,
+                        });
+                        if (compaction) {
+                            yield* runCompaction(compaction);
+                            compactionRetried = true;
+                            continue;
+                        }
+                    }
+                    yield loopEndEvent("context_overflow");
+                    return;
+                }
+                if (providerFailure) {
+                    yield loopEndEvent("error");
+                    return;
+                }
+                if (signal.aborted) {
+                    const msg = makePartialMessage("interrupted");
+                    if (msg.content.length > 0) {
+                        await store.append(msg);
+                        recordAssistantTurn(msg, turnUsageReported ? turnUsage : undefined, toolCalls.map((toolCall) => ({ callId: toolCall.id, name: toolCall.name, args: toolCall.args })), turnIssues.issues, turnIssues.toolIssues);
+                        yield { type: "turn_end", agentId, loopId, ...turnCtx, message: msg };
+                    }
+                    yield loopEndEvent("aborted");
+                    return;
+                }
+                const assistantMessage = buildAssistantMessageFromContent(provider.model, assistantBlocks, turnUsage, stopReason);
+                await store.append(assistantMessage);
+                lastUsage = turnUsage;
+                const aggregateToolCalls = toolCalls.map((toolCall) => ({
+                    callId: toolCall.id,
+                    name: toolCall.name,
+                    args: toolCall.args,
+                }));
+                recordAssistantTurn(assistantMessage, turnUsageReported ? turnUsage : undefined, aggregateToolCalls, turnIssues.issues, turnIssues.toolIssues);
+                if (creditStore && turnUsage.creditsUsed && turnUsage.creditsUsed > 0) {
+                    await creditStore.deduct(turnUsage.creditsUsed);
+                }
+                if (toolCalls.length === 0) {
+                    yield { type: "turn_end", agentId, loopId, ...turnCtx, message: assistantMessage };
+                    const lateSteeringApplied = yield* applyPendingSteering();
+                    if (lateSteeringApplied) {
+                        providerTurn = 0;
+                        compactionRetried = false;
+                        continue;
+                    }
+                    yield loopEndEvent("stop");
+                    return;
+                }
+                const aggregateToolCallMap = new Map(aggregateToolCalls.map((toolCall) => [toolCall.callId, toolCall]));
+                const updateAggregateToolCall = (callId, patch) => {
+                    const aggregateToolCall = aggregateToolCallMap.get(callId);
+                    if (aggregateToolCall)
+                        Object.assign(aggregateToolCall, patch);
+                };
+                let terminalToolCompleted = false;
+                for (const tc of toolCalls) {
+                    yield* executeToolCall(tc, turnCtx, updateAggregateToolCall, turnIssues);
+                    const aggregateToolCall = aggregateToolCallMap.get(tc.id);
+                    if (isTerminalTool(tc.name) && aggregateToolCall && !aggregateToolCall.isError) {
+                        terminalToolCompleted = true;
+                        break;
+                    }
+                }
+                const recordedTurn = loopTurns[loopTurns.length - 1];
+                if (recordedTurn?.message === assistantMessage) {
+                    recordedTurn.issues = turnIssues.issues.map((issue) => ({ ...issue }));
+                    recordedTurn.toolIssues = turnIssues.toolIssues.map((issue) => ({ ...issue }));
+                }
+                yield { type: "turn_end", agentId, loopId, ...turnCtx, message: assistantMessage };
+                if (terminalToolCompleted) {
+                    const lateSteeringApplied = yield* applyPendingSteering();
+                    if (lateSteeringApplied) {
+                        providerTurn = 0;
+                        compactionRetried = false;
+                        continue;
+                    }
+                    yield loopEndEvent("stop");
+                    return;
+                }
+                providerTurn++;
+                compactionRetried = false;
+            }
+        }
+        catch (error) {
+            if (signal.aborted) {
+                yield loopEndEvent("aborted");
+                return;
+            }
+            const issue = runtimeIssue(error);
+            recordIssue(issue);
+            yield issueEvent(issue);
+            yield loopEndEvent("error");
+        }
+    }
+    const eventSource = coalesce ? coalesceOutboundEvents(run(), coalesce) : run();
+    const generator = eventSource[Symbol.asyncIterator]();
+    const loop = {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    const result = await generator.next();
+                    if (!result.done && result.value) {
+                        for (const listener of subscribers)
+                            listener(result.value);
+                    }
+                    return result;
+                },
+                async return(value) {
+                    return generator.return(value);
+                },
+                async throw(error) {
+                    return generator.throw(error);
+                },
+            };
+        },
+        subscribe(listener) {
+            subscribers.push(listener);
+            return () => {
+                const idx = subscribers.indexOf(listener);
+                if (idx >= 0)
+                    subscribers.splice(idx, 1);
+            };
+        },
+        push(event) {
+            channel.push(event);
+        },
+        steer(message) {
+            if (message.trim())
+                steerQueue.push(message);
+        },
+        abort() {
+            abortController.abort();
+        },
+    };
+    return loop;
+};