melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/syndicateSchema.js

@@ -22,6 +22,7 @@
  * SDKs whose fields this repo does not own.
  */
 import { z } from 'zod';
+import { DEFAULT_ROUTE_KEY, NODE_KINDS, ROUTE_STEP_SUFFIX, START_NAME, elementNames, nodeKind } from './workflowConfig.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's own rule (validateAgentName in @google/adk base_agent): checked here
@@ -64,6 +65,55 @@ const generateContentConfig = z
     thinkingConfig: thinkingConfig.optional(),
 })
     .describe('Model generation config (@google/genai GenerateContentConfig). Do not set tools here.');
+// ── Skills ───────────────────────────────────────────────────────────────────
+export const SKILL_SCRIPT_MODES = ['none', 'local'];
+/**
+ * Agent Skills for one agent (lib/tools/skillToolset.ts): the frontmatter
+ * index is injected into the instruction at compile time, a skill is read in
+ * full on demand, and its scripts run only when `scripts` allows and a person
+ * approves each run.
+ */
+const skillsSchema = z
+    .strictObject({
+    dir: z
+        .string()
+        .min(1)
+        .describe('A directory of skills: one subdirectory per skill, named as its SKILL.md frontmatter names it. Relative to the working directory.'),
+    scripts: z
+        .enum(SKILL_SCRIPT_MODES)
+        .optional()
+        .describe('Whether a skill\'s scripts/ may run. "local" runs them on this machine, each after a person approves (ADR 0028); default "none".'),
+    tools: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Registry tool names a skill may unlock through its `allowed-tools` frontmatter once it is loaded. Omitted, no skill unlocks anything.'),
+})
+    .describe('Agent Skills (SKILL.md directories) this agent reads the way a coding harness does.');
+// ── OpenAPI ──────────────────────────────────────────────────────────────────
+const envName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/, 'an environment variable name (A–Z, 0–9, _)');
+const openapiEntry = z
+    .strictObject({
+    spec: z.string().min(1).describe('An OpenAPI 3 spec file (.yaml, .yml, .json), relative to this syndicate file. Files only, never URLs.'),
+    operations: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Operations to expose, by operationId or tool name. Omitted: every GET operation, and nothing that writes.'),
+    base_url: z.string().url().optional().describe('Overrides the spec\'s servers[0].url. Checked by the SSRF guard.'),
+    prefix: z.string().regex(/^[a-z][a-z0-9_]*$/).optional().describe('Prepended to each tool name, to keep two APIs apart.'),
+    auth: z
+        .strictObject({
+        bearer_env: envName.optional().describe('Environment variable holding a bearer token.'),
+        api_key: z
+            .strictObject({ env: envName, in: z.enum(['header', 'query']), name: z.string().min(1) })
+            .optional()
+            .describe('An API key read from `env`, sent in a header or the query under `name`.'),
+    })
+        .refine((a) => !!a.bearer_env !== !!a.api_key, 'exactly one of bearer_env or api_key')
+        .optional()
+        .describe('Credentials, always from the environment, never written in YAML.'),
+})
+    .describe('An HTTP API as tools, from its OpenAPI spec (lib/tools/openapiTools.ts).');
 // ── Agents ───────────────────────────────────────────────────────────────────
 const agentFields = {
     name: agentName,
@@ -75,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()
@@ -104,6 +159,35 @@ 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
+        .literal('gemini')
+        .optional()
+        .describe('"gemini": the model writes and runs Python in Gemini\'s server-side sandbox; nothing runs on this host. Gemini models only.'),
+    context: z
+        .strictObject({
+        compact_after_tokens: z.number().int().min(1000).describe('Compact when the last request\'s prompt passed this many tokens.'),
+        keep_recent_events: z.number().int().min(1).max(100).optional().describe('Events kept verbatim after the summary. Default 6.'),
+        summary_model: z.string().min(1).optional().describe('The model that writes the summary. Default: the agent\'s own.'),
+    })
+        .optional()
+        .describe('Summarize a long conversation instead of overflowing the window. The orchestrator of a delegate syndicate only.'),
+    examples: z
+        .array(z.strictObject({ input: z.string().min(1), output: z.string().min(1) }))
+        .min(1)
+        .max(20)
+        .optional()
+        .describe('Few-shot exchanges (input, output) added to every request\'s instruction.'),
+    mode: z
+        .literal('task')
+        .optional()
+        .describe('"task": the agent works until it calls finish_task; its arguments (matching outputSchema) are the node\'s output. Workflow nodes only.'),
     orchestration: z
         .strictObject({
         role: z.enum(['primary', 'sub-agent']).optional(),
@@ -159,6 +243,48 @@ const dispatchSchema = z
     route_overrides: z.array(routeOverride).optional(),
 })
     .describe('Opts into PLAN-DISPATCH orchestration (lib/dispatch.ts).');
+// ── Workflow ─────────────────────────────────────────────────────────────────
+const nodeName = z.string().min(1);
+const edgeTargets = z.union([nodeName, z.array(nodeName).min(1)]);
+/** One element of an edge chain: a name, several names, or a routing map. */
+const edgeElement = z.union([
+    nodeName,
+    z.array(nodeName).min(1).describe('Several nodes: fan-out when they follow one node, fan-in when one node follows them.'),
+    z
+        .record(z.string().min(1), edgeTargets)
+        .describe('A routing map after a node: `{ <route>: <node or nodes>, default: <node> }`, matched against that node\'s output.'),
+]);
+const retrySchema = z
+    .strictObject({
+    max_attempts: z.number().int().positive().optional().describe('Attempts including the first; 1 = no retry. ADK default 5.'),
+    initial_delay: z.number().nonnegative().optional().describe('Seconds before the first retry.'),
+    max_delay: z.number().nonnegative().optional(),
+    backoff_factor: z.number().positive().optional(),
+})
+    .describe('Retry a node on failure (lib/workflow.ts).');
+const workflowNodeSchema = z
+    .strictObject({
+    ask_user: z.string().min(1).optional().describe('Pause and ask the person this; the reply becomes the node\'s output.'),
+    schema: z.record(z.string(), z.unknown()).optional().describe('JSON Schema a structured reply to ask_user must satisfy; plain text passes as is.'),
+    join: z.literal(true).optional().describe('Wait for every predecessor; output `{ <predecessor>: <output> }`.'),
+    map: z.string().min(1).optional().describe('Run this agent once per item of a list input, concurrently; output the list of results.'),
+    max_parallel: z.number().int().positive().optional().describe('Concurrency of map. Default 8.'),
+    tool: z.string().min(1).optional().describe('Run this registry tool with the node input as its arguments.'),
+    route_key: z.string().min(1).optional().describe('Property of a JSON output holding the route. Default "route".'),
+    retry: retrySchema.optional(),
+    timeout: z.number().positive().optional().describe('Seconds this node may run before it fails.'),
+})
+    .describe('A declared node (exactly one of ask_user, join, map, tool) or modifiers for an agent node (retry, timeout, route_key).');
+const workflowSchema = z
+    .strictObject({
+    edges: z
+        .array(z.array(edgeElement).min(2))
+        .min(1)
+        .describe('Chains of nodes, each a list; `START` begins at least one. A routing map follows the node whose output it routes.'),
+    nodes: z.record(nodeName, workflowNodeSchema).optional(),
+    max_concurrency: z.number().int().positive().optional().describe('Nodes that may run at once. Default: unbounded.'),
+})
+    .describe('Opts into a WORKFLOW: the syndicate as a graph (lib/workflow.ts). Cannot be combined with dispatch.');
 // ── Syndicate ────────────────────────────────────────────────────────────────
 export const syndicateSchema = z
     .strictObject({
@@ -169,6 +295,14 @@ export const syndicateSchema = z
         .optional()
         .describe('The orchestrator\'s team. Omit it (or write `subagents: []`) for a single-agent syndicate.'),
     dispatch: dispatchSchema.optional(),
+    workflow: workflowSchema.optional(),
+    retries: z
+        .strictObject({
+        model_errors: z.number().int().min(0).max(5).optional().describe('Retries of a malformed model reply. Default 2; 0 off.'),
+        tool_errors: z.number().int().min(0).max(5).optional().describe('Retries of a tool that threw, with reflection guidance. Default 3; 0 off.'),
+    })
+        .optional()
+        .describe('Self-correction on model and tool errors (ADK reflect-and-retry plugins). On by default.'),
     variables: z
         .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
         .optional()
@@ -206,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()
@@ -387,19 +521,85 @@ function crossFieldProblems(raw) {
             return;
         }
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
+        // 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)) {
-                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools` });
+            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` });
+            }
+        });
+    };
+    // A skill script run pauses for approval the same way, so it is allowed in
+    // the same places; `skills.tools` may only unlock tools the agent does not
+    // already carry outright.
+    const skillProblems = (agent, path, allowed) => {
+        if (!isObj(agent.skills))
+            return;
+        if (agent.skills.scripts === 'local' && !allowed) {
+            out.push({
+                path: [...path, 'skills', 'scripts'],
+                message: 'skill scripts pause for approval, which only the orchestrator or a plan-dispatch route can do; a delegated subagent cannot pause the turn (ADR 0028)',
+            });
+        }
+        const tools = Array.isArray(agent.tools) ? agent.tools : [];
+        (Array.isArray(agent.skills.tools) ? agent.skills.tools : []).forEach((name, j) => {
+            if (typeof name === 'string' && tools.includes(name)) {
+                out.push({ path: [...path, 'skills', 'tools', j], message: `'${name}' is already in this agent's tools; a skill cannot unlock what is always on` });
             }
         });
     };
+    // ask_user ends the turn waiting for the person, the same pause as an
+    // approval, so it is allowed in the same places (lib/runtime/questions.ts).
+    const questionProblems = (agent, path, allowed) => {
+        const tools = Array.isArray(agent.tools) ? agent.tools : [];
+        const at = tools.indexOf('ask_user');
+        if (at === -1)
+            return;
+        if (isObj(raw.workflow)) {
+            out.push({ path: [...path, 'tools', at], message: 'ask_user is not supported on a workflow node yet; use an ask_user node (workflow.nodes)' });
+        }
+        else if (!allowed) {
+            out.push({ path: [...path, 'tools', at], message: 'ask_user pauses the turn, which only the orchestrator or a plan-dispatch route can do; a delegated subagent cannot' });
+        }
+    };
+    // Execution keys (ADR 0033): where each one means something.
+    const executionProblems = (agent, path, isOrchestrator) => {
+        const model = typeof agent.model === 'string' ? agent.model : isObj(raw.orchestrator) && typeof raw.orchestrator.model === 'string' ? raw.orchestrator.model : '';
+        if (agent.code_execution !== undefined && model && !/^gemini-/.test(model)) {
+            out.push({ path: [...path, 'code_execution'], message: `code_execution: gemini needs a gemini-* model (this agent's is ${model})` });
+        }
+        if (agent.context !== undefined && (!isOrchestrator || isObj(raw.dispatch) || isObj(raw.workflow))) {
+            out.push({
+                path: [...path, 'context'],
+                message: 'context compaction applies to the orchestrator of a delegate syndicate: a dispatch route reads a bounded projection, a workflow node sees only its input, and a subagent starts fresh on every call',
+            });
+        }
+        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);
+    for (const [i, sub] of (Array.isArray(raw.subagents) ? raw.subagents : []).entries())
+        if (isObj(sub))
+            executionProblems(sub, ['subagents', i], false);
+    if (isObj(raw.orchestrator)) {
         gateProblems(raw.orchestrator, ['orchestrator'], true);
+        skillProblems(raw.orchestrator, ['orchestrator'], true);
+        questionProblems(raw.orchestrator, ['orchestrator'], true);
+    }
     const dispatching = isObj(raw.dispatch);
     subs.forEach((sub, i) => {
         if (!isObj(sub))
             return;
         gateProblems(sub, ['subagents', i], dispatching);
+        skillProblems(sub, ['subagents', i], dispatching);
+        questionProblems(sub, ['subagents', i], dispatching);
         const hasRef = typeof sub.yaml_reference === 'string';
         const hasRemote = typeof sub.a2a_agent_url === 'string';
         if (hasRef && hasRemote) {
@@ -427,6 +627,8 @@ function crossFieldProblems(raw) {
             }
         }
     });
+    if (isObj(raw.workflow))
+        out.push(...workflowProblems(raw, subs));
     // Names must be unique across the tree this file declares: two AgentTools
     // with one name collide, and dispatch routes by name.
     const seen = new Map();
@@ -457,6 +659,144 @@ function crossFieldProblems(raw) {
     }
     return out;
 }
+/**
+ * The rules a `workflow:` block must keep (lib/workflow.ts), which a JSON
+ * Schema cannot say: every name is an agent or a declared node, `START`
+ * opens a chain and nothing else, a routing map follows the node it routes,
+ * a declared node is exactly one kind, and the pauses and remotes the graph
+ * cannot carry yet are refused with the reason.
+ */
+function workflowProblems(raw, subs) {
+    const out = [];
+    const wf = raw.workflow;
+    if (isObj(raw.dispatch)) {
+        out.push({ path: ['workflow'], message: 'a syndicate is a workflow or a plan-dispatch router, not both; remove `dispatch`' });
+    }
+    const agentNames = [];
+    if (isObj(raw.orchestrator) && typeof raw.orchestrator.name === 'string')
+        agentNames.push(raw.orchestrator.name);
+    for (const sub of subs)
+        if (isObj(sub) && typeof sub.name === 'string')
+            agentNames.push(sub.name);
+    const nodes = isObj(wf.nodes) ? wf.nodes : {};
+    const declared = Object.keys(nodes);
+    const known = new Set([...agentNames, ...declared]);
+    const mapped = new Set();
+    // Declared nodes: an agent takes modifiers only; anything else is one kind.
+    for (const [name, entry] of Object.entries(nodes)) {
+        if (!isObj(entry))
+            continue;
+        const kinds = NODE_KINDS.filter((k) => entry[k] !== undefined);
+        const isAgent = agentNames.includes(name);
+        if (isAgent && kinds.length > 0) {
+            out.push({ path: ['workflow', 'nodes', name], message: `'${name}' is an agent; its node entry may carry only route_key, retry and timeout` });
+        }
+        else if (!isAgent && kinds.length !== 1) {
+            out.push({ path: ['workflow', 'nodes', name], message: `a declared node is exactly one of ${NODE_KINDS.join(', ')}${kinds.length ? ` (has ${kinds.join(', ')})` : ''}` });
+        }
+        if (name.endsWith(ROUTE_STEP_SUFFIX) || name === START_NAME) {
+            out.push({ path: ['workflow', 'nodes', name], message: `'${name}' is reserved` });
+        }
+        const kind = nodeKind(entry);
+        if (kind === 'map') {
+            const target = entry.map;
+            if (!agentNames.includes(target)) {
+                const hint = suggest(target, agentNames);
+                out.push({ path: ['workflow', 'nodes', name, 'map'], message: `'${target}' is not an agent of this syndicate${hint ? ` (did you mean "${hint}"?)` : ''}` });
+            }
+            else {
+                mapped.add(target);
+            }
+        }
+        if (kind !== 'ask_user' && entry.schema !== undefined) {
+            out.push({ path: ['workflow', 'nodes', name, 'schema'], message: 'schema applies to ask_user only' });
+        }
+        if (kind !== 'map' && entry.max_parallel !== undefined) {
+            out.push({ path: ['workflow', 'nodes', name, 'max_parallel'], message: 'max_parallel applies to map only' });
+        }
+    }
+    for (const name of agentNames) {
+        if (name.endsWith(ROUTE_STEP_SUFFIX))
+            out.push({ path: ['workflow'], message: `agent name '${name}' ends with the reserved suffix ${ROUTE_STEP_SUFFIX}` });
+    }
+    // Edges.
+    const edges = Array.isArray(wf.edges) ? wf.edges : [];
+    let starts = 0;
+    const referenced = new Set();
+    const checkName = (name, path) => {
+        if (known.has(name)) {
+            referenced.add(name);
+            return;
+        }
+        const hint = suggest(name, [...known]);
+        out.push({ path, message: `'${name}' is not an agent or a declared node${hint ? ` (did you mean "${hint}"?)` : ''}` });
+    };
+    edges.forEach((chain, i) => {
+        if (!Array.isArray(chain))
+            return;
+        chain.forEach((element, j) => {
+            const path = ['workflow', 'edges', i, j];
+            if (typeof element === 'string') {
+                if (element === START_NAME) {
+                    if (j !== 0)
+                        out.push({ path, message: 'START opens a chain; it cannot follow a node' });
+                    else
+                        starts++;
+                    return;
+                }
+                checkName(element, path);
+            }
+            else if (Array.isArray(element)) {
+                element.forEach((name, k) => typeof name === 'string' && checkName(name, [...path, k]));
+            }
+            else if (isObj(element)) {
+                const previous = chain[j - 1];
+                if (typeof previous !== 'string' || previous === START_NAME) {
+                    out.push({ path, message: 'a routing map follows the name of the node whose output it routes' });
+                }
+                else if (!agentNames.includes(previous) && nodeKind(nodes[previous]) !== 'tool') {
+                    out.push({ path, message: `'${previous}' is a ${nodeKind(nodes[previous]) ?? 'node'}; only an agent or a tool node emits a route` });
+                }
+                if (j !== chain.length - 1)
+                    out.push({ path, message: 'a routing map ends its chain; start another chain from each target' });
+                for (const [key, target] of Object.entries(element)) {
+                    const targets = Array.isArray(target) ? target : [target];
+                    targets.forEach((name, k) => typeof name === 'string' && checkName(name, [...path, key, k]));
+                }
+            }
+            for (const name of isObj(element) || Array.isArray(element) || typeof element === 'string' ? elementNames(element) : []) {
+                if (mapped.has(name))
+                    out.push({ path, message: `'${name}' is run by a map node; it cannot also appear in an edge` });
+            }
+        });
+    });
+    if (edges.length && starts === 0)
+        out.push({ path: ['workflow', 'edges'], message: `no chain begins with ${START_NAME}` });
+    for (const name of declared) {
+        if (!referenced.has(name) && !agentNames.includes(name))
+            out.push({ path: ['workflow', 'nodes', name], message: 'declared but used in no edge' });
+    }
+    void DEFAULT_ROUTE_KEY;
+    // What a node cannot carry yet (lib/workflow.ts, "Not in this version").
+    const agents = [
+        [['orchestrator'], raw.orchestrator],
+        ...subs.map((sub, i) => [['subagents', i], sub]),
+    ];
+    for (const [path, agent] of agents) {
+        if (!isObj(agent))
+            continue;
+        if (Array.isArray(agent.require_approval) && agent.require_approval.length) {
+            out.push({ path: [...path, 'require_approval'], message: 'approval gates are not supported inside a workflow yet' });
+        }
+        if (isObj(agent.skills) && agent.skills.scripts === 'local') {
+            out.push({ path: [...path, 'skills', 'scripts'], message: 'skill scripts (an approval pause) are not supported inside a workflow yet' });
+        }
+        if (typeof agent.a2a_agent_url === 'string') {
+            out.push({ path: [...path, 'a2a_agent_url'], message: 'a remote agent cannot be a workflow node yet' });
+        }
+    }
+    return out;
+}
 // ── Public API ───────────────────────────────────────────────────────────────
 /**
  * Thrown by validateSyndicateConfig. `problems` holds one `<file>: <path> —

package/dist/lib/toolRegistry.js

@@ -18,6 +18,8 @@ import { WIKI_AGENT_TOOL_CONTRACTS } from './tools/wikiTools.js';
 import { SCIENCE_TOOL_CONTRACTS } from './tools/scienceTools.js';
 import { TASK_TOOL_CONTRACTS } from './tools/taskTools.js';
 import { X_SEARCH } from './tools/xSearchTool.js';
+import { askUserTool } from './runtime/questions.js';
+import { URL_CONTEXT } from './tools/urlContextTool.js';
 import { xApiSearchTool } from './tools/xApiSearchTool.js';
 // Knowledge-bundle tools, derived from their contracts so the YAML names
 // can never drift from the definitions. The agentic composites
@@ -52,6 +54,9 @@ const BUILTIN_TOOLS = {
     // reading (keyless — works on every provider, including local Ollama).
     // augustin.yaml and librarian-style research agents declare it.
     web_extract: webExtractTool,
+    // Gemini reads URLs in the conversation server-side; a no-op (reported as
+    // dropped by the doctor) on other providers. lib/tools/urlContextTool.ts.
+    url_context: URL_CONTEXT,
     x_search: X_SEARCH,
     // X API v2 recent search as a client-side contract, photos transcribed
     // inline — runs on every provider; needs X_BEARER_TOKEN in the server env.
@@ -62,6 +67,10 @@ const BUILTIN_TOOLS = {
     google_search: GOOGLE_SEARCH,
     generate_image: generateImageTool,
     inspect_image: inspectImageTool,
+    // Ask the person mid-turn (lib/runtime/questions.ts): a long-running call
+    // that ends the turn input-required; the next message is its answer. Only
+    // on an agent the turn runs directly (the schema enforces it).
+    ask_user: askUserTool,
     load_memory: LOAD_MEMORY,
     preload_memory: PRELOAD_MEMORY,
 };

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

@@ -0,0 +1,52 @@
+import { BaseTool } from '@google/adk';
+export interface OpenApiAuthConfig {
+    /** Environment variable holding a bearer token (`Authorization: Bearer …`). */
+    bearer_env?: string;
+    /** An API key from an environment variable, sent in a header or the query. */
+    api_key?: {
+        env: string;
+        in: 'header' | 'query';
+        name: string;
+    };
+}
+/** One entry of an agent's `openapi:` list. */
+export interface OpenApiConfig {
+    /** Path to an OpenAPI 3 spec (.yaml, .yml or .json). Relative paths resolve beside the syndicate file. */
+    spec: string;
+    /** Operations to expose, by operationId or tool name. Omitted: every GET operation. */
+    operations?: string[];
+    /** Overrides the spec's `servers[0].url`. */
+    base_url?: string;
+    /** Prepended to every tool name (`<prefix>_<tool>`), to keep two APIs apart. */
+    prefix?: string;
+    auth?: OpenApiAuthConfig;
+}
+/** Characters a single API result may carry into the conversation. */
+export declare const MAX_RESULT_CHARS = 20000;
+/** Marks a tool built here, so require_approval may gate it (lib/compile.ts). */
+export declare const OPENAPI_TOOL: unique symbol;
+/** snake_case, the way ADK names a tool from an operationId. */
+export declare function toSnake(name: string): string;
+/** True when a configured operation name (an operationId or a tool name) names this tool. */
+export declare function namesTool(configured: string, tool: {
+    name: string;
+    operation?: {
+        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;
+/**
+ * The tools one `openapi:` entry gives an agent. Throws (failing the compile)
+ * on a missing spec, an unset auth variable, an operation the spec does not
+ * have, or a server the guard refuses.
+ */
+export declare function buildOpenApiTools(entry: OpenApiConfig, baseDir?: string): Promise<BaseTool[]>;
+/** True for a tool built from an `openapi:` entry. */
+export declare function isOpenApiTool(tool: unknown): boolean;