@zhivex-ai/core 1.3.0 → 1.4.0

package/dist/live-agent.js

@@ -1,9 +1,8 @@
 import { BoundedReplayBroadcast } from "./bounded-broadcast.js";
-import { GuardrailTriggeredError } from "./errors.js";
+import { ConflictError, GuardrailTriggeredError, ValidationError } from "./errors.js";
 import { AGENT_RUN_STATE_SCHEMA_VERSION, normalizeAgentRunState } from "./agent-state.js";
 import { normalizeMessages } from "./generate-text.js";
 import { createTextMessage, getTextFromParts, isCallableToolDefinition, serializeJsonValue, toolResultPart } from "./messages.js";
-import { mergeAbortSignals } from "./runtime.js";
 import { createSecureId } from "./secure-id.js";
 import { toToolSet } from "./tool-registry.js";
 const joinInstructions = (...parts) => {
@@ -15,12 +14,14 @@ const cloneMetadata = (...values) => {
     return Object.keys(merged).length ? merged : undefined;
 };
 const cloneState = (state) => JSON.parse(JSON.stringify(normalizeAgentRunState(state)));
-const createBaseState = (provider, modelId, initialMessages, metadata, agentId, runId) => {
+const createBaseState = (provider, modelId, initialMessages, metadata, agentId, runId, scope, idempotencyKey) => {
     const startedAt = Date.now();
     return {
         schemaVersion: AGENT_RUN_STATE_SCHEMA_VERSION,
         revision: 0,
+        scope,
         runId,
+        idempotencyKey,
         agentId,
         provider,
         modelId,
@@ -37,12 +38,6 @@ const createBaseState = (provider, modelId, initialMessages, metadata, agentId,
         updatedAt: startedAt
     };
 };
-const createFailedState = (state, message) => ({
-    ...state,
-    status: "failed",
-    error: { message },
-    updatedAt: Date.now()
-});
 const applyGuardrailFailure = (state, stage, trigger) => ({
     ...state,
     status: "failed",
@@ -51,44 +46,70 @@ const applyGuardrailFailure = (state, stage, trigger) => ({
     },
     updatedAt: Date.now()
 });
-const emitTelemetryEvent = async (agent, event) => {
-    await agent.onTelemetryEvent?.(event);
+const emitTelemetryEvent = async (agent, event, abortSignal) => {
+    const operation = Promise.resolve().then(() => agent.onTelemetryEvent?.(event));
+    if (abortSignal)
+        await raceWithAbort(operation, abortSignal);
+    else
+        await operation;
+};
+const checkpointState = async (agent, state, abortSignal) => {
+    if (agent.store) {
+        const expectedRevision = state.revision ?? 0;
+        const nextRevision = expectedRevision + 1;
+        if (abortSignal?.aborted)
+            throw abortError(abortSignal);
+        const save = Promise.resolve(agent.store.save(cloneState({ ...state, revision: nextRevision }), { expectedRevision }));
+        if (abortSignal)
+            await raceWithAbort(save, abortSignal);
+        else
+            await save;
+        state.revision = nextRevision;
+    }
 };
-const persistState = async (agent, state) => {
+const persistState = async (agent, state, abortSignal) => {
     state.updatedAt = Date.now();
-    await agent.store?.save(cloneState(state));
+    await checkpointState(agent, state, abortSignal);
     await emitTelemetryEvent(agent, {
         type: "state-saved",
         runId: state.runId,
         agentId: state.agentId,
         status: state.status
-    });
-    await agent.memory?.save?.({
-        runId: state.runId,
-        agentId: state.agentId,
-        state: cloneState(state),
-        metadata: state.metadata
-    });
+    }, abortSignal);
+    if (agent.memory?.save) {
+        const save = Promise.resolve().then(() => agent.memory.save({
+            runId: state.runId,
+            agentId: state.agentId,
+            scope: state.scope,
+            state: cloneState(state),
+            metadata: state.metadata
+        }));
+        if (abortSignal)
+            await raceWithAbort(save, abortSignal);
+        else
+            await save;
+    }
 };
-const runGuardrails = async (agent, state, stage, guardrails, requestFactory) => {
+const runGuardrails = async (agent, state, stage, guardrails, requestFactory, abortSignal) => {
     for (const [index, guardrail] of (guardrails ?? []).entries()) {
-        const trigger = await guardrail(requestFactory(index));
+        const execution = Promise.resolve().then(() => guardrail(requestFactory(index)));
+        const trigger = abortSignal ? await raceWithAbort(execution, abortSignal) : await execution;
         if (!trigger?.triggered) {
             continue;
         }
-        await agent.onTelemetryEvent?.({
+        await emitTelemetryEvent(agent, {
             type: "guardrail-triggered",
             runId: state.runId,
             agentId: state.agentId,
             stage,
             reason: trigger.reason ?? `Agent ${stage} guardrail #${index + 1} triggered.`,
             metadata: trigger.metadata
-        });
+        }, abortSignal);
         return trigger;
     }
     return undefined;
 };
-const emitRunStartTelemetry = async (agent, state, memoryMessages) => {
+const emitRunStartTelemetry = async (agent, state, memoryMessages, abortSignal) => {
     await emitTelemetryEvent(agent, {
         type: "run-start",
         runId: state.runId,
@@ -96,48 +117,53 @@ const emitRunStartTelemetry = async (agent, state, memoryMessages) => {
         provider: state.provider,
         modelId: state.modelId,
         maxSteps: state.maxSteps
-    });
+    }, abortSignal);
     if (memoryMessages.length) {
         await emitTelemetryEvent(agent, {
             type: "memory-loaded",
             runId: state.runId,
             agentId: state.agentId,
             messageCount: memoryMessages.length
-        });
+        }, abortSignal);
     }
 };
-const emitRunFinishTelemetry = async (agent, state) => {
+const emitRunFinishTelemetry = async (agent, state, abortSignal) => {
     await emitTelemetryEvent(agent, {
         type: "run-finish",
         runId: state.runId,
         agentId: state.agentId,
         status: state.status,
         state: cloneState(state)
-    });
+    }, abortSignal);
 };
 const withToolTimeout = async (operation, timeoutMs, abortSignal) => {
-    if (!timeoutMs) {
-        return operation(abortSignal);
-    }
     const controller = new AbortController();
-    const signal = mergeAbortSignals(abortSignal, controller.signal);
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            controller.abort();
-            reject(new Error(`Tool execution timed out after ${timeoutMs}ms.`));
-        }, timeoutMs);
-        Promise.resolve()
-            .then(() => operation(signal))
-            .then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        })
-            .catch((error) => {
+    const abortFromCaller = () => controller.abort(abortSignal?.reason);
+    if (abortSignal?.aborted) {
+        abortFromCaller();
+    }
+    else {
+        abortSignal?.addEventListener("abort", abortFromCaller, { once: true });
+    }
+    const signal = controller.signal;
+    const timer = timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => controller.abort(new ToolExecutionTimeoutError(timeoutMs)), timeoutMs);
+    try {
+        return await raceWithAbort(Promise.resolve().then(() => operation(signal)), signal);
+    }
+    finally {
+        if (timer)
             clearTimeout(timer);
-            reject(error);
-        });
-    });
+        abortSignal?.removeEventListener("abort", abortFromCaller);
+    }
 };
+class ToolExecutionTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Tool execution timed out after ${timeoutMs}ms.`);
+        this.name = "ToolExecutionTimeoutError";
+    }
+}
 const injectContextMessages = (messages, extraMessages) => {
     if (!extraMessages.length) {
         return messages;
@@ -148,6 +174,116 @@ const injectContextMessages = (messages, extraMessages) => {
     return [...extraMessages, ...messages];
 };
 const textFromMessage = (message) => getTextFromParts(message.parts).trim();
+const contextInstructions = (messages) => {
+    const lines = messages.flatMap((message) => {
+        const text = textFromMessage(message);
+        return text ? [`${message.role}: ${text}`] : [];
+    });
+    return lines.length ? `Conversation context:\n${lines.join("\n")}` : undefined;
+};
+const ensureValidScope = (scope) => {
+    if (!scope)
+        return;
+    if (typeof scope.tenantId !== "string" || scope.tenantId.length === 0) {
+        throw new ValidationError('Live agent scope "tenantId" must be a non-empty string.');
+    }
+    for (const field of ["userId", "namespace"]) {
+        if (scope[field] !== undefined && (typeof scope[field] !== "string" || scope[field].length === 0)) {
+            throw new ValidationError(`Live agent scope "${field}" must be a non-empty string when provided.`);
+        }
+    }
+};
+const ensureDurableConfiguration = (agent, input, tools) => {
+    ensureValidScope(input.scope);
+    if (input.idempotencyKey && !agent.store) {
+        throw new ValidationError('The live agent "idempotencyKey" option requires an agent run "store".');
+    }
+    if (input.idempotencyKey && !agent.store?.claimIdempotencyKey) {
+        throw new ValidationError('The live agent run "store" must implement "claimIdempotencyKey()" to use "idempotencyKey" safely.');
+    }
+    const hasCallableTools = Object.values(toToolSet(tools) ?? {}).some(isCallableToolDefinition);
+    if (agent.store &&
+        hasCallableTools &&
+        (!agent.store.claimToolExecution || !agent.store.loadToolExecution || !agent.store.completeToolExecution)) {
+        throw new ValidationError('A live agent run "store" with local tools must implement claimToolExecution(), loadToolExecution(), and completeToolExecution().');
+    }
+};
+class LiveAgentTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Live agent run timed out after ${timeoutMs}ms.`);
+        this.name = "LiveAgentTimeoutError";
+    }
+}
+const createLifetimeAbort = (input) => {
+    if (input.timeoutMs !== undefined &&
+        (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs <= 0 || input.timeoutMs > 24 * 60 * 60 * 1_000)) {
+        throw new ValidationError('The "timeoutMs" option must be a positive safe integer no greater than 86400000.');
+    }
+    const controller = new AbortController();
+    const sources = [input.abortSignal, input.connectOptions?.signal].filter((signal) => Boolean(signal));
+    const listeners = new Map();
+    for (const source of sources) {
+        const abort = () => controller.abort(source.reason);
+        listeners.set(source, abort);
+        if (source.aborted) {
+            abort();
+            break;
+        }
+        source.addEventListener("abort", abort, { once: true });
+    }
+    const timer = input.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => controller.abort(new LiveAgentTimeoutError(input.timeoutMs)), input.timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            if (timer)
+                clearTimeout(timer);
+            for (const [source, listener] of listeners) {
+                source.removeEventListener("abort", listener);
+            }
+        }
+    };
+};
+const abortError = (signal) => signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted.", "AbortError");
+const raceWithAbort = async (operation, signal) => {
+    if (signal.aborted)
+        throw abortError(signal);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+};
+const TERMINAL_FAILURE_CLEANUP_TIMEOUT_MS = 1_000;
+const runTerminalFailureCleanup = async (operations) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException("Terminal live-agent cleanup timed out.", "TimeoutError")), TERMINAL_FAILURE_CLEANUP_TIMEOUT_MS);
+    try {
+        await Promise.allSettled(operations.map((operation) => raceWithAbort(Promise.resolve().then(() => operation(controller.signal)), controller.signal)));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const nextWithAbort = (iterator, signal) => raceWithAbort(Promise.resolve(iterator.next()), signal);
+const canonicalJson = (value) => {
+    if (value === undefined)
+        return "undefined";
+    if (Array.isArray(value))
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+const sameJson = (left, right) => canonicalJson(left) === canonicalJson(right);
 const createResult = (state) => ({
     status: state.status,
     outputText: state.outputText,
@@ -172,7 +308,11 @@ const createBroadcast = () => {
     };
     return {
         publish,
-        stream: () => broadcast.stream()
+        close: () => broadcast.close(),
+        get isClosed() {
+            return broadcast.isClosed;
+        },
+        stream: (accepts) => broadcast.stream(accepts)
     };
 };
 const resolveApproval = async (options) => {
@@ -214,344 +354,571 @@ export const streamLiveAgent = (agent, input = {}) => {
     const broadcast = createBroadcast();
     let resolveSession;
     let rejectSession;
+    let sessionSettled = false;
     const sessionPromise = new Promise((resolve, reject) => {
-        resolveSession = resolve;
-        rejectSession = reject;
+        resolveSession = (session) => {
+            if (sessionSettled)
+                return;
+            sessionSettled = true;
+            resolve(session);
+        };
+        rejectSession = (error) => {
+            if (sessionSettled)
+                return;
+            sessionSettled = true;
+            reject(error);
+        };
     });
+    void sessionPromise.catch(() => undefined);
+    const lifetime = createLifetimeAbort(input);
     const runner = (async () => {
         const runId = input.runId ?? createSecureId("run");
         const metadata = cloneMetadata(agent.metadata, input.metadata);
-        const memoryMessages = agent.memory
-            ? await agent.memory.load({
-                runId,
-                agentId: agent.id,
-                metadata
-            })
-            : [];
-        let messages = normalizeMessages({
-            prompt: input.prompt,
-            messages: input.messages,
-            system: joinInstructions(agent.instructions, input.system)
-        });
-        messages = injectContextMessages(messages, memoryMessages);
-        const state = createBaseState(agent.model.provider, agent.model.modelId, messages, metadata, agent.id, runId);
-        await emitRunStartTelemetry(agent, state, memoryMessages);
-        await broadcast.publish({
-            done: false,
-            value: {
-                type: "agent-run-start",
-                currentStep: 1,
-                maxSteps: 1
-            }
-        });
-        const inputGuardrail = await runGuardrails(agent, state, "input", agent.inputGuardrails, () => ({
-            runId: state.runId,
-            agentId: state.agentId,
-            state: cloneState(state),
-            messages,
-            metadata: state.metadata
-        }));
-        if (inputGuardrail) {
-            const failedState = applyGuardrailFailure(state, "input", inputGuardrail);
-            await persistState(agent, failedState);
-            await emitRunFinishTelemetry(agent, failedState);
-            const error = new GuardrailTriggeredError("input", failedState.error?.message ?? "Agent input guardrail triggered.", {
-                metadata: inputGuardrail.metadata
-            });
-            await broadcast.publish({ done: false, value: { type: "error", error } });
-            await broadcast.publish({
-                done: false,
-                value: {
-                    type: "agent-run-finish",
-                    status: failedState.status,
-                    state: failedState
-                }
-            });
-            await broadcast.publish({ done: true, value: undefined });
-            rejectSession(error);
-            return createResult(failedState);
-        }
-        const resolvedTools = {
-            ...(toToolSet(agent.tools) ?? {}),
-            ...(toToolSet(input.tools) ?? {})
-        };
-        const realtimeConfig = {
-            autoResponse: true,
-            ...input.realtime,
-            instructions: joinInstructions(agent.instructions, input.system, input.realtime?.instructions),
-            tools: Object.keys(resolvedTools).length ? resolvedTools : undefined,
-            toolChoice: input.toolChoice ?? input.realtime?.toolChoice ?? agent.toolChoice,
-            providerOptions: {
-                ...(agent.providerOptions ?? {}),
-                ...(input.providerOptions ?? {}),
-                ...(input.realtime?.providerOptions ?? {})
-            }
-        };
+        let resolvedTools = {};
+        let state;
         let session;
-        let sessionError;
-        let transcript = [...messages];
+        let closePromise;
+        let runError;
+        let failureCleanupRan = false;
+        let transcript = [];
         const toolResults = [];
         const assistantBuffer = [];
+        const outputTranscriptBuffer = [];
         let finalText = "";
+        let sessionError;
+        const processedToolCalls = new Map();
+        const closeSession = async () => {
+            if (!session)
+                return;
+            closePromise ??= Promise.resolve().then(() => session.close());
+            await closePromise;
+        };
+        const abortSession = () => {
+            void closeSession().catch(() => undefined);
+        };
+        lifetime.signal.addEventListener("abort", abortSession, { once: true });
+        const publish = async (event) => {
+            if (!broadcast.isClosed) {
+                const terminal = event.type === "agent-run-finish" || event.type === "error" || event.type === "realtime-end";
+                const operation = broadcast.publish({ done: false, value: event });
+                if (terminal)
+                    await operation;
+                else
+                    await raceWithAbort(operation, lifetime.signal);
+            }
+        };
+        const rejectNoSession = (error) => {
+            rejectSession(error instanceof Error ? error : new Error(String(error)));
+        };
         try {
-            session = await agent.model.connect(realtimeConfig, input.connectOptions);
-            resolveSession(session);
-            if (input.messages) {
-                for (const message of input.messages) {
-                    if (message.role !== "user") {
-                        continue;
-                    }
-                    const text = textFromMessage(message);
-                    if (text) {
-                        await session.sendText(text);
+            resolvedTools = {
+                ...(toToolSet(agent.tools) ?? {}),
+                ...(toToolSet(input.tools) ?? {})
+            };
+            ensureDurableConfiguration(agent, input, resolvedTools);
+            const baseMessages = normalizeMessages({
+                prompt: input.prompt,
+                messages: input.messages,
+                system: joinInstructions(agent.instructions, input.system)
+            });
+            state = createBaseState(agent.model.provider, agent.model.modelId, baseMessages, metadata, agent.id, runId, input.scope, input.idempotencyKey);
+            if (agent.store) {
+                let existing = input.idempotencyKey
+                    ? undefined
+                    : await raceWithAbort(Promise.resolve(agent.store.load(runId, input.scope)), lifetime.signal);
+                if (input.idempotencyKey) {
+                    const claim = await raceWithAbort(Promise.resolve(agent.store.claimIdempotencyKey(state)), lifetime.signal);
+                    if (!claim.claimed)
+                        existing = normalizeAgentRunState(claim.state);
+                    else
+                        state = normalizeAgentRunState(claim.state);
+                }
+                if (existing) {
+                    const normalized = normalizeAgentRunState(existing);
+                    const terminalStatuses = ["completed", "failed", "cancelled", "timed_out"];
+                    if (!terminalStatuses.includes(normalized.status)) {
+                        throw new ConflictError(`Live agent run "${normalized.runId}" is already ${normalized.status}.`);
                     }
+                    state = normalized;
+                    await emitRunStartTelemetry(agent, state, [], lifetime.signal);
+                    await publish({ type: "agent-run-start", currentStep: 1, maxSteps: 1 });
+                    await emitRunFinishTelemetry(agent, state, lifetime.signal);
+                    await publish({ type: "agent-run-finish", status: state.status, state: cloneState(state) });
+                    rejectNoSession(new ValidationError(`Live agent run "${state.runId}" was replayed from durable state and has no active realtime session.`));
+                    return createResult(state);
+                }
+                if (!input.idempotencyKey) {
+                    await checkpointState(agent, state, lifetime.signal);
+                }
+            }
+            const memoryMessages = agent.memory
+                ? await raceWithAbort(Promise.resolve(agent.memory.load({
+                    runId,
+                    agentId: agent.id,
+                    scope: input.scope,
+                    metadata
+                })), lifetime.signal)
+                : [];
+            const messages = injectContextMessages(baseMessages, memoryMessages);
+            transcript = [...messages];
+            state.messages = messages;
+            await emitRunStartTelemetry(agent, state, memoryMessages, lifetime.signal);
+            await persistState(agent, state, lifetime.signal);
+            await publish({ type: "agent-run-start", currentStep: 1, maxSteps: 1 });
+            const inputGuardrail = await runGuardrails(agent, state, "input", agent.inputGuardrails, () => ({
+                runId: state.runId,
+                agentId: state.agentId,
+                state: cloneState(state),
+                messages,
+                metadata: state.metadata
+            }), lifetime.signal);
+            if (inputGuardrail) {
+                const failedState = applyGuardrailFailure(state, "input", inputGuardrail);
+                state = failedState;
+                await persistState(agent, failedState, lifetime.signal);
+                await emitRunFinishTelemetry(agent, failedState, lifetime.signal);
+                const error = new GuardrailTriggeredError("input", failedState.error?.message ?? "Agent input guardrail triggered.", { metadata: inputGuardrail.metadata });
+                await publish({ type: "error", error });
+                await publish({ type: "agent-run-finish", status: failedState.status, state: cloneState(failedState) });
+                rejectNoSession(error);
+                return createResult(failedState);
+            }
+            const explicitMessages = input.messages ?? [];
+            let activeUserIndex = -1;
+            explicitMessages.forEach((message, index) => {
+                if (message.role === "user")
+                    activeUserIndex = index;
+            });
+            const priorConversation = explicitMessages.filter((_, index) => index !== activeUserIndex);
+            const realtimeConfig = {
+                autoResponse: true,
+                ...input.realtime,
+                instructions: joinInstructions(agent.instructions, input.system, contextInstructions([...memoryMessages, ...priorConversation]), input.realtime?.instructions),
+                tools: Object.keys(resolvedTools).length ? resolvedTools : undefined,
+                toolChoice: input.toolChoice ?? input.realtime?.toolChoice ?? agent.toolChoice,
+                providerOptions: {
+                    ...(agent.providerOptions ?? {}),
+                    ...(input.providerOptions ?? {}),
+                    ...(input.realtime?.providerOptions ?? {})
+                }
+            };
+            if (lifetime.signal.aborted)
+                throw abortError(lifetime.signal);
+            const connectPromise = agent.model.connect(realtimeConfig, {
+                ...input.connectOptions,
+                timeoutMs: input.connectOptions?.timeoutMs ?? input.timeoutMs,
+                signal: lifetime.signal
+            });
+            void connectPromise.then((lateSession) => {
+                if (lifetime.signal.aborted && lateSession !== session) {
+                    void lateSession.close().catch(() => undefined);
+                }
+            }, () => undefined);
+            session = await raceWithAbort(connectPromise, lifetime.signal);
+            resolveSession(session);
+            if (activeUserIndex >= 0) {
+                const text = textFromMessage(explicitMessages[activeUserIndex]);
+                if (text) {
+                    if (lifetime.signal.aborted)
+                        throw abortError(lifetime.signal);
+                    await raceWithAbort(session.sendText(text), lifetime.signal);
                 }
             }
             else if (input.prompt) {
-                await session.sendText(input.prompt);
+                if (lifetime.signal.aborted)
+                    throw abortError(lifetime.signal);
+                await raceWithAbort(session.sendText(input.prompt), lifetime.signal);
             }
-            for await (const event of session.eventStream()) {
-                await broadcast.publish({ done: false, value: event });
-                if (event.type === "realtime-text-delta") {
-                    assistantBuffer.push(event.textDelta);
-                    await broadcast.publish({
-                        done: false,
-                        value: {
-                            type: "text-delta",
-                            textDelta: event.textDelta
+            const recordToolResult = async (result, fingerprint) => {
+                processedToolCalls.set(result.toolCallId, { fingerprint, result });
+                toolResults.push(result);
+                transcript.push({ role: "tool", parts: [toolResultPart(result)] });
+                state.messages = transcript;
+                state.toolResults = toolResults;
+                await persistState(agent, state, lifetime.signal);
+                if (lifetime.signal.aborted)
+                    throw abortError(lifetime.signal);
+                await raceWithAbort(session.sendToolResult(result), lifetime.signal);
+            };
+            const executeTool = async (definition, call, parsedInput, serializedInput) => {
+                const idempotencyKey = `${input.idempotencyKey ?? state.runId}:${call.id}`;
+                let journalClaim;
+                if (agent.store) {
+                    const candidate = {
+                        runId: state.runId,
+                        scope: state.scope,
+                        toolCallId: call.id,
+                        toolName: call.name,
+                        status: "pending",
+                        idempotencyKey,
+                        revision: 0,
+                        input: serializedInput,
+                        updatedAt: Date.now()
+                    };
+                    if (lifetime.signal.aborted)
+                        throw abortError(lifetime.signal);
+                    const claim = await raceWithAbort(Promise.resolve(agent.store.claimToolExecution(candidate)), lifetime.signal);
+                    if (!claim.claimed) {
+                        if (claim.entry.toolName !== call.name || !sameJson(claim.entry.input, serializedInput)) {
+                            throw new ConflictError(`Realtime tool call id "${call.id}" was reused with a different payload.`);
+                        }
+                        if (claim.entry.status === "completed") {
+                            return {
+                                toolCallId: call.id,
+                                toolName: call.name,
+                                output: claim.entry.output ?? null,
+                                isError: false
+                            };
+                        }
+                        if (claim.entry.status === "failed") {
+                            return {
+                                toolCallId: call.id,
+                                toolName: call.name,
+                                error: { message: claim.entry.error?.message ?? `Tool "${call.name}" previously failed.` },
+                                isError: true
+                            };
                         }
-                    });
-                    continue;
+                        throw new ConflictError(`Tool "${call.name}" has an indeterminate durable execution. Reconcile idempotency key "${claim.entry.idempotencyKey}" before retrying.`);
+                    }
+                    journalClaim = claim.entry;
                 }
-                if (event.type === "realtime-transcript") {
-                    if (event.role === "user" && event.isFinal && event.text) {
-                        transcript.push(createTextMessage("user", event.text));
+                try {
+                    const output = serializeJsonValue(await withToolTimeout(async (abortSignal) => definition.execute(parsedInput, {
+                        abortSignal,
+                        toolCall: call,
+                        step: 1,
+                        model: agent.model,
+                        realtimeConfig,
+                        runId: state.runId,
+                        agentId: state.agentId,
+                        scope: state.scope,
+                        metadata: state.metadata,
+                        idempotencyKey
+                    }), (input.toolExecution ?? agent.toolExecution)?.timeoutMs, lifetime.signal));
+                    if (journalClaim) {
+                        if (lifetime.signal.aborted)
+                            throw abortError(lifetime.signal);
+                        await raceWithAbort(Promise.resolve(agent.store.completeToolExecution({
+                            ...journalClaim,
+                            status: "completed",
+                            output,
+                            completedAt: Date.now(),
+                            updatedAt: Date.now()
+                        }, { expectedRevision: journalClaim.revision })), lifetime.signal);
                     }
-                    if (event.role === "assistant" && event.isFinal) {
-                        const text = event.text || assistantBuffer.join("");
-                        if (text) {
-                            finalText = text;
-                            transcript.push(createTextMessage("assistant", text));
-                            assistantBuffer.length = 0;
+                    return { toolCallId: call.id, toolName: call.name, output, isError: false };
+                }
+                catch (error) {
+                    const normalizedError = error instanceof Error ? error : new Error(String(error));
+                    if (lifetime.signal.aborted || normalizedError instanceof ToolExecutionTimeoutError) {
+                        throw normalizedError;
+                    }
+                    if (journalClaim) {
+                        try {
+                            if (lifetime.signal.aborted)
+                                throw abortError(lifetime.signal);
+                            await raceWithAbort(Promise.resolve(agent.store.completeToolExecution({
+                                ...journalClaim,
+                                status: "failed",
+                                error: { message: normalizedError.message },
+                                completedAt: Date.now(),
+                                updatedAt: Date.now()
+                            }, { expectedRevision: journalClaim.revision })), lifetime.signal);
+                        }
+                        catch {
+                            // Preserve the original tool error. A running journal entry blocks unsafe replay.
                         }
                     }
-                    continue;
+                    return {
+                        toolCallId: call.id,
+                        toolName: call.name,
+                        error: { message: normalizedError.message },
+                        isError: true
+                    };
                 }
-                if (event.type === "realtime-tool-call") {
-                    await broadcast.publish({
-                        done: false,
-                        value: {
-                            type: "tool-call",
-                            toolCall: event.toolCall
-                        }
-                    });
-                    const definition = resolvedTools[event.toolCall.name];
-                    if (!definition) {
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            error: { message: `Tool "${event.toolCall.name}" is not registered.` },
-                            isError: true
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+            };
+            let waitingForPostToolResponse = false;
+            let postToolResponseObserved = false;
+            let finalOutputTranscriptObserved = false;
+            let terminalResponseCompletionObserved = false;
+            const requiresFinalOutputTranscript = Boolean(realtimeConfig.outputAudioTranscription);
+            const iterator = session.eventStream()[Symbol.asyncIterator]();
+            let iteratorCompleted = false;
+            try {
+                while (true) {
+                    const next = await nextWithAbort(iterator, lifetime.signal);
+                    if (next.done) {
+                        iteratorCompleted = true;
+                        break;
+                    }
+                    const event = next.value;
+                    await publish(event);
+                    if (event.type === "realtime-text-delta") {
+                        assistantBuffer.push(event.textDelta);
+                        if (waitingForPostToolResponse)
+                            postToolResponseObserved = true;
+                        await publish({ type: "text-delta", textDelta: event.textDelta });
                         continue;
                     }
-                    if (!isCallableToolDefinition(definition)) {
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            error: { message: `Tool "${event.toolCall.name}" is provider-hosted and cannot be executed locally.` },
-                            isError: true
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+                    if (event.type === "realtime-transcript") {
+                        if (event.role === "user" && event.isFinal && event.text) {
+                            transcript.push(createTextMessage("user", event.text));
+                        }
+                        if (event.role === "assistant") {
+                            if (event.text && waitingForPostToolResponse)
+                                postToolResponseObserved = true;
+                            if (event.isFinal) {
+                                finalOutputTranscriptObserved = true;
+                                const bufferedTranscript = outputTranscriptBuffer.join("");
+                                finalText = event.text.startsWith(bufferedTranscript)
+                                    ? event.text
+                                    : `${bufferedTranscript}${event.text}`;
+                                if (finalText)
+                                    transcript.push(createTextMessage("assistant", finalText));
+                                assistantBuffer.length = 0;
+                                outputTranscriptBuffer.length = 0;
+                            }
+                            else if (requiresFinalOutputTranscript && event.text) {
+                                outputTranscriptBuffer.push(event.text);
+                            }
+                            if (requiresFinalOutputTranscript &&
+                                terminalResponseCompletionObserved &&
+                                finalOutputTranscriptObserved &&
+                                (!waitingForPostToolResponse || postToolResponseObserved)) {
+                                break;
+                            }
+                        }
                         continue;
                     }
-                    const parsed = definition.schema.safeParse(event.toolCall.input);
-                    if (!parsed.success) {
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            error: { message: `Invalid input for tool "${event.toolCall.name}": ${parsed.error.message}` },
-                            isError: true
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+                    if (event.type === "realtime-tool-call") {
+                        const serializedCallInput = serializeJsonValue(event.toolCall.input);
+                        const fingerprint = `${event.toolCall.name}:${canonicalJson(serializedCallInput)}`;
+                        const previous = processedToolCalls.get(event.toolCall.id);
+                        if (previous) {
+                            if (previous.fingerprint !== fingerprint) {
+                                throw new ConflictError(`Realtime tool call id "${event.toolCall.id}" was reused with a different payload.`);
+                            }
+                            continue;
+                        }
+                        await publish({ type: "tool-call", toolCall: event.toolCall });
+                        waitingForPostToolResponse = true;
+                        postToolResponseObserved = false;
+                        finalOutputTranscriptObserved = false;
+                        terminalResponseCompletionObserved = false;
+                        const definition = resolvedTools[event.toolCall.name];
+                        if (!definition) {
+                            const result = {
+                                toolCallId: event.toolCall.id,
+                                toolName: event.toolCall.name,
+                                error: { message: `Tool "${event.toolCall.name}" is not registered.` },
+                                isError: true
+                            };
+                            await recordToolResult(result, fingerprint);
+                            continue;
+                        }
+                        if (!isCallableToolDefinition(definition)) {
+                            const result = {
+                                toolCallId: event.toolCall.id,
+                                toolName: event.toolCall.name,
+                                error: { message: `Tool "${event.toolCall.name}" is provider-hosted and cannot be executed locally.` },
+                                isError: true
+                            };
+                            await recordToolResult(result, fingerprint);
+                            continue;
+                        }
+                        const parsed = definition.schema.safeParse(event.toolCall.input);
+                        if (!parsed.success) {
+                            const result = {
+                                toolCallId: event.toolCall.id,
+                                toolName: event.toolCall.name,
+                                error: { message: `Invalid input for tool "${event.toolCall.name}": ${parsed.error.message}` },
+                                isError: true
+                            };
+                            await recordToolResult(result, fingerprint);
+                            continue;
+                        }
+                        const approval = await raceWithAbort(resolveApproval({
+                            agent,
+                            input,
+                            state,
+                            call: event.toolCall,
+                            parsedInput: serializeJsonValue(parsed.data),
+                            tool: definition,
+                            realtimeConfig
+                        }), lifetime.signal);
+                        if (approval.approvalRequired) {
+                            throw new ValidationError(`Tool "${event.toolCall.name}" requested resumable approval, but streamLiveAgent only supports immediate approval decisions.`);
+                        }
+                        if (!approval.approved) {
+                            const result = {
+                                toolCallId: event.toolCall.id,
+                                toolName: event.toolCall.name,
+                                error: {
+                                    message: approval.reason ?? `Tool "${event.toolCall.name}" was denied by the approval policy.`
+                                },
+                                isError: true
+                            };
+                            await recordToolResult(result, fingerprint);
+                            continue;
+                        }
+                        const result = await executeTool(definition, event.toolCall, parsed.data, serializeJsonValue(parsed.data));
+                        await recordToolResult(result, fingerprint);
                         continue;
                     }
-                    const approval = await resolveApproval({
-                        agent,
-                        input,
-                        state,
-                        call: event.toolCall,
-                        parsedInput: serializeJsonValue(parsed.data),
-                        tool: definition,
-                        realtimeConfig
-                    });
-                    if (!approval.approved) {
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            error: {
-                                message: approval.reason ?? `Tool "${event.toolCall.name}" was denied by the approval policy.`
-                            },
-                            isError: true
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+                    if (event.type === "realtime-error") {
+                        sessionError = event.error ?? new Error(event.message ?? "Realtime session failed.");
                         continue;
                     }
-                    try {
-                        const output = serializeJsonValue(await withToolTimeout(async (abortSignal) => definition.execute(parsed.data, {
-                            abortSignal,
-                            toolCall: event.toolCall,
-                            step: 1,
-                            model: agent.model,
-                            realtimeConfig
-                        }), (input.toolExecution ?? agent.toolExecution)?.timeoutMs, input.abortSignal));
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            output,
-                            isError: false
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+                    if (event.type === "realtime-end" && event.reason === "error") {
+                        sessionError ??= new Error(typeof event.providerMetadata?.message === "string" ? event.providerMetadata.message : "Realtime session failed.");
                     }
-                    catch (error) {
-                        const result = {
-                            toolCallId: event.toolCall.id,
-                            toolName: event.toolCall.name,
-                            error: { message: error instanceof Error ? error.message : "Tool execution failed." },
-                            isError: true
-                        };
-                        toolResults.push(result);
-                        transcript.push({
-                            role: "tool",
-                            parts: [toolResultPart(result)]
-                        });
-                        await session.sendToolResult(result);
+                    if (event.type === "realtime-response-complete") {
+                        if (event.reason === "generation-complete")
+                            continue;
+                        if (waitingForPostToolResponse && !postToolResponseObserved)
+                            continue;
+                        terminalResponseCompletionObserved = true;
+                        if (requiresFinalOutputTranscript && !finalOutputTranscriptObserved)
+                            continue;
+                        break;
+                    }
+                    if (event.type === "realtime-end") {
+                        break;
                     }
-                    continue;
-                }
-                if (event.type === "realtime-error") {
-                    sessionError = event.error ?? new Error(event.message ?? "Realtime session failed.");
-                    continue;
-                }
-                if (event.type === "realtime-end" && event.reason === "error") {
-                    sessionError ??= new Error(typeof event.providerMetadata?.message === "string" ? event.providerMetadata.message : "Realtime session failed.");
                 }
-                if (event.type === "realtime-response-complete" || event.type === "realtime-end") {
-                    break;
+            }
+            finally {
+                if (!iteratorCompleted && iterator.return) {
+                    const returned = Promise.resolve(iterator.return());
+                    if (lifetime.signal.aborted)
+                        void returned.catch(() => undefined);
+                    else
+                        await raceWithAbort(returned, lifetime.signal);
                 }
             }
             if (sessionError) {
                 throw sessionError;
             }
+            if (waitingForPostToolResponse && !postToolResponseObserved) {
+                throw new ValidationError("Realtime session ended before the response following a tool result was observed.");
+            }
+            if (requiresFinalOutputTranscript &&
+                (!terminalResponseCompletionObserved || !finalOutputTranscriptObserved)) {
+                throw new ValidationError("Realtime session ended before both response completion and final output transcription were observed.");
+            }
+            await closeSession();
             if (assistantBuffer.length && !finalText) {
                 finalText = assistantBuffer.join("");
                 if (finalText) {
                     transcript.push(createTextMessage("assistant", finalText));
                 }
             }
-            state.messages = transcript;
-            state.toolResults = toolResults;
-            state.outputText = finalText;
-            state.status = "completed";
-            state.updatedAt = Date.now();
-            state.error = undefined;
-            const result = createResult(state);
-            const outputGuardrail = await runGuardrails(agent, state, "output", agent.outputGuardrails, () => ({
-                runId: state.runId,
-                agentId: state.agentId,
-                state: cloneState(state),
+            else if (outputTranscriptBuffer.length && !finalText) {
+                finalText = outputTranscriptBuffer.join("");
+                transcript.push(createTextMessage("assistant", finalText));
+            }
+            const completedState = state;
+            completedState.messages = transcript;
+            completedState.toolResults = toolResults;
+            completedState.outputText = finalText;
+            completedState.status = "completed";
+            completedState.updatedAt = Date.now();
+            completedState.error = undefined;
+            const result = createResult(completedState);
+            const outputGuardrail = await runGuardrails(agent, completedState, "output", agent.outputGuardrails, () => ({
+                runId: completedState.runId,
+                agentId: completedState.agentId,
+                state: cloneState(completedState),
                 output: result,
-                metadata: state.metadata
-            }));
-            const finalState = outputGuardrail ? applyGuardrailFailure(state, "output", outputGuardrail) : state;
+                metadata: completedState.metadata
+            }), lifetime.signal);
+            const finalState = outputGuardrail
+                ? applyGuardrailFailure(completedState, "output", outputGuardrail)
+                : completedState;
             if (outputGuardrail) {
-                await broadcast.publish({
-                    done: false,
-                    value: {
-                        type: "error",
-                        error: new GuardrailTriggeredError("output", finalState.error?.message ?? "Agent output guardrail triggered.", {
-                            metadata: outputGuardrail.metadata
-                        })
-                    }
+                await publish({
+                    type: "error",
+                    error: new GuardrailTriggeredError("output", finalState.error?.message ?? "Agent output guardrail triggered.", {
+                        metadata: outputGuardrail.metadata
+                    })
                 });
             }
-            await persistState(agent, finalState);
-            await emitRunFinishTelemetry(agent, finalState);
-            await broadcast.publish({
-                done: false,
-                value: {
-                    type: "agent-run-finish",
-                    status: finalState.status,
-                    state: finalState
-                }
-            });
-            await broadcast.publish({ done: true, value: undefined });
+            await persistState(agent, finalState, lifetime.signal);
+            await emitRunFinishTelemetry(agent, finalState, lifetime.signal);
+            await publish({ type: "agent-run-finish", status: finalState.status, state: cloneState(finalState) });
             return createResult(finalState);
         }
         catch (error) {
-            if (!session) {
-                rejectSession(error);
+            runError = error;
+            failureCleanupRan = true;
+            rejectNoSession(error);
+            const normalizedError = error instanceof Error ? error : new Error(String(error));
+            if (state) {
+                state.messages = transcript.length ? transcript : state.messages;
+                state.toolResults = toolResults;
+                const status = lifetime.signal.aborted
+                    ? lifetime.signal.reason instanceof LiveAgentTimeoutError
+                        ? "timed_out"
+                        : "cancelled"
+                    : "failed";
+                state = {
+                    ...state,
+                    status,
+                    error: { message: normalizedError.message },
+                    ...(status === "cancelled"
+                        ? { cancelledAt: Date.now(), cancellationReason: normalizedError.message }
+                        : {}),
+                    updatedAt: Date.now()
+                };
+                await runTerminalFailureCleanup([
+                    (cleanupSignal) => persistState(agent, state, cleanupSignal),
+                    (cleanupSignal) => emitRunFinishTelemetry(agent, state, cleanupSignal),
+                    () => closeSession()
+                ]);
+                try {
+                    await publish({ type: "error", error: normalizedError });
+                    await publish({ type: "agent-run-finish", status: state.status, state: cloneState(state) });
+                }
+                catch {
+                    // The original failure remains authoritative if the event broadcast also failed.
+                }
             }
-            const failedState = createFailedState(state, error instanceof Error ? error.message : String(error));
-            await persistState(agent, failedState);
-            await emitRunFinishTelemetry(agent, failedState);
-            await broadcast.publish({
-                done: false,
-                value: {
-                    type: "error",
-                    error: error instanceof Error ? error : new Error(String(error))
+            else {
+                await runTerminalFailureCleanup([() => closeSession()]);
+                try {
+                    await publish({ type: "error", error: normalizedError });
                 }
-            });
-            await broadcast.publish({
-                done: false,
-                value: {
-                    type: "agent-run-finish",
-                    status: failedState.status,
-                    state: failedState
+                catch {
+                    // The original failure remains authoritative if the event broadcast also failed.
                 }
-            });
-            await broadcast.publish({ done: true, value: undefined });
+            }
             throw error;
         }
         finally {
-            if (session) {
-                await session.close();
+            lifetime.signal.removeEventListener("abort", abortSession);
+            lifetime.cleanup();
+            if (!failureCleanupRan) {
+                try {
+                    await closeSession();
+                }
+                catch (closeError) {
+                    if (!runError)
+                        runError = closeError;
+                }
+            }
+            if (!sessionSettled) {
+                rejectNoSession(runError ?? new ValidationError(`Live agent run "${runId}" ended without a realtime session.`));
             }
+            broadcast.close();
         }
     })();
+    void runner.catch(() => undefined);
     return {
         eventStream: broadcast.stream(),
         textStream: (async function* () {
-            for await (const event of broadcast.stream()) {
-                if (event.type === "text-delta") {
+            for await (const event of broadcast.stream((candidate) => candidate.type === "text-delta")) {
+                if (event.type === "text-delta")
                     yield event.textDelta;
-                }
             }
         })(),
         session: sessionPromise,