deepagentsdk 0.12.0 → 0.13.0

package/dist/{types-4g9UvXal.d.mts → agent-BDM-PIu8.d.mts}

@@ -1,5 +1,5 @@
-import * as ai3 from "ai";
-import { LanguageModel, LanguageModel as LanguageModel$2, LanguageModelMiddleware, ModelMessage, ModelMessage as ModelMessage$1, StopCondition, ToolLoopAgentSettings, ToolSet } from "ai";
+import * as ai2 from "ai";
+import { LanguageModel, LanguageModel as LanguageModel$2, LanguageModelMiddleware, ModelMessage, ModelMessage as ModelMessage$1, StopCondition, ToolLoopAgent, ToolLoopAgentSettings, ToolSet } from "ai";
 import { z } from "zod";
 
 //#region src/checkpointer/types.d.ts
@@ -256,7 +256,7 @@ declare function createWebSearchTool(state: DeepAgentState, options: {
   onEvent?: EventCallback;
   toolResultEvictionLimit?: number;
   tavilyApiKey: string;
-}): ai3.Tool<{
+}): ai2.Tool<{
   query: string;
   max_results: number;
   topic: "general" | "news" | "finance";
@@ -270,7 +270,7 @@ declare function createHttpRequestTool(state: DeepAgentState, options: {
   onEvent?: EventCallback;
   toolResultEvictionLimit?: number;
   defaultTimeout: number;
-}): ai3.Tool<{
+}): ai2.Tool<{
   timeout: number;
   url: string;
   method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
@@ -286,7 +286,7 @@ declare function createFetchUrlTool(state: DeepAgentState, options: {
   onEvent?: EventCallback;
   toolResultEvictionLimit?: number;
   defaultTimeout: number;
-}): ai3.Tool<{
+}): ai2.Tool<{
   timeout: number;
   url: string;
   extract_article: boolean;
@@ -323,13 +323,13 @@ declare const fetch_url: typeof createFetchUrlTool;
 /**
  * Create the ls tool.
  */
-declare function createLsTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai3.Tool<{
+declare function createLsTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
   path: string;
 }, string>;
 /**
  * Create the read_file tool.
  */
-declare function createReadFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai3.Tool<{
+declare function createReadFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
   file_path: string;
   offset: number;
   limit: number;
@@ -337,14 +337,14 @@ declare function createReadFileTool(state: DeepAgentState, backend: BackendProto
 /**
  * Create the write_file tool.
  */
-declare function createWriteFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai3.Tool<{
-  content: string;
+declare function createWriteFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
   file_path: string;
+  content: string;
 }, string>;
 /**
  * Create the edit_file tool.
  */
-declare function createEditFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai3.Tool<{
+declare function createEditFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
   file_path: string;
   old_string: string;
   new_string: string;
@@ -353,14 +353,14 @@ declare function createEditFileTool(state: DeepAgentState, backend: BackendProto
 /**
  * Create the glob tool.
  */
-declare function createGlobTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai3.Tool<{
+declare function createGlobTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
   path: string;
   pattern: string;
 }, string>;
 /**
  * Create the grep tool.
  */
-declare function createGrepTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai3.Tool<{
+declare function createGrepTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
   path: string;
   pattern: string;
   glob?: string | null | undefined;
@@ -383,29 +383,29 @@ interface CreateFilesystemToolsOptions {
  * @param onEvent - Optional callback for emitting events (deprecated, use options)
  */
 declare function createFilesystemTools(state: DeepAgentState, backendOrOptions?: BackendProtocol | BackendFactory | CreateFilesystemToolsOptions, onEvent?: EventCallback): {
-  ls: ai3.Tool<{
+  ls: ai2.Tool<{
     path: string;
   }, string>;
-  read_file: ai3.Tool<{
+  read_file: ai2.Tool<{
     file_path: string;
     offset: number;
     limit: number;
   }, string>;
-  write_file: ai3.Tool<{
-    content: string;
+  write_file: ai2.Tool<{
     file_path: string;
+    content: string;
   }, string>;
-  edit_file: ai3.Tool<{
+  edit_file: ai2.Tool<{
     file_path: string;
     old_string: string;
     new_string: string;
     replace_all: boolean;
   }, string>;
-  glob: ai3.Tool<{
+  glob: ai2.Tool<{
     path: string;
     pattern: string;
   }, string>;
-  grep: ai3.Tool<{
+  grep: ai2.Tool<{
     path: string;
     pattern: string;
     glob?: string | null | undefined;
@@ -428,7 +428,7 @@ declare const grep: typeof createGrepTool;
  * @param state - The shared agent state
  * @param onEvent - Optional callback for emitting events
  */
-declare function createTodosTool(state: DeepAgentState, onEvent?: EventCallback): ai3.Tool<{
+declare function createTodosTool(state: DeepAgentState, onEvent?: EventCallback): ai2.Tool<{
   todos: {
     status: "pending" | "in_progress" | "completed" | "cancelled";
     id: string;
@@ -489,7 +489,7 @@ interface CreateExecuteToolOptions {
  * });
  * ```
  */
-declare function createExecuteTool(options: CreateExecuteToolOptions): ai3.Tool<{
+declare function createExecuteTool(options: CreateExecuteToolOptions): ai2.Tool<{
   command: string;
 }, string>;
 /**
@@ -507,7 +507,7 @@ declare function createExecuteTool(options: CreateExecuteToolOptions): ai3.Tool<
  * };
  * ```
  */
-declare function createExecuteToolFromBackend(backend: SandboxBackendProtocol): ai3.Tool<{
+declare function createExecuteToolFromBackend(backend: SandboxBackendProtocol): ai2.Tool<{
   command: string;
 }, string>;
 /**
@@ -641,7 +641,7 @@ interface PrepareStepArgs {
   stepNumber: number;
   steps: unknown[];
   model: LanguageModel$2;
-  messages: ai3.ModelMessage[];
+  messages: ai2.ModelMessage[];
   experimental_context?: unknown;
 }
 /**
@@ -1147,5 +1147,354 @@ declare function getStructuredOutput<T>(result: any): T | undefined;
  */
 declare function getEventOutput<T>(event: any): T | undefined;
 //#endregion
-export { createReadFileTool as $, TodosChangedEvent as A, InterruptData as At, InterruptOnConfig as B, HttpRequestStartEvent as C, GrepMatch as Ct, SubagentFinishEvent as D, BaseCheckpointSaver as Dt, StreamWithEventsOptions as E, isSandboxBackend as Et, AgentMemoryOptions as F, execute as G, CreateExecuteToolOptions as H, CreateDeepAgentParams as I, createEditFileTool as J, createTodosTool as K, SummarizationConfig as L, ToolResultEvent as M, ResumeOptions as Mt, WebSearchFinishEvent as N, SubagentStartEvent as O, Checkpoint as Ot, WebSearchStartEvent as P, createLsTool as Q, TodoItem as R, HttpRequestFinishEvent as S, FileInfo as St, StepStartEvent as T, WriteResult as Tt, createExecuteTool as U, SubAgent as V, createExecuteToolFromBackend as W, createGlobTool as X, createFilesystemTools as Y, createGrepTool as Z, FetchUrlFinishEvent as _, BackendProtocol as _t, getStructuredOutput as a, read_file as at, FileWriteStartEvent as b, ExecuteResponse as bt, ApprovalResponseEvent as c, createFetchUrlTool as ct, DeepAgentEvent as d, createWebTools as dt, createWriteFileTool as et, DoneEvent as f, fetch_url as ft, ExecuteStartEvent as g, BackendFactory as gt, ExecuteFinishEvent as h, web_search as ht, getEventOutput as i, ls as it, ToolCallEvent as j, ResumeDecision as jt, TextEvent as k, CheckpointSaverOptions as kt, CheckpointLoadedEvent as l, createHttpRequestTool as lt, EventCallback as m, http_request as mt, StructuredAgentResult as n, glob as nt, hasStructuredOutput as o, write_file as ot, ErrorEvent as p, htmlToMarkdown as pt, write_todos as q, eventHasStructuredOutput as r, grep as rt, ApprovalRequestedEvent as s, CreateWebToolsOptions as st, ModelMessage$1 as t, edit_file as tt, CheckpointSavedEvent as u, createWebSearchTool as ut, FetchUrlStartEvent as v, DeepAgentState as vt, StepFinishEvent as w, SandboxBackendProtocol as wt, FileWrittenEvent as x, FileData as xt, FileEditedEvent as y, EditResult as yt, DynamicApprovalConfig as z };
-//# sourceMappingURL=types-4g9UvXal.d.mts.map
+//#region src/agent.d.ts
+/**
+ * Deep Agent wrapper class that provides generate() and stream() methods.
+ * Uses ToolLoopAgent from AI SDK v6 for the agent loop.
+ */
+declare class DeepAgent {
+  private model;
+  private systemPrompt;
+  private userTools;
+  private maxSteps;
+  private backend;
+  private subagentOptions;
+  private toolResultEvictionLimit?;
+  private enablePromptCaching;
+  private summarizationConfig?;
+  private hasSandboxBackend;
+  private interruptOn?;
+  private checkpointer?;
+  private skillsMetadata;
+  private outputConfig?;
+  private loopControl?;
+  private generationOptions?;
+  private advancedOptions?;
+  constructor(params: CreateDeepAgentParams);
+  /**
+   * Create core tools (todos and filesystem).
+   * @private
+   */
+  private createCoreTools;
+  /**
+   * Create web tools if TAVILY_API_KEY is available.
+   * Uses dynamic import to avoid bundling Node.js dependencies in client builds.
+   * @private
+   */
+  private createWebToolSet;
+  /**
+   * Create execute tool if backend is a sandbox.
+   * @private
+   */
+  private createExecuteToolSet;
+  /**
+   * Create subagent tool if configured.
+   * @private
+   */
+  private createSubagentToolSet;
+  /**
+   * Create all tools for the agent, combining core, web, execute, and subagent tools.
+   * @private
+   */
+  private createTools;
+  /**
+   * Build stop conditions with maxSteps safety limit.
+   * Combines user-provided stop conditions with the maxSteps limit.
+   */
+  private buildStopConditions;
+  /**
+   * Build agent settings by combining passthrough options with defaults.
+   */
+  private buildAgentSettings;
+  /**
+   * Create a ToolLoopAgent for a given state.
+   * @param state - The shared agent state
+   * @param maxSteps - Optional max steps override
+   * @param onEvent - Optional callback for emitting events
+   */
+  private createAgent;
+  /**
+   * Load skills from directory asynchronously.
+   * Supports both legacy skillsDir and new agentId modes.
+   */
+  private loadSkills;
+  /**
+   * Generate a response (non-streaming).
+   */
+  generate(options: {
+    prompt: string;
+    maxSteps?: number;
+  }): Promise<ai2.GenerateTextResult<{}, never> & {
+    state: DeepAgentState;
+  }>;
+  /**
+   * Stream a response.
+   */
+  stream(options: {
+    prompt: string;
+    maxSteps?: number;
+  }): Promise<ai2.StreamTextResult<{}, never> & {
+    state: DeepAgentState;
+  }>;
+  /**
+   * Generate with an existing state (for continuing conversations).
+   */
+  generateWithState(options: {
+    prompt: string;
+    state: DeepAgentState;
+    maxSteps?: number;
+  }): Promise<ai2.GenerateTextResult<{}, never> & {
+    state: DeepAgentState;
+  }>;
+  /**
+   * Get the underlying ToolLoopAgent for advanced usage.
+   * This allows using AI SDK's createAgentUIStream and other utilities.
+   */
+  getAgent(state?: DeepAgentState): ToolLoopAgent<never, {}, never>;
+  /**
+   * Stream a response with real-time events.
+   * This is an async generator that yields DeepAgentEvent objects.
+   *
+   * Supports conversation history via the `messages` option for multi-turn conversations.
+   *
+   * @example
+   * ```typescript
+   * // Single turn
+   * for await (const event of agent.streamWithEvents({ prompt: "..." })) {
+   *   switch (event.type) {
+   *     case 'text':
+   *       process.stdout.write(event.text);
+   *       break;
+   *     case 'done':
+   *       // event.messages contains the updated conversation history
+   *       console.log('Messages:', event.messages);
+   *       break;
+   *   }
+   * }
+   *
+   * // Multi-turn conversation
+   * let messages = [];
+   * for await (const event of agent.streamWithEvents({ prompt: "Hello", messages })) {
+   *   if (event.type === 'done') {
+   *     messages = event.messages; // Save for next turn
+   *   }
+   * }
+   * for await (const event of agent.streamWithEvents({ prompt: "Follow up", messages })) {
+   *   // Agent now has context from previous turn
+   * }
+   * ```
+   */
+  /**
+   * Compose user's onStepFinish callback with DeepAgent's internal checkpointing logic.
+   * User callback executes first, errors are caught to prevent breaking checkpointing.
+   */
+  private composeOnStepFinish;
+  /**
+   * Compose user's onFinish callback with DeepAgent's internal cleanup logic.
+   */
+  private composeOnFinish;
+  /**
+   * Compose user's prepareStep callback with DeepAgent's internal step preparation.
+   * Returns a function typed as `any` to avoid AI SDK's strict toolName inference.
+   */
+  private composePrepareStep;
+  /**
+   * Build streamText options with callbacks for step tracking and checkpointing.
+   *
+   * @private
+   */
+  private buildStreamTextOptions;
+  /**
+   * Build message array from options, handling validation and priority logic.
+   * Priority: explicit messages > prompt > checkpoint history.
+   *
+   * @private
+   */
+  private buildMessageArray;
+  /**
+   * Load checkpoint context if threadId is provided.
+   * Handles checkpoint restoration and resume from interrupt.
+   *
+   * @private
+   */
+  private loadCheckpointContext;
+  streamWithEvents(options: StreamWithEventsOptions): AsyncGenerator<DeepAgentEvent, void, unknown>;
+  /**
+   * Stream with a simple callback interface.
+   * This is a convenience wrapper around streamWithEvents.
+   */
+  streamWithCallback(options: StreamWithEventsOptions, onEvent: EventCallback): Promise<{
+    state: DeepAgentState;
+    text?: string;
+    messages?: ModelMessage$1[];
+  }>;
+}
+/**
+ * Create a Deep Agent with planning, filesystem, and subagent capabilities.
+ *
+ * @param params - Configuration object for the Deep Agent
+ * @param params.model - **Required.** AI SDK LanguageModel instance (e.g., `anthropic('claude-sonnet-4-20250514')`, `openai('gpt-4o')`)
+ * @param params.systemPrompt - Optional custom system prompt for the agent
+ * @param params.tools - Optional custom tools to add to the agent (AI SDK ToolSet)
+ * @param params.subagents - Optional array of specialized subagent configurations for task delegation
+ * @param params.backend - Optional backend for filesystem operations (default: StateBackend for in-memory storage)
+ * @param params.maxSteps - Optional maximum number of steps for the agent loop (default: 100)
+ * @param params.includeGeneralPurposeAgent - Optional flag to include general-purpose subagent (default: true)
+ * @param params.toolResultEvictionLimit - Optional token limit before evicting large tool results to filesystem (default: disabled)
+ * @param params.enablePromptCaching - Optional flag to enable prompt caching for improved performance (Anthropic only, default: false)
+ * @param params.summarization - Optional summarization configuration for automatic conversation summarization
+ * @returns A configured DeepAgent instance
+ *
+ * @see {@link CreateDeepAgentParams} for detailed parameter types
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   systemPrompt: 'You are a research assistant...',
+ * });
+ *
+ * const result = await agent.generate({
+ *   prompt: 'Research the topic and write a report',
+ * });
+ * ```
+ *
+ * @example With custom tools
+ * ```typescript
+ * import { tool } from 'ai';
+ * import { z } from 'zod';
+ *
+ * const customTool = tool({
+ *   description: 'Get current time',
+ *   inputSchema: z.object({}),
+ *   execute: async () => new Date().toISOString(),
+ * });
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   tools: { get_time: customTool },
+ * });
+ * ```
+ *
+ * @example With subagents
+ * ```typescript
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   subagents: [{
+ *     name: 'research-agent',
+ *     description: 'Specialized for research tasks',
+ *     systemPrompt: 'You are a research specialist...',
+ *   }],
+ * });
+ * ```
+ *
+ * @example With StateBackend (default, explicit)
+ * ```typescript
+ * import { StateBackend } from 'deepagentsdk';
+ *
+ * const state = { todos: [], files: {} };
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend: new StateBackend(state), // Ephemeral in-memory storage
+ * });
+ * ```
+ *
+ * @example With FilesystemBackend
+ * ```typescript
+ * import { FilesystemBackend } from 'deepagentsdk';
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend: new FilesystemBackend({ rootDir: './workspace' }), // Persist to disk
+ * });
+ * ```
+ *
+ * @example With PersistentBackend
+ * ```typescript
+ * import { PersistentBackend, InMemoryStore } from 'deepagentsdk';
+ *
+ * const store = new InMemoryStore();
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend: new PersistentBackend({ store, namespace: 'project-1' }), // Cross-session persistence
+ * });
+ * ```
+ *
+ * @example With CompositeBackend
+ * ```typescript
+ * import { CompositeBackend, FilesystemBackend, StateBackend } from 'deepagentsdk';
+ *
+ * const state = { todos: [], files: {} };
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend: new CompositeBackend(
+ *     new StateBackend(state),
+ *     { '/persistent/': new FilesystemBackend({ rootDir: './persistent' }) }
+ *   ), // Route files by path prefix
+ * });
+ * ```
+ *
+ * @example With middleware for logging and caching
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const loggingMiddleware = {
+ *   wrapGenerate: async ({ doGenerate, params }) => {
+ *     console.log('Model called with:', params.prompt);
+ *     const result = await doGenerate();
+ *     console.log('Model returned:', result.text);
+ *     return result;
+ *   },
+ * };
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   middleware: [loggingMiddleware],
+ * });
+ * ```
+ *
+ * @example With middleware factory for context access
+ * ```typescript
+ * import { FilesystemBackend } from 'deepagentsdk';
+ *
+ * function createContextMiddleware(backend: BackendProtocol) {
+ *   return {
+ *     wrapGenerate: async ({ doGenerate }) => {
+ *       const state = await backend.read('state');
+ *       const result = await doGenerate();
+ *       await backend.write('state', { ...state, lastCall: result });
+ *       return result;
+ *     },
+ *   };
+ * }
+ *
+ * const backend = new FilesystemBackend({ rootDir: './workspace' });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ *   middleware: createContextMiddleware(backend),
+ * });
+ * ```
+ *
+ * @example With performance optimizations
+ * ```typescript
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   enablePromptCaching: true,
+ *   toolResultEvictionLimit: 20000,
+ *   summarization: {
+ *     enabled: true,
+ *     tokenThreshold: 170000,
+ *     keepMessages: 6,
+ *   },
+ * });
+ * ```
+ */
+declare function createDeepAgent(params: CreateDeepAgentParams): DeepAgent;
+//#endregion
+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 };
+//# sourceMappingURL=agent-BDM-PIu8.d.mts.map