@standardagents/builder 0.11.0-next.7711e15 → 0.11.0-next.80cee2e

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  export { AgentPluginOptions, agentbuilder } from './plugin.js';
2
2
  import { DurableObjectStorage } from '@cloudflare/workers-types';
3
- import { z, ZodString, ZodNumber, ZodBoolean, ZodNull, ZodLiteral, ZodEnum, ZodOptional, ZodNullable, ZodDefault, ZodArray, ZodObject, ZodRecord, ZodUnion } from 'zod';
3
+ import { ZodObject, ZodRawShape } from 'zod';
4
+ 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';
5
+ 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';
4
6
  import { DurableObject } from 'cloudflare:workers';
5
7
  import 'vite';
6
8
 
@@ -144,122 +146,6 @@ declare class StreamManager {
144
146
  forceClose(): void;
145
147
  }
146
148
 
147
- /**
148
- * Content item types that can be returned by tools
149
- */
150
- interface TextContent {
151
- type: "text";
152
- text: string;
153
- }
154
- interface ImageContent {
155
- type: "image";
156
- data: string;
157
- mimeType: string;
158
- }
159
- type ToolContent = TextContent | ImageContent;
160
- /** Decrement helper to stop recursion at depth 0 */
161
- 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;
162
- /**
163
- * Allowed Zod node for tool arguments.
164
- * Tweak this union as your single source of truth for what’s allowed.
165
- * Increase the default depth if you need crazier nesting.
166
- */
167
- 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<[
168
- ToolArgsNode<Dec<D>>,
169
- ToolArgsNode<Dec<D>>,
170
- ...ToolArgsNode<Dec<D>>[]
171
- ]>);
172
- /**
173
- * Raw shape for an object whose values are ToolArgsNode.
174
- * This is what users write inside z.object({ ... }).
175
- */
176
- type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
177
- /** The top-level schema must be an object for OpenAI tools. */
178
- type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
179
- type StructuredToolReturn = ToolArgs;
180
- /**
181
- * Defines a tool function. Tools accept the current flow state as well as the arguments being passed to them.
182
- */
183
- type Tool<Args extends ToolArgs | null = null> = Args extends ToolArgs ? (flow: FlowState, args: z.infer<Args>) => Promise<ToolResult> : (flow: FlowState) => Promise<ToolResult>;
184
- /**
185
- * @param toolDescription - Description of what the tool does.
186
- * @param args - The arguments for the tool.
187
- * @param tool - The tool function.
188
- * @returns A tuple containing the description, arguments and the tool function.
189
- */
190
- declare function defineTool<Args extends ToolArgs>(toolDescription: string, args: Args, tool: Tool<Args>): [string, Args, Tool<Args>, null];
191
- declare function defineTool(toolDescription: string, tool: Tool<null>): [string, null, Tool<null>, null];
192
- declare function defineTool<Args extends ToolArgs, RetValue extends StructuredToolReturn>(toolDescription: string, args: Args, tool: Tool<Args>, returnSchema: RetValue): [string, Args, Tool<Args>, RetValue];
193
-
194
- /**
195
- * Hook signatures for all available hooks
196
- */
197
- interface HookSignatures {
198
- /**
199
- * Called before messages are filtered and sent to the LLM
200
- * Receives SQL row data with all columns before transformation
201
- * Return value is transformed into chat completion format
202
- */
203
- filter_messages: (state: FlowState, rows: Message[]) => Promise<Message[]>;
204
- /**
205
- * Called after message history is loaded and before sending to LLM
206
- * Receives messages in chat completion format (already transformed)
207
- */
208
- prefilter_llm_history: (state: FlowState, messages: Array<{
209
- role: string;
210
- content: string | null;
211
- tool_calls?: any;
212
- tool_call_id?: string;
213
- name?: string;
214
- }>) => Promise<Array<{
215
- role: string;
216
- content: string | null;
217
- tool_calls?: any;
218
- tool_call_id?: string;
219
- name?: string;
220
- }>>;
221
- /**
222
- * Called before a message is created in the database
223
- */
224
- before_create_message: (state: FlowState, message: Record<string, any>) => Promise<Record<string, any>>;
225
- /**
226
- * Called after a message is created in the database
227
- */
228
- after_create_message: (state: FlowState, message: Record<string, any>) => Promise<void>;
229
- /**
230
- * Called before a message is updated in the database
231
- */
232
- before_update_message: (state: FlowState, messageId: string, updates: Record<string, any>) => Promise<Record<string, any>>;
233
- /**
234
- * Called after a message is updated in the database
235
- */
236
- after_update_message: (state: FlowState, message: Message) => Promise<void>;
237
- /**
238
- * Called before a tool result is stored in the database
239
- */
240
- before_store_tool_result: (state: FlowState, toolCall: Record<string, any>, toolResult: Record<string, any>) => Promise<Record<string, any>>;
241
- /**
242
- * Called after a successful tool call
243
- */
244
- after_tool_call_success: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
245
- /**
246
- * Called after a failed tool call
247
- */
248
- after_tool_call_failure: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
249
- }
250
- /**
251
- * Define a hook with strict typing based on hook name
252
- *
253
- * @example
254
- * ```typescript
255
- * export default defineHook('filter_messages', async (state, rows) => {
256
- * // Only include messages from last 10 turns
257
- * return rows.slice(-10);
258
- * });
259
- * ```
260
- */
261
- declare function defineHook<K extends keyof HookSignatures>(hookName: K, implementation: HookSignatures[K]): HookSignatures[K];
262
-
263
149
  /**
264
150
  * Agent configuration from D1 agents table
265
151
  */
@@ -274,15 +160,15 @@ interface Agent {
274
160
  side_a_stop_on_response: boolean;
275
161
  side_a_stop_tool: string | null;
276
162
  side_a_stop_tool_response_property: string | null;
277
- side_a_max_turns: number | null;
278
- side_a_end_conversation_tool: string | null;
163
+ side_a_max_steps: number | null;
164
+ side_a_end_session_tool: string | null;
279
165
  side_b_label: string | null;
280
166
  side_b_agent_prompt: string | null;
281
167
  side_b_stop_on_response: boolean;
282
168
  side_b_stop_tool: string | null;
283
169
  side_b_stop_tool_response_property: string | null;
284
- side_b_max_turns: number | null;
285
- side_b_end_conversation_tool: string | null;
170
+ side_b_max_steps: number | null;
171
+ side_b_end_session_tool: string | null;
286
172
  }
287
173
  /**
288
174
  * Message in OpenAI chat completion format
@@ -335,6 +221,12 @@ interface ThreadMetadata {
335
221
  type HookRegistry = {
336
222
  [K in keyof HookSignatures]?: () => Promise<HookSignatures[K]>;
337
223
  };
224
+ /**
225
+ * Native tool module type - represents a loaded tool definition.
226
+ * Tools can have args (with validation schema) or no args.
227
+ * Uses local Zod types for compatibility with z.toJSONSchema().
228
+ */
229
+ 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>];
338
230
  /**
339
231
  * Thread instance (forward reference to avoid circular dependency)
340
232
  */
@@ -348,14 +240,44 @@ interface ThreadInstance {
348
240
  }>;
349
241
  getLogs(limit?: number, offset?: number, order?: "asc" | "desc"): Promise<LogData[]>;
350
242
  getThreadMeta(threadId: string): Promise<ThreadMetadata | null>;
243
+ deleteMessage(messageId: string): Promise<{
244
+ success: boolean;
245
+ error?: string;
246
+ }>;
351
247
  shouldStop(): Promise<boolean>;
352
- tools(): Record<string, () => Promise<ReturnType<typeof defineTool>>>;
248
+ tools(): Record<string, () => Promise<NativeToolModule>>;
353
249
  hooks(): HookRegistry;
354
250
  loadModel(name: string): Promise<any>;
355
251
  loadPrompt(name: string): Promise<any>;
356
252
  loadAgent(name: string): Promise<any>;
357
253
  getPromptNames(): string[];
358
254
  getAgentNames(): string[];
255
+ writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: Record<string, unknown>): Promise<any>;
256
+ readFile(path: string): Promise<ArrayBuffer | null>;
257
+ statFile(path: string): Promise<any>;
258
+ readdirFile(path: string): Promise<any[]>;
259
+ unlinkFile(path: string): Promise<void>;
260
+ mkdirFile(path: string): Promise<any>;
261
+ rmdirFile(path: string): Promise<void>;
262
+ getFileStats(): Promise<any>;
263
+ grepFiles(pattern: string): Promise<any[]>;
264
+ findFiles(pattern: string): Promise<any>;
265
+ getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
266
+ readFileChunk(path: string, chunkIndex: number): Promise<{
267
+ success: boolean;
268
+ data?: string;
269
+ error?: string;
270
+ }>;
271
+ runAgent(threadId: string, agentName: string): Promise<void>;
272
+ scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
273
+ getScheduledEffects(name?: string): Promise<Array<{
274
+ id: string;
275
+ name: string;
276
+ args: Record<string, unknown>;
277
+ scheduledAt: number;
278
+ createdAt: number;
279
+ }>>;
280
+ removeScheduledEffect(id: string): Promise<boolean>;
359
281
  insertOrphanedToolCall(params: {
360
282
  content?: string;
361
283
  toolCallId: string;
@@ -389,9 +311,9 @@ type FlowCallWithRetries = FlowCall & {
389
311
  reasons: string[];
390
312
  };
391
313
  /**
392
- * Tool configuration for a prompt - defines options for when a tool is used
314
+ * Sub-prompt configuration - defines options for when a sub-prompt is called as a tool
393
315
  */
394
- interface ToolConfig$1 {
316
+ interface SubpromptConfig$1 {
395
317
  name: string;
396
318
  initUserMessageProperty?: string;
397
319
  includeTextResponse?: boolean;
@@ -412,8 +334,6 @@ interface PromptData {
412
334
  required_schema: string;
413
335
  include_chat: boolean;
414
336
  include_past_tools: boolean;
415
- before_tool: string | null;
416
- after_tool: string | null;
417
337
  prompts: string;
418
338
  created_at: number;
419
339
  /** @deprecated All prompts are now automatically exposed as tools */
@@ -424,10 +344,8 @@ interface PromptData {
424
344
  reasoning_max_tokens: number | null;
425
345
  reasoning_exclude: boolean;
426
346
  include_reasoning: boolean;
427
- maxImagePixels: number | null;
428
347
  recentImageThreshold: number | null;
429
- _tools?: (string | ToolConfig$1)[];
430
- _handoffAgents?: string[];
348
+ _tools?: (string | SubpromptConfig$1)[];
431
349
  _requiredSchema?: any;
432
350
  }
433
351
  /**
@@ -447,9 +365,9 @@ interface FlowState {
447
365
  sideB: PromptData | null;
448
366
  };
449
367
  prompt: PromptData;
450
- turnCount: number;
451
- sideATurnCount: number;
452
- sideBTurnCount: number;
368
+ stepCount: number;
369
+ sideAStepCount: number;
370
+ sideBStepCount: number;
453
371
  stopped: boolean;
454
372
  stoppedBy?: "a" | "b";
455
373
  forcedNextSide?: "side_a" | "side_b";
@@ -556,6 +474,16 @@ interface ToolDefinition {
556
474
  parameters?: Record<string, any>;
557
475
  };
558
476
  }
477
+ /**
478
+ * Image returned by an LLM response (e.g., from image generation models)
479
+ * Format follows OpenAI/OpenRouter chat completions API
480
+ */
481
+ interface LLMResponseImage {
482
+ type: "image_url";
483
+ image_url: {
484
+ url: string;
485
+ };
486
+ }
559
487
  /**
560
488
  * LLM response
561
489
  */
@@ -566,6 +494,7 @@ interface LLMResponse {
566
494
  reasoning_content?: string | null;
567
495
  reasoning_details?: any[];
568
496
  tool_calls?: ToolCall[];
497
+ images?: LLMResponseImage[];
569
498
  finish_reason: string;
570
499
  usage: {
571
500
  prompt_tokens: number;
@@ -581,6 +510,17 @@ interface LLMResponse {
581
510
  provider?: string;
582
511
  };
583
512
  }
513
+ /**
514
+ * Attachment returned by a tool (e.g., generated images)
515
+ * Stored in thread filesystem and linked to the tool message
516
+ */
517
+ interface ToolAttachment {
518
+ name: string;
519
+ mimeType: string;
520
+ data: string;
521
+ width?: number;
522
+ height?: number;
523
+ }
584
524
  /**
585
525
  * Tool result
586
526
  */
@@ -597,6 +537,16 @@ interface ToolResult {
597
537
  result?: string;
598
538
  error?: string;
599
539
  stack?: string;
540
+ /**
541
+ * File attachments returned by the tool.
542
+ *
543
+ * Can contain either:
544
+ * - ToolAttachment: New files with base64 data to be stored
545
+ * - AttachmentRef: References to existing files in the thread filesystem
546
+ *
547
+ * New attachments are stored under /attachments/ directory.
548
+ */
549
+ attachments?: Array<ToolAttachment | AttachmentRef>;
600
550
  }
601
551
  /**
602
552
  * Flow execution result
@@ -605,20 +555,20 @@ interface FlowResult {
605
555
  messages: Message[];
606
556
  stopped: boolean;
607
557
  stoppedBy?: "a" | "b";
608
- turnCount: number;
558
+ stepCount: number;
609
559
  stream: ReadableStream<Uint8Array>;
610
560
  }
611
561
  /**
612
562
  * Telemetry event types
613
563
  */
614
564
  type TelemetryEvent = {
615
- type: "turn_started";
616
- turn: number;
565
+ type: "step_started";
566
+ step: number;
617
567
  side: "a" | "b";
618
568
  timestamp: number;
619
569
  } | {
620
- type: "turn_completed";
621
- turn: number;
570
+ type: "step_completed";
571
+ step: number;
622
572
  stopped: boolean;
623
573
  timestamp: number;
624
574
  } | {
@@ -741,6 +691,8 @@ interface FileRecord {
741
691
  createdAt: number;
742
692
  width?: number | null;
743
693
  height?: number | null;
694
+ isChunked?: boolean;
695
+ chunkCount?: number;
744
696
  }
745
697
  /**
746
698
  * Image-specific metadata stored in FileRecord.metadata
@@ -779,43 +731,178 @@ interface FileStats {
779
731
  fileCount: number;
780
732
  }
781
733
 
734
+ /**
735
+ * Router and endpoint definition module for AgentBuilder.
736
+ *
737
+ * This module re-exports endpoint types from @standardagents/spec and provides
738
+ * the runtime router implementation for handling HTTP requests.
739
+ *
740
+ * @module
741
+ */
742
+
743
+ /**
744
+ * Durable Object namespace interface.
745
+ * This is Cloudflare-specific and used by the builder runtime.
746
+ */
747
+ interface DurableObjectNamespace$1<T = unknown> {
748
+ idFromName(name: string): DurableObjectId;
749
+ idFromString(id: string): DurableObjectId;
750
+ newUniqueId(): DurableObjectId;
751
+ get(id: DurableObjectId): DurableObjectStub$1<T>;
752
+ }
753
+ /**
754
+ * Durable Object ID interface.
755
+ */
756
+ interface DurableObjectId {
757
+ toString(): string;
758
+ equals(other: DurableObjectId): boolean;
759
+ }
760
+ /**
761
+ * Durable Object stub interface.
762
+ * The generic type T represents the RPC methods available on the stub.
763
+ */
764
+ type DurableObjectStub$1<T = unknown> = {
765
+ id: DurableObjectId;
766
+ name?: string;
767
+ fetch(request: Request | string, requestInitr?: RequestInit): Promise<Response>;
768
+ } & T;
769
+ /**
770
+ * Log entry from DurableThread.getLogs()
771
+ */
772
+ interface LogEntry {
773
+ id: string;
774
+ message_id: string;
775
+ provider: string;
776
+ model: string;
777
+ model_name: string | null;
778
+ prompt_name: string | null;
779
+ tools_called: string | null;
780
+ parent_log_id: string | null;
781
+ retry_of_log_id: string | null;
782
+ error: string | null;
783
+ cost_total: number | null;
784
+ is_complete: number;
785
+ created_at: number;
786
+ request_body: string | null;
787
+ }
788
+ /**
789
+ * Agent definition returned from loadAgent()
790
+ */
791
+ interface AgentDefinition$1 {
792
+ name: string;
793
+ title?: string;
794
+ type?: string;
795
+ description?: string;
796
+ icon?: string;
797
+ defaultPrompt?: string;
798
+ defaultModel?: string;
799
+ tools?: string[];
800
+ [key: string]: unknown;
801
+ }
802
+ /**
803
+ * Response from getThreadMeta()
804
+ */
805
+ interface ThreadMetaResponse {
806
+ thread: ThreadRegistryEntry$1;
807
+ agent: AgentDefinition$1 | null;
808
+ stats: {
809
+ messageCount: number;
810
+ logCount: number;
811
+ lastActivity: number | null;
812
+ };
813
+ }
814
+ /**
815
+ * RPC methods exposed by DurableThread for external callers.
816
+ */
817
+ interface DurableThreadRpc {
818
+ stop(): Promise<Response>;
819
+ getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC", includeSilent?: boolean, maxDepth?: number): Promise<{
820
+ messages: unknown[];
821
+ total: number;
822
+ hasMore: boolean;
823
+ }>;
824
+ deleteMessage(messageId: string): Promise<{
825
+ success: boolean;
826
+ error?: string;
827
+ }>;
828
+ updateMessageContent(messageId: string, content: string): Promise<{
829
+ success: boolean;
830
+ error?: string;
831
+ }>;
832
+ getLogs(limit?: number, offset?: number, order?: "ASC" | "DESC"): Promise<{
833
+ logs: LogEntry[];
834
+ total: number;
835
+ hasMore: boolean;
836
+ }>;
837
+ getLogDetails(logId: string): Promise<unknown>;
838
+ getThreadMeta(threadId: string): Promise<ThreadMetaResponse | null>;
839
+ deleteThread(): Promise<void>;
840
+ }
841
+ /**
842
+ * Thread registry entry from DurableAgentBuilder.
843
+ */
844
+ interface ThreadRegistryEntry$1 {
845
+ id: string;
846
+ agent_name: string;
847
+ user_id: string | null;
848
+ tags: string[] | null;
849
+ created_at: number;
850
+ }
851
+ /**
852
+ * RPC methods exposed by DurableAgentBuilder for external callers.
853
+ */
854
+ interface DurableAgentBuilderRpc {
855
+ createThread(params: {
856
+ agent_name: string;
857
+ user_id?: string;
858
+ tags?: string[];
859
+ }): Promise<ThreadRegistryEntry$1>;
860
+ getThread(threadId: string): Promise<ThreadRegistryEntry$1 | null>;
861
+ listThreads(params?: {
862
+ agent_name?: string;
863
+ user_id?: string;
864
+ limit?: number;
865
+ offset?: number;
866
+ }): Promise<{
867
+ threads: ThreadRegistryEntry$1[];
868
+ total: number;
869
+ }>;
870
+ deleteThread(threadId: string): Promise<void>;
871
+ getUserByUsername(username: string): Promise<unknown>;
872
+ createSession(session: {
873
+ user_id: string;
874
+ token_hash: string;
875
+ expires_at: number;
876
+ }): Promise<void>;
877
+ loadAgent(name: string): Promise<AgentDefinition$1>;
878
+ }
782
879
  /**
783
880
  * Minimum required environment bindings for thread endpoints.
784
881
  * User's Env interface should extend this.
785
882
  *
786
- * Uses Rpc.DurableObjectBranded to allow users to specify their own
787
- * Durable Object types that extend DurableThread/DurableAgentBuilder.
883
+ * This is Cloudflare-specific and used by the builder runtime.
788
884
  */
789
885
  interface ThreadEnv {
790
- AGENT_BUILDER_THREAD: DurableObjectNamespace<Rpc.DurableObjectBranded>;
791
- AGENT_BUILDER: DurableObjectNamespace<Rpc.DurableObjectBranded>;
886
+ AGENT_BUILDER_THREAD: DurableObjectNamespace$1<DurableThreadRpc>;
887
+ AGENT_BUILDER: DurableObjectNamespace$1<DurableAgentBuilderRpc>;
792
888
  [key: string]: unknown;
793
889
  }
794
890
  /**
795
- * Virtual module registry types (injected at runtime by plugin)
891
+ * Builder-specific controller context with typed env.
892
+ *
893
+ * This extends the spec's ControllerContext with proper typing for
894
+ * Cloudflare environment bindings.
796
895
  */
797
- type VirtualModuleLoader<T> = () => Promise<T>;
798
- type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
896
+ interface BuilderControllerContext<Env extends ThreadEnv = ThreadEnv> extends Omit<ControllerContext, 'env'> {
897
+ env: Env;
898
+ }
799
899
  /**
800
- * Controller context passed to route handlers.
801
- * Includes optional virtual module registries that are injected at runtime.
900
+ * Builder-specific controller type with typed env.
901
+ */
902
+ type BuilderController<Env extends ThreadEnv = ThreadEnv> = (context: BuilderControllerContext<Env>) => ReturnType<Controller>;
903
+ /**
904
+ * Thread endpoint context with access to thread instance and metadata.
802
905
  */
803
- interface ControllerContext<Env = any> {
804
- req: Request;
805
- params: Record<string, string>;
806
- env: Env;
807
- url: URL;
808
- agents?: VirtualModuleRegistry<unknown>;
809
- agentNames?: string[];
810
- prompts?: VirtualModuleRegistry<unknown>;
811
- promptNames?: string[];
812
- models?: VirtualModuleRegistry<unknown>;
813
- modelNames?: string[];
814
- tools?: VirtualModuleRegistry<unknown>;
815
- hooks?: VirtualModuleRegistry<unknown>;
816
- config?: Record<string, unknown>;
817
- }
818
- 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;
819
906
  interface ThreadEndpointContext {
820
907
  req: Request;
821
908
  thread: {
@@ -823,22 +910,24 @@ interface ThreadEndpointContext {
823
910
  metadata: ThreadMetadata;
824
911
  };
825
912
  }
826
- declare function defineController<Env = any>(controller: Controller<Env>): Controller<Env>;
913
+
827
914
  /**
828
- * Define a thread-specific endpoint that has access to the thread's DurableObject instance and metadata.
829
- * This wraps defineController and automatically looks up the thread by ID from the URL params.
915
+ * Define a controller with typed Cloudflare environment bindings.
830
916
  *
831
- * @param handler - Function that receives the request and thread context
832
- * @returns A Controller that can be used with the router
917
+ * This is the builder's version of defineController that provides
918
+ * proper typing for AGENT_BUILDER_THREAD and other CF bindings.
833
919
  *
834
920
  * @example
835
- * // agentbuilder/api/status.ts
836
- * export default defineThreadEndpoint(async (req, { thread }) => {
837
- * const messages = await thread.instance.getMessages();
838
- * return Response.json({ status: "ok", messageCount: messages.length });
921
+ * ```typescript
922
+ * import { defineController } from '../router/index.js';
923
+ *
924
+ * export default defineController(async ({ req, env }) => {
925
+ * const stub = env.AGENT_BUILDER.get(env.AGENT_BUILDER.idFromName('singleton'));
926
+ * // ...
839
927
  * });
928
+ * ```
840
929
  */
841
- declare function defineThreadEndpoint<Env extends ThreadEnv = ThreadEnv>(handler: (req: Request, context: ThreadEndpointContext["thread"]) => Response | Promise<Response>): Controller<Env>;
930
+ declare function defineController<Env extends ThreadEnv = ThreadEnv>(controller: BuilderController<Env>): BuilderController<Env>;
842
931
 
843
932
  /**
844
933
  * Authentication middleware for protecting API routes
@@ -934,6 +1023,17 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
934
1023
  * @returns Record of agent name to agent loader function
935
1024
  */
936
1025
  agents(): Record<string, () => Promise<any>>;
1026
+ /**
1027
+ * Returns the effects registry for lazy-loading effect definitions.
1028
+ * This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
1029
+ *
1030
+ * Effects are scheduled operations that run outside the tool execution context,
1031
+ * ideal for delayed notifications, webhooks, and cleanup tasks.
1032
+ *
1033
+ * @throws Error if not implemented in a subclass
1034
+ * @returns Record of effect name to effect loader function
1035
+ */
1036
+ effects(): Record<string, () => Promise<any>>;
937
1037
  /**
938
1038
  * Load a model definition by name.
939
1039
  */
@@ -958,6 +1058,59 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
958
1058
  * List available agent names.
959
1059
  */
960
1060
  getAgentNames(): string[];
1061
+ /**
1062
+ * Load an effect definition by name.
1063
+ */
1064
+ loadEffect(name: string): Promise<any>;
1065
+ /**
1066
+ * List available effect names.
1067
+ */
1068
+ getEffectNames(): string[];
1069
+ /**
1070
+ * Get thread metadata from DurableAgentBuilder.
1071
+ * Used for creating ThreadState outside of flow execution.
1072
+ */
1073
+ getThreadMetadata(threadId: string): Promise<ThreadMetadata>;
1074
+ /**
1075
+ * Trigger an agent to run on this thread.
1076
+ *
1077
+ * Queues an agent execution via the alarm queue. The execution
1078
+ * runs asynchronously in the background.
1079
+ *
1080
+ * @param threadId - Thread ID for the execution
1081
+ * @param agentName - Name of the agent to run
1082
+ */
1083
+ runAgent(threadId: string, agentName: string): Promise<void>;
1084
+ /**
1085
+ * Schedule an effect for future execution.
1086
+ *
1087
+ * @param threadId - Thread ID for the effect execution context
1088
+ * @param effectName - Name of the effect to schedule
1089
+ * @param effectArgs - Arguments to pass to the effect handler
1090
+ * @param delayMs - Delay in milliseconds before execution (default: 0)
1091
+ * @returns UUID of the scheduled effect
1092
+ */
1093
+ scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
1094
+ /**
1095
+ * Get scheduled effects for this thread.
1096
+ *
1097
+ * @param name - Optional effect name to filter by
1098
+ * @returns Array of scheduled effect records
1099
+ */
1100
+ getScheduledEffects(name?: string): Promise<Array<{
1101
+ id: string;
1102
+ name: string;
1103
+ args: Record<string, unknown>;
1104
+ scheduledAt: number;
1105
+ createdAt: number;
1106
+ }>>;
1107
+ /**
1108
+ * Remove a scheduled effect.
1109
+ *
1110
+ * @param id - The effect ID returned by scheduleEffect
1111
+ * @returns true if the effect was found and removed, false otherwise
1112
+ */
1113
+ removeScheduledEffect(id: string): Promise<boolean>;
961
1114
  /**
962
1115
  * Ensures the database schema is up to date.
963
1116
  * This method is called on the first request to the Durable Object.
@@ -1046,6 +1199,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
1046
1199
  }>;
1047
1200
  /**
1048
1201
  * Delete a message (RPC method)
1202
+ * Also cleans up any attachment files stored on the thread filesystem
1049
1203
  */
1050
1204
  deleteMessage(messageId: string): Promise<{
1051
1205
  success: boolean;
@@ -1255,7 +1409,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
1255
1409
  private broadcastMessageChunk;
1256
1410
  /**
1257
1411
  * Broadcast a telemetry event to all connected message WebSocket clients
1258
- * Used for execution status updates (turn_started, tool_started, etc.)
1412
+ * Used for execution status updates (step_started, tool_started, etc.)
1259
1413
  */
1260
1414
  private broadcastTelemetry;
1261
1415
  /**
@@ -1291,6 +1445,11 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
1291
1445
  * This is the actual execution logic, separate from the public execute() RPC method
1292
1446
  */
1293
1447
  private executeFlow;
1448
+ /**
1449
+ * Internal method: Execute an effect (called by alarm queue)
1450
+ * Effects run outside the tool execution context.
1451
+ */
1452
+ private executeEffect;
1294
1453
  /**
1295
1454
  * Internal method: Process a message (called by alarm queue)
1296
1455
  * This is the actual message processing logic, separate from the public sendMessage() RPC method
@@ -1542,6 +1701,59 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
1542
1701
  error: any;
1543
1702
  files?: undefined;
1544
1703
  }>;
1704
+ /**
1705
+ * Start a chunked file upload.
1706
+ * Creates file record with is_chunked=1 and chunk_count=null.
1707
+ * Caller should then use writeFileChunk() to write chunks.
1708
+ */
1709
+ startChunkedUpload(path: string, totalSize: number, mimeType: string, options?: {
1710
+ metadata?: Record<string, unknown>;
1711
+ width?: number;
1712
+ height?: number;
1713
+ }): Promise<{
1714
+ success: boolean;
1715
+ chunkSize?: number;
1716
+ expectedChunks?: number;
1717
+ error?: string;
1718
+ }>;
1719
+ /**
1720
+ * Write a single chunk of a chunked file upload.
1721
+ * @param path - File path
1722
+ * @param chunkIndex - 0-based chunk index
1723
+ * @param data - Base64 encoded chunk data
1724
+ */
1725
+ writeFileChunk(path: string, chunkIndex: number, data: string): Promise<{
1726
+ success: boolean;
1727
+ error?: string;
1728
+ }>;
1729
+ /**
1730
+ * Complete a chunked file upload.
1731
+ * Validates all chunks are present and sets chunk_count.
1732
+ */
1733
+ completeChunkedUpload(path: string, expectedChunks: number, options?: {
1734
+ thumbnail?: string;
1735
+ }): Promise<{
1736
+ success: boolean;
1737
+ file?: FileRecord;
1738
+ error?: string;
1739
+ }>;
1740
+ /**
1741
+ * Read a single chunk of a file.
1742
+ * Use for streaming large files to client.
1743
+ */
1744
+ readFileChunk(path: string, chunkIndex: number): Promise<{
1745
+ success: boolean;
1746
+ data?: string;
1747
+ error?: string;
1748
+ }>;
1749
+ /**
1750
+ * Get file info including chunking metadata.
1751
+ */
1752
+ getFileInfo(path: string): Promise<{
1753
+ success: boolean;
1754
+ file?: FileRecord;
1755
+ error?: string;
1756
+ }>;
1545
1757
  }
1546
1758
 
1547
1759
  /**
@@ -1872,181 +2084,44 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
1872
2084
  /**
1873
2085
  * Model definition module for AgentBuilder.
1874
2086
  *
1875
- * Models define LLM configurations including provider, model ID, pricing,
1876
- * and fallback chains. Models are referenced by name from prompts.
2087
+ * This module re-exports model types from @standardagents/spec and provides
2088
+ * a builder-specific version of ModelDefinition that supports the generated
2089
+ * AgentBuilder.Models type for fallback references.
1877
2090
  *
1878
2091
  * @module
1879
2092
  */
2093
+
1880
2094
  /**
1881
- * Supported LLM provider types.
1882
- * Each provider requires a corresponding API key environment variable:
1883
- * - `openai` → `OPENAI_API_KEY`
1884
- * - `openrouter` → `OPENROUTER_API_KEY`
1885
- * - `anthropic` → `ANTHROPIC_API_KEY`
1886
- * - `google` → `GOOGLE_API_KEY`
1887
- * - `test` → No API key required (for testing with scripted responses)
1888
- */
1889
- type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
1890
- /**
1891
- * Model definition configuration.
2095
+ * Model definition configuration with AgentBuilder-specific fallback typing.
1892
2096
  *
1893
- * @template N - The model name as a string literal type for type inference
2097
+ * Extends the base ModelDefinition from @standardagents/spec to support
2098
+ * the generated AgentBuilder.Models type for type-safe fallback references.
1894
2099
  *
1895
- * @example
1896
- * ```typescript
1897
- * import { defineModel } from '@standardagents/builder';
1898
- *
1899
- * export default defineModel({
1900
- * name: 'gpt-4o',
1901
- * provider: 'openai',
1902
- * model: 'gpt-4o',
1903
- * fallbacks: ['gpt-4-turbo', 'gpt-3.5-turbo'],
1904
- * inputPrice: 2.5,
1905
- * outputPrice: 10,
1906
- * });
1907
- * ```
2100
+ * @template N - The model name as a string literal type for type inference
1908
2101
  */
1909
- interface ModelDefinition<N extends string = string> {
1910
- /**
1911
- * Unique name for this model definition.
1912
- * Used as the identifier when referencing from prompts.
1913
- * Should be descriptive and consistent (e.g., 'gpt-4o', 'claude-3-opus').
1914
- */
1915
- name: N;
1916
- /**
1917
- * The LLM provider to use for API calls.
1918
- * The corresponding API key environment variable must be set.
1919
- */
1920
- provider: ModelProvider;
1921
- /**
1922
- * The actual model identifier sent to the provider API.
1923
- *
1924
- * For OpenAI: 'gpt-4o', 'gpt-4-turbo', 'gpt-3.5-turbo', etc.
1925
- * For OpenRouter: 'openai/gpt-4o', 'anthropic/claude-3-opus', etc.
1926
- * For Anthropic: 'claude-3-opus-20240229', 'claude-3-sonnet-20240229', etc.
1927
- * For Google: 'gemini-1.5-pro', 'gemini-1.5-flash', etc.
1928
- */
1929
- model: string;
1930
- /**
1931
- * Optional list of additional provider prefixes for OpenRouter.
1932
- * Allows routing through specific providers when using OpenRouter.
1933
- *
1934
- * @example ['anthropic', 'google'] - prefer Anthropic, fallback to Google
1935
- */
1936
- includedProviders?: string[];
2102
+ interface ModelDefinition<N extends string = string> extends Omit<ModelDefinition$1<N>, 'fallbacks'> {
1937
2103
  /**
1938
2104
  * Fallback models to try if this model fails.
1939
- * Referenced by model name (must be defined in agentbuilder/models/).
2105
+ * Referenced by model name (must be defined in agents/models/).
1940
2106
  * Tried in order after primary model exhausts retries.
1941
2107
  *
1942
2108
  * @example ['gpt-4', 'gpt-3.5-turbo']
1943
2109
  */
1944
2110
  fallbacks?: AgentBuilder.Models[];
1945
- /**
1946
- * Cost per 1 million input tokens in USD.
1947
- * Used for cost tracking and reporting in logs.
1948
- */
1949
- inputPrice?: number;
1950
- /**
1951
- * Cost per 1 million output tokens in USD.
1952
- * Used for cost tracking and reporting in logs.
1953
- */
1954
- outputPrice?: number;
1955
- /**
1956
- * Cost per 1 million cached input tokens in USD.
1957
- * Some providers offer reduced pricing for cached/repeated prompts.
1958
- */
1959
- cachedPrice?: number;
1960
- /**
1961
- * Model capabilities - features this model supports.
1962
- */
1963
- capabilities?: {
1964
- /**
1965
- * Whether the model supports vision (image understanding).
1966
- * When true, image attachments will be sent to the model as part of the request.
1967
- * Models like GPT-4o, Claude 3, and Gemini support vision.
1968
- */
1969
- vision?: boolean;
1970
- /**
1971
- * Whether the model supports function calling (tool use).
1972
- * Most modern models support this, defaults to true if not specified.
1973
- */
1974
- functionCalling?: boolean;
1975
- /**
1976
- * Whether the model supports structured outputs (JSON mode).
1977
- */
1978
- structuredOutputs?: boolean;
1979
- };
1980
2111
  }
1981
- /**
1982
- * Defines an LLM model configuration.
1983
- *
1984
- * Models are the foundation of the agent system - they specify which
1985
- * AI model to use and how to connect to it. Models can have fallbacks
1986
- * for reliability and include pricing for cost tracking.
1987
- *
1988
- * @template N - The model name as a string literal type
1989
- * @param options - Model configuration options
1990
- * @returns The model definition for registration
1991
- *
1992
- * @example
1993
- * ```typescript
1994
- * // agentbuilder/models/gpt_4o.ts
1995
- * import { defineModel } from '@standardagents/builder';
1996
- *
1997
- * export default defineModel({
1998
- * name: 'gpt-4o',
1999
- * provider: 'openai',
2000
- * model: 'gpt-4o',
2001
- * fallbacks: ['gpt-4-turbo'],
2002
- * inputPrice: 2.5,
2003
- * outputPrice: 10,
2004
- * });
2005
- * ```
2006
- *
2007
- * @example
2008
- * ```typescript
2009
- * // Using OpenRouter with provider preferences
2010
- * export default defineModel({
2011
- * name: 'claude-3-opus',
2012
- * provider: 'openrouter',
2013
- * model: 'anthropic/claude-3-opus',
2014
- * includedProviders: ['anthropic'],
2015
- * });
2016
- * ```
2017
- */
2018
- declare function defineModel<N extends string>(options: ModelDefinition<N>): ModelDefinition<N>;
2019
2112
 
2020
2113
  /**
2021
2114
  * Prompt definition module for AgentBuilder.
2022
2115
  *
2023
- * Prompts define LLM interaction configurations including the system prompt,
2024
- * model selection, available tools, and various behavioral options.
2116
+ * This module re-exports prompt types from @standardagents/spec and provides
2117
+ * builder-specific versions that use the generated AgentBuilder namespace types.
2025
2118
  *
2026
2119
  * @module
2027
2120
  */
2028
2121
 
2029
2122
  /**
2030
- * A text part of a prompt - static text content.
2031
- *
2032
- * @example
2033
- * ```typescript
2034
- * { type: 'text', content: 'You are a helpful assistant.\n\n' }
2035
- * ```
2036
- */
2037
- interface PromptTextPart {
2038
- type: 'text';
2039
- /** The text content */
2040
- content: string;
2041
- }
2042
- /**
2043
- * A prompt inclusion part - includes another prompt's content.
2044
- * Uses AgentBuilder.Prompts for type-safe autocomplete of prompt names.
2045
- *
2046
- * @example
2047
- * ```typescript
2048
- * { type: 'include', prompt: 'responder_rules' }
2049
- * ```
2123
+ * A prompt inclusion part with type-safe autocomplete.
2124
+ * Uses AgentBuilder.Prompts for type-safe prompt name references.
2050
2125
  */
2051
2126
  interface PromptIncludePart {
2052
2127
  type: 'include';
@@ -2055,448 +2130,107 @@ interface PromptIncludePart {
2055
2130
  }
2056
2131
  /**
2057
2132
  * A single part of a structured prompt.
2058
- * Discriminated union on `type` field for TypeScript narrowing.
2059
2133
  */
2060
2134
  type PromptPart = PromptTextPart | PromptIncludePart;
2061
2135
  /**
2062
- * A structured prompt is an array of prompt parts.
2063
- * Provides type-safe composition with other prompts via autocomplete.
2064
- *
2065
- * @example
2066
- * ```typescript
2067
- * prompt: [
2068
- * { type: 'text', content: 'You are a helpful assistant.\n\n' },
2069
- * { type: 'include', prompt: 'common_rules' },
2070
- * { type: 'text', content: '\n\nBe concise.' },
2071
- * ]
2072
- * ```
2136
+ * Prompt content can be a string or structured array with type-safe includes.
2073
2137
  */
2074
- type StructuredPrompt = PromptPart[];
2138
+ type PromptContent = string | PromptPart[];
2075
2139
  /**
2076
- * The prompt content can be either a plain string or a structured array.
2077
- *
2078
- * @example
2079
- * ```typescript
2080
- * // Simple string prompt:
2081
- * prompt: 'You are a helpful assistant.'
2082
- *
2083
- * // Structured prompt with includes:
2084
- * prompt: [
2085
- * { type: 'text', content: 'You are a helpful assistant.\n\n' },
2086
- * { type: 'include', prompt: 'common_rules' },
2087
- * ]
2088
- * ```
2140
+ * Sub-prompt configuration with type-safe name references.
2089
2141
  */
2090
- type PromptContent = string | StructuredPrompt;
2091
- /**
2092
- * Tool configuration for including a tool in a prompt.
2093
- *
2094
- * @template T - The tool name type (for type-safe tool references)
2095
- */
2096
- interface ToolConfig<T extends string = AgentBuilder.Callables> {
2097
- /**
2098
- * Name of the tool to include.
2099
- * Must be a tool, prompt, or agent defined in agentbuilder/.
2100
- */
2142
+ interface SubpromptConfig<T extends string = AgentBuilder.Callables> extends Omit<SubpromptConfig$2<T>, 'name'> {
2143
+ /** Name of the sub-prompt (type-safe with autocomplete) */
2101
2144
  name: T;
2102
- /**
2103
- * Include text response content from sub-prompt execution in the tool result.
2104
- * @default true
2105
- */
2106
- includeTextResponse?: boolean;
2107
- /**
2108
- * Include tool call details from sub-prompt execution in the tool result.
2109
- * @default true
2110
- */
2111
- includeToolCalls?: boolean;
2112
- /**
2113
- * Include error details from sub-prompt execution in the tool result.
2114
- * @default true
2115
- */
2116
- includeErrors?: boolean;
2117
- /**
2118
- * Property from the tool call arguments to use as the initial user message
2119
- * when this tool triggers a sub-prompt execution.
2120
- *
2121
- * @example
2122
- * If the tool is called with `{ query: "search term", limit: 10 }` and
2123
- * `initUserMessageProperty: 'query'`, the sub-prompt will receive
2124
- * "search term" as the initial user message.
2125
- */
2126
- initUserMessageProperty?: string;
2127
2145
  }
2128
2146
  /**
2129
- * Reasoning configuration for models that support extended thinking.
2130
- * Applies to models like OpenAI o1, Anthropic Claude with extended thinking,
2131
- * Google Gemini with thinking, and Qwen with reasoning.
2147
+ * @deprecated Use SubpromptConfig instead
2132
2148
  */
2133
- interface ReasoningConfig {
2134
- /**
2135
- * Effort level for reasoning models.
2136
- * Higher effort = more thinking tokens = potentially better results.
2137
- *
2138
- * - `low`: Minimal reasoning, faster responses
2139
- * - `medium`: Balanced reasoning and speed
2140
- * - `high`: Maximum reasoning, slower but more thorough
2141
- *
2142
- * @default undefined (use model defaults)
2143
- */
2144
- effort?: 'low' | 'medium' | 'high';
2145
- /**
2146
- * Maximum tokens to allocate for reasoning.
2147
- * Applies to models that support token limits on reasoning
2148
- * (Anthropic, Gemini, Qwen).
2149
- */
2150
- maxTokens?: number;
2151
- /**
2152
- * Use reasoning internally but exclude from the response.
2153
- * Model thinks through the problem but only returns the final answer.
2154
- * Useful for cleaner outputs while maintaining reasoning quality.
2155
- */
2156
- exclude?: boolean;
2157
- /**
2158
- * Include reasoning content in the message history for multi-turn context.
2159
- * When true, reasoning is preserved and visible to subsequent turns.
2160
- * @default false
2161
- */
2162
- include?: boolean;
2163
- }
2149
+ type ToolConfig<T extends string = AgentBuilder.Callables> = SubpromptConfig<T>;
2150
+
2164
2151
  /**
2165
- * Prompt definition configuration.
2152
+ * Prompt definition configuration with AgentBuilder-specific typing.
2153
+ *
2154
+ * Provides type-safe references to models, tools, and agents via the
2155
+ * generated AgentBuilder namespace.
2166
2156
  *
2167
2157
  * @template N - The prompt name as a string literal type
2168
2158
  * @template S - The Zod schema type for requiredSchema (inferred automatically)
2169
- *
2170
- * @example
2171
- * ```typescript
2172
- * import { definePrompt } from '@standardagents/builder';
2173
- * import { z } from 'zod';
2174
- *
2175
- * export default definePrompt({
2176
- * name: 'customer_support',
2177
- * toolDescription: 'Handle customer support inquiries',
2178
- * model: 'gpt-4o',
2179
- * // Simple string prompt:
2180
- * prompt: `You are a helpful customer support agent.
2181
- * Always be polite and try to resolve issues quickly.`,
2182
- * // Or structured prompt with type-safe includes:
2183
- * // prompt: [
2184
- * // { type: 'text', content: 'You are a helpful customer support agent.\n\n' },
2185
- * // { type: 'include', prompt: 'common_rules' },
2186
- * // ],
2187
- * tools: ['search_knowledge_base', 'create_ticket'],
2188
- * requiredSchema: z.object({
2189
- * query: z.string().describe('The customer inquiry'),
2190
- * }),
2191
- * });
2192
- * ```
2193
2159
  */
2194
- interface PromptDefinition<N extends string = string, S extends z.ZodTypeAny = z.ZodTypeAny> {
2195
- /**
2196
- * Unique name for this prompt.
2197
- * Used as the identifier when referencing from agents or as a tool.
2198
- * Should be snake_case (e.g., 'customer_support', 'data_analyst').
2199
- */
2160
+ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolArgs> {
2161
+ /** Unique name for this prompt. */
2200
2162
  name: N;
2201
- /**
2202
- * Description shown when this prompt is exposed as a tool.
2203
- * Should clearly describe what this prompt does for LLM tool selection.
2204
- */
2163
+ /** Description shown when this prompt is exposed as a tool. */
2205
2164
  toolDescription: string;
2206
- /**
2207
- * The system prompt content sent to the LLM.
2208
- *
2209
- * Can be either:
2210
- * 1. A plain string - simple prompt text
2211
- * 2. A structured array - for composing prompts with type-safe includes
2212
- *
2213
- * @example
2214
- * ```typescript
2215
- * // Simple string prompt:
2216
- * prompt: 'You are a helpful assistant.'
2217
- *
2218
- * // Structured prompt with type-safe includes:
2219
- * prompt: [
2220
- * { type: 'text', content: 'You are a helpful assistant.\n\n' },
2221
- * { type: 'include', prompt: 'common_rules' }, // autocomplete for prompt names!
2222
- * { type: 'text', content: '\n\nBe concise.' },
2223
- * ]
2224
- * ```
2225
- */
2165
+ /** The system prompt content with type-safe includes. */
2226
2166
  prompt: PromptContent;
2227
- /**
2228
- * Model to use for this prompt.
2229
- * Must reference a model defined in agentbuilder/models/.
2230
- * Provides autocomplete when types are generated.
2231
- */
2167
+ /** Model to use (type-safe with autocomplete). */
2232
2168
  model: AgentBuilder.Models;
2233
2169
  /**
2234
2170
  * @deprecated All prompts are now automatically exposed as tools.
2235
- * This property is ignored and will be removed in a future version.
2236
2171
  */
2237
2172
  exposeAsTool?: boolean;
2238
- /**
2239
- * Include full chat history in the LLM context.
2240
- * When true, all previous messages in the conversation are included.
2241
- * @default false
2242
- */
2173
+ /** Include full chat history in the LLM context. @default false */
2243
2174
  includeChat?: boolean;
2244
- /**
2245
- * Include results from past tool calls in the LLM context.
2246
- * When true, previous tool call results are visible to the LLM.
2247
- * @default false
2248
- */
2175
+ /** Include results from past tool calls. @default false */
2249
2176
  includePastTools?: boolean;
2250
- /**
2251
- * Allow parallel execution of multiple tool calls.
2252
- * When true, if the LLM requests multiple tools, they execute concurrently.
2253
- * @default false
2254
- */
2177
+ /** Allow parallel execution of multiple tool calls. @default false */
2255
2178
  parallelToolCalls?: boolean;
2256
- /**
2257
- * Tool calling strategy for the LLM.
2258
- *
2259
- * - `auto`: Model decides when to call tools (default)
2260
- * - `none`: Disable tool calling entirely
2261
- * - `required`: Force the model to call at least one tool
2262
- *
2263
- * @default 'auto'
2264
- */
2179
+ /** Tool calling strategy. @default 'auto' */
2265
2180
  toolChoice?: 'auto' | 'none' | 'required';
2266
- /**
2267
- * Zod schema for validating inputs when this prompt is called as a tool.
2268
- *
2269
- * The schema provides:
2270
- * - Runtime validation of tool call arguments
2271
- * - Type inference for the prompt's input type
2272
- * - Auto-generated JSON Schema for LLM tool definitions
2273
- *
2274
- * Use `.describe()` on schema fields to provide descriptions for the LLM.
2275
- *
2276
- * @example
2277
- * ```typescript
2278
- * requiredSchema: z.object({
2279
- * query: z.string().describe('The search query'),
2280
- * limit: z.number().optional().default(10).describe('Max results'),
2281
- * })
2282
- * ```
2283
- */
2181
+ /** Zod schema for validating inputs when called as a tool. */
2284
2182
  requiredSchema?: S;
2285
- /**
2286
- * Tools available to this prompt.
2287
- * Can be simple tool names or detailed configurations.
2288
- *
2289
- * Tools can be:
2290
- * - Custom tools defined in agentbuilder/tools/
2291
- * - Other prompts with exposeAsTool: true
2292
- * - Agents with exposeAsTool: true
2293
- *
2294
- * @example
2295
- * ```typescript
2296
- * tools: [
2297
- * 'search_docs', // Simple reference
2298
- * { name: 'create_ticket', includeErrors: false }, // With config
2299
- * ]
2300
- * ```
2301
- */
2302
- tools?: (AgentBuilder.Callables | ToolConfig)[];
2303
- /**
2304
- * Agents that can receive handoffs from this prompt.
2305
- * Enables multi-agent workflows where this prompt can transfer
2306
- * the conversation to a specialized agent.
2307
- */
2308
- handoffAgents?: AgentBuilder.Agents[];
2309
- /**
2310
- * Tool to execute before the LLM request.
2311
- * Useful for data fetching, context preparation, or preprocessing.
2312
- * The tool result is available in the prompt context.
2313
- */
2314
- beforeTool?: AgentBuilder.Callables;
2315
- /**
2316
- * Tool to execute after the LLM response.
2317
- * Useful for post-processing, logging, or side effects.
2318
- */
2319
- afterTool?: AgentBuilder.Callables;
2320
- /**
2321
- * Reasoning configuration for models that support extended thinking.
2322
- * Configure effort level, token limits, and visibility of reasoning.
2323
- */
2183
+ /** Tools available to this prompt (type-safe with autocomplete). To enable handoffs, include ai_human agent names. */
2184
+ tools?: (AgentBuilder.Callables | SubpromptConfig)[];
2185
+ /** Reasoning configuration for extended thinking models. */
2324
2186
  reasoning?: ReasoningConfig;
2325
- /**
2326
- * Maximum pixels for image attachments before client-side resize.
2327
- * Images exceeding this limit are scaled down while preserving aspect ratio.
2328
- * Images smaller than this limit are not resized up.
2329
- *
2330
- * Common values:
2331
- * - 262144 (256K): 512x512 equivalent - thumbnails, low cost
2332
- * - 1048576 (1M): 1024x1024 equivalent - good quality (default)
2333
- * - 2073600 (2M): 1440x1440 equivalent - high quality
2334
- * - 4194304 (4M): 2048x2048 equivalent - maximum detail
2335
- *
2336
- * @default 1048576 (1M pixels, ~1024x1024)
2337
- *
2338
- * @example
2339
- * ```typescript
2340
- * // High quality images for detailed analysis
2341
- * maxImagePixels: 2073600
2342
- *
2343
- * // Lower quality for cost-sensitive applications
2344
- * maxImagePixels: 262144
2345
- * ```
2346
- */
2347
- maxImagePixels?: number;
2348
- /**
2349
- * Number of recent messages to keep actual images for in context.
2350
- * Messages older than this threshold will have their images replaced
2351
- * with text descriptions to save context window space.
2352
- *
2353
- * This helps manage context window usage in long conversations with
2354
- * many image attachments by summarizing older images.
2355
- *
2356
- * @default 10
2357
- *
2358
- * @example
2359
- * ```typescript
2360
- * // Keep more images in context for image-heavy workflows
2361
- * recentImageThreshold: 20
2362
- *
2363
- * // Aggressively summarize to save context
2364
- * recentImageThreshold: 5
2365
- * ```
2366
- */
2187
+ /** Number of recent messages to keep actual images for. @default 10 */
2367
2188
  recentImageThreshold?: number;
2368
2189
  }
2369
- /**
2370
- * Helper type to extract the inferred input type from a prompt's Zod schema.
2371
- *
2372
- * @template T - The prompt definition type
2373
- *
2374
- * @example
2375
- * ```typescript
2376
- * const searchPrompt = definePrompt({
2377
- * name: 'search',
2378
- * requiredSchema: z.object({ query: z.string(), limit: z.number() }),
2379
- * // ...
2380
- * });
2381
- *
2382
- * type SearchInput = PromptInput<typeof searchPrompt>;
2383
- * // { query: string; limit: number }
2384
- * ```
2385
- */
2386
- type PromptInput<T extends PromptDefinition<any, any>> = T['requiredSchema'] extends z.ZodTypeAny ? z.infer<T['requiredSchema']> : never;
2387
- /**
2388
- * Defines a prompt configuration for LLM interactions.
2389
- *
2390
- * Prompts are the primary way to configure how agents interact with LLMs.
2391
- * They specify the system prompt, available tools, input validation,
2392
- * and various behavioral options.
2393
- *
2394
- * @template N - The prompt name as a string literal type
2395
- * @template S - The Zod schema type for requiredSchema
2396
- * @param options - Prompt configuration options
2397
- * @returns The prompt definition for registration
2398
- *
2399
- * @example
2400
- * ```typescript
2401
- * // agentbuilder/prompts/customer_support.ts
2402
- * import { definePrompt } from '@standardagents/builder';
2403
- * import { z } from 'zod';
2404
- *
2405
- * export default definePrompt({
2406
- * name: 'customer_support',
2407
- * toolDescription: 'Handle customer support inquiries',
2408
- * model: 'gpt-4o',
2409
- * prompt: `You are a helpful customer support agent.
2410
- * Always be polite and try to resolve issues quickly.
2411
- * If you cannot help, offer to escalate to a human.`,
2412
- * tools: ['search_knowledge_base', 'create_ticket'],
2413
- * handoffAgents: ['escalation_agent'],
2414
- * includeChat: true,
2415
- * exposeAsTool: true,
2416
- * requiredSchema: z.object({
2417
- * query: z.string().describe('The customer inquiry'),
2418
- * }),
2419
- * });
2420
- * ```
2421
- */
2422
- declare function definePrompt<N extends string, S extends z.ZodTypeAny = never>(options: PromptDefinition<N, S>): PromptDefinition<N, S>;
2423
2190
 
2424
2191
  /**
2425
2192
  * Agent definition module for AgentBuilder.
2426
2193
  *
2427
- * Agents orchestrate conversations between AI models (dual_ai) or between
2428
- * AI and human users (ai_human). They define the prompts, stop conditions,
2429
- * and behavioral rules for each side of the conversation.
2194
+ * This module re-exports agent types from @standardagents/spec and provides
2195
+ * builder-specific versions that use the generated AgentBuilder namespace types.
2430
2196
  *
2431
2197
  * @module
2432
2198
  */
2199
+
2433
2200
  /**
2434
- * Agent conversation type.
2435
- *
2436
- * - `ai_human`: AI conversing with a human user (most common)
2437
- * - `dual_ai`: Two AI participants conversing with each other
2438
- */
2439
- type AgentType = 'ai_human' | 'dual_ai';
2440
- /**
2441
- * Configuration for one side of an agent conversation.
2442
- *
2443
- * Each side has a prompt, stop conditions, and turn limits.
2444
- * For `ai_human` agents, only sideA (the AI) needs configuration.
2445
- * For `dual_ai` agents, both sides need configuration.
2201
+ * Side configuration with type-safe autocomplete.
2202
+ * Uses AgentBuilder.Prompts and AgentBuilder.Callables for type-safe references.
2446
2203
  */
2447
- interface SideConfig {
2204
+ interface SideConfig extends Omit<SideConfig$1, 'prompt' | 'stopTool' | 'endSessionTool'> {
2448
2205
  /**
2449
- * Custom label for this side of the conversation.
2450
- * Used in UI and logs for clarity.
2451
- *
2452
- * @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
2453
- */
2454
- label?: string;
2455
- /**
2456
- * The prompt to use for this side.
2457
- * Must reference a prompt defined in agentbuilder/prompts/.
2206
+ * The prompt to use for this side (type-safe with autocomplete).
2207
+ * Must reference a prompt defined in agents/prompts/.
2458
2208
  */
2459
2209
  prompt: AgentBuilder.Prompts;
2460
2210
  /**
2461
- * Stop this side's turn when it returns a text response (no tool calls).
2462
- * When true, the side's turn ends after producing a message without tools.
2463
- * @default true
2464
- */
2465
- stopOnResponse?: boolean;
2466
- /**
2467
- * Stop this side's turn when a specific tool is called.
2211
+ * Stop this side's turn when a specific tool is called (type-safe with autocomplete).
2468
2212
  * Overrides stopOnResponse when the named tool is invoked.
2469
2213
  * Requires stopToolResponseProperty to extract the result.
2470
2214
  */
2471
2215
  stopTool?: AgentBuilder.Callables;
2472
2216
  /**
2473
- * Property to extract from the stop tool's result.
2474
- * Required when stopTool is set.
2475
- * The extracted value is used to determine the conversation outcome.
2476
- */
2477
- stopToolResponseProperty?: string;
2478
- /**
2479
- * Maximum turns for this side before forcing a stop.
2480
- * Safety limit to prevent runaway conversations.
2481
- * A turn is one complete request/response cycle.
2482
- */
2483
- maxTurns?: number;
2484
- /**
2485
- * Tool that ends the entire conversation when called.
2486
- * Different from stopTool - this ends the conversation for both sides,
2217
+ * Tool that ends the entire session when called (type-safe with autocomplete).
2218
+ * Different from stopTool - this ends the session for both sides,
2487
2219
  * not just this side's turn.
2488
2220
  */
2489
- endConversationTool?: AgentBuilder.Callables;
2221
+ endSessionTool?: AgentBuilder.Callables;
2490
2222
  /**
2491
2223
  * Enable manual stop condition handling via hooks.
2492
- * When true, stop conditions are evaluated by custom hook logic
2493
- * instead of the built-in rules.
2224
+ * Builder-specific feature for custom stop logic.
2494
2225
  * @default false
2495
2226
  */
2496
2227
  manualStopCondition?: boolean;
2497
2228
  }
2498
2229
  /**
2499
- * Agent definition configuration.
2230
+ * Agent definition configuration with AgentBuilder-specific typing.
2231
+ *
2232
+ * Provides type-safe references to prompts and tools via the
2233
+ * generated AgentBuilder namespace.
2500
2234
  *
2501
2235
  * @template N - The agent name as a string literal type
2502
2236
  *
@@ -2513,140 +2247,45 @@ interface SideConfig {
2513
2247
  * prompt: 'customer_support',
2514
2248
  * stopOnResponse: true,
2515
2249
  * },
2516
- * tags: ['support', 'tier-1'],
2517
2250
  * });
2518
2251
  * ```
2519
2252
  */
2520
2253
  interface AgentDefinition<N extends string = string> {
2521
- /**
2522
- * Unique name for this agent.
2523
- * Used as the identifier for thread creation and handoffs.
2524
- * Should be snake_case (e.g., 'support_agent', 'research_flow').
2525
- */
2254
+ /** Unique name for this agent. */
2526
2255
  name: N;
2527
2256
  /**
2528
2257
  * Human-readable title for the agent.
2529
- * Optional - if not provided, the name will be used.
2530
2258
  * @deprecated Use name instead. Title will be removed in a future version.
2531
2259
  */
2532
2260
  title?: string;
2533
2261
  /**
2534
2262
  * Agent conversation type.
2535
- *
2536
2263
  * - `ai_human`: AI conversing with a human user (default)
2537
2264
  * - `dual_ai`: Two AI participants conversing
2538
- *
2539
2265
  * @default 'ai_human'
2540
2266
  */
2541
- type?: AgentType;
2267
+ type?: 'ai_human' | 'dual_ai';
2542
2268
  /**
2543
2269
  * Maximum total turns across both sides.
2544
2270
  * Only applies to `dual_ai` agents.
2545
- * Prevents infinite loops in AI-to-AI conversations.
2546
2271
  */
2547
2272
  maxSessionTurns?: number;
2548
- /**
2549
- * Configuration for Side A.
2550
- * For `ai_human`: This is the AI side.
2551
- * For `dual_ai`: This is the first AI participant.
2552
- */
2273
+ /** Configuration for Side A (type-safe with autocomplete). */
2553
2274
  sideA: SideConfig;
2554
- /**
2555
- * Configuration for Side B.
2556
- * For `ai_human`: Optional, the human side doesn't need config.
2557
- * For `dual_ai`: Required, the second AI participant.
2558
- */
2275
+ /** Configuration for Side B (type-safe with autocomplete). */
2559
2276
  sideB?: SideConfig;
2560
2277
  /**
2561
2278
  * Expose this agent as a tool for other prompts.
2562
- * Enables agent composition and handoffs.
2563
- * When true, other prompts can invoke this agent as a tool.
2564
2279
  * @default false
2565
2280
  */
2566
2281
  exposeAsTool?: boolean;
2567
- /**
2568
- * Description shown when agent is used as a tool.
2569
- * Required if exposeAsTool is true.
2570
- * Should clearly describe what this agent does.
2571
- */
2282
+ /** Description shown when agent is used as a tool. */
2572
2283
  toolDescription?: string;
2573
- /**
2574
- * Tags for categorization and filtering.
2575
- * Useful for organizing agents in the UI and filtering in queries.
2576
- *
2577
- * @example ['customer-service', 'tier-1', 'english']
2578
- */
2579
- tags?: string[];
2580
- /**
2581
- * Brief description of what this agent does.
2582
- * Useful for UIs and documentation.
2583
- *
2584
- * @example 'Handles customer support inquiries and resolves issues'
2585
- */
2284
+ /** Brief description of what this agent does. */
2586
2285
  description?: string;
2587
- /**
2588
- * Icon URL or absolute path for the agent.
2589
- * Absolute paths (starting with `/`) are converted to full URLs in API responses.
2590
- *
2591
- * @example 'https://example.com/icon.svg' or '/icons/support.svg'
2592
- */
2286
+ /** Icon URL or absolute path for the agent. */
2593
2287
  icon?: string;
2594
2288
  }
2595
- /**
2596
- * Defines an agent configuration.
2597
- *
2598
- * Agents orchestrate conversations between AI models, or between AI and
2599
- * human users. They use prompts to configure each side of the conversation
2600
- * and define stop conditions to control conversation flow.
2601
- *
2602
- * @template N - The agent name as a string literal type
2603
- * @param options - Agent configuration options
2604
- * @returns The agent definition for registration
2605
- *
2606
- * @example
2607
- * ```typescript
2608
- * // agentbuilder/agents/support_agent.ts
2609
- * import { defineAgent } from '@standardagents/builder';
2610
- *
2611
- * export default defineAgent({
2612
- * name: 'support_agent',
2613
- * title: 'Customer Support Agent',
2614
- * type: 'ai_human',
2615
- * sideA: {
2616
- * label: 'Support',
2617
- * prompt: 'customer_support',
2618
- * stopOnResponse: true,
2619
- * endConversationTool: 'close_ticket',
2620
- * },
2621
- * exposeAsTool: true,
2622
- * toolDescription: 'Hand off to customer support',
2623
- * tags: ['support', 'tier-1'],
2624
- * });
2625
- * ```
2626
- *
2627
- * @example
2628
- * ```typescript
2629
- * // Dual AI agent (two AIs conversing)
2630
- * export default defineAgent({
2631
- * name: 'debate_agent',
2632
- * title: 'AI Debate',
2633
- * type: 'dual_ai',
2634
- * maxSessionTurns: 10,
2635
- * sideA: {
2636
- * label: 'Pro',
2637
- * prompt: 'debate_pro',
2638
- * stopOnResponse: true,
2639
- * },
2640
- * sideB: {
2641
- * label: 'Con',
2642
- * prompt: 'debate_con',
2643
- * stopOnResponse: true,
2644
- * endConversationTool: 'conclude_debate',
2645
- * },
2646
- * });
2647
- * ```
2648
- */
2649
- declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
2650
2289
 
2651
2290
  /**
2652
2291
  * Generate a TypeScript file for a model definition.
@@ -2724,9 +2363,6 @@ interface PromptFileData {
2724
2363
  parallelToolCalls?: boolean;
2725
2364
  toolChoice?: 'auto' | 'none' | 'required';
2726
2365
  tools?: (string | ToolConfigInput)[];
2727
- handoffAgents?: string[];
2728
- beforeTool?: string;
2729
- afterTool?: string;
2730
2366
  reasoning?: {
2731
2367
  effort?: 'low' | 'medium' | 'high';
2732
2368
  maxTokens?: number;
@@ -3811,4 +3447,4 @@ declare class GitHubApiError extends Error {
3811
3447
  constructor(message: string, status: number, details?: unknown);
3812
3448
  }
3813
3449
 
3814
- 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 };
3450
+ 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 };