@standardagents/builder 0.10.1-next.bbd142a → 0.11.0-next.99fb790

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { AgentPluginOptions, agentbuilder } from './plugin.js';
 import { DurableObjectStorage } from '@cloudflare/workers-types';
-import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion } from 'zod';
+import { ZodObject, ZodRawShape } from 'zod';
+import { ToolResult as ToolResult$1, HookSignatures, ControllerContext, Controller, ModelDefinition as ModelDefinition$1, ToolArgs, PromptTextPart, SubpromptConfig as SubpromptConfig$2, ReasoningConfig, SideConfig as SideConfig$1 } from '@standardagents/spec';
+export { AgentType, HookSignatures, ImageContent, ModelCapabilities, ModelProvider, PromptInput, PromptTextPart, ReasoningConfig, StructuredPrompt, TextContent, Tool, ToolArgs, ToolArgsNode, ToolArgsRawShape, ToolContent, defineAgent, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool } from '@standardagents/spec';
 import { DurableObject } from 'cloudflare:workers';
 import 'vite';
 
@@ -144,122 +146,6 @@ declare class StreamManager {
     forceClose(): void;
 }
 
-/**
- * Content item types that can be returned by tools
- */
-interface TextContent {
-    type: "text";
-    text: string;
-}
-interface ImageContent {
-    type: "image";
-    data: string;
-    mimeType: string;
-}
-type ToolContent = TextContent | ImageContent;
-/** 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<ToolResult> : (flow: FlowState) => Promise<ToolResult>;
-/**
- * @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
  */
@@ -274,15 +160,15 @@ interface Agent {
     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_a_max_steps: number | null;
+    side_a_end_session_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;
+    side_b_max_steps: number | null;
+    side_b_end_session_tool: string | null;
 }
 /**
  * Message in OpenAI chat completion format
@@ -335,6 +221,12 @@ interface ThreadMetadata {
 type HookRegistry = {
     [K in keyof HookSignatures]?: () => Promise<HookSignatures[K]>;
 };
+/**
+ * Native tool module type - represents a loaded tool definition.
+ * Tools can have args (with validation schema) or no args.
+ * Uses local Zod types for compatibility with z.toJSONSchema().
+ */
+type NativeToolModule = [description: string, argsSchema: ZodObject<ZodRawShape>, toolFn: (state: any, args: Record<string, unknown>) => Promise<ToolResult$1>] | [description: string, argsSchema: null, toolFn: (state: any) => Promise<ToolResult$1>];
 /**
  * Thread instance (forward reference to avoid circular dependency)
  */
@@ -349,13 +241,38 @@ interface ThreadInstance {
     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>>>;
+    tools(): Record<string, () => Promise<NativeToolModule>>;
     hooks(): HookRegistry;
     loadModel(name: string): Promise<any>;
     loadPrompt(name: string): Promise<any>;
     loadAgent(name: string): Promise<any>;
     getPromptNames(): string[];
     getAgentNames(): string[];
+    writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: Record<string, unknown>): Promise<any>;
+    readFile(path: string): Promise<ArrayBuffer | null>;
+    statFile(path: string): Promise<any>;
+    readdirFile(path: string): Promise<any[]>;
+    unlinkFile(path: string): Promise<void>;
+    mkdirFile(path: string): Promise<any>;
+    rmdirFile(path: string): Promise<void>;
+    getFileStats(): Promise<any>;
+    grepFiles(pattern: string): Promise<any[]>;
+    findFiles(pattern: string): Promise<any>;
+    getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
+    readFileChunk(path: string, chunkIndex: number): Promise<{
+        success: boolean;
+        data?: string;
+        error?: string;
+    }>;
+    scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
+    getScheduledEffects(name?: string): Promise<Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        scheduledAt: number;
+        createdAt: number;
+    }>>;
+    removeScheduledEffect(id: string): Promise<boolean>;
     insertOrphanedToolCall(params: {
         content?: string;
         toolCallId: string;
@@ -389,9 +306,9 @@ type FlowCallWithRetries = FlowCall & {
     reasons: string[];
 };
 /**
- * Tool configuration for a prompt - defines options for when a tool is used
+ * Sub-prompt configuration - defines options for when a sub-prompt is called as a tool
  */
-interface ToolConfig$1 {
+interface SubpromptConfig$1 {
     name: string;
     initUserMessageProperty?: string;
     includeTextResponse?: boolean;
@@ -412,8 +329,6 @@ interface PromptData {
     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 */
@@ -424,10 +339,8 @@ interface PromptData {
     reasoning_max_tokens: number | null;
     reasoning_exclude: boolean;
     include_reasoning: boolean;
-    maxImagePixels: number | null;
     recentImageThreshold: number | null;
-    _tools?: (string | ToolConfig$1)[];
-    _handoffAgents?: string[];
+    _tools?: (string | SubpromptConfig$1)[];
     _requiredSchema?: any;
 }
 /**
@@ -447,9 +360,9 @@ interface FlowState {
         sideB: PromptData | null;
     };
     prompt: PromptData;
-    turnCount: number;
-    sideATurnCount: number;
-    sideBTurnCount: number;
+    stepCount: number;
+    sideAStepCount: number;
+    sideBStepCount: number;
     stopped: boolean;
     stoppedBy?: "a" | "b";
     forcedNextSide?: "side_a" | "side_b";
@@ -556,6 +469,16 @@ interface ToolDefinition {
         parameters?: Record<string, any>;
     };
 }
+/**
+ * Image returned by an LLM response (e.g., from image generation models)
+ * Format follows OpenAI/OpenRouter chat completions API
+ */
+interface LLMResponseImage {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
 /**
  * LLM response
  */
@@ -566,6 +489,7 @@ interface LLMResponse {
     reasoning_content?: string | null;
     reasoning_details?: any[];
     tool_calls?: ToolCall[];
+    images?: LLMResponseImage[];
     finish_reason: string;
     usage: {
         prompt_tokens: number;
@@ -581,6 +505,17 @@ interface LLMResponse {
         provider?: string;
     };
 }
+/**
+ * Attachment returned by a tool (e.g., generated images)
+ * Stored in thread filesystem and linked to the tool message
+ */
+interface ToolAttachment {
+    name: string;
+    mimeType: string;
+    data: string;
+    width?: number;
+    height?: number;
+}
 /**
  * Tool result
  */
@@ -597,6 +532,16 @@ interface ToolResult {
     result?: string;
     error?: string;
     stack?: string;
+    /**
+     * File attachments returned by the tool.
+     *
+     * Can contain either:
+     * - ToolAttachment: New files with base64 data to be stored
+     * - AttachmentRef: References to existing files in the thread filesystem
+     *
+     * New attachments are stored under /attachments/ directory.
+     */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
 }
 /**
  * Flow execution result
@@ -605,20 +550,20 @@ interface FlowResult {
     messages: Message[];
     stopped: boolean;
     stoppedBy?: "a" | "b";
-    turnCount: number;
+    stepCount: number;
     stream: ReadableStream<Uint8Array>;
 }
 /**
  * Telemetry event types
  */
 type TelemetryEvent = {
-    type: "turn_started";
-    turn: number;
+    type: "step_started";
+    step: number;
     side: "a" | "b";
     timestamp: number;
 } | {
-    type: "turn_completed";
-    turn: number;
+    type: "step_completed";
+    step: number;
     stopped: boolean;
     timestamp: number;
 } | {
@@ -739,6 +684,10 @@ interface FileRecord {
     metadata?: Record<string, unknown> | null;
     isDirectory: boolean;
     createdAt: number;
+    width?: number | null;
+    height?: number | null;
+    isChunked?: boolean;
+    chunkCount?: number;
 }
 /**
  * Image-specific metadata stored in FileRecord.metadata
@@ -777,43 +726,178 @@ interface FileStats {
     fileCount: number;
 }
 
+/**
+ * Router and endpoint definition module for AgentBuilder.
+ *
+ * This module re-exports endpoint types from @standardagents/spec and provides
+ * the runtime router implementation for handling HTTP requests.
+ *
+ * @module
+ */
+
+/**
+ * Durable Object namespace interface.
+ * This is Cloudflare-specific and used by the builder runtime.
+ */
+interface DurableObjectNamespace$1<T = unknown> {
+    idFromName(name: string): DurableObjectId;
+    idFromString(id: string): DurableObjectId;
+    newUniqueId(): DurableObjectId;
+    get(id: DurableObjectId): DurableObjectStub$1<T>;
+}
+/**
+ * Durable Object ID interface.
+ */
+interface DurableObjectId {
+    toString(): string;
+    equals(other: DurableObjectId): boolean;
+}
+/**
+ * Durable Object stub interface.
+ * The generic type T represents the RPC methods available on the stub.
+ */
+type DurableObjectStub$1<T = unknown> = {
+    id: DurableObjectId;
+    name?: string;
+    fetch(request: Request | string, requestInitr?: RequestInit): Promise<Response>;
+} & T;
+/**
+ * Log entry from DurableThread.getLogs()
+ */
+interface LogEntry {
+    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: number;
+    created_at: number;
+    request_body: string | null;
+}
+/**
+ * Agent definition returned from loadAgent()
+ */
+interface AgentDefinition$1 {
+    name: string;
+    title?: string;
+    type?: string;
+    description?: string;
+    icon?: string;
+    defaultPrompt?: string;
+    defaultModel?: string;
+    tools?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Response from getThreadMeta()
+ */
+interface ThreadMetaResponse {
+    thread: ThreadRegistryEntry$1;
+    agent: AgentDefinition$1 | null;
+    stats: {
+        messageCount: number;
+        logCount: number;
+        lastActivity: number | null;
+    };
+}
+/**
+ * RPC methods exposed by DurableThread for external callers.
+ */
+interface DurableThreadRpc {
+    stop(): Promise<Response>;
+    getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC", includeSilent?: boolean, maxDepth?: number): Promise<{
+        messages: unknown[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    deleteMessage(messageId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    updateMessageContent(messageId: string, content: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    getLogs(limit?: number, offset?: number, order?: "ASC" | "DESC"): Promise<{
+        logs: LogEntry[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    getLogDetails(logId: string): Promise<unknown>;
+    getThreadMeta(threadId: string): Promise<ThreadMetaResponse | null>;
+    deleteThread(): Promise<void>;
+}
+/**
+ * Thread registry entry from DurableAgentBuilder.
+ */
+interface ThreadRegistryEntry$1 {
+    id: string;
+    agent_name: string;
+    user_id: string | null;
+    tags: string[] | null;
+    created_at: number;
+}
+/**
+ * RPC methods exposed by DurableAgentBuilder for external callers.
+ */
+interface DurableAgentBuilderRpc {
+    createThread(params: {
+        agent_name: string;
+        user_id?: string;
+        tags?: string[];
+    }): Promise<ThreadRegistryEntry$1>;
+    getThread(threadId: string): Promise<ThreadRegistryEntry$1 | null>;
+    listThreads(params?: {
+        agent_name?: string;
+        user_id?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        threads: ThreadRegistryEntry$1[];
+        total: number;
+    }>;
+    deleteThread(threadId: string): Promise<void>;
+    getUserByUsername(username: string): Promise<unknown>;
+    createSession(session: {
+        user_id: string;
+        token_hash: string;
+        expires_at: number;
+    }): Promise<void>;
+    loadAgent(name: string): Promise<AgentDefinition$1>;
+}
 /**
  * Minimum required environment bindings for thread endpoints.
  * User's Env interface should extend this.
  *
- * Uses Rpc.DurableObjectBranded to allow users to specify their own
- * Durable Object types that extend DurableThread/DurableAgentBuilder.
+ * This is Cloudflare-specific and used by the builder runtime.
  */
 interface ThreadEnv {
-    AGENT_BUILDER_THREAD: DurableObjectNamespace<Rpc.DurableObjectBranded>;
-    AGENT_BUILDER: DurableObjectNamespace<Rpc.DurableObjectBranded>;
+    AGENT_BUILDER_THREAD: DurableObjectNamespace$1<DurableThreadRpc>;
+    AGENT_BUILDER: DurableObjectNamespace$1<DurableAgentBuilderRpc>;
     [key: string]: unknown;
 }
 /**
- * Virtual module registry types (injected at runtime by plugin)
+ * Builder-specific controller context with typed env.
+ *
+ * This extends the spec's ControllerContext with proper typing for
+ * Cloudflare environment bindings.
  */
-type VirtualModuleLoader<T> = () => Promise<T>;
-type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
+interface BuilderControllerContext<Env extends ThreadEnv = ThreadEnv> extends Omit<ControllerContext, 'env'> {
+    env: Env;
+}
 /**
- * Controller context passed to route handlers.
- * Includes optional virtual module registries that are injected at runtime.
+ * Builder-specific controller type with typed env.
+ */
+type BuilderController<Env extends ThreadEnv = ThreadEnv> = (context: BuilderControllerContext<Env>) => ReturnType<Controller>;
+/**
+ * Thread endpoint context with access to thread instance and metadata.
  */
-interface ControllerContext<Env = any> {
-    req: Request;
-    params: Record<string, string>;
-    env: Env;
-    url: URL;
-    agents?: VirtualModuleRegistry<unknown>;
-    agentNames?: string[];
-    prompts?: VirtualModuleRegistry<unknown>;
-    promptNames?: string[];
-    models?: VirtualModuleRegistry<unknown>;
-    modelNames?: string[];
-    tools?: VirtualModuleRegistry<unknown>;
-    hooks?: VirtualModuleRegistry<unknown>;
-    config?: Record<string, unknown>;
-}
-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: {
@@ -821,22 +905,24 @@ interface ThreadEndpointContext {
         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.
+ * Define a controller with typed Cloudflare environment bindings.
  *
- * @param handler - Function that receives the request and thread context
- * @returns A Controller that can be used with the router
+ * This is the builder's version of defineController that provides
+ * proper typing for AGENT_BUILDER_THREAD and other CF bindings.
  *
  * @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 });
+ * ```typescript
+ * import { defineController } from '../router/index.js';
+ *
+ * export default defineController(async ({ req, env }) => {
+ *   const stub = env.AGENT_BUILDER.get(env.AGENT_BUILDER.idFromName('singleton'));
+ *   // ...
  * });
+ * ```
  */
-declare function defineThreadEndpoint<Env extends ThreadEnv = ThreadEnv>(handler: (req: Request, context: ThreadEndpointContext["thread"]) => Response | Promise<Response>): Controller<Env>;
+declare function defineController<Env extends ThreadEnv = ThreadEnv>(controller: BuilderController<Env>): BuilderController<Env>;
 
 /**
  * Authentication middleware for protecting API routes
@@ -932,6 +1018,17 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * @returns Record of agent name to agent loader function
      */
     agents(): Record<string, () => Promise<any>>;
+    /**
+     * Returns the effects registry for lazy-loading effect definitions.
+     * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
+     *
+     * Effects are scheduled operations that run outside the tool execution context,
+     * ideal for delayed notifications, webhooks, and cleanup tasks.
+     *
+     * @throws Error if not implemented in a subclass
+     * @returns Record of effect name to effect loader function
+     */
+    effects(): Record<string, () => Promise<any>>;
     /**
      * Load a model definition by name.
      */
@@ -956,6 +1053,49 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * List available agent names.
      */
     getAgentNames(): string[];
+    /**
+     * Load an effect definition by name.
+     */
+    loadEffect(name: string): Promise<any>;
+    /**
+     * List available effect names.
+     */
+    getEffectNames(): string[];
+    /**
+     * Get thread metadata from DurableAgentBuilder.
+     * Used for creating ThreadState outside of flow execution.
+     */
+    getThreadMetadata(threadId: string): Promise<ThreadMetadata>;
+    /**
+     * Schedule an effect for future execution.
+     *
+     * @param threadId - Thread ID for the effect execution context
+     * @param effectName - Name of the effect to schedule
+     * @param effectArgs - Arguments to pass to the effect handler
+     * @param delayMs - Delay in milliseconds before execution (default: 0)
+     * @returns UUID of the scheduled effect
+     */
+    scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
+    /**
+     * Get scheduled effects for this thread.
+     *
+     * @param name - Optional effect name to filter by
+     * @returns Array of scheduled effect records
+     */
+    getScheduledEffects(name?: string): Promise<Array<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        scheduledAt: number;
+        createdAt: number;
+    }>>;
+    /**
+     * Remove a scheduled effect.
+     *
+     * @param id - The effect ID returned by scheduleEffect
+     * @returns true if the effect was found and removed, false otherwise
+     */
+    removeScheduledEffect(id: string): Promise<boolean>;
     /**
      * Ensures the database schema is up to date.
      * This method is called on the first request to the Durable Object.
@@ -1044,6 +1184,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
     }>;
     /**
      * Delete a message (RPC method)
+     * Also cleans up any attachment files stored on the thread filesystem
      */
     deleteMessage(messageId: string): Promise<{
         success: boolean;
@@ -1186,6 +1327,8 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
             id: any;
             title: any;
             type: any;
+            description: any;
+            icon: any;
             side_a_label: any;
             side_b_label: any;
         } | null;
@@ -1251,7 +1394,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
     private broadcastMessageChunk;
     /**
      * Broadcast a telemetry event to all connected message WebSocket clients
-     * Used for execution status updates (turn_started, tool_started, etc.)
+     * Used for execution status updates (step_started, tool_started, etc.)
      */
     private broadcastTelemetry;
     /**
@@ -1287,6 +1430,11 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * This is the actual execution logic, separate from the public execute() RPC method
      */
     private executeFlow;
+    /**
+     * Internal method: Execute an effect (called by alarm queue)
+     * Effects run outside the tool execution context.
+     */
+    private executeEffect;
     /**
      * Internal method: Process a message (called by alarm queue)
      * This is the actual message processing logic, separate from the public sendMessage() RPC method
@@ -1538,6 +1686,59 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
         error: any;
         files?: undefined;
     }>;
+    /**
+     * Start a chunked file upload.
+     * Creates file record with is_chunked=1 and chunk_count=null.
+     * Caller should then use writeFileChunk() to write chunks.
+     */
+    startChunkedUpload(path: string, totalSize: number, mimeType: string, options?: {
+        metadata?: Record<string, unknown>;
+        width?: number;
+        height?: number;
+    }): Promise<{
+        success: boolean;
+        chunkSize?: number;
+        expectedChunks?: number;
+        error?: string;
+    }>;
+    /**
+     * Write a single chunk of a chunked file upload.
+     * @param path - File path
+     * @param chunkIndex - 0-based chunk index
+     * @param data - Base64 encoded chunk data
+     */
+    writeFileChunk(path: string, chunkIndex: number, data: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Complete a chunked file upload.
+     * Validates all chunks are present and sets chunk_count.
+     */
+    completeChunkedUpload(path: string, expectedChunks: number, options?: {
+        thumbnail?: string;
+    }): Promise<{
+        success: boolean;
+        file?: FileRecord;
+        error?: string;
+    }>;
+    /**
+     * Read a single chunk of a file.
+     * Use for streaming large files to client.
+     */
+    readFileChunk(path: string, chunkIndex: number): Promise<{
+        success: boolean;
+        data?: string;
+        error?: string;
+    }>;
+    /**
+     * Get file info including chunking metadata.
+     */
+    getFileInfo(path: string): Promise<{
+        success: boolean;
+        file?: FileRecord;
+        error?: string;
+    }>;
 }
 
 /**
@@ -1868,181 +2069,44 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
 /**
  * Model definition module for AgentBuilder.
  *
- * Models define LLM configurations including provider, model ID, pricing,
- * and fallback chains. Models are referenced by name from prompts.
+ * This module re-exports model types from @standardagents/spec and provides
+ * a builder-specific version of ModelDefinition that supports the generated
+ * AgentBuilder.Models type for fallback references.
  *
  * @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`
- * - `test` → No API key required (for testing with scripted responses)
- */
-type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
-/**
- * Model definition configuration.
+ * Model definition configuration with AgentBuilder-specific fallback typing.
  *
- * @template N - The model name as a string literal type for type inference
+ * Extends the base ModelDefinition from @standardagents/spec to support
+ * the generated AgentBuilder.Models type for type-safe fallback references.
  *
- * @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,
- * });
- * ```
+ * @template N - The model name as a string literal type for type inference
  */
-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[];
+interface ModelDefinition<N extends string = string> extends Omit<ModelDefinition$1<N>, 'fallbacks'> {
     /**
      * Fallback models to try if this model fails.
-     * Referenced by model name (must be defined in agentbuilder/models/).
+     * Referenced by model name (must be defined in agents/models/).
      * Tried in order after primary model exhausts retries.
      *
      * @example ['gpt-4', 'gpt-3.5-turbo']
      */
     fallbacks?: 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;
-    /**
-     * Model capabilities - features this model supports.
-     */
-    capabilities?: {
-        /**
-         * Whether the model supports vision (image understanding).
-         * When true, image attachments will be sent to the model as part of the request.
-         * Models like GPT-4o, Claude 3, and Gemini support vision.
-         */
-        vision?: boolean;
-        /**
-         * Whether the model supports function calling (tool use).
-         * Most modern models support this, defaults to true if not specified.
-         */
-        functionCalling?: boolean;
-        /**
-         * Whether the model supports structured outputs (JSON mode).
-         */
-        structuredOutputs?: boolean;
-    };
 }
-/**
- * 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.
+ * This module re-exports prompt types from @standardagents/spec and provides
+ * builder-specific versions that use the generated AgentBuilder namespace types.
  *
  * @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' }
- * ```
+ * A prompt inclusion part with type-safe autocomplete.
+ * Uses AgentBuilder.Prompts for type-safe prompt name references.
  */
 interface PromptIncludePart {
     type: 'include';
@@ -2051,448 +2115,107 @@ interface PromptIncludePart {
 }
 /**
  * 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.' },
- * ]
- * ```
+ * Prompt content can be a string or structured array with type-safe includes.
  */
-type StructuredPrompt = PromptPart[];
+type PromptContent = string | 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' },
- * ]
- * ```
+ * Sub-prompt configuration with type-safe name references.
  */
-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/.
-     */
+interface SubpromptConfig<T extends string = AgentBuilder.Callables> extends Omit<SubpromptConfig$2<T>, 'name'> {
+    /** Name of the sub-prompt (type-safe with autocomplete) */
     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.
+ * @deprecated Use SubpromptConfig instead
  */
-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;
-}
+type ToolConfig<T extends string = AgentBuilder.Callables> = SubpromptConfig<T>;
+
 /**
- * Prompt definition configuration.
+ * Prompt definition configuration with AgentBuilder-specific typing.
+ *
+ * Provides type-safe references to models, tools, and agents via the
+ * generated AgentBuilder namespace.
  *
  * @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').
-     */
+interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolArgs> {
+    /** Unique name for this prompt. */
     name: N;
-    /**
-     * Description shown when this prompt is exposed as a tool.
-     * Should clearly describe what this prompt does for LLM tool selection.
-     */
+    /** Description shown when this prompt is exposed as a tool. */
     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.' },
-     * ]
-     * ```
-     */
+    /** The system prompt content with type-safe includes. */
     prompt: PromptContent;
-    /**
-     * Model to use for this prompt.
-     * Must reference a model defined in agentbuilder/models/.
-     * Provides autocomplete when types are generated.
-     */
+    /** Model to use (type-safe with autocomplete). */
     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
-     */
+    /** Include full chat history in the LLM context. @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
-     */
+    /** Include results from past tool calls. @default false */
     includePastTools?: boolean;
-    /**
-     * Allow parallel execution of multiple tool calls.
-     * When true, if the LLM requests multiple tools, they execute concurrently.
-     * @default false
-     */
+    /** Allow parallel execution of multiple tool calls. @default false */
     parallelToolCalls?: boolean;
-    /**
-     * Tool calling strategy for the LLM.
-     *
-     * - `auto`: Model decides when to call tools (default)
-     * - `none`: Disable tool calling entirely
-     * - `required`: Force the model to call at least one tool
-     *
-     * @default 'auto'
-     */
+    /** Tool calling strategy. @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'),
-     * })
-     * ```
-     */
+    /** Zod schema for validating inputs when called as a tool. */
     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.
-     */
+    /** Tools available to this prompt (type-safe with autocomplete). To enable handoffs, include ai_human agent names. */
+    tools?: (AgentBuilder.Callables | SubpromptConfig)[];
+    /** Reasoning configuration for extended thinking models. */
     reasoning?: ReasoningConfig;
-    /**
-     * Maximum pixels for image attachments before client-side resize.
-     * Images exceeding this limit are scaled down while preserving aspect ratio.
-     * Images smaller than this limit are not resized up.
-     *
-     * Common values:
-     * - 262144 (256K): 512x512 equivalent - thumbnails, low cost
-     * - 1048576 (1M): 1024x1024 equivalent - good quality (default)
-     * - 2073600 (2M): 1440x1440 equivalent - high quality
-     * - 4194304 (4M): 2048x2048 equivalent - maximum detail
-     *
-     * @default 1048576 (1M pixels, ~1024x1024)
-     *
-     * @example
-     * ```typescript
-     * // High quality images for detailed analysis
-     * maxImagePixels: 2073600
-     *
-     * // Lower quality for cost-sensitive applications
-     * maxImagePixels: 262144
-     * ```
-     */
-    maxImagePixels?: number;
-    /**
-     * Number of recent messages to keep actual images for in context.
-     * Messages older than this threshold will have their images replaced
-     * with text descriptions to save context window space.
-     *
-     * This helps manage context window usage in long conversations with
-     * many image attachments by summarizing older images.
-     *
-     * @default 10
-     *
-     * @example
-     * ```typescript
-     * // Keep more images in context for image-heavy workflows
-     * recentImageThreshold: 20
-     *
-     * // Aggressively summarize to save context
-     * recentImageThreshold: 5
-     * ```
-     */
+    /** Number of recent messages to keep actual images for. @default 10 */
     recentImageThreshold?: number;
 }
-/**
- * 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.
+ * This module re-exports agent types from @standardagents/spec and provides
+ * builder-specific versions that use the generated AgentBuilder namespace types.
  *
  * @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.
+ * Side configuration with type-safe autocomplete.
+ * Uses AgentBuilder.Prompts and AgentBuilder.Callables for type-safe references.
  */
-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;
+interface SideConfig extends Omit<SideConfig$1, 'prompt' | 'stopTool' | 'endSessionTool'> {
     /**
-     * The prompt to use for this side.
-     * Must reference a prompt defined in agentbuilder/prompts/.
+     * The prompt to use for this side (type-safe with autocomplete).
+     * Must reference a prompt defined in agents/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.
+     * Stop this side's turn when a specific tool is called (type-safe with autocomplete).
      * 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,
+     * Tool that ends the entire session when called (type-safe with autocomplete).
+     * Different from stopTool - this ends the session for both sides,
      * not just this side's turn.
      */
-    endConversationTool?: AgentBuilder.Callables;
+    endSessionTool?: 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.
+     * Builder-specific feature for custom stop logic.
      * @default false
      */
     manualStopCondition?: boolean;
 }
 /**
- * Agent definition configuration.
+ * Agent definition configuration with AgentBuilder-specific typing.
+ *
+ * Provides type-safe references to prompts and tools via the
+ * generated AgentBuilder namespace.
  *
  * @template N - The agent name as a string literal type
  *
@@ -2509,126 +2232,45 @@ interface SideConfig {
  *     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').
-     */
+    /** Unique name for this agent. */
     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;
+    type?: 'ai_human' | 'dual_ai';
     /**
      * 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.
-     */
+    /** Configuration for Side A (type-safe with autocomplete). */
     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.
-     */
+    /** Configuration for Side B (type-safe with autocomplete). */
     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.
-     */
+    /** Description shown when agent is used as a tool. */
     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[];
+    /** Brief description of what this agent does. */
+    description?: string;
+    /** Icon URL or absolute path for the agent. */
+    icon?: string;
 }
-/**
- * Defines an agent configuration.
- *
- * Agents orchestrate conversations between AI models, or between AI and
- * human users. They use prompts to configure each side of the conversation
- * and define stop conditions to control conversation flow.
- *
- * @template N - The agent name as a string literal type
- * @param options - Agent configuration options
- * @returns The agent definition for registration
- *
- * @example
- * ```typescript
- * // 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.
@@ -2706,9 +2348,6 @@ interface PromptFileData {
     parallelToolCalls?: boolean;
     toolChoice?: 'auto' | 'none' | 'required';
     tools?: (string | ToolConfigInput)[];
-    handoffAgents?: string[];
-    beforeTool?: string;
-    afterTool?: string;
     reasoning?: {
         effort?: 'low' | 'medium' | 'high';
         maxTokens?: number;
@@ -3793,4 +3432,4 @@ declare class GitHubApiError extends Error {
     constructor(message: string, status: number, details?: unknown);
 }
 
-export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AgentType, type AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, type Controller, type ControllerContext, DurableAgentBuilder, DurableThread, type Env, type FileRecord, type FileStats, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type GrepResult, type HookSignatures, type ImageContent, type ImageContentPart, type ImageContextConfig, type ImageMetadata, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type MessageContent, type ModelDefinition, type ModelProvider, type MultimodalContent, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type Provider, type ReasoningConfig, type RequestContext, type SideConfig, type StorageBackend, type StructuredPrompt, type StructuredToolReturn, type TelemetryEvent, type TextContent, type TextContentPart, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolCall, type ToolConfig, type ToolContent, type ToolResult, type UpdateThreadParams, type User, authenticate, buildImageDescription, cat, defineAgent, defineController, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateAgentFile, generateImageDescription, generateModelFile, generatePromptFile, getFileStats, getMessages, getMessagesToSummarize, getThumbnail, getUnsummarizedImageAttachments, grep, hasImageAttachments, head, injectMessage, linkFile, mkdir, optimizeImageContext, queueTool, readFile, readdir, reloadHistory, replaceImagesWithDescriptions, requireAdmin, requireAuth, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };
+export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, type BuilderController as Controller, type BuilderControllerContext as ControllerContext, DurableAgentBuilder, DurableThread, type Env, type FileRecord, type FileStats, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type GrepResult, type ImageContentPart, type ImageContextConfig, type ImageMetadata, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type MessageContent, type ModelDefinition, type MultimodalContent, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptPart, type Provider, type RequestContext, type SideConfig, type StorageBackend, type SubpromptConfig, type TelemetryEvent, type TextContentPart, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type ToolCall, type ToolConfig, type ToolResult, type UpdateThreadParams, type User, authenticate, buildImageDescription, cat, defineController, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateAgentFile, generateImageDescription, generateModelFile, generatePromptFile, getFileStats, getMessages, getMessagesToSummarize, getThumbnail, getUnsummarizedImageAttachments, grep, hasImageAttachments, head, injectMessage, linkFile, mkdir, optimizeImageContext, queueTool, readFile, readdir, reloadHistory, replaceImagesWithDescriptions, requireAdmin, requireAuth, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };