deepagents 1.6.2 → 1.7.0

package/dist/index.d.cts

@@ -1,17 +1,17 @@
 import * as zod_v30 from "zod/v3";
-import * as langchain9 from "langchain";
+import * as langchain from "langchain";
 import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, InferMiddlewareStates, InterruptOnConfig, ReactAgent, ResponseFormat, ResponseFormatUndefined, StructuredTool, SystemMessage, ToolMessage } from "langchain";
-import * as _Command from "@langchain/langgraph";
+import * as _langchain_langgraph0 from "@langchain/langgraph";
 import { AnnotationRoot, Command, ReducedValue, StateSchema } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
 import * as _messages from "@langchain/core/messages";
-import * as zod0 from "zod";
+import * as zod from "zod";
 import { z as z$1 } from "zod";
 import * as zod_v4_core0 from "zod/v4/core";
 import * as _langchain_core_language_models_base0 from "@langchain/core/language_models/base";
 import { BaseLanguageModel, LanguageModelLike } from "@langchain/core/language_models/base";
-import * as _langchain_core_tools1 from "@langchain/core/tools";
+import * as _langchain_core_tools0 from "@langchain/core/tools";
 import { ClientTool, ServerTool, StructuredTool as StructuredTool$1 } from "@langchain/core/tools";
 import { Runnable } from "@langchain/core/runnables";
 import "@langchain/core/language_models/chat_models";
@@ -252,6 +252,214 @@ interface SandboxBackendProtocol extends BackendProtocol {
  * @returns True if the backend implements SandboxBackendProtocol
  */
 declare function isSandboxBackend(backend: BackendProtocol): backend is SandboxBackendProtocol;
+/**
+ * Metadata for a single sandbox instance.
+ *
+ * This lightweight structure is returned from list operations and provides
+ * basic information about a sandbox without requiring a full connection.
+ *
+ * @typeParam MetadataT - Type of the metadata field. Providers can define
+ *   their own interface for type-safe metadata access.
+ *
+ * @example
+ * ```typescript
+ * // Using default metadata type
+ * const info: SandboxInfo = {
+ *   sandboxId: "sb_abc123",
+ *   metadata: { status: "running", createdAt: "2024-01-15T10:30:00Z" },
+ * };
+ *
+ * // Using typed metadata
+ * interface MyMetadata {
+ *   status: "running" | "stopped";
+ *   createdAt: string;
+ * }
+ * const typedInfo: SandboxInfo<MyMetadata> = {
+ *   sandboxId: "sb_abc123",
+ *   metadata: { status: "running", createdAt: "2024-01-15T10:30:00Z" },
+ * };
+ * ```
+ */
+interface SandboxInfo<MetadataT = Record<string, unknown>> {
+  /** Unique identifier for the sandbox instance */
+  sandboxId: string;
+  /** Optional provider-specific metadata (e.g., creation time, status, template) */
+  metadata?: MetadataT;
+}
+/**
+ * Paginated response from a sandbox list operation.
+ *
+ * This structure supports cursor-based pagination for efficiently browsing
+ * large collections of sandboxes.
+ *
+ * @typeParam MetadataT - Type of the metadata field in SandboxInfo items.
+ *
+ * @example
+ * ```typescript
+ * const response: SandboxListResponse = {
+ *   items: [
+ *     { sandboxId: "sb_001", metadata: { status: "running" } },
+ *     { sandboxId: "sb_002", metadata: { status: "stopped" } },
+ *   ],
+ *   cursor: "eyJvZmZzZXQiOjEwMH0=",
+ * };
+ *
+ * // Fetch next page
+ * const nextResponse = await provider.list({ cursor: response.cursor });
+ * ```
+ */
+interface SandboxListResponse<MetadataT = Record<string, unknown>> {
+  /** List of sandbox metadata objects for the current page */
+  items: SandboxInfo<MetadataT>[];
+  /**
+   * Opaque continuation token for retrieving the next page.
+   * null indicates no more pages available.
+   */
+  cursor: string | null;
+}
+/**
+ * Options for listing sandboxes.
+ */
+interface SandboxListOptions {
+  /**
+   * Continuation token from a previous list() call.
+   * Pass undefined to start from the beginning.
+   */
+  cursor?: string;
+}
+/**
+ * Options for getting or creating a sandbox.
+ */
+interface SandboxGetOrCreateOptions {
+  /**
+   * Unique identifier of an existing sandbox to retrieve.
+   * If undefined, creates a new sandbox instance.
+   * If provided but the sandbox doesn't exist, an error will be thrown.
+   */
+  sandboxId?: string;
+}
+/**
+ * Options for deleting a sandbox.
+ */
+interface SandboxDeleteOptions {
+  /** Unique identifier of the sandbox to delete */
+  sandboxId: string;
+}
+/**
+ * Abstract interface for sandbox provider implementations.
+ *
+ * Defines the lifecycle management interface for sandbox providers. Implementations
+ * should integrate with their respective SDKs to provide standardized sandbox
+ * lifecycle operations (list, getOrCreate, delete).
+ *
+ * This interface separates lifecycle management from sandbox execution:
+ * - `SandboxProvider` handles lifecycle (list, create, delete)
+ * - `SandboxBackendProtocol` handles execution (execute, file operations)
+ *
+ * @typeParam MetadataT - Type of the metadata field in sandbox listings.
+ *   Providers can define their own interface for type-safe metadata access.
+ *
+ * @example
+ * ```typescript
+ * interface MyMetadata {
+ *   status: "running" | "stopped";
+ *   template: string;
+ * }
+ *
+ * class MySandboxProvider implements SandboxProvider<MyMetadata> {
+ *   async list(options?: SandboxListOptions): Promise<SandboxListResponse<MyMetadata>> {
+ *     // Query provider API
+ *     return { items: [...], cursor: null };
+ *   }
+ *
+ *   async getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol> {
+ *     if (options?.sandboxId) {
+ *       return this.get(options.sandboxId);
+ *     }
+ *     return this.create();
+ *   }
+ *
+ *   async delete(options: SandboxDeleteOptions): Promise<void> {
+ *     // Idempotent - no error if already deleted
+ *     await this.client.delete(options.sandboxId);
+ *   }
+ * }
+ *
+ * // Usage
+ * const provider = new MySandboxProvider();
+ * const sandbox = await provider.getOrCreate();
+ * const result = await sandbox.execute("echo hello");
+ * await provider.delete({ sandboxId: sandbox.id });
+ * ```
+ */
+interface SandboxProvider<MetadataT = Record<string, unknown>> {
+  /**
+   * List available sandboxes with optional pagination.
+   *
+   * @param options - Optional list options including cursor for pagination
+   * @returns Paginated list of sandbox metadata
+   *
+   * @example
+   * ```typescript
+   * // First page
+   * const response = await provider.list();
+   * for (const sandbox of response.items) {
+   *   console.log(sandbox.sandboxId);
+   * }
+   *
+   * // Next page if available
+   * if (response.cursor) {
+   *   const nextPage = await provider.list({ cursor: response.cursor });
+   * }
+   * ```
+   */
+  list(options?: SandboxListOptions): Promise<SandboxListResponse<MetadataT>>;
+  /**
+   * Get an existing sandbox or create a new one.
+   *
+   * If sandboxId is provided, retrieves the existing sandbox. If the sandbox
+   * doesn't exist, throws an error (does NOT create a new one).
+   *
+   * If sandboxId is undefined, creates a new sandbox instance.
+   *
+   * @param options - Optional options including sandboxId to retrieve
+   * @returns A sandbox instance implementing SandboxBackendProtocol
+   * @throws Error if sandboxId is provided but the sandbox doesn't exist
+   *
+   * @example
+   * ```typescript
+   * // Create a new sandbox
+   * const sandbox = await provider.getOrCreate();
+   * console.log(sandbox.id); // "sb_new123"
+   *
+   * // Reconnect to existing sandbox
+   * const existing = await provider.getOrCreate({ sandboxId: "sb_new123" });
+   *
+   * // Use the sandbox
+   * const result = await sandbox.execute("node --version");
+   * ```
+   */
+  getOrCreate(options?: SandboxGetOrCreateOptions): Promise<SandboxBackendProtocol>;
+  /**
+   * Delete a sandbox instance.
+   *
+   * This permanently destroys the sandbox and all its associated data.
+   * The operation is idempotent - calling delete on a non-existent sandbox
+   * should succeed without raising an error.
+   *
+   * @param options - Options including the sandboxId to delete
+   *
+   * @example
+   * ```typescript
+   * // Simple deletion
+   * await provider.delete({ sandboxId: "sb_123" });
+   *
+   * // Safe to call multiple times (idempotent)
+   * await provider.delete({ sandboxId: "sb_123" }); // No error
+   * ```
+   */
+  delete(options: SandboxDeleteOptions): Promise<void>;
+}
 /**
  * State and store container for backend initialization.
  *
@@ -314,13 +522,13 @@ interface FilesystemMiddlewareOptions {
  */
 declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOptions): AgentMiddleware<StateSchema<{
   files: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
-}>, undefined, unknown, (langchain9.DynamicStructuredTool<z.ZodObject<{
+}>, undefined, unknown, (langchain.DynamicStructuredTool<z.ZodObject<{
   path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>, {
   path: string;
 }, {
   path?: string | undefined;
-}, string, "ls"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string, "ls"> | langchain.DynamicStructuredTool<z.ZodObject<{
   file_path: z.ZodString;
   offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
   limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
@@ -332,7 +540,7 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
   file_path: string;
   offset?: unknown;
   limit?: unknown;
-}, string, "read_file"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string, "read_file"> | langchain.DynamicStructuredTool<z.ZodObject<{
   file_path: z.ZodString;
   content: z.ZodString;
 }, z.core.$strip>, {
@@ -344,7 +552,7 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
 }, string | ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | Command<unknown, {
   files: Record<string, FileData>;
   messages: ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "write_file"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string>, "write_file"> | langchain.DynamicStructuredTool<z.ZodObject<{
   file_path: z.ZodString;
   old_string: z.ZodString;
   new_string: z.ZodString;
@@ -362,7 +570,7 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
 }, string | ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | Command<unknown, {
   files: Record<string, FileData>;
   messages: ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "edit_file"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string>, "edit_file"> | langchain.DynamicStructuredTool<z.ZodObject<{
   pattern: z.ZodString;
   path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>, {
@@ -371,7 +579,7 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
 }, {
   pattern: string;
   path?: string | undefined;
-}, string, "glob"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string, "glob"> | langchain.DynamicStructuredTool<z.ZodObject<{
   pattern: z.ZodString;
   path: z.ZodDefault<z.ZodOptional<z.ZodString>>;
   glob: z.ZodNullable<z.ZodOptional<z.ZodString>>;
@@ -383,7 +591,7 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
   pattern: string;
   path?: string | undefined;
   glob?: string | null | undefined;
-}, string, "grep"> | langchain9.DynamicStructuredTool<z.ZodObject<{
+}, string, "grep"> | langchain.DynamicStructuredTool<z.ZodObject<{
   command: z.ZodString;
 }, z.core.$strip>, {
   command: string;
@@ -392,6 +600,30 @@ declare function createFilesystemMiddleware(options?: FilesystemMiddlewareOption
 }, string, "execute">)[]>;
 //#endregion
 //#region src/middleware/subagents.d.ts
+/**
+ * Default system prompt for subagents.
+ * Provides a minimal base prompt that can be extended by specific subagent configurations.
+ */
+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.";
+/**
+ * Default description for the general-purpose subagent.
+ * This description is shown to the model when selecting which subagent to use.
+ */
+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.";
+/**
+ * System prompt section that explains how to use the task tool for spawning subagents.
+ *
+ * This prompt is automatically appended to the main agent's system prompt when
+ * using `createSubAgentMiddleware`. It provides guidance on:
+ * - When to use the task tool
+ * - Subagent lifecycle (spawn → run → return → reconcile)
+ * - When NOT to use the task tool
+ * - Best practices for parallel task execution
+ *
+ * You can provide a custom `systemPrompt` to `createSubAgentMiddleware` to override
+ * or extend this default.
+ */
+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 (ex. performing a lot of research and then returned a synthesized report, performing a series of computations or lookups to achieve a concise, relevant answer.)\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 to Remember\n- Whenever possible, parallelize the work that you do. This is true for both tool_calls, and for tasks. Whenever you have independent steps to complete - make tool_calls, or kick off tasks (subagents) in parallel to accomplish them faster. This saves time for the user, which is incredibly important.\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. These agents are highly competent and efficient.";
 /**
  * Type definitions for pre-compiled agents.
  *
@@ -407,24 +639,110 @@ interface CompiledSubAgent<TRunnable extends ReactAgent | Runnable = ReactAgent
   runnable: TRunnable;
 }
 /**
- * Type definitions for subagents
+ * Specification for a subagent that can be dynamically created.
+ *
+ * When using `createDeepAgent`, subagents automatically receive a default middleware
+ * stack (todoListMiddleware, filesystemMiddleware, summarizationMiddleware, etc.) before
+ * any custom `middleware` specified in this spec.
+ *
+ * Required fields:
+ * - `name`: Identifier used to select this subagent in the task tool
+ * - `description`: Shown to the model for subagent selection
+ * - `systemPrompt`: The system prompt for the subagent
+ *
+ * Optional fields:
+ * - `model`: Override the default model for this subagent
+ * - `tools`: Override the default tools for this subagent
+ * - `middleware`: Additional middleware appended after defaults
+ * - `interruptOn`: Human-in-the-loop configuration for specific tools
+ * - `skills`: Skill source paths for SkillsMiddleware (e.g., `["/skills/user/", "/skills/project/"]`)
+ *
+ * @example
+ * ```typescript
+ * const researcher: SubAgent = {
+ *   name: "researcher",
+ *   description: "Research assistant for complex topics",
+ *   systemPrompt: "You are a research assistant.",
+ *   tools: [webSearchTool],
+ *   skills: ["/skills/research/"],
+ * };
+ * ```
  */
 interface SubAgent {
-  /** The name of the agent */
+  /** Identifier used to select this subagent in the task tool */
   name: string;
-  /** The description of the agent */
+  /** Description shown to the model for subagent selection */
   description: string;
   /** The system prompt to use for the agent */
   systemPrompt: string;
   /** The tools to use for the agent (tool instances, not names). Defaults to defaultTools */
   tools?: StructuredTool[];
-  /** The model for the agent. Defaults to default_model */
+  /** The model for the agent. Defaults to defaultModel */
   model?: LanguageModelLike | string;
   /** Additional middleware to append after default_middleware */
   middleware?: readonly AgentMiddleware$1[];
-  /** The tool configs to use for the agent */
+  /** Human-in-the-loop configuration for specific tools. Requires a checkpointer. */
   interruptOn?: Record<string, boolean | InterruptOnConfig>;
+  /**
+   * Skill source paths for SkillsMiddleware.
+   *
+   * List of paths to skill directories (e.g., `["/skills/user/", "/skills/project/"]`).
+   * When specified, the subagent will have its own SkillsMiddleware that loads skills
+   * from these paths. This allows subagents to have different skill sets than the main agent.
+   *
+   * Note: Custom subagents do NOT inherit skills from the main agent by default.
+   * Only the general-purpose subagent inherits the main agent's skills.
+   *
+   * @example
+   * ```typescript
+   * const researcher: SubAgent = {
+   *   name: "researcher",
+   *   description: "Research assistant",
+   *   systemPrompt: "You are a researcher.",
+   *   skills: ["/skills/research/", "/skills/web-search/"],
+   * };
+   * ```
+   */
+  skills?: string[];
 }
+/**
+ * Base specification for the general-purpose subagent.
+ *
+ * This constant provides the default configuration for the general-purpose subagent
+ * that is automatically included when `generalPurposeAgent: true` (the default).
+ *
+ * The general-purpose subagent:
+ * - Has access to all tools from the main agent
+ * - Inherits skills from the main agent (when skills are configured)
+ * - Uses the same model as the main agent (by default)
+ * - Is ideal for delegating complex, multi-step tasks
+ *
+ * You can spread this constant and override specific properties when creating
+ * custom subagents that should behave similarly to the general-purpose agent:
+ *
+ * @example
+ * ```typescript
+ * import { GENERAL_PURPOSE_SUBAGENT, createDeepAgent } from "@anthropic/deepagents";
+ *
+ * // Use as-is (automatically included with generalPurposeAgent: true)
+ * const agent = createDeepAgent({ model: "claude-sonnet-4-5-20250929" });
+ *
+ * // Or create a custom variant with different tools
+ * const customGP: SubAgent = {
+ *   ...GENERAL_PURPOSE_SUBAGENT,
+ *   name: "research-gp",
+ *   tools: [webSearchTool, readFileTool],
+ * };
+ *
+ * const agent = createDeepAgent({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   subagents: [customGP],
+ *   // Disable the default general-purpose agent since we're providing our own
+ *   // (handled automatically when using createSubAgentMiddleware directly)
+ * });
+ * ```
+ */
+declare const GENERAL_PURPOSE_SUBAGENT: Pick<SubAgent, "name" | "description" | "systemPrompt">;
 /**
  * Options for creating subagent middleware
  */
@@ -433,8 +751,13 @@ interface SubAgentMiddlewareOptions {
   defaultModel: LanguageModelLike | string;
   /** The tools to use for the default general-purpose subagent */
   defaultTools?: StructuredTool[];
-  /** Default middleware to apply to all subagents */
+  /** Default middleware to apply to custom subagents (WITHOUT skills from main agent) */
   defaultMiddleware?: AgentMiddleware$1[] | null;
+  /**
+   * Middleware specifically for the general-purpose subagent (includes skills from main agent).
+   * If not provided, falls back to defaultMiddleware.
+   */
+  generalPurposeMiddleware?: AgentMiddleware$1[] | null;
   /** The tool configs for the default general-purpose subagent */
   defaultInterruptOn?: Record<string, boolean | InterruptOnConfig> | null;
   /** A list of additional subagents to provide to the agent */
@@ -449,7 +772,7 @@ interface SubAgentMiddlewareOptions {
 /**
  * Create subagent middleware with task tool
  */
-declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): AgentMiddleware$1<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<z.ZodObject<{
+declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): AgentMiddleware$1<undefined, undefined, unknown, readonly [langchain.DynamicStructuredTool<z.ZodObject<{
   description: z.ZodString;
   subagent_type: z.ZodString;
 }, z.core.$strip>, {
@@ -487,7 +810,7 @@ declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): A
  * });
  * ```
  */
-declare function createPatchToolCallsMiddleware(): AgentMiddleware<undefined, undefined, unknown, readonly (_langchain_core_tools1.ClientTool | _langchain_core_tools1.ServerTool)[]>;
+declare function createPatchToolCallsMiddleware(): AgentMiddleware<undefined, undefined, unknown, readonly (_langchain_core_tools0.ClientTool | _langchain_core_tools0.ServerTool)[]>;
 //#endregion
 //#region src/backends/state.d.ts
 /**
@@ -617,8 +940,8 @@ declare function createMemoryMiddleware(options: MemoryMiddlewareOptions): Agent
    * Marked as private so it's not included in the final agent state.
    */
   memoryContents: z$1.ZodOptional<z$1.ZodRecord<z$1.ZodString, z$1.ZodString>>;
-  files: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
-}>, undefined, unknown, readonly (_langchain_core_tools1.ClientTool | _langchain_core_tools1.ServerTool)[]>;
+  files: _langchain_langgraph0.ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
+}>, undefined, unknown, readonly (_langchain_core_tools0.ClientTool | _langchain_core_tools0.ServerTool)[]>;
 //#endregion
 //#region src/middleware/skills.d.ts
 declare const MAX_SKILL_FILE_SIZE: number;
@@ -700,7 +1023,7 @@ declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): Agent
     allowedTools?: string[] | undefined;
   }[] | undefined>;
   files: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
-}>, undefined, unknown, readonly (_langchain_core_tools1.ClientTool | _langchain_core_tools1.ServerTool)[]>;
+}>, undefined, unknown, readonly (_langchain_core_tools0.ClientTool | _langchain_core_tools0.ServerTool)[]>;
 //#endregion
 //#region src/backends/store.d.ts
 /**
@@ -876,18 +1199,37 @@ declare class FilesystemBackend implements BackendProtocol {
    */
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
   /**
-   * Structured search results or error string for invalid input.
+   * Search for a literal text pattern in files.
+   *
+   * Uses ripgrep if available, falling back to substring search.
+   *
+   * @param pattern - Literal string to search for (NOT regex).
+   * @param dirPath - Directory or file path to search in. Defaults to current directory.
+   * @param glob - Optional glob pattern to filter which files to search.
+   * @returns List of GrepMatch dicts containing path, line number, and matched text.
    */
   grepRaw(pattern: string, dirPath?: string, glob?: string | null): Promise<GrepMatch[] | string>;
   /**
-   * Try to use ripgrep for fast searching.
-   * Returns null if ripgrep is not available or fails.
+   * Search using ripgrep with fixed-string (literal) mode.
+   *
+   * @param pattern - Literal string to search for (unescaped).
+   * @param baseFull - Resolved base path to search in.
+   * @param includeGlob - Optional glob pattern to filter files.
+   * @returns Dict mapping file paths to list of (line_number, line_text) tuples.
+   *          Returns null if ripgrep is unavailable or times out.
    */
   private ripgrepSearch;
   /**
-   * Fallback regex search implementation.
+   * Fallback search using literal substring matching when ripgrep is unavailable.
+   *
+   * Recursively searches files, respecting maxFileSizeBytes limit.
+   *
+   * @param pattern - Literal string to search for.
+   * @param baseFull - Resolved base path to search in.
+   * @param includeGlob - Optional glob pattern to filter files by name.
+   * @returns Dict mapping file paths to list of (line_number, line_text) tuples.
    */
-  private pythonSearch;
+  private literalSearch;
   /**
    * Structured glob matching returning FileInfo objects.
    */
@@ -1058,7 +1400,12 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
    */
   readRaw(filePath: string): Promise<FileData>;
   /**
-   * Structured search results or error string for invalid input.
+   * Search for a literal text pattern in files.
+   *
+   * @param pattern - Literal string to search for (NOT regex).
+   * @param path - Directory or file path to search in.
+   * @param glob - Optional glob pattern to filter which files to search.
+   * @returns List of GrepMatch dicts containing path, line number, and matched text.
    */
   grepRaw(pattern: string, path?: string, glob?: string | null): Promise<GrepMatch[] | string>;
   /**
@@ -1362,7 +1709,7 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
     content: string;
     status: "completed" | "in_progress" | "pending";
   }[] | undefined;
-}>, undefined, unknown, readonly [langchain9.DynamicStructuredTool<zod_v30.ZodObject<{
+}>, undefined, unknown, readonly [langchain.DynamicStructuredTool<zod_v30.ZodObject<{
   todos: zod_v30.ZodArray<zod_v30.ZodObject<{
     content: zod_v30.ZodString;
     status: zod_v30.ZodEnum<["pending", "in_progress", "completed"]>;
@@ -1393,24 +1740,24 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
     content: string;
     status: "completed" | "in_progress" | "pending";
   }[];
-}, _Command.Command<unknown, {
+}, _langchain_langgraph0.Command<unknown, {
   todos: {
     content: string;
     status: "completed" | "in_progress" | "pending";
   }[];
   messages: _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "write_todos">]>, AgentMiddleware<_Command.StateSchema<{
-  files: _Command.ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
-}>, undefined, unknown, (langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  path: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodString>>;
+}, string>, "write_todos">]>, AgentMiddleware<_langchain_langgraph0.StateSchema<{
+  files: _langchain_langgraph0.ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
+}>, undefined, unknown, (langchain.DynamicStructuredTool<zod.ZodObject<{
+  path: zod.ZodDefault<zod.ZodOptional<zod.ZodString>>;
 }, zod_v4_core0.$strip>, {
   path: string;
 }, {
   path?: string | undefined;
-}, string, "ls"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  file_path: zod0.ZodString;
-  offset: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodCoercedNumber<unknown>>>;
-  limit: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodCoercedNumber<unknown>>>;
+}, string, "ls"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  file_path: zod.ZodString;
+  offset: zod.ZodDefault<zod.ZodOptional<zod.ZodCoercedNumber<unknown>>>;
+  limit: zod.ZodDefault<zod.ZodOptional<zod.ZodCoercedNumber<unknown>>>;
 }, zod_v4_core0.$strip>, {
   file_path: string;
   offset: number;
@@ -1419,23 +1766,23 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   file_path: string;
   offset?: unknown;
   limit?: unknown;
-}, string, "read_file"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  file_path: zod0.ZodString;
-  content: zod0.ZodString;
+}, string, "read_file"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  file_path: zod.ZodString;
+  content: zod.ZodString;
 }, zod_v4_core0.$strip>, {
   file_path: string;
   content: string;
 }, {
   file_path: string;
   content: string;
-}, string | _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | _Command.Command<unknown, {
+}, string | _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | _langchain_langgraph0.Command<unknown, {
   files: Record<string, FileData>;
   messages: _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "write_file"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  file_path: zod0.ZodString;
-  old_string: zod0.ZodString;
-  new_string: zod0.ZodString;
-  replace_all: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodBoolean>>;
+}, string>, "write_file"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  file_path: zod.ZodString;
+  old_string: zod.ZodString;
+  new_string: zod.ZodString;
+  replace_all: zod.ZodDefault<zod.ZodOptional<zod.ZodBoolean>>;
 }, zod_v4_core0.$strip>, {
   file_path: string;
   old_string: string;
@@ -1446,22 +1793,22 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   old_string: string;
   new_string: string;
   replace_all?: boolean | undefined;
-}, string | _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | _Command.Command<unknown, {
+}, string | _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>> | _langchain_langgraph0.Command<unknown, {
   files: Record<string, FileData>;
   messages: _messages.ToolMessage<_messages.MessageStructure<_messages.MessageToolSet>>[];
-}, string>, "edit_file"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  pattern: zod0.ZodString;
-  path: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodString>>;
+}, string>, "edit_file"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  pattern: zod.ZodString;
+  path: zod.ZodDefault<zod.ZodOptional<zod.ZodString>>;
 }, zod_v4_core0.$strip>, {
   pattern: string;
   path: string;
 }, {
   pattern: string;
   path?: string | undefined;
-}, string, "glob"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  pattern: zod0.ZodString;
-  path: zod0.ZodDefault<zod0.ZodOptional<zod0.ZodString>>;
-  glob: zod0.ZodNullable<zod0.ZodOptional<zod0.ZodString>>;
+}, string, "glob"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  pattern: zod.ZodString;
+  path: zod.ZodDefault<zod.ZodOptional<zod.ZodString>>;
+  glob: zod.ZodNullable<zod.ZodOptional<zod.ZodString>>;
 }, zod_v4_core0.$strip>, {
   pattern: string;
   path: string;
@@ -1470,22 +1817,22 @@ declare function createDeepAgent<TResponse extends ResponseFormat = ResponseForm
   pattern: string;
   path?: string | undefined;
   glob?: string | null | undefined;
-}, string, "grep"> | langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  command: zod0.ZodString;
+}, string, "grep"> | langchain.DynamicStructuredTool<zod.ZodObject<{
+  command: zod.ZodString;
 }, zod_v4_core0.$strip>, {
   command: string;
 }, {
   command: string;
-}, string, "execute">)[]>, AgentMiddleware<undefined, undefined, unknown, readonly [langchain9.DynamicStructuredTool<zod0.ZodObject<{
-  description: zod0.ZodString;
-  subagent_type: zod0.ZodString;
+}, string, "execute">)[]>, AgentMiddleware<undefined, undefined, unknown, readonly [langchain.DynamicStructuredTool<zod.ZodObject<{
+  description: zod.ZodString;
+  subagent_type: zod.ZodString;
 }, zod_v4_core0.$strip>, {
   description: string;
   subagent_type: string;
 }, {
   description: string;
   subagent_type: string;
-}, string | _Command.Command<unknown, Record<string, unknown>, string>, "task">]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
+}, string | _langchain_langgraph0.Command<unknown, Record<string, unknown>, string>, "task">]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
   trigger: zod_v30.ZodOptional<zod_v30.ZodUnion<[zod_v30.ZodEffects<zod_v30.ZodObject<{
     fraction: zod_v30.ZodOptional<zod_v30.ZodNumber>;
     tokens: zod_v30.ZodOptional<zod_v30.ZodNumber>;
@@ -1745,6 +2092,31 @@ declare function findProjectRoot(startPath?: string): string | null;
  */
 declare function createSettings(options?: SettingsOptions): Settings;
 //#endregion
+//#region src/values.d.ts
+/**
+ * Shared ReducedValue for file data state management.
+ *
+ * This provides a reusable pattern for managing file state with automatic
+ * merging of concurrent updates from parallel subagents. Files can be updated
+ * or deleted (using null values) and the reducer handles the merge logic.
+ *
+ * Similar to LangGraph's messagesValue, this encapsulates the common pattern
+ * of managing files in agent state so you don't have to manually configure
+ * the ReducedValue each time.
+ *
+ * @example
+ * ```typescript
+ * import { filesValue } from "@anthropic/deepagents";
+ * import { StateSchema } from "@langchain/langgraph";
+ *
+ * const MyStateSchema = new StateSchema({
+ *   files: filesValue,
+ *   // ... other state fields
+ * });
+ * ```
+ */
+declare const filesValue: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
+//#endregion
 //#region src/middleware/agent-memory.d.ts
 /**
  * Options for the agent memory middleware.
@@ -1770,7 +2142,7 @@ interface AgentMemoryMiddlewareOptions {
  * @deprecated Use `createMemoryMiddleware` from `./memory.js` instead.
  * This function uses direct filesystem access which limits portability.
  */
-declare function createAgentMemoryMiddleware(options: AgentMemoryMiddlewareOptions): AgentMiddleware<any, undefined, unknown, readonly (_langchain_core_tools1.ClientTool | _langchain_core_tools1.ServerTool)[]>;
+declare function createAgentMemoryMiddleware(options: AgentMemoryMiddlewareOptions): AgentMiddleware<any, undefined, unknown, readonly (_langchain_core_tools0.ClientTool | _langchain_core_tools0.ServerTool)[]>;
 //#endregion
 //#region src/skills/loader.d.ts
 /**
@@ -1824,5 +2196,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, BaseSandbox, type CompiledSubAgent, CompositeBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GrepMatch, type InferDeepAgentSubagents, type InferDeepAgentType, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type SandboxProvider, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, StateBackend, StoreBackend, type SubAgent, type SubAgentMiddlewareOptions, TASK_SYSTEM_PROMPT, type WriteResult, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
 //# sourceMappingURL=index.d.cts.map