@standardagents/builder 0.8.1

package/dist/index.d.ts

@@ -0,0 +1,2962 @@
+export { AgentPluginOptions, agentbuilder } from './plugin.js';
+import { DurableObjectStorage } from '@cloudflare/workers-types';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion } from 'zod';
+import { DurableObject } from 'cloudflare:workers';
+import 'vite';
+
+/**
+ * Global namespace for AgentBuilder types.
+ *
+ * This namespace provides type-safe references for models, prompts, agents, and tools.
+ * Types are automatically populated when you run `pnpm dev` or `pnpm build`,
+ * which scans your `agentbuilder/` directories and generates types.
+ *
+ * The generated types are placed in `.agentbuilder/types.d.ts` and augment this namespace.
+ *
+ * Note: We use interfaces as type registries because TypeScript allows interface
+ * declaration merging. The user's generated types will add properties to these
+ * interfaces, and we extract the union of all property keys.
+ */
+declare global {
+    namespace AgentBuilder {
+        /**
+         * Interface for model type registration.
+         * Generated types add properties: interface ModelRegistry { 'gpt-4o': true; 'claude-3': true; }
+         * This gives us: type Models = keyof ModelRegistry = 'gpt-4o' | 'claude-3'
+         */
+        interface ModelRegistry {
+        }
+        /**
+         * Interface for prompt type registration.
+         */
+        interface PromptRegistry {
+        }
+        /**
+         * Interface for agent type registration.
+         */
+        interface AgentRegistry {
+        }
+        /**
+         * Interface for tool type registration.
+         */
+        interface ToolRegistry {
+        }
+        /**
+         * Interface for callable type registration (prompts, agents, tools).
+         */
+        interface CallableRegistry {
+        }
+        /**
+         * Union type of all model names defined in agentbuilder/models/.
+         * 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 type of all prompt names defined in agentbuilder/prompts/.
+         */
+        type Prompts = keyof PromptRegistry extends never ? string : keyof PromptRegistry;
+        /**
+         * Union type of all agent names defined in agentbuilder/agents/.
+         */
+        type Agents = keyof AgentRegistry extends never ? string : keyof AgentRegistry;
+        /**
+         * Union type of all tool names defined in agentbuilder/tools/.
+         */
+        type Tools = keyof ToolRegistry extends never ? string : keyof ToolRegistry;
+        /**
+         * Union type of all callable items (prompts, agents, tools) that can be used as tools.
+         */
+        type Callables = keyof CallableRegistry extends never ? string : keyof CallableRegistry;
+    }
+}
+
+/**
+ * Callback function to execute before stream closes
+ */
+type BeforeClose = () => Promise<void> | void;
+/**
+ * Manages multiplexed streaming of content (HTTP) and telemetry (WebSocket)
+ * Inspired by bod.coach MultiplexedStream pattern
+ */
+declare class StreamManager {
+    /**
+     * HTTP ReadableStream controller for content
+     */
+    private httpController?;
+    /**
+     * HTTP ReadableStream for content chunks
+     */
+    httpStream: ReadableStream<Uint8Array>;
+    /**
+     * WebSocket connections for telemetry
+     */
+    private wsConnections;
+    /**
+     * Active channels
+     */
+    activeChannels: number;
+    /**
+     * Before close hooks
+     */
+    private beforeCloseHooks;
+    /**
+     * Prevent automatic close
+     */
+    preventClose: boolean;
+    /**
+     * Text encoder for streams
+     */
+    private encoder;
+    /**
+     * Promise that resolves when stream is completely finished
+     */
+    then: Promise<void>;
+    /**
+     * Resolver for the then promise
+     */
+    private resolver;
+    /**
+     * Whether the stream has been closed
+     */
+    private closed;
+    constructor(beforeClose?: BeforeClose | BeforeClose[]);
+    /**
+     * Send content chunk to HTTP stream
+     */
+    sendContent(chunk: string): void;
+    /**
+     * Send telemetry event to all WebSocket connections
+     */
+    sendTelemetry(event: TelemetryEvent): void;
+    /**
+     * Emit a custom event to all WebSocket connections
+     *
+     * This sends a custom event message that can be received by frontend
+     * clients using the onThreadEvent hook.
+     *
+     * @param type - The event type name
+     * @param data - The event payload (any serializable data)
+     */
+    emitEvent(type: string, data: unknown): void;
+    /**
+     * Add a WebSocket connection for telemetry
+     */
+    addWebSocket(ws: WebSocket): void;
+    /**
+     * Add a before close hook
+     */
+    addBeforeClose(hook: BeforeClose | BeforeClose[]): void;
+    /**
+     * Wait for a callback to complete before allowing stream to close
+     */
+    waitFor(callback: () => Promise<void> | void): Promise<void>;
+    /**
+     * Close a channel (decrement active channel count)
+     */
+    closeChannel(): void;
+    /**
+     * Close all streams and connections
+     */
+    close(): Promise<void>;
+    /**
+     * Force close the stream immediately
+     */
+    forceClose(): void;
+}
+
+/** Decrement helper to stop recursion at depth 0 */
+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 node for tool arguments.
+ * Tweak this union as your single source of truth for what’s allowed.
+ * Increase the default depth if you need crazier nesting.
+ */
+type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodEnum<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 an object whose values are ToolArgsNode.
+ * This is what users write inside z.object({ ... }).
+ */
+type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
+/** The top-level schema must be an object for OpenAI tools. */
+type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
+type StructuredToolReturn = ToolArgs;
+/**
+ * Defines a tool function. Tools accept the current flow state as well as the arguments being passed to them.
+ */
+type Tool<Args extends ToolArgs | null = null> = Args extends ToolArgs ? (flow: FlowState, args: z.infer<Args>) => Promise<CallToolResult> : (flow: FlowState) => Promise<CallToolResult>;
+/**
+ * @param toolDescription - Description of what the tool does.
+ * @param args - The arguments for the tool.
+ * @param tool - The tool function.
+ * @returns A tuple containing the description, arguments and the tool function.
+ */
+declare function defineTool<Args extends ToolArgs>(toolDescription: string, args: Args, tool: Tool<Args>): [string, Args, Tool<Args>, null];
+declare function defineTool(toolDescription: string, tool: Tool<null>): [string, null, Tool<null>, null];
+declare function defineTool<Args extends ToolArgs, RetValue extends StructuredToolReturn>(toolDescription: string, args: Args, tool: Tool<Args>, returnSchema: RetValue): [string, Args, Tool<Args>, RetValue];
+
+/**
+ * Hook signatures for all available hooks
+ */
+interface HookSignatures {
+    /**
+     * Called before messages are filtered and sent to the LLM
+     * Receives SQL row data with all columns before transformation
+     * Return value is transformed into chat completion format
+     */
+    filter_messages: (state: FlowState, rows: Message[]) => Promise<Message[]>;
+    /**
+     * Called after message history is loaded and before sending to LLM
+     * Receives messages in chat completion format (already transformed)
+     */
+    prefilter_llm_history: (state: FlowState, messages: Array<{
+        role: string;
+        content: string | null;
+        tool_calls?: any;
+        tool_call_id?: string;
+        name?: string;
+    }>) => Promise<Array<{
+        role: string;
+        content: string | null;
+        tool_calls?: any;
+        tool_call_id?: string;
+        name?: string;
+    }>>;
+    /**
+     * Called before a message is created in the database
+     */
+    before_create_message: (state: FlowState, message: Record<string, any>) => Promise<Record<string, any>>;
+    /**
+     * Called after a message is created in the database
+     */
+    after_create_message: (state: FlowState, message: Record<string, any>) => Promise<void>;
+    /**
+     * Called before a message is updated in the database
+     */
+    before_update_message: (state: FlowState, messageId: string, updates: Record<string, any>) => Promise<Record<string, any>>;
+    /**
+     * Called after a message is updated in the database
+     */
+    after_update_message: (state: FlowState, message: Message) => Promise<void>;
+    /**
+     * Called before a tool result is stored in the database
+     */
+    before_store_tool_result: (state: FlowState, toolCall: Record<string, any>, toolResult: Record<string, any>) => Promise<Record<string, any>>;
+    /**
+     * Called after a successful tool call
+     */
+    after_tool_call_success: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
+    /**
+     * Called after a failed tool call
+     */
+    after_tool_call_failure: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
+}
+/**
+ * Define a hook with strict typing based on hook name
+ *
+ * @example
+ * ```typescript
+ * export default defineHook('filter_messages', async (state, rows) => {
+ *   // Only include messages from last 10 turns
+ *   return rows.slice(-10);
+ * });
+ * ```
+ */
+declare function defineHook<K extends keyof HookSignatures>(hookName: K, implementation: HookSignatures[K]): HookSignatures[K];
+
+/**
+ * Agent configuration from D1 agents table
+ */
+interface Agent {
+    id: string;
+    title: string;
+    type: "dual_ai" | "ai_human";
+    created_at: number;
+    max_session_turns: number | null;
+    side_a_label: string | null;
+    side_a_agent_prompt: string | null;
+    side_a_stop_on_response: boolean;
+    side_a_stop_tool: string | null;
+    side_a_stop_tool_response_property: string | null;
+    side_a_max_turns: number | null;
+    side_a_end_conversation_tool: string | null;
+    side_b_label: string | null;
+    side_b_agent_prompt: string | null;
+    side_b_stop_on_response: boolean;
+    side_b_stop_tool: string | null;
+    side_b_stop_tool_response_property: string | null;
+    side_b_max_turns: number | null;
+    side_b_end_conversation_tool: string | null;
+}
+/**
+ * Message in OpenAI chat completion format
+ */
+interface Message {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    name?: string | null;
+    tool_calls?: string | null;
+    tool_call_id?: string | null;
+    log_id?: string | null;
+    created_at: number;
+    request_sent_at?: number | null;
+    response_completed_at?: number | null;
+    status?: "pending" | "completed" | "failed";
+    silent?: boolean;
+    tool_status?: "success" | "error" | null;
+    reasoning_content?: string | null;
+    reasoning_details?: string | null;
+    parent_id?: string | null;
+    depth?: number;
+}
+/**
+ * Tool call from OpenAI format
+ */
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+    forceAllow?: boolean;
+}
+/**
+ * Thread metadata from DurableAgentBuilder
+ * Note: agent_id is now the agent name (not UUID) since agents are in TypeScript
+ */
+interface ThreadMetadata {
+    id: string;
+    agent_id: string;
+    user_id: string | null;
+    created_at: number;
+}
+/**
+ * Hook registry type - transforms HookSignatures into lazy-loaded optional hooks
+ */
+type HookRegistry = {
+    [K in keyof HookSignatures]?: () => Promise<HookSignatures[K]>;
+};
+/**
+ * Thread instance (forward reference to avoid circular dependency)
+ */
+interface ThreadInstance {
+    ctx: DurableObjectState;
+    env: ThreadEnv;
+    getMessages(limit?: number, offset?: number, order?: "asc" | "desc", includeSilent?: boolean, maxDepth?: number): Promise<{
+        messages: Message[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    getLogs(limit?: number, offset?: number, order?: "asc" | "desc"): Promise<LogData[]>;
+    getThreadMeta(threadId: string): Promise<ThreadMetadata | null>;
+    shouldStop(): Promise<boolean>;
+    tools(): Record<string, () => Promise<ReturnType<typeof defineTool>>>;
+    hooks(): HookRegistry;
+}
+/**
+ * Tool call for internal flow management
+ */
+type FlowToolCall = {
+    tool: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Prompt call for internal flow management
+ */
+type FlowPromptCall = {
+    prompt: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Flow call (tool or prompt)
+ */
+type FlowCall = FlowToolCall | FlowPromptCall;
+/**
+ * Flow call with retry tracking
+ */
+type FlowCallWithRetries = FlowCall & {
+    retries: number;
+    reasons: string[];
+};
+/**
+ * Tool configuration for a prompt - defines options for when a tool is used
+ */
+interface ToolConfig$1 {
+    name: string;
+    initUserMessageProperty?: string;
+    includeTextResponse?: boolean;
+    includeToolCalls?: boolean;
+    includeErrors?: boolean;
+}
+/**
+ * Prompt configuration - now loaded from TypeScript virtual modules
+ */
+interface PromptData {
+    id: string;
+    name: string;
+    prompt: string | any[];
+    system_prompt?: string;
+    model: string;
+    model_id?: string;
+    tool_description: string;
+    required_schema: string;
+    include_chat: boolean;
+    include_past_tools: boolean;
+    before_tool: string | null;
+    after_tool: string | null;
+    prompts: string;
+    created_at: number;
+    /** @deprecated All prompts are now automatically exposed as tools */
+    expose_as_tool?: boolean;
+    parallel_tool_calls: boolean;
+    tool_choice: "auto" | "none" | "required" | "function";
+    reasoning_effort: "low" | "medium" | "high" | null;
+    reasoning_max_tokens: number | null;
+    reasoning_exclude: boolean;
+    include_reasoning: boolean;
+    _tools?: (string | ToolConfig$1)[];
+    _handoffAgents?: string[];
+    _requiredSchema?: any;
+}
+/**
+ * Central state object that flows through execution
+ */
+interface FlowState {
+    threadId: string;
+    flowId: string;
+    thread: {
+        instance: ThreadInstance;
+        metadata: ThreadMetadata;
+    };
+    agentConfig: Agent;
+    currentSide: "a" | "b";
+    prompts: {
+        sideA: PromptData;
+        sideB: PromptData | null;
+    };
+    prompt: PromptData;
+    turnCount: number;
+    sideATurnCount: number;
+    sideBTurnCount: number;
+    stopped: boolean;
+    stoppedBy?: "a" | "b";
+    forcedNextSide?: "side_a" | "side_b";
+    pendingForceTurn?: "side_a" | "side_b";
+    abortController?: AbortController;
+    messageHistory: Message[];
+    /**
+     * Appends these messages
+     */
+    extraMessages: Message[];
+    sequence: {
+        queue: ToolCall[];
+        isHandling: boolean;
+    };
+    active: FlowCallWithRetries;
+    queue: FlowCall[];
+    pendingHandoff?: {
+        agentId: string;
+    };
+    stream: StreamManager;
+    context: Record<string, unknown>;
+    retryCount: number;
+    retryReason?: string;
+    storage: DurableObjectStorage;
+    env: ThreadEnv;
+    emitLog?: (log: unknown) => void;
+    emitMessage?: (message: unknown) => void;
+    emitMessageChunk?: (messageId: string, chunk: string, depth?: number) => void;
+    rootState: FlowState;
+    rootMessageId?: string | null;
+    parentLogId?: string | null;
+    currentLogId?: string | null;
+    parentMessageId?: string;
+    depth: number;
+    pendingMessageId?: string;
+    allowedTools?: ToolDefinition[];
+}
+/**
+ * Request context for LLM calls
+ */
+interface RequestContext {
+    messages: Array<{
+        role: "system" | "user" | "assistant" | "tool";
+        content?: string;
+        tool_calls?: ToolCall[];
+        tool_call_id?: string;
+        name?: string;
+    }>;
+    model: string;
+    tools?: ToolDefinition[];
+    stream?: boolean;
+    promptName?: string;
+    systemPrompt?: string;
+    parentLogId?: string | null;
+    parallel_tool_calls?: boolean;
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    reasoning?: {
+        effort?: "low" | "medium" | "high";
+        max_tokens?: number;
+        exclude?: boolean;
+    };
+}
+/**
+ * Tool definition for LLM requests
+ */
+interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters?: Record<string, any>;
+    };
+}
+/**
+ * LLM response
+ */
+interface LLMResponse {
+    id: string;
+    model: string;
+    content: string | null;
+    reasoning_content?: string | null;
+    reasoning_details?: any[];
+    tool_calls?: ToolCall[];
+    finish_reason: string;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        prompt_tokens_details?: {
+            cached_tokens?: number;
+        };
+        completion_tokens_details?: {
+            reasoning_tokens?: number;
+        };
+        cost?: number;
+        provider?: string;
+    };
+}
+/**
+ * Tool result
+ */
+interface ToolResult {
+    status: "success" | "error";
+    /**
+     * Flattened text representation of the tool output.
+     *
+     * For tools that return structured MCP-style content (an array of
+     * content parts), this will be derived by concatenating all text
+     * parts. For legacy tools that returned a plain string `result`,
+     * that value is used directly.
+     */
+    result?: string;
+    error?: string;
+    stack?: string;
+}
+/**
+ * Flow execution result
+ */
+interface FlowResult {
+    messages: Message[];
+    stopped: boolean;
+    stoppedBy?: "a" | "b";
+    turnCount: number;
+    stream: ReadableStream<Uint8Array>;
+}
+/**
+ * Telemetry event types
+ */
+type TelemetryEvent = {
+    type: "turn_started";
+    turn: number;
+    side: "a" | "b";
+    timestamp: number;
+} | {
+    type: "turn_completed";
+    turn: number;
+    stopped: boolean;
+    timestamp: number;
+} | {
+    type: "llm_request";
+    model: string;
+    attempt: number;
+    timestamp: number;
+} | {
+    type: "llm_response";
+    tokens: number;
+    latency: number;
+    timestamp: number;
+} | {
+    type: "validation_failed";
+    error: string;
+    timestamp: number;
+} | {
+    type: "fallback_triggered";
+    from: string;
+    to: string;
+    timestamp: number;
+} | {
+    type: "tool_started";
+    tool: string;
+    timestamp: number;
+} | {
+    type: "tool_completed";
+    tool: string;
+    status: string;
+    timestamp: number;
+} | {
+    type: "stopped";
+    reason: string;
+    side: "a" | "b";
+    timestamp: number;
+} | {
+    type: "stopped_by_user";
+    timestamp: number;
+};
+/**
+ * Log data for telemetry table
+ */
+interface LogData {
+    id: string;
+    message_id: string;
+    provider: string;
+    model: string;
+    model_name?: string;
+    endpoint?: string;
+    request_body?: string;
+    request_headers?: string;
+    response_body?: string;
+    response_headers?: string;
+    status_code?: number;
+    reasoning_content?: string | null;
+    input_tokens?: number;
+    cached_tokens?: number;
+    output_tokens?: number;
+    reasoning_tokens?: number;
+    total_tokens?: number;
+    latency_ms?: number;
+    time_to_first_token_ms?: number;
+    finish_reason?: string;
+    error?: string;
+    error_type?: string;
+    cost_input?: number;
+    cost_output?: number;
+    cost_total?: number;
+    message_history_length?: number;
+    tools_available?: number;
+    prompt_name?: string;
+    tools_called?: string;
+    parent_log_id?: string | null;
+    tools_schema?: string | null;
+    message_history?: string | null;
+    system_prompt?: string | null;
+    is_complete?: boolean;
+    errors?: string | null;
+    retry_of_log_id?: string | null;
+    created_at: number;
+}
+
+/**
+ * Minimum required environment bindings for thread endpoints.
+ * User's Env interface should extend this.
+ */
+interface ThreadEnv {
+    AGENT_BUILDER_THREAD: DurableObjectNamespace;
+    AGENT_BUILDER: DurableObjectNamespace;
+}
+interface ControllerContext<Env = any> {
+    req: Request;
+    params: Record<string, string>;
+    env: Env;
+    url: URL;
+}
+type Controller<Env = any> = (context: ControllerContext<Env>) => string | Promise<string> | Response | Promise<Response> | ReadableStream | Promise<ReadableStream> | null | Promise<null> | void | Promise<void> | Promise<object> | object;
+interface ThreadEndpointContext {
+    req: Request;
+    thread: {
+        instance: ThreadInstance;
+        metadata: ThreadMetadata;
+    };
+}
+declare function defineController<Env = any>(controller: Controller<Env>): Controller<Env>;
+/**
+ * Define a thread-specific endpoint that has access to the thread's DurableObject instance and metadata.
+ * This wraps defineController and automatically looks up the thread by ID from the URL params.
+ *
+ * @param handler - Function that receives the request and thread context
+ * @returns A Controller that can be used with the router
+ *
+ * @example
+ * // agentbuilder/api/status.ts
+ * export default defineThreadEndpoint(async (req, { thread }) => {
+ *   const messages = await thread.instance.getMessages();
+ *   return Response.json({ status: "ok", messageCount: messages.length });
+ * });
+ */
+declare function defineThreadEndpoint<Env extends ThreadEnv = ThreadEnv>(handler: (req: Request, context: ThreadEndpointContext["thread"]) => Response | Promise<Response>): Controller<Env>;
+
+/**
+ * Authentication middleware for protecting API routes
+ *
+ * Supports multiple authentication types:
+ * - Super admin token (signed with ENCRYPTION_KEY)
+ * - User session token (validated against DurableAgentBuilder)
+ * - API key (validated against DurableAgentBuilder)
+ */
+interface AuthUser {
+    id: string;
+    username: string;
+    role: string;
+}
+interface AuthContext {
+    user: AuthUser;
+    authType: 'super_admin' | 'session' | 'api_key';
+}
+/**
+ * Authenticate a request using various token types
+ */
+declare function authenticate(request: Request, env: any): Promise<AuthContext | null>;
+/**
+ * Middleware to require authentication
+ * Returns 401 if not authenticated
+ */
+declare function requireAuth(request: Request, env: any): Promise<AuthContext | Response>;
+/**
+ * Middleware to require admin role
+ * Returns 401 if not authenticated, 403 if not admin
+ */
+declare function requireAdmin(request: Request, env: any): Promise<AuthContext | Response>;
+
+declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableObject<Env> {
+    private migratedToVersion;
+    private logSockets;
+    private messageSockets;
+    private alarmQueue;
+    private currentAbortController;
+    private isExecuting;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * Returns the tools registry for this thread.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of tool name to tool loader function
+     *
+     * @example
+     * ```typescript
+     * import { DurableThread } from 'virtual:@standardagents/builder'
+     *
+     * export class Thread extends DurableThread {}
+     * ```
+     */
+    tools(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the hooks registry for this thread.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of hook name to hook loader function
+     *
+     * @example
+     * ```typescript
+     * import { DurableThread } from 'virtual:@standardagents/builder'
+     *
+     * export class Thread extends DurableThread {}
+     * ```
+     */
+    hooks(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the models registry for lazy-loading model definitions.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of model name to model loader function
+     */
+    models(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the prompts registry for lazy-loading prompt definitions.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of prompt name to prompt loader function
+     */
+    prompts(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the agents registry for lazy-loading agent definitions.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of agent name to agent loader function
+     */
+    agents(): Record<string, () => Promise<any>>;
+    /**
+     * Load a model definition by name.
+     */
+    loadModel(name: string): Promise<any>;
+    /**
+     * List available model names.
+     */
+    getModelNames(): string[];
+    /**
+     * Load a prompt definition by name.
+     */
+    loadPrompt(name: string): Promise<any>;
+    /**
+     * List available prompt names.
+     */
+    getPromptNames(): string[];
+    /**
+     * Load an agent definition by name.
+     */
+    loadAgent(name: string): Promise<any>;
+    /**
+     * List available agent names.
+     */
+    getAgentNames(): string[];
+    /**
+     * Ensures the database schema is up to date.
+     * This method is called on the first request to the Durable Object.
+     * It checks the schema version and runs any pending migrations.
+     *
+     * Performance:
+     * - Already migrated to latest: ~0.1ms (single SELECT + integer comparison)
+     * - Needs migration: Runs once per Durable Object lifetime per schema version
+     * - Detects new migrations after code deployment
+     */
+    private ensureMigrated;
+    /**
+     * Gets the current schema version from the database.
+     * Returns 0 if the metadata table doesn't exist (brand new database).
+     */
+    private getCurrentVersion;
+    /**
+     * Runs all pending migrations sequentially.
+     * Each migration is run in order, starting from the current version + 1.
+     */
+    private runMigrations;
+    /**
+     * Legacy fetch handler for WebSocket upgrades only
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Execute thread with initial messages (RPC method)
+     * Enqueues the execution to be processed by the alarm handler
+     */
+    execute(threadId: string, agentId: string, initial_messages?: any[], data?: any): Promise<Response>;
+    /**
+     * Send a new message to the thread (RPC method)
+     * Enqueues the message processing to be handled by the alarm handler
+     */
+    sendMessage(threadId: string, content: string, role?: string): Promise<Response>;
+    /**
+     * Check if execution should be stopped (called by FlowEngine)
+     * Reads from SQLite for persistence across hibernation
+     */
+    shouldStop(): Promise<boolean>;
+    /**
+     * Stop the currently executing thread (RPC method)
+     * Simple "off" switch - stops turns, only cleared by user messages
+     */
+    stop(): Promise<Response>;
+    /**
+     * Get message history (RPC method)
+     *
+     * By default, returns the newest messages (when truncating), but in chronological
+     * order (oldest first in the array). This is ideal for chat UIs where messages
+     * should be appended and scrolled to the bottom.
+     *
+     * The offset parameter allows "scrolling up" to view older messages.
+     *
+     * Example:
+     * - getMessages(10, 0) -> newest 10 messages, oldest first in array
+     * - getMessages(10, 10) -> next 10 older messages, oldest first in array
+     *
+     * @param limit Number of messages to return (default: 100)
+     * @param offset Number of newest messages to skip (default: 0)
+     * @param order Internal query order - "DESC" (default) fetches newest first then reverses
+     * @param includeSilent Include silent messages (UI-only messages)
+     * @param maxDepth Maximum depth to include (default: 0 for top-level only)
+     */
+    getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC", includeSilent?: boolean, maxDepth?: number): Promise<{
+        messages: {
+            id: string;
+            role: string;
+            content: string | null;
+            name: string | null;
+            tool_calls: string | null;
+            tool_call_id: string | null;
+            tool_status: "success" | "error" | null;
+            log_id: string | null;
+            created_at: number;
+            silent: boolean;
+            parent_id: string | null;
+            depth: number;
+            status: "pending" | "completed" | "failed" | null;
+            reasoning_content: string | null;
+            reasoning_details: string | null;
+        }[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Delete a message (RPC method)
+     */
+    deleteMessage(messageId: string): Promise<{
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+    }>;
+    /**
+     * Seed messages directly into the database (RPC method - for testing)
+     * This bypasses the normal message processing flow
+     */
+    seedMessages(args: {
+        messages: Array<{
+            id: string;
+            role: string;
+            content: string;
+            created_at: number;
+        }>;
+    }): Promise<{
+        success: boolean;
+        count: number;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        count?: undefined;
+    }>;
+    /**
+     * Get logs (RPC method)
+     */
+    getLogs(limit?: number, offset?: number, order?: "ASC" | "DESC"): Promise<{
+        logs: {
+            id: string;
+            message_id: string;
+            provider: string;
+            model: string;
+            model_name: string | null;
+            prompt_name: string | null;
+            tools_called: string | null;
+            parent_log_id: string | null;
+            retry_of_log_id: string | null;
+            error: string | null;
+            cost_total: number | null;
+            is_complete: boolean;
+            created_at: number;
+            request_body: string | null;
+        }[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * Get detailed information for a single log (RPC method)
+     * This includes all fields including large ones like request/response bodies
+     */
+    getLogDetails(logId: string): Promise<{
+        id: string;
+        message_id: string;
+        provider: string;
+        model: string;
+        model_name: string | null;
+        endpoint: string | null;
+        request_body: string | null;
+        request_headers: string | null;
+        response_body: string | null;
+        response_headers: string | null;
+        status_code: number | null;
+        reasoning_content: string | null;
+        input_tokens: number | null;
+        cached_tokens: number | null;
+        output_tokens: number | null;
+        reasoning_tokens: number | null;
+        total_tokens: number | null;
+        latency_ms: number | null;
+        time_to_first_token_ms: number | null;
+        finish_reason: string | null;
+        error: string | null;
+        error_type: string | null;
+        cost_input: number | null;
+        cost_output: number | null;
+        cost_total: number | null;
+        message_history_length: number | null;
+        tools_available: number | null;
+        prompt_name: string | null;
+        tools_called: string | null;
+        parent_log_id: string | null;
+        tools_schema: string | null;
+        message_history: string | null;
+        system_prompt: string | null;
+        errors: string | null;
+        retry_of_log_id: string | null;
+        tool_results: string | null;
+        is_complete: boolean;
+        created_at: number;
+    }>;
+    /**
+     * Get thread metadata (RPC method)
+     */
+    getThreadMeta(threadId: string): Promise<Response | {
+        thread: {
+            id: any;
+            agent_id: any;
+            user_id: any;
+            tags: any;
+            created_at: any;
+        };
+        agent: {
+            id: any;
+            title: any;
+            type: any;
+            side_a_label: any;
+            side_b_label: any;
+        } | null;
+        stats: {
+            message_count: number;
+            log_count: number;
+        };
+    }>;
+    /**
+     * Update thread metadata (RPC method)
+     * Calls the DurableAgentBuilder to update the thread registry
+     */
+    updateThreadMeta(threadId: string, params: {
+        agent_name?: string;
+        user_id?: string | null;
+        tags?: string[] | null;
+    }): Promise<{
+        success: boolean;
+        thread: {
+            id: any;
+            agent_id: any;
+            user_id: any;
+            tags: any;
+            created_at: any;
+        };
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        thread?: undefined;
+    }>;
+    /**
+     * Delete thread data completely (RPC method)
+     * This will permanently delete the Durable Object instance
+     */
+    deleteThread(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Handle WebSocket upgrade for real-time log streaming
+     * Uses Hibernation API to reduce costs during inactivity
+     */
+    private handleLogsWebSocketUpgrade;
+    /**
+     * Handle WebSocket upgrade for real-time message streaming
+     * Uses Hibernation API to reduce costs during inactivity
+     */
+    private handleMessagesWebSocketUpgrade;
+    /**
+     * Broadcast a log record to all connected WebSocket clients
+     */
+    private broadcastLog;
+    /**
+     * Broadcast a message record to all connected message WebSocket clients
+     * Filters silent messages based on each socket's includeSilent preference
+     */
+    private broadcastMessage;
+    /**
+     * Broadcast a content chunk for real-time streaming
+     * Does NOT update database - only broadcasts to connected clients
+     */
+    private broadcastMessageChunk;
+    /**
+     * WebSocket Hibernation API handler for incoming messages
+     * Called when a message is received on a hibernated WebSocket
+     */
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * WebSocket Hibernation API handler for connection close
+     * Called when a WebSocket connection is closed
+     */
+    webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
+    /**
+     * WebSocket Hibernation API handler for errors
+     * Called when a WebSocket encounters an error
+     */
+    webSocketError(ws: WebSocket, error: unknown): Promise<void>;
+    /**
+     * Alarm handler - called by Cloudflare when a scheduled alarm fires
+     * Processes the next item in the alarm queue
+     *
+     * Important: This method must NEVER throw an exception, as that would break
+     * the alarm chain. All errors are caught and logged.
+     */
+    alarm(): Promise<void>;
+    /**
+     * Internal method: Execute a flow (called by alarm queue)
+     * This is the actual execution logic, separate from the public execute() RPC method
+     */
+    private executeFlow;
+    /**
+     * Internal method: Process a message (called by alarm queue)
+     * This is the actual message processing logic, separate from the public sendMessage() RPC method
+     */
+    private processMessage;
+    /**
+     * TEST METHOD: Queue a test operation
+     * Used for testing alarm queue ordering and timing
+     */
+    queueTestOperation(id: string, label: string, expectedOrder: number, delayMs: number): Promise<Response>;
+    /**
+     * TEST METHOD: Get queue state
+     */
+    getQueueState(): Promise<Response>;
+    /**
+     * TEST METHOD: Get test execution logs
+     */
+    getTestLogs(): Promise<Response>;
+    /**
+     * TEST METHOD: Clear test logs
+     */
+    clearTestLogs(): Promise<Response>;
+    /**
+     * TEST METHOD: Insert a malformed message with orphaned tool calls
+     * This allows testing the tool call filtering logic
+     */
+    insertOrphanedToolCall(params: {
+        content?: string;
+        toolCallId: string;
+        toolName: string;
+        toolArgs: string;
+    }): Promise<Response>;
+    /**
+     * TEST METHOD: Execute a test operation
+     * Internal method called by alarm queue
+     */
+    private testOperation;
+}
+
+/**
+ * Environment type for DurableAgentBuilder.
+ * Users extend this with their own bindings.
+ */
+interface AgentBuilderEnv {
+    AGENT_BUILDER: DurableObjectNamespace<DurableAgentBuilder>;
+    AGENT_BUILDER_THREAD: DurableObjectNamespace;
+    GITHUB_TOKEN?: string;
+    GITHUB_REPO?: string;
+    GITHUB_BRANCH?: string;
+}
+/**
+ * Thread metadata stored in the registry.
+ */
+interface ThreadRegistryEntry {
+    id: string;
+    agent_name: string;
+    user_id: string | null;
+    tags: string[] | null;
+    created_at: number;
+}
+/**
+ * Parameters for updating a thread.
+ */
+interface UpdateThreadParams {
+    agent_name?: string;
+    user_id?: string | null;
+    tags?: string[] | null;
+}
+/**
+ * User record.
+ */
+interface User {
+    id: string;
+    username: string;
+    password_hash: string;
+    role: 'admin';
+    created_at: number;
+    updated_at: number;
+}
+/**
+ * Provider credentials.
+ */
+interface Provider {
+    name: string;
+    sdk: string;
+    api_key: string;
+}
+declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv> extends DurableObject<Env> {
+    private migratedToVersion;
+    private eventSockets;
+    constructor(ctx: DurableObjectState, env: Env);
+    /**
+     * Returns the tools registry for lazy-loading tool definitions.
+     * Must be overridden in a subclass.
+     */
+    tools(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the hooks registry for lazy-loading hook definitions.
+     * Must be overridden in a subclass.
+     */
+    hooks(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the models registry for lazy-loading model definitions.
+     * Must be overridden in a subclass.
+     */
+    models(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the prompts registry for lazy-loading prompt definitions.
+     * Must be overridden in a subclass.
+     */
+    prompts(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the agents registry for lazy-loading agent definitions.
+     * Must be overridden in a subclass.
+     */
+    agents(): Record<string, () => Promise<any>>;
+    private ensureMigrated;
+    private getCurrentVersion;
+    private runMigrations;
+    /**
+     * Create a new thread and add it to the registry.
+     */
+    createThread(params: {
+        agent_name: string;
+        user_id?: string;
+        tags?: string[];
+    }): Promise<ThreadRegistryEntry>;
+    /**
+     * Get a thread by ID.
+     */
+    getThread(id: string): Promise<ThreadRegistryEntry | null>;
+    /**
+     * List threads with optional filtering.
+     */
+    listThreads(params?: {
+        agent_name?: string;
+        user_id?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        threads: ThreadRegistryEntry[];
+        total: number;
+    }>;
+    /**
+     * Delete a thread from the registry.
+     */
+    deleteThread(id: string): Promise<boolean>;
+    /**
+     * Update a thread's agent_name (used during agent handoff).
+     */
+    updateThreadAgent(id: string, agent_name: string): Promise<boolean>;
+    /**
+     * Update a thread's metadata.
+     */
+    updateThread(id: string, params: UpdateThreadParams): Promise<ThreadRegistryEntry | null>;
+    /**
+     * Load a model definition by name.
+     */
+    loadModel(name: string): Promise<any>;
+    /**
+     * List available model names.
+     */
+    getModelNames(): string[];
+    /**
+     * Load a prompt definition by name.
+     */
+    loadPrompt(name: string): Promise<any>;
+    /**
+     * List available prompt names.
+     */
+    getPromptNames(): string[];
+    /**
+     * Load an agent definition by name.
+     */
+    loadAgent(name: string): Promise<any>;
+    /**
+     * List available agent names.
+     */
+    getAgentNames(): string[];
+    /**
+     * Get a provider's credentials.
+     */
+    getProvider(name: string): Promise<Provider | null>;
+    /**
+     * Set a provider's credentials.
+     */
+    setProvider(provider: Provider): Promise<void>;
+    /**
+     * List all providers.
+     */
+    listProviders(): Promise<Provider[]>;
+    /**
+     * Delete a provider.
+     */
+    deleteProvider(name: string): Promise<boolean>;
+    /**
+     * Get a user by username.
+     */
+    getUserByUsername(username: string): Promise<User | null>;
+    /**
+     * Get a user by ID.
+     */
+    getUserById(id: string): Promise<User | null>;
+    /**
+     * Create a new user.
+     */
+    createUser(params: {
+        username: string;
+        password_hash: string;
+        role?: 'admin';
+    }): Promise<User>;
+    /**
+     * Check if any users exist (for first-time setup).
+     */
+    hasUsers(): Promise<boolean>;
+    /**
+     * List all users (excludes password hash).
+     */
+    listUsers(): Promise<Array<{
+        id: string;
+        username: string;
+        role: 'admin';
+        created_at: number;
+        updated_at: number;
+    }>>;
+    /**
+     * Update a user.
+     */
+    updateUser(id: string, params: {
+        username?: string;
+        password_hash?: string;
+        role?: 'admin';
+    }): Promise<User | null>;
+    /**
+     * Delete a user.
+     */
+    deleteUser(id: string): Promise<boolean>;
+    /**
+     * Create a new session.
+     */
+    createSession(params: {
+        user_id: string;
+        token_hash: string;
+        expires_at: number;
+    }): Promise<string>;
+    /**
+     * Validate a session token.
+     */
+    validateSession(tokenHash: string): Promise<{
+        user_id: string;
+        expires_at: number;
+    } | null>;
+    /**
+     * Delete expired sessions.
+     */
+    cleanupSessions(): Promise<number>;
+    /**
+     * Delete a session.
+     */
+    deleteSession(tokenHash: string): Promise<void>;
+    /**
+     * Create an API key.
+     */
+    createApiKey(params: {
+        name: string;
+        key_hash: string;
+        key_prefix: string;
+        last_five: string;
+        user_id: string;
+    }): Promise<string>;
+    /**
+     * Validate an API key.
+     */
+    validateApiKey(keyHash: string): Promise<{
+        user_id: string;
+        id: string;
+    } | null>;
+    /**
+     * List API keys for a user.
+     */
+    listApiKeys(userId: string): Promise<Array<{
+        id: string;
+        name: string;
+        key_prefix: string;
+        last_five: string;
+        created_at: number;
+        last_used_at: number | null;
+    }>>;
+    /**
+     * Delete an API key.
+     */
+    deleteApiKey(id: string, userId: string): Promise<boolean>;
+    /**
+     * Link an OAuth account to a user.
+     */
+    linkOAuthAccount(params: {
+        user_id: string;
+        provider: 'github' | 'google';
+        provider_user_id: string;
+        provider_username?: string;
+    }): Promise<void>;
+    /**
+     * Find user by OAuth account.
+     */
+    findUserByOAuth(provider: 'github' | 'google', providerUserId: string): Promise<User | null>;
+    /**
+     * Acquire edit lock for GitHub commits.
+     */
+    acquireEditLock(params: {
+        locked_by: string;
+        lock_reason: string;
+    }): Promise<boolean>;
+    /**
+     * Release edit lock.
+     */
+    releaseEditLock(lockedBy: string): Promise<boolean>;
+    /**
+     * Get current lock state.
+     */
+    getEditLockState(): Promise<{
+        locked: boolean;
+        locked_by: string | null;
+        locked_at: number | null;
+        lock_reason: string | null;
+        pending_changes: string | null;
+    }>;
+    /**
+     * Store pending changes for commit.
+     */
+    setPendingChanges(changes: string): Promise<void>;
+    /**
+     * Get the Durable Object stub for a thread.
+     */
+    getThreadStub(threadId: string): DurableObjectStub;
+    /**
+     * Handle fetch requests - used for WebSocket upgrades
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Handle WebSocket upgrade for events channel
+     * Uses Hibernation API to reduce costs during inactivity
+     */
+    private handleEventsWebSocketUpgrade;
+    /**
+     * Broadcast an event to all connected WebSocket clients
+     */
+    private broadcastEvent;
+    /**
+     * WebSocket Hibernation API handler for incoming messages
+     * Called when a message is received on a hibernated WebSocket
+     */
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    /**
+     * WebSocket Hibernation API handler for connection close
+     * Called when a WebSocket connection is closed
+     */
+    webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
+    /**
+     * WebSocket Hibernation API handler for errors
+     * Called when a WebSocket encounters an error
+     */
+    webSocketError(ws: WebSocket, error: unknown): Promise<void>;
+}
+
+/**
+ * Model definition module for AgentBuilder.
+ *
+ * Models define LLM configurations including provider, model ID, pricing,
+ * and fallback chains. Models are referenced by name from prompts.
+ *
+ * @module
+ */
+/**
+ * Supported LLM provider types.
+ * 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`
+ */
+type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google';
+/**
+ * Model definition configuration.
+ *
+ * @template N - The model name as a string literal type for type inference
+ *
+ * @example
+ * ```typescript
+ * import { defineModel } from '@standardagents/builder';
+ *
+ * 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 models to try if this model fails.
+     * Referenced by model name (must be defined in agentbuilder/models/).
+     * Tried in order after primary model exhausts retries.
+     *
+     * @example ['gpt-4', 'gpt-3.5-turbo']
+     */
+    fallbacks?: AgentBuilder.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;
+}
+/**
+ * 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
+ * // agentbuilder/models/gpt_4o.ts
+ * import { defineModel } from '@standardagents/builder';
+ *
+ * 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>;
+
+/**
+ * Prompt definition module for AgentBuilder.
+ *
+ * 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.
+ * Uses AgentBuilder.Prompts for type-safe autocomplete of prompt names.
+ *
+ * @example
+ * ```typescript
+ * { type: 'include', prompt: 'responder_rules' }
+ * ```
+ */
+interface PromptIncludePart {
+    type: 'include';
+    /** The name of the prompt to include (type-safe with autocomplete) */
+    prompt: AgentBuilder.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 type-safe composition with other prompts via autocomplete.
+ *
+ * @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;
+/**
+ * Tool configuration for including a tool in a prompt.
+ *
+ * @template T - The tool name type (for type-safe tool references)
+ */
+interface ToolConfig<T extends string = AgentBuilder.Callables> {
+    /**
+     * Name of the tool to include.
+     * Must be a tool, prompt, or agent defined in agentbuilder/.
+     */
+    name: T;
+    /**
+     * Include text response content from sub-prompt execution in the tool result.
+     * @default true
+     */
+    includeTextResponse?: boolean;
+    /**
+     * Include tool call details from sub-prompt execution in the tool result.
+     * @default true
+     */
+    includeToolCalls?: boolean;
+    /**
+     * Include error details from sub-prompt execution in the tool result.
+     * @default true
+     */
+    includeErrors?: boolean;
+    /**
+     * Property from the tool call arguments to use as the initial user message
+     * when this tool triggers a sub-prompt execution.
+     *
+     * @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;
+}
+/**
+ * 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
+     * (Anthropic, Gemini, Qwen).
+     */
+    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/builder';
+ * import { z } from 'zod';
+ *
+ * export default definePrompt({
+ *   name: 'customer_support',
+ *   toolDescription: 'Handle customer support inquiries',
+ *   model: 'gpt-4o',
+ *   // Simple string prompt:
+ *   prompt: `You are a helpful customer support agent.
+ *     Always be polite and try to resolve issues quickly.`,
+ *   // Or structured prompt with type-safe includes:
+ *   // prompt: [
+ *   //   { type: 'text', content: 'You are a helpful customer support agent.\n\n' },
+ *   //   { type: 'include', prompt: 'common_rules' },
+ *   // ],
+ *   tools: ['search_knowledge_base', 'create_ticket'],
+ *   requiredSchema: z.object({
+ *     query: z.string().describe('The customer inquiry'),
+ *   }),
+ * });
+ * ```
+ */
+interface PromptDefinition<N extends string = string, S extends z.ZodTypeAny = z.ZodTypeAny> {
+    /**
+     * 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:
+     * 1. A plain string - simple prompt text
+     * 2. A structured array - for composing prompts with type-safe includes
+     *
+     * @example
+     * ```typescript
+     * // Simple string prompt:
+     * prompt: 'You are a helpful assistant.'
+     *
+     * // Structured prompt with type-safe includes:
+     * prompt: [
+     *   { type: 'text', content: 'You are a helpful assistant.\n\n' },
+     *   { type: 'include', prompt: 'common_rules' }, // autocomplete for prompt names!
+     *   { type: 'text', content: '\n\nBe concise.' },
+     * ]
+     * ```
+     */
+    prompt: PromptContent;
+    /**
+     * Model to use for this prompt.
+     * Must reference a model defined in agentbuilder/models/.
+     * Provides autocomplete when types are generated.
+     */
+    model: AgentBuilder.Models;
+    /**
+     * @deprecated All prompts are now automatically exposed as tools.
+     * This property is ignored and will be removed in a future version.
+     */
+    exposeAsTool?: boolean;
+    /**
+     * Include full chat history in the LLM context.
+     * When true, all previous messages in the conversation are included.
+     * @default false
+     */
+    includeChat?: boolean;
+    /**
+     * Include results from past tool calls in the LLM context.
+     * When true, previous tool call results are visible to the LLM.
+     * @default false
+     */
+    includePastTools?: boolean;
+    /**
+     * Allow parallel execution of multiple tool calls.
+     * When true, if the LLM requests multiple tools, they execute concurrently.
+     * @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.
+     *
+     * The schema provides:
+     * - Runtime validation of tool call arguments
+     * - Type inference for the prompt's input type
+     * - Auto-generated JSON Schema for LLM tool definitions
+     *
+     * Use `.describe()` on schema fields to provide descriptions for the LLM.
+     *
+     * @example
+     * ```typescript
+     * requiredSchema: z.object({
+     *   query: z.string().describe('The search query'),
+     *   limit: z.number().optional().default(10).describe('Max results'),
+     * })
+     * ```
+     */
+    requiredSchema?: S;
+    /**
+     * Tools available to this prompt.
+     * Can be simple tool names or detailed configurations.
+     *
+     * Tools can be:
+     * - Custom tools defined in agentbuilder/tools/
+     * - Other prompts with exposeAsTool: true
+     * - Agents with exposeAsTool: true
+     *
+     * @example
+     * ```typescript
+     * tools: [
+     *   'search_docs',  // Simple reference
+     *   { name: 'create_ticket', includeErrors: false },  // With config
+     * ]
+     * ```
+     */
+    tools?: (AgentBuilder.Callables | ToolConfig)[];
+    /**
+     * Agents that can receive handoffs from this prompt.
+     * Enables multi-agent workflows where this prompt can transfer
+     * the conversation to a specialized agent.
+     */
+    handoffAgents?: AgentBuilder.Agents[];
+    /**
+     * Tool to execute before the LLM request.
+     * Useful for data fetching, context preparation, or preprocessing.
+     * The tool result is available in the prompt context.
+     */
+    beforeTool?: AgentBuilder.Callables;
+    /**
+     * Tool to execute after the LLM response.
+     * Useful for post-processing, logging, or side effects.
+     */
+    afterTool?: AgentBuilder.Callables;
+    /**
+     * Reasoning configuration for models that support extended thinking.
+     * Configure effort level, token limits, and visibility of reasoning.
+     */
+    reasoning?: ReasoningConfig;
+}
+/**
+ * Helper type to extract the inferred input type from a prompt's Zod schema.
+ *
+ * @template T - The prompt definition type
+ *
+ * @example
+ * ```typescript
+ * const searchPrompt = definePrompt({
+ *   name: 'search',
+ *   requiredSchema: z.object({ query: z.string(), limit: z.number() }),
+ *   // ...
+ * });
+ *
+ * type SearchInput = PromptInput<typeof searchPrompt>;
+ * // { query: string; limit: number }
+ * ```
+ */
+type PromptInput<T extends PromptDefinition<any, any>> = T['requiredSchema'] extends z.ZodTypeAny ? 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
+ * // agentbuilder/prompts/customer_support.ts
+ * import { definePrompt } from '@standardagents/builder';
+ * 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.
+ *     Always be polite and try to resolve issues quickly.
+ *     If you cannot help, offer to escalate to a human.`,
+ *   tools: ['search_knowledge_base', 'create_ticket'],
+ *   handoffAgents: ['escalation_agent'],
+ *   includeChat: true,
+ *   exposeAsTool: true,
+ *   requiredSchema: z.object({
+ *     query: z.string().describe('The customer inquiry'),
+ *   }),
+ * });
+ * ```
+ */
+declare function definePrompt<N extends string, S extends z.ZodTypeAny = never>(options: PromptDefinition<N, S>): PromptDefinition<N, S>;
+
+/**
+ * Agent definition module for AgentBuilder.
+ *
+ * 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.
+ */
+interface SideConfig {
+    /**
+     * 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 agentbuilder/prompts/.
+     */
+    prompt: AgentBuilder.Prompts;
+    /**
+     * 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?: AgentBuilder.Callables;
+    /**
+     * 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 turns for this side before forcing a stop.
+     * Safety limit to prevent runaway conversations.
+     * A turn is one complete request/response cycle.
+     */
+    maxTurns?: number;
+    /**
+     * Tool that ends the entire conversation when called.
+     * Different from stopTool - this ends the conversation for both sides,
+     * not just this side's turn.
+     */
+    endConversationTool?: AgentBuilder.Callables;
+    /**
+     * Enable manual stop condition handling via hooks.
+     * When true, stop conditions are evaluated by custom hook logic
+     * instead of the built-in rules.
+     * @default false
+     */
+    manualStopCondition?: boolean;
+}
+/**
+ * Agent definition configuration.
+ *
+ * @template N - The agent name as a string literal type
+ *
+ * @example
+ * ```typescript
+ * import { defineAgent } from '@standardagents/builder';
+ *
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *   },
+ *   tags: ['support', 'tier-1'],
+ * });
+ * ```
+ */
+interface AgentDefinition<N 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Tags for categorization and filtering.
+     * Useful for organizing agents in the UI and filtering in queries.
+     *
+     * @example ['customer-service', 'tier-1', 'english']
+     */
+    tags?: 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
+ * // agentbuilder/agents/support_agent.ts
+ * import { defineAgent } from '@standardagents/builder';
+ *
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *     endConversationTool: 'close_ticket',
+ *   },
+ *   exposeAsTool: true,
+ *   toolDescription: 'Hand off to customer support',
+ *   tags: ['support', 'tier-1'],
+ * });
+ * ```
+ *
+ * @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,
+ *     endConversationTool: 'conclude_debate',
+ *   },
+ * });
+ * ```
+ */
+declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
+
+/**
+ * Generate a TypeScript file for a model definition.
+ */
+declare function generateModelFile(data: ModelDefinition): string;
+
+/**
+ * Converts JSON Schema to Zod code string.
+ *
+ * This is used when saving prompts from the UI - the form editor works with
+ * JSON Schema, but we need to generate Zod code for the TypeScript file.
+ */
+interface JSONSchema {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema;
+    enum?: (string | number | boolean)[];
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    const?: any;
+    default?: any;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    additionalProperties?: boolean | JSONSchema;
+    nullable?: boolean;
+}
+
+/**
+ * Tool configuration from UI (snake_case).
+ */
+interface ToolConfigInput {
+    name: string;
+    include_text_response?: boolean;
+    include_tool_calls?: boolean;
+    include_errors?: boolean;
+    init_user_message_property?: string | null;
+}
+/**
+ * Prompt part as it comes from the UI/API.
+ * Supports both new format (type: 'text'/'include') and legacy format (type: 'string'/'prompt')
+ */
+interface PromptPartInput {
+    type: 'text' | 'include' | 'string' | 'prompt' | 'variable';
+    content?: string;
+    prompt?: string;
+    value?: string;
+    id?: string;
+    label?: string;
+    schema?: any;
+}
+/**
+ * Input data for generating a prompt file.
+ * This can include JSON Schema for requiredSchema which will be converted to Zod.
+ */
+interface PromptFileData {
+    name: string;
+    toolDescription?: string;
+    /**
+     * Prompt content can be:
+     * - A plain string
+     * - A structured array of prompt parts
+     * - A JSON string of a structured array (legacy format from UI)
+     */
+    prompt?: string | PromptPartInput[];
+    model: string;
+    includeChat?: boolean;
+    includePastTools?: boolean;
+    parallelToolCalls?: boolean;
+    toolChoice?: 'auto' | 'none' | 'required';
+    tools?: (string | ToolConfigInput)[];
+    handoffAgents?: string[];
+    beforeTool?: string;
+    afterTool?: string;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+        exclude?: boolean;
+        include?: boolean;
+    };
+    /**
+     * Required schema as JSON Schema (from the UI).
+     * Will be converted to Zod code.
+     */
+    requiredSchema?: JSONSchema;
+}
+/**
+ * Generate a TypeScript file for a prompt definition.
+ *
+ * @param data - Prompt data including JSON Schema for requiredSchema
+ * @returns TypeScript code as a string
+ */
+declare function generatePromptFile(data: PromptFileData): string;
+
+/**
+ * Generate a TypeScript file for an agent definition.
+ */
+declare function generateAgentFile(data: AgentDefinition): string;
+
+/**
+ * Options for injecting a message
+ */
+interface InjectMessageOptions$1 {
+    /** The message content */
+    content: string;
+    /** The message role */
+    role: "system" | "user" | "assistant" | "tool";
+    /** Optional message ID. If not provided, a UUID will be generated */
+    id?: string;
+    /** Optional message to insert before. If not provided, message is appended to the end */
+    beforeMessageId?: string;
+    /** Optional tool call ID (for role="tool" only) */
+    toolCallId?: string;
+    /** Optional name field */
+    name?: string;
+    /** Whether this message is silent (hidden from LLM, visible in UI only). Default: false */
+    silent?: boolean;
+    /** Force message to be top-level (depth 0) even when called from sub-prompts. Default: false */
+    forceTopLevel?: boolean;
+    /** Force a specific side to play the next turn after injecting the message */
+    forceTurn?: "side_a" | "side_b";
+}
+/**
+ * Queue a new tool call to be executed in the current flow
+ *
+ * This adds a tool call to the execution queue without immediately executing it.
+ * The tool will be executed as part of the normal flow processing.
+ *
+ * @param flow - The current FlowState
+ * @param toolName - The name of the tool to call
+ * @param args - The arguments to pass to the tool
+ *
+ * @example
+ * ```typescript
+ * import { queueTool } from '@standardagents/builder';
+ *
+ * queueTool(flow, "search_user", { email: "user@example.com" });
+ * ```
+ */
+declare function queueTool(flow: FlowState, toolName: string, args?: Record<string, unknown>): void;
+/**
+ * Inject a message into the thread without triggering execution
+ *
+ * This allows you to add messages to the conversation history programmatically.
+ * The message is persisted to storage but does not cause the agent to execute.
+ *
+ * By default, messages are appended to the end of the conversation.
+ * You can optionally insert a message before another message by providing beforeMessageId.
+ *
+ * @param flow - The current FlowState
+ * @param options - Message options
+ *
+ * @example
+ * ```typescript
+ * import { injectMessage } from '@standardagents/builder';
+ *
+ * // Append a system message
+ * await injectMessage(flow, {
+ *   role: "system",
+ *   content: "Context has been updated"
+ * });
+ *
+ * // Insert a user message before a specific message
+ * await injectMessage(flow, {
+ *   role: "user",
+ *   content: "Additional context",
+ *   beforeMessageId: "msg-123"
+ * });
+ *
+ * // Inject a message and force a specific side to play next
+ * await injectMessage(flow, {
+ *   role: "system",
+ *   content: "New instructions for the AI",
+ *   forceTurn: "side_a" // Force side_a to respond to this message
+ * });
+ * ```
+ */
+declare function injectMessage(flow: FlowState, options: InjectMessageOptions$1): Promise<Message>;
+/**
+ * Get messages from the thread history
+ *
+ * Retrieves message history from the thread's SQLite storage.
+ * Messages are ordered by creation time (oldest first by default).
+ *
+ * @param flow - The current FlowState
+ * @param limit - Maximum number of messages to retrieve (default: 100)
+ * @param offset - Number of messages to skip (default: 0)
+ * @param order - Sort order: "asc" (oldest first) or "desc" (newest first) (default: "asc")
+ * @returns Array of messages
+ *
+ * @example
+ * ```typescript
+ * import { getMessages } from '@standardagents/builder';
+ *
+ * // Get last 10 messages
+ * const messages = await getMessages(flow, 10);
+ *
+ * // Get 10 messages, skipping the first 20
+ * const messages = await getMessages(flow, 10, 20);
+ *
+ * // Get newest 10 messages
+ * const messages = await getMessages(flow, 10, 0, "desc");
+ * ```
+ */
+declare function getMessages(flow: FlowState, limit?: number, offset?: number, order?: "asc" | "desc"): Promise<Message[]>;
+/**
+ * Reload message history from storage
+ *
+ * Re-loads the complete message history from the thread's SQLite storage,
+ * applying any filter_messages hooks. This is useful when you need to refresh
+ * the message history after making changes (e.g., injecting silent messages).
+ *
+ * @param flow - The current FlowState
+ * @returns Array of messages (reloaded from storage)
+ *
+ * @example
+ * ```typescript
+ * import { injectMessage, reloadHistory } from '@standardagents/builder';
+ *
+ * // Reload history after injecting a silent message
+ * await injectMessage(flow, { role: "system", content: "...", silent: true });
+ * flow.messageHistory = await reloadHistory(flow);
+ * ```
+ */
+declare function reloadHistory(state: FlowState): Promise<Message[]>;
+/**
+ * Emit a custom event to WebSocket clients via the stream
+ *
+ * Sends a custom event to all connected WebSocket clients on the stream channel.
+ * This allows backend code to push arbitrary data to the frontend
+ * outside of the standard message events.
+ *
+ * @param flow - The current FlowState
+ * @param type - The event type name (e.g., "progress", "notification")
+ * @param data - The event payload (any serializable data)
+ *
+ * @example
+ * ```typescript
+ * import { emitThreadEvent } from '@standardagents/builder';
+ *
+ * // Emit a progress update
+ * emitThreadEvent(flow, "progress", { step: 3, total: 10, message: "Processing data..." });
+ *
+ * // Emit a custom notification
+ * emitThreadEvent(flow, "notification", { level: "info", message: "User authenticated" });
+ *
+ * // Emit metadata
+ * emitThreadEvent(flow, "metadata", { userId: "123", sessionId: "abc" });
+ * ```
+ */
+declare function emitThreadEvent(flow: FlowState, type: string, data: unknown): void;
+/**
+ * Force a specific side to play the next turn
+ *
+ * This queues the specified side to play next without interrupting the current turn.
+ * The forced turn only takes effect at the END of the current turn execution.
+ *
+ * If the tool queue is currently being processed (sequence.isHandling is true),
+ * the forced turn is deferred until all queued tools complete. This allows patterns like:
+ *
+ * ```typescript
+ * import { queueTool, forceTurn } from '@standardagents/builder';
+ *
+ * queueTool(flow, 'myTool', {});
+ * forceTurn(flow, 'side_a');
+ * // myTool executes first, THEN the turn switches to side_a
+ * ```
+ *
+ * @param flow - The current FlowState
+ * @param side - Which side should play next ('side_a' or 'side_b')
+ *
+ * @example
+ * ```typescript
+ * import { forceTurn } from '@standardagents/builder';
+ *
+ * // Force current side to continue (override stop condition)
+ * // If side_a is playing and would stop, this forces it to play at least 1 more turn
+ * forceTurn(flow, 'side_a');
+ *
+ * // Force switch to other side
+ * // If side_a is playing, this forces side_b to play next turn
+ * forceTurn(flow, 'side_b');
+ *
+ * // Force human turn in ai_human agent (execution stops and waits for user input)
+ * if (flow.agentConfig.type === 'ai_human') {
+ *   forceTurn(flow, 'side_b'); // Stops execution, awaits user input
+ * }
+ * ```
+ */
+declare function forceTurn(flow: FlowState, side: 'side_a' | 'side_b'): void;
+/**
+ * Thread context from defineThreadEndpoint
+ */
+interface ThreadContext {
+    instance: {
+        updateThreadMeta: (threadId: string, params: {
+            agent_name?: string;
+            user_id?: string | null;
+            tags?: string[] | null;
+        }) => Promise<{
+            success: boolean;
+            error?: string;
+            thread?: {
+                id: string;
+                agent_id: string;
+                user_id: string | null;
+                tags: string[];
+                created_at: number;
+            };
+        }>;
+    };
+    metadata: {
+        id: string;
+        agent_name: string;
+        user_id: string | null;
+        tags: string[] | null;
+        created_at: number;
+    };
+}
+/**
+ * Update a thread's metadata in the DurableAgentBuilder registry
+ *
+ * This allows updating the agent_name, user_id, and tags for an existing thread.
+ * Uses the thread instance from defineThreadEndpoint context.
+ *
+ * @param thread - The thread context from defineThreadEndpoint ({ instance, metadata })
+ * @param params - The fields to update (agent_name, user_id, tags)
+ * @returns The updated thread info, or null if update failed
+ *
+ * @example
+ * ```typescript
+ * import { defineThreadEndpoint, updateThread } from '@standardagents/builder';
+ *
+ * export default defineThreadEndpoint(async (req, thread) => {
+ *   // Update thread's user_id
+ *   await updateThread(thread, { user_id: 'user-123' });
+ *
+ *   // Update thread's tags
+ *   await updateThread(thread, { tags: ['support', 'urgent'] });
+ *
+ *   // Update multiple fields
+ *   const result = await updateThread(thread, {
+ *     agent_name: 'new-agent',
+ *     user_id: 'user-456',
+ *     tags: ['sales']
+ *   });
+ *
+ *   return Response.json(result);
+ * });
+ * ```
+ */
+declare function updateThread(thread: ThreadContext, params: {
+    agent_name?: string;
+    user_id?: string | null;
+    tags?: string[] | null;
+}): Promise<{
+    id: string;
+    agent_id: string;
+    user_id: string | null;
+    tags: string[];
+    created_at: number;
+} | null>;
+
+/**
+ * Options for injecting a message
+ */
+interface InjectMessageOptions {
+    /** The message content */
+    content: string;
+    /** The message role */
+    role: "system" | "user" | "assistant" | "tool";
+    /** Optional message ID. If not provided, a UUID will be generated */
+    id?: string;
+    /** Optional message to insert before. If not provided, message is appended to the end */
+    beforeMessageId?: string;
+    /** Optional tool call ID (for role="tool" only) */
+    toolCallId?: string;
+    /** Optional name field */
+    name?: string;
+    /** Whether this message is silent (hidden from LLM, visible in UI only). Default: false */
+    silent?: boolean;
+    /** Force message to be top-level (depth 0) even when called from sub-prompts. Default: false */
+    forceTopLevel?: boolean;
+    /** Force a specific side to play the next turn after injecting the message */
+    forceTurn?: "side_a" | "side_b";
+}
+/**
+ * Options for broadcasting custom data
+ */
+interface BroadcastOptions {
+    /** The type of the broadcast message */
+    type: string;
+    /** The value/payload of the broadcast message */
+    value: unknown;
+}
+/**
+ * FlowState SDK - Utility methods for working with FlowState
+ *
+ * These methods extend the FlowState object with helpful utilities for:
+ * - Queuing tool calls
+ * - Injecting messages
+ * - Retrieving message history
+ * - Broadcasting custom data via WebSocket
+ */
+declare class FlowStateSdk {
+    /**
+     * Queue a new tool call to be executed in the current flow
+     *
+     * This adds a tool call to the execution queue without immediately executing it.
+     * The tool will be executed as part of the normal flow processing.
+     *
+     * @param flow - The current FlowState
+     * @param toolName - The name of the tool to call
+     * @param args - The arguments to pass to the tool
+     *
+     * @example
+     * ```typescript
+     * FlowStateSdk.queueTool(flow, "search_user", { email: "user@example.com" });
+     * ```
+     */
+    static queueTool(flow: FlowState, toolName: string, args?: Record<string, unknown>): void;
+    /**
+     * Inject a message into the thread without triggering execution
+     *
+     * This allows you to add messages to the conversation history programmatically.
+     * The message is persisted to storage but does not cause the agent to execute.
+     *
+     * By default, messages are appended to the end of the conversation.
+     * You can optionally insert a message before another message by providing beforeMessageId.
+     *
+     * @param flow - The current FlowState
+     * @param options - Message options
+     *
+     * @example
+     * ```typescript
+     * // Append a system message
+     * await FlowStateSdk.injectMessage(flow, {
+     *   role: "system",
+     *   content: "Context has been updated"
+     * });
+     *
+     * // Insert a user message before a specific message
+     * await FlowStateSdk.injectMessage(flow, {
+     *   role: "user",
+     *   content: "Additional context",
+     *   beforeMessageId: "msg-123"
+     * });
+     *
+     * // Inject a message and force a specific side to play next
+     * await FlowStateSdk.injectMessage(flow, {
+     *   role: "system",
+     *   content: "New instructions for the AI",
+     *   forceTurn: "side_a" // Force side_a to respond to this message
+     * });
+     * ```
+     */
+    static injectMessage(flow: FlowState, options: InjectMessageOptions): Promise<Message>;
+    /**
+     * Get messages from the thread history
+     *
+     * Retrieves message history from the thread's SQLite storage.
+     * Messages are ordered by creation time (oldest first by default).
+     *
+     * @param flow - The current FlowState
+     * @param limit - Maximum number of messages to retrieve (default: 100)
+     * @param offset - Number of messages to skip (default: 0)
+     * @param order - Sort order: "asc" (oldest first) or "desc" (newest first) (default: "asc")
+     * @returns Array of messages
+     *
+     * @example
+     * ```typescript
+     * // Get last 10 messages
+     * const messages = await FlowStateSdk.getMessages(flow, 10);
+     *
+     * // Get 10 messages, skipping the first 20
+     * const messages = await FlowStateSdk.getMessages(flow, 10, 20);
+     *
+     * // Get newest 10 messages
+     * const messages = await FlowStateSdk.getMessages(flow, 10, 0, "desc");
+     * ```
+     */
+    static getMessages(flow: FlowState, limit?: number, offset?: number, order?: "asc" | "desc"): Promise<Message[]>;
+    /**
+     * Reload message history from storage
+     *
+     * Re-loads the complete message history from the thread's SQLite storage,
+     * applying any filter_messages hooks. This is useful when you need to refresh
+     * the message history after making changes (e.g., injecting silent messages).
+     *
+     * @param flow - The current FlowState
+     * @returns Array of messages (reloaded from storage)
+     *
+     * @example
+     * ```typescript
+     * // Reload history after injecting a silent message
+     * await FlowStateSdk.injectMessage(flow, { role: "system", content: "...", silent: true });
+     * flow.messageHistory = await FlowStateSdk.reloadHistory(flow);
+     * ```
+     */
+    static reloadHistory(state: FlowState): Promise<Message[]>;
+    /**
+     * Broadcast custom data to WebSocket clients
+     *
+     * Sends a custom message to all connected WebSocket clients.
+     * This allows backend code to push arbitrary data to the frontend
+     * outside of the standard telemetry events.
+     *
+     * The message is sent with the structure: { type: string, value: unknown }
+     *
+     * @param flow - The current FlowState
+     * @param options - Broadcast options
+     *
+     * @example
+     * ```typescript
+     * // Broadcast a progress update
+     * FlowStateSdk.broadcast(flow, {
+     *   type: "progress",
+     *   value: { step: 3, total: 10, message: "Processing data..." }
+     * });
+     *
+     * // Broadcast a custom notification
+     * FlowStateSdk.broadcast(flow, {
+     *   type: "notification",
+     *   value: { level: "info", message: "User authenticated successfully" }
+     * });
+     *
+     * // Broadcast metadata
+     * FlowStateSdk.broadcast(flow, {
+     *   type: "metadata",
+     *   value: { userId: "123", sessionId: "abc", timestamp: Date.now() }
+     * });
+     * ```
+     */
+    static broadcast(flow: FlowState, options: BroadcastOptions): void;
+    /**
+     * Force a specific side to play the next turn
+     *
+     * This queues the specified side to play next without interrupting the current turn.
+     * The forced turn only takes effect at the END of the current turn execution.
+     *
+     * If the tool queue is currently being processed (sequence.isHandling is true),
+     * the forced turn is deferred until all queued tools complete. This allows patterns like:
+     *
+     * ```typescript
+     * FlowStateSdk.queueTool(flow, 'myTool', {});
+     * FlowStateSdk.forceTurn(flow, 'side_a');
+     * // myTool executes first, THEN the turn switches to side_a
+     * ```
+     *
+     * @param flow - The current FlowState
+     * @param side - Which side should play next ('side_a' or 'side_b')
+     *
+     * @example
+     * ```typescript
+     * // Force current side to continue (override stop condition)
+     * // If side_a is playing and would stop, this forces it to play at least 1 more turn
+     * FlowStateSdk.forceTurn(flow, 'side_a');
+     *
+     * // Force switch to other side
+     * // If side_a is playing, this forces side_b to play next turn
+     * FlowStateSdk.forceTurn(flow, 'side_b');
+     *
+     * // Force human turn in ai_human agent (execution stops and waits for user input)
+     * if (flow.agentConfig.type === 'ai_human') {
+     *   FlowStateSdk.forceTurn(flow, 'side_b'); // Stops execution, awaits user input
+     * }
+     * ```
+     */
+    static forceTurn(flow: FlowState, side: 'side_a' | 'side_b'): void;
+}
+/**
+ * Convenience methods added to FlowState (optional - can be used via static methods above)
+ *
+ * These are helper methods that can be added to FlowState instances for convenience.
+ * They delegate to the static methods above.
+ */
+interface FlowStateWithSdk extends FlowState {
+    queueTool: (toolName: string, args?: Record<string, unknown>) => void;
+    injectMessage: (options: InjectMessageOptions) => Promise<Message>;
+    getMessages: (limit?: number, offset?: number, order?: "asc" | "desc") => Promise<Message[]>;
+    reloadHistory: () => Promise<Message[]>;
+    broadcast: (options: BroadcastOptions) => void;
+    forceTurn: (side: 'side_a' | 'side_b') => void;
+}
+/**
+ * Enhance a FlowState object with SDK methods
+ *
+ * This adds convenience methods to a FlowState instance that delegate to
+ * the static FlowStateSdk methods.
+ *
+ * @param flow - The FlowState to enhance
+ * @returns The enhanced FlowState with SDK methods
+ *
+ * @example
+ * ```typescript
+ * const enhancedFlow = enhanceFlowState(flow);
+ *
+ * // Now you can use methods directly on the flow object
+ * enhancedFlow.queueTool("search_user", { email: "user@example.com" });
+ * await enhancedFlow.injectMessage({ role: "system", content: "Context updated" });
+ * const messages = await enhancedFlow.getMessages(10);
+ * flow.messageHistory = await enhancedFlow.reloadHistory();
+ * enhancedFlow.broadcast({ type: "progress", value: { step: 1 } });
+ * enhancedFlow.forceTurn('side_b'); // Force side_b to play next turn
+ * ```
+ */
+declare function enhanceFlowState(flow: FlowState): FlowStateWithSdk;
+
+/**
+ * Types for GitHub REST API integration.
+ */
+interface GitHubConfig {
+    token: string;
+    owner: string;
+    repo: string;
+    branch: string;
+}
+interface GitHubFileChange {
+    path: string;
+    content: string;
+    mode?: '100644' | '100755';
+}
+interface GitHubCommitResult {
+    sha: string;
+    url: string;
+    message: string;
+}
+interface GitHubRef {
+    ref: string;
+    node_id: string;
+    url: string;
+    object: {
+        sha: string;
+        type: string;
+        url: string;
+    };
+}
+interface GitHubTree {
+    sha: string;
+    url: string;
+    truncated: boolean;
+    tree: Array<{
+        path: string;
+        mode: string;
+        type: string;
+        sha: string;
+        size?: number;
+        url: string;
+    }>;
+}
+interface GitHubBlob {
+    sha: string;
+    url: string;
+}
+interface GitHubCommit {
+    sha: string;
+    url: string;
+    html_url: string;
+    author: {
+        name: string;
+        email: string;
+        date: string;
+    };
+    committer: {
+        name: string;
+        email: string;
+        date: string;
+    };
+    message: string;
+    tree: {
+        sha: string;
+        url: string;
+    };
+    parents: Array<{
+        sha: string;
+        url: string;
+    }>;
+}
+
+/**
+ * GitHub REST API client for committing file changes.
+ *
+ * This client is used in production to commit configuration changes
+ * (prompts, models, agents) to the repository via GitHub's REST API.
+ *
+ * The flow for creating a commit:
+ * 1. Get the current branch ref to find HEAD commit SHA
+ * 2. Get the tree SHA from the HEAD commit
+ * 3. Create blobs for each file to be added/modified
+ * 4. Create a new tree with the file changes
+ * 5. Create a commit pointing to the new tree
+ * 6. Update the branch ref to point to the new commit
+ */
+
+declare class GitHubClient {
+    private config;
+    constructor(config: GitHubConfig);
+    /**
+     * Create a GitHubClient from environment variables.
+     * Returns null if required env vars are missing.
+     */
+    static fromEnv(env: {
+        GITHUB_TOKEN?: string;
+        GITHUB_REPO?: string;
+        GITHUB_BRANCH?: string;
+    }): GitHubClient | null;
+    /**
+     * Check if GitHub integration is properly configured.
+     */
+    isConfigured(): boolean;
+    /**
+     * Make an authenticated request to GitHub API.
+     */
+    private request;
+    /**
+     * Get the current branch reference.
+     */
+    getBranchRef(): Promise<GitHubRef>;
+    /**
+     * Get a commit by SHA.
+     */
+    getCommit(sha: string): Promise<GitHubCommit>;
+    /**
+     * Get a tree by SHA.
+     */
+    getTree(sha: string): Promise<GitHubTree>;
+    /**
+     * Create a blob (file content).
+     */
+    createBlob(content: string): Promise<GitHubBlob>;
+    /**
+     * Create a tree with file changes.
+     */
+    createTree(baseTreeSha: string, files: Array<{
+        path: string;
+        sha: string;
+        mode: string;
+    }>): Promise<GitHubTree>;
+    /**
+     * Create a commit.
+     */
+    createCommit(message: string, treeSha: string, parentSha: string): Promise<GitHubCommit>;
+    /**
+     * Update a branch reference to point to a new commit.
+     */
+    updateRef(sha: string): Promise<GitHubRef>;
+    /**
+     * Commit multiple file changes atomically.
+     *
+     * @param message - Commit message
+     * @param files - Array of files to add/modify
+     * @returns The commit result with SHA
+     */
+    commitFiles(message: string, files: GitHubFileChange[]): Promise<GitHubCommitResult>;
+    /**
+     * Delete files from the repository.
+     *
+     * @param message - Commit message
+     * @param paths - Array of file paths to delete
+     * @returns The commit result with SHA
+     */
+    deleteFiles(message: string, paths: string[]): Promise<GitHubCommitResult>;
+    /**
+     * Get the current HEAD commit SHA.
+     */
+    getHeadSha(): Promise<string>;
+}
+/**
+ * Custom error for GitHub API errors.
+ */
+declare class GitHubApiError extends Error {
+    status: number;
+    details: unknown;
+    constructor(message: string, status: number, details?: unknown);
+}
+
+export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AgentType, type AuthContext, type AuthUser, type BroadcastOptions, type Controller, type ControllerContext, DurableAgentBuilder, DurableThread, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type HookSignatures, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type ModelDefinition, type ModelProvider, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type Provider, type ReasoningConfig, type RequestContext, type SideConfig, type StructuredPrompt, type StructuredToolReturn, type TelemetryEvent, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolCall, type ToolConfig, type ToolResult, type UpdateThreadParams, type User, authenticate, defineAgent, defineController, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, emitThreadEvent, enhanceFlowState, forceTurn, generateAgentFile, generateModelFile, generatePromptFile, getMessages, injectMessage, queueTool, reloadHistory, requireAdmin, requireAuth, updateThread };