melchizedek-agents 1.0.2 → 1.1.0

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

@@ -13,12 +13,21 @@
  *
  * ONE CALL, AS ADK'S AgentTool RAN 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.
+ *   2. The subagent's session: filed under the agent path (childAppName,
+ *      ADR 0111), with the caller's user id and session id: the caller's
+ *      app name, the caller's name and the subagent's at the top
+ *      (`<app>/<caller>/<subagent>`), the caller's app name and the
+ *      subagent's below it (`<app>/<caller>/<subagent>/<inner>`). 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. ADK filed it under the subagent's name alone, so two syndicates
+ *      with a same-named subagent on one conversation shared it. A session
+ *      stored under that old key is still read (legacyChild): when no
+ *      session exists under the path and the caller has called the
+ *      subagent before (or is resuming a pause found there), the old one is
+ *      continued, so a stored conversation resumes where it stopped.
  *   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
@@ -34,13 +43,30 @@
  *      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.
+ * A PAUSE INSIDE A SUBAGENT (an ask_user call, an approval request, or a
+ * pause inside its own delegated call) reaches the caller (ADR 0110, which
+ * lifts ADR 0028's refusal). The child run ends paused; the call resolves to
+ * a SubagentPause naming the ids it waits on, and the caller stores no
+ * response to it: the call stays open, and the caller's run ends paused too
+ * (agentLoop.ts). The turn finds the pause by walking down the open calls
+ * (interrupts.ts delegatedPauses) and reports it with the agent path. The
+ * answer comes back as the caller's next user message; the caller resumes
+ * the open call (resumeSubagent), which stores the same answer parts as
+ * the child's next message, under a fresh invocation id, and runs the
+ * child's loop on: it reads the answer from its own session as a top-level
+ * agent reads it (an approval runs or refuses its pinned call, a question's
+ * answer is the call's response), finishes, and its answer is the open
+ * call's response. A child that pauses again leaves the call open again.
  *
- * Calls to subagents in one step run one after another, in call order, as
- * ADK runs them; running them concurrently is WS6.
+ * CALLS TO SUBAGENTS IN ONE STEP RUN CONCURRENTLY (ADR 0116), under the
+ * caller's `max_concurrency` (the syndicate's root key, default
+ * DEFAULT_MAX_CONCURRENCY): agentLoop.ts runs each delegated call through
+ * the step's DelegationGate, which starts them in call order as slots free
+ * up, and runs two calls to the same subagent (one child session) one after
+ * the other. The step's responses are stored once every call has answered,
+ * in call order, whatever order the children finished in; a child that
+ * pauses leaves its call open while the others finish and are stored. ADK
+ * ran them one after another; `max_concurrency: 1` keeps that order.
  *
  * NESTED SYNDICATES: a `yaml_reference` subagent is the nested syndicate's
  * orchestrator, named as the entry, listing its own subagent tools. It runs
@@ -49,6 +75,13 @@
  *
  * A NESTED WORKFLOW (ADR 0098): a `yaml_reference` to a workflow syndicate
  * is a workflowSubagentTool, holding the whole graph as a WorkflowSubagent.
+ * A walk that ends paused (an ask_user node's question, an agent node's
+ * approval request) leaves the call open as a child loop's pause does
+ * (ADR 0111): the call resolves to a SubagentPause naming the walk's open
+ * interrupts, and resumeWorkflowSubagent walks the graph again on the
+ * answer, which the walk's own resume (lib/workflow/resume.ts) reads as it
+ * reads a top-level workflow's. An `ask_user` answer reaches the walk as
+ * ADK's explicit reply to its `adk_request_input` call.
  * 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
@@ -69,6 +102,7 @@ import { randomUUID } from 'node:crypto';
 import { resolveAdapter } from '../../models/registry.js';
 import { createTurnEvent } from '../events.js';
 import { TEMP_STATE_PREFIX } from '../sessions.js';
+import { REQUEST_INPUT_CALL } from './history.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. */
@@ -128,13 +162,91 @@ export function subagentOf(tool) {
         return agent;
     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;
+// ── Running one call ─────────────────────────────────────────────────────────
+/**
+ * A delegated call whose child run ended paused (ADR 0110): the ids the
+ * child waits on. The caller stores no response to the call and ends its
+ * own run paused.
+ */
+export class SubagentPause {
+    pending;
+    constructor(pending) {
+        this.pending = pending;
+    }
+}
+/** Delegated calls one step runs at once when the syndicate sets no `max_concurrency` (ADR 0116). */
+export const DEFAULT_MAX_CONCURRENCY = 4;
+/**
+ * The delegated calls of one step (ADR 0116): at most `limit` run at once,
+ * started in the order they entered (agentLoop.ts enters them in call
+ * order, synchronously, before any of them runs), and calls sharing a key
+ * (the subagent's name, so one child session) run one after another in
+ * that order. A slot is held from the call's start to its release, which
+ * comes as soon as the child's run ends: what the step does after (self-
+ * correction's bookkeeping, which waits on earlier calls) holds no slot. A
+ * call waiting on an earlier same-key call holds its slot meanwhile: the
+ * earlier call already holds one, so the wait always ends.
+ */
+export class DelegationGate {
+    limit;
+    active = 0;
+    waiting = [];
+    lanes = new Map();
+    constructor(limit = DEFAULT_MAX_CONCURRENCY) {
+        this.limit = Number.isInteger(limit) && limit > 0 ? limit : DEFAULT_MAX_CONCURRENCY;
+    }
+    /** Enters one call under `key`, behind every call entered before it. */
+    enter(key) {
+        let granted = false;
+        let released = false;
+        let freeLane;
+        const laneDone = new Promise((resolve) => (freeLane = resolve));
+        const slot = new Promise((resolve) => {
+            this.waiting.push(() => {
+                granted = true;
+                resolve();
+            });
+            this.pump();
+        });
+        const before = this.lanes.get(key);
+        this.lanes.set(key, laneDone);
+        const ready = Promise.all([slot, before]).then(() => undefined);
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            freeLane();
+            if (granted) {
+                this.active -= 1;
+                this.pump();
+            }
+            else {
+                // Never started (a step that failed before reaching the child): the slot it would have taken is not held, and it never will be.
+                void slot.then(() => {
+                    this.active -= 1;
+                    this.pump();
+                });
+            }
+        };
+        return { ready, release };
+    }
+    /** Runs `run` under a ticket for `key`: once ready, the ticket released when it settles. */
+    async run(key, run) {
+        const ticket = this.enter(key);
+        try {
+            await ticket.ready;
+            return await run();
+        }
+        finally {
+            ticket.release();
+        }
+    }
+    pump() {
+        while (this.active < this.limit && this.waiting.length > 0) {
+            this.active += 1;
+            this.waiting.shift()();
+        }
+    }
 }
 /** ADK's AgentTool answer: the last event's non-thought text, joined by a newline; parsed under an output schema. */
 function answerOf(agent, last) {
@@ -148,11 +260,49 @@ function answerOf(agent, last) {
         .join('\n');
     return agent.outputSchema ? JSON.parse(text) : text;
 }
-/** The child's session, as ADK's AgentTool gets or creates it: under the subagent's name, from the caller's state the first time. */
-async function childSession(name, context, scope) {
+/**
+ * The app name a delegated call's child session is filed under (ADR 0111):
+ * the agent path. Below a top-level agent, its app name, its name and the
+ * subagent's (`<app>/<caller>/<subagent>`); below a delegated subagent,
+ * whose own session is already filed under its path, that app name and the
+ * subagent's. Agent names are identifiers (lib/syndicateSchema.ts), so
+ * never hold a `/`.
+ */
+export function childAppName(parent, caller, name) {
+    return parent.delegated ? `${parent.appName}/${name}` : `${parent.appName}/${caller}/${name}`;
+}
+/**
+ * The session a delegated call ran in before ADR 0111, filed under the
+ * subagent's name alone, when it is the one to continue (`continues`): the
+ * caller of a stored conversation called the subagent there before, or a
+ * pause was found waiting in it. Read only when no session exists under the
+ * agent path.
+ */
+export async function legacyChild(sessions, key, name, continues) {
+    if (!continues)
+        return undefined;
+    return sessions.get({ appName: name, userId: key.userId, sessionId: key.sessionId });
+}
+/** Whether `caller` called `name` in `events` in a call other than `callId`: the subagent ran for it before. */
+function calledBefore(events, caller, name, callId) {
+    return events.some((e) => e.author === caller && (e.content?.parts ?? []).some((p) => p.functionCall?.name === name && p.functionCall.id !== callId));
+}
+/**
+ * The child's session, as ADK's AgentTool gets or creates it: filed under
+ * the agent path (childAppName), from the caller's state the first time. A
+ * session under the old key is continued when the caller called the
+ * subagent before, or when `resuming` a pause found there (legacyChild):
+ * a syndicate that never called it, another syndicate's caller included,
+ * starts its own.
+ */
+async function childSession(name, context, scope, resuming) {
     const { sessions, session: parent } = scope.ctx;
-    const key = { appName: name, userId: parent.userId, sessionId: parent.id };
-    return (await sessions.get(key)) ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
+    const key = { appName: childAppName({ appName: parent.appName, delegated: scope.ctx.delegated === true }, scope.caller, name), userId: parent.userId, sessionId: parent.id };
+    const own = await sessions.get(key);
+    if (own)
+        return own;
+    const legacy = await legacyChild(sessions, key, name, resuming || calledBefore(parent.events, scope.caller, name, context.functionCallId));
+    return legacy ?? (await sessions.create({ ...key, state: { ...scope.stateBase, ...context.stateDelta } }));
 }
 /** Step 5: an event's state writes, `temp:` keys aside, into the call's state delta. */
 function recordState(event, context) {
@@ -168,13 +318,22 @@ function recordState(event, context) {
  * 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));
+    return runChild(agent, { role: 'user', parts: [{ text: args.request }] }, context, scope, false);
+}
+/**
+ * Resumes a delegated call the child left paused (ADR 0110): `answer` (the
+ * caller's user message parts that answer what waits below the call) is
+ * stored as the child's next message and the child's loop runs on, as
+ * runSubagent runs it. Resolves as runSubagent does, a SubagentPause again
+ * when the child pauses again.
+ */
+export function resumeSubagent(agent, answer, context, scope) {
+    return runChild(agent, { role: 'user', parts: answer }, context, scope, true);
 }
-async function runChild(agent, args, context, scope) {
+async function runChild(agent, content, context, scope, resuming) {
     const { ctx, signal } = scope;
     const { sessions } = ctx;
-    const content = { role: 'user', parts: [{ text: args.request }] };
-    const session = await childSession(agent.name, context, scope);
+    const session = await childSession(agent.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
     const invocationId = `e-${randomUUID()}`;
@@ -187,24 +346,35 @@ async function runChild(agent, args, context, scope) {
         invocationId,
         userContent: content,
         stream: false,
+        // Its own delegations are filed below its path (childAppName, ADR 0111).
+        delegated: true,
         // 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).
+        // The parent's grants, pinned to the root's app (ADR 0072). Not its consent step: an OAuth
+        // consent inside a subagent is not carried to the caller (ADR 0085, ADR 0110).
         ...(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) {
+    for (;;) {
+        const next = await loop.next();
+        if (next.done) {
+            // A child that ended waiting on a person leaves the call open (ADR 0110).
+            if (next.value.reason === 'paused' && !signal?.aborted)
+                return new SubagentPause(next.value.pending ?? []);
+            break;
+        }
         // ADK's Runner stops yielding once the turn stopped: the answer is the last event it yielded.
-        if (signal?.aborted)
+        if (signal?.aborted) {
+            await loop.return(undefined);
             break;
-        recordState(event, context);
-        last = event;
+        }
+        recordState(next.value, context);
+        last = next.value;
     }
     return answerOf(agent, last);
 }
@@ -215,11 +385,26 @@ async function runChild(agent, args, context, scope) {
  * yielded event's text, '' for none. Throws what the walk throws.
  */
 export function runWorkflowSubagent(workflow, args, context, scope) {
-    return inTurn(scope.queue, () => walkChild(workflow, args, context, scope));
+    return walkChild(workflow, [{ text: args.request }], context, scope, false);
 }
-async function walkChild(workflow, args, context, scope) {
+/** The engine's ask_user tool name (lib/runtime/questions.ts ASK_USER). */
+const ASK_USER_CALL = 'ask_user';
+/**
+ * Resumes a delegated call whose nested workflow ended paused (ADR 0111):
+ * the graph is walked again on `answer` (the caller's user message parts
+ * that answer the walk's open interrupt), which the walk's resume reads as
+ * it reads a top-level workflow's. An approval decision goes as it came; an
+ * `ask_user` answer goes as ADK's explicit reply to the `adk_request_input`
+ * call it answers, under that call's name. Resolves as runWorkflowSubagent
+ * does, a SubagentPause again when the walk pauses again.
+ */
+export function resumeWorkflowSubagent(workflow, answer, context, scope) {
+    const parts = answer.map((p) => (p.functionResponse?.name === ASK_USER_CALL ? { functionResponse: { ...p.functionResponse, name: REQUEST_INPUT_CALL } } : p));
+    return walkChild(workflow, parts, context, scope, true);
+}
+async function walkChild(workflow, userParts, context, scope, resuming) {
     const { ctx, signal } = scope;
-    const session = await childSession(workflow.name, context, scope);
+    const session = await childSession(workflow.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
     const walk = workflow.walk({
@@ -227,7 +412,7 @@ async function walkChild(workflow, args, context, scope) {
         appName: session.appName,
         userId: session.userId,
         sessionId: session.id,
-        userParts: [{ text: args.request }],
+        userParts,
         adapterFor: ctx.adapterFor ?? resolveAdapter,
         // As runChild: ADK's AgentTool runs its sub-runner without the reflect-and-retry plugins (ADR 0075).
         selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
@@ -237,9 +422,20 @@ async function walkChild(workflow, args, context, scope) {
         ...(ctx.credentials ? { credentials: ctx.credentials } : {}),
     });
     let last;
-    for await (const event of walk) {
-        if (signal?.aborted)
+    for (;;) {
+        const next = await walk.next();
+        if (next.done) {
+            // A walk that ended waiting on a person leaves the call open (ADR 0111).
+            const paused = next.value?.run?.interruptIds ?? [];
+            if (paused.length > 0 && !signal?.aborted)
+                return new SubagentPause(paused);
+            break;
+        }
+        if (signal?.aborted) {
+            await walk.return(undefined);
             break;
+        }
+        const event = next.value;
         if (event.partial)
             continue;
         recordState(event, context);

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

@@ -80,12 +80,38 @@
  *      builds its request. A later step finds the agent's own events last,
  *      so the call runs once.
  *
+ * PAUSES INSIDE DELEGATED SUBAGENTS (WS6-2a, ADR 0110). A subagent runs in
+ * its own child session (delegate.ts); an approval request or question it
+ * leaves open ends its run paused, and its caller leaves the delegated
+ * call open (no response stored) and ends paused too, up to the turn.
+ * delegatedPauses finds such a pause from any session by walking down:
+ * each call its agent left open (openCalls) leads to the child session
+ * under the call's name, whose own open request or question is the pause,
+ * or whose own open call leads one level further. The answer travels back
+ * down the same way: before each step, the loop resumes the open call
+ * whose pause the latest user message answers (agentLoop.ts), and the
+ * child reads the same answer from its own session, as it would at the top.
+ *
+ * NESTED SYNDICATES (WS6-2b, ADR 0111). The child session of a call is the
+ * one runSubagent files it under: the agent path (delegate.ts childAppName),
+ * else, for a conversation stored before ADR 0111, the subagent's name
+ * alone (legacyChild). A nested delegate syndicate is its orchestrator
+ * there, so the walk goes on through its open calls. A nested workflow
+ * syndicate holds a paused walk there instead: its own pause record (the
+ * workflow's event naming every interrupt it left open, authored by the
+ * workflow under the call's name) makes an approval request an agent node
+ * raised, or an ask_user node's question, the pause, with the node that
+ * asked at the end of the path. The walk stops there: a pause inside a
+ * workflow node's own delegation does not run (lib/workflow/agentNode.ts).
+ *
  * 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 { PendingInput } from '../../workflowConfig.ts';
+import type { PendingApproval } from '../approvals.ts';
+import type { TurnEvent, TurnFunctionCall, TurnPart } from '../events.ts';
+import type { Session, SessionService } 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';
@@ -106,6 +132,8 @@ interface Scope {
     session: Session;
     invocationId: string;
     branch?: string;
+    /** The session is a delegated subagent's, filed under its agent path (delegate.ts childAppName). */
+    delegated?: boolean;
 }
 /**
  * The pinned calls the latest user message approves or refuses, bound to
@@ -126,4 +154,75 @@ export interface GrantedCalls {
  * AuthPreprocessor, the exchange left to the callback route).
  */
 export declare function grantedCalls(agent: NativeAgent, scope: Scope): Promise<GrantedCalls | undefined>;
+/**
+ * An approval request or a question waiting inside a delegated call: the
+ * open call that leads to it from the session it was found from, and on
+ * down, to the agent that asked.
+ */
+export interface DelegatedPause {
+    /** The agents from the one that made the open call down to the one that asked: `[caller, subagent, …, asker]`. */
+    path: string[];
+    /** The open subagent calls on that path, by id, the outermost first. */
+    callIds: string[];
+    /** The approval request, when the asker waits on one; its `path` is set. */
+    approval?: PendingApproval;
+    /** The question, when the asker waits on one; its `path` is set. */
+    question?: PendingInput;
+}
+/** Where a session's delegated calls opened their child sessions: the store, and the caller's user and session ids. */
+export interface DelegationKey {
+    sessions: Pick<SessionService, 'get'>;
+    userId: string;
+    sessionId: string;
+    /**
+     * The app name of the session whose events are walked: its children are
+     * filed below it (delegate.ts childAppName, ADR 0111). Absent, only the
+     * children a conversation stored before ADR 0111 holds are found.
+     */
+    appName?: string;
+    /** The session walked is a delegated subagent's, already filed under its agent path. */
+    delegated?: boolean;
+}
+/**
+ * The calls an agent made that are still open: no later event answers it,
+ * and the person has not written since. Only an agent's calls count (a
+ * call in a user-authored event is never one), and the engine's own
+ * framework calls are left out. `author`, when given, keeps one agent's
+ * calls. Latest event first, calls in call order.
+ */
+export declare function openCalls(events: readonly TurnEvent[], author?: string): Array<{
+    author: string;
+    call: TurnFunctionCall;
+}>;
+/**
+ * Every pause waiting inside a delegated call still open in `events` (one
+ * session's events), latest call first: each open call whose child session
+ * holds an open approval request or question, at any depth. `author`, when
+ * given, keeps one agent's calls. A call the person has written past is no
+ * longer open, and neither is anything waiting below it.
+ */
+export declare function delegatedPauses(key: DelegationKey, events: readonly TurnEvent[], author?: string, depth?: number, seen?: ReadonlySet<string>): Promise<DelegatedPause[]>;
+/** The interrupt a delegated pause waits on: the approval request's id, or the question's. */
+export declare function interruptIdOf(pause: DelegatedPause): string | undefined;
+/** The open delegated calls the latest user message resumes, and the ones still waiting after it. */
+export interface ResumedDelegations {
+    /** The open calls whose pause the message answers, as the agent made them. */
+    calls: TurnFunctionCall[];
+    /** By call id: the message's parts that answer what waits below it, to be the child's next message. */
+    answers: Map<string, TurnPart[]>;
+    /** The open calls whose pause the message does not answer, by id. */
+    waiting: string[];
+    /** The agent's tools by name, as the loop runs calls against them. */
+    tools: Map<string, unknown>;
+}
+/**
+ * The delegated calls `agent` left open that the latest user message
+ * answers (ADR 0110): the message's approval decisions and question
+ * answers (function responses to `adk_request_confirmation` or `ask_user`)
+ * matched, by interrupt id, to the pause below each open call. Undefined
+ * when the message answers none. The child binds the answer itself: an
+ * approval is checked against its pinned call there (approvedCalls), as at
+ * the top.
+ */
+export declare function resumedDelegations(agent: NativeAgent, scope: Scope, sessions: Pick<SessionService, 'get'>): Promise<ResumedDelegations | undefined>;
 export {};