@standardagents/spec 0.10.0-dev.ffffff

package/dist/index.d.ts

@@ -0,0 +1,1914 @@
+import { ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion, z } 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.
+ *
+ * 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';
+ *
+ * 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 provider preferences
+ * export default defineModel({
+ *   name: 'claude-3-opus',
+ *   provider: 'openrouter',
+ *   model: 'anthropic/claude-3-opus',
+ *   includedProviders: ['anthropic'],
+ * });
+ * ```
+ */
+declare function defineModel<N extends string>(options: ModelDefinition<N>): ModelDefinition<N>;
+
+/**
+ * Thread state types for Standard Agents.
+ *
+ * ThreadState is the unified interface for all thread operations.
+ * It provides access to thread identity, messages, logs, resource loading,
+ * tool invocation, event emission, and execution state.
+ *
+ * @module
+ */
+
+/**
+ * Metadata about a thread.
+ *
+ * This represents the core identity of a thread, separate from its
+ * operational state. Thread metadata is immutable after creation.
+ */
+interface ThreadMetadata {
+    /** Unique identifier for the thread */
+    id: string;
+    /** Agent that owns this thread */
+    agent_id: string;
+    /** User associated with this thread (if any) */
+    user_id: string | null;
+    /** Creation timestamp (microseconds since epoch) */
+    created_at: number;
+}
+/**
+ * Options for retrieving messages.
+ */
+interface GetMessagesOptions {
+    /** Maximum number of messages to return */
+    limit?: number;
+    /** Number of messages to skip */
+    offset?: number;
+    /** Sort order ('asc' for oldest first, 'desc' for newest first) */
+    order?: 'asc' | 'desc';
+    /** Include silent messages (not shown in UI) */
+    includeSilent?: boolean;
+    /** Maximum nesting depth for sub-prompt messages */
+    maxDepth?: number;
+}
+/**
+ * Result of a message query.
+ */
+interface MessagesResult {
+    /** Array of messages */
+    messages: Message[];
+    /** Total number of messages matching the query */
+    total: number;
+    /** Whether there are more messages available */
+    hasMore: boolean;
+}
+/**
+ * A message in the thread conversation.
+ */
+interface Message {
+    /** Unique message identifier */
+    id: string;
+    /** Message role */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Message content (null for tool calls without text) */
+    content: string | null;
+    /** Tool name (for tool result messages) */
+    name?: string | null;
+    /** JSON-encoded array of tool calls (for assistant messages) */
+    tool_calls?: string | null;
+    /** Tool call ID (for tool result messages) */
+    tool_call_id?: string | null;
+    /** Creation timestamp (microseconds since epoch) */
+    created_at: number;
+    /** Parent message ID (for sub-prompt messages) */
+    parent_id?: string | null;
+    /** Nesting depth (0 for top-level messages) */
+    depth?: number;
+    /** Whether this message is silent (not shown in UI) */
+    silent?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Input for injecting a new message.
+ */
+interface InjectMessageInput {
+    /** Message role */
+    role: 'user' | 'assistant' | 'system';
+    /** Message content */
+    content: string;
+    /** Whether to hide from UI */
+    silent?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Updates to apply to an existing message.
+ */
+interface MessageUpdates {
+    /** New content */
+    content?: string;
+    /** 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.
+ *
+ * Implementations define their own storage identifiers (e.g., 'local', 'cloud', 's3').
+ * The spec does not mandate specific storage backends.
+ */
+type FileStorage = string;
+/**
+ * Record representing a file in the thread's file system.
+ */
+interface FileRecord {
+    /** File path (relative to thread root) */
+    path: string;
+    /** File name */
+    name: string;
+    /** MIME type */
+    mimeType: string;
+    /** Storage location */
+    storage: FileStorage;
+    /** File size in bytes */
+    size: number;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Image width in pixels (if applicable) */
+    width?: number;
+    /** Image height in pixels (if applicable) */
+    height?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+    /** Last modified timestamp */
+    updatedAt?: number;
+}
+/**
+ * Options for writing a file.
+ */
+interface WriteFileOptions {
+    /** Custom metadata to attach to the file */
+    metadata?: Record<string, unknown>;
+    /** Image width in pixels (if applicable) */
+    width?: number;
+    /** Image height in pixels (if applicable) */
+    height?: number;
+}
+/**
+ * Result of reading a directory.
+ */
+interface ReaddirResult {
+    /** Files and directories in the path */
+    entries: FileRecord[];
+}
+/**
+ * Statistics about the thread's file system.
+ */
+interface FileStats {
+    /** Total number of files */
+    fileCount: number;
+    /** Total number of directories */
+    directoryCount: number;
+    /** Total size in bytes */
+    totalSize: number;
+}
+/**
+ * Result of a grep search.
+ */
+interface GrepResult {
+    /** File path */
+    path: string;
+    /** Matching lines */
+    matches: Array<{
+        line: number;
+        content: string;
+    }>;
+}
+/**
+ * Result of a find operation.
+ */
+interface FindResult {
+    /** Matching file paths */
+    paths: string[];
+}
+/**
+ * Options for streaming file reads.
+ */
+interface ReadFileStreamOptions {
+    /**
+     * Abort signal for cancellation.
+     *
+     * When signaled, the stream stops yielding new chunks.
+     * Already-yielded chunks remain valid.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * A chunk of file data from a streaming read.
+ */
+interface FileChunk {
+    /** Raw binary data for this chunk */
+    data: Uint8Array;
+    /** 0-based index of this chunk */
+    index: number;
+    /** Total number of chunks (1 for small files) */
+    totalChunks: number;
+    /** Whether this is the final chunk */
+    isLast: boolean;
+}
+/**
+ * Execution-specific state available during agent execution.
+ *
+ * This is present when a thread is actively executing (during tool calls,
+ * hook invocations, etc.) and null when accessing a thread at rest
+ * (from endpoints, external code, etc.).
+ */
+interface ExecutionState {
+    /** Current flow ID (unique per execution) */
+    readonly flowId: string;
+    /** Current side in dual_ai agents ('a' or 'b') */
+    readonly currentSide: 'a' | 'b';
+    /** Total steps executed in this flow */
+    readonly stepCount: number;
+    /** Steps executed by side A */
+    readonly sideAStepCount: number;
+    /** Steps executed by side B */
+    readonly sideBStepCount: number;
+    /** Whether execution has been stopped */
+    readonly stopped: boolean;
+    /** Which side initiated the stop (if stopped) */
+    readonly stoppedBy?: 'a' | 'b';
+    /** Message history loaded for current execution */
+    readonly messageHistory: Message[];
+    /**
+     * Force a specific side to play the next turn.
+     *
+     * Only valid for dual_ai agents. Has no effect on ai_human agents.
+     *
+     * @param side - The side to force ('a' or 'b')
+     */
+    forceTurn(side: 'a' | 'b'): void;
+    /**
+     * Stop the current execution.
+     *
+     * Signals the execution loop to terminate after the current operation
+     * completes. Does not abort in-progress LLM calls.
+     */
+    stop(): void;
+    /**
+     * Abort signal for cancellation.
+     *
+     * Can be used to abort fetch requests or other async operations
+     * when the execution is cancelled.
+     */
+    readonly abortSignal: AbortSignal;
+}
+/**
+ * The unified interface for all thread operations.
+ *
+ * ThreadState provides a consistent API for interacting with threads
+ * regardless of context - whether from tools during execution, hooks,
+ * or HTTP endpoints. The same interface is used throughout, with
+ * execution-specific state available when applicable.
+ *
+ * @example
+ * ```typescript
+ * // In a tool
+ * export default defineTool(
+ *   'Send a greeting',
+ *   z.object({ name: z.string() }),
+ *   async (state, args) => {
+ *     // Access thread identity
+ *     console.log(`Thread: ${state.threadId}`);
+ *
+ *     // Check execution state
+ *     if (state.execution?.stepCount > 10) {
+ *       state.execution.stop();
+ *     }
+ *
+ *     // Emit custom event
+ *     state.emit('greeting', { name: args.name });
+ *
+ *     return { status: 'success', result: `Hello, ${args.name}!` };
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In an endpoint
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   // state.execution is null (not executing)
+ *   const { messages } = await state.getMessages({ limit: 50 });
+ *   return Response.json({ messages });
+ * });
+ * ```
+ */
+interface ThreadState {
+    /** Unique thread identifier */
+    readonly threadId: string;
+    /** Agent that owns this thread */
+    readonly agentId: string;
+    /** User associated with this thread (if any) */
+    readonly userId: string | null;
+    /** Thread creation timestamp (microseconds since epoch) */
+    readonly createdAt: number;
+    /**
+     * Get messages from the thread.
+     *
+     * @param options - Query options (limit, offset, order, etc.)
+     * @returns Messages and pagination info
+     */
+    getMessages(options?: GetMessagesOptions): Promise<MessagesResult>;
+    /**
+     * Get a single message by ID.
+     *
+     * @param messageId - The message ID
+     * @returns The message, or null if not found
+     */
+    getMessage(messageId: string): Promise<Message | null>;
+    /**
+     * Inject a message into the thread.
+     *
+     * Creates a new message in the conversation history. This can be used
+     * to add context, simulate user input, or insert assistant responses.
+     *
+     * @param message - The message to inject
+     * @returns The created message
+     */
+    injectMessage(message: InjectMessageInput): Promise<Message>;
+    /**
+     * Update an existing message.
+     *
+     * @param messageId - The message ID
+     * @param updates - The updates to apply
+     * @returns The updated message
+     */
+    updateMessage(messageId: string, updates: MessageUpdates): Promise<Message>;
+    /**
+     * Get execution logs.
+     *
+     * @param options - Query options
+     * @returns Array of log entries
+     */
+    getLogs(options?: GetLogsOptions): Promise<Log[]>;
+    /**
+     * Load a model definition by name.
+     *
+     * @param name - The model name
+     * @returns The model definition
+     * @throws If the model is not found
+     */
+    loadModel<T = unknown>(name: string): Promise<T>;
+    /**
+     * Load a prompt definition by name.
+     *
+     * @param name - The prompt name
+     * @returns The prompt definition
+     * @throws If the prompt is not found
+     */
+    loadPrompt<T = unknown>(name: string): Promise<T>;
+    /**
+     * Load an agent definition by name.
+     *
+     * @param name - The agent name
+     * @returns The agent definition
+     * @throws If the agent is not found
+     */
+    loadAgent<T = unknown>(name: string): Promise<T>;
+    /**
+     * Get available prompt names.
+     *
+     * @returns Array of prompt names that can be loaded
+     */
+    getPromptNames(): string[];
+    /**
+     * Get available agent names.
+     *
+     * @returns Array of agent names that can be loaded
+     */
+    getAgentNames(): string[];
+    /**
+     * Get available model names.
+     *
+     * @returns Array of model names that can be loaded
+     */
+    getModelNames(): string[];
+    /**
+     * Queue a tool for execution.
+     *
+     * If the thread is currently executing, the tool is added to the
+     * execution queue. If not, this starts a new execution with the
+     * tool call.
+     *
+     * @param toolName - Name of the tool to invoke
+     * @param args - Arguments to pass to the tool
+     */
+    queueTool(toolName: string, args: Record<string, unknown>): void;
+    /**
+     * Invoke a tool directly and wait for the result.
+     *
+     * If the thread is not currently executing, this creates a minimal
+     * execution context for the tool. Unlike queueTool, this blocks
+     * until the tool completes.
+     *
+     * @param toolName - Name of the tool to invoke
+     * @param args - Arguments to pass to the tool
+     * @returns The tool result
+     */
+    invokeTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Emit a custom event to connected clients.
+     *
+     * Events are sent via WebSocket to any connected clients. Use this
+     * for real-time updates, progress notifications, or custom data.
+     *
+     * @param event - Event name
+     * @param data - Event data (must be JSON-serializable)
+     */
+    emit(event: string, data: unknown): void;
+    /**
+     * Key-value storage for custom data scoped to this thread.
+     *
+     * Context data persists across tool calls within a single execution.
+     * For persistent storage across executions, use messages or external
+     * storage.
+     */
+    context: Record<string, unknown>;
+    /**
+     * Write a file to the thread's file system.
+     *
+     * Large files (>1.75MB) are automatically chunked for storage.
+     *
+     * @param path - File path (relative to thread root)
+     * @param data - File content as ArrayBuffer or string
+     * @param mimeType - MIME type of the file
+     * @param options - Optional metadata and dimensions
+     * @returns The created file record
+     */
+    writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: WriteFileOptions): Promise<FileRecord>;
+    /**
+     * Read a file from the thread's file system.
+     *
+     * @param path - File path
+     * @returns File content as ArrayBuffer, or null if not found
+     */
+    readFile(path: string): Promise<ArrayBuffer | null>;
+    /**
+     * Stream a file from the thread's file system in chunks.
+     *
+     * For large files (>1.75MB), this yields one chunk at a time, enabling
+     * memory-efficient access without loading the entire file. Small files
+     * are yielded as a single chunk.
+     *
+     * Returns null if the file is not found or stored externally (S3, R2, URL).
+     *
+     * @param path - File path
+     * @param options - Optional streaming options (abort signal)
+     * @returns Async iterable of file chunks, or null if not found/external
+     *
+     * @example
+     * ```typescript
+     * const stream = await state.readFileStream('/uploads/video.mp4');
+     * if (stream) {
+     *   for await (const chunk of stream) {
+     *     console.log(`Chunk ${chunk.index + 1}/${chunk.totalChunks}`);
+     *     // Process chunk.data (Uint8Array)
+     *   }
+     * }
+     * ```
+     */
+    readFileStream(path: string, options?: ReadFileStreamOptions): Promise<AsyncIterable<FileChunk> | null>;
+    /**
+     * Get metadata about a file.
+     *
+     * @param path - File path
+     * @returns File record, or null if not found
+     */
+    statFile(path: string): Promise<FileRecord | null>;
+    /**
+     * List contents of a directory.
+     *
+     * @param path - Directory path
+     * @returns Directory entries
+     */
+    readdirFile(path: string): Promise<ReaddirResult>;
+    /**
+     * Delete a file.
+     *
+     * @param path - File path
+     */
+    unlinkFile(path: string): Promise<void>;
+    /**
+     * Create a directory.
+     *
+     * @param path - Directory path
+     * @returns The created directory record
+     */
+    mkdirFile(path: string): Promise<FileRecord>;
+    /**
+     * Remove a directory.
+     *
+     * @param path - Directory path (must be empty)
+     */
+    rmdirFile(path: string): Promise<void>;
+    /**
+     * Get overall file system statistics.
+     *
+     * @returns File count, directory count, and total size
+     */
+    getFileStats(): Promise<FileStats>;
+    /**
+     * Search file contents for a pattern.
+     *
+     * @param pattern - Search pattern (regular expression)
+     * @returns Matching files and lines
+     */
+    grepFiles(pattern: string): Promise<GrepResult[]>;
+    /**
+     * Find files matching a glob pattern.
+     *
+     * @param pattern - Glob pattern (e.g., "*.txt", "**\/*.json")
+     * @returns Matching file paths
+     */
+    findFiles(pattern: string): Promise<FindResult>;
+    /**
+     * Get a thumbnail for an image file.
+     *
+     * @param path - Path to the image file
+     * @returns Thumbnail data as ArrayBuffer, or null if not available
+     */
+    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;
+}
+
+/**
+ * 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>>;
+/**
+ * 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>;
+/**
+ * Return type of defineTool function.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @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
+ */
+declare function defineTool<State = ThreadState>(toolDescription: string, tool: Tool<State, null>): ToolDefinition<State, null>;
+
+/**
+ * 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: 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)
+ */
+interface SubpromptConfig<T extends string = string> {
+    /**
+     * 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;
+    /**
+     * Property from the tool call arguments to use as the initial user message
+     * when invoking the sub-prompt.
+     *
+     * @example
+     * If the tool is called with `{ query: "search term", limit: 10 }` and
+     * `initUserMessageProperty: 'query'`, the sub-prompt will receive
+     * "search term" as the initial user message.
+     */
+    initUserMessageProperty?: string;
+}
+/**
+ * @deprecated Use SubpromptConfig instead
+ */
+type ToolConfig<T extends string = string> = SubpromptConfig<T>;
+/**
+ * Reasoning configuration for models that support extended thinking.
+ * Applies to models like OpenAI o1, Anthropic Claude with extended thinking,
+ * Google Gemini with thinking, and Qwen with reasoning.
+ */
+interface ReasoningConfig {
+    /**
+     * 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
+     *
+     * @default undefined (use model defaults)
+     */
+    effort?: 'low' | 'medium' | 'high';
+    /**
+     * Maximum tokens to allocate for reasoning.
+     * Applies to models that support token limits on reasoning.
+     */
+    maxTokens?: number;
+    /**
+     * Use reasoning internally but exclude from the response.
+     * Model thinks through the problem but only returns the final answer.
+     * Useful for cleaner outputs while maintaining reasoning quality.
+     */
+    exclude?: boolean;
+    /**
+     * Include reasoning content in the message history for multi-turn context.
+     * When true, reasoning is preserved and visible to subsequent turns.
+     * @default false
+     */
+    include?: boolean;
+}
+/**
+ * Prompt definition configuration.
+ *
+ * @template N - The prompt name as a string literal type
+ * @template S - The Zod schema type for requiredSchema (inferred automatically)
+ *
+ * @example
+ * ```typescript
+ * import { definePrompt } from '@standardagents/spec';
+ * import { z } from 'zod';
+ *
+ * export default definePrompt({
+ *   name: 'customer_support',
+ *   toolDescription: 'Handle customer support inquiries',
+ *   model: 'gpt-4o',
+ *   prompt: 'You are a helpful customer support agent.',
+ *   tools: ['search_knowledge_base', 'create_ticket'],
+ *   requiredSchema: z.object({
+ *     query: z.string().describe('The customer inquiry'),
+ *   }),
+ * });
+ * ```
+ */
+interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolArgs> {
+    /**
+     * Unique name for this prompt.
+     * Used as the identifier when referencing from agents or as a tool.
+     * Should be snake_case (e.g., 'customer_support', 'data_analyst').
+     */
+    name: N;
+    /**
+     * Description shown when this prompt is exposed as a tool.
+     * Should clearly describe what this prompt does for LLM tool selection.
+     */
+    toolDescription: string;
+    /**
+     * The system prompt content sent to the LLM.
+     * Can be either a plain string or a structured array for composition.
+     */
+    prompt: PromptContent;
+    /**
+     * Model to use for this prompt.
+     * Must reference a model defined in agents/models/.
+     */
+    model: string;
+    /**
+     * Include full chat history in the LLM context.
+     * @default false
+     */
+    includeChat?: boolean;
+    /**
+     * Include results from past tool calls in the LLM context.
+     * @default false
+     */
+    includePastTools?: boolean;
+    /**
+     * Allow parallel execution of multiple tool calls.
+     * @default false
+     */
+    parallelToolCalls?: boolean;
+    /**
+     * Tool calling strategy for the LLM.
+     *
+     * - `auto`: Model decides when to call tools (default)
+     * - `none`: Disable tool calling entirely
+     * - `required`: Force the model to call at least one tool
+     *
+     * @default 'auto'
+     */
+    toolChoice?: 'auto' | 'none' | 'required';
+    /**
+     * Zod schema for validating inputs when this prompt is called as a tool.
+     */
+    requiredSchema?: S;
+    /**
+     * Tools available to this prompt.
+     * Can be simple tool names or sub-prompt configurations.
+     * To enable handoffs, include ai_human agent names in this array.
+     */
+    tools?: (string | SubpromptConfig)[];
+    /**
+     * Reasoning configuration for models that support extended thinking.
+     */
+    reasoning?: ReasoningConfig;
+    /**
+     * Number of recent messages to keep actual images for in context.
+     * @default 10
+     */
+    recentImageThreshold?: number;
+}
+/**
+ * Helper type to extract the inferred input type from a prompt's Zod schema.
+ *
+ * @template T - The prompt definition type
+ */
+type PromptInput<T extends PromptDefinition<string, ToolArgs>> = T['requiredSchema'] extends ToolArgs ? z.infer<T['requiredSchema']> : never;
+/**
+ * Defines a prompt configuration for LLM interactions.
+ *
+ * Prompts are the primary way to configure how agents interact with LLMs.
+ * They specify the system prompt, available tools, input validation,
+ * and various behavioral options.
+ *
+ * @template N - The prompt name as a string literal type
+ * @template S - The Zod schema type for requiredSchema
+ * @param options - Prompt configuration options
+ * @returns The prompt definition for registration
+ *
+ * @example
+ * ```typescript
+ * import { definePrompt } from '@standardagents/spec';
+ * import { z } from 'zod';
+ *
+ * export default definePrompt({
+ *   name: 'customer_support',
+ *   toolDescription: 'Handle customer support inquiries',
+ *   model: 'gpt-4o',
+ *   prompt: 'You are a helpful customer support agent.',
+ *   tools: ['search_knowledge_base', 'create_ticket'],
+ *   includeChat: true,
+ *   requiredSchema: z.object({
+ *     query: z.string().describe('The customer inquiry'),
+ *   }),
+ * });
+ * ```
+ */
+declare function definePrompt<N extends string, S extends ToolArgs = never>(options: PromptDefinition<N, S>): PromptDefinition<N, S>;
+
+/**
+ * Hook definition types for Standard Agents.
+ *
+ * Hooks allow intercepting and modifying agent behavior at key points
+ * in the execution lifecycle. They enable logging, validation,
+ * transformation, and side effects.
+ *
+ * Hooks receive ThreadState as their first parameter, providing full
+ * access to thread operations and execution state.
+ *
+ * @module
+ */
+
+/**
+ * Hook context is ThreadState.
+ *
+ * Hooks receive the full ThreadState, which includes identity, message access,
+ * resource loading, event emission, and execution state (when available).
+ *
+ * @example
+ * ```typescript
+ * const hook = defineHook('filter_messages', async (state, messages) => {
+ *   console.log(`Thread: ${state.threadId}`);
+ *   if (state.execution) {
+ *     console.log(`Turn: ${state.execution.turnCount}`);
+ *   }
+ *   return messages.slice(-10);
+ * });
+ * ```
+ */
+type HookContext = ThreadState;
+/**
+ * Message structure for hook processing.
+ *
+ * Re-exported from threads.ts for convenience.
+ * @see Message
+ */
+type HookMessage = Message;
+/**
+ * Tool call structure for hook processing.
+ */
+interface HookToolCall {
+    /** Unique tool call identifier */
+    id: string;
+    /** Always 'function' for tool calls */
+    type: 'function';
+    /** Function details */
+    function: {
+        /** Tool name */
+        name: string;
+        /** JSON-encoded arguments */
+        arguments: string;
+    };
+}
+/**
+ * Tool result structure for hook processing.
+ */
+interface HookToolResult {
+    /** Execution status */
+    status: 'success' | 'error';
+    /** Result string (for successful executions) */
+    result?: string;
+    /** Error message (for failed executions) */
+    error?: string;
+    /** Stack trace (for debugging) */
+    stack?: string;
+}
+/**
+ * LLM message format for prefilter hook.
+ */
+interface LLMMessage {
+    /** Message role */
+    role: string;
+    /** Message content */
+    content: string | null;
+    /** Tool calls (parsed) */
+    tool_calls?: unknown;
+    /** Tool call ID */
+    tool_call_id?: string;
+    /** Tool name */
+    name?: string;
+}
+/**
+ * Hook signatures for all available hooks.
+ *
+ * Each hook has a specific signature that defines when it's called
+ * and what data it receives. Hooks can modify data by returning
+ * transformed values or perform side effects.
+ *
+ * All hooks receive ThreadState as their first parameter.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Msg - The message type (defaults to HookMessage)
+ * @template ToolCall - The tool call type (defaults to HookToolCall)
+ * @template ToolResult - The tool result type (defaults to HookToolResult)
+ */
+interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> {
+    /**
+     * Called before messages are filtered and sent to the LLM.
+     *
+     * Receives raw message rows from storage before any transformation.
+     * Use for filtering, sorting, or augmenting message history.
+     *
+     * @param state - Thread state
+     * @param messages - Array of messages from storage
+     * @returns Modified message array
+     *
+     * @example
+     * ```typescript
+     * defineHook('filter_messages', async (state, messages) => {
+     *   // Only include messages from last 10 turns
+     *   return messages.slice(-10);
+     * });
+     * ```
+     */
+    filter_messages: (state: State, messages: Msg[]) => Promise<Msg[]>;
+    /**
+     * Called after message history is loaded and before sending to LLM.
+     *
+     * Receives messages already transformed into chat completion format.
+     * Use for final adjustments before LLM request.
+     *
+     * @param state - Thread state
+     * @param messages - Array of LLM-formatted messages
+     * @returns Modified LLM message array
+     *
+     * @example
+     * ```typescript
+     * defineHook('prefilter_llm_history', async (state, messages) => {
+     *   // Add a reminder to the last user message
+     *   return messages;
+     * });
+     * ```
+     */
+    prefilter_llm_history: (state: State, messages: LLMMessage[]) => Promise<LLMMessage[]>;
+    /**
+     * Called before a message is created in the database.
+     *
+     * Receives the message data before insertion. Return modified data
+     * to transform the message before storage.
+     *
+     * @param state - Thread state
+     * @param message - Message data to be created
+     * @returns Modified message data
+     *
+     * @example
+     * ```typescript
+     * defineHook('before_create_message', async (state, message) => {
+     *   // Add metadata to all messages
+     *   return { ...message, metadata: { processed: true } };
+     * });
+     * ```
+     */
+    before_create_message: (state: State, message: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /**
+     * Called after a message is created in the database.
+     *
+     * Use for logging, analytics, or triggering side effects after
+     * message creation. Cannot modify the message.
+     *
+     * @param state - Thread state
+     * @param message - The created message data
+     *
+     * @example
+     * ```typescript
+     * defineHook('after_create_message', async (state, message) => {
+     *   console.log(`Message created: ${message.id}`);
+     * });
+     * ```
+     */
+    after_create_message: (state: State, message: Record<string, unknown>) => Promise<void>;
+    /**
+     * Called before a message is updated in the database.
+     *
+     * Receives the message ID and update data. Return modified updates
+     * to transform the changes before storage.
+     *
+     * @param state - Thread state
+     * @param messageId - ID of message being updated
+     * @param updates - Update data
+     * @returns Modified update data
+     *
+     * @example
+     * ```typescript
+     * defineHook('before_update_message', async (state, messageId, updates) => {
+     *   return { ...updates, updated_at: Date.now() };
+     * });
+     * ```
+     */
+    before_update_message: (state: State, messageId: string, updates: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /**
+     * Called after a message is updated in the database.
+     *
+     * Use for logging, analytics, or triggering side effects after
+     * message update. Cannot modify the message.
+     *
+     * @param state - Thread state
+     * @param message - The updated message
+     *
+     * @example
+     * ```typescript
+     * defineHook('after_update_message', async (state, message) => {
+     *   console.log(`Message updated: ${message.id}`);
+     * });
+     * ```
+     */
+    after_update_message: (state: State, message: Msg) => Promise<void>;
+    /**
+     * Called before a tool result is stored in the database.
+     *
+     * Receives the tool call and result before storage. Return modified
+     * result to transform before storage.
+     *
+     * @param state - Thread state
+     * @param toolCall - The tool call that was executed
+     * @param toolResult - The result from tool execution
+     * @returns Modified tool result data
+     *
+     * @example
+     * ```typescript
+     * defineHook('before_store_tool_result', async (state, toolCall, toolResult) => {
+     *   // Sanitize sensitive data from results
+     *   return { ...toolResult, result: sanitize(toolResult.result) };
+     * });
+     * ```
+     */
+    before_store_tool_result: (state: State, toolCall: Record<string, unknown>, toolResult: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    /**
+     * Called after a successful tool call.
+     *
+     * Receives the tool call and its result. Can return a modified result
+     * or null to use the original. Use for logging, transformation, or
+     * post-processing of successful tool executions.
+     *
+     * @param state - Thread state
+     * @param toolCall - The executed tool call
+     * @param toolResult - The successful result
+     * @returns Modified result or null for original
+     *
+     * @example
+     * ```typescript
+     * defineHook('after_tool_call_success', async (state, toolCall, toolResult) => {
+     *   console.log(`Tool ${toolCall.function.name} succeeded`);
+     *   return null; // Use original result
+     * });
+     * ```
+     */
+    after_tool_call_success: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
+    /**
+     * Called after a failed tool call.
+     *
+     * Receives the tool call and error result. Can return a modified result
+     * or null to use the original. Use for error handling, logging, or
+     * recovery attempts.
+     *
+     * @param state - Thread state
+     * @param toolCall - The failed tool call
+     * @param toolResult - The error result
+     * @returns Modified result or null for original
+     *
+     * @example
+     * ```typescript
+     * defineHook('after_tool_call_failure', async (state, toolCall, toolResult) => {
+     *   console.error(`Tool ${toolCall.function.name} failed: ${toolResult.error}`);
+     *   return null; // Use original error
+     * });
+     * ```
+     */
+    after_tool_call_failure: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
+}
+/**
+ * Valid hook names.
+ */
+type HookName = keyof HookSignatures;
+/**
+ * Hook definition tuple.
+ *
+ * A hook definition is a tuple containing the hook name and implementation.
+ *
+ * @template K - The hook name
+ * @template State - The state type (defaults to ThreadState)
+ * @template Msg - The message type
+ * @template ToolCall - The tool call type
+ * @template ToolResult - The tool result type
+ */
+type HookDefinition<K extends HookName = HookName, State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> = [K, HookSignatures<State, Msg, ToolCall, ToolResult>[K]];
+/**
+ * Define a hook with strict typing based on hook name.
+ *
+ * Hooks intercept specific points in the agent execution lifecycle.
+ * The hook name determines the function signature and when it's called.
+ * All hooks receive ThreadState as their first parameter.
+ *
+ * @template K - The hook name (determines signature)
+ * @param hookName - Name of the hook to define
+ * @param implementation - Hook implementation function
+ * @returns The implementation function (for registration)
+ *
+ * @example
+ * ```typescript
+ * // Filter messages to last 10
+ * export default defineHook('filter_messages', async (state, messages) => {
+ *   return messages.slice(-10);
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Log all tool successes
+ * export default defineHook('after_tool_call_success', async (state, toolCall, result) => {
+ *   console.log(`Tool ${toolCall.function.name} completed`);
+ *   return null; // Use original result
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Transform messages before LLM
+ * export default defineHook('prefilter_llm_history', async (state, messages) => {
+ *   // Add instruction to last message
+ *   const last = messages[messages.length - 1];
+ *   if (last?.role === 'user' && typeof last.content === 'string') {
+ *     last.content += '\n\nRemember to be concise.';
+ *   }
+ *   return messages;
+ * });
+ * ```
+ */
+declare function defineHook<K extends keyof HookSignatures>(hookName: K, implementation: HookSignatures[K]): HookSignatures[K];
+
+/**
+ * Agent definition types for Standard Agents.
+ *
+ * Agents orchestrate conversations between AI models (dual_ai) or between
+ * AI and human users (ai_human). They define the prompts, stop conditions,
+ * and behavioral rules for each side of the conversation.
+ *
+ * @module
+ */
+/**
+ * Agent conversation type.
+ *
+ * - `ai_human`: AI conversing with a human user (most common)
+ * - `dual_ai`: Two AI participants conversing with each other
+ */
+type AgentType = 'ai_human' | 'dual_ai';
+/**
+ * Configuration for one side of an agent conversation.
+ *
+ * Each side has a prompt, stop conditions, and turn limits.
+ * For `ai_human` agents, only sideA (the AI) needs configuration.
+ * For `dual_ai` agents, both sides need configuration.
+ *
+ * @template Prompt - The prompt reference type (string or type-safe union)
+ * @template Callable - The callable reference type (string or type-safe union)
+ *
+ * @example
+ * ```typescript
+ * const sideConfig: SideConfig = {
+ *   label: 'Support Agent',
+ *   prompt: 'customer_support',
+ *   stopOnResponse: true,
+ *   maxSteps: 10,
+ * };
+ * ```
+ */
+interface SideConfig<Prompt extends string = string, Callable extends string = string> {
+    /**
+     * Custom label for this side of the conversation.
+     * Used in UI and logs for clarity.
+     *
+     * @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
+     */
+    label?: string;
+    /**
+     * The prompt to use for this side.
+     * Must reference a prompt defined in agents/prompts/.
+     */
+    prompt: Prompt;
+    /**
+     * Stop this side's turn when it returns a text response (no tool calls).
+     * When true, the side's turn ends after producing a message without tools.
+     * @default true
+     */
+    stopOnResponse?: boolean;
+    /**
+     * Stop this side's turn when a specific tool is called.
+     * Overrides stopOnResponse when the named tool is invoked.
+     * Requires stopToolResponseProperty to extract the result.
+     */
+    stopTool?: Callable;
+    /**
+     * Property to extract from the stop tool's result.
+     * Required when stopTool is set.
+     * The extracted value is used to determine the conversation outcome.
+     */
+    stopToolResponseProperty?: string;
+    /**
+     * Maximum steps for this side before forcing a stop.
+     * Safety limit to prevent runaway execution.
+     * A step is one complete LLM request/response cycle.
+     */
+    maxSteps?: number;
+    /**
+     * Tool that ends the entire session when called.
+     * Different from stopTool - this ends the session for both sides,
+     * not just this side's turn.
+     */
+    endSessionTool?: Callable;
+}
+/**
+ * Agent definition configuration.
+ *
+ * @template N - The agent name as a string literal type
+ * @template Prompt - The prompt reference type (string or type-safe union)
+ * @template Callable - The callable reference type (string or type-safe union)
+ *
+ * @example
+ * ```typescript
+ * import { defineAgent } from '@standardagents/spec';
+ *
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *   },
+ * });
+ * ```
+ */
+interface AgentDefinition<N extends string = string, Prompt extends string = string, Callable extends string = string> {
+    /**
+     * Unique name for this agent.
+     * Used as the identifier for thread creation and handoffs.
+     * Should be snake_case (e.g., 'support_agent', 'research_flow').
+     */
+    name: N;
+    /**
+     * Human-readable title for the agent.
+     * Optional - if not provided, the name will be used.
+     * @deprecated Use name instead. Title will be removed in a future version.
+     */
+    title?: string;
+    /**
+     * Agent conversation type.
+     *
+     * - `ai_human`: AI conversing with a human user (default)
+     * - `dual_ai`: Two AI participants conversing
+     *
+     * @default 'ai_human'
+     */
+    type?: AgentType;
+    /**
+     * Maximum total turns across both sides.
+     * Only applies to `dual_ai` agents.
+     * Prevents infinite loops in AI-to-AI conversations.
+     */
+    maxSessionTurns?: number;
+    /**
+     * Configuration for Side A.
+     * For `ai_human`: This is the AI side.
+     * For `dual_ai`: This is the first AI participant.
+     */
+    sideA: SideConfig<Prompt, Callable>;
+    /**
+     * Configuration for Side B.
+     * For `ai_human`: Optional, the human side doesn't need config.
+     * For `dual_ai`: Required, the second AI participant.
+     */
+    sideB?: SideConfig<Prompt, Callable>;
+    /**
+     * Expose this agent as a tool for other prompts.
+     * Enables agent composition and handoffs.
+     * When true, other prompts can invoke this agent as a tool.
+     * @default false
+     */
+    exposeAsTool?: boolean;
+    /**
+     * Description shown when agent is used as a tool.
+     * Required if exposeAsTool is true.
+     * Should clearly describe what this agent does.
+     */
+    toolDescription?: string;
+    /**
+     * Brief description of what this agent does.
+     * Useful for UIs and documentation.
+     *
+     * @example 'Handles customer support inquiries and resolves issues'
+     */
+    description?: string;
+    /**
+     * Icon URL or absolute path for the agent.
+     * Absolute paths (starting with `/`) are converted to full URLs in API responses.
+     *
+     * @example 'https://example.com/icon.svg' or '/icons/support.svg'
+     */
+    icon?: string;
+}
+/**
+ * Defines an agent configuration.
+ *
+ * Agents orchestrate conversations between AI models, or between AI and
+ * human users. They use prompts to configure each side of the conversation
+ * and define stop conditions to control conversation flow.
+ *
+ * @template N - The agent name as a string literal type
+ * @param options - Agent configuration options
+ * @returns The agent definition for registration
+ *
+ * @example
+ * ```typescript
+ * // agents/agents/support_agent.ts
+ * import { defineAgent } from '@standardagents/spec';
+ *
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *     endSessionTool: 'close_ticket',
+ *   },
+ *   exposeAsTool: true,
+ *   toolDescription: 'Hand off to customer support',
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Dual AI agent (two AIs conversing)
+ * export default defineAgent({
+ *   name: 'debate_agent',
+ *   title: 'AI Debate',
+ *   type: 'dual_ai',
+ *   maxSessionTurns: 10,
+ *   sideA: {
+ *     label: 'Pro',
+ *     prompt: 'debate_pro',
+ *     stopOnResponse: true,
+ *   },
+ *   sideB: {
+ *     label: 'Con',
+ *     prompt: 'debate_con',
+ *     stopOnResponse: true,
+ *     endSessionTool: 'conclude_debate',
+ *   },
+ * });
+ * ```
+ */
+declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
+
+/**
+ * Endpoint definition types for Standard Agents.
+ *
+ * Endpoints expose HTTP APIs for interacting with agent threads.
+ * They can be standard controllers or thread-specific endpoints
+ * with automatic ThreadState injection.
+ *
+ * @module
+ */
+
+/**
+ * Virtual module loader function.
+ *
+ * Lazy-loads a module definition on demand.
+ */
+type VirtualModuleLoader<T> = () => Promise<T>;
+/**
+ * Registry of virtual modules by name.
+ *
+ * Maps module names to their lazy loaders.
+ */
+type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
+/**
+ * Controller context passed to route handlers.
+ *
+ * Contains the request, URL parameters, environment bindings,
+ * and optionally the virtual module registries injected at runtime.
+ *
+ * Note: The `env` property contains implementation-specific bindings.
+ * Cloudflare implementations may include Durable Object namespaces,
+ * KV namespaces, etc. Other implementations may provide different bindings.
+ */
+interface ControllerContext {
+    /** The incoming HTTP request */
+    req: Request;
+    /** URL path parameters extracted by the router */
+    params: Record<string, string>;
+    /** Parsed URL object */
+    url: URL;
+    /**
+     * Environment bindings (implementation-specific).
+     *
+     * Contains platform-specific bindings like Durable Objects, KV, etc.
+     * The exact contents depend on the runtime implementation.
+     */
+    env: Record<string, unknown>;
+    /** Registry of agent definitions (injected at runtime) */
+    agents?: VirtualModuleRegistry<unknown>;
+    /** Available agent names */
+    agentNames?: string[];
+    /** Registry of prompt definitions (injected at runtime) */
+    prompts?: VirtualModuleRegistry<unknown>;
+    /** Available prompt names */
+    promptNames?: string[];
+    /** Registry of model definitions (injected at runtime) */
+    models?: VirtualModuleRegistry<unknown>;
+    /** Available model names */
+    modelNames?: string[];
+    /** Registry of tool definitions (injected at runtime) */
+    tools?: VirtualModuleRegistry<unknown>;
+    /** Registry of hook definitions (injected at runtime) */
+    hooks?: VirtualModuleRegistry<unknown>;
+    /** Additional configuration (injected at runtime) */
+    config?: Record<string, unknown>;
+}
+/**
+ * Controller return types.
+ *
+ * Controllers can return various types that are automatically
+ * converted to appropriate HTTP responses.
+ */
+type ControllerReturn = string | Promise<string> | Response | Promise<Response> | ReadableStream | Promise<ReadableStream> | null | Promise<null> | void | Promise<void> | Promise<object> | object;
+/**
+ * Controller function type.
+ *
+ * Controllers handle HTTP requests and return responses.
+ * The return value is automatically converted to a Response.
+ *
+ * @example
+ * ```typescript
+ * const handler: Controller = async ({ req, params, url }) => {
+ *   return { message: 'Hello, World!' };
+ * };
+ * ```
+ */
+type Controller = (context: ControllerContext) => ControllerReturn;
+/**
+ * Thread endpoint handler function.
+ *
+ * Receives the HTTP request and the ThreadState for the requested thread.
+ * The thread is automatically looked up by ID from URL parameters.
+ */
+type ThreadEndpointHandler = (req: Request, state: ThreadState) => Response | Promise<Response>;
+/**
+ * Define a standard HTTP controller.
+ *
+ * Controllers handle HTTP requests and return responses. They have
+ * access to the controller context including virtual module registries.
+ *
+ * @param controller - The controller function
+ * @returns The controller for registration
+ *
+ * @example
+ * ```typescript
+ * // agents/api/health.get.ts
+ * import { defineController } from '@standardagents/spec';
+ *
+ * export default defineController(async () => {
+ *   return { status: 'ok', timestamp: Date.now() };
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // agents/api/agents/index.get.ts
+ * import { defineController } from '@standardagents/spec';
+ *
+ * export default defineController(async ({ agentNames }) => {
+ *   return { agents: agentNames };
+ * });
+ * ```
+ */
+declare function defineController(controller: Controller): Controller;
+/**
+ * Define a thread-specific endpoint.
+ *
+ * Thread endpoints automatically look up the thread by ID from URL params
+ * and provide access to the ThreadState. The handler receives full
+ * ThreadState with messages, logs, resource loading, event emission,
+ * and (when executing) execution state.
+ *
+ * @param handler - The handler function receiving request and ThreadState
+ * @returns A Controller that can be used with the router
+ *
+ * @example
+ * ```typescript
+ * // agents/api/threads/[id]/status.get.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { messages, total } = await state.getMessages({ limit: 1 });
+ *   return Response.json({
+ *     threadId: state.threadId,
+ *     agent: state.agentId,
+ *     messageCount: total,
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // agents/api/threads/[id]/export.get.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { messages } = await state.getMessages();
+ *   const logs = await state.getLogs();
+ *   return Response.json({
+ *     thread: {
+ *       id: state.threadId,
+ *       agent: state.agentId,
+ *       user: state.userId,
+ *       createdAt: state.createdAt,
+ *     },
+ *     messages,
+ *     logs,
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // agents/api/threads/[id]/invoke.post.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { tool, args } = await req.json();
+ *
+ *   // Queue a tool for execution (starts execution if not running)
+ *   state.queueTool(tool, args);
+ *
+ *   return Response.json({ queued: true });
+ * });
+ * ```
+ */
+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 };