@db3.ai/app 0.1.0-beta.1

package/dist/ai/Agent.d.ts

@@ -0,0 +1,633 @@
+import { type AgentOutputType, type ModelSettings } from '@openai/agents';
+import type * as queue from '@db3.ai/app/queue';
+import type { Serializable, SerializedValueEnvelope } from '@db3.ai/app/serialization';
+import { AiConversation } from './AiConversation.js';
+import { AiRequest } from './AiRequest.js';
+import { type AIProviderSelection } from './index.js';
+import type { AIUsageCharge } from './contracts/AI.js';
+import type * as agent from './contracts/Agent.js';
+/**
+ * Context passed into the complete provider-input builder.
+ */
+export interface AgentInputContext {
+    /** Current user or system task message. */
+    message: string;
+    /** Previous provider-compatible input items in conversation order. */
+    previousMessages: agent.AgentModelInput;
+}
+/**
+ * Shared persisted Agents SDK runtime for interactive and queued application agents.
+ */
+export declare abstract class Agent<TContext extends agent.BaseAgentContext = agent.BaseAgentContext> implements Serializable<TContext> {
+    protected readonly context: TContext;
+    protected readonly maxTurns: number;
+    protected readonly maxPreviousMessages: number;
+    /** Provider reasoning effort used for every run of this agent. */
+    protected readonly reasoningEffort: agent.AgentReasoningEffort | null;
+    protected readonly agentName: string;
+    protected readonly sdkAgentName: string;
+    protected readonly workflowName: string;
+    /** Optional agent-specific model. Omit to use the global `app().ai.model`. */
+    protected readonly model?: string;
+    private currentInput;
+    /**
+     * Creates a persisted agent runtime for the supplied app context.
+     *
+     * @param context - Trusted user, application scope, and optional conversation context.
+     */
+    constructor(context: TContext);
+    /**
+     * 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(): TContext;
+    /**
+     * 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: string): this;
+    /**
+     * Runs this agent through a live stream and emits normalized frontend events.
+     *
+     * @param message - Optional user or task input shortcut for this run.
+     * @param emit - Stream event sink used by the HTTP endpoint.
+     * @returns Completed run metadata and final output.
+     */
+    stream(message: string, emit?: agent.AgentEventSink): Promise<agent.AgentRunResult | null>;
+    stream(emit?: agent.AgentEventSink): Promise<agent.AgentRunResult | null>;
+    /** Runs this agent to completion, preserving the same history and tool lifecycle as stream(). */
+    run(message: string): Promise<agent.AgentRunResult>;
+    /** Generates and optionally stores an image under the active agent attempt. */
+    generateImage<TStored = unknown>(input: import('./contracts/AI.js').GenerateImageInput, options?: import('./contracts/AI.js').GenerateImageOptions<TStored>): Promise<import("./Ai.js").GenerateImageResult<TStored>>;
+    /** Generates an embedding under the active agent attempt. */
+    generateEmbedding(input: string, model?: string, options?: import('./contracts/AI.js').RequestLogOptions): Promise<import("./Ai.js").GenerateEmbeddingResult>;
+    /** Generates schema-validated output under the active agent attempt. */
+    generateStructured<TValue>(input: import('./contracts/AI.js').GenerateStructuredInput<TValue>, options?: import('./contracts/AI.js').AIResponseLogOptions): Promise<{
+        data: TValue;
+        aiRequestId: string | null;
+        aiResponseId: string | null;
+        conversationId: string | null;
+    }>;
+    /**
+     * Prepares and dispatches this agent to the queue for background execution.
+     *
+     * @param message - Optional user or task input shortcut for this run.
+     * @param options - Per-dispatch queue options. `options.queue` is the named queue/channel workers listen on, not the payload data.
+     * @returns Queued run identifiers for debug views and polling.
+     */
+    queue(message: string, options?: queue.DispatchOptions): Promise<agent.QueuedAgentRunResponse>;
+    queue(options?: queue.DispatchOptions): Promise<agent.QueuedAgentRunResponse>;
+    /** Serializes a registered agent before queue preparation creates audit records. */
+    protected serializeForQueue(): Promise<SerializedValueEnvelope>;
+    /**
+     * 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.
+     */
+    private resolveStreamInput;
+    /**
+     * 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.
+     */
+    private resolveQueueInput;
+    /**
+     * Returns the currently configured input message or throws before work starts.
+     *
+     * @returns Current run input message.
+     */
+    private resolvedInputMessage;
+    /**
+     * Resumes a prepared queued run from a worker process.
+     *
+     * @param payload - Queued agent run payload.
+     * @returns Completed run metadata and final output.
+     */
+    runQueued(payload: agent.QueuedAgentRunPayload): Promise<agent.AgentRunResult>;
+    /**
+     * 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.
+     */
+    private resumeFinalizedTrackedRun;
+    /**
+     * Returns the SDK tools that should be available for this agent run.
+     *
+     * @returns Agents SDK tools for this agent.
+     */
+    protected abstract tools(): agent.AgentTool[];
+    /**
+     * Returns the system instructions for this agent.
+     *
+     * @returns Promise resolving to the system instructions sent to the model and persisted for debugging.
+     */
+    abstract instructions(): Promise<string>;
+    /**
+     * Returns the reasoning summary mode for this agent, or null to keep it off.
+     *
+     * @returns Reasoning summary mode requested from the provider.
+     */
+    protected reasoningSummaryMode(): agent.AgentReasoningSummaryMode | 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.
+     */
+    protected outputType(): AgentOutputType | 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.
+     */
+    protected finalOutputText(finalOutput: unknown, streamedText: string): string;
+    /**
+     * 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.
+     */
+    protected afterFinalOutput(_state: agent.AgentPersistenceState, _finalOutput: unknown): Promise<Record<string, unknown> | 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.
+     */
+    protected structuredFinalOutput(finalOutput: unknown): unknown | 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.
+     */
+    protected buildInput(context: AgentInputContext): Promise<agent.AgentModelInput>;
+    /**
+     * Builds a provider-compatible user message.
+     *
+     * @param content - Message text to send as user input.
+     * @returns Agents SDK user message item.
+     */
+    protected userMessage(content: string): Extract<agent.AgentModelInputMessage, {
+        role: 'user';
+    }>;
+    /**
+     * Builds a provider-compatible system message.
+     *
+     * @param content - System context or instruction text.
+     * @returns Agents SDK system message item.
+     */
+    protected systemMessage(content: string): Extract<agent.AgentModelInputMessage, {
+        role: 'system';
+    }>;
+    /**
+     * Builds a provider-compatible assistant message.
+     *
+     * @param content - Assistant text from an earlier turn.
+     * @returns Agents SDK assistant message item.
+     */
+    protected assistantMessage(content: string): Extract<agent.AgentModelInputMessage, {
+        role: 'assistant';
+    }>;
+    /**
+     * 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.
+     */
+    protected queueMetadata(): Record<string, string>;
+    /**
+     * Builds the trace metadata for an SDK runner invocation.
+     *
+     * @param conversation - Conversation attached to the run.
+     * @returns Trace metadata sent to the Agents SDK.
+     */
+    protected traceMetadata(conversation: AiConversation): Record<string, string>;
+    /**
+     * 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.
+     */
+    protected toolRunContext(_state?: agent.AgentPersistenceState): Partial<agent.AgentRunContext>;
+    /**
+     * 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.
+     */
+    protected conversationMetadata(): Record<string, string | null>;
+    /**
+     * 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.
+     */
+    protected conversationAgentNames(): string[];
+    /**
+     * Builds the title for a newly created conversation.
+     *
+     * @param message - Initial message for the run.
+     * @returns Compact conversation title.
+     */
+    protected conversationTitle(message: string): string;
+    /**
+     * Resolves the model used by this agent run.
+     *
+     * @returns Agent-specific model or the global application model.
+     */
+    protected resolvedModel(): string;
+    /**
+     * 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.
+     */
+    protected usageCharge(): AIUsageCharge | 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.
+     */
+    private billableUsageCharge;
+    /**
+     * Returns the model settings shared by live execution and dry-run previews.
+     *
+     * @returns Agents SDK model settings for this agent.
+     */
+    protected modelSettings(): ModelSettings;
+    /**
+     * 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();
+     */
+    previewRequest(): Promise<Record<string, unknown>>;
+    /**
+     * 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.
+     */
+    private prepareAgentInvocation;
+    /**
+     * 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.
+     */
+    private sdkAgent;
+    /**
+     * 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.
+     */
+    private requestPreviewContext;
+    /**
+     * 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.
+     */
+    protected provider(): AIProviderSelection | 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.
+     */
+    private resolveConversation;
+    /**
+     * Throws when a requested conversation is not owned by this agent context.
+     *
+     * @param conversation - Existing conversation requested by the caller.
+     */
+    private assertConversationAccess;
+    /**
+     * 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.
+     */
+    private prepareRun;
+    /**
+     * Loads a prepared run from a queued payload.
+     *
+     * @param payload - Queued run payload.
+     * @returns Prepared run state for worker execution.
+     */
+    private preparedRunFromQueuedPayload;
+    /**
+     * 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.
+     */
+    private executePreparedRun;
+    /**
+     * 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.
+     */
+    private startTrackedAttempt;
+    /**
+     * 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.
+     */
+    private completeTrackedAttempt;
+    /**
+     * 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.
+     */
+    private failTrackedAttempt;
+    /**
+     * Persists sanitized failed provider attempts for auditing and debugging.
+     *
+     * @param state - Active run persistence state.
+     * @param failures - Failed attempts collected so far.
+     */
+    private recordProviderAttempts;
+    /**
+     * 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.
+     */
+    private acquireProviderCapacity;
+    /**
+     * 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.
+     */
+    private attachRateLimitBucket;
+    /**
+     * 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.
+     */
+    private attachPromptRequestPayload;
+    /**
+     * 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.
+     */
+    private promptContextEvent;
+    /**
+     * 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.
+     */
+    private startTrackedRun;
+    /**
+     * 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.
+     */
+    private sdkContext;
+    /**
+     * 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.
+     */
+    private streamEventFromSdkEvent;
+    /**
+     * 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.
+     */
+    private rawModelStreamEvent;
+    /**
+     * 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.
+     */
+    private reasoningSummaryCompletedEvent;
+    /**
+     * 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.
+     */
+    private toolCalledEvent;
+    /**
+     * Persists and emits a tool output event.
+     *
+     * @param state - Active run persistence state.
+     * @param item - SDK run item.
+     * @returns Tool success or error event.
+     */
+    private toolOutputEvent;
+    /**
+     * 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.
+     */
+    private saveMessage;
+    /**
+     * 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.
+     */
+    private completeTrackedRun;
+    /** Controls whether streamed events expose provider costs to this viewer. */
+    protected exposeProviderCosts(): boolean;
+    /** Aggregates provider usage; applications may extend this hook to settle their own credit ledger. */
+    protected settleUsage(rootAiRequest: AiRequest, _initialCharge: import('./contracts/AI.js').AIUsageCharge | null): Promise<{
+        run: import('./contracts/AiRequestRunCostSummary.js').AiRequestRunCostSummary;
+        creditCost: number | 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.
+     */
+    private settleFinalizedTrackedRun;
+    /**
+     * 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.
+     */
+    private deferTrackedRun;
+    /**
+     * 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.
+     */
+    private failTrackedRun;
+    /**
+     * 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.
+     */
+    private touchConversation;
+    /**
+     * 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.
+     */
+    protected previousMessages(conversation: AiConversation, excludeAiRequestId?: string | null): Promise<agent.AgentModelInput>;
+    /**
+     * Builds the queue payload for a prepared background run.
+     *
+     * @param prepared - Prepared run state.
+     * @param serializedAgent - Versioned constructor-state envelope.
+     * @returns Queue-safe payload.
+     */
+    private queuedRunPayload;
+    /**
+     * 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.
+     */
+    private markQueued;
+    /**
+     * 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.
+     */
+    private toolDefinition;
+    /**
+     * Returns the active user id as a string.
+     *
+     * @returns Active user id, or an empty string when unavailable.
+     */
+    protected userId(): string;
+    /**
+     * Returns the active application scope id as a string.
+     *
+     * @returns Active application scope id.
+     */
+    protected scopeId(): string;
+}
+/**
+ * Raised when a user asks for an inaccessible agent conversation.
+ */
+export declare class AgentAuthorizationError extends Error {
+    /**
+     * Creates an agent authorization error.
+     *
+     * @param message - Public error message.
+     */
+    constructor(message: string);
+}