@google/adk 1.6.0 → 2.0.0

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

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseNode } from './base_node.js';
+import { NodeContext } from './node_context.js';
+import { NodeState } from './node_state.js';
+/**
+ * Options controlling a single `ctx.runNode(...)` execution.
+ */
+export interface RunNodeOptions {
+    /** Deterministic tracking name; defaults to `node.name`. */
+    nodeName?: string;
+    /**
+     * Unique id for this specific run. Defaults to a per-node sequence — "1",
+     * "2", "3" in call order — which is what a resume matches checkpoints on.
+     *
+     * Supply one only when position is not stable but identity is (a reorderable
+     * collection: key it off the item's own id). Give it a non-numeric character
+     * so it cannot collide with the automatic sequence: an all-digit id is
+     * refused for any node ADK also numbers automatically in the same context,
+     * whichever call comes first.
+     */
+    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, overriding the default/sub-branch computation. */
+    overrideBranch?: string;
+    /** Explicit isolation scope, overriding inheritance from the parent. */
+    overrideIsolationScope?: string;
+    /**
+     * Explicit node path for the child (used by the dynamic scheduler to embed
+     * the run id, e.g. `wf.node@1`, so distinct runs are distinguishable on
+     * resume). Defaults to `${parent.nodePath}.${nodeName}`.
+     */
+    overrideNodePath?: string;
+}
+/** Parameters for {@link executeChildNode}. */
+export interface ExecuteChildNodeParams {
+    /** The context requesting the child run. */
+    parent: NodeContext;
+    /** The node to execute. */
+    node: BaseNode;
+    /** The input passed to the node. */
+    input: unknown;
+    /** Options controlling this run. */
+    options?: RunNodeOptions;
+    /**
+     * Engine-supplied cancellation signal that overrides the parent invocation's
+     * for this child (used by a Workflow to cancel in-flight siblings when a node
+     * fails). Defaults to the parent invocation's abort signal.
+     */
+    abortSignal?: AbortSignal;
+    nodeState?: NodeState;
+    /**
+     * Resume responses this run may consume, overriding the parent's. The
+     * workflow loop passes an empty map for a run that is not the one recovered
+     * from the previous turn, so a node re-triggered later in a resumed turn
+     * starts clean instead of re-reading a response it already answered.
+     */
+    resumeInputs?: Record<string, unknown>;
+}
+/**
+ * Executes a child node on behalf of `parent.runNode(...)`.
+ *
+ * Responsibilities (Phase 1 scope): create the child {@link NodeContext},
+ * drive `node.run()`, enrich each emitted event (author, node path, branch,
+ * isolation scope), track the child's `output`/`route`, apply the per-node
+ * `timeout`, and retry on failure per `retryConfig`. Returns the child context.
+ *
+ * Retry semantics: each attempt starts with the child's per-attempt state
+ * cleared (output, route, interrupt ids, and `actions.stateDelta`). Events are
+ * the exception — they stream out through the shared channel as they are
+ * produced and cannot be retracted, so a node that emits some events and then
+ * fails will re-emit them when the attempt is retried. Nodes that must not
+ * duplicate observable events across retries should emit only after their
+ * fallible work has succeeded.
+ */
+export declare function executeChildNode(params: ExecuteChildNodeParams): Promise<NodeContext>;

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

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { NodeStatus } from './node_status.js';
+/**
+ * State of a node in the workflow.
+ *
+ * Ported from `google/adk-python` `workflow/_node_state.py`. Note that the
+ * node's *output* is intentionally NOT stored here — it is carried on emitted
+ * events / the node Context, not on the persisted node state.
+ */
+export interface NodeState {
+    /** The run status of the node. */
+    status: NodeStatus;
+    /** The input provided to the node. */
+    input?: unknown;
+    /** The attempt count for this node run (1-based). */
+    attemptCount: number;
+    /** The interrupt ids that are pending to be resolved. */
+    interrupts: string[];
+    /** The responses for resuming the node, keyed by interrupt id. */
+    resumeInputs: Record<string, unknown>;
+    /**
+     * Sequential counter incremented each time the node gets a fresh run.
+     *
+     * Preserving this count independently of `runId` prevents path collisions if
+     * a node switches between custom string IDs and auto-generated numeric IDs.
+     */
+    runCounter: number;
+    /** The run ID of this node run. */
+    runId?: string;
+    /**
+     * The run ID of the parent node which dynamically scheduled this node run.
+     */
+    parentRunId?: string;
+}
+/**
+ * Creates a {@link NodeState} with Python-aligned defaults, overlaying any
+ * provided partial values.
+ */
+export declare function createNodeState(partial?: Partial<NodeState>): NodeState;
+/**
+ * Type guard for a {@link NodeState}-shaped object.
+ */
+export declare function isNodeState(obj: unknown): obj is NodeState;

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The status of a node in the workflow graph.
+ *
+ * Numeric values are aligned with `google/adk-python`
+ * `workflow/_node_status.py` so that persisted node state is portable across
+ * the Python and TypeScript runtimes.
+ */
+export declare enum NodeStatus {
+    /** The node is not ready to be executed. */
+    INACTIVE = 0,
+    /** The node is ready to be executed. */
+    PENDING = 1,
+    /** The node is being executed. */
+    RUNNING = 2,
+    /** The node has been executed successfully. */
+    COMPLETED = 3,
+    /** The node is waiting (e.g. for a user response or re-trigger). */
+    WAITING = 4,
+    /** The node has failed. */
+    FAILED = 5,
+    /** The node has been cancelled. */
+    CANCELLED = 6
+}

package/dist/types/workflow/nodes/function_node.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AuthConfig } from '../../auth/auth_tool.js';
+import { Event } from '../../events/event.js';
+import { BaseNode, BaseNodeConfig } from '../base_node.js';
+import { NodeContext } from '../node_context.js';
+/**
+ * A value a {@link FunctionNodeHandler} may return or yield.
+ */
+export type FunctionNodeResult<TOutput> = TOutput | Event | null | undefined | void;
+/**
+ * The handler wrapped by a {@link FunctionNode}.
+ *
+ * Unlike Python's `FunctionNode` (which binds named parameters from `ctx.state`
+ * or `node_input` via runtime signature introspection), the TypeScript form
+ * uses the idiomatic explicit `(ctx, input)` signature. Read `ctx.state`
+ * directly for state-bound values. It may return a value/`Event`, a Promise, or
+ * a (sync/async) generator of those.
+ */
+export type FunctionNodeHandler<TInput = unknown, TOutput = unknown> = (ctx: NodeContext, input: TInput) => FunctionNodeResult<TOutput> | Promise<FunctionNodeResult<TOutput>> | Generator<FunctionNodeResult<TOutput>, void, unknown> | AsyncGenerator<FunctionNodeResult<TOutput>, void, unknown>;
+/**
+ * Options for a {@link FunctionNode}.
+ */
+export interface FunctionNodeConfig extends Partial<Omit<BaseNodeConfig, 'name'>> {
+    /**
+     * If set, the framework requests user authentication before running (Phase 5
+     * enables the auth gate; stored here now for API parity).
+     */
+    authConfig?: AuthConfig;
+}
+/**
+ * A node that wraps a plain function, async function, or (sync/async) generator.
+ *
+ * Ported (TS-idiomatic subset) from `google/adk-python` `_function_node.py`.
+ * Return-value handling:
+ *  - `Event` → emitted as-is (output validated against `outputSchema`)
+ *  - genai `Content` → emitted as the event content
+ *  - `null`/`undefined` → skipped (unless there are pending state deltas)
+ *  - anything else → emitted as `Event(output=value)`
+ * State written via `ctx.state` during execution is attached to emitted events.
+ */
+export declare class FunctionNode<TInput = unknown, TOutput = unknown> extends BaseNode<TInput, TOutput> {
+    readonly authConfig?: AuthConfig;
+    private readonly handler;
+    /** Per-run shadow of the state entries already attached to an emitted event. */
+    private readonly attachedStateByCtx;
+    constructor(name: string, handler: FunctionNodeHandler<TInput, TOutput>, config?: FunctionNodeConfig);
+    protected runImpl(ctx: NodeContext, input: TInput): AsyncGenerator<Event | TOutput | unknown, void, void>;
+    /**
+     * Ensures a credential for `authConfig` is available. Returns an
+     * `adk_request_credential` interrupt event if the credential must be
+     * requested from the user, or `undefined` if the node may proceed.
+     *
+     * On resume, a credential provided via `ctx.resumeInputs[credentialKey]` is
+     * stored into state before re-checking.
+     */
+    private runAuthGate;
+    /**
+     * Returns the state-delta entries written since the last event was emitted
+     * for this run (new keys or changed values). A multi-event handler would
+     * otherwise re-emit the whole growing delta on every event.
+     *
+     * `ctx.actions.stateDelta` can't be drained — `NodeContext` builds its
+     * `State` over it — so we track what has already been attached in a shadow
+     * map keyed by the run's context (GC'd with the context).
+     */
+    private pendingStateDelta;
+    /**
+     * Writes an emitted event's state delta into the node's own state view, and
+     * records it as already attached so {@link pendingStateDelta} does not emit a
+     * second event carrying the same keys.
+     */
+    private applyEmittedState;
+    protected toEvent(ctx: NodeContext, data: unknown): Event | null;
+}

package/dist/types/workflow/nodes/join_node.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { BaseNode } from '../base_node.js';
+import { NodeContext } from '../node_context.js';
+/**
+ * A fan-in barrier node: via {@link requiresAllPredecessors} the engine holds it
+ * until ALL of its predecessors complete, then runs it with their aggregated
+ * outputs as input.
+ *
+ * This node emits that input unchanged — the engine supplies the
+ * predecessor-name → output map; the join just passes it through as its output.
+ * The barrier itself is enforced by the orchestrator (which reads
+ * `requiresAllPredecessors`) and lands in a later part.
+ *
+ * Ported from `google/adk-python` `workflow/_join_node.py`.
+ */
+export declare class JoinNode extends BaseNode {
+    get requiresAllPredecessors(): boolean;
+    protected runImpl(ctx: NodeContext, input: unknown): AsyncGenerator<Event, void, void>;
+}

package/dist/types/workflow/nodes/node_tool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunAsyncToolRequest } from '../../tools/base_tool.js';
+import { BaseNode } from '../base_node.js';
+/**
+ * A unique symbol branding {@link NodeTool} instances (see `isNodeTool`).
+ */
+declare const NODE_TOOL_SIGNATURE_SYMBOL: unique symbol;
+/**
+ * A tool that executes a {@link BaseNode} (e.g. a `Workflow` or a function node)
+ * on behalf of an `LlmAgent`. This is the inverse of {@link ToolNode} (which
+ * exposes a tool as a workflow node): here a node/workflow is exposed to a model
+ * as a callable tool.
+ *
+ * The wrapped node MUST declare an `inputSchema` (the tool's parameter schema is
+ * derived from it). When the model calls the tool, the node runs with a
+ * {@link NodeContext} bridged from the tool's agent context (sharing the
+ * invocation, session, and state); the node's structured output becomes the
+ * tool result.
+ *
+ * Ported from `google/adk-python` `tools/_node_tool.py::NodeTool`.
+ *
+ * The tool is marked long-running so a node that pauses for input
+ * (`RequestInput`) does not force a synthetic empty response.
+ */
+export declare class NodeTool extends BaseTool {
+    /** Brand identifying this object as a {@link NodeTool} (see `isNodeTool`). */
+    readonly [NODE_TOOL_SIGNATURE_SYMBOL] = true;
+    readonly node: BaseNode;
+    constructor(node: BaseNode, name?: string, description?: string);
+    _getDeclaration(): FunctionDeclaration;
+    /** Whether the node's input schema is a (Zod) object rather than a scalar. */
+    private get inputIsObject();
+    runAsync({ args, toolContext, }: RunAsyncToolRequest): Promise<unknown>;
+    /**
+     * Runs the wrapped node with a {@link NodeContext} bridged from the agent's
+     * tool context. Node events are streamed into the invocation's event queue so
+     * intermediate/interrupt events surface to the agent (and a paused node can be
+     * resumed). Requires being invoked from an `LlmAgent` tool-call step, which is
+     * what provides that queue and the function-call id.
+     */
+    private runNode;
+}
+/**
+ * Type guard for {@link NodeTool}. Matches on the brand rather than `instanceof`
+ * so it stays correct across package copies (mirrors `isBaseTool`).
+ */
+export declare function isNodeTool(value: unknown): value is NodeTool;
+export {};

package/dist/types/workflow/nodes/parallel_worker.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { BaseNode } from '../base_node.js';
+import { RunnableNode } from '../graph.js';
+import { NodeContext } from '../node_context.js';
+/** Options for a {@link ParallelWorker}. */
+export interface ParallelWorkerConfig {
+    /**
+     * Maximum number of items processed concurrently. Defaults to
+     * `DEFAULT_MAX_PARALLEL_WORKERS` (8); pass `Infinity` for unbounded.
+     */
+    maxParallelWorkers?: number;
+}
+/**
+ * A node that runs a wrapped node once per item of a list input, preserving
+ * order, bounded by `maxParallelWorkers`, and stopping on the first error.
+ *
+ * Ported from `google/adk-python` `workflow/_parallel_worker.py`. A non-list
+ * input is treated as a single-element list. Each item runs via
+ * `ctx.runNode(inner, item, {useSubBranch: true})`; the node's output is the
+ * ordered list of the children's outputs.
+ *
+ * The wrapped value is anything an edge accepts — an agent, a tool, a plain
+ * function, or an already-built node — and is built the same way, so
+ * `new ParallelWorker(myAgent)` works without `node(myAgent)`. It is built when
+ * the worker is constructed, not per item, so every item runs the one inner
+ * node — which is also where the worker's own name comes from.
+ *
+ * Notes:
+ * - **retry/timeout live on the inner node.** `retryConfig`/`timeout` passed to
+ *   `buildNode` apply to the wrapped node (per item); the ParallelWorker itself
+ *   carries neither, so the two levels don't compose. Wrapping the value
+ *   yourself — `new ParallelWorker(node(myAgent, {timeout: 5}))` — is how those
+ *   options are set.
+ * - **All-or-nothing.** If any item throws, the first error is rethrown and the
+ *   already-computed sibling outputs are discarded. Make individual items
+ *   failure-tolerant if partial results matter.
+ * - **An item that interrupts pauses the whole worker.** It has no output to
+ *   contribute, so the worker stops claiming items, emits no list, and raises
+ *   the child's interrupt ids as its own. Once they are answered the worker
+ *   re-runs from the top (`rerunOnResume`), and items that already completed
+ *   are fast-forwarded by their run id rather than executed again.
+ * - **Cancellation stops scheduling only.** On abort/timeout the loop stops
+ *   claiming new items, but items already in flight run to completion —
+ *   `ctx.runNode` has no way to forward a signal into a child run.
+ */
+export declare class ParallelWorker extends BaseNode {
+    readonly maxParallelWorkers?: number;
+    private readonly inner;
+    constructor(inner: RunnableNode, config?: ParallelWorkerConfig);
+    protected runImpl(ctx: NodeContext, input: unknown): AsyncGenerator<unknown, void, void>;
+}

package/dist/types/workflow/nodes/tool_node.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../../events/event.js';
+import { BaseTool } from '../../tools/base_tool.js';
+import { BaseNode, BaseNodeConfig } from '../base_node.js';
+import { NodeContext } from '../node_context.js';
+/** Options for a {@link ToolNode}. */
+export interface ToolNodeConfig extends Partial<Omit<BaseNodeConfig, 'name'>> {
+    /** Optional name override; defaults to the tool's name. */
+    name?: string;
+}
+/**
+ * A node that wraps an ADK {@link BaseTool} and invokes it with the node input
+ * as its arguments.
+ *
+ * Ported from `google/adk-python` `workflow/_tool_node.py`. The node input is
+ * coerced to a tool-args object: genai `Content` → its text; a JSON string →
+ * parsed object; `null`/empty → `{}`.
+ *
+ * The tool runs through the canonical execution path
+ * ({@link handleFunctionCallList}), so the plugin `before`/`after`/`onError`
+ * tool callbacks, the confirmation gate, telemetry, and everything the tool
+ * writes to its context (`stateDelta`, `artifactDelta`, requested credentials /
+ * confirmations, …) all apply — exactly as when the same tool is called from an
+ * LLM agent. The emitted event carries a canonical `functionResponse` part.
+ */
+export declare class ToolNode extends BaseNode {
+    readonly tool: BaseTool;
+    constructor(tool: BaseTool, config?: ToolNodeConfig);
+    protected runImpl(ctx: NodeContext, input: unknown): AsyncGenerator<Event, void, void>;
+}

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;