@db3.ai/app 0.1.0-beta.1

package/src/ai/contracts/Providers.ts

@@ -0,0 +1,73 @@
+import type { AIProvider, AIProviderSelection } from './AI';
+
+/**
+ * Static connection settings for one OpenAI-compatible provider.
+ *
+ * Credentials and model defaults are resolved from environment variables by
+ * convention so adding a provider is a single registry entry.
+ */
+export interface AIProviderConfig {
+	/** Environment variable holding the provider API key. */
+	apiKeyEnv: string;
+	/** Environment variable overriding the provider base URL. */
+	baseUrlEnv: string;
+	/** Environment variable holding the provider default model, when provider-owned. */
+	modelEnv: string | null;
+	/** Public OpenAI-compatible base URL used when no override is set. */
+	defaultBaseUrl: string;
+	/** Whether the provider supports the OpenAI Responses API. Chat-completions-only providers can still run agents. */
+	supportsResponsesApi: boolean;
+}
+
+/**
+ * One resolved, fully configured provider attempt in a failover chain.
+ */
+export interface AIProviderAttempt {
+	/** Stable provider id persisted on tracking rows and bucket keys. */
+	provider: AIProvider;
+	/** Model sent to this provider. */
+	model: string;
+	/** API key for this provider. */
+	apiKey: string;
+	/** OpenAI-compatible base URL without an endpoint suffix. */
+	baseUrl: string;
+	/** Whether this provider can serve OpenAI Responses API requests. */
+	supportsResponsesApi: boolean;
+}
+
+/**
+ * Sanitized record of one failed provider attempt stored on AiRequest metadata.
+ */
+export interface AIProviderAttemptFailure {
+	/** Provider that failed. */
+	provider: AIProvider;
+	/** Model the failed attempt used. */
+	model: string;
+	/** HTTP status of the failure, when the provider responded. */
+	status: number | null;
+	/** Provider error code, when supplied. */
+	code: string | null;
+	/** Human-readable failure message. */
+	message: string;
+	/** Milliseconds spent on this attempt. */
+	durationMs: number;
+}
+
+/**
+ * OpenAI credentials resolved by the AI service from options and environment.
+ */
+export interface ResolvedOpenAIConnection {
+	apiKey: string;
+	baseUrl: string;
+	model: string;
+}
+
+/**
+ * Inputs needed to resolve a provider selection into ordered attempts.
+ */
+export interface ResolveProviderChainInput {
+	/** Selection from the call or agent, or null for the OpenAI-only default. */
+	selection: AIProviderSelection | null;
+	/** OpenAI connection resolved by the AI service, including per-call model. */
+	openai: ResolvedOpenAIConnection;
+}

package/src/ai/contracts/QuotaRetry.ts

@@ -0,0 +1,39 @@
+/**
+ * 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/src/ai/contracts/RateLimits.ts

@@ -0,0 +1,49 @@
+import type { AiRequest } from '../AiRequest';
+import type { AiRateLimitBucket, AiRateLimitEndpoint } from '../AiRateLimitBucket';
+import type { AiRateLimitReservation } from '../AiRateLimitReservation';
+import type { AIProvider } from './AI';
+
+/** 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/src/ai/contracts/ResponsesProviderCall.ts

@@ -0,0 +1,30 @@
+import type { AIProviderResponseMetadata } from './RateLimits';
+import type { TextResponsePayloadWithUsage } from './AI';
+
+/**
+ * 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/src/ai/contracts/index.ts

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

package/src/ai/examples/Conversation.ts

@@ -0,0 +1,12 @@
+import { AiConversation } from '@db3.ai/app/ai';
+import type { FieldBuilder } from '@db3.ai/app/db';
+
+/** App-owned conversation fields appear in normal ActiveRecord queries and migrations. */
+export class Conversation extends AiConversation {
+	/** Keeps the framework fields and adds an application label. */
+	static override fields(field: FieldBuilder) {
+		return { ...super.fields(field), topic: field.string({ default: 'support', index: true }) };
+	}
+
+	declare topic: string | null;
+}

package/src/ai/examples/HelpAgent.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { Agent, tool, type AgentTool, type BaseAgentContext } from '@db3.ai/app/ai';
+import { app } from '@db3.ai/app/server';
+
+/** Trusted context supplied by your route or job, never selected by the model. */
+export interface HelpAgentContext extends BaseAgentContext {
+	guidePath: string;
+}
+
+/** Answers questions using a help guide saved by your application. */
+export class HelpAgent extends Agent<HelpAgentContext> {
+	/** Gives the agent its task and source of truth. */
+	async instructions(): Promise<string> {
+		return 'Answer questions about this app using its saved help guide. Read the guide before answering. If the answer is absent, say so.';
+	}
+
+	/** Exposes one function with validated arguments and a server-selected file path. */
+	protected tools(): AgentTool[] {
+		return [Object.assign(tool({
+			name: 'read_help_guide',
+			description: 'Read the application help guide.',
+			parameters: z.object({}),
+			/** Reads only the file selected by trusted application code. */
+			execute: async () => app().storage.getText(this.context.guidePath),
+		}), { title: 'Read help guide', description: 'Read the application help guide.' })];
+	}
+}

package/src/ai/examples/createHelpImage.ts

@@ -0,0 +1,13 @@
+import { app } from '@db3.ai/app/server';
+
+/** Generates a PNG and records the application's storage reference on its AI request. */
+export async function createHelpImage(prompt: string, path: string) {
+	return app().ai.generateImage({ prompt, outputFormat: 'png' }, {
+		/** Saves bytes through the configured framework disk without exposing provider URLs. */
+		store: async ({ b64Json }) => {
+			const disk = app().storage.disk();
+			await disk.put(path, Buffer.from(b64Json, 'base64'), { mimeType: 'image/png' });
+			return { disk: disk.name, path };
+		},
+	});
+}

package/src/ai/index.ts

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

package/src/ai/registry.ts

@@ -0,0 +1,70 @@
+import type { SerializableClass, SerializedValueEnvelope } from '@db3.ai/app/serialization';
+import { app } from '../server/appContext';
+import type { Agent } from './Agent';
+import type { QueuedAgentRunPayload } from './contracts/Agent';
+
+/**
+ * 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: string,
+	AgentClass: SerializableClass<any, Agent>,
+): void {
+	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: string,
+	agent: Agent,
+): Promise<SerializedValueEnvelope> {
+
+	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: QueuedAgentRunPayload): Promise<Agent> {
+
+	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<Agent>(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/src/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/src/ai/toolCallRecovery.ts

@@ -0,0 +1,82 @@
+import { AI_MESSAGE_ROLE, AI_MESSAGE_TOOL_STATE, type AiMessage, type AiMessageToolState } 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: readonly AiMessage[]): Set<string> {
+	const calledIds = new Set<string>();
+	const completedIds = new Set<string>();
+
+	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: AiMessage, content: Record<string, unknown> | null): AiMessageToolState | null {
+	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: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+/**
+ * Normalizes a non-empty string value.
+ *
+ * @param value - Candidate string value.
+ * @returns Trimmed string, or null when unavailable.
+ */
+function stringValue(value: unknown): string | null {
+	return typeof value === 'string' && value.trim() ? value.trim() : null;
+}

package/src/ai/toolHelpers.ts

@@ -0,0 +1,145 @@
+import type { RunContext, ToolCallOutputContent } from '@openai/agents';
+import type { AgentRunContext, ToolResultBase } from './contracts/Agent';
+
+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 function agentToolContext<TContext = AgentRunContext>(runContext: RunContext<TContext> | undefined): TContext | null {
+	return runContext?.context ?? null;
+}
+
+/**
+ * Returns the stable tool-call id used by stream events and persisted messages.
+ */
+export function agentToolCallId(details: AgentToolDetails | undefined, fallback: string): string {
+	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<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> {
+	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: unknown, fallback: string): ToolResultBase {
+	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<TResult extends ToolResultBase>(
+	result: TResult,
+	attachments: ToolCallOutputContent[],
+): AgentToolModelOutput<TResult> {
+	return [
+		{
+			type: 'text',
+			text: JSON.stringify(result),
+		},
+		...attachments,
+	] as 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 function agentToolResultFromStructuredOutput(value: unknown): unknown | null {
+	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: unknown): string | null {
+	if (!Array.isArray(value)) return null;
+
+	for (const item of value) {
+		if (!item || typeof item !== 'object') continue;
+
+		const record = item as Record<string, unknown>;
+
+		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: string): unknown | null {
+	try {
+		return JSON.parse(value) as unknown;
+	} catch {
+		return null;
+	}
+}