@google/adk 1.6.0 → 2.0.0

package/dist/cjs/workflow/base_node.js

@@ -0,0 +1,211 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var base_node_exports = {};
+__export(base_node_exports, {
+  BaseNode: () => BaseNode,
+  START: () => START,
+  isBaseNode: () => isBaseNode,
+  isContent: () => isContent,
+  toContent: () => toContent
+});
+module.exports = __toCommonJS(base_node_exports);
+var import_genai = require("@google/genai");
+var import_event = require("../events/event.js");
+var import_schema = require("../utils/schema.js");
+var import_errors = require("./errors.js");
+var import_request_input = require("./request_input.js");
+var import_retry_config = require("./retry_config.js");
+var import_hitl_utils = require("./utils/hitl_utils.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a;
+const BASE_NODE_SIGNATURE_SYMBOL = Symbol.for("google.adk.workflow.baseNode");
+_a = BASE_NODE_SIGNATURE_SYMBOL;
+const _BaseNode = class _BaseNode {
+  constructor(config) {
+    /** Brand identifying this object as a {@link BaseNode} (see `isBaseNode`). */
+    this[_a] = true;
+    var _a2, _b, _c;
+    if (!config.name || typeof config.name !== "string" || config.name.trim().length === 0) {
+      throw new Error("Node name must be a non-empty string.");
+    }
+    this.name = config.name.trim();
+    this.description = (_a2 = config.description) != null ? _a2 : "";
+    this.rerunOnResume = (_b = config.rerunOnResume) != null ? _b : false;
+    this.waitForOutput = (_c = config.waitForOutput) != null ? _c : false;
+    this.retryConfig = config.retryConfig;
+    this.preparedRetryConfig = config.retryConfig ? (0, import_retry_config.prepareRetryConfig)(config.retryConfig) : void 0;
+    this.timeout = config.timeout;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this.stateSchema = config.stateSchema;
+    this.isolationScope = config.isolationScope;
+  }
+  /**
+   * Whether this node must wait for ALL of its predecessors to trigger before
+   * it runs (fan-in barrier). Overridden by `JoinNode`.
+   */
+  get requiresAllPredecessors() {
+    return false;
+  }
+  /**
+   * Runs the node, normalizing every yielded item into an {@link Event}. This
+   * is what the engine (and `ctx.runNode()`) consumes. Validates the input
+   * against `inputSchema` once, up front (skipping genai `Content`, which nodes
+   * coerce themselves).
+   */
+  async *run(ctx, input) {
+    const validatedInput = this.validateInput(input);
+    for await (const item of this.runImpl(ctx, validatedInput)) {
+      if ((0, import_request_input.isRequestInput)(item)) {
+        yield (0, import_hitl_utils.createRequestInputEvent)(item);
+        continue;
+      }
+      const event = this.toEvent(ctx, item);
+      if (event) {
+        yield event;
+      }
+    }
+  }
+  /**
+   * Validates node input against `inputSchema` (Content passes through). Only
+   * enforced for Zod schemas; a genai `Schema` is left unvalidated (see
+   * `parseWithSchema`).
+   */
+  validateInput(input) {
+    if (isContent(input)) {
+      return input;
+    }
+    try {
+      return (0, import_schema.parseWithSchema)(this.inputSchema, input);
+    } catch (e) {
+      throw new import_errors.NodeSchemaValidationError({
+        nodeName: this.name,
+        direction: "input",
+        cause: e
+      });
+    }
+  }
+  /**
+   * Validates node output against `outputSchema` (Content passes through). Only
+   * enforced for Zod schemas; a genai `Schema` is left unvalidated (see
+   * `parseWithSchema`).
+   */
+  validateOutput(output) {
+    if (isContent(output)) {
+      return output;
+    }
+    try {
+      return (0, import_schema.parseWithSchema)(this.outputSchema, output);
+    } catch (e) {
+      throw new import_errors.NodeSchemaValidationError({
+        nodeName: this.name,
+        direction: "output",
+        cause: e
+      });
+    }
+  }
+  /**
+   * Normalizes a single yielded item into an {@link Event} (or `null` to skip).
+   * Subclasses may override for richer coercion (e.g. `FunctionNode`).
+   */
+  toEvent(ctx, data) {
+    if (data === null || data === void 0) {
+      return null;
+    }
+    if ((0, import_event.isEvent)(data)) {
+      const event = data;
+      if (event.output !== void 0) {
+        event.output = this.validateOutput(event.output);
+      }
+      return event;
+    }
+    const output = this.validateOutput(data);
+    return (0, import_event.createEvent)({
+      author: this.name,
+      invocationId: ctx.invocationContext.invocationId,
+      branch: ctx.branch,
+      content: toContent(output),
+      output
+    });
+  }
+};
+__name(_BaseNode, "BaseNode");
+let BaseNode = _BaseNode;
+function isBaseNode(value) {
+  return typeof value === "object" && value !== null && BASE_NODE_SIGNATURE_SYMBOL in value && value[BASE_NODE_SIGNATURE_SYMBOL] === true;
+}
+__name(isBaseNode, "isBaseNode");
+function isContent(value) {
+  return typeof value === "object" && value !== null && "parts" in value && Array.isArray(value.parts);
+}
+__name(isContent, "isContent");
+const _StartNode = class _StartNode extends BaseNode {
+  // eslint-disable-next-line require-yield
+  async *runImpl() {
+    throw new Error("START node is never executed.");
+  }
+};
+__name(_StartNode, "StartNode");
+let StartNode = _StartNode;
+const START = new StartNode({ name: "__START__" });
+function toContent(val) {
+  if (val === null || val === void 0) {
+    return void 0;
+  }
+  if (isContent(val)) {
+    return val;
+  }
+  try {
+    return (0, import_genai.createModelContent)(val);
+  } catch {
+    return (0, import_genai.createModelContent)(valueToText(val));
+  }
+}
+__name(toContent, "toContent");
+function valueToText(val) {
+  var _a2;
+  if (typeof val === "string") {
+    return val;
+  }
+  try {
+    return (_a2 = JSON.stringify(val)) != null ? _a2 : String(val);
+  } catch {
+    return String(val);
+  }
+}
+__name(valueToText, "valueToText");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseNode,
+  START,
+  isBaseNode,
+  isContent,
+  toContent
+});

package/dist/cjs/workflow/branch_path.js

@@ -0,0 +1,108 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var branch_path_exports = {};
+__export(branch_path_exports, {
+  BranchPath: () => BranchPath,
+  branchPathFromString: () => branchPathFromString,
+  commonPrefixOf: () => commonPrefixOf,
+  commonPrefixOfPaths: () => commonPrefixOfPaths,
+  createSubBranch: () => createSubBranch
+});
+module.exports = __toCommonJS(branch_path_exports);
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const _BranchPath = class _BranchPath {
+  constructor(segments) {
+    this.segments = [...segments];
+  }
+  toString() {
+    return this.segments.join(".");
+  }
+  /** Returns a copy of the path segments. */
+  getSegments() {
+    return [...this.segments];
+  }
+  /** Whether this path is a strict descendant of `ancestor`. */
+  isDescendantOf(ancestor) {
+    if (this.segments.length <= ancestor.segments.length) {
+      return false;
+    }
+    return ancestor.segments.every((seg, i) => this.segments[i] === seg);
+  }
+  /** Returns a new path with a `name@runId` (or `name`) segment appended. */
+  append(name, runId) {
+    const segment = runId !== void 0 ? `${name}@${runId}` : name;
+    return new _BranchPath([...this.segments, segment]);
+  }
+};
+__name(_BranchPath, "BranchPath");
+let BranchPath = _BranchPath;
+function branchPathFromString(path) {
+  if (!path) {
+    return new BranchPath([]);
+  }
+  return new BranchPath(path.split("."));
+}
+__name(branchPathFromString, "branchPathFromString");
+function commonPrefixOfPaths(paths) {
+  if (paths.length === 0) {
+    return new BranchPath([]);
+  }
+  const allSegments = paths.map((p) => p.getSegments());
+  const common = [];
+  const minLen = Math.min(...allSegments.map((s) => s.length));
+  for (let i = 0; i < minLen; i++) {
+    const seg = allSegments[0][i];
+    if (allSegments.every((s) => s[i] === seg)) {
+      common.push(seg);
+    } else {
+      break;
+    }
+  }
+  return new BranchPath(common);
+}
+__name(commonPrefixOfPaths, "commonPrefixOfPaths");
+function createSubBranch(baseBranch, options) {
+  return branchPathFromString(baseBranch).append(options.name, options.runId).toString();
+}
+__name(createSubBranch, "createSubBranch");
+function commonPrefixOf(branches) {
+  return commonPrefixOfPaths(
+    branches.map((b) => branchPathFromString(b))
+  ).toString();
+}
+__name(commonPrefixOf, "commonPrefixOf");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BranchPath,
+  branchPathFromString,
+  commonPrefixOf,
+  commonPrefixOfPaths,
+  createSubBranch
+});

package/dist/cjs/workflow/dynamic_node_scheduler.js

@@ -0,0 +1,220 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var dynamic_node_scheduler_exports = {};
+__export(dynamic_node_scheduler_exports, {
+  DynamicNodeScheduler: () => DynamicNodeScheduler
+});
+module.exports = __toCommonJS(dynamic_node_scheduler_exports);
+var import_errors = require("./errors.js");
+var import_node_runner = require("./node_runner.js");
+var import_node_state = require("./node_state.js");
+var import_node_status = require("./node_status.js");
+var import_rehydration_utils = require("./utils/rehydration_utils.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const _DynamicNodeScheduler = class _DynamicNodeScheduler {
+  /**
+   * @param state Shared dynamic-node bookkeeping for this workflow subtree.
+   * @param abortSignal Workflow-scoped cancellation signal, forwarded to each
+   *   dynamic child so a workflow shutting down on error can cancel in-flight
+   *   `ctx.runNode()` children too.
+   */
+  constructor(state, abortSignal) {
+    this.state = state;
+    this.abortSignal = abortSignal;
+  }
+  /**
+   * Runs a `ctx.runNode()` call and reports any interrupt it is still waiting
+   * on to the caller's own context.
+   *
+   * A child's interrupt is the caller's problem: the caller cannot produce a
+   * trustworthy result until the human answers, and until the engine knows the
+   * caller is waiting it marks it COMPLETED and schedules its successor —
+   * which then runs on the `undefined` the caller returned when it bailed out.
+   * `ParallelWorker` has always copied its items' interrupt ids onto its own
+   * context for exactly this reason; doing it here extends that to every
+   * caller instead of only the one that remembered.
+   *
+   * Only unresolved interrupts arrive here. A child fast-forwarded from a
+   * checkpoint, or handed a resolved reply as its output, reports none.
+   */
+  async schedule(ctx, node, input, options) {
+    const result = await this.scheduleRun(ctx, node, input, options);
+    for (const id of result.interruptIds) {
+      if (!ctx.interruptIds.includes(id)) {
+        ctx.interruptIds.push(id);
+      }
+    }
+    return result;
+  }
+  async scheduleRun(ctx, node, input, options) {
+    var _a, _b, _c;
+    const name = (_a = options.nodeName) != null ? _a : node.name;
+    const runId = options.runId;
+    const nodePath = ctx.nodePath ? `${ctx.nodePath}.${name}@${runId}` : `${name}@${runId}`;
+    const existing = this.state.runs.get(nodePath);
+    if (existing == null ? void 0 : existing.task) {
+      return existing.task;
+    }
+    if (existing == null ? void 0 : existing.result) {
+      return this.handBack(ctx, existing.result, options);
+    }
+    if (!this.state.runs.has(nodePath)) {
+      const prior = (0, import_rehydration_utils.reconstructNodeStatesByPath)(
+        (0, import_rehydration_utils.eventsForCurrentRun)((_c = (_b = ctx.session) == null ? void 0 : _b.events) != null ? _c : [], ctx.invocationId)
+      ).get(nodePath);
+      if (prior && (0, import_rehydration_utils.isFastForwardable)(prior)) {
+        return this.completeWithoutRunning(
+          ctx,
+          { nodePath, runId, options },
+          (0, import_rehydration_utils.makeFastForwardResult)(ctx, prior)
+        );
+      }
+      const handoff = this.resumeHandoff(ctx, node, prior);
+      if (handoff) {
+        return this.completeWithoutRunning(
+          ctx,
+          { nodePath, runId, options },
+          handoff
+        );
+      }
+    }
+    return this.runFresh(ctx, node, input, name, runId, nodePath, options);
+  }
+  /**
+   * Books a dynamic run that completed WITHOUT executing its body — either
+   * fast-forwarded from a cached output or handed the resolved resume value —
+   * and returns `result` for `ctx.runNode()` to give back to the caller.
+   */
+  completeWithoutRunning(ctx, run, result) {
+    this.state.runs.set(run.nodePath, {
+      state: (0, import_node_state.createNodeState)({
+        status: import_node_status.NodeStatus.COMPLETED,
+        runId: run.runId,
+        parentRunId: ctx.runId
+      }),
+      output: result.output,
+      result
+    });
+    return this.handBack(ctx, result, run.options);
+  }
+  /**
+   * Applies a settled result to the caller's context and returns it, so a first
+   * call and a repeat call for the same path are indistinguishable.
+   */
+  handBack(ctx, result, options) {
+    if (options.useAsOutput) {
+      ctx.output = result.output;
+      ctx.route = result.route;
+    }
+    return result;
+  }
+  /**
+   * Builds the completion result for a child that interrupted in a prior turn
+   * and whose interrupts are now all resolved, or `undefined` when the child is
+   * not in that state (so the caller falls through to a fresh run).
+   */
+  resumeHandoff(ctx, node, prior) {
+    var _a;
+    if (!prior || node.rerunOnResume || prior.output !== void 0 || prior.interruptIds.size === 0) {
+      return void 0;
+    }
+    const values = [...prior.interruptIds].map((id) => ctx.resumeInputs[id]);
+    if (!values.every((value) => value !== void 0)) {
+      return void 0;
+    }
+    return {
+      output: values.length === 1 ? values[0] : values,
+      route: void 0,
+      branch: (_a = prior.branch) != null ? _a : ctx.branch,
+      interruptIds: []
+    };
+  }
+  async runFresh(ctx, node, input, name, runId, nodePath, options) {
+    const run = {
+      state: (0, import_node_state.createNodeState)({
+        status: import_node_status.NodeStatus.RUNNING,
+        input,
+        runId,
+        parentRunId: ctx.runId
+      })
+    };
+    this.state.runs.set(nodePath, run);
+    run.task = (0, import_node_runner.executeChildNode)({
+      parent: ctx,
+      node,
+      input,
+      abortSignal: this.abortSignal,
+      options: {
+        nodeName: name,
+        runId,
+        overrideNodePath: nodePath,
+        useAsOutput: options.useAsOutput,
+        useSubBranch: options.useSubBranch,
+        overrideBranch: options.overrideBranch,
+        overrideIsolationScope: options.overrideIsolationScope
+      }
+    });
+    let childCtx;
+    try {
+      childCtx = await run.task;
+    } catch (err) {
+      if ((0, import_errors.isNodeInterruptedError)(err) || (0, import_errors.isDynamicNodeFailError)(err)) {
+        throw err;
+      }
+      run.state.status = import_node_status.NodeStatus.FAILED;
+      const error = err instanceof Error ? err : new Error(String(err));
+      throw new import_errors.DynamicNodeFailError({
+        message: `Dynamic node ${name} failed: ${error.message}`,
+        error,
+        errorNodePath: nodePath
+      });
+    }
+    this.recordResult(run, childCtx, node);
+    return childCtx;
+  }
+  recordResult(run, childCtx, node) {
+    if (childCtx.interruptIds.length > 0) {
+      run.state.status = import_node_status.NodeStatus.WAITING;
+      run.state.interrupts = [...childCtx.interruptIds];
+      childCtx.interruptIds.forEach((id) => this.state.interruptIds.add(id));
+    } else if (node.waitForOutput && childCtx.output === void 0 && childCtx.route === void 0) {
+      run.state.status = import_node_status.NodeStatus.WAITING;
+    } else {
+      run.state.status = import_node_status.NodeStatus.COMPLETED;
+      run.output = childCtx.output;
+    }
+  }
+};
+__name(_DynamicNodeScheduler, "DynamicNodeScheduler");
+let DynamicNodeScheduler = _DynamicNodeScheduler;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DynamicNodeScheduler
+});