melchizedek-agents 1.1.0 → 1.3.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

@@ -46,6 +46,7 @@ import { duplicateInterfacesForLegacy } from '@a2a-js/sdk/compat/v0_3';
 import { agentCardHandler, jsonRpcHandler, restHandler } from '@a2a-js/sdk/server/express';
 import { InProcessSessionService } from '../runtime/sessions.js';
 import { runtimeSetting } from '../runtime/runtimeFlag.js';
+import { refuseChatGptSignInOnServedSurface } from '../chatgpt/state.js';
 import { geminiAdapterSetting } from '../models/adapterResolver.js';
 import { loadSyndicate, loadSyndicateFromRegistry, nestedLoader } from '../loadSyndicate.js';
 import { providerForModel, resolveModel } from '../models/registry.js';
@@ -64,6 +65,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'],
@@ -262,6 +265,8 @@ export async function createA2AApp(options) {
     // A deployment still configured for the removed adk runtime fails here, naming 1.0.0 (ADR 0107).
     runtimeSetting();
     geminiAdapterSetting();
+    // Sign in with ChatGPT is local only (ADR 0126): a served app never runs OpenAI ids on it.
+    refuseChatGptSignInOnServedSurface('The A2A server');
     const log = options.log ?? ((m) => console.log(`[A2A] ${m}`));
     const warn = options.warn ?? ((m) => console.warn(`[A2A] ⚠ ${m}`));
     const bindings = options.bindings ?? (() => ({
@@ -280,21 +285,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
@@ -25,8 +26,11 @@
 import { CREDENTIAL_KEY_ENV, credentialCipherFromEnv } from '../tools/credentialCipher.js';
 import { credentialStore, memoryCredentialRows } from '../tools/credentialStore.js';
 import { oauthConsent } from '../tools/oauthConsent.js';
+import { dynamicOAuthClient, oauthClientRegistry } from '../tools/oauthDiscovery.js';
 import { OAUTH_HOSTS_ENV, oauthHosts } from '../tools/oauthHosts.js';
-import { oauthClientsFor, oauthGrantHostProblems, oauthRefreshProviders, syndicateOAuthGrants, syndicateOAuthHostProblems } from '../tools/oauthTools.js';
+import { dynamicOAuthGrantsFor, 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 +142,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,19 +203,47 @@ 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);
+    const rows = options.rows ?? memoryCredentialRows();
+    // A grant with client_registration: dynamic (ADR 0124): its client is
+    // discovered and registered when first needed, for the configured redirect
+    // URI, and kept sealed beside the users' tokens. Without a redirect URI it
+    // cannot register, and is named in the warning below.
+    const dynamicGrants = dynamicOAuthGrantsFor(options.configs, { env, ...(options.load ? { load: options.load } : {}), allowlist: allowlist ?? null });
+    const registry = oauthClientRegistry({ rows, cipher });
+    const dynamicClients = redirect
+        ? Object.fromEntries(Object.entries(dynamicGrants).map(([name, grant]) => [
+            name,
+            dynamicOAuthClient(grant, { redirectUri: redirect, registry, ...(options.allowPrivate ? { allowPrivate: true } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) }),
+        ]))
+        : {};
+    const allClients = { ...clients, ...dynamicClients };
+    const providers = [...Object.keys(clients), ...Object.keys(dynamicGrants)];
     const store = credentialStore({
-        rows: options.rows ?? memoryCredentialRows(),
+        rows,
         cipher,
-        providers: oauthRefreshProviders(clients, { ...(options.allowPrivate ? { allowPrivate: true } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) }),
+        providers: oauthRefreshProviders(allClients, { ...(options.allowPrivate ? { allowPrivate: true } : {}), ...(options.fetch ? { fetch: options.fetch } : {}) }),
         ...(options.audit ? { audit: options.audit } : {}),
     });
     if (!options.rows)
@@ -184,14 +252,14 @@ 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,
+        providers: allClients,
         redirectUri: redirect,
         credentials: store,
         ...(options.audit ? { audit: options.audit } : {}),
@@ -200,6 +268,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/chatgpt/adapter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * lib/chatgpt/adapter.ts — GPT on the person's ChatGPT plan, through Sign in
+ * with ChatGPT, on their own machine only (ADR 0126).
+ *
+ * It is GptAdapter (the Responses API) with a different credential and the
+ * request shape OpenAI documents for plan usage
+ * (developers.openai.com/siwc/token-sharing-open-source/models-and-inference
+ * and …/preview-limitations):
+ *   - always `POST https://api.openai.com/v1/responses`, never a proxy or a
+ *     platform, with the stored access token as the bearer, refreshed as it
+ *     nears expiry (lib/chatgpt/oauth.ts freshAccessToken), and no
+ *     organization or project header;
+ *   - `stream: true` and `store: false` on every request; a call that did
+ *     not ask to stream is streamed and folded back into one final;
+ *   - none of the parameters the preview refuses: `max_output_tokens`,
+ *     `temperature`, `top_p`;
+ *   - no SDK retries: a plan-usage limit (429) is reported, not hammered.
+ * The provider id stays `openai`, so reasoning replay and the stored events
+ * are the same as on a key.
+ *
+ * On a served surface (lib/chatgpt/state.ts markServedSurface) every call
+ * ends in a CHATGPT_SIGNIN_LOCAL_ONLY final before any token is read.
+ */
+import type { ModelRequest, ModelResponse } from '../models/contract.ts';
+import type { ProviderEndpoint } from '../models/endpoints.ts';
+import { GptAdapter } from '../models/gptAdapter.ts';
+import type { OAuthOptions } from './oauth.ts';
+export interface ChatGptSignInAdapterOptions extends OAuthOptions {
+    model: string;
+    /** The credential file; default signInFile(). */
+    file?: string;
+}
+export declare class ChatGptSignInAdapter extends GptAdapter {
+    #private;
+    protected readonly label: string;
+    constructor(options: ChatGptSignInAdapterOptions);
+    protected endpoint(): ProviderEndpoint;
+    protected baseURL(): string;
+    protected missingKeyMessage(): string;
+    /** The token source: read (and refreshed) on every request, never held in the adapter. */
+    protected clientAuth(): {
+        apiKey: () => Promise<string>;
+        baseURL: string;
+    };
+    protected clientOptions(): Record<string, unknown>;
+    /** The preview takes none of the sampling fields. */
+    protected acceptsSampling(): boolean;
+    requestBody(request: ModelRequest, model?: string, endpoint?: ProviderEndpoint): Record<string, unknown>;
+    generate(request: ModelRequest): AsyncGenerator<ModelResponse, void>;
+}