melchizedek-agents 0.18.0 → 0.20.0

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

@@ -0,0 +1,164 @@
+/**
+ * lib/runtime/native/selfCorrection.ts — self-correction on the native loop:
+ * a model error and a tool error retried with reflection, as ADK's
+ * reflect-and-retry plugins do it on the ADK runtime (ADR 0034, ADR 0075).
+ *
+ * WHY this file exists:
+ *   runSyndicateTurn installs ADK's ReflectAndRetryModelPlugin and
+ *   ReflectAndRetryToolPlugin on every Runner it builds, retries at their
+ *   defaults unless the syndicate's `retries:` says otherwise. They change
+ *   what the model is sent and what the store holds, so the native loop
+ *   does what they do, word for word, or a session one runtime wrote would
+ *   read differently on the other:
+ *
+ *   THE MODEL (`retries.model_errors`, default 2; 0 off):
+ *   - 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
+ *     tool: id `adk_handle_model_error_<uuid>`, the error in its arguments,
+ *     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.
+ *
+ *   THE TOOLS (`retries.tool_errors`, default 3; 0 off):
+ *   - A tool that throws an Error, and a call naming no tool, answer with
+ *     reflection guidance (onToolErrorCallback) in place of the plain error,
+ *     counted per tool name in the run; past the limit, the "retry limit
+ *     exceeded" guidance (the plugin is built not to throw).
+ *   - A call that answered resets its tool's count (afterToolCallback),
+ *     unless the answer is itself reflection guidance.
+ *   - ADK runs a step's calls one after another; the native loop runs them
+ *     in parallel. The counts are kept in call order all the same: each
+ *     call's count waits for the calls before it (StepCorrection).
+ *
+ * The texts, the argument names and the counting quirks are ADK 2.2.0's
+ * (plugins/reflect_retry_*.js), the reflection tool's "attempt 1" included:
+ * it reads `retryCount` where the call carries `retry_count`.
+ * tests/selfCorrection.test.ts and tests/nativeLoop.test.ts hold the two
+ * runtimes to the same stored events.
+ *
+ * ADK stays out of this file but for the LlmResponse type the step already
+ * reads responses as.
+ */
+import type { LlmResponse } from '@google/adk';
+import type { Tool } from '../../tools/tool.ts';
+/** The syndicate's `retries:` key (lib/syndicateSchema.ts). */
+export interface Retries {
+    model_errors?: number;
+    tool_errors?: number;
+}
+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;
+    replaced: boolean;
+} | {
+    failed: {
+        code: string;
+        message: string;
+    };
+};
+/** The model side, for one agent's steps in one run (lib/runtime/native/step.ts). */
+export interface ModelCorrection {
+    /** 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. 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 {
+    /**
+     * The call threw, or named no tool: the guidance that answers it in place
+     * of the error, or undefined to answer the error as it is (a throw that is
+     * not an Error, which ADK hands to no plugin).
+     */
+    failed(toolName: string, args: Record<string, unknown>, error: unknown): Promise<Record<string, unknown> | undefined>;
+    /** The call answered: its tool's count starts again. */
+    answered(toolName: string, result: unknown): Promise<void>;
+}
+/** The tool side for one step's calls, counted in call order. `release(i)` when call i is done, whatever it did. */
+export interface StepCorrection {
+    call(index: number): CallCorrection;
+    release(index: number): void;
+}
+/**
+ * Self-correction for a run: ADK's two plugins, with their counters. One per
+ * turn, as runSyndicateTurn builds one pair of plugins per Runner; the
+ * counters are kept per run (invocation id) within it.
+ */
+export declare class SelfCorrection {
+    #private;
+    readonly modelErrors: number;
+    readonly toolErrors: number;
+    constructor(retries?: Retries);
+    /** The model side for `agentName`'s steps in run `invocationId`; undefined when model retries are off. */
+    forModel(agentName: string, invocationId: string): ModelCorrection | undefined;
+    /** The tool side for one step of `count` calls in run `invocationId`; undefined when tool retries are off. */
+    forCalls(invocationId: string, count: number): StepCorrection | undefined;
+}

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

@@ -0,0 +1,327 @@
+/**
+ * lib/runtime/native/selfCorrection.ts — self-correction on the native loop:
+ * a model error and a tool error retried with reflection, as ADK's
+ * reflect-and-retry plugins do it on the ADK runtime (ADR 0034, ADR 0075).
+ *
+ * WHY this file exists:
+ *   runSyndicateTurn installs ADK's ReflectAndRetryModelPlugin and
+ *   ReflectAndRetryToolPlugin on every Runner it builds, retries at their
+ *   defaults unless the syndicate's `retries:` says otherwise. They change
+ *   what the model is sent and what the store holds, so the native loop
+ *   does what they do, word for word, or a session one runtime wrote would
+ *   read differently on the other:
+ *
+ *   THE MODEL (`retries.model_errors`, default 2; 0 off):
+ *   - 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
+ *     tool: id `adk_handle_model_error_<uuid>`, the error in its arguments,
+ *     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.
+ *
+ *   THE TOOLS (`retries.tool_errors`, default 3; 0 off):
+ *   - A tool that throws an Error, and a call naming no tool, answer with
+ *     reflection guidance (onToolErrorCallback) in place of the plain error,
+ *     counted per tool name in the run; past the limit, the "retry limit
+ *     exceeded" guidance (the plugin is built not to throw).
+ *   - A call that answered resets its tool's count (afterToolCallback),
+ *     unless the answer is itself reflection guidance.
+ *   - ADK runs a step's calls one after another; the native loop runs them
+ *     in parallel. The counts are kept in call order all the same: each
+ *     call's count waits for the calls before it (StepCorrection).
+ *
+ * The texts, the argument names and the counting quirks are ADK 2.2.0's
+ * (plugins/reflect_retry_*.js), the reflection tool's "attempt 1" included:
+ * it reads `retryCount` where the call carries `retry_count`.
+ * tests/selfCorrection.test.ts and tests/nativeLoop.test.ts hold the two
+ * runtimes to the same stored events.
+ *
+ * ADK stays out of this file but for the LlmResponse type the step already
+ * 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';
+export const REFLECT_AND_RETRY_RESPONSE_TYPE = 'ERROR_HANDLED_BY_REFLECT_AND_RETRY_PLUGIN';
+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 {
+    #counts = new Map();
+    increment(scope, name) {
+        let counter = this.#counts.get(scope);
+        if (!counter) {
+            counter = new Map();
+            this.#counts.set(scope, counter);
+        }
+        const next = (counter.get(name) ?? 0) + 1;
+        counter.set(name, next);
+        return next;
+    }
+    reset(scope, name) {
+        const counter = this.#counts.get(scope);
+        if (!counter)
+            return;
+        counter.delete(name);
+        if (counter.size === 0)
+            this.#counts.delete(scope);
+    }
+}
+/**
+ * Self-correction for a run: ADK's two plugins, with their counters. One per
+ * turn, as runSyndicateTurn builds one pair of plugins per Runner; the
+ * counters are kept per run (invocation id) within it.
+ */
+export class SelfCorrection {
+    modelErrors;
+    toolErrors;
+    #models = new FailureTracker();
+    #tools = new FailureTracker();
+    constructor(retries = {}) {
+        this.modelErrors = retries.model_errors ?? DEFAULT_MODEL_ERROR_RETRIES;
+        this.toolErrors = retries.tool_errors ?? DEFAULT_TOOL_ERROR_RETRIES;
+        if (this.modelErrors < 0 || this.toolErrors < 0)
+            throw new Error('maxRetries must be a non-negative integer.');
+    }
+    /** The model side for `agentName`'s steps in run `invocationId`; undefined when model retries are off. */
+    forModel(agentName, invocationId) {
+        if (this.modelErrors <= 0)
+            return undefined;
+        const max = this.modelErrors;
+        const tracker = this.#models;
+        const name = agentName || 'default_model';
+        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.`;
+                return { failed: { code: 'UNKNOWN_ERROR', message: `Error in plugin '${MODEL_PLUGIN}' during 'afterModelCallback' callback: Error: ${thrown}` } };
+            }
+            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 }, ...(signature ? { thoughtSignature: signature } : {}) }],
+                },
+            };
+            return { response, replaced: true };
+        };
+        return {
+            tools: [reflectionTool(max)],
+            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', signature());
+                }
+                if (response.finishReason && MODEL_ERRORS.includes(response.finishReason)) {
+                    return retry(response.errorCode ?? 'MODEL_ERROR', response.errorMessage ?? 'Model error encountered.', response.finishReason, signature());
+                }
+                tracker.reset(invocationId, name);
+                return { response, replaced: false };
+            },
+        };
+    }
+    /** The tool side for one step of `count` calls in run `invocationId`; undefined when tool retries are off. */
+    forCalls(invocationId, count) {
+        if (this.toolErrors <= 0 || count === 0)
+            return undefined;
+        const max = this.toolErrors;
+        const tracker = this.#tools;
+        // Call i's count waits for calls 0..i-1: ADK counts in call order.
+        const done = [];
+        const settled = Array.from({ length: count }, (_, i) => new Promise((resolve) => (done[i] = resolve)));
+        const inTurn = async (index, op) => {
+            if (index > 0)
+                await settled[index - 1];
+            try {
+                return op();
+            }
+            finally {
+                done[index]?.();
+            }
+        };
+        return {
+            release: (index) => done[index]?.(),
+            call: (index) => ({
+                failed: (toolName, args, error) => inTurn(index, () => {
+                    if (!(error instanceof Error)) {
+                        tracker.reset(invocationId, toolName);
+                        return undefined;
+                    }
+                    const retries = tracker.increment(invocationId, toolName);
+                    return retries <= max ? toolReflection(toolName, args, error, retries, max) : toolRetryExceeded(toolName, args, error, max);
+                }),
+                answered: (toolName, result) => inTurn(index, () => {
+                    const reflected = !!result && typeof result === 'object' && result.response_type === REFLECT_AND_RETRY_RESPONSE_TYPE;
+                    if (!reflected)
+                        tracker.reset(invocationId, toolName);
+                }),
+            }),
+        };
+    }
+}
+// ── The reflection tool and the texts ────────────────────────────────────────
+/** The reflection tool as the model plugin declares it: a FunctionTool with no parameters. */
+function reflectionTool(maxRetries) {
+    return {
+        name: ADK_HANDLE_MODEL_ERROR,
+        declaration: () => ({
+            name: ADK_HANDLE_MODEL_ERROR,
+            description: 'A tool that triggers reflection. Reserved for internal framework use only. Do not call directly.',
+            parameters: { type: 'object', properties: {} },
+        }),
+        // ADK's adkHandleModelError reads `retryCount`; the call carries `retry_count`, so it says attempt 1.
+        execute: async (args) => {
+            const attempt = args.retryCount ?? 1;
+            return {
+                reflection_guidance: `
+The call to the model failed.
+
+**Reflection Guidance:**
+- This is retry attempt **${String(attempt)}** of **${maxRetries}**
+- Analyze the error and the arguments you provided. Do not repeat the exact same call.
+
+Formulate a new plan based on your analysis and try a corrected or different approach.
+`.trim(),
+            };
+        },
+    };
+}
+const errorDetailsOf = (error) => `${error.name || 'Error'}: ${error.message}`;
+function toolReflection(toolName, args, error, retryCount, maxRetries) {
+    const reflectionMessage = `
+The call to tool \`${toolName}\` failed.
+
+**Error Details:**
+\`\`\`
+${errorDetailsOf(error)}
+\`\`\`
+
+**Tool Arguments Used:**
+\`\`\`json
+${JSON.stringify(args ?? {}, null, 2)}
+\`\`\`
+
+**Reflection Guidance:**
+This is retry attempt **${retryCount} of ${maxRetries}**. Analyze the error and the arguments you provided. Do not repeat the exact same call. Consider the following before your next attempt:
+
+1.  **Invalid Parameters**: Does the error suggest that one or more arguments are incorrect, badly formatted, or missing? Review the tool's schema and your arguments.
+2.  **State or Preconditions**: Did a previous step fail or not produce the necessary state/resource for this tool to succeed?
+3.  **Alternative Approach**: Is this the right tool for the job? Could another tool or a different sequence of steps achieve the goal?
+4.  **Simplify the Task**: Can you break the problem down into smaller, simpler steps?
+5.  **Wrong Function Name**: Does the error indicates the tool is not found? Please check again and only use available tools.
+
+Formulate a new plan based on your analysis and try a corrected or different approach.
+`.trim();
+    return {
+        response_type: REFLECT_AND_RETRY_RESPONSE_TYPE,
+        error_type: error.name || 'Error',
+        error_details: error.message,
+        retry_count: retryCount,
+        reflection_guidance: reflectionMessage,
+    };
+}
+function toolRetryExceeded(toolName, args, error, maxRetries) {
+    const reflectionMessage = `
+The tool \`${toolName}\` has failed consecutively ${maxRetries} times and the retry limit has been exceeded.
+
+**Last Error:**
+\`\`\`
+${errorDetailsOf(error)}
+\`\`\`
+
+**Last Arguments Used:**
+\`\`\`json
+${JSON.stringify(args ?? {}, null, 2)}
+\`\`\`
+
+**Final Instruction:**
+**Do not attempt to use the \`${toolName}\` tool again for this task.** You must now try a different approach. Acknowledge the failure and devise a new strategy, potentially using other available tools or informing the user that the task cannot be completed.
+`.trim();
+    return {
+        response_type: REFLECT_AND_RETRY_RESPONSE_TYPE,
+        error_type: error.name || 'Error',
+        error_details: error.message,
+        retry_count: maxRetries,
+        reflection_guidance: reflectionMessage,
+    };
+}

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

@@ -0,0 +1,156 @@
+/**
+ * lib/runtime/native/step.ts — one model step of the native loop: build the
+ * request, call the adapter under the turn's controls, and record the
+ * model's answer as the event ADK would have stored (ADR 0045, ADR 0066).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime one step is LlmAgent.runOneStepAsync: build the
+ *   request, call the model through the shim (lib/models/adkShim.ts), turn
+ *   each response into an event, and let the Runner store the ones that are
+ *   not partial. The native loop does the same with no ADK in the path, and
+ *   a session either runtime wrote must be one the other can continue, so
+ *   each piece matches:
+ *
+ *   - THE CALL'S CONTROLS (ADR 0053). The native loop is the adapter's
+ *     caller, so it charges the turn and opens the llm.request span, through
+ *     the same traceLlmGeneration call the shim makes, with the adapter's
+ *     provider, the agent's model id and the request. The step budget, the
+ *     token charge and the span's attributes are therefore the same on both
+ *     runtimes. A turn that has stopped (cancel, deadline, the step limit)
+ *     gets no call and no event: ADK checks the run's signal before the call
+ *     and after each response and returns without an event, and the turn
+ *     runner reports the stop from the turn's control. So does this step.
+ *   - 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. 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
+ *     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/
+ *     errorResponse.ts) is handed to it as a retryable failed final, so the
+ *     fallback answers when nothing was produced yet (FallbackLlm). Any
+ *     other thrown Error ends the step on ADK's error event for it
+ *     (runAndHandleError): UNKNOWN_ERROR, or the code a JSON error message
+ *     names, with the message, key-shaped text scrubbed. A throw that is
+ *     not an Error, or one while the turn is stopping, is rethrown.
+ *   - STORAGE. A final event is appended through the SessionService, which
+ *     applies the store's own rules (trimming, state). A partial event is
+ *     handed to the caller for streaming and stored nowhere.
+ *
+ * WHAT IT RETURNS: the request sent, the stored event, and the answer parsed
+ * into text, thinking (from the partials: a final never holds thinking) and
+ * tool calls with the ids as stored, and the tools the request declared.
+ * Running those calls, and looping, is lib/runtime/native/agentLoop.ts.
+ */
+import type { FinalModelResponse, ModelAdapter, ModelError, ModelRequest, ToolCallPart } from '../../models/contract.ts';
+import type { MemoryService } from '../memoryService.ts';
+import type { TurnContent, TurnEvent } from '../events.ts';
+import type { Session, SessionService } from '../sessions.ts';
+import type { NativeAgent, WorkflowInstructionScope } from './request.ts';
+import type { ModelCorrection } from './selfCorrection.ts';
+export interface ModelStepOptions {
+    agent: NativeAgent;
+    /** The session as it stands, the run's user event already appended. Appending updates it. */
+    session: Session;
+    sessions: SessionService;
+    /** The run's id: every event of the run carries it. */
+    invocationId: string;
+    /** The message that started the run. */
+    userContent?: TurnContent;
+    branch?: string;
+    isolationScope?: string;
+    /** The run's root agent, whose globalInstruction applies. Default: the agent. */
+    root?: Pick<NativeAgent, 'globalInstruction'>;
+    /** The run's memory, already namespaced. */
+    memory?: Pick<MemoryService, 'search'>;
+    /** The leaf adapter to call. Default: resolveAdapter(agent.model) (lib/models/registry.ts). */
+    adapter?: ModelAdapter;
+    /** Stream text and thinking deltas as partial events. Default false. */
+    stream?: boolean;
+    /** The run's signal. Default: the current turn's (lib/runtime/turnControl.ts). */
+    signal?: AbortSignal;
+    /** Each partial event, as it arrives. Never stored. */
+    onPartial?: (event: TurnEvent) => void;
+    /**
+     * The model id the request is sent under. Default the agent's. A fallback
+     * model answers the request built for the agent's own model, under its own
+     * id, as ADK's FallbackLlm sends it (ADR 0044).
+     */
+    model?: string;
+    /** Called on the final event just before it is stored: the loop saves the agent's outputKey here, as ADK does before its Runner appends. */
+    beforeAppend?: (event: TurnEvent) => void;
+    /** State laid over the session's when the request is built: the run's `temp:` keys (lib/runtime/native/tempState.ts). */
+    stateOverlay?: Readonly<Record<string, unknown>>;
+    /**
+     * Called on each failed final, with whether the adapter had yielded
+     * anything before it. True hands the failure back unstored (`redirected`):
+     * a fallback model answers the step instead (ADR 0044, ADR 0053).
+     */
+    redirect?: (final: FinalModelResponse, produced: boolean) => boolean;
+    /**
+     * Self-correction's model side (lib/runtime/native/selfCorrection.ts):
+     * its reflection tool is declared after the agent's tools, and every
+     * response passes through it before it is recorded, as ADK's
+     * reflect-and-retry model plugin sees it.
+     */
+    correction?: ModelCorrection;
+    /** A workflow agent node's run: fills the instruction's workflow placeholders (request.ts, WorkflowInstructionScope). */
+    workflowScope?: WorkflowInstructionScope;
+}
+/** Why a step made no call, or stopped answering: the turn's own stop. */
+export interface StepStop {
+    code: string;
+    message: string;
+}
+export interface ModelStepResult {
+    /** The request sent, or that would have been sent when the turn had stopped. */
+    request: ModelRequest;
+    /** The final event as the store returned it. Absent when the turn stopped or the answer was empty. */
+    event?: TurnEvent;
+    /** The adapter's final response. */
+    response?: FinalModelResponse;
+    /** The answer's text, thinking aside. */
+    text: string;
+    /** The model's reasoning as the partials showed it. Display only. */
+    thinking: string;
+    /** The calls the model made, with the ids as stored. */
+    toolCalls: ToolCallPart[];
+    /** The calls among them that wait for a person. */
+    longRunningToolIds: string[];
+    /** The call failed: the adapter's error. */
+    error?: ModelError;
+    /** The turn stopped before or during the call: no event was made for it. */
+    stopped?: StepStop;
+    /** The failure `redirect` took: nothing was stored for it. */
+    redirected?: ModelError;
+    /** 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;
+/** The turn's stop, as the turn runner reports it; a cancel when the signal aborted outside a turn. */
+/** The turn's stop, as a step reports it. */
+export declare function stopOf(): StepStop;
+/**
+ * One model step for `agent`. Never throws for a failed call: the error is
+ * on the result and on the stored event, as on the ADK runtime, also when
+ * the adapter throws an Error, which the contract forbids. Throws when the
+ * request cannot be built (as ADK does).
+ */
+export declare function runModelStep(options: ModelStepOptions): Promise<ModelStepResult>;