deepagentsdk 0.11.1 → 0.12.0

package/dist/index.d.cts

@@ -0,0 +1,1581 @@
+import { $ as createReadFileTool, A as TodosChangedEvent, At as InterruptData, B as InterruptOnConfig, C as HttpRequestStartEvent, Ct as GrepMatch, D as SubagentFinishEvent, Dt as BaseCheckpointSaver, E as StreamWithEventsOptions, Et as isSandboxBackend, F as AgentMemoryOptions, G as execute, H as CreateExecuteToolOptions, I as CreateDeepAgentParams, J as createEditFileTool, K as createTodosTool, L as SummarizationConfig, M as ToolResultEvent, Mt as ResumeOptions, N as WebSearchFinishEvent, O as SubagentStartEvent, Ot as Checkpoint, P as WebSearchStartEvent, Q as createLsTool, R as TodoItem, S as HttpRequestFinishEvent, St as FileInfo, T as StepStartEvent, Tt as WriteResult, U as createExecuteTool, V as SubAgent, W as createExecuteToolFromBackend, X as createGlobTool, Y as createFilesystemTools, Z as createGrepTool, _ as FetchUrlFinishEvent, _t as BackendProtocol, a as getStructuredOutput, at as read_file, b as FileWriteStartEvent, bt as ExecuteResponse, c as ApprovalResponseEvent, ct as createFetchUrlTool, d as DeepAgentEvent, dt as createWebTools, et as createWriteFileTool, f as DoneEvent, ft as fetch_url, g as ExecuteStartEvent, gt as BackendFactory, h as ExecuteFinishEvent, ht as web_search, i as getEventOutput, it as ls, j as ToolCallEvent, jt as ResumeDecision, k as TextEvent, kt as CheckpointSaverOptions, l as CheckpointLoadedEvent, lt as createHttpRequestTool, m as EventCallback, mt as http_request, n as StructuredAgentResult, nt as glob, o as hasStructuredOutput, ot as write_file, p as ErrorEvent, pt as htmlToMarkdown, q as write_todos, r as eventHasStructuredOutput, rt as grep, s as ApprovalRequestedEvent, st as CreateWebToolsOptions, t as ModelMessage$1, tt as edit_file, u as CheckpointSavedEvent, ut as createWebSearchTool, v as FetchUrlStartEvent, vt as DeepAgentState, w as StepFinishEvent, wt as SandboxBackendProtocol, x as FileWrittenEvent, xt as FileData, y as FileEditedEvent, yt as EditResult, z as DynamicApprovalConfig } from "./types-IulnvhFg.cjs";
+import * as ai0 from "ai";
+import { LanguageModel, LanguageModelMiddleware, LanguageModelMiddleware as LanguageModelMiddleware$1, ModelMessage, ToolLoopAgent, ToolLoopAgent as ToolLoopAgent$1, ToolSet, hasToolCall, stepCountIs, wrapLanguageModel } from "ai";
+
+//#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.
+   * @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<ai0.GenerateTextResult<{}, never> & {
+    state: DeepAgentState;
+  }>;
+  /**
+   * Stream a response.
+   */
+  stream(options: {
+    prompt: string;
+    maxSteps?: number;
+  }): Promise<ai0.StreamTextResult<{}, never> & {
+    state: DeepAgentState;
+  }>;
+  /**
+   * Generate with an existing state (for continuing conversations).
+   */
+  generateWithState(options: {
+    prompt: string;
+    state: DeepAgentState;
+    maxSteps?: number;
+  }): Promise<ai0.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$1<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
+//#region src/backends/state.d.ts
+/**
+ * Backend that stores files in shared state (ephemeral).
+ *
+ * Files persist within a single agent invocation but not across invocations.
+ * This is the default backend for Deep Agent when no backend is specified.
+ *
+ * Files are stored in memory as part of the `DeepAgentState`, making this backend
+ * fast but non-persistent. Use `FilesystemBackend` or `PersistentBackend` for
+ * cross-session persistence.
+ *
+ * @example Default usage (no backend specified)
+ * ```typescript
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   // StateBackend is used by default
+ * });
+ * ```
+ *
+ * @example Explicit usage
+ * ```typescript
+ * const state: DeepAgentState = { todos: [], files: {} };
+ * const backend = new StateBackend(state);
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ */
+declare class StateBackend implements BackendProtocol {
+  private state;
+  /**
+   * Create a new StateBackend instance.
+   *
+   * @param state - The DeepAgentState object that will store the files.
+   *                Files are stored in `state.files` as a Record<string, FileData>.
+   */
+  constructor(state: DeepAgentState);
+  /**
+   * Get files from current state.
+   */
+  private getFiles;
+  /**
+   * List files and directories in the specified directory (non-recursive).
+   */
+  lsInfo(path: string): FileInfo[];
+  /**
+   * Read file content with line numbers.
+   */
+  read(filePath: string, offset?: number, limit?: number): string;
+  /**
+   * Read file content as raw FileData.
+   */
+  readRaw(filePath: string): FileData;
+  /**
+   * Create a new file with content.
+   */
+  write(filePath: string, content: string): WriteResult;
+  /**
+   * Edit a file by replacing string occurrences.
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult;
+  /**
+   * Structured search results or error string for invalid input.
+   */
+  grepRaw(pattern: string, path?: string, glob?: string | null): GrepMatch[] | string;
+  /**
+   * Structured glob matching returning FileInfo objects.
+   */
+  globInfo(pattern: string, path?: string): FileInfo[];
+}
+//#endregion
+//#region src/backends/filesystem.d.ts
+/**
+ * Backend that reads and writes files directly from the filesystem.
+ *
+ * Files are persisted to disk, making them available across agent invocations.
+ * This backend provides real file I/O operations with security checks to prevent
+ * directory traversal attacks.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const backend = new FilesystemBackend({ rootDir: './workspace' });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ *
+ * @example With custom options
+ * ```typescript
+ * const backend = new FilesystemBackend({
+ *   rootDir: './my-project',
+ *   virtualMode: false,
+ *   maxFileSizeMb: 50, // Allow larger files
+ * });
+ * ```
+ */
+declare class FilesystemBackend implements BackendProtocol {
+  private cwd;
+  private virtualMode;
+  private maxFileSizeBytes;
+  /**
+   * Create a new FilesystemBackend instance.
+   *
+   * @param options - Configuration options
+   * @param options.rootDir - Optional root directory for file operations (default: current working directory).
+   *                          All file paths are resolved relative to this directory.
+   * @param options.virtualMode - Optional flag for virtual mode (default: false).
+   *                              When true, files are stored in memory but paths are validated against filesystem.
+   * @param options.maxFileSizeMb - Optional maximum file size in MB (default: 10).
+   *                                Files larger than this will be rejected.
+   */
+  constructor(options?: {
+    rootDir?: string;
+    virtualMode?: boolean;
+    maxFileSizeMb?: number;
+  });
+  /**
+   * Resolve a file path with security checks.
+   */
+  private resolvePath;
+  /**
+   * List files and directories in the specified directory (non-recursive).
+   */
+  lsInfo(dirPath: string): Promise<FileInfo[]>;
+  /**
+   * Read file content with line numbers.
+   */
+  read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   */
+  readRaw(filePath: string): Promise<FileData>;
+  /**
+   * Create a new file with content.
+   */
+  write(filePath: string, content: string): Promise<WriteResult>;
+  /**
+   * Edit a file by replacing string occurrences.
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+  /**
+   * Structured search results or error string for invalid input.
+   */
+  grepRaw(pattern: string, dirPath?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+  /**
+   * Try to use ripgrep for fast searching.
+   */
+  private ripgrepSearch;
+  /**
+   * Fallback regex search implementation.
+   */
+  private regexSearch;
+  /**
+   * Structured glob matching returning FileInfo objects.
+   */
+  globInfo(pattern: string, searchPath?: string): Promise<FileInfo[]>;
+}
+//#endregion
+//#region src/backends/composite.d.ts
+/**
+ * Backend that routes file operations to different backends based on path prefix.
+ *
+ * This enables hybrid storage strategies by routing files to different backends
+ * based on their path prefix. Useful for separating persistent and ephemeral storage,
+ * or using different storage backends for different types of files.
+ *
+ * @example Hybrid storage strategy
+ * ```typescript
+ * import { CompositeBackend, FilesystemBackend, StateBackend } from 'deepagentsdk';
+ *
+ * const state = { todos: [], files: {} };
+ * const backend = new CompositeBackend(
+ *   new StateBackend(state), // Default: ephemeral storage
+ *   {
+ *     '/persistent/': new FilesystemBackend({ rootDir: './persistent' }), // Persistent files
+ *     '/cache/': new StateBackend(state), // Cached files (ephemeral)
+ *   }
+ * );
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ *
+ * @example Multiple persistent backends
+ * ```typescript
+ * const backend = new CompositeBackend(
+ *   new FilesystemBackend({ rootDir: './default' }),
+ *   {
+ *     '/user-data/': new FilesystemBackend({ rootDir: './user-data' }),
+ *     '/system/': new FilesystemBackend({ rootDir: './system' }),
+ *   }
+ * );
+ * ```
+ */
+declare class CompositeBackend implements BackendProtocol {
+  private defaultBackend;
+  private routes;
+  private sortedRoutes;
+  /**
+   * Create a new CompositeBackend instance.
+   *
+   * @param defaultBackend - Backend to use for paths that don't match any route prefix
+   * @param routes - Record mapping path prefixes to backends.
+   *                 Routes are matched by longest prefix first.
+   *                 Example: `{ '/persistent/': filesystemBackend, '/cache/': stateBackend }`
+   */
+  constructor(defaultBackend: BackendProtocol, routes: Record<string, BackendProtocol>);
+  /**
+   * Determine which backend handles this key and strip prefix.
+   */
+  private getBackendAndKey;
+  /**
+   * List files and directories in the specified directory (non-recursive).
+   */
+  lsInfo(path: string): Promise<FileInfo[]>;
+  /**
+   * Read file content, routing to appropriate backend.
+   */
+  read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   */
+  readRaw(filePath: string): Promise<FileData>;
+  /**
+   * Structured search results or error string for invalid input.
+   */
+  grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+  /**
+   * Structured glob matching returning FileInfo objects.
+   */
+  globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+  /**
+   * Create a new file, routing to appropriate backend.
+   */
+  write(filePath: string, content: string): Promise<WriteResult>;
+  /**
+   * Edit a file, routing to appropriate backend.
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+}
+//#endregion
+//#region src/backends/persistent.d.ts
+/**
+ * Generic key-value store interface for persistent storage.
+ *
+ * Implement this interface to use any storage backend (Redis, SQLite, cloud storage, etc.)
+ * with PersistentBackend. The interface uses hierarchical namespaces for organization.
+ *
+ * @example Redis implementation
+ * ```typescript
+ * class RedisStore implements KeyValueStore {
+ *   constructor(private redis: RedisClient) {}
+ *
+ *   async get(namespace: string[], key: string) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     const data = await this.redis.get(redisKey);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async put(namespace: string[], key: string, value: Record<string, unknown>) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     await this.redis.set(redisKey, JSON.stringify(value));
+ *   }
+ *
+ *   async delete(namespace: string[], key: string) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     await this.redis.del(redisKey);
+ *   }
+ *
+ *   async list(namespace: string[]) {
+ *     const prefix = [...namespace].join(':') + ':';
+ *     const keys = await this.redis.keys(prefix + '*');
+ *     const results = [];
+ *     for (const key of keys) {
+ *       const data = await this.redis.get(key);
+ *       if (data) {
+ *         const relativeKey = key.substring(prefix.length);
+ *         results.push({ key: relativeKey, value: JSON.parse(data) });
+ *       }
+ *     }
+ *     return results;
+ *   }
+ * }
+ * ```
+ */
+interface KeyValueStore {
+  /**
+   * Get a value by key from the store.
+   * @param namespace - Hierarchical namespace array (e.g., ["project1", "filesystem"])
+   * @param key - The key to retrieve (file path in the case of PersistentBackend)
+   * @returns The stored value as a record, or undefined if not found
+   */
+  get(namespace: string[], key: string): Promise<Record<string, unknown> | undefined>;
+  /**
+   * Store a value by key in the store.
+   * @param namespace - Hierarchical namespace array
+   * @param key - The key to store (file path in the case of PersistentBackend)
+   * @param value - The value to store (must be serializable to JSON)
+   */
+  put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+  /**
+   * Delete a value by key from the store.
+   * @param namespace - Hierarchical namespace array
+   * @param key - The key to delete (file path in the case of PersistentBackend)
+   */
+  delete(namespace: string[], key: string): Promise<void>;
+  /**
+   * List all keys and values in a namespace.
+   * @param namespace - Hierarchical namespace array
+   * @returns Array of items with key and value pairs directly in this namespace
+   *          (not including sub-namespaces)
+   */
+  list(namespace: string[]): Promise<Array<{
+    key: string;
+    value: Record<string, unknown>;
+  }>>;
+}
+/**
+ * Simple in-memory implementation of KeyValueStore.
+ *
+ * Useful for testing or single-session persistence. Data is stored in a Map
+ * and does not persist across application restarts.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const store = new InMemoryStore();
+ * const backend = new PersistentBackend({ store });
+ * ```
+ *
+ * @example For testing
+ * ```typescript
+ * const store = new InMemoryStore();
+ * // ... run tests ...
+ * store.clear(); // Clean up after tests
+ * ```
+ */
+declare class InMemoryStore implements KeyValueStore {
+  private data;
+  private makeKey;
+  private parseKey;
+  get(namespace: string[], key: string): Promise<Record<string, unknown> | undefined>;
+  put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+  delete(namespace: string[], key: string): Promise<void>;
+  list(namespace: string[]): Promise<Array<{
+    key: string;
+    value: Record<string, unknown>;
+  }>>;
+  /**
+   * Clear all data (useful for testing).
+   */
+  clear(): void;
+  /**
+   * Get the number of stored items.
+   */
+  size(): number;
+}
+/**
+ * Options for creating a PersistentBackend.
+ */
+interface PersistentBackendOptions {
+  /**
+   * **Required.** The key-value store implementation to use.
+   *
+   * You can use the built-in `InMemoryStore` for testing, or implement `KeyValueStore`
+   * for custom storage (Redis, SQLite, etc.).
+   *
+   * @see {@link KeyValueStore} for the interface definition
+   * @see {@link InMemoryStore} for a simple in-memory implementation
+   */
+  store: KeyValueStore;
+  /**
+   * Optional namespace prefix for isolation (e.g., project ID, user ID).
+   *
+   * This allows multiple agents or projects to share the same store without conflicts.
+   * Files are stored under `[namespace]/filesystem/` in the key-value store.
+   *
+   * Default: "default"
+   */
+  namespace?: string;
+}
+/**
+ * Backend that stores files in a persistent key-value store.
+ *
+ * This provides cross-conversation file persistence that survives between agent sessions.
+ * Files are stored in the provided key-value store, allowing you to use any storage backend
+ * (Redis, SQLite, cloud storage, etc.) by implementing the `KeyValueStore` interface.
+ *
+ * @example Using InMemoryStore (for testing or single-session persistence)
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { PersistentBackend, InMemoryStore } from 'deepagentsdk';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const store = new InMemoryStore();
+ * const backend = new PersistentBackend({ store });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ *
+ * @example With custom namespace for project isolation
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { PersistentBackend, InMemoryStore } from 'deepagentsdk';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const store = new InMemoryStore();
+ * const backend = new PersistentBackend({
+ *   store,
+ *   namespace: 'project-123', // Isolate files for this project
+ * });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ *
+ * @example Custom KeyValueStore implementation (Redis)
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { PersistentBackend, type KeyValueStore } from 'deepagentsdk';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ * import { createClient } from 'redis';
+ *
+ * class RedisStore implements KeyValueStore {
+ *   constructor(private redis: ReturnType<typeof createClient>) {}
+ *
+ *   async get(namespace: string[], key: string) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     const data = await this.redis.get(redisKey);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async put(namespace: string[], key: string, value: Record<string, unknown>) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     await this.redis.set(redisKey, JSON.stringify(value));
+ *   }
+ *
+ *   async delete(namespace: string[], key: string) {
+ *     const redisKey = [...namespace, key].join(':');
+ *     await this.redis.del(redisKey);
+ *   }
+ *
+ *   async list(namespace: string[]) {
+ *     const prefix = [...namespace].join(':') + ':';
+ *     const keys = await this.redis.keys(prefix + '*');
+ *     const results = [];
+ *     for (const key of keys) {
+ *       const data = await this.redis.get(key);
+ *       if (data) {
+ *         const relativeKey = key.substring(prefix.length);
+ *         results.push({ key: relativeKey, value: JSON.parse(data) });
+ *       }
+ *     }
+ *     return results;
+ *   }
+ * }
+ *
+ * const redis = createClient();
+ * await redis.connect();
+ *
+ * const backend = new PersistentBackend({
+ *   store: new RedisStore(redis),
+ *   namespace: 'production'
+ * });
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   backend,
+ * });
+ * ```
+ */
+declare class PersistentBackend implements BackendProtocol {
+  private store;
+  private namespacePrefix;
+  /**
+   * Create a new PersistentBackend instance.
+   *
+   * @param options - Configuration options
+   * @param options.store - The key-value store implementation to use
+   * @param options.namespace - Optional namespace prefix for file isolation
+   */
+  constructor(options: PersistentBackendOptions);
+  /**
+   * Get the namespace for store operations.
+   */
+  protected getNamespace(): string[];
+  /**
+   * Convert a store value to FileData format.
+   */
+  private convertToFileData;
+  /**
+   * Convert FileData to a value suitable for store.put().
+   */
+  private convertFromFileData;
+  /**
+   * List files and directories in the specified directory (non-recursive).
+   */
+  lsInfo(path: string): Promise<FileInfo[]>;
+  /**
+   * Read file content with line numbers.
+   */
+  read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read file content as raw FileData.
+   */
+  readRaw(filePath: string): Promise<FileData>;
+  /**
+   * Create a new file with content.
+   */
+  write(filePath: string, content: string): Promise<WriteResult>;
+  /**
+   * Edit a file by replacing string occurrences.
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+  /**
+   * Structured search results or error string for invalid input.
+   */
+  grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+  /**
+   * Structured glob matching returning FileInfo objects.
+   */
+  globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+  /**
+   * Delete a file.
+   */
+  deleteFile(filePath: string): Promise<{
+    error?: string;
+  }>;
+}
+//#endregion
+//#region src/backends/sandbox.d.ts
+/**
+ * Abstract base class for sandbox backends.
+ *
+ * Implements all file operations using shell commands via execute().
+ * Subclasses only need to implement execute() and id.
+ *
+ * @example Creating a custom sandbox backend
+ * ```typescript
+ * class MyCloudSandbox extends BaseSandbox {
+ *   readonly id = 'my-cloud-123';
+ *
+ *   async execute(command: string): Promise<ExecuteResponse> {
+ *     // Call your cloud provider's API
+ *     const result = await myCloudApi.runCommand(command);
+ *     return {
+ *       output: result.stdout + result.stderr,
+ *       exitCode: result.exitCode,
+ *       truncated: false,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseSandbox implements SandboxBackendProtocol {
+  /**
+   * Execute a shell command in the sandbox.
+   * Must be implemented by subclasses.
+   */
+  abstract execute(command: string): Promise<ExecuteResponse>;
+  /**
+   * Unique identifier for this sandbox instance.
+   * Must be implemented by subclasses.
+   */
+  abstract readonly id: string;
+  /**
+   * List files and directories in a path.
+   */
+  lsInfo(path: string): Promise<FileInfo[]>;
+  /**
+   * Read file content with line numbers.
+   */
+  read(filePath: string, offset?: number, limit?: number): Promise<string>;
+  /**
+   * Read raw file data.
+   */
+  readRaw(filePath: string): Promise<FileData>;
+  /**
+   * Write content to a new file.
+   */
+  write(filePath: string, content: string): Promise<WriteResult>;
+  /**
+   * Edit a file by replacing string occurrences.
+   */
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+  /**
+   * Search for pattern in files.
+   */
+  grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
+  /**
+   * Find files matching glob pattern.
+   */
+  globInfo(pattern: string, path?: string): Promise<FileInfo[]>;
+}
+//#endregion
+//#region src/backends/local-sandbox.d.ts
+/**
+ * Options for LocalSandbox.
+ */
+interface LocalSandboxOptions {
+  /**
+   * Working directory for command execution.
+   * All file paths in sandbox operations are relative to this directory.
+   * @default process.cwd()
+   */
+  cwd?: string;
+  /**
+   * Timeout in milliseconds for command execution.
+   * Commands that exceed this timeout will be terminated.
+   * @default 30000 (30 seconds)
+   */
+  timeout?: number;
+  /**
+   * Additional environment variables to set for command execution.
+   * These are merged with the current process environment.
+   */
+  env?: Record<string, string>;
+  /**
+   * Maximum output size in bytes before truncation.
+   * @default 1048576 (1MB)
+   */
+  maxOutputSize?: number;
+}
+/**
+ * Local sandbox that executes commands using Node.js child_process.
+ *
+ * All commands are executed in a bash shell with the specified working directory.
+ * Inherits all file operations (read, write, edit, ls, grep, glob) from BaseSandbox.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { LocalSandbox } from 'deepagentsdk';
+ *
+ * const sandbox = new LocalSandbox({ cwd: './workspace' });
+ *
+ * // Execute commands
+ * const result = await sandbox.execute('ls -la');
+ * console.log(result.output);
+ *
+ * // File operations
+ * await sandbox.write('./src/index.ts', 'console.log("hello")');
+ * const content = await sandbox.read('./src/index.ts');
+ * ```
+ *
+ * @example With timeout and environment
+ * ```typescript
+ * const sandbox = new LocalSandbox({
+ *   cwd: './workspace',
+ *   timeout: 60000, // 60 seconds
+ *   env: {
+ *     NODE_ENV: 'development',
+ *     DEBUG: '*',
+ *   },
+ * });
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const result = await sandbox.execute('npm test');
+ * if (result.exitCode !== 0) {
+ *   console.error('Tests failed:', result.output);
+ * }
+ * ```
+ */
+declare class LocalSandbox extends BaseSandbox {
+  private readonly cwd;
+  private readonly timeout;
+  private readonly env;
+  private readonly maxOutputSize;
+  private readonly _id;
+  /**
+   * Create a new LocalSandbox instance.
+   *
+   * @param options - Configuration options for the sandbox
+   */
+  constructor(options?: LocalSandboxOptions);
+  /**
+   * Unique identifier for this sandbox instance.
+   * Format: `local-{timestamp}-{random}`
+   */
+  get id(): string;
+  /**
+   * Execute a shell command in the local filesystem.
+   *
+   * Commands are executed using bash with the configured working directory
+   * and environment variables. Output is captured from both stdout and stderr.
+   *
+   * @param command - Shell command to execute
+   * @returns ExecuteResponse with output, exit code, and truncation status
+   *
+   * @example
+   * ```typescript
+   * const result = await sandbox.execute('echo "Hello" && ls -la');
+   * console.log(result.output);
+   * console.log('Exit code:', result.exitCode);
+   * ```
+   */
+  execute(command: string): Promise<ExecuteResponse>;
+}
+//#endregion
+//#region src/tools/subagent.d.ts
+/**
+ * Options for creating the subagent tool.
+ */
+interface CreateSubagentToolOptions {
+  /** Default model for subagents (AI SDK LanguageModel instance) */
+  defaultModel: LanguageModel;
+  /** Default tools available to all subagents */
+  defaultTools?: ToolSet;
+  /** List of custom subagent specifications */
+  subagents?: SubAgent[];
+  /** Whether to include the general-purpose agent */
+  includeGeneralPurposeAgent?: boolean;
+  /** Backend for filesystem operations */
+  backend?: BackendProtocol | BackendFactory;
+  /** Custom description for the task tool */
+  taskDescription?: string | null;
+  /** Optional callback for emitting events */
+  onEvent?: EventCallback;
+  /** Interrupt config to pass to subagents */
+  interruptOn?: InterruptOnConfig;
+  /** Parent agent options to pass through to subagents */
+  parentGenerationOptions?: CreateDeepAgentParams["generationOptions"];
+  parentAdvancedOptions?: CreateDeepAgentParams["advancedOptions"];
+}
+/**
+ * Create the task tool for spawning subagents using ToolLoopAgent.
+ */
+declare function createSubagentTool(state: DeepAgentState, options: CreateSubagentToolOptions): ai0.Tool<{
+  description: string;
+  subagent_type: string;
+}, string>;
+//#endregion
+//#region src/prompts.d.ts
+/**
+ * System prompts for Deep Agent.
+ */
+declare const BASE_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
+declare const TODO_SYSTEM_PROMPT = "## `write_todos` (task planning)\n\nYou have access to a `write_todos` tool to help you manage and plan tasks. Use this tool whenever you are working on a complex task.\n\n### When to Use This Tool\n\nUse proactively for:\n1. Complex multi-step tasks (3+ distinct steps)\n2. Non-trivial tasks requiring careful planning\n3. After receiving new instructions - capture requirements as todos\n4. After completing tasks - mark complete and add follow-ups\n5. When starting new tasks - mark as in_progress (ideally only one at a time)\n\n### When NOT to Use\n\nSkip for:\n1. Single, straightforward tasks\n2. Trivial tasks with no organizational benefit\n3. Tasks completable in < 3 trivial steps\n4. Purely conversational/informational requests\n\n### Task States and Management\n\n1. **Task States:**\n  - pending: Not yet started\n  - in_progress: Currently working on\n  - completed: Finished successfully\n  - cancelled: No longer needed\n\n2. **Task Management:**\n  - Update status in real-time\n  - Mark complete IMMEDIATELY after finishing\n  - Only ONE task in_progress at a time\n  - Complete current tasks before starting new ones";
+declare const FILESYSTEM_SYSTEM_PROMPT = "## Virtual Filesystem\n\nYou have access to a virtual filesystem. All file paths must start with a /.\n\n- ls: list files in a directory (requires absolute path)\n- read_file: read a file from the filesystem\n- write_file: write to a file in the filesystem\n- edit_file: edit a file in the filesystem\n- glob: find files matching a pattern (e.g., \"**/*.py\")\n- grep: search for text within files";
+declare const TASK_SYSTEM_PROMPT = "## `task` (subagent spawner)\n\nYou have access to a `task` tool to launch short-lived subagents that handle isolated tasks. These agents are ephemeral \u2014 they live only for the duration of the task and return a single result.\n\nWhen to use the task tool:\n- When a task is complex and multi-step, and can be fully delegated in isolation\n- When a task is independent of other tasks and can run in parallel\n- When a task requires focused reasoning or heavy token/context usage that would bloat the orchestrator thread\n- When sandboxing improves reliability (e.g. code execution, structured searches, data formatting)\n- When you only care about the output of the subagent, and not the intermediate steps\n\nSubagent lifecycle:\n1. **Spawn** \u2192 Provide clear role, instructions, and expected output\n2. **Run** \u2192 The subagent completes the task autonomously\n3. **Return** \u2192 The subagent provides a single structured result\n4. **Reconcile** \u2192 Incorporate or synthesize the result into the main thread\n\nWhen NOT to use the task tool:\n- If you need to see the intermediate reasoning or steps after the subagent has completed (the task tool hides them)\n- If the task is trivial (a few tool calls or simple lookup)\n- If delegating does not reduce token usage, complexity, or context switching\n- If splitting would add latency without benefit\n\n## Important Task Tool Usage Notes\n- Whenever possible, parallelize the work that you do. Whenever you have independent steps to complete - kick off tasks (subagents) in parallel to accomplish them faster.\n- Remember to use the `task` tool to silo independent tasks within a multi-part objective.\n- You should use the `task` tool whenever you have a complex task that will take multiple steps, and is independent from other tasks that the agent needs to complete.";
+/**
+ * Get the task tool description with available subagent types.
+ */
+declare function getTaskToolDescription(subagentDescriptions: string[]): string;
+declare const DEFAULT_GENERAL_PURPOSE_DESCRIPTION = "General-purpose agent for researching complex questions, searching for files and content, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. This agent has access to all tools as the main agent.";
+declare const DEFAULT_SUBAGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools.";
+declare const EXECUTE_SYSTEM_PROMPT = "## `execute` (shell command execution)\n\nYou have access to an `execute` tool to run shell commands in the sandbox environment.\n\n### When to Use This Tool\n\nUse for:\n- Running build commands (npm install, npm run build, bun install)\n- Running tests (npm test, bun test, pytest)\n- Executing scripts (node script.js, python script.py)\n- Installing dependencies\n- Checking system state (ls, cat, pwd, which)\n- Any shell command that helps accomplish the task\n\n### Important Notes\n\n1. **Exit Codes**: Always check the exit code to determine success\n   - 0 = success\n   - non-zero = failure\n   - null = possibly timed out\n\n2. **Command Chaining**:\n   - Use `&&` to chain commands that depend on each other\n   - Use `;` to run commands sequentially regardless of success\n\n3. **Timeouts**: Long-running commands may timeout\n\n4. **Working Directory**: Commands run in the sandbox's working directory";
+//#endregion
+//#region src/utils/patch-tool-calls.d.ts
+/**
+ * Patch dangling tool calls in a message array.
+ *
+ * Scans for assistant messages with tool_calls that don't have corresponding
+ * tool result messages, and adds synthetic "cancelled" responses.
+ *
+ * @param messages - Array of messages to patch
+ * @returns New array with patched messages (original array is not modified)
+ *
+ * @example
+ * ```typescript
+ * const messages = [
+ *   { role: "user", content: "Hello" },
+ *   { role: "assistant", content: [{ type: "tool-call", toolCallId: "1", toolName: "search" }] },
+ *   // Missing tool result for tool call "1"
+ *   { role: "user", content: "Never mind" },
+ * ];
+ *
+ * const patched = patchToolCalls(messages);
+ * // patched now includes a synthetic tool result for the dangling call
+ * ```
+ */
+declare function patchToolCalls(messages: ModelMessage[]): ModelMessage[];
+/**
+ * Check if messages have any dangling tool calls.
+ *
+ * @param messages - Array of messages to check
+ * @returns True if there are dangling tool calls
+ */
+declare function hasDanglingToolCalls(messages: ModelMessage[]): boolean;
+//#endregion
+//#region src/utils/eviction.d.ts
+/**
+ * Default token limit before evicting a tool result.
+ * Approximately 20,000 tokens (~80KB of text).
+ */
+declare const DEFAULT_EVICTION_TOKEN_LIMIT = 20000;
+/**
+ * Estimate the number of tokens in a string.
+ * Uses a simple character-based approximation.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Check if a tool result should be evicted based on size.
+ */
+declare function shouldEvict(result: string, tokenLimit?: number): boolean;
+/**
+ * Options for evicting a tool result.
+ */
+interface EvictOptions {
+  /** The tool result content */
+  result: string;
+  /** The tool call ID (used for filename) */
+  toolCallId: string;
+  /** The tool name */
+  toolName: string;
+  /** Backend to write the evicted content to */
+  backend: BackendProtocol;
+  /** Token limit before eviction (default: 20000) */
+  tokenLimit?: number;
+}
+/**
+ * Result of an eviction operation.
+ */
+interface EvictResult {
+  /** Whether the result was evicted */
+  evicted: boolean;
+  /** The content to return (either original or truncated message) */
+  content: string;
+  /** Path where content was evicted to (if evicted) */
+  evictedPath?: string;
+}
+/**
+ * Evict a large tool result to the filesystem.
+ *
+ * If the result exceeds the token limit, writes it to a file and
+ * returns a truncated message with the file path.
+ *
+ * @param options - Eviction options
+ * @returns Eviction result with content and metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await evictToolResult({
+ *   result: veryLongString,
+ *   toolCallId: "call_123",
+ *   toolName: "grep",
+ *   backend: filesystemBackend,
+ * });
+ *
+ * if (result.evicted) {
+ *   console.log(`Content saved to ${result.evictedPath}`);
+ * }
+ * ```
+ */
+declare function evictToolResult(options: EvictOptions): Promise<EvictResult>;
+/**
+ * Create a tool result wrapper that automatically evicts large results.
+ *
+ * @param backend - Backend or factory for filesystem operations
+ * @param state - Current agent state (for factory backends)
+ * @param tokenLimit - Token limit before eviction
+ * @returns Function that wraps tool results with eviction
+ */
+declare function createToolResultWrapper(backend: BackendProtocol | BackendFactory, state: DeepAgentState, tokenLimit?: number): (result: string, toolCallId: string, toolName: string) => Promise<string>;
+//#endregion
+//#region src/utils/summarization.d.ts
+/**
+ * Default token threshold before triggering summarization.
+ * 170k tokens is a safe threshold for most models.
+ */
+declare const DEFAULT_SUMMARIZATION_THRESHOLD = 170000;
+/**
+ * Default number of recent messages to keep intact.
+ */
+declare const DEFAULT_KEEP_MESSAGES = 6;
+/**
+ * Options for summarization.
+ */
+interface SummarizationOptions {
+  /** Model to use for summarization (AI SDK LanguageModel instance) */
+  model: LanguageModel;
+  /** Token threshold to trigger summarization (default: 170000) */
+  tokenThreshold?: number;
+  /** Number of recent messages to keep intact (default: 6) */
+  keepMessages?: number;
+  /** Generation options to pass through */
+  generationOptions?: any;
+  /** Advanced options to pass through */
+  advancedOptions?: any;
+}
+/**
+ * Result of summarization check.
+ */
+interface SummarizationResult {
+  /** Whether summarization was needed */
+  summarized: boolean;
+  /** The processed messages (either original or with summary) */
+  messages: ModelMessage$1[];
+  /** Token count before processing */
+  tokensBefore?: number;
+  /** Token count after processing */
+  tokensAfter?: number;
+}
+/**
+ * Estimate total tokens in a messages array.
+ */
+declare function estimateMessagesTokens(messages: ModelMessage$1[]): number;
+/**
+ * Summarize older messages when approaching token limits.
+ *
+ * This function checks if the total tokens in the messages exceed the threshold.
+ * If so, it summarizes older messages while keeping recent ones intact.
+ *
+ * @param messages - Array of conversation messages
+ * @param options - Summarization options
+ * @returns Processed messages with optional summary
+ *
+ * @example
+ * ```typescript
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const result = await summarizeIfNeeded(messages, {
+ *   model: anthropic('claude-haiku-4-5-20251001'),
+ *   tokenThreshold: 170000,
+ *   keepMessages: 6,
+ * });
+ *
+ * if (result.summarized) {
+ *   console.log(`Reduced from ${result.tokensBefore} to ${result.tokensAfter} tokens`);
+ * }
+ * ```
+ */
+declare function summarizeIfNeeded(messages: ModelMessage$1[], options: SummarizationOptions): Promise<SummarizationResult>;
+/**
+ * Check if messages need summarization without performing it.
+ */
+declare function needsSummarization(messages: ModelMessage$1[], tokenThreshold?: number): boolean;
+//#endregion
+//#region src/checkpointer/memory-saver.d.ts
+/**
+ * In-memory checkpoint saver.
+ *
+ * Stores checkpoints in a Map. Data is lost when the process exits.
+ * Useful for testing or single-session applications.
+ *
+ * @example
+ * ```typescript
+ * const saver = new MemorySaver();
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   checkpointer: saver,
+ * });
+ * ```
+ */
+declare class MemorySaver implements BaseCheckpointSaver {
+  private checkpoints;
+  private namespace;
+  constructor(options?: CheckpointSaverOptions);
+  private getKey;
+  save(checkpoint: Checkpoint): Promise<void>;
+  load(threadId: string): Promise<Checkpoint | undefined>;
+  list(): Promise<string[]>;
+  delete(threadId: string): Promise<void>;
+  exists(threadId: string): Promise<boolean>;
+  /**
+   * Clear all checkpoints (useful for testing).
+   */
+  clear(): void;
+  /**
+   * Get the number of stored checkpoints.
+   */
+  size(): number;
+}
+//#endregion
+//#region src/checkpointer/file-saver.d.ts
+/**
+ * Options for FileSaver.
+ */
+interface FileSaverOptions {
+  /** Directory to store checkpoint files */
+  dir: string;
+}
+/**
+ * File-based checkpoint saver.
+ *
+ * Stores checkpoints as JSON files in a directory. Each thread gets
+ * its own file named `{threadId}.json`.
+ *
+ * @example
+ * ```typescript
+ * const saver = new FileSaver({ dir: './.checkpoints' });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   checkpointer: saver,
+ * });
+ * ```
+ */
+declare class FileSaver implements BaseCheckpointSaver {
+  private dir;
+  constructor(options: FileSaverOptions);
+  private getFilePath;
+  save(checkpoint: Checkpoint): Promise<void>;
+  load(threadId: string): Promise<Checkpoint | undefined>;
+  list(): Promise<string[]>;
+  delete(threadId: string): Promise<void>;
+  exists(threadId: string): Promise<boolean>;
+}
+//#endregion
+//#region src/checkpointer/kv-saver.d.ts
+/**
+ * Options for KeyValueStoreSaver.
+ */
+interface KeyValueStoreSaverOptions extends CheckpointSaverOptions {
+  /** The KeyValueStore implementation to use */
+  store: KeyValueStore;
+}
+/**
+ * Checkpoint saver using KeyValueStore interface.
+ *
+ * This adapter allows using any KeyValueStore implementation (Redis,
+ * database, cloud storage, etc.) for checkpoint storage.
+ *
+ * @example
+ * ```typescript
+ * import { InMemoryStore } from 'deepagentsdk';
+ *
+ * const store = new InMemoryStore();
+ * const saver = new KeyValueStoreSaver({ store });
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   checkpointer: saver,
+ * });
+ * ```
+ *
+ * @example With Redis
+ * ```typescript
+ * const redisStore = new RedisStore(redisClient); // Your implementation
+ * const saver = new KeyValueStoreSaver({ store: redisStore });
+ * ```
+ */
+declare class KeyValueStoreSaver implements BaseCheckpointSaver {
+  private store;
+  private namespace;
+  constructor(options: KeyValueStoreSaverOptions);
+  save(checkpoint: Checkpoint): Promise<void>;
+  load(threadId: string): Promise<Checkpoint | undefined>;
+  list(): Promise<string[]>;
+  delete(threadId: string): Promise<void>;
+  exists(threadId: string): Promise<boolean>;
+}
+//#endregion
+//#region src/skills/types.d.ts
+/**
+ * Metadata extracted from SKILL.md frontmatter.
+ */
+interface SkillMetadata {
+  /**
+   * Unique skill name (kebab-case, e.g., 'web-research')
+   */
+  name: string;
+  /**
+   * Short description of what the skill does
+   */
+  description: string;
+  /**
+   * Absolute path to the SKILL.md file
+   */
+  path: string;
+  /**
+   * Source of the skill ('user' or 'project')
+   * Project skills override user skills with same name
+   */
+  source: 'user' | 'project';
+}
+/**
+ * Options for skill loading
+ */
+interface SkillLoadOptions {
+  /**
+   * User-level skills directory (e.g., ~/.deepagents/skills/)
+   */
+  userSkillsDir?: string;
+  /**
+   * Project-level skills directory (e.g., ./.deepagents/skills/)
+   */
+  projectSkillsDir?: string;
+  /**
+   * Optional agent ID for loading agent-specific skills.
+   * When provided, looks for skills in ~/.deepagents/{agentId}/skills/
+   * and .deepagents/skills/ (project-level, shared across agents).
+   */
+  agentId?: string;
+  /**
+   * Optional working directory for detecting project root.
+   * Only used when agentId is provided.
+   */
+  workingDirectory?: string;
+}
+//#endregion
+//#region src/skills/load.d.ts
+/**
+ * Parse YAML frontmatter from a SKILL.md file.
+ *
+ * Expected format:
+ * ---
+ * name: skill-name
+ * description: What this skill does
+ * ---
+ *
+ * # Skill Content
+ * ...
+ */
+declare function parseSkillMetadata(skillMdPath: string, source: 'user' | 'project'): Promise<SkillMetadata | null>;
+/**
+ * List all skills from user and project directories.
+ * Project skills override user skills with the same name.
+ *
+ * Supports two modes:
+ * 1. Legacy mode: Use userSkillsDir and projectSkillsDir directly (deprecated)
+ * 2. Agent mode: Use agentId to load from ~/.deepagents/{agentId}/skills/ and .deepagents/skills/
+ */
+declare function listSkills(options: SkillLoadOptions): Promise<SkillMetadata[]>;
+//#endregion
+//#region src/middleware/agent-memory.d.ts
+/**
+ * Configuration options for agent memory middleware.
+ */
+interface AgentMemoryOptions$1 {
+  /**
+   * Unique identifier for the agent (e.g., "code-architect", "research-agent").
+   * Used to locate agent-specific memory at ~/.deepagents/{agentId}/agent.md
+   */
+  agentId: string;
+  /**
+   * Optional working directory for project-level memory detection.
+   * Defaults to process.cwd().
+   */
+  workingDirectory?: string;
+  /**
+   * Optional custom path for user-level .deepagents directory.
+   * Defaults to os.homedir() + '/.deepagents'.
+   *
+   * Useful for testing or custom deployment environments.
+   *
+   * @example
+   * ```typescript
+   * userDeepagentsDir: '/custom/path/.deepagents'
+   * // Will look for memory at: /custom/path/.deepagents/{agentId}/agent.md
+   * ```
+   */
+  userDeepagentsDir?: string;
+  /**
+   * Optional callback to request user approval for creating project-level .deepagents/ directory.
+   * If not provided, project memory will be silently skipped if directory doesn't exist.
+   *
+   * @param projectPath - Absolute path to the detected git root
+   * @returns Promise<boolean> - true if user approves, false otherwise
+   */
+  requestProjectApproval?: (projectPath: string) => Promise<boolean>;
+}
+/**
+ * Create agent memory middleware for AI SDK v6.
+ *
+ * This middleware loads agent memory from:
+ * 1. User-level: ~/.deepagents/{agentId}/agent.md (personality, preferences)
+ * 2. Project-level: [git-root]/.deepagents/agent.md (project-specific context)
+ * 3. Additional files: Any other .md files in the user-level directory
+ *
+ * The memory is injected into the system prompt before each model call, teaching
+ * the agent when and how to read/update its own memory using filesystem tools.
+ *
+ * @param options - Configuration for agent memory
+ * @param options.agentId - Unique identifier for the agent (e.g., "code-architect")
+ * @param options.workingDirectory - Optional working directory for project detection (defaults to process.cwd())
+ * @param options.userDeepagentsDir - Optional custom path for user-level .deepagents directory (defaults to ~/.deepagents)
+ * @param options.requestProjectApproval - Optional callback to request approval before creating project .deepagents/ directory
+ * @returns AI SDK v6 middleware
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { createDeepAgent } from 'deepagentsdk';
+ * import { createAgentMemoryMiddleware } from 'deepagentsdk/middleware';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ *
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ * });
+ *
+ * const agent = createDeepAgent({
+ *   model: anthropic('claude-sonnet-4-5'),
+ *   middleware: memoryMiddleware,
+ * });
+ * ```
+ *
+ * @example With project approval callback
+ * ```typescript
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ *   requestProjectApproval: async (projectPath) => {
+ *     console.log(`Create .deepagents/ in ${projectPath}? (y/n)`);
+ *     // ... get user input
+ *     return userSaidYes;
+ *   }
+ * });
+ * ```
+ *
+ * @example With custom user directory path
+ * ```typescript
+ * const memoryMiddleware = createAgentMemoryMiddleware({
+ *   agentId: 'code-architect',
+ *   userDeepagentsDir: '/custom/path/.deepagents',
+ *   // Memory will be loaded from:
+ *   // - /custom/path/.deepagents/code-architect/agent.md
+ *   // - [git-root]/.deepagents/agent.md (project-level)
+ * });
+ * ```
+ */
+declare function createAgentMemoryMiddleware(options: AgentMemoryOptions$1): LanguageModelMiddleware$1;
+//#endregion
+//#region src/utils/project-detection.d.ts
+/**
+ * Find the git root by walking up the directory tree.
+ * Returns null if no .git directory is found.
+ *
+ * @param startPath - Starting directory (defaults to process.cwd())
+ * @returns Absolute path to git root, or null if not in a git repository
+ */
+declare function findGitRoot(startPath?: string): Promise<string | null>;
+//#endregion
+export { type AgentMemoryOptions, type ApprovalRequestedEvent, type ApprovalResponseEvent, BASE_PROMPT, type BackendFactory, type BackendProtocol, BaseCheckpointSaver, BaseSandbox, Checkpoint, type CheckpointLoadedEvent, type CheckpointSavedEvent, CheckpointSaverOptions, CompositeBackend, type CreateDeepAgentParams, type CreateExecuteToolOptions, type CreateSubagentToolOptions, type CreateWebToolsOptions, DEFAULT_EVICTION_TOKEN_LIMIT, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_KEEP_MESSAGES, DEFAULT_SUBAGENT_PROMPT, DEFAULT_SUMMARIZATION_THRESHOLD, DeepAgent, type DeepAgentEvent, type DeepAgentState, type DoneEvent, type DynamicApprovalConfig, EXECUTE_SYSTEM_PROMPT, type EditResult, type ErrorEvent, type EventCallback, type EvictOptions, type EvictResult, type ExecuteFinishEvent, type ExecuteResponse, type ExecuteStartEvent, FILESYSTEM_SYSTEM_PROMPT, type FetchUrlFinishEvent, type FetchUrlStartEvent, type FileData, type FileEditedEvent, type FileInfo, FileSaver, FileSaverOptions, type FileWriteStartEvent, type FileWrittenEvent, FilesystemBackend, type GrepMatch, type HttpRequestFinishEvent, type HttpRequestStartEvent, InMemoryStore, InterruptData, type InterruptOnConfig, type KeyValueStore, KeyValueStoreSaver, KeyValueStoreSaverOptions, type LanguageModelMiddleware, LocalSandbox, type LocalSandboxOptions, MemorySaver, PersistentBackend, type PersistentBackendOptions, ResumeDecision, ResumeOptions, type SandboxBackendProtocol, type SkillLoadOptions, type SkillMetadata, StateBackend, type StepFinishEvent, type StepStartEvent, type StructuredAgentResult, type SubAgent, type SubagentFinishEvent, type SubagentStartEvent, type SummarizationConfig, type SummarizationOptions, type SummarizationResult, TASK_SYSTEM_PROMPT, TODO_SYSTEM_PROMPT, type TextEvent, type TodoItem, type TodosChangedEvent, type ToolCallEvent, ToolLoopAgent, type ToolResultEvent, type WebSearchFinishEvent, type WebSearchStartEvent, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createEditFileTool, createExecuteTool, createExecuteToolFromBackend, createFetchUrlTool, createFilesystemTools, createGlobTool, createGrepTool, createHttpRequestTool, createLsTool, createReadFileTool, createSubagentTool, createTodosTool, createToolResultWrapper, createWebSearchTool, createWebTools, createWriteFileTool, edit_file, estimateMessagesTokens, estimateTokens, eventHasStructuredOutput, evictToolResult, execute, fetch_url, findGitRoot, getEventOutput, getStructuredOutput, getTaskToolDescription, glob, grep, hasDanglingToolCalls, hasStructuredOutput, hasToolCall, htmlToMarkdown, http_request, isSandboxBackend, listSkills, ls, needsSummarization, parseSkillMetadata, patchToolCalls, read_file, shouldEvict, stepCountIs, summarizeIfNeeded, web_search, wrapLanguageModel, write_file, write_todos };
+//# sourceMappingURL=index.d.cts.map