melchizedek-agents 1.0.2 → 1.1.0

package/dist/lib/dispatch.d.ts

@@ -26,11 +26,16 @@
  * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
  * mode the choice is only ever implicit in a tool call.
  *
- * ── Why the router MUST be tool-less ──────────────────────────────────────
- * The classifier holds an `outputSchema`, and an agent holding one answers
- * with that JSON and nothing else (see config/agents/examples/critic.yaml; ADK
- * refused the combination outright). So the classifier is a leaf with no
- * subagent tools, and dispatch happens in code where it belongs.
+ * ── Why the router is tool-less ────────────────────────────────────────────
+ * The classifier holds an `outputSchema`, and an agent holding one ends its
+ * turn on that JSON. Its JSON names a route for code to run, so it holds no
+ * subagent tools: dispatch happens in code where it belongs. This is a choice
+ * of method, not a constraint of the engine: an orchestrator may hold an
+ * `outputSchema` beside its subagent tools, delegate, and answer in that
+ * schema itself (ADR 0109; ADK refused the combination, the engine does not).
+ * Plan-dispatch is for a turn whose answer IS the specialist's; a schema on a
+ * delegating orchestrator is for a turn whose answer is the orchestrator's
+ * own structured judgment of what its team returned.
  *
  * ── Fail-static ───────────────────────────────────────────────────────────
  * Every failure mode here resolves to `default_route` and answers the user.

package/dist/lib/dispatch.js

@@ -26,11 +26,16 @@
  * be logged, traced, and streamed to a waiting user as progress. In DELEGATE
  * mode the choice is only ever implicit in a tool call.
  *
- * ── Why the router MUST be tool-less ──────────────────────────────────────
- * The classifier holds an `outputSchema`, and an agent holding one answers
- * with that JSON and nothing else (see config/agents/examples/critic.yaml; ADK
- * refused the combination outright). So the classifier is a leaf with no
- * subagent tools, and dispatch happens in code where it belongs.
+ * ── Why the router is tool-less ────────────────────────────────────────────
+ * The classifier holds an `outputSchema`, and an agent holding one ends its
+ * turn on that JSON. Its JSON names a route for code to run, so it holds no
+ * subagent tools: dispatch happens in code where it belongs. This is a choice
+ * of method, not a constraint of the engine: an orchestrator may hold an
+ * `outputSchema` beside its subagent tools, delegate, and answer in that
+ * schema itself (ADR 0109; ADK refused the combination, the engine does not).
+ * Plan-dispatch is for a turn whose answer IS the specialist's; a schema on a
+ * delegating orchestrator is for a turn whose answer is the orchestrator's
+ * own structured judgment of what its team returned.
  *
  * ── Fail-static ───────────────────────────────────────────────────────────
  * Every failure mode here resolves to `default_route` and answers the user.

package/dist/lib/doctor.d.ts

@@ -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:
@@ -46,6 +47,34 @@ export interface DoctorRow {
     gaps: CapabilityGap[];
 }
 export type VerdictState = 'ready' | 'ready-local' | 'via-gateway' | 'blocked';
+/**
+ * A tool that sends an OAuth token (ADR 0112): which agent holds it, the
+ * provider, and the grant. An authorization_code grant needs each user's
+ * consent before the tool works for them; a client_credentials grant needs
+ * its variables set. Variable names only, never a value.
+ */
+export interface DoctorGrant {
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    provider: string;
+    grant: 'authorization_code' | 'client_credentials';
+    scopes: string[];
+    /** The variables the grant reads that are not set here. */
+    missingEnv: string[];
+    /** Why the operator's OAuth host allowlist refuses this grant here (ADR 0114); empty when it is permitted. */
+    hostProblems: string[];
+}
+/**
+ * The server's OAuth setup under this environment (ADR 0114): which of its
+ * variables are set, and what is wrong, names only. Present when a
+ * syndicate declares a grant or any of the variables is set.
+ */
+export interface DoctorOAuth {
+    /** Which of MELCHIZEDEK_CREDENTIAL_KEY, OAUTH_REDIRECT_URI and MELCHIZEDEK_OAUTH_HOSTS are set. */
+    set: Record<string, boolean>;
+    problems: string[];
+}
 export interface DoctorSyndicate {
     /** Path relative to the agents dir, e.g. "examples/council.yaml". */
     file: string;
@@ -75,6 +104,8 @@ export interface DoctorSyndicate {
         declared: boolean;
         issue?: string;
     };
+    /** The tools that need an OAuth grant (ADR 0112), when any do. */
+    grants?: DoctorGrant[];
 }
 export interface Unlock {
     env: string;
@@ -108,6 +139,8 @@ export interface DoctorResult {
     /** Every provider not on its default endpoint: a cloud platform or a proxy (ADR 0023). */
     endpoints: DoctorEndpoint[];
     counts: Record<VerdictState, number>;
+    /** The OAuth setup, when any syndicate declares a grant or its variables are set. */
+    oauth?: DoctorOAuth;
 }
 export interface DoctorEndpoint {
     provider: ProviderId;

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,10 @@ 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';
 function resolvable(module) {
     try {
         createRequire(import.meta.url).resolve(module);
@@ -160,6 +165,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 +196,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 +237,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 +303,8 @@ 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);
         const memory = config.memory_system === 'long-term'
             ? {
                 namespace: config.memory_namespace ?? LEGACY_MEMORY_APP_NAME,
@@ -302,6 +323,7 @@ export function diagnoseSyndicate(file, agentsDir, scripts) {
             ...(runCommand ? { runCommand } : {}),
             ...(nestedErrors.length ? { error: nestedErrors.join('\n') } : {}),
             ...(memory ? { memory } : {}),
+            ...(grants.length ? { grants } : {}),
         };
     }
     catch (err) {
@@ -398,7 +420,11 @@ 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;
+    return { agentsDir, runtime: runtimeReport(), syndicates, unlocks, gateway, endpoints: endpointRows(), counts, ...(oauth ? { oauth } : {}) };
 }
 // ── Rendering ────────────────────────────────────────────────────────────────
 const ANSI = {
@@ -464,6 +490,14 @@ 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.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}`);
+    }
     lines.push('');
     // The table: one line per syndicate (name, verdict, run command), then
     // one indented line per agent.
@@ -490,6 +524,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,45 @@ 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';
+    };
+    /**
+     * 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 +252,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 +289,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,21 @@ export declare function capabilityOf(model: string, capability: Capability, opts
 }): CapabilityCell & {
     row: MatrixRow;
 };
+/**
+ * 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[];

package/dist/lib/models/capabilities.js

@@ -20,7 +20,7 @@
 import { PROVIDERS } from './providerMap.js';
 import { planTransport } from './gateway.js';
 import { nativeSearchOn, PLATFORMS_FOR, platformFromEnv } from './endpoints.js';
-import { claudeUrlImagesOn } from './claudeModels.js';
+import { claudeGeneration, claudeUrlImagesOn } from './claudeModels.js';
 /** The platform a direct path uses (ADR 0023); a misconfigured one reads as direct here, the doctor reports it. */
 function directPlatform(provider) {
     try {
@@ -117,6 +117,7 @@ export const CAPABILITIES = [
     'delegation',
     'memory_tools',
     'structured_output',
+    'structured_output_with_tools',
     'thinking_with_tools',
     'streaming',
     'vision',
@@ -126,6 +127,7 @@ export const CAPABILITY_LABELS = {
     delegation: 'delegation (subagents as tools)',
     memory_tools: 'memory tools (load_memory)',
     structured_output: 'structured output (outputSchema)',
+    structured_output_with_tools: 'structured output beside tools (an outputSchema on an agent that calls tools or delegates)',
     thinking_with_tools: 'thinking with tool use',
     streaming: 'token streaming',
     vision: 'image input',
@@ -138,12 +140,14 @@ const nativeSearch = (row) => SERVER_SIDE_TOOLS.web_search.includes(row)
     ? ok()
     : unsupported('no native search on this path; the web_search sentinel is dropped (use web_extract)');
 const responsesReasoningNote = (ids) => `encrypted reasoning items are replayed verbatim within the turn's tool loop, with store: false (ADR 0050); ${ids}`;
+const setModelResponseNote = (why) => `the schema travels as a set_model_response tool beside the agent's tools, so the model is asked, not held, to answer in it: the turn ends when it calls the tool, and its arguments are the answer (${why}; ADR 0109)`;
 const CHAT_THINKING_NOTE = "reasoning: is the lever, sent as reasoning_effort in the model's word, a thinking budget as the level that covers it (ADR 0047); the reasoning is not carried between tool steps, so the model re-reasons each step";
 export const CAPABILITY_MATRIX = {
     gemini: {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: degraded(setModelResponseNote('on the Gemini API; Gemini 2 and later on Vertex AI take responseJsonSchema beside the tools in one request')),
         thinking_with_tools: ok(),
         streaming: ok(),
         vision: ok(),
@@ -153,6 +157,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'output_config.format (json_schema) from Opus 4.8, Sonnet 5 and Haiku 5.5 on; a forced tool call on Claude 4.6 and earlier and Opus 4.7, offered under tool_choice auto when thinking is on (ADR 0049)'),
+        structured_output_with_tools: ok('test', 'output_config.format beside the tools in one request from Opus 4.8, Sonnet 5 and Haiku 5.5 on; Claude 4.6 and earlier and Opus 4.7 get a set_model_response tool beside them (ADR 0109)'),
         thinking_with_tools: ok('test', "a thinking budget on Claude 4.6 and earlier, adaptive thinking with output_config.effort after (ADR 0049); signed thinking blocks are replayed verbatim within the turn's tool loop (ADR 0046), and where the model binds them to the conversation (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5) under drop_block, so a block whose history changed is dropped rather than rejected; with a budget, a step answering another model's tool call runs without thinking"),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -162,6 +167,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: ok('test', 'text.format (strict json_schema) beside the tools in one request (ADR 0109)'),
         thinking_with_tools: ok('test', responsesReasoningNote('reasoning ids only (o-series, gpt-5*)')),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -171,6 +177,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: degraded(setModelResponseNote('the schema is not yet sent beside tools on xAI')),
         thinking_with_tools: ok('test', responsesReasoningNote('grok-4.5, grok-4.6 and grok-4.7; other grok ids re-reason each step')),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -180,6 +187,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'strict json_schema; kimi-k2.6 is documented as unstable on complex schemas ($ref, oneOf)'),
+        structured_output_with_tools: degraded(setModelResponseNote('the schema is not yet sent beside tools on Moonshot')),
         thinking_with_tools: ok('test', "reasoning_content is sent back on the turn's tool-loop assistant messages for the same model (ADR 0046) on kimi-k3, kimi-k2.6 and kimi-k2.7-code; earlier turns' reasoning is not, which K3 and K2.7 Code also ask for; effort travels as reasoning_effort (K3) or a thinking switch (K2.x)"),
         streaming: ok(),
         vision: ok('test', 'user-turn images only, sent as base64 (Moonshot takes no public image URLs)'),
@@ -189,6 +197,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'json_schema, enforced by grammar-constrained decoding from Ollama 0.5.0 (an older server ignores it); not enforced on Ollama Cloud (ADR 0096)'),
+        structured_output_with_tools: degraded(setModelResponseNote('grammar-constrained decoding to the schema would hold back the tool calls')),
         thinking_with_tools: degraded(CHAT_THINKING_NOTE),
         streaming: ok(),
         vision: ok('test', 'needs a vision model, e.g. ollama/qwen3-vl:8b'),
@@ -198,6 +207,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'strict json_schema; upstream support varies by model'),
+        structured_output_with_tools: degraded(setModelResponseNote('upstream support for a schema beside tools varies by model')),
         thinking_with_tools: degraded(CHAT_THINKING_NOTE),
         streaming: ok(),
         vision: ok('test', 'upstream model must accept images'),
@@ -215,6 +225,45 @@ export function capabilityOf(model, capability, opts = {}) {
     }
     return { row, ...CAPABILITY_MATRIX[row][capability] };
 }
+/**
+ * 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 function outputSchemaBesideTools(model, opts = {}) {
+    let cell;
+    try {
+        cell = capabilityOf(model, 'structured_output_with_tools', opts);
+    }
+    catch {
+        return false;
+    }
+    if (cell.support !== 'supported')
+        return false;
+    switch (cell.row) {
+        case 'anthropic':
+            return claudeGeneration(model).structuredOutput === 'output_format';
+        case 'gemini':
+            return geminiMajorVersion(model) >= 2;
+        default:
+            return true;
+    }
+}
+/** A Gemini id's major version (a Vertex AI resource name's last segment), or 0 when it is not a `gemini-<n>` id. Read without a pattern. */
+function geminiMajorVersion(model) {
+    const name = model.slice(model.lastIndexOf('/') + 1);
+    if (!name.startsWith('gemini-'))
+        return 0;
+    const major = Number.parseInt(name.slice('gemini-'.length), 10);
+    return Number.isFinite(major) ? major : 0;
+}
 export function requiredCapabilities(agent) {
     const tools = agent.tools ?? [];
     const needs = new Set();
@@ -224,6 +273,8 @@ export function requiredCapabilities(agent) {
         needs.add('memory_tools');
     if (agent.outputSchema)
         needs.add('structured_output');
+    if (agent.outputSchema && (tools.length > 0 || agent.delegates))
+        needs.add('structured_output_with_tools');
     const thinking = agent.generateContentConfig?.thinkingConfig;
     const thinks = agent.reasoning !== undefined
         ? agent.reasoning !== 'none' && !(typeof agent.reasoning === 'object' && agent.reasoning.budget_tokens === 0)
@@ -256,6 +307,9 @@ export function capabilityGaps(model, agent, opts = {}) {
 export function platformCell(provider, platform, capability) {
     if (platform === 'direct')
         return undefined;
+    if (capability === 'structured_output_with_tools' && provider === 'gemini' && platform === 'vertex') {
+        return ok('test', 'responseJsonSchema beside the tools in one request on Gemini 2 and later; an earlier id gets set_model_response (ADR 0109)');
+    }
     if (capability === 'vision' && provider === 'anthropic' && !claudeUrlImagesOn(platform)) {
         return degraded(`user-turn images inline (base64) only; an image given by URL is dropped, since ${PLATFORM_LABEL[platform]} takes no URL image source`);
     }

package/dist/lib/observability/tracer.d.ts

@@ -1,4 +1,4 @@
-import type { SpanContext } from '@opentelemetry/api';
+import type { Span, SpanContext, SpanOptions } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
@@ -43,6 +43,13 @@ export declare function takeTraceStats(traceId: string): TraceStats | undefined;
 /** Name of the agent of the nearest enclosing agent span (ADK's `invoke_agent`, the loop's `agent.invoke`), or null. */
 export declare function agentForSpan(spanId: string | undefined): string | null;
 export declare function initializeTracing(): void;
+/**
+ * Starts a span on the named tracer, starting the tracer first; in a turn
+ * that opted out of tracing, a non-recording span and no tracer. Every span
+ * the engine opens inside a turn goes through here or checks turnUntraced
+ * itself.
+ */
+export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions): Span;
 export interface TraceMetadata {
     syndicateName: string;
     bindings?: Record<string, any>;