melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/a2a/oauthSetup.js

@@ -0,0 +1,259 @@
+/**
+ * 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)
+ *     MELCHIZEDEK_CREDENTIAL_HOSTS  which hosts each static credential variable may go to (ADR 0122)
+ *     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';
+import { CREDENTIAL_HOSTS_ENV, credentialHosts } from '../tools/credentialHosts.js';
+import { syndicateCredentialHostProblems, syndicateCredentialUses, unboundCredentialEnvs } from '../tools/credentialUses.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 warning for credential variables no allowlist binds (ADR 0122), or
+ * null: with no credential host allowlist, each variable in `envs` (the
+ * ones the served YAML sends) still goes to whatever host the YAML names.
+ * Names only.
+ */
+export function unboundCredentialWarning(envs, env = process.env) {
+    let allowlist;
+    try {
+        allowlist = credentialHosts(env);
+    }
+    catch {
+        return null; // A malformed allowlist is a problem, reported as one.
+    }
+    if (allowlist)
+        return null; // Configured: an unbound variable is refused, not warned about.
+    const unbound = [...new Set(envs)].sort();
+    if (!unbound.length)
+        return null;
+    return `${unbound.join(', ')} ${unbound.length === 1 ? 'is' : 'are'} sent to whatever host the YAML names: no ${CREDENTIAL_HOSTS_ENV} binds ${unbound.length === 1 ? 'it' : 'them'} to ${unbound.length === 1 ? 'its' : 'their'} hosts`;
+}
+/**
+ * What is wrong with the credential host allowlist for these uses, one line
+ * each, names and hosts only: a malformed allowlist, or each use it refuses
+ * (lib/tools/credentialUses.ts). Empty when none is configured.
+ */
+export function credentialHostEnvProblems(configs, env = process.env, load) {
+    let allowlist;
+    try {
+        allowlist = credentialHosts(env);
+    }
+    catch (err) {
+        return [err instanceof Error ? err.message : `${CREDENTIAL_HOSTS_ENV} is malformed`];
+    }
+    return syndicateCredentialHostProblems(configs, { allowlist: allowlist ?? null, ...(load ? { load } : {}) });
+}
+/**
+ * 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  - ')}`);
+    // The credential host allowlist (ADR 0122): malformed throws here, at boot; a served file it refuses too.
+    const credentialList = credentialHosts(env);
+    const credentialRefused = syndicateCredentialHostProblems(options.configs, { ...(options.load ? { load: options.load } : {}), allowlist: credentialList ?? null });
+    if (credentialRefused.length)
+        throw new Error(`refusing a credential the operator's credential host allowlist does not permit:\n  - ${credentialRefused.join('\n  - ')}`);
+    const uses = syndicateCredentialUses(options.configs, options.load);
+    const unboundWarning = unboundCredentialWarning(uses.map((u) => u.env), env);
+    if (unboundWarning)
+        warnings.push(`${unboundWarning.charAt(0).toUpperCase()}${unboundWarning.slice(1)}.`);
+    const credentialSummary = credentialList
+        ? `bound: ${Object.keys(credentialList).join(', ')} (${CREDENTIAL_HOSTS_ENV})`
+        : uses.length
+            ? `no allowlist (${CREDENTIAL_HOSTS_ENV}): ${unboundCredentialEnvs(uses, undefined).join(', ')} unbound`
+            : `no allowlist (${CREDENTIAL_HOSTS_ENV}); no served file sends a static credential`;
+    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}`, credentialSummary, 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}`, credentialSummary, 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}`, credentialSummary, 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}`,
+        credentialSummary,
+        warnings,
+    };
+}

package/dist/lib/agentDialect.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 `tool_choice` from ADR 0117) 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`, `output` and `tool_choice` 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[];
+    readonly v1: readonly string[];
+    /** The engine value for the v2 value, when the two are spelled differently. */
+    readonly toV1?: (value: unknown) => unknown;
+}
+/**
+ * `tool_choice` as Gemini's function-calling config, which the engine reads
+ * (lib/models/genaiMapping.ts toolChoiceOf): `auto` is AUTO, `none` NONE,
+ * `required` ANY, and `{ name }` ANY with that one name allowed (ADR 0117).
+ */
+export declare function functionCallingConfigOf(choice: unknown): Record<string, unknown>;
+/** 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', 'tool_choice', '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`, `output` and `tool_choice` 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 none of the three, 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,151 @@
+/**
+ * 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 `tool_choice` from ADR 0117) 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`, `output` and `tool_choice` 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);
+/**
+ * `tool_choice` as Gemini's function-calling config, which the engine reads
+ * (lib/models/genaiMapping.ts toolChoiceOf): `auto` is AUTO, `none` NONE,
+ * `required` ANY, and `{ name }` ANY with that one name allowed (ADR 0117).
+ */
+export function functionCallingConfigOf(choice) {
+    if (choice === 'none')
+        return { mode: 'NONE' };
+    if (choice === 'required')
+        return { mode: 'ANY' };
+    if (isObj(choice) && typeof choice.name === 'string')
+        return { mode: 'ANY', allowedFunctionNames: [choice.name] };
+    return { mode: 'AUTO' };
+}
+/** 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'] },
+    { v2: ['tool_choice'], v1: ['generateContentConfig', 'toolConfig', 'functionCallingConfig'], toV1: functionCallingConfigOf },
+];
+/** 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', 'tool_choice', '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`, `output` and `tool_choice` 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 none of the three, 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 && a.tool_choice === 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, tool_choice: _toolChoice, ...rest } = a;
+    const out = { ...rest };
+    for (const s of V2_SPELLINGS) {
+        const raw = at(a, s.v2);
+        if (raw === undefined)
+            continue;
+        const value = s.toV1 ? s.toV1(raw) : raw;
+        // Copy each object on the v1 path, so the caller's config is never written to.
+        let parent = out;
+        for (const seg of s.v1.slice(0, -1)) {
+            const next = { ...(isObj(parent[seg]) ? parent[seg] : {}) };
+            parent[seg] = next;
+            parent = next;
+        }
+        parent[s.v1[s.v1.length - 1]] = value;
+    }
+    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

@@ -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;
 }
@@ -177,6 +205,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,20 +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 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'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): 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). */
+/** 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
@@ -205,8 +238,11 @@ 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).
+ * 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): 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