@db3.ai/app 0.1.0-beta.1

package/dist/ai/Agent.js

@@ -0,0 +1,2976 @@
+import { aiExecutionContext } from './AiExecutionContext.js';
+import { Agent as SdkAgent, Runner, generateTraceId } from '@openai/agents';
+import { isQueueRetryLaterError } from '@db3.ai/app/queue';
+import { agentMarkdownWithCitations, normalizedAgentCitations } from '@db3.ai/pure';
+import { app } from '../server/appContext.js';
+import { AI_MESSAGE_ROLE, AI_MESSAGE_TOOL_STATE } from './AiMessage.js';
+import { AI_REQUEST_STATUS } from './AiRequest.js';
+import { AI_PROVIDER, AIQuotaDeferredError, AIRateLimitDeferredError, isFailoverableFailure, openAIProviderError, responsesRateLimitEndpoint, simulatedProviderOutage } from './index.js';
+import { AIAllowanceExceededError } from './AIErrors.js';
+import { estimateTokensFromText } from './Estimates.js';
+import { calculateAIHostedToolCost, calculateAIRequestCostUSD, calculateAIRequestEntriesCostUSD, combineAIRequestCostUSD } from './Models.js';
+import { AgentRunJob } from './AgentRunJob.js';
+import { openAIQuotaRetryDecision, withOpenAIQuotaRetryMetadata, withoutOpenAIQuotaRetryMetadata } from './OpenAIQuotaRetry.js';
+import { agentCitationFromStreamRecord, agentCitationsFromFinalModelResponse, rememberAgentCitation } from './agentCitations.js';
+import { serializeQueuedAgent } from './registry.js';
+import { agentToolResultFromStructuredOutput } from './toolHelpers.js';
+import { INTERRUPTED_TOOL_CALL_MESSAGE, unresolvedToolCallIds } from './toolCallRecovery.js';
+/**
+ * Shared persisted Agents SDK runtime for interactive and queued application agents.
+ */
+export class Agent {
+    context;
+    maxTurns = 8;
+    maxPreviousMessages = 50;
+    /** Provider reasoning effort used for every run of this agent. */
+    reasoningEffort = null;
+    agentName = this.constructor.name;
+    sdkAgentName = this.constructor.name;
+    workflowName = this.constructor.name;
+    /** Optional agent-specific model. Omit to use the global `app().ai.model`. */
+    model;
+    currentInput = null;
+    /**
+     * Creates a persisted agent runtime for the supplied app context.
+     *
+     * @param context - Trusted user, application scope, and optional conversation context.
+     */
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Returns the complete constructor context for durable agent reconstruction.
+     *
+     * ActiveRecord values are reduced to registered model references by the
+     * framework serializer. Mutable fluent input remains explicit run payload
+     * data and is intentionally not part of constructor state.
+     *
+     * @returns Complete context accepted by this agent's constructor.
+     */
+    toJSON() {
+        return this.context;
+    }
+    /**
+     * Sets the user or task input for the next stream or queued run.
+     *
+     * @param message - User or system task input for the agent.
+     * @returns This agent instance for fluent calls.
+     */
+    input(message) {
+        this.currentInput = { message };
+        return this;
+    }
+    async stream(messageOrEmit, emit) {
+        const streamInput = this.resolveStreamInput(messageOrEmit, emit);
+        let state = null;
+        const traceId = generateTraceId();
+        try {
+            const prepared = await this.prepareRun(streamInput.message, 'ndjson', traceId);
+            state = prepared.state;
+            await streamInput.emit({
+                type: 'conversation.created',
+                conversationId: String(state.conversation.id),
+                aiRequestId: state.aiRequest.id ? String(state.aiRequest.id) : null,
+                traceId,
+                toolDefinitions: state.toolDefinitions,
+            });
+            await streamInput.emit({
+                type: 'message.created',
+                id: String(state.metadata.userMessageId),
+                role: 'user',
+                content: streamInput.message,
+                createdAt: state.metadata.userMessageCreatedAt,
+            });
+            const result = await this.executePreparedRun(prepared, streamInput.emit);
+            await streamInput.emit({
+                type: 'run.completed',
+                conversationId: result.conversationId,
+                aiRequestId: result.aiRequestId,
+                traceId,
+                usage: result.usage,
+                creditCost: result.creditCost,
+                ...(this.exposeProviderCosts() ? { costUSD: result.costUSD } : {}),
+                finalOutput: result.finalOutput,
+            });
+            return result;
+        }
+        catch (error) {
+            const payload = agentErrorPayload(error, `Unable to run ${this.agentName}.`);
+            if (state) {
+                await this.failTrackedRun(state, payload.message);
+            }
+            await streamInput.emit({
+                type: 'run.error',
+                conversationId: state?.conversation.id ? String(state.conversation.id) : null,
+                aiRequestId: state?.aiRequest.id ? String(state.aiRequest.id) : null,
+                traceId,
+                error: payload,
+            });
+            return null;
+        }
+    }
+    /** Runs this agent to completion, preserving the same history and tool lifecycle as stream(). */
+    async run(message) {
+        let failure = null;
+        const result = await this.stream(message, event => { if (event.type === 'run.error')
+            failure = event.error.message; });
+        if (!result)
+            throw new Error(failure ?? 'Agent run failed.');
+        return result;
+    }
+    /** Generates and optionally stores an image under the active agent attempt. */
+    generateImage(input, options = {}) {
+        return app().ai.generateImage(input, { user: this.userId(), [app().ai.scopeField]: this.scopeId(), ...options });
+    }
+    /** Generates an embedding under the active agent attempt. */
+    generateEmbedding(input, model, options = {}) {
+        return app().ai.generateEmbedding(input, model, { user: this.userId(), [app().ai.scopeField]: this.scopeId(), ...options });
+    }
+    /** Generates schema-validated output under the active agent attempt. */
+    generateStructured(input, options = {}) {
+        return app().ai.generateStructured(input, { user: this.userId(), [app().ai.scopeField]: this.scopeId(), ...options });
+    }
+    async queue(messageOrOptions = {}, options = {}) {
+        const queueInput = this.resolveQueueInput(messageOrOptions, options);
+        const traceId = generateTraceId();
+        const serializedAgent = await this.serializeForQueue();
+        const prepared = await this.prepareRun(queueInput.message, 'queue', traceId);
+        const payload = this.queuedRunPayload(prepared, serializedAgent);
+        try {
+            const jobId = await app().queue.dispatch(new AgentRunJob(payload), queueInput.options);
+            await this.markQueued(prepared.state, jobId);
+            return {
+                jobId,
+                conversationId: String(prepared.state.conversation.id),
+                aiRequestId: prepared.state.aiRequest.id ? String(prepared.state.aiRequest.id) : null,
+                traceId,
+            };
+        }
+        catch (error) {
+            await this.failTrackedRun(prepared.state, error instanceof Error ? error.message : 'Unable to queue agent run.');
+            throw error;
+        }
+    }
+    /** Serializes a registered agent before queue preparation creates audit records. */
+    async serializeForQueue() {
+        return serializeQueuedAgent(this.agentName, this);
+    }
+    /**
+     * Resolves the current stream input from the fluent input state or shortcut argument.
+     *
+     * @param messageOrEmit - Optional message shortcut or stream event sink.
+     * @param emit - Optional stream event sink when a message shortcut is supplied.
+     * @returns Resolved message and event sink for this stream run.
+     */
+    resolveStreamInput(messageOrEmit, emit) {
+        if (typeof messageOrEmit === 'string') {
+            this.input(messageOrEmit);
+            return {
+                message: this.resolvedInputMessage(),
+                emit: emit ?? noopAgentEventSink,
+            };
+        }
+        return {
+            message: this.resolvedInputMessage(),
+            emit: messageOrEmit ?? noopAgentEventSink,
+        };
+    }
+    /**
+     * Resolves the current queue input from the fluent input state or shortcut argument.
+     *
+     * @param messageOrOptions - Optional message shortcut or dispatch options.
+     * @param options - Optional dispatch options when a message shortcut is supplied.
+     * @returns Resolved message and dispatch options for this queued run.
+     */
+    resolveQueueInput(messageOrOptions, options) {
+        if (typeof messageOrOptions === 'string') {
+            this.input(messageOrOptions);
+            return {
+                message: this.resolvedInputMessage(),
+                options,
+            };
+        }
+        return {
+            message: this.resolvedInputMessage(),
+            options: messageOrOptions,
+        };
+    }
+    /**
+     * Returns the currently configured input message or throws before work starts.
+     *
+     * @returns Current run input message.
+     */
+    resolvedInputMessage() {
+        if (this.currentInput === null) {
+            throw new Error(`${this.agentName} requires input before it can run.`);
+        }
+        return this.currentInput.message;
+    }
+    /**
+     * Resumes a prepared queued run from a worker process.
+     *
+     * @param payload - Queued agent run payload.
+     * @returns Completed run metadata and final output.
+     */
+    async runQueued(payload) {
+        if (payload.agentName !== this.agentName) {
+            throw new Error(`Queued payload for "${payload.agentName}" cannot run on "${this.agentName}".`);
+        }
+        const prepared = await this.preparedRunFromQueuedPayload(payload);
+        try {
+            if (recordValue(prepared.state.rootAiRequest.response)?.providerFinalized === true) {
+                return await this.resumeFinalizedTrackedRun(prepared);
+            }
+            return await this.executePreparedRun(prepared, async () => { });
+        }
+        catch (error) {
+            if (isQueueRetryLaterError(error))
+                throw error;
+            const quotaRetry = openAIQuotaRetryDecision(error, prepared.state.aiRequest);
+            if (quotaRetry && !quotaRetry.expired) {
+                await this.deferTrackedRun(prepared.state, quotaRetry);
+                throw new AIQuotaDeferredError(quotaRetry.delaySeconds, quotaRetry.retryAt, quotaRetry.retryUntil, quotaRetry.deferralCount, quotaRetry.message);
+            }
+            const providerError = openAIProviderError(error);
+            if (quotaRetry) {
+                prepared.state.aiRequest.metadata = withOpenAIQuotaRetryMetadata(prepared.state.aiRequest.metadata, quotaRetry.metadata);
+            }
+            await this.failTrackedRun(prepared.state, error instanceof Error ? error.message : `Unable to run ${this.agentName}.`, providerError.code);
+            throw error;
+        }
+    }
+    /**
+     * Resumes only settlement for a queued run whose provider output is durable.
+     *
+     * This closes the credit-settlement/root-save retry window without replaying
+     * model turns, hosted tools, images, or embeddings that already completed.
+     *
+     * @param prepared - Restored queued root with a provider-finalized response.
+     * @returns Completed run result rebuilt from the persisted root response.
+     */
+    async resumeFinalizedTrackedRun(prepared) {
+        const billing = await this.settleFinalizedTrackedRun(prepared.state);
+        const response = recordValue(prepared.state.rootAiRequest.response);
+        return {
+            conversationId: String(prepared.state.conversation.id),
+            aiRequestId: prepared.state.rootAiRequest.id ? String(prepared.state.rootAiRequest.id) : null,
+            traceId: prepared.traceId,
+            usage: billing.usage,
+            creditCost: billing.creditCost,
+            costUSD: billing.costUSD,
+            finalOutput: stringValue(response?.finalOutput) ?? '',
+        };
+    }
+    /**
+     * Returns the reasoning summary mode for this agent, or null to keep it off.
+     *
+     * @returns Reasoning summary mode requested from the provider.
+     */
+    reasoningSummaryMode() {
+        return null;
+    }
+    /**
+     * Returns a structured output schema for the SDK agent, or null for text output.
+     *
+     * @returns Agent output type used to parse final model output.
+     */
+    outputType() {
+        return null;
+    }
+    /**
+     * Converts the SDK final output into the assistant message text stored by application.
+     *
+     * @param finalOutput - Final output returned by the Agents SDK.
+     * @param streamedText - Text accumulated from output deltas while streaming.
+     * @returns Assistant message content to persist and emit.
+     */
+    finalOutputText(finalOutput, streamedText) {
+        return defaultAgentFinalOutputText(finalOutput, streamedText);
+    }
+    /**
+     * Performs app-owned side effects after the model has produced a final output.
+     *
+     * @param _state - Active persistence state for the completed run.
+     * @param _finalOutput - Final output returned by the Agents SDK.
+     * @returns Optional metadata to store on the tracked AI response.
+     */
+    async afterFinalOutput(_state, _finalOutput) {
+        return null;
+    }
+    /**
+     * Returns structured final output to store on the tracked AI response.
+     *
+     * @param finalOutput - Final output returned by the Agents SDK.
+     * @returns Structured output for audit storage, or undefined for plain text.
+     */
+    structuredFinalOutput(finalOutput) {
+        return typeof finalOutput === 'object' && finalOutput !== null ? finalOutput : undefined;
+    }
+    /**
+     * Builds the complete provider input for a run.
+     *
+     * @param context - Current message and previous provider-shaped input items.
+     * @returns Provider-compatible input items for this run.
+     */
+    async buildInput(context) {
+        return [
+            ...context.previousMessages,
+            this.userMessage(context.message),
+        ];
+    }
+    /**
+     * Builds a provider-compatible user message.
+     *
+     * @param content - Message text to send as user input.
+     * @returns Agents SDK user message item.
+     */
+    userMessage(content) {
+        return userInputMessage(content);
+    }
+    /**
+     * Builds a provider-compatible system message.
+     *
+     * @param content - System context or instruction text.
+     * @returns Agents SDK system message item.
+     */
+    systemMessage(content) {
+        return systemInputMessage(content);
+    }
+    /**
+     * Builds a provider-compatible assistant message.
+     *
+     * @param content - Assistant text from an earlier turn.
+     * @returns Agents SDK assistant message item.
+     */
+    assistantMessage(content) {
+        return assistantInputMessage(content);
+    }
+    /**
+     * Returns lightweight queue metadata used without reconstructing the agent.
+     *
+     * Subclasses should expose only identifiers needed by lifecycle projections.
+     * Constructor state belongs in `toJSON()` and is not duplicated here.
+     *
+     * @returns Application-owned queue lifecycle metadata.
+     */
+    queueMetadata() {
+        return {};
+    }
+    /**
+     * Builds the trace metadata for an SDK runner invocation.
+     *
+     * @param conversation - Conversation attached to the run.
+     * @returns Trace metadata sent to the Agents SDK.
+     */
+    traceMetadata(conversation) {
+        return {
+            app: 'db3',
+            agent: this.agentName,
+            scopeId: this.scopeId(),
+            [`${app().ai.scopeField}Id`]: this.scopeId(),
+            conversationId: String(conversation.id),
+        };
+    }
+    /**
+     * Returns additional server-owned values to expose to local tools.
+     *
+     * Subclasses can add task identifiers here when a queued run needs to keep
+     * model-visible tool arguments separate from application-owned boundaries.
+     *
+     * @param _state - Active persistence state, or undefined for a no-run preview.
+     * @returns Additional tool context values.
+     */
+    toolRunContext(_state) {
+        return {};
+    }
+    /**
+     * Returns application-owned metadata that scopes a conversation.
+     *
+     * Values are persisted when a conversation is created and compared again
+     * before later turns are appended, preventing one workflow context from
+     * accidentally continuing inside another.
+     *
+     * @returns Stable conversation-scope metadata for this agent instance.
+     */
+    conversationMetadata() {
+        return {};
+    }
+    /**
+     * Returns persisted agent identities permitted to continue this conversation.
+     *
+     * Concrete agents normally accept only their own stable identity. A narrowly
+     * scoped replacement agent may override this hook to continue conversations
+     * created by the exact predecessor it supersedes.
+     *
+     * @returns Persisted agent names accepted by conversation authorization.
+     */
+    conversationAgentNames() {
+        return [this.agentName];
+    }
+    /**
+     * Builds the title for a newly created conversation.
+     *
+     * @param message - Initial message for the run.
+     * @returns Compact conversation title.
+     */
+    conversationTitle(message) {
+        const title = message.replace(/\s+/g, ' ').trim();
+        if (title.length <= 72)
+            return title || `${this.sdkAgentName} conversation`;
+        return `${title.slice(0, 69).trim()}...`;
+    }
+    /**
+     * Resolves the model used by this agent run.
+     *
+     * @returns Agent-specific model or the global application model.
+     */
+    resolvedModel() {
+        return this.model ?? app().ai.model;
+    }
+    /**
+     * Returns the application credit charge reserved before this agent turn.
+     *
+     * The shared runtime remains unmetered by default because concrete agents
+     * own the product bucket and minimum debit that permits work to begin.
+     * Provider retries reuse the same tracked request id, so allowance adapters
+     * can make repeated checks idempotent.
+     *
+     * @returns Concrete agent charge, or null when funded by another workflow.
+     */
+    usageCharge() {
+        return null;
+    }
+    /**
+     * Returns the billable charge for this invocation.
+     *
+     * Nested agents belong to the outer request tree and therefore cannot
+     * reserve or settle credits independently.
+     *
+     * @returns Top-level product charge, or null for nested and unmetered runs.
+     */
+    billableUsageCharge() {
+        return this.context.parentAiRequestId ? null : this.usageCharge();
+    }
+    /**
+     * Returns the model settings shared by live execution and dry-run previews.
+     *
+     * @returns Agents SDK model settings for this agent.
+     */
+    modelSettings() {
+        const reasoningSummaryMode = this.reasoningSummaryMode();
+        return {
+            parallelToolCalls: false,
+            toolChoice: 'auto',
+            ...(this.reasoningEffort || reasoningSummaryMode ? {
+                reasoning: {
+                    ...(this.reasoningEffort ? { effort: this.reasoningEffort } : {}),
+                    ...(reasoningSummaryMode ? { summary: reasoningSummaryMode } : {}),
+                },
+            } : {}),
+        };
+    }
+    /**
+     * Returns the exact first-turn OpenAI Responses request body without calling
+     * OpenAI or creating persistence state.
+     *
+     * The preview enters the same Agents SDK request-preparation path used by a
+     * live run. A request-capturing model stops execution at the provider boundary
+     * before any network transport or tool callback can run.
+     *
+     * @returns JSON request body that would be sent to `responses.create`.
+     *
+     * @example
+     * const request = await agent
+     * 	.input('Complete this task.')
+     * 	.previewRequest();
+     */
+    async previewRequest() {
+        const model = this.resolvedModel();
+        const invocation = await this.prepareAgentInvocation(this.resolvedInputMessage(), []);
+        return openAIResponseRequestBody({
+            agent: this.sdkAgent(invocation, model),
+            context: this.requestPreviewContext(),
+            input: invocation.input,
+            maxTurns: this.maxTurns,
+            model,
+            modelSettings: invocation.modelSettings,
+        });
+    }
+    /**
+     * Builds the application-owned values used for one SDK model invocation.
+     *
+     * @param message - Current user or task message.
+     * @param previousMessages - Prior provider-compatible conversation input.
+     * @returns Prepared values shared by live execution and request previews.
+     */
+    async prepareAgentInvocation(message, previousMessages) {
+        const tools = this.tools();
+        return {
+            instructions: await this.instructions(),
+            input: await this.buildInput({
+                message,
+                previousMessages,
+            }),
+            modelSettings: this.modelSettings(),
+            outputType: this.outputType(),
+            tools,
+            toolDefinitions: agentToolDefinitions(tools),
+        };
+    }
+    /**
+     * Creates the SDK Agent from one shared prepared invocation.
+     *
+     * @param invocation - Application-owned request values.
+     * @param model - Provider model selected for this attempt.
+     * @returns Configured Agents SDK Agent.
+     */
+    sdkAgent(invocation, model) {
+        return new SdkAgent({
+            name: this.sdkAgentName,
+            instructions: invocation.instructions,
+            model,
+            tools: invocation.tools,
+            ...(invocation.outputType ? { outputType: invocation.outputType } : {}),
+        });
+    }
+    /**
+     * Builds non-persisted SDK context for first-request preparation.
+     *
+     * These runtime-only values are not included in the OpenAI request. They let
+     * the Runner evaluate the same configured tools and dynamic SDK capabilities
+     * without creating a conversation or AI request.
+     *
+     * @returns Tool context used only while the SDK prepares the preview request.
+     */
+    requestPreviewContext() {
+        return {
+            ...this.toolRunContext(),
+            userId: this.userId(),
+            scopeId: this.scopeId(),
+            [`${app().ai.scopeField}Id`]: this.scopeId(),
+            conversationId: this.context.conversationId || 'request-preview',
+            aiRequestId: null,
+            rootAiRequestId: null,
+            traceId: 'request-preview',
+            emitToolProgress: noopAgentEventSink,
+        };
+    }
+    /**
+     * Returns the provider failover selection for this agent's runs.
+     *
+     * Return an ordered provider list to fail over using each provider's default
+     * model, or an ordered provider-to-model record to pin a comparable model per
+     * provider. The agent's reasoning settings apply to every attempt. Null uses
+     * the app default chain, which is OpenAI-only unless configured otherwise.
+     *
+     * @example
+     * protected override provider(): AIProviderSelection {
+     * 	return {
+     * 		[AI_PROVIDER.openai]: this.resolvedModel(),
+     * 		[AI_PROVIDER.openrouter]: 'comparable-model',
+     * 	};
+     * }
+     *
+     * @returns Provider selection for this agent, or null for the app default.
+     */
+    provider() {
+        return null;
+    }
+    /**
+     * Resolves a new or existing conversation and verifies it belongs to this context.
+     *
+     * @param message - Current run message.
+     * @param traceId - Trace id generated for this run.
+     * @param transport - Transport that started the run.
+     * @returns Conversation for the run.
+     */
+    async resolveConversation(message, traceId, transport) {
+        if (this.context.conversationId) {
+            const conversation = await app().ai.models.conversation.findOrFail(this.context.conversationId);
+            this.assertConversationAccess(conversation);
+            return conversation;
+        }
+        return await new (app().ai.models.conversation)({
+            user: this.userId() || null,
+            [app().ai.scopeField]: this.scopeId(),
+            agent: this.agentName,
+            title: this.conversationTitle(message),
+            metadata: {
+                traceId,
+                transport,
+                ...this.conversationMetadata(),
+            },
+        }).save();
+    }
+    /**
+     * Throws when a requested conversation is not owned by this agent context.
+     *
+     * @param conversation - Existing conversation requested by the caller.
+     */
+    assertConversationAccess(conversation) {
+        const conversationUserId = entityRefId(conversation.user);
+        const conversationScopeId = entityRefId(conversation[app().ai.scopeField]);
+        if ((conversationUserId ?? '') !== this.userId()) {
+            throw new AgentAuthorizationError('Permission denied.');
+        }
+        if ((conversationScopeId ?? '') !== this.scopeId()) {
+            throw new AgentAuthorizationError('Permission denied.');
+        }
+        if (conversation.agent && !this.conversationAgentNames().includes(conversation.agent)) {
+            throw new AgentAuthorizationError('Permission denied.');
+        }
+        for (const [key, expectedValue] of Object.entries(this.conversationMetadata())) {
+            const metadata = conversation.metadata ?? {};
+            if (!Object.prototype.hasOwnProperty.call(metadata, key))
+                continue;
+            const actualValue = metadata[key] ?? null;
+            if (actualValue !== expectedValue) {
+                throw new AgentAuthorizationError('Permission denied.');
+            }
+        }
+    }
+    /**
+     * Prepares conversation, request, and input messages before an SDK run starts.
+     *
+     * @param message - Current run message.
+     * @param transport - Transport that started the run.
+     * @param traceId - Trace id for the run.
+     * @returns Prepared run state ready for stream or queue execution.
+     */
+    async prepareRun(message, transport, traceId) {
+        const model = this.resolvedModel();
+        const conversation = await this.resolveConversation(message, traceId, transport);
+        const previousMessages = await this.previousMessages(conversation);
+        const invocation = await this.prepareAgentInvocation(message, previousMessages);
+        const state = await this.startTrackedRun({
+            conversation,
+            invocation,
+            message,
+            model,
+            traceId,
+            transport,
+        });
+        const userMessage = await this.saveMessage(state, {
+            role: AI_MESSAGE_ROLE.user,
+            content: message,
+            contentJson: null,
+            metadata: {
+                eventType: 'user_message',
+                traceId,
+            },
+        });
+        state.metadata.userMessageId = String(userMessage.id);
+        state.metadata.userMessageCreatedAt = dateString(userMessage.createdAt);
+        return {
+            message,
+            model,
+            traceId,
+            previousMessages,
+            invocation,
+            state,
+        };
+    }
+    /**
+     * Loads a prepared run from a queued payload.
+     *
+     * @param payload - Queued run payload.
+     * @returns Prepared run state for worker execution.
+     */
+    async preparedRunFromQueuedPayload(payload) {
+        if (!payload.aiRequestId) {
+            throw new Error('Queued agent run is missing an AI request id.');
+        }
+        const conversation = await app().ai.models.conversation.findOrFail(payload.conversationId);
+        const aiRequest = await app().ai.models.request.findOrFail(payload.aiRequestId);
+        this.assertConversationAccess(conversation);
+        const previousMessages = await this.previousMessages(conversation, aiRequest.id ? String(aiRequest.id) : null);
+        const invocation = await this.prepareAgentInvocation(payload.message, previousMessages);
+        return {
+            message: payload.message,
+            model: payload.model,
+            traceId: payload.traceId,
+            previousMessages,
+            invocation,
+            state: {
+                conversation,
+                rootAiRequest: aiRequest,
+                aiRequest,
+                nextSequence: await nextMessageSequence(conversation),
+                model: payload.model,
+                traceId: payload.traceId,
+                startTimeMs: Date.now(),
+                metadata: {},
+                toolDefinitions: invocation.toolDefinitions,
+                hostedToolUsage: {},
+                hostedToolCallIds: new Set(),
+                citations: [],
+                toolArgumentsByCallId: {},
+            },
+        };
+    }
+    /**
+     * Executes a prepared SDK run and persists assistant output, tools, and usage.
+     *
+     * @param prepared - Prepared run state.
+     * @param emit - Stream event sink, or a no-op for queued runs.
+     * @returns Completed run metadata.
+     */
+    async executePreparedRun(prepared, emit) {
+        const { state } = prepared;
+        const invocation = prepared.invocation;
+        const instructions = invocation.instructions;
+        const modelInput = invocation.input;
+        const attempts = app().ai.resolveProviders(this.provider(), prepared.model);
+        const attemptFailures = [];
+        await this.attachPromptRequestPayload(state, {
+            instructions,
+            input: modelInput,
+            message: prepared.message,
+            previousMessages: prepared.previousMessages,
+        });
+        await emit(this.promptContextEvent(state, {
+            instructions,
+            input: modelInput,
+            model: prepared.model,
+        }));
+        for (let index = 0; index < attempts.length; index++) {
+            const attempt = attempts[index];
+            const hasFallback = index < attempts.length - 1;
+            const attemptStartMs = Date.now();
+            let rateLimitLease = null;
+            let sawStreamEvent = false;
+            let activeUsage = null;
+            let attemptState = null;
+            let attemptSettled = false;
+            let providerStarted = false;
+            try {
+                attemptState = await this.startTrackedAttempt(state, attempt, attemptStartMs);
+                rateLimitLease = await this.acquireProviderCapacity(prepared, instructions, modelInput, attempt, attemptState);
+                const simulatedOutage = simulatedProviderOutage(attempt.provider);
+                if (simulatedOutage)
+                    throw simulatedOutage;
+                const executionState = attemptState;
+                return await aiExecutionContext.run(executionState, async () => {
+                    providerStarted = true;
+                    const runner = new Runner({
+                        model: attempt.model,
+                        modelProvider: app().ai.createAgentProvider(attempt, rateLimitLease),
+                        modelSettings: modelSettingsForProvider(invocation.modelSettings, attempt.provider),
+                        tracingDisabled: process.env.OPENAI_AGENTS_TRACING_DISABLED === 'true',
+                        traceIncludeSensitiveData: false,
+                        workflowName: this.workflowName,
+                        traceId: prepared.traceId,
+                        groupId: String(state.conversation.id),
+                        traceMetadata: this.traceMetadata(state.conversation),
+                    });
+                    const sdkAgent = this.sdkAgent(invocation, attempt.model);
+                    const sdkContext = this.sdkContext(executionState, emit);
+                    const stream = await runner.run(sdkAgent, modelInput, {
+                        stream: true,
+                        context: sdkContext,
+                        maxTurns: this.maxTurns,
+                        reasoningItemIdPolicy: 'preserve',
+                    });
+                    activeUsage = stream.runContext.usage;
+                    let assistantText = '';
+                    for await (const event of stream) {
+                        sawStreamEvent = true;
+                        const streamEvent = await this.streamEventFromSdkEvent(executionState, event);
+                        if (!streamEvent)
+                            continue;
+                        if (streamEvent.type === 'text.delta') {
+                            assistantText += streamEvent.delta;
+                        }
+                        await emit(streamEvent);
+                    }
+                    await stream.completed;
+                    const rawFinalOutput = this.finalOutputText(stream.finalOutput, assistantText);
+                    const finalResponseCitations = agentCitationsFromFinalModelResponse(stream.rawResponses);
+                    const citations = finalResponseCitations ?? normalizedAgentCitations(executionState.citations);
+                    for (const citation of citations) {
+                        if (!rememberAgentCitation(executionState.citations, citation))
+                            continue;
+                        await emit({
+                            type: 'citation.added',
+                            citation,
+                        });
+                    }
+                    await this.completeTrackedAttempt(executionState, activeUsage, stream.lastResponseId ?? null);
+                    attemptSettled = true;
+                    const structuredOutput = this.structuredFinalOutput(stream.finalOutput);
+                    const finalOutput = agentMarkdownWithCitations(rawFinalOutput, citations);
+                    const outputMetadata = await this.afterFinalOutput(state, stream.finalOutput);
+                    const assistantMessage = await this.saveMessage(executionState, {
+                        role: AI_MESSAGE_ROLE.assistant,
+                        content: finalOutput,
+                        contentJson: {
+                            type: 'assistant_text',
+                            citations,
+                        },
+                        metadata: {
+                            eventType: 'assistant_message',
+                            traceId: prepared.traceId,
+                            lastResponseId: stream.lastResponseId ?? null,
+                        },
+                    });
+                    const billing = await this.completeTrackedRun(state, {
+                        finalOutput,
+                        citations,
+                        lastResponseId: stream.lastResponseId ?? null,
+                        successfulAttemptAiRequestId: executionState.aiRequest.id ? String(executionState.aiRequest.id) : null,
+                        structuredOutput,
+                        outputMetadata,
+                    });
+                    await emit({
+                        type: 'message.completed',
+                        id: String(assistantMessage.id),
+                        role: 'assistant',
+                        content: finalOutput,
+                        citations,
+                        createdAt: dateString(assistantMessage.createdAt),
+                    });
+                    return {
+                        conversationId: String(state.conversation.id),
+                        aiRequestId: state.aiRequest.id ? String(state.aiRequest.id) : null,
+                        traceId: prepared.traceId,
+                        usage: billing.usage,
+                        creditCost: billing.creditCost,
+                        costUSD: billing.costUSD,
+                        finalOutput,
+                    };
+                });
+            }
+            catch (caught) {
+                const error = agentRateLimitError(caught);
+                if (attemptState && !attemptSettled) {
+                    await this.failTrackedAttempt(attemptState, activeUsage, providerStarted, error);
+                }
+                // Failover is only safe before the SDK has streamed anything: once
+                // events arrive, tool calls and partial output may already be
+                // persisted or visible, and replaying them would duplicate work.
+                if (hasFallback && !sawStreamEvent && isFailoverableFailure(error)) {
+                    const details = openAIProviderError(error);
+                    attemptFailures.push({
+                        provider: attempt.provider,
+                        model: attempt.model,
+                        status: details.status,
+                        code: details.code,
+                        message: details.message,
+                        durationMs: Date.now() - attemptStartMs,
+                    });
+                    await this.recordProviderAttempts(state, attemptFailures);
+                    continue;
+                }
+                throw error;
+            }
+            finally {
+                await app().ai.releaseRateLimit(rateLimitLease);
+            }
+        }
+        // Unreachable: the final attempt always returns or throws above.
+        throw new Error(`Unable to run ${this.agentName}: no provider attempt completed.`);
+    }
+    /**
+     * Creates the append-only request row for one SDK provider execution attempt.
+     *
+     * The logical root is reused by queue retries, while every provider attempt has
+     * its own immutable cost boundary. Tool children use this attempt as their
+     * parent so replayed or concurrent work cannot overwrite earlier spend.
+     *
+     * @param rootState - Logical run root and shared conversation state.
+     * @param attempt - Provider and model selected for this execution.
+     * @param startedAtMs - Attempt start timestamp in milliseconds.
+     * @returns Persistence state scoped to the new provider attempt.
+     */
+    async startTrackedAttempt(rootState, attempt, startedAtMs) {
+        const aiRequest = await new (app().ai.models.request)({
+            conversation: rootState.conversation,
+            parentAiRequest: rootState.rootAiRequest,
+            user: rootState.rootAiRequest.user,
+            [app().ai.scopeField]: rootState.rootAiRequest[app().ai.scopeField],
+            provider: attempt.provider,
+            model: attempt.model,
+            operation: 'agents.run.attempt',
+            status: AI_REQUEST_STATUS.pending,
+            request: {
+                rootAiRequestId: rootState.rootAiRequest.id,
+                traceId: rootState.traceId,
+            },
+            startedAt: new Date(startedAtMs),
+            metadata: {
+                agent: this.agentName,
+                traceId: rootState.traceId,
+                outcome: 'provider_attempt',
+            },
+        }).save();
+        return {
+            ...rootState,
+            aiRequest,
+            nextSequence: await nextMessageSequence(rootState.conversation),
+            model: attempt.model,
+            startTimeMs: startedAtMs,
+            metadata: { ...rootState.metadata },
+            hostedToolUsage: {},
+            hostedToolCallIds: new Set(),
+            citations: [],
+            toolArgumentsByCallId: {},
+        };
+    }
+    /**
+     * Finalizes one successful provider attempt before application side effects run.
+     *
+     * @param state - Attempt-scoped persistence state.
+     * @param sdkUsage - Complete Agents SDK usage for this attempt.
+     * @param lastResponseId - Last provider response id in the attempt.
+     */
+    async completeTrackedAttempt(state, sdkUsage, lastResponseId) {
+        const usage = agentRunUsage(sdkUsage);
+        const requestUsageEntries = agentRequestCostUsageEntries(sdkUsage);
+        const cost = agentAttemptCost(state.aiRequest.provider, state.model, usage, requestUsageEntries, state.hostedToolUsage);
+        state.aiRequest.assign({
+            response: agentAttemptResponse(usage, requestUsageEntries, cost, state.hostedToolUsage, {
+                lastResponseId,
+            }),
+            status: AI_REQUEST_STATUS.completed,
+            completedAt: new Date(),
+            durationMs: Date.now() - state.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD: cost.costUSD,
+            knownCostUSD: cost.knownCostUSD,
+            errorCode: null,
+            errorMessage: null,
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Finalizes a failed provider attempt with every usage dimension observed.
+     *
+     * @param state - Attempt-scoped persistence state.
+     * @param sdkUsage - Partial SDK usage accumulated before failure.
+     * @param providerStarted - Whether execution crossed the provider boundary.
+     * @param error - Error that ended the attempt.
+     */
+    async failTrackedAttempt(state, sdkUsage, providerStarted, error) {
+        const usage = sdkUsage ? agentRunUsage(sdkUsage) : emptyAgentRunUsage();
+        const requestUsageEntries = sdkUsage ? agentRequestCostUsageEntries(sdkUsage) : [];
+        const hasBillableUsage = sdkUsage
+            ? hasBillableAgentAttemptUsage(sdkUsage, state.hostedToolUsage)
+            : Object.values(state.hostedToolUsage).some(count => Number.isFinite(count) && count > 0);
+        const cost = hasBillableUsage
+            ? agentAttemptCost(state.aiRequest.provider, state.model, usage, requestUsageEntries, state.hostedToolUsage)
+            : emptyAgentAttemptCost(providerStarted);
+        const message = error instanceof Error ? error.message : `Unable to run ${this.agentName}.`;
+        state.aiRequest.assign({
+            response: agentAttemptResponse(usage, requestUsageEntries, cost, state.hostedToolUsage, {
+                error: message,
+            }),
+            status: AI_REQUEST_STATUS.failed,
+            completedAt: new Date(),
+            durationMs: Date.now() - state.startTimeMs,
+            inputTokens: usage.inputTokens,
+            outputTokens: usage.outputTokens,
+            totalTokens: usage.totalTokens,
+            reasoningTokens: usage.reasoningTokens,
+            cachedTokens: usage.cachedTokens,
+            cacheWriteTokens: usage.cacheWriteTokens,
+            costUSD: cost.costUSD,
+            knownCostUSD: cost.knownCostUSD,
+            errorCode: openAIProviderError(error).code,
+            errorMessage: message,
+            metadata: {
+                ...(state.aiRequest.metadata ?? {}),
+                outcome: hasBillableUsage ? 'failed_after_provider_usage' : 'failed_without_reported_usage',
+                providerStarted,
+            },
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Persists sanitized failed provider attempts for auditing and debugging.
+     *
+     * @param state - Active run persistence state.
+     * @param failures - Failed attempts collected so far.
+     */
+    async recordProviderAttempts(state, failures) {
+        state.aiRequest.assign({
+            metadata: {
+                ...(state.aiRequest.metadata ?? {}),
+                providerAttempts: failures,
+            },
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Checks app allowance and reserves capacity for the attempt's first HTTP request.
+     *
+     * @param prepared - Prepared run state with an existing AiRequest row.
+     * @param instructions - System instructions sent to the SDK agent.
+     * @param input - Complete model input for token estimation.
+     * @param attempt - Provider attempt about to run.
+     * @param attemptState - Append-only request row for this provider execution.
+     * @returns Active provider rate-limit lease, or null when rate limiting is disabled.
+     */
+    async acquireProviderCapacity(prepared, instructions, input, attempt, attemptState) {
+        const operation = prepared.state.aiRequest.operation || 'agents.run.stream';
+        const estimatedTokens = estimatedAgentRunTokens({ instructions, input });
+        await app().ai.checkAllowance({
+            provider: attempt.provider,
+            endpoint: responsesRateLimitEndpoint(),
+            model: attempt.model,
+            operation,
+            user: this.userId() || null,
+            scope: this.scopeId() || null,
+            aiRequest: prepared.state.rootAiRequest,
+            estimatedTokens,
+            usage: this.billableUsageCharge(),
+            metadata: {
+                agent: this.agentName,
+                traceId: prepared.traceId,
+                toolNames: prepared.invocation.toolDefinitions.map(tool => tool.name),
+            },
+        });
+        const lease = await app().ai.acquireRateLimit({
+            provider: attempt.provider,
+            endpoint: responsesRateLimitEndpoint(),
+            model: attempt.model,
+            operation,
+            estimatedTokens,
+            aiRequest: attemptState.aiRequest,
+        });
+        try {
+            await this.attachRateLimitBucket(attemptState, lease);
+            return lease;
+        }
+        catch (error) {
+            await app().ai.releaseRateLimit(lease);
+            throw error;
+        }
+    }
+    /**
+     * Stores the current provider bucket on the tracked request for audit/debugging.
+     *
+     * @param state - Active run persistence state.
+     * @param lease - Provider rate-limit lease returned by the AI service.
+     */
+    async attachRateLimitBucket(state, lease) {
+        if (!lease?.bucket)
+            return;
+        state.aiRequest.assign({
+            rateLimitBucket: lease.bucket,
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Stores the exact system instructions and built SDK input used for a run.
+     *
+     * @param state - Active run persistence state.
+     * @param input - Prompt data sent to the Agents SDK runner.
+     */
+    async attachPromptRequestPayload(state, input) {
+        state.aiRequest.assign({
+            request: {
+                ...(recordValue(state.aiRequest.request) ?? {}),
+                message: input.message,
+                previousMessages: input.previousMessages,
+                instructions: input.instructions,
+                input: input.input,
+                prompt: promptMessagesForRequest(input.instructions, input.input),
+            },
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Builds the debug timeline event for the exact prompt sent to the SDK.
+     *
+     * @param state - Active run persistence state.
+     * @param input - System instructions, model input, and model name for the run.
+     * @returns Prompt-context stream event for the frontend timeline.
+     */
+    promptContextEvent(state, input) {
+        return {
+            type: 'prompt.context',
+            id: promptContextId(state.aiRequest.id, state.traceId),
+            aiRequestId: state.aiRequest.id ? String(state.aiRequest.id) : null,
+            traceId: state.traceId,
+            model: input.model,
+            createdAt: dateString(state.aiRequest.startedAt ?? state.aiRequest.createdAt),
+            userMessageId: state.metadata.userMessageId ?? null,
+            messages: promptContextMessages(input.instructions, input.input),
+        };
+    }
+    /**
+     * Creates the pending provider request row and records the system message.
+     *
+     * @param input - Run metadata needed for persistence.
+     * @returns Persistence state for subsequent messages and completion.
+     */
+    async startTrackedRun(input) {
+        const toolDefinitions = input.invocation.toolDefinitions;
+        const aiRequest = await new (app().ai.models.request)({
+            conversation: input.conversation,
+            parentAiRequest: this.context.parentAiRequestId ?? null,
+            user: this.userId() || null,
+            [app().ai.scopeField]: this.scopeId(),
+            provider: AI_PROVIDER.openai,
+            model: input.model,
+            operation: input.transport === 'queue' ? 'agents.run.queue' : 'agents.run.stream',
+            status: AI_REQUEST_STATUS.pending,
+            costUSD: 0,
+            knownCostUSD: 0,
+            request: {
+                message: input.message,
+                model: input.model,
+                tools: toolDefinitions.map(tool => tool.name),
+                toolDefinitions,
+                traceId: input.traceId,
+            },
+            metadata: {
+                agent: this.agentName,
+                traceId: input.traceId,
+                transport: input.transport,
+            },
+            startedAt: new Date(),
+        }).save();
+        const state = {
+            conversation: input.conversation,
+            rootAiRequest: aiRequest,
+            aiRequest,
+            nextSequence: await nextMessageSequence(input.conversation),
+            model: input.model,
+            traceId: input.traceId,
+            startTimeMs: Date.now(),
+            metadata: {},
+            toolDefinitions,
+            hostedToolUsage: {},
+            hostedToolCallIds: new Set(),
+            citations: [],
+            toolArgumentsByCallId: {},
+        };
+        await this.saveMessage(state, {
+            role: AI_MESSAGE_ROLE.system,
+            content: input.invocation.instructions,
+            contentJson: null,
+            metadata: {
+                eventType: 'system_instructions',
+                traceId: input.traceId,
+            },
+        });
+        return state;
+    }
+    /**
+     * Builds the run context object shared with local function tools.
+     *
+     * @param state - Active run persistence state.
+     * @param emit - Stream event sink, or no-op for queued runs.
+     * @returns Agents SDK run context.
+     */
+    sdkContext(state, emit) {
+        return {
+            ...this.toolRunContext(state),
+            userId: this.userId(),
+            scopeId: this.scopeId(),
+            [`${app().ai.scopeField}Id`]: this.scopeId(),
+            conversationId: String(state.conversation.id),
+            aiRequestId: state.aiRequest.id ? String(state.aiRequest.id) : null,
+            rootAiRequestId: state.rootAiRequest.id ? String(state.rootAiRequest.id) : null,
+            traceId: state.traceId,
+            emitToolProgress: async (progress) => {
+                await emit({
+                    type: 'tool.progress',
+                    id: progress.toolCallId,
+                    toolName: progress.toolName,
+                    progress: {
+                        id: `${progress.toolCallId}:${Date.now()}`,
+                        message: progress.message,
+                        current: progress.current,
+                        total: progress.total,
+                        data: progress.data,
+                        createdAt: new Date().toISOString(),
+                    },
+                });
+            },
+        };
+    }
+    /**
+     * Converts an Agents SDK stream event into a application frontend stream event.
+     *
+     * @param state - Active run persistence state.
+     * @param event - SDK stream event.
+     * @returns Normalized stream event, or null when the event is not displayed.
+     */
+    async streamEventFromSdkEvent(state, event) {
+        if (event.type === 'raw_model_stream_event') {
+            return await this.rawModelStreamEvent(state, event.data);
+        }
+        if (event.type !== 'run_item_stream_event')
+            return null;
+        if (event.name === 'tool_called')
+            return await this.toolCalledEvent(state, event.item);
+        if (event.name === 'tool_output')
+            return await this.toolOutputEvent(state, event.item);
+        if (event.name === 'tool_search_called')
+            return await this.toolCalledEvent(state, event.item);
+        if (event.name === 'tool_search_output_created')
+            return await this.toolOutputEvent(state, event.item);
+        return null;
+    }
+    /**
+     * Converts raw model stream data into a persisted app stream event.
+     *
+     * @param state - Active run persistence state.
+     * @param data - Raw SDK model stream data.
+     * @returns Normalized stream event, or null when ignored.
+     */
+    async rawModelStreamEvent(state, data) {
+        const record = recordValue(data);
+        if (!record)
+            return null;
+        const citation = agentCitationFromStreamRecord(record);
+        if (citation) {
+            if (!rememberAgentCitation(state.citations, citation))
+                return null;
+            return {
+                type: 'citation.added',
+                citation,
+            };
+        }
+        if (record.type === 'response.reasoning_summary_text.done') {
+            return await this.reasoningSummaryCompletedEvent(state, record);
+        }
+        return rawModelStreamRecordEvent(record, state.toolDefinitions);
+    }
+    /**
+     * Persists a completed reasoning summary and returns its stream event.
+     *
+     * @param state - Active run persistence state.
+     * @param record - Raw Responses reasoning summary completion event.
+     * @returns Reasoning summary completion event, or null when malformed.
+     */
+    async reasoningSummaryCompletedEvent(state, record) {
+        const id = reasoningSummaryEventId(record);
+        const text = stringValue(record.text);
+        if (!id || !text)
+            return null;
+        const message = await this.saveMessage(state, {
+            role: AI_MESSAGE_ROLE.system,
+            content: text,
+            contentJson: {
+                type: 'reasoning_summary',
+                id,
+                text,
+            },
+            metadata: {
+                eventType: 'reasoning_summary',
+                traceId: state.traceId,
+            },
+        });
+        return {
+            type: 'reasoning.summary.completed',
+            id,
+            text,
+            createdAt: dateString(message.createdAt),
+        };
+    }
+    /**
+     * Persists and emits a tool-call start event.
+     *
+     * @param state - Active run persistence state.
+     * @param item - SDK run item.
+     * @returns Tool calling event or final hosted-tool output event.
+     */
+    async toolCalledEvent(state, item) {
+        const rawItem = rawItemFromRunItem(item);
+        const toolName = hostedToolNameFromRawItem(rawItem) ?? stringValue(rawItem?.name) ?? 'unknown_tool';
+        const callId = toolCallId(rawItem, toolName);
+        const argumentsValue = toolArguments(rawItem);
+        const toolDefinition = this.toolDefinition(state, toolName);
+        rememberToolArguments(state, callId, argumentsValue);
+        if (hostedToolCompleted(rawItem)) {
+            return await this.toolOutputEvent(state, item);
+        }
+        await this.saveMessage(state, {
+            role: AI_MESSAGE_ROLE.tool,
+            content: `${toolName} started.`,
+            contentJson: {
+                state: AI_MESSAGE_TOOL_STATE.calling,
+                arguments: argumentsValue,
+            },
+            toolCallId: callId,
+            toolName,
+            toolState: AI_MESSAGE_TOOL_STATE.calling,
+            metadata: {
+                eventType: 'tool_calling',
+                traceId: state.traceId,
+            },
+        });
+        return {
+            type: 'tool.calling',
+            id: callId,
+            toolName,
+            arguments: argumentsValue,
+            toolDefinition,
+        };
+    }
+    /**
+     * Persists and emits a tool output event.
+     *
+     * @param state - Active run persistence state.
+     * @param item - SDK run item.
+     * @returns Tool success or error event.
+     */
+    async toolOutputEvent(state, item) {
+        const rawItem = rawItemFromRunItem(item);
+        const output = outputFromRunItem(item, rawItem);
+        const hostedToolName = hostedToolNameFromRawItem(rawItem);
+        const toolName = hostedToolName ?? stringValue(rawItem?.name) ?? outputToolName(rawItem) ?? 'unknown_tool';
+        const callId = toolCallId(rawItem, toolName);
+        const argumentsValue = toolOutputArguments(state, callId, toolArguments(rawItem));
+        const parsedOutput = parseToolOutput(output);
+        const errorMessage = hostedToolErrorMessage(rawItem) ?? toolResultErrorMessage(parsedOutput);
+        const toolState = errorMessage ? AI_MESSAGE_TOOL_STATE.error : AI_MESSAGE_TOOL_STATE.success;
+        recordHostedToolUsage(state, hostedToolName, callId, rawItem);
+        await this.saveMessage(state, {
+            role: AI_MESSAGE_ROLE.tool,
+            content: errorMessage ? `${toolName} failed.` : `${toolName} completed.`,
+            contentJson: {
+                state: toolState,
+                arguments: argumentsValue,
+                result: parsedOutput,
+            },
+            toolCallId: callId,
+            toolName,
+            toolState,
+            metadata: {
+                eventType: errorMessage ? 'tool_error' : 'tool_success',
+                traceId: state.traceId,
+            },
+        });
+        if (errorMessage) {
+            return {
+                type: 'tool.error',
+                id: callId,
+                toolName,
+                arguments: argumentsValue,
+                error: {
+                    message: errorMessage,
+                    details: parsedOutput,
+                },
+            };
+        }
+        return {
+            type: 'tool.success',
+            id: callId,
+            toolName,
+            arguments: argumentsValue,
+            result: parsedOutput,
+        };
+    }
+    /**
+     * Saves one normalized AI message and increments the persisted sequence.
+     *
+     * @param state - Active run persistence state.
+     * @param input - Message fields to persist.
+     * @returns Persisted message record.
+     */
+    async saveMessage(state, input) {
+        const message = await new (app().ai.models.message)({
+            conversation: state.conversation,
+            aiRequest: state.rootAiRequest,
+            user: entityRefId(state.rootAiRequest.user),
+            [app().ai.scopeField]: entityRefId(state.rootAiRequest[app().ai.scopeField]),
+            role: input.role,
+            sequence: state.nextSequence,
+            content: input.content,
+            contentJson: input.contentJson,
+            toolCallId: input.toolCallId ?? null,
+            toolName: input.toolName ?? null,
+            toolState: input.toolState ?? null,
+            provider: state.aiRequest.provider ?? AI_PROVIDER.openai,
+            model: state.model,
+            metadata: input.metadata,
+        }).save();
+        state.nextSequence += 1;
+        return message;
+    }
+    /**
+     * Stores the provider-finalized logical run and settles its recursive cost tree.
+     *
+     * The attempt row is already durable before this method runs. Persisting the
+     * provider-finalized marker before credit settlement lets a queued retry resume
+     * settlement without making another provider request.
+     *
+     * @param state - Logical root persistence state.
+     * @param input - Final output and successful attempt identity.
+     * @returns Settled application-credit charge and recorded provider cost.
+     */
+    async completeTrackedRun(state, input) {
+        const response = {
+            finalOutput: input.finalOutput,
+            citations: input.citations,
+            lastResponseId: input.lastResponseId,
+            traceId: state.traceId,
+            providerFinalized: true,
+            successfulAttemptAiRequestId: input.successfulAttemptAiRequestId,
+            ...(input.structuredOutput !== undefined ? { structuredOutput: input.structuredOutput } : {}),
+            ...(input.outputMetadata ? { outputMetadata: input.outputMetadata } : {}),
+        };
+        state.rootAiRequest.assign({
+            response,
+            status: AI_REQUEST_STATUS.pending,
+            completedAt: null,
+            durationMs: Date.now() - state.startTimeMs,
+            inputTokens: null,
+            outputTokens: null,
+            totalTokens: null,
+            reasoningTokens: null,
+            cachedTokens: null,
+            cacheWriteTokens: null,
+            costUSD: 0,
+            knownCostUSD: 0,
+            errorCode: null,
+            errorMessage: null,
+            metadata: withoutOpenAIQuotaRetryMetadata(state.rootAiRequest.metadata),
+        });
+        await state.rootAiRequest.save();
+        return await this.settleFinalizedTrackedRun(state);
+    }
+    /** Controls whether streamed events expose provider costs to this viewer. */
+    exposeProviderCosts() { return false; }
+    /** Aggregates provider usage; applications may extend this hook to settle their own credit ledger. */
+    async settleUsage(rootAiRequest, _initialCharge) {
+        const run = await app().ai.models.request.runCostSummary(String(rootAiRequest.id));
+        if (!run)
+            throw new Error('Tracked AI request tree is missing.');
+        return { run, creditCost: null };
+    }
+    /**
+     * Settles and completes a root whose provider attempts are already durable.
+     *
+     * @param state - Logical root persistence state.
+     * @returns Recursive usage, settled credits, and complete provider cost.
+     */
+    async settleFinalizedTrackedRun(state) {
+        const settlement = await this.settleUsage(state.rootAiRequest, this.billableUsageCharge());
+        const run = settlement.run;
+        const usage = {
+            requests: run.providerRequestCount,
+            inputTokens: run.inputTokens,
+            outputTokens: run.outputTokens,
+            totalTokens: run.totalTokens,
+            reasoningTokens: run.reasoningTokens,
+            cachedTokens: run.cachedTokens,
+            cacheWriteTokens: run.cacheWriteTokens,
+        };
+        const response = recordValue(state.rootAiRequest.response) ?? {};
+        const lastResponseId = stringValue(response.lastResponseId);
+        state.rootAiRequest.assign({
+            status: AI_REQUEST_STATUS.completed,
+            completedAt: new Date(),
+            errorCode: null,
+            errorMessage: null,
+            costUSD: 0,
+            knownCostUSD: 0,
+            response: {
+                ...response,
+                usage,
+                cost: {
+                    rootCostUSD: run.rootCostUSD,
+                    childCostUSD: run.childCostUSD,
+                    totalCostUSD: run.totalCostUSD,
+                    requestCount: run.requestCount,
+                    providerRequestCount: run.providerRequestCount,
+                    unpricedRequestCount: run.unpricedRequestCount,
+                    creditCost: settlement.creditCost,
+                },
+            },
+        });
+        await state.rootAiRequest.save();
+        await this.touchConversation(state, {
+            lastTraceId: state.traceId,
+            lastResponseId,
+            lastStatus: AI_REQUEST_STATUS.completed,
+            lastError: null,
+            nextRetryAt: null,
+            retryUntil: null,
+        });
+        return {
+            usage,
+            creditCost: settlement.creditCost,
+            costUSD: run.unpricedRequestCount > 0 ? null : run.totalCostUSD,
+        };
+    }
+    /**
+     * Keeps a quota-blocked queued run pending and records its next retry.
+     *
+     * @param state - Active run persistence state.
+     * @param quotaRetry - Bounded exponential quota retry decision.
+     */
+    async deferTrackedRun(state, quotaRetry) {
+        state.aiRequest.assign({
+            status: AI_REQUEST_STATUS.pending,
+            completedAt: null,
+            durationMs: null,
+            errorCode: quotaRetry.code,
+            errorMessage: quotaRetry.message,
+            metadata: withOpenAIQuotaRetryMetadata(state.aiRequest.metadata, quotaRetry.metadata),
+        });
+        await state.aiRequest.save();
+        await this.touchConversation(state, {
+            lastTraceId: state.traceId,
+            lastStatus: AI_REQUEST_STATUS.pending,
+            lastError: quotaRetry.message,
+            nextRetryAt: quotaRetry.retryAt.toISOString(),
+            retryUntil: quotaRetry.retryUntil.toISOString(),
+        });
+    }
+    /**
+     * Marks the tracked AI request as failed.
+     *
+     * @param state - Active run persistence state.
+     * @param message - Failure message to persist.
+     * @param errorCode - Provider error code, when available.
+     */
+    async failTrackedRun(state, message, errorCode = null) {
+        state.aiRequest.assign({
+            status: AI_REQUEST_STATUS.failed,
+            completedAt: new Date(),
+            durationMs: Date.now() - state.startTimeMs,
+            errorCode,
+            errorMessage: message,
+            response: {
+                ...(recordValue(state.aiRequest.response) ?? {}),
+                traceId: state.traceId,
+                error: message,
+            },
+        });
+        await state.aiRequest.save();
+        await this.touchConversation(state, {
+            lastTraceId: state.traceId,
+            lastStatus: AI_REQUEST_STATUS.failed,
+            lastError: message,
+            nextRetryAt: null,
+        });
+    }
+    /**
+     * Touches the conversation row so history sorting reflects the latest agent turn.
+     *
+     * Agent-owned scope metadata is reapplied on every update so lifecycle fields
+     * cannot erase the stable identity used by workflow-specific history lookups.
+     *
+     * @param state - Active run persistence state.
+     * @param metadata - Metadata fields to merge onto the conversation.
+     * @returns Nothing after the conversation metadata is persisted.
+     */
+    async touchConversation(state, metadata) {
+        state.conversation.assign({
+            metadata: {
+                ...(state.conversation.metadata ?? {}),
+                ...this.conversationMetadata(),
+                ...metadata,
+            },
+        });
+        await state.conversation.save();
+    }
+    /**
+     * Loads the previous conversation flow for prompt continuity.
+     *
+     * @param conversation - Conversation to read from.
+     * @param excludeAiRequestId - Current run request id to exclude when a queued run resumes.
+     * @returns Previous turns and tool events in provider-compatible input shape.
+     */
+    async previousMessages(conversation, excludeAiRequestId = null) {
+        if (!conversation.id)
+            return [];
+        const messages = await app().ai.models.message
+            .where('conversation', String(conversation.id))
+            .orderBy('sequence', 'desc')
+            .limit((this.maxPreviousMessages * 2) + 12)
+            .all();
+        const replayMessages = messages
+            .reverse()
+            .filter(message => !excludeAiRequestId || entityRefId(message.aiRequest) !== excludeAiRequestId);
+        const unresolvedCallIds = unresolvedToolCallIds(replayMessages);
+        const seenToolCallIds = new Set();
+        return replayMessages
+            .flatMap(message => agentInputItemsFromAiMessage(message, seenToolCallIds, unresolvedCallIds))
+            .slice(-this.maxPreviousMessages);
+    }
+    /**
+     * Builds the queue payload for a prepared background run.
+     *
+     * @param prepared - Prepared run state.
+     * @param serializedAgent - Versioned constructor-state envelope.
+     * @returns Queue-safe payload.
+     */
+    queuedRunPayload(prepared, serializedAgent) {
+        return {
+            agentName: this.agentName,
+            agent: serializedAgent,
+            message: prepared.message,
+            metadata: this.queueMetadata(),
+            conversationId: String(prepared.state.conversation.id),
+            aiRequestId: prepared.state.aiRequest.id ? String(prepared.state.aiRequest.id) : null,
+            traceId: prepared.traceId,
+            model: prepared.model,
+        };
+    }
+    /**
+     * Stores the queue job id on the pending AI request for debugging.
+     *
+     * @param state - Active run persistence state.
+     * @param jobId - Queue job id returned by the queue driver.
+     */
+    async markQueued(state, jobId) {
+        state.aiRequest.assign({
+            request: {
+                ...(recordValue(state.aiRequest.request) ?? {}),
+                queueJobId: jobId,
+            },
+            metadata: {
+                ...(state.aiRequest.metadata ?? {}),
+                queueJobId: jobId,
+            },
+        });
+        await state.aiRequest.save();
+    }
+    /**
+     * Returns the public tool definition for a tool name.
+     *
+     * @param state - Active run carrying metadata derived from its configured tools.
+     * @param toolName - SDK or hosted tool name.
+     * @returns Public tool definition, or null when unavailable.
+     */
+    toolDefinition(state, toolName) {
+        return state.toolDefinitions.find(definition => definition.name === toolName) ?? null;
+    }
+    /**
+     * Returns the active user id as a string.
+     *
+     * @returns Active user id, or an empty string when unavailable.
+     */
+    userId() {
+        return contextIdentity(this.context.user);
+    }
+    /**
+     * Returns the active application scope id as a string.
+     *
+     * @returns Active application scope id.
+     */
+    scopeId() {
+        return contextIdentity(this.context.scope);
+    }
+}
+/**
+ * Restores local capacity deferrals wrapped as connection failures by the SDK.
+ *
+ * @param error - SDK or application failure from an agent turn.
+ * @returns Original limiter deferral, or the unchanged failure for normal handling.
+ */
+function agentRateLimitError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error && !seen.has(current)) {
+        if (current instanceof AIRateLimitDeferredError)
+            return current;
+        seen.add(current);
+        current = current.cause;
+    }
+    return error;
+}
+/**
+ * Builds frontend-safe metadata from the executable tools returned by an agent.
+ *
+ * @param tools - Executable tools configured for one agent invocation.
+ * @returns Serializable definitions in provider tool order.
+ */
+function agentToolDefinitions(tools) {
+    return tools.map(tool => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+    }));
+}
+/**
+ * Captures the exact Responses request prepared by the Agents SDK Runner.
+ *
+ * The capturing model invokes the OpenAI provider's own request builder and
+ * stops before transport. Awaiting the Runner is important because its request
+ * preparation includes enabled-tool serialization, output-schema conversion,
+ * and model-specific default settings.
+ *
+ * @param preview - Shared SDK Agent, input, context, and model configuration.
+ * @returns JSON-safe `responses.create` request body.
+ */
+async function openAIResponseRequestBody(preview) {
+    const [{ OpenAIResponsesModel }, { default: OpenAI }] = await Promise.all([
+        import('@openai/agents'),
+        import('openai'),
+    ]);
+    const requestCaptured = new Error('OpenAI request preview captured.');
+    let requestBody = null;
+    /**
+     * Request-only model that stops before the OpenAI transport call.
+     */
+    class OpenAIRequestPreviewModel extends OpenAIResponsesModel {
+        /**
+         * Captures the JSON body passed to the OpenAI Responses client.
+         *
+         * @param request - Complete ModelRequest prepared by the SDK Runner.
+         * @returns Async iterable that stops with the private capture sentinel.
+         */
+        async *getStreamedResponse(request) {
+            const built = this._buildResponsesCreateRequest(request, true);
+            requestBody = JSON.parse(JSON.stringify(built.requestData));
+            throw requestCaptured;
+        }
+    }
+    const previewModel = new OpenAIRequestPreviewModel(new OpenAI({ apiKey: 'dry-run-request-preview' }), preview.model);
+    const runner = new Runner({
+        model: preview.model,
+        modelProvider: {
+            /**
+             * Returns the request-capturing model instead of a transport model.
+             *
+             * @returns OpenAI Responses model that stops before network transport.
+             */
+            async getModel() {
+                return previewModel;
+            },
+        },
+        modelSettings: preview.modelSettings,
+        tracingDisabled: true,
+        traceIncludeSensitiveData: false,
+    });
+    const stream = await runner.run(preview.agent, preview.input, {
+        stream: true,
+        context: preview.context,
+        maxTurns: preview.maxTurns,
+        reasoningItemIdPolicy: 'preserve',
+    });
+    try {
+        await stream.completed;
+    }
+    catch (error) {
+        if (error !== requestCaptured)
+            throw error;
+    }
+    if (requestBody === null) {
+        throw new Error('The Agents SDK did not prepare an OpenAI request preview.');
+    }
+    return requestBody;
+}
+/**
+ * Accepts stream events when the caller does not need live output.
+ */
+async function noopAgentEventSink() { }
+/**
+ * Raised when a user asks for an inaccessible agent conversation.
+ */
+export class AgentAuthorizationError extends Error {
+    /**
+     * Creates an agent authorization error.
+     *
+     * @param message - Public error message.
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'AgentAuthorizationError';
+    }
+}
+/**
+ * Returns the next message sequence for a conversation.
+ *
+ * @param conversation - Conversation to append to.
+ * @returns Next message sequence number.
+ */
+async function nextMessageSequence(conversation) {
+    if (!conversation.id)
+        return 1;
+    const lastMessage = await app().ai.models.message
+        .where('conversation', String(conversation.id))
+        .orderBy('sequence', 'desc')
+        .first();
+    return (lastMessage?.sequence ?? 0) + 1;
+}
+/**
+ * Normalizes link-field entity refs to their string id.
+ *
+ * @param value - Unknown entity reference value.
+ * @returns Entity id string or null.
+ */
+function entityRefId(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!value || typeof value !== 'object')
+        return null;
+    const id = value.id;
+    return id === null || id === undefined ? null : String(id);
+}
+/**
+ * Converts raw model stream records into text, reasoning, or hosted-tool events.
+ *
+ * @param record - Raw SDK model stream record.
+ * @param toolDefinitions - Public tool definitions available to the active agent.
+ * @returns Normalized stream event, or null when ignored.
+ */
+function rawModelStreamRecordEvent(record, toolDefinitions) {
+    if (record.type === 'response.reasoning_summary_text.delta') {
+        const id = reasoningSummaryEventId(record);
+        const delta = stringValue(record.delta);
+        return id && delta ? { type: 'reasoning.summary.delta', id, delta } : null;
+    }
+    if (record.type !== 'response.output_text.delta' && record.type !== 'output_text_delta') {
+        return rawHostedToolStreamEvent(record, toolDefinitions);
+    }
+    const delta = stringValue(record.delta);
+    return delta ? { type: 'text.delta', delta } : null;
+}
+/**
+ * Builds a stable timeline id for one reasoning summary stream item.
+ *
+ * @param record - Raw Responses reasoning summary stream event.
+ * @returns Stable summary id, or null when the event has no item id.
+ */
+function reasoningSummaryEventId(record) {
+    const itemId = stringValue(record.item_id) || stringValue(record.itemId);
+    const summaryIndex = typeof record.summary_index === 'number' ? record.summary_index : record.summaryIndex;
+    if (!itemId)
+        return null;
+    return `${itemId}:${typeof summaryIndex === 'number' ? summaryIndex : 0}`;
+}
+/**
+ * Converts raw Responses hosted-tool lifecycle events into tool-card updates.
+ *
+ * @param record - Raw hosted-tool stream record.
+ * @param toolDefinitions - Public tool definitions available to the active agent.
+ * @returns Normalized stream event, or null when ignored.
+ */
+function rawHostedToolStreamEvent(record, toolDefinitions) {
+    const eventType = stringValue(record.type);
+    const outputItem = recordValue(record.item);
+    const outputItemToolName = hostedToolNameFromRawItem(outputItem);
+    if (eventType === 'response.output_item.added' && outputItemToolName) {
+        return {
+            type: 'tool.calling',
+            id: rawHostedToolItemCallId(outputItem, outputItemToolName),
+            toolName: outputItemToolName,
+            arguments: rawHostedToolItemArguments(outputItem),
+            toolDefinition: toolDefinitions.find(definition => definition.name === outputItemToolName) ?? null,
+        };
+    }
+    if (eventType === 'response.output_item.done' && outputItemToolName) {
+        const callId = rawHostedToolItemCallId(outputItem, outputItemToolName);
+        const status = stringValue(outputItem?.status);
+        if (status === 'failed' || status === 'incomplete') {
+            return {
+                type: 'tool.error',
+                id: callId,
+                toolName: outputItemToolName,
+                arguments: rawHostedToolItemArguments(outputItem),
+                error: {
+                    message: `${outputItemToolName} ${status}.`,
+                    details: outputItem,
+                },
+            };
+        }
+        return {
+            type: 'tool.success',
+            id: callId,
+            toolName: outputItemToolName,
+            arguments: rawHostedToolItemArguments(outputItem),
+            result: outputItem,
+        };
+    }
+    const toolName = hostedToolNameFromRawEvent(eventType);
+    if (!eventType || !toolName)
+        return null;
+    const callId = rawHostedToolCallId(record, toolName);
+    const result = rawHostedToolResult(record);
+    if (eventType.endsWith('.completed')) {
+        return {
+            type: 'tool.success',
+            id: callId,
+            toolName,
+            result,
+        };
+    }
+    if (eventType.endsWith('.failed')) {
+        return {
+            type: 'tool.error',
+            id: callId,
+            toolName,
+            error: {
+                message: 'The hosted tool failed.',
+                details: result,
+            },
+        };
+    }
+    if (eventType.endsWith('.in_progress')) {
+        return {
+            type: 'tool.calling',
+            id: callId,
+            toolName,
+            arguments: rawHostedToolArguments(record),
+            toolDefinition: toolDefinitions.find(definition => definition.name === toolName) ?? null,
+        };
+    }
+    return {
+        type: 'tool.progress',
+        id: callId,
+        toolName,
+        progress: {
+            id: `${callId}:${eventType}`,
+            message: rawHostedToolProgressMessage(eventType),
+            data: rawHostedToolProgressData(record),
+            createdAt: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Extracts the raw model item from an Agents SDK run item.
+ *
+ * @param item - SDK run item.
+ * @returns Raw model item record or null.
+ */
+function rawItemFromRunItem(item) {
+    const record = recordValue(item);
+    return recordValue(record?.rawItem);
+}
+/**
+ * Extracts a tool output payload from an Agents SDK run item.
+ *
+ * @param item - SDK run item.
+ * @param rawItem - Raw model item record.
+ * @returns Tool output payload.
+ */
+function outputFromRunItem(item, rawItem) {
+    const record = recordValue(item);
+    if (record && 'output' in record && record.output !== undefined && record.output !== null)
+        return record.output;
+    if (rawItem && 'output' in rawItem && rawItem.output !== undefined && rawItem.output !== null)
+        return rawItem.output;
+    if (rawItem?.providerData)
+        return rawItem.providerData;
+    return rawItem;
+}
+/**
+ * Returns a stable id for a tool call.
+ *
+ * @param rawItem - Raw SDK item.
+ * @param fallback - Fallback id when the SDK item has no id.
+ * @returns Stable tool call id.
+ */
+function toolCallId(rawItem, fallback) {
+    return stringValue(rawItem?.callId) || stringValue(rawItem?.call_id) || stringValue(rawItem?.id) || fallback;
+}
+/**
+ * Reads the tool name from a function-call result when available.
+ *
+ * @param rawItem - Raw SDK item.
+ * @returns Tool name or null.
+ */
+function outputToolName(rawItem) {
+    return stringValue(rawItem?.name);
+}
+/**
+ * Extracts the best available tool arguments for local and hosted tool calls.
+ *
+ * @param rawItem - Raw SDK item.
+ * @returns Tool arguments.
+ */
+function toolArguments(rawItem) {
+    const providerData = recordValue(rawItem?.providerData);
+    const providerAction = providerData?.action ?? providerData?.query ?? providerData?.queries;
+    return parseToolArguments(rawItem?.arguments ?? providerAction ?? {});
+}
+/**
+ * Remembers non-empty tool arguments from the call item for later output items.
+ *
+ * @param state - Active run persistence state.
+ * @param callId - Stable tool call id.
+ * @param value - Parsed argument payload from the SDK item.
+ */
+function rememberToolArguments(state, callId, value) {
+    if (!hasToolArguments(value))
+        return;
+    state.toolArgumentsByCallId[callId] = value;
+}
+/**
+ * Returns output-item arguments, falling back to the matching call item.
+ *
+ * @param state - Active run persistence state.
+ * @param callId - Stable tool call id.
+ * @param value - Parsed output item argument payload.
+ * @returns Best available arguments for the tool call.
+ */
+function toolOutputArguments(state, callId, value) {
+    if (hasToolArguments(value)) {
+        state.toolArgumentsByCallId[callId] = value;
+        return value;
+    }
+    return state.toolArgumentsByCallId[callId] ?? value;
+}
+/**
+ * Returns true when a parsed argument payload carries model-provided input.
+ *
+ * @param value - Parsed argument payload.
+ * @returns True when the payload should replace existing arguments.
+ */
+function hasToolArguments(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    const record = recordValue(value);
+    if (record)
+        return Object.keys(record).length > 0;
+    return true;
+}
+/**
+ * Parses a tool-call arguments value when the SDK supplies JSON text.
+ *
+ * @param value - Unknown arguments value.
+ * @returns Parsed arguments value.
+ */
+function parseToolArguments(value) {
+    if (typeof value !== 'string')
+        return value ?? {};
+    return parseJson(value) ?? value;
+}
+/**
+ * Parses a function-tool output value into the result shape returned by the tool.
+ *
+ * @param value - Unknown tool output value.
+ * @returns Parsed tool output value.
+ */
+function parseToolOutput(value) {
+    const structuredResult = agentToolResultFromStructuredOutput(value);
+    if (structuredResult !== null)
+        return structuredResult;
+    if (typeof value !== 'string')
+        return value;
+    return parseJson(value) ?? value;
+}
+/**
+ * Returns a tool-level error message when the tool result reports one.
+ *
+ * @param value - Parsed tool output value.
+ * @returns Error message or null.
+ */
+function toolResultErrorMessage(value) {
+    const record = recordValue(value);
+    if (record?.status !== 'error')
+        return null;
+    return stringValue(record.message) ?? 'The tool failed.';
+}
+/**
+ * Returns a hosted-tool error when the provider marks the call as failed.
+ *
+ * @param rawItem - Raw SDK item.
+ * @returns Hosted tool error message or null.
+ */
+function hostedToolErrorMessage(rawItem) {
+    const status = stringValue(rawItem?.status);
+    if (status !== 'failed' && status !== 'incomplete')
+        return null;
+    return `${stringValue(rawItem?.name) ?? 'Hosted tool'} ${status}.`;
+}
+/**
+ * Returns true when a hosted tool call item already contains its final status.
+ *
+ * @param rawItem - Raw SDK item.
+ * @returns True when the hosted tool has completed.
+ */
+function hostedToolCompleted(rawItem) {
+    const status = rawItem?.status;
+    return hostedToolNameFromRawItem(rawItem) !== null
+        && (status === 'completed' || status === 'failed' || status === 'incomplete');
+}
+/**
+ * Maps raw Responses hosted-tool event names to the normalized tool name.
+ *
+ * @param eventType - Raw event type.
+ * @returns Hosted tool name or null.
+ */
+function hostedToolNameFromRawEvent(eventType) {
+    if (!eventType)
+        return null;
+    if (eventType.startsWith('response.web_search_call.'))
+        return 'web_search_call';
+    if (eventType.startsWith('response.image_generation_call.'))
+        return 'image_generation_call';
+    return null;
+}
+/**
+ * Maps raw Responses output items to hosted tool names.
+ *
+ * @param item - Raw output item.
+ * @returns Hosted tool name or null.
+ */
+function hostedToolNameFromRawItem(item) {
+    const type = stringValue(item?.type);
+    if (type === 'web_search_call')
+        return 'web_search_call';
+    if (type === 'image_generation_call')
+        return 'image_generation_call';
+    if (type === 'hosted_tool_call')
+        return stringValue(item?.name);
+    return null;
+}
+/**
+ * Records one completed hosted provider-tool call on the active request.
+ *
+ * Web searches are recorded only for `search` actions because page opens are
+ * included in history but are not separate billable calls. Other hosted tools
+ * are retained so the pricing layer can either price them or mark the request
+ * incomplete instead of silently omitting a provider charge.
+ *
+ * @param state - Active run persistence state.
+ * @param toolName - Normalized hosted tool name.
+     * @param callId - Stable provider call id used to prevent duplicate billing.
+ * @param rawItem - Completed raw provider tool item.
+ */
+function recordHostedToolUsage(state, toolName, callId, rawItem) {
+    if (!toolName)
+        return;
+    if (state.hostedToolCallIds.has(callId))
+        return;
+    if (toolName === 'web_search_call') {
+        const providerData = recordValue(rawItem?.providerData);
+        const action = recordValue(rawItem?.action) ?? recordValue(providerData?.action);
+        if (stringValue(action?.type) !== 'search')
+            return;
+    }
+    state.hostedToolCallIds.add(callId);
+    state.hostedToolUsage[toolName] = (state.hostedToolUsage[toolName] ?? 0) + 1;
+}
+/**
+ * Extracts a stable hosted-tool call id from a raw Responses output item.
+ *
+ * @param item - Raw output item.
+ * @param toolName - Hosted tool name.
+ * @returns Stable tool call id.
+ */
+function rawHostedToolItemCallId(item, toolName) {
+    return stringValue(item?.id) || stringValue(item?.call_id) || stringValue(item?.callId) || toolName;
+}
+/**
+ * Extracts hosted-tool arguments from a raw Responses output item.
+ *
+ * @param item - Raw output item.
+ * @returns Hosted tool arguments.
+ */
+function rawHostedToolItemArguments(item) {
+    return recordValue(item?.action) ?? item?.query ?? item?.queries ?? {};
+}
+/**
+ * Extracts a stable hosted-tool call id from a raw Responses stream event.
+ *
+ * @param record - Raw stream event.
+ * @param toolName - Hosted tool name.
+ * @returns Stable tool call id.
+ */
+function rawHostedToolCallId(record, toolName) {
+    return stringValue(record.item_id)
+        || stringValue(record.itemId)
+        || stringValue(record.id)
+        || `${toolName}:${String(record.output_index ?? record.sequence_number ?? 'active')}`;
+}
+/**
+ * Extracts hosted-tool arguments from a raw Responses stream event.
+ *
+ * @param record - Raw stream event.
+ * @returns Hosted tool arguments.
+ */
+function rawHostedToolArguments(record) {
+    return recordValue(record.action) ?? recordValue(record.query) ?? {};
+}
+/**
+ * Builds a compact hosted-tool result payload for raw completed events.
+ *
+ * @param record - Raw stream event.
+ * @returns Compact hosted-tool result.
+ */
+function rawHostedToolResult(record) {
+    const item = recordValue(record.item);
+    return item ?? compactHostedToolRecord(record);
+}
+/**
+ * Builds compact progress data for hosted tools without large binary previews.
+ *
+ * @param record - Raw stream event.
+ * @returns Compact progress data.
+ */
+function rawHostedToolProgressData(record) {
+    const data = compactHostedToolRecord(record);
+    if ('partial_image_b64' in record) {
+        data.hasPartialImage = true;
+    }
+    return data;
+}
+/**
+ * Returns a user-facing hosted-tool progress message.
+ *
+ * @param eventType - Raw hosted-tool event type.
+ * @returns Human-readable progress message.
+ */
+function rawHostedToolProgressMessage(eventType) {
+    if (eventType.includes('.searching'))
+        return 'Searching the web';
+    if (eventType.includes('.generating'))
+        return 'Generating image';
+    if (eventType.includes('.partial_image'))
+        return 'Receiving image preview';
+    return 'Using hosted tool';
+}
+/**
+ * Copies safe scalar hosted-tool fields for progress and generic result views.
+ *
+ * @param record - Raw hosted-tool record.
+ * @returns Compact record without large binary fields.
+ */
+function compactHostedToolRecord(record) {
+    const compact = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'partial_image_b64')
+            continue;
+        if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) {
+            compact[key] = value;
+        }
+    }
+    return compact;
+}
+/**
+ * Parses JSON and returns null when the input is not valid JSON.
+ *
+ * @param value - JSON string to parse.
+ * @returns Parsed value or null.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Creates a provider-compatible user message.
+ *
+ * @param content - Message text to send as user input.
+ * @returns Agents SDK user message item.
+ */
+function userInputMessage(content) {
+    return {
+        type: 'message',
+        role: AI_MESSAGE_ROLE.user,
+        content,
+    };
+}
+/**
+ * Creates a provider-compatible assistant message from persisted text.
+ *
+ * @param content - Assistant text stored from an earlier run.
+ * @returns Agents SDK assistant message item.
+ */
+function assistantInputMessage(content) {
+    return {
+        type: 'message',
+        role: AI_MESSAGE_ROLE.assistant,
+        status: 'completed',
+        content: [
+            {
+                type: 'output_text',
+                text: content,
+            },
+        ],
+    };
+}
+/**
+ * Creates a provider-compatible system message for debug snapshots.
+ *
+ * @param content - System instruction text.
+ * @returns Agents SDK system message item.
+ */
+function systemInputMessage(content) {
+    return {
+        type: 'message',
+        role: AI_MESSAGE_ROLE.system,
+        content,
+    };
+}
+/**
+ * Converts one persisted conversation row into SDK input items.
+ *
+ * Tool result rows require a matching call item. When the original call row is
+ * outside the replay window, the result row carries enough normalized data to
+ * synthesize the call immediately before the result.
+ *
+ * @param message - Persisted conversation row.
+ * @param seenToolCallIds - Tool call ids already emitted into the replay input.
+ * @param unresolvedCallIds - Calls that have no persisted terminal result.
+ * @returns Provider-compatible input items for the row.
+ */
+function agentInputItemsFromAiMessage(message, seenToolCallIds, unresolvedCallIds) {
+    if (message.role === AI_MESSAGE_ROLE.assistant) {
+        return [assistantInputMessage(message.content ?? '')];
+    }
+    if (message.role === AI_MESSAGE_ROLE.user) {
+        return [userInputMessage(message.content ?? '')];
+    }
+    if (message.role === AI_MESSAGE_ROLE.tool) {
+        return toolInputItemsFromAiMessage(message, seenToolCallIds, unresolvedCallIds);
+    }
+    return [];
+}
+/**
+ * Converts one persisted tool timeline row into SDK function-call input items.
+ *
+ * @param message - Persisted tool message.
+ * @param seenToolCallIds - Tool call ids already emitted into the replay input.
+ * @param unresolvedCallIds - Calls that have no persisted terminal result.
+ * @returns Provider-compatible function call and result items for the row.
+ */
+function toolInputItemsFromAiMessage(message, seenToolCallIds, unresolvedCallIds) {
+    const content = recordValue(message.contentJson);
+    const state = persistedToolState(message, content);
+    const toolName = message.toolName || stringValue(content?.toolName);
+    const callId = message.toolCallId || stringValue(content?.callId) || stringValue(content?.call_id);
+    const argumentsValue = content?.arguments ?? {};
+    if (!state || !toolName || !callId)
+        return [];
+    if (state === AI_MESSAGE_TOOL_STATE.calling) {
+        seenToolCallIds.add(callId);
+        return unresolvedCallIds.has(callId)
+            ? [
+                toolCallInputItem(toolName, callId, argumentsValue),
+                interruptedToolResultInputItem(toolName, callId),
+            ]
+            : [toolCallInputItem(toolName, callId, argumentsValue)];
+    }
+    const items = [];
+    if (!seenToolCallIds.has(callId)) {
+        items.push(toolCallInputItem(toolName, callId, argumentsValue));
+        seenToolCallIds.add(callId);
+    }
+    items.push(toolResultInputItem(toolName, callId, state, content, message));
+    return items;
+}
+/**
+ * Reads the normalized lifecycle state from a persisted tool row.
+ *
+ * @param message - Persisted tool message.
+ * @param content - Parsed tool message payload.
+ * @returns Normalized tool state, or null when unsupported.
+ */
+function persistedToolState(message, content) {
+    const state = message.toolState ?? stringValue(content?.state);
+    if (state === AI_MESSAGE_TOOL_STATE.calling
+        || state === AI_MESSAGE_TOOL_STATE.success
+        || state === AI_MESSAGE_TOOL_STATE.error) {
+        return state;
+    }
+    return null;
+}
+/**
+ * Builds the SDK input item representing a previous model tool call.
+ *
+ * @param name - Tool name shown to the model.
+ * @param callId - Provider call id that links the call to its result.
+ * @param argumentsValue - Tool arguments supplied by the model.
+ * @returns Function-call input item accepted by the Agents SDK.
+ */
+function toolCallInputItem(name, callId, argumentsValue) {
+    return {
+        type: 'function_call',
+        callId,
+        name,
+        status: 'completed',
+        arguments: serializedToolArguments(argumentsValue),
+    };
+}
+/**
+ * Builds the SDK input item representing a previous tool result.
+ *
+ * @param name - Tool name shown to the model.
+ * @param callId - Provider call id that links the result to its call.
+ * @param state - Persisted tool completion state.
+ * @param content - Parsed persisted tool payload.
+ * @param message - Persisted tool message.
+ * @returns Function-result input item accepted by the Agents SDK.
+ */
+function toolResultInputItem(name, callId, state, content, message) {
+    return {
+        type: 'function_call_result',
+        name,
+        callId,
+        status: 'completed',
+        output: serializedToolOutput(name, state, content, message),
+    };
+}
+/**
+ * Builds a synthetic result that closes an interrupted persisted function call.
+ *
+ * The result is supplied only to future model turns. The tool is not executed
+ * again automatically because a partially completed tool may have side effects.
+ *
+ * @param name - Persisted function tool name.
+ * @param callId - Provider call id that must receive a matching output.
+ * @returns Provider-compatible error result for the interrupted call.
+ */
+function interruptedToolResultInputItem(name, callId) {
+    return {
+        type: 'function_call_result',
+        name,
+        callId,
+        status: 'completed',
+        output: serializedToolValue({
+            status: 'error',
+            message: INTERRUPTED_TOOL_CALL_MESSAGE,
+        }),
+    };
+}
+/**
+ * Serializes model-provided tool arguments for SDK replay.
+ *
+ * @param value - Persisted arguments payload.
+ * @returns JSON argument string expected by function-call items.
+ */
+function serializedToolArguments(value) {
+    if (typeof value === 'string')
+        return value;
+    return serializedToolValue(value ?? {});
+}
+/**
+ * Serializes stored tool output for SDK replay.
+ *
+ * @param name - Tool name used for fallback error text.
+ * @param state - Persisted tool completion state.
+ * @param content - Parsed persisted tool payload.
+ * @param message - Persisted tool message.
+ * @returns Tool output string for a function-result item.
+ */
+function serializedToolOutput(name, state, content, message) {
+    const result = content && 'result' in content ? content.result : message.content ?? '';
+    if (state === AI_MESSAGE_TOOL_STATE.error) {
+        return serializedToolValue({
+            status: 'error',
+            message: message.content || `${name} failed.`,
+            result,
+        });
+    }
+    return serializedToolValue(result);
+}
+/**
+ * Safely serializes a tool payload for model replay and debug display.
+ *
+ * @param value - Tool payload to serialize.
+ * @returns JSON text, plain string value, or a string fallback.
+ */
+function serializedToolValue(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value ?? {});
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Builds the complete debug prompt array stored with an AI request.
+ *
+ * @param instructions - System instructions configured on the SDK agent.
+ * @param input - Provider-compatible runner input.
+ * @returns Prompt messages for request auditing.
+ */
+function promptMessagesForRequest(instructions, input) {
+    return [
+        systemInputMessage(instructions),
+        ...input,
+    ];
+}
+/**
+ * Builds frontend prompt-context messages from provider-compatible input items.
+ *
+ * @param instructions - System instructions configured on the SDK agent.
+ * @param input - Provider-compatible runner input.
+ * @returns Role-tagged text messages for the debug UI.
+ */
+function promptContextMessages(instructions, input) {
+    return promptMessagesForRequest(instructions, input)
+        .map(promptContextMessageFromInputItem)
+        .filter((message) => message !== null);
+}
+/**
+ * Converts one SDK input item into a prompt-context text message when possible.
+ *
+ * @param item - Provider-compatible input item.
+ * @returns Frontend prompt-context message, or null for unsupported items.
+ */
+function promptContextMessageFromInputItem(item) {
+    const record = recordValue(item);
+    if (!record)
+        return null;
+    const toolMessage = promptContextMessageFromToolItem(record);
+    if (toolMessage)
+        return toolMessage;
+    const role = record?.role;
+    if (role !== AI_MESSAGE_ROLE.system
+        && role !== AI_MESSAGE_ROLE.user
+        && role !== AI_MESSAGE_ROLE.assistant
+        && role !== AI_MESSAGE_ROLE.tool) {
+        return null;
+    }
+    const content = inputContentText(record.content);
+    if (content === null)
+        return null;
+    return {
+        role,
+        content,
+    };
+}
+/**
+ * Converts SDK tool input items into readable prompt-context messages.
+ *
+ * @param item - Provider-compatible tool input item.
+ * @returns Tool prompt-context message, or null when the item is not a tool.
+ */
+function promptContextMessageFromToolItem(item) {
+    const type = item.type;
+    if (type === 'function_call') {
+        const name = stringValue(item.name) || 'unknown_tool';
+        return {
+            role: AI_MESSAGE_ROLE.tool,
+            content: [
+                `Tool call: ${name}`,
+                `Call ID: ${stringValue(item.callId) || stringValue(item.call_id) || 'unknown'}`,
+                'Arguments:',
+                promptPayloadText(item.arguments),
+            ].join('\n'),
+        };
+    }
+    if (type === 'function_call_result') {
+        const name = stringValue(item.name) || 'unknown_tool';
+        return {
+            role: AI_MESSAGE_ROLE.tool,
+            content: [
+                `Tool result: ${name}`,
+                `Call ID: ${stringValue(item.callId) || stringValue(item.call_id) || 'unknown'}`,
+                'Output:',
+                promptPayloadText(item.output),
+            ].join('\n'),
+        };
+    }
+    if (type === 'hosted_tool_call') {
+        const name = stringValue(item.name) || 'hosted_tool';
+        const output = item.output === undefined ? null : ['Output:', promptPayloadText(item.output)].join('\n');
+        return {
+            role: AI_MESSAGE_ROLE.tool,
+            content: [
+                `Hosted tool: ${name}`,
+                `Status: ${stringValue(item.status) || 'unknown'}`,
+                'Arguments:',
+                promptPayloadText(item.arguments),
+                output,
+            ].filter((line) => line !== null).join('\n'),
+        };
+    }
+    return null;
+}
+/**
+ * Converts provider message content into readable text for debugging.
+ *
+ * @param value - String or content-part array from an SDK message.
+ * @returns Readable text, or null when no text can be extracted.
+ */
+function inputContentText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    const text = value
+        .map(inputContentPartText)
+        .filter((part) => part !== null)
+        .join('\n');
+    return text || null;
+}
+/**
+ * Converts one provider content part into readable text.
+ *
+ * @param value - Unknown content part.
+ * @returns Text extracted from the content part, or null when unsupported.
+ */
+function inputContentPartText(value) {
+    const part = recordValue(value);
+    if (!part)
+        return null;
+    if (typeof part.text === 'string')
+        return part.text;
+    if (typeof part.refusal === 'string')
+        return part.refusal;
+    if (typeof part.transcript === 'string')
+        return part.transcript;
+    return null;
+}
+/**
+ * Converts an arbitrary prompt payload into readable debug text.
+ *
+ * @param value - Unknown prompt payload.
+ * @returns Human-readable prompt payload text.
+ */
+function promptPayloadText(value) {
+    const content = inputContentText(value);
+    if (content !== null)
+        return prettyJsonText(content);
+    if (value === undefined)
+        return '{}';
+    return prettyJsonText(value);
+}
+/**
+ * Pretty-prints JSON strings and objects without truncating prompt content.
+ *
+ * @param value - Unknown payload value.
+ * @returns Readable JSON or scalar text.
+ */
+function prettyJsonText(value) {
+    if (typeof value === 'string') {
+        const parsed = parseJson(value);
+        if (parsed !== null)
+            return prettyJsonText(parsed);
+        return value;
+    }
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Estimates the provider token cost for a full agent run before usage is known.
+ *
+ * @param input - System instructions and complete SDK input.
+ * @returns Non-zero token estimate for rate-limit reservations.
+ */
+function estimatedAgentRunTokens(input) {
+    const text = [
+        input.instructions,
+        ...promptContextMessages('', input.input).map(message => message.content),
+    ].join('\n');
+    return estimateTokensFromText(text);
+}
+/**
+ * Converts the SDK final output value into text for persistence and display.
+ *
+ * @param finalOutput - SDK final output.
+ * @param streamedText - Text collected from streaming deltas.
+ * @returns Final output text.
+ */
+function defaultAgentFinalOutputText(finalOutput, streamedText) {
+    if (typeof finalOutput === 'string' && finalOutput.trim())
+        return finalOutput;
+    return streamedText.trim();
+}
+/**
+ * Converts SDK usage into the app's normalized usage summary.
+ *
+ * @param usage - Agents SDK usage object.
+ * @returns Normalized usage summary.
+ */
+function agentRunUsage(usage) {
+    return {
+        requests: usage.requests,
+        inputTokens: numberOrNull(usage.inputTokens),
+        outputTokens: numberOrNull(usage.outputTokens),
+        totalTokens: numberOrNull(usage.totalTokens),
+        reasoningTokens: sumTokenDetails(usage.outputTokensDetails, 'reasoning_tokens'),
+        cachedTokens: sumTokenDetails(usage.inputTokensDetails, 'cached_tokens'),
+        cacheWriteTokens: sumTokenDetails(usage.inputTokensDetails, 'cache_write_tokens'),
+    };
+}
+/**
+ * Normalizes the SDK's individual provider-request usage for accurate pricing.
+ *
+ * @param usage - Agents SDK aggregate usage object.
+ * @returns Individual request entries with cached-input details preserved.
+ */
+function agentRequestCostUsageEntries(usage) {
+    return (usage.requestUsageEntries ?? []).map(entry => ({
+        inputTokens: numberOrNull(entry.inputTokens),
+        outputTokens: numberOrNull(entry.outputTokens),
+        cachedTokens: tokenDetailValue(entry.inputTokensDetails, 'cached_tokens'),
+        cacheWriteTokens: tokenDetailValue(entry.inputTokensDetails, 'cache_write_tokens'),
+        ...(entry.endpoint ? { endpoint: entry.endpoint } : {}),
+    }));
+}
+/**
+ * Prices one agent attempt only when its provider and usage granularity are safe.
+ *
+ * Long-context and cache-write charges apply per provider request. Multiple SDK
+ * requests therefore require a complete request-usage entry set; aggregate
+ * fallback is accepted only for exactly one request.
+ *
+ * @param provider - Provider that executed the attempt.
+ * @param model - Provider model used by the attempt.
+ * @param usage - Aggregate attempt usage.
+ * @param requestUsageEntries - Per-provider-request usage entries.
+ * @param hostedToolUsage - Completed hosted provider-tool calls.
+ * @returns Complete attempt cost and any unpriced dimensions.
+ */
+function agentAttemptCost(provider, model, usage, requestUsageEntries, hostedToolUsage) {
+    const usesPerRequestUsage = usage.requests > 0
+        && requestUsageEntries.length === usage.requests;
+    const usesSingleRequestAggregate = usage.requests === 1
+        && requestUsageEntries.length === 0;
+    const modelCostUSD = provider === AI_PROVIDER.openai
+        ? usesPerRequestUsage
+            ? calculateAIRequestEntriesCostUSD(model, requestUsageEntries)
+            : usesSingleRequestAggregate
+                ? calculateAIRequestCostUSD(model, usage)
+                : null
+        : null;
+    const hostedToolCost = provider === AI_PROVIDER.openai
+        ? calculateAIHostedToolCost(hostedToolUsage)
+        : {
+            costUSD: 0,
+            unpricedUsage: normalizedHostedToolUsage(hostedToolUsage),
+        };
+    const knownCostUSD = combineAIRequestCostUSD(modelCostUSD ?? 0, hostedToolCost.costUSD) ?? 0;
+    const costUSD = Object.keys(hostedToolCost.unpricedUsage).length === 0
+        ? combineAIRequestCostUSD(modelCostUSD, hostedToolCost.costUSD)
+        : null;
+    return {
+        modelCostUSD,
+        hostedToolCostUSD: hostedToolCost.costUSD,
+        unpricedHostedToolUsage: hostedToolCost.unpricedUsage,
+        knownCostUSD,
+        costUSD,
+        pricingUsage: provider !== AI_PROVIDER.openai
+            ? 'unpriced_incomplete'
+            : usesPerRequestUsage
+                ? 'per_request'
+                : usesSingleRequestAggregate
+                    ? 'single_request_aggregate'
+                    : 'unpriced_incomplete',
+    };
+}
+/**
+ * Normalizes completed hosted-tool counts when provider-specific pricing is absent.
+ *
+ * @param usage - Hosted-tool counts observed during one provider attempt.
+ * @returns Positive whole call counts that must remain explicitly unpriced.
+ */
+function normalizedHostedToolUsage(usage) {
+    const normalized = {};
+    for (const [toolName, count] of Object.entries(usage)) {
+        if (!Number.isFinite(count) || count <= 0)
+            continue;
+        normalized[toolName] = Math.trunc(count);
+    }
+    return normalized;
+}
+/**
+ * Returns a cost result for an attempt with no observed billable usage.
+ *
+ * @param providerStarted - Whether execution may have crossed the provider boundary.
+ * @returns Confirmed zero before provider work, otherwise an unknown cost.
+ */
+function emptyAgentAttemptCost(providerStarted) {
+    return {
+        modelCostUSD: providerStarted ? null : 0,
+        hostedToolCostUSD: 0,
+        unpricedHostedToolUsage: {},
+        knownCostUSD: 0,
+        costUSD: providerStarted ? null : 0,
+        pricingUsage: providerStarted ? 'unpriced_incomplete' : 'known_zero',
+    };
+}
+/**
+ * Builds the persisted response payload for one provider attempt.
+ *
+ * @param usage - Normalized aggregate usage.
+ * @param requestUsageEntries - Per-provider-request usage entries.
+ * @param cost - Complete and partial cost result.
+ * @param hostedToolUsage - Completed hosted provider-tool counts.
+ * @param metadata - Attempt result fields such as response id or error.
+ * @returns Auditable attempt response without raw model content.
+ */
+function agentAttemptResponse(usage, requestUsageEntries, cost, hostedToolUsage, metadata) {
+    return {
+        ...metadata,
+        usage,
+        cost: {
+            modelCostUSD: cost.modelCostUSD,
+            hostedToolCostUSD: cost.hostedToolCostUSD,
+            unpricedHostedToolUsage: cost.unpricedHostedToolUsage,
+            knownCostUSD: cost.knownCostUSD,
+            requestCostUSD: cost.costUSD,
+            hostedToolUsage,
+            pricingUsage: cost.pricingUsage,
+            requestUsageEntries,
+        },
+    };
+}
+/**
+ * Returns the absence-preserving usage shape for an attempt without SDK usage.
+ *
+ * @returns Empty usage with no invented provider token counts.
+ */
+function emptyAgentRunUsage() {
+    return {
+        requests: 0,
+        inputTokens: null,
+        outputTokens: null,
+        totalTokens: null,
+        reasoningTokens: null,
+        cachedTokens: null,
+        cacheWriteTokens: null,
+    };
+}
+/**
+ * Applies Standard service tier only to direct OpenAI provider requests.
+ *
+ * @param settings - Agent-owned model settings.
+ * @param provider - Provider selected for the current attempt.
+ * @returns Provider-safe settings with deterministic OpenAI billing tier.
+ */
+function modelSettingsForProvider(settings, provider) {
+    if (provider !== AI_PROVIDER.openai)
+        return settings;
+    return {
+        ...settings,
+        providerData: {
+            ...(settings.providerData ?? {}),
+            service_tier: 'default',
+        },
+    };
+}
+/**
+ * Checks whether a failed agent attempt accumulated any potentially billable work.
+ *
+ * @param usage - Mutable Agents SDK usage collected during the attempt.
+ * @param hostedToolUsage - Completed hosted provider-tool calls for the attempt.
+ * @returns True when a failed-attempt child request should preserve usage.
+ */
+function hasBillableAgentAttemptUsage(usage, hostedToolUsage) {
+    return usage.requests > 0
+        || usage.inputTokens > 0
+        || usage.outputTokens > 0
+        || Object.values(hostedToolUsage).some(count => Number.isFinite(count) && count > 0);
+}
+/**
+ * Sums one token detail field across the SDK's aggregate detail records.
+ *
+ * @param details - Usage detail records.
+ * @param key - Detail key to sum.
+ * @returns Total when positive, otherwise null.
+ */
+function sumTokenDetails(details, key) {
+    const total = details.reduce((sum, detail) => {
+        const value = detail[key];
+        return typeof value === 'number' && Number.isFinite(value) ? sum + value : sum;
+    }, 0);
+    return total > 0 ? total : null;
+}
+/**
+ * Reads one token detail from an individual SDK request usage entry.
+ *
+ * @param details - Provider request token-detail record.
+ * @param key - Detail key to read.
+ * @returns Non-negative integer detail value, or null when absent.
+ */
+function tokenDetailValue(details, key) {
+    const value = details[key];
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? Math.trunc(value)
+        : null;
+}
+/**
+ * Normalizes finite numbers while preserving unknown usage values as null.
+ *
+ * @param value - Numeric usage value.
+ * @returns Integer usage value or null.
+ */
+function numberOrNull(value) {
+    return Number.isFinite(value) ? Math.trunc(value) : null;
+}
+/**
+ * Creates the public agent error payload for stream errors.
+ *
+ * @param error - Unknown error value.
+ * @param fallback - Fallback public error message.
+ * @returns Public stream error payload.
+ */
+function agentErrorPayload(error, fallback) {
+    return {
+        code: error instanceof AIAllowanceExceededError ? error.publicCode : undefined,
+        message: error instanceof Error && error.message ? error.message : fallback,
+        details: error instanceof AgentAuthorizationError ? undefined : errorDetails(error),
+    };
+}
+/**
+ * Returns safe developer-facing error details without including secrets.
+ *
+ * @param error - Unknown error value.
+ * @returns Safe error details.
+ */
+function errorDetails(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            stack: process.env.NODE_ENV === 'production' ? undefined : error.stack,
+        };
+    }
+    return error;
+}
+/**
+ * Safely narrows unknown values to object records.
+ *
+ * @param value - Unknown value.
+ * @returns Object record or null.
+ */
+function recordValue(value) {
+    return value !== null && typeof value === 'object' ? value : null;
+}
+/**
+ * Returns a string value when the unknown input is a non-empty string.
+ *
+ * @param value - Unknown value.
+ * @returns String value or null.
+ */
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Builds a stable frontend id for a prompt-context timeline item.
+ *
+ * @param aiRequestId - Persisted AI request id when available.
+ * @param traceId - Provider trace id used as a fallback.
+ * @returns Prompt-context timeline id.
+ */
+function promptContextId(aiRequestId, traceId) {
+    const id = aiRequestId === null || aiRequestId === undefined ? traceId : String(aiRequestId);
+    return `prompt_context:${id}`;
+}
+/**
+ * Serializes dates for stream events.
+ *
+ * @param value - Date value to serialize.
+ * @returns ISO timestamp.
+ */
+function dateString(value) {
+    return value instanceof Date ? value.toISOString() : new Date().toISOString();
+}
+/** Normalizes a trusted app context identity without requiring a particular user or tenant model. */
+function contextIdentity(value) {
+    if (typeof value === 'string')
+        return value;
+    return value?.id == null ? '' : String(value.id);
+}