@google/adk 1.6.0 → 2.1.0

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

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { InvocationContext } from '../agents/invocation_context.js';
+import { Event } from '../events/event.js';
+import { EventActions } from '../events/event_actions.js';
+import { State } from '../sessions/state.js';
+import { AsyncQueue } from '../utils/async_queue.js';
+import type { SchemaLike } from '../utils/schema.js';
+import type { RouteValue, RunnableNode } from './graph.js';
+import { RunNodeOptions } from './node_runner.js';
+import type { ScheduleDynamicNode } from './schedule_dynamic_node.js';
+/**
+ * The result of running a node: the fields a caller (and the engine's
+ * completion handling) reads off a finished run — its `output`, emitted
+ * `route`, the `branch` it ran on, and any raised interrupt ids.
+ *
+ * A node that actually executes returns its full {@link NodeContext} (which
+ * satisfies this shape). A node that is *fast-forwarded* on resume (its output
+ * was cached in a prior turn, so its body is not re-run) returns a bare
+ * `NodeResult` with no live context behaviour — so callers of `ctx.runNode()`
+ * should treat the result as a `NodeResult` and read only these fields.
+ */
+export interface NodeResult {
+    /** The structured output the node produced (if any). */
+    output: unknown;
+    /** The route key(s) the node emitted, if any (array = multi-route). */
+    route?: RouteValue | RouteValue[];
+    /** The branch the node ran on. */
+    branch?: string;
+    /** Interrupt ids the node is blocked on (empty when it completed). */
+    interruptIds: string[];
+}
+/**
+ * Options for constructing a {@link NodeContext}.
+ */
+export interface NodeContextOptions {
+    invocationContext: InvocationContext;
+    channel: AsyncQueue<Event>;
+    /** Dotted node path of the owning node (empty string for the root). */
+    nodePath: string;
+    /** Deterministic run id of the owning node. */
+    runId: string;
+    /** Responses for resuming interrupted child nodes, keyed by interrupt id. */
+    resumeInputs?: Record<string, unknown>;
+    /** Scope tag isolating this node's events from peer scopes. */
+    isolationScope?: string;
+    /** Accumulator for event actions (state delta, etc). */
+    actions?: EventActions;
+    /**
+     * Declares the keys this node may write to `ctx.state` and their types.
+     * Resolved by the runner: the node's own schema, or the parent's.
+     */
+    stateSchema?: SchemaLike;
+}
+/**
+ * The execution context for a workflow node — the TypeScript analogue of
+ * `google/adk-python` `agents/context.py::Context` (the workflow flavour).
+ *
+ * It exposes `ctx.runNode(...)` for programmatic child execution, `ctx.state`
+ * for delta-aware session state, `ctx.emit(...)` to stream an event, and the
+ * mutable `output`/`route`/`interruptIds` a node sets while running.
+ */
+export declare class NodeContext {
+    readonly invocationContext: InvocationContext;
+    readonly channel: AsyncQueue<Event>;
+    readonly nodePath: string;
+    readonly runId: string;
+    /**
+     * Node paths whose output this node's output also becomes: its parent's if
+     * the parent ran it with `useAsOutput`, plus whatever the parent was standing
+     * in for. Stamped onto every output event as `nodeInfo.outputFor`, so a
+     * resumed run can tell that an ancestor already has a result.
+     */
+    outputForAncestors: readonly string[];
+    /**
+     * Whether this node handed its output to a child run with `useAsOutput`.
+     *
+     * The child already emitted that value as its own result, so an event from
+     * this node repeating it would put the same text in the stream twice. The
+     * node still reports the output — only the duplicate event is suppressed.
+     */
+    outputDelegated: boolean;
+    readonly actions: EventActions;
+    resumeInputs: Record<string, unknown>;
+    isolationScope?: string;
+    /** The structured output produced by the node during its run. */
+    output: unknown;
+    /** The route key(s) emitted by the node, if any (array = multi-route). */
+    route?: RouteValue | RouteValue[];
+    /** Interrupt ids the node is currently blocked on (HITL). */
+    interruptIds: string[];
+    /**
+     * The failure a node reported by emitting an error event rather than by
+     * throwing. Read back at the end of the attempt; cleared per attempt.
+     */
+    reportedError?: {
+        errorCode?: string;
+        errorMessage?: string;
+    };
+    /**
+     * Abort signal for the current node run, set by the engine while the node is
+     * executing under a deadline or an external cancellation signal — i.e. when
+     * the node declares a `timeout`, when the invocation itself can be aborted, or
+     * when it runs inside a Workflow (whose signal fires if a sibling fails).
+     * Cooperative node bodies can observe `ctx.abortSignal` to wind down their own
+     * in-flight work (e.g. pass it to a model/tool call); the engine also stops
+     * consuming the node's events once it fires, so nothing is pushed past
+     * cancellation. A fired `timeout` surfaces as a `NodeTimeoutError`; an external
+     * abort stops the node without raising.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * The dynamic-node scheduler for this subtree. When set, `ctx.runNode()`
+     * routes through it (dedup/resume/fresh); otherwise it runs the child
+     * directly. Propagated to child contexts by the node runner; a nested
+     * Workflow overrides it with its own scheduler.
+     */
+    scheduler?: ScheduleDynamicNode;
+    /** The current attempt number (1-based) for the running node (see retry). */
+    attemptCount: number;
+    /**
+     * The state schema in force for this node, inherited by its children unless
+     * they declare their own.
+     */
+    readonly stateSchema?: SchemaLike;
+    private readonly _state;
+    private readonly dynamicRunCounters;
+    /** Run ids this context handed out automatically, per node name. */
+    private readonly autoRunIds;
+    /**
+     * Caller-supplied run ids shaped like an automatic one (all digits), per node
+     * name — the set {@link assertNoNumericCustomRunIds} refuses to auto-number
+     * around.
+     */
+    private readonly numericCustomRunIds;
+    constructor(opts: NodeContextOptions);
+    /** Delta-aware session state; writes accumulate in `actions.stateDelta`. */
+    get state(): State;
+    /** The branch of the owning invocation context. */
+    get branch(): string | undefined;
+    /** The current invocation id. */
+    get invocationId(): string;
+    /** The current session. */
+    get session(): import("../common.js").Session;
+    /**
+     * The invocation context to run a nested agent against.
+     *
+     * The single place where "what a node sees" is translated into "what an
+     * agent sees", so an agent run as a node (`BaseAgent.runImpl`) and one run
+     * directly go through the same seam.
+     *
+     * It hands back the node's own invocation context unchanged, and that is the
+     * intended behaviour rather than a placeholder.
+     *
+     * adk-python's counterpart (`agents/context.py` `get_invocation_context`) is
+     * documented as returning "a copy with the proxy session", which reads as
+     * though the agent is handed a different view of state. It is not: that
+     * `Context.session` returns `self._invocation_context.session`, so the copy
+     * substitutes the same object, and `Context._state` is built directly over
+     * `session.state`. A Python agent run as a node reads session state exactly
+     * as a TypeScript one does.
+     *
+     * The other thing that copy carries — the isolation scope — is already
+     * applied by the time this runs: the node runner builds the child invocation
+     * context with the node's scope, so it is present on the object returned.
+     *
+     * That leaves the node's own `state`, which is this node's pending delta over
+     * `session.state` — the same thing an agent reads, so the two cannot
+     * disagree. The agent-node cases in
+     * `core/test/workflow/state_consistency_test.ts` pin that.
+     */
+    getInvocationContext(): InvocationContext;
+    /** Streams a single event out through the workflow's event channel. */
+    emit(event: Event): void;
+    /**
+     * Runs a child node programmatically, streaming its events through the same
+     * channel and resolving to the child's result — a full {@link NodeContext}
+     * for a node that actually ran, or a bare {@link NodeResult} for one that was
+     * fast-forwarded from cached output on resume. Either way the caller can read
+     * `output`, `route`, `branch`, and `interruptIds`; only a `NodeContext`
+     * offers live behaviour (`emit`, `state`, nested `runNode`).
+     *
+     * When a dynamic-node {@link scheduler} is set (inside a Workflow subtree),
+     * the call routes through it for dedup/resume; otherwise the child runs
+     * directly.
+     *
+     * Takes anything an edge takes — an agent, a tool, a plain function, or an
+     * already-built node — and wraps it the same way the graph does, so
+     * `ctx.runNode(myAgent, input)` works without `node(myAgent)`. Wrap it
+     * yourself when you need the options `node()` carries, such as a schema or a
+     * name that differs from the value's own.
+     */
+    runNode(nodeLike: RunnableNode, input?: unknown, options?: RunNodeOptions): Promise<NodeContext | NodeResult>;
+    /**
+     * Runs a child through the scheduler, raising {@link NodeInterruptedError}
+     * when it comes back waiting on an unanswered interrupt.
+     *
+     * The caller's body must not continue past a child that stopped to ask the
+     * user: everything after the call would run on a missing answer, and would
+     * run again when the turn resumes. The scheduler has already copied the
+     * child's interrupt ids onto this context by the time it returns, so the
+     * runner that catches the throw records this node as waiting.
+     */
+    private scheduleAndUnwind;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CreateEventParams, Event } from '../events/event.js';
+export interface NodeErrorEvent extends Event {
+    readonly isNodeError: true;
+    errorType: string;
+    attemptCount: number;
+}
+export interface CreateNodeErrorEventParams extends CreateEventParams {
+    error: unknown;
+    attemptCount?: number;
+}
+export declare function isNodeErrorEvent(event: Event): event is NodeErrorEvent;
+export declare function claimNodeErrorReport(error: unknown, invocationId: string): boolean;
+export declare function createNodeErrorEvent(params: CreateNodeErrorEventParams): NodeErrorEvent;

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>;
+}