melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/runtime/syndicateTurn.js

@@ -0,0 +1,597 @@
+/**
+ * lib/runtime/syndicateTurn.ts — ONE implementation of "run a syndicate for
+ * one user message". The A2A server, the terminal REPL, the background
+ * worker and the observatory's eval harness all call `runSyndicateTurn`, and
+ * so does a package consumer embedding the engine.
+ *
+ * ── Why this exists ───────────────────────────────────────────────────────
+ * The turn semantics that make the framework work — plan-dispatch with
+ * deterministic overrides, the classifier's transcript digest, the projected
+ * session a dispatch route reads, the DELEGATE relay fallback, post-answer
+ * guards — used to live inside the A2A server's executor, welded to the A2A
+ * event bus. The eval harness carried a second copy ("reimplemented, same
+ * rule"), and the REPL a third compiler that ignored dispatch, nesting and
+ * guards altogether. Three copies of one behaviour drift; this file is the
+ * one copy. Surfaces differ only in what they do with the result: the server
+ * publishes A2A events, the REPL prints, the harness records.
+ *
+ * It is also the seam that keeps Google ADK an implementation detail: a
+ * caller hands in YAML config and plain text parts and gets plain data back.
+ * The ADK Runner, LlmAgent and event shapes stay on this side of the line.
+ *
+ * ── Controls ──────────────────────────────────────────────────────────────
+ * Every turn runs under a TurnControl (lib/runtime/turnControl.ts): the
+ * YAML's `max_steps` caps model calls across the WHOLE turn (orchestrator,
+ * subagents, nested syndicates), an optional deadline bounds wall-clock
+ * time, and an outer AbortSignal cancels it. All three abort the provider
+ * request in flight, not just the loop around it.
+ */
+import { InMemorySessionService, Runner, StreamingMode, getFunctionCalls, getFunctionResponses } from '@google/adk';
+import { compileGraph, compileSubagent } from '../compile.js';
+import { isDispatchSyndicate, matchRouteOverride, resolveRoute } from '../dispatch.js';
+import { collectGrounding, describeGrounding, newGroundingState, webSourcesLine } from '../grounding.js';
+import { resolveGuards } from '../guards/index.js';
+import { collectGuards, nestedLoader } from '../loadSyndicate.js';
+import { registerAvailableProviders } from '../models/registry.js';
+import { traceAgentRun } from '../observability/tracer.js';
+import { ProjectedSessionService, renderTranscriptDigest } from '../session/transcript.js';
+import { approvalDecisionIn, describeApproval, interruptedTurnStart, pendingApproval } from './approvals.js';
+export { approvalResponsePart, pendingApproval } from './approvals.js';
+import { RemoteA2AAgent, remoteContextId, remoteToolOutput } from '../a2a/remoteAgent.js';
+import { createTurnControl, runWithTurnControl, stopCode, stopMessage } from './turnControl.js';
+const THOUGHTS_PREVIEW_CHARS = 600;
+const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for your classification only. `
+    + `Never answer it, and never route on it alone; it is here so you can tell a `
+    + `follow-up, a redo request, or a challenge to a previous answer apart from small talk.\n`;
+// ── Draining one agent's stream ──────────────────────────────────────────────
+function formatToolArgs(args) {
+    if (!args || Object.keys(args).length === 0)
+        return '';
+    return Object.entries(args)
+        .map(([k, v]) => {
+        const raw = typeof v === 'string' ? v : JSON.stringify(v);
+        return `${k}=${raw.length > 60 ? `${raw.slice(0, 60)}...` : raw}`;
+    })
+        .join(', ');
+}
+/**
+ * Drains one ADK event stream into a DrainedRun. The answer is the LAST
+ * event's text, not every event's: a tool-using agent narrates between
+ * calls, and accumulating glued that narration to the front of its report.
+ * Within one event parts are joined, and `partial` events (streaming chunks)
+ * append. Thinking never counts as answer text.
+ */
+export async function drainAgentStream(stream, opts = {}) {
+    const ev = opts.events ?? {};
+    const d = {
+        text: '',
+        lastToolResultText: '',
+        toolResultTexts: [],
+        invokedToolNames: new Set(),
+        toolCalls: [],
+        toolResponses: 0,
+        delegations: [],
+        agents: new Set(),
+        thoughts: '',
+        tokens: { input: 0, output: 0, thinking: 0 },
+        eventCount: 0,
+    };
+    const grounding = newGroundingState();
+    let groundingAnnounced = false;
+    let streamed = false;
+    for await (const event of stream) {
+        const e = event;
+        d.eventCount++;
+        ev.onEvent?.(event);
+        if (e.author)
+            d.agents.add(e.author);
+        // Native search grounding rides on the model event, not on a tool call.
+        if (collectGrounding(e, grounding)) {
+            const firstSight = grounding.queries.size + grounding.sources.size > 0 && !groundingAnnounced;
+            ev.log?.(`⌕ Grounding: ${describeGrounding(grounding)}`);
+            // Same shape as a function-tool line so consumers that parse
+            // "Invoking tool:" status lines list it too.
+            if (opts.publishToolStatus && firstSight)
+                ev.onProgress?.('Invoking tool: web_search');
+            groundingAnnounced = true;
+        }
+        if ((e.errorCode || e.errorMessage) && e.errorCode !== 'STOP') {
+            d.error = { code: String(e.errorCode ?? 'ERROR'), message: String(e.errorMessage ?? '') };
+            ev.warn?.(`Error [${d.error.code}]: ${d.error.message}`);
+            break;
+        }
+        if (e.usageMetadata) {
+            // Same aggregation as traceAgentRun: peak prompt, summed completions.
+            d.tokens.input = Math.max(d.tokens.input, e.usageMetadata.promptTokenCount ?? 0);
+            d.tokens.output += e.usageMetadata.candidatesTokenCount ?? 0;
+            d.tokens.thinking += e.usageMetadata.thoughtsTokenCount ?? 0;
+        }
+        const calls = getFunctionCalls(event) ?? [];
+        // Text streamed before a tool call was narration, not the answer.
+        if (streamed && calls.length) {
+            ev.onTextReset?.();
+            streamed = false;
+        }
+        for (const call of calls) {
+            const name = call.name ?? '';
+            const args = (call.args ?? {});
+            if (name === 'transfer_to_agent') {
+                const target = String(args.agentName ?? 'unknown');
+                d.delegations.push(target);
+                ev.log?.(`→ Delegating to: ${target}`);
+                if (opts.publishToolStatus)
+                    ev.onProgress?.(`Delegating to subagent: ${target}`);
+                continue;
+            }
+            if (!name)
+                continue;
+            d.invokedToolNames.add(name);
+            if (opts.subagentNames?.has(name))
+                d.delegations.push(name);
+            d.toolCalls.push({ agent: e.author ?? 'unknown', name, args });
+            ev.log?.(`→ Tool: ${name}(${formatToolArgs(args)})`);
+            if (opts.publishToolStatus)
+                ev.onProgress?.(`Invoking tool: ${name}`);
+        }
+        for (const resp of getFunctionResponses(event) ?? []) {
+            const r = resp;
+            const name = r.name ?? r.functionResponse?.name ?? '';
+            const content = r.response ?? r.functionResponse?.response ?? {};
+            d.toolResponses++;
+            if (name)
+                d.invokedToolNames.add(name);
+            const asString = typeof content === 'string' ? content : JSON.stringify(content);
+            ev.log?.(`← Result: ${name || 'unknown'} — ${asString.length.toLocaleString()} chars`);
+            // Only plain text results are relayable answers — a structured or
+            // base64 payload (image tools) is not.
+            const resultText = typeof content === 'string'
+                ? content
+                : typeof content?.result === 'string'
+                    ? content.result
+                    : '';
+            if (resultText.trim()) {
+                d.lastToolResultText = resultText.trim();
+                d.toolResultTexts.push(resultText.trim());
+            }
+        }
+        let eventText = '';
+        for (const part of event.content?.parts ?? []) {
+            const p = part;
+            if (!p.text)
+                continue;
+            if (p.thought === true) {
+                if (d.thoughts.length < THOUGHTS_PREVIEW_CHARS)
+                    d.thoughts += p.text;
+            }
+            else {
+                eventText += p.text;
+            }
+        }
+        if (eventText)
+            d.text = e.partial === true ? d.text + eventText : eventText;
+        if (opts.streamText && e.partial === true && eventText) {
+            ev.onTextDelta?.(eventText);
+            streamed = true;
+        }
+    }
+    const sourcesLine = webSourcesLine(grounding);
+    // A consumer contract clients parse: "Web sources: a, b",
+    // published once, after the stream, with the full set.
+    if (opts.publishToolStatus && sourcesLine)
+        ev.onProgress?.(sourcesLine);
+    if (grounding.queries.size || grounding.sources.size) {
+        d.grounding = { queries: [...grounding.queries], sources: [...grounding.sources] };
+    }
+    d.text = d.text.trim();
+    return d;
+}
+/** True when an orchestrator's text is just the name of a tool it called —
+ *  the degenerate relay ("FinancialAnalyst", 3 tokens). Deliberately narrow:
+ *  short real answers are legitimate, so no length heuristic. */
+export function echoesToolName(text, toolNames) {
+    const normalize = (s) => s.replace(/[^a-z0-9]/gi, '').toLowerCase();
+    if (!text)
+        return false;
+    for (const name of toolNames)
+        if (normalize(name) === normalize(text))
+            return true;
+    return false;
+}
+// ── The turn ─────────────────────────────────────────────────────────────────
+/**
+ * Runs one user message through a syndicate and returns what the user
+ * receives. Never throws for model or tool failures — those come back as
+ * `status: 'failed'` with an error. It throws only for programming errors
+ * (a session service that rejects, a config naming a route it does not
+ * declare), which a surface should treat as an internal error.
+ */
+export async function runSyndicateTurn(opts) {
+    const { config } = opts;
+    // A model id given as a string resolves through ADK's LLMRegistry. Without
+    // the framework's adapters registered there, Gemini would be ADK's own
+    // class, which bypasses traceLlmGeneration: no max_steps, no cancel. A
+    // caller that resolves models itself (the A2A server) is left alone.
+    if (!opts.compile?.resolveModel)
+        registerAvailableProviders();
+    const control = createTurnControl({
+        maxLlmCalls: opts.maxLlmCalls ?? config.max_steps,
+        deadlineMs: opts.deadlineMs,
+        signal: opts.signal,
+    });
+    try {
+        return await runWithTurnControl(control, () => runTurnInner(opts, control));
+    }
+    finally {
+        control.dispose();
+    }
+}
+async function runTurnInner(opts, control) {
+    const { config, appName, userId, sessionId, sessionService } = opts;
+    const ev = opts.events ?? {};
+    // Nested references load from the definition's bundle when it has one
+    // (a registry version, ADR 0018 item 6), else from files.
+    const compileOpts = { ...opts.compile, loadNested: opts.compile?.loadNested ?? nestedLoader(config) };
+    const transform = opts.transformAgent ?? ((a) => a);
+    const subagentNames = new Set((config.subagents ?? []).map((s) => s.name));
+    const trace = opts.trace === false ? undefined : opts.trace ?? {};
+    const parts = opts.parts.map((p) => (typeof p === 'string' ? { text: p } : p));
+    const messageText = parts.map((p) => (typeof p.text === 'string' ? p.text : '')).join('\n');
+    const result = {
+        status: 'completed',
+        text: '',
+        relayFallback: false,
+        guardNotes: [],
+        resumedSession: false,
+        llmCalls: 0,
+        usage: { llmCalls: 0, inputTokens: 0, outputTokens: 0, thinkingTokens: 0 },
+    };
+    const finish = () => {
+        result.llmCalls = control.llmCalls;
+        result.usage = {
+            llmCalls: control.llmCalls,
+            inputTokens: control.inputTokens,
+            outputTokens: control.outputTokens,
+            thinkingTokens: control.thinkingTokens,
+        };
+        if (control.stopReason) {
+            result.stopReason = control.stopReason;
+            result.status = control.stopReason === 'canceled' ? 'canceled' : 'failed';
+            result.error = { code: stopCode(control.stopReason), message: stopMessage(control.stopReason, control) };
+        }
+        return result;
+    };
+    // ── Session ────────────────────────────────────────────────────────────────
+    const existing = await sessionService.getSession({ appName, userId, sessionId });
+    if (existing) {
+        result.resumedSession = true;
+    }
+    else {
+        await sessionService.createSession({ appName, userId, sessionId });
+    }
+    // A guard rewrites the answer after it is complete, so a guarded
+    // syndicate never streams: nothing may leave before the guard has read it.
+    const guarded = collectGuards(config, compileOpts.loadNested).length > 0;
+    // ── Approvals (ADR 0028) ───────────────────────────────────────────────────
+    // A message answering an approval resumes the agent that asked; the answer
+    // must name the request still open in this conversation.
+    const decision = approvalDecisionIn(parts);
+    let resuming;
+    if (decision) {
+        resuming = pendingApproval(existing?.events ?? []);
+        if (!resuming || resuming.id !== decision.id) {
+            result.status = 'failed';
+            result.error = { code: 'NO_PENDING_APPROVAL', message: `No approval ${decision.id} is waiting in this conversation.` };
+            return finish();
+        }
+        // The log names the call, not its arguments: they are user content.
+        ev.log?.(`✓ Approval ${decision.approved ? 'granted' : 'refused'}: ${resuming.agent} → ${resuming.tool}`);
+    }
+    /** After the answering run: is a gated call now waiting? */
+    const awaitingApproval = async (agentName) => {
+        const after = await sessionService.getSession({ appName, userId, sessionId });
+        const pending = pendingApproval(after?.events ?? []);
+        return pending && pending.agent === agentName ? pending : undefined;
+    };
+    const pause = (pending) => {
+        result.status = 'input-required';
+        result.approval = pending;
+        result.text = `Approval needed: ${describeApproval(pending)}.`;
+        ev.log?.(`⏸ Approval needed: ${pending.agent} → ${pending.tool}`);
+        return finish();
+    };
+    /** Run ONE agent against ONE session, under the turn's controls. */
+    const runAgent = async (params) => {
+        const runner = new Runner({
+            agent: params.agent,
+            appName,
+            sessionService: params.sessions,
+            ...(opts.memoryService ? { memoryService: opts.memoryService } : {}),
+        });
+        let stream = runner.runAsync({
+            userId,
+            sessionId: params.sid,
+            newMessage: { role: 'user', parts: params.userParts },
+            abortSignal: control.signal,
+            ...(opts.streaming ? { runConfig: { streamingMode: StreamingMode.SSE } } : {}),
+        });
+        if (trace) {
+            stream = traceAgentRun(stream, {
+                syndicateName: trace.syndicateName ?? config.syndicate_name ?? appName,
+                bindings: trace.bindings ?? config.variables ?? {},
+                input: params.userParts,
+                route: params.route,
+                // Identity: the CONVERSATION id, not the classifier's throwaway lane —
+                // every stage of one turn shares session and task ids.
+                sessionId,
+                userId,
+                taskId: trace.taskId,
+                stage: params.stage,
+                configHash: trace.configHash,
+                attributes: trace.attributes,
+                onSpanStart: trace.onSpanStart,
+                onEnd: () => ({
+                    'syndicate.relay_fallback': params.stage === 'delegate' && !!params.relayFallback?.(),
+                    ...(control.stopReason ? { 'syndicate.stop_reason': control.stopReason } : {}),
+                    'syndicate.llm_calls': control.llmCalls,
+                }),
+            });
+        }
+        try {
+            return await drainAgentStream(stream, {
+                events: params.stage === 'classify' ? { ...ev, onEvent: undefined } : ev,
+                publishToolStatus: params.publishToolStatus,
+                subagentNames,
+                streamText: params.stage !== 'classify' && !guarded,
+            });
+        }
+        catch (err) {
+            // A provider call aborted by cancel / deadline surfaces as a thrown
+            // AbortError. That is a stop, not a crash.
+            if (control.stopReason) {
+                return emptyRun({ code: stopCode(control.stopReason), message: stopMessage(control.stopReason, control) });
+            }
+            throw err;
+        }
+    };
+    let answer;
+    if (isDispatchSyndicate(config)) {
+        // ══ PLAN ═════════════════════════════════════════════════════════════
+        // Deterministic overrides first: when the message itself decides the
+        // route there is nothing to classify, and the classifier call is skipped.
+        const warnings = [];
+        let resolution = resuming ? null : matchRouteOverride(messageText, config, warnings);
+        let decidedBy = 'override';
+        for (const w of warnings)
+            ev.warn?.(w);
+        if (resuming) {
+            if (!subagentNames.has(resuming.agent)) {
+                throw new Error(`Approval ${resuming.id} was raised by '${resuming.agent}', which is not a route of this syndicate.`);
+            }
+            resolution = { route: resuming.agent, reason: 'resuming an approval', fellBack: false, fallbackReason: '', viaOverride: false };
+            decidedBy = 'approval';
+        }
+        else if (resolution) {
+            ev.log?.(`⇄ Route pinned by override: ${resolution.route}`);
+        }
+        else if (opts.forceRoute) {
+            if (!subagentNames.has(opts.forceRoute)) {
+                throw new Error(`forceRoute '${opts.forceRoute}' is not a declared subagent`);
+            }
+            resolution = { route: opts.forceRoute, reason: 'forced by the caller', fellBack: false, fallbackReason: '', viaOverride: false };
+            decidedBy = 'forced';
+        }
+        else {
+            decidedBy = 'classifier';
+            // The classifier reads the SHARED transcript as an input digest and runs
+            // in a throwaway in-memory lane, so its JSON verdicts never enter the
+            // conversation the next specialist reads.
+            const routerAgent = transform(await compileGraph(config, compileOpts));
+            const routerSid = `${sessionId}::route`;
+            const routerSessions = new InMemorySessionService();
+            await routerSessions.createSession({ appName, userId, sessionId: routerSid });
+            const shared = await sessionService.getSession({ appName, userId, sessionId });
+            const digest = renderTranscriptDigest(shared?.events ?? []);
+            const routerParts = digest
+                ? [{ text: `${CLASSIFIER_PREAMBLE}${digest}\n\n--- MESSAGE TO CLASSIFY ---\n${messageText}` }]
+                : parts;
+            const plan = await runAgent({
+                agent: routerAgent,
+                sid: routerSid,
+                userParts: routerParts,
+                sessions: routerSessions,
+                stage: 'classify',
+                publishToolStatus: false,
+            });
+            result.classifier = plan;
+            if (control.stopReason)
+                return finish();
+            // Fail-static: a dead classifier costs the user a good route, never
+            // their answer. An empty payload resolves to default_route.
+            resolution = resolveRoute(plan.error ? '' : plan.text, config);
+            if (plan.error) {
+                ev.warn?.(`Router failed [${plan.error.code}] — defaulting to '${resolution.route}'.`);
+            }
+            else if (resolution.fellBack) {
+                ev.warn?.(`Routing fell back to '${resolution.route}': ${resolution.fallbackReason}`);
+            }
+        }
+        const routeCfg = (config.subagents ?? []).find((s) => s.name === resolution.route);
+        if (!routeCfg)
+            throw new Error(`Dispatch failed: no subagent named '${resolution.route}' is declared.`);
+        result.route = { ...resolution, decidedBy };
+        const routeNote = resolution.reason ? ` — ${resolution.reason}` : '';
+        ev.log?.(`⇄ Route: ${resolution.route}${routeNote}`);
+        ev.onProgress?.(`Routed to ${resolution.route}${routeNote}`);
+        // ══ DISPATCH ═════════════════════════════════════════════════════════
+        if (routeCfg.a2a_agent_url) {
+            // A remote route answers over A2A; its conversation id is derived from
+            // this one, so follow-ups reach the same remote conversation.
+            answer = await runRemoteRoute(routeCfg.name, routeCfg.a2a_agent_url, messageText, sessionId, control, ev);
+        }
+        else {
+            // The route answers directly in the SHARED session, read through a
+            // projection: ADK would otherwise render other agents' turns as user
+            // speech mixed with their tool payloads (lib/session/transcript.ts).
+            const routeAgent = transform(await compileSubagent(routeCfg, compileOpts));
+            answer = await runAgent({
+                agent: routeAgent,
+                sid: sessionId,
+                userParts: parts,
+                // Resuming an approval: the interrupted turn is replayed raw, so ADK
+                // finds the call the approval answers (ADR 0028).
+                sessions: new ProjectedSessionService(sessionService, routeCfg.name, resuming ? { rawFrom: (events) => interruptedTurnStart(events, resuming.id) } : {}),
+                stage: 'dispatch',
+                route: resolution,
+                publishToolStatus: true,
+            });
+        }
+        result.answer = answer;
+        if (answer.error || control.stopReason) {
+            result.status = 'failed';
+            result.failedStage = 'dispatch';
+            result.error = answer.error;
+            return finish();
+        }
+        if (!routeCfg.a2a_agent_url && routeCfg.require_approval?.length) {
+            const pending = await awaitingApproval(routeCfg.name);
+            if (pending)
+                return pause(pending);
+        }
+        result.text = answer.text;
+        if (!result.text) {
+            // Naming the route turns a blank reply into a lead (the XScout outage
+            // shape: the specialist ran and returned nothing because its provider
+            // rejected the call upstream).
+            ev.warn?.(`Route '${resolution.route}' produced no output.`);
+            result.text = `${resolution.route} returned no output — the server logs carry the upstream error.`;
+        }
+    }
+    else {
+        // ══ DELEGATE ═════════════════════════════════════════════════════════
+        // Subagents are AgentTools; the orchestrator relays the answer it got.
+        const orchestrator = transform(await compileGraph(config, compileOpts));
+        let drained;
+        answer = await runAgent({
+            agent: orchestrator,
+            sid: sessionId,
+            userParts: parts,
+            sessions: sessionService,
+            stage: 'delegate',
+            publishToolStatus: true,
+            relayFallback: () => !!drained && (!drained.text || echoesToolName(drained.text, drained.invokedToolNames)) && !!drained.lastToolResultText,
+        });
+        drained = answer;
+        result.answer = answer;
+        if (answer.error || control.stopReason) {
+            result.status = 'failed';
+            result.failedStage = 'delegate';
+            result.error = answer.error;
+            return finish();
+        }
+        if (config.orchestrator.require_approval?.length) {
+            const pending = await awaitingApproval(config.orchestrator.name);
+            if (pending)
+                return pause(pending);
+        }
+        result.text = answer.text;
+        // Failed-relay fallback: an orchestrator can botch the hop that relays a
+        // specialist's answer — STOP with no text, or the bare tool NAME as its
+        // text. Both discard a fully-formed result, so the last tool result is
+        // returned deterministically instead of retrying the relay.
+        const echoed = echoesToolName(result.text, answer.invokedToolNames);
+        if ((!result.text || echoed) && answer.lastToolResultText) {
+            ev.warn?.(`Orchestrator ${echoed ? `echoed the tool name ("${result.text}")` : 'emitted no text'} — `
+                + `relaying last tool result verbatim (${answer.lastToolResultText.length.toLocaleString()} chars).`);
+            result.text = answer.lastToolResultText;
+            result.relayFallback = true;
+        }
+    }
+    // ══ GUARDS ═══════════════════════════════════════════════════════════════
+    // Named in the syndicate's `guards:` list (and any nested syndicate's). They
+    // REWRITE rather than retry, on the answering turn's text with every tool
+    // result it produced. The classifier never reaches here.
+    const guardNames = collectGuards(config, compileOpts.loadNested);
+    if (result.text && guardNames.length) {
+        const inputs = answer.toolResultTexts;
+        for (const guard of resolveGuards(guardNames, (n) => ev.warn?.(`Unknown guard '${n}' — ignored`))) {
+            try {
+                const out = await guard.run(result.text, inputs);
+                // Always logged, notes or not: a guard that ran clean must be
+                // distinguishable from one that never ran.
+                ev.log?.(`⛨ ${guard.name}: checked ${result.text.length.toLocaleString()} chars against ${inputs.length} tool result${inputs.length === 1 ? '' : 's'} — ${out.notes.length} note${out.notes.length === 1 ? '' : 's'}`);
+                for (const note of out.notes) {
+                    ev.log?.(`⛨ ${guard.name}: ${note}`);
+                    ev.onProgress?.(`Guard ${guard.name}: ${note}`);
+                    result.guardNotes.push(`${guard.name}: ${note}`);
+                }
+                result.text = out.text;
+            }
+            catch (guardErr) {
+                const msg = guardErr instanceof Error ? guardErr.message : String(guardErr);
+                ev.warn?.(`Guard '${guard.name}' failed (answer shipped unguarded): ${msg}`);
+                ev.onProgress?.(`Guard ${guard.name}: did not run (${msg})`);
+                result.guardNotes.push(`${guard.name}: did not run (${msg})`);
+            }
+        }
+    }
+    return finish();
+}
+/** A plan-dispatch route that is a remote A2A agent (`a2a_agent_url`). */
+async function runRemoteRoute(name, url, messageText, sessionId, control, ev) {
+    ev.onProgress?.(`Invoking remote agent: ${name}`);
+    try {
+        const answer = await new RemoteA2AAgent(url).send(messageText, {
+            contextId: remoteContextId(sessionId, name),
+            signal: control.signal,
+        });
+        const run = emptyRun();
+        run.agents.add(name);
+        run.delegations.push(name);
+        if (answer.state === 'completed') {
+            run.text = answer.text;
+        }
+        else {
+            run.error = { code: `REMOTE_${answer.state.toUpperCase().replace(/-/g, '_')}`, message: remoteToolOutput(name, answer) };
+        }
+        return run;
+    }
+    catch (err) {
+        if (control.stopReason)
+            return emptyRun({ code: stopCode(control.stopReason), message: stopMessage(control.stopReason, control) });
+        return emptyRun({ code: 'REMOTE_UNREACHABLE', message: `${name}: ${err instanceof Error ? err.message : String(err)}` });
+    }
+}
+function emptyRun(error) {
+    return {
+        text: '',
+        lastToolResultText: '',
+        toolResultTexts: [],
+        invokedToolNames: new Set(),
+        toolCalls: [],
+        toolResponses: 0,
+        delegations: [],
+        agents: new Set(),
+        thoughts: '',
+        tokens: { input: 0, output: 0, thinking: 0 },
+        eventCount: 0,
+        ...(error ? { error } : {}),
+    };
+}
+/**
+ * Distils the conversation into long-term memory. Call it after the answer
+ * has been delivered — it never delays the reply, and a failure here never
+ * fails the turn. Returns false when there was nothing to ingest.
+ */
+export async function ingestTurnMemory(params) {
+    const session = await params.sessionService.getSession({
+        appName: params.appName,
+        userId: params.userId,
+        sessionId: params.sessionId,
+    });
+    if (!session || session.events.length === 0)
+        return false;
+    await params.memoryService.addSessionToMemory(session, params.extractionRules, {
+        extractionModel: params.extractionModel,
+    });
+    return true;
+}