melchizedek-agents 1.0.2 → 1.1.0

package/dist/lib/a2a/oauthSetup.js

@@ -0,0 +1,205 @@
+/**
+ * lib/a2a/oauthSetup.ts — tool credentials and the OAuth consent step from
+ * the environment, for the server binary (WS6-3d, ADR 0114).
+ *
+ * WHY this file exists:
+ *   `createA2AApp({ toolCredentials })` takes a credential store and a
+ *   consent step, and the YAML declares the grants (ADR 0112), but the
+ *   `melchizedek-serve` binary built neither: a declared authorization-code
+ *   grant worked only for an embedder who wrote the wiring. This module is
+ *   that wiring, from four variables, so the binary and an embedder build it
+ *   the same way:
+ *
+ *     MELCHIZEDEK_CREDENTIAL_KEY  the key that seals each user's tokens (ADR 0072)
+ *     OAUTH_REDIRECT_URI          the consent callback, as registered at every provider (ADR 0085)
+ *     MELCHIZEDEK_OAUTH_HOSTS     which hosts each provider's tokens may go to (ADR 0114)
+ *     the client id and secret variables each YAML grant names
+ *
+ *   The consent clients are built from the syndicates the server serves from
+ *   files (`oauthClientsFor`), never from a registry row, so a stored YAML
+ *   can name a provider the files declare but cannot define one.
+ *
+ * WHAT IT NEVER DOES: print, return or log a value. Problems name variables,
+ * providers and hosts only (secrets-hygiene).
+ */
+import { CREDENTIAL_KEY_ENV, credentialCipherFromEnv } from '../tools/credentialCipher.js';
+import { credentialStore, memoryCredentialRows } from '../tools/credentialStore.js';
+import { oauthConsent } from '../tools/oauthConsent.js';
+import { OAUTH_HOSTS_ENV, oauthHosts } from '../tools/oauthHosts.js';
+import { oauthClientsFor, oauthGrantHostProblems, oauthRefreshProviders, syndicateOAuthGrants, syndicateOAuthHostProblems } from '../tools/oauthTools.js';
+/** The consent callback's URL, exactly as registered at every provider. */
+export const OAUTH_REDIRECT_URI_ENV = 'OAUTH_REDIRECT_URI';
+/** Who may complete a consent callback: `required` (the browser carries the user's identity) or `state` (the nonce alone). */
+export const OAUTH_CALLBACK_IDENTITY_ENV = 'OAUTH_CALLBACK_IDENTITY';
+/** OAUTH_CALLBACK_IDENTITY, checked: `required` (the default) or `state`. Throws on anything else. */
+export function callbackIdentity(env = process.env) {
+    const raw = (env[OAUTH_CALLBACK_IDENTITY_ENV] ?? '').trim().toLowerCase() || 'required';
+    if (raw !== 'required' && raw !== 'state')
+        throw new Error(`${OAUTH_CALLBACK_IDENTITY_ENV} must be 'required' or 'state' (got '${raw.slice(0, 40)}')`);
+    return raw;
+}
+/**
+ * Why consent callbacks would all be refused under this environment, or
+ * null: a required caller identity that the configured authenticator cannot
+ * give a browser (only a gateway's header can: A2A_AUTH=header).
+ */
+export function callbackIdentityProblem(env = process.env) {
+    const authKind = (env.A2A_AUTH ?? 'secret').trim().toLowerCase() || 'secret';
+    if (callbackIdentity(env) !== 'required' || authKind === 'header')
+        return null;
+    return `the consent callback requires the browser to carry the user's identity, which A2A_AUTH=${authKind} cannot give a browser, so every callback is refused: serve behind a gateway (A2A_AUTH=header), or set ${OAUTH_CALLBACK_IDENTITY_ENV}=state to let the single-use state alone bind it`;
+}
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/** Why `raw` cannot be the consent redirect URI, or null (the rule oauthConsent enforces). */
+export function redirectUriProblem(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return `${OAUTH_REDIRECT_URI_ENV} is not a URL`;
+    }
+    if (!(url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname))))
+        return `${OAUTH_REDIRECT_URI_ENV} must use https (http only on a loopback host)`;
+    if (url.username || url.password)
+        return `${OAUTH_REDIRECT_URI_ENV} must not carry credentials`;
+    if (url.search || url.hash)
+        return `${OAUTH_REDIRECT_URI_ENV} must not carry a query or a fragment`;
+    return null;
+}
+/** The MCP server a grant's tools call, when the grant is an MCP one. */
+const serversOf = (use) => (use.tools.startsWith('mcp ') && use.tools.length > 4 ? [use.tools.slice(4)] : []);
+/**
+ * Why this grant's hosts are refused by the allowlist in `env`, one line
+ * each (the MCP server, the token and authorization endpoints; an OpenAPI
+ * entry's servers are checked when it compiles). Names and hosts only.
+ */
+export function grantHostProblems(use, env = process.env) {
+    let allowlist;
+    try {
+        allowlist = oauthHosts(env) ?? null;
+    }
+    catch {
+        return [`${OAUTH_HOSTS_ENV} is malformed`];
+    }
+    return oauthGrantHostProblems(use.oauth2, serversOf(use), allowlist);
+}
+/**
+ * What is wrong with this environment for these declared grants, one line
+ * each, names only: the credential key, the redirect URI and the allowlist
+ * (each grant's own hosts: grantHostProblems). The doctor prints these; the
+ * server refuses to start on the ones that would make it unsafe.
+ */
+export function oauthEnvProblems(grants, env = process.env) {
+    const problems = [];
+    const authCode = [...new Set(grants.filter((g) => g.oauth2.grant === 'authorization_code').map((g) => g.oauth2.provider))];
+    const keySet = !!env[CREDENTIAL_KEY_ENV]?.trim();
+    const redirect = env[OAUTH_REDIRECT_URI_ENV]?.trim();
+    if (keySet) {
+        try {
+            credentialCipherFromEnv(env);
+        }
+        catch (err) {
+            // parseCredentialKey's message names the variable and the shape, never the value.
+            problems.push(err instanceof Error ? err.message : `${CREDENTIAL_KEY_ENV} is malformed`);
+        }
+    }
+    if (redirect) {
+        const problem = redirectUriProblem(redirect);
+        if (problem)
+            problems.push(problem);
+        if (!keySet)
+            problems.push(`${OAUTH_REDIRECT_URI_ENV} is set but ${CREDENTIAL_KEY_ENV} is not: the consent step has nowhere to keep a grant`);
+        try {
+            const identity = callbackIdentityProblem(env);
+            if (identity && authCode.length)
+                problems.push(identity);
+        }
+        catch (err) {
+            problems.push(err instanceof Error ? err.message : `${OAUTH_CALLBACK_IDENTITY_ENV} is malformed`);
+        }
+    }
+    if (authCode.length) {
+        const who = authCode.join(', ');
+        if (!keySet)
+            problems.push(`authorization_code grants (${who}) need ${CREDENTIAL_KEY_ENV}: without it no user's token can be held, and their tools answer unavailable`);
+        if (!redirect)
+            problems.push(`authorization_code grants (${who}) need ${OAUTH_REDIRECT_URI_ENV}: without it a user who has not connected cannot be asked to`);
+    }
+    let allowlist;
+    try {
+        allowlist = oauthHosts(env);
+    }
+    catch (err) {
+        problems.push(err instanceof Error ? err.message : `${OAUTH_HOSTS_ENV} is malformed`);
+    }
+    if (authCode.length && allowlist === undefined && !problems.some((p) => p.startsWith(OAUTH_HOSTS_ENV))) {
+        problems.push(`authorization_code grants (${authCode.join(', ')}) need ${OAUTH_HOSTS_ENV}: without it the operator has bound no provider to its hosts, so they are refused`);
+    }
+    return problems;
+}
+/**
+ * The credential store and consent step from the environment. Throws, naming
+ * variables only, when the configuration would be unsafe or cannot work: a
+ * malformed key, a redirect URI without a key, a malformed redirect URI or
+ * allowlist, an authorization-code grant the allowlist does not permit, a
+ * grant whose client variables are unset.
+ */
+export function oauthServerSetup(options) {
+    const env = options.env ?? process.env;
+    const warnings = [];
+    const grants = syndicateOAuthGrants(options.configs, options.load);
+    const authCode = [...new Set(grants.filter((g) => g.oauth2.grant === 'authorization_code').map((g) => g.oauth2.provider))];
+    const redirect = env[OAUTH_REDIRECT_URI_ENV]?.trim() || undefined;
+    const cipher = credentialCipherFromEnv(env); // a malformed key throws here, at boot
+    const allowlist = oauthHosts(env); // a malformed allowlist throws here, at boot
+    const hostsLabel = allowlist ? `host allowlist for ${Object.keys(allowlist).join(', ')}` : `no host allowlist (${OAUTH_HOSTS_ENV}): authorization_code grants refused`;
+    if (redirect) {
+        const problem = redirectUriProblem(redirect);
+        if (problem)
+            throw new Error(problem);
+    }
+    // A served syndicate whose grant the allowlist refuses is refused here, at boot, as its route would refuse it.
+    const refused = syndicateOAuthHostProblems(options.configs, { ...(options.load ? { load: options.load } : {}), allowlist: allowlist ?? null });
+    if (refused.length)
+        throw new Error(`refusing an OAuth grant the operator's host allowlist does not permit:\n  - ${refused.join('\n  - ')}`);
+    if (!cipher) {
+        if (redirect)
+            throw new Error(`${OAUTH_REDIRECT_URI_ENV} is set but ${CREDENTIAL_KEY_ENV} is not: the consent step has nowhere to keep a grant. Set ${CREDENTIAL_KEY_ENV} (openssl rand -base64 32).`);
+        if (authCode.length)
+            warnings.push(`authorization_code grants (${authCode.join(', ')}) are declared but ${CREDENTIAL_KEY_ENV} is not set: their tools answer unavailable.`);
+        return { summary: `off (${CREDENTIAL_KEY_ENV} unset) · ${hostsLabel}`, warnings };
+    }
+    const clients = oauthClientsFor(options.configs, { env, ...(options.load ? { load: options.load } : {}), allowlist: allowlist ?? null });
+    const providers = Object.keys(clients);
+    const store = credentialStore({
+        rows: options.rows ?? memoryCredentialRows(),
+        cipher,
+        providers: oauthRefreshProviders(clients, { ...(options.allowPrivate ? { allowPrivate: true } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) }),
+        ...(options.audit ? { audit: options.audit } : {}),
+    });
+    if (!options.rows)
+        warnings.push(`Tool credentials are held in process memory: lost on restart, one instance only. Set DATABASE_URL to keep them sealed in Postgres.`);
+    const where = options.rows ? 'postgres' : 'process memory';
+    if (!redirect) {
+        if (providers.length)
+            warnings.push(`${OAUTH_REDIRECT_URI_ENV} is not set: a user who has not connected ${providers.join(', ')} cannot be asked to.`);
+        return { toolCredentials: { store }, summary: `sealed (key ${cipher.keyId}) in ${where}; no consent step · ${hostsLabel}`, warnings };
+    }
+    if (!providers.length) {
+        warnings.push(`${OAUTH_REDIRECT_URI_ENV} is set but no served syndicate declares an authorization_code grant: no consent callback is mounted.`);
+        return { toolCredentials: { store }, summary: `sealed (key ${cipher.keyId}) in ${where}; no consent step · ${hostsLabel}`, warnings };
+    }
+    const consent = oauthConsent({
+        providers: clients,
+        redirectUri: redirect,
+        credentials: store,
+        ...(options.audit ? { audit: options.audit } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    return {
+        toolCredentials: { store, consent },
+        summary: `sealed (key ${cipher.keyId}) in ${where}; consent at ${new URL(redirect).pathname} for ${providers.join(', ')} · ${hostsLabel}`,
+        warnings,
+    };
+}

package/dist/lib/agentDialect.d.ts

@@ -0,0 +1,66 @@
+/**
+ * lib/agentDialect.ts — the YAML v2 agent keys and the engine form they map to
+ * (ADR 0115).
+ *
+ * WHY this file exists:
+ *   An agent's sampling and structured-output settings were spelled in
+ *   Gemini's dialect (`generateContentConfig.temperature`, `outputSchema`),
+ *   which is what the engine still reads (lib/runtime/native/request.ts
+ *   buildModelRequest). YAML v2 spells them provider-neutrally (`sampling`,
+ *   `output`) and adds per-provider instruction overrides (`model_overrides`).
+ *   This module is the one place the two spellings meet:
+ *
+ *   - `V2_SPELLINGS`: each v2 key path and the v1 path it replaces. The
+ *     loader (lib/syndicateSchema.ts crossFieldProblems) refuses a file that
+ *     sets both; `toEngineAgent` refuses a config built in code that does.
+ *   - `toEngineAgent`: folds `sampling` and `output` into the engine form.
+ *     validateSyndicateConfig applies it to every agent it returns, so every
+ *     loader hands downstream the engine form; lib/compile.ts applies it
+ *     again (idempotent) for configs built in code.
+ *   - `v1SpellingsOf`: the deprecated v1 key paths a raw file still uses, for
+ *     the loader's one-line deprecation warning (paths only, never values).
+ *   - `instructionFor`: an agent's instruction with its `model_overrides`
+ *     entry for the provider of the model it runs on applied.
+ *
+ * Internal: not in the lib/index.ts barrel nor the package exports map.
+ */
+import type { AgentYamlConfig } from './loadSyndicate.ts';
+/** One v2 key and the v1 (engine) path it replaces. Both paths are relative to the agent. */
+export interface V2Spelling {
+    readonly v2: readonly [string, string];
+    readonly v1: readonly string[];
+}
+/** Every v2 key with a v1 equivalent; the mapper writes the v1 path. */
+export declare const V2_SPELLINGS: readonly V2Spelling[];
+/** The v2 agent keys, which an inline agent alone may carry (not a yaml_reference or a2a_agent_url subagent). */
+export declare const V2_AGENT_KEYS: readonly ['sampling', 'output', 'model_overrides'];
+/** The v1 spellings ADR 0115 deprecates, as agent keys. */
+export declare const V1_AGENT_KEYS: readonly ['generateContentConfig', 'outputSchema'];
+/** The v2/v1 pairs an agent sets both of: each is a conflict. */
+export declare function conflictsOf(agent: unknown): V2Spelling[];
+/** The loader's message for one conflict, reported against the v2 key path. */
+export declare function conflictMessage(s: V2Spelling): string;
+/**
+ * An agent in the engine form: `sampling` and `output` folded into
+ * `generateContentConfig` and `outputSchema` (the table above) and removed;
+ * `model_overrides` kept (lib/compile.ts applies it). The same object when
+ * the agent has neither `sampling` nor `output`, so it is idempotent. Throws
+ * when a v2 key and the v1 key it replaces are both set.
+ */
+export declare function toEngineAgent<T extends object>(agent: T): T;
+/**
+ * The deprecated v1 key paths a raw syndicate uses, in file order:
+ * `orchestrator.generateContentConfig`, `subagents[2].outputSchema`, ...
+ * Paths only: the loader logs them, never the values under them.
+ */
+export declare function v1SpellingsOf(raw: unknown): string[];
+/**
+ * An agent's base instruction for the model it runs on: its
+ * `model_overrides` entry for that model's provider replaces it
+ * (`instruction`) or is appended after a blank line (`instruction_append`).
+ * The base instruction when there is no entry or no model id. The skills
+ * index (lib/compile.ts withSkills) is appended after this.
+ */
+export declare function instructionFor(agent: Pick<AgentYamlConfig, 'model_overrides'> & {
+    instruction?: string;
+}, modelId: string | undefined): string;

package/dist/lib/agentDialect.js

@@ -0,0 +1,134 @@
+/**
+ * lib/agentDialect.ts — the YAML v2 agent keys and the engine form they map to
+ * (ADR 0115).
+ *
+ * WHY this file exists:
+ *   An agent's sampling and structured-output settings were spelled in
+ *   Gemini's dialect (`generateContentConfig.temperature`, `outputSchema`),
+ *   which is what the engine still reads (lib/runtime/native/request.ts
+ *   buildModelRequest). YAML v2 spells them provider-neutrally (`sampling`,
+ *   `output`) and adds per-provider instruction overrides (`model_overrides`).
+ *   This module is the one place the two spellings meet:
+ *
+ *   - `V2_SPELLINGS`: each v2 key path and the v1 path it replaces. The
+ *     loader (lib/syndicateSchema.ts crossFieldProblems) refuses a file that
+ *     sets both; `toEngineAgent` refuses a config built in code that does.
+ *   - `toEngineAgent`: folds `sampling` and `output` into the engine form.
+ *     validateSyndicateConfig applies it to every agent it returns, so every
+ *     loader hands downstream the engine form; lib/compile.ts applies it
+ *     again (idempotent) for configs built in code.
+ *   - `v1SpellingsOf`: the deprecated v1 key paths a raw file still uses, for
+ *     the loader's one-line deprecation warning (paths only, never values).
+ *   - `instructionFor`: an agent's instruction with its `model_overrides`
+ *     entry for the provider of the model it runs on applied.
+ *
+ * Internal: not in the lib/index.ts barrel nor the package exports map.
+ */
+import { providerForModel } from './models/providerMap.js';
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** Every v2 key with a v1 equivalent; the mapper writes the v1 path. */
+export const V2_SPELLINGS = [
+    { v2: ['sampling', 'temperature'], v1: ['generateContentConfig', 'temperature'] },
+    { v2: ['sampling', 'top_p'], v1: ['generateContentConfig', 'topP'] },
+    { v2: ['sampling', 'max_output_tokens'], v1: ['generateContentConfig', 'maxOutputTokens'] },
+    { v2: ['sampling', 'stop'], v1: ['generateContentConfig', 'stopSequences'] },
+    { v2: ['output', 'schema'], v1: ['outputSchema'] },
+    { v2: ['output', 'mime'], v1: ['generateContentConfig', 'responseMimeType'] },
+];
+/** The v2 agent keys, which an inline agent alone may carry (not a yaml_reference or a2a_agent_url subagent). */
+export const V2_AGENT_KEYS = ['sampling', 'output', 'model_overrides'];
+/** The v1 spellings ADR 0115 deprecates, as agent keys. */
+export const V1_AGENT_KEYS = ['generateContentConfig', 'outputSchema'];
+/** The value at `path` under `root`, or undefined. */
+function at(root, path) {
+    let cur = root;
+    for (const seg of path) {
+        if (!isObj(cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+/** The v2/v1 pairs an agent sets both of: each is a conflict. */
+export function conflictsOf(agent) {
+    return V2_SPELLINGS.filter((s) => at(agent, s.v2) !== undefined && at(agent, s.v1) !== undefined);
+}
+/** The loader's message for one conflict, reported against the v2 key path. */
+export function conflictMessage(s) {
+    return `cannot be combined with ${s.v1.join('.')}; ${s.v2.join('.')} replaces it, so keep one (ADR 0115)`;
+}
+/**
+ * An agent in the engine form: `sampling` and `output` folded into
+ * `generateContentConfig` and `outputSchema` (the table above) and removed;
+ * `model_overrides` kept (lib/compile.ts applies it). The same object when
+ * the agent has neither `sampling` nor `output`, so it is idempotent. Throws
+ * when a v2 key and the v1 key it replaces are both set.
+ */
+export function toEngineAgent(agent) {
+    const a = agent;
+    if (a.sampling === undefined && a.output === undefined)
+        return agent;
+    const clash = conflictsOf(a);
+    if (clash.length) {
+        const name = typeof a.name === 'string' ? a.name : 'agent';
+        throw new Error(`${name}: ${clash.map((s) => `${s.v2.join('.')} cannot be combined with ${s.v1.join('.')}`).join('; ')}; the v2 key replaces it, so keep one (ADR 0115)`);
+    }
+    const { sampling: _sampling, output: _output, ...rest } = a;
+    const out = { ...rest };
+    let gcc;
+    for (const s of V2_SPELLINGS) {
+        const value = at(a, s.v2);
+        if (value === undefined)
+            continue;
+        if (s.v1.length === 1) {
+            out[s.v1[0]] = value;
+            continue;
+        }
+        gcc ??= { ...(isObj(a.generateContentConfig) ? a.generateContentConfig : {}) };
+        gcc[s.v1[1]] = value;
+    }
+    if (gcc)
+        out.generateContentConfig = gcc;
+    return out;
+}
+/**
+ * The deprecated v1 key paths a raw syndicate uses, in file order:
+ * `orchestrator.generateContentConfig`, `subagents[2].outputSchema`, ...
+ * Paths only: the loader logs them, never the values under them.
+ */
+export function v1SpellingsOf(raw) {
+    if (!isObj(raw))
+        return [];
+    const agents = [['orchestrator', raw.orchestrator]];
+    if (Array.isArray(raw.subagents))
+        raw.subagents.forEach((sub, i) => agents.push([`subagents[${i}]`, sub]));
+    const out = [];
+    for (const [path, agent] of agents) {
+        if (!isObj(agent))
+            continue;
+        for (const key of V1_AGENT_KEYS)
+            if (agent[key] !== undefined)
+                out.push(`${path}.${key}`);
+    }
+    return out;
+}
+/**
+ * An agent's base instruction for the model it runs on: its
+ * `model_overrides` entry for that model's provider replaces it
+ * (`instruction`) or is appended after a blank line (`instruction_append`).
+ * The base instruction when there is no entry or no model id. The skills
+ * index (lib/compile.ts withSkills) is appended after this.
+ */
+export function instructionFor(agent, modelId) {
+    const base = agent.instruction ?? '';
+    if (!agent.model_overrides || modelId === undefined)
+        return base;
+    const entry = agent.model_overrides[providerForModel(modelId)];
+    if (!entry)
+        return base;
+    if (entry.instruction !== undefined)
+        return entry.instruction;
+    if (entry.instruction_append !== undefined)
+        return base ? `${base}\n\n${entry.instruction_append}` : entry.instruction_append;
+    return base;
+}

package/dist/lib/compile.d.ts

@@ -177,6 +177,8 @@ export interface AgentSpec {
     context?: ContextConfig;
     /** `mode: task`. */
     mode?: 'task';
+    /** The syndicate's `max_concurrency`, on its orchestrator (ADR 0116): delegated calls one step runs at once. */
+    maxConcurrency?: number;
 }
 /**
  * The spec of a workflow syndicate: every agent through compileSubagentSpec
@@ -184,11 +186,12 @@ 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 runs inside its caller's tool call, so a pause inside it
- * could not reach the caller (ADR 0028, as for any nested syndicate): an
- * `ask_user` node is refused by name here.
+ * 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.
  */
-export declare function compileWorkflowSpec(config: SyndicateYamlConfig, opts?: CompileOptions, name?: string, description?: string, ref?: string): Promise<WorkflowSpec>;
+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). */
@@ -205,8 +208,10 @@ 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).
  */
-export declare function compileEntrySpec(subCfg: SubagentYamlConfig, opts?: CompileOptions): Promise<EntrySpec>;
+export declare function compileEntrySpec(subCfg: SubagentYamlConfig, opts?: CompileOptions, delegated?: boolean): Promise<EntrySpec>;
 /**
  * The names of a syndicate's subagent entries that are `yaml_reference`s to
  * a workflow syndicate. Loads each reference once and compiles nothing, so a

package/dist/lib/compile.js

@@ -40,6 +40,7 @@ import { isWorkflowSyndicate, nodeKind } from './workflowConfig.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
+import { instructionFor, toEngineAgent } from './agentDialect.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
 import { createMcpTools } from './tools/mcpToolFactory.js';
 import { requireApproval, toolOf } from './tools/tool.js';
@@ -144,7 +145,7 @@ export function examplesTool(examples) {
     const tool = examplesInstructionTool(examples);
     return tool ? [tool] : [];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
+async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed, mcpAuth) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
     for (const entry of openapi ?? []) {
@@ -158,7 +159,8 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
     }
     if (mcpServerUrl) {
         opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        const offered = await createMcpTools(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.
@@ -201,9 +203,11 @@ async function withSkills(instruction, tools, skills, agentName, opts) {
 export function agentGates(agent) {
     return !!agent?.require_approval?.length || agent?.skills?.scripts === 'local';
 }
-function specOf(yaml, name, description, instruction, tools, opts) {
-    const resolvedModel = (opts.resolveModel ?? ((m) => m))(yaml.model);
-    const modelId = modelIdOf(yaml.model, resolvedModel);
+function resolveAgentModel(model, opts) {
+    const resolvedModel = (opts.resolveModel ?? ((m) => m))(model);
+    return { resolvedModel, modelId: modelIdOf(model, resolvedModel) };
+}
+function specOf(yaml, name, description, instruction, tools, { resolvedModel, modelId }) {
     const spec = {
         name,
         instruction,
@@ -240,12 +244,6 @@ function specOf(yaml, name, description, instruction, tools, opts) {
     return spec;
 }
 const asTools = (tools) => tools.map((tool) => ({ kind: 'tool', tool }));
-/**
- * A nested `yaml_reference:` syndicate, loaded. A nested syndicate runs
- * inside a tool call (or as a route whose own subagents do): a pause there
- * cannot reach the caller (ADR 0028), so one that declares approval gates is
- * refused.
- */
 /** Where the yaml_reference chain a compile is inside is kept: an own symbol on the options, so a spread copy keeps it. */
 const NESTING = Symbol('melchizedek.compile.nesting');
 /** The deepest a yaml_reference chain may go: well past any syndicate the engine ships, short of the stack. */
@@ -265,11 +263,30 @@ function nestedOptions(ref, opts) {
         throw new Error(`${ref}: nested syndicates go deeper than ${MAX_NESTING_DEPTH} levels (${[...chain, ref].join(' → ')}).`);
     return { ...opts, [NESTING]: [...chain, ref] };
 }
-function loadNestedSyndicate(ref, opts) {
+/**
+ * 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.
+ */
+function loadNestedSyndicate(ref, opts, delegated = false) {
     opts.log?.(`Loading nested syndicate: ${ref}`);
     const nested = (opts.loadNested ?? loadSyndicate)(ref);
-    if (declaresApprovals(nested)) {
-        throw new Error(`${ref}: approval gates (require_approval) are not supported inside a nested syndicate.`);
+    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.`);
+        }
+    }
+    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.`);
     }
     return nested;
 }
@@ -279,17 +296,18 @@ function loadNestedSyndicate(ref, opts) {
  * 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 runs inside its caller's tool call, so a pause inside it
- * could not reach the caller (ADR 0028, as for any nested syndicate): an
- * `ask_user` node is refused by name here.
+ * 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.
  */
-export async function compileWorkflowSpec(config, opts = {}, name, description, ref) {
+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) {
+    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 nested in another syndicate (${name}) cannot carry to its caller; run the workflow as its own syndicate, or remove the node.`);
+            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;
@@ -328,13 +346,15 @@ 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).
  */
-export async function compileEntrySpec(subCfg, opts = {}) {
+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);
+        const nested = loadNestedSyndicate(subCfg.yaml_reference, nestedOpts, delegated);
         if (isWorkflowSyndicate(nested)) {
-            return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference) };
+            return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference, delegated) };
         }
         return { kind: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
     }
@@ -371,10 +391,14 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         }
         return compileSpec(nested, nestedOpts, subCfg.name, subCfg.description);
     }
-    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples, subCfg.mcp_tools), subCfg.require_approval, subCfg.name);
-    const { instruction, tools } = await withSkills(subCfg.instruction ?? '', gated, subCfg.skills, subCfg.name, opts);
-    logCapabilities(opts, subCfg.name, subCfg.model, subCfg.tools);
-    return specOf(subCfg, subCfg.name, subCfg.description, instruction, asTools(tools), opts);
+    // 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 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);
+    logCapabilities(opts, agent.name, agent.model, agent.tools);
+    return specOf(agent, agent.name, agent.description, instruction, asTools(tools), model);
 }
 /**
  * The spec of a syndicate's orchestrator. In DELEGATE mode its subagents
@@ -401,16 +425,24 @@ export async function compileSpec(config, opts = {}, overrideName, overrideDescr
                 opts.log?.(`Remote A2A agent: ${subCfg.name} → ${subCfg.a2a_agent_url}`);
                 return { kind: 'remote', name: subCfg.name, description: subCfg.description, url: subCfg.a2a_agent_url };
             }
-            const entry = await compileEntrySpec(subCfg, opts);
+            // 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 };
         }));
-    const name = overrideName || config.orchestrator.name;
-    // Orchestrator tools are registry names only — no entrypoint has ever
-    // attached an MCP server to an orchestrator, and this compiler preserves
-    // that exactly rather than widening the contract in passing.
-    const own = gateTools(await resolveAgentTools(config.orchestrator.tools, undefined, opts, config.orchestrator.openapi, config.orchestrator.examples), config.orchestrator.require_approval, name);
-    // The skills toolset goes last, after the delegations and the agent's own tools.
-    const { instruction, tools } = await withSkills(config.orchestrator.instruction, own, config.orchestrator.skills, name, opts);
-    logCapabilities(opts, name, config.orchestrator.model, config.orchestrator.tools);
-    return specOf(config.orchestrator, name, overrideDescription || config.orchestrator.description, instruction, [...delegated, ...asTools(tools)], opts);
+    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);
+    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.
+    const { instruction, tools } = await withSkills(instructionFor(orchestrator, model.modelId), own, orchestrator.skills, name, opts);
+    logCapabilities(opts, name, orchestrator.model, orchestrator.tools);
+    const spec = specOf(orchestrator, name, overrideDescription || orchestrator.description, instruction, [...delegated, ...asTools(tools)], model);
+    // The syndicate's own key: a nested syndicate's orchestrator runs its delegations under its own file's (ADR 0116).
+    if (config.max_concurrency !== undefined)
+        spec.maxConcurrency = config.max_concurrency;
+    return spec;
 }

package/dist/lib/compileNative.js

@@ -145,6 +145,8 @@ export function compileNative(spec) {
         agent.fallbackModel = spec.fallbackModel;
     if (spec.context)
         agent.context = spec.context;
+    if (spec.maxConcurrency !== undefined)
+        agent.maxConcurrency = spec.maxConcurrency;
     return agent;
 }
 /**