melchizedek-agents 0.18.0 → 0.20.0

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

@@ -0,0 +1,705 @@
+/**
+ * lib/runtime/native/agentLoop.ts — the native loop for one agent: a model
+ * step, the step's tool calls, their results fed back, until the model
+ * stops calling tools or the turn stops it (ADR 0045, ADR 0066).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime this is LlmAgent.runAsyncImpl: run one step
+ *   (lib/runtime/native/step.ts is the native step), run the answer's
+ *   function calls (ADK's handleFunctionCallList), store the response
+ *   event, and step again unless the last event is a final response. A
+ *   session either runtime wrote must be one the other continues, so every
+ *   event this loop stores is the one ADK stores for the same answer and the
+ *   same tool results, ids and times aside. tests/nativeLoop.test.ts runs
+ *   the boundary suite's single-agent cases both ways and compares.
+ *
+ * ONE STEP, AS ADK RUNS IT:
+ *   1. The model step (runModelStep). Its partial events are yielded as they
+ *      arrive and stored nowhere, so drainAgentStream hands their text to
+ *      onTextDelta exactly as it does on the ADK path. With a
+ *      `fallback_model`, the step runs once per leaf adapter (ADR 0053): a
+ *      provider-side failure before anything was produced is not stored,
+ *      and the fallback answers the same request under its own model id, by
+ *      ADK's FallbackLlm's rules and the shared circuit breaker (ADR 0044).
+ *   2. The answer's calls run in parallel, each with its own context (its
+ *      own state delta and actions). Results are kept in call order:
+ *      - a call naming no declared tool answers
+ *        `{ error: "Function <name> is not found in the toolsDict." }`;
+ *      - a tool that throws answers `{ error: "Error in tool '<name>': …" }`,
+ *        the text ADK's FunctionTool writes (lib/tools/adkTool.ts);
+ *      - with self-correction's tool side on (retries.tool_errors, default
+ *        3), those two answer with reflection guidance instead, counted per
+ *        tool in call order (lib/runtime/native/selfCorrection.ts);
+ *      - a tool that requires approval and has none asks for it, as
+ *        FunctionTool's gate does: `{ error: APPROVAL_TEXTS.pending }`,
+ *        `skipSummarization`, and the request under the call's id;
+ *      - 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;
+ *      - 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
+ *      another and lets a call read the state an earlier call of the same
+ *      step wrote; here each call reads the state as the step left it.
+ *   3. An approval request ends the run: the response is NOT stored; in its
+ *      place the event ADK stores, a call to `adk_request_confirmation`
+ *      (args: the original call and the confirmation; an `adk-` id listed in
+ *      longRunningToolIds), carrying the response's actions. The answer
+ *      resumes it: before each step, lib/runtime/native/interrupts.ts runs
+ *      the pinned call the latest user message approves or refuses, as ADK's
+ *      request-confirmation processor does, and its response is stored
+ *      before the request is built.
+ *   4. The agent's outputKey is written into each final event's stateDelta
+ *      before it is stored (ADK's maybeSaveOutputToState, case for case).
+ *      The `temp:` keys of every event stored are kept for the rest of the
+ *      run, beside the session and never in it, and each later step and
+ *      call reads them (lib/runtime/native/tempState.ts).
+ *   5. The loop goes on unless the step's last event is final (ADK's
+ *      isFinalResponse), the turn stopped the step, or the step stored
+ *      nothing. A model call that waits on a person (ask_user) is final: its
+ *      model event lists the call in longRunningToolIds, and the run ends
+ *      with no response to it, the call pending. The answer resumes it: the
+ *      turn runner stores the person's next message as the call's function
+ *      response, and the next run's first step reads the call and its answer
+ *      from the history (history.ts), as ADK's content processor does. No
+ *      request processor acts on it (ADR 0079).
+ *
+ * DELEGATION: a call to a subagent tool runs the subagent as its own child
+ * loop, as ADK's AgentTool runs it (lib/runtime/native/delegate.ts, ADR 0074).
+ *
+ * SELF-CORRECTION (ADR 0034, ADR 0075) is ADK's reflect-and-retry plugins,
+ * ported to lib/runtime/native/selfCorrection.ts: the step declares the
+ * reflection tool and passes each response through its model side, and
+ * each call's error or answer goes through its tool side. On by default,
+ * as runSyndicateTurn installs the plugins by default.
+ *
+ * COMPACTION (ADR 0033): with the agent's `context:`, each step may first
+ * store ADK's compacted event, written by the summary model
+ * (lib/runtime/native/compaction.ts). It is yielded like any stored event
+ * and is not the run's `lastEvent`.
+ *
+ * TASK MODE (ADR 0033, ADR 0081): finish_task is an own tool the request
+ * declares; a run marked `taskNode` ends on its successful answer
+ * (lib/runtime/native/taskMode.ts).
+ *
+ * WORKFLOW NODES (ADR 0090): a run for a workflow agent node passes
+ * `nodeStamp`, which writes the node's output and path on each event before
+ * it is stored (lib/workflow/agentNode.ts).
+ *
+ * CONSENT (WS6-3b, ADR 0085): with `credentials`, each call's
+ * `accessToken(provider)` reads the user's grant (ADR 0072). With `consent`,
+ * a call whose provider the user has not granted asks for it
+ * (`requestCredential`, or `accessToken` by itself): the call answers
+ * CONSENT_TEXTS.pending, ADK's `adk_request_credential` event is stored
+ * before the response (ADK's generateAuthEvent), and the run ends paused on
+ * it. The flow's secrets stay in the consent step (lib/tools/oauthConsent.ts).
+ * Before each step, a credential request the latest user message answers
+ * runs its paused call again (interrupts.ts grantedCalls, ADK's auth
+ * preprocessor), ahead of the approval resume.
+ *
+ * NOT HERE (later tickets): transfer_to_agent (no compiled syndicate sets
+ * subAgents). The run's spans (agent.invoke, model.call,
+ * tool.execute) are lib/runtime/native/telemetry.ts.
+ *
+ * ADK stays out of this file: an ADK tool an agent still lists during the
+ * dual period (a registry FunctionTool, the skills toolset's tools) is run
+ * through its runAsync with a context shaped like ADK's, by shape.
+ */
+import { randomUUID } from 'node:crypto';
+import { circuitOpen, recordFailure, recordSuccess } from '../../models/circuitBreaker.js';
+import { providerForModel } from '../../models/providerMap.js';
+import { resolveAdapter } from '../../models/registry.js';
+import { toContractJsonSchema } from '../../models/schemaNormalize.js';
+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, runWorkflowSubagent, subagentOf, workflowSubagentOf } from './delegate.js';
+import { approvedCalls, grantedCalls } from './interrupts.js';
+import { SelfCorrection } from './selfCorrection.js';
+import { eitherSignal, runModelStep, stopOf } from './step.js';
+import { taskNodeRun } from './taskMode.js';
+import { createRunTempState, withStateOverlay } from './tempState.js';
+import { traceAgentInvocation, traceModelCall, traceToolCall } from './telemetry.js';
+/** ADK's own ceiling on model calls in one run (RunConfig.maxLlmCalls); the turn's max_steps is lower. */
+const MAX_LLM_CALLS = 500;
+// ── Events as ADK makes them ─────────────────────────────────────────────────
+const REQUEST_CONFIRMATION = 'adk_request_confirmation';
+const REQUEST_CREDENTIAL = 'adk_request_credential';
+const isEmptyRecord = (r) => !r || Object.keys(r).length === 0;
+/** Sets an own property even for a key such as `__proto__`. */
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** ADK's isDefaultEventActions. */
+function isDefaultActions(a) {
+    return (isEmptyRecord(a.stateDelta) &&
+        isEmptyRecord(a.artifactDelta) &&
+        isEmptyRecord(a.requestedAuthConfigs) &&
+        isEmptyRecord(a.requestedToolConfirmations) &&
+        a.skipSummarization === undefined &&
+        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)
+            assignOwn(out.stateDelta, s.stateDelta);
+        if (s.artifactDelta)
+            assignOwn(out.artifactDelta, s.artifactDelta);
+        if (s.requestedAuthConfigs)
+            assignOwn(out.requestedAuthConfigs, s.requestedAuthConfigs);
+        if (s.requestedToolConfirmations)
+            assignOwn(out.requestedToolConfirmations, s.requestedToolConfirmations);
+        if (s.skipSummarization !== undefined)
+            out.skipSummarization = s.skipSummarization;
+        if (s.transferToAgent !== undefined)
+            out.transferToAgent = s.transferToAgent;
+        if (s.escalate !== undefined)
+            out.escalate = s.escalate;
+    }
+    return out;
+}
+// ── outputKey (ADK's maybeSaveOutputToState) ─────────────────────────────────
+const validators = new WeakMap();
+/** The output schema as a validator, as ADK reads it (z.fromJSONSchema); null when it cannot be read. */
+function validatorFor(schema) {
+    let v = validators.get(schema);
+    if (v !== undefined)
+        return v;
+    try {
+        v = z.fromJSONSchema(toContractJsonSchema(schema));
+    }
+    catch {
+        v = null;
+    }
+    validators.set(schema, v);
+    return v;
+}
+/**
+ * Writes the agent's final answer into `event`'s stateDelta under its
+ * outputKey: the text of its parts; with an output schema, the parsed and
+ * validated JSON (the text itself when it does not parse; the parsed value
+ * when it does not validate).
+ */
+export function saveOutput(agent, event) {
+    if (event.author !== agent.name || !agent.outputKey || !isFinal(event))
+        return;
+    const parts = event.content?.parts;
+    if (!parts?.length)
+        return;
+    const text = parts.map((p) => (p.text ? p.text : '')).join('');
+    const delta = (event.actions.stateDelta ??= {});
+    let result = text;
+    if (agent.outputSchema) {
+        if (!text.trim())
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            setOwn(delta, agent.outputKey, text);
+            return;
+        }
+        try {
+            const validator = validatorFor(agent.outputSchema);
+            result = validator ? validator.parse(parsed) : parsed;
+        }
+        catch {
+            result = parsed;
+        }
+    }
+    setOwn(delta, agent.outputKey, result);
+}
+function callContext(scope, functionCallId, confirmation) {
+    const { agent, ctx, stateBase } = scope;
+    const session = ctx.session;
+    const actions = createEventActions();
+    const delta = actions.stateDelta;
+    const state = {
+        get: (key, fallback) => (Object.hasOwn(delta, key) ? delta[key] : Object.hasOwn(stateBase, key) ? stateBase[key] : fallback),
+        set: (key, value) => setOwn(delta, key, value),
+        has: (key) => Object.hasOwn(delta, key) || Object.hasOwn(stateBase, key),
+    };
+    const memory = ctx.memory;
+    // ADK's Context.requestCredential, with the flow held server-side (ADR 0085): the request, keyed by the call's id.
+    const consent = ctx.consent;
+    const requestCredential = consent && functionCallId
+        ? async (provider) => {
+            const request = await consent.begin({ appName: session.appName, userId: session.userId, sessionId: session.id, functionCallId, provider });
+            // 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;
+    const readToken = credentials ? toolAccessToken(credentials, session.appName, session.userId, scope.signal) : undefined;
+    // A grant the user has not given (or that can no longer be renewed) is asked for, when the provider has a consent step.
+    const accessToken = readToken
+        ? async (provider) => {
+            try {
+                return await readToken(provider);
+            }
+            catch (error) {
+                const ask = error instanceof ToolCredentialError && (error.code === 'not_connected' || error.code === 'expired' || error.code === 'refresh_failed');
+                if (ask && requestCredential && consent?.has(provider))
+                    await requestCredential(provider);
+                throw error;
+            }
+        }
+        : undefined;
+    return {
+        invocationId: ctx.invocationId,
+        agentName: agent.name,
+        functionCallId,
+        userId: session.userId,
+        appName: session.appName,
+        sessionId: session.id,
+        state,
+        get stateDelta() {
+            return delta;
+        },
+        actions,
+        // ADK's Context.requestConfirmation: the request, keyed by the call's id.
+        requestConfirmation: ({ hint, payload } = {}) => {
+            if (!functionCallId)
+                throw new Error('functionCallId is not set.');
+            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,
+        toolConfirmation: confirmation,
+        signal: scope.signal,
+        abortSignal: scope.signal,
+        ...(ctx.userContent ? { userContent: ctx.userContent } : {}),
+        ...(memory
+            ? { searchMemory: (query) => memory.search({ appName: session.appName, userId: session.userId, query }) }
+            : {}),
+        ...(accessToken ? { accessToken } : {}),
+        ...(requestCredential ? { requestCredential } : {}),
+        invocationContext: {
+            invocationId: ctx.invocationId,
+            agent: { name: agent.name },
+            branch: ctx.branch,
+            session,
+            userContent: ctx.userContent,
+        },
+    };
+}
+/** 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)
+        return { result: value };
+    if (Array.isArray(value))
+        return { results: value };
+    return value;
+}
+function isAdkShaped(tool) {
+    return !!tool && typeof tool === 'object' && typeof tool.runAsync === 'function';
+}
+/** An own Tool's call, as FunctionTool runs it on the ADK path: its approval gate, then execute, a throw named for the tool. */
+async function runOwnTool(tool, args, context) {
+    try {
+        if (tool.requiresApproval === true) {
+            if (!context.confirmation) {
+                context.requestConfirmation({ hint: APPROVAL_TEXTS.hint(tool.name) });
+                context.actions.skipSummarization = true;
+                return { error: APPROVAL_TEXTS.pending };
+            }
+            if (!context.confirmation.confirmed)
+                return { error: APPROVAL_TEXTS.rejected };
+        }
+        return await tool.execute(args, context);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Error in tool '${tool.name}': ${message}`);
+    }
+}
+async function runCall(scope, call, tools, correction, confirmation) {
+    const context = callContext(scope, call.id || undefined, confirmation);
+    const name = call.name ?? '';
+    const tool = name && tools.has(name) ? tools.get(name) : undefined;
+    const callable = isTool(tool) || isAdkShaped(tool);
+    if (!callable) {
+        const toolName = name || '<unnamed>';
+        const notFound = `Function ${toolName} is not found in the toolsDict.`;
+        const guided = await correction?.failed(toolName, call.args ?? {}, new Error(notFound));
+        const part = {
+            functionResponse: { name: toolName, response: guided ?? { error: notFound }, id: context.functionCallId },
+        };
+        return { part, actions: context.actions };
+    }
+    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, 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, 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;
+        // Self-correction answers a thrown Error with reflection guidance in its place; a call waiting on a grant is not a failure.
+        const guided = isEmptyRecord(context.actions.requestedAuthConfigs) ? await correction?.failed(toolName, args, e) : undefined;
+        if (guided)
+            [response, failure] = [guided, undefined];
+    }
+    // Consent hook (WS6-3b, ADR 0085): a call that asked for a grant answers that it waits, whatever it returned or threw.
+    const asked = Object.values(context.actions.requestedAuthConfigs ?? {});
+    if (asked.length > 0) {
+        const provider = String(asked[0]?.credentialKey ?? '');
+        return { part: { functionResponse: { id: context.functionCallId, name: toolName, response: { result: CONSENT_TEXTS.pending(provider) } } }, actions: context.actions };
+    }
+    if (failure === undefined)
+        await correction?.answered(toolName, response);
+    // As ADK: a long-running call with no response answers nothing, even when it threw.
+    if (longRunning && (response === null || response === undefined)) {
+        return isDefaultActions(context.actions) ? undefined : { actions: context.actions };
+    }
+    const answer = failure ? { error: failure } : response === null || response === undefined ? { result: response } : asResponse(response);
+    // 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
+ * (not yet stored); undefined when none answered. `confirmations` holds the
+ * person's answer for a pinned call an approval resumes, by call id.
+ */
+async function runCalls(scope, calls, tools, confirmations) {
+    const order = scope.selfCorrection?.forCalls(scope.ctx.invocationId, calls.length);
+    const outcomes = (await Promise.all(calls.map((call, i) => traceToolCall(call, tools.get(call.name ?? ''), () => runCall(scope, call, tools, order?.call(i), call.id ? confirmations?.get(call.id) : undefined)).finally(() => order?.release(i))))).filter((o) => !!o);
+    if (outcomes.length === 0)
+        return undefined;
+    const base = { invocationId: scope.ctx.invocationId, author: scope.agent.name };
+    const contentOf = (parts) => ({ role: 'user', parts });
+    if (outcomes.length === 1) {
+        const [only] = outcomes;
+        return createTurnEvent({
+            ...base,
+            ...(only.part ? { content: contentOf([only.part]) } : {}),
+            actions: only.actions,
+            branch: scope.ctx.branch,
+        });
+    }
+    return createTurnEvent({
+        ...base,
+        branch: scope.ctx.branch,
+        content: contentOf(outcomes.flatMap((o) => (o.part ? [o.part] : []))),
+        actions: mergeActions(outcomes.map((o) => o.actions)),
+    });
+}
+/** ADK's generateAuthEvent: a credential request per call that asked for one. */
+function authEvent(scope, response) {
+    const configs = response.actions.requestedAuthConfigs;
+    if (isEmptyRecord(configs))
+        return undefined;
+    const parts = Object.entries(configs).map(([callId, authConfig]) => ({
+        functionCall: { name: REQUEST_CREDENTIAL, args: { function_call_id: callId, auth_config: authConfig }, id: `${ADK_CALL_ID_PREFIX}${randomUUID()}` },
+    }));
+    return createTurnEvent({
+        invocationId: scope.ctx.invocationId,
+        author: scope.agent.name,
+        branch: scope.ctx.branch,
+        content: { parts, role: response.content?.role ?? 'user' },
+        longRunningToolIds: parts.map((p) => p.functionCall?.id),
+    });
+}
+/** ADK's generateRequestConfirmationEvent: an adk_request_confirmation call per gated call, carrying the response's actions. */
+function confirmationEvent(scope, modelEvent, response) {
+    const requested = response.actions.requestedToolConfirmations;
+    if (isEmptyRecord(requested))
+        return undefined;
+    const calls = getFunctionCalls(modelEvent);
+    const parts = [];
+    for (const [callId, toolConfirmation] of Object.entries(requested)) {
+        const originalFunctionCall = calls.find((c) => c.id === callId);
+        if (!originalFunctionCall)
+            continue;
+        parts.push({ functionCall: { name: REQUEST_CONFIRMATION, args: { originalFunctionCall, toolConfirmation }, id: `${ADK_CALL_ID_PREFIX}${randomUUID()}` } });
+    }
+    return createTurnEvent({
+        invocationId: scope.ctx.invocationId,
+        author: scope.agent.name,
+        branch: scope.ctx.branch,
+        content: { parts, role: response.content?.role ?? 'user' },
+        actions: response.actions,
+        longRunningToolIds: parts.map((p) => p.functionCall?.id),
+    });
+}
+/**
+ * ADK's request-confirmation processor, before a step: the pinned calls the
+ * latest user message approves or refuses run with the answer in their
+ * context, and their response is returned to be stored (interrupts.ts). Undefined when
+ * there is none; 'stopped' when the turn stopped while they ran (nothing is
+ * stored). Throws IntentMismatchError when an answer does not bind.
+ */
+async function resumeApprovals(agent, ctx, stateBase, selfCorrection) {
+    const signal = eitherSignal(ctx.signal, currentTurnSignal());
+    const scope = { agent, ctx, stateBase, selfCorrection, ...(signal ? { signal } : {}) };
+    const approved = await approvedCalls(agent, ctx, (id) => callContext(scope, id));
+    if (!approved)
+        return undefined;
+    const response = await runCalls(scope, approved.calls, approved.tools, approved.confirmations);
+    if (signal?.aborted)
+        return 'stopped';
+    return response;
+}
+/**
+ * ADK's auth preprocessor, before a step (ADR 0085): the paused calls whose
+ * credential requests the latest user message answers run again, now with
+ * the grant in the store (interrupts.ts grantedCalls). Returns their
+ * response and the credential request a call raised again, if any, to be
+ * stored; undefined when there is none; 'stopped' when the turn stopped
+ * while they ran.
+ */
+async function resumeGrants(agent, ctx, stateBase, selfCorrection) {
+    const granted = await grantedCalls(agent, ctx);
+    if (!granted)
+        return undefined;
+    const signal = eitherSignal(ctx.signal, currentTurnSignal());
+    const scope = { agent, ctx, stateBase, selfCorrection, ...(signal ? { signal } : {}) };
+    const response = await runCalls(scope, granted.calls, granted.tools);
+    if (signal?.aborted)
+        return 'stopped';
+    if (!response)
+        return undefined;
+    const auth = authEvent(scope, response);
+    return { response, ...(auth ? { auth } : {}) };
+}
+// ── The model step, with partials and the fallback ───────────────────────────
+/** Runs a step, yielding its partial events as they arrive; returns the step's result. */
+async function* withPartials(start) {
+    const queue = [];
+    let wake;
+    let done = false;
+    const settle = () => {
+        done = true;
+        wake?.();
+    };
+    const run = start((event) => {
+        queue.push(event);
+        wake?.();
+    });
+    run.then(settle, settle);
+    for (;;) {
+        while (queue.length > 0)
+            yield queue.shift();
+        if (done)
+            break;
+        await new Promise((resolve) => (wake = resolve));
+        wake = undefined;
+    }
+    return await run;
+}
+const hasParts = (event) => (event.content?.parts?.length ?? 0) > 0;
+/**
+ * One model step for the agent: its own model, and with a fallback_model
+ * the fallback by ADK's FallbackLlm's rules (ADR 0044), each a leaf adapter
+ * called by its own step (ADR 0053).
+ */
+async function* modelStep(agent, ctx, stepOptions) {
+    const adapterFor = ctx.adapterFor ?? resolveAdapter;
+    const fallbackId = agent.fallbackModel;
+    if (!fallbackId) {
+        return yield* withPartials((onPartial) => runModelStep({ ...stepOptions, adapter: adapterFor(agent.model), onPartial }));
+    }
+    const log = ctx.log ?? ((m) => console.warn(m));
+    const onFallback = (why) => {
+        log(`[models] ${why}; answering from ${fallbackId}.`);
+        return withPartials((onPartial) => runModelStep({ ...stepOptions, adapter: adapterFor(fallbackId), model: fallbackId, onPartial }));
+    };
+    const provider = providerForModel(agent.model);
+    if (circuitOpen(provider))
+        return yield* onFallback(`${provider} circuit is open`);
+    let answered = false;
+    const first = yield* withPartials((onPartial) => runModelStep({
+        ...stepOptions,
+        adapter: adapterFor(agent.model),
+        onPartial: (event) => {
+            if (hasParts(event))
+                answered = true;
+            onPartial(event);
+        },
+        // FallbackLlm: a retryable failure counts against the provider, and redirects when nothing was produced.
+        redirect: (final, produced) => {
+            if (!final.error?.retryable)
+                return false;
+            recordFailure(provider);
+            return !produced && final.parts.length === 0;
+        },
+    }));
+    if (first.redirected) {
+        return yield* onFallback(`${agent.model} failed (${first.redirected.code}: ${first.redirected.message.slice(0, 120)})`);
+    }
+    if (first.event && hasParts(first.event))
+        answered = true;
+    if (answered && !first.error && !first.stopped)
+        recordSuccess(provider);
+    return first;
+}
+// ── The loop ─────────────────────────────────────────────────────────────────
+/**
+ * Runs `agent` on the session in `ctx` until its answer is final, yielding
+ * every event in order: partials as they arrive (never stored), then each
+ * event as the store returned it. Returns how the run ended.
+ *
+ * Never throws for a failed model call or a failing tool: the first is the
+ * last event, stored with its error, the second the call's error response.
+ * An adapter that throws an Error ends the step on ADK's error event for
+ * it (lib/runtime/native/step.ts). Throws where the ADK runtime throws: a
+ * request that cannot be built, a store that throws.
+ */
+export function runAgentLoop(agent, ctx) {
+    // Telemetry hook (WS2-11, lib/runtime/native/telemetry.ts): the run is an agent.invoke span.
+    return traceAgentInvocation(agent, ctx, () => agentLoop(agent, ctx));
+}
+async function* agentLoop(agent, ctx) {
+    const { session, sessions } = ctx;
+    // The run's temp: keys, read from each event before the store drops them (lib/runtime/native/tempState.ts).
+    const runTemp = createRunTempState();
+    // Task-mode hook (WS3-5): a task node's run ends on finish_task's successful answer.
+    const task = ctx.taskNode && agent.mode === 'task' ? taskNodeRun(agent) : undefined;
+    const beforeStore = (event) => {
+        saveOutput(agent, event);
+        task?.beforeStore(event);
+        ctx.nodeStamp?.(event);
+        runTemp.record(event);
+    };
+    const store = async (event) => {
+        beforeStore(event);
+        return sessions.append(session, event);
+    };
+    let steps = 0;
+    let lastEvent;
+    const selfCorrection = ctx.selfCorrection ?? new SelfCorrection();
+    const correction = selfCorrection.forModel(agent.name, ctx.invocationId);
+    for (;;) {
+        // Consent hook (WS6-3b, interrupts.ts): a granted credential request runs its paused call again before the step, as ADK's auth preprocessor
+        // does, ahead of the approval resume as ADK orders its processors. A call that asks again pauses the run on its new request.
+        const regranted = await resumeGrants(agent, ctx, withStateOverlay(session.state, runTemp.values()), selfCorrection);
+        if (regranted === 'stopped')
+            return { reason: 'stopped', steps, lastEvent, stop: stopOf() };
+        if (regranted) {
+            if (regranted.auth) {
+                lastEvent = await store(regranted.auth);
+                yield lastEvent;
+            }
+            const pausedOn = regranted.auth ? [...(lastEvent?.longRunningToolIds ?? [])] : [];
+            lastEvent = await store(regranted.response);
+            yield lastEvent;
+            if (pausedOn.length > 0)
+                return { reason: 'paused', steps, lastEvent, pending: pausedOn };
+        }
+        // Interrupts hook (WS2-7a, interrupts.ts): an answered approval runs its pinned call before the step, as ADK's request-confirmation processor does; it runs
+        // first, then compaction (ADK inserts its compactor before the contents processor), both before the step budget. ADK's request-input processor sits
+        // between them and resumes node-tool calls only, which no native agent lists; an answered ask_user needs none (interrupts.ts, ADR 0079).
+        const resumed = await resumeApprovals(agent, ctx, withStateOverlay(session.state, runTemp.values()), selfCorrection);
+        if (resumed === 'stopped')
+            return { reason: 'stopped', steps, lastEvent, stop: stopOf() };
+        if (resumed) {
+            lastEvent = await store(resumed);
+            yield lastEvent;
+        }
+        // Compaction hook (WS2-9, lib/runtime/native/compaction.ts): with `context:`, the summary is stored before the step reads the history,
+        // before the step budget, as ADK's request processors run before its call count.
+        const compacted = await compactBeforeStep(agent, {
+            session,
+            adapterFor: ctx.adapterFor ?? resolveAdapter,
+            ...(ctx.branch !== undefined ? { branch: ctx.branch } : {}),
+            ...(ctx.isolationScope !== undefined ? { isolationScope: ctx.isolationScope } : {}),
+            ...(currentTurnSignal() ? { signal: currentTurnSignal() } : {}),
+        });
+        if (compacted) {
+            // As ADK's Runner: a turn that stopped during the summary stores nothing and makes no step.
+            if (ctx.signal?.aborted || currentTurnSignal()?.aborted)
+                return { reason: 'stopped', steps, lastEvent, stop: stopOf() };
+            // A workflow node's stamp (ADR 0093): ADK's node runner stamps the summary as it does every event its agent yields, and outside
+            // task mode its maybeSetOutput gives it the summary as output. The outputKey and task hooks never see it, as on ADK.
+            ctx.nodeStamp?.(compacted);
+            yield await sessions.append(session, compacted);
+        }
+        if (steps >= MAX_LLM_CALLS) {
+            return { reason: 'stopped', steps, lastEvent, stop: { code: 'STEP_LIMIT', message: `Max number of llm calls limit of ${MAX_LLM_CALLS} exceeded` } };
+        }
+        steps += 1;
+        // Telemetry hook: each step is a model.call span.
+        const step = yield* traceModelCall(agent, ctx, (traced) => modelStep(agent, traced, { ...traced, agent, beforeAppend: beforeStore, stateOverlay: runTemp.values(), ...(correction ? { correction } : {}) }));
+        if (step.stopped)
+            return { reason: 'stopped', steps, lastEvent, stop: step.stopped };
+        const modelEvent = step.event;
+        if (!modelEvent)
+            return { reason: 'empty', steps, lastEvent };
+        yield modelEvent;
+        lastEvent = modelEvent;
+        let stepEnd = modelEvent;
+        const hadCalls = getFunctionCalls(modelEvent).length > 0;
+        if (hadCalls) {
+            const scope = { agent, ctx, stateBase: withStateOverlay(session.state, runTemp.values()), selfCorrection, ...(step.request.signal ? { signal: step.request.signal } : {}) };
+            const response = await runCalls(scope, getFunctionCalls(modelEvent), step.tools);
+            // As ADK: a turn that stopped while the calls ran (a long subagent run, say) stores no response.
+            if (scope.signal?.aborted)
+                return { reason: 'stopped', steps, lastEvent, stop: stopOf() };
+            if (response) {
+                const auth = authEvent(scope, response);
+                if (auth) {
+                    lastEvent = await store(auth);
+                    yield lastEvent;
+                }
+                const authIds = auth ? [...(lastEvent.longRunningToolIds ?? [])] : [];
+                const confirmation = confirmationEvent(scope, modelEvent, response);
+                if (confirmation) {
+                    lastEvent = await store(confirmation);
+                    yield lastEvent;
+                    return { reason: 'paused', steps, lastEvent, pending: [...(lastEvent.longRunningToolIds ?? [])] };
+                }
+                lastEvent = await store(response);
+                yield lastEvent;
+                // As ADK: the response asking for auth is final, and the run waits on its credential request (ADR 0085).
+                if (authIds.length > 0)
+                    return { reason: 'paused', steps, lastEvent, pending: authIds };
+                stepEnd = lastEvent;
+                if (task?.finished)
+                    return { reason: 'final', steps, lastEvent, output: task.output };
+            }
+        }
+        // ADK's runAsyncImpl: stop on a final event, unless it is an empty metadata event after tool calls.
+        const emptyMetadata = stepEnd.author === agent.name && !stepEnd.partial && !hasParts(stepEnd) && isDefaultActions(stepEnd.actions);
+        if (isFinal(stepEnd) && !(emptyMetadata && hadCalls)) {
+            if (stepEnd.errorCode && stepEnd.errorCode !== 'STOP')
+                return { reason: 'error', steps, lastEvent };
+            const answered = new Set(getFunctionResponses(stepEnd).map((r) => r.id));
+            const pending = (modelEvent.longRunningToolIds ?? []).filter((id) => !answered.has(id));
+            if (pending.length > 0)
+                return { reason: 'paused', steps, lastEvent, pending };
+            return { reason: 'final', steps, lastEvent };
+        }
+    }
+}