melchizedek-agents 0.18.0 → 0.19.0

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

@@ -0,0 +1,299 @@
+/**
+ * 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 { SpanStatusCode, context, trace } from '@opentelemetry/api';
+import { resolveAdapter } from '../../models/registry.js';
+import { RUNTIME_SPAN_SCOPE } from '../../observability/lineage.js';
+import { payloadPolicyFromEnv } from '../../observability/supabaseSpanExporter.js';
+import { initializeTracing } from '../../observability/tracer.js';
+/** The most a payload attribute holds, as for a failed call's (lib/observability/tracer.ts). */
+const PAYLOAD_MAX_CHARS = 200_000;
+const runtimeTracer = () => trace.getTracer(RUNTIME_SPAN_SCOPE);
+/** JSON that never throws and never exceeds the cap. */
+function payloadJson(value) {
+    let json;
+    try {
+        json = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        json = String(value);
+    }
+    return json.length > PAYLOAD_MAX_CHARS ? json.slice(0, PAYLOAD_MAX_CHARS) : json;
+}
+/**
+ * Runs `inner` with `spanContext` active for every step it takes, as ADK's
+ * runAsyncGeneratorWithOtelContext does: spans the generator opens are
+ * children of the span. A consumer that stops early closes `inner` too, so
+ * its own spans end.
+ */
+async function* within(spanContext, inner) {
+    let finished = false;
+    try {
+        for (;;) {
+            const next = await context.with(spanContext, () => inner.next());
+            if (next.done) {
+                finished = true;
+                return next.value;
+            }
+            yield next.value;
+        }
+    }
+    finally {
+        if (!finished)
+            await context.with(spanContext, () => inner.return(undefined));
+    }
+}
+function failed(span, error) {
+    span.recordException(error instanceof Error ? error : String(error));
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw error;
+}
+/** The agent's run as an `agent.invoke <name>` span, opened when the run starts. */
+export async function* traceAgentInvocation(agent, ctx, run) {
+    initializeTracing();
+    const span = runtimeTracer().startSpan(`agent.invoke ${agent.name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'invoke_agent',
+            'gen_ai.agent.name': agent.name,
+            'gen_ai.agent.description': agent.description ?? '',
+            'gen_ai.conversation.id': ctx.session.id,
+            'adk.invocation_id': ctx.invocationId,
+        },
+    });
+    try {
+        const end = yield* within(trace.setSpan(context.active(), span), run());
+        span.setAttribute('agent.end_reason', end.reason);
+        span.setAttribute('agent.steps', end.steps);
+        if (end.stop)
+            span.setAttribute('agent.stop_code', end.stop.code);
+        return end;
+    }
+    catch (error) {
+        return failed(span, error);
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * 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 async function* traceModelCall(agent, ctx, step) {
+    initializeTracing();
+    const span = runtimeTracer().startSpan('model.call', {
+        attributes: {
+            'gen_ai.operation.name': 'chat',
+            'gen_ai.agent.name': agent.name,
+            'llm.agent': agent.name,
+            'gen_ai.request.model': agent.model,
+            'gen_ai.conversation.id': ctx.session.id,
+            'adk.invocation_id': ctx.invocationId,
+        },
+    });
+    let provider;
+    const adapterFor = ctx.adapterFor ?? resolveAdapter;
+    const traced = {
+        ...ctx,
+        adapterFor: (model) => {
+            const adapter = adapterFor(model);
+            provider = adapter.provider;
+            return adapter;
+        },
+    };
+    try {
+        const result = yield* within(trace.setSpan(context.active(), span), step(traced));
+        recordModelCall(span, result, provider);
+        return result;
+    }
+    catch (error) {
+        return failed(span, error);
+    }
+    finally {
+        span.end();
+    }
+}
+function recordModelCall(span, result, provider) {
+    // gen_ai.request.model stays the agent's model, as on ADK's call_llm; the
+    // llm.request span (and the payload's request) name the leaf that answered.
+    if (provider)
+        span.setAttribute('gen_ai.system', provider);
+    const response = result.response;
+    if (response?.usage) {
+        span.setAttribute('gen_ai.usage.input_tokens', response.usage.inputTokens);
+        span.setAttribute('gen_ai.usage.output_tokens', response.usage.outputTokens);
+    }
+    if (response?.finishReason)
+        span.setAttribute('gen_ai.response.finish_reasons', [response.finishReason]);
+    if (result.stopped) {
+        span.setAttribute('model.call.stop_code', result.stopped.code);
+        return;
+    }
+    if (!response)
+        return;
+    if (response.error) {
+        // The failed call's payload is on its llm.request span; the code alone here.
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        span.setAttribute('llm.error_code', String(response.error.code));
+        return;
+    }
+    if (payloadPolicyFromEnv().mode === 'off')
+        return;
+    const { signal: _signal, ...request } = result.request;
+    span.setAttribute('llm.payload.request', payloadJson(request));
+    span.setAttribute('llm.payload.response', payloadJson(response));
+}
+/** One tool call as a `tool.execute <name>` span, under the agent's. */
+export async function traceToolCall(call, tool, run) {
+    initializeTracing();
+    const name = call.name || '<unnamed>';
+    const description = tool && typeof tool === 'object' ? tool.description : undefined;
+    const span = runtimeTracer().startSpan(`tool.execute ${name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'execute_tool',
+            'gen_ai.tool.name': name,
+            'gen_ai.tool.description': typeof description === 'string' ? description : '',
+            ...(call.id ? { 'gen_ai.tool.call.id': call.id } : {}),
+        },
+    });
+    try {
+        const outcome = await context.with(trace.setSpan(context.active(), span), run);
+        const response = outcome?.part?.functionResponse?.response;
+        if (!outcome?.part)
+            span.setAttribute('tool.pending', true);
+        else if (response && Object.hasOwn(response, 'error')) {
+            // The error text can quote the person's words; the response event holds it.
+            span.setAttribute('tool.error', true);
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        }
+        return outcome;
+    }
+    catch (error) {
+        return failed(span, error);
+    }
+    finally {
+        span.end();
+    }
+}
+// ── A workflow's spans (ADR 0095) ────────────────────────────────────────────
+// ADK opens `invoke_workflow <name>` around a workflow's walk, `execute_node
+// <name>` around each node run (a map item's under its map's), and
+// `execute_tool <name>` around a tool node's call. The native walk opens the
+// same three under the engine's names, `workflow.invoke`, `node.execute` and
+// `tool.execute`, with ADK's attributes. An agent node's own `agent.invoke`
+// (traceAgentInvocation, above) opens inside its node's span, so the ledger
+// attributes each model call to the node's agent, as on ADK.
+/** The walk as a `workflow.invoke <name>` span; every node span opens under it. */
+export async function traceWorkflowInvocation(workflow, ctx, run) {
+    initializeTracing();
+    const span = runtimeTracer().startSpan(`workflow.invoke ${workflow.name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'invoke_workflow',
+            'gen_ai.conversation.id': ctx.sessionId,
+            'adk.workflow.name': workflow.name,
+            'adk.node.path': workflow.path,
+            'adk.invocation_id': ctx.invocationId,
+        },
+    });
+    try {
+        return await context.with(trace.setSpan(context.active(), span), run);
+    }
+    catch (error) {
+        return failed(span, error);
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * 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 async function traceNodeExecution(node, run) {
+    initializeTracing();
+    const span = runtimeTracer().startSpan(`node.execute ${node.name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'execute_node',
+            'adk.node.path': node.path,
+            'adk.node.run_id': node.runId,
+            'adk.node.kind': node.kind,
+        },
+    });
+    const settle = (status, interrupts) => span.setAttributes({ 'adk.node.attempt': node.attempts.count, 'adk.node.status': status, 'adk.node.interrupt_count': interrupts });
+    try {
+        const result = await context.with(trace.setSpan(context.active(), span), run);
+        const interrupts = result.interruptIds?.length ?? 0;
+        settle(interrupts > 0 ? 'waiting' : 'completed', interrupts);
+        return result;
+    }
+    catch (error) {
+        settle('failed', 0);
+        return failed(span, error);
+    }
+    finally {
+        span.end();
+    }
+}
+/** A tool node's call as a `tool.execute <name>` span, under its node's (ToolNodeContext.traceCall). */
+export async function traceToolNodeCall(call, tool, run) {
+    initializeTracing();
+    const description = tool && typeof tool === 'object' ? tool.description : undefined;
+    const span = runtimeTracer().startSpan(`tool.execute ${call.name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'execute_tool',
+            'gen_ai.tool.name': call.name,
+            'gen_ai.tool.description': typeof description === 'string' ? description : '',
+            'gen_ai.tool.call.id': call.id,
+        },
+    });
+    try {
+        return await context.with(trace.setSpan(context.active(), span), run);
+    }
+    catch (error) {
+        // The tool node turns the throw into its { error } response; the span notes the failure, not the message.
+        span.setAttribute('tool.error', true);
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * lib/runtime/native/tempState.ts — the run's `temp:` state, kept beside
+ * the session and never in it (ADR 0071, ADR 0073).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime a tool's `state.set('temp:x', …)` writes into the
+ *   live session object as well as the event's delta, so the next step of
+ *   the same invocation reads it (an instruction's `{temp:x}`, a tool's
+ *   `state.get`), and the store drops it when it saves the event. The
+ *   native loop applies a delta to the session only through the store
+ *   (SessionService.append), which drops `temp:` keys as every store must.
+ *   Writing them into the session object instead would reach a store that
+ *   saves the whole session (the Supabase store does). So the run keeps
+ *   them here: every event the loop stores is read for its `temp:` keys
+ *   before the store sees it, and each step reads the session's state with
+ *   these laid over it.
+ *
+ * Own keys only, set as own properties, so a key such as `__proto__` is a
+ * key and never a prototype.
+ */
+import type { TurnEvent } from '../events.ts';
+/** The `temp:` keys one run has written so far. */
+export interface RunTempState {
+    /** Reads `event`'s delta for `temp:` keys. Call it before the event is stored: the store drops them. */
+    record(event: TurnEvent): void;
+    /** The keys written so far, as a new object. */
+    values(): Record<string, unknown>;
+}
+export declare function createRunTempState(): RunTempState;
+/** `state` with `overlay`'s keys laid over it, as a new object; `state` itself when there is nothing to lay. */
+export declare function withStateOverlay(state: Readonly<Record<string, unknown>>, overlay: Readonly<Record<string, unknown>> | undefined): Readonly<Record<string, unknown>>;

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

@@ -0,0 +1,56 @@
+/**
+ * lib/runtime/native/tempState.ts — the run's `temp:` state, kept beside
+ * the session and never in it (ADR 0071, ADR 0073).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime a tool's `state.set('temp:x', …)` writes into the
+ *   live session object as well as the event's delta, so the next step of
+ *   the same invocation reads it (an instruction's `{temp:x}`, a tool's
+ *   `state.get`), and the store drops it when it saves the event. The
+ *   native loop applies a delta to the session only through the store
+ *   (SessionService.append), which drops `temp:` keys as every store must.
+ *   Writing them into the session object instead would reach a store that
+ *   saves the whole session (the Supabase store does). So the run keeps
+ *   them here: every event the loop stores is read for its `temp:` keys
+ *   before the store sees it, and each step reads the session's state with
+ *   these laid over it.
+ *
+ * Own keys only, set as own properties, so a key such as `__proto__` is a
+ * key and never a prototype.
+ */
+import { TEMP_STATE_PREFIX } from '../sessions.js';
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+export function createRunTempState() {
+    const held = {};
+    return {
+        record(event) {
+            if (event.partial)
+                return;
+            const delta = event.actions?.stateDelta;
+            if (!delta)
+                return;
+            for (const [key, value] of Object.entries(delta))
+                if (key.startsWith(TEMP_STATE_PREFIX))
+                    setOwn(held, key, value);
+        },
+        values() {
+            const out = {};
+            for (const [key, value] of Object.entries(held))
+                setOwn(out, key, value);
+            return out;
+        },
+    };
+}
+/** `state` with `overlay`'s keys laid over it, as a new object; `state` itself when there is nothing to lay. */
+export function withStateOverlay(state, overlay) {
+    if (!overlay || Object.keys(overlay).length === 0)
+        return state;
+    const out = {};
+    for (const [key, value] of Object.entries(state))
+        setOwn(out, key, value);
+    for (const [key, value] of Object.entries(overlay))
+        setOwn(out, key, value);
+    return out;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * lib/runtime/nativeTurn.ts — which runtime runs a turn, and one agent's
+ * run on the native runtime (ADR 0045, ADR 0073).
+ *
+ * The flag itself is lib/runtime/runtimeFlag.ts.
+ *
+ * WHY this file exists:
+ *   runSyndicateTurn (lib/runtime/syndicateTurn.ts) runs every turn on ADK
+ *   by default. MELCHIZEDEK_RUNTIME=native, or the turn's `runtime: 'native'`
+ *   option, runs it on the engine's own agent loop instead
+ *   (lib/runtime/native/agentLoop.ts), with the agents lib/compileNative.ts
+ *   builds from the same AgentSpec. The turn runner keeps its own logic —
+ *   routing, guards, the relay fallback, approvals and questions read from
+ *   the stored events — and swaps only what runs one agent: ADK's Runner,
+ *   or runNativeAgent here. Both store the same events (ADR 0071), and the
+ *   turn runner drains both with drainAgentStream.
+ *
+ * WHAT NATIVE REFUSES, before any model call, with a message naming the
+ * feature and the runtime (UnsupportedOnRuntimeError): a caller's ADK agent
+ * transform, and an `ask_user` tool on a workflow's agent (the schema
+ * refuses it on both runtimes; a config that skipped validation is refused
+ * here, ADR 0095). A workflow syndicate runs on native through the engine's
+ * scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an approval
+ * resumes on native (lib/runtime/native/interrupts.ts), an answer to a
+ * question resumes the agent that asked (lib/runtime/questions.ts, ADR
+ * 0079), `context:` compacts on native (lib/runtime/native/compaction.ts),
+ * and `mode: task` runs on native (lib/runtime/native/taskMode.ts).
+ */
+import type { BaseMemoryService, BaseSessionService } from '@google/adk';
+import type { SyndicateYamlConfig } from '../loadSyndicate.ts';
+import type { ModelAdapter } from '../models/contract.ts';
+import type { TurnEvent } from './events.ts';
+import type { MemoryService } from './memoryService.ts';
+import type { AgentLoopEnd } from './native/agentLoop.ts';
+import type { NativeAgent } from './native/request.ts';
+import type { SelfCorrection } from './native/selfCorrection.ts';
+import type { SessionService } from './sessions.ts';
+import type { CredentialStore } from '../tools/auth.ts';
+import type { OAuthConsent } from '../tools/oauthConsent.ts';
+/**
+ * Throws UnsupportedOnRuntimeError for a syndicate or a call the native
+ * runtime does not run yet.
+ */
+export declare function refuseOnNative(config: SyndicateYamlConfig, call: {
+    isWorkflow: boolean;
+    transformAgent?: unknown;
+}): void;
+/**
+ * The search the native loop's memory tools call: the engine's MemoryService
+ * as it is, or an ADK-only service's searchMemory, which takes and returns
+ * the same JSON. The caller has already pinned the namespace.
+ */
+export declare function nativeMemory(service: BaseMemoryService | MemoryService | undefined): Pick<MemoryService, 'search'> | undefined;
+export interface NativeRunParams {
+    agent: NativeAgent;
+    /** The leaf adapter for a model id (lib/compileNative.ts nativeAdapterFor). */
+    adapterFor: (model: string) => ModelAdapter;
+    /** The store, either face (lib/runtime/adkSessionBridge.ts). */
+    sessions: SessionService | BaseSessionService;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    /** The message's parts. */
+    userParts: unknown[];
+    /** The turn's signal. */
+    signal?: AbortSignal;
+    /** Stream text as partial events. */
+    stream?: boolean;
+    memory?: Pick<MemoryService, 'search'>;
+    log?: (message: string) => void;
+    /** The turn's self-correction (ADR 0075), built once per turn from `retries:`. Default: retries at their defaults. */
+    selfCorrection?: SelfCorrection;
+    /** The run's tool credentials, pinned to its app (ADR 0072). */
+    credentials?: Pick<CredentialStore, 'get'>;
+    /** The consent step (ADR 0085). */
+    consent?: Pick<OAuthConsent, 'has' | 'begin'>;
+}
+/**
+ * Runs `agent` for one message, as ADK's Runner runs an agent: read the
+ * session (it must exist), store the message as the user's event under a
+ * new `e-` invocation id, then run the agent loop on it, yielding every
+ * event the loop yields. A run whose signal aborted before the message was
+ * stored stores nothing, as on ADK. Returns how the loop ended, or
+ * undefined when it never started.
+ */
+export declare function runNativeAgent(params: NativeRunParams): AsyncGenerator<TurnEvent, AgentLoopEnd | undefined>;

package/dist/lib/runtime/nativeTurn.js

@@ -0,0 +1,107 @@
+/**
+ * lib/runtime/nativeTurn.ts — which runtime runs a turn, and one agent's
+ * run on the native runtime (ADR 0045, ADR 0073).
+ *
+ * The flag itself is lib/runtime/runtimeFlag.ts.
+ *
+ * WHY this file exists:
+ *   runSyndicateTurn (lib/runtime/syndicateTurn.ts) runs every turn on ADK
+ *   by default. MELCHIZEDEK_RUNTIME=native, or the turn's `runtime: 'native'`
+ *   option, runs it on the engine's own agent loop instead
+ *   (lib/runtime/native/agentLoop.ts), with the agents lib/compileNative.ts
+ *   builds from the same AgentSpec. The turn runner keeps its own logic —
+ *   routing, guards, the relay fallback, approvals and questions read from
+ *   the stored events — and swaps only what runs one agent: ADK's Runner,
+ *   or runNativeAgent here. Both store the same events (ADR 0071), and the
+ *   turn runner drains both with drainAgentStream.
+ *
+ * WHAT NATIVE REFUSES, before any model call, with a message naming the
+ * feature and the runtime (UnsupportedOnRuntimeError): a caller's ADK agent
+ * transform, and an `ask_user` tool on a workflow's agent (the schema
+ * refuses it on both runtimes; a config that skipped validation is refused
+ * here, ADR 0095). A workflow syndicate runs on native through the engine's
+ * scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an approval
+ * resumes on native (lib/runtime/native/interrupts.ts), an answer to a
+ * question resumes the agent that asked (lib/runtime/questions.ts, ADR
+ * 0079), `context:` compacts on native (lib/runtime/native/compaction.ts),
+ * and `mode: task` runs on native (lib/runtime/native/taskMode.ts).
+ */
+import { randomUUID } from 'node:crypto';
+import { asSessionService } from './adkSessionBridge.js';
+import { createTurnEvent } from './events.js';
+import { runAgentLoop } from './native/agentLoop.js';
+import { ASK_USER } from './questions.js';
+import { unsupportedOnNative } from './runtimeFlag.js';
+// ── What native refuses before a turn starts ─────────────────────────────────
+/**
+ * Throws UnsupportedOnRuntimeError for a syndicate or a call the native
+ * runtime does not run yet.
+ */
+export function refuseOnNative(config, call) {
+    const where = config.syndicate_name || config.orchestrator?.name || 'syndicate';
+    if (call.transformAgent)
+        throw unsupportedOnNative('transformAgent (it transforms ADK agents)', where);
+    if (call.isWorkflow) {
+        // A pause inside an agent node cannot be resumed by the native walk (lib/workflow/resume.ts).
+        const asking = [config.orchestrator, ...(config.subagents ?? [])].find((agent) => (agent?.tools ?? []).includes(ASK_USER));
+        if (asking)
+            throw unsupportedOnNative(`an ${ASK_USER} tool on a workflow node (${asking.name}; use an ask_user node)`, where);
+    }
+}
+// ── Memory ───────────────────────────────────────────────────────────────────
+/**
+ * The search the native loop's memory tools call: the engine's MemoryService
+ * as it is, or an ADK-only service's searchMemory, which takes and returns
+ * the same JSON. The caller has already pinned the namespace.
+ */
+export function nativeMemory(service) {
+    if (!service)
+        return undefined;
+    const engine = service;
+    if (typeof engine.search === 'function')
+        return { search: (request) => engine.search(request) };
+    const adk = service;
+    if (typeof adk.searchMemory !== 'function')
+        return undefined;
+    return {
+        search: async (request) => (await adk.searchMemory(request)),
+    };
+}
+/**
+ * Runs `agent` for one message, as ADK's Runner runs an agent: read the
+ * session (it must exist), store the message as the user's event under a
+ * new `e-` invocation id, then run the agent loop on it, yielding every
+ * event the loop yields. A run whose signal aborted before the message was
+ * stored stores nothing, as on ADK. Returns how the loop ended, or
+ * undefined when it never started.
+ */
+export async function* runNativeAgent(params) {
+    const sessions = asSessionService(params.sessions);
+    const { appName, userId, sessionId } = params;
+    const session = await sessions.get({ appName, userId, sessionId });
+    if (!session)
+        throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
+    if (params.signal?.aborted)
+        return undefined;
+    if (params.userParts.length === 0)
+        throw new Error('No parts in the newMessage.');
+    const invocationId = `e-${randomUUID()}`;
+    const userContent = { role: 'user', parts: params.userParts };
+    await sessions.append(session, createTurnEvent({ invocationId, author: 'user', content: userContent }));
+    if (params.signal?.aborted)
+        return undefined;
+    return yield* runAgentLoop(params.agent, {
+        session,
+        sessions,
+        invocationId,
+        userContent,
+        stream: params.stream ?? false,
+        adapterFor: params.adapterFor,
+        ...(params.signal ? { signal: params.signal } : {}),
+        ...(params.memory ? { memory: params.memory } : {}),
+        ...(params.log ? { log: params.log } : {}),
+        ...(params.selfCorrection ? { selfCorrection: params.selfCorrection } : {}),
+        ...(params.credentials ? { credentials: params.credentials } : {}),
+        ...(params.consent ? { consent: params.consent } : {}),
+    });
+}

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

@@ -6,8 +6,8 @@
  * these three accounts?", "what is the order number?". Before this, an
  * agent could only end its turn with a question in its text and hope the
  * next message answered it, with nothing in the session saying a question
- * was open. `ask_user` is ADK's long-running tool mechanism under one YAML
- * name: the call is recorded, the run ends without a response to it, the
+ * was open. `ask_user` is a long-running tool (lib/tools/tool.ts) under one
+ * YAML name: the call is recorded, the run ends without a response to it, the
  * turn ends `input-required` (`result.input`), and the next message on the
  * conversation becomes the call's response, so the agent resumes its own
  * tool loop where it asked, with the question and the answer side by side
@@ -21,8 +21,15 @@
  * plan-dispatch route), as with approval gates: inside a delegated
  * subagent ADK swallows the pause. Not inside a workflow node yet. The
  * schema refuses both.
+ *
+ * RUNTIMES: the same on ADK and on the native loop (ADR 0079). The answer is
+ * an ordinary function response, so either runtime resumes a question either
+ * one opened; neither runs a request processor for it.
+ *
+ * TRUST: a question is an agent's call. One in an event the user authored
+ * (a forged call in a message) is ignored, on both runtimes, as approvals
+ * refuse a user-authored request (ADR 0077, ADR 0088).
  */
-import { LongRunningFunctionTool } from '@google/adk';
 import type { Event } from '@google/adk';
 import { z } from 'zod';
 import type { PendingInput } from '../workflowConfig.ts';
@@ -30,13 +37,15 @@ import type { PendingInput } from '../workflowConfig.ts';
 export declare const ASK_USER = "ask_user";
 export declare const MAX_OPTIONS = 10;
 /**
- * The tool. Its execute returns nothing: a long-running call with no result
- * ends the run, and ADK waits for a function response with the call's id.
+ * The tool, an own Tool marked long-running; the registry hands the ADK
+ * runtime its FunctionTool (lib/tools/adkTool.ts). Its execute returns
+ * nothing: a long-running call with no result ends the run, and the runtime
+ * waits for a function response with the call's id.
  */
-export declare const askUserTool: LongRunningFunctionTool<z.ZodObject<{
+export declare const askUserTool: import("../tools/toolContract.ts").DefinedTool<z.ZodObject<{
     question: z.ZodString;
     options: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, undefined>;
 /** The question an `ask_user` call carries, as the turn result reports it. */
 export declare function questionFrom(author: string | undefined, call: {
     name?: string;
@@ -47,8 +56,21 @@ export declare function questionFrom(author: string | undefined, call: {
  * The question still waiting for an answer in a session, or undefined. A
  * question the person moved past (a text message after it was answered)
  * is not pending; an answered one carries a function response with its id.
+ * Only an agent asks: an `ask_user` call in an event the user authored is
+ * no question, so the next message never becomes its answer (as approvals
+ * refuse a user-authored request, ADR 0077; ADR 0088).
  */
 export declare function pendingQuestion(events: readonly Event[]): PendingInput | undefined;
+/**
+ * The workflow question (`adk_request_input`, an ask_user node's request)
+ * still open in a session's events, or undefined. The answer is stored as
+ * the person's next text message, not as a function response, so a text
+ * message after the question closes it; a function response with its id
+ * answers it too. As with pendingQuestion, only a node asks: a request in
+ * an event the user authored is none. The resume (lib/workflow/resume.ts)
+ * reads the same events to route the answer.
+ */
+export declare function pendingWorkflowInput(events: readonly Event[]): PendingInput | undefined;
 /** The message part that answers question `id` with the person's text. */
 export declare function questionAnswerPart(id: string, answer: string): Record<string, unknown>;
 /** Index of the user message that started the turn holding call `id` (replayed raw on a dispatch resume). */