salmon-loop 0.2.3

package/dist/core/tools/mapper.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+function unwrapForSchemaGeneration(schema) {
+    let current = schema;
+    for (let depth = 0; depth < 20; depth++) {
+        const ZodEffects = z.ZodEffects;
+        if (typeof ZodEffects === 'function' && current instanceof ZodEffects) {
+            current = current._def.schema;
+            continue;
+        }
+        if (current instanceof z.ZodPipe) {
+            // z.preprocess in Zod v4 produces a ZodPipe(in=ZodTransform, out=<schema>).
+            current = current._def.out;
+            continue;
+        }
+        if (current instanceof z.ZodOptional) {
+            current = current._def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodNullable) {
+            current = current._def.innerType;
+            continue;
+        }
+        if (current instanceof z.ZodDefault) {
+            current = current._def.innerType;
+            continue;
+        }
+        break;
+    }
+    return current;
+}
+function zodToOpenApi3(schema) {
+    const unwrapped = unwrapForSchemaGeneration(schema);
+    const description = unwrapped.description;
+    if (unwrapped instanceof z.ZodObject) {
+        const shape = unwrapped.shape;
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(shape)) {
+            properties[key] = zodToOpenApi3(value);
+            if (!value.isOptional())
+                required.push(key);
+        }
+        const out = {
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+        };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodArray) {
+        const items = zodToOpenApi3(unwrapped._def.type);
+        const out = { type: 'array', items };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodEnum) {
+        const options = unwrapped.options ?? unwrapped._def?.values;
+        let values = [];
+        if (Array.isArray(options)) {
+            values = options.map(String);
+        }
+        else if (options && typeof options === 'object') {
+            values = Object.values(options).map(String);
+        }
+        const out = values.length > 0 ? { type: 'string', enum: values } : { type: 'string' };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodLiteral) {
+        const out = { const: unwrapped._def.value };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodUnion) {
+        const options = unwrapped._def.options;
+        const out = { oneOf: options.map((o) => zodToOpenApi3(o)) };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodString) {
+        const out = { type: 'string' };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodBoolean) {
+        const out = { type: 'boolean' };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    if (unwrapped instanceof z.ZodNumber) {
+        const isInt = Boolean(unwrapped._def.checks?.some((c) => c.kind === 'int'));
+        const out = { type: isInt ? 'integer' : 'number' };
+        if (description)
+            out.description = description;
+        return out;
+    }
+    // Fallback: keep schema permissive but include any description as a hint.
+    return description ? { description } : {};
+}
+/**
+ * Maps a SalmonLoop ToolSpec to the OpenAI tool definition format.
+ */
+export function toolToOpenAI(spec) {
+    return {
+        type: 'function',
+        function: {
+            name: spec.name,
+            description: spec.description,
+            parameters: zodToOpenApi3(spec.inputSchema),
+        },
+    };
+}
+/**
+ * Maps a SalmonLoop ToolSpec to the Anthropic tool definition format.
+ */
+export function toolToAnthropic(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        input_schema: zodToOpenApi3(spec.inputSchema),
+    };
+}
+/**
+ * Formats tool specifications for in-line prompt documentation.
+ */
+export function formatToolsForPrompt(specs) {
+    return specs
+        .map((spec) => {
+        const schema = zodToOpenApi3(spec.inputSchema);
+        return `Tool: ${spec.name}\nDescription: ${spec.description}\nSchema: ${JSON.stringify(schema, null, 2)}`;
+    })
+        .join('\n\n---\n\n');
+}
+//# sourceMappingURL=mapper.js.map

package/dist/core/tools/mcp/client.js

@@ -0,0 +1,308 @@
+import { createInterface } from 'readline';
+import { LIMITS } from '../../config/limits.js';
+import { getLogger } from '../../observability/logger.js';
+import { spawnInteractiveProcess } from '../../runtime/process-runner.js';
+import { assertOk, createMcpHeaders, decodeSseEvents, delayMs, isEventStreamResponse, safeDrainResponse, } from './streamable-http.js';
+/**
+ * MCP Client handling JSON-RPC communication over stdio with an external server.
+ */
+export class McpClient {
+    config;
+    process = null;
+    requestId = 0;
+    pendingRequests = new Map();
+    rl = null;
+    sessionId;
+    constructor(config) {
+        this.config = config;
+    }
+    isHttp() {
+        return Boolean(this.config.url);
+    }
+    /**
+     * Starts the MCP server process and performs the initialization handshake.
+     */
+    async start() {
+        if (this.isHttp()) {
+            getLogger().info(`Connecting to MCP server: ${this.config.name} (url: ${this.config.url})`);
+            await this.initialize();
+            getLogger().info(`MCP server ${this.config.name} ready.`);
+            return;
+        }
+        getLogger().info(`Starting MCP server: ${this.config.name} (command: ${this.config.command})`);
+        this.process = spawnInteractiveProcess({
+            command: this.config.command,
+            args: this.config.args || [],
+            env: { ...process.env, ...this.config.env },
+            cwd: this.config.cwd,
+            // Never inherit stderr into the parent TTY: it bypasses UI sanitization and can leak raw errors.
+            windowsHide: true,
+        });
+        if (!this.process) {
+            throw new Error(`Failed to spawn MCP server process: ${this.config.name}`);
+        }
+        this.process.on('error', (err) => {
+            getLogger().error(`MCP process error (${this.config.name}): ${err}`);
+        });
+        this.process.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                getLogger().error(`MCP server ${this.config.name} exited with code ${code}`);
+            }
+        });
+        this.rl = createInterface({
+            input: this.process.stdout,
+            terminal: false,
+        });
+        this.rl.on('line', (line) => this.handleMessage(line));
+        // Drain stderr to avoid backpressure deadlocks, but do not surface raw output to UI.
+        this.process.stderr?.on('data', () => { });
+        await this.initialize();
+        getLogger().info(`MCP server ${this.config.name} ready.`);
+    }
+    /**
+     * Retrieves the list of tools provided by the MCP server.
+     */
+    async listTools() {
+        const response = await this.request('tools/list', {});
+        return response.tools || [];
+    }
+    /**
+     * Executes a tool on the MCP server.
+     */
+    async callTool(name, args) {
+        return await this.request('tools/call', { name, arguments: args });
+    }
+    async initialize() {
+        // Step 1: Initialize handshake
+        await this.request('initialize', {
+            protocolVersion: '2025-11-25',
+            capabilities: {},
+            clientInfo: { name: 'salmon-loop', version: '0.2.0' },
+        });
+        // Step 2: Signal initialized
+        await this.notification('notifications/initialized', {});
+    }
+    async request(method, params) {
+        if (this.isHttp()) {
+            return (await this.requestHttp(method, params));
+        }
+        if (!this.process?.stdin?.write) {
+            throw new Error(`MCP client ${this.config.name} is not started`);
+        }
+        const id = ++this.requestId;
+        const message = JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n';
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(id, { resolve: resolve, reject });
+            this.process.stdin.write(message);
+            // Default timeout for MCP requests
+            setTimeout(() => {
+                if (this.pendingRequests.has(id)) {
+                    this.pendingRequests.delete(id);
+                    reject(new Error(`MCP Request ${id} (${method}) to ${this.config.name} timed out after ${LIMITS.defaultToolTimeoutMs / 1000}s`));
+                }
+            }, LIMITS.defaultToolTimeoutMs);
+        });
+    }
+    async notification(method, params) {
+        if (this.isHttp()) {
+            await this.notificationHttp(method, params);
+            return;
+        }
+        if (!this.process?.stdin?.write)
+            return;
+        const message = JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n';
+        this.process.stdin.write(message);
+    }
+    handleMessage(line) {
+        if (!line.trim())
+            return;
+        try {
+            const message = JSON.parse(line);
+            // Handle JSON-RPC Response
+            if (message.id !== undefined && this.pendingRequests.has(message.id)) {
+                const { resolve, reject } = this.pendingRequests.get(message.id);
+                this.pendingRequests.delete(message.id);
+                if (message.error) {
+                    reject(new Error(`MCP Error [${message.error.code}]: ${message.error.message}`));
+                }
+                else {
+                    resolve(message.result);
+                }
+            }
+            // Handle Notifications/Requests from Server (Optional, future proofing)
+            else if (message.method) {
+                getLogger().debug(`Received MCP notification/request: ${message.method} (server: ${this.config.name})`);
+            }
+        }
+        catch (err) {
+            getLogger().error(`Failed to parse MCP message from ${this.config.name}: ${err} (line: ${line})`);
+        }
+    }
+    async stop() {
+        if (this.isHttp()) {
+            await this.stopHttp();
+            return;
+        }
+        this.rl?.close();
+        this.process?.kill();
+        this.process = null;
+        this.pendingRequests.clear();
+    }
+    async requestHttp(method, params) {
+        const url = this.config.url;
+        const headers = this.config.headers ?? {};
+        const id = ++this.requestId;
+        const payload = { jsonrpc: '2.0', id, method, params };
+        const timeoutMs = LIMITS.defaultToolTimeoutMs;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: createMcpHeaders({ sessionId: this.sessionId, extra: headers }),
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            const newSessionId = response.headers.get('mcp-session-id');
+            if (newSessionId)
+                this.sessionId = newSessionId;
+            assertOk(response, `MCP request ${id} (${method}) to ${this.config.name}`);
+            if (!isEventStreamResponse(response)) {
+                const message = (await response.json());
+                if (message && typeof message === 'object' && message.error) {
+                    const err = message.error;
+                    throw new Error(`MCP Error [${err.code}]: ${err.message}`);
+                }
+                return message?.result;
+            }
+            let lastEventId;
+            let retryMs = 1000;
+            // Streamable HTTP can require reconnect (via GET + Last-Event-ID) to resume a dropped stream.
+            let streamResponse = response;
+            while (true) {
+                if (!streamResponse.body) {
+                    throw new Error(`MCP SSE response missing body (${this.config.name})`);
+                }
+                for await (const event of decodeSseEvents(streamResponse.body)) {
+                    if (event.id)
+                        lastEventId = event.id;
+                    if (typeof event.retry === 'number')
+                        retryMs = Math.max(0, event.retry);
+                    if (!event.data)
+                        continue;
+                    try {
+                        const msg = JSON.parse(event.data);
+                        if (msg.id === id) {
+                            if (msg.error) {
+                                const err = msg.error;
+                                throw new Error(`MCP Error [${err.code}]: ${err.message}`);
+                            }
+                            return msg.result;
+                        }
+                        if (msg.method) {
+                            getLogger().debug(`Received MCP notification/request: ${msg.method} (server: ${this.config.name})`);
+                        }
+                    }
+                    catch (err) {
+                        getLogger().error(`Failed to parse MCP SSE message from ${this.config.name}: ${String(err)} (data: ${event.data})`);
+                    }
+                }
+                // Stream ended without response for this request. Try to resume via GET.
+                if (!lastEventId) {
+                    throw new Error(`MCP SSE stream ended before response for request ${id} (${method}) (${this.config.name})`);
+                }
+                await delayMs(retryMs);
+                const resumeController = new AbortController();
+                const resumeTimeout = setTimeout(() => resumeController.abort(), timeoutMs);
+                try {
+                    streamResponse = await fetch(url, {
+                        method: 'GET',
+                        headers: {
+                            ...createMcpHeaders({ sessionId: this.sessionId, extra: headers }),
+                            'Last-Event-ID': lastEventId,
+                        },
+                        signal: resumeController.signal,
+                    });
+                    const resumedSessionId = streamResponse.headers.get('mcp-session-id');
+                    if (resumedSessionId)
+                        this.sessionId = resumedSessionId;
+                    assertOk(streamResponse, `MCP SSE resume for ${this.config.name}`);
+                    if (!isEventStreamResponse(streamResponse)) {
+                        throw new Error(`MCP SSE resume did not return text/event-stream (${this.config.name})`);
+                    }
+                }
+                finally {
+                    clearTimeout(resumeTimeout);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`MCP Request ${id} (${method}) to ${this.config.name} timed out after ${timeoutMs / 1000}s`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async notificationHttp(method, params) {
+        const url = this.config.url;
+        const headers = this.config.headers ?? {};
+        const payload = { jsonrpc: '2.0', method, params };
+        const timeoutMs = LIMITS.defaultToolTimeoutMs;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: createMcpHeaders({ sessionId: this.sessionId, extra: headers }),
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            const newSessionId = response.headers.get('mcp-session-id');
+            if (newSessionId)
+                this.sessionId = newSessionId;
+            if (!response.ok) {
+                await safeDrainResponse(response);
+                throw new Error(`MCP notification ${method} failed with HTTP ${response.status}`);
+            }
+            await safeDrainResponse(response);
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`MCP notification ${method} to ${this.config.name} timed out after ${timeoutMs / 1000}s`);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async stopHttp() {
+        if (!this.config.url || !this.sessionId)
+            return;
+        const timeoutMs = 3000;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(this.config.url, {
+                method: 'DELETE',
+                headers: createMcpHeaders({
+                    sessionId: this.sessionId,
+                    extra: this.config.headers ?? {},
+                }),
+                signal: controller.signal,
+            });
+            await safeDrainResponse(response);
+        }
+        catch {
+            // best-effort cleanup
+        }
+        finally {
+            clearTimeout(timeout);
+            this.sessionId = undefined;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/core/tools/mcp/loader.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { LIMITS } from '../../config/limits.js';
+import { getLogger } from '../../observability/logger.js';
+import { Phase } from '../../types/runtime.js';
+import { McpClient } from './client.js';
+import { jsonSchemaToZod } from './schema.js';
+const OUTPUT_SCHEMA = z
+    .object({
+    content: z.array(z.record(z.string(), z.any())),
+})
+    .passthrough();
+const PROCESS_SIDE_EFFECTS = ['process', 'network'];
+const ALLOWED_PHASES = [Phase.VERIFY];
+function matchesPattern(value, pattern) {
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('*')) {
+        return value.startsWith(pattern.slice(0, -1));
+    }
+    return value === pattern;
+}
+function isToolAllowed(toolName, allowList) {
+    if (!allowList || allowList.length === 0)
+        return false;
+    return allowList.some((pattern) => matchesPattern(toolName, pattern));
+}
+export async function registerMcpTools(registry, servers) {
+    for (const server of servers) {
+        if (!server.enabled)
+            continue;
+        if (!server.allowTools || server.allowTools.length === 0) {
+            getLogger().warn(`MCP server ${server.name} has no tool allowlist; skipping registration.`);
+            continue;
+        }
+        const client = server.transport === 'http'
+            ? new McpClient({
+                name: server.name,
+                url: server.url,
+                headers: server.headers,
+            })
+            : new McpClient({
+                name: server.name,
+                command: server.command,
+                args: server.args,
+                env: server.env,
+                cwd: server.cwd,
+            });
+        try {
+            await client.start();
+            const toolList = await client.listTools();
+            if (!Array.isArray(toolList) || toolList.length === 0) {
+                getLogger().warn(`MCP server ${server.name} reported no tools.`);
+            }
+            for (const tool of toolList) {
+                const toolName = tool.name;
+                if (!toolName)
+                    continue;
+                if (!isToolAllowed(toolName, server.allowTools)) {
+                    continue;
+                }
+                const spec = {
+                    name: `mcp.${server.name}.${toolName}`,
+                    source: 'mcp',
+                    intent: 'INFRA',
+                    description: tool.description || `MCP tool ${toolName}`,
+                    riskLevel: 'medium',
+                    sideEffects: PROCESS_SIDE_EFFECTS,
+                    concurrency: 'serial_only',
+                    allowedPhases: ALLOWED_PHASES,
+                    inputSchema: jsonSchemaToZod(tool.inputSchema),
+                    outputSchema: OUTPUT_SCHEMA,
+                    defaultTimeoutMs: LIMITS.defaultToolTimeoutMs,
+                    executor: async (input) => {
+                        const runtimeClient = server.transport === 'http'
+                            ? new McpClient({
+                                name: server.name,
+                                url: server.url,
+                                headers: server.headers,
+                            })
+                            : new McpClient({
+                                name: server.name,
+                                command: server.command,
+                                args: server.args,
+                                env: server.env,
+                                cwd: server.cwd,
+                            });
+                        try {
+                            await runtimeClient.start();
+                            const result = await runtimeClient.callTool(toolName, input);
+                            return result;
+                        }
+                        finally {
+                            await runtimeClient.stop();
+                        }
+                    },
+                };
+                getLogger().info(`Registered MCP tool ${spec.name} from ${server.name}`);
+                registry.register(spec);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            getLogger().error(`Failed to register MCP server ${server.name}: ${message}`);
+        }
+        finally {
+            await client.stop();
+        }
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/core/tools/mcp/schema.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { getLogger } from '../../observability/logger.js';
+/**
+ * Converts a JSON Schema (commonly used in MCP) to a Zod schema.
+ * This implementation covers the core JSON Schema types used by tools.
+ */
+export function jsonSchemaToZod(jsonSchema) {
+    if (!jsonSchema || typeof jsonSchema !== 'object') {
+        return z.any();
+    }
+    const schema = jsonSchema;
+    // Handle cases where the schema is just a description or empty
+    if (!schema.type && !schema.properties) {
+        return z.any();
+    }
+    try {
+        switch (schema.type) {
+            case 'string':
+                return z.string().describe(schema.description || '');
+            case 'number':
+            case 'integer':
+                return z.number().describe(schema.description || '');
+            case 'boolean':
+                return z.boolean().describe(schema.description || '');
+            case 'array': {
+                const items = schema.items ? jsonSchemaToZod(schema.items) : z.any();
+                return z.array(items).describe(schema.description || '');
+            }
+            case 'object':
+            case undefined: {
+                // Often schemas with properties omit 'type: object'
+                const shape = {};
+                const properties = (schema.properties || {});
+                const required = schema.required || [];
+                for (const [key, prop] of Object.entries(properties)) {
+                    let fieldSchema = jsonSchemaToZod(prop);
+                    if (!required.includes(key)) {
+                        fieldSchema = fieldSchema.optional();
+                    }
+                    shape[key] = fieldSchema;
+                }
+                return z.object(shape).describe(schema.description || '');
+            }
+            default:
+                getLogger().debug(`Unsupported JSON schema type: ${schema.type}, falling back to any`);
+                return z.any();
+        }
+    }
+    catch (err) {
+        getLogger().error(`Failed to convert JSON schema to Zod: ${String(err)} (Schema: ${JSON.stringify(schema)})`);
+        return z.any();
+    }
+}
+//# sourceMappingURL=schema.js.map