@google/adk 1.5.0 → 2.0.0

package/dist/esm/workflow/utils/graph_validation.js

@@ -0,0 +1,189 @@
+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 { START } from "../base_node.js";
+import { DEFAULT_ROUTE } from "../graph.js";
+function validateDuplicateNodeNames(nodes) {
+  var _a;
+  const counts = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    counts.set(node.name, ((_a = counts.get(node.name)) != null ? _a : 0) + 1);
+  }
+  const duplicates = [...counts.entries()].filter(([, c]) => c > 1).map(([name]) => name).sort();
+  if (duplicates.length > 0) {
+    throw new Error(
+      `Graph validation failed. Duplicate node names found: ${JSON.stringify(
+        duplicates
+      )}. Pass the exact same object instance to reuse a node, or give distinct nodes unique names.`
+    );
+  }
+  return new Set(counts.keys());
+}
+__name(validateDuplicateNodeNames, "validateDuplicateNodeNames");
+function validateStartNode(nodeNames) {
+  if (!nodeNames.has(START.name)) {
+    throw new Error(
+      `Graph validation failed. START node (name: '${START.name}') not found in graph nodes.`
+    );
+  }
+}
+__name(validateStartNode, "validateStartNode");
+function validateStartEdges(edges) {
+  for (const edge of edges) {
+    if (edge.fromNode.name === START.name && edge.route !== null) {
+      throw new Error(
+        `Graph validation failed. Edges from START must not have routes (edge to ${edge.toNode.name} has route ${String(
+          edge.route
+        )}).`
+      );
+    }
+  }
+}
+__name(validateStartEdges, "validateStartEdges");
+function validateConnectivity(edges, nodeNames) {
+  var _a;
+  const adj = /* @__PURE__ */ new Map();
+  for (const name of nodeNames) {
+    adj.set(name, /* @__PURE__ */ new Set());
+  }
+  const toNodes = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    adj.get(edge.fromNode.name).add(edge.toNode.name);
+    toNodes.add(edge.toNode.name);
+  }
+  const reachable = /* @__PURE__ */ new Set();
+  const stack = [START.name];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (reachable.has(node)) {
+      continue;
+    }
+    reachable.add(node);
+    for (const next of (_a = adj.get(node)) != null ? _a : []) {
+      if (!reachable.has(next)) {
+        stack.push(next);
+      }
+    }
+  }
+  const unreachable = [...nodeNames].filter((n) => !reachable.has(n)).sort();
+  if (unreachable.length > 0) {
+    throw new Error(
+      `Graph validation failed. The following nodes are unreachable from START: ${JSON.stringify(
+        unreachable
+      )}`
+    );
+  }
+  if (toNodes.has(START.name)) {
+    throw new Error(
+      "Graph validation failed. START node must not have incoming edges."
+    );
+  }
+}
+__name(validateConnectivity, "validateConnectivity");
+function validateDuplicateEdges(edges) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    const unconditional = edge.route === null || edge.route === void 0;
+    const routes = unconditional ? [null] : (Array.isArray(edge.route) ? edge.route : [edge.route]).map(String);
+    for (const route of routes) {
+      const key = JSON.stringify([edge.fromNode.name, edge.toNode.name, route]);
+      if (seen.has(key)) {
+        throw new Error(
+          `Graph validation failed. Duplicate edge found: from=${edge.fromNode.name}, to=${edge.toNode.name}${unconditional ? "" : `, route=${JSON.stringify(route)}`}. ${unconditional ? "The same pair is already connected unconditionally" : "That route already points at this node"}, so the target would be triggered twice.`
+        );
+      }
+      seen.add(key);
+    }
+  }
+}
+__name(validateDuplicateEdges, "validateDuplicateEdges");
+function validateDefaultRoutes(edges) {
+  const defaultRouteEdges = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (Array.isArray(edge.route) && edge.route.includes(DEFAULT_ROUTE)) {
+      throw new Error(
+        `Graph validation failed. DEFAULT_ROUTE cannot be combined with other routes in a list (edge from=${edge.fromNode.name}, to=${edge.toNode.name}). Use a separate edge for DEFAULT_ROUTE.`
+      );
+    }
+    if (edge.route === DEFAULT_ROUTE) {
+      const from = edge.fromNode.name;
+      if (defaultRouteEdges.has(from)) {
+        throw new Error(
+          `Graph validation failed. Multiple DEFAULT_ROUTE edges found from node ${from} to ${defaultRouteEdges.get(
+            from
+          )} and ${edge.toNode.name}`
+        );
+      }
+      defaultRouteEdges.set(from, edge.toNode.name);
+    }
+  }
+}
+__name(validateDefaultRoutes, "validateDefaultRoutes");
+function detectUnconditionalCycles(edges, nodeNames) {
+  const adj = /* @__PURE__ */ new Map();
+  for (const name of nodeNames) {
+    adj.set(name, []);
+  }
+  for (const edge of edges) {
+    if (edge.route === null) {
+      adj.get(edge.fromNode.name).push(edge.toNode.name);
+    }
+  }
+  const inStack = /* @__PURE__ */ new Set();
+  const done = /* @__PURE__ */ new Set();
+  const dfs = /* @__PURE__ */ __name((node, path) => {
+    var _a;
+    inStack.add(node);
+    path.push(node);
+    for (const neighbor of (_a = adj.get(node)) != null ? _a : []) {
+      if (inStack.has(neighbor)) {
+        const cycleStart = path.indexOf(neighbor);
+        const cycle = [...path.slice(cycleStart), neighbor];
+        throw new Error(
+          `Graph validation failed. Unconditional cycle detected: ${cycle.join(
+            " -> "
+          )}. An unconditional cycle has no exit and would loop forever; break it with at least one conditional (routed) edge so a node can leave the cycle by not emitting that route. (A routed cycle can still loop if a node keeps emitting the route \u2014 bounding that is the node's responsibility, not this validator's.)`
+        );
+      }
+      if (!done.has(neighbor)) {
+        dfs(neighbor, path);
+      }
+    }
+    path.pop();
+    inStack.delete(node);
+    done.add(node);
+  }, "dfs");
+  for (const name of nodeNames) {
+    if (!done.has(name)) {
+      dfs(name, []);
+    }
+  }
+}
+__name(detectUnconditionalCycles, "detectUnconditionalCycles");
+function computeTerminalNodes(nodes, edges) {
+  const fromNames = new Set(edges.map((e) => e.fromNode.name));
+  return new Set(
+    nodes.filter((n) => n.name !== START.name && !fromNames.has(n.name)).map((n) => n.name)
+  );
+}
+__name(computeTerminalNodes, "computeTerminalNodes");
+function validateGraph(nodes, edges) {
+  const nodeNames = validateDuplicateNodeNames(nodes);
+  validateStartNode(nodeNames);
+  validateStartEdges(edges);
+  validateConnectivity(edges, nodeNames);
+  validateDuplicateEdges(edges);
+  validateDefaultRoutes(edges);
+  detectUnconditionalCycles(edges, nodeNames);
+  return computeTerminalNodes(nodes, edges);
+}
+__name(validateGraph, "validateGraph");
+export {
+  validateGraph
+};

package/dist/esm/workflow/utils/hitl_utils.js

@@ -0,0 +1,222 @@
+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 {
+  REQUEST_CREDENTIAL_FUNCTION_CALL_NAME,
+  REQUEST_INPUT_FUNCTION_CALL_NAME
+} from "../../agents/functions.js";
+import {
+  AuthCredentialTypes
+} from "../../auth/auth_credential.js";
+import { AuthHandler } from "../../auth/auth_handler.js";
+import { bindCredentialResponse } from "../../auth/credential_response_binding.js";
+import { createEvent } from "../../events/event.js";
+import { logger } from "../../utils/logger.js";
+import { compileJsonSchema, toJsonSchema } from "../../utils/schema.js";
+import {
+  REQUEST_CREDENTIAL_FUNCTION_CALL_NAME as REQUEST_CREDENTIAL_FUNCTION_CALL_NAME2,
+  REQUEST_INPUT_FUNCTION_CALL_NAME as REQUEST_INPUT_FUNCTION_CALL_NAME2
+} from "../../agents/functions.js";
+const RESPONSE_SCHEMA_ARG = "response_schema";
+function createRequestInputEvent(requestInput) {
+  var _a, _b;
+  const args = {
+    interruptId: requestInput.interruptId,
+    payload: (_a = requestInput.payload) != null ? _a : null,
+    message: (_b = requestInput.message) != null ? _b : null,
+    [RESPONSE_SCHEMA_ARG]: requestInput.responseSchema ? toJsonSchema(requestInput.responseSchema) : null
+  };
+  return createEvent({
+    content: {
+      role: "model",
+      parts: [
+        {
+          functionCall: {
+            name: REQUEST_INPUT_FUNCTION_CALL_NAME,
+            args,
+            id: requestInput.interruptId
+          }
+        }
+      ]
+    },
+    longRunningToolIds: [requestInput.interruptId]
+  });
+}
+__name(createRequestInputEvent, "createRequestInputEvent");
+function responseSchemasByInterruptId(events) {
+  var _a, _b, _c;
+  const schemas = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    for (const part of (_b = (_a = event.content) == null ? void 0 : _a.parts) != null ? _b : []) {
+      const fc = part.functionCall;
+      if ((fc == null ? void 0 : fc.name) !== REQUEST_INPUT_FUNCTION_CALL_NAME || !fc.id) {
+        continue;
+      }
+      const schema = (_c = fc.args) == null ? void 0 : _c[RESPONSE_SCHEMA_ARG];
+      if (schema) {
+        schemas.set(fc.id, schema);
+      }
+    }
+  }
+  return schemas;
+}
+__name(responseSchemasByInterruptId, "responseSchemasByInterruptId");
+function interruptResponseMismatch(interruptId, value, jsonSchema) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  const validator = compileJsonSchema(jsonSchema);
+  if (!validator) {
+    return void 0;
+  }
+  const result = validator.safeParse(value);
+  if (result.success) {
+    return void 0;
+  }
+  const issues = result.error.issues.map((issue) => {
+    const at = issue.path.length ? ` at '${issue.path.join(".")}'` : "";
+    return `${issue.message}${at}`;
+  }).join("; ");
+  return `The reply to interrupt '${interruptId}' does not match the responseSchema it declared: ${issues}. A structured reply must either match that schema, or wrap a bare value as {result: <value>}; a plain-text reply is accepted as-is and is not checked. The interrupt is still waiting, so you can answer it again.`;
+}
+__name(interruptResponseMismatch, "interruptResponseMismatch");
+function hasRequestInputFunctionCall(event) {
+  var _a, _b;
+  return ((_b = (_a = event.content) == null ? void 0 : _a.parts) != null ? _b : []).some(
+    (p) => {
+      var _a2;
+      return ((_a2 = p.functionCall) == null ? void 0 : _a2.name) === REQUEST_INPUT_FUNCTION_CALL_NAME;
+    }
+  );
+}
+__name(hasRequestInputFunctionCall, "hasRequestInputFunctionCall");
+function hasAuthRequestFunctionCall(event) {
+  var _a, _b;
+  return ((_b = (_a = event.content) == null ? void 0 : _a.parts) != null ? _b : []).some(
+    (p) => {
+      var _a2;
+      return ((_a2 = p.functionCall) == null ? void 0 : _a2.name) === REQUEST_CREDENTIAL_FUNCTION_CALL_NAME;
+    }
+  );
+}
+__name(hasAuthRequestFunctionCall, "hasAuthRequestFunctionCall");
+function getRequestInputInterruptIds(event) {
+  var _a, _b;
+  const ids = [];
+  for (const part of (_b = (_a = event.content) == null ? void 0 : _a.parts) != null ? _b : []) {
+    const fc = part.functionCall;
+    if (fc && fc.name === REQUEST_INPUT_FUNCTION_CALL_NAME && fc.id) {
+      ids.push(fc.id);
+    }
+  }
+  return ids;
+}
+__name(getRequestInputInterruptIds, "getRequestInputInterruptIds");
+function createRequestInputResponse(interruptId, response) {
+  return {
+    functionResponse: {
+      id: interruptId,
+      name: REQUEST_INPUT_FUNCTION_CALL_NAME,
+      response
+    }
+  };
+}
+__name(createRequestInputResponse, "createRequestInputResponse");
+function hasAuthCredential(authConfig, state) {
+  return new AuthHandler(authConfig).getAuthResponse(state) !== void 0;
+}
+__name(hasAuthCredential, "hasAuthCredential");
+function createAuthRequestEvent(authConfig, interruptId) {
+  const authRequest = new AuthHandler(authConfig).generateAuthRequest();
+  const args = {
+    functionCallId: interruptId,
+    authConfig: authRequest,
+    message: buildAuthMessage(authConfig)
+  };
+  return createEvent({
+    content: {
+      role: "model",
+      parts: [
+        {
+          functionCall: {
+            name: REQUEST_CREDENTIAL_FUNCTION_CALL_NAME,
+            id: interruptId,
+            args
+          }
+        }
+      ]
+    },
+    longRunningToolIds: [interruptId]
+  });
+}
+__name(createAuthRequestEvent, "createAuthRequestEvent");
+async function processAuthResume({
+  responseData,
+  authConfig,
+  state
+}) {
+  let responseConfig;
+  if (isAuthConfigLike(responseData)) {
+    responseConfig = bindCredentialResponse(authConfig, responseData);
+  } else {
+    responseConfig = {
+      ...authConfig,
+      exchangedAuthCredential: buildCredentialFromValue(
+        authConfig,
+        responseData
+      )
+    };
+  }
+  if (!responseConfig) {
+    logger.warn(
+      `Ignoring auth resume response for '${authConfig.credentialKey}': it carries no credential for the request that was raised.`
+    );
+    return;
+  }
+  await new AuthHandler(responseConfig).parseAndStoreAuthResponse(state);
+}
+__name(processAuthResume, "processAuthResume");
+function isAuthConfigLike(value) {
+  return typeof value === "object" && value !== null && "authScheme" in value && "credentialKey" in value;
+}
+__name(isAuthConfigLike, "isAuthConfigLike");
+function buildCredentialFromValue(authConfig, value) {
+  var _a;
+  if (((_a = authConfig.rawAuthCredential) == null ? void 0 : _a.authType) === AuthCredentialTypes.API_KEY) {
+    return { authType: AuthCredentialTypes.API_KEY, apiKey: String(value) };
+  }
+  return value;
+}
+__name(buildCredentialFromValue, "buildCredentialFromValue");
+function buildAuthMessage(authConfig) {
+  var _a;
+  const authType = (_a = authConfig.rawAuthCredential) == null ? void 0 : _a.authType;
+  if (authType === AuthCredentialTypes.API_KEY) {
+    return "Please provide your API key.";
+  }
+  if (authType === AuthCredentialTypes.OAUTH2 || authType === AuthCredentialTypes.OPEN_ID_CONNECT) {
+    return "Please complete the authentication flow.";
+  }
+  return "Please provide your authentication credentials.";
+}
+__name(buildAuthMessage, "buildAuthMessage");
+export {
+  REQUEST_CREDENTIAL_FUNCTION_CALL_NAME2 as REQUEST_CREDENTIAL_FUNCTION_CALL_NAME,
+  REQUEST_INPUT_FUNCTION_CALL_NAME2 as REQUEST_INPUT_FUNCTION_CALL_NAME,
+  createAuthRequestEvent,
+  createRequestInputEvent,
+  createRequestInputResponse,
+  getRequestInputInterruptIds,
+  hasAuthCredential,
+  hasAuthRequestFunctionCall,
+  hasRequestInputFunctionCall,
+  interruptResponseMismatch,
+  processAuthResume,
+  responseSchemasByInterruptId
+};