deepagentsdk 0.11.1 → 0.13.0

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.
Files changed (99) hide show
  1. package/dist/adapters/elements/index.cjs +274 -0
  2. package/dist/adapters/elements/index.cjs.map +1 -0
  3. package/dist/adapters/elements/index.d.cts +122 -0
  4. package/dist/adapters/elements/index.d.mts +122 -0
  5. package/dist/adapters/elements/index.mjs +268 -0
  6. package/dist/adapters/elements/index.mjs.map +1 -0
  7. package/dist/agent-BDM-PIu8.d.mts +1500 -0
  8. package/dist/agent-DToEVxs-.d.cts +1500 -0
  9. package/dist/chunk-C5azi7Hr.cjs +67 -0
  10. package/dist/cli/index.cjs +3162 -0
  11. package/dist/cli/index.cjs.map +1 -0
  12. package/dist/cli/index.d.cts +1 -0
  13. package/dist/cli/index.d.mts +1 -0
  14. package/dist/cli/index.mjs +3120 -0
  15. package/dist/cli/index.mjs.map +1 -0
  16. package/dist/file-saver-BYPKakT4.cjs +3990 -0
  17. package/dist/file-saver-BYPKakT4.cjs.map +1 -0
  18. package/dist/file-saver-Hj5so3dV.mjs +3568 -0
  19. package/dist/file-saver-Hj5so3dV.mjs.map +1 -0
  20. package/dist/index.cjs +1481 -0
  21. package/dist/index.cjs.map +1 -0
  22. package/dist/index.d.cts +1233 -0
  23. package/dist/index.d.mts +1233 -0
  24. package/dist/index.mjs +1381 -0
  25. package/dist/index.mjs.map +1 -0
  26. package/dist/load-BBYEnMwz.mjs +142 -0
  27. package/dist/load-BBYEnMwz.mjs.map +1 -0
  28. package/dist/load-BDxe6Cet.mjs +3 -0
  29. package/dist/load-BrRAKlO6.cjs +163 -0
  30. package/dist/load-BrRAKlO6.cjs.map +1 -0
  31. package/dist/load-DqllBbDc.cjs +4 -0
  32. package/package.json +26 -12
  33. package/src/adapters/elements/index.ts +0 -27
  34. package/src/adapters/elements/messageAdapter.ts +0 -165
  35. package/src/adapters/elements/statusAdapter.ts +0 -39
  36. package/src/adapters/elements/types.ts +0 -97
  37. package/src/adapters/elements/useElementsAdapter.ts +0 -261
  38. package/src/agent.ts +0 -1258
  39. package/src/backends/composite.ts +0 -273
  40. package/src/backends/filesystem.ts +0 -692
  41. package/src/backends/index.ts +0 -22
  42. package/src/backends/local-sandbox.ts +0 -175
  43. package/src/backends/persistent.ts +0 -593
  44. package/src/backends/sandbox.ts +0 -510
  45. package/src/backends/state.ts +0 -244
  46. package/src/backends/utils.ts +0 -287
  47. package/src/checkpointer/file-saver.ts +0 -98
  48. package/src/checkpointer/index.ts +0 -5
  49. package/src/checkpointer/kv-saver.ts +0 -82
  50. package/src/checkpointer/memory-saver.ts +0 -82
  51. package/src/checkpointer/types.ts +0 -125
  52. package/src/cli/components/ApiKeyInput.tsx +0 -300
  53. package/src/cli/components/FilePreview.tsx +0 -237
  54. package/src/cli/components/Input.tsx +0 -277
  55. package/src/cli/components/Message.tsx +0 -93
  56. package/src/cli/components/ModelSelection.tsx +0 -338
  57. package/src/cli/components/SlashMenu.tsx +0 -101
  58. package/src/cli/components/StatusBar.tsx +0 -89
  59. package/src/cli/components/Subagent.tsx +0 -91
  60. package/src/cli/components/TodoList.tsx +0 -133
  61. package/src/cli/components/ToolApproval.tsx +0 -70
  62. package/src/cli/components/ToolCall.tsx +0 -144
  63. package/src/cli/components/ToolCallSummary.tsx +0 -175
  64. package/src/cli/components/Welcome.tsx +0 -75
  65. package/src/cli/components/index.ts +0 -24
  66. package/src/cli/hooks/index.ts +0 -12
  67. package/src/cli/hooks/useAgent.ts +0 -933
  68. package/src/cli/index.tsx +0 -1066
  69. package/src/cli/theme.ts +0 -205
  70. package/src/cli/utils/model-list.ts +0 -365
  71. package/src/constants/errors.ts +0 -29
  72. package/src/constants/limits.ts +0 -195
  73. package/src/index.ts +0 -176
  74. package/src/middleware/agent-memory.ts +0 -330
  75. package/src/prompts.ts +0 -196
  76. package/src/skills/index.ts +0 -2
  77. package/src/skills/load.ts +0 -191
  78. package/src/skills/types.ts +0 -53
  79. package/src/tools/execute.ts +0 -167
  80. package/src/tools/filesystem.ts +0 -418
  81. package/src/tools/index.ts +0 -39
  82. package/src/tools/subagent.ts +0 -443
  83. package/src/tools/todos.ts +0 -101
  84. package/src/tools/web.ts +0 -567
  85. package/src/types/backend.ts +0 -177
  86. package/src/types/core.ts +0 -220
  87. package/src/types/events.ts +0 -430
  88. package/src/types/index.ts +0 -94
  89. package/src/types/structured-output.ts +0 -43
  90. package/src/types/subagent.ts +0 -96
  91. package/src/types.ts +0 -22
  92. package/src/utils/approval.ts +0 -213
  93. package/src/utils/events.ts +0 -416
  94. package/src/utils/eviction.ts +0 -181
  95. package/src/utils/index.ts +0 -34
  96. package/src/utils/model-parser.ts +0 -38
  97. package/src/utils/patch-tool-calls.ts +0 -233
  98. package/src/utils/project-detection.ts +0 -32
  99. package/src/utils/summarization.ts +0 -254
@@ -0,0 +1,1500 @@
1
+ import * as ai2 from "ai";
2
+ import { LanguageModel, LanguageModel as LanguageModel$2, LanguageModelMiddleware, ModelMessage, ModelMessage as ModelMessage$1, StopCondition, ToolLoopAgent, ToolLoopAgentSettings, ToolSet } from "ai";
3
+ import { z } from "zod";
4
+
5
+ //#region src/checkpointer/types.d.ts
6
+
7
+ /**
8
+ * Data stored in a checkpoint.
9
+ * Contains everything needed to resume an agent session.
10
+ */
11
+ interface Checkpoint {
12
+ /** Unique identifier for the conversation thread */
13
+ threadId: string;
14
+ /** Step number when this checkpoint was created */
15
+ step: number;
16
+ /** Conversation history (serialized messages) */
17
+ messages: ModelMessage$1[];
18
+ /** Agent state (todos and StateBackend files) */
19
+ state: DeepAgentState;
20
+ /**
21
+ * Interrupt data if the agent was paused mid-execution.
22
+ * Present when waiting for tool approval.
23
+ */
24
+ interrupt?: InterruptData;
25
+ /** ISO 8601 timestamp when checkpoint was created */
26
+ createdAt: string;
27
+ /** ISO 8601 timestamp when checkpoint was last updated */
28
+ updatedAt: string;
29
+ }
30
+ /**
31
+ * Data about an interrupted tool execution.
32
+ * Used to resume from approval requests.
33
+ */
34
+ interface InterruptData {
35
+ /** The tool call that requires approval */
36
+ toolCall: {
37
+ toolCallId: string;
38
+ toolName: string;
39
+ args: unknown;
40
+ };
41
+ /** Step number where interrupt occurred */
42
+ step: number;
43
+ }
44
+ /**
45
+ * Decision to resume from an interrupt.
46
+ */
47
+ interface ResumeDecision {
48
+ /** Type of decision */
49
+ type: 'approve' | 'deny';
50
+ /** Optional modified arguments (for future "edit" feature) */
51
+ modifiedArgs?: unknown;
52
+ }
53
+ /**
54
+ * Options for resuming from a checkpoint.
55
+ */
56
+ interface ResumeOptions {
57
+ /** Decisions for pending tool approvals */
58
+ decisions: ResumeDecision[];
59
+ }
60
+ /**
61
+ * Interface for checkpoint storage implementations.
62
+ *
63
+ * Implement this interface to use any storage backend (memory, files,
64
+ * Redis, database, etc.) for persisting checkpoints.
65
+ */
66
+ interface BaseCheckpointSaver {
67
+ /**
68
+ * Save a checkpoint.
69
+ * If a checkpoint for the threadId already exists, it is overwritten.
70
+ *
71
+ * @param checkpoint - The checkpoint data to save
72
+ */
73
+ save(checkpoint: Checkpoint): Promise<void>;
74
+ /**
75
+ * Load the latest checkpoint for a thread.
76
+ *
77
+ * @param threadId - The thread identifier
78
+ * @returns The checkpoint, or undefined if not found
79
+ */
80
+ load(threadId: string): Promise<Checkpoint | undefined>;
81
+ /**
82
+ * List all thread IDs with saved checkpoints.
83
+ *
84
+ * @returns Array of thread IDs
85
+ */
86
+ list(): Promise<string[]>;
87
+ /**
88
+ * Delete a checkpoint.
89
+ *
90
+ * @param threadId - The thread identifier to delete
91
+ */
92
+ delete(threadId: string): Promise<void>;
93
+ /**
94
+ * Check if a checkpoint exists for a thread.
95
+ *
96
+ * @param threadId - The thread identifier
97
+ * @returns True if checkpoint exists
98
+ */
99
+ exists(threadId: string): Promise<boolean>;
100
+ }
101
+ /**
102
+ * Options for creating a checkpoint saver.
103
+ */
104
+ interface CheckpointSaverOptions {
105
+ /** Optional namespace prefix for isolation */
106
+ namespace?: string;
107
+ }
108
+ //#endregion
109
+ //#region src/types/backend.d.ts
110
+ /**
111
+ * File data structure used by backends.
112
+ */
113
+ interface FileData {
114
+ /** Lines of text content */
115
+ content: string[];
116
+ /** ISO format timestamp of creation */
117
+ created_at: string;
118
+ /** ISO format timestamp of last modification */
119
+ modified_at: string;
120
+ }
121
+ /**
122
+ * Structured file listing info.
123
+ */
124
+ interface FileInfo {
125
+ /** File path */
126
+ path: string;
127
+ /** Whether this is a directory */
128
+ is_dir?: boolean;
129
+ /** File size in bytes (approximate) */
130
+ size?: number;
131
+ /** ISO 8601 timestamp of last modification */
132
+ modified_at?: string;
133
+ }
134
+ /**
135
+ * Structured grep match entry.
136
+ */
137
+ interface GrepMatch {
138
+ /** File path where match was found */
139
+ path: string;
140
+ /** Line number (1-indexed) */
141
+ line: number;
142
+ /** The matching line text */
143
+ text: string;
144
+ }
145
+ /**
146
+ * Result from backend write operations.
147
+ */
148
+ interface WriteResult {
149
+ /** Whether the write operation succeeded */
150
+ success: boolean;
151
+ /** Error message on failure, undefined on success */
152
+ error?: string;
153
+ /** File path of written file, undefined on failure */
154
+ path?: string;
155
+ }
156
+ /**
157
+ * Result from backend edit operations.
158
+ */
159
+ interface EditResult {
160
+ /** Whether the edit operation succeeded */
161
+ success: boolean;
162
+ /** Error message on failure, undefined on success */
163
+ error?: string;
164
+ /** File path of edited file, undefined on failure */
165
+ path?: string;
166
+ /** Number of replacements made, undefined on failure */
167
+ occurrences?: number;
168
+ }
169
+ /**
170
+ * Shared state for deep agent operations.
171
+ * This is passed to tools and modified during execution.
172
+ */
173
+ interface DeepAgentState {
174
+ /** Current todo list */
175
+ todos: TodoItem[];
176
+ /** Virtual filesystem (for StateBackend) */
177
+ files: Record<string, FileData>;
178
+ }
179
+ /**
180
+ * Protocol for pluggable memory backends.
181
+ */
182
+ interface BackendProtocol {
183
+ /**
184
+ * Structured listing with file metadata.
185
+ */
186
+ lsInfo(path: string): FileInfo[] | Promise<FileInfo[]>;
187
+ /**
188
+ * Read file content with line numbers or an error string.
189
+ */
190
+ read(filePath: string, offset?: number, limit?: number): string | Promise<string>;
191
+ /**
192
+ * Read file content as raw FileData.
193
+ */
194
+ readRaw(filePath: string): FileData | Promise<FileData>;
195
+ /**
196
+ * Structured search results or error string for invalid input.
197
+ */
198
+ grepRaw(pattern: string, path?: string | null, glob?: string | null): GrepMatch[] | string | Promise<GrepMatch[] | string>;
199
+ /**
200
+ * Structured glob matching returning FileInfo objects.
201
+ */
202
+ globInfo(pattern: string, path?: string): FileInfo[] | Promise<FileInfo[]>;
203
+ /**
204
+ * Create a new file or overwrite existing file.
205
+ */
206
+ write(filePath: string, content: string): WriteResult | Promise<WriteResult>;
207
+ /**
208
+ * Edit a file by replacing string occurrences.
209
+ */
210
+ edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult | Promise<EditResult>;
211
+ }
212
+ /**
213
+ * Factory function type for creating backend instances from agent state.
214
+ */
215
+ type BackendFactory = (state: DeepAgentState) => BackendProtocol;
216
+ /**
217
+ * Result of command execution in a sandbox.
218
+ */
219
+ interface ExecuteResponse {
220
+ /** Combined stdout and stderr output of the executed command */
221
+ output: string;
222
+ /** Exit code (0 = success, non-zero = failure, null = unknown/timeout) */
223
+ exitCode: number | null;
224
+ /** Whether the output was truncated due to size limits */
225
+ truncated: boolean;
226
+ }
227
+ /**
228
+ * Protocol for sandbox backends with command execution capability.
229
+ */
230
+ interface SandboxBackendProtocol extends BackendProtocol {
231
+ /**
232
+ * Execute a shell command in the sandbox.
233
+ */
234
+ execute(command: string): Promise<ExecuteResponse>;
235
+ /**
236
+ * Unique identifier for this sandbox instance.
237
+ */
238
+ readonly id: string;
239
+ }
240
+ /**
241
+ * Type guard to check if a backend is a SandboxBackendProtocol.
242
+ */
243
+ declare function isSandboxBackend(backend: BackendProtocol): backend is SandboxBackendProtocol;
244
+ //#endregion
245
+ //#region src/tools/web.d.ts
246
+ /**
247
+ * Convert HTML to Markdown with article extraction.
248
+ * Uses Mozilla Readability to extract main content, then converts to Markdown.
249
+ */
250
+ declare function htmlToMarkdown(html: string, url: string): string;
251
+ /**
252
+ * Create the web_search tool.
253
+ */
254
+ declare function createWebSearchTool(state: DeepAgentState, options: {
255
+ backend?: BackendProtocol | BackendFactory;
256
+ onEvent?: EventCallback;
257
+ toolResultEvictionLimit?: number;
258
+ tavilyApiKey: string;
259
+ }): ai2.Tool<{
260
+ query: string;
261
+ max_results: number;
262
+ topic: "general" | "news" | "finance";
263
+ include_raw_content: boolean;
264
+ }, string>;
265
+ /**
266
+ * Create the http_request tool.
267
+ */
268
+ declare function createHttpRequestTool(state: DeepAgentState, options: {
269
+ backend?: BackendProtocol | BackendFactory;
270
+ onEvent?: EventCallback;
271
+ toolResultEvictionLimit?: number;
272
+ defaultTimeout: number;
273
+ }): ai2.Tool<{
274
+ timeout: number;
275
+ url: string;
276
+ method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
277
+ headers?: Record<string, string> | undefined;
278
+ params?: Record<string, string> | undefined;
279
+ body?: string | Record<string, any> | undefined;
280
+ }, string>;
281
+ /**
282
+ * Create the fetch_url tool.
283
+ */
284
+ declare function createFetchUrlTool(state: DeepAgentState, options: {
285
+ backend?: BackendProtocol | BackendFactory;
286
+ onEvent?: EventCallback;
287
+ toolResultEvictionLimit?: number;
288
+ defaultTimeout: number;
289
+ }): ai2.Tool<{
290
+ timeout: number;
291
+ url: string;
292
+ extract_article: boolean;
293
+ }, string>;
294
+ /**
295
+ * Options for creating web tools.
296
+ */
297
+ interface CreateWebToolsOptions {
298
+ /** Backend for filesystem operations (for eviction) */
299
+ backend?: BackendProtocol | BackendFactory;
300
+ /** Callback for emitting events */
301
+ onEvent?: EventCallback;
302
+ /** Token limit before evicting large tool results (default: disabled) */
303
+ toolResultEvictionLimit?: number;
304
+ /** Tavily API key (defaults to process.env.TAVILY_API_KEY) */
305
+ tavilyApiKey?: string;
306
+ /** Default timeout for HTTP requests in seconds (default: 30) */
307
+ defaultTimeout?: number;
308
+ }
309
+ /**
310
+ * Create all web tools (web_search, http_request, fetch_url).
311
+ * Tools are only created if TAVILY_API_KEY is available.
312
+ */
313
+ declare function createWebTools(state: DeepAgentState, options?: CreateWebToolsOptions): Record<string, any>;
314
+ /**
315
+ * Individual builtin tool references for selective subagent configuration.
316
+ * These are references to the creator functions, not instances.
317
+ */
318
+ declare const web_search: typeof createWebSearchTool;
319
+ declare const http_request: typeof createHttpRequestTool;
320
+ declare const fetch_url: typeof createFetchUrlTool;
321
+ //#endregion
322
+ //#region src/tools/filesystem.d.ts
323
+ /**
324
+ * Create the ls tool.
325
+ */
326
+ declare function createLsTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
327
+ path: string;
328
+ }, string>;
329
+ /**
330
+ * Create the read_file tool.
331
+ */
332
+ declare function createReadFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
333
+ file_path: string;
334
+ offset: number;
335
+ limit: number;
336
+ }, string>;
337
+ /**
338
+ * Create the write_file tool.
339
+ */
340
+ declare function createWriteFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
341
+ file_path: string;
342
+ content: string;
343
+ }, string>;
344
+ /**
345
+ * Create the edit_file tool.
346
+ */
347
+ declare function createEditFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
348
+ file_path: string;
349
+ old_string: string;
350
+ new_string: string;
351
+ replace_all: boolean;
352
+ }, string>;
353
+ /**
354
+ * Create the glob tool.
355
+ */
356
+ declare function createGlobTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
357
+ path: string;
358
+ pattern: string;
359
+ }, string>;
360
+ /**
361
+ * Create the grep tool.
362
+ */
363
+ declare function createGrepTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
364
+ path: string;
365
+ pattern: string;
366
+ glob?: string | null | undefined;
367
+ }, string>;
368
+ /**
369
+ * Options for creating filesystem tools.
370
+ */
371
+ interface CreateFilesystemToolsOptions {
372
+ /** Backend for filesystem operations */
373
+ backend?: BackendProtocol | BackendFactory;
374
+ /** Callback for emitting events */
375
+ onEvent?: EventCallback;
376
+ /** Token limit before evicting large tool results (default: disabled) */
377
+ toolResultEvictionLimit?: number;
378
+ }
379
+ /**
380
+ * Create all filesystem tools.
381
+ * @param state - The shared agent state
382
+ * @param backendOrOptions - Backend or options object
383
+ * @param onEvent - Optional callback for emitting events (deprecated, use options)
384
+ */
385
+ declare function createFilesystemTools(state: DeepAgentState, backendOrOptions?: BackendProtocol | BackendFactory | CreateFilesystemToolsOptions, onEvent?: EventCallback): {
386
+ ls: ai2.Tool<{
387
+ path: string;
388
+ }, string>;
389
+ read_file: ai2.Tool<{
390
+ file_path: string;
391
+ offset: number;
392
+ limit: number;
393
+ }, string>;
394
+ write_file: ai2.Tool<{
395
+ file_path: string;
396
+ content: string;
397
+ }, string>;
398
+ edit_file: ai2.Tool<{
399
+ file_path: string;
400
+ old_string: string;
401
+ new_string: string;
402
+ replace_all: boolean;
403
+ }, string>;
404
+ glob: ai2.Tool<{
405
+ path: string;
406
+ pattern: string;
407
+ }, string>;
408
+ grep: ai2.Tool<{
409
+ path: string;
410
+ pattern: string;
411
+ glob?: string | null | undefined;
412
+ }, string>;
413
+ };
414
+ /**
415
+ * Individual builtin tool references for selective subagent configuration.
416
+ * These are references to the creator functions, not instances.
417
+ */
418
+ declare const ls: typeof createLsTool;
419
+ declare const read_file: typeof createReadFileTool;
420
+ declare const write_file: typeof createWriteFileTool;
421
+ declare const edit_file: typeof createEditFileTool;
422
+ declare const glob: typeof createGlobTool;
423
+ declare const grep: typeof createGrepTool;
424
+ //#endregion
425
+ //#region src/tools/todos.d.ts
426
+ /**
427
+ * Create the write_todos tool for task planning.
428
+ * @param state - The shared agent state
429
+ * @param onEvent - Optional callback for emitting events
430
+ */
431
+ declare function createTodosTool(state: DeepAgentState, onEvent?: EventCallback): ai2.Tool<{
432
+ todos: {
433
+ status: "pending" | "in_progress" | "completed" | "cancelled";
434
+ id: string;
435
+ content: string;
436
+ }[];
437
+ merge: boolean;
438
+ }, string>;
439
+ /**
440
+ * Individual builtin tool reference for selective subagent configuration.
441
+ * This is a reference to the creator function, not an instance.
442
+ */
443
+ declare const write_todos: typeof createTodosTool;
444
+ //#endregion
445
+ //#region src/tools/execute.d.ts
446
+ /**
447
+ * Options for creating the execute tool.
448
+ */
449
+ interface CreateExecuteToolOptions {
450
+ /** The sandbox backend to execute commands in */
451
+ backend: SandboxBackendProtocol;
452
+ /** Optional callback for emitting events */
453
+ onEvent?: EventCallback;
454
+ /** Optional custom description for the tool */
455
+ description?: string;
456
+ }
457
+ /**
458
+ * Create an execute tool for running shell commands.
459
+ *
460
+ * @param options - Options including the sandbox backend and optional event callback
461
+ * @returns An AI SDK tool that executes shell commands
462
+ *
463
+ * @example Basic usage
464
+ * ```typescript
465
+ * import { LocalSandbox, createExecuteTool } from 'deepagentsdk';
466
+ *
467
+ * const sandbox = new LocalSandbox({ cwd: './workspace' });
468
+ * const executeTool = createExecuteTool({ backend: sandbox });
469
+ *
470
+ * // Use with agent
471
+ * const agent = createDeepAgent({
472
+ * model: anthropic('claude-sonnet-4-20250514'),
473
+ * backend: sandbox,
474
+ * tools: { execute: executeTool },
475
+ * });
476
+ * ```
477
+ *
478
+ * @example With event streaming
479
+ * ```typescript
480
+ * const executeTool = createExecuteTool({
481
+ * backend: sandbox,
482
+ * onEvent: (event) => {
483
+ * if (event.type === 'execute-start') {
484
+ * console.log(`Running: ${event.command}`);
485
+ * } else if (event.type === 'execute-finish') {
486
+ * console.log(`Exit code: ${event.exitCode}`);
487
+ * }
488
+ * },
489
+ * });
490
+ * ```
491
+ */
492
+ declare function createExecuteTool(options: CreateExecuteToolOptions): ai2.Tool<{
493
+ command: string;
494
+ }, string>;
495
+ /**
496
+ * Convenience function to create execute tool from just a backend.
497
+ * Useful for simple cases without event handling.
498
+ *
499
+ * @param backend - The sandbox backend
500
+ * @returns An AI SDK tool that executes shell commands
501
+ *
502
+ * @example
503
+ * ```typescript
504
+ * const sandbox = new LocalSandbox({ cwd: './workspace' });
505
+ * const tools = {
506
+ * execute: createExecuteToolFromBackend(sandbox),
507
+ * };
508
+ * ```
509
+ */
510
+ declare function createExecuteToolFromBackend(backend: SandboxBackendProtocol): ai2.Tool<{
511
+ command: string;
512
+ }, string>;
513
+ /**
514
+ * Individual builtin tool reference for selective subagent configuration.
515
+ * This is a reference to the creator function, not an instance.
516
+ */
517
+ declare const execute: typeof createExecuteTool;
518
+ //#endregion
519
+ //#region src/types/subagent.d.ts
520
+ /**
521
+ * Configuration for dynamic tool approval.
522
+ */
523
+ interface DynamicApprovalConfig {
524
+ /**
525
+ * Function to determine if approval is needed based on tool arguments.
526
+ */
527
+ shouldApprove?: (args: unknown) => boolean | Promise<boolean>;
528
+ }
529
+ /**
530
+ * Configuration for human-in-the-loop tool approval.
531
+ */
532
+ type InterruptOnConfig = Record<string, boolean | DynamicApprovalConfig>;
533
+ /**
534
+ * Type for builtin tool creator functions.
535
+ */
536
+ type BuiltinToolCreator = typeof createWebSearchTool | typeof createHttpRequestTool | typeof createFetchUrlTool | typeof createLsTool | typeof createReadFileTool | typeof createWriteFileTool | typeof createEditFileTool | typeof createGlobTool | typeof createGrepTool | typeof createTodosTool | typeof createExecuteTool;
537
+ /**
538
+ * Union type for subagent tool configuration.
539
+ */
540
+ type SubagentToolConfig = ToolSet | BuiltinToolCreator;
541
+ /**
542
+ * SubAgent specification for task delegation.
543
+ */
544
+ interface SubAgent {
545
+ /**
546
+ * Unique name identifier for the subagent.
547
+ */
548
+ name: string;
549
+ /**
550
+ * Description shown to the main agent when deciding which subagent to use.
551
+ */
552
+ description: string;
553
+ /**
554
+ * System prompt that defines the subagent's behavior and instructions.
555
+ */
556
+ systemPrompt: string;
557
+ /**
558
+ * Optional custom tools available only to this subagent.
559
+ */
560
+ tools?: ToolSet | SubagentToolConfig[];
561
+ /**
562
+ * Optional model override for this subagent.
563
+ */
564
+ model?: LanguageModel;
565
+ /**
566
+ * Optional interrupt configuration for this subagent.
567
+ */
568
+ interruptOn?: InterruptOnConfig;
569
+ /**
570
+ * Optional structured output configuration for this subagent.
571
+ */
572
+ output?: {
573
+ schema: z.ZodType<any>;
574
+ description?: string;
575
+ };
576
+ /**
577
+ * Advanced generation options for this subagent.
578
+ */
579
+ generationOptions?: GenerationOptions;
580
+ /**
581
+ * Advanced agent options for this subagent.
582
+ */
583
+ advancedOptions?: AdvancedAgentOptions;
584
+ }
585
+ //#endregion
586
+ //#region src/types/core.d.ts
587
+ /**
588
+ * Configuration options for agent memory middleware.
589
+ */
590
+ interface AgentMemoryOptions {
591
+ /**
592
+ * Unique identifier for the agent (e.g., "code-architect", "research-agent").
593
+ * Used to locate agent-specific memory at ~/.deepagents/{agentId}/agent.md
594
+ */
595
+ agentId: string;
596
+ /**
597
+ * Optional working directory for project-level memory detection.
598
+ * Defaults to process.cwd().
599
+ */
600
+ workingDirectory?: string;
601
+ /**
602
+ * Optional custom path for user-level .deepagents directory.
603
+ * Defaults to os.homedir() + '/.deepagents'.
604
+ */
605
+ userDeepagentsDir?: string;
606
+ /**
607
+ * Optional callback to request user approval for creating project-level .deepagents/ directory.
608
+ */
609
+ requestProjectApproval?: (projectPath: string) => Promise<boolean>;
610
+ }
611
+ /**
612
+ * Todo item for task planning and tracking.
613
+ */
614
+ interface TodoItem {
615
+ /** Unique identifier for the todo */
616
+ id: string;
617
+ /** Description of the task */
618
+ content: string;
619
+ /** Current status */
620
+ status: "pending" | "in_progress" | "completed" | "cancelled";
621
+ }
622
+ /**
623
+ * Tool choice type for prepareStep.
624
+ */
625
+ type DeepAgentToolChoice = "auto" | "none" | "required" | {
626
+ type: "tool";
627
+ toolName: string;
628
+ };
629
+ /**
630
+ * Result from prepareStep callback.
631
+ */
632
+ interface PrepareStepResult {
633
+ toolChoice?: DeepAgentToolChoice;
634
+ model?: LanguageModel$2;
635
+ [key: string]: unknown;
636
+ }
637
+ /**
638
+ * Arguments passed to prepareStep callback.
639
+ */
640
+ interface PrepareStepArgs {
641
+ stepNumber: number;
642
+ steps: unknown[];
643
+ model: LanguageModel$2;
644
+ messages: ai2.ModelMessage[];
645
+ experimental_context?: unknown;
646
+ }
647
+ /**
648
+ * Prepare step function type with permissive tool choice typing.
649
+ */
650
+ type PrepareStepFunction = (args: PrepareStepArgs) => PrepareStepResult | PromiseLike<PrepareStepResult>;
651
+ /**
652
+ * Loop control callbacks for agent iteration.
653
+ */
654
+ interface LoopControlOptions {
655
+ /**
656
+ * Called before each step to dynamically adjust settings.
657
+ */
658
+ prepareStep?: PrepareStepFunction;
659
+ /**
660
+ * Called after each step finishes.
661
+ */
662
+ onStepFinish?: ToolLoopAgentSettings["onStepFinish"];
663
+ /**
664
+ * Called when all steps are finished.
665
+ */
666
+ onFinish?: ToolLoopAgentSettings["onFinish"];
667
+ /**
668
+ * Custom stop conditions (composed with maxSteps safety limit).
669
+ */
670
+ stopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
671
+ }
672
+ /**
673
+ * Sampling and generation parameters for model calls.
674
+ */
675
+ interface GenerationOptions {
676
+ /** Sampling temperature (0-2). */
677
+ temperature?: number;
678
+ /** Nucleus sampling (0-1). */
679
+ topP?: number;
680
+ /** Top-K sampling. */
681
+ topK?: number;
682
+ /** Maximum number of tokens to generate per response. */
683
+ maxOutputTokens?: number;
684
+ /** Presence penalty (-1 to 1). */
685
+ presencePenalty?: number;
686
+ /** Frequency penalty (-1 to 1). */
687
+ frequencyPenalty?: number;
688
+ /** Random seed for deterministic generation. */
689
+ seed?: number;
690
+ /** Sequences that stop generation when encountered. */
691
+ stopSequences?: string[];
692
+ /** Maximum number of retries for failed API calls. */
693
+ maxRetries?: number;
694
+ }
695
+ /**
696
+ * Advanced options for power users.
697
+ */
698
+ interface AdvancedAgentOptions {
699
+ /** OpenTelemetry configuration for observability. */
700
+ experimental_telemetry?: ToolLoopAgentSettings["experimental_telemetry"];
701
+ /** Provider-specific options passed through to the model provider. */
702
+ providerOptions?: ToolLoopAgentSettings["providerOptions"];
703
+ /** Custom context passed to tool executions. */
704
+ experimental_context?: ToolLoopAgentSettings["experimental_context"];
705
+ /** Control which tool the model should call. */
706
+ toolChoice?: ToolLoopAgentSettings["toolChoice"];
707
+ /** Limit which tools are available for the model to call. */
708
+ activeTools?: string[];
709
+ }
710
+ /**
711
+ * Summarization configuration options.
712
+ */
713
+ interface SummarizationConfig {
714
+ /** Enable automatic summarization when approaching token limits. */
715
+ enabled: boolean;
716
+ /** Token threshold to trigger summarization (default: 170000). */
717
+ tokenThreshold?: number;
718
+ /** Number of recent messages to keep intact without summarization (default: 6). */
719
+ keepMessages?: number;
720
+ /** Model to use for summarization. */
721
+ model?: LanguageModel$2;
722
+ }
723
+ /**
724
+ * Configuration parameters for creating a Deep Agent.
725
+ */
726
+ interface CreateDeepAgentParams {
727
+ /** The AI SDK LanguageModel instance to use. */
728
+ model: LanguageModel$2;
729
+ /** Optional middleware to wrap the model. */
730
+ middleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
731
+ /** Optional custom tools the agent should have access to. */
732
+ tools?: ToolSet;
733
+ /** Optional custom system prompt for the agent. */
734
+ systemPrompt?: string;
735
+ /** Optional list of subagent specifications for task delegation. */
736
+ subagents?: SubAgent[];
737
+ /** Optional backend for filesystem operations. */
738
+ backend?: BackendProtocol | BackendFactory;
739
+ /** Optional maximum number of steps for the agent loop (default: 100). */
740
+ maxSteps?: number;
741
+ /** Optional flag to include the general-purpose subagent (default: true). */
742
+ includeGeneralPurposeAgent?: boolean;
743
+ /** Optional token limit before evicting large tool results to filesystem. */
744
+ toolResultEvictionLimit?: number;
745
+ /** Optional flag to enable prompt caching (Anthropic only). */
746
+ enablePromptCaching?: boolean;
747
+ /** Optional summarization configuration. */
748
+ summarization?: SummarizationConfig;
749
+ /** Configuration for human-in-the-loop tool approval. */
750
+ interruptOn?: InterruptOnConfig;
751
+ /** Optional checkpointer for persisting agent state. */
752
+ checkpointer?: BaseCheckpointSaver;
753
+ /** @deprecated Use `agentId` instead. */
754
+ skillsDir?: string;
755
+ /** Optional agent identifier for loading agent-specific memory and skills. */
756
+ agentId?: string;
757
+ /** Optional configuration for structured output parsing. */
758
+ output?: {
759
+ schema: z.ZodType<any>;
760
+ description?: string;
761
+ };
762
+ /** Advanced loop control options. */
763
+ loopControl?: LoopControlOptions;
764
+ /** Advanced generation options. */
765
+ generationOptions?: GenerationOptions;
766
+ /** Advanced agent options. */
767
+ advancedOptions?: AdvancedAgentOptions;
768
+ }
769
+ //#endregion
770
+ //#region src/types/events.d.ts
771
+ /**
772
+ * Event emitted when text is streamed from the agent.
773
+ */
774
+ interface TextEvent {
775
+ type: "text";
776
+ text: string;
777
+ }
778
+ /**
779
+ * Event emitted when a step starts.
780
+ */
781
+ interface StepStartEvent {
782
+ type: "step-start";
783
+ stepNumber: number;
784
+ }
785
+ /**
786
+ * Event emitted when a step finishes.
787
+ */
788
+ interface StepFinishEvent {
789
+ type: "step-finish";
790
+ stepNumber: number;
791
+ toolCalls: Array<{
792
+ toolName: string;
793
+ args: unknown;
794
+ result: unknown;
795
+ }>;
796
+ }
797
+ /**
798
+ * Event emitted when a tool is called.
799
+ */
800
+ interface ToolCallEvent {
801
+ type: "tool-call";
802
+ toolName: string;
803
+ toolCallId: string;
804
+ args: unknown;
805
+ }
806
+ /**
807
+ * Event emitted when a tool returns a result.
808
+ */
809
+ interface ToolResultEvent {
810
+ type: "tool-result";
811
+ toolName: string;
812
+ toolCallId: string;
813
+ result: unknown;
814
+ isError?: boolean;
815
+ }
816
+ /**
817
+ * Event emitted when the todo list changes.
818
+ */
819
+ interface TodosChangedEvent {
820
+ type: "todos-changed";
821
+ todos: TodoItem[];
822
+ }
823
+ /**
824
+ * Event emitted when a file write starts (for preview).
825
+ */
826
+ interface FileWriteStartEvent {
827
+ type: "file-write-start";
828
+ path: string;
829
+ content: string;
830
+ }
831
+ /**
832
+ * Event emitted when a file is written.
833
+ */
834
+ interface FileWrittenEvent {
835
+ type: "file-written";
836
+ path: string;
837
+ content: string;
838
+ }
839
+ /**
840
+ * Event emitted when a file is edited.
841
+ */
842
+ interface FileEditedEvent {
843
+ type: "file-edited";
844
+ path: string;
845
+ occurrences: number;
846
+ }
847
+ /**
848
+ * Event emitted when a file is read.
849
+ */
850
+ interface FileReadEvent {
851
+ type: "file-read";
852
+ path: string;
853
+ /** Number of lines read */
854
+ lines: number;
855
+ }
856
+ /**
857
+ * Event emitted when listing directory contents.
858
+ */
859
+ interface LsEvent {
860
+ type: "ls";
861
+ path: string;
862
+ /** Number of items found */
863
+ count: number;
864
+ }
865
+ /**
866
+ * Event emitted when searching with glob pattern.
867
+ */
868
+ interface GlobEvent {
869
+ type: "glob";
870
+ pattern: string;
871
+ /** Number of files found */
872
+ count: number;
873
+ }
874
+ /**
875
+ * Event emitted when searching with grep.
876
+ */
877
+ interface GrepEvent {
878
+ type: "grep";
879
+ pattern: string;
880
+ /** Number of matches found */
881
+ count: number;
882
+ }
883
+ /**
884
+ * Event emitted when a command execution starts.
885
+ */
886
+ interface ExecuteStartEvent {
887
+ type: "execute-start";
888
+ /** The command being executed */
889
+ command: string;
890
+ /** The sandbox ID where the command is running */
891
+ sandboxId: string;
892
+ }
893
+ /**
894
+ * Event emitted when a command execution finishes.
895
+ */
896
+ interface ExecuteFinishEvent {
897
+ type: "execute-finish";
898
+ /** The command that was executed */
899
+ command: string;
900
+ /** Exit code (0 = success, non-zero = failure, null = unknown/timeout) */
901
+ exitCode: number | null;
902
+ /** Whether the output was truncated */
903
+ truncated: boolean;
904
+ /** The sandbox ID where the command ran */
905
+ sandboxId: string;
906
+ }
907
+ /**
908
+ * Event emitted when a web search starts.
909
+ */
910
+ interface WebSearchStartEvent {
911
+ type: "web-search-start";
912
+ /** The search query */
913
+ query: string;
914
+ }
915
+ /**
916
+ * Event emitted when a web search finishes.
917
+ */
918
+ interface WebSearchFinishEvent {
919
+ type: "web-search-finish";
920
+ /** The search query */
921
+ query: string;
922
+ /** Number of results returned */
923
+ resultCount: number;
924
+ }
925
+ /**
926
+ * Event emitted when an HTTP request starts.
927
+ */
928
+ interface HttpRequestStartEvent {
929
+ type: "http-request-start";
930
+ /** The request URL */
931
+ url: string;
932
+ /** HTTP method (GET, POST, etc.) */
933
+ method: string;
934
+ }
935
+ /**
936
+ * Event emitted when an HTTP request finishes.
937
+ */
938
+ interface HttpRequestFinishEvent {
939
+ type: "http-request-finish";
940
+ /** The request URL */
941
+ url: string;
942
+ /** HTTP status code */
943
+ statusCode: number;
944
+ }
945
+ /**
946
+ * Event emitted when a URL fetch starts.
947
+ */
948
+ interface FetchUrlStartEvent {
949
+ type: "fetch-url-start";
950
+ /** The URL being fetched */
951
+ url: string;
952
+ }
953
+ /**
954
+ * Event emitted when a URL fetch finishes.
955
+ */
956
+ interface FetchUrlFinishEvent {
957
+ type: "fetch-url-finish";
958
+ /** The URL that was fetched */
959
+ url: string;
960
+ /** Whether extraction was successful */
961
+ success: boolean;
962
+ }
963
+ /**
964
+ * Event emitted when a subagent starts.
965
+ */
966
+ interface SubagentStartEvent {
967
+ type: "subagent-start";
968
+ name: string;
969
+ task: string;
970
+ }
971
+ /**
972
+ * Event emitted when a subagent finishes.
973
+ */
974
+ interface SubagentFinishEvent {
975
+ type: "subagent-finish";
976
+ name: string;
977
+ result: string;
978
+ }
979
+ /**
980
+ * Event emitted when a subagent completes a step with tool calls.
981
+ */
982
+ interface SubagentStepEvent {
983
+ type: "subagent-step";
984
+ stepIndex: number;
985
+ toolCalls: Array<{
986
+ toolName: string;
987
+ args: any;
988
+ result: any;
989
+ }>;
990
+ }
991
+ /**
992
+ * Event emitted for a segment of text (used for CLI display).
993
+ * Text segments are flushed before tool events to maintain chronological order.
994
+ */
995
+ interface TextSegmentEvent {
996
+ type: "text-segment";
997
+ text: string;
998
+ }
999
+ /**
1000
+ * Event emitted when a user sends a message (used for CLI history).
1001
+ */
1002
+ interface UserMessageEvent {
1003
+ type: "user-message";
1004
+ content: string;
1005
+ }
1006
+ /**
1007
+ * Event emitted when the agent is done.
1008
+ */
1009
+ interface DoneEvent {
1010
+ type: "done";
1011
+ state: DeepAgentState;
1012
+ text?: string;
1013
+ /** Updated conversation history including the assistant's response */
1014
+ messages?: ModelMessage[];
1015
+ /** Structured output if schema was provided (validated by Zod) */
1016
+ output?: unknown;
1017
+ }
1018
+ /**
1019
+ * Event emitted when an error occurs.
1020
+ */
1021
+ interface ErrorEvent {
1022
+ type: "error";
1023
+ error: Error;
1024
+ }
1025
+ /**
1026
+ * Event emitted when a tool requires approval before execution.
1027
+ */
1028
+ interface ApprovalRequestedEvent {
1029
+ type: "approval-requested";
1030
+ /** Unique ID for this approval request */
1031
+ approvalId: string;
1032
+ /** The tool call ID */
1033
+ toolCallId: string;
1034
+ /** Name of the tool requiring approval */
1035
+ toolName: string;
1036
+ /** Arguments that will be passed to the tool */
1037
+ args: unknown;
1038
+ }
1039
+ /**
1040
+ * Event emitted when user responds to an approval request.
1041
+ */
1042
+ interface ApprovalResponseEvent {
1043
+ type: "approval-response";
1044
+ /** The approval ID being responded to */
1045
+ approvalId: string;
1046
+ /** Whether the tool was approved */
1047
+ approved: boolean;
1048
+ }
1049
+ /**
1050
+ * Event emitted when a checkpoint is saved.
1051
+ */
1052
+ interface CheckpointSavedEvent {
1053
+ type: "checkpoint-saved";
1054
+ /** Thread ID */
1055
+ threadId: string;
1056
+ /** Step number */
1057
+ step: number;
1058
+ }
1059
+ /**
1060
+ * Event emitted when a checkpoint is loaded.
1061
+ */
1062
+ interface CheckpointLoadedEvent {
1063
+ type: "checkpoint-loaded";
1064
+ /** Thread ID */
1065
+ threadId: string;
1066
+ /** Step number from loaded checkpoint */
1067
+ step: number;
1068
+ /** Number of messages restored */
1069
+ messagesCount: number;
1070
+ }
1071
+ /**
1072
+ * Union type of all possible Deep Agent events.
1073
+ */
1074
+ type DeepAgentEvent = TextEvent | StepStartEvent | StepFinishEvent | ToolCallEvent | ToolResultEvent | TodosChangedEvent | FileWriteStartEvent | FileWrittenEvent | FileEditedEvent | FileReadEvent | LsEvent | GlobEvent | GrepEvent | ExecuteStartEvent | ExecuteFinishEvent | WebSearchStartEvent | WebSearchFinishEvent | HttpRequestStartEvent | HttpRequestFinishEvent | FetchUrlStartEvent | FetchUrlFinishEvent | SubagentStartEvent | SubagentFinishEvent | SubagentStepEvent | TextSegmentEvent | UserMessageEvent | ApprovalRequestedEvent | ApprovalResponseEvent | CheckpointSavedEvent | CheckpointLoadedEvent | DoneEvent | ErrorEvent;
1075
+ /**
1076
+ * Callback function for handling Deep Agent events.
1077
+ */
1078
+ type EventCallback = (event: DeepAgentEvent) => void;
1079
+ /**
1080
+ * Options for streamWithEvents method.
1081
+ */
1082
+ interface StreamWithEventsOptions {
1083
+ /** @deprecated Use messages instead for better conversation context support */
1084
+ /** The user's prompt/message */
1085
+ prompt?: string;
1086
+ /** Maximum number of steps for the agent loop */
1087
+ maxSteps?: number;
1088
+ /** Shared state for todos and files */
1089
+ state?: DeepAgentState;
1090
+ /** Conversation history for multi-turn conversations. Takes precedence over prompt. */
1091
+ messages?: ModelMessage[];
1092
+ /** Signal to abort the generation */
1093
+ abortSignal?: AbortSignal;
1094
+ /**
1095
+ * Thread ID for checkpoint persistence.
1096
+ * When provided with a checkpointer, enables:
1097
+ * - Auto-saving checkpoints after each step
1098
+ * - Loading previous conversation state on start
1099
+ * - Resume from interrupts
1100
+ */
1101
+ threadId?: string;
1102
+ /**
1103
+ * Resume options for continuing from an interrupt.
1104
+ * Use when resuming from a tool approval request.
1105
+ */
1106
+ resume?: ResumeOptions;
1107
+ /**
1108
+ * Callback to handle tool approval requests.
1109
+ * Return true to approve, false to deny.
1110
+ * If not provided, tools requiring approval will be auto-denied.
1111
+ */
1112
+ onApprovalRequest?: (request: {
1113
+ approvalId: string;
1114
+ toolCallId: string;
1115
+ toolName: string;
1116
+ args: unknown;
1117
+ }) => Promise<boolean>;
1118
+ }
1119
+ //#endregion
1120
+ //#region src/types/structured-output.d.ts
1121
+ /**
1122
+ * Interface for agent results that include structured output
1123
+ */
1124
+ interface StructuredAgentResult<T = unknown> {
1125
+ text: string;
1126
+ output?: T;
1127
+ state?: any;
1128
+ messages?: any[];
1129
+ }
1130
+ /**
1131
+ * Type guard for checking if a result has structured output
1132
+ */
1133
+ declare function hasStructuredOutput<T>(result: any): result is StructuredAgentResult<T>;
1134
+ /**
1135
+ * Type guard for checking if an event has structured output
1136
+ */
1137
+ declare function eventHasStructuredOutput<T>(event: any): event is {
1138
+ type: "done";
1139
+ output: T;
1140
+ };
1141
+ /**
1142
+ * Extract structured output from agent result with type safety
1143
+ */
1144
+ declare function getStructuredOutput<T>(result: any): T | undefined;
1145
+ /**
1146
+ * Extract structured output from event with type safety
1147
+ */
1148
+ declare function getEventOutput<T>(event: any): T | undefined;
1149
+ //#endregion
1150
+ //#region src/agent.d.ts
1151
+ /**
1152
+ * Deep Agent wrapper class that provides generate() and stream() methods.
1153
+ * Uses ToolLoopAgent from AI SDK v6 for the agent loop.
1154
+ */
1155
+ declare class DeepAgent {
1156
+ private model;
1157
+ private systemPrompt;
1158
+ private userTools;
1159
+ private maxSteps;
1160
+ private backend;
1161
+ private subagentOptions;
1162
+ private toolResultEvictionLimit?;
1163
+ private enablePromptCaching;
1164
+ private summarizationConfig?;
1165
+ private hasSandboxBackend;
1166
+ private interruptOn?;
1167
+ private checkpointer?;
1168
+ private skillsMetadata;
1169
+ private outputConfig?;
1170
+ private loopControl?;
1171
+ private generationOptions?;
1172
+ private advancedOptions?;
1173
+ constructor(params: CreateDeepAgentParams);
1174
+ /**
1175
+ * Create core tools (todos and filesystem).
1176
+ * @private
1177
+ */
1178
+ private createCoreTools;
1179
+ /**
1180
+ * Create web tools if TAVILY_API_KEY is available.
1181
+ * Uses dynamic import to avoid bundling Node.js dependencies in client builds.
1182
+ * @private
1183
+ */
1184
+ private createWebToolSet;
1185
+ /**
1186
+ * Create execute tool if backend is a sandbox.
1187
+ * @private
1188
+ */
1189
+ private createExecuteToolSet;
1190
+ /**
1191
+ * Create subagent tool if configured.
1192
+ * @private
1193
+ */
1194
+ private createSubagentToolSet;
1195
+ /**
1196
+ * Create all tools for the agent, combining core, web, execute, and subagent tools.
1197
+ * @private
1198
+ */
1199
+ private createTools;
1200
+ /**
1201
+ * Build stop conditions with maxSteps safety limit.
1202
+ * Combines user-provided stop conditions with the maxSteps limit.
1203
+ */
1204
+ private buildStopConditions;
1205
+ /**
1206
+ * Build agent settings by combining passthrough options with defaults.
1207
+ */
1208
+ private buildAgentSettings;
1209
+ /**
1210
+ * Create a ToolLoopAgent for a given state.
1211
+ * @param state - The shared agent state
1212
+ * @param maxSteps - Optional max steps override
1213
+ * @param onEvent - Optional callback for emitting events
1214
+ */
1215
+ private createAgent;
1216
+ /**
1217
+ * Load skills from directory asynchronously.
1218
+ * Supports both legacy skillsDir and new agentId modes.
1219
+ */
1220
+ private loadSkills;
1221
+ /**
1222
+ * Generate a response (non-streaming).
1223
+ */
1224
+ generate(options: {
1225
+ prompt: string;
1226
+ maxSteps?: number;
1227
+ }): Promise<ai2.GenerateTextResult<{}, never> & {
1228
+ state: DeepAgentState;
1229
+ }>;
1230
+ /**
1231
+ * Stream a response.
1232
+ */
1233
+ stream(options: {
1234
+ prompt: string;
1235
+ maxSteps?: number;
1236
+ }): Promise<ai2.StreamTextResult<{}, never> & {
1237
+ state: DeepAgentState;
1238
+ }>;
1239
+ /**
1240
+ * Generate with an existing state (for continuing conversations).
1241
+ */
1242
+ generateWithState(options: {
1243
+ prompt: string;
1244
+ state: DeepAgentState;
1245
+ maxSteps?: number;
1246
+ }): Promise<ai2.GenerateTextResult<{}, never> & {
1247
+ state: DeepAgentState;
1248
+ }>;
1249
+ /**
1250
+ * Get the underlying ToolLoopAgent for advanced usage.
1251
+ * This allows using AI SDK's createAgentUIStream and other utilities.
1252
+ */
1253
+ getAgent(state?: DeepAgentState): ToolLoopAgent<never, {}, never>;
1254
+ /**
1255
+ * Stream a response with real-time events.
1256
+ * This is an async generator that yields DeepAgentEvent objects.
1257
+ *
1258
+ * Supports conversation history via the `messages` option for multi-turn conversations.
1259
+ *
1260
+ * @example
1261
+ * ```typescript
1262
+ * // Single turn
1263
+ * for await (const event of agent.streamWithEvents({ prompt: "..." })) {
1264
+ * switch (event.type) {
1265
+ * case 'text':
1266
+ * process.stdout.write(event.text);
1267
+ * break;
1268
+ * case 'done':
1269
+ * // event.messages contains the updated conversation history
1270
+ * console.log('Messages:', event.messages);
1271
+ * break;
1272
+ * }
1273
+ * }
1274
+ *
1275
+ * // Multi-turn conversation
1276
+ * let messages = [];
1277
+ * for await (const event of agent.streamWithEvents({ prompt: "Hello", messages })) {
1278
+ * if (event.type === 'done') {
1279
+ * messages = event.messages; // Save for next turn
1280
+ * }
1281
+ * }
1282
+ * for await (const event of agent.streamWithEvents({ prompt: "Follow up", messages })) {
1283
+ * // Agent now has context from previous turn
1284
+ * }
1285
+ * ```
1286
+ */
1287
+ /**
1288
+ * Compose user's onStepFinish callback with DeepAgent's internal checkpointing logic.
1289
+ * User callback executes first, errors are caught to prevent breaking checkpointing.
1290
+ */
1291
+ private composeOnStepFinish;
1292
+ /**
1293
+ * Compose user's onFinish callback with DeepAgent's internal cleanup logic.
1294
+ */
1295
+ private composeOnFinish;
1296
+ /**
1297
+ * Compose user's prepareStep callback with DeepAgent's internal step preparation.
1298
+ * Returns a function typed as `any` to avoid AI SDK's strict toolName inference.
1299
+ */
1300
+ private composePrepareStep;
1301
+ /**
1302
+ * Build streamText options with callbacks for step tracking and checkpointing.
1303
+ *
1304
+ * @private
1305
+ */
1306
+ private buildStreamTextOptions;
1307
+ /**
1308
+ * Build message array from options, handling validation and priority logic.
1309
+ * Priority: explicit messages > prompt > checkpoint history.
1310
+ *
1311
+ * @private
1312
+ */
1313
+ private buildMessageArray;
1314
+ /**
1315
+ * Load checkpoint context if threadId is provided.
1316
+ * Handles checkpoint restoration and resume from interrupt.
1317
+ *
1318
+ * @private
1319
+ */
1320
+ private loadCheckpointContext;
1321
+ streamWithEvents(options: StreamWithEventsOptions): AsyncGenerator<DeepAgentEvent, void, unknown>;
1322
+ /**
1323
+ * Stream with a simple callback interface.
1324
+ * This is a convenience wrapper around streamWithEvents.
1325
+ */
1326
+ streamWithCallback(options: StreamWithEventsOptions, onEvent: EventCallback): Promise<{
1327
+ state: DeepAgentState;
1328
+ text?: string;
1329
+ messages?: ModelMessage$1[];
1330
+ }>;
1331
+ }
1332
+ /**
1333
+ * Create a Deep Agent with planning, filesystem, and subagent capabilities.
1334
+ *
1335
+ * @param params - Configuration object for the Deep Agent
1336
+ * @param params.model - **Required.** AI SDK LanguageModel instance (e.g., `anthropic('claude-sonnet-4-20250514')`, `openai('gpt-4o')`)
1337
+ * @param params.systemPrompt - Optional custom system prompt for the agent
1338
+ * @param params.tools - Optional custom tools to add to the agent (AI SDK ToolSet)
1339
+ * @param params.subagents - Optional array of specialized subagent configurations for task delegation
1340
+ * @param params.backend - Optional backend for filesystem operations (default: StateBackend for in-memory storage)
1341
+ * @param params.maxSteps - Optional maximum number of steps for the agent loop (default: 100)
1342
+ * @param params.includeGeneralPurposeAgent - Optional flag to include general-purpose subagent (default: true)
1343
+ * @param params.toolResultEvictionLimit - Optional token limit before evicting large tool results to filesystem (default: disabled)
1344
+ * @param params.enablePromptCaching - Optional flag to enable prompt caching for improved performance (Anthropic only, default: false)
1345
+ * @param params.summarization - Optional summarization configuration for automatic conversation summarization
1346
+ * @returns A configured DeepAgent instance
1347
+ *
1348
+ * @see {@link CreateDeepAgentParams} for detailed parameter types
1349
+ *
1350
+ * @example Basic usage
1351
+ * ```typescript
1352
+ * import { createDeepAgent } from 'deepagentsdk';
1353
+ * import { anthropic } from '@ai-sdk/anthropic';
1354
+ *
1355
+ * const agent = createDeepAgent({
1356
+ * model: anthropic('claude-sonnet-4-20250514'),
1357
+ * systemPrompt: 'You are a research assistant...',
1358
+ * });
1359
+ *
1360
+ * const result = await agent.generate({
1361
+ * prompt: 'Research the topic and write a report',
1362
+ * });
1363
+ * ```
1364
+ *
1365
+ * @example With custom tools
1366
+ * ```typescript
1367
+ * import { tool } from 'ai';
1368
+ * import { z } from 'zod';
1369
+ *
1370
+ * const customTool = tool({
1371
+ * description: 'Get current time',
1372
+ * inputSchema: z.object({}),
1373
+ * execute: async () => new Date().toISOString(),
1374
+ * });
1375
+ *
1376
+ * const agent = createDeepAgent({
1377
+ * model: anthropic('claude-sonnet-4-20250514'),
1378
+ * tools: { get_time: customTool },
1379
+ * });
1380
+ * ```
1381
+ *
1382
+ * @example With subagents
1383
+ * ```typescript
1384
+ * const agent = createDeepAgent({
1385
+ * model: anthropic('claude-sonnet-4-20250514'),
1386
+ * subagents: [{
1387
+ * name: 'research-agent',
1388
+ * description: 'Specialized for research tasks',
1389
+ * systemPrompt: 'You are a research specialist...',
1390
+ * }],
1391
+ * });
1392
+ * ```
1393
+ *
1394
+ * @example With StateBackend (default, explicit)
1395
+ * ```typescript
1396
+ * import { StateBackend } from 'deepagentsdk';
1397
+ *
1398
+ * const state = { todos: [], files: {} };
1399
+ * const agent = createDeepAgent({
1400
+ * model: anthropic('claude-sonnet-4-20250514'),
1401
+ * backend: new StateBackend(state), // Ephemeral in-memory storage
1402
+ * });
1403
+ * ```
1404
+ *
1405
+ * @example With FilesystemBackend
1406
+ * ```typescript
1407
+ * import { FilesystemBackend } from 'deepagentsdk';
1408
+ *
1409
+ * const agent = createDeepAgent({
1410
+ * model: anthropic('claude-sonnet-4-20250514'),
1411
+ * backend: new FilesystemBackend({ rootDir: './workspace' }), // Persist to disk
1412
+ * });
1413
+ * ```
1414
+ *
1415
+ * @example With PersistentBackend
1416
+ * ```typescript
1417
+ * import { PersistentBackend, InMemoryStore } from 'deepagentsdk';
1418
+ *
1419
+ * const store = new InMemoryStore();
1420
+ * const agent = createDeepAgent({
1421
+ * model: anthropic('claude-sonnet-4-20250514'),
1422
+ * backend: new PersistentBackend({ store, namespace: 'project-1' }), // Cross-session persistence
1423
+ * });
1424
+ * ```
1425
+ *
1426
+ * @example With CompositeBackend
1427
+ * ```typescript
1428
+ * import { CompositeBackend, FilesystemBackend, StateBackend } from 'deepagentsdk';
1429
+ *
1430
+ * const state = { todos: [], files: {} };
1431
+ * const agent = createDeepAgent({
1432
+ * model: anthropic('claude-sonnet-4-20250514'),
1433
+ * backend: new CompositeBackend(
1434
+ * new StateBackend(state),
1435
+ * { '/persistent/': new FilesystemBackend({ rootDir: './persistent' }) }
1436
+ * ), // Route files by path prefix
1437
+ * });
1438
+ * ```
1439
+ *
1440
+ * @example With middleware for logging and caching
1441
+ * ```typescript
1442
+ * import { createDeepAgent } from 'deepagentsdk';
1443
+ * import { anthropic } from '@ai-sdk/anthropic';
1444
+ *
1445
+ * const loggingMiddleware = {
1446
+ * wrapGenerate: async ({ doGenerate, params }) => {
1447
+ * console.log('Model called with:', params.prompt);
1448
+ * const result = await doGenerate();
1449
+ * console.log('Model returned:', result.text);
1450
+ * return result;
1451
+ * },
1452
+ * };
1453
+ *
1454
+ * const agent = createDeepAgent({
1455
+ * model: anthropic('claude-sonnet-4-20250514'),
1456
+ * middleware: [loggingMiddleware],
1457
+ * });
1458
+ * ```
1459
+ *
1460
+ * @example With middleware factory for context access
1461
+ * ```typescript
1462
+ * import { FilesystemBackend } from 'deepagentsdk';
1463
+ *
1464
+ * function createContextMiddleware(backend: BackendProtocol) {
1465
+ * return {
1466
+ * wrapGenerate: async ({ doGenerate }) => {
1467
+ * const state = await backend.read('state');
1468
+ * const result = await doGenerate();
1469
+ * await backend.write('state', { ...state, lastCall: result });
1470
+ * return result;
1471
+ * },
1472
+ * };
1473
+ * }
1474
+ *
1475
+ * const backend = new FilesystemBackend({ rootDir: './workspace' });
1476
+ * const agent = createDeepAgent({
1477
+ * model: anthropic('claude-sonnet-4-20250514'),
1478
+ * backend,
1479
+ * middleware: createContextMiddleware(backend),
1480
+ * });
1481
+ * ```
1482
+ *
1483
+ * @example With performance optimizations
1484
+ * ```typescript
1485
+ * const agent = createDeepAgent({
1486
+ * model: anthropic('claude-sonnet-4-20250514'),
1487
+ * enablePromptCaching: true,
1488
+ * toolResultEvictionLimit: 20000,
1489
+ * summarization: {
1490
+ * enabled: true,
1491
+ * tokenThreshold: 170000,
1492
+ * keepMessages: 6,
1493
+ * },
1494
+ * });
1495
+ * ```
1496
+ */
1497
+ declare function createDeepAgent(params: CreateDeepAgentParams): DeepAgent;
1498
+ //#endregion
1499
+ export { createLsTool as $, TextEvent as A, CheckpointSaverOptions as At, DynamicApprovalConfig as B, FileWrittenEvent as C, FileInfo as Ct, StepStartEvent as D, isSandboxBackend as Dt, StepFinishEvent as E, WriteResult as Et, WebSearchStartEvent as F, createExecuteToolFromBackend as G, SubAgent as H, AgentMemoryOptions as I, write_todos as J, execute as K, CreateDeepAgentParams as L, ToolCallEvent as M, ResumeDecision as Mt, ToolResultEvent as N, ResumeOptions as Nt, SubagentFinishEvent as O, BaseCheckpointSaver as Ot, WebSearchFinishEvent as P, createGrepTool as Q, SummarizationConfig as R, FileWriteStartEvent as S, FileData as St, HttpRequestStartEvent as T, SandboxBackendProtocol as Tt, CreateExecuteToolOptions as U, InterruptOnConfig as V, createExecuteTool as W, createFilesystemTools as X, createEditFileTool as Y, createGlobTool as Z, ExecuteFinishEvent as _, BackendFactory as _t, eventHasStructuredOutput as a, ls as at, FetchUrlStartEvent as b, EditResult as bt, hasStructuredOutput as c, CreateWebToolsOptions as ct, CheckpointLoadedEvent as d, createWebSearchTool as dt, createReadFileTool as et, CheckpointSavedEvent as f, createWebTools as ft, EventCallback as g, web_search as gt, ErrorEvent as h, http_request as ht, StructuredAgentResult as i, grep as it, TodosChangedEvent as j, InterruptData as jt, SubagentStartEvent as k, Checkpoint as kt, ApprovalRequestedEvent as l, createFetchUrlTool as lt, DoneEvent as m, htmlToMarkdown as mt, createDeepAgent as n, edit_file as nt, getEventOutput as o, read_file as ot, DeepAgentEvent as p, fetch_url as pt, createTodosTool as q, ModelMessage$1 as r, glob as rt, getStructuredOutput as s, write_file as st, DeepAgent as t, createWriteFileTool as tt, ApprovalResponseEvent as u, createHttpRequestTool as ut, ExecuteStartEvent as v, BackendProtocol as vt, HttpRequestFinishEvent as w, GrepMatch as wt, FileEditedEvent as x, ExecuteResponse as xt, FetchUrlFinishEvent as y, DeepAgentState as yt, TodoItem as z };
1500
+ //# sourceMappingURL=agent-BDM-PIu8.d.mts.map