deepagents 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 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, Runtime, StructuredTool, SystemMessage, ToolMessage, ToolRuntime, ToolStrategy } from "langchain";
+import { AgentMiddleware, AgentMiddleware as AgentMiddleware$1, AgentRunStream, AgentTypeConfig, CreateAgentParams, HumanMessage, InferMiddlewareStates, InterruptOnConfig, ProviderStrategy, ReactAgent, ResponseFormat, ResponseFormatUndefined, Runtime, StructuredTool, SystemMessage, ToolCallStreamUnion, ToolMessage, ToolRuntime, ToolStrategy } from "langchain";
 import * as _langgraph from "@langchain/langgraph";
-import { AnnotationRoot, Command, ReducedValue, StateSchema } from "@langchain/langgraph";
+import { AnnotationRoot, ChatModelStream, Command, Namespace, NativeStreamTransformer, ReducedValue, StateSchema, StreamTransformer } from "@langchain/langgraph";
 import { z } from "zod/v4";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
 import * as _messages from "@langchain/core/messages";
@@ -670,7 +670,74 @@ 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
+/**
+ * Tools that should be excluded from the large result eviction logic.
+ *
+ * This array contains tools that should NOT have their results evicted to the filesystem
+ * when they exceed token limits. Tools are excluded for different reasons:
+ *
+ * 1. Tools with built-in truncation (ls, glob, grep):
+ *    These tools truncate their own output when it becomes too large. When these tools
+ *    produce truncated output due to many matches, it typically indicates the query
+ *    needs refinement rather than full result preservation. In such cases, the truncated
+ *    matches are potentially more like noise and the LLM should be prompted to narrow
+ *    its search criteria instead.
+ *
+ * 2. Tools with problematic truncation behavior (read_file):
+ *    read_file is tricky to handle as the failure mode here is single long lines
+ *    (e.g., imagine a jsonl file with very long payloads on each line). If we try to
+ *    truncate the result of read_file, the agent may then attempt to re-read the
+ *    truncated file using read_file again, which won't help.
+ *
+ * 3. Tools that never exceed limits (edit_file, write_file):
+ *    These tools return minimal confirmation messages and are never expected to produce
+ *    output large enough to exceed token limits, so checking them would be unnecessary.
+ */
+/**
+ * All tool names registered by FilesystemMiddleware.
+ * This is the single source of truth — used by createDeepAgent to detect
+ * collisions with user-supplied tools at construction time.
+ */
+declare const FILESYSTEM_TOOL_NAMES: readonly ["ls", "read_file", "write_file", "edit_file", "glob", "grep", "execute"];
 /**
  * Type for the files state record.
  */
@@ -693,6 +760,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 +898,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 +981,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 +1064,7 @@ interface StoreBackendOptions extends BackendOptions {
  */
 declare class StoreBackend implements BackendProtocolV2 {
   private stateAndStore;
+  private storeOverride;
   private _namespace;
   private fileFormat;
   constructor(options?: StoreBackendOptions);
@@ -955,15 +1083,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 +1326,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 +1727,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 +1947,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 +2201,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 +2254,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 +2263,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 +2367,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.
    */
@@ -2321,6 +2502,19 @@ interface AsyncTask {
   /** ISO timestamp of the most recent status poll via the check tool. */
   checkedAt?: string;
 }
+/**
+ * Task statuses that will never change.
+ *
+ * When listing tasks, live-status fetches are skipped for tasks whose
+ * cached status is in this set, since they are guaranteed to be final.
+ */
+/**
+ * Names of the tools added by the async subagent middleware.
+ *
+ * Exported so `agent.ts` can include them in `BUILTIN_TOOL_NAMES` and
+ * surface a `ConfigurationError` if a user-provided tool collides.
+ */
+declare const ASYNC_TASK_TOOL_NAMES: readonly ["start_async_task", "check_async_task", "update_async_task", "cancel_async_task", "list_async_tasks"];
 /**
  * Options for creating async subagent middleware.
  */
@@ -2422,8 +2616,100 @@ declare function createAsyncSubAgentMiddleware(options: AsyncSubAgentMiddlewareO
   statusFilter?: string | null | undefined;
 }, string | Command<unknown, Record<string, unknown>, string>, unknown, "list_async_tasks">)[]>;
 //#endregion
+//#region src/stream.d.ts
+/**
+ * Represents a single subagent invocation observed during a deep agent run.
+ *
+ * @typeParam TOutput - The subagent's output state type. Defaults to
+ *   `unknown`; inferred to the subagent's `MergedAgentState` for
+ *   `CompiledSubAgent` via {@link SubagentRunStreamUnion}.
+ */
+interface SubagentRunStream<TOutput = unknown, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[]> {
+  readonly name: string;
+  readonly taskInput: Promise<string>;
+  readonly output: Promise<TOutput>;
+  readonly messages: AsyncIterable<ChatModelStream>;
+  readonly toolCalls: AsyncIterable<ToolCallStreamUnion<TTools>>;
+  readonly subagents: AsyncIterable<SubagentRunStream>;
+}
+/**
+ * Extract the output state type from a subagent spec.
+ * For `CompiledSubAgent<ReactAgent<Types>>`, resolves to the agent's
+ * invoke return type. Falls back to `unknown` for `SubAgent` and
+ * `AsyncSubAgent`.
+ */
+type SubagentOutputOf<T extends AnySubAgent> = T extends CompiledSubAgent<infer R> ? R extends ReactAgent<infer Types> ? Awaited<ReturnType<ReactAgent<Types>["invoke"]>> : unknown : unknown;
+/**
+ * Extract the tools tuple from a subagent spec.
+ * For `CompiledSubAgent<ReactAgent<Types>>`, resolves to `Types["Tools"]`.
+ * Falls back to the default `(ClientTool | ServerTool)[]` for `SubAgent`
+ * and `AsyncSubAgent`.
+ */
+type SubagentToolsOf<T extends AnySubAgent> = T extends CompiledSubAgent<infer R> ? R extends ReactAgent<infer Types> ? Types["Tools"] : readonly (ClientTool | ServerTool)[] : readonly (ClientTool | ServerTool)[];
+/**
+ * A typed `SubagentRunStream` variant for a single subagent spec.
+ * Narrows `.name` to the literal string type, `.output` to the
+ * inferred state type, and `.toolCalls` to the subagent's tools
+ * when available.
+ */
+type NamedSubagentRunStream<T extends AnySubAgent> = T extends {
+  name: infer N extends string;
+} ? SubagentRunStream<SubagentOutputOf<T>, SubagentToolsOf<T>> & {
+  readonly name: N;
+} : SubagentRunStream;
+/**
+ * Discriminated union of {@link SubagentRunStream} variants, one per
+ * subagent in `TSubagents`. Enables TypeScript to narrow `.output`
+ * when the consumer checks `sub.name === "someSubagentName"`.
+ */
+type SubagentRunStreamUnion<TSubagents extends readonly AnySubAgent[]> = { [K in keyof TSubagents]: NamedSubagentRunStream<TSubagents[K]> }[number];
+/**
+ * An {@link AgentRunStream} with native deep-agent projections assigned
+ * directly on the instance by `createGraphRunStream` (via `__native`
+ * transformers).
+ *
+ * This is a pure type overlay — no runtime class exists.  The
+ * `subagents` property is populated at runtime by the
+ * `createSubagentTransformer` registered at compile time.
+ */
+type DeepAgentRunStream<TValues = Record<string, unknown>, TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TSubagents extends readonly AnySubAgent[] = readonly AnySubAgent[], TExtensions extends Record<string, unknown> = Record<string, unknown>> = AgentRunStream<TValues, TTools, TExtensions> & {
+  /** Subagent invocation streams from the native SubagentTransformer. */subagents: AsyncIterable<SubagentRunStreamUnion<TSubagents>>;
+};
+interface SubagentProjection {
+  subagents: AsyncIterable<SubagentRunStream>;
+}
+/**
+ * Native transformer that correlates `task` tool calls into
+ * {@link SubagentRunStream} objects and routes child-namespace
+ * `tools` and `messages` events into per-subagent channels.
+ *
+ * Marked `__native: true` — the `subagents` projection key lands
+ * directly on the `GraphRunStream` instance as `run.subagents`.
+ */
+declare function createSubagentTransformer(path: Namespace): () => NativeStreamTransformer<SubagentProjection>;
+//#endregion
 //#region src/types.d.ts
 type AnyAnnotationRoot = AnnotationRoot<any>;
+/**
+ * Literal union of all built-in deep agent tool names.
+ * These are always present on the agent regardless of user-provided tools.
+ */
+type DeepAgentBuiltinToolName = (typeof FILESYSTEM_TOOL_NAMES)[number] | (typeof ASYNC_TASK_TOOL_NAMES)[number] | "task" | "write_todos";
+/**
+ * A placeholder StructuredTool type with a literal `name` for each
+ * built-in tool. Used to thread built-in tool names into the
+ * `ToolCallStreamUnion` so they appear in `run.toolCalls` alongside
+ * user-provided tools.
+ */
+type BuiltinToolPlaceholder<N extends string> = {
+  name: N;
+} & StructuredTool$1;
+/**
+ * Tuple of placeholder tool types for all built-in deep agent tools.
+ * Combined with `TTypes["Tools"]` in the `DeepAgentRunStream` return type.
+ */
+type DeepAgentBuiltinToolsTuple = { [K in DeepAgentBuiltinToolName]: BuiltinToolPlaceholder<K> }[DeepAgentBuiltinToolName][];
+type InferDeepAgentStreamExtensions<T extends ReadonlyArray<() => StreamTransformer<any>>> = T extends readonly [] ? Record<string, never> : T extends readonly [() => StreamTransformer<infer P>, ...infer Rest extends ReadonlyArray<() => StreamTransformer<any>>] ? P & InferDeepAgentStreamExtensions<Rest> : Record<string, unknown>;
 /** Any subagent specification — sync, compiled, or async. */
 type AnySubAgent = SubAgent | CompiledSubAgent | AsyncSubAgent;
 interface TypedToolStrategy<T = unknown> extends Array<ToolStrategy<any>> {
@@ -2504,7 +2790,7 @@ type InferStructuredResponse<T extends SupportedResponseFormat> = SupportedRespo
  * type Types = InferDeepAgentType<typeof agent, "Subagents">;
  * ```
  */
-interface DeepAgentTypeConfig<TResponse extends Record<string, any> | ResponseFormatUndefined = Record<string, any> | ResponseFormatUndefined, TState extends AnyAnnotationRoot | InteropZodObject | undefined = AnyAnnotationRoot | InteropZodObject | undefined, TContext extends AnyAnnotationRoot | InteropZodObject = AnyAnnotationRoot | InteropZodObject, TMiddleware extends readonly AgentMiddleware[] = readonly AgentMiddleware[], TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TSubagents extends readonly AnySubAgent[] = readonly AnySubAgent[]> extends AgentTypeConfig<TResponse, TState, TContext, TMiddleware, TTools> {
+interface DeepAgentTypeConfig<TResponse extends Record<string, any> | ResponseFormatUndefined = Record<string, any> | ResponseFormatUndefined, TState extends AnyAnnotationRoot | InteropZodObject | undefined = AnyAnnotationRoot | InteropZodObject | undefined, TContext extends AnyAnnotationRoot | InteropZodObject = AnyAnnotationRoot | InteropZodObject, TMiddleware extends readonly AgentMiddleware[] = readonly AgentMiddleware[], TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TSubagents extends readonly AnySubAgent[] = readonly AnySubAgent[], TStreamTransformers extends ReadonlyArray<() => StreamTransformer<any>> = ReadonlyArray<() => StreamTransformer<any>>> extends AgentTypeConfig<TResponse, TState, TContext, TMiddleware, TTools, TStreamTransformers> {
   /** The subagents array type for type-safe streaming */
   Subagents: TSubagents;
 }
@@ -2519,6 +2805,7 @@ interface DefaultDeepAgentTypeConfig extends DeepAgentTypeConfig {
   Middleware: readonly AgentMiddleware[];
   Tools: readonly (ClientTool | ServerTool)[];
   Subagents: readonly AnySubAgent[];
+  StreamTransformers: readonly [];
 }
 /**
  * DeepAgent extends ReactAgent with additional subagent type information.
@@ -2536,9 +2823,86 @@ interface DefaultDeepAgentTypeConfig extends DeepAgentTypeConfig {
  * type Subagents = InferDeepAgentSubagents<typeof agent>;
  * ```
  */
-type DeepAgent<TTypes extends DeepAgentTypeConfig = DeepAgentTypeConfig> = ReactAgent<TTypes> & {
-  /** Type brand for DeepAgent type inference */readonly "~deepAgentTypes": TTypes;
-};
+interface DeepAgent<TTypes extends DeepAgentTypeConfig = DeepAgentTypeConfig> extends ReactAgent<TTypes> {
+  /** Type brand for DeepAgent type inference */
+  readonly "~deepAgentTypes": TTypes;
+  /**
+   * Executes the agent with the v3 streaming interface, returning an
+   * {@link DeepAgentRunStream} that provides ergonomic, typed projections for
+   * messages, tool calls, subagents, and middleware events.
+   *
+   * Pass `version: "v3"` to opt into this projection-oriented stream. Omitting
+   * `version` preserves the legacy internal LangGraph event-stream behavior
+   * for compatibility with LangGraph Platform integrations.
+   *
+   * This v3 stream is experimental and its API may change in future releases.
+   * It will become the default in a future major release.
+   *
+   * @param state - The initial state for the agent execution. Can be:
+   *   - An object containing `messages` array and any middleware-specific state properties
+   *   - A Command object for more advanced control flow
+   *
+   * @param config - Runtime configuration including:
+   * @param config.version - Must be `"v3"` to use the {@link DeepAgentRunStream}
+   *   interface. The default legacy event stream is maintained for internal
+   *   integrations and should not be used for new user-facing agent streaming.
+   * @param config.context - The context for the agent execution.
+   * @param config.configurable - LangGraph configuration options like `thread_id`, `run_id`, etc.
+   * @param config.store - The store for the agent execution for persisting state.
+   * @param config.signal - An optional AbortSignal for the agent execution.
+   * @param config.recursionLimit - The recursion limit for the agent execution.
+   *
+   * @returns A Promise that resolves to an {@link DeepAgentRunStream} providing:
+   *   - `run.messages` — all AI message lifecycles with streaming `.text` and `.reasoning`
+   *   - `run.toolCalls` — individual tool call streams with `.input`, `.output`, `.status`
+   *   - `run.subagents` — subagent delegation streams
+   *   - `run.middleware` — middleware lifecycle events (before/after agent/model)
+   *   - `run.values` — state snapshots (async iterable + promise-like)
+   *   - `run.output` — final agent state when the run completes
+   *   - `run.subgraphs` — child subgraph run streams
+   *   - `run.extensions` — merged projections from user-supplied transformers
+   *
+   * @example
+   * ```typescript
+   * const run = await agent.streamEvents(
+   *   {
+   *     messages: [{ role: "user", content: "What's the weather in Paris?" }],
+   *   },
+   *   { version: "v3" }
+   * );
+   *
+   * // Stream all messages
+   * for await (const msg of run.messages) {
+   *   for await (const token of msg.text) {
+   *     process.stdout.write(token);
+   *   }
+   * }
+   *
+   * // Observe tool calls
+   * for await (const call of run.toolCalls) {
+   *   console.log(`Tool: ${call.name}`, call.input);
+   *   console.log(`Result:`, await call.output);
+   * }
+   *
+   * // Observe subagent delegations
+   * for await (const subagent of run.subagents) {
+   *   console.log(`Subagent: ${subagent.name}`);
+   *
+   *   for await (const msg of subagent.messages) {
+   *     for await (const token of msg.text) {
+   *       process.stdout.write(token);
+   *     }
+   *   }
+   * }
+   *
+   * // Get final state
+   * const state = await run.output;
+   * ```
+   */
+  streamEvents: ((state: Parameters<ReactAgent<TTypes>["invoke"]>[0], config: NonNullable<Parameters<ReactAgent<TTypes>["invoke"]>[1]> & {
+    version: "v3";
+  }) => Promise<DeepAgentRunStream<Awaited<ReturnType<ReactAgent<TTypes>["invoke"]>>, readonly [...TTypes["Tools"], ...DeepAgentBuiltinToolsTuple], TTypes["Subagents"], InferDeepAgentStreamExtensions<TTypes["StreamTransformers"]>>>) & ReactAgent<TTypes>["streamEvents"];
+}
 /**
  * Helper type to resolve a DeepAgentTypeConfig from either:
  * - A DeepAgentTypeConfig directly
@@ -2618,8 +2982,9 @@ type InferSubagentReactAgentType<TSubagent extends SubAgent | CompiledSubAgent>
  * @typeParam TMiddleware - The middleware array type for proper type inference
  * @typeParam TSubagents - The subagents array type for extracting subagent middleware states
  * @typeParam TTools - The tools array type
+ * @typeParam TStreamTransformers - Custom stream transformer factories
  */
-interface CreateDeepAgentParams<TResponse extends SupportedResponseFormat = SupportedResponseFormat, ContextSchema extends AnnotationRoot<any> | InteropZodObject = AnnotationRoot<any>, TMiddleware extends readonly AgentMiddleware[] = readonly AgentMiddleware[], TSubagents extends readonly AnySubAgent[] = readonly AnySubAgent[], TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[]> {
+interface CreateDeepAgentParams<TResponse extends SupportedResponseFormat = SupportedResponseFormat, ContextSchema extends AnnotationRoot<any> | InteropZodObject = AnnotationRoot<any>, TMiddleware extends readonly AgentMiddleware[] = readonly AgentMiddleware[], TSubagents extends readonly AnySubAgent[] = readonly AnySubAgent[], TTools extends readonly (ClientTool | ServerTool)[] = readonly (ClientTool | ServerTool)[], TStreamTransformers extends ReadonlyArray<() => StreamTransformer<any>> = readonly []> {
   /** The model to use (model name string or LanguageModelLike instance). Defaults to claude-sonnet-4-5-20250929 */
   model?: BaseLanguageModel | string;
   /** Tools the agent should have access to */
@@ -2695,6 +3060,33 @@ 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[];
+  /**
+   * Optional {@link StreamTransformer} factories to register with the underlying agent.
+   *
+   * Deepagents always registers its built-in subagent transformer; custom
+   * transformers are appended after it and are exposed on `run.extensions`
+   * when using `streamEvents(..., { version: "v3" })`.
+   */
+  streamTransformers?: TStreamTransformers;
 }
 //#endregion
 //#region src/agent.d.ts
@@ -2728,7 +3120,7 @@ interface CreateDeepAgentParams<TResponse extends SupportedResponseFormat = Supp
  * // result.research is properly typed as string
  * ```
  */
-declare function createDeepAgent<TResponse extends SupportedResponseFormat = SupportedResponseFormat, ContextSchema extends InteropZodObject = InteropZodObject, const TMiddleware extends readonly AgentMiddleware[] = readonly [], const TSubagents extends readonly AnySubAgent[] = readonly [], const TTools extends readonly (ClientTool | ServerTool)[] = readonly []>(params?: CreateDeepAgentParams<TResponse, ContextSchema, TMiddleware, TSubagents, TTools>): DeepAgent<DeepAgentTypeConfig<InferStructuredResponse<TResponse>, undefined, ContextSchema, readonly [AgentMiddleware<_$zod_v30.ZodObject<{
+declare function createDeepAgent<TResponse extends SupportedResponseFormat = SupportedResponseFormat, ContextSchema extends InteropZodObject = InteropZodObject, const TMiddleware extends readonly AgentMiddleware[] = readonly [], const TSubagents extends readonly AnySubAgent[] = readonly [], const TTools extends readonly (ClientTool | ServerTool)[] = readonly [], const TStreamTransformers extends ReadonlyArray<() => StreamTransformer<any>> = readonly []>(params?: CreateDeepAgentParams<TResponse, ContextSchema, TMiddleware, TSubagents, TTools, TStreamTransformers>): DeepAgent<DeepAgentTypeConfig<InferStructuredResponse<TResponse>, undefined, ContextSchema, readonly [AgentMiddleware<_$zod_v30.ZodObject<{
   todos: _$zod_v30.ZodDefault<_$zod_v30.ZodArray<_$zod_v30.ZodObject<{
     content: _$zod_v30.ZodString;
     status: _$zod_v30.ZodEnum<["pending", "in_progress", "completed"]>;
@@ -2886,7 +3278,7 @@ declare function createDeepAgent<TResponse extends SupportedResponseFormat = Sup
     summaryMessage: z$2.ZodCustom<_messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>, _messages.HumanMessage<_messages.MessageStructure<_messages.MessageToolSet>>>;
     filePath: z$2.ZodNullable<z$2.ZodString>;
   }, _$zod_v4_core0.$strip>>;
-}, _$zod_v4_core0.$strip>, undefined, unknown, 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, TStreamTransformers>>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -3133,5 +3525,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 DeepAgentRunStream, 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 SubagentRunStream, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSubagentTransformer, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
 //# sourceMappingURL=index.d.cts.map