melchizedek-agents 1.1.0 → 1.3.0

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

@@ -104,6 +104,38 @@
  * 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).
  *
+ * NESTED WORKFLOWS AS A ROUTE OR A NODE (ADR 0119). A workflow node that is
+ * a nested workflow raises its walk's open requests again on its caller's
+ * walk, on one event of its own (lib/workflow/turn.ts), so the caller's
+ * walk pauses on the same ids; deepestPause follows such a request down,
+ * by id, through each child session filed under entryAppName (its kind in
+ * the key: `route:`, `node:`, ADR 0120; else an older key, legacyEntry) to
+ * the node that asked. A dispatch route that is one leaves its pause
+ * record as the conversation's last event (routePause). A delegated nested
+ * workflow's node that is one is followed the same way.
+ *
+ * NESTED DISPATCH SYNDICATES (ADR 0120). One runs as a turn of its own on
+ * its own conversation (the child session of a delegated call, a route or
+ * a node), its routes answering there as a turn's routes answer in the
+ * turn's conversation. conversationPause finds what it waits on as the
+ * turn finds it at the top: a route's pause record, a route's open
+ * request, question or consent request, else a pause inside a call a route
+ * left open (filed `<conversation>/<route>/<subagent>`). pauseBelow falls
+ * to it when the subagent's own checks find nothing; nestedWorkflowPause
+ * when the child session is not a walk. The answer goes down the open
+ * call, the route's pause record or the node's raised request, and the
+ * nested turn reads it as a message at the top.
+ *
+ * CONSENT AND SKILL SCRIPTS INSIDE DELEGATED SUBAGENTS (ADR 0118). A skill
+ * script run asks for approval through the same `adk_request_confirmation`
+ * call a gated tool stores, so the walk and the resume above carry it with
+ * nothing of its own. An OAuth consent request (`adk_request_credential`)
+ * the subagent left open in its child session is a pause too: the walk
+ * reports it with the path (pendingConsent), the turn runner stores the
+ * grant's answer once the callback has stored the grant, and the open
+ * call carries that answer down as it carries an approval decision; the
+ * child's own grantedCalls binds it and runs its paused call again.
+ *
  * ADK stays out of this file: an ADK tool an agent still lists is asked
  * whether it gates through its own checkRequireConfirmation, by shape.
  */
@@ -111,10 +143,11 @@ import { isDeepStrictEqual } from 'node:util';
 import { nativeToolOf } from '../../models/schemaNormalize.js';
 import { instructionToolOf, isTool, toolOf } from '../../tools/tool.js';
 import { inputRequestFrom } from '../../workflowConfig.js';
-import { pendingApproval } from '../approvals.js';
+import { approvalRequestOf, pendingApproval } from '../approvals.js';
+import { pendingConsent } from '../credentials.js';
 import { getFunctionCalls, getFunctionResponses } from '../events.js';
 import { ASK_USER, pendingQuestion } from '../questions.js';
-import { childAppName, legacyChild } from './delegate.js';
+import { childAppName, entryAppName, legacyChild, legacyEntry } from './delegate.js';
 import { REQUEST_CONFIRMATION_CALL, REQUEST_CREDENTIAL_CALL, REQUEST_INPUT_CALL, isSegmentPrefix } from './history.js';
 import { isToolset } from './request.js';
 /** A confirmation that does not bind to its pinned call: ADK's IntentMismatchError, by name and text. */
@@ -386,9 +419,9 @@ async function pauseBelow(key, caller, call, depth, seen) {
     if (!child)
         return undefined;
     const here = [caller, name];
-    const walked = workflowPause(child.events, name);
+    const walked = await workflowPauseIn(key, child, name);
     if (walked) {
-        const path = [...here, walked.asker];
+        const path = [caller, ...walked.path];
         return {
             path,
             callIds: [id],
@@ -402,50 +435,206 @@ async function pauseBelow(key, caller, call, depth, seen) {
     const question = pendingQuestion(child.events);
     if (question && question.node === name)
         return { path: here, callIds: [id], question: { ...question, path: here } };
+    // Only the subagent's own request counts (pendingConsent already skips a user-authored one).
+    const consent = pendingConsent(child.events);
+    if (consent && consent.agent === name)
+        return { path: here, callIds: [id], consent: { ...consent, path: here } };
     const [first] = await delegatedPauses({ ...key, appName: child.appName, delegated: true }, child.events, name, depth + 1, new Set([...seen, name]));
+    if (first) {
+        const path = [caller, ...first.path];
+        return {
+            path,
+            callIds: [id, ...first.callIds],
+            ...(first.approval ? { approval: { ...first.approval, path } } : {}),
+            ...(first.question ? { question: { ...first.question, path } } : {}),
+            ...(first.consent ? { consent: { ...first.consent, path } } : {}),
+        };
+    }
+    // A nested dispatch syndicate delegated to (ADR 0120): its routes answer in the child session, as routes answer in a turn's.
+    const routed = await conversationPause(key, child, name, undefined, depth + 1, new Set([...seen, name]));
+    if (!routed)
+        return undefined;
+    const path = [caller, ...routed.path];
+    return {
+        path,
+        callIds: [id],
+        ...(routed.approval ? { approval: { ...routed.approval, path } } : {}),
+        ...(routed.question ? { question: { ...routed.question, path } } : {}),
+        ...(routed.consent ? { consent: { ...routed.consent, path } } : {}),
+    };
+}
+/** The id a pause found below waits on. */
+const idOf = (pause) => pause.approval?.id ?? pause.question?.id ?? pause.consent?.id;
+/**
+ * What a nested dispatch syndicate's conversation (`child`, filed for the
+ * entry `name`) waits on (ADR 0120): what its own turn would report at the
+ * top. Its routes answer there as a turn's routes answer in the turn's
+ * conversation, so it is found as the turn finds it: a route's pause record
+ * (a nested workflow or a nested dispatch syndicate run as a route, followed
+ * down), a route's open approval request, question or consent request, else
+ * a pause inside a call a route left open, its child filed under the
+ * route's name (`<child>/<route>/<subagent>`, as a turn's route files its
+ * own). The path runs from `name` down to the agent that asked. With `id`,
+ * only that request counts. Calls `name` made itself are not a route's.
+ */
+async function conversationPause(key, child, name, id, depth, seen = new Set()) {
+    if (depth >= MAX_DELEGATION_DEPTH)
+        return undefined;
+    const at = { ...key, appName: child.appName, delegated: false };
+    const wanted = (found) => !!found && (id === undefined || found === id);
+    const down = (path) => [name, ...path];
+    const routed = await routePause(at, child.events, undefined, depth + 1);
+    if (routed && wanted(idOf(routed))) {
+        const path = down(routed.path);
+        return {
+            path,
+            ...(routed.approval ? { approval: { ...routed.approval, path } } : {}),
+            ...(routed.question ? { question: { ...routed.question, path } } : {}),
+            ...(routed.consent ? { consent: { ...routed.consent, path } } : {}),
+        };
+    }
+    const approval = pendingApproval(child.events);
+    if (approval && approval.agent && approval.agent !== 'user' && approval.agent !== name && wanted(approval.id)) {
+        const path = down([approval.agent]);
+        return { path, approval: { ...approval, path } };
+    }
+    const question = pendingQuestion(child.events);
+    if (question && question.node && question.node !== 'user' && question.node !== name && wanted(question.id)) {
+        const path = down([question.node]);
+        return { path, question: { ...question, path } };
+    }
+    const consent = pendingConsent(child.events);
+    if (consent && consent.agent && consent.agent !== name && wanted(consent.id)) {
+        const path = down([consent.agent]);
+        return { path, consent: { ...consent, path } };
+    }
+    const below = await delegatedPauses(at, child.events, undefined, depth + 1, seen);
+    const first = below.find((p) => p.path[0] !== name && wanted(interruptIdOf(p)));
     if (!first)
         return undefined;
-    const path = [caller, ...first.path];
+    const path = down(first.path);
     return {
         path,
-        callIds: [id, ...first.callIds],
         ...(first.approval ? { approval: { ...first.approval, path } } : {}),
         ...(first.question ? { question: { ...first.question, path } } : {}),
+        ...(first.consent ? { consent: { ...first.consent, path } } : {}),
     };
 }
+/** A walk's session: its node events carry a dotted node path (`<workflow>.<node>`). */
+const isWalk = (session) => session.events.some((e) => typeof e.nodeInfo?.path === 'string' && e.nodeInfo.path.includes('.'));
 /**
  * The pause a nested workflow's walk holds in its child session (ADR 0111):
  * the workflow's own pause record, the last event, authored by the
  * workflow (`name`) at its own path with no content, names the open
  * interrupts; the approval request or ask_user question among them is the
- * pause, and the node that raised it the asker. Undefined when the session
- * holds no paused walk of `name`'s.
+ * pause, and the node that raised it the asker. With `id`, only that
+ * interrupt counts. Undefined when the session holds no paused walk of
+ * `name`'s. A node that is itself a nested workflow raised its walk's
+ * requests again on its own event (lib/workflow/turn.ts, ADR 0119), so it
+ * is the asker here, and workflowPauseIn goes on down.
  */
-function workflowPause(events, name) {
+function workflowPause(events, name, id) {
     const record = events[events.length - 1];
     if (!record || record.author !== name || (record.content?.parts ?? []).length > 0 || record.nodeInfo?.path !== name)
         return undefined;
-    const open = new Set(record.longRunningToolIds ?? []);
+    const open = new Set((record.longRunningToolIds ?? []).filter((x) => id === undefined || x === id));
     if (open.size === 0)
         return undefined;
-    const approval = pendingApproval(events);
-    if (approval && open.has(approval.id) && approval.agent && approval.agent !== 'user')
-        return { asker: approval.agent, approval };
-    // The ask_user node's request the record names: the walk stores node inputs as user turns, so a later one may follow it.
-    for (let i = events.length - 2; i >= 0; i--) {
-        const event = events[i];
-        if (!event.author || event.author === 'user')
-            continue;
-        for (const call of getFunctionCalls(event)) {
-            if (call.name !== REQUEST_INPUT_CALL || !call.id || !open.has(call.id))
+    // The latest open request the record names, an approval first: the walk stores node inputs as user turns, so a later one may follow it.
+    for (const kind of [REQUEST_CONFIRMATION_CALL, REQUEST_INPUT_CALL]) {
+        for (let i = events.length - 2; i >= 0; i--) {
+            const event = events[i];
+            if (!event.author || event.author === 'user')
                 continue;
-            const question = inputRequestFrom(event.author, call);
-            if (question && question.id === call.id)
-                return { asker: event.author, question };
+            for (const call of getFunctionCalls(event)) {
+                if (call.name !== kind || !call.id || !open.has(call.id))
+                    continue;
+                if (kind === REQUEST_CONFIRMATION_CALL)
+                    return { asker: event.author, approval: approvalRequestOf(event, call) };
+                const question = inputRequestFrom(event.author, call);
+                if (question && question.id === call.id)
+                    return { asker: event.author, question };
+            }
         }
     }
     return undefined;
 }
+/**
+ * The pause the walk of `name` holds in `child` (its child session), with
+ * `id` the only interrupt that counts when given: the node that asked, or,
+ * when that node is itself a nested workflow (ADR 0119), the pause its own
+ * child session holds under the same id, one level further down.
+ */
+async function workflowPauseIn(key, child, name, id, depth = 0) {
+    const walked = workflowPause(child.events, name, id);
+    if (!walked)
+        return undefined;
+    const found = (walked.approval?.id ?? walked.question?.id);
+    const deeper = await nestedWorkflowPause({ ...key, appName: child.appName }, walked.asker, 'node', found, depth + 1);
+    const path = deeper ? [name, ...deeper.path] : [name, walked.asker];
+    const approval = deeper ? deeper.approval : walked.approval;
+    const question = deeper ? deeper.question : walked.question;
+    return { path, ...(approval ? { approval: { ...approval, path } } : {}), ...(question ? { question: { ...question, path } } : {}) };
+}
+/**
+ * The pause a nested workflow run as a dispatch route or a workflow node
+ * holds (ADR 0119): `name`'s child session below the session filed under
+ * `key.appName` (delegate.ts entryAppName), else the one filed under its
+ * name alone (legacyChild), and the paused walk there, followed down to the
+ * node that asked. With `id`, only that interrupt counts: a request a node
+ * raised again on its caller's walk names the one its own walk waits on.
+ */
+export async function nestedWorkflowPause(key, name, kind, id, depth = 0) {
+    if (depth >= MAX_DELEGATION_DEPTH)
+        return undefined;
+    const own = await key.sessions.get({ appName: entryAppName(key.appName, name, kind), userId: key.userId, sessionId: key.sessionId });
+    const child = own ?? (await legacyEntry(key.sessions, key, name, true));
+    if (!child)
+        return undefined;
+    const walked = await workflowPauseIn(key, child, name, id, depth);
+    if (walked || isWalk(child))
+        return walked;
+    // A nested dispatch syndicate run as the route or the node (ADR 0120): its own conversation, as its turn reads it.
+    return conversationPause(key, child, name, id, depth + 1);
+}
+/**
+ * A dispatch route that is a nested workflow, paused (ADR 0119): the
+ * conversation's last event is the route's pause record (authored by the
+ * route at its own path, no content, the walk's open interrupts in
+ * `longRunningToolIds`; lib/runtime/syndicateTurn.ts stores it), and the
+ * route's child session holds the paused walk under one of those ids.
+ * Anything stored after the record closes it. `routes`, when given, are the
+ * names a record may carry.
+ */
+export async function routePause(key, events, routes, depth = 0) {
+    const record = events[events.length - 1];
+    const route = record?.author;
+    if (!record || !route || route === 'user' || (record.content?.parts ?? []).length > 0 || record.nodeInfo?.path !== route)
+        return undefined;
+    if (routes && !routes.has(route))
+        return undefined;
+    for (const id of record.longRunningToolIds ?? []) {
+        const pause = await nestedWorkflowPause(key, route, 'route', id, depth);
+        if (pause)
+            return { ...pause, route };
+    }
+    return undefined;
+}
+/**
+ * An approval request or question found in a workflow's own session, raised
+ * by a node that is a nested workflow (lib/workflow/turn.ts raises its
+ * walk's requests again on the node's event, ADR 0119): the one its walk
+ * waits on, with the path from the node down to the one that asked. Any
+ * other request comes back as it is.
+ */
+export async function deepestPause(key, pending) {
+    const raisedBy = 'agent' in pending ? pending.agent : pending.node;
+    if (!raisedBy || pending.path)
+        return pending;
+    const below = await nestedWorkflowPause(key, raisedBy, 'node', pending.id);
+    const found = 'agent' in pending ? below?.approval : below?.question;
+    return found ?? pending;
+}
 /**
  * Every pause waiting inside a delegated call still open in `events` (one
  * session's events), latest call first: each open call whose child session
@@ -462,18 +651,19 @@ export async function delegatedPauses(key, events, author, depth = 0, seen = new
     }
     return out;
 }
-/** The interrupt a delegated pause waits on: the approval request's id, or the question's. */
+/** The interrupt a delegated pause waits on: the approval request's id, the question's, or the consent request's. */
 export function interruptIdOf(pause) {
-    return pause.approval?.id ?? pause.question?.id;
+    return pause.approval?.id ?? pause.question?.id ?? pause.consent?.id;
 }
 /**
  * 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.
+ * and grants (to `adk_request_credential`, ADR 0118) 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), a grant against its request
+ * (grantedCalls), as at the top.
  */
 export async function resumedDelegations(agent, scope, sessions) {
     const events = scope.session.events;
@@ -485,7 +675,7 @@ export async function resumedDelegations(agent, scope, sessions) {
         return undefined;
     const answerParts = (latest.content?.parts ?? []).filter((p) => {
         const r = p.functionResponse;
-        return !!r?.id && (r.name === REQUEST_CONFIRMATION_CALL || r.name === ASK_USER);
+        return !!r?.id && (r.name === REQUEST_CONFIRMATION_CALL || r.name === ASK_USER || r.name === REQUEST_CREDENTIAL_CALL);
     });
     if (answerParts.length === 0)
         return undefined;

package/dist/lib/runtime/syndicateTurn.d.ts

@@ -158,7 +158,8 @@ export interface SyndicateTurnOptions {
      * the native runtime. The store is pinned to `appName`; a tool reads the
      * grant of `userId` only. With `consent`, a call whose provider the user
      * has not granted pauses the turn input-required (`result.consent`), and
-     * the next message after the grant resumes it. Omitted: tools have no
+     * the next message after the grant resumes it; inside a delegated
+     * subagent too, with `consent.path` set (ADR 0118). Omitted: tools have no
      * `accessToken`, as before.
      */
     toolCredentials?: ToolCredentials;
@@ -229,7 +230,8 @@ export interface SyndicateTurnResult {
     input?: PendingInput;
     /** The OAuth grant a paused call waits for, when status is input-required
      *  (ADR 0085): the person opens `consent.authUri`; their next message after
-     *  the grant is stored resumes the call. */
+     *  the grant is stored resumes the call. `consent.path` is set for a call
+     *  inside a delegated subagent (ADR 0118). */
     consent?: PendingConsent;
     /** The text the user receives (relay fallback and guards applied). */
     text: string;