@standardagents/builder 0.11.0-next.41deba4 → 0.11.0-next.56def20

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { AgentPluginOptions, agentbuilder } from './plugin.js';
 import { DurableObjectStorage } from '@cloudflare/workers-types';
 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 { ToolResult as ToolResult$1, HookSignatures, AgentDefinition as AgentDefinition$1, ControllerContext, Controller, ModelDefinition as ModelDefinition$1, ToolArgs, PromptTextPart, SubpromptConfig as SubpromptConfig$2, ReasoningConfig, SideConfig as SideConfig$1, LLMProviderInterface, ContentPart, TextPart, ImagePart, FilePart } from '@standardagents/spec';
+export { AgentType, HookSignatures, ImageContent, ModelCapabilities, ModelProvider, PromptInput, PromptTextPart, ProviderAssistantMessage, ProviderError, ProviderErrorCode, ProviderFactory, ProviderFactoryConfig, ProviderFinishReason, ProviderGeneratedImage, ProviderMessage, ProviderMessageContent, ModelCapabilities as ProviderModelCapabilities, ProviderReasoningDetail, ProviderRequest, ProviderResponse, ProviderStreamChunk, ProviderSystemMessage, ProviderTool, ProviderToolCallPart, ProviderToolMessage, ProviderToolResultContent, ProviderUsage, ProviderUserMessage, ReasoningConfig, StructuredPrompt, TextContent, Tool, ToolArgs, ToolArgsNode, ToolArgsRawShape, ToolContent, defineAgent, defineHook, defineModel, definePrompt, defineTool, mapReasoningLevel } from '@standardagents/spec';
 import { DurableObject } from 'cloudflare:workers';
 import 'vite';
 
@@ -213,6 +213,8 @@ interface ThreadMetadata {
     id: string;
     agent_id: string;
     user_id: string | null;
+    tenvs: Record<string, unknown> | null;
+    properties: Record<string, unknown> | null;
     created_at: number;
 }
 /**
@@ -226,7 +228,26 @@ type HookRegistry = {
  * 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>];
+interface NativeToolModule {
+    /** Description of what the tool does (shown to the LLM). */
+    description: string;
+    /** Zod schema for validating tool arguments, or null for no args. */
+    args: ZodObject<ZodRawShape> | null;
+    /** The tool implementation function. */
+    execute: ((state: any, args: Record<string, unknown>) => Promise<ToolResult$1>) | ((state: any) => Promise<ToolResult$1>);
+    /** Zod schema for thread environment variables, or null if none. */
+    tenvs?: ZodObject<ZodRawShape> | null;
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider').
+     */
+    executionProvider?: string;
+}
 /**
  * Thread instance (forward reference to avoid circular dependency)
  */
@@ -240,6 +261,10 @@ interface ThreadInstance {
     }>;
     getLogs(limit?: number, offset?: number, order?: "asc" | "desc"): Promise<LogData[]>;
     getThreadMeta(threadId: string): Promise<ThreadMetadata | null>;
+    deleteMessage(messageId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     shouldStop(): Promise<boolean>;
     tools(): Record<string, () => Promise<NativeToolModule>>;
     hooks(): HookRegistry;
@@ -249,7 +274,11 @@ interface ThreadInstance {
     getPromptNames(): string[];
     getAgentNames(): string[];
     writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: Record<string, unknown>): Promise<any>;
-    readFile(path: string): Promise<ArrayBuffer | null>;
+    readFile(path: string): Promise<{
+        success: boolean;
+        data?: string;
+        error?: string;
+    }>;
     statFile(path: string): Promise<any>;
     readdirFile(path: string): Promise<any[]>;
     unlinkFile(path: string): Promise<void>;
@@ -264,6 +293,7 @@ interface ThreadInstance {
         data?: string;
         error?: string;
     }>;
+    runAgent(threadId: string, agentName: string): Promise<void>;
     scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
     getScheduledEffects(name?: string): Promise<Array<{
         id: string;
@@ -311,6 +341,7 @@ type FlowCallWithRetries = FlowCall & {
 interface SubpromptConfig$1 {
     name: string;
     initUserMessageProperty?: string;
+    initAttachmentsProperty?: string;
     includeTextResponse?: boolean;
     includeToolCalls?: boolean;
     includeErrors?: boolean;
@@ -401,6 +432,7 @@ interface FlowState {
     depth: number;
     pendingMessageId?: string;
     allowedTools?: ToolDefinition[];
+    pendingMetadataPromises?: Promise<void>[];
 }
 /**
  * Text content part for multimodal messages
@@ -437,6 +469,10 @@ interface RequestContext {
         tool_calls?: ToolCall[];
         tool_call_id?: string;
         name?: string;
+        reasoning_content?: string;
+        reasoning_details?: any[];
+        attachments?: any[];
+        toolName?: string;
     }>;
     model: string;
     tools?: ToolDefinition[];
@@ -468,6 +504,17 @@ interface ToolDefinition {
         description: string;
         parameters?: Record<string, any>;
     };
+    /**
+     * Where this tool is executed:
+     * - 'local': Execute locally by the execution engine (default)
+     * - 'provider': Executed by the LLM provider, results come in response
+     */
+    executionMode?: 'local' | 'provider';
+    /**
+     * Which provider executes this tool (when executionMode='provider')
+     * e.g., 'openai', 'anthropic'
+     */
+    executionProvider?: string;
 }
 /**
  * Image returned by an LLM response (e.g., from image generation models)
@@ -475,6 +522,12 @@ interface ToolDefinition {
  */
 interface LLMResponseImage {
     type: "image_url";
+    /** Unique ID for this generated image (used to link to tool call) */
+    id?: string;
+    /** Name of the tool that generated this image (e.g., 'image_generation') */
+    toolName?: string;
+    /** The revised/actual prompt used to generate the image (from OpenAI's image_generation) */
+    revisedPrompt?: string;
     image_url: {
         url: string;
     };
@@ -504,6 +557,12 @@ interface LLMResponse {
         cost?: number;
         provider?: string;
     };
+    /** @internal Provider instance reference for async metadata fetching */
+    _provider?: unknown;
+    /** @internal Provider response ID for async metadata fetching */
+    _providerResponseId?: string;
+    /** @internal Aggregate response for logging */
+    _aggregate_response?: unknown;
 }
 /**
  * Attachment returned by a tool (e.g., generated images)
@@ -636,6 +695,7 @@ interface LogData {
     tools_available?: number;
     prompt_name?: string;
     tools_called?: string;
+    actual_provider?: string | null;
     parent_log_id?: string | null;
     tools_schema?: string | null;
     message_history?: string | null;
@@ -780,20 +840,6 @@ interface LogEntry {
     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()
  */
@@ -806,6 +852,50 @@ interface ThreadMetaResponse {
         lastActivity: number | null;
     };
 }
+/**
+ * Log details returned by getLogDetails
+ */
+interface LogDetails {
+    id: string;
+    message_id: string;
+    provider: string;
+    actual_provider: string | null;
+    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;
+    provider_tools: string | null;
+    parent_log_id: string | null;
+    tools_schema: string | null;
+    system_prompt: string | null;
+    errors: string | null;
+    retry_of_log_id: string | null;
+    tool_results: string | null;
+    is_complete: number;
+    created_at: number;
+}
 /**
  * RPC methods exposed by DurableThread for external callers.
  */
@@ -829,9 +919,14 @@ interface DurableThreadRpc {
         total: number;
         hasMore: boolean;
     }>;
-    getLogDetails(logId: string): Promise<unknown>;
+    getLogDetails(logId: string): Promise<LogDetails | null>;
     getThreadMeta(threadId: string): Promise<ThreadMetaResponse | null>;
     deleteThread(): Promise<void>;
+    readFile(path: string): Promise<{
+        success: boolean;
+        data?: string;
+        error?: string;
+    }>;
 }
 /**
  * Thread registry entry from DurableAgentBuilder.
@@ -851,11 +946,16 @@ interface DurableAgentBuilderRpc {
         agent_name: string;
         user_id?: string;
         tags?: string[];
+        tenvs?: Record<string, unknown>;
+        properties?: Record<string, unknown>;
     }): Promise<ThreadRegistryEntry$1>;
     getThread(threadId: string): Promise<ThreadRegistryEntry$1 | null>;
     listThreads(params?: {
         agent_name?: string;
         user_id?: string;
+        search?: string;
+        startDate?: number;
+        endDate?: number;
         limit?: number;
         offset?: number;
     }): Promise<{
@@ -905,6 +1005,49 @@ interface ThreadEndpointContext {
         metadata: ThreadMetadata;
     };
 }
+/**
+ * Handler function for builder thread endpoints.
+ *
+ * Unlike the spec's ThreadEndpointHandler which receives ThreadState,
+ * the builder's handler receives direct access to the Durable Object
+ * instance and thread metadata. This allows for lower-level operations
+ * like calling RPC methods directly on the instance.
+ */
+type BuilderThreadEndpointHandler = (req: Request, context: {
+    instance: ThreadInstance;
+    metadata: ThreadMetadata;
+}) => Response | Promise<Response>;
+/**
+ * Define a thread-specific endpoint with access to the Durable Object instance.
+ *
+ * This is the builder's version of defineThreadEndpoint. It provides direct
+ * access to the thread's Durable Object instance and metadata, allowing
+ * for lower-level operations like calling RPC methods directly.
+ *
+ * @param handler - Function that receives the request and thread context
+ * @returns A Controller that can be used with the router
+ *
+ * @example
+ * ```typescript
+ * import { defineThreadEndpoint } from '@standardagents/builder';
+ *
+ * export default defineThreadEndpoint(async (req, { instance, metadata }) => {
+ *   // Access thread metadata
+ *   console.log('Thread ID:', metadata.id);
+ *   console.log('Agent ID:', metadata.agent_id);
+ *
+ *   // Call RPC methods on the Durable Object instance
+ *   const messagesResult = await instance.getMessages();
+ *   const logs = await instance.getLogs();
+ *
+ *   return Response.json({
+ *     messageCount: messagesResult.messages.length,
+ *     logCount: logs.length,
+ *   });
+ * });
+ * ```
+ */
+declare function defineThreadEndpoint(handler: BuilderThreadEndpointHandler): BuilderController;
 
 /**
  * Define a controller with typed Cloudflare environment bindings.
@@ -1066,6 +1209,16 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * Used for creating ThreadState outside of flow execution.
      */
     getThreadMetadata(threadId: string): Promise<ThreadMetadata>;
+    /**
+     * Trigger an agent to run on this thread.
+     *
+     * Queues an agent execution via the alarm queue. The execution
+     * runs asynchronously in the background.
+     *
+     * @param threadId - Thread ID for the execution
+     * @param agentName - Name of the agent to run
+     */
+    runAgent(threadId: string, agentName: string): Promise<void>;
     /**
      * Schedule an effect for future execution.
      *
@@ -1141,6 +1294,15 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * Simple "off" switch - stops turns, only cleared by user messages
      */
     stop(): Promise<Response>;
+    /**
+     * Continue execution from where it stopped (RPC method)
+     * Useful for debugging - continues the FlowEngine with additional steps
+     * without adding a new message.
+     *
+     * @param threadId The thread ID
+     * @param side Which side to start from ('a' or 'b'), defaults to 'a'
+     */
+    continueExecution(threadId: string, side?: 'a' | 'b'): Promise<Response>;
     /**
      * Get message history (RPC method)
      *
@@ -1253,10 +1415,12 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
             id: string;
             message_id: string;
             provider: string;
+            actual_provider: string | null;
             model: string;
             model_name: string | null;
             prompt_name: string | null;
             tools_called: string | null;
+            provider_tools: string | null;
             parent_log_id: string | null;
             retry_of_log_id: string | null;
             error: string | null;
@@ -1276,6 +1440,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
         id: string;
         message_id: string;
         provider: string;
+        actual_provider: string | null;
         model: string;
         model_name: string | null;
         endpoint: string | null;
@@ -1302,6 +1467,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
         tools_available: number | null;
         prompt_name: string | null;
         tools_called: string | null;
+        provider_tools: string | null;
         parent_log_id: string | null;
         tools_schema: string | null;
         message_history: string | null;
@@ -1410,8 +1576,9 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
     /**
      * WebSocket Hibernation API handler for connection close
      * Called when a WebSocket connection is closed
+     * Note: Do NOT call ws.close() here - the connection is already closed
      */
-    webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
+    webSocketClose(ws: WebSocket, _code: number, _reason: string, _wasClean: boolean): Promise<void>;
     /**
      * WebSocket Hibernation API handler for errors
      * Called when a WebSocket encounters an error
@@ -1440,6 +1607,11 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
      * This is the actual message processing logic, separate from the public sendMessage() RPC method
      */
     private processMessage;
+    /**
+     * Internal method: Continue execution without adding a message (called by alarm queue)
+     * This allows resuming FlowEngine execution from where it stopped.
+     */
+    private doContinueExecution;
     /**
      * TEST METHOD: Queue a test operation
      * Used for testing alarm queue ordering and timing
@@ -1751,6 +1923,7 @@ interface AgentBuilderEnv {
     GITHUB_TOKEN?: string;
     GITHUB_REPO?: string;
     GITHUB_BRANCH?: string;
+    ENCRYPTION_KEY?: string;
 }
 /**
  * Thread metadata stored in the registry.
@@ -1760,6 +1933,8 @@ interface ThreadRegistryEntry {
     agent_name: string;
     user_id: string | null;
     tags: string[] | null;
+    tenvs: Record<string, unknown> | null;
+    properties: Record<string, unknown> | null;
     created_at: number;
 }
 /**
@@ -1784,7 +1959,7 @@ interface User {
 /**
  * Provider credentials.
  */
-interface Provider {
+interface Provider$1 {
     name: string;
     sdk: string;
     api_key: string;
@@ -1828,6 +2003,8 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
         agent_name: string;
         user_id?: string;
         tags?: string[];
+        tenvs?: Record<string, unknown>;
+        properties?: Record<string, unknown>;
     }): Promise<ThreadRegistryEntry>;
     /**
      * Get a thread by ID.
@@ -1835,10 +2012,15 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
     getThread(id: string): Promise<ThreadRegistryEntry | null>;
     /**
      * List threads with optional filtering.
+     * Note: tenvs are not decrypted in list operations for performance.
+     * Use getThread() to retrieve a thread with decrypted tenvs.
      */
     listThreads(params?: {
         agent_name?: string;
         user_id?: string;
+        search?: string;
+        startDate?: number;
+        endDate?: number;
         limit?: number;
         offset?: number;
     }): Promise<{
@@ -1884,15 +2066,15 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
     /**
      * Get a provider's credentials.
      */
-    getProvider(name: string): Promise<Provider | null>;
+    getProvider(name: string): Promise<Provider$1 | null>;
     /**
      * Set a provider's credentials.
      */
-    setProvider(provider: Provider): Promise<void>;
+    setProvider(provider: Provider$1): Promise<void>;
     /**
      * List all providers.
      */
-    listProviders(): Promise<Provider[]>;
+    listProviders(): Promise<Provider$1[]>;
     /**
      * Delete a provider.
      */
@@ -2266,16 +2448,34 @@ interface AgentDefinition<N extends string = string> {
     exposeAsTool?: boolean;
     /** Description shown when agent is used as a tool. */
     toolDescription?: string;
+    /**
+     * Thread environment variables for this agent.
+     * Merged into thread tenvs at creation time.
+     * Later values (thread) override earlier ones (prompt -> agent).
+     */
+    tenvs?: Record<string, unknown>;
     /** Brief description of what this agent does. */
     description?: string;
     /** Icon URL or absolute path for the agent. */
     icon?: string;
 }
 
+/**
+ * Options for generating a model file.
+ */
+interface GenerateModelFileOptions {
+    /** The provider export name (e.g., 'openai', 'openrouter') */
+    providerName: string;
+    /** The provider package (e.g., '@standardagents/openai') */
+    providerPackage: string;
+}
 /**
  * Generate a TypeScript file for a model definition.
+ *
+ * @param data - The model definition data
+ * @param options - Provider import options (required since providers are functions)
  */
-declare function generateModelFile(data: ModelDefinition): string;
+declare function generateModelFile(data: ModelDefinition, options: GenerateModelFileOptions): string;
 
 /**
  * Converts JSON Schema to Zod code string.
@@ -2314,6 +2514,8 @@ interface ToolConfigInput {
     include_tool_calls?: boolean;
     include_errors?: boolean;
     init_user_message_property?: string | null;
+    init_attachments_property?: string | null;
+    tenvs?: Record<string, unknown>;
 }
 /**
  * Prompt part as it comes from the UI/API.
@@ -3432,4 +3634,15 @@ declare class GitHubApiError extends Error {
     constructor(message: string, status: number, details?: unknown);
 }
 
-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 };
+/** @public Alias for LLMProviderInterface */
+type Provider = LLMProviderInterface;
+/** @public Alias for ContentPart */
+type ProviderContentPart = ContentPart;
+/** @public Alias for TextPart */
+type ProviderTextPart = TextPart;
+/** @public Alias for ImagePart */
+type ProviderImagePart = ImagePart;
+/** @public Alias for FilePart */
+type ProviderFilePart = FilePart;
+
+export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, type BuilderThreadEndpointHandler, 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 Provider as LLMProviderInterface, type LLMResponse, type Message, type MessageContent, type ModelDefinition, type MultimodalContent, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptPart, type Provider$1 as Provider, type ProviderContentPart, type ProviderFilePart, type ProviderImagePart, type ProviderTextPart, 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, defineThreadEndpoint, 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 };