melchizedek-agents 0.19.0 → 0.20.0

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

@@ -36,7 +36,11 @@
  *      - a long-running tool (ask_user) that returns nothing answers
  *        nothing; its actions, when it set any, make an event of their own;
  *      - a result that is not an object is wrapped `{ result }`, an array
- *        `{ results }`, as ADK wraps them.
+ *        `{ results }`, as ADK wraps them;
+ *      - a result nested deeper than MAX_VALUE_DEPTH levels answers
+ *        `{ error: TOO_DEEP_RESULT }` instead: every later reader of the
+ *        session would overflow its stack on it (lib/runtime/valueDepth.ts,
+ *        ADR 0101). ADK keeps it.
  *      One call's response is stored as its own event; several are merged
  *      into one, parts in call order and actions merged (ADK's
  *      mergeParallelFunctionResponseEvents). ADK runs the calls one after
@@ -115,10 +119,11 @@ import { z } from 'zod';
 import { ToolCredentialError, toolAccessToken } from '../../tools/auth.js';
 import { APPROVAL_TEXTS, CONSENT_TEXTS, isTool } from '../../tools/tool.js';
 import { createEventActions, createTurnEvent, getFunctionCalls, getFunctionResponses, isFinal } from '../events.js';
+import { MAX_VALUE_DEPTH, nestedDeeperThan } from '../valueDepth.js';
 import { currentTurnSignal } from '../turnControl.js';
 import { compactBeforeStep } from './compaction.js';
 import { ADK_CALL_ID_PREFIX } from './history.js';
-import { runSubagent, subagentOf } from './delegate.js';
+import { runSubagent, runWorkflowSubagent, subagentOf, workflowSubagentOf } from './delegate.js';
 import { approvedCalls, grantedCalls } from './interrupts.js';
 import { SelfCorrection } from './selfCorrection.js';
 import { eitherSignal, runModelStep, stopOf } from './step.js';
@@ -145,19 +150,23 @@ function isDefaultActions(a) {
         a.transferToAgent === undefined &&
         a.escalate === undefined);
 }
+/** Copies `from`'s own keys onto `to` as own keys: Object.assign would re-parent `to` for a key `__proto__` (a model-chosen call id). */
+function assignOwn(to, from) {
+    for (const [k, v] of Object.entries(from))
+        setOwn(to, k, v);
+}
 /** ADK's mergeEventActions: dictionaries merged in order, the later flag winning. */
 function mergeActions(sources) {
     const out = createEventActions();
     for (const s of sources) {
         if (s.stateDelta)
-            for (const [k, v] of Object.entries(s.stateDelta))
-                setOwn(out.stateDelta, k, v);
+            assignOwn(out.stateDelta, s.stateDelta);
         if (s.artifactDelta)
-            Object.assign(out.artifactDelta, s.artifactDelta);
+            assignOwn(out.artifactDelta, s.artifactDelta);
         if (s.requestedAuthConfigs)
-            Object.assign(out.requestedAuthConfigs, s.requestedAuthConfigs);
+            assignOwn(out.requestedAuthConfigs, s.requestedAuthConfigs);
         if (s.requestedToolConfirmations)
-            Object.assign(out.requestedToolConfirmations, s.requestedToolConfirmations);
+            assignOwn(out.requestedToolConfirmations, s.requestedToolConfirmations);
         if (s.skipSummarization !== undefined)
             out.skipSummarization = s.skipSummarization;
         if (s.transferToAgent !== undefined)
@@ -235,7 +244,8 @@ function callContext(scope, functionCallId, confirmation) {
     const requestCredential = consent && functionCallId
         ? async (provider) => {
             const request = await consent.begin({ appName: session.appName, userId: session.userId, sessionId: session.id, functionCallId, provider });
-            actions.requestedAuthConfigs[functionCallId] = request.authConfig;
+            // An own key, as every delta: a call id such as `__proto__` names a request, never a prototype.
+            setOwn(actions.requestedAuthConfigs, functionCallId, request.authConfig);
         }
         : undefined;
     const credentials = ctx.credentials;
@@ -270,7 +280,7 @@ function callContext(scope, functionCallId, confirmation) {
         requestConfirmation: ({ hint, payload } = {}) => {
             if (!functionCallId)
                 throw new Error('functionCallId is not set.');
-            actions.requestedToolConfirmations[functionCallId] = { hint: hint ?? '', confirmed: false, payload };
+            setOwn(actions.requestedToolConfirmations, functionCallId, { hint: hint ?? '', confirmed: false, payload });
         },
         // The person's answer, when this call is the pinned call an approval resumes (interrupts.ts).
         confirmation,
@@ -292,6 +302,8 @@ function callContext(scope, functionCallId, confirmation) {
         },
     };
 }
+/** What a tool's result becomes when it nests past MAX_VALUE_DEPTH (ADR 0101). */
+export const TOO_DEEP_RESULT = (toolName) => `The result of tool '${toolName}' nested deeper than ${MAX_VALUE_DEPTH} levels and was not kept.`;
 /** ADK's normalization of a tool's result into a function response. */
 function asResponse(value) {
     if (typeof value !== 'object' || value === null)
@@ -339,14 +351,18 @@ async function runCall(scope, call, tools, correction, confirmation) {
     const args = call.args ?? {};
     const toolName = tool.name;
     const longRunning = isTool(tool) ? tool.longRunning === true : tool.isLongRunning === true;
-    // Delegation (WS2-6): a subagent runs as its own child loop, before the generic path (delegate.ts).
+    // Delegation (WS2-6): a subagent runs as its own child loop, a nested workflow as its own walk (ADR 0098), before the generic path (delegate.ts).
     const subagent = subagentOf(tool);
+    const workflow = subagent ? undefined : workflowSubagentOf(tool);
+    const delegation = { ctx: scope.ctx, stateBase: scope.stateBase, signal: scope.signal, runLoop: runAgentLoop, queue: scope };
     let response;
     let failure;
     try {
         response = subagent
-            ? await runSubagent(subagent, args, context, { ctx: scope.ctx, stateBase: scope.stateBase, signal: scope.signal, runLoop: runAgentLoop, queue: scope })
-            : isTool(tool) ? await runOwnTool(tool, args, context) : await tool.runAsync({ args, toolContext: context });
+            ? await runSubagent(subagent, args, context, delegation)
+            : workflow
+                ? await runWorkflowSubagent(workflow, args, context, delegation)
+                : isTool(tool) ? await runOwnTool(tool, args, context) : await tool.runAsync({ args, toolContext: context });
     }
     catch (e) {
         failure = e instanceof Error ? e.message : e;
@@ -368,7 +384,9 @@ async function runCall(scope, call, tools, correction, confirmation) {
         return isDefaultActions(context.actions) ? undefined : { actions: context.actions };
     }
     const answer = failure ? { error: failure } : response === null || response === undefined ? { result: response } : asResponse(response);
-    return { part: { functionResponse: { id: context.functionCallId, name: toolName, response: answer } }, actions: context.actions };
+    // A result nested past MAX_VALUE_DEPTH would overflow every later reader of the session (lib/runtime/valueDepth.ts, ADR 0101): a note stands in for it.
+    const kept = nestedDeeperThan(answer) ? { error: TOO_DEEP_RESULT(toolName) } : answer;
+    return { part: { functionResponse: { id: context.functionCallId, name: toolName, response: kept } }, actions: context.actions };
 }
 /**
  * The calls run, in parallel, as the one response event ADK stores for them

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

@@ -47,6 +47,17 @@
  * here like any subagent, and its own delegations open sessions under their
  * own names, as on ADK.
  *
+ * A NESTED WORKFLOW (ADR 0098): a `yaml_reference` to a workflow syndicate
+ * is a workflowSubagentTool, holding the whole graph as a WorkflowSubagent.
+ * A call runs as steps 1 to 6 say, with the walk in place of the loop: the
+ * graph's walk (lib/workflow/turn.ts, runNativeWorkflow, which
+ * lib/compileNative.ts hands over) stores the message itself and yields the
+ * events ADK's Runner yields for a Workflow root, node input turns aside;
+ * the answer is the last of them's text, as ADK's AgentTool reads it from a
+ * Workflow (never parsed: a Workflow has no output schema). A node that
+ * gave up fails the call with its error. The walk is not imported here, so
+ * this module stays below lib/workflow/ in the import graph.
+ *
  * The DELEGATE relay fallback (an orchestrator that echoes a tool name or
  * says nothing) stays in lib/runtime/syndicateTurn.ts: it reads the drained
  * run, whichever runtime produced it.
@@ -54,12 +65,17 @@
  * ADK stays out of this file: an ADK AgentTool is recognized by ADK's global
  * symbol only to refuse it, with a message naming what to list instead.
  */
+import type { ModelAdapter } from '../../models/contract.ts';
 import type { Tool, ToolContext } from '../../tools/tool.ts';
 import type { TurnEvent } from '../events.ts';
+import type { SessionService } from '../sessions.ts';
 import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
 import type { NativeAgent } from './request.ts';
+import { SelfCorrection } from './selfCorrection.ts';
 /** Where a subagent tool keeps the agent it runs. A global symbol, so a second copy of this module still finds it. */
 export declare const SUBAGENT: unique symbol;
+/** Where a workflow subagent tool keeps the graph it runs. */
+export declare const WORKFLOW_SUBAGENT: unique symbol;
 /** A subagent listed on its caller as a tool: the declaration ADK's AgentTool gives it, and the agent the call runs. */
 export interface SubagentTool extends Tool {
     readonly [SUBAGENT]: NativeAgent;
@@ -70,6 +86,36 @@ export interface SubagentTool extends Tool {
  * one string `request`. Only the native loop runs it.
  */
 export declare function subagentTool(agent: NativeAgent): SubagentTool;
+/** One call's walk of a nested workflow, on the child session (WorkflowSubagent.walk). */
+export interface WorkflowSubagentRun {
+    sessions: SessionService;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    /** The message's parts: the call's request as one text part. */
+    userParts: unknown[];
+    signal?: AbortSignal;
+    adapterFor: (model: string) => ModelAdapter;
+    memory?: AgentLoopContext['memory'];
+    log?: (message: string) => void;
+    selfCorrection: SelfCorrection;
+    credentials?: AgentLoopContext['credentials'];
+}
+/** A workflow syndicate delegated to as a subagent (ADR 0098): its name and description, and the walk one call runs. */
+export interface WorkflowSubagent {
+    name: string;
+    description?: string;
+    /** Stores the message on the child session and walks the whole graph, yielding each event ADK's Runner yields. Throws what a node gave up with. */
+    walk(run: WorkflowSubagentRun): AsyncGenerator<TurnEvent, unknown>;
+}
+/** A nested workflow listed on its caller as a tool: the declaration ADK's AgentTool gives a Workflow, and the graph the call walks. */
+export interface WorkflowSubagentTool extends Tool {
+    readonly [WORKFLOW_SUBAGENT]: WorkflowSubagent;
+}
+/** `workflow` as a tool its caller lists, as lib/compileAdk.ts lists a nested Workflow as an AgentTool: one string `request`. Only the native loop runs it. */
+export declare function workflowSubagentTool(workflow: WorkflowSubagent): WorkflowSubagentTool;
+/** The nested workflow a delegated call walks: the one a workflow subagent tool holds, else undefined. */
+export declare function workflowSubagentOf(tool: unknown): WorkflowSubagent | undefined;
 /**
  * The agent a delegated call runs: the one a subagent tool (or anything
  * carrying SUBAGENT) holds, else undefined. Throws for an ADK AgentTool that
@@ -96,3 +142,10 @@ export interface DelegationScope {
  * throws, and for an output-schema answer that does not parse.
  */
 export declare function runSubagent(agent: NativeAgent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;
+/**
+ * Runs one delegated call to a nested workflow (ADR 0098): the whole graph
+ * walked on the child session with the call's `request` as its message,
+ * the walk's state writes recorded in `context`. Resolves to the last
+ * yielded event's text, '' for none. Throws what the walk throws.
+ */
+export declare function runWorkflowSubagent(workflow: WorkflowSubagent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;

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

@@ -47,6 +47,17 @@
  * here like any subagent, and its own delegations open sessions under their
  * own names, as on ADK.
  *
+ * A NESTED WORKFLOW (ADR 0098): a `yaml_reference` to a workflow syndicate
+ * is a workflowSubagentTool, holding the whole graph as a WorkflowSubagent.
+ * A call runs as steps 1 to 6 say, with the walk in place of the loop: the
+ * graph's walk (lib/workflow/turn.ts, runNativeWorkflow, which
+ * lib/compileNative.ts hands over) stores the message itself and yields the
+ * events ADK's Runner yields for a Workflow root, node input turns aside;
+ * the answer is the last of them's text, as ADK's AgentTool reads it from a
+ * Workflow (never parsed: a Workflow has no output schema). A node that
+ * gave up fails the call with its error. The walk is not imported here, so
+ * this module stays below lib/workflow/ in the import graph.
+ *
  * The DELEGATE relay fallback (an orchestrator that echoes a tool name or
  * says nothing) stays in lib/runtime/syndicateTurn.ts: it reads the drained
  * run, whichever runtime produced it.
@@ -55,6 +66,7 @@
  * symbol only to refuse it, with a message naming what to list instead.
  */
 import { randomUUID } from 'node:crypto';
+import { resolveAdapter } from '../../models/registry.js';
 import { createTurnEvent } from '../events.js';
 import { TEMP_STATE_PREFIX } from '../sessions.js';
 import { SelfCorrection } from './selfCorrection.js';
@@ -63,6 +75,8 @@ import { SelfCorrection } from './selfCorrection.js';
 export const SUBAGENT = Symbol.for('melchizedek.subagent');
 /** ADK's own mark on an AgentTool (agent_tool.js). */
 const ADK_AGENT_TOOL = Symbol.for('google.adk.agentTool');
+/** Where a workflow subagent tool keeps the graph it runs. */
+export const WORKFLOW_SUBAGENT = Symbol.for('melchizedek.workflowSubagent');
 /**
  * `agent` as a tool its caller lists, as lib/compile.ts lists a subagent as
  * an AgentTool: named for the agent, described by its description, taking
@@ -82,6 +96,28 @@ export function subagentTool(agent) {
         },
     };
 }
+/** `workflow` as a tool its caller lists, as lib/compileAdk.ts lists a nested Workflow as an AgentTool: one string `request`. Only the native loop runs it. */
+export function workflowSubagentTool(workflow) {
+    return {
+        name: workflow.name,
+        [WORKFLOW_SUBAGENT]: workflow,
+        declaration: () => ({
+            name: workflow.name,
+            description: workflow.description ?? '',
+            parameters: { type: 'object', properties: { request: { type: 'string' } }, required: ['request'] },
+        }),
+        execute: async () => {
+            throw new Error(`${workflow.name}: a workflow subagent tool runs only on the native loop (lib/runtime/native/agentLoop.ts)`);
+        },
+    };
+}
+/** The nested workflow a delegated call walks: the one a workflow subagent tool holds, else undefined. */
+export function workflowSubagentOf(tool) {
+    if (!tool || typeof tool !== 'object')
+        return undefined;
+    const workflow = tool[WORKFLOW_SUBAGENT];
+    return workflow && typeof workflow === 'object' ? workflow : undefined;
+}
 /**
  * The agent a delegated call runs: the one a subagent tool (or anything
  * carrying SUBAGENT) holds, else undefined. Throws for an ADK AgentTool that
@@ -107,7 +143,7 @@ function inTurn(key, run) {
     queues.set(key, mine.then(() => undefined, () => undefined));
     return mine;
 }
-/** ADK's AgentTool answer: the last event's non-thought text, joined by a newline. */
+/** ADK's AgentTool answer: the last event's non-thought text, joined by a newline; parsed under an output schema. */
 function answerOf(agent, last) {
     const parts = last?.content?.parts;
     if (!parts?.length)
@@ -119,6 +155,19 @@ function answerOf(agent, last) {
         .join('\n');
     return agent.outputSchema ? JSON.parse(text) : text;
 }
+/** The child's session, as ADK's AgentTool gets or creates it: under the subagent's name, from the caller's state the first time. */
+async function childSession(name, context, scope) {
+    const { sessions, session: parent } = scope.ctx;
+    const key = { appName: name, userId: parent.userId, sessionId: parent.id };
+    return (await sessions.get(key)) ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
+}
+/** Step 5: an event's state writes, `temp:` keys aside, into the call's state delta. */
+function recordState(event, context) {
+    for (const [k, v] of Object.entries(event.actions?.stateDelta ?? {})) {
+        if (!k.startsWith(TEMP_STATE_PREFIX))
+            context.state.set(k, v);
+    }
+}
 /**
  * Runs one delegated call: `agent` on its own session with the call's
  * `request` as its message, the child's state writes recorded in `context`.
@@ -131,10 +180,8 @@ export function runSubagent(agent, args, context, scope) {
 async function runChild(agent, args, context, scope) {
     const { ctx, signal } = scope;
     const { sessions } = ctx;
-    const parent = ctx.session;
     const content = { role: 'user', parts: [{ text: args.request }] };
-    const key = { appName: agent.name, userId: parent.userId, sessionId: parent.id };
-    const session = (await sessions.get(key)) ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
+    const session = await childSession(agent.name, context, scope);
     if (signal?.aborted)
         return '';
     const invocationId = `e-${randomUUID()}`;
@@ -163,11 +210,47 @@ async function runChild(agent, args, context, scope) {
         // ADK's Runner stops yielding once the turn stopped: the answer is the last event it yielded.
         if (signal?.aborted)
             break;
-        for (const [k, v] of Object.entries(event.actions?.stateDelta ?? {})) {
-            if (!k.startsWith(TEMP_STATE_PREFIX))
-                context.state.set(k, v);
-        }
+        recordState(event, context);
         last = event;
     }
     return answerOf(agent, last);
 }
+/**
+ * Runs one delegated call to a nested workflow (ADR 0098): the whole graph
+ * walked on the child session with the call's `request` as its message,
+ * the walk's state writes recorded in `context`. Resolves to the last
+ * yielded event's text, '' for none. Throws what the walk throws.
+ */
+export function runWorkflowSubagent(workflow, args, context, scope) {
+    return inTurn(scope.queue, () => walkChild(workflow, args, context, scope));
+}
+async function walkChild(workflow, args, context, scope) {
+    const { ctx, signal } = scope;
+    const session = await childSession(workflow.name, context, scope);
+    if (signal?.aborted)
+        return '';
+    const walk = workflow.walk({
+        sessions: ctx.sessions,
+        appName: session.appName,
+        userId: session.userId,
+        sessionId: session.id,
+        userParts: [{ text: args.request }],
+        adapterFor: ctx.adapterFor ?? resolveAdapter,
+        // As runChild: ADK's AgentTool runs its sub-runner without the reflect-and-retry plugins (ADR 0075).
+        selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        ...(ctx.memory ? { memory: ctx.memory } : {}),
+        ...(ctx.log ? { log: ctx.log } : {}),
+        ...(ctx.credentials ? { credentials: ctx.credentials } : {}),
+    });
+    let last;
+    for await (const event of walk) {
+        if (signal?.aborted)
+            break;
+        if (event.partial)
+            continue;
+        recordState(event, context);
+        last = event;
+    }
+    return answerOf({}, last);
+}

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

@@ -62,7 +62,9 @@
  *      nothing happens.
  *   2. The requests they answer: `adk_request_credential` calls this agent
  *      made, by id. An answer naming no such request is ignored, as ADK
- *      ignores it.
+ *      ignores it. So is an answer to a request an earlier grant already
+ *      bound (step 3): a replayed grant runs nothing, where ADK would run
+ *      the paused call again (WS5-5).
  *   3. The binding. ADK's answer carries the authorization response (a code
  *      or the redirect URL), which ADK exchanges in-process with the client
  *      secret its request event stored. Here the server's callback route has
@@ -71,8 +73,9 @@
  *      `{ credentialKey, granted: true }`, bound to the request by its
  *      credentialKey. An answer that does not bind is ignored.
  *   4. The paused calls the bound requests name (`function_call_id`, ADK's
- *      toolset requests aside) run again, from the latest event that made
- *      them, through the loop's own call path. The tool now reads its grant
+ *      toolset requests aside) run again, from the latest event this agent
+ *      authored that made them (ADK reads any author's; a call forged into
+ *      a user event never runs), through the loop's own call path. The tool now reads its grant
  *      through ctx.accessToken. The response is stored before the step
  *      builds its request. A later step finds the agent's own events last,
  *      so the call runs once.

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

@@ -62,7 +62,9 @@
  *      nothing happens.
  *   2. The requests they answer: `adk_request_credential` calls this agent
  *      made, by id. An answer naming no such request is ignored, as ADK
- *      ignores it.
+ *      ignores it. So is an answer to a request an earlier grant already
+ *      bound (step 3): a replayed grant runs nothing, where ADK would run
+ *      the paused call again (WS5-5).
  *   3. The binding. ADK's answer carries the authorization response (a code
  *      or the redirect URL), which ADK exchanges in-process with the client
  *      secret its request event stored. Here the server's callback route has
@@ -71,8 +73,9 @@
  *      `{ credentialKey, granted: true }`, bound to the request by its
  *      credentialKey. An answer that does not bind is ignored.
  *   4. The paused calls the bound requests name (`function_call_id`, ADK's
- *      toolset requests aside) run again, from the latest event that made
- *      them, through the loop's own call path. The tool now reads its grant
+ *      toolset requests aside) run again, from the latest event this agent
+ *      authored that made them (ADK reads any author's; a call forged into
+ *      a user event never runs), through the loop's own call path. The tool now reads its grant
  *      through ctx.accessToken. The response is stored before the step
  *      builds its request. A later step finds the agent's own events last,
  *      so the call runs once.
@@ -256,6 +259,16 @@ export async function grantedCalls(agent, scope) {
             answers.set(r.id, r.response);
     if (answers.size === 0)
         return undefined;
+    // The answers earlier events gave the same requests: one that bound closed its request (below).
+    const earlier = new Map();
+    for (const event of events) {
+        if (event === last)
+            break;
+        for (const r of getFunctionResponses(event)) {
+            if (r.name === REQUEST_CREDENTIAL_CALL && r.id && answers.has(r.id))
+                earlier.set(r.id, [...(earlier.get(r.id) ?? []), r.response]);
+        }
+    }
     // The requests this agent made, by id.
     const requests = new Map();
     for (const event of events) {
@@ -274,14 +287,20 @@ export async function grantedCalls(agent, scope) {
         const request = requests.get(id);
         if (!request || !bindsGrant(request.config, response))
             continue;
+        // A request a grant already bound is closed (WS5-5): a replayed grant runs nothing, as a replayed approval runs nothing. ADK resumes it again.
+        if ((earlier.get(id) ?? []).some((before) => bindsGrant(request.config, before)))
+            continue;
         const callId = request.args.function_call_id ?? request.args.functionCallId;
         if (typeof callId === 'string' && callId && !callId.startsWith(TOOLSET_AUTH_CREDENTIAL_ID_PREFIX))
             resume.add(callId);
     }
     if (resume.size === 0)
         return undefined;
-    // As ADK: the latest event before the answer that made any of the calls, those calls only.
+    // As ADK: the latest event before the answer that made any of the calls, those calls only. Only one this agent authored (WS5-5):
+    // ADK takes any author's, so a call forged into a user event with the paused call's id would run with the forged arguments.
     for (let i = events.length - 2; i >= 0; i--) {
+        if (events[i]?.author !== agent.name)
+            continue;
         const calls = getFunctionCalls(events[i]);
         if (!calls.some((c) => c.id && resume.has(c.id)))
             continue;

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

@@ -43,7 +43,7 @@
  *      xAI); `code_execution` first among Gemini's own tools; and the
  *      set_model_response tool when (2) asked for it, then the caller's
  *      `extraTools` (self-correction's reflection tool, as ADK's plugin adds
- *      it to the toolsDict last). In `mode: task`, finish_task takes
+ *      it to the toolsDict last, when the step declares it: ADR 0097). In `mode: task`, finish_task takes
  *      set_model_response's place and the output schema is never the
  *      response schema (lib/runtime/native/taskMode.ts).
  *   5. Tool choice, the output schema or JSON mode, reasoning and sampling,

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

@@ -43,7 +43,7 @@
  *      xAI); `code_execution` first among Gemini's own tools; and the
  *      set_model_response tool when (2) asked for it, then the caller's
  *      `extraTools` (self-correction's reflection tool, as ADK's plugin adds
- *      it to the toolsDict last). In `mode: task`, finish_task takes
+ *      it to the toolsDict last, when the step declares it: ADR 0097). In `mode: task`, finish_task takes
  *      set_model_response's place and the output schema is never the
  *      response schema (lib/runtime/native/taskMode.ts).
  *   5. Tool choice, the output schema or JSON mode, reasoning and sampling,

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

@@ -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.
  *
@@ -56,6 +68,48 @@ export declare const DEFAULT_MODEL_ERROR_RETRIES = 2;
 export declare const DEFAULT_TOOL_ERROR_RETRIES = 3;
 export declare const ADK_HANDLE_MODEL_ERROR = "adk_handle_model_error";
 export declare const REFLECT_AND_RETRY_RESPONSE_TYPE = "ERROR_HANDLED_BY_REFLECT_AND_RETRY_PLUGIN";
+/**
+ * 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 declare function servedThroughShim<T extends object>(adapter: T): T;
+/**
+ * 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 declare function declaresReflectionTool(adapter: {
+    readonly provider: string;
+}): boolean;
+/**
+ * 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 declare function standsForAdkGemini(adapter: {
+    readonly provider: string;
+}): boolean;
+/** How the reflection call stored in a model's place is signed. */
+export interface ReflectionSigning {
+    /** The signature for a reflection call whose replaced response carried none; absent: left unsigned. */
+    placeholder?: string;
+}
+/**
+ * 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 declare function reflectionSigning(adapter: {
+    readonly provider: string;
+}, model: string | undefined): ReflectionSigning | undefined;
 /** What afterModel leaves of a response: the response to record, or the error event that ends the step. */
 export type CorrectedResponse = {
     response: LlmResponse;
@@ -68,10 +122,14 @@ export type CorrectedResponse = {
 };
 /** The model side, for one agent's steps in one run (lib/runtime/native/step.ts). */
 export interface ModelCorrection {
-    /** Declared after the agent's own tools: the reflection tool. */
+    /** After the agent's own tools: the reflection tool. Declared to the model only where ADK declares it (declaresReflectionTool). */
     readonly tools: readonly Tool[];
-    /** ADK's afterModelCallback, on every response the step reads. */
-    afterModel(response: LlmResponse): CorrectedResponse;
+    /**
+     * ADK's afterModelCallback, on every response the step reads. With
+     * `signing` (reflectionSigning), a reflection call put in the response's
+     * place is signed.
+     */
+    afterModel(response: LlmResponse, signing?: ReflectionSigning): CorrectedResponse;
 }
 /** The tool side, for one call (lib/runtime/native/agentLoop.ts). Each call makes exactly one of these. */
 export interface CallCorrection {