melchizedek-agents 0.9.0

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

@@ -0,0 +1,21 @@
+/**
+ * inspectImageTool — native ADK FunctionTool for BLIND visual inventory.
+ *
+ * WHY a FunctionTool instead of an AgentTool subagent:
+ *   Same constraint as generateImageTool in reverse — AgentTool converts all
+ *   traffic to text, so image bytes can't ride into a subagent's context.
+ *   A FunctionTool reads the saved file directly and calls the vision model
+ *   itself.
+ *
+ * WHY the inventory prompt is hard-coded here and takes ONLY a file path:
+ *   The whole point of the inventory is that it is blind. An agent that knows
+ *   the spec asked for three amphorae will helpfully "see" three (expectation
+ *   bias). Because this tool's signature accepts nothing but a path, the
+ *   orchestrator CANNOT leak the spec into the inventory even by accident —
+ *   the separation of perception from judgment is enforced by the type
+ *   system, not by good intentions. Judgment happens downstream in the
+ *   SpecAuditor subagent, which sees spec + inventory but never the image.
+ */
+import { FunctionTool } from '@google/adk';
+import { type Schema } from '@google/genai';
+export declare const inspectImageTool: FunctionTool<Schema>;

package/dist/lib/tools/inspectImageTool.js

@@ -0,0 +1,97 @@
+/**
+ * inspectImageTool — native ADK FunctionTool for BLIND visual inventory.
+ *
+ * WHY a FunctionTool instead of an AgentTool subagent:
+ *   Same constraint as generateImageTool in reverse — AgentTool converts all
+ *   traffic to text, so image bytes can't ride into a subagent's context.
+ *   A FunctionTool reads the saved file directly and calls the vision model
+ *   itself.
+ *
+ * WHY the inventory prompt is hard-coded here and takes ONLY a file path:
+ *   The whole point of the inventory is that it is blind. An agent that knows
+ *   the spec asked for three amphorae will helpfully "see" three (expectation
+ *   bias). Because this tool's signature accepts nothing but a path, the
+ *   orchestrator CANNOT leak the spec into the inventory even by accident —
+ *   the separation of perception from judgment is enforced by the type
+ *   system, not by good intentions. Judgment happens downstream in the
+ *   SpecAuditor subagent, which sees spec + inventory but never the image.
+ */
+import { FunctionTool } from '@google/adk';
+import { GoogleGenAI } from '@google/genai';
+import { readFileSync } from 'node:fs';
+import { resolve, extname, sep } from 'node:path';
+const VISION_MODEL = 'gemini-3.7-flash';
+const INVENTORY_PROTOCOL = `You are a blind visual inventory agent. You know NOTHING about what this image was supposed to be, who requested it, or why. Enumerate ONLY what is actually present:
+
+1. SUBJECTS — every distinct subject and object, with EXACT counts.
+2. COMPOSITION — framing, perspective, and placement (foreground / midground / background).
+3. LIGHT — direction, quality, and any notable lighting phenomena.
+4. PALETTE — dominant colors and tonal range.
+5. MEDIUM CUES — photographic, painterly, or rendered qualities; grain, texture, brushwork.
+6. TEXT & ARTIFACTS — any lettering, watermarks, or generation artifacts.
+
+RULES:
+- Counts are exact numbers, never "several".
+- ZERO quality judgments: no "beautiful", no "well-composed", no "striking".
+- ZERO guesses about intent or purpose.
+- If something is genuinely ambiguous, write "uncertain:" and describe what is visible.
+Return a plain, factual, numbered inventory.`;
+export const inspectImageTool = new FunctionTool({
+    name: 'inspect_image',
+    description: 'Performs a BLIND visual inventory of a previously saved image (subjects with exact counts, ' +
+        'composition, light, palette, medium cues, artifacts). Pass ONLY the file path returned by ' +
+        'generate_image — never describe the expected content, or the inventory will be primed.',
+    parameters: {
+        type: 'OBJECT',
+        properties: {
+            image_path: {
+                type: 'STRING',
+                description: 'Path to the saved image, e.g. "outputs/image_1234.png".',
+            },
+        },
+        required: ['image_path'],
+    },
+    execute: async (input) => {
+        const { image_path } = input;
+        console.log(`[InspectTool] Blind inventory requested for: ${image_path}`);
+        // Confine reads to the outputs/ directory — this tool inventories
+        // generated artifacts, not the filesystem. OUTPUTS_DIR env overrides
+        // the cwd default (must match generateImageTool's).
+        const outputsDir = process.env.OUTPUTS_DIR
+            ? resolve(process.env.OUTPUTS_DIR)
+            : resolve(process.cwd(), 'outputs');
+        const fullPath = resolve(process.cwd(), image_path);
+        if (!fullPath.startsWith(outputsDir + sep)) {
+            throw new Error('inspect_image only reads files under outputs/');
+        }
+        const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_GENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('Gemini API Key is not configured (neither GEMINI_API_KEY nor GOOGLE_GENAI_API_KEY was found in environment).');
+        }
+        const bytes = readFileSync(fullPath);
+        const ext = extname(fullPath).slice(1).toLowerCase() || 'png';
+        const mimeType = `image/${ext === 'jpg' ? 'jpeg' : ext}`;
+        const ai = new GoogleGenAI({ apiKey });
+        console.log(`[InspectTool] Sending image (${bytes.length} bytes, ${mimeType}) to ${VISION_MODEL}...`);
+        const response = await ai.models.generateContent({
+            model: VISION_MODEL,
+            contents: [
+                {
+                    role: 'user',
+                    parts: [
+                        { inlineData: { mimeType, data: bytes.toString('base64') } },
+                        { text: INVENTORY_PROTOCOL },
+                    ],
+                },
+            ],
+        });
+        const text = response.candidates?.[0]?.content?.parts
+            ?.map((p) => p.text ?? '')
+            .join('') ?? '';
+        if (!text) {
+            throw new Error('inspect_image: vision model returned no text inventory.');
+        }
+        console.log(`[InspectTool] Inventory received (${text.length} chars).`);
+        return `BLIND INVENTORY of ${image_path}:\n${text}`;
+    },
+});

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

@@ -0,0 +1,2 @@
+import { FunctionTool } from '@google/adk';
+export declare function createMcpTools(mcpServerUrl: string): Promise<FunctionTool[]>;

package/dist/lib/tools/mcpToolFactory.js

@@ -0,0 +1,116 @@
+import { FunctionTool } from '@google/adk';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+// Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
+// config. Restrict the schemes we'll dial and block private/loopback/link-local
+// hosts so a malicious config can't reach internal services or the cloud
+// metadata endpoint. Set ALLOW_PRIVATE_MCP=true to permit private hosts in
+// local development (where MCP servers commonly run on localhost).
+function assertSafeMcpUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`Invalid MCP server URL: ${raw}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`Unsupported MCP URL scheme: ${url.protocol}`);
+    }
+    if (process.env.ALLOW_PRIVATE_MCP === 'true')
+        return url;
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const isPrivate = host === 'localhost' ||
+        host === '0.0.0.0' ||
+        host === '::1' ||
+        host.endsWith('.localhost') ||
+        host.endsWith('.internal') ||
+        /^127\./.test(host) ||
+        /^10\./.test(host) ||
+        /^192\.168\./.test(host) ||
+        /^169\.254\./.test(host) || // link-local incl. 169.254.169.254 metadata
+        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+        /^fc/.test(host) || /^fd/.test(host) || /^fe80:/.test(host); // IPv6 ULA/link-local
+    if (isPrivate) {
+        throw new Error(`Refusing to connect to private/loopback MCP host: ${host} (set ALLOW_PRIVATE_MCP=true for local dev)`);
+    }
+    return url;
+}
+export async function createMcpTools(mcpServerUrl) {
+    try {
+        const transport = new SSEClientTransport(assertSafeMcpUrl(mcpServerUrl));
+        const client = new Client({
+            name: 'melchizedek-a2a-client',
+            version: '1.0.0'
+        }, {
+            capabilities: {}
+        });
+        await client.connect(transport);
+        // Fetch available tools from the MCP server
+        const toolsResponse = await client.listTools();
+        // MCP servers describe tools in standard lowercase JSON Schema; the ADK
+        // is Gemini-native and expects UPPERCASE type names. Uppercase deeply,
+        // preserving enum/description/required and nested properties/items —
+        // non-Gemini adapters normalize back to lowercase at request-build time
+        // via lib/models/schemaNormalize.ts.
+        const toGeminiSchema = (node) => {
+            if (Array.isArray(node))
+                return node.map(toGeminiSchema);
+            if (!node || typeof node !== 'object')
+                return node;
+            const out = {};
+            for (const [key, value] of Object.entries(node)) {
+                if (key === 'type') {
+                    out[key] = typeof value === 'string' ? value.toUpperCase() : value;
+                }
+                else if (key === 'enum' || key === 'required') {
+                    out[key] = value; // value lists, not schema nodes
+                }
+                else {
+                    out[key] = toGeminiSchema(value);
+                }
+            }
+            return out;
+        };
+        return toolsResponse.tools.map(tool => {
+            const properties = {};
+            const required = tool.inputSchema?.required || [];
+            if (tool.inputSchema?.properties) {
+                for (const [key, prop] of Object.entries(tool.inputSchema.properties)) {
+                    properties[key] = toGeminiSchema({
+                        ...prop,
+                        type: prop.type ?? 'string',
+                        description: prop.description || ''
+                    });
+                }
+            }
+            return new FunctionTool({
+                name: tool.name,
+                description: tool.description || `MCP Tool: ${tool.name}`,
+                parameters: {
+                    type: 'OBJECT',
+                    properties,
+                    required
+                },
+                execute: async (input) => {
+                    try {
+                        const result = await client.callTool({
+                            name: tool.name,
+                            arguments: input
+                        });
+                        const content = result.content;
+                        const texts = content.filter(c => c.type === 'text').map(c => c.text ?? '');
+                        return texts.join('\n');
+                    }
+                    catch (error) {
+                        return `[MCP ERROR] Tool ${tool.name} failed: ${error.message}`;
+                    }
+                }
+            });
+        });
+    }
+    catch (error) {
+        console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error);
+        return [];
+    }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * lib/tools/toolContract.ts — define a tool ONCE, serve it anywhere.
+ *
+ * WHY this file exists:
+ *   A native tool that should be reachable both by our own agents (ADK
+ *   FunctionTool, Gemini-dialect Schema) and by outside MCP clients
+ *   (standard JSON Schema in tools/list) previously needed its schema
+ *   hand-written twice — two dialects of the same contract, guaranteed to
+ *   drift. Here a tool is one object — name, description, zod schema,
+ *   execute — and thin adapters DERIVE each deployment surface:
+ *
+ *     defineTool(...) ──► toFunctionTool()       ADK / syndicate agents
+ *                    └──► toMcpToolDefinition()  MCP tools/list entry
+ *
+ *   The zod schema is the single source of truth. zod v4's native
+ *   z.toJSONSchema() emits standard JSON Schema (what MCP and every
+ *   non-Gemini provider natively want); toGeminiSchema() below derives the
+ *   ADK dialect from it — the exact inverse of the request-time bridge in
+ *   lib/models/schemaNormalize.ts, which keeps lowercasing FunctionTool
+ *   schemas for Anthropic/OpenAI/xAI/Ollama and is unaffected by this file.
+ *
+ *   DELIBERATELY NOT HERE: exposure. Defining a contract publishes nothing.
+ *   An agent sees the tool only when its name is added to TOOL_MAP in
+ *   lib/toolRegistry.ts AND declared in the syndicate YAML; an MCP client
+ *   sees it only when a server script explicitly lists it (see
+ *   scripts/financial_mcp_server.ts). Both remain deliberate acts.
+ */
+import { FunctionTool } from '@google/adk';
+import { z } from 'zod';
+export interface ToolContract<S extends z.ZodType = z.ZodType> {
+    name: string;
+    /** LLM-facing prompt text, not developer docs — it steers when agents call the tool. */
+    description: string;
+    /** Single source of truth for the input shape; both wire dialects derive from it. */
+    schema: S;
+    execute: (input: z.infer<S>) => Promise<string>;
+}
+/** Identity helper whose only job is inferring the execute() input type from the schema. */
+export declare function defineTool<S extends z.ZodType>(contract: ToolContract<S>): ToolContract<S>;
+/**
+ * Validate args against the contract's schema and run it. Validation failure
+ * returns an error STRING (never throws) so the calling model sees what to
+ * fix and can retry — the same convention the hand-written tools used for
+ * upstream API failures. Unknown keys are stripped by zod's default object
+ * behavior.
+ */
+export declare function executeContract(contract: ToolContract<any>, args: unknown): Promise<string>;
+/**
+ * Standard JSON Schema for the contract's input — the canonical dialect
+ * (MCP inputSchema; also what four of our five providers natively accept).
+ * `$schema` is dropped: it's metadata about the document, noise on the wire.
+ */
+export declare function toStandardJsonSchema(contract: ToolContract<any>): Record<string, unknown>;
+/**
+ * Standard JSON Schema → Gemini/ADK dialect. The inverse of
+ * schemaNormalize.toLowercaseJsonSchema(): every `type` value is UPPERCASED
+ * ('object' → 'OBJECT'). Also drops keywords the Gemini API rejects or
+ * ignores: `additionalProperties` (zod emits it on every object) and
+ * `default` (defaults are applied by zod at parse time, not by the model).
+ * `enum` and `required` are value lists, copied verbatim.
+ */
+export declare function toGeminiSchema(jsonSchema: unknown): Record<string, unknown>;
+/**
+ * ADK surface: a live FunctionTool whose Gemini-dialect parameters are
+ * derived from the zod schema and whose execute() zod-validates its input.
+ * Non-Gemini providers keep receiving this schema through
+ * schemaNormalize.toLowercaseJsonSchema() at request-build time, unchanged.
+ */
+export declare function toFunctionTool(contract: ToolContract<any>): FunctionTool;
+/**
+ * MCP surface: a tools/list entry. Pair with executeContract() in the
+ * server's CallTool handler — see scripts/financial_mcp_server.ts.
+ */
+export declare function toMcpToolDefinition(contract: ToolContract<any>): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};

package/dist/lib/tools/toolContract.js

@@ -0,0 +1,129 @@
+/**
+ * lib/tools/toolContract.ts — define a tool ONCE, serve it anywhere.
+ *
+ * WHY this file exists:
+ *   A native tool that should be reachable both by our own agents (ADK
+ *   FunctionTool, Gemini-dialect Schema) and by outside MCP clients
+ *   (standard JSON Schema in tools/list) previously needed its schema
+ *   hand-written twice — two dialects of the same contract, guaranteed to
+ *   drift. Here a tool is one object — name, description, zod schema,
+ *   execute — and thin adapters DERIVE each deployment surface:
+ *
+ *     defineTool(...) ──► toFunctionTool()       ADK / syndicate agents
+ *                    └──► toMcpToolDefinition()  MCP tools/list entry
+ *
+ *   The zod schema is the single source of truth. zod v4's native
+ *   z.toJSONSchema() emits standard JSON Schema (what MCP and every
+ *   non-Gemini provider natively want); toGeminiSchema() below derives the
+ *   ADK dialect from it — the exact inverse of the request-time bridge in
+ *   lib/models/schemaNormalize.ts, which keeps lowercasing FunctionTool
+ *   schemas for Anthropic/OpenAI/xAI/Ollama and is unaffected by this file.
+ *
+ *   DELIBERATELY NOT HERE: exposure. Defining a contract publishes nothing.
+ *   An agent sees the tool only when its name is added to TOOL_MAP in
+ *   lib/toolRegistry.ts AND declared in the syndicate YAML; an MCP client
+ *   sees it only when a server script explicitly lists it (see
+ *   scripts/financial_mcp_server.ts). Both remain deliberate acts.
+ */
+import { FunctionTool } from '@google/adk';
+import { z } from 'zod';
+/** Identity helper whose only job is inferring the execute() input type from the schema. */
+export function defineTool(contract) {
+    return contract;
+}
+/**
+ * Validate args against the contract's schema and run it. Validation failure
+ * returns an error STRING (never throws) so the calling model sees what to
+ * fix and can retry — the same convention the hand-written tools used for
+ * upstream API failures. Unknown keys are stripped by zod's default object
+ * behavior.
+ */
+export async function executeContract(contract, args) {
+    const parsed = contract.schema.safeParse(args ?? {});
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        return `Error: invalid arguments for ${contract.name}: ${issues}`;
+    }
+    return contract.execute(parsed.data);
+}
+/**
+ * Standard JSON Schema for the contract's input — the canonical dialect
+ * (MCP inputSchema; also what four of our five providers natively accept).
+ * `$schema` is dropped: it's metadata about the document, noise on the wire.
+ */
+export function toStandardJsonSchema(contract) {
+    const { $schema: _drop, ...schema } = z.toJSONSchema(contract.schema);
+    return schema;
+}
+/**
+ * Standard JSON Schema → Gemini/ADK dialect. The inverse of
+ * schemaNormalize.toLowercaseJsonSchema(): every `type` value is UPPERCASED
+ * ('object' → 'OBJECT'). Also drops keywords the Gemini API rejects or
+ * ignores: `additionalProperties` (zod emits it on every object) and
+ * `default` (defaults are applied by zod at parse time, not by the model).
+ * `enum` and `required` are value lists, copied verbatim.
+ */
+export function toGeminiSchema(jsonSchema) {
+    const result = geminiNode(jsonSchema);
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        return result;
+    }
+    return { type: 'OBJECT', properties: {} };
+}
+function geminiNode(node) {
+    if (Array.isArray(node))
+        return node.map(geminiNode);
+    if (!node || typeof node !== 'object')
+        return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'additionalProperties' || key === 'default' || key === '$schema') {
+            continue;
+        }
+        else if (key === 'type') {
+            if (typeof value === 'string') {
+                out[key] = value.toUpperCase();
+            }
+            else if (Array.isArray(value)) {
+                out[key] = value.map((v) => (typeof v === 'string' ? v.toUpperCase() : v));
+            }
+            else {
+                out[key] = value;
+            }
+        }
+        else if (key === 'enum' || key === 'required') {
+            out[key] = Array.isArray(value) ? [...value] : value;
+        }
+        else {
+            out[key] = geminiNode(value);
+        }
+    }
+    return out;
+}
+/**
+ * ADK surface: a live FunctionTool whose Gemini-dialect parameters are
+ * derived from the zod schema and whose execute() zod-validates its input.
+ * Non-Gemini providers keep receiving this schema through
+ * schemaNormalize.toLowercaseJsonSchema() at request-build time, unchanged.
+ */
+export function toFunctionTool(contract) {
+    return new FunctionTool({
+        name: contract.name,
+        description: contract.description,
+        parameters: toGeminiSchema(toStandardJsonSchema(contract)),
+        execute: (input) => executeContract(contract, input),
+    });
+}
+/**
+ * MCP surface: a tools/list entry. Pair with executeContract() in the
+ * server's CallTool handler — see scripts/financial_mcp_server.ts.
+ */
+export function toMcpToolDefinition(contract) {
+    return {
+        name: contract.name,
+        description: contract.description,
+        inputSchema: toStandardJsonSchema(contract),
+    };
+}

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

@@ -0,0 +1,70 @@
+/**
+ * lib/tools/webExtractTool.ts — deterministic URL → clean-text reading.
+ *
+ * WHY this file exists:
+ *   `web_search` routes to each provider's SERVER-SIDE search (§7.5): the
+ *   provider decides which pages to fetch and which snippets to quote. An
+ *   agent could never say "now read THIS article in full" — for a news
+ *   agent that is the difference between arbitrating what a search chose
+ *   to quote and actually reading the five articles being compared.
+ *   `web_extract` closes that gap: a plain client-side function tool that
+ *   fetches given URLs and returns the page's clean text. Deterministic,
+ *   no LLM summarization, and KEYLESS — it also works on local Ollama
+ *   agents, the first web capability local mode gets.
+ *
+ * DESIGN (cribbed from NousResearch/hermes-agent `web_extract`, adapted):
+ *   - Up to 5 URLs per call; per-page character budget (default 15k,
+ *     WEB_EXTRACT_CHAR_LIMIT env, clamped 2k–500k — deployment config,
+ *     never YAML, the XAI_COLLECTION_IDS doctrine).
+ *   - Over-budget pages return a head+tail window (~75%/25%) with an
+ *     omission marker. Hermes spills full text to disk and tells the
+ *     agent to page with read_file; melchizedek agents have no filesystem
+ *     tools, so paging is an `offset` param instead: the full text is
+ *     held in a 15-minute in-process cache and re-calling with
+ *     `{urls:[same], offset:N}` continues reading without refetching.
+ *   - Zero new dependencies: native fetch + a heuristic HTML→markdown
+ *     pipeline (strip script/style/nav chrome, prefer <article>/<main>,
+ *     headings/lists/links/blockquotes to markdown, entities decoded,
+ *     base64 images never survive because <img> collapses to alt text).
+ *
+ * SECURITY (SSRF):
+ *   Agents pass arbitrary URLs and this process may run server-side
+ *   (A2A on Heroku), so http(s)-only plus a literal-host guard: loopback,
+ *   RFC-1918, link-local/metadata (169.254.*), CGNAT, ULA/IPv6-local and
+ *   localhost-ish hostnames are refused, and redirects are followed
+ *   manually so every hop is re-checked. Deliberate v1 limit: the guard
+ *   inspects literals only — it does not resolve DNS, so a public
+ *   hostname that resolves privately can still slip; acceptable for a
+ *   tool that runs with no ambient credentials, revisit if that changes.
+ *
+ * FAILURE CONTRACT: never throws. Each URL yields either its content
+ *   block or an inline `Error:` block; one bad URL never sinks the rest.
+ */
+import { z } from 'zod';
+export declare const WEB_EXTRACT_TOOL_NAME = "web_extract";
+/** Per-page char budget from the environment; malformed values warn and fall back. */
+export declare function extractCharLimit(): number;
+/** Reason the host is refused, or null when it looks routable. Literals only — see header. */
+export declare function blockedHostReason(hostname: string): string | null;
+export declare function decodeEntities(text: string): string;
+export interface ExtractedPage {
+    title: string | null;
+    text: string;
+}
+export declare function extractHtml(html: string): ExtractedPage;
+/**
+ * Reason the extraction looks like a block page rather than content, or
+ * null when it looks legitimate. `htmlBytes` is the raw document size —
+ * the thinness check needs it to tell "big page, no text" (a JS shell)
+ * from a genuinely small page, which stays valid.
+ */
+export declare function blockedPageReason(text: string, htmlBytes: number): string | null;
+export declare function windowContent(text: string, url: string, limit: number, offset?: number): string;
+/** Test hook — the cache is process-global. */
+export declare function clearWebExtractCache(): void;
+export declare const webExtractContract: import("./toolContract.ts").ToolContract<z.ZodObject<{
+    urls: z.ZodArray<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+/** ADK surface, ready for the registry. */
+export declare const webExtractTool: import("@google/adk").FunctionTool<undefined>;