@google/adk 1.6.0 → 2.0.0

package/dist/types/tools/tool_confirmation.d.ts

@@ -23,3 +23,50 @@ export declare class ToolConfirmation {
         payload?: unknown;
     });
 }
+/**
+ * Why a confirmation was refused. Each value is one of the checks the resume
+ * path makes before it runs a tool call a human approved.
+ */
+export type IntentMismatchReason = 
+/** The `adk_request_confirmation` call was not raised by the agent. */
+'untrusted_request'
+/** The `adk_request_confirmation` call carries no usable pinned call. */
+ | 'malformed_request'
+/** The pinned call is absent from session history. */
+ | 'unknown_original_call'
+/** The pinned call names a tool the agent does not have. */
+ | 'unregistered_tool'
+/** The pinned tool does not gate on confirmation, so nothing was approved. */
+ | 'confirmation_not_required'
+/** The pinned tool name disagrees with the call in history. */
+ | 'tool_name_mismatch'
+/** The pinned arguments disagree with the call in history. */
+ | 'arguments_mismatch';
+/**
+ * Raised when a tool confirmation does not bind to the action it claims to
+ * approve — the approval and the action about to run are not the same thing.
+ *
+ * The framework fails closed on this: a mismatch aborts the invocation rather
+ * than running an action no human agreed to. It is worth alerting on, so the
+ * message names the reason and the call, and deliberately carries no argument
+ * values — a rejected payload is attacker-controlled and does not belong in
+ * logs.
+ */
+export declare class IntentMismatchError extends Error {
+    /** Which binding check refused the confirmation. */
+    readonly reason: IntentMismatchReason;
+    /** The id of the pinned call, when one was named. */
+    readonly functionCallId?: string;
+    constructor(options: {
+        reason: IntentMismatchReason;
+        functionCallId?: string;
+    });
+}
+/**
+ * Type guard for {@link IntentMismatchError}.
+ *
+ * Matches on `name` rather than `instanceof` so it stays correct when the error
+ * crosses a package boundary (two copies of adk-js in one runtime would fail an
+ * `instanceof` check between them).
+ */
+export declare function isIntentMismatchError(e: unknown): e is IntentMismatchError;

package/dist/types/utils/async_queue.d.ts

@@ -4,15 +4,47 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
- * A generic, async-safe queue that implements AsyncIterable.
+ * A generic, single-consumer async queue that implements AsyncIterable,
+ * bridging a *push* producer to a *pull* consumer (`for await (const x of q)`).
+ *
+ * Producers call {@link push} as values are produced and {@link close} (or
+ * {@link fail}) when finished. A single consumer drains the queue.
+ *
+ * Semantics:
+ *  - Buffered items are always delivered before an end/error signal.
+ *  - {@link close} ends iteration cleanly (`done: true`); idempotent.
+ *  - {@link fail} surfaces the error to the consumer *after* any buffered items
+ *    have been drained; it is sticky (first failure wins) and also closes the
+ *    queue, so a later `close()` can't discard the error.
+ *  - {@link push} after close/fail is ignored (the producer has already
+ *    signalled completion).
  */
 export declare class AsyncQueue<T> implements AsyncIterable<T> {
     private queue;
     private resolvers;
     private closed;
-    private errorVal?;
+    private failure?;
+    /** Whether the queue has been closed or failed. */
+    get isClosed(): boolean;
+    /** Number of items buffered and not yet consumed. */
+    get size(): number;
+    /**
+     * Enqueues a value. If a consumer is currently awaiting, it is resolved
+     * immediately; otherwise the value is buffered. No-op once closed/failed.
+     */
     push(value: T): void;
+    /**
+     * Signals that production failed. Buffered items are still delivered first;
+     * once the buffer drains, the consumer's next `next()` rejects with `error`.
+     * Sticky (first failure wins) and closes the queue.
+     */
+    fail(error: unknown): void;
+    /** @deprecated Alias for {@link fail}; kept for existing callers. */
     error(err: unknown): void;
+    /**
+     * Signals that no more items will be produced. Any awaiting consumer receives
+     * `{done: true}`. Idempotent.
+     */
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }

package/dist/types/utils/deprecated.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Resets the warned-once registry. Test-only. */
+export declare function resetDeprecationWarnings(): void;
+type Constructor = new (...args: any[]) => any;
+/**
+ * Marks a class as deprecated, logging `reason` once the first time it is
+ * instantiated.
+ *
+ * The JSDoc `@deprecated` tag is what a reader and an editor see; this is what
+ * someone running the code sees, so a deprecation is not silent to a caller who
+ * never opens the source. Mirrors `typing_extensions.deprecated`, which
+ * adk-python applies to the same classes, and follows the shape of
+ * {@link experimental}: one warning per class, not per instance, so a hot loop
+ * does not turn into a wall of logs.
+ */
+export declare function deprecated(reason: string): <T extends Constructor>(target: T) => T;
+export {};

package/dist/types/utils/env_aware_utils.d.ts

@@ -59,3 +59,19 @@ export declare function isBase64Encoded(data: string): boolean;
  * @return The boolean value of the environment variable.
  */
 export declare function getBooleanEnvVar(envVar: string): boolean;
+/**
+ * Returns whether Google GenAI enterprise mode is enabled.
+ *
+ * `GOOGLE_GENAI_USE_ENTERPRISE` takes precedence whenever it is set, even when
+ * it is set to a falsy value. `GOOGLE_GENAI_USE_VERTEXAI` is only consulted
+ * when `GOOGLE_GENAI_USE_ENTERPRISE` is absent.
+ *
+ * Setting the deprecated `GOOGLE_GENAI_USE_VERTEXAI` logs a deprecation
+ * warning, whether it is used or overridden. When both variables are set the
+ * warning also states that `GOOGLE_GENAI_USE_VERTEXAI` is ignored, so a stale
+ * value silently overridden by the new variable is still surfaced. This is
+ * read per request, so the warning is logged only once.
+ *
+ * @return True if enterprise mode is enabled, false otherwise.
+ */
+export declare function isEnterpriseModeEnabled(): boolean;

package/dist/types/utils/file_utils.d.ts

@@ -5,9 +5,17 @@
  */
 import { File } from '../code_executors/code_execution_utils.js';
 /**
- * Creates files with the given paths in the current working directory.
+ * Writes `files` into `dir`, refusing any entry that resolves outside of it.
+ *
+ * `dir` is deliberately required and has no default: file names typically
+ * originate from a code executor's output (i.e. from model- or skill-controlled
+ * content), so the destination must be a dedicated directory chosen by the
+ * caller. Defaulting to `process.cwd()` would let such content drop files into
+ * the host application's working directory.
+ *
  * @param files The files to materialize.
+ * @param dir The directory to materialize the files into.
  */
-export declare function materializeFiles(files: File[], dir?: string): Promise<File[]>;
+export declare function materializeFiles(files: File[], dir: string): Promise<File[]>;
 export declare const EXTENSION_TO_MIME_TYPE: Record<string, string>;
 export declare function guessMimeType(filePath: string): string;

package/dist/types/utils/genai_schema_to_json.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Schema } from '@google/genai';
+/**
+ * Converts a genai `Schema` into a standard JSON Schema object.
+ *
+ * This is the inverse of `zodObjectToSchema`, which renders Zod into the
+ * genai/OpenAPI dialect. The two dialects differ in four ways, all handled
+ * here:
+ *
+ * - `type` is an uppercase enum (`STRING`) rather than a JSON Schema type name
+ *   (`string`). `TYPE_UNSPECIFIED` means "no constraint" and is dropped.
+ * - `nullable: true` widens the type, which JSON Schema expresses as a type
+ *   union (`['string', 'null']`).
+ * - Count and length bounds are stringified (`maxItems: '5'`).
+ * - `propertyOrdering` and `example` have no JSON Schema equivalent.
+ *
+ * Everything else (`description`, `title`, `default`, `pattern`, `required`,
+ * `minimum`, `maximum`, `format`) is already JSON-Schema-shaped and passes
+ * through, with `items`, `properties` and `anyOf` converted recursively.
+ */
+export declare function genaiSchemaToJsonSchema(schema: Schema): Record<string, unknown>;

package/dist/types/utils/optional_peer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Describes the optional peer dependency a feature is asking for. */
+export interface OptionalPeer {
+    /** The npm package name, e.g. `@google-cloud/storage`. */
+    packageName: string;
+    /** The ADK feature that needs it, used in the error message. */
+    feature: string;
+}
+/**
+ * Loads an optional peer dependency, translating "not installed" into an
+ * actionable error.
+ *
+ * The dynamic `import()` is passed in as a thunk rather than being built from
+ * `packageName`, so that the specifier stays a literal in the calling module
+ * and remains visible to bundlers and to test doubles installed with
+ * `vi.mock()`.
+ *
+ * ```ts
+ * const {Storage} = await loadOptionalPeer(
+ *   {packageName: '@google-cloud/storage', feature: 'GcsArtifactService'},
+ *   () => import('@google-cloud/storage'),
+ * );
+ * ```
+ *
+ * @param peer The package being loaded and the feature that needs it.
+ * @param load Thunk performing the dynamic `import()`.
+ * @return The imported module namespace.
+ * @throws If the package is not installed, an error naming the feature and
+ *   the `npm install` command that fixes it. Any other load failure is
+ *   rethrown unchanged.
+ */
+export declare function loadOptionalPeer<T>(peer: OptionalPeer, load: () => Promise<T>): Promise<T>;

package/dist/types/utils/redact_uri.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Redacts the credentials from a connection URI so the URI can be safely
+ * included in error messages and logs.
+ *
+ * A database or session-service connection URI such as
+ * `postgres://user:password@host:5432/db` embeds the password in its userinfo
+ * component. Including such a URI verbatim in a thrown Error or log entry leaks
+ * the credential to wherever those are collected (log files, error-tracking
+ * services, stdout captured by an orchestrator), which is frequently a
+ * different trust boundary from whoever provisioned the connection string.
+ *
+ * The same credential can instead arrive as a query parameter, for example
+ * `postgres://user@host/db?password=secret`, which several drivers accept and
+ * which reaches the same error paths. Both forms are masked.
+ *
+ * The rest of the URI is kept intact for debugging, mirroring the semantics of
+ * Go's `net/url.URL.Redacted()`. A URI carrying no credential is returned
+ * unchanged, byte for byte.
+ *
+ * If the input cannot be parsed as a URL, only its scheme prefix is returned so
+ * that a credential embedded in an otherwise-unparseable string is not leaked.
+ */
+export declare function redactUriPassword(uri: string): string;

package/dist/types/utils/schema.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A single, reusable abstraction over the schema formats ADK APIs accept: a Zod
+ * v3 type, a Zod v4 type, or a genai `Schema`. Mirrors the union
+ * `FunctionTool` uses for its parameters, but at the `ZodType` level (any
+ * schema, not just an object) so it also fits value validation.
+ */
+import { Schema } from '@google/genai';
+import { z as z3 } from 'zod/v3';
+import { z as z4 } from 'zod/v4';
+/**
+ * A schema accepted by ADK APIs, expressed as a Zod v3 type, a Zod v4 type, or
+ * a genai `Schema`.
+ *
+ * Use `parseWithSchema` to validate a value against one, and `toJsonSchema` to
+ * render one as a plain JSON Schema.
+ */
+export type SchemaLike = z3.ZodType | z4.ZodType | Schema;
+/**
+ * Validates `value` against `schema`, returning the parsed value.
+ *
+ * Every schema form ADK accepts is enforced:
+ *
+ * - Zod v3/v4: runs `schema.parse(value)`.
+ * - genai `Schema`: converted to JSON Schema and compiled to a Zod type once
+ *   (then cached), so a declaration written in the genai dialect is checked
+ *   just as a Zod one is.
+ * - `undefined`: returns `value` unchanged.
+ *
+ * A genai `Schema` that has no Zod equivalent is left unenforced rather than
+ * rejected — see {@link genaiSchemaValidator}.
+ */
+export declare function parseWithSchema<T>(schema: SchemaLike | undefined, value: T): T;
+/**
+ * Renders a {@link SchemaLike} as a plain JSON Schema object.
+ *
+ * Zod v3 and v4 schemas are converted with their respective serializers. A
+ * genai `Schema` is translated out of the genai/OpenAPI dialect (uppercase
+ * type names, stringified bounds, `nullable`) so that every schema form
+ * produces the same JSON Schema shape for a consumer to read.
+ */
+export declare function toJsonSchema(schema: SchemaLike): Record<string, unknown>;
+/**
+ * Compiles a plain JSON Schema into a validator, for schemas that survive only
+ * in serialized form — a `RequestInput.responseSchema` reaches the resume that
+ * answers it as the JSON Schema recorded on the interrupt event, not as the
+ * original {@link SchemaLike}.
+ *
+ * Returns `undefined` when the schema cannot be compiled (JSON Schema is wider
+ * than Zod can express). Callers treat that as "no contract to check" rather
+ * than failing: refusing data because we could not build the validator would be
+ * worse than the unchecked pass-through this replaces.
+ */
+export declare function compileJsonSchema(jsonSchema: unknown): z4.ZodType | undefined;
+/**
+ * Decomposes an object {@link SchemaLike} into its declared fields, each mapped
+ * to a validator for that field alone.
+ *
+ * This is what lets a *partial* object be checked key by key. A state schema
+ * declares the keys a workflow may write, but the state holds only the ones
+ * written so far, so validating the whole object against the schema would
+ * reject it for missing fields that simply have not been set yet.
+ *
+ * Returns `undefined` when the schema is not an object schema or cannot be
+ * decomposed, and maps a field to `undefined` when that field's own schema has
+ * no Zod equivalent. Both mean "unvalidatable" rather than invalid, consistent
+ * with {@link parseWithSchema}.
+ */
+export declare function objectSchemaFields(schema: SchemaLike): Map<string, z4.ZodType | undefined> | undefined;

package/dist/types/utils/simple_zod_to_json.d.ts

@@ -6,8 +6,16 @@
 import { Schema } from '@google/genai';
 import { z as z3 } from 'zod/v3';
 import { z as z4 } from 'zod/v4';
+type ZodSchema<T = unknown> = z3.ZodType<T> | z4.ZodType<T>;
+/** Returns true if the value is a Zod schema (v3 or v4). */
+export declare function isZodSchema(obj: unknown): obj is ZodSchema;
+/** Returns true if the value is a Zod v3 schema. */
+export declare function isZodV3Schema(obj: unknown): obj is z3.ZodTypeAny;
+/** Returns true if the value is a Zod v4 schema. */
+export declare function isZodV4Schema(obj: unknown): obj is z4.ZodType;
 /**
  * Returns true if the given object is a ZodObject (supports both Zod v3 and v4).
  */
 export declare function isZodObject(obj: unknown): obj is z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape>;
 export declare function zodObjectToSchema(schema: z3.ZodObject<z3.ZodRawShape> | z4.ZodObject<z4.ZodRawShape>): Schema;
+export {};

package/dist/types/utils/vertex_ai_utils.d.ts

@@ -7,6 +7,10 @@ export declare const EXPRESS_MODE_UNSUPPORTED_MESSAGE: string;
 /**
  * Validates and returns the API key for Express Mode.
  *
+ * The key is only returned when enterprise mode is enabled via
+ * `GOOGLE_GENAI_USE_ENTERPRISE` (or the deprecated
+ * `GOOGLE_GENAI_USE_VERTEXAI`).
+ *
  * @param project The project id.
  * @param location The location.
  * @param expressModeApiKey The API key for Express Mode.

package/dist/types/version.d.ts

@@ -3,4 +3,4 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-export declare const version = "1.6.0";
+export declare const version = "2.0.0";

package/dist/types/workflow/base_node.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Content } from '@google/genai';
+import { Event } from '../events/event.js';
+import { SchemaLike } from '../utils/schema.js';
+import type { NodeContext } from './node_context.js';
+import { PreparedRetryConfig, RetryConfig } from './retry_config.js';
+/**
+ * A unique symbol branding {@link BaseNode} instances.
+ *
+ * Guards match on this brand rather than `instanceof` so a node stays
+ * recognisable when it crosses a package boundary (two copies of adk-js in one
+ * runtime would fail an `instanceof` check between them) — mirroring the
+ * `Symbol.for('google.adk.*')` brands used across ADK (`isBaseAgent`,
+ * `isBaseTool`, `isEvent`).
+ */
+declare const BASE_NODE_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * Configuration shared by all workflow nodes.
+ *
+ * Mirrors the fields of `google/adk-python` `workflow/_base_node.py::BaseNode`.
+ */
+export interface BaseNodeConfig {
+    /** Canonical, unique-within-a-graph node name. */
+    name: string;
+    /** Human-readable description (used when a node is exposed as a tool). */
+    description?: string;
+    /**
+     * If true, the node re-executes when a workflow resumes even if it already
+     * completed in a prior turn. Default false.
+     */
+    rerunOnResume?: boolean;
+    /**
+     * If true, the node only produces its output once all of its predecessors
+     * have triggered it (fan-in / join semantics). Default false.
+     */
+    waitForOutput?: boolean;
+    /** Optional retry configuration for transient failures. */
+    retryConfig?: RetryConfig;
+    /** Maximum time, in seconds, for this node to complete. */
+    timeout?: number;
+    /** Optional schema validating the node input (Zod v3/v4 or genai `Schema`). */
+    inputSchema?: SchemaLike;
+    /** Optional schema validating the node output (Zod v3/v4 or genai `Schema`). */
+    outputSchema?: SchemaLike;
+    /** Optional schema validating relevant session state (Zod v3/v4 or genai `Schema`). */
+    stateSchema?: SchemaLike;
+    /**
+     * Runs this node's subtree in an isolated conversation scope: an agent inside
+     * it sees only session events carrying the same scope, plus untagged ones.
+     * `true` derives a scope per node run; a string is an explicit shared tag.
+     */
+    isolationScope?: string | true;
+}
+/**
+ * Abstract base class for all nodes in an ADK workflow.
+ *
+ * A node is a discrete unit of execution. Subclasses implement {@link runImpl},
+ * which may yield {@link Event}s, raw values (boxed into an event), or
+ * `null`/`undefined` (skipped). {@link run} normalizes those into a stream of
+ * {@link Event}s consumed by the engine.
+ */
+export declare abstract class BaseNode<TInput = unknown, TOutput = unknown> {
+    /** Brand identifying this object as a {@link BaseNode} (see `isBaseNode`). */
+    readonly [BASE_NODE_SIGNATURE_SYMBOL] = true;
+    readonly name: string;
+    readonly description: string;
+    readonly rerunOnResume: boolean;
+    readonly waitForOutput: boolean;
+    readonly retryConfig?: RetryConfig;
+    /**
+     * The retry config with its exception filter normalized once, up front (see
+     * {@link prepareRetryConfig}). Used by the node runner so the retry hot path
+     * never re-normalizes or throws on a malformed config mid-retry.
+     */
+    readonly preparedRetryConfig?: PreparedRetryConfig;
+    readonly timeout?: number;
+    readonly inputSchema?: SchemaLike;
+    readonly outputSchema?: SchemaLike;
+    readonly stateSchema?: SchemaLike;
+    readonly isolationScope?: string | true;
+    constructor(config: BaseNodeConfig);
+    /**
+     * Whether this node must wait for ALL of its predecessors to trigger before
+     * it runs (fan-in barrier). Overridden by `JoinNode`.
+     */
+    get requiresAllPredecessors(): boolean;
+    /**
+     * Core execution contract. Subclasses yield one of:
+     *  - an {@link Event} (emitted as-is),
+     *  - a raw value (boxed into an event whose `output` is that value),
+     *  - `null`/`undefined` (skipped).
+     */
+    protected abstract runImpl(ctx: NodeContext, input: TInput): AsyncGenerator<Event | TOutput | unknown, void, void>;
+    /**
+     * Runs the node, normalizing every yielded item into an {@link Event}. This
+     * is what the engine (and `ctx.runNode()`) consumes. Validates the input
+     * against `inputSchema` once, up front (skipping genai `Content`, which nodes
+     * coerce themselves).
+     */
+    run(ctx: NodeContext, input: TInput): AsyncGenerator<Event, void, void>;
+    /**
+     * Validates node input against `inputSchema` (Content passes through). Only
+     * enforced for Zod schemas; a genai `Schema` is left unvalidated (see
+     * `parseWithSchema`).
+     */
+    protected validateInput(input: TInput): TInput;
+    /**
+     * Validates node output against `outputSchema` (Content passes through). Only
+     * enforced for Zod schemas; a genai `Schema` is left unvalidated (see
+     * `parseWithSchema`).
+     */
+    protected validateOutput(output: unknown): unknown;
+    /**
+     * Normalizes a single yielded item into an {@link Event} (or `null` to skip).
+     * Subclasses may override for richer coercion (e.g. `FunctionNode`).
+     */
+    protected toEvent(ctx: NodeContext, data: unknown): Event | null;
+}
+/**
+ * Type guard for {@link BaseNode}.
+ *
+ * Matches on the {@link BASE_NODE_SIGNATURE_SYMBOL} brand rather than
+ * `instanceof` so it stays correct across package copies (see the brand's doc).
+ */
+export declare function isBaseNode(value: unknown): value is BaseNode;
+/** Returns whether a value looks like a genai `Content` object. */
+export declare function isContent(value: unknown): value is Content;
+/** The workflow entry-point sentinel node (name `__START__`). */
+export declare const START: BaseNode;
+/**
+ * Best-effort conversion of an arbitrary value to genai `Content` for display.
+ *
+ * Strings, `Part`s, and arrays of them are converted via `createModelContent`.
+ * Any other value (a plain object, number, boolean, …) is not a valid genai
+ * part list, so it is serialized to text rather than throwing.
+ */
+export declare function toContent(val: unknown): Content | undefined;
+export {};

package/dist/types/workflow/branch_path.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Hierarchical, dot-separated path for execution branches. Each segment is a
+ * node run, typically formatted as `name@runId` (or just `name`).
+ *
+ * Ported from `google/adk-python` `events/_branch_path.py::_BranchPath`.
+ *
+ * @example 'parent_agent@1.collect_tool@2.sub_workflow'
+ */
+export declare class BranchPath {
+    private readonly segments;
+    constructor(segments: string[]);
+    toString(): string;
+    /** Returns a copy of the path segments. */
+    getSegments(): string[];
+    /** Whether this path is a strict descendant of `ancestor`. */
+    isDescendantOf(ancestor: BranchPath): boolean;
+    /** Returns a new path with a `name@runId` (or `name`) segment appended. */
+    append(name: string, runId?: string): BranchPath;
+}
+/** Parses a dot-separated string into a {@link BranchPath}. */
+export declare function branchPathFromString(path?: string | null): BranchPath;
+/** Finds the common prefix across a list of {@link BranchPath}s. */
+export declare function commonPrefixOfPaths(paths: BranchPath[]): BranchPath;
+/**
+ * Creates a new dot-separated sub-branch string by appending a segment.
+ *
+ * @example createSubBranch('parent', {name: 'child', runId: '1'}) -> 'parent.child@1'
+ * @example createSubBranch(undefined, {name: 'agent'}) -> 'agent'
+ */
+export declare function createSubBranch(baseBranch: string | undefined | null, options: {
+    name: string;
+    runId?: string;
+}): string;
+/** Finds the common prefix of a list of dot-separated branch strings. */
+export declare function commonPrefixOf(branches: string[]): string;

package/dist/types/workflow/dynamic_node_scheduler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseNode } from './base_node.js';
+import { NodeContext, NodeResult } from './node_context.js';
+import { DynamicNodeState, ScheduleDynamicNode, ScheduleDynamicNodeOptions } from './schedule_dynamic_node.js';
+/**
+ * Handles `ctx.runNode()` calls for a {@link Workflow} subtree.
+ *
+ * Ported (Phase 4 subset) from `google/adk-python`
+ * `workflow/_dynamic_node_scheduler.py`. Implemented now: fresh execution and
+ * deduplication of concurrent calls to the same node path. Resumption from
+ * session events (rehydration + replay interception) is added in Phase 5 at the
+ * marked hook point.
+ */
+export declare class DynamicNodeScheduler implements ScheduleDynamicNode {
+    private readonly state;
+    private readonly abortSignal?;
+    /**
+     * @param state Shared dynamic-node bookkeeping for this workflow subtree.
+     * @param abortSignal Workflow-scoped cancellation signal, forwarded to each
+     *   dynamic child so a workflow shutting down on error can cancel in-flight
+     *   `ctx.runNode()` children too.
+     */
+    constructor(state: DynamicNodeState, abortSignal?: AbortSignal | undefined);
+    /**
+     * Runs a `ctx.runNode()` call and reports any interrupt it is still waiting
+     * on to the caller's own context.
+     *
+     * A child's interrupt is the caller's problem: the caller cannot produce a
+     * trustworthy result until the human answers, and until the engine knows the
+     * caller is waiting it marks it COMPLETED and schedules its successor —
+     * which then runs on the `undefined` the caller returned when it bailed out.
+     * `ParallelWorker` has always copied its items' interrupt ids onto its own
+     * context for exactly this reason; doing it here extends that to every
+     * caller instead of only the one that remembered.
+     *
+     * Only unresolved interrupts arrive here. A child fast-forwarded from a
+     * checkpoint, or handed a resolved reply as its output, reports none.
+     */
+    schedule(ctx: NodeContext, node: BaseNode, input: unknown, options: ScheduleDynamicNodeOptions): Promise<NodeContext | NodeResult>;
+    private scheduleRun;
+    /**
+     * Books a dynamic run that completed WITHOUT executing its body — either
+     * fast-forwarded from a cached output or handed the resolved resume value —
+     * and returns `result` for `ctx.runNode()` to give back to the caller.
+     */
+    private completeWithoutRunning;
+    /**
+     * Applies a settled result to the caller's context and returns it, so a first
+     * call and a repeat call for the same path are indistinguishable.
+     */
+    private handBack;
+    /**
+     * Builds the completion result for a child that interrupted in a prior turn
+     * and whose interrupts are now all resolved, or `undefined` when the child is
+     * not in that state (so the caller falls through to a fresh run).
+     */
+    private resumeHandoff;
+    private runFresh;
+    private recordResult;
+}