@google/adk 1.6.0 → 2.0.0

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

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Errors raised by the workflow framework.
+ *
+ * Ported from `google/adk-python` `workflow/_errors.py`.
+ */
+/**
+ * Internal: raised when a dynamic node interrupts (HITL).
+ *
+ * Used exclusively by `ctx.runNode()` to signal that the dynamic child has
+ * unresolved interrupt IDs. The parent's NodeRunner catches this and reads the
+ * interrupt IDs from the parent's ctx (set by `ctx.runNode()` before throwing).
+ *
+ * Internal to the framework — not part of the public API.
+ */
+export declare class NodeInterruptedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Type guard for {@link NodeInterruptedError}.
+ *
+ * Matches on `name` rather than `instanceof <subclass>` so it stays correct when
+ * errors cross a package boundary (two copies of adk-js in one runtime would
+ * fail an `instanceof` check between them).
+ */
+export declare function isNodeInterruptedError(e: unknown): e is NodeInterruptedError;
+/**
+ * Raised when a node exceeds its configured timeout.
+ *
+ * This is a regular `Error` (retryable) so a timed-out node can be retried via
+ * `retryConfig`.
+ */
+export declare class NodeTimeoutError extends Error {
+    readonly nodeName: string;
+    readonly timeout: number;
+    /**
+     * @param options.nodeName The name of the node that timed out.
+     * @param options.timeout The timeout, in seconds, that was exceeded.
+     */
+    constructor(options: {
+        nodeName: string;
+        timeout: number;
+    });
+}
+/** Type guard for {@link NodeTimeoutError} (name-based; see above). */
+export declare function isNodeTimeoutError(e: unknown): e is NodeTimeoutError;
+/**
+ * Raised when a dynamic node fails.
+ *
+ * Caught by the parent node's NodeRunner to propagate the error.
+ * Internal to the framework — not part of the public API.
+ */
+export declare class DynamicNodeFailError extends Error {
+    readonly error: Error;
+    readonly errorNodePath: string;
+    /**
+     * @param options.message Human-readable failure message.
+     * @param options.error The underlying error thrown by the dynamic node.
+     * @param options.errorNodePath The node path where the failure occurred.
+     */
+    constructor(options: {
+        message: string;
+        error: Error;
+        errorNodePath: string;
+    });
+}
+/** Type guard for {@link DynamicNodeFailError} (name-based; see above). */
+export declare function isDynamicNodeFailError(e: unknown): e is DynamicNodeFailError;
+/**
+ * Raised when a node reported a failure by emitting an error event instead of
+ * throwing, and produced nothing.
+ *
+ * A regular `Error`, so `retryConfig` can retry it via
+ * `exceptions: ['NodeReportedError']`; `code` carries the reported error code.
+ */
+export declare class NodeReportedError extends Error {
+    readonly code: string;
+    readonly nodeName: string;
+    /**
+     * @param options.nodeName The node that reported the error.
+     * @param options.errorCode The code carried on the reported event.
+     * @param options.errorMessage The message carried on the reported event.
+     */
+    constructor(options: {
+        nodeName: string;
+        errorCode?: string;
+        errorMessage?: string;
+    });
+}
+/** Type guard for {@link NodeReportedError} (name-based; see above). */
+export declare function isNodeReportedError(e: unknown): e is NodeReportedError;
+/**
+ * Raised when the invocation is aborted (e.g. its abort signal fires) while the
+ * engine is waiting — currently during a node's retry backoff delay.
+ *
+ * Distinct from a node's own failure so a caller can tell "the invocation was
+ * cancelled" apart from "the node threw".
+ */
+export declare class InvocationAbortedError extends Error {
+    constructor(message?: string);
+}
+/** Type guard for {@link InvocationAbortedError} (name-based; see above). */
+export declare function isInvocationAbortedError(e: unknown): e is InvocationAbortedError;
+/**
+ * Raised when a node's input or output fails its declared schema.
+ *
+ * The underlying validation error (a `ZodError`, typically) carries the field
+ * path but not the node it came from, which leaves a failure in a large graph
+ * effectively unattributed. This wrapper names the node and which side of it
+ * failed, and keeps the original error on `cause` for the full detail.
+ */
+export declare class NodeSchemaValidationError extends Error {
+    readonly nodeName: string;
+    /** Which side of the node failed: its `inputSchema` or its `outputSchema`. */
+    readonly direction: 'input' | 'output';
+    /**
+     * @param options.nodeName The name of the node that failed validation.
+     * @param options.direction Whether the input or the output failed.
+     * @param options.cause The underlying validation error.
+     */
+    constructor(options: {
+        nodeName: string;
+        direction: 'input' | 'output';
+        cause: unknown;
+    });
+}
+/** Type guard for {@link NodeSchemaValidationError} (name-based; see above). */
+export declare function isNodeSchemaValidationError(e: unknown): e is NodeSchemaValidationError;

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

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BaseAgent } from '../agents/base_agent.js';
+import { BaseTool } from '../tools/base_tool.js';
+import { BaseNode } from './base_node.js';
+/**
+ * A unique symbol branding {@link Edge} instances.
+ *
+ * `isEdge` matches on this brand rather than `instanceof` so an edge built
+ * by another copy of adk-js in the same runtime is still recognised (an
+ * `instanceof` check fails across package copies) — mirroring the
+ * `Symbol.for('google.adk.*')` brands used across ADK.
+ */
+declare const EDGE_SIGNATURE_SYMBOL: unique symbol;
+/** Valid routing values used in conditional graph edges. */
+export type RouteValue = boolean | number | string;
+/** The fallback route key used when no specific route matches. */
+export declare const DEFAULT_ROUTE = "__DEFAULT__";
+/**
+ * Any value that can be converted to a workflow node: a node, a tool, a plain
+ * function, or the `'START'` sentinel literal. (Agent wrapping is added in
+ * Phase 3 via `build_node`.)
+ */
+export type NodeLike = BaseNode | BaseAgent | BaseTool | ((...args: never[]) => unknown) | 'START';
+/**
+ * What `ctx.runNode()` accepts: everything an edge accepts except the `'START'`
+ * sentinel, which marks a graph entry point rather than something runnable.
+ */
+export type RunnableNode = Exclude<NodeLike, 'START'>;
+/**
+ * A mapping from route values to destination node(s). A value may be a single
+ * node or an array of nodes (fan-out).
+ *
+ * @example
+ *   {question: answerNode, statement: commentNode}
+ *   {retry: [nodeA, nodeB]}   // fan-out: both triggered
+ *
+ * @remarks
+ * JavaScript object keys are always strings, so a numeric key (`{2: node}`) and
+ * a boolean key (`{true: node}`) are reconstructed to their typed
+ * {@link RouteValue} (`2`, `true`) when parsed — mirroring Python dict keys.
+ * Because of this, routes are matched **by string value**
+ * ({@link Graph.getNextPendingNodes} compares `String(route)` on both sides), so
+ * a node emitting `2` and one emitting `'2'` both fire a `{2: node}` edge. The
+ * flip side is that a numeric/boolean-looking route and its string spelling
+ * cannot be distinguished in a routing map; use distinct, non-ambiguous route
+ * keys when that matters.
+ */
+export type RoutingMap = Record<string | number, NodeLike | readonly NodeLike[]>;
+/** An element within a workflow chain. */
+export type ChainElement = NodeLike | readonly NodeLike[] | RoutingMap;
+/**
+ * An item that can be parsed into workflow edges: an explicit {@link Edge}, or a
+ * chain expressed as an array of {@link ChainElement}s (e.g.
+ * `['START', nodeA, nodeB]`).
+ */
+export type EdgeItem = Edge | ChainElement[];
+/**
+ * A directed edge in the workflow graph.
+ *
+ * Mirrors `google/adk-python` `workflow/_graph.py::Edge`.
+ */
+export declare class Edge {
+    readonly fromNode: BaseNode;
+    readonly toNode: BaseNode;
+    /**
+     * The route(s) this edge is associated with. `null` means unconditional
+     * (always triggered). A single value or a list; the edge fires when the
+     * emitted route matches any listed value.
+     */
+    readonly route: RouteValue | RouteValue[] | null;
+    /** Brand identifying this object as an {@link Edge} (see `isEdge`). */
+    readonly [EDGE_SIGNATURE_SYMBOL] = true;
+    constructor(fromNode: BaseNode, toNode: BaseNode, 
+    /**
+     * The route(s) this edge is associated with. `null` means unconditional
+     * (always triggered). A single value or a list; the edge fires when the
+     * emitted route matches any listed value.
+     */
+    route?: RouteValue | RouteValue[] | null);
+}
+/**
+ * Type guard for {@link Edge}.
+ *
+ * Matches on the {@link EDGE_SIGNATURE_SYMBOL} brand rather than `instanceof` so
+ * it stays correct across package copies (see the brand's doc).
+ */
+export declare function isEdge(value: unknown): value is Edge;
+/**
+ * A compiled workflow graph. Nodes are inferred (deduped by identity) from the
+ * edges.
+ *
+ * Mirrors `google/adk-python` `workflow/_graph.py::Graph`.
+ */
+export declare class Graph {
+    readonly nodes: BaseNode[];
+    readonly edges: Edge[];
+    private _terminalNodeNames;
+    constructor(edges: Edge[]);
+    /** Terminal node names (no outgoing edges); populated by {@link validate}. */
+    get terminalNodeNames(): ReadonlySet<string>;
+    /**
+     * Determines the next nodes to transition to PENDING based on the route(s)
+     * emitted by a completed node. Ported from Python `get_next_pending_nodes`.
+     *
+     * Logs at debug when the node emitted a route, has conditional outgoing
+     * edges, and none of them (nor a `DEFAULT_ROUTE` edge) matched — the branch
+     * stops there, which is easy to mistake for a bug. Behaviour is unchanged.
+     */
+    getNextPendingNodes(nodeName: string, routesToMatch: RouteValue | RouteValue[] | null | undefined): string[];
+    /** Validates the graph and computes terminal node names. */
+    validate(): void;
+}
+/**
+ * Builds, validates, and returns a {@link Graph} from a list of edge items.
+ *
+ * Validation runs here (not opt-in) so structural problems a graph can only
+ * have at build time — unreachable nodes, duplicate names/edges, routed edges
+ * from START, unconditional cycles — fail loudly at construction rather than
+ * surfacing as silent mis-routing at run time. It also populates the graph's
+ * {@link Graph.terminalNodeNames}, which is otherwise empty.
+ */
+export declare function createGraphFromEdgeItems(edgeItems: EdgeItem[]): Graph;
+export {};

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

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The new ADK workflow module (parity port of `google/adk-python`
+ * `google/adk/workflow`). Public surface mirrors Python's `__all__`, plus the
+ * TypeScript-specific helpers and the types needed to use the
+ * API from TypeScript.
+ */
+export { asRunnableRoot, isRunnableRoot, runNodeAsInvocation, } from './run_node_as_invocation.js';
+export type { RunNodeAsInvocationOptions, RunnableRoot, } from './run_node_as_invocation.js';
+export { Workflow, isWorkflow } from './workflow.js';
+export type { DynamicEntry, WorkflowConfig } from './workflow.js';
+export { BaseNode, START } from './base_node.js';
+export type { BaseNodeConfig } from './base_node.js';
+export { WorkflowNode, node } from './node.js';
+export type { NodeOptions } from './node.js';
+export { FunctionNode } from './nodes/function_node.js';
+export type { FunctionNodeConfig, FunctionNodeHandler, FunctionNodeResult, } from './nodes/function_node.js';
+export { JoinNode } from './nodes/join_node.js';
+export { NodeTool } from './nodes/node_tool.js';
+export { ParallelWorker } from './nodes/parallel_worker.js';
+export type { ParallelWorkerConfig } from './nodes/parallel_worker.js';
+export { ToolNode } from './nodes/tool_node.js';
+export type { ToolNodeConfig } from './nodes/tool_node.js';
+export type { BuildNodeOptions } from './utils/workflow_graph_utils.js';
+export { DEFAULT_ROUTE, Edge, Graph } from './graph.js';
+export type { ChainElement, EdgeItem, NodeLike, RouteValue, RoutingMap, RunnableNode, } from './graph.js';
+export { BranchPath, commonPrefixOf, createSubBranch } from './branch_path.js';
+export { NodeContext } from './node_context.js';
+export type { NodeContextOptions, NodeResult } from './node_context.js';
+export type { RunNodeOptions } from './node_runner.js';
+export { createNodeState, isNodeState } from './node_state.js';
+export type { NodeState } from './node_state.js';
+export { NodeStatus } from './node_status.js';
+export type { ScheduleDynamicNode, ScheduleDynamicNodeOptions, } from './schedule_dynamic_node.js';
+export { RequestInput, isRequestInput } from './request_input.js';
+export type { RequestInputParams } from './request_input.js';
+export { REQUEST_CREDENTIAL_FUNCTION_CALL_NAME, REQUEST_INPUT_FUNCTION_CALL_NAME, } from './utils/hitl_utils.js';
+export { normalizeRetryExceptions, prepareRetryConfig } from './retry_config.js';
+export type { ErrorClass, PreparedRetryConfig, RetryConfig, } from './retry_config.js';
+export { NodeReportedError, NodeSchemaValidationError, NodeTimeoutError, isNodeReportedError, isNodeSchemaValidationError, isNodeTimeoutError, } from './errors.js';
+export { createNodeErrorEvent, isNodeErrorEvent } from './node_error_event.js';
+export type { CreateNodeErrorEventParams, NodeErrorEvent, } from './node_error_event.js';

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

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Event } from '../events/event.js';
+import { BaseNode } from './base_node.js';
+import { NodeLike } from './graph.js';
+import { NodeContext } from './node_context.js';
+import { BuildNodeOptions } from './utils/workflow_graph_utils.js';
+/** Options accepted by {@link node}. */
+export type NodeOptions = BuildNodeOptions;
+/**
+ * Wraps a {@link NodeLike} (function, tool, agent, or existing node) into a
+ * {@link BaseNode}, optionally overriding its properties.
+ *
+ * The TypeScript form is a plain function (there is no `@node` decorator form,
+ * unlike Python). Examples:
+ *
+ * ```ts
+ * const a = node(myFunction, {name: 'classify'});
+ * const b = node(myTool);
+ * ```
+ *
+ * Ported from `google/adk-python` `workflow/_node.py::node`.
+ */
+export declare function node(nodeLike: NodeLike, options?: NodeOptions): BaseNode;
+/**
+ * A base class designed for subclassing. Implement {@link runNodeImpl} to
+ * provide node logic; subclasses inherit the schema/retry/timeout machinery of
+ * {@link BaseNode}.
+ *
+ * Named `WorkflowNode` (not `Node`) to read consistently with `Workflow` and
+ * `WorkflowConfig`, and to avoid shadowing the DOM / `@types/node` `Node`
+ * global in the flat `@google/adk` namespace. The `node()` factory remains the
+ * ergonomic way to wrap a function/tool/agent.
+ *
+ * Mirrors `google/adk-python` `workflow/_node.py::Node`. The `parallel_worker`
+ * capability is added in Phase 6.
+ */
+export declare abstract class WorkflowNode<TInput = unknown, TOutput = unknown> extends BaseNode<TInput, TOutput> {
+    /**
+     * Implement node execution logic here. May yield `Event`s, raw values, or
+     * `null` (normalized by {@link BaseNode.run}).
+     */
+    protected abstract runNodeImpl(ctx: NodeContext, input: TInput): AsyncGenerator<Event | TOutput | unknown, void, void>;
+    protected runImpl(ctx: NodeContext, input: TInput): AsyncGenerator<Event | TOutput | unknown, void, void>;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { NodeBuilder, ParallelWorkerFactory } from './utils/workflow_graph_utils.js';
+/**
+ * The built-in node builders, consulted in order by `buildNode` / `isNodeLike`
+ * to turn a bare function or tool into the right `BaseNode`.
+ *
+ * There is no agent builder: an agent is already a `BaseNode` and goes into a
+ * graph as itself. What used to be built here — an `LLMAgentWrapper` around it
+ * — now lives on the agent, as `LlmAgent.runImpl`.
+ *
+ * This is a single, explicit, statically-imported list — node-type modules are
+ * wired in here rather than self-registering at import time, so there is no
+ * global mutable registry and no import-order side effects. Order is the match
+ * precedence (first match wins). Each node-type part adds its builder here.
+ */
+export declare const NODE_BUILDERS: readonly NodeBuilder[];
+/**
+ * Wraps an already-built node in a parallel worker, used by the engine for
+ * `buildNode(..., {parallelWorker: true})`.
+ */
+export declare const PARALLEL_WORKER_FACTORY: ParallelWorkerFactory | undefined;

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;