@google/adk 1.5.0 → 2.0.0

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { SchemaLike } from '../utils/schema.js';
+/**
+ * A unique symbol branding {@link RequestInput} instances.
+ *
+ * {@link isRequestInput} matches on this brand rather than `instanceof` so a
+ * request built by another copy of adk-js in the same runtime is still
+ * recognised (an `instanceof` check fails across package copies). This matters
+ * because the guard gates the HITL interrupt path in `BaseNode.run`: a missed
+ * match would silently stringify the request into a text part instead of
+ * pausing the workflow. Mirrors the `Symbol.for('google.adk.*')` brands used
+ * across ADK.
+ */
+declare const REQUEST_INPUT_SIGNATURE_SYMBOL: unique symbol;
+/** Parameters for constructing a {@link RequestInput}. */
+export interface RequestInputParams {
+    /** The interrupt id (usually a function-call id). Auto-generated if omitted. */
+    interruptId?: string;
+    /** Custom payload provided for resuming. */
+    payload?: unknown;
+    /** A message to display to the user when requesting input. */
+    message?: string;
+    /**
+     * The expected shape of the reply (Zod v3/v4 or genai `Schema`).
+     *
+     * It tells a client what to collect — the dev UI renders a form from it —
+     * and a *structured* reply is checked against it on resume. Nothing coerces
+     * a human's answer into the shape: a plain-text reply is routed to the
+     * interrupt as-is and is not checked, so put an agent node after the pause
+     * if you need free text normalized.
+     */
+    responseSchema?: SchemaLike;
+}
+/**
+ * A request for input from the user, yielded/returned by a node to pause a
+ * workflow (Human-in-the-Loop). The framework converts it to an interrupt
+ * event; the workflow surfaces the interrupt id to the caller, which later
+ * resumes by providing `resumeInputs[interruptId]`.
+ *
+ * A client answers in one of two ways:
+ *
+ * - **Plain text.** A text turn is routed to every pending interrupt as-is.
+ *   This is what the interactive CLI sends, and the dev UI whenever it has no
+ *   schema to build a form from.
+ * - **A `functionResponse`** named `adk_request_input`, carrying the interrupt
+ *   id. Wrap a bare value as `{result: <value>}` — that envelope is unwrapped
+ *   for you, and what it holds counts as plain text. Any other object is
+ *   delivered to the node unchanged, so it must already match
+ *   {@link RequestInputParams.responseSchema} when one is set.
+ *
+ * Ported from `google/adk-python` `events/request_input.py`.
+ */
+export declare class RequestInput {
+    /** Brand identifying this object as a {@link RequestInput} (see {@link isRequestInput}). */
+    readonly [REQUEST_INPUT_SIGNATURE_SYMBOL] = true;
+    readonly interruptId: string;
+    readonly payload?: unknown;
+    readonly message?: string;
+    readonly responseSchema?: SchemaLike;
+    constructor(params?: RequestInputParams);
+}
+/**
+ * Type guard for {@link RequestInput}.
+ *
+ * Matches on the `REQUEST_INPUT_SIGNATURE_SYMBOL` brand rather than
+ * `instanceof` so it stays correct across package copies (see the brand's doc).
+ */
+export declare function isRequestInput(value: unknown): value is RequestInput;
+export {};

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

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * An error constructor usable in {@link RetryConfig.exceptions}.
+ */
+export type ErrorClass = new (...args: never[]) => Error;
+/**
+ * Configuration for retrying a node.
+ *
+ * Ported from `google/adk-python` `workflow/_retry_config.py`. Delays are
+ * expressed in **seconds** (fractions allowed) to match the Python semantics
+ * and keep configuration portable across runtimes. Unset fields fall back to
+ * the documented defaults inside the retry utilities.
+ */
+export interface RetryConfig {
+    /**
+     * Maximum number of attempts, including the original request. If 0 or 1, it
+     * means no retries. If not specified, defaults to 5.
+     */
+    maxAttempts?: number;
+    /**
+     * Initial delay before the first retry, in seconds. If not specified,
+     * defaults to 1.0 second.
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay between retries, in seconds. If not specified, defaults to
+     * 60.0 seconds.
+     */
+    maxDelay?: number;
+    /**
+     * Multiplier by which the delay increases after each attempt. If not
+     * specified, defaults to 2.0.
+     */
+    backoffFactor?: number;
+    /**
+     * Randomness factor for the delay. If not specified, defaults to 1.0. Use 0.0
+     * to remove randomness.
+     */
+    jitter?: number;
+    /**
+     * Exceptions to retry on. Accepts error class names as strings (e.g.
+     * `['TypeError']`) or error classes directly (e.g. `[TypeError]`).
+     * `undefined`/`null` means retry on all errors.
+     */
+    exceptions?: Array<string | ErrorClass> | null;
+}
+/**
+ * Normalizes the `exceptions` field of a {@link RetryConfig} to a list of error
+ * class name strings, mirroring Python's `field_validator`.
+ *
+ * @returns The list of class-name strings, or `undefined` to mean "retry on all
+ *   errors".
+ */
+export declare function normalizeRetryExceptions(exceptions?: Array<string | ErrorClass> | null): string[] | undefined;
+/**
+ * A {@link RetryConfig} whose `exceptions` filter has been normalized to error
+ * class-name strings once, up front.
+ *
+ * Produced by {@link prepareRetryConfig} when a node accepts its config, so the
+ * retry hot path neither re-normalizes on every failure nor throws on a
+ * malformed config from inside the retry loop.
+ */
+export interface PreparedRetryConfig {
+    readonly maxAttempts?: number;
+    readonly initialDelay?: number;
+    readonly maxDelay?: number;
+    readonly backoffFactor?: number;
+    readonly jitter?: number;
+    /** Normalized exception names; `undefined` means retry on all errors. */
+    readonly exceptions?: readonly string[];
+}
+/**
+ * Validates and normalizes a {@link RetryConfig} once, at config-acceptance
+ * time (i.e. when a node is constructed).
+ *
+ * Throws if `exceptions` contains a malformed entry, surfacing the
+ * misconfiguration at construction rather than masking a node's real error from
+ * inside the retry path.
+ */
+export declare function prepareRetryConfig(config: RetryConfig): PreparedRetryConfig;

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LlmAgent } from '../agents/llm_agent.js';
+import { Event } from '../events/event.js';
+import { NodeContext } from './node_context.js';
+/**
+ * Runs an {@link LlmAgent} as a workflow node: the node input is appended as a
+ * user turn, the agent runs, and its reply becomes the node output.
+ *
+ * `LlmAgent.runImpl` is the only caller. It is a free function rather than a
+ * wrapper node because an agent is already a `BaseNode` — putting a second node
+ * around it meant the graph held something that was not the agent the caller
+ * passed in, and the agent's own node configuration (`timeout`, `rerunOnResume`,
+ * …) was dropped on the floor. adk-python makes the same split: no wrapper
+ * class, and `LlmAgent._run_impl` delegating to `run_llm_agent_as_node` in
+ * `workflow/_llm_agent_wrapper.py`.
+ *
+ * Only `LlmAgent` needs this. Any other agent run as a node keeps
+ * `BaseAgent.runImpl`, which is plain delegation to `runAsync` — an agent whose
+ * input is its conversation has nothing to inject and no model text to promote.
+ *
+ * `single_turn` and `task` modes are ported; `chat` mode (task delegation via
+ * `FinishTaskTool`, isolation scopes) is not yet supported.
+ */
+export declare function runLlmAgentAsNode(agent: LlmAgent, ctx: NodeContext, nodeInput: unknown): AsyncGenerator<Event, void, void>;

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

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseAgent } from '../agents/base_agent.js';
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { BaseNode } from './base_node.js';
+import type { RunnableNode } from './graph.js';
+import { Workflow } from './workflow.js';
+/**
+ * What can be run as the root of an invocation: an agent, or a `Workflow` the
+ * runner drives as a node. See {@link isRunnableRoot}.
+ */
+export type RunnableRoot = BaseAgent | Workflow;
+/** Options for {@link runNodeAsInvocation}. */
+export interface RunNodeAsInvocationOptions {
+    /**
+     * Author for the event announcing the node's output, when one is needed.
+     * Defaults to the node's own name.
+     */
+    author?: string;
+}
+/**
+ * Runs a node as a whole invocation, turning it into a stream of events.
+ *
+ * This is the seam between the two execution shapes ADK has. A node is driven
+ * by pushing events into a channel while something else drains it; a caller of
+ * an invocation expects to pull events out of a generator. Bridging them means
+ * three things: give the node a root {@link NodeContext} to run in, derive its
+ * input from the user's message, and pump the channel.
+ *
+ * adk-python does the same work in `Runner._run_node_async`, over
+ * `ic._event_queue` rather than a local queue. It lives as a free function
+ * rather than a method because the runner is not its only caller: anything that
+ * has to run a node as a whole invocation goes through here.
+ */
+export declare function runNodeAsInvocation(node: BaseNode, ic: InvocationContext, options?: RunNodeAsInvocationOptions): AsyncGenerator<Event, void, void>;
+/**
+ * Whether a value is already a root, and so is worth handing to
+ * {@link asRunnableRoot}.
+ *
+ * An agent always is. A `Workflow` is because the runner drives it as a node
+ * rather than running it through `runAsync`.
+ *
+ * Used where a root is *discovered* rather than passed — the agent loader
+ * sifting a module's exports — so a workflow export is found the same way an
+ * agent export is.
+ *
+ * Deliberately narrower than what {@link asRunnableRoot} accepts: a passed root
+ * is a statement of intent, while a discovered one is a guess, and every module
+ * exports functions that are not meant to be the app.
+ */
+export declare function isRunnableRoot(value: unknown): value is RunnableRoot;
+/**
+ * Normalizes whatever was handed in as a root into a {@link RunnableRoot}.
+ *
+ * An agent and a workflow are both roots already and pass through as
+ * themselves. Anything else node-like — a tool, a plain function, an
+ * already-built node — becomes the single node of a one-node workflow, exactly
+ * what `edges: [['START', value]]` spells by hand, so `{agent: node}` and
+ * `{agent: new Workflow({edges: [['START', node]]})}` are the same request
+ * spelled two ways.
+ *
+ * The value is built before it reaches the graph parser, which would build it
+ * anyway, because the built node is what carries the name and description the
+ * wrapping workflow takes.
+ *
+ * @throws if `root` is not something an edge would accept.
+ */
+export declare function asRunnableRoot(root: RunnableNode): RunnableRoot;

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

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BaseNode } from './base_node.js';
+import type { NodeContext, NodeResult } from './node_context.js';
+import { NodeState } from './node_state.js';
+/**
+ * Options for scheduling a dynamic node via {@link ScheduleDynamicNode}.
+ */
+export interface ScheduleDynamicNodeOptions {
+    /** Deterministic tracking name; defaults to `node.name`. */
+    nodeName?: string;
+    /** Unique id for this specific execution (used for path/dedup keys). */
+    runId: string;
+    /** If true, the child's output replaces the caller's output. */
+    useAsOutput?: boolean;
+    /** If true, run the child in an isolated sub-branch. */
+    useSubBranch?: boolean;
+    /** Explicit branch override. */
+    overrideBranch?: string;
+    /** Explicit isolation-scope override. */
+    overrideIsolationScope?: string;
+}
+/**
+ * Protocol for scheduling a dynamically-invoked node (via `ctx.runNode()`).
+ *
+ * Implementations handle fresh execution, deduplication of concurrent calls,
+ * and (Phase 5) resumption from session events. Ported from
+ * `google/adk-python` `workflow/_schedule_dynamic_node.py`.
+ */
+export interface ScheduleDynamicNode {
+    schedule(ctx: NodeContext, node: BaseNode, input: unknown, options: ScheduleDynamicNodeOptions): Promise<NodeContext | NodeResult>;
+}
+/**
+ * Combines state, output, and the running task for a single dynamic node
+ * execution.
+ */
+export interface DynamicNodeRun {
+    state: NodeState;
+    output?: unknown;
+    task?: Promise<NodeContext>;
+    transferToAgent?: string;
+    /**
+     * The result of a run that completed without executing its body, kept so a
+     * repeat call for the same path hands back the same result. Runs that did
+     * execute are deduplicated by `task` instead.
+     */
+    result?: NodeResult;
+}
+/**
+ * State for tracking dynamic nodes scheduled via `ctx.runNode()`.
+ *
+ * Ported (Phase 4 subset) from `google/adk-python`
+ * `workflow/_dynamic_node_scheduler.py::DynamicNodeState`. Replay/rehydration
+ * fields are added in Phase 5.
+ */
+export declare class DynamicNodeState {
+    /** Dynamic node runs keyed by unique node path (e.g. `wf/node_a@1`). */
+    readonly runs: Map<string, DynamicNodeRun>;
+    /** Union of unresolved interrupt ids across dynamic child nodes. */
+    readonly interruptIds: Set<string>;
+    /** All in-flight dynamic node tasks. */
+    getDynamicTasks(): Array<Promise<NodeContext>>;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * A buffered trigger for a downstream node.
+ *
+ * Ported from `google/adk-python` `workflow/_trigger.py`. Unlike the previous
+ * TypeScript `Trigger` (a route-matching predicate), this is a plain data record
+ * describing *how* a target node should be invoked when its turn comes.
+ */
+export interface Trigger {
+    /** The input to pass to the triggered node. */
+    input?: unknown;
+    /** Whether this trigger should run the node in an isolated sub-branch. */
+    useSubBranch?: boolean;
+    /** The branch inherited from the predecessor node. */
+    branch?: string;
+    /** Scope tag explicitly propagated to this trigger. */
+    isolationScope?: string;
+}

package/dist/types/workflow/utils/graph_parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Edge, EdgeItem } from '../graph.js';
+/** Parses a list of edge items into a flat list of {@link Edge} objects. */
+export declare function parseEdgeItems(edgeItems: EdgeItem[]): Edge[];

package/dist/types/workflow/utils/graph_validation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Validates workflow graphs and computes terminal nodes.
+ *
+ * Ported from `google/adk-python` `workflow/utils/_graph_validation.py`.
+ * The Phase 3 static-schema check and the Phase 7 chat-agent wiring check are
+ * intentionally deferred to their respective phases.
+ */
+import { BaseNode } from '../base_node.js';
+import { Edge } from '../graph.js';
+/**
+ * Validates the workflow graph and returns the set of terminal node names.
+ */
+export declare function validateGraph(nodes: BaseNode[], edges: Edge[]): Set<string>;

package/dist/types/workflow/utils/hitl_utils.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Utilities for Human-in-the-Loop (HITL) workflows.
+ *
+ * Ported (subset) from `google/adk-python`
+ * `workflow/utils/_workflow_hitl_utils.py`.
+ */
+import { Part } from '@google/genai';
+import { AuthConfig } from '../../auth/auth_tool.js';
+import { Event } from '../../events/event.js';
+import { State } from '../../sessions/state.js';
+import { RequestInput } from '../request_input.js';
+export { REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, } from '../../agents/functions.js';
+/**
+ * Creates an interrupt {@link Event} from a {@link RequestInput}. The event
+ * carries an `adk_request_input` function call and marks the interrupt id as a
+ * long-running tool id.
+ */
+export declare function createRequestInputEvent(requestInput: RequestInput): Event;
+/**
+ * Collects the `responseSchema` each pending interrupt declared, keyed by
+ * interrupt id, as the JSON Schema recorded on its `adk_request_input` call.
+ *
+ * The original {@link RequestInput} is long gone by the time a reply arrives —
+ * a node with `rerunOnResume: false` never runs its body again — so the
+ * serialized copy on the event is the only surviving record of the contract.
+ */
+export declare function responseSchemasByInterruptId(events: Event[]): Map<string, unknown>;
+/**
+ * Checks a *structured* reply against the `responseSchema` its interrupt
+ * declared, and describes the mismatch when there is one. Returns `undefined`
+ * when the reply is acceptable.
+ *
+ * Reporting rather than throwing is what lets a caller be loud about the reply
+ * that just arrived and quiet about the same reply on every later replay: a
+ * rejected reply stays in the session forever, so a checker that threw on
+ * sight would end the session rather than the turn.
+ *
+ * Only structured replies are checked. A plain-text reply is routed to every
+ * pending interrupt as-is (the interactive CLI and the dev UI both rely on
+ * that), and holding free text to an object schema would break it.
+ *
+ * A reply that unwraps to a bare scalar counts as plain text and is exempt for
+ * the same reason: `{result: <text>}` is the envelope a client sends when it
+ * has only a chat box to offer, so checking it would reject the very answer
+ * the plain-text path accepts.
+ *
+ * What remains checked is the case this exists for: a reply in the wrong
+ * *shape*. A client that wraps its answer as `{response: x}` instead of
+ * `{result: x}` gets the whole envelope delivered as the node's input, which
+ * typically surfaces far downstream as a stringified `[object Object]`.
+ */
+export declare function interruptResponseMismatch(interruptId: string, value: unknown, jsonSchema: unknown): string | undefined;
+/** Returns whether an event contains a `request_input` function call. */
+export declare function hasRequestInputFunctionCall(event: Event): boolean;
+/** Returns whether an event contains an `adk_request_credential` function call. */
+export declare function hasAuthRequestFunctionCall(event: Event): boolean;
+/** Extracts interrupt ids from `request_input` function calls in an event. */
+export declare function getRequestInputInterruptIds(event: Event): string[];
+/**
+ * Creates a `FunctionResponse` part answering a `request_input` interrupt,
+ * suitable for appending to a session as the user's resume response.
+ */
+export declare function createRequestInputResponse(interruptId: string, response: Record<string, unknown>): Part;
+/** Whether a credential for the given auth config already exists in state. */
+export declare function hasAuthCredential(authConfig: AuthConfig, state: State): boolean;
+/**
+ * Creates an event requesting user authentication credentials
+ * (`adk_request_credential`), marking the interrupt id as a long-running tool.
+ *
+ * Ported from `google/adk-python` `create_auth_request_event`.
+ */
+export declare function createAuthRequestEvent(authConfig: AuthConfig, interruptId: string): Event;
+/** Parameters for {@link processAuthResume}. */
+export interface ProcessAuthResumeParams {
+    /** The resume response: a full {@link AuthConfig} or a plain value. */
+    responseData: unknown;
+    /** The auth config the credential is being stored for. */
+    authConfig: AuthConfig;
+    /** The session state to store the credential in. */
+    state: State;
+}
+/**
+ * Stores credentials from an auth resume response into session state. Accepts a
+ * full {@link AuthConfig} (web UI flow) or a plain value (e.g. an API key
+ * string), mirroring `google/adk-python` `process_auth_resume`.
+ */
+export declare function processAuthResume({ responseData, authConfig, state, }: ProcessAuthResumeParams): Promise<void>;

package/dist/types/workflow/utils/rehydration_utils.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { RouteValue } from '../graph.js';
+import type { NodeContext, NodeResult } from '../node_context.js';
+/** Reconstructed state for a single node, keyed by node name. */
+export interface RehydratedNode {
+    /** The node's cached output from a prior run, if it produced one. */
+    output?: unknown;
+    /** The route(s) the node emitted, if any (array = multi-route). */
+    route?: RouteValue | RouteValue[];
+    /** The branch the node ran on. */
+    branch?: string;
+    /** The input the node was invoked with (captured when it interrupted). */
+    input?: unknown;
+    /** Interrupt ids the node raised. */
+    interruptIds: Set<string>;
+    /** Resolved interrupt responses, keyed by interrupt id. */
+    resolvedResponses: Map<string, unknown>;
+}
+/**
+ * Narrows session events to the workflow run still in progress, dropping every
+ * earlier run that already finished.
+ *
+ * Rehydration exists to resume a run that paused, so it must not see a run that
+ * already completed: the finished nodes' cached outputs would be fast-forwarded
+ * into the new run, and the workflow would replay its previous answer instead
+ * of acting on the new input.
+ *
+ * `google/adk-python` scopes this by invocation id, because there a resumed
+ * invocation keeps its id. The TypeScript runner mints a fresh invocation id
+ * for every turn (`Runner.runAsync`), so a run that spans a pause covers
+ * several invocations and an id filter would discard the very outputs resume
+ * needs. Runs are delimited by pausing instead:
+ *
+ *   - An invocation that raised an interrupt ended paused, so it belongs to the
+ *     run still in progress.
+ *   - An invocation that emitted node events without raising one ran to
+ *     completion; it is the boundary, and it and everything before it are
+ *     dropped.
+ *
+ * The current invocation is always kept: it is in progress by definition, and
+ * it carries the user function responses that resolve the pending interrupts.
+ */
+export declare function eventsForCurrentRun(events: Event[], currentInvocationId: string): Event[];
+/**
+ * Scans session events and reconstructs per-node state (outputs, routes, raised
+ * interrupts, and resolved interrupt responses).
+ *
+ * When `parentPath` is given, reconstruction is scoped to that path's DIRECT
+ * children (keyed by child name), so nested workflows whose nodes share a name
+ * do not collide on resume. When omitted, nodes are keyed by their path leaf
+ * (utility mode, robust to author rewrite).
+ */
+export declare function reconstructNodeStates(events: Event[], parentPath?: string): Map<string, RehydratedNode>;
+/**
+ * Like {@link reconstructNodeStates} but keyed by the full node path
+ * (`wf.node@runId`), so distinct dynamic (`ctx.runNode`) iterations are tracked
+ * separately for per-run resume/dedup.
+ */
+export declare function reconstructNodeStatesByPath(events: Event[]): Map<string, RehydratedNode>;
+/**
+ * Every interrupt raised in `events` that now has an accepted reply, as
+ * interrupt id -> value.
+ *
+ * Flat and unscoped, unlike {@link reconstructNodeStates}: interrupt ids are
+ * unique, and a reply has to reach whoever raised it however deep that sits. A
+ * dynamic (`ctx.runNode`) child or a nested workflow's leaf is keyed out of the
+ * per-parent view, so a scoped map silently drops its answer and the run pauses
+ * on the same question forever.
+ *
+ * A reply that does not match the schema its interrupt declared resolves
+ * nothing. It throws while it is the turn being processed, so the client hears
+ * about it once, and is skipped on every replay after that (see
+ * {@link interruptResponseMismatch}).
+ */
+export declare function resolvedInterruptResponses(events: Event[]): Map<string, unknown>;
+/**
+ * Reconstructs each node's prior runs in order, rather than merging them into
+ * one record per node.
+ *
+ * A node the graph routes back to runs more than once, and a pause can fall
+ * between two of its runs — the revise loop in the request-input samples pauses
+ * on `request_human_review@1`, resumes, and pauses again on `@2`. Merged into a
+ * single record those two runs are indistinguishable, and the resumed turn
+ * replays the first run's answer forever. `google/adk-python` avoids this by
+ * keying its recovered executions on `name@run_id`; TypeScript node paths carry
+ * no run id for static graph nodes, so the runs are recovered positionally
+ * instead: the Nth activation in the resumed turn matches the Nth prior run.
+ *
+ * A run is closed once it has produced an output, a route, or an interrupt, so
+ * the next event for that node opens the next run. Events a run emits before
+ * that (messages, state deltas) accumulate into the run in progress.
+ */
+export declare function reconstructNodeRuns(events: Event[], parentPath?: string): Map<string, RehydratedNode[]>;
+/**
+ * Whether a rehydrated node can be fast-forwarded on resume: it produced a
+ * result — an output or a route — and all of its raised interrupts have been
+ * resolved.
+ */
+export declare function isFastForwardable(node: RehydratedNode): boolean;
+/**
+ * Builds the completion result for a fast-forwarded (cached) node on resume.
+ * The node's body is not re-run and its events are NOT re-emitted (they already
+ * exist in the session), so this returns a bare {@link NodeResult} rather than a
+ * live {@link NodeContext} — the honest type for "cached output, no behaviour".
+ */
+export declare function makeFastForwardResult(parent: NodeContext, prior: RehydratedNode): NodeResult;
+/** Extracts the node name (leaf, without run id) from a dotted node path. */
+export declare function nodeNameFromPath(path: string): string;
+/**
+ * Unwraps a `{result: value}` FunctionResponse envelope to the bare value.
+ *
+ * A string value is JSON-parsed when it parses, because the envelope does not
+ * say whether the text is structured: a client answering a `RequestInput` that
+ * declared a `responseSchema` sends the object as text (the web frontend wraps
+ * whatever the user submitted as `{result: text}`), and the node expects the
+ * object back. Text that is not JSON — "approve", "shorter" — is returned
+ * as-is. That is parity with Python's `_unwrap_response`.
+ *
+ * `responseSchema`, when the interrupt declared one, decides whether parsing
+ * applies at all. Parsing text the schema asked for as text is destructive
+ * rather than helpful: an answer of "42" to a `z.string()` interrupt reached
+ * the node as the number 42 and crashed it on the first string method, and
+ * every JSON literal did the same — "true", "null", "1e3". So a schema that
+ * accepts a string keeps the text verbatim, and only a schema that cannot
+ * (an object, an array, a number) still parses.
+ */
+export declare function unwrapResponse(response: unknown, responseSchema?: unknown): unknown;

package/dist/types/workflow/utils/retry_utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Utility functions for retrying nodes in a workflow.
+ *
+ * Ported from `google/adk-python` `workflow/utils/_retry_utils.py`.
+ */
+import { NodeState } from '../node_state.js';
+import { PreparedRetryConfig } from '../retry_config.js';
+/**
+ * Resolves every runtime name a thrown value can be matched by: its class name,
+ * as Python's `type(exception).__name__` gives, and any `name` assigned on top
+ * of it. A subclass that never sets `this.name` inherits `'Error'`, so the two
+ * disagree exactly when matching on one alone would miss.
+ */
+export declare function errorNames(error: unknown): string[];
+/**
+ * Resolves the most specific runtime name of a thrown value, for reporting.
+ * Mirrors Python's `type(exception).__name__`, preferring an assigned `name`
+ * only when the class name carries nothing more than `Error`.
+ */
+export declare function errorName(error: unknown): string;
+/** Parameters for {@link shouldRetryNode}. */
+export interface ShouldRetryNodeParams {
+    /** The error thrown by the node. */
+    error: unknown;
+    /** The node's prepared (normalized) retry configuration. */
+    retryConfig: PreparedRetryConfig;
+    /** The current node state (its `attemptCount` is 1-based). */
+    nodeState: NodeState;
+}
+/**
+ * Checks if a failed node should be retried based on its retry config.
+ */
+export declare function shouldRetryNode({ error, retryConfig, nodeState, }: ShouldRetryNodeParams): boolean;
+/** Parameters for {@link getRetryDelaySeconds}. */
+export interface GetRetryDelaySecondsParams {
+    /** The node's prepared (normalized) retry configuration. */
+    retryConfig: PreparedRetryConfig;
+    /**
+     * The current node state (its `attemptCount` is the 1-based attempt number
+     * that just failed).
+     */
+    nodeState: NodeState;
+    /** Injectable uniform RNG in [0, 1) for deterministic testing. */
+    randomFn?: () => number;
+}
+/**
+ * Calculates the delay, in seconds, before retrying a node.
+ */
+export declare function getRetryDelaySeconds({ retryConfig, nodeState, randomFn, }: GetRetryDelaySecondsParams): number;