@standardagents/spec 0.11.0-next.5d2e71b → 0.11.0-next.7005954

package/dist/index.d.ts

@@ -1,159 +1,83 @@
-import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion } 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.
- *
- * Models define LLM configurations including provider, model ID, pricing,
- * and fallback chains. Models are referenced by name from prompts.
- *
- * @module
- */
-/**
- * Supported LLM provider identifiers.
- *
- * 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)
- */
-type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
-/**
- * Model capability flags indicating supported features.
- */
-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;
-}
-/**
- * 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
- * ```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,
- * });
- * ```
- */
-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;
-}
-/**
- * Defines an LLM model configuration.
+ * Global namespace for Standard Agent Specification types.
  *
- * 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.
+ * This namespace provides extensible registries that consumers can augment
+ * via TypeScript's declaration merging to enable type-safe references.
  *
- * @template N - The model name as a string literal type
- * @param options - Model configuration options
- * @returns The model definition for registration
+ * When registries are empty, all types fall back to `string` for flexibility.
+ * When augmented with registry entries, types narrow to the specific values.
  *
- * @example
+ * @example Augmenting the namespace (typically in generated types)
  * ```typescript
- * // agents/models/gpt_4o.ts
- * import { defineModel } from '@standardagents/spec';
- *
- * export default defineModel({
- *   name: 'gpt-4o',
- *   provider: 'openai',
- *   model: 'gpt-4o',
- *   fallbacks: ['gpt-4-turbo'],
- *   inputPrice: 2.5,
- *   outputPrice: 10,
- * });
+ * declare global {
+ *   namespace StandardAgentSpec {
+ *     interface ModelRegistry {
+ *       'gpt-4o': true;
+ *       'claude-3': true;
+ *     }
+ *   }
+ * }
  * ```
  *
- * @example
- * ```typescript
- * // Using OpenRouter with provider preferences
- * export default defineModel({
- *   name: 'claude-3-opus',
- *   provider: 'openrouter',
- *   model: 'anthropic/claude-3-opus',
- *   includedProviders: ['anthropic'],
- * });
- * ```
+ * @module
  */
-declare function defineModel<N extends string>(options: ModelDefinition<N>): ModelDefinition<N>;
+declare global {
+    namespace StandardAgentSpec {
+        /**
+         * Registry of model names. Augment to add model names.
+         * Generated types add properties: interface ModelRegistry { 'gpt-4o': true; }
+         * This gives us: type Models = keyof ModelRegistry = 'gpt-4o'
+         */
+        interface ModelRegistry {
+        }
+        /**
+         * Registry of prompt names. Augment to add prompt names.
+         */
+        interface PromptRegistry {
+        }
+        /**
+         * Registry of agent names. Augment to add agent names.
+         */
+        interface AgentRegistry {
+        }
+        /**
+         * Registry of tool names. Augment to add tool names.
+         */
+        interface ToolRegistry {
+        }
+        /**
+         * Registry of all callable items (prompts, agents, tools).
+         * Used for tool references in prompts and agents.
+         */
+        interface CallableRegistry {
+        }
+        /**
+         * Union of all model names, or string when registry is empty.
+         * When ModelRegistry is empty, this defaults to string for flexibility.
+         * When populated, it narrows to the specific model names.
+         */
+        type Models = keyof ModelRegistry extends never ? string : keyof ModelRegistry;
+        /**
+         * Union of all prompt names, or string when registry is empty.
+         */
+        type Prompts = keyof PromptRegistry extends never ? string : keyof PromptRegistry;
+        /**
+         * Union of all agent names, or string when registry is empty.
+         */
+        type Agents = keyof AgentRegistry extends never ? string : keyof AgentRegistry;
+        /**
+         * Union of all tool names, or string when registry is empty.
+         */
+        type Tools = keyof ToolRegistry extends never ? string : keyof ToolRegistry;
+        /**
+         * Union of all callable names, or string when registry is empty.
+         * Callables include prompts, agents, and tools that can be used as tools.
+         */
+        type Callables = keyof CallableRegistry extends never ? string : keyof CallableRegistry;
+    }
+}
 
 /**
  * Effect definition types for Standard Agents.
@@ -304,6 +228,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.
@@ -977,6 +905,30 @@ type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
  * @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.
  *
@@ -988,127 +940,998 @@ type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
  */
 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.
+ * Options for defining a tool.
  *
- * A tuple containing:
- * - Tool description string
- * - Argument schema (or null)
- * - Tool implementation function
+ * @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
  */
-type ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null> = [string, Args, Tool<State, Args>];
+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;
+}
 /**
- * Define a tool with arguments.
+ * Tool definition object returned by defineTool().
+ *
+ * Contains all the metadata and implementation needed to register
+ * and execute a tool.
  *
- * @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
+ * @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
  */
-declare function defineTool<State = ThreadState, Args extends ToolArgs = ToolArgs>(toolDescription: string, args: Args, tool: Tool<State, Args>): ToolDefinition<State, Args>;
+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;
+}
 /**
- * Define a tool without arguments.
+ * 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'),
+ *   }),
+ * });
  *
- * @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
+ * // 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>(toolDescription: string, tool: Tool<State, null>): ToolDefinition<State, null>;
+declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null>(options: DefineToolOptions<State, Args, Tenvs>): ToolDefinition<State, Args, Tenvs>;
 
 /**
- * Prompt definition types for Standard Agents.
+ * Provider types for Standard Agents.
  *
- * Prompts define LLM interaction configurations including the system prompt,
- * model selection, available tools, and various behavioral options.
+ * These types define the interface between Standard Agents and LLM providers.
+ * Provider packages implement these types to integrate with different LLM APIs.
  *
  * @module
  */
 
 /**
- * A text part of a prompt - static text content.
- *
- * @example
- * ```typescript
- * { type: 'text', content: 'You are a helpful assistant.\n\n' }
- * ```
+ * Stripped-down response summary for async metadata fetching.
+ * Intentionally excludes content/attachments to avoid passing large data.
  */
-interface PromptTextPart {
-    type: 'text';
-    /** The text content */
-    content: string;
+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;
+    };
 }
 /**
- * A prompt inclusion part - includes another prompt's content.
- *
- * @example
- * ```typescript
- * { type: 'include', prompt: 'responder_rules' }
- * ```
+ * Model information returned by provider's getModels method.
  */
-interface PromptIncludePart {
-    type: 'include';
-    /** The name of the prompt to include */
-    prompt: string;
+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;
 }
 /**
- * A single part of a structured prompt.
- * Discriminated union on `type` field for TypeScript narrowing.
- */
-type PromptPart = PromptTextPart | PromptIncludePart;
-/**
- * A structured prompt is an array of prompt parts.
- * Provides composition with other prompts via includes.
- *
- * @example
- * ```typescript
- * prompt: [
- *   { type: 'text', content: 'You are a helpful assistant.\n\n' },
- *   { type: 'include', prompt: 'common_rules' },
- *   { type: 'text', content: '\n\nBe concise.' },
- * ]
- * ```
- */
-type StructuredPrompt = PromptPart[];
-/**
- * The prompt content can be either a plain string or a structured array.
- *
- * @example
- * ```typescript
- * // Simple string prompt:
- * prompt: 'You are a helpful assistant.'
- *
- * // Structured prompt with includes:
- * prompt: [
- *   { type: 'text', content: 'You are a helpful assistant.\n\n' },
- *   { type: 'include', prompt: 'common_rules' },
- * ]
- * ```
- */
-type PromptContent = string | StructuredPrompt;
-/**
- * Configuration for sub-prompts used as tools.
- * These options control how results from sub-prompts are returned to the caller.
- *
- * @template T - The sub-prompt name type (for type-safe references)
+ * Provider interface - thin translation layer between Standard Agents and LLM APIs
  */
-interface SubpromptConfig<T extends string = string> {
+interface LLMProviderInterface {
+    readonly name: string;
+    readonly specificationVersion: '1';
     /**
-     * Name of the sub-prompt to call.
-     * Must be a prompt defined in agents/prompts/.
+     * Non-streaming generation
      */
-    name: T;
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
     /**
-     * Include text response content from sub-prompt execution in the result string.
-     * @default true
+     * Streaming generation
      */
-    includeTextResponse?: boolean;
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
     /**
-     * Serialize tool calls made by the sub-prompt (and their results) into the result string.
-     * @default true
+     * Check if this provider supports a model
      */
-    includeToolCalls?: boolean;
+    supportsModel?(modelId: string): boolean;
     /**
-     * Serialize any errors from the sub-prompt into the result string.
-     * @default true
+     * 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?: StandardAgentSpec.Models[];
+    /**
+     * 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;
+    /**
+     * Provider-specific options passed through to the provider.
+     * These are merged with prompt-level providerOptions (model options are defaults).
+     *
+     * The type is automatically inferred from the provider's schema when available,
+     * providing TypeScript autocompletion and runtime validation.
+     *
+     * @example
+     * ```typescript
+     * // With OpenAI provider
+     * providerOptions: {
+     *   service_tier: 'default',
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With OpenRouter provider
+     * providerOptions: {
+     *   provider: {
+     *     zdr: true,
+     *     max_price: { prompt: 1 },
+     *   },
+     * }
+     * ```
+     */
+    providerOptions?: InferProviderOptions<P>;
+    /**
+     * Provider tools available for this model.
+     * References tool names from provider.getTools().
+     *
+     * 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.
+     *
+     * @example
+     * ```typescript
+     * providerTools: ['web_search', 'code_interpreter'],
+     * ```
+     */
+    providerTools?: string[];
+}
+/**
+ * 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';
+ * import { openai } from '@standardagents/openai';
+ *
+ * export default defineModel({
+ *   name: 'gpt-4o',
+ *   provider: openai,
+ *   model: 'gpt-4o',
+ *   fallbacks: ['gpt-4-turbo'],
+ *   inputPrice: 2.5,
+ *   outputPrice: 10,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using OpenRouter with typed provider options
+ * import { openrouter } from '@standardagents/openrouter';
+ *
+ * export default defineModel({
+ *   name: 'claude-3-opus',
+ *   provider: openrouter,
+ *   model: 'anthropic/claude-3-opus',
+ *   providerOptions: {
+ *     provider: {
+ *       zdr: true,
+ *       only: ['anthropic'],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineModel<N extends string, P extends ProviderFactoryWithOptions<ZodTypeAny>>(options: ModelDefinition<N, P>): ModelDefinition<N, P>;
+
+/**
+ * Prompt definition types for Standard Agents.
+ *
+ * Prompts define LLM interaction configurations including the system prompt,
+ * model selection, available tools, and various behavioral options.
+ *
+ * @module
+ */
+
+/**
+ * A text part of a prompt - static text content.
+ *
+ * @example
+ * ```typescript
+ * { type: 'text', content: 'You are a helpful assistant.\n\n' }
+ * ```
+ */
+interface PromptTextPart {
+    type: 'text';
+    /** The text content */
+    content: string;
+}
+/**
+ * A prompt inclusion part - includes another prompt's content.
+ *
+ * @example
+ * ```typescript
+ * { type: 'include', prompt: 'responder_rules' }
+ * ```
+ */
+interface PromptIncludePart {
+    type: 'include';
+    /** The name of the prompt to include */
+    prompt: StandardAgentSpec.Prompts;
+}
+/**
+ * A single part of a structured prompt.
+ * Discriminated union on `type` field for TypeScript narrowing.
+ */
+type PromptPart = PromptTextPart | PromptIncludePart;
+/**
+ * A structured prompt is an array of prompt parts.
+ * Provides composition with other prompts via includes.
+ *
+ * @example
+ * ```typescript
+ * prompt: [
+ *   { type: 'text', content: 'You are a helpful assistant.\n\n' },
+ *   { type: 'include', prompt: 'common_rules' },
+ *   { type: 'text', content: '\n\nBe concise.' },
+ * ]
+ * ```
+ */
+type StructuredPrompt = PromptPart[];
+/**
+ * The prompt content can be either a plain string or a structured array.
+ *
+ * @example
+ * ```typescript
+ * // Simple string prompt:
+ * prompt: 'You are a helpful assistant.'
+ *
+ * // Structured prompt with includes:
+ * prompt: [
+ *   { type: 'text', content: 'You are a helpful assistant.\n\n' },
+ *   { type: 'include', prompt: 'common_rules' },
+ * ]
+ * ```
+ */
+type PromptContent = string | StructuredPrompt;
+/**
+ * Configuration for sub-prompts used as tools.
+ * These options control how results from sub-prompts are returned to the caller.
+ *
+ * @template T - The sub-prompt name type (for type-safe references)
+ */
+interface SubpromptConfig<T extends string = StandardAgentSpec.Callables> {
+    /**
+     * Name of the sub-prompt to call.
+     * Must be a prompt defined in agents/prompts/.
+     */
+    name: T;
+    /**
+     * Include text response content from sub-prompt execution in the result string.
+     * @default true
+     */
+    includeTextResponse?: boolean;
+    /**
+     * Serialize tool calls made by the sub-prompt (and their results) into the result string.
+     * @default true
+     */
+    includeToolCalls?: boolean;
+    /**
+     * Serialize any errors from the sub-prompt into the result string.
+     * @default true
      */
     includeErrors?: boolean;
     /**
@@ -1121,24 +1944,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: StandardAgentSpec.Callables;
+    /**
+     * 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)
      */
@@ -1205,7 +2090,7 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * Model to use for this prompt.
      * Must reference a model defined in agents/models/.
      */
-    model: string;
+    model: StandardAgentSpec.Models;
     /**
      * Include full chat history in the LLM context.
      * @default false
@@ -1237,10 +2122,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)[];
+    tools?: (StandardAgentSpec.Callables | 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',
+     * }
+     * ```
+     */
+    tenvs?: Record<string, unknown>;
     /**
      * Reasoning configuration for models that support extended thinking.
      */
@@ -1250,6 +2162,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.
@@ -1655,7 +2583,7 @@ type AgentType = 'ai_human' | 'dual_ai';
  * };
  * ```
  */
-interface SideConfig<Prompt extends string = string, Callable extends string = string> {
+interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
     /**
      * Custom label for this side of the conversation.
      * Used in UI and logs for clarity.
@@ -1722,7 +2650,7 @@ interface SideConfig<Prompt extends string = string, Callable extends string = s
  * });
  * ```
  */
-interface AgentDefinition<N extends string = string, Prompt extends string = string, Callable extends string = string> {
+interface AgentDefinition<N extends string = string, Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
     /**
      * Unique name for this agent.
      * Used as the identifier for thread creation and handoffs.
@@ -1789,6 +2717,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.
@@ -2030,4 +2976,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 Effect, type EffectDefinition, type ExecutionState, type FileChunk, 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 InjectMessageInput, type LLMMessage, 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 ScheduledEffect, 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, defineEffect, 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 };