@cleocode/core 2026.6.13 → 2026.6.15

package/dist/tools/mcp-agent-tool.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Native MCP client (fan-IN) agent tool — connect-time `listTools` → register each
+ * remote tool into the {@link ./agent-registry.js | AgentToolRegistry}
+ * (T11948 · M7 · epic T11456 · SG-TOOLS · satisfies T11593 EP-MCP-HOST-FANIN + T1746).
+ *
+ * Where the runtime gateway is the MCP *server* (fan-OUT: it EXPOSES cleo ops as
+ * MCP tools), this is the MCP *client* (fan-IN: it CONNECTS to an external MCP
+ * server and PULLS its tools into cleo's own agent loop). On connect the client
+ * performs the MCP handshake (`initialize` → `tools/list`) and registers EACH
+ * remote tool as a proxy {@link AgentToolDescriptor} BEFORE the registry is frozen
+ * (init-time fan-in). Each proxy tool's `execute` issues a `tools/call` over the
+ * SAME transport and formats the result for the loop; a transport failure becomes a
+ * typed result (the executable NEVER throws — the frozen ToolDispatchEngine is
+ * unchanged).
+ *
+ * This REPLACES the external mcp-tool dependency for the host-loop path. It is a
+ * deliberately-minimal native client — NO external MCP SDK dependency: the wire is
+ * the standard MCP JSON-RPC ({@link McpTransport}), with stdio / SSE / HTTP
+ * transports as concrete {@link McpTransport} implementations. Placed in `core` per
+ * the package boundary (consumed by the harness, never redefined there — Gate-11).
+ *
+ * ## Availability (AC — live-connection only)
+ *
+ * A fan-in tool is available ONLY while its MCP server connection is live. The
+ * client exposes an {@link McpConnection.isLive} cell that each proxy tool's
+ * {@link AvailabilityCheck} reads; once the connection closes (or its transport
+ * errors fatally), the proxy tools report unavailable rather than dispatching into
+ * a dead transport.
+ *
+ * ## Gate-13
+ *
+ * No model/transport/provider LLM client is constructed here — the MCP transport
+ * speaks the tool protocol, not an LLM wire. There is no chokepoint concern.
+ *
+ * @epic T11456
+ * @task T11948
+ * @see ../../runtime/src/gateway/mcp/types.ts — the MCP server (fan-out) wire types this mirrors
+ * @see ./exec-code-agent-tool.js — the injectable-seam + self-registering-marker pattern mirrored here
+ */
+import type { AgentToolDescriptor, AgentToolRegistry } from './agent-registry.js';
+/** JSON Schema property descriptor for a single remote-tool input field. */
+export interface McpInputProperty {
+    /** JSON Schema primitive type (`'string'`, `'number'`, …). */
+    readonly type: string;
+    /** Human-readable description. */
+    readonly description?: string;
+    /** Allowed values (JSON Schema `enum`). */
+    readonly enum?: readonly string[];
+}
+/**
+ * MCP remote-tool definition (minimal subset — no external MCP SDK dependency).
+ * The shape returned by an MCP server's `tools/list`.
+ */
+export interface McpRemoteTool {
+    /** Stable remote tool name. */
+    readonly name: string;
+    /** Human-readable description. */
+    readonly description?: string;
+    /** JSON Schema for the tool's input parameters. */
+    readonly inputSchema?: {
+        readonly type?: string;
+        readonly properties?: Readonly<Record<string, McpInputProperty>>;
+        readonly required?: readonly string[];
+    };
+}
+/** A single content block returned by an MCP `tools/call`. */
+export interface McpContent {
+    readonly type: string;
+    readonly text?: string;
+}
+/** Result returned by an MCP `tools/call`. */
+export interface McpToolCallResult {
+    readonly content?: readonly McpContent[];
+    readonly isError?: boolean;
+}
+/**
+ * The wire seam every MCP transport implements: issue a JSON-RPC `method` with
+ * `params` and resolve the typed `result`. The stdio / SSE / HTTP transports are
+ * concrete implementations; the unit test injects an in-memory fake. The transport
+ * owns framing + correlation — this module only speaks MCP methods over it.
+ */
+export interface McpTransport {
+    /**
+     * Send an MCP JSON-RPC request and resolve its `result`.
+     *
+     * @param method - The MCP method (`'initialize'`, `'tools/list'`, `'tools/call'`).
+     * @param params - The method params.
+     * @returns The JSON-RPC `result` payload.
+     * @throws When the transport is dead or the server returns a JSON-RPC error.
+     */
+    request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** Close the transport (idempotent). After close, {@link request} rejects. */
+    close(): Promise<void>;
+}
+/** Transport kinds a native MCP client connection can speak over. */
+export declare const MCP_TRANSPORT_KINDS: readonly ["stdio", "sse", "http"];
+/** One supported {@link MCP_TRANSPORT_KINDS} value. */
+export type McpTransportKind = (typeof MCP_TRANSPORT_KINDS)[number];
+/**
+ * A live MCP client connection: a transport + the liveness cell the proxy tools'
+ * availability predicate reads. Produced by {@link connectMcpServer}.
+ */
+export interface McpConnection {
+    /** A stable server name used to namespace the fan-in tool names. */
+    readonly serverName: string;
+    /** The underlying transport. */
+    readonly transport: McpTransport;
+    /** The remote tools discovered at connect (`tools/list`). */
+    readonly tools: readonly McpRemoteTool[];
+    /** `true` while the connection is live; flips `false` on {@link disconnect}. */
+    isLive(): boolean;
+    /** Close the transport and flip the liveness cell to `false`. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Perform the MCP handshake over `transport` and discover its tools: send
+ * `initialize`, then `tools/list`. Returns a live {@link McpConnection} whose
+ * liveness cell is `true` until {@link McpConnection.disconnect}. The transport is
+ * supplied by the caller (so stdio / SSE / HTTP — or an in-memory fake — all flow
+ * through the same path).
+ *
+ * @param serverName - Stable name to namespace this server's fan-in tools.
+ * @param transport - The MCP transport to handshake over.
+ * @returns The connected {@link McpConnection}.
+ * @throws When `initialize` or `tools/list` fails (the connection is not live).
+ */
+export declare function connectMcpServer(serverName: string, transport: McpTransport): Promise<McpConnection>;
+/**
+ * The namespaced agent-tool name for a remote MCP tool: `mcp_<server>_<tool>`. So
+ * two servers exposing a same-named tool never collide in the registry.
+ *
+ * @param serverName - The MCP server's stable name.
+ * @param toolName - The remote tool's name.
+ * @returns The namespaced, registry-unique tool name.
+ */
+export declare function mcpToolName(serverName: string, toolName: string): string;
+/**
+ * Build the proxy {@link AgentToolDescriptor} for ONE remote tool over a live
+ * connection. Its `execute` issues `tools/call` over the connection's transport
+ * and formats the result; a transport / server error becomes a typed result (never
+ * throws). Its availability returns `true` only while the connection is live.
+ *
+ * @param conn - The live MCP connection.
+ * @param tool - The remote tool to proxy.
+ * @returns The proxy descriptor to register.
+ */
+export declare function buildMcpProxyTool(conn: McpConnection, tool: McpRemoteTool): AgentToolDescriptor;
+/**
+ * Register every fan-in proxy tool for a live MCP connection into `registry`. Pure
+ * registration over an ALREADY-connected {@link McpConnection} — the connect /
+ * `tools/list` happened in {@link connectMcpServer} (which the host calls at
+ * init-time, before the registry is frozen). Each remote tool becomes one proxy
+ * descriptor (AC1); each is hidden once the connection drops (AC — live-only).
+ *
+ * @param registry - The registry to populate (must not yet be frozen).
+ * @param conn - The live MCP connection whose tools to fan in.
+ * @returns The registered proxy tool names.
+ */
+export declare function registerMcpConnectionTools(registry: AgentToolRegistry, conn: McpConnection): string[];
+/** Options for {@link registerMcpAgentTools} — the connections to fan in. */
+export interface McpAgentToolOptions {
+    /**
+     * Already-connected MCP connections whose remote tools to fan in. The host
+     * connects each server (via {@link connectMcpServer}) at init-time, BEFORE the
+     * registry is frozen, then passes the live connections here. Defaults to none —
+     * with no MCP servers configured this is a no-op (core runs MCP-OFF).
+     */
+    readonly connections?: readonly McpConnection[];
+}
+/**
+ * Register the fan-in proxy tools for every supplied MCP connection. Pure
+ * registration — no network handshake here (the connections are already live);
+ * the connect happens earlier in {@link connectMcpServer}. With no connections
+ * this is a no-op (the common no-MCP-configured case).
+ *
+ * @param registry - The registry to populate.
+ * @param options - The live connections to fan in.
+ */
+export declare function registerMcpAgentTools(registry: AgentToolRegistry, options?: McpAgentToolOptions): void;
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. With no live
+ * connections supplied this registers nothing (a host wires connections via
+ * {@link registerMcpAgentTools} directly with its connected servers).
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentTools(registry: AgentToolRegistry): void;
+//# sourceMappingURL=mcp-agent-tool.d.ts.map

package/dist/tools/mcp-agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-agent-tool.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-agent-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAElB,MAAM,qBAAqB,CAAC;AAI7B,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;QACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACvC,CAAC;CACH;AAED,8DAA8D;AAC9D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,8EAA8E;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,mCAAoC,CAAC;AAErE,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,gFAAgF;IAChF,MAAM,IAAI,OAAO,CAAC;IAClB,iEAAiE;IACjE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,YAAY,GACtB,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAiBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,mBAAmB,CA6C/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,aAAa,GAClB,MAAM,EAAE,CAQV;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAIN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAEpE"}

package/dist/tools/mcp-agent-tool.js

@@ -0,0 +1,243 @@
+/**
+ * Native MCP client (fan-IN) agent tool — connect-time `listTools` → register each
+ * remote tool into the {@link ./agent-registry.js | AgentToolRegistry}
+ * (T11948 · M7 · epic T11456 · SG-TOOLS · satisfies T11593 EP-MCP-HOST-FANIN + T1746).
+ *
+ * Where the runtime gateway is the MCP *server* (fan-OUT: it EXPOSES cleo ops as
+ * MCP tools), this is the MCP *client* (fan-IN: it CONNECTS to an external MCP
+ * server and PULLS its tools into cleo's own agent loop). On connect the client
+ * performs the MCP handshake (`initialize` → `tools/list`) and registers EACH
+ * remote tool as a proxy {@link AgentToolDescriptor} BEFORE the registry is frozen
+ * (init-time fan-in). Each proxy tool's `execute` issues a `tools/call` over the
+ * SAME transport and formats the result for the loop; a transport failure becomes a
+ * typed result (the executable NEVER throws — the frozen ToolDispatchEngine is
+ * unchanged).
+ *
+ * This REPLACES the external mcp-tool dependency for the host-loop path. It is a
+ * deliberately-minimal native client — NO external MCP SDK dependency: the wire is
+ * the standard MCP JSON-RPC ({@link McpTransport}), with stdio / SSE / HTTP
+ * transports as concrete {@link McpTransport} implementations. Placed in `core` per
+ * the package boundary (consumed by the harness, never redefined there — Gate-11).
+ *
+ * ## Availability (AC — live-connection only)
+ *
+ * A fan-in tool is available ONLY while its MCP server connection is live. The
+ * client exposes an {@link McpConnection.isLive} cell that each proxy tool's
+ * {@link AvailabilityCheck} reads; once the connection closes (or its transport
+ * errors fatally), the proxy tools report unavailable rather than dispatching into
+ * a dead transport.
+ *
+ * ## Gate-13
+ *
+ * No model/transport/provider LLM client is constructed here — the MCP transport
+ * speaks the tool protocol, not an LLM wire. There is no chokepoint concern.
+ *
+ * @epic T11456
+ * @task T11948
+ * @see ../../runtime/src/gateway/mcp/types.ts — the MCP server (fan-out) wire types this mirrors
+ * @see ./exec-code-agent-tool.js — the injectable-seam + self-registering-marker pattern mirrored here
+ */
+import { z } from 'zod';
+import { getLogger } from '../logger.js';
+const log = getLogger('tool-mcp-client');
+/** Transport kinds a native MCP client connection can speak over. */
+export const MCP_TRANSPORT_KINDS = ['stdio', 'sse', 'http'];
+/**
+ * Perform the MCP handshake over `transport` and discover its tools: send
+ * `initialize`, then `tools/list`. Returns a live {@link McpConnection} whose
+ * liveness cell is `true` until {@link McpConnection.disconnect}. The transport is
+ * supplied by the caller (so stdio / SSE / HTTP — or an in-memory fake — all flow
+ * through the same path).
+ *
+ * @param serverName - Stable name to namespace this server's fan-in tools.
+ * @param transport - The MCP transport to handshake over.
+ * @returns The connected {@link McpConnection}.
+ * @throws When `initialize` or `tools/list` fails (the connection is not live).
+ */
+export async function connectMcpServer(serverName, transport) {
+    await transport.request('initialize', {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'cleo', version: '0' },
+    });
+    const listed = await transport.request('tools/list', {});
+    const tools = extractRemoteTools(listed);
+    let live = true;
+    return {
+        serverName,
+        transport,
+        tools,
+        isLive: () => live,
+        disconnect: async () => {
+            live = false;
+            try {
+                await transport.close();
+            }
+            catch (err) {
+                log.debug({ err, serverName }, 'mcp: transport close failed (ignored)');
+            }
+        },
+    };
+}
+/** Narrow a `tools/list` result into an {@link McpRemoteTool}[] defensively. */
+function extractRemoteTools(listed) {
+    if (typeof listed === 'object' &&
+        listed !== null &&
+        'tools' in listed &&
+        Array.isArray(listed.tools)) {
+        return listed.tools.filter((t) => typeof t?.name === 'string');
+    }
+    return [];
+}
+/**
+ * The namespaced agent-tool name for a remote MCP tool: `mcp_<server>_<tool>`. So
+ * two servers exposing a same-named tool never collide in the registry.
+ *
+ * @param serverName - The MCP server's stable name.
+ * @param toolName - The remote tool's name.
+ * @returns The namespaced, registry-unique tool name.
+ */
+export function mcpToolName(serverName, toolName) {
+    const safe = (s) => s.replace(/[^a-zA-Z0-9_]/g, '_');
+    return `mcp_${safe(serverName)}_${safe(toolName)}`;
+}
+/**
+ * Build a Zod parameter schema from a remote tool's JSON Schema. The fan-in proxy
+ * accepts an open object (the remote server is the source of truth for its own
+ * validation); we surface declared properties as a permissive record so the model
+ * sees the shape while the remote performs authoritative validation.
+ *
+ * @param tool - The remote tool definition.
+ * @returns A Zod schema for the proxy's parameters.
+ */
+function remoteToolSchema(tool) {
+    const props = tool.inputSchema?.properties ?? {};
+    const shape = {};
+    const required = new Set(tool.inputSchema?.required ?? []);
+    for (const [key, prop] of Object.entries(props)) {
+        let field;
+        switch (prop.type) {
+            case 'number':
+            case 'integer':
+                field = z.number();
+                break;
+            case 'boolean':
+                field = z.boolean();
+                break;
+            case 'array':
+                field = z.array(z.unknown());
+                break;
+            case 'object':
+                field = z.record(z.string(), z.unknown());
+                break;
+            default:
+                field = z.string();
+        }
+        if (prop.description)
+            field = field.describe(prop.description);
+        shape[key] = required.has(key) ? field : field.optional();
+    }
+    return z.object(shape).passthrough();
+}
+/**
+ * Build the proxy {@link AgentToolDescriptor} for ONE remote tool over a live
+ * connection. Its `execute` issues `tools/call` over the connection's transport
+ * and formats the result; a transport / server error becomes a typed result (never
+ * throws). Its availability returns `true` only while the connection is live.
+ *
+ * @param conn - The live MCP connection.
+ * @param tool - The remote tool to proxy.
+ * @returns The proxy descriptor to register.
+ */
+export function buildMcpProxyTool(conn, tool) {
+    const liveOnly = () => conn.isLive();
+    return {
+        name: mcpToolName(conn.serverName, tool.name),
+        // 'net' — the proxy reaches an external MCP server over its transport.
+        class: 'net',
+        description: tool.description ??
+            `Proxy for remote MCP tool "${tool.name}" on server "${conn.serverName}".`,
+        toolset: 'agent',
+        stateless: false,
+        available: liveOnly,
+        parameters: remoteToolSchema(tool),
+        execute: async (rawArgs) => {
+            if (!conn.isLive()) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'E_MCP_CONNECTION_DEAD',
+                        message: `MCP server "${conn.serverName}" connection is no longer live`,
+                    },
+                };
+            }
+            try {
+                const result = (await conn.transport.request('tools/call', {
+                    name: tool.name,
+                    arguments: rawArgs,
+                }));
+                const text = (result.content ?? [])
+                    .map((c) => c.text ?? '')
+                    .filter((t) => t.length > 0)
+                    .join('\n');
+                return { ok: result.isError !== true, isError: result.isError === true, content: text };
+            }
+            catch (err) {
+                // A transport / server error is a typed dispatch failure, never a throw.
+                return {
+                    ok: false,
+                    error: {
+                        code: 'E_MCP_CALL_FAILED',
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                };
+            }
+        },
+    };
+}
+/**
+ * Register every fan-in proxy tool for a live MCP connection into `registry`. Pure
+ * registration over an ALREADY-connected {@link McpConnection} — the connect /
+ * `tools/list` happened in {@link connectMcpServer} (which the host calls at
+ * init-time, before the registry is frozen). Each remote tool becomes one proxy
+ * descriptor (AC1); each is hidden once the connection drops (AC — live-only).
+ *
+ * @param registry - The registry to populate (must not yet be frozen).
+ * @param conn - The live MCP connection whose tools to fan in.
+ * @returns The registered proxy tool names.
+ */
+export function registerMcpConnectionTools(registry, conn) {
+    const names = [];
+    for (const tool of conn.tools) {
+        const descriptor = buildMcpProxyTool(conn, tool);
+        registry.register(descriptor);
+        names.push(descriptor.name);
+    }
+    return names;
+}
+/**
+ * Register the fan-in proxy tools for every supplied MCP connection. Pure
+ * registration — no network handshake here (the connections are already live);
+ * the connect happens earlier in {@link connectMcpServer}. With no connections
+ * this is a no-op (the common no-MCP-configured case).
+ *
+ * @param registry - The registry to populate.
+ * @param options - The live connections to fan in.
+ */
+export function registerMcpAgentTools(registry, options = {}) {
+    for (const conn of options.connections ?? []) {
+        registerMcpConnectionTools(registry, conn);
+    }
+}
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. With no live
+ * connections supplied this registers nothing (a host wires connections via
+ * {@link registerMcpAgentTools} directly with its connected servers).
+ *
+ * @param registry - The registry to populate.
+ */
+export function registerAgentTools(registry) {
+    registerMcpAgentTools(registry);
+}
+//# sourceMappingURL=mcp-agent-tool.js.map

package/dist/tools/mcp-agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-agent-tool.js","sourceRoot":"","sources":["../../src/tools/mcp-agent-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/media-agent-tools.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Vision / media agent-tool family — `vision_analyze` / `image_generate` /
+ * `text_to_speech` (T11951 · M7 · epic T11456 · SG-TOOLS).
+ *
+ * The FIRST occupants of the previously-empty `media` toolset. Every model /
+ * multimodal call routes THROUGH the single E9 chokepoint
+ * ({@link import('../llm/system-resolver.js')}'s `resolveLLMForSystem` →
+ * {@link import('../llm/model-runner.js')}'s `ModelRunner`), EXACTLY like
+ * `browser_vision` ({@link ./web-agent-tools.js}). There is NO raw provider client,
+ * NO new transport, NO API-key read at this call-site — the plaintext credential is
+ * materialized from the sealed handle ONLY at the wire inside `ModelRunner.build`
+ * (Gate-13 stays green).
+ *
+ *   - **`vision_analyze`** — read a local image + a prompt, send them as a single
+ *     multimodal user turn through the chokepoint, return the model's analysis.
+ *   - **`image_generate`** — send an image prompt through the chokepoint; returns
+ *     the model's response (text/asset-ref it emits). When the resolved model
+ *     cannot generate an image the chokepoint degrades — the tool surfaces an
+ *     `unsupported` flag rather than constructing a bespoke image client.
+ *   - **`text_to_speech`** — send text through the chokepoint for narration intent;
+ *     same degradation contract when the modality is unsupported.
+ *
+ * ## Availability (AC3 — mirrors `browser_vision`)
+ *
+ * Hidden unless outbound egress is permitted AND the host advertises a multimodal
+ * model (`networkEgressAllowed !== false && capabilities.multimodal === true`).
+ * Registered-but-hidden so core runs credential-OFF / egress-OFF and the catalog
+ * stays stable. (The capability flag is the host's "a multimodal model is
+ * resolvable" promise — availability is a SYNC predicate, so the actual resolution
+ * happens at `execute` time with graceful degradation when no credential resolves.)
+ *
+ * @epic T11456
+ * @task T11951
+ * @see ./web-agent-tools.js — `browser_vision`, the E9-routed multimodal pattern mirrored here
+ * @see ../llm/system-resolver.js — `resolveLLMForSystem` (the E9 chokepoint)
+ * @see ../llm/model-runner.js — `ModelRunner` (the single SSoT wire builder)
+ */
+import type { AgentToolRegistry, AvailabilityCheck } from './agent-registry.js';
+/**
+ * Available only when outbound egress is permitted AND the host advertises a
+ * multimodal model. Mirrors `browser_vision`'s availability: registered-but-hidden
+ * (so the `media` catalog is stable) until a context advertises both
+ * `networkEgressAllowed !== false` and `capabilities.multimodal === true`.
+ */
+export declare const multimodalAvailable: AvailabilityCheck;
+/**
+ * Read a local image file as base64 + sniff its MIME type from the extension.
+ * Injectable so the unit test supplies image bytes without a real file on disk.
+ */
+export type ImageReader = (path: string) => Promise<{
+    base64: string;
+    mediaType: string;
+}>;
+/** The outcome of a chokepoint-routed media call. */
+export interface MediaModelResult {
+    /** Whether a model produced a response. */
+    readonly ok: boolean;
+    /** The model's textual response (analysis / description / refusal). */
+    readonly content?: string;
+    /** The model that answered (present once a credential resolves). */
+    readonly model?: string;
+    /**
+     * `true` when no credential resolved through the E9 chokepoint — the call
+     * degraded gracefully rather than throwing (mirrors `browser_vision`).
+     */
+    readonly aiUnavailable?: boolean;
+    /**
+     * `true` when the resolved model cannot serve the requested modality
+     * (e.g. true image synthesis / TTS audio). The tool does NOT construct a
+     * bespoke client for an unsupported modality (Gate-13) — it reports this.
+     */
+    readonly unsupported?: boolean;
+    /** A stable code + message when the call failed for another reason. */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** Options for {@link registerMediaAgentTools} — all injectable for testing. */
+export interface MediaAgentToolOptions {
+    /** The local-image reader. Defaults to a real `fs` read + MIME sniff. */
+    readonly readImage?: ImageReader;
+    /** Project root threaded into the E9 resolver (defaults to the resolver's own fallback). */
+    readonly projectRoot?: string;
+}
+/**
+ * Register the vision / media agent-tool family into `registry`. Pure
+ * registration — no model is resolved, no credential is read, no file is opened
+ * here; all of that happens later inside each tool's `execute` through the E9
+ * chokepoint (and the injected image reader). Import-time side-effect-free.
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable image reader / project root (for testing).
+ */
+export declare function registerMediaAgentTools(registry: AgentToolRegistry, options?: MediaAgentToolOptions): void;
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. Aliases
+ * {@link registerMediaAgentTools} so a future scan-dir discovery (or the built-in
+ * aggregator) can call it uniformly with the other agent-tool modules.
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentTools(registry: AgentToolRegistry): void;
+//# sourceMappingURL=media-agent-tools.d.ts.map

package/dist/tools/media-agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-agent-tools.d.ts","sourceRoot":"","sources":["../../src/tools/media-agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,qBAAqB,CAAC;AAI7B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,iBAC2C,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAuB3F,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA4DD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,qBAA0B,GAClC,IAAI,CAsHN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAEpE"}