melchizedek-agents 0.17.0 → 0.18.0

package/dist/lib/a2a/app.js

@@ -36,8 +36,13 @@ import { providerForModel, resolveModel } from '../models/registry.js';
 import { createSupabaseServices, hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
 import { inProcessTurnLock } from './turnLock.js';
 import { compareSchema, schemaBehindMessage, shippedSchemaVersion } from '../storage/schemaVersion.js';
+import { scopeHashOf } from '../observability/audit.js';
+import { validTraceparent } from '../observability/tracer.js';
+/** One end user's concurrent tasks, unless maxConcurrentPerScope says otherwise (ADR 0039). */
+export const DEFAULT_MAX_CONCURRENT_PER_SCOPE = 4;
 import { eraseScope } from '../memory/erase.js';
 import { namespacedMemoryService } from '../memory/namespace.js';
+import { memoryCrossesProviders, memoryDestinations } from '../memory/providers.js';
 import { A2A_APP_NAME, SyndicateExecutor, TaskLimiter, deriveUserId, requestContextStorage, } from './executor.js';
 import { HEADER_VALUE_PATTERN, SCOPE_KEY_PATTERN } from './identity.js';
 import { createMetrics } from '../observability/metrics.js';
@@ -286,6 +291,22 @@ export async function createA2AApp(options) {
      * and only `long-term` syndicates get the memory service.
      */
     const internalSessions = new InMemorySessionService();
+    // Long-term memory sends transcripts to its extraction and embedding
+    // providers; say so once per syndicate when they are not the agents' own.
+    const memoryFlowWarned = new Set();
+    const warnMemoryFlow = (cfg) => {
+        if (memoryFlowWarned.has(cfg.syndicate_name))
+            return;
+        memoryFlowWarned.add(cfg.syndicate_name);
+        const dest = memoryDestinations(process.env, { extractor: options.memory?.extractor, embedder: options.memory?.embedder });
+        const models = [cfg.orchestrator?.model, ...(cfg.subagents ?? []).map((s) => s.model)];
+        const crossed = memoryCrossesProviders(models, dest);
+        if (crossed.length) {
+            warn(`'${cfg.syndicate_name}' keeps long-term memory, so its transcripts also go to ${crossed.join(' and ')} `
+                + `(extraction: ${dest.extraction}, embeddings: ${dest.embeddings}), which its agents do not use. `
+                + 'Set MEMORY_EXTRACTION_MODEL and MEMORY_EMBEDDING_PROVIDER to keep memory on an approved provider.');
+        }
+    };
     const servicesFor = (cfg) => {
         const mode = cfg.memory_system;
         const sessionService = mode === 'internal-only' || !durableSessions ? internalSessions : durableSessions;
@@ -293,6 +314,8 @@ export async function createA2AApp(options) {
         // turn reaches — including AgentTool children, which run under their own
         // ADK app name — recalls and stores in the root syndicate's memory.
         const memory = mode === 'long-term' && memoryService ? namespacedMemoryService(memoryService, memoryAppName(cfg)) : undefined;
+        if (memory)
+            warnMemoryFlow(cfg);
         if (mode === 'long-term' && !memoryService) {
             warn(`'${cfg.syndicate_name}' requests long-term memory but Supabase is not configured — memory disabled.`);
         }
@@ -301,7 +324,11 @@ export async function createA2AApp(options) {
         }
         return { sessionService, memoryService: memory, durable: sessionService !== internalSessions };
     };
-    const limiter = new TaskLimiter(options.maxConcurrentTasks ?? 0);
+    const audit = options.audit ?? options.storage?.audit;
+    const limiter = new TaskLimiter(options.maxConcurrentTasks ?? 0, {
+        perScope: options.maxConcurrentPerScope ?? DEFAULT_MAX_CONCURRENT_PER_SCOPE,
+        perCaller: options.maxConcurrentPerCaller ?? 0,
+    });
     const metrics = options.metricsToken ? createMetrics() : undefined;
     const onTaskEnd = (record) => {
         metrics?.observeTask(record);
@@ -363,6 +390,7 @@ export async function createA2AApp(options) {
             agentId,
             policy: options.policy,
             onTaskEnd,
+            onAudit: audit,
             log,
             warn,
         });
@@ -415,11 +443,60 @@ export async function createA2AApp(options) {
             res.type('text/plain; version=0.0.4').send(metrics.render(limiter.inFlight));
         });
     }
-    app.get('/readyz', (_req, res) => {
-        if (limiter.isDraining) {
+    // Readiness: not while stopping, and not while durable storage is
+    // unreachable (a turn there would fail). The reason is logged once per
+    // change of state, never per probe, and the answer names no host.
+    let unready = false;
+    let storageDown = false;
+    // /readyz is unauthenticated, so the database is asked at most once per
+    // READY_CACHE_MS however often it is probed; concurrent probes share the
+    // one check in flight.
+    const READY_CACHE_MS = 2_000;
+    let lastCheck;
+    let checking;
+    const checkStorage = async () => {
+        let timer;
+        try {
+            await Promise.race([
+                readSchemaVersion(),
+                new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('no answer within 2 s')), 2_000); }),
+            ]);
+            if (storageDown)
+                log('readyz: the database answers again.');
+            storageDown = false;
+            return true;
+        }
+        catch (err) {
+            if (!storageDown)
+                warn(`readyz: the database is unreachable (${err instanceof Error ? err.message : String(err)}); reporting not ready.`);
+            storageDown = true;
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const storageReachable = async () => {
+        if (!readSchemaVersion)
+            return true;
+        if (lastCheck && Date.now() - lastCheck.at < READY_CACHE_MS)
+            return lastCheck.ok;
+        checking ??= checkStorage().then((ok) => {
+            lastCheck = { at: Date.now(), ok };
+            checking = undefined;
+            return ok;
+        });
+        return checking;
+    };
+    app.get('/readyz', async (_req, res) => {
+        if (unready || limiter.isDraining) {
             res.status(503).json({ status: 'draining' });
             return;
         }
+        if (!(await storageReachable())) {
+            res.status(503).json({ status: 'unavailable', reason: 'storage' });
+            return;
+        }
         res.json({ status: 'ready', sessions: sessionBackend, inFlight: limiter.inFlight });
     });
     // ── 2–3. Authentication ───────────────────────────────────────────────────
@@ -437,6 +514,12 @@ export async function createA2AApp(options) {
     }));
     const rejectAuth = (req, res, error) => {
         warn(`401 ${req.method} ${req.path} from ${req.ip}: ${error}`);
+        try {
+            audit?.({ event: 'auth.failure', outcome: 'denied', sourceIp: req.ip, detail: { method: req.method, path: req.path, reason: error } });
+        }
+        catch {
+            /* the refusal stands whatever the sink does */
+        }
         res.status(401).json({ error });
     };
     if (options.serverSecret) {
@@ -544,6 +627,7 @@ export async function createA2AApp(options) {
                 caller: identity.caller,
                 ownsNested: identity.ownsNested ?? false,
                 operator: identity.operator ?? false,
+                sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
             }, () => next());
             return;
         }
@@ -568,7 +652,7 @@ export async function createA2AApp(options) {
             // The caller's key funds its provider, and its hash prefixes the scope
             // so no key holder can reach another's data.
             const scopeKey = deriveUserId({ apiKey, siteUserId });
-            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret }, () => next());
+            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret, sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent) }, () => next());
             return;
         }
         // Server mode: the server's credentials pay; X-API-Key is not used.
@@ -585,6 +669,7 @@ export async function createA2AApp(options) {
             // Everyone holding the secret is one caller; without a secret (loopback) the caller is local.
             caller: options.serverSecret ? 'shared-secret' : 'local',
             operator: !!options.serverSecret,
+            sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
         }, () => next());
     });
     // ── 6. Task rate limit ────────────────────────────────────────────────────
@@ -640,11 +725,13 @@ export async function createA2AApp(options) {
                 includeNested: !!ctx.ownsNested,
             });
             log(`Erasure for scope ${ctx.scopeKey}${all ? ' (all namespaces)' : ''}: ${JSON.stringify(counts)}`);
+            audit?.({ event: 'memory.erase', outcome: 'ok', caller: ctx.caller, scopeHash: scopeHashOf(ctx.scopeKey), sourceIp: ctx.sourceIp, detail: { allNamespaces: all, deleted: counts } });
             res.json({ deleted: counts });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             warn(`Erasure failed: ${msg}`);
+            audit?.({ event: 'memory.erase', outcome: 'failed', caller: ctx.caller, scopeHash: scopeHashOf(ctx.scopeKey), sourceIp: ctx.sourceIp, detail: { allNamespaces: all } });
             res.status(503).json({ error: msg });
         }
     });
@@ -745,6 +832,9 @@ export async function createA2AApp(options) {
         app,
         config,
         sessionBackend,
+        markUnready: () => {
+            unready = true;
+        },
         shutdown: async (graceMs) => {
             const left = await limiter.drain(graceMs);
             for (const t of leaseTimers)

package/dist/lib/a2a/executor.d.ts

@@ -18,6 +18,7 @@ import type { TurnLock } from './turnLock.ts';
 import type { PendingApproval } from '../runtime/approvals.ts';
 import type { MessagePart, SyndicateTurnResult } from '../runtime/syndicateTurn.ts';
 import type { TaskRecord } from '../observability/metrics.ts';
+import type { AuditSink } from '../observability/audit.ts';
 import type { Policy } from './policy.ts';
 /** Per-request caller context, set by the server's identity middleware. */
 export interface A2AContext {
@@ -44,6 +45,10 @@ export interface A2AContext {
      *  server secret), as opposed to an end user (a JWT, a gateway header).
      *  Operator-only adopter routes check it. */
     operator?: boolean;
+    /** The request's source address (behind A2A_TRUST_PROXY), for the audit trail only. */
+    sourceIp?: string;
+    /** The caller's W3C traceparent, when well formed: the turn's root span links to it. */
+    traceparent?: string;
 }
 export interface SurfaceContext {
     name: string;
@@ -103,6 +108,8 @@ export interface ExecutorOptions {
     policy?: Policy;
     /** One record per task, however it ended: the task log and metrics. */
     onTaskEnd?: (record: TaskRecord) => void;
+    /** Receives one `task.end` audit event per task (ADR 0042). */
+    onAudit?: AuditSink;
     /**
      * Stream the answer as the model writes it, as `answer` artifact chunks
      * (see answerStream). Off by default; never for a syndicate with guards.
@@ -115,16 +122,39 @@ export interface ExecutorOptions {
     log: (message: string) => void;
     warn: (message: string) => void;
 }
-/** Concurrency cap and in-flight registry shared by all executors. */
+/** Per-key caps beside the global one: 0 or absent means no cap. */
+export interface TaskLimits {
+    /** Concurrent tasks for one scope (one end user's data). */
+    perScope?: number;
+    /** Concurrent tasks for one authenticated caller (a backend, a token). */
+    perCaller?: number;
+}
+/** Concurrency caps and in-flight registry shared by all executors. */
 export declare class TaskLimiter {
     readonly max: number;
+    readonly perScope: number;
+    readonly perCaller: number;
     private readonly running;
+    /** taskId → the keys it counts against, so release frees exactly those. */
+    private readonly keysOf;
+    private readonly counts;
     private draining;
     private idleWaiters;
-    constructor(max: number);
+    constructor(max: number, limits?: TaskLimits);
+    /**
+     * Why a task for this scope and caller may not start now, or undefined.
+     * Checked before acquire() so the refusal can name the cap that was hit.
+     */
+    refusal(who?: {
+        scopeKey?: string;
+        caller?: string;
+    }): string | undefined;
     get inFlight(): number;
-    /** Reserve a slot. Returns undefined when saturated or shutting down. */
-    acquire(taskId: string): AbortController | undefined;
+    /** Reserve a slot. Returns undefined when any cap is reached or the server is shutting down. */
+    acquire(taskId: string, who?: {
+        scopeKey?: string;
+        caller?: string;
+    }): AbortController | undefined;
     release(taskId: string): void;
     cancel(taskId: string): boolean;
     /** Stop admitting tasks; resolve when all running ones finish or `graceMs` passes,

package/dist/lib/a2a/executor.js

@@ -122,28 +122,64 @@ export function a2aPartsToMessage(rawParts) {
     return { parts };
 }
 const NO_USAGE = { llmCalls: 0, inputTokens: 0, outputTokens: 0, thinkingTokens: 0 };
-/** Concurrency cap and in-flight registry shared by all executors. */
+/** Concurrency caps and in-flight registry shared by all executors. */
 export class TaskLimiter {
     max;
+    perScope;
+    perCaller;
     running = new Map();
+    /** taskId → the keys it counts against, so release frees exactly those. */
+    keysOf = new Map();
+    counts = new Map();
     draining = false;
     idleWaiters = [];
-    constructor(max) {
+    constructor(max, limits = {}) {
         this.max = max > 0 ? max : Infinity;
+        this.perScope = limits.perScope && limits.perScope > 0 ? limits.perScope : Infinity;
+        this.perCaller = limits.perCaller && limits.perCaller > 0 ? limits.perCaller : Infinity;
+    }
+    /**
+     * Why a task for this scope and caller may not start now, or undefined.
+     * Checked before acquire() so the refusal can name the cap that was hit.
+     */
+    refusal(who = {}) {
+        if (this.draining)
+            return 'The server is shutting down; retry shortly.';
+        if (this.running.size >= this.max)
+            return `The server is at its limit of ${this.max} concurrent tasks; retry shortly.`;
+        if (who.scopeKey && (this.counts.get(`s:${who.scopeKey}`) ?? 0) >= this.perScope) {
+            return `This user already has ${this.perScope} tasks running, the most allowed at once; retry when one finishes.`;
+        }
+        if (who.caller && (this.counts.get(`c:${who.caller}`) ?? 0) >= this.perCaller) {
+            return `This caller already has ${this.perCaller} tasks running, the most allowed at once; retry when one finishes.`;
+        }
+        return undefined;
     }
     get inFlight() {
         return this.running.size;
     }
-    /** Reserve a slot. Returns undefined when saturated or shutting down. */
-    acquire(taskId) {
-        if (this.draining || this.running.size >= this.max)
+    /** Reserve a slot. Returns undefined when any cap is reached or the server is shutting down. */
+    acquire(taskId, who = {}) {
+        if (this.refusal(who))
             return undefined;
         const controller = new AbortController();
         this.running.set(taskId, controller);
+        const keys = [who.scopeKey && `s:${who.scopeKey}`, who.caller && `c:${who.caller}`].filter((k) => !!k);
+        for (const k of keys)
+            this.counts.set(k, (this.counts.get(k) ?? 0) + 1);
+        this.keysOf.set(taskId, keys);
         return controller;
     }
     release(taskId) {
         this.running.delete(taskId);
+        for (const k of this.keysOf.get(taskId) ?? []) {
+            const n = (this.counts.get(k) ?? 1) - 1;
+            if (n > 0)
+                this.counts.set(k, n);
+            else
+                this.counts.delete(k);
+        }
+        this.keysOf.delete(taskId);
         if (this.running.size === 0)
             for (const w of this.idleWaiters.splice(0))
                 w();
@@ -367,6 +403,8 @@ export class SyndicateExecutor {
         // Reports the task once: to the task log and metrics, and its spend to
         // the policy. Never throws into the task.
         let reported = false;
+        // The turn's trace (the last root span started: a dispatch turn's answer).
+        let traceId;
         const report = async (ctx, status, reason, usage = NO_USAGE) => {
             if (reported)
                 return;
@@ -382,6 +420,9 @@ export class SyndicateExecutor {
             }
             try {
                 this.opts.onTaskEnd?.({
+                    taskId,
+                    traceId,
+                    ...(ctx?.traceparent ? { callerTraceId: ctx.traceparent.split('-')[1] } : {}),
                     agentId,
                     syndicate: config.syndicate_name,
                     caller: ctx?.caller,
@@ -395,6 +436,21 @@ export class SyndicateExecutor {
             catch {
                 /* a broken log sink must not fail the task */
             }
+            try {
+                this.opts.onAudit?.({
+                    event: 'task.end',
+                    outcome: status,
+                    caller: ctx?.caller,
+                    scopeHash: scopeKey ? createHash('sha256').update(scopeKey).digest('hex').slice(0, 12) : undefined,
+                    sourceIp: ctx?.sourceIp,
+                    agentId,
+                    taskId,
+                    detail: { syndicate: config.syndicate_name, ...(reason ? { reason } : {}), ...(traceId ? { traceId } : {}), durationMs: Date.now() - started, llmCalls: usage.llmCalls },
+                });
+            }
+            catch {
+                /* nor a broken audit sink */
+            }
         };
         let ctxForReport;
         try {
@@ -443,11 +499,10 @@ export class SyndicateExecutor {
                     return;
                 }
             }
-            slot = this.opts.limiter.acquire(taskId);
+            const who = { scopeKey: ctx.scopeKey, caller: ctx.caller };
+            slot = this.opts.limiter.acquire(taskId, who);
             if (!slot) {
-                const why = this.opts.limiter.isDraining
-                    ? 'The server is shutting down; retry shortly.'
-                    : `The server is at its limit of ${this.opts.limiter.max} concurrent tasks; retry shortly.`;
+                const why = this.opts.limiter.refusal(who) ?? 'The server is at capacity; retry shortly.';
                 warn(`Task ${short} rejected — ${why}`);
                 publishFinal(eventBus, taskId, contextId, 'rejected', why);
                 await report(ctx, 'rejected', 'capacity');
@@ -506,6 +561,10 @@ export class SyndicateExecutor {
                     taskId,
                     configHash: this.configHashFor(),
                     attributes: surfaceAttributes(ctx),
+                    traceparent: ctx.traceparent,
+                    onSpanStart: (ids) => {
+                        traceId = ids.traceId;
+                    },
                 },
                 events: {
                     onProgress: (text) => publishWorking(eventBus, taskId, contextId, text),

package/dist/lib/compile.d.ts

@@ -27,9 +27,8 @@
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * Contract and rationale: lib/dispatch.ts.
  */
-import { FunctionTool, LlmAgent } from '@google/adk';
+import { BaseLlm, FunctionTool, LlmAgent } from '@google/adk';
 import type { BaseTool } from '@google/adk';
-import type { BaseLlm } from '@google/adk';
 import type { SubagentYamlConfig, SyndicateYamlConfig } from './loadSyndicate.ts';
 import type { SkillsConfig } from './tools/skillToolset.ts';
 export interface CompileOptions {

package/dist/lib/compile.js

@@ -27,13 +27,15 @@
  * dispatches to is identical to the one DELEGATE would have wrapped.
  * Contract and rationale: lib/dispatch.ts.
  */
-import { AgentTool, BuiltInCodeExecutor, ExampleTool, FunctionTool, LLMRegistry, LlmAgent, LlmSummarizer, TokenBasedContextCompactor } from '@google/adk';
+import { AgentTool, BaseLlm, BuiltInCodeExecutor, ExampleTool, FunctionTool, LLMRegistry, LlmAgent, LlmSummarizer, TokenBasedContextCompactor } from '@google/adk';
 import { relative } from 'node:path';
 import { isDispatchSyndicate } from './dispatch.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { resolveTools as resolveNamedTools } from './toolRegistry.js';
 import { createMcpTools } from './tools/mcpToolFactory.js';
 import { capabilitySummary, describeCapabilities } from './models/capabilities.js';
+import { FallbackLlm } from './models/fallback.js';
+import { resolveModel as resolveRegistryModel } from './models/registry.js';
 import { remoteAgentTool } from './a2a/remoteAgent.js';
 import { buildSkillHarness } from './tools/skillToolset.js';
 import { buildOpenApiTools, isOpenApiTool, namesTool } from './tools/openapiTools.js';
@@ -193,7 +195,19 @@ export function examplesTool(examples) {
         new ExampleTool(examples.map((e) => ({ input: { role: 'user', parts: [{ text: e.input }] }, output: [{ role: 'model', parts: [{ text: e.output }] }] }))),
     ];
 }
-async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples) {
+/**
+ * An agent with `fallback_model:` gets its model wrapped (lib/models/fallback.ts):
+ * the fallback answers a provider-side failure, and a provider that keeps
+ * failing is skipped for a cooldown. A model id string is resolved to its
+ * adapter first, so the wrapper always holds two adapters.
+ */
+function withFallback(primary, fallbackId, resolve, opts) {
+    if (!fallbackId)
+        return primary;
+    const asLlm = (m) => (m instanceof BaseLlm ? m : resolveRegistryModel(String(m)));
+    return new FallbackLlm(asLlm(primary), asLlm(resolve(fallbackId)), opts.log ?? ((m) => console.warn(m)));
+}
+async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, examples, mcpAllowed) {
     const tools = [...resolveNamedTools(toolNames, opts.onUnknownTool), ...examplesTool(examples)];
     // OpenAPI operations become tools here, so require_approval can name them.
     for (const entry of openapi ?? []) {
@@ -207,7 +221,20 @@ async function resolveAgentTools(toolNames, mcpServerUrl, opts, openapi, example
     }
     if (mcpServerUrl) {
         opts.log?.(`Loading MCP tools: ${mcpServerUrl}`);
-        const mcpTools = await createMcpTools(mcpServerUrl);
+        const offered = await createMcpTools(mcpServerUrl);
+        // mcp_tools: only the named tools are exposed (a server's list is its
+        // own to change); a name the server does not offer is reported, and a
+        // gate on it fails the compile in gateTools.
+        const allowed = mcpAllowed ? new Set(mcpAllowed) : undefined;
+        const mcpTools = allowed ? offered.filter((t) => allowed.has(t.name)) : offered;
+        if (allowed) {
+            const missing = [...allowed].filter((n) => !offered.some((t) => t.name === n));
+            if (missing.length)
+                opts.log?.(`MCP ${mcpServerUrl} does not offer ${missing.map((n) => `'${n}'`).join(', ')} (mcp_tools)`);
+            const hidden = offered.length - mcpTools.length;
+            if (hidden)
+                opts.log?.(`MCP ${mcpServerUrl}: ${hidden} tool(s) not in mcp_tools are not exposed`);
+        }
         for (const mcpTool of mcpTools) {
             if (!tools.some((t) => t.name === mcpTool.name))
                 tools.push(mcpTool);
@@ -259,14 +286,14 @@ export async function compileSubagent(subCfg, opts = {}) {
         }
         return compileGraph(nested, opts, subCfg.name, subCfg.description);
     }
-    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples), subCfg.require_approval, subCfg.name);
+    const gated = gateTools(await resolveAgentTools(subCfg.tools, subCfg.mcp_server_url, opts, subCfg.openapi, subCfg.examples, subCfg.mcp_tools), subCfg.require_approval, subCfg.name);
     const { instruction, tools } = await withSkills(subCfg.instruction ?? '', gated, subCfg.skills, subCfg.name, opts);
     const resolveModel = opts.resolveModel ?? ((m) => m);
     logCapabilities(opts, subCfg.name, subCfg.model, subCfg.tools);
     return new LlmAgent({
         name: subCfg.name,
         description: subCfg.description,
-        model: resolveModel(subCfg.model),
+        model: withFallback(resolveModel(subCfg.model), subCfg.fallback_model, resolveModel, opts),
         instruction,
         tools: tools.length > 0 ? tools : undefined,
         outputSchema: subCfg.outputSchema,
@@ -313,7 +340,7 @@ export async function compileGraph(config, opts = {}, overrideName, overrideDesc
     return new LlmAgent({
         name: overrideName || config.orchestrator.name,
         description: overrideDescription || config.orchestrator.description,
-        model: resolveModel(config.orchestrator.model),
+        model: withFallback(resolveModel(config.orchestrator.model), config.orchestrator.fallback_model, resolveModel, opts),
         instruction,
         tools: orchestratorTools.length > 0 ? orchestratorTools : undefined,
         outputSchema: config.orchestrator.outputSchema,

package/dist/lib/config.d.ts

@@ -76,6 +76,13 @@ export declare const DEFAULT_KIMI_MODEL = "kimi-k3";
  * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
  */
 export declare const DEFAULT_KIMI_REASONING_EFFORT = "high";
+/**
+ * Model calls one turn may make, subagents included, when the syndicate sets
+ * no `max_steps`. A runaway tool loop stops here instead of at the provider's
+ * bill. Every shipped example that sets a cap sets 12 to 30; a syndicate that
+ * needs more raises its own `max_steps` (ADR 0039).
+ */
+export declare const DEFAULT_MAX_STEPS = 50;
 /**
  * Default open-weight model, served locally by Ollama (lib/models/ollamaLlm.ts).
  * qwen3:8b is the smallest pulled model that supports tool calling — the

package/dist/lib/config.js

@@ -77,6 +77,13 @@ export const DEFAULT_KIMI_MODEL = 'kimi-k3';
  * override. Source: platform.moonshot.ai › Guides › Reasoning effort.
  */
 export const DEFAULT_KIMI_REASONING_EFFORT = 'high';
+/**
+ * Model calls one turn may make, subagents included, when the syndicate sets
+ * no `max_steps`. A runaway tool loop stops here instead of at the provider's
+ * bill. Every shipped example that sets a cap sets 12 to 30; a syndicate that
+ * needs more raises its own `max_steps` (ADR 0039).
+ */
+export const DEFAULT_MAX_STEPS = 50;
 /**
  * Default open-weight model, served locally by Ollama (lib/models/ollamaLlm.ts).
  * qwen3:8b is the smallest pulled model that supports tool calling — the

package/dist/lib/loadEnv.d.ts

@@ -19,6 +19,11 @@
  * as a credential. Before this, `cp .env.example .env` crashed the default
  * quickstart (`Invalid supabaseUrl`), made the doctor report every provider
  * funded, and turned the example bearer secret into a live one.
+ *
+ * `MELCHIZEDEK_DOTENV=off` in the environment skips every file: the process
+ * runs on its ambient environment alone. A container whose secrets arrive as
+ * real variables wants that, and so does a test that starts a bin from a
+ * clone holding a real `.env`, which must never reach live services.
  */
 /** True for template placeholders that must never act as real values. */
 export declare function isPlaceholderValue(value: string | undefined): boolean;

package/dist/lib/loadEnv.js

@@ -19,6 +19,11 @@
  * as a credential. Before this, `cp .env.example .env` crashed the default
  * quickstart (`Invalid supabaseUrl`), made the doctor report every provider
  * funded, and turned the example bearer secret into a live one.
+ *
+ * `MELCHIZEDEK_DOTENV=off` in the environment skips every file: the process
+ * runs on its ambient environment alone. A container whose secrets arrive as
+ * real variables wants that, and so does a test that starts a bin from a
+ * clone holding a real `.env`, which must never reach live services.
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -69,6 +74,8 @@ export function parseEnvFile(raw) {
  *   clone run from another directory still finds its own `.env`.
  */
 export function loadEnv(moduleUrl) {
+    if (process.env.MELCHIZEDEK_DOTENV?.trim().toLowerCase() === 'off')
+        return;
     const files = [join(process.cwd(), '.env')];
     if (moduleUrl) {
         const own = join(findRepoRoot(dirname(fileURLToPath(moduleUrl))), '.env');

package/dist/lib/loadSyndicate.d.ts

@@ -88,6 +88,10 @@ export interface AgentYamlConfig {
      */
     outputSchema?: Record<string, unknown>;
     mcp_server_url?: string;
+    /** The MCP server's tools this agent may use; the rest are not exposed. */
+    mcp_tools?: string[];
+    /** Answers when `model` fails provider-side, or its provider's circuit is open (ADR 0044). */
+    fallback_model?: string;
     /**
      * Agent Skills (SKILL.md directories) this agent holds the way a coding
      * harness does: the index in its instruction, a skill read on demand, its

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

@@ -97,3 +97,30 @@ export interface MemoryProviders {
  * model or embedder is Gemini.
  */
 export declare function memoryProvidersFromEnv(env?: NodeJS.ProcessEnv, geminiKey?: string): MemoryProviders;
+/**
+ * Where long-term memory sends a syndicate's transcripts: the provider that
+ * extracts facts and the one that embeds them. By default both are Gemini,
+ * whatever the agents run on, so a deployment approved for one provider can
+ * send transcripts to another without noticing; the server warns when they
+ * differ (memoryCrossesProviders).
+ */
+export declare function memoryDestinations(env?: NodeJS.ProcessEnv, override?: {
+    extractor?: {
+        model: string;
+    };
+    embedder?: {
+        provider: string;
+    };
+}): {
+    extraction: string;
+    embeddings: string;
+};
+/**
+ * The memory destinations a syndicate's own agents do not already use, or []
+ * when memory stays with the agents' providers. An embedding endpoint the
+ * operator configured themselves (`openai-compatible`) is not counted.
+ */
+export declare function memoryCrossesProviders(models: Array<string | undefined>, dest: {
+    extraction: string;
+    embeddings: string;
+}): string[];

package/dist/lib/memory/providers.js

@@ -238,3 +238,31 @@ export function memoryProvidersFromEnv(env = process.env, geminiKey) {
     }
     return { extractor, embedder };
 }
+/**
+ * Where long-term memory sends a syndicate's transcripts: the provider that
+ * extracts facts and the one that embeds them. By default both are Gemini,
+ * whatever the agents run on, so a deployment approved for one provider can
+ * send transcripts to another without noticing; the server warns when they
+ * differ (memoryCrossesProviders).
+ */
+export function memoryDestinations(env = process.env, override = {}) {
+    const model = override.extractor?.model ?? (env.MEMORY_EXTRACTION_MODEL?.trim() || MEMORY_EXTRACTION_MODEL);
+    return {
+        extraction: providerForModel(model),
+        embeddings: (override.embedder?.provider ?? (env.MEMORY_EMBEDDING_PROVIDER?.trim() || 'gemini')).toLowerCase(),
+    };
+}
+/**
+ * The memory destinations a syndicate's own agents do not already use, or []
+ * when memory stays with the agents' providers. An embedding endpoint the
+ * operator configured themselves (`openai-compatible`) is not counted.
+ */
+export function memoryCrossesProviders(models, dest) {
+    const agents = new Set(models.filter((m) => !!m).map((m) => providerForModel(m)));
+    const out = new Set();
+    if (!agents.has(dest.extraction))
+        out.add(dest.extraction);
+    if (dest.embeddings !== 'openai-compatible' && !agents.has(dest.embeddings))
+        out.add(dest.embeddings);
+    return [...out];
+}