@standardagents/spec 0.11.0-next.af971ae → 0.11.0-next.c3b4490

package/dist/index.d.ts

@@ -1,159 +1,75 @@
-import { ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion, z } from 'zod';
+import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion, ZodTypeAny } from 'zod';
 
 /**
- * Model definition types for Standard Agents.
+ * Effect definition types for Standard Agents.
  *
- * Models define LLM configurations including provider, model ID, pricing,
- * and fallback chains. Models are referenced by name from prompts.
+ * Effects are scheduled operations that run outside the tool execution context.
+ * They enable implementation-specific side effects with optional delay support,
+ * leveraging the runtime's scheduling mechanism (e.g., Cloudflare Durable Object alarms).
+ *
+ * Unlike tools, effects:
+ * - Do not return results to the LLM
+ * - Can be delayed for future execution
+ * - Run independently of the conversation flow
+ * - Are ideal for notifications, cleanup, and async operations
  *
  * @module
  */
+
 /**
- * Supported LLM provider identifiers.
+ * Effect function signature.
+ *
+ * Effects are async functions that receive a ThreadState and
+ * optionally validated arguments. Unlike tools, they return void
+ * since results are not included in the conversation.
  *
- * Each provider requires a corresponding API key environment variable:
- * - `openai` → `OPENAI_API_KEY`
- * - `openrouter` → `OPENROUTER_API_KEY`
- * - `anthropic` → `ANTHROPIC_API_KEY`
- * - `google` → `GOOGLE_API_KEY`
- * - `test` → No API key required (for testing with scripted responses)
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for effect arguments, or null for no args
  */
-type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
+type Effect<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<void> | void : (state: State) => Promise<void> | void;
 /**
- * Model capability flags indicating supported features.
+ * Return type of defineEffect function.
+ *
+ * A tuple containing:
+ * - Effect description string
+ * - Argument schema (or null)
+ * - Effect implementation function
  */
-interface ModelCapabilities {
-    /**
-     * Whether the model supports vision (image understanding).
-     * When true, image attachments will be sent to the model as part of the request.
-     * Models like GPT-4o, Claude 3, and Gemini support vision.
-     */
-    vision?: boolean;
-    /**
-     * Whether the model supports function calling (tool use).
-     * Most modern models support this, defaults to true if not specified.
-     */
-    functionCalling?: boolean;
-    /**
-     * Whether the model supports structured outputs (JSON mode).
-     */
-    structuredOutputs?: boolean;
-}
+type EffectDefinition<State = ThreadState, Args extends ToolArgs | null = null> = [string, Args, Effect<State, Args>];
 /**
- * Model definition configuration.
- *
- * Defines an LLM model with its provider, pricing, capabilities, and fallback chain.
+ * Record of a scheduled effect.
  *
- * @template N - The model name as a string literal type for type inference
- *
- * @example
- * ```typescript
- * import { defineModel } from '@standardagents/spec';
- *
- * export default defineModel({
- *   name: 'gpt-4o',
- *   provider: 'openai',
- *   model: 'gpt-4o',
- *   fallbacks: ['gpt-4-turbo', 'gpt-3.5-turbo'],
- *   inputPrice: 2.5,
- *   outputPrice: 10,
- * });
- * ```
+ * Returned by getScheduledEffects() to inspect pending effects.
  */
-interface ModelDefinition<N extends string = string> {
-    /**
-     * Unique name for this model definition.
-     * Used as the identifier when referencing from prompts.
-     * Should be descriptive and consistent (e.g., 'gpt-4o', 'claude-3-opus').
-     */
-    name: N;
-    /**
-     * The LLM provider to use for API calls.
-     * The corresponding API key environment variable must be set.
-     */
-    provider: ModelProvider;
-    /**
-     * The actual model identifier sent to the provider API.
-     *
-     * For OpenAI: 'gpt-4o', 'gpt-4-turbo', 'gpt-3.5-turbo', etc.
-     * For OpenRouter: 'openai/gpt-4o', 'anthropic/claude-3-opus', etc.
-     * For Anthropic: 'claude-3-opus-20240229', 'claude-3-sonnet-20240229', etc.
-     * For Google: 'gemini-1.5-pro', 'gemini-1.5-flash', etc.
-     */
-    model: string;
-    /**
-     * Optional list of additional provider prefixes for OpenRouter.
-     * Allows routing through specific providers when using OpenRouter.
-     *
-     * @example ['anthropic', 'google'] - prefer Anthropic, fallback to Google
-     */
-    includedProviders?: string[];
-    /**
-     * Fallback model names to try if this model fails.
-     * Referenced by model name (must be defined in agents/models/).
-     * Tried in order after primary model exhausts retries.
-     *
-     * @example ['gpt-4', 'gpt-3.5-turbo']
-     */
-    fallbacks?: string[];
-    /**
-     * Cost per 1 million input tokens in USD.
-     * Used for cost tracking and reporting in logs.
-     */
-    inputPrice?: number;
-    /**
-     * Cost per 1 million output tokens in USD.
-     * Used for cost tracking and reporting in logs.
-     */
-    outputPrice?: number;
-    /**
-     * Cost per 1 million cached input tokens in USD.
-     * Some providers offer reduced pricing for cached/repeated prompts.
-     */
-    cachedPrice?: number;
-    /**
-     * Model capabilities - features this model supports.
-     */
-    capabilities?: ModelCapabilities;
+interface ScheduledEffect {
+    /** Unique identifier for this scheduled effect. */
+    id: string;
+    /** Name of the effect to execute. */
+    name: string;
+    /** Arguments to pass to the effect handler. */
+    args: Record<string, unknown>;
+    /** When the effect is scheduled to run (microseconds since epoch). */
+    scheduledAt: number;
+    /** When the effect was created (microseconds since epoch). */
+    createdAt: number;
 }
 /**
- * Defines an LLM model configuration.
- *
- * Models are the foundation of the agent system - they specify which
- * AI model to use and how to connect to it. Models can have fallbacks
- * for reliability and include pricing for cost tracking.
- *
- * @template N - The model name as a string literal type
- * @param options - Model configuration options
- * @returns The model definition for registration
- *
- * @example
- * ```typescript
- * // agents/models/gpt_4o.ts
- * import { defineModel } from '@standardagents/spec';
+ * Define an effect with arguments.
  *
- * export default defineModel({
- *   name: 'gpt-4o',
- *   provider: 'openai',
- *   model: 'gpt-4o',
- *   fallbacks: ['gpt-4-turbo'],
- *   inputPrice: 2.5,
- *   outputPrice: 10,
- * });
- * ```
+ * @param description - Description of what the effect does
+ * @param args - Zod schema for validating effect arguments
+ * @param handler - The effect implementation function
+ * @returns A tuple containing the effect definition
+ */
+declare function defineEffect<State = ThreadState, Args extends ToolArgs = ToolArgs>(description: string, args: Args, handler: Effect<State, Args>): EffectDefinition<State, Args>;
+/**
+ * Define an effect without arguments.
  *
- * @example
- * ```typescript
- * // Using OpenRouter with provider preferences
- * export default defineModel({
- *   name: 'claude-3-opus',
- *   provider: 'openrouter',
- *   model: 'anthropic/claude-3-opus',
- *   includedProviders: ['anthropic'],
- * });
- * ```
+ * @param description - Description of what the effect does
+ * @param handler - The effect implementation function
+ * @returns A tuple containing the effect definition
  */
-declare function defineModel<N extends string>(options: ModelDefinition<N>): ModelDefinition<N>;
+declare function defineEffect<State = ThreadState>(description: string, handler: Effect<State, null>): EffectDefinition<State, null>;
 
 /**
  * Thread state types for Standard Agents.
@@ -233,6 +149,10 @@ interface Message {
     silent?: boolean;
     /** Custom metadata */
     metadata?: Record<string, unknown>;
+    /** Message processing status */
+    status?: 'pending' | 'completed' | 'failed' | null;
+    /** Tool execution status (for tool result messages) */
+    tool_status?: 'success' | 'error' | null;
 }
 /**
  * Input for injecting a new message.
@@ -256,32 +176,6 @@ interface MessageUpdates {
     /** Updated metadata (merged with existing) */
     metadata?: Record<string, unknown>;
 }
-/**
- * Options for retrieving logs.
- */
-interface GetLogsOptions {
-    /** Maximum number of logs to return */
-    limit?: number;
-    /** Number of logs to skip */
-    offset?: number;
-    /** Sort order */
-    order?: 'asc' | 'desc';
-}
-/**
- * An execution log entry.
- */
-interface Log {
-    /** Unique log identifier */
-    id: string;
-    /** Log type (e.g., 'tool_call', 'llm_request', 'error') */
-    type: string;
-    /** Log data (structure varies by type) */
-    data: Record<string, unknown>;
-    /** Creation timestamp (microseconds since epoch) */
-    created_at: number;
-    /** Parent log ID (for nested operations) */
-    parent_id?: string | null;
-}
 /**
  * Storage location identifier.
  *
@@ -519,12 +413,15 @@ interface ThreadState {
      */
     updateMessage(messageId: string, updates: MessageUpdates): Promise<Message>;
     /**
-     * Get execution logs.
+     * Delete a message from the thread.
      *
-     * @param options - Query options
-     * @returns Array of log entries
+     * Removes the message and any associated attachments from storage.
+     * Tool call results are cascade-deleted when their parent message is removed.
+     *
+     * @param messageId - The message ID to delete
+     * @returns true if the message was found and deleted, false if not found
      */
-    getLogs(options?: GetLogsOptions): Promise<Log[]>;
+    deleteMessage(messageId: string): Promise<boolean>;
     /**
      * Load a model definition by name.
      *
@@ -590,6 +487,69 @@ interface ThreadState {
      * @returns The tool result
      */
     invokeTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Schedule an effect for future execution.
+     *
+     * Effects are executed outside the current conversation flow, making them
+     * ideal for delayed operations like sending notifications, triggering
+     * webhooks, or running cleanup tasks.
+     *
+     * @param name - Name of the effect to schedule (must exist in agents/effects/)
+     * @param args - Arguments to pass to the effect handler
+     * @param delay - Delay in milliseconds before execution (default: 0 for immediate)
+     * @returns Unique ID of the scheduled effect (UUID)
+     *
+     * @example
+     * ```typescript
+     * // Schedule a reminder email in 30 minutes
+     * const effectId = await state.scheduleEffect(
+     *   'send_reminder_email',
+     *   { to: 'user@example.com', subject: 'Reminder' },
+     *   30 * 60 * 1000
+     * );
+     * ```
+     */
+    scheduleEffect(name: string, args: Record<string, unknown>, delay?: number): Promise<string>;
+    /**
+     * Get scheduled effects for this thread.
+     *
+     * Returns effects that are pending execution. Can optionally filter
+     * by effect name.
+     *
+     * @param name - Optional effect name to filter by
+     * @returns Array of scheduled effect records
+     */
+    getScheduledEffects(name?: string): Promise<ScheduledEffect[]>;
+    /**
+     * Remove a scheduled effect.
+     *
+     * Cancels a pending effect before it executes. Has no effect if the
+     * effect has already executed or doesn't exist.
+     *
+     * @param id - The effect ID returned by scheduleEffect
+     * @returns true if the effect was found and removed, false otherwise
+     */
+    removeScheduledEffect(id: string): Promise<boolean>;
+    /**
+     * Trigger an agent to run on this thread.
+     *
+     * Starts a new agent execution asynchronously. This is useful for effects
+     * that need to trigger background agent work (e.g., running a finalizer
+     * agent after a delay).
+     *
+     * The agent runs in the background - this method returns immediately
+     * after queuing the execution.
+     *
+     * @param agentName - Name of the agent to run (must exist in agents/agents/)
+     * @returns Promise that resolves when the execution is queued
+     *
+     * @example
+     * ```typescript
+     * // In an effect handler, trigger a finalizer agent
+     * await state.runAgent('booking_finalizer');
+     * ```
+     */
+    runAgent(agentName: string): Promise<void>;
     /**
      * Emit a custom event to connected clients.
      *
@@ -711,197 +671,1092 @@ interface ThreadState {
      * @param path - Path to the image file
      * @returns Thumbnail data as ArrayBuffer, or null if not available
      */
-    getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
+    getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
+    /**
+     * Execution-specific state.
+     *
+     * This is present when the thread is actively executing (tools, hooks)
+     * and null when accessing a thread at rest (endpoints, external code).
+     *
+     * Use this to access step counts, force turns, or stop execution.
+     */
+    execution: ExecutionState | null;
+    /**
+     * Runtime-specific context that cannot be packed or shared.
+     *
+     * This property allows runtime implementations to inject non-portable
+     * context (e.g., Cloudflare env bindings, database connections).
+     *
+     * WARNING: Tools using this property cannot be packed, shared, or
+     * published as they depend on runtime-specific context.
+     */
+    readonly _notPackableRuntimeContext?: Record<string, unknown>;
+}
+
+/**
+ * Tool definition types for Standard Agents.
+ *
+ * Tools are callable functions that agents can invoke during execution.
+ * They receive the current ThreadState and validated arguments,
+ * and return results that are included in the conversation.
+ *
+ * @module
+ */
+
+/**
+ * Text content item returned by tools.
+ */
+interface TextContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * Image content item returned by tools.
+ */
+interface ImageContent {
+    type: 'image';
+    /** Base64-encoded image data. */
+    data: string;
+    /** MIME type of the image (e.g., 'image/png', 'image/jpeg'). */
+    mimeType: string;
+}
+/**
+ * Content types that can be returned by tools.
+ */
+type ToolContent = TextContent | ImageContent;
+/**
+ * File attachment generated by a tool.
+ *
+ * Attachments are stored in the thread's file system and linked to
+ * the tool result message. Unlike user uploads, tool attachments are
+ * not subject to image downsampling.
+ */
+interface ToolAttachment {
+    /** File name for the attachment. */
+    name: string;
+    /** MIME type of the attachment. */
+    mimeType: string;
+    /** Base64-encoded file data. */
+    data: string;
+    /** Width in pixels (for images). */
+    width?: number;
+    /** Height in pixels (for images). */
+    height?: number;
+}
+/**
+ * Reference to a pre-existing attachment in the thread file system.
+ */
+interface AttachmentRef {
+    /** Unique identifier for the attachment. */
+    id: string;
+    /** Attachment type. */
+    type: 'file';
+    /** Path in the thread file system. */
+    path: string;
+    /** File name. */
+    name: string;
+    /** MIME type. */
+    mimeType: string;
+    /** File size in bytes. */
+    size: number;
+    /** Width in pixels (for images). */
+    width?: number;
+    /** Height in pixels (for images). */
+    height?: number;
+    /** AI-generated description. */
+    description?: string;
+}
+/**
+ * Result returned by a tool execution.
+ */
+interface ToolResult {
+    /** Status of the tool execution. */
+    status: 'success' | 'error';
+    /**
+     * Text representation of the tool output.
+     *
+     * For tools that return structured content, this is derived by
+     * concatenating all text parts. For simple tools, this is the
+     * direct result string.
+     */
+    result?: string;
+    /** Error message if status is 'error'. */
+    error?: string;
+    /** Stack trace for error debugging. */
+    stack?: string;
+    /**
+     * File attachments returned by the tool.
+     *
+     * Can contain either:
+     * - ToolAttachment: New files with base64 data to be stored
+     * - AttachmentRef: References to existing files in the thread filesystem
+     *
+     * Implementations MUST store new attachments under /attachments/ directory.
+     */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
+}
+/** Decrement helper to limit recursion depth. */
+type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
+/**
+ * Allowed Zod types for tool argument nodes.
+ *
+ * This is the single source of truth for which Zod types can be used
+ * in tool argument schemas. The depth parameter limits recursion to
+ * prevent infinite type expansion.
+ *
+ * @template D - Maximum nesting depth (default: 7)
+ */
+type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodEnum<Readonly<Record<string, string>>> | (D extends 0 ? never : ZodOptional<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodNullable<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodDefault<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodArray<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodObject<Record<string, ToolArgsNode<Dec<D>>>>) | (D extends 0 ? never : ZodRecord<ZodString, ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodUnion<[
+    ToolArgsNode<Dec<D>>,
+    ToolArgsNode<Dec<D>>,
+    ...ToolArgsNode<Dec<D>>[]
+]>);
+/**
+ * Raw shape for a Zod object schema containing tool argument nodes.
+ *
+ * @template D - Maximum nesting depth (default: 7)
+ */
+type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
+/**
+ * Top-level tool argument schema.
+ *
+ * Tool arguments MUST be defined as a Zod object schema.
+ * This is required for compatibility with OpenAI's function calling API.
+ *
+ * @template D - Maximum nesting depth (default: 7)
+ */
+type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
+/**
+ * Raw shape for tenv schema - uses same pattern as ToolArgsRawShape.
+ * Each key is a tenv name, value is a Zod schema for validation.
+ *
+ * @template D - Maximum nesting depth (default: 7)
+ */
+type TenvRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
+/**
+ * Top-level thread environment variable schema.
+ *
+ * Defines which thread environment variables a tool requires.
+ * Required tenvs are non-optional fields, optional tenvs use .optional().
+ *
+ * @example
+ * ```typescript
+ * z.object({
+ *   vectorStoreId: z.string().describe('OpenAI Vector Store ID'),        // Required
+ *   userLocation: z.string().optional().describe('User location'),       // Optional
+ * })
+ * ```
+ *
+ * @template D - Maximum nesting depth (default: 7)
+ */
+type ToolTenvs<D extends number = 7> = z.ZodObject<TenvRawShape<D>>;
+/**
+ * Tool function signature.
+ *
+ * Tools are async functions that receive a ThreadState and
+ * optionally validated arguments, returning a ToolResult.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
+ */
+type Tool<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<ToolResult> : (state: State) => Promise<ToolResult>;
+/**
+ * Options for defining a tool.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
+ * @template Tenvs - The Zod schema for thread environment variables, or null
+ */
+interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null> {
+    /** Description of what the tool does (shown to the LLM). */
+    description: string;
+    /** Zod schema for validating tool arguments. Omit for tools with no args. */
+    args?: Args;
+    /** The tool implementation function. */
+    execute: Tool<State, Args>;
+    /** Zod schema for thread environment variables the tool requires. */
+    tenvs?: Tenvs;
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider').
+     * e.g., 'openai', 'anthropic'
+     */
+    executionProvider?: string;
+}
+/**
+ * Tool definition object returned by defineTool().
+ *
+ * Contains all the metadata and implementation needed to register
+ * and execute a tool.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Args - The Zod schema for tool arguments, or null for no args
+ * @template Tenvs - The Zod schema for thread environment variables, or null
+ */
+interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null> {
+    /** Description of what the tool does (shown to the LLM). */
+    description: string;
+    /** Zod schema for validating tool arguments, or null for no args. */
+    args: Args;
+    /** The tool implementation function. */
+    execute: Tool<State, Args>;
+    /** Zod schema for thread environment variables, or null if none. */
+    tenvs: Tenvs;
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider').
+     */
+    executionProvider?: string;
+}
+/**
+ * Defines a tool that agents can call during execution.
+ *
+ * Tools are the primary way agents interact with external systems.
+ * Each tool has a description (shown to the LLM), optional argument
+ * schema (validated at runtime), an implementation function, and
+ * optional thread environment variable (tenv) requirements.
+ *
+ * @example
+ * ```typescript
+ * import { defineTool } from '@standardagents/spec';
+ * import { z } from 'zod';
+ *
+ * // Tool with arguments
+ * export default defineTool({
+ *   description: 'Search the knowledge base for relevant information',
+ *   args: z.object({
+ *     query: z.string().describe('Search query'),
+ *     limit: z.number().optional().describe('Max results'),
+ *   }),
+ *   execute: async (state, args) => {
+ *     const results = await search(args.query, args.limit);
+ *     return { status: 'success', result: JSON.stringify(results) };
+ *   },
+ * });
+ *
+ * // Tool without arguments
+ * export default defineTool({
+ *   description: 'Get the current server time',
+ *   execute: async (state) => {
+ *     return { status: 'success', result: new Date().toISOString() };
+ *   },
+ * });
+ *
+ * // Tool with tenvs (thread environment variables)
+ * export default defineTool({
+ *   description: 'Search through uploaded files',
+ *   args: z.object({ query: z.string() }),
+ *   execute: async (state, args) => ({ status: 'success', result: 'done' }),
+ *   tenvs: z.object({
+ *     vectorStoreId: z.string().describe('OpenAI Vector Store ID'),
+ *   }),
+ * });
+ *
+ * // Provider-executed tool (e.g., OpenAI built-in tools)
+ * export default defineTool({
+ *   description: 'Generate images using DALL-E',
+ *   args: z.object({ prompt: z.string() }),
+ *   execute: async () => ({ status: 'success', result: 'Handled by provider' }),
+ *   executionMode: 'provider',
+ *   executionProvider: 'openai',
+ * });
+ * ```
+ *
+ * @param options - Tool definition options
+ * @returns A tool definition object
+ */
+declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null>(options: DefineToolOptions<State, Args, Tenvs>): ToolDefinition<State, Args, Tenvs>;
+
+/**
+ * Provider types for Standard Agents.
+ *
+ * These types define the interface between Standard Agents and LLM providers.
+ * Provider packages implement these types to integrate with different LLM APIs.
+ *
+ * @module
+ */
+
+/**
+ * Stripped-down response summary for async metadata fetching.
+ * Intentionally excludes content/attachments to avoid passing large data.
+ */
+interface ResponseSummary {
+    /** Provider-specific response/generation ID */
+    responseId?: string;
+    /** Model that handled the request */
+    model: string;
+    /** How the response ended */
+    finishReason: ProviderFinishReason;
+    /** Token usage (without detailed breakdowns) */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Model information returned by provider's getModels method.
+ */
+interface ProviderModelInfo {
+    /** The model identifier used in API calls (e.g., 'gpt-4o', 'anthropic/claude-3-opus') */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Optional description of the model */
+    description?: string;
+    /** Optional context window size in tokens */
+    contextLength?: number;
+    /** Optional icon identifier for UI display */
+    iconId?: string;
+    /** Optional slug for additional lookups (e.g., OpenRouter endpoint queries) */
+    slug?: string;
+}
+/**
+ * Provider interface - thin translation layer between Standard Agents and LLM APIs
+ */
+interface LLMProviderInterface {
+    readonly name: string;
+    readonly specificationVersion: '1';
+    /**
+     * Non-streaming generation
+     */
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * Streaming generation
+     */
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
+    /**
+     * Check if this provider supports a model
+     */
+    supportsModel?(modelId: string): boolean;
+    /**
+     * List available models from this provider.
+     * Optional for backwards compatibility - providers may implement this
+     * to enable model selection in the UI.
+     *
+     * @param filter - Optional search string to filter models by name/id
+     * @returns Array of available models
+     */
+    getModels?(filter?: string): Promise<ProviderModelInfo[]>;
+    /**
+     * Fetch capabilities for a specific model.
+     * Optional for backwards compatibility - providers may implement this
+     * to enable auto-detection of model features in the UI.
+     *
+     * @param modelId - The model identifier (e.g., 'gpt-4o', 'anthropic/claude-3-opus')
+     * @returns The model capabilities, or null if not available
+     */
+    getModelCapabilities?(modelId: string): Promise<ModelCapabilities | null>;
+    /**
+     * Get tools embedded in this provider.
+     * Optional - providers may implement this to expose built-in tools
+     * (e.g., OpenAI's web_search, file_search, code_interpreter).
+     *
+     * These tools are defined using defineTool() with optional tenv requirements.
+     * Tools returned here can be referenced by name in model/prompt definitions.
+     *
+     * @param modelId - Optional filter to get tools available for a specific model
+     * @returns Record of tool name to tool definition (sync or async)
+     */
+    getTools?(modelId?: string): Record<string, ToolDefinition<any, ToolArgs | null, ToolTenvs | null>> | Promise<Record<string, ToolDefinition<any, ToolArgs | null, ToolTenvs | null>>>;
+    /**
+     * Get an icon for this provider or a specific model.
+     * Optional - providers may implement this to provide UI icons.
+     *
+     * **Preferred return format: SVG data URI** (e.g., 'data:image/svg+xml,...')
+     *
+     * The data URI format allows icons to be embedded directly in the UI without
+     * additional network requests. Use the `svgToDataUri()` helper from provider
+     * packages to convert SVG strings.
+     *
+     * Return value can be:
+     * - A data URI (e.g., 'data:image/svg+xml,...') - **PREFERRED**
+     * - A full URL (e.g., 'https://example.com/icon.svg')
+     * - An icon identifier that the UI resolves (legacy)
+     *
+     * For providers like OpenRouter that host many models, the modelId parameter
+     * allows returning different icons based on the model's origin lab
+     * (e.g., 'anthropic/claude-3-opus' -> anthropic icon).
+     *
+     * @param modelId - Optional model ID to get a model-specific icon
+     * @returns SVG data URI (preferred), URL, icon identifier, or undefined
+     *
+     * @example
+     * ```typescript
+     * // Provider returning its own icon
+     * getIcon() {
+     *   return svgToDataUri(OPENAI_ICON);
+     * }
+     *
+     * // Provider returning model-specific icon (e.g., OpenRouter)
+     * getIcon(modelId?: string) {
+     *   if (modelId) {
+     *     const lab = modelId.split('/')[0]; // 'anthropic' from 'anthropic/claude-3'
+     *     return getLabIconDataUri(lab);
+     *   }
+     *   return svgToDataUri(OPENROUTER_ICON);
+     * }
+     * ```
+     */
+    getIcon?(modelId?: string): string | undefined;
+    /**
+     * Transform a ProviderRequest to the provider's native format for inspection/debugging.
+     * Returns the transformed request as it would be sent to the provider's API.
+     *
+     * This is used by the admin UI to view logged requests in provider-specific format,
+     * helping debug issues like message transformation or tool handling.
+     *
+     * Implementations should truncate base64 data to ~50 chars for readability.
+     *
+     * @param request - The Standard Agents format request to transform
+     * @returns The transformed request in the provider's native format
+     */
+    inspectRequest?(request: ProviderRequest): Promise<InspectedRequest>;
+    /**
+     * Fetch additional metadata about a completed response.
+     * Called asynchronously after the response is received - does not block the main execution flow.
+     *
+     * This is useful for providers (like aggregators) where complete metadata isn't available
+     * immediately. The execution engine calls this in the background and uses the returned
+     * data to update log records.
+     *
+     * @param summary - Stripped-down response info (no content/attachments)
+     * @param signal - Optional abort signal for cancellation
+     * @returns Additional metadata or null if unavailable
+     */
+    getResponseMetadata?(summary: ResponseSummary, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Result from inspectRequest() - the transformed request in provider's native format
+ */
+interface InspectedRequest {
+    /** The transformed request body as it would be sent to the API */
+    body: Record<string, unknown>;
+    /** Path to the messages array within body (e.g., "input" for OpenAI, "messages" for others) */
+    messagesPath: string;
+    /** Optional: Additional metadata about the transformation */
+    metadata?: {
+        /** The API endpoint that would be called */
+        endpoint?: string;
+        /** Headers that would be sent (excluding auth) */
+        headers?: Record<string, string>;
+    };
+}
+/**
+ * Standard Agent request format - providers translate to their native format
+ */
+interface ProviderRequest {
+    model: string;
+    messages: ProviderMessage[];
+    tools?: ProviderTool[];
+    toolChoice?: 'auto' | 'none' | 'required' | {
+        name: string;
+    };
+    parallelToolCalls?: boolean;
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    stopSequences?: string[];
+    reasoning?: {
+        level?: number;
+        maxTokens?: number;
+        exclude?: boolean;
+    };
+    responseFormat?: {
+        type: 'text';
+    } | {
+        type: 'json';
+        schema?: Record<string, unknown>;
+    };
+    signal?: AbortSignal;
+    providerOptions?: Record<string, unknown>;
+}
+type ProviderMessage = ProviderSystemMessage | ProviderUserMessage | ProviderAssistantMessage | ProviderToolMessage;
+interface ProviderSystemMessage {
+    role: 'system';
+    content: string;
+}
+interface ProviderUserMessage {
+    role: 'user';
+    content: ProviderMessageContent;
+}
+interface ProviderAssistantMessage {
+    role: 'assistant';
+    content?: string | null;
+    reasoning?: string | null;
+    reasoningDetails?: ProviderReasoningDetail[];
+    toolCalls?: ProviderToolCallPart[];
+}
+interface ProviderToolMessage {
+    role: 'tool';
+    toolCallId: string;
+    toolName: string;
+    content: ProviderToolResultContent;
+    attachments?: ProviderAttachment[];
+}
+/**
+ * Attachment on a provider message (loaded from storage, ready for provider-specific transformation)
+ */
+interface ProviderAttachment {
+    type: 'image' | 'file';
+    data: string;
+    mediaType: string;
+    name?: string;
+    path?: string;
+}
+type ProviderMessageContent = string | ContentPart[];
+type ContentPart = TextPart | ImagePart | ImageUrlPart | FilePart;
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+interface ImagePart {
+    type: 'image';
+    data: string;
+    mediaType: string;
+    detail?: 'auto' | 'low' | 'high';
+}
+/**
+ * Image URL content part (OpenAI/OpenRouter format).
+ * Used for passing image URLs directly to providers.
+ */
+interface ImageUrlPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+interface FilePart {
+    type: 'file';
+    data: string;
+    mediaType: string;
+    filename?: string;
+}
+interface ProviderTool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters?: Record<string, unknown>;
+    };
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider')
+     * e.g., 'openai', 'anthropic'
+     */
+    executionProvider?: string;
+}
+interface ProviderToolCallPart {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+type ProviderToolResultContent = string | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'error';
+    error: string;
+} | ContentPart[];
+interface ProviderResponse {
+    content: string | null;
+    reasoning?: string | null;
+    reasoningDetails?: ProviderReasoningDetail[];
+    toolCalls?: ProviderToolCallPart[];
+    images?: ProviderGeneratedImage[];
+    finishReason: ProviderFinishReason;
+    usage: ProviderUsage;
+    metadata?: Record<string, unknown>;
+}
+type ProviderFinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+interface ProviderUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    reasoningTokens?: number;
+    cachedTokens?: number;
+    cost?: number;
+    /** The actual provider that fulfilled the request (e.g., 'google', 'anthropic') */
+    provider?: string;
+}
+interface ProviderGeneratedImage {
+    /** Unique ID for this generated image (used to link to tool call) */
+    id?: string;
+    /** Name of the tool that generated this image (e.g., 'image_generation') */
+    toolName?: string;
+    data: string;
+    mediaType: string;
+    revisedPrompt?: string;
+}
+interface ProviderReasoningDetail {
+    type: 'summary' | 'encrypted' | 'text';
+    /** Original reasoning ID from provider (e.g., rs_xxx for OpenAI) */
+    id?: string;
+    text?: string;
+    data?: string;
+}
+/**
+ * Web search result from provider
+ */
+interface ProviderWebSearchResult {
+    /** Unique ID of the web search call */
+    id: string;
+    /** Status of the search */
+    status: 'in_progress' | 'searching' | 'completed' | 'failed';
+    /** Search actions performed */
+    actions?: Array<{
+        type: 'search' | 'open_page' | 'find';
+        query?: string;
+        url?: string;
+        pattern?: string;
+        sources?: Array<{
+            type: 'url';
+            url: string;
+            title?: string;
+        }>;
+    }>;
+}
+type ProviderStreamChunk = {
+    type: 'content-delta';
+    delta: string;
+} | {
+    type: 'content-done';
+} | {
+    type: 'reasoning-delta';
+    delta: string;
+} | {
+    type: 'reasoning-done';
+} | {
+    type: 'tool-call-start';
+    id: string;
+    name: string;
+} | {
+    type: 'tool-call-delta';
+    id: string;
+    argumentsDelta: string;
+} | {
+    type: 'tool-call-done';
+    id: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'image-delta';
+    index: number;
+    data: string;
+} | {
+    type: 'image-done';
+    index: number;
+    image: ProviderGeneratedImage;
+} | {
+    type: 'web-search-done';
+    result: ProviderWebSearchResult;
+} | {
+    type: 'finish';
+    finishReason: ProviderFinishReason;
+    usage: ProviderUsage;
+    reasoningDetails?: ProviderReasoningDetail[];
+} | {
+    type: 'error';
+    error: string;
+    code?: string;
+};
+type ProviderErrorCode = 'rate_limit' | 'invalid_request' | 'auth_error' | 'server_error' | 'timeout' | 'unknown';
+declare class ProviderError extends Error {
+    code: ProviderErrorCode;
+    statusCode?: number | undefined;
+    retryAfter?: number | undefined;
+    constructor(message: string, code: ProviderErrorCode, statusCode?: number | undefined, retryAfter?: number | undefined);
+    /**
+     * Whether this error is retryable
+     */
+    get isRetryable(): boolean;
+}
+/**
+ * Maps a 0-100 reasoning level to the model's nearest supported level
+ */
+declare function mapReasoningLevel(level: number, reasoningLevels: Record<number, string | null> | undefined): string | null;
+
+/**
+ * Model definition types for Standard Agents.
+ *
+ * Models define LLM configurations including provider, model ID, pricing,
+ * and fallback chains. Models are referenced by name from prompts.
+ *
+ * @module
+ */
+
+/**
+ * Legacy provider identifiers - kept for reference only.
+ * New code should use ProviderFactory imports from provider packages.
+ *
+ * @deprecated Use ProviderFactory from provider packages instead
+ * @internal
+ */
+type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
+/**
+ * Provider interface for LLM providers.
+ *
+ * Provider packages export a factory function that creates instances
+ * implementing this interface. This is structurally compatible with
+ * LLMProviderInterface from providers.ts.
+ */
+interface ProviderInstance {
+    readonly name: string;
+    readonly specificationVersion: '1';
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
+    supportsModel?(modelId: string): boolean;
+    /** List available models from this provider */
+    getModels?(filter?: string): Promise<ProviderModelInfo[]>;
+    /** Fetch capabilities for a specific model */
+    getModelCapabilities?(modelId: string): Promise<ModelCapabilities | null>;
+    /** Get provider-specific tools available for a model */
+    getTools?(modelId?: string): Record<string, ToolDefinition<unknown, ToolArgs | null, ToolTenvs | null>> | Promise<Record<string, ToolDefinition<unknown, ToolArgs | null, ToolTenvs | null>>>;
+    /** Get the icon URL for this provider or a specific model */
+    getIcon?(modelId?: string): string | undefined;
+    /** Inspect a raw request for debugging purposes */
+    inspectRequest?(request: ProviderRequest): Promise<InspectedRequest>;
+    /** Fetch additional metadata about a completed response */
+    getResponseMetadata?(summary: ResponseSummary, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
+}
+/**
+ * Configuration passed to provider factory functions.
+ */
+interface ProviderFactoryConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+/**
+ * Provider factory with optional typed providerOptions schema.
+ *
+ * The schema property allows type inference and runtime validation of
+ * provider-specific options in model definitions.
+ *
+ * @template TOptions - Zod schema type for providerOptions (defaults to ZodTypeAny)
+ *
+ * @example
+ * ```typescript
+ * import { openai } from '@standardagents/openai';
+ *
+ * // openai is a ProviderFactoryWithOptions with typed schema
+ * const provider = openai({ apiKey: 'sk-...' });
+ *
+ * // Access the schema for validation
+ * openai.providerOptions?.parse({ service_tier: 'default' });
+ * ```
+ */
+interface ProviderFactoryWithOptions<TOptions extends ZodTypeAny = ZodTypeAny> {
+    (config: ProviderFactoryConfig): ProviderInstance;
+    /** Zod schema for provider-specific options */
+    providerOptions?: TOptions;
+}
+/**
+ * Factory function that creates provider instances.
+ *
+ * Provider packages (like @standardagents/openai) export this type.
+ * This is an alias for ProviderFactoryWithOptions for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * import { openai } from '@standardagents/openai';
+ *
+ * // openai is a ProviderFactory
+ * const provider = openai({ apiKey: 'sk-...' });
+ * ```
+ */
+type ProviderFactory = ProviderFactoryWithOptions<ZodTypeAny>;
+/**
+ * Extract providerOptions type from a provider factory.
+ *
+ * Returns the inferred input type from the provider's Zod schema,
+ * or Record<string, unknown> if no schema is defined.
+ *
+ * @template P - Provider factory type
+ */
+type InferProviderOptions<P> = P extends ProviderFactoryWithOptions<infer S> ? S extends ZodTypeAny ? z.input<S> extends Record<string, unknown> ? z.input<S> : Record<string, unknown> : Record<string, unknown> : Record<string, unknown>;
+/**
+ * Model capability flags indicating supported features.
+ *
+ * These capabilities are used by the FlowEngine to determine how to
+ * interact with the model and what features are available.
+ */
+interface ModelCapabilities {
+    /**
+     * Reasoning level mapping (0-100 scale → model-specific values).
+     * Keys are breakpoints, values are model's native reasoning strings.
+     *
+     * @example
+     * // OpenAI o-series
+     * reasoningLevels: { 0: null, 33: 'low', 66: 'medium', 100: 'high' }
+     *
+     * @example
+     * // Binary reasoning (Claude extended thinking)
+     * reasoningLevels: { 0: null, 100: 'enabled' }
+     *
+     * @example
+     * // No reasoning support
+     * reasoningLevels: { 0: null }
+     */
+    reasoningLevels?: Record<number, string | null>;
+    /**
+     * Whether the model supports vision (image understanding).
+     * When true, image attachments will be sent to the model as part of the request.
+     * Models like GPT-4o, Claude 3, and Gemini support vision.
+     */
+    supportsImages?: boolean;
+    /**
+     * @deprecated Use supportsImages instead
+     */
+    vision?: boolean;
+    /**
+     * Whether the model supports function calling (tool use).
+     * Most modern models support this, defaults to true if not specified.
+     */
+    supportsToolCalls?: boolean;
+    /**
+     * @deprecated Use supportsToolCalls instead
+     */
+    functionCalling?: boolean;
+    /**
+     * Whether the model supports streaming responses.
+     * @default true
+     */
+    supportsStreaming?: boolean;
+    /**
+     * Whether the model supports structured outputs (JSON mode).
+     */
+    supportsJsonMode?: boolean;
+    /**
+     * @deprecated Use supportsJsonMode instead
+     */
+    structuredOutputs?: boolean;
+    /**
+     * Maximum context window size in tokens.
+     */
+    maxContextTokens?: number;
+    /**
+     * Maximum output tokens the model can generate.
+     */
+    maxOutputTokens?: number;
+}
+/**
+ * Model definition configuration.
+ *
+ * Defines an LLM model with its provider, pricing, capabilities, and fallback chain.
+ *
+ * @template N - The model name as a string literal type for type inference
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { defineModel } from '@standardagents/spec';
+ * import { openai } from '@standardagents/openai';
+ *
+ * export default defineModel({
+ *   name: 'gpt-4o',
+ *   provider: openai,
+ *   model: 'gpt-4o',
+ *   inputPrice: 2.5,
+ *   outputPrice: 10,
+ * });
+ * ```
+ *
+ * @example With capabilities and typed provider options
+ * ```typescript
+ * import { defineModel } from '@standardagents/spec';
+ * import { openai } from '@standardagents/openai';
+ *
+ * export default defineModel({
+ *   name: 'gpt-4o',
+ *   provider: openai,
+ *   model: 'gpt-4o',
+ *   inputPrice: 2.5,
+ *   outputPrice: 10,
+ *   capabilities: {
+ *     supportsImages: true,
+ *     supportsToolCalls: true,
+ *     supportsJsonMode: true,
+ *     maxContextTokens: 128000,
+ *   },
+ *   providerOptions: {
+ *     service_tier: 'default',  // TypeScript knows this is valid
+ *   },
+ * });
+ * ```
+ */
+interface ModelDefinition<N extends string = string, P extends ProviderFactoryWithOptions<ZodTypeAny> = ProviderFactoryWithOptions<ZodTypeAny>> {
+    /**
+     * Unique name for this model definition.
+     * Used as the identifier when referencing from prompts.
+     * Should be descriptive and consistent (e.g., 'gpt-4o', 'claude-3-opus').
+     */
+    name: N;
+    /**
+     * The LLM provider factory function to use for API calls.
+     *
+     * Import from a provider package like @standardagents/openai or @standardagents/openrouter.
+     * The provider's type determines what providerOptions are available.
+     *
+     * @example
+     * ```typescript
+     * import { openai } from '@standardagents/openai';
+     * provider: openai
+     * ```
+     *
+     * @example
+     * ```typescript
+     * import { openrouter } from '@standardagents/openrouter';
+     * provider: openrouter
+     * ```
+     */
+    provider: P;
+    /**
+     * The actual model identifier sent to the provider API.
+     *
+     * For OpenAI: 'gpt-4o', 'gpt-4-turbo', 'gpt-3.5-turbo', etc.
+     * For OpenRouter: 'openai/gpt-4o', 'anthropic/claude-3-opus', etc.
+     * For Anthropic: 'claude-3-opus-20240229', 'claude-3-sonnet-20240229', etc.
+     * For Google: 'gemini-1.5-pro', 'gemini-1.5-flash', etc.
+     */
+    model: string;
+    /**
+     * Optional list of additional provider prefixes for OpenRouter.
+     * Allows routing through specific providers when using OpenRouter.
+     *
+     * @example ['anthropic', 'google'] - prefer Anthropic, fallback to Google
+     */
+    includedProviders?: string[];
+    /**
+     * Fallback model names to try if this model fails.
+     * Referenced by model name (must be defined in agents/models/).
+     * Tried in order after primary model exhausts retries.
+     *
+     * @example ['gpt-4', 'gpt-3.5-turbo']
+     */
+    fallbacks?: string[];
+    /**
+     * Cost per 1 million input tokens in USD.
+     * Used for cost tracking and reporting in logs.
+     */
+    inputPrice?: number;
+    /**
+     * Cost per 1 million output tokens in USD.
+     * Used for cost tracking and reporting in logs.
+     */
+    outputPrice?: number;
+    /**
+     * Cost per 1 million cached input tokens in USD.
+     * Some providers offer reduced pricing for cached/repeated prompts.
+     */
+    cachedPrice?: number;
     /**
-     * Execution-specific state.
-     *
-     * This is present when the thread is actively executing (tools, hooks)
-     * and null when accessing a thread at rest (endpoints, external code).
-     *
-     * Use this to access step counts, force turns, or stop execution.
+     * Model capabilities - features this model supports.
      */
-    execution: ExecutionState | null;
+    capabilities?: ModelCapabilities;
     /**
-     * Runtime-specific context that cannot be packed or shared.
+     * Provider-specific options passed through to the provider.
+     * These are merged with prompt-level providerOptions (model options are defaults).
      *
-     * This property allows runtime implementations to inject non-portable
-     * context (e.g., Cloudflare env bindings, database connections).
+     * The type is automatically inferred from the provider's schema when available,
+     * providing TypeScript autocompletion and runtime validation.
      *
-     * WARNING: Tools using this property cannot be packed, shared, or
-     * published as they depend on runtime-specific context.
-     */
-    readonly _notPackableRuntimeContext?: Record<string, unknown>;
-}
-
-/**
- * Tool definition types for Standard Agents.
- *
- * Tools are callable functions that agents can invoke during execution.
- * They receive the current ThreadState and validated arguments,
- * and return results that are included in the conversation.
- *
- * @module
- */
-
-/**
- * Text content item returned by tools.
- */
-interface TextContent {
-    type: 'text';
-    text: string;
-}
-/**
- * Image content item returned by tools.
- */
-interface ImageContent {
-    type: 'image';
-    /** Base64-encoded image data. */
-    data: string;
-    /** MIME type of the image (e.g., 'image/png', 'image/jpeg'). */
-    mimeType: string;
-}
-/**
- * Content types that can be returned by tools.
- */
-type ToolContent = TextContent | ImageContent;
-/**
- * File attachment generated by a tool.
- *
- * Attachments are stored in the thread's file system and linked to
- * the tool result message. Unlike user uploads, tool attachments are
- * not subject to image downsampling.
- */
-interface ToolAttachment {
-    /** File name for the attachment. */
-    name: string;
-    /** MIME type of the attachment. */
-    mimeType: string;
-    /** Base64-encoded file data. */
-    data: string;
-    /** Width in pixels (for images). */
-    width?: number;
-    /** Height in pixels (for images). */
-    height?: number;
-}
-/**
- * Reference to a pre-existing attachment in the thread file system.
- */
-interface AttachmentRef {
-    /** Unique identifier for the attachment. */
-    id: string;
-    /** Attachment type. */
-    type: 'file';
-    /** Path in the thread file system. */
-    path: string;
-    /** File name. */
-    name: string;
-    /** MIME type. */
-    mimeType: string;
-    /** File size in bytes. */
-    size: number;
-    /** Width in pixels (for images). */
-    width?: number;
-    /** Height in pixels (for images). */
-    height?: number;
-    /** AI-generated description. */
-    description?: string;
-}
-/**
- * Result returned by a tool execution.
- */
-interface ToolResult {
-    /** Status of the tool execution. */
-    status: 'success' | 'error';
-    /**
-     * Text representation of the tool output.
+     * @example
+     * ```typescript
+     * // With OpenAI provider
+     * providerOptions: {
+     *   service_tier: 'default',
+     * }
+     * ```
      *
-     * For tools that return structured content, this is derived by
-     * concatenating all text parts. For simple tools, this is the
-     * direct result string.
+     * @example
+     * ```typescript
+     * // With OpenRouter provider
+     * providerOptions: {
+     *   provider: {
+     *     zdr: true,
+     *     max_price: { prompt: 1 },
+     *   },
+     * }
+     * ```
      */
-    result?: string;
-    /** Error message if status is 'error'. */
-    error?: string;
-    /** Stack trace for error debugging. */
-    stack?: string;
+    providerOptions?: InferProviderOptions<P>;
     /**
-     * File attachments returned by the tool.
+     * Provider tools available for this model.
+     * References tool names from provider.getTools().
      *
-     * Can contain either:
-     * - ToolAttachment: New files with base64 data to be stored
-     * - AttachmentRef: References to existing files in the thread filesystem
+     * Provider tools are built-in tools offered by the provider (e.g., OpenAI's
+     * web_search, file_search, code_interpreter, image_generation). These tools
+     * can be used in prompts alongside custom tools.
      *
-     * Implementations MUST store new attachments under /attachments/ directory.
+     * @example
+     * ```typescript
+     * providerTools: ['web_search', 'code_interpreter'],
+     * ```
      */
-    attachments?: Array<ToolAttachment | AttachmentRef>;
+    providerTools?: string[];
 }
-/** Decrement helper to limit recursion depth. */
-type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
-/**
- * Allowed Zod types for tool argument nodes.
- *
- * This is the single source of truth for which Zod types can be used
- * in tool argument schemas. The depth parameter limits recursion to
- * prevent infinite type expansion.
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodEnum<Readonly<Record<string, string>>> | (D extends 0 ? never : ZodOptional<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodNullable<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodDefault<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodArray<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodObject<Record<string, ToolArgsNode<Dec<D>>>>) | (D extends 0 ? never : ZodRecord<ZodString, ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodUnion<[
-    ToolArgsNode<Dec<D>>,
-    ToolArgsNode<Dec<D>>,
-    ...ToolArgsNode<Dec<D>>[]
-]>);
-/**
- * Raw shape for a Zod object schema containing tool argument nodes.
- *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
 /**
- * Top-level tool argument schema.
- *
- * Tool arguments MUST be defined as a Zod object schema.
- * This is required for compatibility with OpenAI's function calling API.
+ * Defines an LLM model configuration.
  *
- * @template D - Maximum nesting depth (default: 7)
- */
-type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
-/**
- * Tool function signature.
+ * Models are the foundation of the agent system - they specify which
+ * AI model to use and how to connect to it. Models can have fallbacks
+ * for reliability and include pricing for cost tracking.
  *
- * Tools are async functions that receive a ThreadState and
- * optionally validated arguments, returning a ToolResult.
+ * @template N - The model name as a string literal type
+ * @param options - Model configuration options
+ * @returns The model definition for registration
  *
- * @template State - The state type (defaults to ThreadState)
- * @template Args - The Zod schema for tool arguments, or null for no args
- */
-type Tool<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<ToolResult> : (state: State) => Promise<ToolResult>;
-/**
- * Return type of defineTool function.
+ * @example
+ * ```typescript
+ * // agents/models/gpt_4o.ts
+ * import { defineModel } from '@standardagents/spec';
+ * import { openai } from '@standardagents/openai';
  *
- * A tuple containing:
- * - Tool description string
- * - Argument schema (or null)
- * - Tool implementation function
- */
-type ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null> = [string, Args, Tool<State, Args>];
-/**
- * Define a tool with arguments.
+ * export default defineModel({
+ *   name: 'gpt-4o',
+ *   provider: openai,
+ *   model: 'gpt-4o',
+ *   fallbacks: ['gpt-4-turbo'],
+ *   inputPrice: 2.5,
+ *   outputPrice: 10,
+ * });
+ * ```
  *
- * @param toolDescription - Description of what the tool does (shown to the LLM)
- * @param args - Zod schema for validating tool arguments
- * @param tool - The tool implementation function
- * @returns A tuple containing the tool definition
- */
-declare function defineTool<State = ThreadState, Args extends ToolArgs = ToolArgs>(toolDescription: string, args: Args, tool: Tool<State, Args>): ToolDefinition<State, Args>;
-/**
- * Define a tool without arguments.
+ * @example
+ * ```typescript
+ * // Using OpenRouter with typed provider options
+ * import { openrouter } from '@standardagents/openrouter';
  *
- * @param toolDescription - Description of what the tool does (shown to the LLM)
- * @param tool - The tool implementation function
- * @returns A tuple containing the tool definition
+ * export default defineModel({
+ *   name: 'claude-3-opus',
+ *   provider: openrouter,
+ *   model: 'anthropic/claude-3-opus',
+ *   providerOptions: {
+ *     provider: {
+ *       zdr: true,
+ *       only: ['anthropic'],
+ *     },
+ *   },
+ * });
+ * ```
  */
-declare function defineTool<State = ThreadState>(toolDescription: string, tool: Tool<State, null>): ToolDefinition<State, null>;
+declare function defineModel<N extends string, P extends ProviderFactoryWithOptions<ZodTypeAny>>(options: ModelDefinition<N, P>): ModelDefinition<N, P>;
 
 /**
  * Prompt definition types for Standard Agents.
@@ -1010,24 +1865,86 @@ interface SubpromptConfig<T extends string = string> {
      * "search term" as the initial user message.
      */
     initUserMessageProperty?: string;
+    /**
+     * Property containing attachment path(s) to include as multimodal content
+     * when invoking the sub-prompt.
+     *
+     * Supports both a single path string or an array of paths.
+     *
+     * @example
+     * If the tool is called with `{ image: "/attachments/123.jpg" }` and
+     * `initAttachmentsProperty: 'image'`, the sub-prompt will receive
+     * the image as an attachment in the user message.
+     *
+     * @example
+     * If the tool is called with `{ images: ["/attachments/a.jpg", "/attachments/b.jpg"] }` and
+     * `initAttachmentsProperty: 'images'`, the sub-prompt will receive
+     * both images as attachments.
+     */
+    initAttachmentsProperty?: string;
 }
 /**
  * @deprecated Use SubpromptConfig instead
  */
 type ToolConfig<T extends string = string> = SubpromptConfig<T>;
+/**
+ * Configuration for a tool used in a prompt.
+ * Allows specifying tenv values and static options for the tool.
+ *
+ * @example
+ * ```typescript
+ * // Tool with tenv values
+ * { name: 'file_search', tenvs: { vectorStoreId: 'vs_abc123' } }
+ *
+ * // Tool with options
+ * { name: 'web_search', options: { searchContextSize: 'high' } }
+ * ```
+ */
+interface PromptToolConfig {
+    /**
+     * Name of the tool (custom tool or provider tool).
+     */
+    name: string;
+    /**
+     * Thread environment variable values for this tool.
+     * These values are merged with agent and thread tenvs (prompt tenvs are lowest priority).
+     */
+    tenvs?: Record<string, unknown>;
+    /**
+     * Static options for this tool.
+     * Passed to the tool handler at execution time.
+     */
+    options?: Record<string, unknown>;
+}
 /**
  * Reasoning configuration for models that support extended thinking.
- * Applies to models like OpenAI o1, Anthropic Claude with extended thinking,
+ * Applies to models like OpenAI o1/o3, Anthropic Claude with extended thinking,
  * Google Gemini with thinking, and Qwen with reasoning.
  */
 interface ReasoningConfig {
     /**
+     * Numeric reasoning level on a 0-100 scale.
+     * The FlowEngine maps this to the model's nearest supported reasoning option.
+     *
+     * @example
+     * // Typical breakpoints:
+     * // 0   = No reasoning
+     * // 33  = Low effort
+     * // 66  = Medium effort
+     * // 100 = Maximum effort
+     *
+     * reasoning: { level: 75 } // Maps to 'high' on most models
+     */
+    level?: number;
+    /**
+     * @deprecated Use `level` instead. Will be removed in future versions.
+     *
      * Effort level for reasoning models.
      * Higher effort = more thinking tokens = potentially better results.
      *
-     * - `low`: Minimal reasoning, faster responses
-     * - `medium`: Balanced reasoning and speed
-     * - `high`: Maximum reasoning, slower but more thorough
+     * - `low`: Minimal reasoning, faster responses (equivalent to level ~33)
+     * - `medium`: Balanced reasoning and speed (equivalent to level ~66)
+     * - `high`: Maximum reasoning, slower but more thorough (equivalent to level ~100)
      *
      * @default undefined (use model defaults)
      */
@@ -1126,10 +2043,37 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
     requiredSchema?: S;
     /**
      * Tools available to this prompt.
-     * Can be simple tool names or sub-prompt configurations.
+     * Can be:
+     * - string: Simple tool name (custom or provider tool)
+     * - SubpromptConfig: Sub-prompt used as a tool
+     * - PromptToolConfig: Tool with tenv values and/or options
+     *
      * To enable handoffs, include ai_human agent names in this array.
+     *
+     * @example
+     * ```typescript
+     * tools: [
+     *   'custom_tool',                                    // Simple tool name
+     *   { name: 'other_prompt' },                         // Sub-prompt as tool
+     *   { name: 'file_search', tenvs: { vectorStoreId: 'vs_123' } },  // Tool with tenvs
+     * ]
+     * ```
+     */
+    tools?: (string | SubpromptConfig | PromptToolConfig)[];
+    /**
+     * Thread environment variables for this prompt.
+     * These values are merged with agent and thread tenvs when creating a thread.
+     * Prompt tenvs have lowest priority (overridden by agent and thread tenvs).
+     *
+     * @example
+     * ```typescript
+     * tenvs: {
+     *   vectorStoreId: 'vs_default_123',
+     *   apiEndpoint: 'https://api.example.com',
+     * }
+     * ```
      */
-    tools?: (string | SubpromptConfig)[];
+    tenvs?: Record<string, unknown>;
     /**
      * Reasoning configuration for models that support extended thinking.
      */
@@ -1139,6 +2083,22 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * @default 10
      */
     recentImageThreshold?: number;
+    /**
+     * Provider-specific options passed through to the provider.
+     * These override model-level providerOptions for this prompt.
+     *
+     * Options are merged in order (later wins):
+     * 1. model.providerOptions (defaults)
+     * 2. prompt.providerOptions (this field - overrides)
+     *
+     * @example
+     * ```typescript
+     * providerOptions: {
+     *   response_format: { type: 'json_object' },
+     * }
+     * ```
+     */
+    providerOptions?: Record<string, unknown>;
 }
 /**
  * Helper type to extract the inferred input type from a prompt's Zod schema.
@@ -1678,6 +2638,24 @@ interface AgentDefinition<N extends string = string, Prompt extends string = str
      * @example 'https://example.com/icon.svg' or '/icons/support.svg'
      */
     icon?: string;
+    /**
+     * Thread environment variables for this agent.
+     * These values are merged with prompt and thread tenvs when creating a thread.
+     *
+     * Merge priority (later wins):
+     * 1. Prompt tenvs (lowest)
+     * 2. Agent tenvs (this field)
+     * 3. Thread tenvs (highest)
+     *
+     * @example
+     * ```typescript
+     * tenvs: {
+     *   vectorStoreId: 'vs_agent_default',
+     *   apiEndpoint: 'https://api.example.com',
+     * }
+     * ```
+     */
+    tenvs?: Record<string, unknown>;
 }
 /**
  * Defines an agent configuration.
@@ -1890,7 +2868,6 @@ declare function defineController(controller: Controller): Controller;
  *
  * export default defineThreadEndpoint(async (req, state) => {
  *   const { messages } = await state.getMessages();
- *   const logs = await state.getLogs();
  *   return Response.json({
  *     thread: {
  *       id: state.threadId,
@@ -1899,7 +2876,6 @@ declare function defineController(controller: Controller): Controller;
  *       createdAt: state.createdAt,
  *     },
  *     messages,
- *     logs,
  *   });
  * });
  * ```
@@ -1921,4 +2897,4 @@ declare function defineController(controller: Controller): Controller;
  */
 declare function defineThreadEndpoint(handler: ThreadEndpointHandler): Controller;
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type Controller, type ControllerContext, type ControllerReturn, type ExecutionState, type FileChunk, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetLogsOptions, type GetMessagesOptions, type GrepResult, type HookContext, type HookDefinition, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type InjectMessageInput, type LLMMessage, type Log, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type SideConfig, type StructuredPrompt, type SubpromptConfig, type TextContent, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, defineAgent, defineController, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool };
+export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type Effect, type EffectDefinition, type ExecutionState, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GrepResult, type HookContext, type HookDefinition, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResponseSummary, type ScheduledEffect, type SideConfig, type StructuredPrompt, type SubpromptConfig, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, mapReasoningLevel };