melchizedek-agents 0.17.0 → 0.18.0

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

@@ -0,0 +1,41 @@
+/**
+ * lib/models/fallback.ts — a fallback model and a per-provider circuit
+ * breaker for an agent that declares `fallback_model:` (ADR 0044).
+ *
+ * WHY: lib/models/retry.ts makes one call survive a blip. It does nothing for
+ * an outage: every turn on a provider that is down spends its retries and
+ * fails. An agent that names a fallback model now answers from it instead,
+ * and a provider that keeps failing is skipped for a cooldown rather than
+ * tried on every turn.
+ *
+ * THE RULES:
+ *   - Only provider-side failures count: what retry.ts classifies retryable
+ *     (408/409/425/429/5xx, connection resets) once the adapter's own retries
+ *     are spent. A 4xx is the request's fault and is thrown as it is; a
+ *     canceled turn is never counted or redirected.
+ *   - The fallback runs only if the primary produced nothing yet: a stream
+ *     that failed midway is thrown, never replayed on another model.
+ *   - The breaker is per provider, shared by every agent in the process:
+ *     MODEL_BREAKER_THRESHOLD consecutive failures (default 5; 0 disables)
+ *     open it for MODEL_BREAKER_COOLDOWN_MS (default 30 s). While open, a
+ *     wrapped agent goes straight to its fallback; after the cooldown one
+ *     call is let through, and a success closes the circuit.
+ */
+import { BaseLlm } from '@google/adk';
+import type { BaseLlmConnection, LlmRequest, LlmResponse } from '@google/adk';
+/** True while `provider`'s circuit is open (calls skip it). */
+export declare function circuitOpen(provider: string, now?: number): boolean;
+/** For tests: close every circuit. */
+export declare function resetCircuits(): void;
+/** A provider-side failure: worth counting against the provider and worth a fallback. */
+export declare function isProviderFailure(err: unknown): boolean;
+export declare class FallbackLlm extends BaseLlm {
+    readonly primary: BaseLlm;
+    readonly fallback: BaseLlm;
+    private readonly log;
+    private readonly primaryProvider;
+    constructor(primary: BaseLlm, fallback: BaseLlm, log?: (m: string) => void);
+    generateContentAsync(llmRequest: LlmRequest, stream?: boolean, abortSignal?: AbortSignal): AsyncGenerator<LlmResponse, void>;
+    private onFallback;
+    connect(llmRequest: LlmRequest): Promise<BaseLlmConnection>;
+}

package/dist/lib/models/fallback.js

@@ -0,0 +1,105 @@
+/**
+ * lib/models/fallback.ts — a fallback model and a per-provider circuit
+ * breaker for an agent that declares `fallback_model:` (ADR 0044).
+ *
+ * WHY: lib/models/retry.ts makes one call survive a blip. It does nothing for
+ * an outage: every turn on a provider that is down spends its retries and
+ * fails. An agent that names a fallback model now answers from it instead,
+ * and a provider that keeps failing is skipped for a cooldown rather than
+ * tried on every turn.
+ *
+ * THE RULES:
+ *   - Only provider-side failures count: what retry.ts classifies retryable
+ *     (408/409/425/429/5xx, connection resets) once the adapter's own retries
+ *     are spent. A 4xx is the request's fault and is thrown as it is; a
+ *     canceled turn is never counted or redirected.
+ *   - The fallback runs only if the primary produced nothing yet: a stream
+ *     that failed midway is thrown, never replayed on another model.
+ *   - The breaker is per provider, shared by every agent in the process:
+ *     MODEL_BREAKER_THRESHOLD consecutive failures (default 5; 0 disables)
+ *     open it for MODEL_BREAKER_COOLDOWN_MS (default 30 s). While open, a
+ *     wrapped agent goes straight to its fallback; after the cooldown one
+ *     call is let through, and a success closes the circuit.
+ */
+import { BaseLlm } from '@google/adk';
+import { classifyError } from './retry.js';
+import { providerForModel } from './providerMap.js';
+const circuits = new Map();
+function breakerSettings(env = process.env) {
+    const n = (name, fallback) => {
+        const v = Number(env[name]);
+        return Number.isFinite(v) && v >= 0 ? Math.floor(v) : fallback;
+    };
+    return { threshold: n('MODEL_BREAKER_THRESHOLD', 5), cooldownMs: n('MODEL_BREAKER_COOLDOWN_MS', 30_000) };
+}
+/** True while `provider`'s circuit is open (calls skip it). */
+export function circuitOpen(provider, now = Date.now()) {
+    const c = circuits.get(provider);
+    return !!c && c.openUntil > now;
+}
+function recordFailure(provider, now = Date.now()) {
+    const { threshold, cooldownMs } = breakerSettings();
+    if (threshold === 0)
+        return;
+    const c = circuits.get(provider) ?? { failures: 0, openUntil: 0 };
+    c.failures += 1;
+    if (c.failures >= threshold)
+        c.openUntil = now + cooldownMs;
+    circuits.set(provider, c);
+}
+function recordSuccess(provider) {
+    circuits.delete(provider);
+}
+/** For tests: close every circuit. */
+export function resetCircuits() {
+    circuits.clear();
+}
+/** A provider-side failure: worth counting against the provider and worth a fallback. */
+export function isProviderFailure(err) {
+    if (err?.name === 'AbortError')
+        return false;
+    return classifyError(err).retryable;
+}
+export class FallbackLlm extends BaseLlm {
+    primary;
+    fallback;
+    log;
+    primaryProvider;
+    constructor(primary, fallback, log = (m) => console.warn(m)) {
+        super({ model: primary.model });
+        this.primary = primary;
+        this.fallback = fallback;
+        this.log = log;
+        this.primaryProvider = providerForModel(primary.model);
+    }
+    async *generateContentAsync(llmRequest, stream, abortSignal) {
+        if (circuitOpen(this.primaryProvider)) {
+            yield* this.onFallback(llmRequest, stream, abortSignal, `${this.primaryProvider} circuit is open`);
+            return;
+        }
+        let yielded = false;
+        try {
+            for await (const r of this.primary.generateContentAsync(llmRequest, stream, abortSignal)) {
+                yielded = true;
+                yield r;
+            }
+            recordSuccess(this.primaryProvider);
+        }
+        catch (err) {
+            if (abortSignal?.aborted || !isProviderFailure(err))
+                throw err;
+            recordFailure(this.primaryProvider);
+            if (yielded)
+                throw err;
+            yield* this.onFallback(llmRequest, stream, abortSignal, `${this.primary.model} failed (${err instanceof Error ? err.message.slice(0, 120) : String(err)})`);
+        }
+    }
+    async *onFallback(llmRequest, stream, abortSignal, why) {
+        this.log(`[models] ${why}; answering from ${this.fallback.model}.`);
+        const request = { ...llmRequest, model: this.fallback.model };
+        yield* this.fallback.generateContentAsync(request, stream, abortSignal);
+    }
+    connect(llmRequest) {
+        return this.primary.connect(llmRequest);
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { Pool } from 'pg';
+export type AuditEventName = 'auth.failure' | 'task.end' | 'memory.erase';
+export interface AuditEvent {
+    event: AuditEventName;
+    /** denied | ok | the task's final status. */
+    outcome: string;
+    /** The authenticated caller's name ('shared-secret', a caller token's name, 'jwt'). */
+    caller?: string;
+    /** SHA-256 prefix of the scope key, never the key. */
+    scopeHash?: string;
+    sourceIp?: string;
+    agentId?: string;
+    taskId?: string;
+    /** Small, content-free facts: a reason code, counts, a path. */
+    detail?: Record<string, unknown>;
+}
+export type AuditSink = (event: AuditEvent) => void;
+/** The scope's SHA-256 prefix, as the task log writes it. */
+export declare function scopeHashOf(scopeKey: string | undefined): string | undefined;
+/** Appends events to melchizedek_audit through the storage pool. */
+export declare function postgresAuditSink(pool: Pick<Pool, 'query'>, warn?: (m: string) => void): AuditSink;

package/dist/lib/observability/audit.js

@@ -0,0 +1,39 @@
+/**
+ * lib/observability/audit.ts — the audit trail: who did what, when, from
+ * where (ADR 0042).
+ *
+ * The ledger (adk_turns) records what a turn said. An auditor asks a
+ * different question: which caller, authenticated how, from which address,
+ * did what, and was it allowed. Those events are written to
+ * melchizedek_audit (db/migrations/0012), which a trigger keeps
+ * append-only. An event never carries conversation content or a scope
+ * key: a scope is a SHA-256 prefix, as in the task log.
+ *
+ * The sink is fire-and-forget: an audit write never delays or fails a
+ * request. A failed write is logged once per outage, and the event is
+ * written to stderr as one JSON line instead, so it is not lost silently.
+ */
+import { createHash } from 'node:crypto';
+/** The scope's SHA-256 prefix, as the task log writes it. */
+export function scopeHashOf(scopeKey) {
+    return scopeKey ? createHash('sha256').update(scopeKey).digest('hex').slice(0, 12) : undefined;
+}
+/** Appends events to melchizedek_audit through the storage pool. */
+export function postgresAuditSink(pool, warn = (m) => console.warn(m)) {
+    let failing = false;
+    return (e) => {
+        pool
+            .query('INSERT INTO melchizedek_audit (event, outcome, caller, scope_hash, source_ip, agent_id, task_id, detail) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)', [e.event, e.outcome, e.caller ?? null, e.scopeHash ?? null, e.sourceIp ?? null, e.agentId ?? null, e.taskId ?? null, JSON.stringify(e.detail ?? {})])
+            .then(() => {
+            if (failing)
+                warn('[audit] writes to melchizedek_audit succeed again.');
+            failing = false;
+        })
+            .catch((err) => {
+            if (!failing)
+                warn(`[audit] could not write to melchizedek_audit (${err instanceof Error ? err.message : String(err)}); events go to stderr until it recovers.`);
+            failing = true;
+            console.error(JSON.stringify({ audit: { ...e, at: new Date().toISOString() } }));
+        });
+    };
+}

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

@@ -10,6 +10,12 @@
  */
 /** One finished (or refused) task, as the executor reports it. */
 export interface TaskRecord {
+    /** The A2A task id: joins this record to the task store and the audit trail. */
+    taskId?: string;
+    /** The turn's trace id: joins this record to its spans and its ledger row. */
+    traceId?: string;
+    /** The trace id of the caller's `traceparent`, when it sent one: the turn's root span links to it. */
+    callerTraceId?: string;
     /** The agent id the task was sent to; '' is the default syndicate. */
     agentId: string;
     syndicate: string;

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

@@ -1,3 +1,4 @@
+import type { SpanContext } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { Event, LlmResponse } from '@google/adk';
 /**
@@ -67,6 +68,14 @@ export interface TraceMetadata {
         traceId: string;
         spanId: string;
     }) => void;
+    /**
+     * A caller's W3C `traceparent`. The turn's root span LINKS to the caller's
+     * span (and records `caller.trace_id`) instead of joining its trace: a turn's
+     * trace id keys its ledger attribution, its in-process stats and erasure,
+     * so it must stay unique to the turn and never be chosen by a caller.
+     * Ignored unless well formed (validTraceparent).
+     */
+    traceparent?: string;
     /**
      * Identity of the turn. These are what make a stored turn joinable to
      * its session row (`adk_sessions.id` = app:user:session) and to the ADK
@@ -103,6 +112,10 @@ export declare function serverToolEvents(ev: any): Array<{
     name: 'ToolCall' | 'ToolResponse';
     attributes: Record<string, string | boolean>;
 }>;
+/** A well-formed version-00 W3C traceparent, or undefined. Never throws. */
+export declare function validTraceparent(value: unknown): string | undefined;
+/** The caller's span a turn links to, from its `traceparent`; undefined when absent or malformed. */
+export declare function callerSpanContext(traceparent: string | undefined): SpanContext | undefined;
 export declare function traceAgentRun(stream: AsyncIterableIterator<Event>, metadata: TraceMetadata): AsyncGenerator<Event, void, void>;
 export interface LlmCallMeta {
     /** Provider id, e.g. 'anthropic', 'openai', 'xai', 'moonshot', 'ollama', 'gemini'. */

package/dist/lib/observability/tracer.js

@@ -1,4 +1,4 @@
-import { trace, context } from '@opentelemetry/api';
+import { trace, context, defaultTextMapGetter, ROOT_CONTEXT } from '@opentelemetry/api';
 import { createRequire } from 'node:module';
 import { TELEMETRY_SCHEMA_VERSION, engineVersion } from './lineage.js';
 import { FilteringSpanExporter, otlpContentMode } from './otlpFilter.js';
@@ -345,9 +345,23 @@ export function serverToolEvents(ev) {
     }
     return out;
 }
+const TRACEPARENT = /^00-(?!0{32})[0-9a-f]{32}-(?!0{16})[0-9a-f]{16}-[0-9a-f]{2}$/;
+/** A well-formed version-00 W3C traceparent, or undefined. Never throws. */
+export function validTraceparent(value) {
+    return typeof value === 'string' && TRACEPARENT.test(value.trim().toLowerCase()) ? value.trim().toLowerCase() : undefined;
+}
+/** The caller's span a turn links to, from its `traceparent`; undefined when absent or malformed. */
+export function callerSpanContext(traceparent) {
+    const tp = validTraceparent(traceparent);
+    if (!tp)
+        return undefined;
+    const ctx = new core.W3CTraceContextPropagator().extract(ROOT_CONTEXT, { traceparent: tp }, defaultTextMapGetter);
+    return trace.getSpanContext(ctx);
+}
 export async function* traceAgentRun(stream, metadata) {
     initializeTracing();
-    const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`);
+    const caller = callerSpanContext(metadata.traceparent);
+    const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`, caller ? { links: [{ context: caller }], attributes: { 'caller.trace_id': caller.traceId } } : undefined);
     turnContexts.set(span.spanContext().traceId, {
         sessionId: metadata.sessionId,
         userId: metadata.userId,

package/dist/lib/runtime/syndicateTurn.d.ts

@@ -77,6 +77,8 @@ export interface TraceOptions {
         traceId: string;
         spanId: string;
     }) => void;
+    /** A caller's W3C traceparent: the turn's root span links to it (never joins it). */
+    traceparent?: string;
 }
 export interface SyndicateTurnOptions {
     config: SyndicateYamlConfig;
@@ -100,7 +102,7 @@ export interface SyndicateTurnOptions {
     signal?: AbortSignal;
     /** Wall-clock budget for the turn, in ms. Default: none. */
     deadlineMs?: number;
-    /** Model-call ceiling for the whole turn. Default: the YAML's `max_steps`. */
+    /** Model-call ceiling for the whole turn. Default: the YAML's `max_steps`, else DEFAULT_MAX_STEPS (50). */
     maxLlmCalls?: number;
     /** Ask adapters for token-by-token partial events (the REPL's live view). */
     streaming?: boolean;

package/dist/lib/runtime/syndicateTurn.js

@@ -27,6 +27,7 @@
  * request in flight, not just the loop around it.
  */
 import { InMemorySessionService, ReflectAndRetryModelPlugin, ReflectAndRetryToolPlugin, Runner, StreamingMode, getFunctionCalls, getFunctionResponses } from '@google/adk';
+import { DEFAULT_MAX_STEPS } from '../config.js';
 import { agentGates, compileGraph, compileSubagent } from '../compile.js';
 import { ROUTE_STEP_SUFFIX, compileWorkflow, describeInput, inputRequestFrom, isWorkflowSyndicate } from '../workflow.js';
 export { describeInput } from '../workflow.js';
@@ -265,7 +266,7 @@ export async function runSyndicateTurn(opts) {
     if (!opts.compile?.resolveModel)
         registerAvailableProviders();
     const control = createTurnControl({
-        maxLlmCalls: opts.maxLlmCalls ?? config.max_steps,
+        maxLlmCalls: opts.maxLlmCalls ?? config.max_steps ?? DEFAULT_MAX_STEPS,
         deadlineMs: opts.deadlineMs,
         signal: opts.signal,
     });
@@ -408,6 +409,7 @@ async function runTurnInner(opts, control) {
                 configHash: trace.configHash,
                 attributes: trace.attributes,
                 onSpanStart: trace.onSpanStart,
+                traceparent: trace.traceparent,
                 onEnd: () => ({
                     'syndicate.relay_fallback': params.stage === 'delegate' && !!params.relayFallback?.(),
                     ...(control.stopReason ? { 'syndicate.stop_reason': control.stopReason } : {}),

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

@@ -17,6 +17,7 @@ import type { Embedder, MemoryExtractor } from '../../memory/providers.ts';
 import type { EraseCounts, EraseOptions } from '../../memory/erase.ts';
 import { PostgresSessionService } from './sessionService.ts';
 import { PostgresTaskStore } from './taskStore.ts';
+import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
 import type { TaskBackend } from '../../tools/taskTools.ts';
 import type { TurnLock } from '../../a2a/turnLock.ts';
@@ -76,6 +77,8 @@ export interface PostgresStorage {
      * tables (lib/storage/rlsStatus.ts). Never throws.
      */
     rlsHardening: () => Promise<RlsHardeningStatus>;
+    /** Appends to melchizedek_audit (migration 0012, ADR 0042). */
+    audit: AuditSink;
     /**
      * One turn at a time per conversation, across every instance on this
      * database: a session-level advisory lock on a dedicated connection, so a

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

@@ -20,6 +20,7 @@ import { PostgresTaskStore, reapExpiredTasks, renewTaskLeases } from './taskStor
 import { postgresTaskBackend } from './taskQueue.js';
 import { searchPathOption } from '../schema.js';
 import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
+import { postgresAuditSink } from '../../observability/audit.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
@@ -122,6 +123,7 @@ export function postgresStorage(options) {
                 throw err;
             }
         },
+        audit: postgresAuditSink(pool),
         async rlsHardening() {
             try {
                 const r = await pool.query(POSTGRES_RLS_QUERY);

package/dist/lib/syndicateSchema.d.ts

@@ -29,6 +29,7 @@ export declare const agentSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     model: z.ZodString;
+    fallback_model: z.ZodOptional<z.ZodString>;
     instruction: z.ZodString;
     globalInstruction: z.ZodOptional<z.ZodString>;
     tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -62,6 +63,7 @@ export declare const agentSchema: z.ZodObject<{
     }, z.core.$loose>>;
     outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     mcp_server_url: z.ZodOptional<z.ZodString>;
+    mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     skills: z.ZodOptional<z.ZodObject<{
         dir: z.ZodString;
         scripts: z.ZodOptional<z.ZodEnum<{
@@ -114,6 +116,7 @@ export declare const agentSchema: z.ZodObject<{
  */
 export declare const subagentSchema: z.ZodObject<{
     name: z.ZodString;
+    fallback_model: z.ZodOptional<z.ZodString>;
     globalInstruction: z.ZodOptional<z.ZodString>;
     tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -146,6 +149,7 @@ export declare const subagentSchema: z.ZodObject<{
     }, z.core.$loose>>;
     outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     mcp_server_url: z.ZodOptional<z.ZodString>;
+    mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     skills: z.ZodOptional<z.ZodObject<{
         dir: z.ZodString;
         scripts: z.ZodOptional<z.ZodEnum<{
@@ -201,6 +205,7 @@ export declare const syndicateSchema: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         model: z.ZodString;
+        fallback_model: z.ZodOptional<z.ZodString>;
         instruction: z.ZodString;
         globalInstruction: z.ZodOptional<z.ZodString>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -234,6 +239,7 @@ export declare const syndicateSchema: z.ZodObject<{
         }, z.core.$loose>>;
         outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         mcp_server_url: z.ZodOptional<z.ZodString>;
+        mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         skills: z.ZodOptional<z.ZodObject<{
             dir: z.ZodString;
             scripts: z.ZodOptional<z.ZodEnum<{
@@ -280,6 +286,7 @@ export declare const syndicateSchema: z.ZodObject<{
     }, z.core.$strict>;
     subagents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
+        fallback_model: z.ZodOptional<z.ZodString>;
         globalInstruction: z.ZodOptional<z.ZodString>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -312,6 +319,7 @@ export declare const syndicateSchema: z.ZodObject<{
         }, z.core.$loose>>;
         outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         mcp_server_url: z.ZodOptional<z.ZodString>;
+        mcp_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         skills: z.ZodOptional<z.ZodObject<{
             dir: z.ZodString;
             scripts: z.ZodOptional<z.ZodEnum<{

package/dist/lib/syndicateSchema.js

@@ -125,6 +125,11 @@ const agentFields = {
         .string()
         .min(1)
         .describe('Model id; its prefix picks the provider (gemini-*, claude-*, gpt-*/o*, grok-*, ollama/*).'),
+    fallback_model: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A model on another provider that answers when this agent\'s model fails provider-side (5xx, 429, network) before producing anything, or while that provider\'s circuit is open (ADR 0044).'),
     instruction: z.string().min(1).describe('System prompt / persona.'),
     globalInstruction: z
         .string()
@@ -154,6 +159,11 @@ const agentFields = {
         .string()
         .optional()
         .describe('MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.'),
+    mcp_tools: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('The MCP server\'s tools this agent may use, by name; any other tool the server lists is not exposed. Without it, every listed tool is. require_approval may name these. Needs mcp_server_url.'),
     skills: skillsSchema.optional(),
     openapi: z.array(openapiEntry).min(1).optional(),
     code_execution: z
@@ -330,7 +340,7 @@ export const syndicateSchema = z
         .int()
         .positive()
         .optional()
-        .describe('Hard cap on runner loops (LLM → tool cycles).'),
+        .describe('Hard cap on model calls per turn, subagents included. Default 50 (DEFAULT_MAX_STEPS) when unset.'),
     bundled_references: z
         .record(z.string(), z.record(z.string(), z.unknown()))
         .optional()
@@ -511,11 +521,13 @@ function crossFieldProblems(raw) {
             return;
         }
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
-        // An OpenAPI operation can be gated once it is named under `operations`.
+        // An OpenAPI operation can be gated once it is named under `operations`,
+        // and an MCP tool once it is named under `mcp_tools`.
         const operations = (Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations : []));
+        const mcpTools = Array.isArray(agent.mcp_tools) ? agent.mcp_tools : [];
         (Array.isArray(agent.require_approval) ? agent.require_approval : []).forEach((name, j) => {
-            if (typeof name === 'string' && !tools.includes(name) && !operations.includes(name)) {
-                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools or its openapi operations` });
+            if (typeof name === 'string' && !tools.includes(name) && !operations.includes(name) && !mcpTools.includes(name)) {
+                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools, its openapi operations or its mcp_tools` });
             }
         });
     };
@@ -567,6 +579,9 @@ function crossFieldProblems(raw) {
         if (agent.mode !== undefined && !isObj(raw.workflow)) {
             out.push({ path: [...path, 'mode'], message: 'mode: task applies to workflow nodes, whose output is the finish_task arguments' });
         }
+        if (agent.mcp_tools !== undefined && typeof agent.mcp_server_url !== 'string') {
+            out.push({ path: [...path, 'mcp_tools'], message: 'mcp_tools chooses among an MCP server\'s tools; it needs mcp_server_url' });
+        }
     };
     if (isObj(raw.orchestrator))
         executionProblems(raw.orchestrator, ['orchestrator'], true);

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

@@ -1,4 +1,30 @@
 import { FunctionTool } from '@google/adk';
+import type { RedirectPolicy } from '../net/redirects.ts';
 export declare function assertSafeMcpUrl(raw: string, env?: NodeJS.ProcessEnv): Promise<URL>;
 export declare function mcpAuthHeaders(url: URL, env?: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Where an MCP connection may be redirected (ADR 0036's rule, applied to MCP):
+ * a hop on the server's own origin gets the server's check (ALLOW_PRIVATE_MCP
+ * applies), a hop anywhere else the full guard with no development exception,
+ * and lib/net/redirects.ts strips every credential header from it, so a
+ * bearer token from MCP_BEARER_TOKENS never follows a redirect off its host.
+ * The SDK already refuses a POST endpoint on another origin.
+ */
+export declare const MCP_REDIRECTS: RedirectPolicy;
+/** The fetch an MCP transport uses: every redirect hop checked before it is followed. */
+export declare const mcpFetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * A remote MCP server is an untrusted tool vendor: its tool descriptions go
+ * into the prompt and its results into the conversation. Both are bounded,
+ * so a server cannot flood the context (or the bill) with either.
+ */
+export declare const MAX_MCP_DESCRIPTION_CHARS = 1000;
+export declare const MAX_MCP_RESULT_CHARS = 20000;
+/**
+ * Close every open MCP connection. A connection otherwise lives as long as
+ * the process (its tools are called for the life of the compiled agent), and
+ * its stream reconnects when the server restarts; an embedding app that
+ * stops cleanly, or a test, calls this.
+ */
+export declare function closeMcpConnections(): Promise<void>;
 export declare function createMcpTools(mcpServerUrl: string): Promise<FunctionTool[]>;

package/dist/lib/tools/mcpToolFactory.js

@@ -2,6 +2,7 @@ import { FunctionTool } from '@google/adk';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { checkHost } from '../net/addressGuard.js';
+import { fetchWithRedirectPolicy } from '../net/redirects.js';
 // Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
 // config. Only http(s), and the host must pass lib/net/addressGuard.ts (the
 // same guard web_extract uses): local names and non-public addresses —
@@ -53,11 +54,61 @@ export function mcpAuthHeaders(url, env = process.env) {
     const token = tokens[host];
     return typeof token === 'string' && token ? { Authorization: `Bearer ${token}` } : {};
 }
+/**
+ * Where an MCP connection may be redirected (ADR 0036's rule, applied to MCP):
+ * a hop on the server's own origin gets the server's check (ALLOW_PRIVATE_MCP
+ * applies), a hop anywhere else the full guard with no development exception,
+ * and lib/net/redirects.ts strips every credential header from it, so a
+ * bearer token from MCP_BEARER_TOKENS never follows a redirect off its host.
+ * The SDK already refuses a POST endpoint on another origin.
+ */
+export const MCP_REDIRECTS = {
+    async hopProblem(url, crossOrigin) {
+        if (!crossOrigin) {
+            try {
+                await assertSafeMcpUrl(url.href);
+                return null;
+            }
+            catch (err) {
+                return err instanceof Error ? err.message : String(err);
+            }
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return `${url.protocol} is not http(s)`;
+        const reason = await checkHost(url.hostname);
+        return reason ? `refusing MCP redirect to ${url.hostname}: ${reason}` : null;
+    },
+};
+/** The fetch an MCP transport uses: every redirect hop checked before it is followed. */
+export const mcpFetch = (input, init) => fetchWithRedirectPolicy(input, init, MCP_REDIRECTS, (i, o) => fetch(i, o));
+/**
+ * A remote MCP server is an untrusted tool vendor: its tool descriptions go
+ * into the prompt and its results into the conversation. Both are bounded,
+ * so a server cannot flood the context (or the bill) with either.
+ */
+export const MAX_MCP_DESCRIPTION_CHARS = 1_000;
+export const MAX_MCP_RESULT_CHARS = 20_000;
+const bounded = (text, max, what) => text.length <= max ? text : `${text.slice(0, max)}… [${what} cut at ${max} characters]`;
+/** Every MCP connection opened and still in use, so a shutdown can close them. */
+const openTransports = new Set();
+/**
+ * Close every open MCP connection. A connection otherwise lives as long as
+ * the process (its tools are called for the life of the compiled agent), and
+ * its stream reconnects when the server restarts; an embedding app that
+ * stops cleanly, or a test, calls this.
+ */
+export async function closeMcpConnections() {
+    const all = [...openTransports];
+    openTransports.clear();
+    await Promise.all(all.map((t) => t.close().catch(() => { })));
+}
 export async function createMcpTools(mcpServerUrl) {
+    let transport;
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
-        const transport = new SSEClientTransport(url, {
-            requestInit: { headers: mcpAuthHeaders(url) }
+        transport = new SSEClientTransport(url, {
+            requestInit: { headers: mcpAuthHeaders(url) },
+            fetch: mcpFetch,
         });
         const client = new Client({
             name: 'melchizedek-a2a-client',
@@ -66,6 +117,7 @@ export async function createMcpTools(mcpServerUrl) {
             capabilities: {}
         });
         await client.connect(transport);
+        openTransports.add(transport);
         // Fetch available tools from the MCP server
         const toolsResponse = await client.listTools();
         // MCP servers describe tools in standard lowercase JSON Schema; the ADK
@@ -106,7 +158,7 @@ export async function createMcpTools(mcpServerUrl) {
             }
             return new FunctionTool({
                 name: tool.name,
-                description: tool.description || `MCP Tool: ${tool.name}`,
+                description: bounded(tool.description || `MCP Tool: ${tool.name}`, MAX_MCP_DESCRIPTION_CHARS, 'description'),
                 parameters: {
                     type: 'OBJECT',
                     properties,
@@ -120,7 +172,7 @@ export async function createMcpTools(mcpServerUrl) {
                         });
                         const content = result.content;
                         const texts = content.filter(c => c.type === 'text').map(c => c.text ?? '');
-                        return texts.join('\n');
+                        return bounded(texts.join('\n'), MAX_MCP_RESULT_CHARS, 'result');
                     }
                     catch (error) {
                         return `[MCP ERROR] Tool ${tool.name} failed: ${error.message}`;
@@ -131,6 +183,11 @@ export async function createMcpTools(mcpServerUrl) {
     }
     catch (error) {
         console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error);
+        // A failed connect leaves the SSE stream's reconnect timer running; close
+        // it, or every unreachable server keeps retrying for the process's life.
+        if (transport)
+            openTransports.delete(transport);
+        await transport?.close().catch(() => { });
         return [];
     }
 }

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

@@ -34,6 +34,12 @@ export declare function namesTool(configured: string, tool: {
         operationId?: string;
     };
 }): boolean;
+/**
+ * Why an `auth` may not read this variable, or null. With
+ * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
+ * it, anything but the framework's own variables is.
+ */
+export declare function credentialEnvProblem(name: string, env?: NodeJS.ProcessEnv): string | null;
 /** Cut an API result to MAX_RESULT_CHARS, saying so. */
 export declare function boundResult(result: unknown): unknown;
 /**