melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/doctor.js

@@ -7,7 +7,8 @@
  *   from the YAMLs and the environment: every syndicate the loader can see,
  *   every agent's model, the provider that id routes to, whether that path
  *   is funded (direct key, gateway, or local), and which declared
- *   server-side tools the path will drop. Then it says exactly what to set,
+ *   server-side tools the path will drop, and which tools need an OAuth
+ *   grant before they work (ADR 0112). Then it says exactly what to set,
  *   grouped by how much each variable unlocks.
  *
  * WHAT IT NEVER DOES:
@@ -33,6 +34,13 @@ import { credentialSource, endpointFromEnv, endpointLabel, endpointProblems, PLA
 import { GATEWAY_ENV, GATEWAY_KEY_ENV, GATEWAYS, gatewayConfig, gatewayProblem, gatewayUsable, } from './models/gateway.js';
 import { PROVIDERS } from './models/providerMap.js';
 import { describeRuntime } from './runtime/runtimeFlag.js';
+import { agentOAuthGrants, oauthEnvNames } from './tools/oauthTools.js';
+import { grantHostProblems, OAUTH_REDIRECT_URI_ENV, oauthEnvProblems } from './a2a/oauthSetup.js';
+import { CREDENTIAL_KEY_ENV } from './tools/credentialCipher.js';
+import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
+import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
+import { syndicateCredentialUses } from './tools/credentialUses.js';
+import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
 function resolvable(module) {
     try {
         createRequire(import.meta.url).resolve(module);
@@ -95,6 +103,69 @@ export function endpointRows() {
     }
     return rows;
 }
+/** One status per provider, probed with an id of its own prefix (the providers line). */
+export function providerPaths() {
+    return Object.keys(PROVIDERS).map((p) => {
+        const r = describeCapabilities(PROBE_ID[p]);
+        return {
+            provider: p,
+            label: PROVIDERS[p].label,
+            funded: r.funded,
+            transport: r.transport,
+            ...(r.gateway ? { gateway: r.gateway } : {}),
+            platform: p === 'ollama' ? 'local' : (r.platform ?? 'direct'),
+            keyEnv: r.keyEnv,
+        };
+    });
+}
+/** The serving variables the doctor reports by presence. */
+export const SERVING_ENV = [
+    'A2A_AUTH',
+    'A2A_SERVER_SECRET',
+    'A2A_CALLERS',
+    'A2A_JWT_ISSUER',
+    'A2A_JWT_AUDIENCE',
+    'A2A_JWT_JWKS_URL',
+    'A2A_JWT_SECRET',
+    'A2A_TRUSTED_USER_HEADER',
+    'A2A_KEY_MODE',
+    'PUBLIC_URL',
+];
+/**
+ * How the A2A server would authenticate callers and who would pay, from the
+ * environment; undefined when none of its variables is set. The checks are
+ * the ones scripts/a2a_server.ts stops on, reported by name.
+ */
+export function servingReport(env = process.env) {
+    const has = (name) => !!env[name]?.trim();
+    const set = Object.fromEntries(SERVING_ENV.map((name) => [name, has(name)]));
+    if (!Object.values(set).some(Boolean))
+        return undefined;
+    // A value outside the known modes is reported as `invalid`, never echoed:
+    // a secret pasted into the wrong variable must not reach the terminal.
+    const rawAuth = (env.A2A_AUTH ?? '').trim().toLowerCase() || 'secret';
+    const rawKeyMode = (env.A2A_KEY_MODE ?? '').trim().toLowerCase() || 'server';
+    const auth = ['secret', 'callers', 'jwt', 'header'].includes(rawAuth) ? rawAuth : 'invalid';
+    const keyMode = rawKeyMode === 'server' || rawKeyMode === 'byok' ? rawKeyMode : 'invalid';
+    const problems = [];
+    if (auth === 'invalid')
+        problems.push('A2A_AUTH must be secret, callers, jwt or header');
+    if (auth === 'callers' && !has('A2A_CALLERS'))
+        problems.push('A2A_AUTH=callers needs A2A_CALLERS');
+    if (auth === 'jwt' && (!has('A2A_JWT_ISSUER') || !has('A2A_JWT_AUDIENCE')))
+        problems.push('A2A_AUTH=jwt needs A2A_JWT_ISSUER and A2A_JWT_AUDIENCE');
+    if (auth === 'jwt' && !has('A2A_JWT_JWKS_URL') && !has('A2A_JWT_SECRET'))
+        problems.push('A2A_AUTH=jwt needs A2A_JWT_JWKS_URL or A2A_JWT_SECRET');
+    if (auth === 'header' && (!has('A2A_TRUSTED_USER_HEADER') || !has('A2A_SERVER_SECRET')))
+        problems.push('A2A_AUTH=header needs A2A_TRUSTED_USER_HEADER and A2A_SERVER_SECRET');
+    if (keyMode !== 'server' && keyMode !== 'byok')
+        problems.push("A2A_KEY_MODE must be 'server' or 'byok'");
+    if (has('PUBLIC_URL') && !has('A2A_AUTH'))
+        problems.push('PUBLIC_URL is set, so A2A_AUTH must be set explicitly (with A2A_SERVED_AGENTS and A2A_TRUST_PROXY)');
+    if (auth === 'secret' && !has('A2A_SERVER_SECRET') && keyMode === 'byok')
+        problems.push('A2A_KEY_MODE=byok without A2A_SERVER_SECRET (or caller tokens) serves unauthenticated, loopback only');
+    return { auth, authDeclared: has('A2A_AUTH'), keyMode, set, problems };
+}
 // ── Where to get a key ───────────────────────────────────────────────────────
 export const CONSOLE_URLS = {
     gemini: 'https://aistudio.google.com',
@@ -160,6 +231,18 @@ export function tierOf(rows) {
         return 'multi-provider';
     return providers[0] === 'ollama' ? 'keyless' : providers[0];
 }
+/** The OAuth grants one agent's tools declare, with the variables not set here. */
+function grantsOf(agent, prefix) {
+    return agentOAuthGrants(agent, prefix).map((use) => ({
+        agent: use.agent,
+        tools: use.tools,
+        provider: use.oauth2.provider,
+        grant: use.oauth2.grant,
+        scopes: [...(use.oauth2.scopes ?? [])],
+        missingEnv: oauthEnvNames(use.oauth2).filter((name) => !process.env[name]?.trim()),
+        hostProblems: grantHostProblems(use),
+    }));
+}
 /** The first problem, without the file prefix the doctor already shows. */
 function firstProblem(err) {
     if (err instanceof SyndicateValidationError)
@@ -179,6 +262,8 @@ function needsOf(agent, delegates = false) {
 function walk(config, prefix, opts, rows) {
     const orch = config.orchestrator;
     const orchModel = orch?.model;
+    if (orch)
+        opts.grants.push(...grantsOf(orch, prefix));
     if (orch && orchModel) {
         // In DELEGATE mode the orchestrator calls its subagents as tools; under
         // plan-dispatch it is a tool-less classifier and code runs the route; in
@@ -218,6 +303,7 @@ function walk(config, prefix, opts, rows) {
             }
             continue;
         }
+        opts.grants.push(...grantsOf(sub, prefix));
         // A subagent without its own model inherits the orchestrator's.
         const model = sub.model ?? orchModel;
         if (!model)
@@ -283,7 +369,19 @@ export function diagnoseSyndicate(file, agentsDir, scripts) {
         const config = load(file);
         const rows = [];
         const nestedErrors = [];
-        walk(config, '', { load, seen: new Set([file, path.basename(file)]), nestedErrors }, rows);
+        const grants = [];
+        walk(config, '', { load, seen: new Set([file, path.basename(file)]), nestedErrors, grants }, rows);
+        // Static credentials and the credential host allowlist (ADR 0122); a nested file that cannot load is reported above.
+        const loadQuiet = (ref) => {
+            try {
+                return load(ref);
+            }
+            catch {
+                return {};
+            }
+        };
+        const credentialEnvs = [...new Set(syndicateCredentialUses([config], loadQuiet).map((u) => u.env))].sort();
+        const credentials = credentialEnvs.length ? { envs: credentialEnvs, problems: credentialHostEnvProblems([config], process.env, loadQuiet) } : undefined;
         const memory = config.memory_system === 'long-term'
             ? {
                 namespace: config.memory_namespace ?? LEGACY_MEMORY_APP_NAME,
@@ -302,6 +400,8 @@ export function diagnoseSyndicate(file, agentsDir, scripts) {
             ...(runCommand ? { runCommand } : {}),
             ...(nestedErrors.length ? { error: nestedErrors.join('\n') } : {}),
             ...(memory ? { memory } : {}),
+            ...(grants.length ? { grants } : {}),
+            ...(credentials ? { credentials } : {}),
         };
     }
     catch (err) {
@@ -383,8 +483,9 @@ export function runDoctor(options = {}) {
     const rawGateway = (process.env[GATEWAY_ENV] ?? '').trim();
     const gateway = rawGateway
         ? {
-            id: cfg?.gateway.id ?? rawGateway,
-            label: cfg?.gateway.label ?? rawGateway,
+            // An unrecognised value is never echoed: it may be a key pasted into the wrong variable.
+            id: cfg?.gateway.id ?? 'unrecognised',
+            label: cfg?.gateway.label ?? 'an unrecognised gateway',
             usable: gatewayUsable(),
             ...(gatewayProblem() ? { problem: gatewayProblem() } : {}),
         }
@@ -398,7 +499,43 @@ export function runDoctor(options = {}) {
     for (const s of syndicates)
         counts[s.verdict.state]++;
     flagMemoryNamespaces(syndicates);
-    return { agentsDir, runtime: runtimeReport(), syndicates, unlocks, gateway, endpoints: endpointRows(), counts };
+    // The server's OAuth setup (ADR 0114): the key, the redirect URI and the allowlist, names only.
+    const grants = syndicates.flatMap((s) => s.grants ?? []).map((g) => ({ agent: g.agent, tools: g.tools, oauth2: { provider: g.provider, grant: g.grant, token_url: '' } }));
+    const set = Object.fromEntries([CREDENTIAL_KEY_ENV, OAUTH_REDIRECT_URI_ENV, OAUTH_HOSTS_ENV].map((name) => [name, !!process.env[name]?.trim()]));
+    const oauth = grants.length || Object.values(set).some(Boolean) ? { set, problems: oauthEnvProblems(grants) } : undefined;
+    // The credential host allowlist (ADR 0122): unbound variables named, refusals listed, names and hosts only.
+    const credentialSet = !!process.env[CREDENTIAL_HOSTS_ENV]?.trim();
+    const envs = [...new Set(syndicates.flatMap((s) => s.credentials?.envs ?? []))].sort();
+    let credentials;
+    if (envs.length || credentialSet) {
+        const problems = [];
+        try {
+            credentialHosts();
+        }
+        catch (err) {
+            problems.push(err instanceof Error ? err.message : `${CREDENTIAL_HOSTS_ENV} is malformed`);
+        }
+        if (!problems.length)
+            for (const s of syndicates)
+                for (const p of s.credentials?.problems ?? [])
+                    problems.push(`${s.file}: ${p}`);
+        const warning = unboundCredentialWarning(envs);
+        credentials = { set: credentialSet, envs, ...(warning ? { warning } : {}), problems };
+    }
+    const serving = servingReport();
+    return {
+        agentsDir,
+        runtime: runtimeReport(),
+        syndicates,
+        unlocks,
+        gateway,
+        endpoints: endpointRows(),
+        counts,
+        ...(oauth ? { oauth } : {}),
+        ...(credentials ? { credentials } : {}),
+        providers: providerPaths(),
+        ...(serving ? { serving } : {}),
+    };
 }
 // ── Rendering ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -419,6 +556,29 @@ const PROBE_ID = {
     moonshot: 'kimi-x',
     ollama: 'ollama/x',
 };
+/**
+ * Why `melchizedek-doctor --check` exits non-zero, one line each; empty when
+ * it passes. A blocked syndicate, a runtime problem, the OAuth setup's and
+ * the credential allowlist's problems, and each grant whose hosts the OAuth
+ * host allowlist refuses (ADR 0114). Names and hosts only, never a value.
+ */
+export function checkProblems(result) {
+    const problems = [];
+    if (result.counts.blocked > 0)
+        problems.push(`${result.counts.blocked} syndicate(s) blocked`);
+    if (result.runtime.problem)
+        problems.push(result.runtime.problem);
+    for (const p of result.oauth?.problems ?? [])
+        problems.push(`oauth: ${p}`);
+    for (const p of result.credentials?.problems ?? [])
+        problems.push(`credentials: ${p}`);
+    for (const s of result.syndicates) {
+        for (const g of s.grants ?? [])
+            for (const p of g.hostProblems ?? [])
+                problems.push(`${s.file}: ${g.agent} · ${g.provider}: ${p}`);
+    }
+    return problems;
+}
 function pad(s, n) {
     return s.length >= n ? s.slice(0, n - 1) + '…' : s.padEnd(n);
 }
@@ -445,11 +605,10 @@ export function renderDoctor(result, opts = {}) {
     // Provider line: what is funded, and how. Each provider is probed with an
     // id of its own prefix, so the line names ITS key (a fallthrough once put
     // xAI's key beside Moonshot).
-    const providerBits = Object.keys(PROVIDERS).map((p) => {
-        const r = describeCapabilities(PROBE_ID[p]);
+    const providerBits = (result.providers ?? providerPaths()).map((r) => {
         const mark = !r.funded ? `${c.red}✗${c.reset}` : r.transport === 'gateway' ? `${c.yellow}◇${c.reset}` : `${c.green}✓${c.reset}`;
-        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : p === 'ollama' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform ?? 'direct'}${c.reset}`;
-        return `${mark} ${PROVIDERS[p].label} ${how}`;
+        const how = !r.funded ? `${c.dim}${r.keyEnv} not set${c.reset}` : r.transport === 'gateway' ? `${c.dim}via gateway:${r.gateway}${c.reset}` : r.platform === 'local' ? `${c.dim}local${c.reset}` : `${c.dim}${r.platform}${c.reset}`;
+        return `${mark} ${r.label} ${how}`;
     });
     lines.push('providers   ' + providerBits.join('   '));
     for (const e of result.endpoints ?? []) {
@@ -464,6 +623,33 @@ export function renderDoctor(result, opts = {}) {
             ? `gateway     ${c.red}✗${c.reset} ${result.gateway.problem}`
             : `gateway     ${c.yellow}◇${c.reset} ${result.gateway.label} fills in for any provider whose direct key is absent ${c.dim}(native search is lost on that path)${c.reset}`);
     }
+    if (result.serving) {
+        // Names only: the A2A identity mode, who pays, and what the server would refuse.
+        const sv = result.serving;
+        const mark = sv.problems.length ? `${c.red}✗${c.reset}` : `${c.green}✓${c.reset}`;
+        const set = Object.entries(sv.set).filter(([, on]) => on).map(([name]) => name).join(', ');
+        lines.push(`serving     ${mark} A2A_AUTH=${sv.auth}${sv.authDeclared ? '' : ' (default)'} · A2A_KEY_MODE=${sv.keyMode} ${c.dim}· set: ${set || 'none'}${c.reset}`);
+        for (const p of sv.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
+    if (result.oauth) {
+        // Names only: which variables are set, never their values (ADR 0114).
+        const set = Object.entries(result.oauth.set).map(([name, on]) => `${name} ${on ? 'set' : 'unset'}`).join(' · ');
+        const mark = result.oauth.problems.length ? `${c.red}✗${c.reset}` : `${c.green}✓${c.reset}`;
+        lines.push(`oauth       ${mark} ${c.dim}${set}${c.reset}`);
+        for (const p of result.oauth.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
+    if (result.credentials) {
+        // Names only: which variables are sent, never their values (ADR 0122).
+        const cr = result.credentials;
+        const mark = cr.problems.length ? `${c.red}✗${c.reset}` : cr.warning ? `${c.yellow}⚠${c.reset}` : `${c.green}✓${c.reset}`;
+        lines.push(`credentials ${mark} ${c.dim}${CREDENTIAL_HOSTS_ENV} ${cr.set ? 'set' : 'unset'}${cr.envs.length ? ` · sent: ${cr.envs.join(', ')}` : ''}${c.reset}`);
+        if (cr.warning)
+            lines.push(`            ${c.yellow}⚠ ${cr.warning}${c.reset}`);
+        for (const p of cr.problems)
+            lines.push(`            ${c.red}✗ ${p}${c.reset}`);
+    }
     lines.push('');
     // The table: one line per syndicate (name, verdict, run command), then
     // one indented line per agent.
@@ -490,6 +676,16 @@ export function renderDoctor(result, opts = {}) {
         if (s.memory?.issue) {
             lines.push(`  ${c.yellow}⚠ memory: ${s.memory.issue}${c.reset}`);
         }
+        for (const g of s.grants ?? []) {
+            const scopes = g.scopes.length ? ` ${c.dim}[${g.scopes.join(' ')}]${c.reset}` : '';
+            const what = g.grant === 'authorization_code'
+                ? `needs a grant: each user connects ${g.provider} (consent) before ${g.tools} works for them`
+                : `needs a grant: the server's own ${g.provider} token (client_credentials) for ${g.tools}`;
+            const missing = g.missingEnv.length ? ` ${c.red}✗ ${g.missingEnv.join(', ')} not set${c.reset}` : '';
+            lines.push(`  ${c.cyan}⚿ ${g.agent}${c.reset} ${what}${scopes}${missing}`);
+            for (const p of g.hostProblems ?? [])
+                lines.push(`    ${c.red}✗ ${p}${c.reset}`);
+        }
         if (s.declaredTier && s.declaredTier !== s.tier) {
             lines.push(`  ${c.yellow}⚠ header says "tier: ${s.declaredTier}" but the models say ${s.tier}${c.reset}`);
         }

package/dist/lib/loadSyndicate.d.ts

@@ -2,6 +2,7 @@ import type { DispatchConfig } from './dispatch.ts';
 export type { DispatchConfig } from './dispatch.ts';
 import type { SkillsConfig } from './tools/skillToolset.ts';
 import type { OpenApiConfig } from './tools/openapiTools.ts';
+import type { McpAuthConfig } from './tools/oauthTools.ts';
 import type { ContextConfig, ExampleConfig } from './compile.ts';
 export type { OpenApiConfig } from './tools/openapiTools.ts';
 export type { SkillsConfig } from './tools/skillToolset.ts';
@@ -91,7 +92,9 @@ export interface AgentYamlConfig {
     outputKey?: string;
     /**
      * Model generation config (temperature, topP, safety, thinking, etc.)
-     * Maps to LlmAgentConfig.generateContentConfig.
+     * Maps to LlmAgentConfig.generateContentConfig. In YAML a v1 spelling,
+     * deprecated (ADR 0115): write `sampling`, `output` and `reasoning`. It
+     * stays the engine form the loader hands downstream.
      */
     generateContentConfig?: GenerateContentConfig;
     /**
@@ -102,12 +105,54 @@ export interface AgentYamlConfig {
     reasoning?: ReasoningSetting;
     /**
      * Output schema for structured JSON responses.
-     * Maps to LlmAgentConfig.outputSchema.
+     * Maps to LlmAgentConfig.outputSchema. In YAML a v1 spelling, deprecated
+     * (ADR 0115): write `output.schema`. It stays the engine form.
      */
     outputSchema?: Record<string, unknown>;
+    /**
+     * Sampling, provider-neutral (v2): replaces generateContentConfig's
+     * temperature, topP, maxOutputTokens and stopSequences. The loader folds it
+     * into generateContentConfig (lib/agentDialect.ts toEngineAgent), so a
+     * loaded config never carries it. Cannot be combined with the v1 key it replaces.
+     */
+    sampling?: {
+        temperature?: number;
+        top_p?: number;
+        max_output_tokens?: number;
+        stop?: string[];
+    };
+    /**
+     * Structured output (v2): `schema` replaces outputSchema, `mime` replaces
+     * generateContentConfig.responseMimeType. Folded into those by the loader.
+     */
+    output?: {
+        schema?: Record<string, unknown>;
+        mime?: 'application/json' | 'text/plain';
+    };
+    /**
+     * Which tools the model may call (v2, ADR 0117): `auto`, `none`,
+     * `required`, or `{ name }` for one tool. Replaces
+     * generateContentConfig.toolConfig.functionCallingConfig; folded into it
+     * by the loader (lib/agentDialect.ts toEngineAgent).
+     */
+    tool_choice?: 'auto' | 'none' | 'required' | {
+        name: string;
+    };
+    /**
+     * Per-provider instruction (v2), keyed by provider id (lib/models/providerMap.ts):
+     * `instruction` replaces the agent's instruction, `instruction_append` is
+     * appended after a blank line, for the provider of the model the agent runs
+     * on. Applied at compile time, before the skills index; not for fallback_model.
+     */
+    model_overrides?: Partial<Record<'gemini' | 'anthropic' | 'openai' | 'xai' | 'moonshot' | 'ollama', {
+        instruction?: string;
+        instruction_append?: string;
+    }>>;
     mcp_server_url?: string;
     /** The MCP server's tools this agent may use; the rest are not exposed. */
     mcp_tools?: string[];
+    /** The OAuth grant the MCP server takes (ADR 0112): each user's, or the server's own. */
+    mcp_auth?: McpAuthConfig;
     /** Answers when `model` fails provider-side, or its provider's circuit is open (ADR 0044). */
     fallback_model?: string;
     /**
@@ -216,6 +261,8 @@ export interface SyndicateYamlConfig {
     memory_retention_days?: number;
     /** Optional hard limit on the turn's model calls, subagents included (LLM -> Tool cycles). */
     max_steps?: number;
+    /** Delegated calls from one model step that run at once (ADR 0116). Default 4. */
+    max_concurrency?: number;
     /**
      * The nested `yaml_reference:` syndicates this one reaches, raw, keyed by
      * reference: written by the registry publisher (`bundleReferences`) so a
@@ -251,6 +298,11 @@ export interface LoadSyndicateOptions {
      * with the public example of the same name (ADR 0018).
      */
     shippedFallback?: boolean;
+    /**
+     * Where load-time warnings go (the deprecated v1 spellings of ADR 0115).
+     * Default console.warn. A warning names the file and key paths, never a value.
+     */
+    onWarning?: (message: string) => void;
 }
 /**
  * Parse CLI variable bindings into a VariableMap.

package/dist/lib/loadSyndicate.js

@@ -4,6 +4,7 @@ import * as path from 'path';
 import { createClient } from '@supabase/supabase-js';
 import { hasSupabaseCredentials } from './persistence/supabaseProvider.js';
 import { validateSyndicateConfig } from './syndicateSchema.js';
+import { v1SpellingsOf } from './agentDialect.js';
 // ── Variable Injection (private) ──────────────────────────
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
@@ -87,6 +88,7 @@ function resolveAndValidate(raw, label, options) {
         ...bindings,
     };
     const interpolated = isPlainObject(raw) ? interpolateDeep(raw, merged) : raw;
+    warnV1Spellings(interpolated, label, options.onWarning);
     const unresolved = findUnresolvedTokens(interpolated);
     if (unresolved.length > 0) {
         console.warn(`⚠ Unresolved template variables: ${unresolved.map((t) => `{{${t}}}`).join(', ')}`);
@@ -99,6 +101,24 @@ function resolveAndValidate(raw, label, options) {
     }
     return config;
 }
+/** Labels already warned about, so a server loading one file per request warns once per process. */
+const warnedV1 = new Set();
+/**
+ * One line per label when a file still uses the v1 spellings ADR 0115
+ * deprecates. Key paths and the label only: never a value (a prompt, a key).
+ */
+function warnV1Spellings(raw, label, onWarning = console.warn) {
+    if (warnedV1.has(label))
+        return;
+    const paths = v1SpellingsOf(raw);
+    if (!paths.length)
+        return;
+    warnedV1.add(label);
+    const fix = label.startsWith('registry:') || label.startsWith('bundled:')
+        ? 'Run npx melchizedek-codemod on the file it was published from, and republish'
+        : `Run npx melchizedek-codemod ${label} to rewrite them`;
+    onWarning(`⚠ ${label}: generateContentConfig and outputSchema are v1 spellings, deprecated (ADR 0115): ${paths.join(', ')}. ${fix}.`);
+}
 function applyOverrides(config, overrides) {
     return { ...config, ...overrides };
 }
@@ -227,9 +247,9 @@ export function collectGuards(config, loadNested = nestedLoader(config), seen =
     return [...names];
 }
 export function loadSyndicate(filename, options = {}) {
-    const { bindings = {}, overrides } = options;
+    const { bindings = {}, overrides, onWarning } = options;
     const { raw, label, filePath } = readSyndicateFile(filename, options);
-    return anchorSpecPaths(resolveAndValidate(raw, label, { bindings, overrides }), path.dirname(filePath));
+    return anchorSpecPaths(resolveAndValidate(raw, label, { bindings, overrides, onWarning }), path.dirname(filePath));
 }
 /**
  * An `openapi:` spec path is written relative to the syndicate file, so a

package/dist/lib/memory/namespace.d.ts

@@ -2,11 +2,12 @@
  * lib/memory/namespace.ts — memory always resolves to the ROOT syndicate's
  * namespace (ADR 0020 item 3).
  *
- * WHY: a DELEGATE subagent runs on its own session row under
- * `appName = <the subagent's name>`, and its memory tools search with the
- * session's app name. Facts are written under the root syndicate's
- * namespace, so a `load_memory` declared on a subagent would search
- * `<SubAgent>/<user>`, find nothing, and say so without error. Wrapping the
+ * WHY: a DELEGATE subagent runs on its own session row, filed under its
+ * agent path (`appName = <app>/<caller>/<subagent>`, ADR 0111; the
+ * subagent's name alone in a conversation stored before), and its memory
+ * tools search with the session's app name. Facts are written under the
+ * root syndicate's namespace, so a `load_memory` declared on a subagent
+ * would search the child's own key, find nothing, and say so without error. Wrapping the
  * service the runtime receives pins every search and ingestion to one
  * namespace, whatever app name the caller carries.
  *

package/dist/lib/memory/namespace.js

@@ -2,11 +2,12 @@
  * lib/memory/namespace.ts — memory always resolves to the ROOT syndicate's
  * namespace (ADR 0020 item 3).
  *
- * WHY: a DELEGATE subagent runs on its own session row under
- * `appName = <the subagent's name>`, and its memory tools search with the
- * session's app name. Facts are written under the root syndicate's
- * namespace, so a `load_memory` declared on a subagent would search
- * `<SubAgent>/<user>`, find nothing, and say so without error. Wrapping the
+ * WHY: a DELEGATE subagent runs on its own session row, filed under its
+ * agent path (`appName = <app>/<caller>/<subagent>`, ADR 0111; the
+ * subagent's name alone in a conversation stored before), and its memory
+ * tools search with the session's app name. Facts are written under the
+ * root syndicate's namespace, so a `load_memory` declared on a subagent
+ * would search the child's own key, find nothing, and say so without error. Wrapping the
  * service the runtime receives pins every search and ingestion to one
  * namespace, whatever app name the caller carries.
  *

package/dist/lib/memory/providers.js

@@ -30,12 +30,12 @@
  */
 import { endpointFromEnv } from '../models/endpoints.js';
 import { GoogleGenAI } from '@google/genai';
-import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { SpanStatusCode } from '@opentelemetry/api';
 import { llmRequestToModelRequest, modelResponseToLlmResponse } from '../models/genaiMapping.js';
 import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL, MEMORY_EXTRACTION_MODEL } from '../config.js';
 import { providerForModel } from '../models/providerMap.js';
 import { resolveModel } from '../models/registry.js';
-import { initializeTracing, traceLlmGeneration } from '../observability/tracer.js';
+import { startEngineSpan, traceLlmGeneration } from '../observability/tracer.js';
 import { trimTrailingSlashes } from '../models/urls.js';
 /**
  * Extraction on any model id. The key passed here reaches only a model of
@@ -86,8 +86,7 @@ export function modelExtractor(opts = {}) {
  * a reasoning step.
  */
 async function traced(provider, model, count, fn) {
-    initializeTracing();
-    const span = trace.getTracer('melchizedek-tracer').startSpan('llm.request');
+    const span = startEngineSpan('melchizedek-tracer', 'llm.request');
     span.setAttribute('llm.provider', provider);
     span.setAttribute('llm.model', model);
     span.setAttribute('llm.purpose', 'memory_embedding');

package/dist/lib/models/capabilities.d.ts

@@ -55,7 +55,7 @@ export declare function describeCapabilities(model: string, tools?: readonly str
  * a funded direct path with no dropped tool is the quiet default.
  */
 export declare function capabilitySummary(agentName: string, r: CapabilityReport): string | undefined;
-export declare const CAPABILITIES: readonly ['delegation', 'memory_tools', 'structured_output', 'thinking_with_tools', 'streaming', 'vision', 'native_search'];
+export declare const CAPABILITIES: readonly ['delegation', 'memory_tools', 'structured_output', 'structured_output_with_tools', 'thinking_with_tools', 'streaming', 'vision', 'native_search'];
 export type Capability = (typeof CAPABILITIES)[number];
 export declare const CAPABILITY_LABELS: Record<Capability, string>;
 export type Support = 'supported' | 'degraded' | 'unsupported';
@@ -74,6 +74,30 @@ export declare function capabilityOf(model: string, capability: Capability, opts
 }): CapabilityCell & {
     row: MatrixRow;
 };
+/**
+ * The reasoning levels above `high` (ADR 0117), per row: what `reasoning:
+ * xhigh` and `reasoning: max` reach the provider as. A level a model lacks
+ * goes as its highest setting, and the request's `llm.request` span carries
+ * `llm.reasoning.weakened` with the level asked for. Asserted against the
+ * request bodies in tests/toolChoiceEffort.test.ts; the direct adapters read
+ * lib/models/reasoning.ts effortCeiling.
+ */
+export declare const REASONING_ABOVE_HIGH: Readonly<Record<MatrixRow, string>>;
+/**
+ * Whether an outputSchema goes in the same request as the agent's tools, as
+ * the provider's own structured-output field, on the path `model` takes
+ * (ADR 0109). True only where the `structured_output_with_tools` cell is
+ * supported and the model's generation takes it: Claude from Opus 4.8,
+ * Sonnet 5 and Haiku 5.5 on (`output_config.format`), every OpenAI id
+ * (`text.format`), Gemini 2 and later on Vertex AI (`responseJsonSchema`).
+ * Elsewhere the native loop declares set_model_response beside the tools
+ * (lib/runtime/native/request.ts), which works on every path. A path that
+ * cannot be planned (a malformed gateway setting) answers false, the form
+ * that works everywhere.
+ */
+export declare function outputSchemaBesideTools(model: string, opts?: {
+    callerKey?: boolean;
+}): boolean;
 /** What one agent's YAML asks of its model. */
 export interface AgentNeedsInput {
     tools?: readonly string[];