deepagents 1.9.0-alpha.1 → 1.9.1

package/dist/index.d.cts

@@ -670,6 +670,44 @@ type BackendFactory = (runtime: BackendRuntime) => MaybePromise<AnyBackendProtoc
  */
 declare function resolveBackend(backend: AnyBackendProtocol | BackendFactory, runtime: BackendRuntime | ToolRuntime): Promise<BackendProtocolV2>;
 //#endregion
+//#region src/permissions/types.d.ts
+/**
+ * The filesystem operations a permission rule can govern.
+ */
+type FilesystemOperation = "read" | "write";
+/**
+ * Whether a matched rule permits or blocks the operation.
+ */
+type PermissionMode = "allow" | "deny";
+/**
+ * A single filesystem permission rule.
+ *
+ * Rules are evaluated in declaration order; the first rule whose
+ * `operations` includes the requested operation AND whose `paths`
+ * glob-matches the target path determines the outcome. If no rule
+ * matches, access is **allowed** (permissive default).
+ *
+ * All `paths` must be absolute glob patterns (start with `/`, no `..` or `~`).
+ * Supports `**` (any depth), `*` (within one segment), and `{a,b}` brace expansion.
+ * Paths are validated when passed to {@link createFilesystemMiddleware}.
+ */
+interface FilesystemPermission {
+  /**
+   * The operations this rule applies to.
+   */
+  operations: readonly FilesystemOperation[];
+  /**
+   * Absolute glob patterns for paths this rule matches.
+   * Must start with `/`; must not contain `..` or `~`.
+   * Supports `**` (any depth), `*` (within one segment), and `{a,b}` brace expansion.
+   */
+  paths: string[];
+  /**
+   * Whether matching paths are permitted or blocked. Defaults to `"allow"`.
+   */
+  mode?: PermissionMode;
+}
+//#endregion
 //#region src/middleware/fs.d.ts
 /**
  * Type for the files state record.
@@ -693,6 +731,22 @@ interface FilesystemMiddlewareOptions {
   toolTokenLimitBeforeEvict?: number | null;
   /** Optional token limit before evicting a HumanMessage to the filesystem (default: 50000 tokens, ~200KB) */
   humanMessageTokenLimitBeforeEvict?: number | null;
+  /**
+   * Filesystem permission rules enforced on every tool call.
+   *
+   * Rules are evaluated in declaration order; first match wins; permissive
+   * default. Applies to `ls`, `read_file`, `write_file`, `edit_file`,
+   * `glob`, and `grep`.
+   *
+   * **Note on `execute`**: permissions are not enforced on `execute` because
+   * shell commands can access any path regardless of path-based rules. Using
+   * permissions with an execution-capable backend (one where `isSandboxBackend`
+   * returns `true`) throws a `ConfigurationError` unless the backend is a
+   * `CompositeBackend` and every permission path is scoped to a route prefix.
+   *
+   * When omitted or empty, all filesystem operations are permitted.
+   */
+  permissions?: FilesystemPermission[];
 }
 /**
  * Create filesystem middleware with all tools and features.
@@ -815,10 +869,10 @@ declare class StateBackend implements BackendProtocolV2 {
    * Get files from current state.
    *
    * In legacy mode, reads from the injected {@link BackendRuntime}.
-   * In zero-arg mode, reads from the LangGraph execution context via
-   * {@link getCurrentTaskInput}.
+   * In zero-arg mode, reads via {@link PREGEL_READ_KEY} with fresh=true,
+   * which applies any pending task writes through the reducer before returning.
    */
-  private getFiles;
+  private get files();
   /**
    * Push a files state update through LangGraph's internal send channel.
    *
@@ -898,32 +952,76 @@ declare class StateBackend implements BackendProtocolV2 {
 }
 //#endregion
 //#region src/backends/store.d.ts
+/**
+ * Context provided to dynamic namespace factory functions.
+ */
+interface StoreBackendContext<StateT = unknown> {
+  /**
+   * Current graph state, when available.
+   *
+   * In legacy factory mode this is the injected runtime state. In zero-arg mode
+   * this is read from the current LangGraph execution context.
+   */
+  state: StateT;
+  /**
+   * Runnable config, when available.
+   *
+   * This mirrors the Python implementation's access to config metadata for
+   * namespace resolution.
+   */
+  config?: {
+    metadata?: Record<string, unknown>;
+    configurable?: Record<string, unknown>;
+  };
+  /**
+   * Legacy assistant identifier, resolved from config metadata first and then
+   * from the injected runtime for backwards compatibility.
+   */
+  assistantId?: string;
+}
+type StoreBackendNamespaceFactory<StateT = unknown> = (context: StoreBackendContext<StateT>) => string[];
 /**
  * Options for StoreBackend constructor.
  */
-interface StoreBackendOptions extends BackendOptions {
+interface StoreBackendOptions<StateT = unknown> extends BackendOptions {
+  /**
+   * Explicit store instance to use for persistence.
+   *
+   * This mirrors the Python API and allows constructing a backend directly with
+   * a store instance, e.g. `new StoreBackend({ store })`.
+   *
+   * When omitted, the backend uses the legacy injected runtime store or the
+   * LangGraph execution-context store.
+   */
+  store?: BaseStore;
   /**
    * Custom namespace for store operations.
    *
-   * Determines where files are stored in the LangGraph store, enabling
-   * user-scoped, org-scoped, or any custom isolation pattern.
+   * Accepts either a static namespace array or a factory that derives the
+   * namespace from the current backend context.
    *
-   * If not provided, falls back to legacy behavior using assistantId from {@link BackendRuntime}.
+   * If not provided, falls back to legacy assistant-id detection from config
+   * metadata, then the injected runtime's `assistantId`, and finally
+   * `["filesystem"]`.
    *
    * @example
    * ```typescript
-   * // User-scoped storage
-   * new StoreBackend(runtime, {
+   * // Static namespace
+   * new StoreBackend({
    *   namespace: ["memories", orgId, userId, "filesystem"],
    * });
    *
-   * // Org-scoped storage
-   * new StoreBackend(runtime, {
-   *   namespace: ["memories", orgId, "filesystem"],
+   * // Dynamic namespace
+   * new StoreBackend({
+   *   namespace: ({ state }) => [
+   *     "memories",
+   *     (state as { userId: string }).userId,
+   *     "filesystem",
+   *   ],
    * });
    * ```
    */
-  namespace?: string[];
+  namespace?: string[] | StoreBackendNamespaceFactory<StateT>;
 }
 /**
  * Backend that stores files in LangGraph's BaseStore (persistent).
@@ -937,6 +1035,7 @@ interface StoreBackendOptions extends BackendOptions {
  */
 declare class StoreBackend implements BackendProtocolV2 {
   private stateAndStore;
+  private storeOverride;
   private _namespace;
   private fileFormat;
   constructor(options?: StoreBackendOptions);
@@ -955,15 +1054,28 @@ declare class StoreBackend implements BackendProtocolV2 {
    * @throws Error if no store is available in either mode
    */
   private getStore;
+  /**
+   * Get the current graph state when available.
+   */
+  private getState;
+  /**
+   * Get the most relevant runnable config for namespace resolution.
+   */
+  private getNamespaceConfig;
+  /**
+   * Legacy assistant-id detection compatible with both Python and the
+   * historical TypeScript `assistantId` runtime property.
+   */
+  private getLegacyAssistantId;
   /**
    * Get the namespace for store operations.
    *
    * Resolution order:
-   * 1. Explicit namespace from constructor options (both modes)
-   * 2. Legacy mode: `[assistantId, "filesystem"]` fallback from {@link StateAndStore}
-   * 3. Zero-arg mode without namespace: `["filesystem"]` with a deprecation warning
-   *    nudging callers to pass an explicit namespace
-   * 4. Legacy mode without assistantId: `["filesystem"]`
+   * 1. Explicit namespace from constructor options
+   * 2. Namespace factory resolved from the current backend context
+   * 3. Assistant ID from runtime config / LangGraph config metadata
+   * 4. Legacy `assistantId` from the injected runtime
+   * 5. `["filesystem"]`
    */
   protected getNamespace(): string[];
   /**
@@ -1185,6 +1297,15 @@ declare class CompositeBackend implements BackendProtocolV2 {
   constructor(defaultBackend: AnyBackendProtocol, routes: Record<string, AnyBackendProtocol>);
   /** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
   get id(): string;
+  /** Route prefixes registered on this backend (e.g. `["/workspace"]`). */
+  get routePrefixes(): string[];
+  /**
+   * Type guard — returns true if `backend` is a {@link CompositeBackend}.
+   *
+   * Uses duck-typing on `routePrefixes` so it works across module boundaries
+   * where `instanceof` may fail.
+   */
+  static isInstance(backend: unknown): backend is CompositeBackend;
   /**
    * Determine which backend handles this key and strip prefix.
    *
@@ -1577,6 +1698,8 @@ interface LangSmithSandboxCreateOptions extends Omit<CreateSandboxOptions, "name
  *
  * Use the static `LangSmithSandbox.create()` factory for the simplest setup,
  * or construct directly with an existing `Sandbox` instance.
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 declare class LangSmithSandbox extends BaseSandbox {
   #private;
@@ -1795,6 +1918,27 @@ interface SubAgent {
    * ```
    */
   responseFormat?: CreateAgentParams["responseFormat"];
+  /**
+   * Filesystem permission rules for this subagent.
+   *
+   * When specified, these rules **replace** the parent agent's permissions
+   * for all tool calls made by this subagent. When omitted, the subagent
+   * inherits the parent agent's permissions.
+   *
+   * Subagent permissions are a full replacement, not a merge.
+   *
+   * @example
+   * ```ts
+   * // Parent denies /restricted/**; this subagent can read it.
+   * const reader: SubAgent = {
+   *   name: "reader",
+   *   permissions: [
+   *     { operations: ["read"], paths: ["/restricted/**"] },
+   *   ],
+   * };
+   * ```
+   */
+  permissions?: FilesystemPermission[];
 }
 /**
  * Base specification for the general-purpose subagent.
@@ -2028,6 +2172,11 @@ interface SkillMetadata$1 {
    * - Space-delimited list of tool names
    */
   allowedTools?: string[];
+  /**
+   * Path to a JS/TS entrypoint file for a QuickJS REPL module, relative to the skill
+   * directory.
+   */
+  module?: string;
 }
 /**
  * Options for the skills middleware.
@@ -2076,6 +2225,7 @@ declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): Agent
     compatibility?: string | null | undefined;
     metadata?: Record<string, string> | undefined;
     allowedTools?: string[] | undefined;
+    module?: string | undefined;
   }[] | undefined, {
     name: string;
     description: string;
@@ -2084,6 +2234,7 @@ declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): Agent
     compatibility?: string | null | undefined;
     metadata?: Record<string, string> | undefined;
     allowedTools?: string[] | undefined;
+    module?: string | undefined;
   }[] | undefined>;
   files: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
 }>, undefined, unknown, readonly (_$_langchain_core_tools0.ClientTool | _$_langchain_core_tools0.ServerTool)[]>;
@@ -2187,8 +2338,9 @@ interface SummarizationMiddlewareOptions {
   /**
    * The language model to use for generating summaries.
    * Can be a model string (e.g., "gpt-4o-mini") or a language model instance.
+   * If omitted, middleware will use the active request model.
    */
-  model: string | BaseChatModel | BaseLanguageModel;
+  model?: string | BaseChatModel | BaseLanguageModel;
   /**
    * Backend instance or factory for persisting conversation history.
    */
@@ -2695,6 +2847,25 @@ interface CreateDeepAgentParams<TResponse extends SupportedResponseFormat = Supp
    * ```
    */
   skills?: string[];
+  /**
+   * Filesystem permission rules for this agent.
+   *
+   * Rules are evaluated in declaration order; first match wins; permissive
+   * default. Applied to `ls`, `read_file`, `write_file`, `edit_file`, `glob`,
+   * and `grep`. Subagents inherit these rules unless they specify their own
+   * `permissions` field.
+   *
+   * @example
+   * ```ts
+   * createDeepAgent({
+   *   permissions: [
+   *     { operations: ["read"], paths: ["/workspace/**"] },
+   *     { operations: ["read"], paths: ["/**"], mode: "deny" },
+   *   ],
+   * });
+   * ```
+   */
+  permissions?: FilesystemPermission[];
 }
 //#endregion
 //#region src/agent.d.ts
@@ -3133,5 +3304,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, 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 GlobResult, type GrepMatch, type GrepResult, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, 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, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
+export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, 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 FilesystemOperation, type FilesystemPermission, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GlobResult, type GrepMatch, type GrepResult, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type PermissionMode, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, 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 StoreBackendContext, type StoreBackendNamespaceFactory, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -672,6 +672,44 @@ type BackendFactory = (runtime: BackendRuntime) => MaybePromise<AnyBackendProtoc
  */
 declare function resolveBackend(backend: AnyBackendProtocol | BackendFactory, runtime: BackendRuntime | ToolRuntime): Promise<BackendProtocolV2>;
 //#endregion
+//#region src/permissions/types.d.ts
+/**
+ * The filesystem operations a permission rule can govern.
+ */
+type FilesystemOperation = "read" | "write";
+/**
+ * Whether a matched rule permits or blocks the operation.
+ */
+type PermissionMode = "allow" | "deny";
+/**
+ * A single filesystem permission rule.
+ *
+ * Rules are evaluated in declaration order; the first rule whose
+ * `operations` includes the requested operation AND whose `paths`
+ * glob-matches the target path determines the outcome. If no rule
+ * matches, access is **allowed** (permissive default).
+ *
+ * All `paths` must be absolute glob patterns (start with `/`, no `..` or `~`).
+ * Supports `**` (any depth), `*` (within one segment), and `{a,b}` brace expansion.
+ * Paths are validated when passed to {@link createFilesystemMiddleware}.
+ */
+interface FilesystemPermission {
+  /**
+   * The operations this rule applies to.
+   */
+  operations: readonly FilesystemOperation[];
+  /**
+   * Absolute glob patterns for paths this rule matches.
+   * Must start with `/`; must not contain `..` or `~`.
+   * Supports `**` (any depth), `*` (within one segment), and `{a,b}` brace expansion.
+   */
+  paths: string[];
+  /**
+   * Whether matching paths are permitted or blocked. Defaults to `"allow"`.
+   */
+  mode?: PermissionMode;
+}
+//#endregion
 //#region src/middleware/fs.d.ts
 /**
  * Type for the files state record.
@@ -695,6 +733,22 @@ interface FilesystemMiddlewareOptions {
   toolTokenLimitBeforeEvict?: number | null;
   /** Optional token limit before evicting a HumanMessage to the filesystem (default: 50000 tokens, ~200KB) */
   humanMessageTokenLimitBeforeEvict?: number | null;
+  /**
+   * Filesystem permission rules enforced on every tool call.
+   *
+   * Rules are evaluated in declaration order; first match wins; permissive
+   * default. Applies to `ls`, `read_file`, `write_file`, `edit_file`,
+   * `glob`, and `grep`.
+   *
+   * **Note on `execute`**: permissions are not enforced on `execute` because
+   * shell commands can access any path regardless of path-based rules. Using
+   * permissions with an execution-capable backend (one where `isSandboxBackend`
+   * returns `true`) throws a `ConfigurationError` unless the backend is a
+   * `CompositeBackend` and every permission path is scoped to a route prefix.
+   *
+   * When omitted or empty, all filesystem operations are permitted.
+   */
+  permissions?: FilesystemPermission[];
 }
 /**
  * Create filesystem middleware with all tools and features.
@@ -817,10 +871,10 @@ declare class StateBackend implements BackendProtocolV2 {
    * Get files from current state.
    *
    * In legacy mode, reads from the injected {@link BackendRuntime}.
-   * In zero-arg mode, reads from the LangGraph execution context via
-   * {@link getCurrentTaskInput}.
+   * In zero-arg mode, reads via {@link PREGEL_READ_KEY} with fresh=true,
+   * which applies any pending task writes through the reducer before returning.
    */
-  private getFiles;
+  private get files();
   /**
    * Push a files state update through LangGraph's internal send channel.
    *
@@ -900,32 +954,76 @@ declare class StateBackend implements BackendProtocolV2 {
 }
 //#endregion
 //#region src/backends/store.d.ts
+/**
+ * Context provided to dynamic namespace factory functions.
+ */
+interface StoreBackendContext<StateT = unknown> {
+  /**
+   * Current graph state, when available.
+   *
+   * In legacy factory mode this is the injected runtime state. In zero-arg mode
+   * this is read from the current LangGraph execution context.
+   */
+  state: StateT;
+  /**
+   * Runnable config, when available.
+   *
+   * This mirrors the Python implementation's access to config metadata for
+   * namespace resolution.
+   */
+  config?: {
+    metadata?: Record<string, unknown>;
+    configurable?: Record<string, unknown>;
+  };
+  /**
+   * Legacy assistant identifier, resolved from config metadata first and then
+   * from the injected runtime for backwards compatibility.
+   */
+  assistantId?: string;
+}
+type StoreBackendNamespaceFactory<StateT = unknown> = (context: StoreBackendContext<StateT>) => string[];
 /**
  * Options for StoreBackend constructor.
  */
-interface StoreBackendOptions extends BackendOptions {
+interface StoreBackendOptions<StateT = unknown> extends BackendOptions {
+  /**
+   * Explicit store instance to use for persistence.
+   *
+   * This mirrors the Python API and allows constructing a backend directly with
+   * a store instance, e.g. `new StoreBackend({ store })`.
+   *
+   * When omitted, the backend uses the legacy injected runtime store or the
+   * LangGraph execution-context store.
+   */
+  store?: BaseStore;
   /**
    * Custom namespace for store operations.
    *
-   * Determines where files are stored in the LangGraph store, enabling
-   * user-scoped, org-scoped, or any custom isolation pattern.
+   * Accepts either a static namespace array or a factory that derives the
+   * namespace from the current backend context.
    *
-   * If not provided, falls back to legacy behavior using assistantId from {@link BackendRuntime}.
+   * If not provided, falls back to legacy assistant-id detection from config
+   * metadata, then the injected runtime's `assistantId`, and finally
+   * `["filesystem"]`.
    *
    * @example
    * ```typescript
-   * // User-scoped storage
-   * new StoreBackend(runtime, {
+   * // Static namespace
+   * new StoreBackend({
    *   namespace: ["memories", orgId, userId, "filesystem"],
    * });
    *
-   * // Org-scoped storage
-   * new StoreBackend(runtime, {
-   *   namespace: ["memories", orgId, "filesystem"],
+   * // Dynamic namespace
+   * new StoreBackend({
+   *   namespace: ({ state }) => [
+   *     "memories",
+   *     (state as { userId: string }).userId,
+   *     "filesystem",
+   *   ],
    * });
    * ```
    */
-  namespace?: string[];
+  namespace?: string[] | StoreBackendNamespaceFactory<StateT>;
 }
 /**
  * Backend that stores files in LangGraph's BaseStore (persistent).
@@ -939,6 +1037,7 @@ interface StoreBackendOptions extends BackendOptions {
  */
 declare class StoreBackend implements BackendProtocolV2 {
   private stateAndStore;
+  private storeOverride;
   private _namespace;
   private fileFormat;
   constructor(options?: StoreBackendOptions);
@@ -957,15 +1056,28 @@ declare class StoreBackend implements BackendProtocolV2 {
    * @throws Error if no store is available in either mode
    */
   private getStore;
+  /**
+   * Get the current graph state when available.
+   */
+  private getState;
+  /**
+   * Get the most relevant runnable config for namespace resolution.
+   */
+  private getNamespaceConfig;
+  /**
+   * Legacy assistant-id detection compatible with both Python and the
+   * historical TypeScript `assistantId` runtime property.
+   */
+  private getLegacyAssistantId;
   /**
    * Get the namespace for store operations.
    *
    * Resolution order:
-   * 1. Explicit namespace from constructor options (both modes)
-   * 2. Legacy mode: `[assistantId, "filesystem"]` fallback from {@link StateAndStore}
-   * 3. Zero-arg mode without namespace: `["filesystem"]` with a deprecation warning
-   *    nudging callers to pass an explicit namespace
-   * 4. Legacy mode without assistantId: `["filesystem"]`
+   * 1. Explicit namespace from constructor options
+   * 2. Namespace factory resolved from the current backend context
+   * 3. Assistant ID from runtime config / LangGraph config metadata
+   * 4. Legacy `assistantId` from the injected runtime
+   * 5. `["filesystem"]`
    */
   protected getNamespace(): string[];
   /**
@@ -1187,6 +1299,15 @@ declare class CompositeBackend implements BackendProtocolV2 {
   constructor(defaultBackend: AnyBackendProtocol, routes: Record<string, AnyBackendProtocol>);
   /** Delegates to default backend's id if it is a sandbox, otherwise empty string. */
   get id(): string;
+  /** Route prefixes registered on this backend (e.g. `["/workspace"]`). */
+  get routePrefixes(): string[];
+  /**
+   * Type guard — returns true if `backend` is a {@link CompositeBackend}.
+   *
+   * Uses duck-typing on `routePrefixes` so it works across module boundaries
+   * where `instanceof` may fail.
+   */
+  static isInstance(backend: unknown): backend is CompositeBackend;
   /**
    * Determine which backend handles this key and strip prefix.
    *
@@ -1579,6 +1700,8 @@ interface LangSmithSandboxCreateOptions extends Omit<CreateSandboxOptions, "name
  *
  * Use the static `LangSmithSandbox.create()` factory for the simplest setup,
  * or construct directly with an existing `Sandbox` instance.
+ *
+ * @experimental This feature is experimental, and breaking changes are expected.
  */
 declare class LangSmithSandbox extends BaseSandbox {
   #private;
@@ -1797,6 +1920,27 @@ interface SubAgent {
    * ```
    */
   responseFormat?: CreateAgentParams["responseFormat"];
+  /**
+   * Filesystem permission rules for this subagent.
+   *
+   * When specified, these rules **replace** the parent agent's permissions
+   * for all tool calls made by this subagent. When omitted, the subagent
+   * inherits the parent agent's permissions.
+   *
+   * Subagent permissions are a full replacement, not a merge.
+   *
+   * @example
+   * ```ts
+   * // Parent denies /restricted/**; this subagent can read it.
+   * const reader: SubAgent = {
+   *   name: "reader",
+   *   permissions: [
+   *     { operations: ["read"], paths: ["/restricted/**"] },
+   *   ],
+   * };
+   * ```
+   */
+  permissions?: FilesystemPermission[];
 }
 /**
  * Base specification for the general-purpose subagent.
@@ -2030,6 +2174,11 @@ interface SkillMetadata$1 {
    * - Space-delimited list of tool names
    */
   allowedTools?: string[];
+  /**
+   * Path to a JS/TS entrypoint file for a QuickJS REPL module, relative to the skill
+   * directory.
+   */
+  module?: string;
 }
 /**
  * Options for the skills middleware.
@@ -2078,6 +2227,7 @@ declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): Agent
     compatibility?: string | null | undefined;
     metadata?: Record<string, string> | undefined;
     allowedTools?: string[] | undefined;
+    module?: string | undefined;
   }[] | undefined, {
     name: string;
     description: string;
@@ -2086,6 +2236,7 @@ declare function createSkillsMiddleware(options: SkillsMiddlewareOptions): Agent
     compatibility?: string | null | undefined;
     metadata?: Record<string, string> | undefined;
     allowedTools?: string[] | undefined;
+    module?: string | undefined;
   }[] | undefined>;
   files: ReducedValue<FilesRecord | undefined, FilesRecordUpdate | undefined>;
 }>, undefined, unknown, readonly (_$_langchain_core_tools0.ClientTool | _$_langchain_core_tools0.ServerTool)[]>;
@@ -2189,8 +2340,9 @@ interface SummarizationMiddlewareOptions {
   /**
    * The language model to use for generating summaries.
    * Can be a model string (e.g., "gpt-4o-mini") or a language model instance.
+   * If omitted, middleware will use the active request model.
    */
-  model: string | BaseChatModel | BaseLanguageModel;
+  model?: string | BaseChatModel | BaseLanguageModel;
   /**
    * Backend instance or factory for persisting conversation history.
    */
@@ -2697,6 +2849,25 @@ interface CreateDeepAgentParams<TResponse extends SupportedResponseFormat = Supp
    * ```
    */
   skills?: string[];
+  /**
+   * Filesystem permission rules for this agent.
+   *
+   * Rules are evaluated in declaration order; first match wins; permissive
+   * default. Applied to `ls`, `read_file`, `write_file`, `edit_file`, `glob`,
+   * and `grep`. Subagents inherit these rules unless they specify their own
+   * `permissions` field.
+   *
+   * @example
+   * ```ts
+   * createDeepAgent({
+   *   permissions: [
+   *     { operations: ["read"], paths: ["/workspace/**"] },
+   *     { operations: ["read"], paths: ["/**"], mode: "deny" },
+   *   ],
+   * });
+   * ```
+   */
+  permissions?: FilesystemPermission[];
 }
 //#endregion
 //#region src/agent.d.ts
@@ -3135,5 +3306,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, 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 GlobResult, type GrepMatch, type GrepResult, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, 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, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
+export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, 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 FilesystemOperation, type FilesystemPermission, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GlobResult, type GrepMatch, type GrepResult, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, LangSmithSandbox, type LangSmithSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type PermissionMode, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, 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 StoreBackendContext, type StoreBackendNamespaceFactory, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
 //# sourceMappingURL=index.d.ts.map