@google/adk 1.5.0 → 2.0.0

package/dist/cjs/workflow/node_context.js

@@ -0,0 +1,246 @@
+/**
+  * @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 node_context_exports = {};
+__export(node_context_exports, {
+  NodeContext: () => NodeContext
+});
+module.exports = __toCommonJS(node_context_exports);
+var import_event_actions = require("../events/event_actions.js");
+var import_state = require("../sessions/state.js");
+var import_errors = require("./errors.js");
+var import_node_runner = require("./node_runner.js");
+var import_workflow_graph_utils = require("./utils/workflow_graph_utils.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const _NodeContext = class _NodeContext {
+  constructor(opts) {
+    /**
+     * 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.
+     */
+    this.outputForAncestors = [];
+    /**
+     * 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.
+     */
+    this.outputDelegated = false;
+    /** The structured output produced by the node during its run. */
+    this.output = void 0;
+    /** Interrupt ids the node is currently blocked on (HITL). */
+    this.interruptIds = [];
+    /** The current attempt number (1-based) for the running node (see retry). */
+    this.attemptCount = 1;
+    this.dynamicRunCounters = /* @__PURE__ */ new Map();
+    /** Run ids this context handed out automatically, per node name. */
+    this.autoRunIds = /* @__PURE__ */ new Map();
+    /**
+     * Caller-supplied run ids shaped like an automatic one (all digits), per node
+     * name — the set {@link assertNoNumericCustomRunIds} refuses to auto-number
+     * around.
+     */
+    this.numericCustomRunIds = /* @__PURE__ */ new Map();
+    var _a, _b;
+    this.invocationContext = opts.invocationContext;
+    this.channel = opts.channel;
+    this.nodePath = opts.nodePath;
+    this.runId = opts.runId;
+    this.resumeInputs = (_a = opts.resumeInputs) != null ? _a : {};
+    this.isolationScope = opts.isolationScope;
+    this.actions = (_b = opts.actions) != null ? _b : (0, import_event_actions.createEventActions)();
+    this.stateSchema = opts.stateSchema;
+    this._state = new import_state.State(
+      opts.invocationContext.session.state,
+      this.actions.stateDelta,
+      opts.stateSchema
+    );
+  }
+  /** Delta-aware session state; writes accumulate in `actions.stateDelta`. */
+  get state() {
+    return this._state;
+  }
+  /** The branch of the owning invocation context. */
+  get branch() {
+    return this.invocationContext.branch;
+  }
+  /** The current invocation id. */
+  get invocationId() {
+    return this.invocationContext.invocationId;
+  }
+  /** The current session. */
+  get session() {
+    return this.invocationContext.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() {
+    return this.invocationContext;
+  }
+  /** Streams a single event out through the workflow's event channel. */
+  emit(event) {
+    this.channel.push(event);
+  }
+  /**
+   * 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, input, options) {
+    var _a, _b;
+    const node = (0, import_workflow_graph_utils.buildNode)(nodeLike);
+    if (this.scheduler) {
+      const nodeName = (_a = options == null ? void 0 : options.nodeName) != null ? _a : node.name;
+      let runId = options == null ? void 0 : options.runId;
+      if (runId !== void 0) {
+        assertCustomRunId(runId, nodeName, mapSet(this.autoRunIds, nodeName));
+        if (isAutoNumberShaped(runId)) {
+          mapSet(this.numericCustomRunIds, nodeName).add(runId);
+        }
+      }
+      if (!runId) {
+        assertNoNumericCustomRunIds(
+          nodeName,
+          mapSet(this.numericCustomRunIds, nodeName)
+        );
+        const next = ((_b = this.dynamicRunCounters.get(nodeName)) != null ? _b : 0) + 1;
+        this.dynamicRunCounters.set(nodeName, next);
+        runId = String(next);
+        mapSet(this.autoRunIds, nodeName).add(runId);
+      }
+      return this.scheduleAndUnwind(node, input, {
+        ...options,
+        nodeName,
+        runId
+      });
+    }
+    return (0, import_node_runner.executeChildNode)({ parent: this, node, input, options });
+  }
+  /**
+   * 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.
+   */
+  async scheduleAndUnwind(node, input, options) {
+    const child = await this.scheduler.schedule(this, node, input, options);
+    if (child.interruptIds.length > 0) {
+      throw new import_errors.NodeInterruptedError();
+    }
+    return child;
+  }
+};
+__name(_NodeContext, "NodeContext");
+let NodeContext = _NodeContext;
+function mapSet(map, key) {
+  let set = map.get(key);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    map.set(key, set);
+  }
+  return set;
+}
+__name(mapSet, "mapSet");
+function isAutoNumberShaped(runId) {
+  return /^\d+$/.test(runId);
+}
+__name(isAutoNumberShaped, "isAutoNumberShaped");
+function numericRunIdMixError(nodeName, runId) {
+  return new Error(
+    `Invalid runId '${runId}' for node '${nodeName}': ADK numbers automatic runs of a node "1", "2", "3", \u2026 per context, so an all-digit custom id draws from that same namespace. A later turn that issues a different set of custom ids shifts the automatic sequence onto a checkpoint path an earlier call already wrote, and the call is fast-forwarded to that run's cached output with its own input silently discarded. Give the custom id a non-numeric part, e.g. '${nodeName}-${runId}', or supply an explicit id for every run of this node so ADK never numbers one.`
+  );
+}
+__name(numericRunIdMixError, "numericRunIdMixError");
+function assertCustomRunId(runId, nodeName, autoRunIds) {
+  if (runId.trim() === "") {
+    throw new Error(
+      `Invalid runId for node '${nodeName}': a custom run id cannot be empty. Omit runId to let ADK number the run automatically.`
+    );
+  }
+  if (autoRunIds.size > 0 && isAutoNumberShaped(runId)) {
+    throw numericRunIdMixError(nodeName, runId);
+  }
+}
+__name(assertCustomRunId, "assertCustomRunId");
+function assertNoNumericCustomRunIds(nodeName, numericCustomRunIds) {
+  const first = numericCustomRunIds.values().next();
+  if (!first.done) {
+    throw numericRunIdMixError(nodeName, first.value);
+  }
+}
+__name(assertNoNumericCustomRunIds, "assertNoNumericCustomRunIds");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NodeContext
+});

package/dist/cjs/workflow/node_error_event.js

@@ -0,0 +1,86 @@
+/**
+  * @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 node_error_event_exports = {};
+__export(node_error_event_exports, {
+  claimNodeErrorReport: () => claimNodeErrorReport,
+  createNodeErrorEvent: () => createNodeErrorEvent,
+  isNodeErrorEvent: () => isNodeErrorEvent
+});
+module.exports = __toCommonJS(node_error_event_exports);
+var import_event = require("../events/event.js");
+var import_retry_utils = require("./utils/retry_utils.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function isNodeErrorEvent(event) {
+  return "isNodeError" in event && event.isNodeError === true;
+}
+__name(isNodeErrorEvent, "isNodeErrorEvent");
+const reportedInvocationIds = /* @__PURE__ */ new WeakMap();
+function claimNodeErrorReport(error, invocationId) {
+  if (typeof error !== "object" || error === null) {
+    return true;
+  }
+  if (reportedInvocationIds.get(error) === invocationId) {
+    return false;
+  }
+  reportedInvocationIds.set(error, invocationId);
+  return true;
+}
+__name(claimNodeErrorReport, "claimNodeErrorReport");
+function createNodeErrorEvent(params) {
+  var _a, _b;
+  const { error, attemptCount, ...eventParams } = params;
+  return {
+    ...(0, import_event.createEvent)(eventParams),
+    isNodeError: true,
+    errorType: (0, import_retry_utils.errorName)(error),
+    errorCode: (_a = eventParams.errorCode) != null ? _a : errorCodeOf(error),
+    errorMessage: (_b = eventParams.errorMessage) != null ? _b : errorMessageOf(error),
+    attemptCount: attemptCount != null ? attemptCount : 1
+  };
+}
+__name(createNodeErrorEvent, "createNodeErrorEvent");
+function errorCodeOf(error) {
+  const code = error == null ? void 0 : error.code;
+  if (typeof code === "string" || typeof code === "number") {
+    return String(code);
+  }
+  return "UNKNOWN_ERROR";
+}
+__name(errorCodeOf, "errorCodeOf");
+function errorMessageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+__name(errorMessageOf, "errorMessageOf");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  claimNodeErrorReport,
+  createNodeErrorEvent,
+  isNodeErrorEvent
+});