melchizedek-agents 1.1.0 → 1.2.0

package/config/agents/syndicateSchema.yaml

@@ -365,7 +365,7 @@ orchestrator:
 
   # ── reasoning ─────────────────────────────────────────────
   # [optional] How hard the agent reasons, on any provider (ADR 0047):
-  #   none | low | medium | high, or { budget_tokens: <int> }.
+  #   none | low | medium | high | xhigh | max, or { budget_tokens: <int> }.
   # The compiler sends each provider the field it reads:
   #   gemini-3 and later    → thinkingConfig.thinkingLevel
   #                           (none = MINIMAL, then LOW, MEDIUM, HIGH)
@@ -382,6 +382,10 @@ orchestrator:
   # A budget is sent as-is to Gemini and to Claude 4.6 and earlier, and as
   # the smallest level that covers it everywhere else. Unset, each provider
   # keeps its default.
+  # xhigh and max (ADR 0117) reach the models that take them: both on later
+  # claude-*, max on kimi-k3 (xhigh rounds up to it), xhigh on gpt-5.2 and
+  # later and grok-4.7. Elsewhere the model's highest setting is sent and
+  # the span carries llm.reasoning.weakened; a gateway gets high.
   # Cannot be combined with generateContentConfig.thinkingConfig or
   # generateContentConfig.reasoningEffort, its deprecated v1 spelling.
   reasoning: medium
@@ -422,6 +426,14 @@ orchestrator:
     #     answer: { type: string }
     #   required: [answer]
 
+  # ── tool_choice ───────────────────────────────────────────
+  # [optional] Which tools the model may call, on any provider (ADR 0117):
+  #   auto (the default) | none | required (some tool)
+  #   | { name: <tool> } (that one tool).
+  # A provider that rejects forcing a tool gets a weaker choice, and the
+  # span carries llm.tool_choice.weakened.
+  # tool_choice: auto
+
   # ── model_overrides ───────────────────────────────────────
   # [optional] A prompt nuance for one provider (ADR 0115). Keys are the
   # providers a model id routes to: gemini, anthropic, openai, xai,
@@ -438,11 +450,11 @@ orchestrator:
   # The v1 spelling: @google/genai's GenerateContentConfig, with
   # outputSchema beside it. Still loads and behaves as before, with one
   # deprecation line per file; `npx melchizedek-codemod <file>` rewrites
-  # it into sampling, output and reasoning. A v2 key beside its v1
-  # spelling is a load error. Only a few fields have no v2 form yet:
-  # toolConfig (tool choice) and the effort words xhigh and max
-  # (reasoningEffort). topK, seed, the penalties, candidateCount,
-  # safetySettings and includeThoughts reach no provider.
+  # it into sampling, output, reasoning and tool_choice. A v2 key beside
+  # its v1 spelling is a load error. Only toolConfig's VALIDATED mode and
+  # Gemini's dynamic budget (thinkingBudget: -1) have no v2 form. topK,
+  # seed, the penalties, candidateCount, safetySettings and
+  # includeThoughts reach no provider.
 
 # ── Subagents ───────────────────────────────────────────────
 # Each entry is an agent the orchestrator calls as a tool (DELEGATE),

package/config/agents/templates/intake_extractor.yaml

@@ -23,8 +23,9 @@
 #
 # SHAPE: a single agent with an `outputSchema`, so the reply is JSON the
 # schema describes, parseable without a second model call. No subagents and
-# no tools: the document is the only input, and the extractor may not add
-# anything the document does not say.
+# no tools, by choice rather than by rule (an agent that delegates or calls
+# tools may hold a schema too, ADR 0109): the document is the only input,
+# and the extractor may not add anything the document does not say.
 #
 # REDACTION: card numbers, bank details, passwords and government IDs are
 # never copied into the record, not even as a `references` entry; `redacted`

package/config/agents/templates/systems_operator.yaml

@@ -24,8 +24,11 @@
 #       `mcp_auth: { oauth2 }` (ADR 0112): uncomment the block on Systems
 #       below. client_credentials gives the server's own token on every
 #       request. authorization_code (each person's own token, granted
-#       through the consent pause) needs the agent to run the turn
-#       itself: a dispatch route, not a delegated subagent like Systems.
+#       through the consent pause) works on Systems too: the first call
+#       for a person who has not connected pauses the turn with an
+#       authorization link, and their next message after the grant
+#       resumes Systems' call (ADR 0118). It also needs mcp_tools, the
+#       server's tool names, and an operator allowlist (ADR 0114).
 #       `npm run doctor` lists every tool that needs a grant.
 #       Loopback and private addresses are refused unless
 #       ALLOW_PRIVATE_MCP=true (local development).

package/dist/lib/a2a/app.d.ts

@@ -219,6 +219,18 @@ export interface A2AAppOptions {
      * refused when loaded, when compiled, and at each call.
      */
     oauthHosts?: Record<string, string[]>;
+    /**
+     * The credential host allowlist (ADR 0122): each static credential
+     * variable a YAML may send (`bearer_env`, `api_key.env`,
+     * `client_secret_env`) and the hosts its value may go to, e.g.
+     * `{ TRACKER_TOKEN: ['api.tracker.example.com'] }`. Wins over
+     * MELCHIZEDEK_CREDENTIAL_HOSTS; it is set for this process. With neither,
+     * a credential goes to the host the YAML names, as before. With one, it is
+     * the whole list: a syndicate that sends a variable it does not bind, or
+     * to a host outside that variable's, is refused when loaded, when
+     * compiled, and at each call.
+     */
+    credentialHosts?: Record<string, string[]>;
     toolCredentials?: ToolCredentials & {
         /** Callback requests per window per client IP. Default 30 per 15 minutes. */
         callbackLimit?: {

package/dist/lib/a2a/app.js

@@ -64,6 +64,8 @@ import { HEADER_VALUE_PATTERN, SCOPE_KEY_PATTERN } from './identity.js';
 import { createMetrics } from '../observability/metrics.js';
 import { ConsentError } from '../tools/oauthConsent.js';
 import { setOAuthHosts } from '../tools/oauthHosts.js';
+import { setCredentialHosts } from '../tools/credentialHosts.js';
+import { syndicateCredentialHostProblems } from '../tools/credentialUses.js';
 import { syndicateOAuthHostProblems } from '../tools/oauthTools.js';
 const SURFACE_HEADERS = [
     ['x-surface', 'name'],
@@ -280,21 +282,30 @@ export async function createA2AApp(options) {
     // ── The OAuth host allowlist (ADR 0114) ────────────────────────────────────
     if (options.oauthHosts)
         setOAuthHosts(options.oauthHosts);
-    /** A served syndicate whose OAuth grant names a provider or host outside the allowlist is refused at load. */
+    // ── The credential host allowlist (ADR 0122) ───────────────────────────────
+    if (options.credentialHosts)
+        setCredentialHosts(options.credentialHosts);
+    /**
+     * A served syndicate whose OAuth grant names a provider or host outside the
+     * OAuth allowlist, or that sends a static credential the credential
+     * allowlist does not bind to its host, is refused at load.
+     */
     const checkOAuthHosts = (cfg, label) => {
         const nested = nestedLoader(cfg, (ref) => loadSyndicate(ref, { bindings: bindings() }));
-        const problems = syndicateOAuthHostProblems([cfg], {
-            load: (ref) => {
-                try {
-                    return nested(ref);
-                }
-                catch {
-                    return {}; // A nested file that cannot load fails its own compile.
-                }
-            },
-        });
+        const load = (ref) => {
+            try {
+                return nested(ref);
+            }
+            catch {
+                return {}; // A nested file that cannot load fails its own compile.
+            }
+        };
+        const problems = syndicateOAuthHostProblems([cfg], { load });
         if (problems.length)
             throw new Error(`${label}: refusing an OAuth grant the operator's host allowlist does not permit:\n  - ${problems.join('\n  - ')}`);
+        const credentials = syndicateCredentialHostProblems([cfg], { load });
+        if (credentials.length)
+            throw new Error(`${label}: refusing a credential the operator's credential host allowlist does not permit:\n  - ${credentials.join('\n  - ')}`);
         return cfg;
     };
     // ── The default syndicate ──────────────────────────────────────────────────

package/dist/lib/a2a/executor.js

@@ -22,7 +22,7 @@ import { turnLockKey } from './turnLock.js';
 import { ingestTurnMemory, runSyndicateTurn } from '../runtime/syndicateTurn.js';
 import { approvalResponsePart, describeApproval, pendingApproval } from '../runtime/approvals.js';
 import { declaresApprovals } from '../compile.js';
-import { delegatedPauses } from '../runtime/native/interrupts.js';
+import { deepestPause, delegatedPauses, routePause } from '../runtime/native/interrupts.js';
 import { isWorkflowSyndicate } from '../workflow.js';
 import { describeInput } from '../runtime/syndicateTurn.js';
 import { describeConsent } from '../runtime/credentials.js';
@@ -323,7 +323,8 @@ function publishApprovalRequest(eventBus, taskId, contextId, pending) {
  * naming the provider, with a data part carrying the authorization URL and
  * its state nonce. The person opens the URL; the server's callback stores
  * the grant; the next message on the conversation resumes the call. The
- * part carries no token, code or verifier.
+ * part carries no token, code or verifier. For a call inside a delegated
+ * subagent it carries the agent path too (ADR 0118).
  */
 function publishConsentRequest(eventBus, taskId, contextId, pending) {
     const message = statusMessage(taskId, contextId, `Authorization needed: ${describeConsent(pending)}. Open ${pending.authUri} to authorize, then send any message on this conversation to continue.`);
@@ -338,6 +339,8 @@ function publishConsentRequest(eventBus, taskId, contextId, pending) {
                 authorization_url: pending.authUri,
                 state: pending.state,
                 scopes: pending.scopes,
+                // A call paused inside a delegated subagent: the agents from the turn's own down to the one that asked (ADR 0118).
+                ...(pending.path ? { path: pending.path } : {}),
             },
         },
         metadata: undefined,
@@ -594,13 +597,18 @@ export class SyndicateExecutor {
             // A call gated inside a delegated subagent waits below an open call
             // (ADR 0110), wherever the gate is declared, so a syndicate that
             // delegates is read too.
-            const delegates = !isWorkflowSyndicate(config) && !!config.subagents?.length;
-            if (declaresApprovals(config) || delegates) {
+            // A workflow's node that is a nested workflow, and a dispatch route that is one, pause on their walk's gates
+            // wherever those are declared (ADR 0119), so every workflow, and every syndicate that delegates or routes, is read.
+            const workflow = isWorkflowSyndicate(config);
+            const delegates = !workflow && !!config.subagents?.length;
+            if (declaresApprovals(config) || delegates || workflow) {
                 const session = await this.sessions.get({ appName, userId, sessionId: contextId });
                 // The stored Event JSON (ADR 0052), read as TurnEvents.
                 const events = session?.events ?? [];
-                const pending = (declaresApprovals(config) ? pendingApproval(events) : undefined) ??
-                    (delegates ? (await delegatedPauses({ sessions: this.sessions, userId, sessionId: contextId, appName }, events))[0]?.approval : undefined);
+                const key = { sessions: this.sessions, userId, sessionId: contextId, appName };
+                const own = declaresApprovals(config) || workflow ? pendingApproval(events) : undefined;
+                const pending = (own && workflow ? await deepestPause(key, own) : own) ??
+                    (delegates ? ((await routePause(key, events))?.approval ?? (await delegatedPauses(key, events))[0]?.approval) : undefined);
                 if (pending) {
                     const answer = approvalAnswer(rawParts, pending);
                     if (!answer) {

package/dist/lib/a2a/oauthSetup.d.ts

@@ -13,6 +13,7 @@
  *     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
@@ -54,6 +55,19 @@ export declare function grantHostProblems(use: OAuthGrantUse, env?: NodeJS.Proce
  * server refuses to start on the ones that would make it unsafe.
  */
 export declare function oauthEnvProblems(grants: readonly OAuthGrantUse[], env?: NodeJS.ProcessEnv): string[];
+/**
+ * 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 declare function unboundCredentialWarning(envs: readonly string[], env?: NodeJS.ProcessEnv): string | null;
+/**
+ * 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 declare function credentialHostEnvProblems(configs: readonly SyndicateLike[], env?: NodeJS.ProcessEnv, load?: (ref: string) => SyndicateLike): string[];
 /** The parts of a syndicate config the setup reads. */
 type SyndicateLike = Parameters<typeof oauthClientsFor>[0][number];
 export interface OAuthServerSetupOptions {
@@ -76,6 +90,8 @@ export interface OAuthServerSetup {
     toolCredentials?: ToolCredentials;
     /** One line for the server's banner: key id, row store, consent path, providers, allowlist. No value. */
     summary: string;
+    /** One line for the server's banner: the credential host allowlist (ADR 0122), variable names only. */
+    credentialSummary: string;
     /** What works less than the YAML asks, names only. */
     warnings: string[];
 }

package/dist/lib/a2a/oauthSetup.js

@@ -13,6 +13,7 @@
  *     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
@@ -27,6 +28,8 @@ import { credentialStore, memoryCredentialRows } from '../tools/credentialStore.
 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). */
@@ -138,6 +141,42 @@ export function oauthEnvProblems(grants, env = process.env) {
     }
     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
@@ -163,12 +202,26 @@ export function oauthServerSetup(options) {
     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}`, warnings };
+        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);
@@ -184,11 +237,11 @@ export function oauthServerSetup(options) {
     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 };
+        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}`, warnings };
+        return { toolCredentials: { store }, summary: `sealed (key ${cipher.keyId}) in ${where}; no consent step · ${hostsLabel}`, credentialSummary, warnings };
     }
     const consent = oauthConsent({
         providers: clients,
@@ -200,6 +253,7 @@ export function oauthServerSetup(options) {
     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

@@ -7,13 +7,15 @@
  *   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`).
+ *   `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` and `output` into the engine form.
+ *   - `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.
@@ -27,13 +29,21 @@
 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 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', 'model_overrides'];
+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. */
@@ -41,10 +51,10 @@ 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
+ * 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;

package/dist/lib/agentDialect.js

@@ -7,13 +7,15 @@
  *   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`).
+ *   `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` and `output` into the engine form.
+ *   - `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.
@@ -26,6 +28,20 @@
  */
 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'] },
@@ -34,9 +50,10 @@ export const V2_SPELLINGS = [
     { 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', 'model_overrides'];
+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. */
@@ -58,37 +75,37 @@ 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
+ * 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)
+    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, ...rest } = a;
+    const { sampling: _sampling, output: _output, tool_choice: _toolChoice, ...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;
+        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;
         }
-        gcc ??= { ...(isObj(a.generateContentConfig) ? a.generateContentConfig : {}) };
-        gcc[s.v1[1]] = value;
+        parent[s.v1[s.v1.length - 1]] = value;
     }
-    if (gcc)
-        out.generateContentConfig = gcc;
     return out;
 }
 /**

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>;
 /**