@db3.ai/app 0.1.0-beta.1

package/dist/ai/contracts/QuotaRetry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Persisted quota retry metadata stored on the tracked AI request.
+ */
+export interface OpenAIQuotaRetryMetadata extends Record<string, unknown> {
+    /** Provider error code that triggered the deferral. */
+    code: string;
+    /** Number of quota deferrals recorded for this request. */
+    deferralCount: number;
+    /** First time quota exhaustion deferred this request. */
+    firstDeferredAt: string;
+    /** Most recent quota deferral time. */
+    lastDeferredAt: string;
+    /** Next scheduled provider attempt. */
+    retryAt: string;
+    /** Absolute time after which another quota failure becomes terminal. */
+    retryUntil: string;
+}
+/**
+ * Bounded exponential retry decision for one OpenAI quota failure.
+ */
+export interface OpenAIQuotaRetryDecision {
+    /** Provider error code that triggered quota handling. */
+    code: string;
+    /** Human-readable provider failure message. */
+    message: string;
+    /** Number of quota deferrals including the current failure. */
+    deferralCount: number;
+    /** Seconds before the next provider attempt. */
+    delaySeconds: number;
+    /** Absolute time of the next provider attempt. */
+    retryAt: Date;
+    /** Absolute time after which another quota failure becomes terminal. */
+    retryUntil: Date;
+    /** Whether the request has exhausted its quota-retry window. */
+    expired: boolean;
+    /** Metadata to persist on the tracked AI request. */
+    metadata: OpenAIQuotaRetryMetadata;
+}

package/dist/ai/contracts/QuotaRetry.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/RateLimits.d.ts

@@ -0,0 +1,45 @@
+import type { AiRequest } from '../AiRequest.js';
+import type { AiRateLimitBucket, AiRateLimitEndpoint } from '../AiRateLimitBucket.js';
+import type { AiRateLimitReservation } from '../AiRateLimitReservation.js';
+import type { AIProvider } from './AI.js';
+/** Provider operation and estimated capacity to reserve before external work begins. */
+export interface AIRateLimitAcquireInput {
+    provider?: AIProvider;
+    endpoint: AiRateLimitEndpoint;
+    model: string;
+    operation: string;
+    estimatedTokens?: number | null;
+    aiRequest?: AiRequest | null;
+}
+/** Reservation that must be settled or released after one provider operation. */
+export interface AIRateLimitLease {
+    bucketKey: string;
+    bucket: AiRateLimitBucket | null;
+    reservation: AiRateLimitReservation | null;
+    endpoint: AiRateLimitEndpoint;
+    model: string;
+    operation: string;
+}
+/** Provider-reported capacity and reset times observed from response headers. */
+export interface AIRateLimitSnapshot {
+    observedAt: string;
+    headers: Record<string, string>;
+    limitRequests: number | null;
+    remainingRequests: number | null;
+    requestsResetAfterMs: number | null;
+    requestsResetAt: string | null;
+    limitTokens: number | null;
+    remainingTokens: number | null;
+    tokensResetAfterMs: number | null;
+    tokensResetAt: string | null;
+    limitProjectTokens: number | null;
+    remainingProjectTokens: number | null;
+    projectTokensResetAfterMs: number | null;
+    projectTokensResetAt: string | null;
+}
+/** Provider request identity, processing time and observed rate-limit capacity. */
+export interface AIProviderResponseMetadata {
+    providerRequestId: string | null;
+    providerProcessingMs: number | null;
+    rateLimitSnapshot: AIRateLimitSnapshot | null;
+}

package/dist/ai/contracts/RateLimits.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/ResponsesProviderCall.d.ts

@@ -0,0 +1,28 @@
+import type { AIProviderResponseMetadata } from './RateLimits.js';
+import type { TextResponsePayloadWithUsage } from './AI.js';
+/**
+ * One OpenAI-compatible Responses API request against a specific provider.
+ */
+export interface ResponsesProviderCallInput {
+    /** Provider base URL without the /responses suffix. */
+    baseUrl: string;
+    /** Provider API key sent as a bearer token. */
+    apiKey: string;
+    /** Serialized Responses API request payload. */
+    request: Record<string, unknown>;
+    /** Fetch implementation used to send the request. */
+    fetcher: typeof fetch;
+}
+/**
+ * Raw transport result for one provider attempt, before tracking or error policy.
+ */
+export interface ResponsesProviderCallResult {
+    /** Whether the provider returned a 2xx response. */
+    ok: boolean;
+    /** HTTP status returned by the provider. */
+    status: number;
+    /** Parsed JSON payload, or null when the body was not JSON. */
+    payload: TextResponsePayloadWithUsage | null;
+    /** Parsed provider rate-limit and request-id headers. */
+    metadata: AIProviderResponseMetadata;
+}

package/dist/ai/contracts/ResponsesProviderCall.js

@@ -0,0 +1 @@
+export {};

package/dist/ai/contracts/index.d.ts

@@ -0,0 +1,8 @@
+export * from './AI.js';
+export * from './Agent.js';
+export * from './AiRequestRunCostSummary.js';
+export * from './Pricing.js';
+export * from './Providers.js';
+export * from './RateLimits.js';
+export * from './ResponsesProviderCall.js';
+export * from './QuotaRetry.js';

package/dist/ai/contracts/index.js

@@ -0,0 +1,8 @@
+export * from './AI.js';
+export * from './Agent.js';
+export * from './AiRequestRunCostSummary.js';
+export * from './Pricing.js';
+export * from './Providers.js';
+export * from './RateLimits.js';
+export * from './ResponsesProviderCall.js';
+export * from './QuotaRetry.js';

package/dist/ai/index.d.ts

@@ -0,0 +1,27 @@
+export * from './Ai.js';
+export * from './AIErrors.js';
+export * from './contracts/AI.js';
+export * from './AiConversation.js';
+export * from './AiMessage.js';
+export * from './AiRequest.js';
+export * from './AiRateLimitBucket.js';
+export * from './AiRateLimitReservation.js';
+export * from './AIFailover.js';
+export * from './AIProviders.js';
+export * from './AIQuotaDeferredError.js';
+export * from './AIRateLimiter.js';
+export * from './Estimates.js';
+export * from './Models.js';
+export * from './OpenAIProviderError.js';
+export * from './ProviderCosts.js';
+export * from './Agent.js';
+export * from './contracts/Agent.js';
+export * from './AgentRunJob.js';
+export * from './registry.js';
+export * from './toolHelpers.js';
+export * from './agentCitations.js';
+export * from './OpenAIQuotaRetry.js';
+export * from './ResponsesProviderCall.js';
+export { agentConversationTimeline } from './AgentHistory.js';
+export { tool, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
+export { INTERRUPTED_TOOL_CALL_MESSAGE, unresolvedToolCallIds } from './toolCallRecovery.js';

package/dist/ai/index.js

@@ -0,0 +1,27 @@
+export * from './Ai.js';
+export * from './AIErrors.js';
+export * from './contracts/AI.js';
+export * from './AiConversation.js';
+export * from './AiMessage.js';
+export * from './AiRequest.js';
+export * from './AiRateLimitBucket.js';
+export * from './AiRateLimitReservation.js';
+export * from './AIFailover.js';
+export * from './AIProviders.js';
+export * from './AIQuotaDeferredError.js';
+export * from './AIRateLimiter.js';
+export * from './Estimates.js';
+export * from './Models.js';
+export * from './OpenAIProviderError.js';
+export * from './ProviderCosts.js';
+export * from './Agent.js';
+export * from './contracts/Agent.js';
+export * from './AgentRunJob.js';
+export * from './registry.js';
+export * from './toolHelpers.js';
+export * from './agentCitations.js';
+export * from './OpenAIQuotaRetry.js';
+export * from './ResponsesProviderCall.js';
+export { agentConversationTimeline } from './AgentHistory.js';
+export { tool, webSearchTool, fileSearchTool, imageGenerationTool } from '@openai/agents';
+export { INTERRUPTED_TOOL_CALL_MESSAGE, unresolvedToolCallIds } from './toolCallRecovery.js';

package/dist/ai/registry.d.ts

@@ -0,0 +1,28 @@
+import type { SerializableClass, SerializedValueEnvelope } from '@db3.ai/app/serialization';
+import type { Agent } from './Agent.js';
+import type { QueuedAgentRunPayload } from './contracts/Agent.js';
+/**
+ * Registers one concrete agent class for durable reconstruction.
+ *
+ * Call this during application boot in both HTTP and worker processes.
+ *
+ * @param agentName - Stable persisted agent name.
+ * @param AgentClass - Constructor accepting the state returned by `toJSON()`.
+ * @returns Nothing.
+ */
+export declare function registerQueuedAgent(agentName: string, AgentClass: SerializableClass<any, Agent>): void;
+/**
+ * Serializes one agent before its queued run creates persistence side effects.
+ *
+ * @param agentName - Stable persisted agent name.
+ * @param agent - Concrete agent instance to serialize.
+ * @returns Versioned agent constructor-state envelope.
+ */
+export declare function serializeQueuedAgent(agentName: string, agent: Agent): Promise<SerializedValueEnvelope>;
+/**
+ * Rebuilds an agent instance from one queued run payload.
+ *
+ * @param payload - Queued run payload containing a serialized agent envelope.
+ * @returns Agent instance ready to resume the prepared run.
+ */
+export declare function queuedAgentFromPayload(payload: QueuedAgentRunPayload): Promise<Agent>;

package/dist/ai/registry.js

@@ -0,0 +1,49 @@
+import { app } from '../server/appContext.js';
+/**
+ * Registers one concrete agent class for durable reconstruction.
+ *
+ * Call this during application boot in both HTTP and worker processes.
+ *
+ * @param agentName - Stable persisted agent name.
+ * @param AgentClass - Constructor accepting the state returned by `toJSON()`.
+ * @returns Nothing.
+ */
+export function registerQueuedAgent(agentName, AgentClass) {
+    app().serializer.registry.registerClass(agentName, AgentClass);
+}
+/**
+ * Serializes one agent before its queued run creates persistence side effects.
+ *
+ * @param agentName - Stable persisted agent name.
+ * @param agent - Concrete agent instance to serialize.
+ * @returns Versioned agent constructor-state envelope.
+ */
+export async function serializeQueuedAgent(agentName, agent) {
+    if (!app().serializer.registry.classForName(agentName)) {
+        throw new Error(`No queued agent registered for "${agentName}".`);
+    }
+    const envelope = app().serializer.serialize(agent);
+    if (envelope.name !== agentName) {
+        throw new Error(`Serialized agent envelope "${envelope.name}" does not match "${agentName}".`);
+    }
+    return envelope;
+}
+/**
+ * Rebuilds an agent instance from one queued run payload.
+ *
+ * @param payload - Queued run payload containing a serialized agent envelope.
+ * @returns Agent instance ready to resume the prepared run.
+ */
+export async function queuedAgentFromPayload(payload) {
+    if (payload.agent.name !== payload.agentName) {
+        throw new Error(`Queued agent envelope "${payload.agent.name}" does not match "${payload.agentName}".`);
+    }
+    if (!app().serializer.registry.classForName(payload.agentName)) {
+        throw new Error(`No queued agent registered for "${payload.agentName}".`);
+    }
+    const restored = await app().serializer.deserialize(payload.agent);
+    if (!restored || typeof restored.runQueued !== 'function') {
+        throw new Error(`Registered queued agent "${payload.agentName}" did not restore an agent runtime.`);
+    }
+    return restored;
+}

package/dist/ai/sdkNodeCompatibility.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Type-only compatibility for the Agents SDK 0.12 Node shim.
+ *
+ * Its lifecycle classes promise the SDK's event-map interface but declare their
+ * implementation as Node's EventEmitter, whose conditional overloads are not
+ * assignable under strict TypeScript checking. Keep Node's other members and
+ * static helpers, while describing these four methods with the SDK contract.
+ * Runtime imports continue to resolve to the unmodified SDK and Node emitter.
+ *
+ * This file must remain an ambient script, not a module augmentation. Keep the
+ * declarations aligned with the pinned SDK and remove them when an unmodified
+ * SDK passes the packed consumer with skipLibCheck disabled.
+ */
+declare module '@openai/agents-core/_shims' {
+	import type { EventEmitter as NodeEventEmitter } from 'node:events';
+
+	/** Event names and their listener argument tuples, as defined by the SDK. */
+	export type EventEmitterEvents = Record<string, any[]>;
+
+	/** Common emitter interface used by SDK lifecycle and transport classes. */
+	export interface EventEmitter<Events extends EventEmitterEvents = Record<string, any[]>> {
+		/** Registers a listener for an event and returns the emitter. */
+		on<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): EventEmitter<Events>;
+		/** Removes a previously registered listener and returns the emitter. */
+		off<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): EventEmitter<Events>;
+		/** Invokes listeners with the event's argument tuple. */
+		emit<K extends keyof Events>(type: K, ...args: Events[K]): boolean;
+		/** Registers a listener that is removed after its first invocation. */
+		once<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): EventEmitter<Events>;
+	}
+
+	/** Node emitter instance with the event-map contract promised by the SDK. */
+	export interface RuntimeEventEmitter<Events extends EventEmitterEvents = Record<string, any[]>> extends Omit<NodeEventEmitter<Events>, keyof EventEmitter<Events>> {
+		/** Registers a typed listener while retaining Node's fluent instance API. */
+		on<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): this;
+		/** Removes a typed listener and returns the original Node instance. */
+		off<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): this;
+		/** Emits the argument tuple for a known SDK event. */
+		emit<K extends keyof Events>(type: K, ...args: Events[K]): boolean;
+		/** Registers a typed single-use listener and returns the Node instance. */
+		once<K extends keyof Events>(type: K, listener: (...args: Events[K]) => void): this;
+	}
+
+	/** Unmodified Node constructor and static helpers exported by the SDK. */
+	export const RuntimeEventEmitter: Pick<typeof NodeEventEmitter, Exclude<keyof typeof NodeEventEmitter, 'prototype'>> & {
+		/** Creates an emitter with the SDK's listener argument tuples. */
+		new <Events extends EventEmitterEvents = Record<string, any[]>>(options?: ConstructorParameters<typeof NodeEventEmitter>[0]): RuntimeEventEmitter<Events>;
+	};
+
+	export { Readable } from 'node:stream';
+	export { ReadableStream, ReadableStreamController, TransformStream } from 'node:stream/web';
+	export { AsyncLocalStorage } from 'node:async_hooks';
+	export { randomUUID } from 'node:crypto';
+	export { clearTimeout } from 'node:timers';
+	export { MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE } from '@openai/agents-core';
+
+	/** Node timer handle returned by the SDK's timer adapter. */
+	export type Timeout = NodeJS.Timeout;
+
+	/** Timer contract shared by the SDK runtime environments. */
+	export interface Timer {
+		/** Schedules the callback and returns its Node timer handle. */
+		setTimeout(callback: (...args: any[]) => any, ms: number): Timeout;
+		/** Cancels a timer previously created by the adapter. */
+		clearTimeout(timeoutId: Timeout | string | number | undefined): void;
+	}
+
+	/** Timer adapter used by the SDK's Node runtime. */
+	export const timer: Timer;
+	/** Returns the Node environment without changing it. */
+	export function loadEnv(): Record<string, string | undefined>;
+	/** Reports whether the Node tracing loop starts by default. */
+	export function isTracingLoopRunningByDefault(): boolean;
+	/** Reports whether the current SDK adapter is a browser runtime. */
+	export function isBrowserEnvironment(): boolean;
+}

package/dist/ai/toolCallRecovery.d.ts

@@ -0,0 +1,16 @@
+import { type AiMessage } from './AiMessage.js';
+/**
+ * User- and model-facing explanation for a persisted call with no saved result.
+ */
+export declare const INTERRUPTED_TOOL_CALL_MESSAGE = "This tool call was interrupted before a result was recorded. Ask the agent to try again if it is still needed.";
+/**
+ * Finds persisted function calls that have no matching success or error row.
+ *
+ * A server restart can leave the initial `calling` row durable while preventing
+ * the terminal row from being saved. Replaying that call without an output is
+ * invalid provider input, so restore boundaries treat it as interrupted.
+ *
+ * @param messages - Persisted conversation messages in any order.
+ * @returns Tool call ids that have a call row but no terminal result row.
+ */
+export declare function unresolvedToolCallIds(messages: readonly AiMessage[]): Set<string>;

package/dist/ai/toolCallRecovery.js

@@ -0,0 +1,71 @@
+import { AI_MESSAGE_ROLE, AI_MESSAGE_TOOL_STATE } from './AiMessage.js';
+/**
+ * User- and model-facing explanation for a persisted call with no saved result.
+ */
+export const INTERRUPTED_TOOL_CALL_MESSAGE = 'This tool call was interrupted before a result was recorded. Ask the agent to try again if it is still needed.';
+/**
+ * Finds persisted function calls that have no matching success or error row.
+ *
+ * A server restart can leave the initial `calling` row durable while preventing
+ * the terminal row from being saved. Replaying that call without an output is
+ * invalid provider input, so restore boundaries treat it as interrupted.
+ *
+ * @param messages - Persisted conversation messages in any order.
+ * @returns Tool call ids that have a call row but no terminal result row.
+ */
+export function unresolvedToolCallIds(messages) {
+    const calledIds = new Set();
+    const completedIds = new Set();
+    for (const message of messages) {
+        if (message.role !== AI_MESSAGE_ROLE.tool)
+            continue;
+        const content = recordValue(message.contentJson);
+        const callId = message.toolCallId || stringValue(content?.callId) || stringValue(content?.call_id);
+        const state = persistedToolState(message, content);
+        if (!callId || !state)
+            continue;
+        if (state === AI_MESSAGE_TOOL_STATE.calling) {
+            calledIds.add(callId);
+        }
+        else {
+            completedIds.add(callId);
+        }
+    }
+    return new Set([...calledIds].filter(callId => !completedIds.has(callId)));
+}
+/**
+ * Reads a supported tool lifecycle state from columns or legacy JSON content.
+ *
+ * @param message - Persisted tool message.
+ * @param content - Parsed structured message content.
+ * @returns Normalized tool state, or null when the row is 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;
+}
+/**
+ * Narrows an unknown JSON value to a plain record.
+ *
+ * @param value - Candidate JSON value.
+ * @returns Record value, or null for arrays and primitives.
+ */
+function recordValue(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Normalizes a non-empty string value.
+ *
+ * @param value - Candidate string value.
+ * @returns Trimmed string, or null when unavailable.
+ */
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}

package/dist/ai/toolHelpers.d.ts

@@ -0,0 +1,65 @@
+import type { RunContext, ToolCallOutputContent } from '@openai/agents';
+import type { AgentRunContext, ToolResultBase } from './contracts/Agent.js';
+type AgentToolDetails = {
+    toolCall?: {
+        callId?: string;
+        id?: string;
+    };
+};
+/**
+ * Structured tool output that keeps the UI result as JSON text while attaching
+ * additional model-visible content such as screenshots.
+ */
+export type AgentToolModelOutput<TResult extends ToolResultBase> = ToolCallOutputContent[] & {
+    readonly __agentToolResult?: TResult;
+};
+/**
+ * Returns the application context passed to an Agents SDK tool invocation.
+ *
+ * @param runContext - SDK invocation carrying the application's trusted context.
+ * @returns The original context with its application type preserved, or null.
+ */
+export declare function agentToolContext<TContext = AgentRunContext>(runContext: RunContext<TContext> | undefined): TContext | null;
+/**
+ * Returns the stable tool-call id used by stream events and persisted messages.
+ */
+export declare function agentToolCallId(details: AgentToolDetails | undefined, fallback: string): string;
+/**
+ * Emits a progress update for the active tool call when the run context is available.
+ *
+ * @param input - Tool identity, progress values and a context with a progress sink.
+ * @returns Promise that resolves after the application has received the update.
+ */
+export declare function emitAgentToolProgress<TContext extends Pick<AgentRunContext, 'emitToolProgress'>>(input: {
+    runContext: RunContext<TContext> | undefined;
+    details: AgentToolDetails | undefined;
+    toolName: string;
+    message: string;
+    current?: number;
+    total?: number;
+    data?: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Converts an unknown thrown value into a model-visible tool result.
+ */
+export declare function agentToolErrorResult(error: unknown, fallback: string): ToolResultBase;
+/**
+ * Builds a structured tool output with a JSON result and model-visible attachments.
+ *
+ * The first text item is intentionally kept JSON-compatible so application can
+ * persist and render the usual tool result without storing large attachment
+ * payloads in conversation history.
+ *
+ * @param result - UI and history result returned by the tool.
+ * @param attachments - Model-visible content attached to the tool output.
+ * @returns Structured Agents SDK tool output.
+ */
+export declare function agentToolOutputWithModelAttachments<TResult extends ToolResultBase>(result: TResult, attachments: ToolCallOutputContent[]): AgentToolModelOutput<TResult>;
+/**
+ * Extracts a JSON tool result from structured model-visible tool output.
+ *
+ * @param value - Tool output returned by the Agents SDK.
+ * @returns Parsed JSON result, or null when the output is not a JSON text attachment.
+ */
+export declare function agentToolResultFromStructuredOutput(value: unknown): unknown | null;
+export {};

package/dist/ai/toolHelpers.js

@@ -0,0 +1,106 @@
+/**
+ * Returns the application context passed to an Agents SDK tool invocation.
+ *
+ * @param runContext - SDK invocation carrying the application's trusted context.
+ * @returns The original context with its application type preserved, or null.
+ */
+export function agentToolContext(runContext) {
+    return runContext?.context ?? null;
+}
+/**
+ * Returns the stable tool-call id used by stream events and persisted messages.
+ */
+export function agentToolCallId(details, fallback) {
+    return details?.toolCall?.callId || details?.toolCall?.id || fallback;
+}
+/**
+ * Emits a progress update for the active tool call when the run context is available.
+ *
+ * @param input - Tool identity, progress values and a context with a progress sink.
+ * @returns Promise that resolves after the application has received the update.
+ */
+export async function emitAgentToolProgress(input) {
+    const context = agentToolContext(input.runContext);
+    if (!context)
+        return;
+    await context.emitToolProgress({
+        toolCallId: agentToolCallId(input.details, input.toolName),
+        toolName: input.toolName,
+        message: input.message,
+        current: input.current,
+        total: input.total,
+        data: input.data,
+    });
+}
+/**
+ * Converts an unknown thrown value into a model-visible tool result.
+ */
+export function agentToolErrorResult(error, fallback) {
+    return {
+        status: 'error',
+        message: error instanceof Error && error.message ? error.message : fallback,
+    };
+}
+/**
+ * Builds a structured tool output with a JSON result and model-visible attachments.
+ *
+ * The first text item is intentionally kept JSON-compatible so application can
+ * persist and render the usual tool result without storing large attachment
+ * payloads in conversation history.
+ *
+ * @param result - UI and history result returned by the tool.
+ * @param attachments - Model-visible content attached to the tool output.
+ * @returns Structured Agents SDK tool output.
+ */
+export function agentToolOutputWithModelAttachments(result, attachments) {
+    return [
+        {
+            type: 'text',
+            text: JSON.stringify(result),
+        },
+        ...attachments,
+    ];
+}
+/**
+ * Extracts a JSON tool result from structured model-visible tool output.
+ *
+ * @param value - Tool output returned by the Agents SDK.
+ * @returns Parsed JSON result, or null when the output is not a JSON text attachment.
+ */
+export function agentToolResultFromStructuredOutput(value) {
+    const text = structuredToolOutputText(value);
+    return text ? parseJson(text) : null;
+}
+/**
+ * Reads the first text item from structured tool output arrays.
+ *
+ * @param value - Tool output returned by the Agents SDK.
+ * @returns Text payload or null.
+ */
+function structuredToolOutputText(value) {
+    if (!Array.isArray(value))
+        return null;
+    for (const item of value) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        if ((record.type === 'text' || record.type === 'input_text') && typeof record.text === 'string') {
+            return record.text;
+        }
+    }
+    return null;
+}
+/**
+ * Parses JSON and returns null when the input is not valid JSON.
+ *
+ * @param value - JSON string to parse.
+ * @returns Parsed JSON value, or null.
+ */
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}