melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/chatgpt/state.js

@@ -0,0 +1,145 @@
+/**
+ * lib/chatgpt/state.ts — where a Sign in with ChatGPT credential lives, whether
+ * it is the OpenAI path, and the served-surface refusal (ADR 0126).
+ *
+ * WHY a leaf (node:fs, node:os, node:path only):
+ *   The gateway's transport rule (lib/models/gateway.ts), the doctor, the
+ *   resolver and every served bin ask the same two questions — is a sign-in
+ *   stored, and does it carry OpenAI ids here — so the answer lives in one
+ *   module with no adapter or SDK in its import graph.
+ *
+ * LOCAL ONLY:
+ *   OpenAI's plan-usage flow is for open-source apps that run on the user's
+ *   own machine (developers.openai.com/siwc/token-sharing-open-source). The
+ *   A2A server, the worker and any other served surface call
+ *   `refuseChatGptSignInOnServedSurface` at startup and stop while the
+ *   sign-in would carry OpenAI ids; `markServedSurface` also makes the
+ *   adapter refuse at call time, so a surface that skipped the startup check
+ *   still never spends a person's ChatGPT plan on someone else's request.
+ *
+ * WHAT IT NEVER DOES: return or print a token. The status carries presence,
+ * times and the file's path.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** Where the credential file lives, when not the default (a path; never a value). */
+export const CHATGPT_SIGNIN_FILE_ENV = 'MELCHIZEDEK_CHATGPT_SIGNIN_FILE';
+/** `off` ignores a stored sign-in (a served process on a machine that also signed in). */
+export const CHATGPT_SIGNIN_ENV = 'MELCHIZEDEK_CHATGPT_SIGNIN';
+/** The scope that lets the token use the person's ChatGPT plan. */
+export const PLAN_SCOPE = 'chatgpt.tokens.use.direct';
+/** The credential file: MELCHIZEDEK_CHATGPT_SIGNIN_FILE, else ~/.melchizedek/chatgpt-signin.json. */
+export function signInFile(env = process.env) {
+    const set = env[CHATGPT_SIGNIN_FILE_ENV]?.trim();
+    return set ? resolve(set) : join(homedir(), '.melchizedek', 'chatgpt-signin.json');
+}
+/** The git work tree a path sits inside, if any (an ancestor holding `.git`). */
+export function insideGitWorkTree(file) {
+    let dir = dirname(resolve(file));
+    for (;;) {
+        if (existsSync(join(dir, '.git')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Whether a parsed value has the stored shape. */
+export function isStoredSignIn(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const o = v;
+    return o.version === 1 && typeof o.issuer === 'string' && typeof o.hostId === 'string';
+}
+/**
+ * Read the credential file: undefined when absent; throws, naming the file
+ * and never its content, when it is readable by others or malformed.
+ */
+export function readStoredSignIn(file) {
+    if (!existsSync(file))
+        return undefined;
+    if (process.platform !== 'win32' && (statSync(file).mode & 0o077) !== 0) {
+        throw new Error(`${file} is readable by other users; run \`chmod 600 ${file}\` (or sign in again).`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        throw new Error(`${file} is not a Sign in with ChatGPT credential file; delete it and sign in again.`);
+    }
+    if (!isStoredSignIn(parsed))
+        throw new Error(`${file} is not a Sign in with ChatGPT credential file; delete it and sign in again.`);
+    return parsed;
+}
+/** Signed in: a refresh token, and the plan scope granted. */
+export function isSignedIn(s) {
+    return !!s?.refreshToken && !!s.accessToken && (s.scopes ?? []).includes(PLAN_SCOPE);
+}
+/** The stored sign-in's status under this environment. */
+export function chatGptSignInStatus(env = process.env) {
+    const file = signInFile(env);
+    const enabled = env[CHATGPT_SIGNIN_ENV]?.trim().toLowerCase() !== 'off';
+    const present = existsSync(file);
+    if (!present)
+        return { enabled, file, present, signedIn: false };
+    try {
+        const s = readStoredSignIn(file);
+        const signedIn = isSignedIn(s);
+        return { enabled, file, present, signedIn, ...(signedIn && s?.expiresAt ? { expiresAt: s.expiresAt } : {}) };
+    }
+    catch (err) {
+        return { enabled, file, present, signedIn: false, problem: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Whether OpenAI ids would run on the sign-in here: it is enabled and signed
+ * in, no OPENAI_API_KEY is set, and OpenAI is on its own API (no
+ * OPENAI_PLATFORM other than direct, no OPENAI_BASE_URL proxy, which must
+ * never receive the token).
+ */
+export function chatGptSignInRoutesOpenAi(env = process.env) {
+    if (env.OPENAI_API_KEY?.trim())
+        return false;
+    const platform = env.OPENAI_PLATFORM?.trim().toLowerCase();
+    if (platform && platform !== 'direct')
+        return false;
+    if (env.OPENAI_BASE_URL?.trim())
+        return false;
+    const status = chatGptSignInStatus(env);
+    return status.enabled && status.signedIn;
+}
+// ── Local only ───────────────────────────────────────────────────────────────
+let served;
+/** Mark this process a served surface: the sign-in adapter refuses every call from here on. */
+export function markServedSurface(surface) {
+    served ??= surface;
+}
+/** The served surface this process was marked as, if any. */
+export function servedSurface() {
+    return served;
+}
+/** Test seam: forget the mark. */
+export function resetServedSurfaceForTests() {
+    served = undefined;
+}
+/** The message a served surface stops with. */
+export function servedSurfaceMessage(surface, env = process.env) {
+    return (`${surface} will not start: Sign in with ChatGPT is local only, and it is the OpenAI path here ` +
+        `(a sign-in is stored at ${signInFile(env)} and OPENAI_API_KEY is not set). ` +
+        `A served surface answers other people, and a ChatGPT plan pays only for its owner's own use on their own machine. ` +
+        `Set OPENAI_API_KEY (or Azure OpenAI), or set ${CHATGPT_SIGNIN_ENV}=off for this process, ` +
+        `or sign out with \`melchizedek-setup --chatgpt-signout\`.`);
+}
+/**
+ * Called by every served surface at startup: marks the process served, and
+ * throws when the sign-in would carry OpenAI ids here. The A2A app, the A2A
+ * server bin and the worker call it; a new served surface calls it too.
+ */
+export function refuseChatGptSignInOnServedSurface(surface, env = process.env) {
+    markServedSurface(surface);
+    if (chatGptSignInRoutesOpenAi(env))
+        throw new Error(servedSurfaceMessage(surface, env));
+}

package/dist/lib/chatgpt/store.d.ts

@@ -0,0 +1,24 @@
+/**
+ * lib/chatgpt/store.ts — writing the Sign in with ChatGPT credential file and
+ * serializing its refreshes (ADR 0126).
+ *
+ * The file is the person's own: mode 600 in a mode-700 directory, outside any
+ * git work tree, replaced atomically (a new mode-600 file renamed over the
+ * old one). OpenAI's refresh tokens rotate, so two processes must not refresh
+ * the same session at once (developers.openai.com/siwc/token-sharing-open-source/
+ * profiles-and-sessions): a lock file beside the credential serializes them.
+ */
+import type { StoredSignIn } from './state.ts';
+/** Write the credential file: mode 600, atomically, never inside a git work tree. */
+export declare function writeStoredSignIn(file: string, value: StoredSignIn): void;
+/** The stored sign-in with its tokens removed; the host id and the issued client id stay (OpenAI asks apps to reuse them). */
+export declare function withoutTokens(s: StoredSignIn): StoredSignIn;
+/** Remove the tokens from the file, keeping the registration. */
+export declare function clearTokens(file: string): void;
+/**
+ * Run `fn` holding the credential's lock file (created exclusively). A lock
+ * older than a minute is a crashed holder's and is taken over.
+ */
+export declare function withSignInLock<T>(file: string, fn: () => Promise<T>, opts?: {
+    waitMs?: number;
+}): Promise<T>;

package/dist/lib/chatgpt/store.js

@@ -0,0 +1,94 @@
+/**
+ * lib/chatgpt/store.ts — writing the Sign in with ChatGPT credential file and
+ * serializing its refreshes (ADR 0126).
+ *
+ * The file is the person's own: mode 600 in a mode-700 directory, outside any
+ * git work tree, replaced atomically (a new mode-600 file renamed over the
+ * old one). OpenAI's refresh tokens rotate, so two processes must not refresh
+ * the same session at once (developers.openai.com/siwc/token-sharing-open-source/
+ * profiles-and-sessions): a lock file beside the credential serializes them.
+ */
+import { randomUUID } from 'node:crypto';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { insideGitWorkTree, readStoredSignIn } from './state.js';
+/** Write the credential file: mode 600, atomically, never inside a git work tree. */
+export function writeStoredSignIn(file, value) {
+    const repo = insideGitWorkTree(file);
+    if (repo) {
+        throw new Error(`refusing to store a ChatGPT sign-in inside the git work tree ${repo}; set MELCHIZEDEK_CHATGPT_SIGNIN_FILE to a path outside it.`);
+    }
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    const fd = openSync(tmp, 'wx', 0o600);
+    try {
+        writeSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        if (process.platform !== 'win32')
+            chmodSync(tmp, 0o600);
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+/** The stored sign-in with its tokens removed; the host id and the issued client id stay (OpenAI asks apps to reuse them). */
+export function withoutTokens(s) {
+    const { accessToken: _a, refreshToken: _r, expiresAt: _e, earliestRefreshAt: _n, scopes: _s, ...kept } = s;
+    return { ...kept, savedAt: new Date().toISOString() };
+}
+/** Remove the tokens from the file, keeping the registration. */
+export function clearTokens(file) {
+    const s = readStoredSignIn(file);
+    if (s)
+        writeStoredSignIn(file, withoutTokens(s));
+}
+const LOCK_STALE_MS = 60_000;
+const LOCK_WAIT_MS = 20_000;
+/**
+ * Run `fn` holding the credential's lock file (created exclusively). A lock
+ * older than a minute is a crashed holder's and is taken over.
+ */
+export async function withSignInLock(file, fn, opts = {}) {
+    const lock = `${file}.lock`;
+    const dir = dirname(file);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + (opts.waitMs ?? LOCK_WAIT_MS);
+    for (;;) {
+        try {
+            closeSync(openSync(lock, 'wx', 0o600));
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            try {
+                if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+                    rmSync(lock, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`another process holds ${lock}; try again, or delete it if no melchizedek process is running.`);
+            await delay(100);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        rmSync(lock, { force: true });
+    }
+}

package/dist/lib/compile.d.ts

@@ -110,7 +110,30 @@ export type SpecTool = {
 } | {
     kind: 'workflow';
     workflow: WorkflowSpec;
+} | {
+    kind: 'dispatch';
+    dispatch: DispatchSpec;
 };
+/**
+ * A nested dispatch (plan-dispatch) syndicate (ADR 0120): it runs as it
+ * runs at the top, as a turn of its own on its own conversation (its
+ * classifier picks a route, the route answers), so what it compiles to is
+ * the file and the options its turn loads its routes with. The turn runner
+ * runs it (lib/runtime/syndicateTurn.ts, TurnControl.nestedDispatch), as a
+ * delegated call, a dispatch route or a workflow node.
+ */
+export interface DispatchSpec {
+    /** The entry's name, under which its caller lists it. */
+    name: string;
+    /** The entry's description: the tool's, when delegated to. */
+    description: string;
+    /** The nested syndicate, as loaded. */
+    config: SyndicateYamlConfig;
+    /** The file it came from. */
+    ref: string;
+    /** The options its routes compile with: the caller's, its nesting chain extended by `ref`. */
+    compile: CompileOptions;
+}
 /**
  * A workflow syndicate, compiled: lib/compileNative.ts builds the walk's
  * graph and agents from it. Nested as a subagent (a `yaml_reference` in
@@ -138,6 +161,11 @@ export interface WorkflowSpec {
         yaml: SubagentYamlConfig;
         workflow: WorkflowSpec;
     }>;
+    /** Every node that is a `yaml_reference` to a dispatch syndicate, with its YAML entry: the walk runs it as the node, as its own turn (ADR 0120). */
+    dispatches?: Array<{
+        yaml: SubagentYamlConfig;
+        dispatch: DispatchSpec;
+    }>;
     /** The registry entry for a tool node's tool name, or undefined (CompileOptions.onUnknownTool applies). */
     resolveTool: (name: string) => unknown;
 }
@@ -186,21 +214,23 @@ export interface AgentSpec {
  * lookup for its tool nodes. `name` and `description` name a nested one
  * after its subagent entry (ADR 0098); `ref` is the file it came from.
  *
- * A nested workflow delegated to as a subagent (`delegated`) pauses through
- * its caller's open call (ADR 0111). Run as a dispatch route or a workflow
- * node, its pause cannot reach the turn yet: an `ask_user` node is refused
- * by name there.
+ * A nested workflow's pauses (an `ask_user` node, a gate) reach the turn
+ * wherever it runs (ADR 0111, ADR 0119). `delegated` is accepted for the
+ * callers that pass it and no longer changes what compiles.
  */
 export declare function compileWorkflowSpec(config: SyndicateYamlConfig, opts?: CompileOptions, name?: string, description?: string, ref?: string, delegated?: boolean): Promise<WorkflowSpec>;
 /** Every agent spec a workflow runs, its nested workflow nodes' agents included, for one adapter lookup (nativeAdapterFor). */
 export declare function workflowAgentSpecs(spec: WorkflowSpec): AgentSpec[];
-/** A subagent entry, compiled: one agent, or a nested workflow syndicate's whole graph (ADR 0098, ADR 0106). */
+/** A subagent entry, compiled: one agent, a nested workflow syndicate's whole graph (ADR 0098, ADR 0106), or a nested dispatch syndicate's own turn (ADR 0120). */
 export type EntrySpec = {
     kind: 'agent';
     spec: AgentSpec;
 } | {
     kind: 'workflow';
     workflow: WorkflowSpec;
+} | {
+    kind: 'dispatch';
+    dispatch: DispatchSpec;
 };
 /**
  * A subagent entry as what it runs: an inline agent or a nested syndicate's
@@ -208,8 +238,9 @@ export type EntrySpec = {
  * as its whole graph under the entry's name and description. A delegated
  * subagent, a dispatch route and a workflow node all compile through here,
  * so the graph a file describes is the graph that runs (ADR 0106).
- * `delegated` marks a delegated subagent's entry, whose nested workflow may
- * pause (ADR 0111).
+ * A nested workflow pauses wherever it runs (ADR 0111, ADR 0119);
+ * `delegated` is accepted for the callers that pass it and no longer
+ * changes what compiles.
  */
 export declare function compileEntrySpec(subCfg: SubagentYamlConfig, opts?: CompileOptions, delegated?: boolean): Promise<EntrySpec>;
 /**

package/dist/lib/compile.js

@@ -145,10 +145,10 @@ export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
     return tool ? [tool] : [];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed, mcpAuth) {
-    const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
+async function resolveAgentTools(agent, opts) {
+    const tools = [...resolveNamedTools(agent.tools, opts.onUnknownTool), ...examplesTool(agent.examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
-    for (const entry of openapi ?? []) {
+    for (const entry of agent.openapi ?? []) {
         const built = await buildOpenApiTools(entry);
         opts.log?.(`openapi · ${relative(process.cwd(), entry.spec) || entry.spec}: ${built.map((t) => t.name).join(', ') || '(no operations)'}`);
         for (const t of built) {
@@ -157,28 +157,43 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
             tools.push(t);
         }
     }
-    if (mcpServerUrl) {
-        opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        // An authorization_code server lists nothing at startup: its tools are the mcp_tools names, each on its user's own connection (ADR 0112).
-        const offered = await createMcpTools(mcpServerUrl, { ...(mcpAllowed ? { tools: mcpAllowed } : {}), ...(mcpAuth?.oauth2 ? { oauth2: mcpAuth.oauth2 } : {}) });
-        // mcp_tools: only the named tools are exposed (a server's list is its
-        // own to change); a name the server does not offer is reported, and a
-        // gate on it fails the compile in gateTools.
-        const allowed = mcpAllowed ? new Set(mcpAllowed) : undefined;
-        const mcpTools = allowed ? offered.filter((t) => allowed.has(t.name)) : offered;
-        if (allowed) {
-            const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
-            if (missing.length)
-                opts.log?.(`MCP ${mcpServerUrl} does not offer ${missing.map((n) => `'${n}'`).join(', ')} (mcp_tools)`);
-            const hidden = offered.length - mcpTools.length;
-            if (hidden)
-                opts.log?.(`MCP ${mcpServerUrl}: ${hidden} tool(s) not in mcp_tools are not exposed`);
-        }
-        for (const mcpTool of mcpTools) {
+    /** One server's tools, narrowed to the names the YAML allows (a server's list is its own to change). */
+    const offeredBy = async (label, url, allowedNames, oauth2, transport) => {
+        opts.log?.(`Loading MCP tools: ${label}`);
+        // An authorization_code server lists nothing at startup: its tools are the allowed names, each on its user's own connection (ADR 0112).
+        const offered = await createMcpTools(url, { ...(allowedNames ? { tools: allowedNames } : {}), ...(oauth2 ? { oauth2 } : {}), ...(transport ? { transport } : {}) });
+        if (!allowedNames)
+            return offered;
+        // A name the server does not offer is reported, and a gate on it fails the compile in gateTools.
+        const allowed = new Set(allowedNames);
+        const kept = offered.filter((t) => allowed.has(t.name));
+        const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
+        if (missing.length)
+            opts.log?.(`MCP ${label} does not offer ${missing.map((n) => `'${n}'`).join(', ')}`);
+        const hidden = offered.length - kept.length;
+        if (hidden)
+            opts.log?.(`MCP ${label}: ${hidden} tool(s) not named for this agent are not exposed`);
+        return kept;
+    };
+    if (agent.mcp_server_url) {
+        // The single-server form: a name the agent already has keeps the agent's tool.
+        for (const mcpTool of await offeredBy(agent.mcp_server_url, agent.mcp_server_url, agent.mcp_tools, agent.mcp_auth?.oauth2, agent.mcp_transport)) {
             if (!tools.some((t) => t.name === mcpTool.name))
                 tools.push(mcpTool);
         }
     }
+    // mcp_servers (ADR 0124): the loader refused a declared name twice; a
+    // server that answers with a name already taken is refused here too, so
+    // no server's tool can stand in for another's or the agent's own.
+    const servers = await Promise.all((agent.mcp_servers ?? []).map((server) => offeredBy(`${server.name} (${server.url})`, server.url, server.tools, server.auth?.oauth2, server.transport)));
+    for (const [i, offered] of servers.entries()) {
+        const server = agent.mcp_servers[i];
+        for (const mcpTool of offered) {
+            if (tools.some((t) => t?.name === mcpTool.name))
+                throw new Error(`mcp_servers ${server.name}: tool '${mcpTool.name}' collides with another of this agent's tools (ADR 0124)`);
+            tools.push(mcpTool);
+        }
+    }
     return tools;
 }
 /**
@@ -264,31 +279,44 @@ function nestedOptions(ref, opts) {
     return { ...opts, [NESTING]: [...chain, ref] };
 }
 /**
- * A nested `yaml_reference:` syndicate, loaded, with the approval gates that
- * cannot pause where it runs refused by name (ADR 0110, ADR 0111):
- *   - a nested delegate syndicate's gates pause the turn through the open
- *     call, wherever it runs;
- *   - a nested dispatch syndicate runs its classifier alone (compileSpec
- *     lists no route on it), so its orchestrator may gate, and a gate on a
- *     route, which never runs nested, is refused;
- *   - a nested workflow's gates pause the walk, which reaches the caller
- *     only through a delegated call's open call (`delegated`): as a
- *     dispatch route or a workflow node, its pause cannot reach the turn
- *     yet, so they are refused there.
+ * A nested `yaml_reference:` syndicate, loaded. Every pause inside one
+ * reaches the turn wherever it runs (ADR 0110, ADR 0111, ADR 0119,
+ * ADR 0120): a nested delegate syndicate's through the open call, a nested
+ * workflow's through its walk, a nested dispatch syndicate's through its
+ * own turn, whose routes run as they run at the top. Nothing is refused
+ * here any more.
  */
-function loadNestedSyndicate(ref, opts, delegated = false) {
+function loadNestedSyndicate(ref, opts) {
     opts.log?.(`Loading nested syndicate: ${ref}`);
-    const nested = (opts.loadNested ?? loadSyndicate)(ref);
-    if (isDispatchSyndicate(nested)) {
-        const gated = (nested.subagents ?? []).find((s) => agentGates(s));
-        if (gated) {
-            throw new Error(`${ref}: approval gates (require_approval, or skill scripts) on the route '${gated.name}' never run: a nested dispatch syndicate runs its classifier alone. Gate the classifier, or run the syndicate as its own.`);
+    return (opts.loadNested ?? loadSyndicate)(ref);
+}
+/**
+ * A nested dispatch syndicate as its entry runs it (ADR 0120). Its routes
+ * compile when its turn routes to one, as at the top, so a route that
+ * cannot compile fails that turn; the references below it are followed
+ * here (loaded, not compiled: no tool is resolved and no MCP server is
+ * reached), so a reference cycle or a depth past the limit is refused at
+ * load, by name, before any model call. A route may not carry the entry's
+ * name: the pause walk tells the nested syndicate from its routes by name.
+ */
+function compileDispatchEntry(subCfg, nested, nestedOpts) {
+    const ref = subCfg.yaml_reference;
+    for (const route of nested.subagents ?? []) {
+        if (route.name === subCfg.name) {
+            throw new Error(`${ref}: the route '${route.name}' has the name its caller gives the nested syndicate; rename the route or the entry.`);
         }
     }
-    else if (isWorkflowSyndicate(nested) && !delegated && declaresApprovals(nested)) {
-        throw new Error(`${ref}: approval gates (require_approval, or skill scripts) in a workflow run as a dispatch route or a workflow node cannot pause the turn yet; delegate to the workflow as a subagent, or run it as its own syndicate.`);
+    followReferences(nested, nestedOpts);
+    return { name: subCfg.name, description: subCfg.description ?? '', config: nested, ref, compile: nestedOpts };
+}
+/** Loads every `yaml_reference` below `config`, depth first, through nestedOptions: a cycle or a chain past the limit throws by name. */
+function followReferences(config, opts) {
+    for (const entry of config.subagents ?? []) {
+        if (!entry.yaml_reference || entry.a2a_agent_url)
+            continue;
+        const below = nestedOptions(entry.yaml_reference, opts);
+        followReferences(loadNestedSyndicate(entry.yaml_reference, below), below);
     }
-    return nested;
 }
 /**
  * The spec of a workflow syndicate: every agent through compileSubagentSpec
@@ -296,35 +324,34 @@ function loadNestedSyndicate(ref, opts, delegated = false) {
  * lookup for its tool nodes. `name` and `description` name a nested one
  * after its subagent entry (ADR 0098); `ref` is the file it came from.
  *
- * A nested workflow delegated to as a subagent (`delegated`) pauses through
- * its caller's open call (ADR 0111). Run as a dispatch route or a workflow
- * node, its pause cannot reach the turn yet: an `ask_user` node is refused
- * by name there.
+ * A nested workflow's pauses (an `ask_user` node, a gate) reach the turn
+ * wherever it runs (ADR 0111, ADR 0119). `delegated` is accepted for the
+ * callers that pass it and no longer changes what compiles.
  */
 export async function compileWorkflowSpec(config, opts = {}, name, description, ref, delegated = false) {
     if (!isWorkflowSyndicate(config))
         throw new Error(`${config.syndicate_name}: no workflow block`);
-    if (name && !delegated) {
-        const asking = Object.entries(config.workflow.nodes ?? {}).find(([, node]) => nodeKind(node) === 'ask_user');
-        if (asking) {
-            throw new Error(`${ref ?? config.syndicate_name}: the ask_user node '${asking[0]}' pauses for a person, which a workflow run as a dispatch route or a workflow node (${name}) cannot carry to the turn yet; delegate to the workflow as a subagent, run it as its own syndicate, or remove the node.`);
-        }
-    }
     const workflowName = name || config.syndicate_name;
     const agents = [];
     const workflows = [];
+    const dispatches = [];
     for (const yaml of [{ description: '', ...config.orchestrator }, ...(config.subagents ?? [])]) {
         const entry = await compileEntrySpec(yaml, opts);
         if (entry.kind === 'workflow')
             workflows.push({ yaml, workflow: entry.workflow });
+        else if (entry.kind === 'dispatch')
+            dispatches.push({ yaml, dispatch: entry.dispatch });
         else
             agents.push({ yaml, spec: entry.spec });
     }
-    // A map runs one agent per item; a nested graph is not an agent a map item can be (ADR 0106).
+    // A map runs one agent per item; a nested graph or a nested dispatch syndicate is not an agent a map item can be (ADR 0106, ADR 0120).
     for (const [node, entry] of Object.entries(config.workflow.nodes ?? {})) {
-        const mapped = nodeKind(entry) === 'map' ? workflows.find((w) => w.yaml.name === entry.map) : undefined;
+        if (nodeKind(entry) !== 'map')
+            continue;
+        const mapped = workflows.find((w) => w.yaml.name === entry.map) ?? dispatches.find((d) => d.yaml.name === entry.map);
         if (mapped) {
-            throw new Error(`${ref ?? config.syndicate_name}: the map node '${node}' runs '${mapped.yaml.name}', a workflow syndicate (${mapped.yaml.yaml_reference}); a map runs one agent per item, so make the workflow a node of its own.`);
+            const what = 'workflow' in mapped ? 'a workflow syndicate' : 'a dispatch syndicate';
+            throw new Error(`${ref ?? config.syndicate_name}: the map node '${node}' runs '${mapped.yaml.name}', ${what} (${mapped.yaml.yaml_reference}); a map runs one agent per item, so make it a node of its own.`);
         }
     }
     return {
@@ -333,6 +360,7 @@ export async function compileWorkflowSpec(config, opts = {}, name, description,
         config: { ...config, syndicate_name: workflowName },
         agents,
         workflows,
+        dispatches,
         resolveTool: (tool) => resolveNamedTools([tool], opts.onUnknownTool)[0],
     };
 }
@@ -346,16 +374,20 @@ export function workflowAgentSpecs(spec) {
  * as its whole graph under the entry's name and description. A delegated
  * subagent, a dispatch route and a workflow node all compile through here,
  * so the graph a file describes is the graph that runs (ADR 0106).
- * `delegated` marks a delegated subagent's entry, whose nested workflow may
- * pause (ADR 0111).
+ * A nested workflow pauses wherever it runs (ADR 0111, ADR 0119);
+ * `delegated` is accepted for the callers that pass it and no longer
+ * changes what compiles.
  */
 export async function compileEntrySpec(subCfg, opts = {}, delegated = false) {
     if (subCfg.yaml_reference && !subCfg.a2a_agent_url) {
         const nestedOpts = nestedOptions(subCfg.yaml_reference, opts);
-        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts, delegated);
+        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts);
         if (isWorkflowSyndicate(nested)) {
             return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference, delegated) };
         }
+        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs.
+        if (isDispatchSyndicate(nested))
+            return { kind: 'dispatch', dispatch: compileDispatchEntry(subCfg, nested, nestedOpts) };
         return { kind: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
     }
     return { kind: 'agent', spec: await compileSubagentSpec(subCfg, opts) };
@@ -389,11 +421,14 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         if (isWorkflowSyndicate(nested)) {
             throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a workflow syndicate, which runs as its whole graph, not as one agent; compile the entry with compileEntrySpec (ADR 0106).`);
         }
+        if (isDispatchSyndicate(nested)) {
+            throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a dispatch syndicate, which runs as its own turn (its classifier, then a route), not as one agent; compile the entry with compileEntrySpec (ADR 0120).`);
+        }
         return compileSpec(nested, nestedOpts, subCfg.name, subCfg.description);
     }
     // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).
     const agent = toEngineAgent(subCfg);
-    const gated = gateTools(await resolveAgentTools(agent.tools, agent.mcp_server_url, opts, agent.openapi, agent.examples, agent.mcp_tools, agent.mcp_auth), agent.require_approval, agent.name);
+    const gated = gateTools(await resolveAgentTools(agent, opts), agent.require_approval, agent.name);
     const model = resolveAgentModel(agent.model, opts);
     // model_overrides for the provider the agent runs on, before the skills index is appended.
     const { instruction, tools } = await withSkills(instructionFor(agent, model.modelId), gated, agent.skills, agent.name, opts);
@@ -427,14 +462,14 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
             }
             // A delegated subagent: a pause inside it, a nested workflow's included, reaches the caller (ADR 0110, ADR 0111).
             const entry = await compileEntrySpec(subCfg, opts, true);
-            return entry.kind === 'workflow' ? entry : { kind: 'agent', agent: entry.spec };
+            return entry.kind === 'agent' ? { kind: 'agent', agent: entry.spec } : entry;
         }));
     const orchestrator = toEngineAgent(config.orchestrator); // YAML v2 (ADR 0115), for a config built in code
     const name = overrideName || orchestrator.name;
     // The orchestrator's own tools resolve as a subagent's do: registry
-    // names, OpenAPI operations, and the MCP server's tools (narrowed by
-    // mcp_tools, under its mcp_auth grant), so a one-agent syndicate can reach an MCP server.
-    const own = gateTools(await resolveAgentTools(orchestrator.tools, orchestrator.mcp_server_url, opts, orchestrator.openapi, orchestrator.examples, orchestrator.mcp_tools, orchestrator.mcp_auth), orchestrator.require_approval, name);
+    // names, OpenAPI operations, and the MCP servers' tools (narrowed by
+    // mcp_tools or each mcp_servers entry's tools, under its grant), so a one-agent syndicate can reach an MCP server.
+    const own = gateTools(await resolveAgentTools(orchestrator, opts), orchestrator.require_approval, name);
     const model = resolveAgentModel(orchestrator.model, opts);
     // The skills toolset goes last, after the delegations and the agent's own tools; the
     // skills index goes after the instruction with its model_overrides entry applied.

package/dist/lib/compileNative.d.ts

@@ -32,13 +32,14 @@
  * caller's. ADK classes are told apart by ADK's own Symbol.for marks, so
  * this file imports nothing from ADK.
  */
-import type { AgentSpec, CompileOptions, WorkflowSpec } from './compile.ts';
+import type { AgentSpec, CompileOptions, DispatchSpec, WorkflowSpec } from './compile.ts';
 import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
 import type { ModelAdapter } from './models/contract.ts';
 import type { WorkflowSubagent } from './runtime/native/delegate.ts';
 import type { NativeAgent } from './runtime/native/request.ts';
 export { UnsupportedOnRuntimeError, unsupportedOnNative } from './runtime/runtimeFlag.ts';
 import type { WorkflowGraph } from './workflow/graph.ts';
+import type { NestedRun } from './workflow/turn.ts';
 /**
  * The class name of an ADK model the runtime cannot run, else undefined:
  * any ADK BaseLlm (ADR 0107; the ADK runtime that ran one left in 1.0.0).
@@ -67,8 +68,8 @@ export interface NativeWorkflow {
     graph: WorkflowGraph;
     agents: Map<string, NativeAgent>;
     resolveTool: (name: string) => unknown;
-    /** The nodes that are a nested workflow syndicate, each compiled the same way, by YAML name (ADR 0106). */
-    workflows: Map<string, NativeWorkflow>;
+    /** The nodes that are a nested workflow syndicate, each compiled the same way (ADR 0106), or a nested dispatch syndicate, its own turn (ADR 0120), by YAML name. */
+    workflows: Map<string, NativeWorkflow | NestedRun>;
 }
 /**
  * A workflow spec for the walk: the graph, every agent compiled from its
@@ -82,6 +83,13 @@ export declare function compileNativeWorkflow(spec: WorkflowSpec): NativeWorkflo
  * session lib/runtime/native/delegate.ts opened.
  */
 export declare function workflowSubagentOf(workflow: NativeWorkflow): WorkflowSubagent;
+/**
+ * A nested dispatch syndicate as the delegated subagent the native loop
+ * calls, or the node a walk runs (ADR 0120): one call runs it as its own
+ * turn (nestedDispatchWalk) on the child session lib/runtime/native/delegate.ts
+ * (or lib/workflow/turn.ts) opened.
+ */
+export declare function dispatchSubagentOf(dispatch: DispatchSpec): WorkflowSubagent & NestedRun;
 /** One subagent entry (a dispatch route) for the native loop: compileSubagentSpec, then compileNative. */
 export declare function compileNativeSubagent(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<NativeAgent>;
 /** What nativeAdapterFor reads from a spec: its model resolution, the other ids it calls, and its delegated subagents. */