melchizedek-agents 0.19.0 → 0.20.0

package/dist/lib/runtime/valueDepth.js

@@ -0,0 +1,41 @@
+/**
+ * lib/runtime/valueDepth.ts — how deeply a JSON value nests, read without
+ * recursion (WS5-5, ADR 0101).
+ *
+ * WHY this file exists:
+ *   A tool call's arguments come from a model, and a tool's result can come
+ *   from a remote server (an MCP tool, a fetched API). Both are stored in the
+ *   session and read again on every later step: cloned for the history,
+ *   serialized for a durable store and a span. Those readers recurse, so a
+ *   value nested a few thousand levels deep overflows the stack in each of
+ *   them, on this turn and on every turn after it: the session stops
+ *   working. No tool schema the engine knows nests anywhere near
+ *   MAX_VALUE_DEPTH, so a value past it is malformed, and the runtime keeps
+ *   a short note in its place (lib/models/genaiMapping.ts contractOutputPart for
+ *   arguments, lib/runtime/native/agentLoop.ts for results).
+ *
+ *   The check itself walks with an explicit stack, so the value it guards
+ *   against cannot overflow it.
+ */
+/** The deepest a tool call's arguments or a tool's result may nest, in levels of objects and arrays (the value itself is level 1). */
+export const MAX_VALUE_DEPTH = 64;
+/** True when `value` nests objects or arrays more than `max` levels deep. Iterative; a value seen twice (a cycle) is walked once. */
+export function nestedDeeperThan(value, max = MAX_VALUE_DEPTH) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const stack = [{ node: value, level: 1 }];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const { node, level } = stack.pop();
+        if (level > max)
+            return true;
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        for (const child of Object.values(node)) {
+            if (typeof child === 'object' && child !== null)
+                stack.push({ node: child, level: level + 1 });
+        }
+    }
+    return false;
+}

package/dist/lib/session/supabaseSessionService.d.ts

@@ -25,7 +25,7 @@
  *   - lastUpdateTime is the appended event's timestamp, which is the clock
  *     of the process that made the event, just before the append.
  */
-import { BaseSessionService } from '@google/adk';
+import { BaseSessionService } from '../adkPeer.ts';
 import type { CreateSessionRequest as AdkCreateSessionRequest, DeleteSessionRequest as AdkDeleteSessionRequest, Event as AdkEvent, GetSessionRequest as AdkGetSessionRequest, ListSessionsRequest as AdkListSessionsRequest, ListSessionsResponse as AdkListSessionsResponse, Session as AdkSession } from '@google/adk';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { TurnEvent } from '../runtime/events.ts';

package/dist/lib/session/supabaseSessionService.js

@@ -25,7 +25,7 @@
  *   - lastUpdateTime is the appended event's timestamp, which is the clock
  *     of the process that made the event, just before the append.
  */
-import { BaseSessionService } from '@google/adk';
+import { BaseSessionService } from '../adkPeer.js';
 import { randomUUID } from 'crypto';
 import { applyEvent, listPage, listWindow, selectEvents, withoutTempKeys } from '../runtime/sessions.js';
 import { trimEventForStorage } from './transcript.js';

package/dist/lib/session/transcript.d.ts

@@ -40,7 +40,7 @@
  * adapter keeps every event verbatim. Both keep the text whole, which is all
  * long-term memory ingestion reads.
  */
-import { BaseSessionService } from '@google/adk';
+import { BaseSessionService } from '../adkPeer.ts';
 import type { CreateSessionRequest, GetSessionRequest, ListSessionsRequest, ListSessionsResponse, DeleteSessionRequest, Session, Event } from '@google/adk';
 import type { TurnEvent } from '../runtime/events.ts';
 import type { CreateSessionRequest as EngineCreateSessionRequest, GetSessionOptions, ListSessionsRequest as EngineListSessionsRequest, ListSessionsResult, Session as EngineSession, SessionKey, SessionService } from '../runtime/sessions.ts';

package/dist/lib/session/transcript.js

@@ -40,8 +40,8 @@
  * adapter keeps every event verbatim. Both keep the text whole, which is all
  * long-term memory ingestion reads.
  */
-import { BaseSessionService } from '@google/adk';
-import { AdkSessionServiceForEngine, asAdkSessionService, isAdkSessionService, isSessionService } from '../runtime/adkSessionBridge.js';
+import { BaseSessionService } from '../adkPeer.js';
+import { asAdkSessionService, asSessionService, isAdkSessionService, isSessionService } from '../runtime/adkSessionBridge.js';
 import { applyEvent } from '../runtime/sessions.js';
 const DEFAULT_MAX_HISTORY_CHARS = 40_000;
 const DEFAULT_MAX_HISTORY_TURNS = 16;
@@ -313,7 +313,9 @@ export class ProjectedSessionService extends BaseSessionService {
         // always was, so the ADK face reaches the same object it did.
         const engineOnly = isSessionService(inner) && !isAdkSessionService(inner);
         this.inner = engineOnly ? asAdkSessionService(inner) : inner;
-        this.own = isSessionService(inner) ? inner : new AdkSessionServiceForEngine(inner);
+        // A bridge is unwrapped to the store it wraps, so the engine face of an
+        // engine store never goes through ADK's base service (ADR 0102).
+        this.own = asSessionService(inner);
         this.forAgent = forAgent;
         this.options = options;
     }

package/dist/lib/storage/postgres/sessionService.d.ts

@@ -32,7 +32,7 @@
  * '<appName>:<userId>:<sessionId>'), so erase and the session prune cover
  * both. Tables: db/migrations/0001_base.sql and 0003_postgres_storage.sql.
  */
-import { BaseSessionService } from '@google/adk';
+import { BaseSessionService } from '../../adkPeer.ts';
 import type { CreateSessionRequest as AdkCreateSessionRequest, DeleteSessionRequest as AdkDeleteSessionRequest, Event as AdkEvent, GetSessionRequest as AdkGetSessionRequest, ListSessionsRequest as AdkListSessionsRequest, ListSessionsResponse as AdkListSessionsResponse, Session as AdkSession } from '@google/adk';
 import type { Pool } from 'pg';
 import type { TurnEvent } from '../../runtime/events.ts';

package/dist/lib/storage/postgres/sessionService.js

@@ -33,7 +33,7 @@
  * both. Tables: db/migrations/0001_base.sql and 0003_postgres_storage.sql.
  */
 import { randomUUID } from 'node:crypto';
-import { BaseSessionService } from '@google/adk';
+import { BaseSessionService } from '../../adkPeer.js';
 import { applyEvent, listPage, listWindow, withoutTempKeys } from '../../runtime/sessions.js';
 function dbId(appName, userId, sessionId) {
     return `${appName}:${userId}:${sessionId}`;

package/dist/lib/syndicateSchema.d.ts

@@ -440,6 +440,8 @@ export declare const syndicateSchema: z.ZodObject<{
                 initial_delay: z.ZodOptional<z.ZodNumber>;
                 max_delay: z.ZodOptional<z.ZodNumber>;
                 backoff_factor: z.ZodOptional<z.ZodNumber>;
+                jitter: z.ZodOptional<z.ZodNumber>;
+                exceptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
             timeout: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>>;

package/dist/lib/syndicateSchema.js

@@ -296,12 +296,20 @@ const edgeElement = z.union([
         .record(z.string().min(1), edgeTargets)
         .describe('A routing map after a node: `{ <route>: <node or nodes>, default: <node> }`, matched against that node\'s output.'),
 ]);
+/** An error class name, as ADK matches `exceptions` against one: an identifier. */
+const ERROR_NAME = /^[A-Za-z_$][\w$]*$/;
 const retrySchema = z
     .strictObject({
     max_attempts: z.number().int().positive().optional().describe('Attempts including the first; 1 = no retry. ADK default 5.'),
     initial_delay: z.number().nonnegative().optional().describe('Seconds before the first retry.'),
     max_delay: z.number().nonnegative().optional(),
     backoff_factor: z.number().positive().optional(),
+    jitter: z.number().nonnegative().optional().describe('Randomness of the backoff; 0 = none. ADK default 1.'),
+    exceptions: z
+        .array(z.string().regex(ERROR_NAME, 'an error name, such as TypeError or NodeTimeoutError'))
+        .min(1)
+        .optional()
+        .describe('Error names to retry on (the error\'s class or its `name`); every error when absent.'),
 })
     .describe('Retry a node on failure (lib/workflow.ts).');
 const workflowNodeSchema = z
@@ -313,8 +321,8 @@ const workflowNodeSchema = z
     max_parallel: z.number().int().positive().optional().describe('Concurrency of map. Default 8.'),
     tool: z.string().min(1).optional().describe('Run this registry tool with the node input as its arguments.'),
     route_key: z.string().min(1).optional().describe('Property of a JSON output holding the route. Default "route".'),
-    retry: retrySchema.optional(),
-    timeout: z.number().positive().optional().describe('Seconds this node may run before it fails.'),
+    retry: retrySchema.optional().describe('Retry this node on failure. Not on a map node: each item runs under its agent\'s own retry.'),
+    timeout: z.number().positive().optional().describe('Seconds this node may run before it fails. Not on a map node: each item runs under its agent\'s own timeout.'),
 })
     .describe('A declared node (exactly one of ask_user, join, map, tool) or modifiers for an agent node (retry, timeout, route_key).');
 const workflowSchema = z
@@ -663,11 +671,14 @@ function crossFieldProblems(raw) {
         questionProblems(raw.orchestrator, ['orchestrator'], true);
     }
     const dispatching = isObj(raw.dispatch);
+    // A workflow's subagents are its nodes, not delegated tools: a gated call pauses its node, and
+    // the walk resumes it (ADR 0098). Skill scripts stay refused inside a workflow (workflowProblems).
+    const pausing = dispatching || isObj(raw.workflow);
     subs.forEach((sub, i) => {
         if (!isObj(sub))
             return;
-        gateProblems(sub, ['subagents', i], dispatching);
-        skillProblems(sub, ['subagents', i], dispatching);
+        gateProblems(sub, ['subagents', i], pausing);
+        skillProblems(sub, ['subagents', i], pausing);
         questionProblems(sub, ['subagents', i], dispatching);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';
@@ -783,6 +794,15 @@ function workflowProblems(raw, subs) {
         if (kind !== 'map' && entry.max_parallel !== undefined) {
             out.push({ path: ['workflow', 'nodes', name, 'max_parallel'], message: 'max_parallel applies to map only' });
         }
+        // A map item runs under its agent's own modifiers, as on ADK (ADR 0089, ADR 0103): the map entry's would be applied by neither runtime.
+        if (kind === 'map') {
+            for (const key of ['retry', 'timeout']) {
+                if (entry[key] === undefined)
+                    continue;
+                const target = entry.map;
+                out.push({ path: ['workflow', 'nodes', name, key], message: `${key} on a map node is not applied: each item runs under its agent's own ${key}; set it on nodes.${target}` });
+            }
+        }
     }
     for (const name of agentNames) {
         if (name.endsWith(ROUTE_STEP_SUFFIX))
@@ -854,8 +874,9 @@ function workflowProblems(raw, subs) {
     for (const [path, agent] of agents) {
         if (!isObj(agent))
             continue;
-        if (Array.isArray(agent.require_approval) && agent.require_approval.length) {
-            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported inside a workflow yet' });
+        // A map item cannot pause: the walk resumes a paused agent node, not an item of a map (ADR 0094, ADR 0098).
+        if (typeof agent.name === 'string' && mapped.has(agent.name) && Array.isArray(agent.require_approval) && agent.require_approval.length) {
+            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported on an agent a map node runs: a map item cannot pause the walk' });
         }
         if (isObj(agent.skills) && agent.skills.scripts === 'local') {
             out.push({ path: [...path, 'skills', 'scripts'], message: 'skill scripts (an approval pause) are not supported inside a workflow yet' });

package/dist/lib/toolRegistry.d.ts

@@ -22,6 +22,15 @@
  * callers can log in their own format.
  */
 export declare function resolveTools(toolNames?: string[], onUnknown?: (name: string) => void): any[];
+/**
+ * Names the framework itself declares, calls or reads on the wire: the
+ * approval, credential and input interrupts, the reflection tool, delegation,
+ * structured output and task mode. A consumer's tool under one of them would
+ * be mistaken for the framework's own (a forged approval request, a fake
+ * transfer), so registerTool refuses them. `ask_user` is the framework's
+ * question tool; only that tool may be registered under it.
+ */
+export declare const RESERVED_TOOL_NAMES: readonly string[];
 /**
  * Make a tool resolvable by name from a syndicate YAML's `tools:` list.
  *
@@ -34,7 +43,9 @@ export declare function resolveTools(toolNames?: string[], onUnknown?: (name: st
  * a ready ADK tool. A contract or Tool reaches the ADK runtime through
  * toFunctionTool, an InstructionTool through toAdkInstructionTool, a
  * NativeToolMarker as its sentinel (toAdkTool, lib/tools/adkTool.ts).
- * Replacing a built-in requires `{ override: true }`.
+ * Replacing a built-in requires `{ override: true }`. A reserved framework
+ * name (RESERVED_TOOL_NAMES), as the registry name or the tool's own, is
+ * refused whatever the options say.
  */
 export declare function registerTool(name: string, tool: unknown, options?: {
     override?: boolean;

package/dist/lib/toolRegistry.js

@@ -21,7 +21,7 @@ import { inspectImageTool } from './tools/inspectImageTool.js';
 import { toAdkInstructionTool, toAdkTool, toFunctionTool } from './tools/adkTool.js';
 import { loadMemoryTool, preloadMemoryTool } from './tools/memoryTools.js';
 import { COLLECTIONS_SEARCH_MARKER, GOOGLE_SEARCH_MARKER, URL_CONTEXT_MARKER, WEB_SEARCH_MARKER, X_SEARCH_MARKER, } from './tools/nativeTools.js';
-import { isInstructionTool, isNativeToolMarker, isTool } from './tools/tool.js';
+import { isInstructionTool, isNativeToolMarker, isTool, toolOf } from './tools/tool.js';
 import { webExtractTool } from './tools/webExtractTool.js';
 import { WIKI_AGENT_TOOL_CONTRACTS } from './tools/wikiTools.js';
 import { SCIENCE_TOOL_CONTRACTS } from './tools/scienceTools.js';
@@ -104,6 +104,40 @@ export function resolveTools(toolNames = [], onUnknown) {
     })
         .filter(Boolean);
 }
+/**
+ * Names the framework itself declares, calls or reads on the wire: the
+ * approval, credential and input interrupts, the reflection tool, delegation,
+ * structured output and task mode. A consumer's tool under one of them would
+ * be mistaken for the framework's own (a forged approval request, a fake
+ * transfer), so registerTool refuses them. `ask_user` is the framework's
+ * question tool; only that tool may be registered under it.
+ */
+export const RESERVED_TOOL_NAMES = [
+    'adk_request_confirmation',
+    'adk_request_credential',
+    'adk_request_input',
+    'ask_user',
+    'adk_handle_model_error',
+    'transfer_to_agent',
+    'set_model_response',
+    'finish_task',
+];
+/** Whether `tool` is the framework's own ask_user (the own Tool, or the registry's wrapper of it). */
+function isFrameworkAskUser(tool) {
+    return tool === askUserTool || tool === TOOL_MAP.ask_user || (!!tool && typeof tool === 'object' && toolOf(tool) === askUserTool);
+}
+/** The reserved name `name` or `tool` would take, if any. */
+function reservedNameOf(name, tool) {
+    const own = tool && typeof tool === 'object' ? tool.name : undefined;
+    for (const candidate of [name, typeof own === 'string' ? own : undefined]) {
+        if (!candidate || !RESERVED_TOOL_NAMES.includes(candidate))
+            continue;
+        if (candidate === 'ask_user' && isFrameworkAskUser(tool))
+            continue;
+        return candidate;
+    }
+    return undefined;
+}
 /**
  * Make a tool resolvable by name from a syndicate YAML's `tools:` list.
  *
@@ -116,12 +150,18 @@ export function resolveTools(toolNames = [], onUnknown) {
  * a ready ADK tool. A contract or Tool reaches the ADK runtime through
  * toFunctionTool, an InstructionTool through toAdkInstructionTool, a
  * NativeToolMarker as its sentinel (toAdkTool, lib/tools/adkTool.ts).
- * Replacing a built-in requires `{ override: true }`.
+ * Replacing a built-in requires `{ override: true }`. A reserved framework
+ * name (RESERVED_TOOL_NAMES), as the registry name or the tool's own, is
+ * refused whatever the options say.
  */
 export function registerTool(name, tool, options = {}) {
     if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(name)) {
         throw new Error(`registerTool: '${name}' is not a valid tool name`);
     }
+    const reserved = reservedNameOf(name, tool);
+    if (reserved) {
+        throw new Error(`registerTool: '${reserved}' is reserved by the framework (${RESERVED_TOOL_NAMES.join(', ')}); register the tool under another name`);
+    }
     if (Object.prototype.hasOwnProperty.call(TOOL_MAP, name) && !options.override) {
         throw new Error(`registerTool: '${name}' is already registered (pass { override: true } to replace it)`);
     }

package/dist/lib/tools/adkTool.d.ts

@@ -38,7 +38,7 @@
  *
  *   toAdkTool takes any of these and picks the wrapper.
  */
-import { BaseTool, BaseToolset, FunctionTool } from '@google/adk';
+import { BaseTool, BaseToolset, FunctionTool } from '../adkPeer.ts';
 import type { InstructionTool, NativeToolMarker, Tool, ToolContext, Toolset } from './tool.ts';
 import type { ToolContract } from './toolContract.ts';
 /** The ToolContext for one ADK call; a standalone one outside a run. */

package/dist/lib/tools/adkTool.js

@@ -38,7 +38,7 @@
  *
  *   toAdkTool takes any of these and picks the wrapper.
  */
-import { BaseTool, BaseToolset, FunctionTool, GOOGLE_SEARCH } from '@google/adk';
+import { BaseTool, BaseToolset, FunctionTool, GOOGLE_SEARCH } from '../adkPeer.js';
 import { currentTurnSignal } from '../runtime/turnControl.js';
 import { COLLECTIONS_SEARCH } from './collectionsSearchTool.js';
 import { OWN_TOOL, createToolContext, isInstructionTool, isNativeToolMarker, isOwnToolset, nativeToolMarkerOf } from './tool.js';

package/dist/lib/tools/collectionsSearchTool.d.ts

@@ -30,7 +30,7 @@
  *   silent no-op everywhere else (same non-throwing routing contract as
  *   web_search / x_search).
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.ts';
 import type { LlmRequest } from '@google/adk';
 import { NATIVE_TOOL } from './tool.ts';
 export declare const COLLECTIONS_SEARCH_TOOL_NAME = "collections_search";

package/dist/lib/tools/collectionsSearchTool.js

@@ -30,7 +30,7 @@
  *   silent no-op everywhere else (same non-throwing routing contract as
  *   web_search / x_search).
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.js';
 import { providerForModel } from '../models/providerMap.js';
 import { COLLECTIONS_SEARCH_MARKER } from './nativeTools.js';
 import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';

package/dist/lib/tools/generateImageTool.d.ts

@@ -22,4 +22,4 @@ export declare const generateImageContract: import("./toolContract.ts").DefinedT
     color_palette: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, string>;
 /** ADK surface, ready for the registry. */
-export declare const generateImageTool: import("@google/adk").FunctionTool<undefined>;
+export declare const generateImageTool: import("../adkPeer.ts").FunctionTool;

package/dist/lib/tools/inspectImageTool.d.ts

@@ -21,4 +21,4 @@ export declare const inspectImageContract: import("./toolContract.ts").DefinedTo
     image_path: z.ZodString;
 }, z.core.$strip>, string>;
 /** ADK surface, ready for the registry. */
-export declare const inspectImageTool: import("@google/adk").FunctionTool<undefined>;
+export declare const inspectImageTool: import("../adkPeer.ts").FunctionTool;

package/dist/lib/tools/urlContextTool.d.ts

@@ -14,7 +14,7 @@
  * deployment's network is reachable through it. Page text arrives as model
  * input; treat it as data, as any fetched page.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.ts';
 import type { LlmRequest } from '@google/adk';
 import { NATIVE_TOOL } from './tool.ts';
 export declare const URL_CONTEXT_TOOL_NAME = "url_context";

package/dist/lib/tools/urlContextTool.js

@@ -14,7 +14,7 @@
  * deployment's network is reachable through it. Page text arrives as model
  * input; treat it as data, as any fetched page.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.js';
 import { providerForModel } from '../models/providerMap.js';
 import { URL_CONTEXT_MARKER } from './nativeTools.js';
 import { NATIVE_TOOL } from './tool.js';

package/dist/lib/tools/webExtractTool.d.ts

@@ -70,4 +70,4 @@ export declare const webExtractContract: import("./toolContract.ts").DefinedTool
     offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, string>;
 /** ADK surface, ready for the registry. */
-export declare const webExtractTool: import("@google/adk").FunctionTool<undefined>;
+export declare const webExtractTool: import("../adkPeer.ts").FunctionTool;

package/dist/lib/tools/webSearchTool.d.ts

@@ -26,7 +26,7 @@
  *   `google_search` remains available as the Gemini-only ADK tool for
  *   backward compatibility; new YAMLs should declare `web_search`.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.ts';
 import type { LlmRequest } from '@google/adk';
 import { NATIVE_TOOL } from './tool.ts';
 export declare const WEB_SEARCH_TOOL_NAME = "web_search";

package/dist/lib/tools/webSearchTool.js

@@ -26,7 +26,7 @@
  *   `google_search` remains available as the Gemini-only ADK tool for
  *   backward compatibility; new YAMLs should declare `web_search`.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.js';
 import { providerForModel } from '../models/providerMap.js';
 import { WEB_SEARCH_MARKER } from './nativeTools.js';
 import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';

package/dist/lib/tools/xApiSearchTool.d.ts

@@ -191,4 +191,4 @@ export declare const xApiSearchContract: import("./toolContract.ts").DefinedTool
     read_images: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, string>;
 /** ADK surface, registered under its contract name in lib/toolRegistry.ts. */
-export declare const xApiSearchTool: import("@google/adk").FunctionTool<undefined>;
+export declare const xApiSearchTool: import("../adkPeer.ts").FunctionTool;

package/dist/lib/tools/xSearchTool.d.ts

@@ -33,7 +33,7 @@
  *   malformed dates are dropped, oversize handle lists truncate, and when
  *   both lists are set the allowlist wins.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.ts';
 import type { LlmRequest } from '@google/adk';
 import { NATIVE_TOOL } from './tool.ts';
 export declare const X_SEARCH_TOOL_NAME = "x_search";

package/dist/lib/tools/xSearchTool.js

@@ -33,7 +33,7 @@
  *   malformed dates are dropped, oversize handle lists truncate, and when
  *   both lists are set the allowlist wins.
  */
-import { BaseTool } from '@google/adk';
+import { BaseTool } from '../adkPeer.js';
 import { providerForModel } from '../models/providerMap.js';
 import { X_SEARCH_MARKER } from './nativeTools.js';
 import { NATIVE_TOOL, nativeToolMarkerOf } from './tool.js';

package/dist/lib/wiki/agentRun.d.ts

@@ -34,7 +34,7 @@ export interface WikiAgentRun {
     tools?: FunctionTool[];
     temperature?: number;
     maxOutputTokens?: number;
-    /** The runtime that runs the agent. Default: MELCHIZEDEK_RUNTIME, else adk. */
+    /** The runtime that runs the agent. Default: MELCHIZEDEK_RUNTIME, else native. */
     runtime?: RuntimeName;
     /** Native runtime only: the leaf adapter for a model id. Default resolveAdapter (lib/models/registry.ts). */
     adapterFor?: (model: string) => ModelAdapter;

package/dist/lib/wiki/agentRun.js

@@ -23,7 +23,7 @@
  *   read the same way.
  */
 import { randomUUID } from 'node:crypto';
-import { InMemorySessionService, LlmAgent, Runner } from '@google/adk';
+import { requireAdk } from '../adkPeer.js';
 import { providerForModel, providerKeyPresent, registerAvailableProviders, resolveAdapter, } from '../models/registry.js';
 import { SelfCorrection } from '../runtime/native/selfCorrection.js';
 import { runNativeAgent } from '../runtime/nativeTurn.js';
@@ -101,6 +101,7 @@ export async function runWikiAgent(run) {
             selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
         }));
     }
+    const { InMemorySessionService, LlmAgent, Runner } = requireAdk('A wiki agent on the adk runtime (MELCHIZEDEK_RUNTIME=adk)');
     registerAvailableProviders();
     const agent = new LlmAgent({
         name: run.name,

package/dist/lib/workflow/agentNode.d.ts

@@ -43,8 +43,25 @@
  *      error; a run that ends with one and no output returns it as the
  *      run's `error`, and the scheduler fails the attempt with
  *      NodeReportedError, ADK's message, retried or stopping the walk as
- *      ADK's does, and reported once (by the node's own event). A run the turn stopped throws. A run that pauses on a person
- *      (an ask_user tool, an approval) is an interrupt, not run here yet.
+ *      ADK's does, and reported once (by the node's own event). A run the turn stopped throws. A run that pauses on
+ *      an ask_user tool call is refused by name.
+ *   8. APPROVALS (ADR 0098). A run that pauses on approval requests (a tool
+ *      in the agent's `require_approval`) resolves with their ids as the
+ *      node's interrupts: the node waits and the walk ends paused, as an
+ *      ask_user node's does. The resumed walk reruns the node with
+ *      `resumedInterruptIds`: until every request has a decision among the
+ *      answers (a confirmation, never a plain-text message) it waits again
+ *      without running, its open requests raised again on one event of the
+ *      new run (`waitAgain`), so the run after still resumes them; then the
+ *      agent's run continues instead of starting afresh, unless it already
+ *      did on an earlier resume, whose stored output is then the node's
+ *      (`outputAfter`). No input turn is stored, so the person's answer stays the
+ *      latest user event, and the loop's approval resume
+ *      (lib/runtime/native/interrupts.ts, ADR 0077) runs or refuses the
+ *      pinned call before the next model step, which reads the node's turn
+ *      from its input on. ADK's runLlmAgentAsNode stores the input again and
+ *      starts the agent afresh, so the pinned call never runs there; ADK
+ *      turns refuse gates on workflow nodes instead.
  *
  * `agentNodeRuntime` puts it together for the scheduler: a `runNode` for
  * agent nodes and map items, and an `onEvent` that stores the event ADK
@@ -52,7 +69,7 @@
  * (lib/workflow/nodeEvents.ts), so a session the native walk writes holds
  * what ADK's holds, in the same order.
  *
- * NOT HERE: interrupts inside a node (an ask_user tool call, an approval),
+ * NOT HERE: an ask_user tool call inside a node, a pause inside a map item,
  * tool nodes (lib/workflow/toolNode.ts) and ask_user nodes
  * (lib/workflow/pause.ts). It imports nothing from ADK.
  */
@@ -102,7 +119,7 @@ export interface AgentNodeContext {
  * one with no output. Throws NodeStoppedError when the turn stopped it, and
  * an Error when it paused on a person.
  */
-export declare function runAgentNode(agent: NativeAgent, run: Pick<NodeRun, 'input' | 'path' | 'branch' | 'signal'>, ctx: AgentNodeContext): Promise<NodeResult>;
+export declare function runAgentNode(agent: NativeAgent, run: Pick<NodeRun, 'input' | 'path' | 'branch' | 'signal' | 'resumeInputs' | 'resumedInterruptIds'>, ctx: AgentNodeContext): Promise<NodeResult>;
 export interface AgentNodeRuntimeOptions extends Omit<AgentNodeContext, 'appendInput'> {
     /** Every agent of the syndicate, compiled for native, by YAML name. */
     agents: ReadonlyMap<string, NativeAgent>;