melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/syndicateSchema.js

@@ -24,6 +24,8 @@
 import { z } from 'zod';
 import { DEFAULT_ROUTE_KEY, NODE_KINDS, ROUTE_STEP_SUFFIX, START_NAME, elementNames, nodeKind } from './workflowConfig.js';
 import { isSecretShapedEnvName } from './tools/skills/env.js';
+import { OAUTH_SCOPE, PROVIDER_NAME } from './tools/auth.js';
+import { V2_AGENT_KEYS, conflictMessage, conflictsOf, toEngineAgent } from './agentDialect.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's agent-name rule (validateAgentName in ADK's base_agent), kept: checked here
@@ -43,7 +45,7 @@ const thinkingConfig = z
     includeThoughts: z.boolean().optional().describe('Stream the thinking trace in the response.'),
 })
     .describe('Older spelling of `reasoning` for Gemini and Claude (thinkingLevel or thinkingBudget). Cannot be combined with `reasoning`.');
-export const REASONING_LEVELS = ['none', 'low', 'medium', 'high'];
+export const REASONING_LEVELS = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
 /**
  * The provider-neutral reasoning key (ADR 0047): a level, or a token budget.
  * The compiler maps it per provider (lib/compile.ts reasoningConfig).
@@ -60,7 +62,7 @@ const reasoningSchema = z
         return `must be one of ${REASONING_LEVELS.join(' | ')}, or { budget_tokens: <integer ≥ 0> } (got ${describeValue(iss.input)}${hint ? ` — did you mean "${hint}"?` : ''})`;
     },
 })
-    .describe('How hard this agent reasons, on any provider: none | low | medium | high, or { budget_tokens: <int> }. Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047).');
+    .describe('How hard this agent reasons, on any provider: none | low | medium | high | xhigh | max, or { budget_tokens: <int> }. xhigh and max reach the models that take them; elsewhere they go as the model\'s highest setting (ADR 0117). Replaces generateContentConfig.thinkingConfig and reasoningEffort (ADR 0047).');
 /**
  * Loose on purpose: provider-specific fields (e.g. `toolConfig`) pass through
  * to the SDK. Only the documented fields are typed, so `temperature: hot`
@@ -87,8 +89,82 @@ const generateContentConfig = z
         .optional()
         .describe('Older spelling of `reasoning` for the chat-completions and Responses providers. Cannot be combined with `reasoning`.'),
 })
-    .describe('Model generation config (@google/genai GenerateContentConfig). Do not set tools here.');
+    .describe('Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType), `reasoning` (thinkingConfig, reasoningEffort) and `tool_choice` (toolConfig.functionCallingConfig) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. Do not set tools here.')
+    .meta({ deprecated: true });
+// ── YAML v2 agent keys (ADR 0115) ────────────────────────────────────────────
+/** `sampling` and `output` must say something: an empty block is a leftover. */
+const nonEmpty = (o) => Object.keys(o).length > 0;
+/** Only when the block has no other problem: `sampling: { topP: 1 }` is a typo, not an empty block. */
+const quiet = (payload) => payload.issues.length === 0;
+const samplingSchema = z
+    .strictObject({
+    temperature: z.number().optional().describe('Sampling temperature. Replaces generateContentConfig.temperature.'),
+    top_p: z.number().optional().describe('Nucleus sampling. Replaces generateContentConfig.topP.'),
+    max_output_tokens: z.number().int().positive().optional().describe('Cap on the reply\'s tokens. Replaces generateContentConfig.maxOutputTokens.'),
+    stop: z.array(z.string()).min(1).optional().describe('Stop sequences. Replaces generateContentConfig.stopSequences.'),
+})
+    .refine(nonEmpty, { message: 'must set at least one of temperature, top_p, max_output_tokens, stop', when: quiet })
+    .describe('How this agent samples, on any provider (ADR 0115). Replaces the same keys under generateContentConfig; cannot be combined with them.');
+export const OUTPUT_MIMES = ['application/json', 'text/plain'];
+const outputSchemaV2 = z
+    .strictObject({
+    schema: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe('JSON Schema the final reply is one object of. Replaces outputSchema; same behaviour beside tools and subagents (ADR 0109).'),
+    mime: z.enum(OUTPUT_MIMES).optional().describe('application/json: JSON mode without a schema. Replaces generateContentConfig.responseMimeType.'),
+})
+    .refine(nonEmpty, { message: 'must set schema or mime', when: quiet })
+    .describe('What this agent\'s final reply is (ADR 0115). Replaces outputSchema and generateContentConfig.responseMimeType; cannot be combined with them.');
+export const TOOL_CHOICE_MODES = ['auto', 'none', 'required'];
+const toolChoiceSchema = z
+    .union([
+    z.enum(TOOL_CHOICE_MODES),
+    z.strictObject({
+        name: z.string().min(1).describe('The one tool the model must call: a name from this agent\'s tools, subagents or MCP tools.'),
+    }),
+], {
+    error: (iss) => {
+        const hint = typeof iss.input === 'string' ? suggest(iss.input, TOOL_CHOICE_MODES) : undefined;
+        return `must be one of ${TOOL_CHOICE_MODES.join(' | ')}, or { name: <tool> } (got ${describeValue(iss.input)}${hint ? ` — did you mean "${hint}"?` : ''})`;
+    },
+})
+    .describe('Which tools the model may call, on any provider (ADR 0117): auto (the default), none, required (some tool), or { name: <tool> } (that tool). A provider that rejects forcing sends a weaker choice and marks the span llm.tool_choice.weakened. Replaces generateContentConfig.toolConfig.functionCallingConfig; cannot be combined with it.');
+const modelOverrideEntry = z
+    .strictObject({
+    instruction: z.string().min(1).optional().describe('Replaces the agent\'s instruction on this provider.'),
+    instruction_append: z.string().min(1).optional().describe('Appended to the agent\'s instruction, after a blank line, on this provider.'),
+})
+    .refine((o) => (o.instruction === undefined) !== (o.instruction_append === undefined), 'exactly one of instruction or instruction_append')
+    .describe('The instruction on one provider: exactly one of instruction or instruction_append.');
+const modelOverridesSchema = z
+    .strictObject({
+    gemini: modelOverrideEntry.optional(),
+    anthropic: modelOverrideEntry.optional(),
+    openai: modelOverrideEntry.optional(),
+    xai: modelOverrideEntry.optional(),
+    moonshot: modelOverrideEntry.optional(),
+    ollama: modelOverrideEntry.optional(),
+})
+    .describe('Per-provider instruction, keyed by the provider of the agent\'s model id (lib/models/providerMap.ts). Applied at compile time before the skills index; not to fallback_model, and never to globalInstruction (ADR 0115).');
+/** Keys valid inside the v2 blocks, for did-you-mean (knownKeysAt). */
+function v2KnownKeysAt(key) {
+    const agentKey = key.replace(/^(orchestrator|subagents\/#)\//, '');
+    if (agentKey === key)
+        return [];
+    if (agentKey === 'sampling')
+        return Object.keys(samplingSchema.shape);
+    if (agentKey === 'output')
+        return Object.keys(outputSchemaV2.shape);
+    if (agentKey === 'model_overrides')
+        return Object.keys(modelOverridesSchema.shape);
+    if (agentKey.startsWith('model_overrides/') && !agentKey.slice('model_overrides/'.length).includes('/'))
+        return Object.keys(modelOverrideEntry.shape);
+    return [];
+}
 // ── Skills ───────────────────────────────────────────────────────────────────
+/** The most delegated calls one step may run at once (`max_concurrency`, ADR 0116): each is a model run that costs money. */
+const MAX_DELEGATION_CONCURRENCY = 32;
 export const SKILL_SCRIPT_MODES = ['none', 'local'];
 const envName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, 'an environment variable name (A–Z, 0–9, _)');
 /**
@@ -131,6 +207,50 @@ const skillsSchema = z
     }
 })
     .describe('Agent Skills (SKILL.md directories) this agent reads the way a coding harness does.');
+// ── OAuth (ADR 0112) ─────────────────────────────────────────────────────────
+const oauth2Auth = z
+    .strictObject({
+    provider: z
+        .string()
+        .regex(PROVIDER_NAME, 'a provider name: lowercase letters, digits, and . _ - inside, at most 64 characters')
+        .describe('The credential store\'s name for the provider (e.g. github). Every tool naming it shares one grant.'),
+    grant: z
+        .enum(['authorization_code', 'client_credentials'])
+        .describe('authorization_code: each user\'s own token, granted through the consent pause (ADR 0085). client_credentials: the server\'s own token, from the token endpoint.'),
+    authorization_url: z.string().url().optional().describe('The provider\'s authorization endpoint (https). authorization_code only.'),
+    token_url: z.string().url().describe('The provider\'s token endpoint (https).'),
+    client_id: z.string().min(1).max(512).optional().describe('The OAuth client id, written out (it is not a secret). Or client_id_env.'),
+    client_id_env: envName.optional().describe('Environment variable holding the client id. Or client_id.'),
+    client_secret_env: envName
+        .optional()
+        .describe('Environment variable NAME holding the client secret, never the value. Required for client_credentials; omit for a public client (PKCE alone).'),
+    scopes: z.array(z.string().regex(OAUTH_SCOPE, 'an OAuth scope: visible ASCII, no space, quote or backslash')).max(64).optional().describe('The scopes the grant asks for.'),
+    authorization_params: z
+        .record(z.string().regex(/^[A-Za-z0-9_.-]{1,64}$/), z.string().max(512))
+        .optional()
+        .describe('Extra authorization parameters (e.g. access_type: offline). authorization_code only; never state, redirect_uri, scope, client_id or the PKCE pair.'),
+})
+    .superRefine((o, ctx) => {
+    if (!!o.client_id === !!o.client_id_env)
+        ctx.addIssue({ code: 'custom', path: ['client_id'], message: 'exactly one of client_id or client_id_env' });
+    if (o.grant === 'authorization_code' && !o.authorization_url) {
+        ctx.addIssue({ code: 'custom', path: ['authorization_url'], message: 'an authorization_code grant needs authorization_url' });
+    }
+    if (o.grant === 'client_credentials') {
+        if (!o.client_secret_env)
+            ctx.addIssue({ code: 'custom', path: ['client_secret_env'], message: 'a client_credentials grant needs client_secret_env' });
+        for (const key of ['authorization_url', 'authorization_params']) {
+            if (o[key] !== undefined)
+                ctx.addIssue({ code: 'custom', path: [key], message: `${key} is for authorization_code only` });
+        }
+    }
+    const reserved = ['state', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'client_id', 'response_type', 'scope'];
+    for (const key of Object.keys(o.authorization_params ?? {})) {
+        if (reserved.includes(key))
+            ctx.addIssue({ code: 'custom', path: ['authorization_params', key], message: `authorization_params may not set "${key}"` });
+    }
+})
+    .describe('An OAuth 2 access token sent as a bearer token on every call (lib/tools/oauthTools.ts). Secrets come from environment variable names, never values.');
 // ── OpenAPI ──────────────────────────────────────────────────────────────────
 const openapiEntry = z
     .strictObject({
@@ -149,8 +269,9 @@ const openapiEntry = z
             .strictObject({ env: envName, in: z.enum(['header', 'query']), name: z.string().min(1) })
             .optional()
             .describe('An API key read from `env`, sent in a header or the query under `name`.'),
+        oauth2: oauth2Auth.optional(),
     })
-        .refine((a) => !!a.bearer_env !== !!a.api_key, 'exactly one of bearer_env or api_key')
+        .refine((a) => [a.bearer_env, a.api_key, a.oauth2].filter((x) => x !== undefined).length === 1, 'exactly one of bearer_env, api_key or oauth2')
         .optional()
         .describe('Credentials, always from the environment, never written in YAML.'),
 })
@@ -183,7 +304,7 @@ const agentFields = {
     require_approval: z
         .array(z.string().min(1))
         .optional()
-        .describe('Tools from this agent\'s `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on the orchestrator and on plan-dispatch routes.'),
+        .describe('Tools from this agent\'s `tools` that run only after a person approves the exact call (ADR 0028): the A2A task ends input-required until the caller answers approve or reject. Allowed on any agent but one a workflow map node runs; inside a delegated subagent the pause reaches the caller through its open call (ADR 0110).'),
     includeContents: z
         .enum(['default', 'none'])
         .optional()
@@ -193,10 +314,15 @@ const agentFields = {
     outputKey: z.string().optional().describe('Session-state key the final reply is saved under.'),
     generateContentConfig: generateContentConfig.optional(),
     reasoning: reasoningSchema.optional(),
+    sampling: samplingSchema.optional(),
+    output: outputSchemaV2.optional(),
+    tool_choice: toolChoiceSchema.optional(),
+    model_overrides: modelOverridesSchema.optional(),
     outputSchema: z
         .record(z.string(), z.unknown())
+        .meta({ deprecated: true })
         .optional()
-        .describe('JSON Schema for structured output: the agent answers with one JSON object matching it. Hold it on a leaf; an agent that delegates and holds one ends its turn on that JSON.'),
+        .describe('Deprecated v1 spelling (ADR 0115): write output.schema. JSON Schema for structured output: the agent answers with one JSON object matching it. An agent that also calls tools or delegates to subagents does that first, then ends its turn on that JSON: the schema travels beside the tools where the model takes both in one request, as a set_model_response tool elsewhere (the capability matrix\'s structured_output_with_tools, ADR 0109).'),
     mcp_server_url: z
         .string()
         .optional()
@@ -206,6 +332,10 @@ const agentFields = {
         .min(1)
         .optional()
         .describe('The MCP server\'s tools this agent may use, by name; any other tool the server lists is not exposed. Without it, every listed tool is. require_approval may name these. Needs mcp_server_url.'),
+    mcp_auth: z
+        .strictObject({ oauth2: oauth2Auth })
+        .optional()
+        .describe('The OAuth grant the MCP server takes (ADR 0112). With authorization_code, each user\'s own token on their own connection, and mcp_tools is required. Needs mcp_server_url; replaces MCP_BEARER_TOKENS for this server.'),
     skills: skillsSchema.optional(),
     openapi: z.array(openapiEntry).min(1).optional(),
     code_execution: z
@@ -259,7 +389,7 @@ export const subagentSchema = z
         .string()
         .min(1)
         .optional()
-        .describe('A whole nested syndicate (filename under the agents dir) used as this subagent.'),
+        .describe('A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate\'s gates anywhere, a dispatch syndicate\'s on its routes, which it classifies and runs as at the top, its route\'s answer being its own (ADR 0120), and a workflow\'s ask_user nodes and gates, wherever each runs: delegated to as a subagent, as a dispatch route or as a workflow node (ADR 0119).'),
     a2a_agent_url: z
         .string()
         .min(1)
@@ -391,6 +521,13 @@ export const syndicateSchema = z
         .positive()
         .optional()
         .describe('Hard cap on model calls per turn, subagents included. Default 50 (DEFAULT_MAX_STEPS) when unset.'),
+    max_concurrency: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_DELEGATION_CONCURRENCY)
+        .optional()
+        .describe('Subagent calls from one orchestrator step that run at once; the rest wait their turn, in call order. Default 4; 1 runs them one after another. A delegate syndicate only (ADR 0116).'),
     bundled_references: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional()
@@ -466,7 +603,7 @@ function knownKeysAt(p) {
         case 'subagents/#/orchestration':
             return ['role', 'delegates'];
         default:
-            return [];
+            return v2KnownKeysAt(key);
     }
 }
 function valueAt(root, p) {
@@ -559,16 +696,16 @@ function crossFieldProblems(raw) {
         });
     }
     const subs = Array.isArray(raw.subagents) ? raw.subagents : [];
-    // Approval gates (ADR 0028): only tools the agent has, and only on agents
-    // the turn runs directly — a delegated subagent runs inside a tool call,
-    // where the pause cannot reach the caller and the gated tool silently never runs.
+    // Approval gates (ADR 0028): only tools the agent has. A delegated
+    // subagent's pause reaches the caller through the open call (ADR 0110),
+    // so every agent of a delegate, dispatch or workflow syndicate may gate.
     const gateProblems = (agent, path, allowed) => {
         if (agent.require_approval === undefined)
             return;
         if (!allowed) {
             out.push({
                 path: [...path, 'require_approval'],
-                message: 'approval gates run only on the orchestrator or a plan-dispatch route; a delegated subagent cannot pause the turn (ADR 0028)',
+                message: 'approval gates are not supported here (ADR 0028, ADR 0110)',
             });
             return;
         }
@@ -584,17 +721,11 @@ function crossFieldProblems(raw) {
         });
     };
     // A skill script run pauses for approval the same way, so it is allowed in
-    // the same places; `skills.tools` may only unlock tools the agent does not
-    // already carry outright.
-    const skillProblems = (agent, path, allowed) => {
+    // the same places, a delegated subagent included (ADR 0118); `skills.tools`
+    // may only unlock tools the agent does not already carry outright.
+    const skillProblems = (agent, path) => {
         if (!isObj(agent.skills))
             return;
-        if (agent.skills.scripts === 'local' && !allowed) {
-            out.push({
-                path: [...path, 'skills', 'scripts'],
-                message: 'skill scripts pause for approval, which only the orchestrator or a plan-dispatch route can do; a delegated subagent cannot pause the turn (ADR 0028)',
-            });
-        }
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
         (Array.isArray(agent.skills.tools) ? agent.skills.tools : []).forEach((name, j) => {
             if (typeof name === 'string' && tools.includes(name)) {
@@ -603,7 +734,8 @@ function crossFieldProblems(raw) {
         });
     };
     // ask_user ends the turn waiting for the person, the same pause as an
-    // approval, so it is allowed in the same places (lib/runtime/questions.ts).
+    // approval, so it is allowed in the same places (lib/runtime/questions.ts),
+    // a delegated subagent included (ADR 0110); a workflow node asks through an ask_user node.
     const questionProblems = (agent, path, allowed) => {
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
         const at = tools.indexOf('ask_user');
@@ -613,7 +745,7 @@ function crossFieldProblems(raw) {
             out.push({ path: [...path, 'tools', at], message: 'ask_user is not supported on a workflow node yet; use an ask_user node (workflow.nodes)' });
         }
         else if (!allowed) {
-            out.push({ path: [...path, 'tools', at], message: 'ask_user pauses the turn, which only the orchestrator or a plan-dispatch route can do; a delegated subagent cannot' });
+            out.push({ path: [...path, 'tools', at], message: 'ask_user is not supported here (ADR 0110)' });
         }
     };
     // Execution keys (ADR 0033): where each one means something.
@@ -634,9 +766,24 @@ function crossFieldProblems(raw) {
         if (agent.mcp_tools !== undefined && typeof agent.mcp_server_url !== 'string') {
             out.push({ path: [...path, 'mcp_tools'], message: 'mcp_tools chooses among an MCP server\'s tools; it needs mcp_server_url' });
         }
+        if (agent.mcp_auth !== undefined && typeof agent.mcp_server_url !== 'string') {
+            out.push({ path: [...path, 'mcp_auth'], message: 'mcp_auth is the grant an MCP server takes; it needs mcp_server_url' });
+        }
+        if (isObj(agent.mcp_auth) && isObj(agent.mcp_auth.oauth2) && agent.mcp_auth.oauth2.grant === 'authorization_code' && agent.mcp_tools === undefined) {
+            out.push({ path: [...path, 'mcp_auth'], message: 'an authorization_code mcp_auth needs mcp_tools: no user\'s grant exists at startup to list the server\'s tools' });
+        }
     };
     if (isObj(raw.orchestrator))
         executionProblems(raw.orchestrator, ['orchestrator'], true);
+    // max_concurrency bounds an orchestrator's delegated calls (ADR 0116): a workflow bounds its nodes under workflow:, and a dispatch classifier delegates nothing.
+    if (raw.max_concurrency !== undefined && (isObj(raw.workflow) || isObj(raw.dispatch))) {
+        out.push({
+            path: ['max_concurrency'],
+            message: isObj(raw.workflow)
+                ? 'max_concurrency at the root bounds a delegate orchestrator\'s subagent calls; a workflow bounds its nodes with workflow.max_concurrency'
+                : 'max_concurrency bounds a delegate orchestrator\'s subagent calls; a dispatch syndicate\'s classifier delegates nothing (set it in a route\'s own syndicate file)',
+        });
+    }
     for (const [i, sub] of (Array.isArray(raw.subagents) ? raw.subagents : []).entries())
         if (isObj(sub))
             executionProblems(sub, ['subagents', i], false);
@@ -665,21 +812,38 @@ function crossFieldProblems(raw) {
     for (const [i, sub] of subs.entries())
         if (isObj(sub))
             reasoningProblems(sub, ['subagents', i]);
+    // YAML v2 (ADR 0115): one spelling per setting, as for `reasoning` above;
+    // and the v2 keys belong to an inline agent, never to a nested or remote one.
+    const v2Problems = (agent, path) => {
+        if (typeof agent.yaml_reference === 'string' || typeof agent.a2a_agent_url === 'string') {
+            for (const key of V2_AGENT_KEYS) {
+                if (agent[key] === undefined)
+                    continue;
+                out.push({ path: [...path, key], message: 'applies to an inline agent; a nested syndicate (yaml_reference) or a remote agent (a2a_agent_url) sets its own' });
+            }
+        }
+        for (const clash of conflictsOf(agent))
+            out.push({ path: [...path, ...clash.v2], message: conflictMessage(clash) });
+    };
+    if (isObj(raw.orchestrator))
+        v2Problems(raw.orchestrator, ['orchestrator']);
+    for (const [i, sub] of subs.entries())
+        if (isObj(sub))
+            v2Problems(sub, ['subagents', i]);
     if (isObj(raw.orchestrator)) {
         gateProblems(raw.orchestrator, ['orchestrator'], true);
-        skillProblems(raw.orchestrator, ['orchestrator'], true);
+        skillProblems(raw.orchestrator, ['orchestrator']);
         questionProblems(raw.orchestrator, ['orchestrator'], true);
     }
-    const dispatching = isObj(raw.dispatch);
     // A workflow's subagents are its nodes, not delegated tools: a gated call pauses its node, and
     // the walk resumes it (ADR 0098); a skill script run pauses on the same approval (ADR 0106). A map item cannot (workflowProblems).
-    const pausing = dispatching || isObj(raw.workflow);
     subs.forEach((sub, i) => {
         if (!isObj(sub))
             return;
-        gateProblems(sub, ['subagents', i], pausing);
-        skillProblems(sub, ['subagents', i], pausing);
-        questionProblems(sub, ['subagents', i], dispatching);
+        // A delegated subagent's gate, question and skill script run pause the turn through the open call (ADR 0110, ADR 0118).
+        gateProblems(sub, ['subagents', i], true);
+        skillProblems(sub, ['subagents', i]);
+        questionProblems(sub, ['subagents', i], true);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';
         if (hasRef && hasRemote) {
@@ -933,6 +1097,9 @@ export function validateSyndicateConfig(raw, file) {
     // A single-agent syndicate may omit `subagents`; callers always get a list.
     if (raw.subagents === undefined)
         raw.subagents = [];
+    // YAML v2 (ADR 0115): every loader hands downstream the engine form.
+    raw.orchestrator = toEngineAgent(raw.orchestrator);
+    raw.subagents = raw.subagents.map((sub) => toEngineAgent(sub));
     return raw;
 }
 /**
@@ -959,6 +1126,13 @@ export function syndicateJsonSchema() {
                 ];
                 ctx.jsonSchema.not = { required: ['yaml_reference', 'a2a_agent_url'] };
             }
+            // YAML v2 (ADR 0115): the refinements, where JSON Schema can say them.
+            if (ctx.zodSchema === samplingSchema || ctx.zodSchema === outputSchemaV2) {
+                ctx.jsonSchema.minProperties = 1;
+            }
+            if (ctx.zodSchema === modelOverrideEntry) {
+                ctx.jsonSchema.oneOf = [{ required: ['instruction'] }, { required: ['instruction_append'] }];
+            }
         },
     });
     return { ...schema, title: 'Melchizedek syndicate' };

package/dist/lib/tools/auth.d.ts

@@ -22,9 +22,9 @@
  *   (`pinnedCredentialStore`, like namespacedMemoryService), so a delegated
  *   subagent, which runs under its own app name, reads the root's
  *   credentials. The consent step that puts a token is
- *   lib/tools/oauthConsent.ts (ADR 0085); the YAML that lets an agent use a
- *   provider (WS6-3c) comes later; nothing here
- *   wires a tool to the store.
+ *   lib/tools/oauthConsent.ts (ADR 0085); the YAML that lets an OpenAPI or
+ *   MCP tool use a provider (`auth: { oauth2 }`, lib/tools/oauthTools.ts,
+ *   ADR 0112) is what calls `accessToken` for a declared tool.
  *
  * A LEAF: types and plain functions, no runtime imports, so lib/tools/tool.ts
  * can bind the member without loading crypto, pg or telemetry.
@@ -50,7 +50,7 @@ export interface AccessGrant {
     scopes: string[];
     expiresAt?: Date;
 }
-/** How a provider renews and withdraws a token (from the provider's config; WS6-3c). */
+/** How a provider renews and withdraws a token (`oauthRefreshProviders` builds the refresh from a YAML grant, ADR 0112). */
 export interface OAuthProvider {
     /**
      * A new token set for this refresh token. Throw when the provider refuses;
@@ -92,18 +92,32 @@ export interface CredentialStore {
 }
 /** What the ToolContext member gives a tool: a valid access token for a provider, for this run's user only. */
 export type ToolAccessToken = (provider: string) => Promise<string>;
-export type ToolCredentialErrorCode = 'not_connected' | 'expired' | 'refresh_failed' | 'unreadable' | 'no_user' | 'invalid';
+export type ToolCredentialErrorCode = 'not_connected' | 'expired' | 'refresh_failed' | 'unreadable' | 'no_user' | 'invalid' | 'unavailable' | 'grant_failed' | 'host_refused';
+/**
+ * Which operator allowlist refused a `host_refused` call: the OAuth host
+ * allowlist, which binds a provider's tokens to its hosts
+ * (`MELCHIZEDEK_OAUTH_HOSTS`, ADR 0114), or the credential host allowlist,
+ * which binds a static credential variable such as a client secret to its
+ * hosts (`MELCHIZEDEK_CREDENTIAL_HOSTS`, ADR 0122).
+ */
+export type HostAllowlist = 'oauth' | 'credential';
 /**
  * A credential that cannot be used. The message names the provider and what
  * to do, never a token, a user or a key, so a tool may return it to the model.
+ * A `host_refused` error names the allowlist that refused (`allowlist`,
+ * `'oauth'` when not given).
  */
 export declare class ToolCredentialError extends Error {
     readonly code: ToolCredentialErrorCode;
     readonly provider?: string;
-    constructor(code: ToolCredentialErrorCode, provider?: string);
+    /** For `host_refused`: the allowlist that refused the host. */
+    readonly allowlist?: HostAllowlist;
+    constructor(code: ToolCredentialErrorCode, provider?: string, allowlist?: HostAllowlist);
 }
 /** A provider name: lowercase letters, digits, and . _ - inside; at most 64 characters. */
 export declare const PROVIDER_NAME: RegExp;
+/** One OAuth scope token (RFC 6749 3.3: visible ASCII but space, `"` and `\`), at most 256 characters. One class, so it cannot backtrack. */
+export declare const OAUTH_SCOPE: RegExp;
 /**
  * The ToolContext member: an access token for `provider`, from this app's
  * and this user's credentials only. A context that does not know its app

package/dist/lib/tools/auth.js

@@ -22,9 +22,9 @@
  *   (`pinnedCredentialStore`, like namespacedMemoryService), so a delegated
  *   subagent, which runs under its own app name, reads the root's
  *   credentials. The consent step that puts a token is
- *   lib/tools/oauthConsent.ts (ADR 0085); the YAML that lets an agent use a
- *   provider (WS6-3c) comes later; nothing here
- *   wires a tool to the store.
+ *   lib/tools/oauthConsent.ts (ADR 0085); the YAML that lets an OpenAPI or
+ *   MCP tool use a provider (`auth: { oauth2 }`, lib/tools/oauthTools.ts,
+ *   ADR 0112) is what calls `accessToken` for a declared tool.
  *
  * A LEAF: types and plain functions, no runtime imports, so lib/tools/tool.ts
  * can bind the member without loading crypto, pg or telemetry.
@@ -32,11 +32,15 @@
 /**
  * A credential that cannot be used. The message names the provider and what
  * to do, never a token, a user or a key, so a tool may return it to the model.
+ * A `host_refused` error names the allowlist that refused (`allowlist`,
+ * `'oauth'` when not given).
  */
 export class ToolCredentialError extends Error {
     code;
     provider;
-    constructor(code, provider) {
+    /** For `host_refused`: the allowlist that refused the host. */
+    allowlist;
+    constructor(code, provider, allowlist) {
         const p = provider ? `"${provider}"` : 'this provider';
         super(code === 'not_connected'
             ? `No ${p} account is connected for this user; ask them to connect it.`
@@ -48,14 +52,26 @@ export class ToolCredentialError extends Error {
                         ? `The stored ${p} authorization cannot be read with this server's credential key.`
                         : code === 'no_user'
                             ? 'Third-party access needs the app and user of the run.'
-                            : `Invalid credential request for ${p}.`);
+                            : code === 'unavailable'
+                                ? `This server holds no ${p} authorizations: its operator has not configured tool credentials.`
+                                : code === 'grant_failed'
+                                    ? `The server's own ${p} authorization could not be obtained from the provider's token endpoint.`
+                                    : code === 'host_refused'
+                                        ? allowlist === 'credential'
+                                            ? `The ${p} client secret may not be sent to this host: the operator's credential host allowlist (MELCHIZEDEK_CREDENTIAL_HOSTS) does not bind it there.`
+                                            : `The ${p} authorization may not be sent to this host: the operator's OAuth host allowlist (MELCHIZEDEK_OAUTH_HOSTS) does not include it.`
+                                        : `Invalid credential request for ${p}.`);
         this.name = 'ToolCredentialError';
         this.code = code;
         this.provider = provider;
+        if (code === 'host_refused')
+            this.allowlist = allowlist ?? 'oauth';
     }
 }
 /** A provider name: lowercase letters, digits, and . _ - inside; at most 64 characters. */
 export const PROVIDER_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** One OAuth scope token (RFC 6749 3.3: visible ASCII but space, `"` and `\`), at most 256 characters. One class, so it cannot backtrack. */
+export const OAUTH_SCOPE = /^[\x21\x23-\x5b\x5d-\x7e]{1,256}$/;
 /**
  * The ToolContext member: an access token for `provider`, from this app's
  * and this user's credentials only. A context that does not know its app

package/dist/lib/tools/credentialEnv.d.ts

@@ -0,0 +1,28 @@
+/**
+ * lib/tools/credentialEnv.ts — which environment variables a YAML may name
+ * as a credential, and the one way a credential is read from one.
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names both a variable and
+ *   the host its value is sent to: an OpenAPI `auth` (bearer_env, api_key,
+ *   oauth2), an MCP server's `mcp_auth.oauth2`. So a YAML may never name one
+ *   of the framework's own secrets: the database URL, a provider key or an
+ *   A2A secret cannot be sent to an API or a token endpoint.
+ *   OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list of
+ *   variables any of these may name.
+ *
+ * A value is read here and handed to the code that sends it; an error names
+ * the variable, never its value.
+ */
+/**
+ * Why an `auth` may not read this variable, or null. With
+ * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
+ * it, anything but the framework's own variables is.
+ */
+export declare function credentialEnvProblem(name: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * The credential in `name`, trimmed. Throws when the allowlist refuses the
+ * variable or it is not set; `where` prefixes the message, which names the
+ * variable and never its value.
+ */
+export declare function readCredentialEnv(name: string, where: string, env?: NodeJS.ProcessEnv): string;

package/dist/lib/tools/credentialEnv.js

@@ -0,0 +1,52 @@
+/**
+ * lib/tools/credentialEnv.ts — which environment variables a YAML may name
+ * as a credential, and the one way a credential is read from one.
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names both a variable and
+ *   the host its value is sent to: an OpenAPI `auth` (bearer_env, api_key,
+ *   oauth2), an MCP server's `mcp_auth.oauth2`. So a YAML may never name one
+ *   of the framework's own secrets: the database URL, a provider key or an
+ *   A2A secret cannot be sent to an API or a token endpoint.
+ *   OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list of
+ *   variables any of these may name.
+ *
+ * A value is read here and handed to the code that sends it; an error names
+ * the variable, never its value.
+ */
+/** Prefixes and names of variables the framework itself reads: never an API credential. */
+const FRAMEWORK_ENV_PREFIXES = [
+    'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
+    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
+    'ALLOW_', 'OPENAPI_',
+];
+const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT', 'OAUTH_REDIRECT_URI', 'OAUTH_CALLBACK_IDENTITY']);
+/**
+ * Why an `auth` may not read this variable, or null. With
+ * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
+ * it, anything but the framework's own variables is.
+ */
+export function credentialEnvProblem(name, env = process.env) {
+    const allow = env.OPENAPI_CREDENTIAL_ENVS?.split(',').map((s) => s.trim()).filter(Boolean);
+    if (allow?.length) {
+        return allow.includes(name) ? null : `${name} is not in OPENAPI_CREDENTIAL_ENVS (${allow.join(', ')})`;
+    }
+    if (FRAMEWORK_ENV_NAMES.has(name) || FRAMEWORK_ENV_PREFIXES.some((p) => name.startsWith(p))) {
+        return `${name} is one of the framework's own settings and may not be sent to an API; give the API its own variable (or list it in OPENAPI_CREDENTIAL_ENVS)`;
+    }
+    return null;
+}
+/**
+ * The credential in `name`, trimmed. Throws when the allowlist refuses the
+ * variable or it is not set; `where` prefixes the message, which names the
+ * variable and never its value.
+ */
+export function readCredentialEnv(name, where, env = process.env) {
+    const refused = credentialEnvProblem(name, env);
+    if (refused)
+        throw new Error(`${where}: ${refused}`);
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`${where}: ${name} is not set (auth reads it from the environment)`);
+    return value;
+}