melchizedek-agents 0.18.0 → 0.19.0

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

@@ -0,0 +1,312 @@
+/**
+ * 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 { getFunctionCalls, getFunctionResponses } from '../events.js';
+/** ADK prefixes the call ids it makes with this (AF_FUNCTION_CALL_ID_PREFIX). */
+export const ADK_CALL_ID_PREFIX = 'adk-';
+/** ADK's framework calls that a model never sees in its history. */
+export const REQUEST_CONFIRMATION_CALL = 'adk_request_confirmation';
+export const REQUEST_CREDENTIAL_CALL = 'adk_request_credential';
+export const REQUEST_INPUT_CALL = 'adk_request_input';
+const UNSTRINGIFIABLE_VALUE = '<unstringifiable value>';
+export function isCompacted(event) {
+    return event.isCompacted === true;
+}
+function isVisible(event, scope) {
+    return event.isolationScope === undefined || event.isolationScope === scope;
+}
+/** The latest compaction and what follows it, or every visible event when there is none (ADK's getActiveEvents). */
+export function activeEvents(events, scope) {
+    const visible = events.filter((e) => isVisible(e, scope));
+    const latest = visible.filter(isCompacted).pop();
+    if (!latest)
+        return visible;
+    return [latest, ...visible.filter((e) => !isCompacted(e) && e.timestamp > latest.endTime)];
+}
+export function isSegmentPrefix(current, target) {
+    return !target || target === current || (!!current && current.startsWith(`${target}.`));
+}
+function namesCall(event, name) {
+    return (event.content?.parts ?? []).some((p) => p.functionCall?.name === name || p.functionResponse?.name === name);
+}
+function shouldInclude(event, branch, scope) {
+    if (!event.content?.role || event.content.parts?.[0]?.text === '')
+        return false;
+    if (branch && event.branch && !isSegmentPrefix(branch, event.branch))
+        return false;
+    if (!isVisible(event, scope))
+        return false;
+    return !namesCall(event, REQUEST_CREDENTIAL_CALL) && !namesCall(event, REQUEST_CONFIRMATION_CALL) && !namesCall(event, REQUEST_INPUT_CALL);
+}
+function fromAnotherAgent(agentName, event) {
+    return !!agentName && event.author !== agentName && event.author !== 'user';
+}
+function clone(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+function safeStringify(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        const json = JSON.stringify(value);
+        if (typeof json === 'string')
+            return json;
+    }
+    catch {
+        // fall through to String()
+    }
+    try {
+        return String(value);
+    }
+    catch {
+        return UNSTRINGIFIABLE_VALUE;
+    }
+}
+/** Another agent's event, retold to this one as context in a user message. */
+function retold(event) {
+    if (!event.content?.parts?.length)
+        return event;
+    const parts = [{ text: 'For context:' }];
+    for (const part of event.content.parts) {
+        if (part.text && !part.thought) {
+            parts.push({ text: `[${event.author}] said: ${part.text}` });
+        }
+        else if (part.functionCall) {
+            parts.push({ text: `[${event.author}] called tool \`${part.functionCall.name}\` with parameters: ${safeStringify(part.functionCall.args)}` });
+        }
+        else if (part.functionResponse) {
+            parts.push({ text: `[${event.author}] tool \`${part.functionResponse.name}\` returned result: ${safeStringify(part.functionResponse.response)}` });
+        }
+        else {
+            parts.push(clone(part));
+        }
+    }
+    return { ...event, author: 'user', content: { role: 'user', parts } };
+}
+function summaryOf(event) {
+    return { ...event, author: 'user', content: { role: 'user', parts: [{ text: `[Previous Context Summary]:\n${event.compactedContent}` }] } };
+}
+/** Several answer events as one, a later answer to a call replacing an earlier one in place. */
+function mergeResponses(events) {
+    if (events.length === 0)
+        throw new Error('Cannot merge an empty list of events.');
+    const first = events[0];
+    const content = clone(first.content);
+    const parts = content?.parts;
+    if (!parts || parts.length === 0)
+        throw new Error('There should be at least one function_response part.');
+    const index = new Map();
+    parts.forEach((part, i) => {
+        if (part.functionResponse?.id)
+            index.set(part.functionResponse.id, i);
+    });
+    for (const event of events.slice(1)) {
+        if (!event.content?.parts)
+            throw new Error('There should be at least one function_response part.');
+        for (const part of event.content.parts) {
+            const copy = clone(part);
+            const id = copy.functionResponse?.id;
+            if (id) {
+                const at = index.get(id);
+                if (at !== undefined)
+                    parts[at] = copy;
+                else {
+                    parts.push(copy);
+                    index.set(id, parts.length - 1);
+                }
+            }
+            else {
+                parts.push(copy);
+            }
+        }
+    }
+    return { ...first, content };
+}
+/** The latest event answers calls: its answers, merged, sit right after the event that made those calls. */
+function latestAnswerNextToItsCall(events) {
+    if (events.length === 0)
+        return events;
+    const latest = events[events.length - 1];
+    const responses = getFunctionResponses(latest);
+    if (!responses.length)
+        return events;
+    const ids = new Set(responses.filter((r) => !!r.id).map((r) => r.id));
+    const secondLatest = events.at(-2);
+    if (secondLatest && getFunctionCalls(secondLatest).some((c) => c.id && ids.has(c.id)))
+        return events;
+    let match;
+    for (let i = events.length - 2; i >= 0 && !match; i--) {
+        const calls = getFunctionCalls(events[i]);
+        if (!calls.length)
+            continue;
+        if (!calls.some((c) => c.id && ids.has(c.id)))
+            continue;
+        const callIds = new Set(calls.map((c) => c.id).filter((id) => !!id));
+        if (![...ids].every((id) => callIds.has(id))) {
+            throw new Error(`Last response event should only contain the responses for the function calls in the same function call event. Function call ids found : ${[...callIds].join(', ')}, function response ids provided: ${[...ids].join(', ')}`);
+        }
+        match = { at: i, ids: callIds };
+    }
+    if (!match)
+        throw new Error(`No function call event found for function responses ids: ${[...ids].join(', ')}`);
+    const answers = [];
+    for (let i = match.at + 1; i < events.length - 1; i++) {
+        const event = events[i];
+        if (getFunctionResponses(event).some((r) => r.id && match.ids.has(r.id)))
+            answers.push(event);
+    }
+    answers.push(latest);
+    return [...events.slice(0, match.at + 1), mergeResponses(answers)];
+}
+/** Each earlier call's answers, wherever they landed, sit right after the call. */
+function answersNextToTheirCalls(events) {
+    const answeredAt = new Map();
+    events.forEach((event, i) => {
+        for (const r of getFunctionResponses(event))
+            if (r.id)
+                answeredAt.set(r.id, i);
+    });
+    const out = [];
+    for (const event of events) {
+        if (getFunctionResponses(event).length > 0)
+            continue;
+        const calls = getFunctionCalls(event);
+        out.push(event);
+        if (!calls.length)
+            continue;
+        const at = new Set();
+        for (const call of calls) {
+            const i = call.id ? answeredAt.get(call.id) : undefined;
+            if (i !== undefined)
+                at.add(i);
+        }
+        if (at.size === 1)
+            out.push(events[[...at][0]]);
+        else if (at.size > 1)
+            out.push(mergeResponses([...at].sort((a, b) => a - b).map((i) => events[i])));
+    }
+    return out;
+}
+function stripAdkCallIds(content) {
+    for (const part of content?.parts ?? []) {
+        if (part.functionCall?.id?.startsWith(ADK_CALL_ID_PREFIX))
+            part.functionCall.id = undefined;
+        if (part.functionResponse?.id?.startsWith(ADK_CALL_ID_PREFIX))
+            part.functionResponse.id = undefined;
+    }
+}
+/** The contents of every visible event, projected for `agentName` (ADK's getContents). The compactor's estimate reads it too. */
+export function contentsOf(events, agentName, branch, scope) {
+    const kept = [];
+    for (const event of events) {
+        if (!isVisible(event, scope))
+            continue;
+        if (isCompacted(event)) {
+            kept.push(summaryOf(event));
+            continue;
+        }
+        if (!shouldInclude(event, branch, scope))
+            continue;
+        kept.push(fromAnotherAgent(agentName, event) ? retold(event) : event);
+    }
+    const arranged = answersNextToTheirCalls(latestAnswerNextToItsCall(kept));
+    return arranged.map((event) => {
+        const content = clone(event.content);
+        stripAdkCallIds(content);
+        return content;
+    });
+}
+/** Where the current turn starts: the anchor, or earlier when its answers answer earlier calls. */
+function turnStart(events, anchor) {
+    const answered = new Set();
+    for (const event of events.slice(anchor)) {
+        for (const part of event.content?.parts ?? [])
+            if (part.functionResponse?.id)
+                answered.add(part.functionResponse.id);
+    }
+    if (answered.size === 0)
+        return anchor;
+    let start = anchor;
+    for (let i = anchor - 1; i >= 0; i--) {
+        const calls = (events[i]?.content?.parts ?? []).flatMap((p) => (p.functionCall ? [p.functionCall] : []));
+        if (calls.some((c) => (c.id ? answered.has(c.id) : false)))
+            start = i;
+    }
+    return start;
+}
+/**
+ * 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 function projectHistory(events, scope) {
+    const active = activeEvents(events, scope.isolationScope);
+    if ((scope.includeContents ?? 'default') === 'default') {
+        return contentsOf(active, scope.agentName, scope.branch, scope.isolationScope);
+    }
+    for (let i = active.length - 1; i >= 0; i--) {
+        const event = active[i];
+        if (!shouldInclude(event, scope.branch, scope.isolationScope))
+            continue;
+        if (event.author === 'user' || fromAnotherAgent(scope.agentName, event)) {
+            return contentsOf(active.slice(turnStart(active, i)), scope.agentName, scope.branch, scope.isolationScope);
+        }
+    }
+    return [];
+}
+// ── Gemini code execution in the history ─────────────────────────────────────
+/** ADK's BaseCodeExecutor delimiters: the first code block's, and the result's. */
+const CODE_BLOCK = ['```tool_code\n', '\n```'];
+const EXECUTION_RESULT = ['```tool_output\n', '\n```'];
+/**
+ * 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 function convertCodeExecutionParts(content) {
+    const parts = content.parts;
+    if (!parts?.length)
+        return;
+    const last = parts[parts.length - 1];
+    if (last.executableCode) {
+        parts[parts.length - 1] = { text: CODE_BLOCK[0] + (last.executableCode.code || '') + CODE_BLOCK[1] };
+    }
+    else if (parts.length === 1 && last.codeExecutionResult) {
+        const output = last.codeExecutionResult.output;
+        parts[parts.length - 1] = { text: output == null ? '' : EXECUTION_RESULT[0] + output + EXECUTION_RESULT[1] };
+        content.role = 'user';
+    }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * lib/runtime/native/interrupts.ts — approvals on the native loop: the
+ * answer to an `adk_request_confirmation` call runs or refuses the pinned
+ * call before the next model step (WS2-7a, ADR 0028, ADR 0077).
+ *
+ * WHY this file exists:
+ *   A tool that requires approval does not run when called. The loop
+ *   (agentLoop.ts) stores ADK's `adk_request_confirmation` call in place of
+ *   the response, pinning the original call and its arguments, and the run
+ *   ends paused. The person's answer arrives as the next user message: a
+ *   function response to that call carrying `{ confirmed }`. On the ADK
+ *   runtime, LlmAgent's request-confirmation processor reads it before every
+ *   model step and runs the pinned call with the confirmation. This file is
+ *   that processor, case for case, so an approval opened on either runtime
+ *   resumes on the other and both store the same events.
+ *
+ * BEFORE EACH STEP, AS ADK'S PROCESSOR RUNS IT:
+ *   1. The answers: the function responses named `adk_request_confirmation`
+ *      in the latest user event (events on another branch left out), each
+ *      read as `{ confirmed, hint, payload }`, or as JSON under `response`.
+ *      None: nothing happens, and the step goes on as usual.
+ *   2. The gates they answer: every `adk_request_confirmation` call whose id
+ *      an answer names. A request authored by the user is refused
+ *      (`untrusted_request`); one authored by another agent is skipped; one
+ *      whose pinned call has no id or name is refused (`malformed_request`);
+ *      one this agent has already answered the pinned call after is skipped,
+ *      so a later step never runs the call again.
+ *   3. The binding. The pinned call must be one this agent made, by id
+ *      (`unknown_original_call`); its tool must be the agent's
+ *      (`unregistered_tool`); the name and the arguments must equal the
+ *      call's as the model made it (`tool_name_mismatch`,
+ *      `arguments_mismatch`); and the tool must require approval, or have
+ *      asked for it (`confirmation_not_required`). A refusal throws ADK's
+ *      IntentMismatchError text and nothing runs.
+ *   4. The bound calls run through the loop's own call path with the
+ *      confirmation in their context: an approved call runs its tool, a
+ *      refused one answers ADK's refusal. Their response is stored as its
+ *      own event before the step builds its request, so the model reads it.
+ *
+ * Not here: a plain-text "yes" as an answer (ADK's plainTextToolConfirmation,
+ * which no surface turns on), and answers delivered by a remote peer (ADK's
+ * remoteDelivered, which no surface sets).
+ *
+ * QUESTIONS (ask_user, WS2-7b, ADR 0079) need no processor here. ADK runs its
+ * request-input processor (REQUEST_INPUT_LLM_REQUEST_PROCESSOR) next, before
+ * compaction, but it only re-runs a node tool (a workflow run as a tool) that
+ * paused on an `adk_request_input` call; for an agent that lists no node tool
+ * it returns before doing anything, and no native agent lists one (native
+ * refuses workflows). An `ask_user` call is an ordinary long-running call:
+ * the turn runner stores the person's next message as its function response
+ * (lib/runtime/questions.ts questionAnswerPart), and the step reads the call
+ * and the answer side by side from the history (history.ts), as ADK's
+ * content processor does. When workflows run natively (WS4), the node-tool
+ * resume is ported beside approvedCalls, in the same place in the order.
+ *
+ * CREDENTIALS (OAuth consent, WS6-3b, ADR 0085) run first, as ADK runs its
+ * auth preprocessor (AUTH_PREPROCESSOR) before request-confirmation.
+ * grantedCalls is that preprocessor, check for check, with one difference
+ * in what the answer carries:
+ *   1. The answers: the function responses named `adk_request_credential`
+ *      in the last event with content, which must be the user's. None:
+ *      nothing happens.
+ *   2. The requests they answer: `adk_request_credential` calls this agent
+ *      made, by id. An answer naming no such request is ignored, as ADK
+ *      ignores it.
+ *   3. The binding. ADK's answer carries the authorization response (a code
+ *      or the redirect URL), which ADK exchanges in-process with the client
+ *      secret its request event stored. Here the server's callback route has
+ *      already exchanged the code and stored the grant
+ *      (lib/tools/oauthConsent.ts), so the answer carries no credential:
+ *      `{ credentialKey, granted: true }`, bound to the request by its
+ *      credentialKey. An answer that does not bind is ignored.
+ *   4. The paused calls the bound requests name (`function_call_id`, ADK's
+ *      toolset requests aside) run again, from the latest event that made
+ *      them, through the loop's own call path. The tool now reads its grant
+ *      through ctx.accessToken. The response is stored before the step
+ *      builds its request. A later step finds the agent's own events last,
+ *      so the call runs once.
+ *
+ * ADK stays out of this file: an ADK tool an agent still lists is asked
+ * whether it gates through its own checkRequireConfirmation, by shape.
+ */
+import type { ToolConfirmation } from '../../tools/tool.ts';
+import type { TurnFunctionCall } from '../events.ts';
+import type { Session } from '../sessions.ts';
+import type { NativeAgent } from './request.ts';
+/** Why a confirmation does not bind to the call it pins: ADK's IntentMismatchError reasons. */
+export type IntentMismatchReason = 'untrusted_request' | 'malformed_request' | 'unknown_original_call' | 'unregistered_tool' | 'tool_name_mismatch' | 'arguments_mismatch' | 'confirmation_not_required';
+/** A confirmation that does not bind to its pinned call: ADK's IntentMismatchError, by name and text. */
+export declare class IntentMismatchError extends Error {
+    readonly reason: IntentMismatchReason;
+    readonly functionCallId?: string;
+    constructor(reason: IntentMismatchReason, functionCallId?: string);
+}
+/** The pinned calls an answer lets run, each with its confirmation, in the order the gates were stored. */
+export interface ApprovedCalls {
+    calls: TurnFunctionCall[];
+    confirmations: Map<string, ToolConfirmation>;
+    /** The agent's tools by name, as the loop runs calls against them. */
+    tools: Map<string, unknown>;
+}
+interface Scope {
+    session: Session;
+    invocationId: string;
+    branch?: string;
+}
+/**
+ * The pinned calls the latest user message approves or refuses, bound to
+ * the calls this agent made; undefined when it answers no open request.
+ * Throws IntentMismatchError when an answer does not bind (nothing runs).
+ * `contextFor` makes the context a tool's gate check reads.
+ */
+export declare function approvedCalls(agent: NativeAgent, scope: Scope, contextFor: (callId: string) => unknown): Promise<ApprovedCalls | undefined>;
+/** The paused calls a granted consent lets run again, from the event that made them. */
+export interface GrantedCalls {
+    calls: TurnFunctionCall[];
+    /** The agent's tools by name, as the loop runs calls against them. */
+    tools: Map<string, unknown>;
+}
+/**
+ * The paused calls the latest user message resumes by answering this
+ * agent's credential requests; undefined when it answers none (ADK's
+ * AuthPreprocessor, the exchange left to the callback route).
+ */
+export declare function grantedCalls(agent: NativeAgent, scope: Scope): Promise<GrantedCalls | undefined>;
+export {};