melchizedek-agents 0.16.2 → 0.17.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,
@@ -104,6 +154,30 @@ const agentFields = {
         .string()
         .optional()
         .describe('MCP server (SSE) whose tools are discovered at runtime and merged with `tools`.'),
+    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 +233,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 +285,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()
@@ -387,19 +511,80 @@ function crossFieldProblems(raw) {
             return;
         }
         const tools = Array.isArray(agent.tools) ? agent.tools : [];
+        // An OpenAPI operation can be gated once it is named under `operations`.
+        const operations = (Array.isArray(agent.openapi) ? agent.openapi : []).flatMap((e) => (isObj(e) && Array.isArray(e.operations) ? e.operations : []));
         (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)) {
+                out.push({ path: [...path, 'require_approval', j], message: `'${name}' is not in this agent's tools or its openapi operations` });
             }
         });
     };
+    // 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 (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 +612,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 +644,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/openapiTools.d.ts

@@ -0,0 +1,46 @@
+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;
+/** 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;

package/dist/lib/tools/openapiTools.js

@@ -0,0 +1,195 @@
+/**
+ * lib/tools/openapiTools.ts — any HTTP API with an OpenAPI spec becomes an
+ * agent's tools, from YAML.
+ *
+ * WHY: "Bring your own API" was a code task: write a `defineTool` per
+ * endpoint, register it, name it in YAML. ADK 2.2 ships `OpenAPIToolset`,
+ * which turns an OpenAPI 3 spec into one tool per operation (parameters and
+ * request body as the tool's schema, the operation's summary as its
+ * description). An agent's `openapi:` list hands it a spec file:
+ *
+ *   openapi:
+ *     - spec: "specs/weather.yaml"          # beside this YAML file
+ *       operations: [getForecast]           # omitted: the GET operations only
+ *       auth: { api_key: { env: "WEATHER_KEY", in: "header", name: "X-Api-Key" } }
+ *
+ * WHAT THE ENGINE ADDS to ADK's toolset, all of it exposure discipline:
+ *   - READ-ONLY BY DEFAULT. Without `operations`, only GET operations become
+ *     tools; anything that writes is exposed only by naming it, and a named
+ *     operation can be listed under `require_approval` like a registry tool
+ *     (ADR 0028), so a POST or a DELETE can wait for a person.
+ *   - SECRETS FROM THE ENVIRONMENT. `auth` names an environment variable,
+ *     never a value; a variable that is not set fails the compile, so an
+ *     agent never runs half-authenticated.
+ *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
+ *     and pass lib/net/addressGuard.ts: its literal rules at compile time
+ *     (offline), and the full check with DNS before each call (a name can
+ *     re-resolve between calls). ALLOW_PRIVATE_OPENAPI=true permits
+ *     private hosts for local development, as ALLOW_PRIVATE_MCP does for MCP.
+ *     The model chooses arguments, never the host: path parameters are
+ *     URL-encoded by ADK and dot segments refused.
+ *   - REDIRECTS HELD TO THE SAME GUARD. ADK calls globalThis.fetch, which
+ *     follows redirects; a call runs under lib/net/redirects.ts instead, so
+ *     each hop is checked before it is fetched. A hop on the same origin
+ *     gets the server's own check; a hop to another origin must pass the
+ *     full guard even with ALLOW_PRIVATE_OPENAPI (that permits the server
+ *     you configured, not wherever it points), and loses every header but
+ *     content negotiation, credentials included.
+ *   - BOUNDED RESULTS. A response larger than MAX_RESULT_CHARS is cut and
+ *     says so; a network failure comes back as `{ error }`, never a throw.
+ *
+ * Spec files only, never URLs: a spec fetched at compile time would be a
+ * second outbound surface, and a spec that changes under a running agent
+ * changes its tools. Save the spec beside the YAML and review it like code.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { OpenAPIToolset, tokenToSchemeCredential } from '@google/adk';
+import { blockedHostReason, checkHost } from '../net/addressGuard.js';
+import { withRedirectGuard } from '../net/redirects.js';
+/** Characters a single API result may carry into the conversation. */
+export const MAX_RESULT_CHARS = 20_000;
+/** Marks a tool built here, so require_approval may gate it (lib/compile.ts). */
+export const OPENAPI_TOOL = Symbol.for('melchizedek.openapiTool');
+/** snake_case, the way ADK names a tool from an operationId. */
+export function toSnake(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+/** True when a configured operation name (an operationId or a tool name) names this tool. */
+export function namesTool(configured, tool) {
+    return configured === tool.name || configured === tool.operation?.operationId || toSnake(configured) === tool.name;
+}
+/**
+ * Why a server may not be called, or null. At compile time only the literal
+ * rules apply (no connection is made, and a build must not need DNS); before
+ * each call the name is resolved too, which guards the connection itself.
+ */
+async function hostProblem(baseUrl, resolve) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return `'${baseUrl}' is not a URL`;
+    }
+    if (!/^https?:$/.test(url.protocol))
+        return `'${baseUrl}' must be http(s)`;
+    if (process.env.ALLOW_PRIVATE_OPENAPI === 'true')
+        return null;
+    const reason = resolve ? await checkHost(url.hostname) : blockedHostReason(url.hostname);
+    return reason ? `refusing ${url.hostname}: ${reason} (set ALLOW_PRIVATE_OPENAPI=true for local development)` : null;
+}
+function credentialFor(auth, spec) {
+    if (!auth)
+        return {};
+    const read = (env) => {
+        const value = process.env[env]?.trim();
+        if (!value)
+            throw new Error(`openapi ${spec}: ${env} is not set (auth reads it from the environment)`);
+        return value;
+    };
+    if (auth.bearer_env) {
+        const [authScheme, authCredential] = tokenToSchemeCredential('oauth2Token', undefined, undefined, read(auth.bearer_env));
+        return { authScheme, authCredential };
+    }
+    if (auth.api_key) {
+        const [authScheme, authCredential] = tokenToSchemeCredential('apikey', auth.api_key.in, auth.api_key.name, read(auth.api_key.env));
+        return { authScheme, authCredential };
+    }
+    return {};
+}
+/**
+ * Where an API call may be redirected: the server's own rule on its origin,
+ * the full guard (no development exception) anywhere else.
+ */
+const REDIRECTS = {
+    async hopProblem(url, crossOrigin) {
+        if (!/^https?:$/.test(url.protocol))
+            return `${url.protocol} is not http(s)`;
+        if (!crossOrigin)
+            return hostProblem(url.href, true);
+        const reason = await checkHost(url.hostname);
+        return reason ? `refusing ${url.hostname}: ${reason}` : null;
+    },
+};
+/** Cut an API result to MAX_RESULT_CHARS, saying so. */
+export function boundResult(result) {
+    const text = typeof result === 'string' ? result : JSON.stringify(result ?? null);
+    if (text.length <= MAX_RESULT_CHARS)
+        return result;
+    return { truncated: true, text: `${text.slice(0, MAX_RESULT_CHARS)}… [cut at ${MAX_RESULT_CHARS} characters]` };
+}
+/**
+ * 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 async function buildOpenApiTools(entry, baseDir = process.cwd()) {
+    const specPath = resolve(baseDir, entry.spec);
+    if (!existsSync(specPath))
+        throw new Error(`openapi: spec not found: ${entry.spec}`);
+    const ext = extname(specPath).toLowerCase();
+    if (!['.yaml', '.yml', '.json'].includes(ext))
+        throw new Error(`openapi ${entry.spec}: a spec is .yaml, .yml or .json`);
+    const toolset = new OpenAPIToolset({
+        specStr: readFileSync(specPath, 'utf-8'),
+        specType: ext === '.json' ? 'json' : 'yaml',
+        ...(entry.prefix ? { prefix: entry.prefix } : {}),
+        ...credentialFor(entry.auth, entry.spec),
+    });
+    const all = (await toolset.getTools());
+    let chosen;
+    if (entry.operations?.length) {
+        const unknown = entry.operations.filter((op) => !all.some((t) => namesTool(op, t) || namesTool(op, { name: t.name.replace(`${entry.prefix}_`, ''), operation: t.operation })));
+        if (unknown.length) {
+            throw new Error(`openapi ${entry.spec}: no operation ${unknown.map((u) => `'${u}'`).join(', ')} (the spec has ${all.map((t) => t.operation?.operationId ?? t.name).join(', ')})`);
+        }
+        chosen = all.filter((t) => entry.operations.some((op) => namesTool(op, t) || namesTool(op, { name: t.name.replace(`${entry.prefix}_`, ''), operation: t.operation })));
+    }
+    else {
+        chosen = all.filter((t) => t.endpoint.method.toLowerCase() === 'get');
+    }
+    if (entry.base_url)
+        for (const t of chosen)
+            t.endpoint.baseUrl = entry.base_url;
+    for (const baseUrl of new Set(chosen.map((t) => t.endpoint.baseUrl))) {
+        if (!baseUrl)
+            throw new Error(`openapi ${entry.spec}: the spec names no server; set base_url`);
+        const problem = await hostProblem(baseUrl, false);
+        if (problem)
+            throw new Error(`openapi ${entry.spec}: ${problem}`);
+    }
+    return chosen.map(guarded);
+}
+/**
+ * A copy of a generated tool whose call re-checks its host, follows
+ * redirects only where the guard allows, catches a network failure, and
+ * bounds the result. The original is untouched.
+ */
+function guarded(tool) {
+    const copy = Object.create(tool);
+    const original = tool.runAsync.bind(tool);
+    Object.defineProperty(copy, OPENAPI_TOOL, { value: true });
+    Object.defineProperty(copy, 'runAsync', {
+        value: async (request) => {
+            const problem = await hostProblem(tool.endpoint.baseUrl, true);
+            if (problem)
+                return { error: `${tool.name} was not called: ${problem}` };
+            try {
+                return boundResult(await withRedirectGuard(REDIRECTS, () => original(request)));
+            }
+            catch (err) {
+                return { error: `${tool.name} failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
+    });
+    return copy;
+}
+/** True for a tool built from an `openapi:` entry. */
+export function isOpenApiTool(tool) {
+    return !!tool && typeof tool === 'object' && tool[OPENAPI_TOOL] === true;
+}