@google/adk 1.6.0 → 2.1.0

package/dist/esm/workflow/node_runner.js

@@ -0,0 +1,439 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
+import { InvocationContext } from "../agents/invocation_context.js";
+import { createEvent } from "../events/event.js";
+import { traceNodeExecution, tracer } from "../telemetry/tracing.js";
+import { formatError } from "../utils/error_utils.js";
+import { createSubBranch } from "./branch_path.js";
+import {
+  InvocationAbortedError,
+  isDynamicNodeFailError,
+  isInvocationAbortedError,
+  isNodeInterruptedError,
+  NodeReportedError,
+  NodeTimeoutError
+} from "./errors.js";
+import { NodeContext } from "./node_context.js";
+import { claimNodeErrorReport, isNodeErrorEvent } from "./node_error_event.js";
+import { createNodeState } from "./node_state.js";
+import { NodeStatus } from "./node_status.js";
+import { getRetryDelaySeconds, shouldRetryNode } from "./utils/retry_utils.js";
+function executeChildNode(params) {
+  var _a, _b;
+  const { parent, node, options = {} } = params;
+  const nodeName = (_a = options.nodeName) != null ? _a : node.name;
+  const nodePath = (_b = options.overrideNodePath) != null ? _b : parent.nodePath ? `${parent.nodePath}.${nodeName}` : nodeName;
+  const span = tracer.startSpan(`execute_node ${nodeName}`);
+  return context.with(
+    trace.setSpan(context.active(), span),
+    () => runChildNode({ params, nodeName, nodePath, span })
+  );
+}
+__name(executeChildNode, "executeChildNode");
+async function runChildNode({
+  params: {
+    parent,
+    node,
+    input,
+    options = {},
+    abortSignal,
+    nodeState: callerNodeState,
+    resumeInputs
+  },
+  nodeName,
+  nodePath,
+  span
+}) {
+  var _a, _b, _c, _d;
+  const runId = (_a = options.runId) != null ? _a : nodeName;
+  let branch = parent.branch;
+  if (options.overrideBranch !== void 0) {
+    branch = options.overrideBranch;
+  } else if (options.useSubBranch) {
+    branch = createSubBranch(parent.branch, {
+      name: nodeName,
+      runId: options.runId
+    });
+  }
+  const declaredScope = node.isolationScope === true ? `${nodePath}@${runId}` : node.isolationScope;
+  const isolationScope = (_c = (_b = options.overrideIsolationScope) != null ? _b : declaredScope) != null ? _c : parent.isolationScope;
+  const effectiveAbortSignal = abortSignal != null ? abortSignal : parent.invocationContext.abortSignal;
+  const childIc = branch === parent.invocationContext.branch && effectiveAbortSignal === parent.invocationContext.abortSignal && isolationScope === parent.invocationContext.isolationScope ? parent.invocationContext : new InvocationContext({
+    ...parent.invocationContext,
+    branch,
+    abortSignal: effectiveAbortSignal,
+    isolationScope
+  });
+  const child = new NodeContext({
+    invocationContext: childIc,
+    channel: parent.channel,
+    nodePath,
+    runId,
+    resumeInputs: resumeInputs != null ? resumeInputs : parent.resumeInputs,
+    isolationScope,
+    // A node's own schema wins; otherwise it answers to its parent's.
+    stateSchema: (_d = node.stateSchema) != null ? _d : parent.stateSchema
+  });
+  child.scheduler = parent.scheduler;
+  if (options.useAsOutput) {
+    child.outputForAncestors = [
+      parent.nodePath,
+      ...parent.outputForAncestors
+    ].filter((path) => path !== "");
+  }
+  const nodeState = callerNodeState != null ? callerNodeState : createNodeState({
+    status: NodeStatus.RUNNING,
+    input,
+    runId
+  });
+  const pluginManager = child.invocationContext.pluginManager;
+  try {
+    if (pluginManager == null ? void 0 : pluginManager.hasPlugins) {
+      const skipOutput = await pluginManager.runBeforeNodeCallback({
+        node,
+        nodeContext: child,
+        input
+      });
+      if (skipOutput !== void 0) {
+        child.output = skipOutput;
+        traceNodeExecution({
+          nodePath,
+          runId,
+          attempt: nodeState.attemptCount,
+          status: "completed",
+          interruptCount: child.interruptIds.length
+        });
+        if (options.useAsOutput) {
+          parent.output = child.output;
+          parent.route = child.route;
+        }
+        return child;
+      }
+    }
+    let succeeded = false;
+    let inputRecorded = false;
+    while (!succeeded) {
+      resetState(child);
+      child.attemptCount = nodeState.attemptCount;
+      try {
+        inputRecorded = await runAttempt({
+          node,
+          child,
+          input,
+          nodeName,
+          branch,
+          isolationScope,
+          nodePath,
+          runId,
+          attempt: nodeState.attemptCount
+        });
+        failIfNodeReportedError(child, nodeName);
+        succeeded = true;
+      } catch (err) {
+        if (isNodeInterruptedError(err)) {
+          succeeded = true;
+          break;
+        }
+        if (isInvocationAbortedError(err)) {
+          throw err;
+        }
+        if (isDynamicNodeFailError(err)) {
+          throw err;
+        }
+        const retryConfig = node.preparedRetryConfig;
+        if (!retryConfig || !shouldRetryNode({ error: err, retryConfig, nodeState })) {
+          throw err;
+        }
+        const delaySeconds = getRetryDelaySeconds({ retryConfig, nodeState });
+        nodeState.attemptCount += 1;
+        await delay(delaySeconds * 1e3, effectiveAbortSignal);
+      }
+    }
+    if (!inputRecorded && child.interruptIds.length > 0) {
+      recordInputForResume({ child, nodeName, branch, isolationScope, input });
+    }
+    traceNodeExecution({
+      nodePath,
+      runId,
+      attempt: nodeState.attemptCount,
+      status: child.interruptIds.length > 0 ? "waiting" : "completed",
+      interruptCount: child.interruptIds.length
+    });
+    if (pluginManager == null ? void 0 : pluginManager.hasPlugins) {
+      const replacedOutput = await pluginManager.runAfterNodeCallback({
+        node,
+        nodeContext: child,
+        output: child.output
+      });
+      if (replacedOutput !== void 0) {
+        child.output = replacedOutput;
+      }
+    }
+    if (options.useAsOutput) {
+      parent.output = child.output;
+      parent.route = child.route;
+      parent.outputDelegated = true;
+    }
+    return child;
+  } catch (err) {
+    traceNodeExecution({
+      nodePath,
+      runId,
+      attempt: nodeState.attemptCount,
+      status: "failed",
+      interruptCount: child.interruptIds.length
+    });
+    span.setStatus({ code: SpanStatusCode.ERROR, message: formatError(err) });
+    throw err;
+  } finally {
+    span.end();
+  }
+}
+__name(runChildNode, "runChildNode");
+function runAttempt(params) {
+  const { node, nodePath, runId, attempt } = params;
+  if (!node.preparedRetryConfig) {
+    return runOnce(params);
+  }
+  return tracer.startActiveSpan(
+    `execute_node_attempt ${params.nodeName}`,
+    async (span) => {
+      try {
+        const inputRecorded = await runOnce(params);
+        traceNodeExecution({
+          nodePath,
+          runId,
+          attempt,
+          status: params.child.interruptIds.length > 0 ? "waiting" : "completed",
+          interruptCount: params.child.interruptIds.length
+        });
+        return inputRecorded;
+      } catch (err) {
+        traceNodeExecution({
+          nodePath,
+          runId,
+          attempt,
+          status: "failed",
+          interruptCount: params.child.interruptIds.length
+        });
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: formatError(err)
+        });
+        throw err;
+      } finally {
+        span.end();
+      }
+    }
+  );
+}
+__name(runAttempt, "runAttempt");
+function failIfNodeReportedError(child, nodeName) {
+  const reported = child.reportedError;
+  if (!reported || child.output !== void 0 || child.route !== void 0 || child.interruptIds.length > 0) {
+    return;
+  }
+  const error = new NodeReportedError({ nodeName, ...reported });
+  claimNodeErrorReport(error, child.invocationId);
+  throw error;
+}
+__name(failIfNodeReportedError, "failIfNodeReportedError");
+function resetState(childNodeContext) {
+  childNodeContext.output = void 0;
+  childNodeContext.route = void 0;
+  childNodeContext.interruptIds = [];
+  childNodeContext.reportedError = void 0;
+  for (const key of Object.keys(childNodeContext.actions.stateDelta)) {
+    delete childNodeContext.actions.stateDelta[key];
+  }
+}
+__name(resetState, "resetState");
+async function runOnce({
+  node,
+  child,
+  input,
+  nodeName,
+  branch,
+  isolationScope
+}) {
+  var _a;
+  let inputRecorded = false;
+  const consume = /* @__PURE__ */ __name((event) => {
+    var _a2, _b, _c;
+    enrichEvent({ event, child, nodeName, branch, isolationScope });
+    const emittedDelta = (_a2 = event.actions) == null ? void 0 : _a2.stateDelta;
+    if (emittedDelta && emittedDelta !== child.actions.stateDelta) {
+      child.state.validateDelta(emittedDelta);
+    }
+    if (event.output !== void 0) {
+      child.output = event.output;
+      if (child.outputDelegated) {
+        const stateDelta = (_b = event.actions) == null ? void 0 : _b.stateDelta;
+        if (!stateDelta || Object.keys(stateDelta).length === 0) {
+          return;
+        }
+        event.output = void 0;
+        event.content = void 0;
+      }
+    }
+    if (event.route !== void 0) {
+      child.route = event.route;
+    }
+    if (event.errorCode !== void 0 && !isNodeErrorEvent(event)) {
+      child.reportedError = {
+        errorCode: event.errorCode,
+        errorMessage: event.errorMessage
+      };
+    }
+    if (event.longRunningToolIds && event.longRunningToolIds.length > 0) {
+      for (const id of event.longRunningToolIds) {
+        if (!child.interruptIds.includes(id)) {
+          child.interruptIds.push(id);
+        }
+      }
+      event.actions.agentState = {
+        ...(_c = event.actions.agentState) != null ? _c : {},
+        input
+      };
+      inputRecorded = true;
+    }
+    child.channel.push(event);
+  }, "consume");
+  const parentSignal = child.invocationContext.abortSignal;
+  const hasTimeout = typeof node.timeout === "number" && node.timeout > 0;
+  if (!hasTimeout && !parentSignal) {
+    for await (const event of node.run(child, input)) {
+      consume(event);
+    }
+    return inputRecorded;
+  }
+  if (!hasTimeout) {
+    child.abortSignal = parentSignal;
+    try {
+      for await (const event of node.run(child, input)) {
+        consume(event);
+      }
+    } finally {
+      child.abortSignal = void 0;
+    }
+    return inputRecorded;
+  }
+  const timeoutSeconds = node.timeout;
+  const controller = new AbortController();
+  const onParentAbort = /* @__PURE__ */ __name(() => controller.abort(), "onParentAbort");
+  if (parentSignal == null ? void 0 : parentSignal.aborted) {
+    controller.abort();
+  } else {
+    parentSignal == null ? void 0 : parentSignal.addEventListener("abort", onParentAbort, { once: true });
+  }
+  let deadlineFired = false;
+  const timer = setTimeout(
+    () => {
+      deadlineFired = true;
+      controller.abort();
+    },
+    (timeoutSeconds != null ? timeoutSeconds : 0) * 1e3
+  );
+  child.abortSignal = controller.signal;
+  const aborted = new Promise((_, reject) => {
+    const fail = /* @__PURE__ */ __name(() => reject(
+      deadlineFired ? new NodeTimeoutError({ nodeName, timeout: timeoutSeconds != null ? timeoutSeconds : 0 }) : new InvocationAbortedError(
+        `Invocation aborted while running node '${nodeName}'.`
+      )
+    ), "fail");
+    if (controller.signal.aborted) {
+      fail();
+    } else {
+      controller.signal.addEventListener("abort", fail, { once: true });
+    }
+  });
+  const iterator = node.run(child, input)[Symbol.asyncIterator]();
+  try {
+    let result = await Promise.race([iterator.next(), aborted]);
+    while (!result.done) {
+      consume(result.value);
+      result = await Promise.race([iterator.next(), aborted]);
+    }
+  } finally {
+    clearTimeout(timer);
+    parentSignal == null ? void 0 : parentSignal.removeEventListener("abort", onParentAbort);
+    child.abortSignal = void 0;
+    void Promise.resolve((_a = iterator.return) == null ? void 0 : _a.call(iterator, void 0)).catch(() => {
+    });
+  }
+  return inputRecorded;
+}
+__name(runOnce, "runOnce");
+function recordInputForResume({
+  child,
+  nodeName,
+  branch,
+  isolationScope,
+  input
+}) {
+  const event = createEvent({
+    author: nodeName,
+    invocationId: child.invocationId,
+    branch,
+    longRunningToolIds: [...child.interruptIds],
+    actions: { agentState: { input } }
+  });
+  enrichEvent({ event, child, nodeName, branch, isolationScope });
+  child.channel.push(event);
+}
+__name(recordInputForResume, "recordInputForResume");
+function enrichEvent({
+  event,
+  child,
+  nodeName,
+  branch,
+  isolationScope
+}) {
+  var _a;
+  if (!event.author) {
+    event.author = nodeName;
+  }
+  if (!event.invocationId) {
+    event.invocationId = child.invocationId;
+  }
+  event.nodeInfo = { ...(_a = event.nodeInfo) != null ? _a : {}, path: child.nodePath };
+  if (event.output !== void 0) {
+    event.nodeInfo.outputFor = [child.nodePath, ...child.outputForAncestors];
+  }
+  if (branch !== void 0 && event.branch === void 0) {
+    event.branch = branch;
+  }
+  if (isolationScope !== void 0 && event.isolationScope === void 0) {
+    event.isolationScope = isolationScope;
+  }
+}
+__name(enrichEvent, "enrichEvent");
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal == null ? void 0 : signal.aborted) {
+      reject(new InvocationAbortedError("Invocation aborted during retry."));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal == null ? void 0 : signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = /* @__PURE__ */ __name(() => {
+      clearTimeout(timer);
+      reject(new InvocationAbortedError("Invocation aborted during retry."));
+    }, "onAbort");
+    signal == null ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+__name(delay, "delay");
+export {
+  executeChildNode
+};

package/dist/esm/workflow/node_state.js

@@ -0,0 +1,29 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { NodeStatus } from "./node_status.js";
+function createNodeState(partial) {
+  return {
+    status: NodeStatus.INACTIVE,
+    attemptCount: 1,
+    interrupts: [],
+    resumeInputs: {},
+    runCounter: 0,
+    ...partial
+  };
+}
+__name(createNodeState, "createNodeState");
+function isNodeState(obj) {
+  return typeof obj === "object" && obj !== null && "status" in obj && typeof obj.status === "number" && "attemptCount" in obj && "interrupts" in obj && Array.isArray(obj.interrupts);
+}
+__name(isNodeState, "isNodeState");
+export {
+  createNodeState,
+  isNodeState
+};

package/dist/esm/workflow/node_status.js

@@ -0,0 +1,20 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var NodeStatus = /* @__PURE__ */ ((NodeStatus2) => {
+  NodeStatus2[NodeStatus2["INACTIVE"] = 0] = "INACTIVE";
+  NodeStatus2[NodeStatus2["PENDING"] = 1] = "PENDING";
+  NodeStatus2[NodeStatus2["RUNNING"] = 2] = "RUNNING";
+  NodeStatus2[NodeStatus2["COMPLETED"] = 3] = "COMPLETED";
+  NodeStatus2[NodeStatus2["WAITING"] = 4] = "WAITING";
+  NodeStatus2[NodeStatus2["FAILED"] = 5] = "FAILED";
+  NodeStatus2[NodeStatus2["CANCELLED"] = 6] = "CANCELLED";
+  return NodeStatus2;
+})(NodeStatus || {});
+export {
+  NodeStatus
+};

package/dist/esm/workflow/nodes/function_node.js

@@ -0,0 +1,172 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createEvent, isEvent } from "../../events/event.js";
+import { carryDeltaStamp } from "../../sessions/state_write_order.js";
+import { BaseNode, isContent, toContent } from "../base_node.js";
+import {
+  createAuthRequestEvent,
+  hasAuthCredential,
+  processAuthResume
+} from "../utils/hitl_utils.js";
+const _FunctionNode = class _FunctionNode extends BaseNode {
+  constructor(name, handler, config = {}) {
+    if (typeof handler !== "function") {
+      throw new TypeError("FunctionNode handler must be a function.");
+    }
+    super({ ...config, name });
+    /** Per-run shadow of the state entries already attached to an emitted event. */
+    this.attachedStateByCtx = /* @__PURE__ */ new WeakMap();
+    this.handler = handler;
+    this.authConfig = config.authConfig;
+  }
+  async *runImpl(ctx, input) {
+    if (this.authConfig) {
+      const authRequest = await this.runAuthGate(ctx);
+      if (authRequest) {
+        yield authRequest;
+        return;
+      }
+    }
+    const result = this.handler(ctx, input);
+    if (isAsyncIterable(result)) {
+      for await (const item of result) {
+        yield item;
+      }
+    } else if (isSyncGenerator(result)) {
+      for (const item of result) {
+        yield item;
+      }
+    } else {
+      yield await result;
+    }
+    yield void 0;
+  }
+  /**
+   * 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.
+   */
+  async runAuthGate(ctx) {
+    const authConfig = this.authConfig;
+    if (hasAuthCredential(authConfig, ctx.state)) {
+      return void 0;
+    }
+    const resumeResponse = ctx.resumeInputs[authConfig.credentialKey];
+    if (resumeResponse !== void 0) {
+      await processAuthResume({
+        responseData: resumeResponse,
+        authConfig,
+        state: ctx.state
+      });
+      if (hasAuthCredential(authConfig, ctx.state)) {
+        return void 0;
+      }
+    }
+    return createAuthRequestEvent(authConfig, authConfig.credentialKey);
+  }
+  /**
+   * 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).
+   */
+  pendingStateDelta(ctx) {
+    let shadow = this.attachedStateByCtx.get(ctx);
+    if (!shadow) {
+      shadow = /* @__PURE__ */ new Map();
+      this.attachedStateByCtx.set(ctx, shadow);
+    }
+    const delta = {};
+    for (const [key, value] of Object.entries(ctx.actions.stateDelta)) {
+      if (!shadow.has(key) || shadow.get(key) !== value) {
+        delta[key] = value;
+        shadow.set(key, value);
+        carryDeltaStamp(ctx.actions.stateDelta, delta, key);
+      }
+    }
+    return Object.keys(delta).length > 0 ? delta : void 0;
+  }
+  /**
+   * 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.
+   */
+  applyEmittedState(ctx, delta) {
+    if (!delta || Object.keys(delta).length === 0) {
+      return;
+    }
+    ctx.state.update(delta);
+    const shadow = this.attachedStateByCtx.get(ctx);
+    if (shadow) {
+      for (const [key, value] of Object.entries(delta)) {
+        shadow.set(key, value);
+      }
+    }
+  }
+  toEvent(ctx, data) {
+    const stateDelta = this.pendingStateDelta(ctx);
+    if (data === null || data === void 0) {
+      return stateDelta ? createEvent({
+        author: this.name,
+        invocationId: ctx.invocationId,
+        branch: ctx.branch,
+        actions: { stateDelta }
+      }) : null;
+    }
+    if (isEvent(data)) {
+      const event = data;
+      if (event.output !== void 0) {
+        event.output = this.validateOutput(event.output);
+      }
+      if (stateDelta) {
+        event.actions.stateDelta = { ...stateDelta, ...event.actions.stateDelta };
+      }
+      this.applyEmittedState(ctx, event.actions.stateDelta);
+      return event;
+    }
+    if (isContent(data)) {
+      return createEvent({
+        author: this.name,
+        invocationId: ctx.invocationId,
+        branch: ctx.branch,
+        content: data,
+        actions: stateDelta ? { stateDelta } : void 0
+      });
+    }
+    const output = this.validateOutput(data);
+    return createEvent({
+      author: this.name,
+      invocationId: ctx.invocationId,
+      branch: ctx.branch,
+      content: toContent(output),
+      output,
+      actions: stateDelta ? { stateDelta } : void 0
+    });
+  }
+};
+__name(_FunctionNode, "FunctionNode");
+let FunctionNode = _FunctionNode;
+function isAsyncIterable(value) {
+  return value != null && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isAsyncIterable, "isAsyncIterable");
+function isSyncGenerator(value) {
+  return value != null && typeof value[Symbol.iterator] === "function" && typeof value.next === "function";
+}
+__name(isSyncGenerator, "isSyncGenerator");
+export {
+  FunctionNode
+};

package/dist/esm/workflow/nodes/join_node.js

@@ -0,0 +1,29 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createEvent } from "../../events/event.js";
+import { BaseNode } from "../base_node.js";
+const _JoinNode = class _JoinNode extends BaseNode {
+  get requiresAllPredecessors() {
+    return true;
+  }
+  async *runImpl(ctx, input) {
+    yield createEvent({
+      author: this.name,
+      invocationId: ctx.invocationId,
+      branch: ctx.branch,
+      output: input
+    });
+  }
+};
+__name(_JoinNode, "JoinNode");
+let JoinNode = _JoinNode;
+export {
+  JoinNode
+};