melchizedek-agents 0.17.0 → 0.19.0

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

@@ -0,0 +1,103 @@
+/**
+ * lib/runtime/native/compaction.ts — context compaction on the native loop:
+ * the YAML's `context:` block, run as ADK runs it (ADR 0033, ADR 0045).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime `context:` compiles to ADK's TokenBasedContextCompactor
+ *   with an LlmSummarizer (lib/compile.ts), which ADK's
+ *   ContextCompactorRequestProcessor runs before every model step of the
+ *   agent. A session either runtime wrote must be one the other continues,
+ *   so this is that compactor and that summarizer, rule for rule
+ *   (context/token_based_context_compactor.js, context/compaction_utils.js
+ *   and context/summarizers/llm_summarizer.js in @google/adk 2.2), and the
+ *   event it stores is the one ADK stores:
+ *
+ *   - WHEN. Before each model step, over the session's active events (the
+ *     latest compaction and what follows it, in the run's isolation scope).
+ *     The raw events (compactions aside) must number more than
+ *     `keep_recent_events`, and the cut must leave something to summarize:
+ *     the cut starts `keep_recent_events` from the end and moves back while
+ *     it would separate a call from its answer. Then the prompt size must
+ *     pass `compact_after_tokens`: the latest active event's
+ *     usageMetadata.promptTokenCount, or, when no event carries one, the
+ *     characters of the agent's projected history (text, and each call and
+ *     answer as JSON) divided by 4, rounded up.
+ *   - WHAT IS SUMMARIZED. The raw events before the cut, after the active
+ *     compaction when there is one, so a later summary folds the earlier in.
+ *   - THE CALL. One user message: ADK's default prompt, a blank line, then
+ *     per event `[Event i - Author: <author>]`, its text (thoughts aside) and
+ *     a blank line. No system prompt, no tools, not streamed. It goes to
+ *     `summary_model` (default the agent's own model), as a leaf adapter
+ *     with no fallback, through traceLlmGeneration as the shim calls it: the
+ *     llm.request span, under the agent span and outside any model.call,
+ *     and the turn's charge (ADR 0053, ADR 0076). The summary is the first
+ *     response's first part's text and each later response's; a first
+ *     response with no text throws "LLM failed to return a valid summary.",
+ *     as ADK does, and the turn fails.
+ *   - THE EVENT. author `system`, no invocation id, content `{ role: model,
+ *     parts: [{ text: summary }] }`, `isCompacted: true`, `startTime` and
+ *     `endTime` (the first and last summarized events' timestamps),
+ *     `compactedContent`, and the run's isolation scope. The loop appends it
+ *     before the step, so the step's request already reads it: the history
+ *     builder (lib/runtime/native/history.ts) puts
+ *     "[Previous Context Summary]:\n<summary>" in place of the events up to
+ *     `endTime`. The full history stays stored.
+ *
+ * NOT PORTED: ADK's before/after context-compaction plugin hooks. No plugin
+ * the engine installs implements them.
+ */
+import type { ModelAdapter, ModelRequest } from '../../models/contract.ts';
+import type { TurnEvent } from '../events.ts';
+import type { Session } from '../sessions.ts';
+import type { CompactedEvent } from './history.ts';
+/** An agent's `context:` block, in the YAML's spelling (ADR 0033). */
+export interface ContextConfig {
+    /** Compact when the last request's prompt passed this many tokens. */
+    compact_after_tokens: number;
+    /** Events kept verbatim after the summary. Default 6. */
+    keep_recent_events?: number;
+    /** The model that writes the summary. Default: the agent's own. */
+    summary_model?: string;
+}
+export declare const DEFAULT_KEEP_RECENT_EVENTS = 6;
+/** ADK's LlmSummarizer default prompt, which compile's summarizer uses. */
+export declare const SUMMARY_PROMPT = "The following is a conversation history between a user and an AI agent. Please summarize the conversation, focusing on key information and decisions made, as well as any unresolved questions or tasks. The summary should be concise and capture the essence of the interaction.";
+/** ADK's message when the summarizer's first response has no text. */
+export declare const SUMMARY_FAILED = "LLM failed to return a valid summary.";
+/** Where the agent stands when it compacts. */
+export interface CompactionScope {
+    agentName: string;
+    session: Session;
+    branch?: string;
+    isolationScope?: string;
+}
+/** Where the verbatim tail starts: `keep` from the end, moved back so no answer loses its call. */
+export declare function retainStartIndex(raw: readonly TurnEvent[], keep: number): number;
+/**
+ * The events a compaction would summarize now (the active compaction first,
+ * when there is one), or undefined when the agent should not compact.
+ */
+export declare function eventsToCompact(config: ContextConfig, scope: CompactionScope): TurnEvent[] | undefined;
+/** The one request the summarizer sends, as the shim maps ADK's LlmRequest for it. */
+export declare function summaryRequest(events: readonly TurnEvent[], model: string, signal?: AbortSignal): ModelRequest;
+/**
+ * Summarizes `events` with `adapter` under `model` and returns the
+ * compacted event (not stored). Charged and traced as one model call.
+ * Throws SUMMARY_FAILED when the first response carries no text.
+ */
+export declare function summarize(events: readonly TurnEvent[], adapter: ModelAdapter, model: string, options?: {
+    signal?: AbortSignal;
+    isolationScope?: string;
+}): Promise<CompactedEvent>;
+/**
+ * Before a model step: the compacted event when the agent's `context:` says
+ * to compact now, else undefined. The caller stores it before the step.
+ */
+export declare function compactBeforeStep(agent: {
+    name: string;
+    model: string;
+    context?: ContextConfig;
+}, scope: Omit<CompactionScope, 'agentName'> & {
+    adapterFor: (model: string) => ModelAdapter;
+    signal?: AbortSignal;
+}): Promise<CompactedEvent | undefined>;

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

@@ -0,0 +1,191 @@
+/**
+ * lib/runtime/native/compaction.ts — context compaction on the native loop:
+ * the YAML's `context:` block, run as ADK runs it (ADR 0033, ADR 0045).
+ *
+ * WHY this file exists:
+ *   On the ADK runtime `context:` compiles to ADK's TokenBasedContextCompactor
+ *   with an LlmSummarizer (lib/compile.ts), which ADK's
+ *   ContextCompactorRequestProcessor runs before every model step of the
+ *   agent. A session either runtime wrote must be one the other continues,
+ *   so this is that compactor and that summarizer, rule for rule
+ *   (context/token_based_context_compactor.js, context/compaction_utils.js
+ *   and context/summarizers/llm_summarizer.js in @google/adk 2.2), and the
+ *   event it stores is the one ADK stores:
+ *
+ *   - WHEN. Before each model step, over the session's active events (the
+ *     latest compaction and what follows it, in the run's isolation scope).
+ *     The raw events (compactions aside) must number more than
+ *     `keep_recent_events`, and the cut must leave something to summarize:
+ *     the cut starts `keep_recent_events` from the end and moves back while
+ *     it would separate a call from its answer. Then the prompt size must
+ *     pass `compact_after_tokens`: the latest active event's
+ *     usageMetadata.promptTokenCount, or, when no event carries one, the
+ *     characters of the agent's projected history (text, and each call and
+ *     answer as JSON) divided by 4, rounded up.
+ *   - WHAT IS SUMMARIZED. The raw events before the cut, after the active
+ *     compaction when there is one, so a later summary folds the earlier in.
+ *   - THE CALL. One user message: ADK's default prompt, a blank line, then
+ *     per event `[Event i - Author: <author>]`, its text (thoughts aside) and
+ *     a blank line. No system prompt, no tools, not streamed. It goes to
+ *     `summary_model` (default the agent's own model), as a leaf adapter
+ *     with no fallback, through traceLlmGeneration as the shim calls it: the
+ *     llm.request span, under the agent span and outside any model.call,
+ *     and the turn's charge (ADR 0053, ADR 0076). The summary is the first
+ *     response's first part's text and each later response's; a first
+ *     response with no text throws "LLM failed to return a valid summary.",
+ *     as ADK does, and the turn fails.
+ *   - THE EVENT. author `system`, no invocation id, content `{ role: model,
+ *     parts: [{ text: summary }] }`, `isCompacted: true`, `startTime` and
+ *     `endTime` (the first and last summarized events' timestamps),
+ *     `compactedContent`, and the run's isolation scope. The loop appends it
+ *     before the step, so the step's request already reads it: the history
+ *     builder (lib/runtime/native/history.ts) puts
+ *     "[Previous Context Summary]:\n<summary>" in place of the events up to
+ *     `endTime`. The full history stays stored.
+ *
+ * NOT PORTED: ADK's before/after context-compaction plugin hooks. No plugin
+ * the engine installs implements them.
+ */
+import { llmRequestToModelRequest, modelResponseToLlmResponse } from '../../models/genaiMapping.js';
+import { traceLlmGeneration } from '../../observability/tracer.js';
+import { createTurnEvent, getFunctionCalls, getFunctionResponses } from '../events.js';
+import { activeEvents, contentsOf, isCompacted } from './history.js';
+export const DEFAULT_KEEP_RECENT_EVENTS = 6;
+/** ADK's LlmSummarizer default prompt, which compile's summarizer uses. */
+export const SUMMARY_PROMPT = 'The following is a conversation history between a user and an AI agent. Please summarize the conversation, focusing on key information and decisions made, as well as any unresolved questions or tasks. The summary should be concise and capture the essence of the interaction.';
+/** ADK's message when the summarizer's first response has no text. */
+export const SUMMARY_FAILED = 'LLM failed to return a valid summary.';
+const CHARS_PER_TOKEN = 4;
+// ── When (ADK's shouldCompact) ───────────────────────────────────────────────
+/** Where the verbatim tail starts: `keep` from the end, moved back so no answer loses its call. */
+export function retainStartIndex(raw, keep) {
+    let start = Math.max(0, raw.length - keep);
+    while (start > 0) {
+        if (getFunctionResponses(raw[start]).length > 0 && getFunctionCalls(raw[start - 1]).length > 0)
+            start--;
+        else
+            break;
+    }
+    return start;
+}
+/** The latest prompt token count an active event carries, else the estimate from the projected history. */
+function promptTokens(active, scope) {
+    for (let i = active.length - 1; i >= 0; i--) {
+        const count = active[i]?.usageMetadata?.promptTokenCount;
+        if (count !== undefined)
+            return count;
+    }
+    // ADK estimates from getContents with no isolation scope: scoped events count for nothing here.
+    let chars = 0;
+    for (const content of contentsOf(active, scope.agentName, scope.branch, undefined)) {
+        for (const part of content.parts ?? []) {
+            if (part.text)
+                chars += part.text.length;
+            if (part.functionCall)
+                chars += JSON.stringify(part.functionCall).length;
+            if (part.functionResponse)
+                chars += JSON.stringify(part.functionResponse).length;
+        }
+    }
+    return chars <= 0 ? undefined : Math.ceil(chars / CHARS_PER_TOKEN);
+}
+/**
+ * The events a compaction would summarize now (the active compaction first,
+ * when there is one), or undefined when the agent should not compact.
+ */
+export function eventsToCompact(config, scope) {
+    const keep = config.keep_recent_events ?? DEFAULT_KEEP_RECENT_EVENTS;
+    const active = activeEvents(scope.session.events, scope.isolationScope);
+    const raw = active.filter((e) => !isCompacted(e));
+    if (raw.length <= keep)
+        return undefined;
+    const start = retainStartIndex(raw, keep);
+    if (start === 0)
+        return undefined;
+    const tokens = promptTokens(active, scope);
+    if (tokens === undefined || tokens <= config.compact_after_tokens)
+        return undefined;
+    const present = active.find(isCompacted);
+    const cut = raw.slice(0, start);
+    return present ? [present, ...cut] : cut;
+}
+// ── The summary (ADK's LlmSummarizer) ────────────────────────────────────────
+/** An event's text, thoughts aside (ADK's stringifyContent). */
+function textOf(event) {
+    const parts = event.content?.parts;
+    if (!parts)
+        return '';
+    return parts
+        .filter((p) => !p.thought)
+        .map((p) => p.text ?? '')
+        .join('');
+}
+/** The one request the summarizer sends, as the shim maps ADK's LlmRequest for it. */
+export function summaryRequest(events, model, signal) {
+    let formatted = '';
+    events.forEach((event, i) => {
+        formatted += `[Event ${i + 1} - Author: ${event.author}]\n`;
+        formatted += `${textOf(event)}\n\n`;
+    });
+    const llmRequest = {
+        contents: [{ role: 'user', parts: [{ text: `${SUMMARY_PROMPT}\n\n${formatted}` }] }],
+        toolsDict: {},
+        liveConnectConfig: {},
+    };
+    return llmRequestToModelRequest(llmRequest, { model, stream: false, ...(signal ? { signal } : {}) });
+}
+/**
+ * Summarizes `events` with `adapter` under `model` and returns the
+ * compacted event (not stored). Charged and traced as one model call.
+ * Throws SUMMARY_FAILED when the first response carries no text.
+ */
+export async function summarize(events, adapter, model, options = {}) {
+    if (events.length === 0)
+        throw new Error('Cannot summarize an empty list of events.');
+    const startTime = events[0].timestamp;
+    const endTime = events[events.length - 1].timestamp;
+    const request = summaryRequest(events, model, options.signal);
+    async function* inner() {
+        for await (const response of adapter.generate(request))
+            yield modelResponseToLlmResponse(response);
+    }
+    const responses = traceLlmGeneration({ provider: adapter.provider, model, request }, inner());
+    // As ADK: the first response must carry text; nothing after a failure is read.
+    const first = await responses.next();
+    const head = first.done ? undefined : first.value.content?.parts?.[0]?.text;
+    if (!head)
+        throw new Error(SUMMARY_FAILED);
+    let summary = head;
+    for await (const chunk of responses) {
+        const text = chunk.content?.parts?.[0]?.text;
+        if (text)
+            summary += text;
+    }
+    const event = {
+        ...createTurnEvent({ author: 'system', content: { role: 'model', parts: [{ text: summary }] } }),
+        isCompacted: true,
+        startTime,
+        endTime,
+        compactedContent: summary,
+    };
+    if (options.isolationScope !== undefined)
+        event.isolationScope = options.isolationScope;
+    return event;
+}
+// ── The loop's hook ──────────────────────────────────────────────────────────
+/**
+ * Before a model step: the compacted event when the agent's `context:` says
+ * to compact now, else undefined. The caller stores it before the step.
+ */
+export async function compactBeforeStep(agent, scope) {
+    if (!agent.context)
+        return undefined;
+    const events = eventsToCompact(agent.context, { ...scope, agentName: agent.name });
+    if (!events)
+        return undefined;
+    const model = agent.context.summary_model ?? agent.model;
+    return summarize(events, scope.adapterFor(model), model, {
+        ...(scope.signal ? { signal: scope.signal } : {}),
+        ...(scope.isolationScope !== undefined ? { isolationScope: scope.isolationScope } : {}),
+    });
+}

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

@@ -0,0 +1,98 @@
+/**
+ * lib/runtime/native/delegate.ts — delegation on the native loop: a
+ * subagent runs as a tool, with its own child loop (WS2-6, ADR 0074).
+ *
+ * WHY this file exists:
+ *   A DELEGATE syndicate (lib/compile.ts) lists each subagent on its
+ *   orchestrator as ADK's AgentTool. The native loop (agentLoop.ts) runs
+ *   the same delegation without ADK, and a session either runtime wrote must
+ *   be one the other continues, so a delegated call stores what ADK's
+ *   AgentTool stores, ids and times aside. tests/nativeDelegate.test.ts runs
+ *   the boundary suite's delegation cases, a nested syndicate and the
+ *   council example both ways and compares every session.
+ *
+ * ONE CALL, AS ADK'S AgentTool RUNS IT:
+ *   1. The message: `{ role: 'user', parts: [{ text: args.request }] }`.
+ *   2. The subagent's session: the one under the subagent's own name as the
+ *      app name, with the caller's user id and session id. It is created on
+ *      the first call, with the caller's state as it stands (the session's,
+ *      then this call's writes; `temp:` keys dropped), and kept: a later
+ *      call, in this turn or another, continues it. This is not a branch of
+ *      the caller's session; ADK's AgentTool runs a Runner of its own.
+ *   3. A turn already stopped answers an empty text, before or after the
+ *      message is stored.
+ *   4. The message is stored as a user event under a fresh invocation id
+ *      (`e-<uuid>`), and the subagent runs on runAgentLoop as the root of
+ *      its run: not streamed, under the turn's controls and signal (its
+ *      calls count toward max_steps), with the caller's memory.
+ *   5. Each event the child stores has its stateDelta, `temp:` keys aside,
+ *      written into the call's own state delta, so it lands on the caller's
+ *      response event. Once the turn has stopped, ADK's Runner yields no
+ *      more events: the answer is read from the last one it yielded.
+ *   6. The answer is the last event's text: its non-thought text parts
+ *      joined by a newline, or '' when it has no parts. With an output
+ *      schema it is parsed as JSON; text that does not parse fails the call
+ *      with the parser's message, as on ADK.
+ *
+ * A PAUSE INSIDE A SUBAGENT (an ask_user call, an approval request) cannot
+ * reach the caller, exactly as under ADK (ADR 0028): the child run ends
+ * paused, its last event carries no text, the call answers '', and the gated
+ * tool never runs. WS6-2a lifts this.
+ *
+ * Calls to subagents in one step run one after another, in call order, as
+ * ADK runs them; running them concurrently is WS6.
+ *
+ * NESTED SYNDICATES: a `yaml_reference` subagent is the nested syndicate's
+ * orchestrator, named as the entry, listing its own subagent tools. It runs
+ * here like any subagent, and its own delegations open sessions under their
+ * own names, as on ADK.
+ *
+ * The DELEGATE relay fallback (an orchestrator that echoes a tool name or
+ * says nothing) stays in lib/runtime/syndicateTurn.ts: it reads the drained
+ * run, whichever runtime produced it.
+ *
+ * ADK stays out of this file: an ADK AgentTool is recognized by ADK's global
+ * symbol only to refuse it, with a message naming what to list instead.
+ */
+import type { Tool, ToolContext } from '../../tools/tool.ts';
+import type { TurnEvent } from '../events.ts';
+import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
+import type { NativeAgent } from './request.ts';
+/** Where a subagent tool keeps the agent it runs. A global symbol, so a second copy of this module still finds it. */
+export declare const SUBAGENT: unique symbol;
+/** A subagent listed on its caller as a tool: the declaration ADK's AgentTool gives it, and the agent the call runs. */
+export interface SubagentTool extends Tool {
+    readonly [SUBAGENT]: NativeAgent;
+}
+/**
+ * `agent` as a tool its caller lists, as lib/compile.ts lists a subagent as
+ * an AgentTool: named for the agent, described by its description, taking
+ * one string `request`. Only the native loop runs it.
+ */
+export declare function subagentTool(agent: NativeAgent): SubagentTool;
+/**
+ * The agent a delegated call runs: the one a subagent tool (or anything
+ * carrying SUBAGENT) holds, else undefined. Throws for an ADK AgentTool that
+ * carries none: its LlmAgent cannot run on the native loop.
+ */
+export declare function subagentOf(tool: unknown): NativeAgent | undefined;
+/** What a delegated call needs from its caller's step. */
+export interface DelegationScope {
+    /** The caller's loop context: its session, store, adapters, memory, signal. */
+    ctx: AgentLoopContext;
+    /** The caller's session state as the step left it. */
+    stateBase: Readonly<Record<string, unknown>>;
+    /** The turn's signal, as the step sent it. */
+    signal?: AbortSignal;
+    /** The loop the child runs on (agentLoop.ts passes its own runAgentLoop). */
+    runLoop: (agent: NativeAgent, ctx: AgentLoopContext) => AsyncGenerator<TurnEvent, AgentLoopEnd>;
+    /** Calls sharing this key run one after another (agentLoop.ts passes the step's scope). */
+    queue: object;
+}
+/**
+ * Runs one delegated call: `agent` on its own session with the call's
+ * `request` as its message, the child's state writes recorded in `context`.
+ * Resolves to the call's result: the subagent's answer, '' for none. Throws what the child run
+ * throws, and for an output-schema answer that does not parse.
+ */
+export declare function runSubagent(agent: NativeAgent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;

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

@@ -0,0 +1,173 @@
+/**
+ * lib/runtime/native/delegate.ts — delegation on the native loop: a
+ * subagent runs as a tool, with its own child loop (WS2-6, ADR 0074).
+ *
+ * WHY this file exists:
+ *   A DELEGATE syndicate (lib/compile.ts) lists each subagent on its
+ *   orchestrator as ADK's AgentTool. The native loop (agentLoop.ts) runs
+ *   the same delegation without ADK, and a session either runtime wrote must
+ *   be one the other continues, so a delegated call stores what ADK's
+ *   AgentTool stores, ids and times aside. tests/nativeDelegate.test.ts runs
+ *   the boundary suite's delegation cases, a nested syndicate and the
+ *   council example both ways and compares every session.
+ *
+ * ONE CALL, AS ADK'S AgentTool RUNS IT:
+ *   1. The message: `{ role: 'user', parts: [{ text: args.request }] }`.
+ *   2. The subagent's session: the one under the subagent's own name as the
+ *      app name, with the caller's user id and session id. It is created on
+ *      the first call, with the caller's state as it stands (the session's,
+ *      then this call's writes; `temp:` keys dropped), and kept: a later
+ *      call, in this turn or another, continues it. This is not a branch of
+ *      the caller's session; ADK's AgentTool runs a Runner of its own.
+ *   3. A turn already stopped answers an empty text, before or after the
+ *      message is stored.
+ *   4. The message is stored as a user event under a fresh invocation id
+ *      (`e-<uuid>`), and the subagent runs on runAgentLoop as the root of
+ *      its run: not streamed, under the turn's controls and signal (its
+ *      calls count toward max_steps), with the caller's memory.
+ *   5. Each event the child stores has its stateDelta, `temp:` keys aside,
+ *      written into the call's own state delta, so it lands on the caller's
+ *      response event. Once the turn has stopped, ADK's Runner yields no
+ *      more events: the answer is read from the last one it yielded.
+ *   6. The answer is the last event's text: its non-thought text parts
+ *      joined by a newline, or '' when it has no parts. With an output
+ *      schema it is parsed as JSON; text that does not parse fails the call
+ *      with the parser's message, as on ADK.
+ *
+ * A PAUSE INSIDE A SUBAGENT (an ask_user call, an approval request) cannot
+ * reach the caller, exactly as under ADK (ADR 0028): the child run ends
+ * paused, its last event carries no text, the call answers '', and the gated
+ * tool never runs. WS6-2a lifts this.
+ *
+ * Calls to subagents in one step run one after another, in call order, as
+ * ADK runs them; running them concurrently is WS6.
+ *
+ * NESTED SYNDICATES: a `yaml_reference` subagent is the nested syndicate's
+ * orchestrator, named as the entry, listing its own subagent tools. It runs
+ * here like any subagent, and its own delegations open sessions under their
+ * own names, as on ADK.
+ *
+ * The DELEGATE relay fallback (an orchestrator that echoes a tool name or
+ * says nothing) stays in lib/runtime/syndicateTurn.ts: it reads the drained
+ * run, whichever runtime produced it.
+ *
+ * ADK stays out of this file: an ADK AgentTool is recognized by ADK's global
+ * symbol only to refuse it, with a message naming what to list instead.
+ */
+import { randomUUID } from 'node:crypto';
+import { createTurnEvent } from '../events.js';
+import { TEMP_STATE_PREFIX } from '../sessions.js';
+import { SelfCorrection } from './selfCorrection.js';
+// ── The subagent tool ────────────────────────────────────────────────────────
+/** Where a subagent tool keeps the agent it runs. A global symbol, so a second copy of this module still finds it. */
+export const SUBAGENT = Symbol.for('melchizedek.subagent');
+/** ADK's own mark on an AgentTool (agent_tool.js). */
+const ADK_AGENT_TOOL = Symbol.for('google.adk.agentTool');
+/**
+ * `agent` as a tool its caller lists, as lib/compile.ts lists a subagent as
+ * an AgentTool: named for the agent, described by its description, taking
+ * one string `request`. Only the native loop runs it.
+ */
+export function subagentTool(agent) {
+    return {
+        name: agent.name,
+        [SUBAGENT]: agent,
+        declaration: () => ({
+            name: agent.name,
+            description: agent.description ?? '',
+            parameters: { type: 'object', properties: { request: { type: 'string' } }, required: ['request'] },
+        }),
+        execute: async () => {
+            throw new Error(`${agent.name}: a subagent tool runs only on the native loop (lib/runtime/native/agentLoop.ts)`);
+        },
+    };
+}
+/**
+ * The agent a delegated call runs: the one a subagent tool (or anything
+ * carrying SUBAGENT) holds, else undefined. Throws for an ADK AgentTool that
+ * carries none: its LlmAgent cannot run on the native loop.
+ */
+export function subagentOf(tool) {
+    if (!tool || typeof tool !== 'object')
+        return undefined;
+    const agent = tool[SUBAGENT];
+    if (agent && typeof agent === 'object')
+        return agent;
+    if (tool[ADK_AGENT_TOOL] === true) {
+        const name = tool.name;
+        throw new Error(`${String(name)}: an ADK AgentTool cannot run on the native loop; list subagentTool(agent) (lib/runtime/native/delegate.ts)`);
+    }
+    return undefined;
+}
+const queues = new WeakMap();
+/** Runs `run` after every earlier call queued under `key`, whether it succeeded or not. */
+function inTurn(key, run) {
+    const before = queues.get(key) ?? Promise.resolve();
+    const mine = before.then(run, run);
+    queues.set(key, mine.then(() => undefined, () => undefined));
+    return mine;
+}
+/** ADK's AgentTool answer: the last event's non-thought text, joined by a newline. */
+function answerOf(agent, last) {
+    const parts = last?.content?.parts;
+    if (!parts?.length)
+        return '';
+    const text = parts
+        .filter((p) => !p.thought)
+        .map((p) => p.text)
+        .filter((t) => t)
+        .join('\n');
+    return agent.outputSchema ? JSON.parse(text) : text;
+}
+/**
+ * Runs one delegated call: `agent` on its own session with the call's
+ * `request` as its message, the child's state writes recorded in `context`.
+ * Resolves to the call's result: the subagent's answer, '' for none. Throws what the child run
+ * throws, and for an output-schema answer that does not parse.
+ */
+export function runSubagent(agent, args, context, scope) {
+    return inTurn(scope.queue, () => runChild(agent, args, context, scope));
+}
+async function runChild(agent, args, context, scope) {
+    const { ctx, signal } = scope;
+    const { sessions } = ctx;
+    const parent = ctx.session;
+    const content = { role: 'user', parts: [{ text: args.request }] };
+    const key = { appName: agent.name, userId: parent.userId, sessionId: parent.id };
+    const session = (await sessions.get(key)) ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
+    if (signal?.aborted)
+        return '';
+    const invocationId = `e-${randomUUID()}`;
+    await sessions.append(session, createTurnEvent({ invocationId, author: 'user', content }));
+    if (signal?.aborted)
+        return '';
+    const loop = scope.runLoop(agent, {
+        session,
+        sessions,
+        invocationId,
+        userContent: content,
+        stream: false,
+        // ADK's AgentTool builds its sub-runner without the reflect-and-retry
+        // plugins, so a subagent's own errors are not retried (ADR 0075).
+        selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
+        ...(ctx.memory ? { memory: ctx.memory } : {}),
+        // The parent's grants, pinned to the root's app (ADR 0072). Not its consent step: a subagent's
+        // pause would end inside the call, as ADK's AgentTool swallows it (ADR 0085).
+        ...(ctx.credentials ? { credentials: ctx.credentials } : {}),
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        ...(ctx.adapterFor ? { adapterFor: ctx.adapterFor } : {}),
+        ...(ctx.log ? { log: ctx.log } : {}),
+    });
+    let last;
+    for await (const event of loop) {
+        // ADK's Runner stops yielding once the turn stopped: the answer is the last event it yielded.
+        if (signal?.aborted)
+            break;
+        for (const [k, v] of Object.entries(event.actions?.stateDelta ?? {})) {
+            if (!k.startsWith(TEMP_STATE_PREFIX))
+                context.state.set(k, v);
+        }
+        last = event;
+    }
+    return answerOf(agent, last);
+}

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

@@ -0,0 +1,83 @@
+/**
+ * lib/runtime/native/history.ts — which stored events a native model call
+ * sees, and in what form (ADR 0045, ADR 0066).
+ *
+ * WHY this file exists:
+ *   A model request's history is the session's events projected for one
+ *   agent: its own turns as they are, the person's words as they are,
+ *   another agent's turns retold as context, approvals and credential
+ *   requests left out, and a tool's late answer moved next to the call it
+ *   answers. ADK's content processor does this on the ADK runtime
+ *   (agents/processors/content_processor_utils.js in @google/adk 2.2), and a
+ *   session one runtime wrote must read the same on the other, so this is
+ *   that processor, rule for rule, over TurnEvents:
+ *
+ *   - includeContents `default`: every visible event; `none`: from the
+ *     latest message by the person or by another agent, reaching back to
+ *     the calls its tool answers answer (getCurrentTurnContents).
+ *   - Skipped: an event with no role, or whose first part is empty text; an
+ *     event on another branch (a branch that is not a prefix of this one);
+ *     an event in another isolation scope; ADK's credential, confirmation
+ *     and input-request calls and answers.
+ *   - Another agent's event becomes a user message: "For context:", then
+ *     `[name] said: …`, `[name] called tool …`, `[name] tool … returned
+ *     result: …`, any other part copied.
+ *   - The latest compaction summary stands in for the events it covers, as
+ *     "[Previous Context Summary]:\n<summary>".
+ *   - The answer to the latest call is merged and moved next to that call;
+ *     an earlier call's answers likewise.
+ *   - ADK's own call ids (`adk-…`) are removed: the provider never sees them.
+ *   The contents are deep copies, so nothing here changes a stored event.
+ *
+ * The result is genai-shaped content, as stored. The request builder maps it
+ * to the model contract through lib/models/genaiMapping.ts, the same mapping
+ * the ADK shim applies, so both runtimes hand an adapter the same messages.
+ */
+import type { TurnContent, TurnEvent } from '../events.ts';
+/** ADK prefixes the call ids it makes with this (AF_FUNCTION_CALL_ID_PREFIX). */
+export declare const ADK_CALL_ID_PREFIX = "adk-";
+/** ADK's framework calls that a model never sees in its history. */
+export declare const REQUEST_CONFIRMATION_CALL = "adk_request_confirmation";
+export declare const REQUEST_CREDENTIAL_CALL = "adk_request_credential";
+export declare const REQUEST_INPUT_CALL = "adk_request_input";
+/** Where in a session the projecting agent stands. */
+export interface HistoryScope {
+    /** The agent whose request this is: its own events stay as they are. */
+    agentName: string;
+    /** `default` (the conversation) or `none` (the current turn only). */
+    includeContents?: 'default' | 'none';
+    /** The invocation's branch; undefined at the root. */
+    branch?: string;
+    /** The invocation's isolation scope; undefined outside one. */
+    isolationScope?: string;
+}
+/**
+ * A compaction as ADK stores it (and as lib/runtime/native/compaction.ts
+ * writes it): a summary in place of the events from `startTime` to `endTime`.
+ */
+export interface CompactedEvent extends TurnEvent {
+    isCompacted: true;
+    compactedContent?: string;
+    startTime?: number;
+    endTime?: number;
+    isScratchpad?: boolean;
+}
+export declare function isCompacted(event: TurnEvent): event is CompactedEvent;
+/** The latest compaction and what follows it, or every visible event when there is none (ADK's getActiveEvents). */
+export declare function activeEvents(events: readonly TurnEvent[], scope: string | undefined): TurnEvent[];
+export declare function isSegmentPrefix(current: string | undefined, target: string | undefined): boolean;
+/** The contents of every visible event, projected for `agentName` (ADK's getContents). The compactor's estimate reads it too. */
+export declare function contentsOf(events: readonly TurnEvent[], agentName: string, branch: string | undefined, scope: string | undefined): TurnContent[];
+/**
+ * The genai contents a model request carries for `scope.agentName`, from
+ * the session's events (oldest first), as ADK's content processor builds
+ * them for the same session.
+ */
+export declare function projectHistory(events: readonly TurnEvent[], scope: HistoryScope): TurnContent[];
+/**
+ * An agent with `code_execution: gemini`: a content that ends in code
+ * becomes that code as a fenced block, and a content that is only a result
+ * becomes the result as a user message (ADK's convertCodeExecutionParts,
+ * which its code-execution processor applies to every content). In place.
+ */
+export declare function convertCodeExecutionParts(content: TurnContent): void;