deepagents 1.8.4 → 1.8.6

package/dist/index.d.cts

@@ -1,20 +1,21 @@
 import * as zod_v30 from "zod/v3";
 import * as langchain from "langchain";
-import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, CreateAgentParams, HumanMessage, InferMiddlewareStates, InterruptOnConfig, ProviderStrategy, ReactAgent, ResponseFormat, ResponseFormatUndefined, StructuredTool, SystemMessage, ToolMessage, ToolStrategy } from "langchain";
+import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, CreateAgentParams, HumanMessage, InferMiddlewareStates, InterruptOnConfig, ProviderStrategy, ReactAgent, ResponseFormat, ResponseFormatUndefined, Runtime, StructuredTool, SystemMessage, ToolMessage, ToolStrategy } from "langchain";
 import * as _langchain_langgraph0 from "@langchain/langgraph";
 import { AnnotationRoot, Command, ReducedValue, StateSchema } from "@langchain/langgraph";
 import { z } from "zod/v4";
+import * as _langchain_core_tools0 from "@langchain/core/tools";
+import { ClientTool, ServerTool, StructuredTool as StructuredTool$1, ToolRuntime } from "@langchain/core/tools";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
 import * as _messages from "@langchain/core/messages";
 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_tools0 from "@langchain/core/tools";
-import { ClientTool, ServerTool, StructuredTool as StructuredTool$1 } from "@langchain/core/tools";
 import { BaseLanguageModel, LanguageModelLike } from "@langchain/core/language_models/base";
 import { Runnable } from "@langchain/core/runnables";
 import { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { InteropZodObject } from "@langchain/core/utils/types";
+import { CreateSandboxOptions, Sandbox } from "langsmith/experimental/sandbox";
 
 //#region src/backends/protocol.d.ts
 type MaybePromise<T> = T | Promise<T>;
@@ -411,6 +412,8 @@ declare class SandboxError extends Error {
  * Different contexts build this differently:
  * - Tools: Extract state via getCurrentTaskInput(config)
  * - Middleware: Use request.state directly
+ *
+ * @deprecated Use {@link BackendRuntime} instead.
  */
 interface StateAndStore {
   /** Current agent state with files, messages, etc. */
@@ -420,21 +423,36 @@ interface StateAndStore {
   /** Optional assistant ID for per-assistant isolation in store */
   assistantId?: string;
 }
+/**
+ * Agent {@link Runtime} with `state`
+ */
+interface BackendRuntime<StateT = unknown> extends Runtime {
+  /** Current agent state with files, messages, etc. */
+  state: StateT;
+}
 /**
  * Factory function type for creating backend instances.
  *
- * Backends receive StateAndStore which contains the current state
- * and optional store, extracted from the execution context.
+ * Backends receive {@link BackendRuntime} which contains the current state
+ * and runtime information, extracted from the execution context.
  *
  * @example
  * ```typescript
  * // Using in middleware
  * const middleware = createFilesystemMiddleware({
- *   backend: (stateAndStore) => new StateBackend(stateAndStore)
+ *   backend: (runtime) => new StateBackend(runtime)
  * });
  * ```
  */
-type BackendFactory = (stateAndStore: StateAndStore) => BackendProtocol;
+type BackendFactory = (runtime: BackendRuntime) => MaybePromise<BackendProtocol>;
+/**
+ * Resolve a backend instance or await a {@link BackendFactory}.
+ *
+ * Accepts {@link BackendRuntime} or {@link ToolRuntime} — store typing differs
+ * between LangGraph checkpoint stores and core `ToolRuntime`; factories receive
+ * a value that is structurally compatible at runtime.
+ */
+declare function resolveBackend(backend: BackendProtocol | BackendFactory, runtime: BackendRuntime | ToolRuntime): Promise<BackendProtocol>;
 //#endregion
 //#region src/middleware/fs.d.ts
 /**
@@ -754,11 +772,18 @@ declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): A
 //#endregion
 //#region src/middleware/patch_tool_calls.d.ts
 /**
- * Create middleware that patches dangling tool calls in the messages history.
+ * Create middleware that enforces strict tool call / tool response parity in
+ * the messages history.
  *
- * When an AI message contains tool_calls but subsequent messages don't include
- * the corresponding ToolMessage responses, this middleware adds synthetic
- * ToolMessages saying the tool call was cancelled.
+ * Two kinds of violations are repaired:
+ * 1. **Dangling tool_calls** — an AIMessage contains tool_calls with no
+ *    matching ToolMessage responses. Synthetic cancellation ToolMessages are
+ *    injected so every tool_call has a response.
+ * 2. **Orphaned ToolMessages** — a ToolMessage exists whose `tool_call_id`
+ *    does not match any tool_call in a preceding AIMessage. These are removed.
+ *
+ * This is critical for providers like Google Gemini that reject requests with
+ * mismatched function call / function response counts (400 INVALID_ARGUMENT).
  *
  * This middleware patches in two places:
  * 1. `beforeAgent`: Patches state at the start of the agent loop (handles most cases)
@@ -766,7 +791,7 @@ declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): A
  *    edge cases like HITL rejection during graph resume where state updates from
  *    beforeAgent may not be applied in time)
  *
- * @returns AgentMiddleware that patches dangling tool calls
+ * @returns AgentMiddleware that enforces tool call / response parity
  *
  * @example
  * ```typescript
@@ -794,8 +819,8 @@ declare function createPatchToolCallsMiddleware(): AgentMiddleware<undefined, un
  * for the middleware to apply via Command.
  */
 declare class StateBackend implements BackendProtocol {
-  private stateAndStore;
-  constructor(stateAndStore: StateAndStore);
+  private runtime;
+  constructor(runtime: BackendRuntime);
   /**
    * Get files from current state.
    */
@@ -1168,17 +1193,17 @@ interface StoreBackendOptions {
    * Determines where files are stored in the LangGraph store, enabling
    * user-scoped, org-scoped, or any custom isolation pattern.
    *
-   * If not provided, falls back to legacy behavior using assistantId from StateAndStore.
+   * If not provided, falls back to legacy behavior using assistantId from {@link BackendRuntime}.
    *
    * @example
    * ```typescript
    * // User-scoped storage
-   * new StoreBackend(stateAndStore, {
+   * new StoreBackend(runtime, {
    *   namespace: ["memories", orgId, userId, "filesystem"],
    * });
    *
    * // Org-scoped storage
-   * new StoreBackend(stateAndStore, {
+   * new StoreBackend(runtime, {
    *   namespace: ["memories", orgId, "filesystem"],
    * });
    * ```
@@ -1787,6 +1812,98 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }
 //#endregion
+//#region src/backends/langsmith.d.ts
+/** Options for constructing a LangSmithSandbox from an existing Sandbox instance. */
+interface LangSmithSandboxOptions {
+  /** An already-created LangSmith Sandbox instance to wrap. */
+  sandbox: Sandbox;
+  /**
+   * Default command timeout in seconds.
+   * @default 1800 (30 minutes)
+   */
+  defaultTimeout?: number;
+}
+/** Options for the `LangSmithSandbox.create()` static factory. */
+interface LangSmithSandboxCreateOptions extends Omit<CreateSandboxOptions, "name" | "timeout" | "waitForReady"> {
+  /**
+   * Name of the LangSmith sandbox template to use.
+   * @default "deepagents"
+   */
+  templateName?: string;
+  /**
+   * LangSmith API key. Defaults to the `LANGSMITH_API_KEY` environment variable.
+   */
+  apiKey?: string;
+  /**
+   * Default command timeout in seconds.
+   * @default 1800 (30 minutes)
+   */
+  defaultTimeout?: number;
+}
+/**
+ * LangSmith Sandbox backend for deepagents.
+ *
+ * Extends `BaseSandbox` to provide command execution and file operations
+ * via the LangSmith Sandbox API.
+ *
+ * Use the static `LangSmithSandbox.create()` factory for the simplest setup,
+ * or construct directly with an existing `Sandbox` instance.
+ */
+declare class LangSmithSandbox extends BaseSandbox {
+  #private;
+  constructor(options: LangSmithSandboxOptions);
+  /** Whether the sandbox is currently active. */
+  get isRunning(): boolean;
+  /** Return the LangSmith sandbox name as the unique identifier. */
+  get id(): string;
+  /**
+   * Execute a shell command in the LangSmith sandbox.
+   *
+   * @param command - Shell command string to execute
+   * @param options.timeout - Override timeout in seconds; 0 disables timeout
+   */
+  execute(command: string, options?: {
+    timeout?: number;
+  }): Promise<ExecuteResponse>;
+  /**
+   * Download files from the sandbox using LangSmith's native file read API.
+   * @param paths - List of file paths to download
+   * @returns List of FileDownloadResponse objects, one per input path
+   */
+  downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
+  /**
+   * Upload files to the sandbox using LangSmith's native file write API.
+   * @param files - List of [path, content] tuples to upload
+   * @returns List of FileUploadResponse objects, one per input file
+   */
+  uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+  /**
+   * Delete this sandbox and mark it as no longer running.
+   *
+   * After calling this, `isRunning` will be `false` and the sandbox
+   * cannot be used again.
+   */
+  close(): Promise<void>;
+  /**
+   * Create and return a new LangSmithSandbox in one step.
+   *
+   * This is the recommended way to create a sandbox — no need to import
+   * anything from `langsmith/experimental/sandbox` directly.
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await LangSmithSandbox.create({ templateName: "deepagents" });
+   * try {
+   *   const agent = createDeepAgent({ model, backend: sandbox });
+   *   await agent.invoke({ messages: [...] });
+   * } finally {
+   *   await sandbox.close();
+   * }
+   * ```
+   */
+  static create(options?: LangSmithSandboxCreateOptions): Promise<LangSmithSandbox>;
+}
+//#endregion
 //#region src/types.d.ts
 type AnyAnnotationRoot = AnnotationRoot<any>;
 interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {
@@ -2237,27 +2354,47 @@ declare function createDeepAgent<TResponse extends SupportedResponseFormat = Sup
     summaryMessage: zod.ZodCustom<_messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>, _messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>>;
     filePath: zod.ZodNullable<zod.ZodString>;
   }, zod_v4_core0.$strip>>;
-}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
-  enableCaching: zod_v30.ZodOptional<zod_v30.ZodBoolean>;
-  ttl: zod_v30.ZodOptional<zod_v30.ZodEnum<["5m", "1h"]>>;
-  minMessagesToCache: zod_v30.ZodOptional<zod_v30.ZodNumber>;
-  unsupportedModelBehavior: zod_v30.ZodOptional<zod_v30.ZodEnum<["ignore", "warn", "raise"]>>;
-}, "strip", zod_v30.ZodTypeAny, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}>, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]>, ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
+}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]>, ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error codes for {@link ConfigurationError}.
+ *
+ * Each code represents a distinct misconfiguration that can be detected at
+ * agent-construction time. Add new codes here as new validations are added.
+ */
+type ConfigurationErrorCode = "TOOL_NAME_COLLISION";
+declare const CONFIGURATION_ERROR_SYMBOL: unique symbol;
+/**
+ * Thrown when `createDeepAgent` receives invalid configuration.
+ *
+ * Follows the same pattern as {@link SandboxError}: a human-readable
+ * `message`, a structured `code` for programmatic handling, and a
+ * static `isInstance` guard that works across realms.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   createDeepAgent({ tools: [myTool] });
+ * } catch (error) {
+ *   if (ConfigurationError.isInstance(error)) {
+ *     switch (error.code) {
+ *       case "TOOL_NAME_COLLISION":
+ *         console.error("Rename your tool:", error.message);
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class ConfigurationError extends Error {
+  readonly code: ConfigurationErrorCode;
+  readonly cause?: Error | undefined;
+  [CONFIGURATION_ERROR_SYMBOL]: true;
+  readonly name: string;
+  constructor(message: string, code: ConfigurationErrorCode, cause?: Error | undefined);
+  static isInstance(error: unknown): error is ConfigurationError;
+}
 //#endregion
 //#region src/config.d.ts
 /**
@@ -2464,5 +2601,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, 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 InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, type BackendRuntime, BaseSandbox, type CompiledSubAgent, CompositeBackend, ConfigurationError, type ConfigurationErrorCode, 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 InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata, resolveBackend };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as langchain from "langchain";
-import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, CreateAgentParams, HumanMessage, InferMiddlewareStates, InterruptOnConfig, ProviderStrategy, ReactAgent, ResponseFormat, ResponseFormatUndefined, StructuredTool, SystemMessage, ToolMessage, ToolStrategy } from "langchain";
+import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentTypeConfig, CreateAgentParams, HumanMessage, InferMiddlewareStates, InterruptOnConfig, ProviderStrategy, ReactAgent, ResponseFormat, ResponseFormatUndefined, Runtime, StructuredTool, SystemMessage, ToolMessage, ToolStrategy } from "langchain";
 import { Runnable } from "@langchain/core/runnables";
 import * as _langchain_langgraph0 from "@langchain/langgraph";
 import { AnnotationRoot, Command, ReducedValue, StateSchema } from "@langchain/langgraph";
@@ -7,11 +7,12 @@ import { z } from "zod/v4";
 import * as _messages from "@langchain/core/messages";
 import * as zod from "zod";
 import { z as z$1 } from "zod";
+import { CreateSandboxOptions, Sandbox } from "langsmith/experimental/sandbox";
 import * as zod_v30 from "zod/v3";
+import * as _langchain_core_tools0 from "@langchain/core/tools";
+import { ClientTool, ServerTool, StructuredTool as StructuredTool$1, ToolRuntime } from "@langchain/core/tools";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
 import * as zod_v4_core0 from "zod/v4/core";
-import * as _langchain_core_tools0 from "@langchain/core/tools";
-import { ClientTool, ServerTool, StructuredTool as StructuredTool$1 } from "@langchain/core/tools";
 import { BaseLanguageModel, LanguageModelLike } from "@langchain/core/language_models/base";
 import { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { InteropZodObject } from "@langchain/core/utils/types";
@@ -411,6 +412,8 @@ declare class SandboxError extends Error {
  * Different contexts build this differently:
  * - Tools: Extract state via getCurrentTaskInput(config)
  * - Middleware: Use request.state directly
+ *
+ * @deprecated Use {@link BackendRuntime} instead.
  */
 interface StateAndStore {
   /** Current agent state with files, messages, etc. */
@@ -420,21 +423,36 @@ interface StateAndStore {
   /** Optional assistant ID for per-assistant isolation in store */
   assistantId?: string;
 }
+/**
+ * Agent {@link Runtime} with `state`
+ */
+interface BackendRuntime<StateT = unknown> extends Runtime {
+  /** Current agent state with files, messages, etc. */
+  state: StateT;
+}
 /**
  * Factory function type for creating backend instances.
  *
- * Backends receive StateAndStore which contains the current state
- * and optional store, extracted from the execution context.
+ * Backends receive {@link BackendRuntime} which contains the current state
+ * and runtime information, extracted from the execution context.
  *
  * @example
  * ```typescript
  * // Using in middleware
  * const middleware = createFilesystemMiddleware({
- *   backend: (stateAndStore) => new StateBackend(stateAndStore)
+ *   backend: (runtime) => new StateBackend(runtime)
  * });
  * ```
  */
-type BackendFactory = (stateAndStore: StateAndStore) => BackendProtocol;
+type BackendFactory = (runtime: BackendRuntime) => MaybePromise<BackendProtocol>;
+/**
+ * Resolve a backend instance or await a {@link BackendFactory}.
+ *
+ * Accepts {@link BackendRuntime} or {@link ToolRuntime} — store typing differs
+ * between LangGraph checkpoint stores and core `ToolRuntime`; factories receive
+ * a value that is structurally compatible at runtime.
+ */
+declare function resolveBackend(backend: BackendProtocol | BackendFactory, runtime: BackendRuntime | ToolRuntime): Promise<BackendProtocol>;
 //#endregion
 //#region src/middleware/fs.d.ts
 /**
@@ -754,11 +772,18 @@ declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): A
 //#endregion
 //#region src/middleware/patch_tool_calls.d.ts
 /**
- * Create middleware that patches dangling tool calls in the messages history.
+ * Create middleware that enforces strict tool call / tool response parity in
+ * the messages history.
  *
- * When an AI message contains tool_calls but subsequent messages don't include
- * the corresponding ToolMessage responses, this middleware adds synthetic
- * ToolMessages saying the tool call was cancelled.
+ * Two kinds of violations are repaired:
+ * 1. **Dangling tool_calls** — an AIMessage contains tool_calls with no
+ *    matching ToolMessage responses. Synthetic cancellation ToolMessages are
+ *    injected so every tool_call has a response.
+ * 2. **Orphaned ToolMessages** — a ToolMessage exists whose `tool_call_id`
+ *    does not match any tool_call in a preceding AIMessage. These are removed.
+ *
+ * This is critical for providers like Google Gemini that reject requests with
+ * mismatched function call / function response counts (400 INVALID_ARGUMENT).
  *
  * This middleware patches in two places:
  * 1. `beforeAgent`: Patches state at the start of the agent loop (handles most cases)
@@ -766,7 +791,7 @@ declare function createSubAgentMiddleware(options: SubAgentMiddlewareOptions): A
  *    edge cases like HITL rejection during graph resume where state updates from
  *    beforeAgent may not be applied in time)
  *
- * @returns AgentMiddleware that patches dangling tool calls
+ * @returns AgentMiddleware that enforces tool call / response parity
  *
  * @example
  * ```typescript
@@ -794,8 +819,8 @@ declare function createPatchToolCallsMiddleware(): AgentMiddleware<undefined, un
  * for the middleware to apply via Command.
  */
 declare class StateBackend implements BackendProtocol {
-  private stateAndStore;
-  constructor(stateAndStore: StateAndStore);
+  private runtime;
+  constructor(runtime: BackendRuntime);
   /**
    * Get files from current state.
    */
@@ -1168,17 +1193,17 @@ interface StoreBackendOptions {
    * Determines where files are stored in the LangGraph store, enabling
    * user-scoped, org-scoped, or any custom isolation pattern.
    *
-   * If not provided, falls back to legacy behavior using assistantId from StateAndStore.
+   * If not provided, falls back to legacy behavior using assistantId from {@link BackendRuntime}.
    *
    * @example
    * ```typescript
    * // User-scoped storage
-   * new StoreBackend(stateAndStore, {
+   * new StoreBackend(runtime, {
    *   namespace: ["memories", orgId, userId, "filesystem"],
    * });
    *
    * // Org-scoped storage
-   * new StoreBackend(stateAndStore, {
+   * new StoreBackend(runtime, {
    *   namespace: ["memories", orgId, "filesystem"],
    * });
    * ```
@@ -1787,6 +1812,98 @@ declare abstract class BaseSandbox implements SandboxBackendProtocol {
   edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
 }
 //#endregion
+//#region src/backends/langsmith.d.ts
+/** Options for constructing a LangSmithSandbox from an existing Sandbox instance. */
+interface LangSmithSandboxOptions {
+  /** An already-created LangSmith Sandbox instance to wrap. */
+  sandbox: Sandbox;
+  /**
+   * Default command timeout in seconds.
+   * @default 1800 (30 minutes)
+   */
+  defaultTimeout?: number;
+}
+/** Options for the `LangSmithSandbox.create()` static factory. */
+interface LangSmithSandboxCreateOptions extends Omit<CreateSandboxOptions, "name" | "timeout" | "waitForReady"> {
+  /**
+   * Name of the LangSmith sandbox template to use.
+   * @default "deepagents"
+   */
+  templateName?: string;
+  /**
+   * LangSmith API key. Defaults to the `LANGSMITH_API_KEY` environment variable.
+   */
+  apiKey?: string;
+  /**
+   * Default command timeout in seconds.
+   * @default 1800 (30 minutes)
+   */
+  defaultTimeout?: number;
+}
+/**
+ * LangSmith Sandbox backend for deepagents.
+ *
+ * Extends `BaseSandbox` to provide command execution and file operations
+ * via the LangSmith Sandbox API.
+ *
+ * Use the static `LangSmithSandbox.create()` factory for the simplest setup,
+ * or construct directly with an existing `Sandbox` instance.
+ */
+declare class LangSmithSandbox extends BaseSandbox {
+  #private;
+  constructor(options: LangSmithSandboxOptions);
+  /** Whether the sandbox is currently active. */
+  get isRunning(): boolean;
+  /** Return the LangSmith sandbox name as the unique identifier. */
+  get id(): string;
+  /**
+   * Execute a shell command in the LangSmith sandbox.
+   *
+   * @param command - Shell command string to execute
+   * @param options.timeout - Override timeout in seconds; 0 disables timeout
+   */
+  execute(command: string, options?: {
+    timeout?: number;
+  }): Promise<ExecuteResponse>;
+  /**
+   * Download files from the sandbox using LangSmith's native file read API.
+   * @param paths - List of file paths to download
+   * @returns List of FileDownloadResponse objects, one per input path
+   */
+  downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
+  /**
+   * Upload files to the sandbox using LangSmith's native file write API.
+   * @param files - List of [path, content] tuples to upload
+   * @returns List of FileUploadResponse objects, one per input file
+   */
+  uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+  /**
+   * Delete this sandbox and mark it as no longer running.
+   *
+   * After calling this, `isRunning` will be `false` and the sandbox
+   * cannot be used again.
+   */
+  close(): Promise<void>;
+  /**
+   * Create and return a new LangSmithSandbox in one step.
+   *
+   * This is the recommended way to create a sandbox — no need to import
+   * anything from `langsmith/experimental/sandbox` directly.
+   *
+   * @example
+   * ```typescript
+   * const sandbox = await LangSmithSandbox.create({ templateName: "deepagents" });
+   * try {
+   *   const agent = createDeepAgent({ model, backend: sandbox });
+   *   await agent.invoke({ messages: [...] });
+   * } finally {
+   *   await sandbox.close();
+   * }
+   * ```
+   */
+  static create(options?: LangSmithSandboxCreateOptions): Promise<LangSmithSandbox>;
+}
+//#endregion
 //#region src/types.d.ts
 type AnyAnnotationRoot = AnnotationRoot<any>;
 interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {
@@ -2237,27 +2354,47 @@ declare function createDeepAgent<TResponse extends SupportedResponseFormat = Sup
     summaryMessage: zod.ZodCustom<_messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>, _messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>>;
     filePath: zod.ZodNullable<zod.ZodString>;
   }, zod_v4_core0.$strip>>;
-}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, zod_v30.ZodObject<{
-  enableCaching: zod_v30.ZodOptional<zod_v30.ZodBoolean>;
-  ttl: zod_v30.ZodOptional<zod_v30.ZodEnum<["5m", "1h"]>>;
-  minMessagesToCache: zod_v30.ZodOptional<zod_v30.ZodNumber>;
-  unsupportedModelBehavior: zod_v30.ZodOptional<zod_v30.ZodEnum<["ignore", "warn", "raise"]>>;
-}, "strip", zod_v30.ZodTypeAny, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}>, {
-  enableCaching?: boolean | undefined;
-  ttl?: "1h" | "5m" | undefined;
-  minMessagesToCache?: number | undefined;
-  unsupportedModelBehavior?: "ignore" | "raise" | "warn" | undefined;
-}, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]>, ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
+}, zod_v4_core0.$strip>, undefined, unknown, readonly (ClientTool | ServerTool)[]>, AgentMiddleware<undefined, undefined, unknown, readonly (ClientTool | ServerTool)[]>, ...TMiddleware, ...FlattenSubAgentMiddleware<TSubagents>], TTools, TSubagents>>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error codes for {@link ConfigurationError}.
+ *
+ * Each code represents a distinct misconfiguration that can be detected at
+ * agent-construction time. Add new codes here as new validations are added.
+ */
+type ConfigurationErrorCode = "TOOL_NAME_COLLISION";
+declare const CONFIGURATION_ERROR_SYMBOL: unique symbol;
+/**
+ * Thrown when `createDeepAgent` receives invalid configuration.
+ *
+ * Follows the same pattern as {@link SandboxError}: a human-readable
+ * `message`, a structured `code` for programmatic handling, and a
+ * static `isInstance` guard that works across realms.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   createDeepAgent({ tools: [myTool] });
+ * } catch (error) {
+ *   if (ConfigurationError.isInstance(error)) {
+ *     switch (error.code) {
+ *       case "TOOL_NAME_COLLISION":
+ *         console.error("Rename your tool:", error.message);
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class ConfigurationError extends Error {
+  readonly code: ConfigurationErrorCode;
+  readonly cause?: Error | undefined;
+  [CONFIGURATION_ERROR_SYMBOL]: true;
+  readonly name: string;
+  constructor(message: string, code: ConfigurationErrorCode, cause?: Error | undefined);
+  static isInstance(error: unknown): error is ConfigurationError;
+}
 //#endregion
 //#region src/config.d.ts
 /**
@@ -2464,5 +2601,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, 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 InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata };
+export { type AgentMemoryMiddlewareOptions, type BackendFactory, type BackendProtocol, type BackendRuntime, BaseSandbox, type CompiledSubAgent, CompositeBackend, ConfigurationError, type ConfigurationErrorCode, 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 InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, computeSummarizationDefaults, createAgentMemoryMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isSandboxBackend, listSkills, parseSkillMetadata, resolveBackend };
 //# sourceMappingURL=index.d.ts.map