melchizedek-agents 1.1.0 → 1.2.0

package/dist/lib/session/transcript.js

@@ -340,6 +340,15 @@ export class ProjectedSessionService {
      * The event lands in the projected session the runtime holds and, through
      * the store, in the real one `get` read. A session `get` did not hand out
      * is the real one, and the store alone applies the event to it.
+     *
+     * A store may answer an append with events of its own: a durable run's
+     * store restoring a checkpoint (lib/runtime/native/checkpoint.ts, ADR 0113)
+     * answers the opening message with the run's stored events, the stored
+     * opening returned in place of the one given. The projected session then
+     * takes, in place of the event given, every event the real session gained,
+     * unprojected: they are the current turn, which is never projected. The
+     * agent loop thereby reads the restored steps, as it would on the store's
+     * own session.
      */
     async append(session, event) {
         if (event.partial)
@@ -347,7 +356,17 @@ export class ProjectedSessionService {
         const real = this.stored.get(this.key(session.appName, session.userId, session.id));
         if (!real || real === session)
             return this.own.append(session, event);
+        const before = real.events.length;
+        const at = session.events.length;
         applyEvent(session, event);
-        return this.own.append(real, event);
+        const stored = await this.own.append(real, event);
+        if (stored.id !== event.id) {
+            // The store answered with its own events: they replace the one applied above.
+            if (session.events[at]?.id === event.id)
+                session.events.splice(at, 1);
+            for (const gained of real.events.slice(before))
+                applyEvent(session, gained);
+        }
+        return stored;
     }
 }

package/dist/lib/skills.d.ts

@@ -48,3 +48,21 @@ export interface InstallResult {
 export declare function destinationsFor(opts: InstallOptions): string[];
 /** Copy the suite into every destination. Returns one result per destination. */
 export declare function installSkills(opts?: InstallOptions): InstallResult[];
+/** The markers that delimit the block this installer owns inside AGENTS.md. */
+export declare const AGENTS_MD_BEGIN = "<!-- melchizedek-skills:begin -->";
+export declare const AGENTS_MD_END = "<!-- melchizedek-skills:end -->";
+/** The pointer: where the skills are, and the onboarding entry point. */
+export declare function agentsMdBlock(destinations: string[], projectRoot: string): string;
+export interface AgentsMdResult {
+    path: string;
+    status: 'created' | 'appended' | 'updated' | 'unchanged';
+}
+/**
+ * Write the pointer into `<projectRoot>/AGENTS.md`, the instructions file
+ * Codex and other agents read: create the file when absent, append the block
+ * when the file has none, or replace only the block between the markers.
+ * Nothing outside the markers is ever changed.
+ */
+export declare function writeAgentsMdPointer(projectRoot: string, destinations: string[], opts?: {
+    dryRun?: boolean;
+}): AgentsMdResult;

package/dist/lib/skills.js

@@ -15,7 +15,7 @@
  * A SKILL.md's frontmatter is read by the skills harness's own parser
  * (lib/tools/skills/frontmatter.ts), the one an agent's `skills:` uses.
  */
-import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readSync, readdirSync, readFileSync, statSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -162,3 +162,75 @@ export function installSkills(opts = {}) {
     }
     return results;
 }
+// ── The AGENTS.md pointer ────────────────────────────────────────────────────
+/** The markers that delimit the block this installer owns inside AGENTS.md. */
+export const AGENTS_MD_BEGIN = '<!-- melchizedek-skills:begin -->';
+export const AGENTS_MD_END = '<!-- melchizedek-skills:end -->';
+/** The pointer: where the skills are, and the onboarding entry point. */
+export function agentsMdBlock(destinations, projectRoot) {
+    const where = destinations.map((d) => `\`${relative(projectRoot, d) || '.'}/\``).join(' and ');
+    return [
+        AGENTS_MD_BEGIN,
+        '## Melchizedek agent skills',
+        '',
+        `The melchizedek-agents skills are installed in ${where}, one directory per skill with a SKILL.md.`,
+        'To onboard someone, start with `melchizedek-onboard/SKILL.md`, or run `npx melchizedek-setup --auto`.',
+        'Never ask for an API key in chat and never print a value from `.env`: the person types keys into `.env` themselves.',
+        AGENTS_MD_END,
+    ].join('\n');
+}
+/**
+ * Write the pointer into `<projectRoot>/AGENTS.md`, the instructions file
+ * Codex and other agents read: create the file when absent, append the block
+ * when the file has none, or replace only the block between the markers.
+ * Nothing outside the markers is ever changed.
+ */
+export function writeAgentsMdPointer(projectRoot, destinations, opts = {}) {
+    const path = join(resolve(projectRoot), 'AGENTS.md');
+    const block = agentsMdBlock(destinations, resolve(projectRoot));
+    const plan = (text) => {
+        if (text === undefined)
+            return { status: 'created', next: `# AGENTS.md\n\n${block}\n` };
+        const start = text.indexOf(AGENTS_MD_BEGIN);
+        const end = text.indexOf(AGENTS_MD_END);
+        if (start !== -1 && end > start) {
+            const next = text.slice(0, start) + block + text.slice(end + AGENTS_MD_END.length);
+            return { status: next === text ? 'unchanged' : 'updated', next };
+        }
+        return { status: 'appended', next: `${text}${text.endsWith('\n') ? '' : '\n'}\n${block}\n` };
+    };
+    if (opts.dryRun) {
+        // Nothing is written, so a path check is enough to report what would happen.
+        if (existsSync(path) && lstatSync(path).isSymbolicLink())
+            throw new Error(`refusing to write through a symlink: ${path}`);
+        return { path, status: plan(existsSync(path) ? readFileSync(path, 'utf-8') : undefined).status };
+    }
+    // One handle for the read and the write, so the file read is the file written:
+    // created if absent, never followed through a symlink (O_NOFOLLOW).
+    let fd;
+    try {
+        fd = openSync(path, fsConstants.O_RDWR | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0), 0o644);
+    }
+    catch (err) {
+        if (err.code === 'ELOOP')
+            throw new Error(`refusing to write through a symlink: ${path}`);
+        throw err;
+    }
+    let status;
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new Error(`not a regular file: ${path}`);
+        const existing = stat.size > 0 ? readFileSync(fd, 'utf-8') : undefined;
+        const result = plan(existing);
+        status = result.status;
+        if (status !== 'unchanged') {
+            ftruncateSync(fd, 0);
+            writeSync(fd, result.next, 0);
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { path, status };
+}

package/dist/lib/storage/postgres/index.d.ts

@@ -21,7 +21,7 @@ import type { CredentialStoreOptions } from '../../tools/credentialStore.ts';
 import type { CredentialStore } from '../../tools/auth.ts';
 import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
-import type { TaskBackend } from '../../tools/taskTools.ts';
+import type { TaskBackend, TaskBackendOptions } from '../../tools/taskTools.ts';
 import type { TurnLock } from '../../a2a/turnLock.ts';
 import type { PostgresTaskStoreOptions } from './taskStore.ts';
 export { PostgresSessionService } from './sessionService.ts';
@@ -73,6 +73,11 @@ export interface PostgresStorageOptions {
      * go to this storage's audit trail.
      */
     credentials?: Omit<CredentialStoreOptions, 'rows' | 'audit'>;
+    /**
+     * The job queue's checkpoints (ADR 0113): the largest one stored, in bytes
+     * of JSON (default 5 MiB), and where a skipped save is logged.
+     */
+    taskQueue?: TaskBackendOptions;
 }
 export interface PostgresStorage {
     pool: Pool;

package/dist/lib/storage/postgres/index.js

@@ -120,7 +120,7 @@ export function postgresStorage(options) {
             reap: () => reapExpiredTasks(pool),
             cancelRequested: () => cancelRequestedTasks(pool, lease),
         },
-        taskQueue: postgresTaskBackend(pool),
+        taskQueue: postgresTaskBackend(pool, options.taskQueue),
         async schemaVersion() {
             try {
                 const r = await pool.query('SELECT max(version) AS v FROM melchizedek_schema_version');

package/dist/lib/storage/postgres/taskQueue.d.ts

@@ -27,8 +27,12 @@
  * survives while the job is running or queued: recover's requeue keeps it,
  * so the next claim resumes from it, and claimNext leaves it; a mutate that
  * moves the job to any other status, or recover failing it, clears it; a
- * deleted row takes it along.
+ * deleted row takes it along. A checkpoint whose JSON is above the cap
+ * (TaskBackendOptions.checkpointMaxBytes, default 5 MiB) is not written:
+ * the column keeps the previous one, the save still reports the claim, and
+ * one line names the job id and the sizes.
  */
 import type { Pool } from 'pg';
-import type { TaskBackend } from '../../tools/taskTools.ts';
-export declare function postgresTaskBackend(pool: Pool): TaskBackend;
+import type { TaskBackend, TaskBackendOptions } from '../../tools/taskTools.ts';
+/** The task backend on `pool`; `options` caps the checkpoint a save stores (TaskBackendOptions). */
+export declare function postgresTaskBackend(pool: Pool, options?: TaskBackendOptions): TaskBackend;

package/dist/lib/storage/postgres/taskQueue.js

@@ -1,4 +1,4 @@
-import { applyFinish, applyInterrupted } from '../../tools/taskTools.js';
+import { applyFinish, applyInterrupted, checkpointJson } from '../../tools/taskTools.js';
 const seqOf = (id) => Number(id.slice(1)) || 0;
 async function loadOwner(db, owner, lock) {
     const head = await db.query(`SELECT next_id FROM melchizedek_task_owners WHERE owner = $1${lock ? ' FOR UPDATE' : ''}`, [owner]);
@@ -21,7 +21,8 @@ async function inTransaction(pool, run) {
         client.release();
     }
 }
-export function postgresTaskBackend(pool) {
+/** The task backend on `pool`; `options` caps the checkpoint a save stores (TaskBackendOptions). */
+export function postgresTaskBackend(pool, options = {}) {
     return {
         read: (owner) => loadOwner(pool, owner, false),
         async mutate(owner, change) {
@@ -82,8 +83,14 @@ export function postgresTaskBackend(pool) {
             return (r.rowCount ?? 0) > 0;
         },
         async saveCheckpoint(worker, job, checkpoint) {
+            const json = checkpointJson(job, checkpoint, options);
+            if (json === null) {
+                // Over the cap: the previous checkpoint is kept; the answer is still whether the claim holds.
+                const held = await pool.query(`SELECT 1 FROM melchizedek_tasks WHERE owner = $1 AND id = $2 AND lease_owner = $3 AND status = 'running'`, [job.owner, job.id, worker.workerId]);
+                return (held.rowCount ?? 0) > 0;
+            }
             const r = await pool.query(`UPDATE melchizedek_tasks SET checkpoint = $4::jsonb, checkpoint_at = NOW()
-          WHERE owner = $1 AND id = $2 AND lease_owner = $3 AND status = 'running'`, [job.owner, job.id, worker.workerId, JSON.stringify(checkpoint)]);
+          WHERE owner = $1 AND id = $2 AND lease_owner = $3 AND status = 'running'`, [job.owner, job.id, worker.workerId, json]);
             return (r.rowCount ?? 0) > 0;
         },
         async loadCheckpoint(job) {

package/dist/lib/syndicateSchema.d.ts

@@ -24,8 +24,9 @@
 import { z } from 'zod';
 import type { SyndicateYamlConfig } from './loadSyndicate.ts';
 export declare const MEMORY_SYSTEMS: readonly ['internal-only', 'session-only', 'long-term'];
-export declare const REASONING_LEVELS: readonly ['none', 'low', 'medium', 'high'];
+export declare const REASONING_LEVELS: readonly ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
 export declare const OUTPUT_MIMES: readonly ['application/json', 'text/plain'];
+export declare const TOOL_CHOICE_MODES: readonly ['auto', 'none', 'required'];
 export declare const SKILL_SCRIPT_MODES: readonly ['none', 'local'];
 export declare const agentSchema: z.ZodObject<{
     name: z.ZodString;
@@ -67,8 +68,10 @@ export declare const agentSchema: z.ZodObject<{
     reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         high: "high";
         low: "low";
+        max: "max";
         medium: "medium";
         none: "none";
+        xhigh: "xhigh";
     }>, z.ZodObject<{
         budget_tokens: z.ZodNumber;
     }, z.core.$strict>]>>;
@@ -85,6 +88,13 @@ export declare const agentSchema: z.ZodObject<{
             "text/plain": "text/plain";
         }>>;
     }, z.core.$strict>>;
+    tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        required: "required";
+    }>, z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>]>>;
     model_overrides: z.ZodOptional<z.ZodObject<{
         gemini: z.ZodOptional<z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
@@ -233,8 +243,10 @@ export declare const subagentSchema: z.ZodObject<{
     reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
         high: "high";
         low: "low";
+        max: "max";
         medium: "medium";
         none: "none";
+        xhigh: "xhigh";
     }>, z.ZodObject<{
         budget_tokens: z.ZodNumber;
     }, z.core.$strict>]>>;
@@ -251,6 +263,13 @@ export declare const subagentSchema: z.ZodObject<{
             "text/plain": "text/plain";
         }>>;
     }, z.core.$strict>>;
+    tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        required: "required";
+    }>, z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$strict>]>>;
     model_overrides: z.ZodOptional<z.ZodObject<{
         gemini: z.ZodOptional<z.ZodObject<{
             instruction: z.ZodOptional<z.ZodString>;
@@ -403,8 +422,10 @@ export declare const syndicateSchema: z.ZodObject<{
         reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
             high: "high";
             low: "low";
+            max: "max";
             medium: "medium";
             none: "none";
+            xhigh: "xhigh";
         }>, z.ZodObject<{
             budget_tokens: z.ZodNumber;
         }, z.core.$strict>]>>;
@@ -421,6 +442,13 @@ export declare const syndicateSchema: z.ZodObject<{
                 "text/plain": "text/plain";
             }>>;
         }, z.core.$strict>>;
+        tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            auto: "auto";
+            none: "none";
+            required: "required";
+        }>, z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>]>>;
         model_overrides: z.ZodOptional<z.ZodObject<{
             gemini: z.ZodOptional<z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;
@@ -563,8 +591,10 @@ export declare const syndicateSchema: z.ZodObject<{
         reasoning: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
             high: "high";
             low: "low";
+            max: "max";
             medium: "medium";
             none: "none";
+            xhigh: "xhigh";
         }>, z.ZodObject<{
             budget_tokens: z.ZodNumber;
         }, z.core.$strict>]>>;
@@ -581,6 +611,13 @@ export declare const syndicateSchema: z.ZodObject<{
                 "text/plain": "text/plain";
             }>>;
         }, z.core.$strict>>;
+        tool_choice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            auto: "auto";
+            none: "none";
+            required: "required";
+        }>, z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strict>]>>;
         model_overrides: z.ZodOptional<z.ZodObject<{
             gemini: z.ZodOptional<z.ZodObject<{
                 instruction: z.ZodOptional<z.ZodString>;

package/dist/lib/syndicateSchema.js

@@ -45,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).
@@ -62,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`
@@ -89,7 +89,7 @@ const generateContentConfig = z
         .optional()
         .describe('Older spelling of `reasoning` for the chat-completions and Responses providers. Cannot be combined with `reasoning`.'),
 })
-    .describe('Deprecated v1 spelling (ADR 0115): write `sampling` (temperature, top_p, max_output_tokens, stop), `output.mime` (responseMimeType) and `reasoning` (thinkingConfig, reasoningEffort) instead; npx melchizedek-codemod rewrites a file. Still read: the Gemini GenerateContentConfig shape the engine takes. 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. */
@@ -116,6 +116,20 @@ const outputSchemaV2 = z
 })
     .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.'),
@@ -302,6 +316,7 @@ const agentFields = {
     reasoning: reasoningSchema.optional(),
     sampling: samplingSchema.optional(),
     output: outputSchemaV2.optional(),
+    tool_choice: toolChoiceSchema.optional(),
     model_overrides: modelOverridesSchema.optional(),
     outputSchema: z
         .record(z.string(), z.unknown())
@@ -374,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. 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 classifier (its routes never run nested), and a workflow\'s ask_user nodes and gates when it is delegated to as a 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)
@@ -706,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 on a delegated subagent are not supported yet; run them on the orchestrator or a plan-dispatch route (ADR 0110)',
-            });
-        }
         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)) {
@@ -823,19 +832,17 @@ function crossFieldProblems(raw) {
             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;
-        // A delegated subagent's gate and question pause the turn through the open call (ADR 0110); its skill scripts stay refused.
+        // 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], pausing);
+        skillProblems(sub, ['subagents', i]);
         questionProblems(sub, ['subagents', i], true);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';

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

@@ -93,14 +93,26 @@ 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' | '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;

package/dist/lib/tools/auth.js

@@ -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.`
@@ -53,11 +57,15 @@ export class ToolCredentialError extends Error {
                                 : code === 'grant_failed'
                                     ? `The server's own ${p} authorization could not be obtained from the provider's token endpoint.`
                                     : code === 'host_refused'
-                                        ? `The ${p} authorization may not be sent to this host: the operator's OAuth host allowlist does not include it.`
+                                        ? 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. */

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

@@ -0,0 +1,88 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+/** The environment variable the allowlist is read from when no option sets it. */
+export declare const CREDENTIAL_HOSTS_ENV = "MELCHIZEDEK_CREDENTIAL_HOSTS";
+/** Credential variable name → the hosts its value may be sent to. */
+export type CredentialHostAllowlist = Readonly<Record<string, readonly string[]>>;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export declare function checkCredentialHosts(allowlist: Record<string, readonly string[]>, source?: string): Record<string, string[]>;
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export declare function parseCredentialHosts(text: string): Record<string, string[]>;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export declare function setCredentialHosts(allowlist: Record<string, readonly string[]> | undefined): void;
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export declare function credentialHosts(env?: NodeJS.ProcessEnv): CredentialHostAllowlist | undefined;
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export declare function credentialHostProblem(name: string, url: string, role?: string, allowlist?: CredentialHostAllowlist | null | undefined): string | null;
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export declare function credentialCallProblem(name: string, destination: string): string | null;
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export declare const CLIENT_SECRET_ENV: unique symbol;
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export declare function clientSecretEnvOf(client: object): string | undefined;