melchizedek-agents 0.19.0 → 0.20.0

package/dist/lib/runtime/native/selfCorrection.js

@@ -12,9 +12,14 @@
  *   read differently on the other:
  *
  *   THE MODEL (`retries.model_errors`, default 2; 0 off):
- *   - Every request declares the reflection tool, `adk_handle_model_error`,
- *     after the agent's own tools (the plugin's beforeModelCallback adds it
- *     to the toolsDict last).
+ *   - The reflection tool, `adk_handle_model_error`, is one of every step's
+ *     tools, after the agent's own: the plugin's beforeModelCallback adds it
+ *     to the request's toolsDict last, and never to its config. Whether the
+ *     model is told of it depends on the model class ADK hands the request
+ *     to (ADR 0097): the ADK shim and the engine's own ADK classes declare
+ *     the toolsDict, so the tool is declared; ADK's own Gemini sends the
+ *     config alone, so a Gemini model is never told of it. The step asks
+ *     `declaresReflectionTool` and runs the tool either way.
  *   - Each response is checked (afterModelCallback), partials included. A
  *     response that calls the reflection tool itself, or whose finish reason
  *     is MALFORMED_FUNCTION_CALL, is replaced by a call to the reflection
@@ -22,6 +27,13 @@
  *     the retry's number counted per agent in the run. The loop runs that
  *     call like any other, and the tool answers with reflection guidance.
  *     Any other response resets the agent's count.
+ *   - ON A GEMINI MODEL the stored reflection call is signed (ADR 0103), where
+ *     ADK's plugin stores it unsigned: it carries the replaced response's
+ *     thoughtSignature, or on Gemini 3 Gemini's documented placeholder when
+ *     the response had none (a MALFORMED_FUNCTION_CALL has no parts). Gemini 3
+ *     rejects the next request with an unsigned current-turn call (400,
+ *     "missing a thought_signature"); ADK's runtime still does. This is the
+ *     one place the native loop stores what ADK would not (reflectionSigning).
  *   - Past the limit the step ends on ADK's error event for a callback that
  *     threw: UNKNOWN_ERROR, and the plugin manager's message.
  *
@@ -46,6 +58,7 @@
  * reads responses as.
  */
 import { randomUUID } from 'node:crypto';
+import { GEMINI_PROVIDER, PLACEHOLDER_THOUGHT_SIGNATURE } from '../../models/geminiState.js';
 export const DEFAULT_MODEL_ERROR_RETRIES = 2;
 export const DEFAULT_TOOL_ERROR_RETRIES = 3;
 export const ADK_HANDLE_MODEL_ERROR = 'adk_handle_model_error';
@@ -54,6 +67,63 @@ const RESERVED_TOOL_CALL = 'RESERVED_TOOL_CALL';
 /** The finish reasons the model plugin retries (its onModelErrors default). */
 const MODEL_ERRORS = ['MALFORMED_FUNCTION_CALL'];
 const MODEL_PLUGIN = 'reflect_retry_model_plugin';
+// ── Where ADK declares the reflection tool ──────────────────────────────────
+/** Gemini adapters a caller handed over as a contract adapter or behind the ADK shim: on ADK the shim declares the toolsDict. */
+const SHIMMED_GEMINI = new WeakSet();
+/**
+ * Marks `adapter` as one the ADK runtime would call through the ADK shim
+ * (a resolver's shim or contract adapter, lib/compileNative.ts), not through
+ * ADK's own Gemini. Returns it.
+ */
+export function servedThroughShim(adapter) {
+    SHIMMED_GEMINI.add(adapter);
+    return adapter;
+}
+/**
+ * Whether the ADK runtime would tell this adapter's model of the reflection
+ * tool (ADR 0097). The plugin puts the tool in the toolsDict alone. Every
+ * model class the engine hands ADK declares the toolsDict, but ADK's own
+ * Gemini (and TracedGemini over it) sends only the request's config, which
+ * never holds it. A Gemini adapter stands for ADK's Gemini unless a caller
+ * handed it over behind the shim (servedThroughShim).
+ */
+export function declaresReflectionTool(adapter) {
+    return !standsForAdkGemini(adapter);
+}
+/**
+ * Whether this adapter stands, on the native runtime, for ADK's own Gemini
+ * (TracedGemini) on the ADK runtime: a Gemini adapter no caller handed over
+ * behind the shim. The step declares no reflection tool to it (ADR 0097) and
+ * stores no `turnComplete` on its events, as ADK's Gemini writes none
+ * (ADR 0100).
+ */
+export function standsForAdkGemini(adapter) {
+    return adapter.provider === GEMINI_PROVIDER && !SHIMMED_GEMINI.has(adapter);
+}
+/**
+ * How self-correction signs the reflection call it stores in place of this
+ * adapter's response, or undefined to store it unsigned, as ADK's plugin
+ * does. A Gemini adapter's call carries the replaced response's signature;
+ * on a Gemini 3 model, whose API rejects an unsigned current-turn call, the
+ * placeholder stands in when there was none.
+ */
+export function reflectionSigning(adapter, model) {
+    if (adapter.provider !== GEMINI_PROVIDER)
+        return undefined;
+    return isGemini3(model) ? { placeholder: PLACEHOLDER_THOUGHT_SIGNATURE } : {};
+}
+/** A Gemini 3 model id, bare or under a resource path (`models/…`, `publishers/google/models/…`). */
+function isGemini3(model) {
+    if (!model)
+        return false;
+    return model.slice(model.lastIndexOf('/') + 1).startsWith('gemini-3');
+}
+/** The signature the replaced response carried: its first call's, else its first signed part's. */
+function signatureOf(response) {
+    const parts = response.content?.parts ?? [];
+    const signed = (p) => typeof p.thoughtSignature === 'string' && p.thoughtSignature.length > 0;
+    return (parts.find((p) => p.functionCall && signed(p)) ?? parts.find(signed))?.thoughtSignature;
+}
 // ── Counting, per run ────────────────────────────────────────────────────────
 /** ADK's ScopedFailureTracker: failures per name, within one run (invocation scope). */
 class FailureTracker {
@@ -100,7 +170,7 @@ export class SelfCorrection {
         const max = this.modelErrors;
         const tracker = this.#models;
         const name = agentName || 'default_model';
-        const retry = (errorType, errorDetails, finishReason) => {
+        const retry = (errorType, errorDetails, finishReason, signature) => {
             const count = tracker.increment(invocationId, name);
             if (count > max) {
                 const thrown = `The model has failed consecutively ${max} times and the retry limit has been exceeded.`;
@@ -108,18 +178,22 @@ export class SelfCorrection {
             }
             const args = { response_type: REFLECT_AND_RETRY_RESPONSE_TYPE, error_type: errorType, error_details: errorDetails, finish_reason: finishReason, retry_count: count };
             const response = {
-                content: { role: 'model', parts: [{ functionCall: { id: `${ADK_HANDLE_MODEL_ERROR}_${randomUUID()}`, name: ADK_HANDLE_MODEL_ERROR, args } }] },
+                content: {
+                    role: 'model',
+                    parts: [{ functionCall: { id: `${ADK_HANDLE_MODEL_ERROR}_${randomUUID()}`, name: ADK_HANDLE_MODEL_ERROR, args }, ...(signature ? { thoughtSignature: signature } : {}) }],
+                },
             };
             return { response, replaced: true };
         };
         return {
             tools: [reflectionTool(max)],
-            afterModel(response) {
+            afterModel(response, signing) {
+                const signature = () => (signing ? (signatureOf(response) ?? signing.placeholder) : undefined);
                 if (response.content?.parts?.some((p) => p.functionCall?.name === ADK_HANDLE_MODEL_ERROR)) {
-                    return retry(RESERVED_TOOL_CALL, `Model attempted to call reserved tool ${ADK_HANDLE_MODEL_ERROR} directly. This tool is reserved for framework use only. Do not call it.`, 'OTHER');
+                    return retry(RESERVED_TOOL_CALL, `Model attempted to call reserved tool ${ADK_HANDLE_MODEL_ERROR} directly. This tool is reserved for framework use only. Do not call it.`, 'OTHER', signature());
                 }
                 if (response.finishReason && MODEL_ERRORS.includes(response.finishReason)) {
-                    return retry(response.errorCode ?? 'MODEL_ERROR', response.errorMessage ?? 'Model error encountered.', response.finishReason);
+                    return retry(response.errorCode ?? 'MODEL_ERROR', response.errorMessage ?? 'Model error encountered.', response.finishReason, signature());
                 }
                 tracker.reset(invocationId, name);
                 return { response, replaced: false };

package/dist/lib/runtime/native/step.d.ts

@@ -23,16 +23,24 @@
  *   - THE EVENT. Each response becomes ADK's event for it: created before
  *     the call with the run's id, the agent as author and the branch, and
  *     merged with the response as the shim maps it (modelResponseToLlmResponse),
- *     a fresh id for every response after the first. A tool call with no id
+ *     a fresh id for every response after the first. For a Gemini adapter
+ *     that stands for ADK's own Gemini (standsForAdkGemini), the event has no
+ *     turnComplete, since ADK's Gemini writes none (ADR 0100). A tool call with no id
  *     gets ADK's `adk-<uuid>`; a call to a long-running tool is listed in
  *     longRunningToolIds; a set_model_response call becomes its arguments as
  *     JSON text, ending the step (skipSummarization). An answer with no
  *     parts, no error and no usage makes no event.
  *   - SELF-CORRECTION (ADR 0075). With the caller's `correction`, the
- *     request declares the reflection tool after the agent's tools, and each
- *     response passes through it first, as ADK's reflect-and-retry model
- *     plugin sees it: a retry may stand in its place, or the step may end on
- *     the plugin's UNKNOWN_ERROR event (lib/runtime/native/selfCorrection.ts).
+ *     reflection tool is one of the step's tools, after the agent's, and
+ *     each response passes through it first, as ADK's reflect-and-retry
+ *     model plugin sees it: a retry may stand in its place, or the step may
+ *     end on the plugin's UNKNOWN_ERROR event (lib/runtime/native/
+ *     selfCorrection.ts). The request declares the tool only where ADK's
+ *     model class would (declaresReflectionTool): never to a Gemini model
+ *     ADK's own Gemini would serve, which sends no toolsDict (ADR 0097).
+ *     On a Gemini adapter the reflection call stored in a response's place
+ *     carries its signature, or Gemini 3's placeholder (reflectionSigning,
+ *     ADR 0103), where ADK stores it unsigned.
  *   - A THROWN FAILURE. The contract forbids an adapter to throw, but a
  *     leaf that does (an ADK-era model class) is read as ADK reads it. With
  *     a `redirect`, a provider-side failure (errorDecision, lib/models/
@@ -132,7 +140,7 @@ export interface ModelStepResult {
     stopped?: StepStop;
     /** The failure `redirect` took: nothing was stored for it. */
     redirected?: ModelError;
-    /** The client-side tools the request declared, by name: what runs the answer's calls. */
+    /** The client-side tools the request declared, and the reflection tool when it was not declared, by name: what runs the answer's calls. */
     tools: Map<string, unknown>;
 }
 export declare function eitherSignal(...candidates: Array<AbortSignal | undefined>): AbortSignal | undefined;

package/dist/lib/runtime/native/step.js

@@ -23,16 +23,24 @@
  *   - THE EVENT. Each response becomes ADK's event for it: created before
  *     the call with the run's id, the agent as author and the branch, and
  *     merged with the response as the shim maps it (modelResponseToLlmResponse),
- *     a fresh id for every response after the first. A tool call with no id
+ *     a fresh id for every response after the first. For a Gemini adapter
+ *     that stands for ADK's own Gemini (standsForAdkGemini), the event has no
+ *     turnComplete, since ADK's Gemini writes none (ADR 0100). A tool call with no id
  *     gets ADK's `adk-<uuid>`; a call to a long-running tool is listed in
  *     longRunningToolIds; a set_model_response call becomes its arguments as
  *     JSON text, ending the step (skipSummarization). An answer with no
  *     parts, no error and no usage makes no event.
  *   - SELF-CORRECTION (ADR 0075). With the caller's `correction`, the
- *     request declares the reflection tool after the agent's tools, and each
- *     response passes through it first, as ADK's reflect-and-retry model
- *     plugin sees it: a retry may stand in its place, or the step may end on
- *     the plugin's UNKNOWN_ERROR event (lib/runtime/native/selfCorrection.ts).
+ *     reflection tool is one of the step's tools, after the agent's, and
+ *     each response passes through it first, as ADK's reflect-and-retry
+ *     model plugin sees it: a retry may stand in its place, or the step may
+ *     end on the plugin's UNKNOWN_ERROR event (lib/runtime/native/
+ *     selfCorrection.ts). The request declares the tool only where ADK's
+ *     model class would (declaresReflectionTool): never to a Gemini model
+ *     ADK's own Gemini would serve, which sends no toolsDict (ADR 0097).
+ *     On a Gemini adapter the reflection call stored in a response's place
+ *     carries its signature, or Gemini 3's placeholder (reflectionSigning,
+ *     ADR 0103), where ADK stores it unsigned.
  *   - A THROWN FAILURE. The contract forbids an adapter to throw, but a
  *     leaf that does (an ADK-era model class) is read as ADK reads it. With
  *     a `redirect`, a provider-side failure (errorDecision, lib/models/
@@ -53,7 +61,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { errorDecision, errorText } from '../../models/errorResponse.js';
-import { modelResponseToLlmResponse } from '../../models/genaiMapping.js';
+import { contractModelResponse, modelResponseToLlmResponse } from '../../models/genaiMapping.js';
 import { resolveAdapter } from '../../models/registry.js';
 import { traceLlmGeneration } from '../../observability/tracer.js';
 import { createTurnEvent, getFunctionCalls, newEventId } from '../events.js';
@@ -61,6 +69,7 @@ import { currentTurnControl, currentTurnSignal, stopCode, stopMessage } from '..
 import { toolOf } from '../../tools/tool.js';
 import { ADK_CALL_ID_PREFIX } from './history.js';
 import { SET_MODEL_RESPONSE, buildModelRequest } from './request.js';
+import { declaresReflectionTool, reflectionSigning, standsForAdkGemini } from './selfCorrection.js';
 export function eitherSignal(...candidates) {
     const signals = [...new Set(candidates.filter((s) => s !== undefined))];
     return signals.length <= 1 ? signals[0] : AbortSignal.any(signals);
@@ -108,6 +117,10 @@ function thrownModelError(err) {
 export async function runModelStep(options) {
     const { agent, session, sessions } = options;
     const signal = eitherSignal(options.signal, currentTurnSignal());
+    const adapter = options.adapter ?? resolveAdapter(agent.model);
+    // ADK's plugin puts the reflection tool in the toolsDict alone: declared where the model class reads it, run either way.
+    const correctionTools = options.correction?.tools ?? [];
+    const declareCorrection = correctionTools.length > 0 && declaresReflectionTool(adapter);
     const { request, tools } = await buildModelRequest(agent, {
         session,
         invocationId: options.invocationId,
@@ -119,15 +132,17 @@ export async function runModelStep(options) {
         ...(options.stateOverlay ? { stateOverlay: options.stateOverlay } : {}),
         stream: options.stream ?? false,
         ...(signal ? { signal } : {}),
-        ...(options.correction ? { extraTools: options.correction.tools } : {}),
+        ...(declareCorrection ? { extraTools: correctionTools } : {}),
         ...(options.workflowScope ? { workflowScope: options.workflowScope } : {}),
     });
+    if (!declareCorrection)
+        for (const tool of correctionTools)
+            tools.set(tool.name, tool);
     if (options.model)
         request.model = options.model;
     const result = { request, text: '', thinking: '', toolCalls: [], longRunningToolIds: [], tools };
     if (signal?.aborted)
         return { ...result, stopped: stopOf() };
-    const adapter = options.adapter ?? resolveAdapter(agent.model);
     // The event ADK creates before the call; each response after the first gets a fresh id and time.
     const base = createTurnEvent({ invocationId: options.invocationId, author: agent.name, branch: options.branch });
     let next = { id: base.id, timestamp: base.timestamp };
@@ -135,10 +150,18 @@ export async function runModelStep(options) {
     const sources = new WeakMap();
     // What the adapter itself threw, as opposed to the store or a callback.
     let thrown;
+    // ADK's own Gemini writes no turnComplete, so its stand-in's events carry none (ADR 0100).
+    const adkGemini = standsForAdkGemini(adapter);
+    // How a reflection call stored in this adapter's place is signed (ADR 0103).
+    const signing = reflectionSigning(adapter, request.model);
     async function* inner() {
         try {
-            for await (const response of adapter.generate(request)) {
+            for await (const unchecked of adapter.generate(request)) {
+                // The answer held to the contract, as the shim's mapping holds it (contractModelResponse): the step reads and stores the same parts.
+                const response = contractModelResponse(unchecked);
                 const mapped = modelResponseToLlmResponse(response);
+                if (adkGemini)
+                    delete mapped.turnComplete;
                 sources.set(mapped, response);
                 yield mapped;
             }
@@ -186,7 +209,8 @@ export async function runModelStep(options) {
                 return { ...result, response: source, redirected: source.error };
             produced = true;
             // Self-correction sees the response as ADK's afterModelCallback does: it may stand a retry in its place, or end the step.
-            const corrected = options.correction?.afterModel(traced) ?? { response: traced, replaced: false };
+            // On Gemini the reflection call it stores is signed, so the next request does not 400 (ADR 0103).
+            const corrected = options.correction?.afterModel(traced, signing) ?? { response: traced, replaced: false };
             if ('failed' in corrected) {
                 // ADK's runAndHandleError: a callback that threw ends the step on an error event of its own.
                 const { code, message } = corrected.failed;

package/dist/lib/runtime/runtimeFlag.d.ts

@@ -2,10 +2,11 @@
  * lib/runtime/runtimeFlag.ts — which runtime runs a turn: MELCHIZEDEK_RUNTIME
  * and the turn's `runtime` option (ADR 0045, ADR 0073).
  *
- * `adk` runs each agent on Google ADK's Runner, `native` on the engine's own
- * agent loop (lib/runtime/native/agentLoop.ts). The default is `adk` until
- * the release that makes native the default (ADR 0045). A feature the native
- * runtime does not run yet fails before any model call with
+ * `native` runs each agent on the engine's own agent loop
+ * (lib/runtime/native/agentLoop.ts), `adk` on Google ADK's Runner. `native`
+ * is the default since 0.20.0 (ADR 0045, ADR 0102); `adk` needs the optional
+ * peer @google/adk installed, and leaves the package at 1.0.0. A feature the
+ * native runtime does not run yet fails before any model call with
  * UnsupportedOnRuntimeError, which names the feature and the runtime.
  *
  * A leaf module: it imports nothing, so every caller (the compiler, the
@@ -18,7 +19,7 @@ export declare const RUNTIMES: readonly RuntimeName[];
 export declare const DEFAULT_RUNTIME: RuntimeName;
 /** MELCHIZEDEK_RUNTIME as set, or undefined when unset or blank. Any other value is a configuration error. */
 export declare function runtimeSetting(env?: NodeJS.ProcessEnv): RuntimeName | undefined;
-/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else adk. */
+/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else native. */
 export declare function chooseRuntime(option?: string, env?: NodeJS.ProcessEnv): RuntimeName;
 /** A feature the chosen runtime does not run yet. Thrown before any model call. */
 export declare class UnsupportedOnRuntimeError extends Error {
@@ -28,3 +29,10 @@ export declare class UnsupportedOnRuntimeError extends Error {
 }
 /** The error for a feature the native runtime does not run yet; `where` names the agent or syndicate. */
 export declare function unsupportedOnNative(feature: string, where: string): UnsupportedOnRuntimeError;
+/** Where the runtime in use came from: the caller's option, MELCHIZEDEK_RUNTIME, or the default. */
+export type RuntimeSource = 'option' | 'MELCHIZEDEK_RUNTIME' | 'default';
+/** The runtime chooseRuntime picks, and where it came from (the doctor prints both). */
+export declare function describeRuntime(option?: string, env?: NodeJS.ProcessEnv): {
+    runtime: RuntimeName;
+    source: RuntimeSource;
+};

package/dist/lib/runtime/runtimeFlag.js

@@ -2,10 +2,11 @@
  * lib/runtime/runtimeFlag.ts — which runtime runs a turn: MELCHIZEDEK_RUNTIME
  * and the turn's `runtime` option (ADR 0045, ADR 0073).
  *
- * `adk` runs each agent on Google ADK's Runner, `native` on the engine's own
- * agent loop (lib/runtime/native/agentLoop.ts). The default is `adk` until
- * the release that makes native the default (ADR 0045). A feature the native
- * runtime does not run yet fails before any model call with
+ * `native` runs each agent on the engine's own agent loop
+ * (lib/runtime/native/agentLoop.ts), `adk` on Google ADK's Runner. `native`
+ * is the default since 0.20.0 (ADR 0045, ADR 0102); `adk` needs the optional
+ * peer @google/adk installed, and leaves the package at 1.0.0. A feature the
+ * native runtime does not run yet fails before any model call with
  * UnsupportedOnRuntimeError, which names the feature and the runtime.
  *
  * A leaf module: it imports nothing, so every caller (the compiler, the
@@ -13,7 +14,7 @@
  */
 export const RUNTIMES = ['adk', 'native'];
 /** The runtime when neither the turn nor MELCHIZEDEK_RUNTIME names one. */
-export const DEFAULT_RUNTIME = 'adk';
+export const DEFAULT_RUNTIME = 'native';
 function asRuntime(raw, source) {
     const value = raw.trim().toLowerCase();
     if (value === 'adk' || value === 'native')
@@ -27,7 +28,7 @@ export function runtimeSetting(env = process.env) {
         return undefined;
     return asRuntime(raw, 'MELCHIZEDEK_RUNTIME');
 }
-/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else adk. */
+/** The runtime to use: the caller's option, else MELCHIZEDEK_RUNTIME, else native. */
 export function chooseRuntime(option, env = process.env) {
     if (option !== undefined)
         return asRuntime(option, 'The runtime option');
@@ -48,3 +49,10 @@ export class UnsupportedOnRuntimeError extends Error {
 export function unsupportedOnNative(feature, where) {
     return new UnsupportedOnRuntimeError(feature, 'native', where);
 }
+/** The runtime chooseRuntime picks, and where it came from (the doctor prints both). */
+export function describeRuntime(option, env = process.env) {
+    if (option !== undefined)
+        return { runtime: asRuntime(option, 'The runtime option'), source: 'option' };
+    const set = runtimeSetting(env);
+    return set ? { runtime: set, source: 'MELCHIZEDEK_RUNTIME' } : { runtime: DEFAULT_RUNTIME, source: 'default' };
+}

package/dist/lib/runtime/syndicateTurn.d.ts

@@ -26,13 +26,15 @@
  * time, and an outer AbortSignal cancels it. All three abort the provider
  * request in flight, not just the loop around it.
  *
- * ── Runtimes (ADR 0045, ADR 0073) ─────────────────────────────────────────
- * Each agent of a turn runs on ADK's Runner (the default) or on the
- * engine's own agent loop: the turn's `runtime` option, else
+ * ── Runtimes (ADR 0045, ADR 0073, ADR 0102) ───────────────────────────────
+ * Each agent of a turn runs on the engine's own agent loop (the default
+ * since 0.20.0) or on ADK's Runner: the turn's `runtime` option, else
  * MELCHIZEDEK_RUNTIME. Both compile the same AgentSpec (lib/compile.ts),
  * store the same events and drain through drainAgentStream, so everything
  * else here is shared. What native does not run yet fails before any model
- * call, naming the feature (lib/runtime/nativeTurn.ts).
+ * call, naming the feature (lib/runtime/nativeTurn.ts). The adk runtime
+ * needs @google/adk installed; without it, a turn asked to run there fails
+ * before the session is touched, naming the package (lib/adkPeer.ts).
  */
 import type { BasePlugin } from '@google/adk';
 import type { BaseMemoryService, BaseSessionService, Event, LlmAgent } from '@google/adk';
@@ -42,8 +44,11 @@ import type { PendingConsent } from './credentials.ts';
 export { CREDENTIAL_REQUEST, credentialResponsePart, describeConsent, pendingConsent } from './credentials.ts';
 export type { PendingConsent } from './credentials.ts';
 export type { ToolCredentials } from '../tools/oauthConsent.ts';
-export { chooseRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, UnsupportedOnRuntimeError } from './runtimeFlag.ts';
-export type { RuntimeName } from './runtimeFlag.ts';
+export { chooseRuntime, describeRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, UnsupportedOnRuntimeError } from './runtimeFlag.ts';
+export type { RuntimeName, RuntimeSource } from './runtimeFlag.ts';
+export { AdkNotInstalledError, adkInstalled } from '../adkPeer.ts';
+export { InProcessSessionService } from './sessions.ts';
+export { asAdkSessionService, asSessionService } from './adkSessionBridge.ts';
 import type { PendingInput } from '../workflow.ts';
 export { describeInput } from '../workflow.ts';
 export type { PendingInput } from '../workflow.ts';
@@ -112,10 +117,10 @@ export interface SyndicateTurnOptions {
     /** Applied to every compiled agent before it runs (eval tool replay). ADK runtime only. */
     transformAgent?: (agent: LlmAgent) => LlmAgent;
     /**
-     * The runtime that runs the turn's agents: `adk` (Google ADK's Runner) or
-     * `native` (the engine's own loop). Default: MELCHIZEDEK_RUNTIME, else
-     * `adk`. A feature native does not run yet throws UnsupportedOnRuntimeError
-     * before any model call.
+     * The runtime that runs the turn's agents: `native` (the engine's own
+     * loop) or `adk` (Google ADK's Runner, which needs @google/adk installed).
+     * Default: MELCHIZEDEK_RUNTIME, else `native`. A feature native does not
+     * run yet throws UnsupportedOnRuntimeError before any model call.
      */
     runtime?: RuntimeName;
     /** Plan-dispatch only: skip the classifier and run this route. Overrides

package/dist/lib/runtime/syndicateTurn.js

@@ -26,30 +26,36 @@
  * time, and an outer AbortSignal cancels it. All three abort the provider
  * request in flight, not just the loop around it.
  *
- * ── Runtimes (ADR 0045, ADR 0073) ─────────────────────────────────────────
- * Each agent of a turn runs on ADK's Runner (the default) or on the
- * engine's own agent loop: the turn's `runtime` option, else
+ * ── Runtimes (ADR 0045, ADR 0073, ADR 0102) ───────────────────────────────
+ * Each agent of a turn runs on the engine's own agent loop (the default
+ * since 0.20.0) or on ADK's Runner: the turn's `runtime` option, else
  * MELCHIZEDEK_RUNTIME. Both compile the same AgentSpec (lib/compile.ts),
  * store the same events and drain through drainAgentStream, so everything
  * else here is shared. What native does not run yet fails before any model
- * call, naming the feature (lib/runtime/nativeTurn.ts).
+ * call, naming the feature (lib/runtime/nativeTurn.ts). The adk runtime
+ * needs @google/adk installed; without it, a turn asked to run there fails
+ * before the session is touched, naming the package (lib/adkPeer.ts).
  */
-import { InMemorySessionService, ReflectAndRetryModelPlugin, ReflectAndRetryToolPlugin, Runner, StreamingMode, getFunctionCalls, getFunctionResponses } from '@google/adk';
 import { DEFAULT_MAX_STEPS } from '../config.js';
-import { agentGates, compileGraph, compileSpec, compileSubagent, compileSubagentSpec } from '../compile.js';
-import { compileNative, nativeAdapterFor } from '../compileNative.js';
+import { agentGates, compileGraph, compileSpec, compileSubagent, compileSubagentSpec, compileWorkflowSpec, declaresApprovals } from '../compile.js';
+import { compileNative, compileNativeWorkflow, nativeAdapterFor } from '../compileNative.js';
 import { nativeMemory, refuseOnNative, runNativeAgent } from './nativeTurn.js';
-import { asSessionService } from './adkSessionBridge.js';
-import { resolveTools } from '../toolRegistry.js';
-import { buildWorkflowGraph } from '../workflow/graph.js';
+import { asAdkSessionService, asSessionService } from './adkSessionBridge.js';
+import { requireAdk } from '../adkPeer.js';
+import { getFunctionCalls, getFunctionResponses } from './events.js';
+import { InProcessSessionService } from './sessions.js';
 import { UnsupportedWorkflowResumeError } from '../workflow/resume.js';
-import { refuseUnrunnableNodes, runNativeWorkflow } from '../workflow/turn.js';
+import { runNativeWorkflow } from '../workflow/turn.js';
 import { SelfCorrection } from './native/selfCorrection.js';
 import { UnsupportedOnRuntimeError, chooseRuntime } from './runtimeFlag.js';
 import { pinnedCredentialStore } from '../tools/auth.js';
 import { credentialResponsePart, describeConsent, pendingConsent } from './credentials.js';
 export { CREDENTIAL_REQUEST, credentialResponsePart, describeConsent, pendingConsent } from './credentials.js';
-export { chooseRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, UnsupportedOnRuntimeError } from './runtimeFlag.js';
+export { chooseRuntime, describeRuntime, runtimeSetting, DEFAULT_RUNTIME, RUNTIMES, UnsupportedOnRuntimeError } from './runtimeFlag.js';
+export { AdkNotInstalledError, adkInstalled } from '../adkPeer.js';
+// A turn's session store with no ADK: runSyndicateTurn takes it as asAdkSessionService(new InProcessSessionService()) (ADR 0102).
+export { InProcessSessionService } from './sessions.js';
+export { asAdkSessionService, asSessionService } from './adkSessionBridge.js';
 import { ROUTE_STEP_SUFFIX, compileWorkflow, describeInput, inputRequestFrom, isWorkflowSyndicate } from '../workflow.js';
 export { describeInput } from '../workflow.js';
 import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from '../dispatch.js';
@@ -85,6 +91,9 @@ export function retryPlugins(retries) {
     const model = retries?.model_errors ?? DEFAULT_MODEL_ERROR_RETRIES;
     const tool = retries?.tool_errors ?? DEFAULT_TOOL_ERROR_RETRIES;
     const plugins = [];
+    if (model <= 0 && tool <= 0)
+        return plugins;
+    const { ReflectAndRetryModelPlugin, ReflectAndRetryToolPlugin } = requireAdk("ADK's retry plugins (retryPlugins)");
     if (model > 0)
         plugins.push(new ReflectAndRetryModelPlugin({ maxRetries: model }));
     if (tool > 0)
@@ -173,7 +182,7 @@ export async function drainAgentStream(stream, opts = {}) {
             d.tokens.output += e.usageMetadata.candidatesTokenCount ?? 0;
             d.tokens.thinking += e.usageMetadata.thoughtsTokenCount ?? 0;
         }
-        const calls = getFunctionCalls(event) ?? [];
+        const calls = getFunctionCalls(event);
         // Text streamed before a tool call was narration, not the answer.
         if (streamed && calls.length) {
             ev.onTextReset?.();
@@ -207,7 +216,7 @@ export async function drainAgentStream(stream, opts = {}) {
             if (opts.publishToolStatus)
                 ev.onProgress?.(`Invoking tool: ${name}`);
         }
-        for (const resp of getFunctionResponses(event) ?? []) {
+        for (const resp of getFunctionResponses(event)) {
             const r = resp;
             const name = r.name ?? r.functionResponse?.name ?? '';
             const content = r.response ?? r.functionResponse?.response ?? {};
@@ -286,6 +295,9 @@ export async function runSyndicateTurn(opts) {
     // class, which bypasses traceLlmGeneration: no max_steps, no cancel. A
     // caller that resolves models itself (the A2A server) is left alone.
     const runtime = chooseRuntime(opts.runtime);
+    // The adk runtime without @google/adk installed fails here, naming the package (ADR 0102).
+    if (runtime === 'adk')
+        requireAdk("The adk runtime (MELCHIZEDEK_RUNTIME=adk, or the turn's runtime option)");
     if (!opts.compile?.resolveModel)
         registerAvailableProviders();
     const control = createTurnControl({
@@ -303,23 +315,15 @@ export async function runSyndicateTurn(opts) {
 /**
  * A workflow syndicate for the native runtime: its graph, every agent
  * compiled for native from the same specs ADK's compileWorkflow builds its
- * agents from, one adapter lookup that knows every agent's models, and the
- * registry's lookup for tool nodes. A tool node ADK's compile refuses (an
- * unregistered or long-running tool) is refused here, before any model
- * call, with ADK's message.
+ * agents from (compileWorkflowSpec, then compileNativeWorkflow), one adapter
+ * lookup that knows every agent's models, and the registry's lookup for tool
+ * nodes. A tool node ADK's compile refuses (an unregistered or long-running
+ * tool) is refused here, before any model call, with ADK's message.
  */
-async function compileNativeWorkflow(config, opts) {
-    const graph = buildWorkflowGraph(config);
-    const specs = [];
-    const agents = new Map();
-    for (const sub of [{ description: '', ...config.orchestrator }, ...(config.subagents ?? [])]) {
-        const spec = await compileSubagentSpec(sub, opts);
-        specs.push(spec);
-        agents.set(sub.name, compileNative(spec));
-    }
-    const resolveTool = (name) => resolveTools([name], opts.onUnknownTool)[0];
-    refuseUnrunnableNodes(graph, resolveTool);
-    return { runtime: 'native-workflow', graph, agents, adapterFor: nativeAdapterFor(opts, specs), resolveTool };
+async function compileNativeWorkflowAgent(config, opts) {
+    const spec = await compileWorkflowSpec(config, opts);
+    const { graph, agents, resolveTool } = compileNativeWorkflow(spec);
+    return { runtime: 'native-workflow', graph, agents, adapterFor: nativeAdapterFor(opts, spec.agents.map((a) => a.spec)), resolveTool };
 }
 async function runTurnInner(opts, control, runtime) {
     const { config, appName, userId, sessionId, sessionService } = opts;
@@ -336,6 +340,11 @@ async function runTurnInner(opts, control, runtime) {
     // What native does not run yet fails here, before the session is touched.
     if (native)
         refuseOnNative(config, { isWorkflow: isWorkflowSyndicate(config), transformAgent: opts.transformAgent });
+    // ADK pauses a gated call in a workflow node, but its resume reruns the node from its input, so the
+    // pinned call never runs: approvals on workflow nodes run on native only (ADR 0098).
+    if (!native && isWorkflowSyndicate(config) && declaresApprovals(config)) {
+        throw new UnsupportedOnRuntimeError('an approval gate (require_approval) on a workflow node', 'adk', config.syndicate_name || 'syndicate');
+    }
     const nativeOf = (spec) => ({ runtime: 'native', agent: compileNative(spec), adapterFor: nativeAdapterFor(compileOpts, spec) });
     /** The orchestrator (a DELEGATE root, or a dispatch classifier) for the turn's runtime. */
     const compileRoot = async () => native ? nativeOf(await compileSpec(config, compileOpts)) : { runtime: 'adk', agent: transform(await compileGraph(config, compileOpts)) };
@@ -534,6 +543,7 @@ async function runTurnInner(opts, control, runtime) {
             });
         }
         else {
+            const { Runner, StreamingMode } = requireAdk('The adk runtime');
             const runner = new Runner({
                 agent: params.agent.agent,
                 appName,
@@ -624,7 +634,10 @@ async function runTurnInner(opts, control, runtime) {
             // conversation the next specialist reads.
             const routerAgent = await compileRoot();
             const routerSid = `${sessionId}::route`;
-            const routerSessions = new InMemorySessionService();
+            // ADK's in-memory store on adk; the engine's on native, which needs no ADK.
+            const routerSessions = native
+                ? asAdkSessionService(new InProcessSessionService())
+                : new (requireAdk('The adk runtime').InMemorySessionService)();
             await routerSessions.createSession({ appName, userId, sessionId: routerSid });
             const shared = await sessionService.getSession({ appName, userId, sessionId });
             const digest = renderTranscriptDigest(shared?.events ?? []);
@@ -726,8 +739,15 @@ async function runTurnInner(opts, control, runtime) {
         // unless its YAML says otherwise, so no projection is needed. An
         // `ask_user` node ends the turn input-required; the next message
         // resumes the graph where it waited.
+        // While a gated call waits, a message that is not its decision repeats the request: the walk cannot move past
+        // the waiting node, so nothing is stored and nothing runs, as the A2A server answers it (ADR 0098).
+        if (!decision && declaresApprovals(config)) {
+            const open = pendingApproval(existing?.events ?? []);
+            if (open)
+                return pause(open);
+        }
         const workflowAgent = native
-            ? await compileNativeWorkflow(config, compileOpts)
+            ? await compileNativeWorkflowAgent(config, compileOpts)
             : { runtime: 'adk', agent: (await compileWorkflow(config, compileOpts, transform)).workflow };
         try {
             answer = await runAgent({
@@ -759,6 +779,13 @@ async function runTurnInner(opts, control, runtime) {
             result.error = answer.error;
             return finish();
         }
+        // A gated call paused its node, and the walk with it (ADR 0098): the next message answers it.
+        if (declaresApprovals(config)) {
+            const after = await sessionService.getSession({ appName, userId, sessionId });
+            const pending = pendingApproval(after?.events ?? []);
+            if (pending)
+                return pause(pending);
+        }
         if (answer.inputRequests.length) {
             const input = answer.inputRequests[answer.inputRequests.length - 1];
             result.status = 'input-required';

package/dist/lib/runtime/valueDepth.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 declare 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 declare function nestedDeeperThan(value: unknown, max?: number): boolean;