@slopus/happy-agent-base 0.0.0 → 0.0.1

package/dist/AgentBase.js

@@ -0,0 +1,909 @@
+import { areProviderModelsCompatible } from "@slopus/happy-providers";
+import { Value } from "@sinclair/typebox/value";
+import { asyncLock, withLifetime } from "@steve.kite/stdlib";
+import { withAgentBaseContext } from "./AgentBaseContext.js";
+import { AgentProviders } from "./AgentProviders.js";
+/** Race winner when an abort interrupts a wait on the stream or a running tool. */
+const ABORTED = Symbol("aborted");
+/**
+ * A single agent session over one provider. Messages arrive through two FIFO queues: steering
+ * messages inject as soon as the current assistant response and its tool batch finish, while
+ * sent messages wait until the agent would otherwise stop — no tool calls or steering remain.
+ * Each queue drains per its configured mode, and the conversation is durable through
+ * append-only persistence loaded on the first inference attempt.
+ */
+export class AgentBase {
+    id;
+    /**
+     * The agent's own copy of the initial state, mutable directly; every inference reads the
+     * current values.
+     */
+    state;
+    #baseCtx;
+    #ctx;
+    #providers;
+    #providerId;
+    #persistence;
+    #model;
+    #effort;
+    #serviceTier;
+    #hooks;
+    /**
+     * Serializes every persistence operation together with its in-memory effect, so storage
+     * order always matches history order and a load never overlaps an append.
+     */
+    #persistenceLock = asyncLock({ reentry: "block" });
+    #steeringMode;
+    #sendMode;
+    #session;
+    #messages = [];
+    #steering = [];
+    #sends = [];
+    #pendingTools = [];
+    #pendingSequence = 0;
+    #loaded;
+    #recoveryChecked = false;
+    #compaction;
+    #abortController;
+    #turnRequested = false;
+    #runPromise;
+    #closed = false;
+    constructor(ctx, options) {
+        this.id = options.id;
+        this.#baseCtx = ctx;
+        this.#providers = options.providers;
+        this.#providerId = options.provider;
+        this.#persistence = options.persistence;
+        this.#hooks = options.hooks ?? {};
+        this.state = {
+            instructions: options.initialState?.instructions ?? "",
+            tools: [...(options.initialState?.tools ?? [])],
+        };
+        this.#model = options.model;
+        this.#effort = options.effort;
+        this.#serviceTier = options.serviceTier;
+        // Everything the agent does — hooks and tool executions included — runs on a context
+        // carrying its provider and the currently effective model, effort, and service tier.
+        this.#ctx = this.#deriveCtx();
+        this.#steeringMode = options.steeringMode ?? "one-at-a-time";
+        this.#sendMode = options.sendMode ?? "one-at-a-time";
+    }
+    #deriveCtx() {
+        return withAgentBaseContext(this.#baseCtx, {
+            provider: this.#providerId,
+            model: this.#model,
+            effort: this.#effort,
+            serviceTier: this.#serviceTier,
+        });
+    }
+    /**
+     * Queue a user message that injects as soon as the current assistant response and its tool
+     * batch finish; steering always takes precedence over sent messages. The returned promise
+     * resolves once the durable write lands; it waits neither for the history load nor for the
+     * turn, and a failed write keeps the message out of the conversation entirely.
+     */
+    async steer(ctx, message, options) {
+        await this.#enqueue(ctx, "steering.", this.#steering, message, options ?? {});
+    }
+    /**
+     * Queue a user message that waits until the agent would otherwise stop — no tool calls or
+     * steering remain — before injecting. The returned promise resolves once the durable write
+     * lands; it waits neither for the history load nor for the turn, and a failed write keeps
+     * the message out of the conversation entirely.
+     */
+    async send(ctx, message, options) {
+        await this.#enqueue(ctx, "send.", this.#sends, message, options ?? {});
+    }
+    async #enqueue(ctx, prefix, queue, message, options) {
+        if (this.#closed)
+            throw new Error("The agent has been closed.");
+        await this.#persistenceLock.runInLock(ctx, async (lockCtx) => {
+            const key = this.#queueKey(prefix);
+            await this.#persistence.writeValue(lockCtx, key, { message, options });
+            queue.push({ key, message, options });
+            this.#turnRequested = true;
+            this.#startRun();
+        });
+    }
+    /**
+     * Start the loop without a new message: load the durable state and, if a turn was cut off —
+     * queued messages, a dispatched tool batch without results, or an unanswered user or tool
+     * message — continue it to completion. On an idle history this loads and does nothing more.
+     */
+    start() {
+        if (this.#closed)
+            throw new Error("The agent has been closed.");
+        this.#startRun();
+    }
+    async waitForIdle() {
+        while (this.#runPromise !== undefined) {
+            await this.#runPromise;
+        }
+    }
+    /**
+     * Compact the conversation. The compaction waits for the active turn to end — or runs right
+     * away when idle — and replaces the compacted history with the provider's replacement
+     * context while keeping every message that joined the history after the snapshot. Calls made
+     * while a compaction is pending or running await that same compaction; the shared promise
+     * resolves when it completes and rejects when the provider reports failure.
+     */
+    async compact(ctx) {
+        if (this.#closed)
+            throw new Error("The agent has been closed.");
+        return this.#ensureCompaction();
+    }
+    #ensureCompaction() {
+        if (this.#compaction === undefined) {
+            let resolve;
+            let reject;
+            const promise = new Promise((res, rej) => {
+                resolve = res;
+                reject = rej;
+            });
+            this.#compaction = { promise, resolve, reject };
+            this.#turnRequested = true;
+            this.#startRun();
+        }
+        return this.#compaction.promise;
+    }
+    /**
+     * The system prompt for the next request: the hook's answer when one is provided, the
+     * mutable state otherwise. A throwing hook falls back to the state; it never fails the run.
+     */
+    #instructions() {
+        try {
+            return this.#hooks.instructions?.(this.#ctx) ?? this.state.instructions;
+        }
+        catch {
+            return this.state.instructions;
+        }
+    }
+    /**
+     * The tools for the next request or execution: the hook's answer when one is provided, the
+     * mutable state otherwise. A throwing hook falls back to the state; it never fails the run.
+     */
+    #tools() {
+        try {
+            return this.#hooks.tools?.(this.#ctx) ?? this.state.tools;
+        }
+        catch {
+            return this.state.tools;
+        }
+    }
+    /**
+     * Cancel the active turn: stop consuming the inference stream, settle still-running tool
+     * calls as aborted error results, and drop the queued turn request. Blocks that already
+     * finished stay in the history; an unfinished block is dropped. Messages still waiting in
+     * the steering and send queues stay durable and join the next requested turn. Resolves
+     * once the loop has stopped; a no-op when the agent is idle.
+     */
+    async abort() {
+        const run = this.#runPromise;
+        if (run === undefined)
+            return;
+        this.#turnRequested = false;
+        this.#abortController?.abort();
+        await run;
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        await this.#runPromise;
+        await this.#session?.destroy();
+        this.#session = undefined;
+    }
+    #startRun() {
+        if (this.#runPromise !== undefined)
+            return;
+        this.#runPromise = this.#runLoop().finally(() => {
+            this.#runPromise = undefined;
+        });
+    }
+    async #runLoop() {
+        // The outer loop reopens when an `afterAgentLoop` action requests more work, so the
+        // loop hooks always bracket a settled-to-settled span.
+        do {
+            this.#invokeHook(this.#hooks.beforeAgentLoop);
+            do {
+                this.#turnRequested = false;
+                this.#invokeHook(this.#hooks.beforeTurn);
+                await this.#runInference();
+                await this.#applyActions(this.#hooks.afterTurn);
+            } while (this.#turnRequested && !this.#closed);
+            await this.#applyActions(this.#hooks.afterAgentLoop);
+        } while (this.#turnRequested && !this.#closed);
+    }
+    #invokeHook(hook) {
+        try {
+            hook?.(this.#ctx);
+        }
+        catch {
+            // Hooks observe the run; they never fail it.
+        }
+    }
+    /**
+     * Ask a lifecycle hook what to do next and carry its actions out: queue steering or sent
+     * messages through the ordinary durable path, or trigger a compaction. Every returned
+     * action is applied before the loop continues, so they all take effect at the same point.
+     * Neither a throwing hook nor a failing action ever fails the run.
+     */
+    async #applyActions(hook) {
+        if (hook === undefined)
+            return;
+        let actions;
+        try {
+            actions = hook(this.#ctx);
+        }
+        catch {
+            return;
+        }
+        for (const action of actions ?? []) {
+            try {
+                if (action.type === "compact") {
+                    this.#ensureCompaction().catch(() => undefined);
+                    continue;
+                }
+                const queue = action.type === "steer" ? this.#steering : this.#sends;
+                const prefix = action.type === "steer" ? "steering." : "send.";
+                await this.#enqueue(this.#ctx, prefix, queue, action.message, {});
+            }
+            catch {
+                // A hook-driven action must not fail the run.
+            }
+        }
+    }
+    async #runInference() {
+        // One abort scope per pass; a single shared promise keeps races from piling up
+        // listeners on the signal.
+        const abort = new AbortController();
+        this.#abortController = abort;
+        const abortPromise = new Promise((resolve) => {
+            abort.signal.addEventListener("abort", () => resolve(ABORTED), { once: true });
+        });
+        try {
+            // A failed load is not sticky: the cache resets so the next turn retries it.
+            this.#loaded ??= this.#loadHistory().catch((error) => {
+                this.#loaded = undefined;
+                throw error;
+            });
+            await this.#loaded;
+            // Resume a tool batch that was dispatched but cut off before its results landed, so
+            // the interrupted results reach the main store before any queued message.
+            const resumed = this.#pendingTools;
+            this.#pendingTools = [];
+            if (resumed.length > 0) {
+                await this.#runToolBatch(resumed, true, abort.signal, abortPromise);
+            }
+            // A response is owed without any injection when tool results from a resumed batch
+            // end the context, or — checked once, against the freshly loaded durable state —
+            // when a cut-off run left its trailing user or tool message unanswered. Afterwards
+            // a trailing user message can be legitimate: a response may have zero blocks.
+            let responseOwed = resumed.length > 0;
+            if (!this.#recoveryChecked) {
+                this.#recoveryChecked = true;
+                const last = this.#messages[this.#messages.length - 1];
+                responseOwed ||= last?.role === "user" || last?.role === "tool";
+            }
+            // Each cycle first drains the queues, then runs one inference. Steering injects at
+            // every stop between responses and always outranks sends; sent messages inject
+            // only when the agent would otherwise stop — no tool results or steering remain.
+            // Queue consumption happens only here, between inferences, so an injected message
+            // can never interleave with an active response's block records.
+            // The message of an error response that has not been recovered from yet. A later
+            // successful response clears it; a turn that ends while it is set has failed and
+            // surfaces it to the context as a system message.
+            let pendingError;
+            while (true) {
+                // An abort during the tool batch ends the turn here, before the next inference.
+                if (abort.signal.aborted) {
+                    this.#emit({ type: "done", state: "cancelled" });
+                    break;
+                }
+                let injected = await this.#consumeQueue(this.#steering, this.#steeringMode);
+                if (!injected && !responseOwed) {
+                    injected = await this.#consumeQueue(this.#sends, this.#sendMode);
+                }
+                // Nothing to answer — a start() on an idle history, or the queues ran dry.
+                if (!injected && !responseOwed)
+                    break;
+                const session = await this.#ensureSession();
+                this.#invokeHook(this.#hooks.beforeInference);
+                const stream = session.run(this.#ctx, {
+                    context: {
+                        instructions: this.#instructions(),
+                        messages: [...this.#messages],
+                    },
+                    ...(this.#model === undefined ? {} : { model: this.#model }),
+                    ...(this.#effort === undefined ? {} : { effort: this.#effort }),
+                    ...(this.#serviceTier === undefined
+                        ? {}
+                        : { serviceTier: this.#serviceTier }),
+                });
+                const { content, state, errorMessage } = await this.#collect(stream, abortPromise);
+                this.#invokeHook(this.#hooks.afterInference);
+                if (content.length > 0) {
+                    this.#messages.push({ role: "assistant", content });
+                }
+                responseOwed = false;
+                pendingError = state === "error" ? errorMessage : undefined;
+                if (state === "tool_call") {
+                    const calls = content.filter((block) => block.type === "tool_call" && block.server !== true);
+                    if (calls.length === 0)
+                        continue;
+                    await this.#runToolBatch(calls.map((call, index) => ({
+                        key: this.#toolKey(index, call.callId),
+                        call,
+                    })), false, abort.signal, abortPromise);
+                    responseOwed = true;
+                    continue;
+                }
+                // A natural stop keeps draining, and so does a provider-reported error: the
+                // failed response never answers the queued messages, so they still get their
+                // fresh inference — each drain consumes from a finite queue, so a persistently
+                // failing provider cannot loop. A cancellation or a stream that ended without
+                // a done event ends the turn with the queues intact.
+                if (state !== "normal" && state !== "length" && state !== "error")
+                    break;
+            }
+            if (pendingError !== undefined) {
+                await this.#appendFailure(pendingError);
+            }
+        }
+        catch (error) {
+            this.#emit({
+                type: "done",
+                state: "error",
+                kind: "internal_error",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            await this.#appendFailure(error instanceof Error ? error.message : String(error));
+        }
+        // The turn is over; a requested compaction runs now, before the next pass can start.
+        await this.#runCompaction();
+    }
+    /**
+     * Run the pending compaction, if any. The snapshot is taken here, with the turn over and
+     * this pass being the only history writer, so nothing joins the history mid-compaction; the
+     * suffix copy still keeps any such message, defensively. The replacement is appended as a
+     * compaction record — the load-time reset point — and settles the shared promise for every
+     * caller awaiting it. A provider failure rejects them and leaves the history untouched.
+     */
+    async #runCompaction() {
+        const pending = this.#compaction;
+        if (pending === undefined)
+            return;
+        try {
+            const session = await this.#ensureSession();
+            const snapshot = [...this.#messages];
+            const result = await session.compact(this.#ctx, {
+                context: { instructions: this.#instructions(), messages: snapshot },
+                ...(this.#model === undefined ? {} : { model: this.#model }),
+            });
+            if (result.status === "failed") {
+                throw new Error(result.message);
+            }
+            if (result.status === "completed") {
+                await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                    const suffix = this.#messages.slice(snapshot.length);
+                    const replaced = [...result.context.messages, ...suffix];
+                    // Physically delete the superseded records and write the replacement —
+                    // which keeps the messages that stay — in one atomic step.
+                    await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                        await this.#persistence.clearRecords(txCtx);
+                        await this.#persistence.append(txCtx, {
+                            type: "compaction",
+                            messages: replaced,
+                        });
+                    });
+                    this.#messages = replaced;
+                });
+            }
+            this.#compaction = undefined;
+            pending.resolve();
+        }
+        catch (error) {
+            this.#compaction = undefined;
+            pending.reject(error);
+        }
+    }
+    /**
+     * Surface a failed turn to the conversation as a system message, so the next inference sees
+     * what went wrong. Only unrecovered failures reach here — a later successful response in the
+     * same turn clears its error without a trace. Skipped when the history never loaded, since
+     * there is no context to append to; its own failure is swallowed, so surfacing a failure can
+     * never cause another.
+     */
+    async #appendFailure(message) {
+        if (this.#loaded === undefined)
+            return;
+        const failure = {
+            role: "system",
+            content: [{ type: "text", text: `The last turn failed: ${message}` }],
+        };
+        try {
+            await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+                await this.#persistence.append(lockCtx, { type: "system", message: failure });
+                this.#messages.push(failure);
+            });
+        }
+        catch {
+            // The turn already failed; a failing write must not escalate it.
+        }
+    }
+    /**
+     * Move the oldest queued message — or, in "all" mode, every queued message — into the main
+     * context store and the in-memory history. The moves run in one transaction, so a message
+     * is never durable in both stores or neither, and memory changes only after the commit.
+     */
+    async #consumeQueue(queue, mode) {
+        return await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            if (queue.length === 0)
+                return false;
+            const count = mode === "all" ? queue.length : 1;
+            const batch = queue.slice(0, count);
+            // Settings carried by the consumed messages become the effective settings for the
+            // inference that follows, each defined field superseding the previous value. The
+            // effective values are persisted alongside the consumption so a restart keeps them.
+            let provider = this.#providerId;
+            let model = this.#model;
+            let effort = this.#effort;
+            let serviceTier = this.#serviceTier;
+            let changed = false;
+            for (const entry of batch) {
+                if (entry.options.provider !== undefined) {
+                    provider = entry.options.provider;
+                    changed = true;
+                }
+                if (entry.options.model !== undefined) {
+                    model = entry.options.model;
+                    changed = true;
+                }
+                if (entry.options.effort !== undefined) {
+                    effort = entry.options.effort;
+                    changed = true;
+                }
+                if (entry.options.serviceTier !== undefined) {
+                    serviceTier = entry.options.serviceTier;
+                    changed = true;
+                }
+            }
+            // A provider or model change is checked against the provider-model compatibility
+            // matrix. An incompatible change resets the conversation: the history is erased
+            // completely, the old provider session is destroyed, and the `modelChanged` hook
+            // may inject one handoff system message at the very beginning of the fresh
+            // context. A compatible provider change keeps the history but still gets a fresh
+            // session, since a session is bound to the provider that created it.
+            const selectionChanged = provider !== this.#providerId || model !== this.#model;
+            let reset = false;
+            let injected;
+            if (selectionChanged) {
+                if (this.#model !== undefined && model !== undefined) {
+                    const previousType = this.#providers.typeOf(this.#providerId);
+                    const nextType = this.#providers.typeOf(provider);
+                    reset =
+                        previousType === null ||
+                            nextType === null ||
+                            !areProviderModelsCompatible({
+                                modelId: this.#model,
+                                providerId: this.#providerId,
+                                providerType: previousType,
+                            }, {
+                                modelId: model,
+                                providerId: provider,
+                                providerType: nextType,
+                            });
+                }
+                else {
+                    // A selection without a model on either side cannot be judged compatible.
+                    reset = model !== this.#model;
+                }
+                if (this.#hooks.modelChanged !== undefined && model !== undefined) {
+                    const changeCtx = withAgentBaseContext(this.#baseCtx, {
+                        provider,
+                        model,
+                        effort,
+                        serviceTier,
+                    });
+                    try {
+                        injected = this.#hooks.modelChanged(changeCtx, {
+                            previousModel: this.#model,
+                            model,
+                            previousProvider: this.#providerId,
+                            provider,
+                            providers: this.#providers,
+                            previousProviderInstance: this.#providers.get(this.#providerId),
+                            providerInstance: this.#providers.get(provider),
+                            wasReset: reset,
+                        });
+                    }
+                    catch {
+                        // Hooks observe the run; they never fail it.
+                    }
+                    if (!reset)
+                        injected = undefined;
+                }
+            }
+            await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                if (reset) {
+                    await this.#persistence.clearRecords(txCtx);
+                    if (injected !== undefined) {
+                        await this.#persistence.append(txCtx, {
+                            type: "system",
+                            message: injected,
+                        });
+                    }
+                }
+                for (const entry of batch) {
+                    await this.#persistence.append(txCtx, {
+                        type: "user",
+                        message: entry.message,
+                    });
+                    await this.#persistence.deleteValue(txCtx, entry.key);
+                }
+                if (changed) {
+                    await this.#persistence.writeValue(txCtx, "settings", {
+                        provider,
+                        ...(model === undefined ? {} : { model }),
+                        ...(effort === undefined ? {} : { effort }),
+                        ...(serviceTier === undefined ? {} : { serviceTier }),
+                    });
+                }
+            });
+            queue.splice(0, count);
+            if (reset) {
+                this.#messages = injected === undefined ? [] : [injected];
+            }
+            if (reset || provider !== this.#providerId) {
+                const session = this.#session;
+                this.#session = undefined;
+                try {
+                    await session?.destroy();
+                }
+                catch {
+                    // The change already committed; a failing destroy must not undo it.
+                }
+            }
+            this.#messages.push(...batch.map((entry) => entry.message));
+            if (changed) {
+                this.#providerId = provider;
+                this.#model = model;
+                this.#effort = effort;
+                this.#serviceTier = serviceTier;
+                this.#ctx = this.#deriveCtx();
+            }
+            return true;
+        });
+    }
+    /**
+     * Replace the in-memory state with the durable one. The persistence lock guarantees every
+     * message already in memory reached storage first, so the load result supersedes memory
+     * entirely: the main store rebuilds the context, and the sorted queue keys rebuild the
+     * not-yet-consumed queues. Consecutive block records reassemble into one assistant message.
+     */
+    async #loadHistory() {
+        await this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            const records = await this.#persistence.load(lockCtx);
+            let restored = [];
+            for (const record of records) {
+                if (record.type === "compaction") {
+                    // A compaction record carries the complete replacement context and
+                    // supersedes everything before it.
+                    restored = [...record.messages];
+                    continue;
+                }
+                if (record.type === "user" || record.type === "tool" || record.type === "system") {
+                    restored.push(record.message);
+                    continue;
+                }
+                const last = restored[restored.length - 1];
+                if (last?.role === "assistant") {
+                    restored[restored.length - 1] = {
+                        role: "assistant",
+                        content: [...last.content, record.block],
+                    };
+                }
+                else {
+                    restored.push({ role: "assistant", content: [record.block] });
+                }
+            }
+            const steering = await this.#persistence.readValues(lockCtx, "steering.");
+            const sends = await this.#persistence.readValues(lockCtx, "send.");
+            const pendingTools = await this.#persistence.readValues(lockCtx, "tool.");
+            const settings = await this.#persistence.readValues(lockCtx, "settings");
+            this.#messages = restored;
+            const entry = (key, value) => {
+                const envelope = value;
+                return { key, message: envelope.message, options: envelope.options ?? {} };
+            };
+            this.#steering = steering.map(({ key, value }) => entry(key, value));
+            this.#sends = sends.map(({ key, value }) => entry(key, value));
+            // The persisted settings are the complete effective triple from the last change; an
+            // absent field means that setting was effectively unset when it was written.
+            const persisted = settings[0]?.value;
+            if (persisted !== undefined) {
+                if (persisted.provider !== undefined)
+                    this.#providerId = persisted.provider;
+                this.#model = persisted.model;
+                this.#effort = persisted.effort;
+                this.#serviceTier = persisted.serviceTier;
+                this.#ctx = this.#deriveCtx();
+            }
+            this.#pendingTools = pendingTools.map(({ key, value }) => ({
+                key,
+                call: value,
+            }));
+        });
+    }
+    /**
+     * Run one batch of tool calls. The whole batch is committed to the sorted store before any
+     * call executes, so a crash mid-batch leaves a durable record of the calls still owed a
+     * result. All calls run in parallel, but results land strictly in call order: a finished
+     * result waits until every earlier call in the batch has committed, and each commit appends
+     * the tool record and removes the pending entry in one transaction before memory changes.
+     * On resume, only durable tools execute again; the rest become error results. An abort
+     * settles every call still running as an aborted error result, so the batch always leaves a
+     * complete context behind.
+     */
+    async #runToolBatch(entries, resume, signal, abortPromise) {
+        if (!resume) {
+            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#persistence.transaction(lockCtx, async (txCtx) => {
+                for (const entry of entries) {
+                    await this.#persistence.writeValue(txCtx, entry.key, entry.call);
+                }
+            }));
+        }
+        const results = new Array(entries.length);
+        let committed = 0;
+        const commitReady = () => this.#persistenceLock.runInLock(this.#ctx, async (lockCtx) => {
+            while (committed < entries.length) {
+                const entry = entries[committed];
+                const result = results[committed];
+                if (entry === undefined || result === undefined)
+                    return;
+                await this.#persistence.transaction(lockCtx, async (txCtx) => {
+                    await this.#persistence.append(txCtx, {
+                        type: "tool",
+                        message: result,
+                    });
+                    await this.#persistence.deleteValue(txCtx, entry.key);
+                });
+                this.#messages.push(result);
+                committed += 1;
+            }
+        });
+        await Promise.all(entries.map(async (entry, index) => {
+            const outcome = resume && !this.#isDurable(entry.call)
+                ? {
+                    role: "tool",
+                    callId: entry.call.callId,
+                    content: [
+                        {
+                            type: "text",
+                            text: "The tool call was interrupted by a restart and was not retried.",
+                        },
+                    ],
+                    isError: true,
+                }
+                : await Promise.race([
+                    this.#executeToolCall(withLifetime(this.#ctx, signal), entry.call),
+                    abortPromise,
+                ]);
+            results[index] =
+                outcome === ABORTED
+                    ? {
+                        role: "tool",
+                        callId: entry.call.callId,
+                        content: [{ type: "text", text: "The tool call was aborted." }],
+                        isError: true,
+                    }
+                    : outcome;
+            await commitReady();
+        }));
+    }
+    #isDurable(call) {
+        const tool = this.#tools().find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
+        return tool?.durable === true;
+    }
+    /** Sorted by position in the batch; only one batch is ever pending at a time. */
+    #toolKey(index, callId) {
+        return `tool.${String(index).padStart(6, "0")}.${callId}`;
+    }
+    /**
+     * Run one tool call; every failure becomes an error tool result instead of an exception.
+     * The context carries the turn's abort signal as its lifetime, so a running tool can
+     * observe cancellation and stop its own work.
+     */
+    async #executeToolCall(ctx, call) {
+        const failure = (text) => ({
+            role: "tool",
+            callId: call.callId,
+            content: [{ type: "text", text }],
+            isError: true,
+        });
+        const tool = this.#tools().find((candidate) => candidate.name === call.name && candidate.namespace === call.namespace);
+        if (tool === undefined) {
+            return failure(`Tool "${call.name}" is not available.`);
+        }
+        if (call.incomplete === true) {
+            return failure("The tool call was incomplete and was not executed.");
+        }
+        let args;
+        try {
+            args = call.arguments.trim().length === 0 ? {} : JSON.parse(call.arguments);
+        }
+        catch {
+            return failure(`The arguments for "${call.name}" were not valid JSON.`);
+        }
+        if (tool.parameters !== undefined && !Value.Check(tool.parameters, args)) {
+            return failure(`The arguments for "${call.name}" did not match its schema.`);
+        }
+        try {
+            const result = await tool.execute(ctx, args);
+            if (!Value.Check(tool.returnType, result)) {
+                return failure(`Tool "${call.name}" returned an invalid result.`);
+            }
+            const content = tool.toLLM(result);
+            const isError = tool.isError?.(result) === true;
+            return {
+                role: "tool",
+                callId: call.callId,
+                content: [...content],
+                ...(isError ? { isError: true } : {}),
+            };
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+    }
+    /** Sorted after every earlier key of its queue, within this process and across restarts. */
+    #queueKey(prefix) {
+        const time = String(Date.now()).padStart(14, "0");
+        const sequence = String(this.#pendingSequence++).padStart(6, "0");
+        return `${prefix}${time}.${sequence}`;
+    }
+    async #collect(stream, abortPromise) {
+        const content = [];
+        // Blocks that finished and were durably appended. An abort keeps exactly these, so the
+        // in-memory assistant message never diverges from what a reload would rebuild.
+        const persisted = [];
+        const toolCallIndexes = new Map();
+        const persist = async (block) => {
+            if (block === undefined)
+                return;
+            await this.#persistenceLock.runInLock(this.#ctx, (lockCtx) => this.#persistence.append(lockCtx, { type: "block", block }));
+            persisted.push(block);
+        };
+        const iterator = stream[Symbol.asyncIterator]();
+        while (true) {
+            const next = await Promise.race([iterator.next(), abortPromise]);
+            if (next === ABORTED) {
+                // Close the provider stream, drop the unfinished block, and end the turn.
+                void Promise.resolve(iterator.return?.()).catch(() => undefined);
+                this.#emit({ type: "done", state: "cancelled" });
+                return { content: persisted, state: "cancelled" };
+            }
+            if (next.done === true)
+                break;
+            const event = next.value;
+            this.#emit(event);
+            switch (event.type) {
+                case "text_start":
+                    content.push({ type: "text", text: "" });
+                    break;
+                case "text_delta": {
+                    const last = content[content.length - 1];
+                    if (last?.type === "text") {
+                        content[content.length - 1] = {
+                            type: "text",
+                            text: last.text + event.delta,
+                        };
+                    }
+                    break;
+                }
+                case "text_end": {
+                    const last = content[content.length - 1];
+                    await persist(last?.type === "text" ? last : undefined);
+                    break;
+                }
+                case "reasoning_start":
+                    content.push({ type: "reasoning", text: "" });
+                    break;
+                case "reasoning_delta": {
+                    const last = content[content.length - 1];
+                    if (last?.type === "reasoning") {
+                        content[content.length - 1] = {
+                            ...last,
+                            text: (last.text ?? "") + event.delta,
+                        };
+                    }
+                    break;
+                }
+                case "reasoning_end": {
+                    const last = content[content.length - 1];
+                    if (last?.type === "reasoning") {
+                        const finished = {
+                            ...last,
+                            ...(event.reasoning === undefined
+                                ? {}
+                                : { reasoning: event.reasoning }),
+                        };
+                        content[content.length - 1] = finished;
+                        await persist(finished);
+                    }
+                    break;
+                }
+                case "toolcall_start":
+                    toolCallIndexes.set(event.callId, content.length);
+                    content.push({
+                        type: "tool_call",
+                        callId: event.callId,
+                        name: event.name,
+                        arguments: "",
+                        ...(event.namespace === undefined ? {} : { namespace: event.namespace }),
+                        ...(event.server === undefined ? {} : { server: event.server }),
+                        ...(event.vendor === undefined ? {} : { vendor: event.vendor }),
+                    });
+                    break;
+                case "toolcall_end": {
+                    const index = toolCallIndexes.get(event.callId);
+                    const block = index === undefined ? undefined : content[index];
+                    if (index !== undefined && block?.type === "tool_call") {
+                        const finished = {
+                            ...block,
+                            arguments: event.arguments,
+                            ...(event.incomplete === undefined
+                                ? {}
+                                : { incomplete: event.incomplete }),
+                        };
+                        content[index] = finished;
+                        await persist(finished);
+                    }
+                    break;
+                }
+                // The provider settled a server tool call on its own backend and streams the
+                // result here. The agent simply ignores it: nothing to execute, nothing to
+                // store — the events still reach the hooks like every other event.
+                case "toolcall_result_start":
+                case "toolcall_result_delta":
+                case "toolcall_result_end":
+                    break;
+                case "done":
+                    return {
+                        content,
+                        state: event.state,
+                        ...(event.state === "error" ? { errorMessage: event.message } : {}),
+                    };
+                default:
+                    break;
+            }
+        }
+        return { content, state: undefined };
+    }
+    /**
+     * Create the provider session on first use, resolving the provider from the registry by its
+     * serializable ID at that moment; an unregistered ID fails the turn like any thrown error.
+     */
+    async #ensureSession() {
+        if (this.#session === undefined) {
+            const provider = this.#providers.get(this.#providerId);
+            if (provider === null) {
+                throw new Error(`Provider "${this.#providerId}" is not registered.`);
+            }
+            this.#session = await provider.session(this.id, {
+                instructions: this.#instructions(),
+                tools: [...this.#tools()],
+            });
+        }
+        return this.#session;
+    }
+    #emit(event) {
+        try {
+            this.#hooks.onEvent?.(this.#ctx, event);
+        }
+        catch {
+            // Hooks observe the stream; they never fail a run.
+        }
+    }
+}
+//# sourceMappingURL=AgentBase.js.map