melchizedek-agents 0.18.0 → 0.20.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,151 @@
+/**
+ * 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.
+ *
+ * A NESTED WORKFLOW (ADR 0098): a `yaml_reference` to a workflow syndicate
+ * is a workflowSubagentTool, holding the whole graph as a WorkflowSubagent.
+ * A call runs as steps 1 to 6 say, with the walk in place of the loop: the
+ * graph's walk (lib/workflow/turn.ts, runNativeWorkflow, which
+ * lib/compileNative.ts hands over) stores the message itself and yields the
+ * events ADK's Runner yields for a Workflow root, node input turns aside;
+ * the answer is the last of them's text, as ADK's AgentTool reads it from a
+ * Workflow (never parsed: a Workflow has no output schema). A node that
+ * gave up fails the call with its error. The walk is not imported here, so
+ * this module stays below lib/workflow/ in the import graph.
+ *
+ * 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 { ModelAdapter } from '../../models/contract.ts';
+import type { Tool, ToolContext } from '../../tools/tool.ts';
+import type { TurnEvent } from '../events.ts';
+import type { SessionService } from '../sessions.ts';
+import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
+import type { NativeAgent } from './request.ts';
+import { SelfCorrection } from './selfCorrection.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;
+/** Where a workflow subagent tool keeps the graph it runs. */
+export declare const WORKFLOW_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;
+/** One call's walk of a nested workflow, on the child session (WorkflowSubagent.walk). */
+export interface WorkflowSubagentRun {
+    sessions: SessionService;
+    appName: string;
+    userId: string;
+    sessionId: string;
+    /** The message's parts: the call's request as one text part. */
+    userParts: unknown[];
+    signal?: AbortSignal;
+    adapterFor: (model: string) => ModelAdapter;
+    memory?: AgentLoopContext['memory'];
+    log?: (message: string) => void;
+    selfCorrection: SelfCorrection;
+    credentials?: AgentLoopContext['credentials'];
+}
+/** A workflow syndicate delegated to as a subagent (ADR 0098): its name and description, and the walk one call runs. */
+export interface WorkflowSubagent {
+    name: string;
+    description?: string;
+    /** Stores the message on the child session and walks the whole graph, yielding each event ADK's Runner yields. Throws what a node gave up with. */
+    walk(run: WorkflowSubagentRun): AsyncGenerator<TurnEvent, unknown>;
+}
+/** A nested workflow listed on its caller as a tool: the declaration ADK's AgentTool gives a Workflow, and the graph the call walks. */
+export interface WorkflowSubagentTool extends Tool {
+    readonly [WORKFLOW_SUBAGENT]: WorkflowSubagent;
+}
+/** `workflow` as a tool its caller lists, as lib/compileAdk.ts lists a nested Workflow as an AgentTool: one string `request`. Only the native loop runs it. */
+export declare function workflowSubagentTool(workflow: WorkflowSubagent): WorkflowSubagentTool;
+/** The nested workflow a delegated call walks: the one a workflow subagent tool holds, else undefined. */
+export declare function workflowSubagentOf(tool: unknown): WorkflowSubagent | undefined;
+/**
+ * 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>;
+/**
+ * Runs one delegated call to a nested workflow (ADR 0098): the whole graph
+ * walked on the child session with the call's `request` as its message,
+ * the walk's state writes recorded in `context`. Resolves to the last
+ * yielded event's text, '' for none. Throws what the walk throws.
+ */
+export declare function runWorkflowSubagent(workflow: WorkflowSubagent, args: Record<string, unknown>, context: ToolContext, scope: DelegationScope): Promise<unknown>;