melchizedek-agents 0.18.0 → 0.20.0

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

@@ -0,0 +1,263 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+import { errorDecision, errorText } from '../../models/errorResponse.js';
+import { contractModelResponse, modelResponseToLlmResponse } from '../../models/genaiMapping.js';
+import { resolveAdapter } from '../../models/registry.js';
+import { traceLlmGeneration } from '../../observability/tracer.js';
+import { createTurnEvent, getFunctionCalls, newEventId } from '../events.js';
+import { currentTurnControl, currentTurnSignal, stopCode, stopMessage } from '../turnControl.js';
+import { toolOf } from '../../tools/tool.js';
+import { ADK_CALL_ID_PREFIX } from './history.js';
+import { SET_MODEL_RESPONSE, buildModelRequest } from './request.js';
+import { declaresReflectionTool, reflectionSigning, standsForAdkGemini } from './selfCorrection.js';
+export function eitherSignal(...candidates) {
+    const signals = [...new Set(candidates.filter((s) => s !== undefined))];
+    return signals.length <= 1 ? signals[0] : AbortSignal.any(signals);
+}
+/** 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 function stopOf() {
+    const reason = currentTurnControl()?.stopReason ?? 'canceled';
+    return { code: stopCode(reason), message: stopMessage(reason, currentTurnControl()) };
+}
+function isLongRunning(tool) {
+    const own = toolOf(tool);
+    if (own)
+        return own.longRunning === true;
+    return !!tool && typeof tool === 'object' && tool.isLongRunning === true;
+}
+/** ADK's postprocess: whether a response makes an event at all. */
+function makesEvent(response) {
+    const usageOnly = !response.content && !!response.usageMetadata;
+    return !((!response.content || response.content.parts?.length === 0) && !response.errorCode && !response.interrupted && !usageOnly);
+}
+/** What ADK stores for a model call that threw: UNKNOWN_ERROR, or the code and message of a JSON error body. */
+function thrownModelError(err) {
+    let code = 'UNKNOWN_ERROR';
+    let message = err.message;
+    try {
+        const body = JSON.parse(err.message);
+        if (body?.error) {
+            code = String(body.error.code || 'UNKNOWN_ERROR');
+            if (typeof body.error.message === 'string' && body.error.message)
+                message = body.error.message;
+        }
+    }
+    catch {
+        // Not JSON: the message as it is.
+    }
+    return { code, message: errorText(message) };
+}
+/**
+ * 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 async function runModelStep(options) {
+    const { agent, session, sessions } = options;
+    const signal = eitherSignal(options.signal, currentTurnSignal());
+    const adapter = options.adapter ?? resolveAdapter(agent.model);
+    // ADK's plugin puts the reflection tool in the toolsDict alone: declared where the model class reads it, run either way.
+    const correctionTools = options.correction?.tools ?? [];
+    const declareCorrection = correctionTools.length > 0 && declaresReflectionTool(adapter);
+    const { request, tools } = await buildModelRequest(agent, {
+        session,
+        invocationId: options.invocationId,
+        ...(options.userContent ? { userContent: options.userContent } : {}),
+        ...(options.branch !== undefined ? { branch: options.branch } : {}),
+        ...(options.isolationScope !== undefined ? { isolationScope: options.isolationScope } : {}),
+        ...(options.root ? { root: options.root } : {}),
+        ...(options.memory ? { memory: options.memory } : {}),
+        ...(options.stateOverlay ? { stateOverlay: options.stateOverlay } : {}),
+        stream: options.stream ?? false,
+        ...(signal ? { signal } : {}),
+        ...(declareCorrection ? { extraTools: correctionTools } : {}),
+        ...(options.workflowScope ? { workflowScope: options.workflowScope } : {}),
+    });
+    if (!declareCorrection)
+        for (const tool of correctionTools)
+            tools.set(tool.name, tool);
+    if (options.model)
+        request.model = options.model;
+    const result = { request, text: '', thinking: '', toolCalls: [], longRunningToolIds: [], tools };
+    if (signal?.aborted)
+        return { ...result, stopped: stopOf() };
+    // The event ADK creates before the call; each response after the first gets a fresh id and time.
+    const base = createTurnEvent({ invocationId: options.invocationId, author: agent.name, branch: options.branch });
+    let next = { id: base.id, timestamp: base.timestamp };
+    // The tracer reads LlmResponses, as on the shim; the contract response each came from rides beside it.
+    const sources = new WeakMap();
+    // What the adapter itself threw, as opposed to the store or a callback.
+    let thrown;
+    // ADK's own Gemini writes no turnComplete, so its stand-in's events carry none (ADR 0100).
+    const adkGemini = standsForAdkGemini(adapter);
+    // How a reflection call stored in this adapter's place is signed (ADR 0103).
+    const signing = reflectionSigning(adapter, request.model);
+    async function* inner() {
+        try {
+            for await (const unchecked of adapter.generate(request)) {
+                // The answer held to the contract, as the shim's mapping holds it (contractModelResponse): the step reads and stores the same parts.
+                const response = contractModelResponse(unchecked);
+                const mapped = modelResponseToLlmResponse(response);
+                if (adkGemini)
+                    delete mapped.turnComplete;
+                sources.set(mapped, response);
+                yield mapped;
+            }
+        }
+        catch (err) {
+            thrown = { error: err };
+            throw err;
+        }
+    }
+    let produced = false;
+    try {
+        return await readResponses();
+    }
+    catch (err) {
+        // An adapter that threw (see the header): FallbackLlm's catch.
+        if (thrown?.error !== err || signal?.aborted)
+            throw err;
+        const decision = errorDecision(err);
+        if (options.redirect && decision.retryable) {
+            const error = { code: 'PROVIDER_ERROR', message: errorText(err), retryable: true, ...(decision.status !== undefined ? { status: decision.status } : {}) };
+            const failed = { partial: false, parts: [], finishReason: 'error', error };
+            if (options.redirect(failed, produced))
+                return { ...result, response: failed, redirected: error };
+        }
+        if (!(err instanceof Error))
+            throw err;
+        // ADK's runAndHandleError: the step ends on an error event of its own.
+        const { code, message } = thrownModelError(err);
+        const event = createTurnEvent({ invocationId: options.invocationId, author: agent.name, errorCode: code, errorMessage: message });
+        options.beforeAppend?.(event);
+        const stored = await sessions.append(session, event);
+        return { ...result, event: stored, error: { code, message, retryable: false } };
+    }
+    async function readResponses() {
+        for await (const traced of traceLlmGeneration({ provider: adapter.provider, model: request.model, request }, inner())) {
+            if (signal?.aborted)
+                return { ...result, stopped: stopOf() };
+            const source = sources.get(traced);
+            if (!source) {
+                // A refusal the tracer made in place of the call: the turn has stopped.
+                return { ...result, stopped: { code: String(traced.errorCode), message: String(traced.errorMessage ?? '') } };
+            }
+            // Leaving the loop closes this call (and its span) before a fallback's opens.
+            if (!source.partial && source.error && options.redirect?.(source, produced))
+                return { ...result, response: source, redirected: source.error };
+            produced = true;
+            // Self-correction sees the response as ADK's afterModelCallback does: it may stand a retry in its place, or end the step.
+            // On Gemini the reflection call it stores is signed, so the next request does not 400 (ADR 0103).
+            const corrected = options.correction?.afterModel(traced, signing) ?? { response: traced, replaced: false };
+            if ('failed' in corrected) {
+                // ADK's runAndHandleError: a callback that threw ends the step on an error event of its own.
+                const { code, message } = corrected.failed;
+                const event = createTurnEvent({ invocationId: options.invocationId, author: agent.name, errorCode: code, errorMessage: message });
+                options.beforeAppend?.(event);
+                const stored = await sessions.append(session, event);
+                return { ...result, event: stored, ...(source.partial ? {} : { response: source }), error: { code, message, retryable: false } };
+            }
+            const llmResponse = corrected.response;
+            if (!makesEvent(llmResponse)) {
+                if (!source.partial)
+                    result.response = source;
+                continue;
+            }
+            const event = createTurnEvent({ ...base, ...next, actions: base.actions, ...llmResponse });
+            next = { id: newEventId(), timestamp: Date.now() };
+            if (source.partial) {
+                for (const part of source.parts)
+                    if (part.type === 'thinking')
+                        result.thinking += part.text;
+                options.onPartial?.(event);
+                continue;
+            }
+            const calls = getFunctionCalls(event);
+            const setModelResponse = calls.find((c) => c.name === SET_MODEL_RESPONSE);
+            if (event.content && setModelResponse) {
+                event.content.parts = [{ text: JSON.stringify(setModelResponse.args) }];
+                event.actions.skipSummarization = true;
+            }
+            else if (calls.length > 0) {
+                for (const call of calls)
+                    if (!call.id)
+                        call.id = `${ADK_CALL_ID_PREFIX}${randomUUID()}`;
+                event.longRunningToolIds = [
+                    ...new Set(calls.filter((c) => c.name && c.id && tools.has(c.name) && isLongRunning(tools.get(c.name))).map((c) => c.id)),
+                ];
+            }
+            options.beforeAppend?.(event);
+            const stored = await sessions.append(session, event);
+            result.event = stored;
+            result.response = source;
+            if (source.error && !corrected.replaced)
+                result.error = source.error;
+            result.text = (stored.content?.parts ?? []).filter((p) => !p.thought && typeof p.text === 'string').map((p) => p.text).join('');
+            result.toolCalls = getFunctionCalls(stored).map((c) => ({ type: 'toolCall', id: c.id, name: c.name ?? '', args: c.args ?? {} }));
+            result.longRunningToolIds = [...(stored.longRunningToolIds ?? [])];
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * lib/runtime/native/taskMode.ts — `mode: task` on the native loop: the
+ * finish_task tool, and how a task-mode node's run ends (ADR 0033, ADR 0081).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime `mode: task` is three things in ADK 2.2: LlmAgent
+ *   adds its FinishTaskTool after the agent's own tools and never sets the
+ *   output schema as the response schema; the tool declares the output
+ *   schema as its parameters, adds a line to the instruction and answers
+ *   "Task completed." (or an error naming the missing required keys); and
+ *   a workflow node in task mode (ADK's runTaskMode) ends its run on that
+ *   answer, the finish_task arguments its output. This file is those three
+ *   for the native loop, word for word, so a session either runtime wrote
+ *   holds the same events (tests/execution.test.ts).
+ *
+ * WHERE IT PLUGS IN:
+ *   - lib/runtime/native/request.ts adds finishTaskTool(agent.outputSchema)
+ *     after the agent's tools and before the caller's extra tools, as
+ *     LlmAgent adds it after its own and before a plugin's;
+ *   - lib/runtime/native/agentLoop.ts, when its context says the run is a
+ *     task-mode node (`taskNode`), passes each event through
+ *     taskNodeRun's `beforeStore` and ends the run when `output` is set.
+ *   In a plain run (not a node) the loop goes on after finish_task's
+ *   answer, as LlmAgent.runAsync does; the schema allows `mode: task` on
+ *   workflow nodes only, so a validated syndicate never does that.
+ *
+ * QUIRKS KEPT FOR PARITY: the arguments are wrapped under `result` unless
+ * the schema's type is Gemini's `OBJECT` (ADK compares to Type.OBJECT, so a
+ * lowercase `object` is wrapped too), and only top-level `required` keys
+ * are checked. The arguments are the model's output: data, read by the next
+ * node, never instructions.
+ */
+import type { Tool } from '../../tools/tool.ts';
+import type { TurnEvent } from '../events.ts';
+import type { NativeAgent } from './request.ts';
+/** ADK's FINISH_TASK_TOOL_NAME. */
+export declare const FINISH_TASK_TOOL_NAME = "finish_task";
+/** ADK's FINISH_TASK_SUCCESS_RESULT: the tool's answer when the arguments carry every required key. */
+export declare const FINISH_TASK_SUCCESS_RESULT = "Task completed.";
+/** The line FinishTaskTool.processLlmRequest appends to the instruction. */
+export declare const FINISH_TASK_INSTRUCTION = "Do NOT call `finish_task` prematurely. Use your available tools to fully complete every aspect of the task first. If the task is unclear, ask the user for clarification before proceeding. Once the task is fully complete, call `finish_task` by itself with no accompanying text output.";
+/** A finish_task own Tool, with the extractor a task-mode node reads its output through. */
+export interface FinishTaskTool extends Tool {
+    /** The node's output from a finish_task call's arguments: unwrapped from `result` when the schema is not an OBJECT. */
+    extractOutput(args: Record<string, unknown>): unknown;
+}
+/** ADK's FinishTaskTool for an agent's output schema, as an own Tool the native loop declares and runs. */
+export declare function finishTaskTool(outputSchema?: Record<string, unknown>): FinishTaskTool;
+/** One task-mode node's run: what the loop's task hook reads (ADK's runTaskMode). */
+export interface TaskNodeRun {
+    /** Called on each event before it is stored: notes a finish_task call, and marks its successful answer as the node's output. */
+    beforeStore(event: TurnEvent): void;
+    /** True once finish_task answered with success: the run ends after that event is stored. */
+    readonly finished: boolean;
+    /** The node's output: the finish_task arguments, extracted. */
+    readonly output: unknown;
+}
+/**
+ * The task hook for a node run of `agent`: the latest finish_task call's
+ * arguments are held; the event that answers it with success gets
+ * `output` (the extracted arguments), `nodeInfo.messageAsOutput`, and the
+ * output under the agent's outputKey in its stateDelta, before it is stored.
+ */
+export declare function taskNodeRun(agent: Pick<NativeAgent, 'outputSchema' | 'outputKey'>): TaskNodeRun;

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

@@ -0,0 +1,126 @@
+/**
+ * lib/runtime/native/taskMode.ts — `mode: task` on the native loop: the
+ * finish_task tool, and how a task-mode node's run ends (ADR 0033, ADR 0081).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime `mode: task` is three things in ADK 2.2: LlmAgent
+ *   adds its FinishTaskTool after the agent's own tools and never sets the
+ *   output schema as the response schema; the tool declares the output
+ *   schema as its parameters, adds a line to the instruction and answers
+ *   "Task completed." (or an error naming the missing required keys); and
+ *   a workflow node in task mode (ADK's runTaskMode) ends its run on that
+ *   answer, the finish_task arguments its output. This file is those three
+ *   for the native loop, word for word, so a session either runtime wrote
+ *   holds the same events (tests/execution.test.ts).
+ *
+ * WHERE IT PLUGS IN:
+ *   - lib/runtime/native/request.ts adds finishTaskTool(agent.outputSchema)
+ *     after the agent's tools and before the caller's extra tools, as
+ *     LlmAgent adds it after its own and before a plugin's;
+ *   - lib/runtime/native/agentLoop.ts, when its context says the run is a
+ *     task-mode node (`taskNode`), passes each event through
+ *     taskNodeRun's `beforeStore` and ends the run when `output` is set.
+ *   In a plain run (not a node) the loop goes on after finish_task's
+ *   answer, as LlmAgent.runAsync does; the schema allows `mode: task` on
+ *   workflow nodes only, so a validated syndicate never does that.
+ *
+ * QUIRKS KEPT FOR PARITY: the arguments are wrapped under `result` unless
+ * the schema's type is Gemini's `OBJECT` (ADK compares to Type.OBJECT, so a
+ * lowercase `object` is wrapped too), and only top-level `required` keys
+ * are checked. The arguments are the model's output: data, read by the next
+ * node, never instructions.
+ */
+import { toContractJsonSchema } from '../../models/schemaNormalize.js';
+import { getFunctionCalls, getFunctionResponses } from '../events.js';
+/** ADK's FINISH_TASK_TOOL_NAME. */
+export const FINISH_TASK_TOOL_NAME = 'finish_task';
+/** ADK's FINISH_TASK_SUCCESS_RESULT: the tool's answer when the arguments carry every required key. */
+export const FINISH_TASK_SUCCESS_RESULT = 'Task completed.';
+const DESCRIPTION = 'Signal that this agent has completed its delegated task. Call this when you have finished your delegated task.';
+const DESCRIPTION_WITH_SCHEMA = `${DESCRIPTION} Pass the required output data in the parameters.`;
+/** The line FinishTaskTool.processLlmRequest appends to the instruction. */
+export const FINISH_TASK_INSTRUCTION = 'Do NOT call `finish_task` prematurely. Use your available tools to fully complete every aspect of the task first. If the task is unclear, ask the user for clarification before proceeding. Once the task is fully complete, call `finish_task` by itself with no accompanying text output.';
+/** ADK's DEFAULT_TASK_OUTPUT_SCHEMA, for an agent with no output schema. */
+const DEFAULT_TASK_OUTPUT_SCHEMA = {
+    type: 'OBJECT',
+    properties: { result: { type: 'STRING', description: 'A brief summary of what the agent accomplished.' } },
+    required: ['result'],
+};
+/** The key the arguments are wrapped under, or undefined when the schema is Gemini's OBJECT (ADK's wrapperKey). */
+function wrapperKeyOf(schema) {
+    return schema.type === 'OBJECT' ? undefined : 'result';
+}
+/** The required keys `value` lacks, as FinishTaskTool.missingRequiredKeys reads them. */
+function missingRequiredKeys(schema, wrapperKey, value) {
+    if (wrapperKey)
+        return value === undefined || value === null ? [wrapperKey] : [];
+    const required = Array.isArray(schema.required) ? schema.required.filter((k) => typeof k === 'string') : [];
+    if (typeof value !== 'object' || value === null)
+        return required;
+    return required.filter((key) => value[key] === undefined);
+}
+/** ADK's FinishTaskTool for an agent's output schema, as an own Tool the native loop declares and runs. */
+export function finishTaskTool(outputSchema) {
+    const schema = outputSchema ?? DEFAULT_TASK_OUTPUT_SCHEMA;
+    const wrapperKey = wrapperKeyOf(schema);
+    const description = outputSchema ? DESCRIPTION_WITH_SCHEMA : DESCRIPTION;
+    const parameters = wrapperKey ? { type: 'OBJECT', properties: { [wrapperKey]: schema }, required: [wrapperKey] } : schema;
+    return {
+        name: FINISH_TASK_TOOL_NAME,
+        declaration: () => ({ name: FINISH_TASK_TOOL_NAME, description, parameters: toContractJsonSchema(parameters) }),
+        instruction: async () => FINISH_TASK_INSTRUCTION,
+        execute: async (args) => {
+            const value = wrapperKey ? args[wrapperKey] : args;
+            const missing = missingRequiredKeys(schema, wrapperKey, value);
+            if (missing.length > 0) {
+                return {
+                    error: `Invoking \`${FINISH_TASK_TOOL_NAME}()\` failed due to missing required parameters: ${missing.join(', ')}. You could retry calling this tool, but it is IMPORTANT for you to provide all the mandatory parameters with correct types.`,
+                };
+            }
+            return FINISH_TASK_SUCCESS_RESULT;
+        },
+        extractOutput: (args) => (wrapperKey ? args[wrapperKey] : args),
+    };
+}
+function isSuccess(event) {
+    return getFunctionResponses(event).some((r) => r.name === FINISH_TASK_TOOL_NAME && (r.response ?? {}).result === FINISH_TASK_SUCCESS_RESULT);
+}
+/**
+ * The task hook for a node run of `agent`: the latest finish_task call's
+ * arguments are held; the event that answers it with success gets
+ * `output` (the extracted arguments), `nodeInfo.messageAsOutput`, and the
+ * output under the agent's outputKey in its stateDelta, before it is stored.
+ */
+export function taskNodeRun(agent) {
+    const tool = finishTaskTool(agent.outputSchema);
+    let pendingArgs;
+    let finished = false;
+    let output;
+    return {
+        beforeStore(event) {
+            if (finished || event.partial)
+                return;
+            const call = getFunctionCalls(event).find((c) => c.name === FINISH_TASK_TOOL_NAME);
+            if (call) {
+                pendingArgs = { ...(call.args ?? {}) };
+                return;
+            }
+            if (pendingArgs === undefined || !isSuccess(event))
+                return;
+            output = tool.extractOutput(pendingArgs);
+            event.output = output;
+            event.nodeInfo = { ...(event.nodeInfo ?? {}), messageAsOutput: true };
+            if (agent.outputKey && output !== undefined) {
+                const delta = (event.actions.stateDelta ??= {});
+                Object.defineProperty(delta, agent.outputKey, { value: output, writable: true, enumerable: true, configurable: true });
+            }
+            finished = true;
+        },
+        get finished() {
+            return finished;
+        },
+        get output() {
+            return output;
+        },
+    };
+}

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

@@ -0,0 +1,75 @@
+/**
+ * lib/runtime/native/telemetry.ts — the native loop's spans: one per agent
+ * run, one per model step, one per tool call (ADR 0076).
+ *
+ * WHY this file exists:
+ *   The ledger (lib/observability/supabaseSpanExporter.ts) is a projection of
+ *   a turn's spans. On the ADK runtime, ADK opens `invoke_agent <name>`
+ *   around an agent's run, `call_llm` around each step's model call and
+ *   `execute_tool <name>` around each tool call; the tracer reads them to
+ *   attribute a model call to its agent and to sum tool time, and the
+ *   exporter reads `call_llm` for the payload tier. A native run writes the
+ *   same ledger rows because the loop opens the same three spans under the
+ *   engine's own names and scope:
+ *
+ *     agent.invoke <name>   the agent's run (runAgentLoop), parent of the rest
+ *     model.call            one model step, parent of the step's llm.request
+ *                           span(s): two when a fallback model answers
+ *     tool.execute <name>   one tool call; a step's calls run side by side
+ *
+ *   All three are in scope `melchizedek.runtime`, which the console exporter
+ *   keeps quiet as it keeps ADK's (OTEL_CONSOLE_ALL_SPANS prints them).
+ *
+ * WHAT A SPAN CARRIES:
+ *   gen_ai.* attributes as ADK sets them (operation, agent, conversation,
+ *   tool name and call id, request model, usage, finish reason), and on
+ *   model.call the provider the answering adapter names (`gen_ai.system`),
+ *   where ADK's call_llm names its own scope. A model step that did not fail
+ *   carries its payload as the engine holds it: `llm.payload.request` (the
+ *   ModelRequest, its signal left out) and `llm.payload.response` (the
+ *   adapter's final response). A failed step carries none: its llm.request
+ *   span carries the failed call's payload, as on the ADK runtime, where a
+ *   failed call_llm never ends. With TELEMETRY_PAYLOADS=off no payload is
+ *   recorded at all. Tool spans carry no arguments and no results: the root
+ *   span's ToolCall/ToolResponse events are where the ledger keeps those.
+ *
+ * The loop calls three hooks (agentLoop.ts): traceAgentInvocation around the
+ * whole run, traceModelCall around each step, traceToolCall around each call.
+ */
+import type { TurnEvent, TurnFunctionCall, TurnPart } from '../events.ts';
+import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
+import type { NativeAgent } from './request.ts';
+import type { ModelStepResult } from './step.ts';
+import type { NodeResult, TracedNode } from '../../workflow/scheduler.ts';
+/** The agent's run as an `agent.invoke <name>` span, opened when the run starts. */
+export declare function traceAgentInvocation(agent: Pick<NativeAgent, 'name' | 'description'>, ctx: Pick<AgentLoopContext, 'session' | 'invocationId'>, run: () => AsyncGenerator<TurnEvent, AgentLoopEnd>): AsyncGenerator<TurnEvent, AgentLoopEnd>;
+/**
+ * One model step as a `model.call` span. `step` gets the loop's context with
+ * an `adapterFor` that notes the adapter it hands out, so the span names the
+ * provider that answered (the fallback's, when a fallback answered).
+ */
+export declare function traceModelCall(agent: Pick<NativeAgent, 'name' | 'model'>, ctx: AgentLoopContext, step: (traced: AgentLoopContext) => AsyncGenerator<TurnEvent, ModelStepResult>): AsyncGenerator<TurnEvent, ModelStepResult>;
+/** One tool call as a `tool.execute <name>` span, under the agent's. */
+export declare function traceToolCall<O extends {
+    part?: TurnPart;
+} | undefined>(call: TurnFunctionCall, tool: unknown, run: () => Promise<O>): Promise<O>;
+/** The walk as a `workflow.invoke <name>` span; every node span opens under it. */
+export declare function traceWorkflowInvocation<T>(workflow: {
+    name: string;
+    path: string;
+}, ctx: {
+    sessionId: string;
+    invocationId: string;
+}, run: () => Promise<T>): Promise<T>;
+/**
+ * One node run as a `node.execute <name>` span (the scheduler's traceNode
+ * hook): every attempt of the run inside it, ending with ADK's status
+ * (`completed`, `waiting` when the run paused on a person, `failed`) and the
+ * attempts the run made.
+ */
+export declare function traceNodeExecution(node: TracedNode, run: () => Promise<NodeResult>): Promise<NodeResult>;
+/** A tool node's call as a `tool.execute <name>` span, under its node's (ToolNodeContext.traceCall). */
+export declare function traceToolNodeCall<T>(call: {
+    id: string;
+    name: string;
+}, tool: unknown, run: () => Promise<T>): Promise<T>;