@purista/harness 1.0.0

package/dist/tools/mcp/http.js

@@ -0,0 +1,109 @@
+import { McpAuthError, McpProtocolError, OperationTimeoutError } from '../../errors/index.js';
+import { withMcpTimeout } from './runner.js';
+export function createHttpMcpTransportRunner(config) {
+    let connected;
+    async function connect(options) {
+        connected ??= (async () => {
+            const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
+                import('@modelcontextprotocol/sdk/client/index.js'),
+                import('@modelcontextprotocol/sdk/client/streamableHttp.js')
+            ]);
+            const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+                requestInit: { headers: buildHeaders(config.headers, config.auth) }
+            });
+            const client = new Client({ name: `purista-harness-${config.localToolId}`, version: '0.0.0' });
+            try {
+                await client.connect(transport, toSdkOptions(options));
+            }
+            catch (error) {
+                connected = undefined;
+                throw mapHttpError(config, 'connect', error);
+            }
+            return { client, transport };
+        })();
+        return connected;
+    }
+    return {
+        async listTools(options) {
+            try {
+                const { client } = await connect(options);
+                return (await client.listTools(undefined, toSdkOptions(options))).tools;
+            }
+            catch (error) {
+                if (error instanceof McpAuthError || error instanceof McpProtocolError)
+                    throw error;
+                throw mapHttpError(config, 'list', error);
+            }
+        },
+        async callTool(name, input, options) {
+            try {
+                const { client } = await connect(options);
+                return await withMcpTimeout({ ...(options?.signal ? { signal: options.signal } : {}), timeoutMs: options?.timeoutMs ?? config.timeoutMs, scope: 'tool' }, (signal) => client.callTool({ name, arguments: input }, undefined, toSdkOptions({ ...(signal ? { signal } : {}), timeoutMs: options?.timeoutMs ?? config.timeoutMs })));
+            }
+            catch (error) {
+                if (error instanceof McpAuthError || error instanceof McpProtocolError)
+                    throw error;
+                if (error instanceof OperationTimeoutError)
+                    throw error;
+                throw mapHttpError(config, 'call', error);
+            }
+        },
+        async close() {
+            if (!connected)
+                return;
+            const current = await connected.catch(() => undefined);
+            connected = undefined;
+            await current?.transport.close();
+            await current?.client.close();
+        }
+    };
+}
+function buildHeaders(headers, auth) {
+    const next = { ...(headers ?? {}) };
+    if (!auth || auth.kind === 'none')
+        return next;
+    if (auth.kind === 'bearer')
+        next['authorization'] = `Bearer ${auth.token}`;
+    if (auth.kind === 'oauth2')
+        next['authorization'] = `Bearer ${auth.accessToken}`;
+    if (auth.kind === 'api_key')
+        next[auth.header] = auth.value;
+    if (auth.kind === 'basic')
+        next['authorization'] = `Basic ${Buffer.from(`${auth.username}:${auth.password}`).toString('base64')}`;
+    return next;
+}
+function toSdkOptions(options) {
+    if (!options)
+        return undefined;
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.timeoutMs ? { timeout: options.timeoutMs } : {})
+    };
+}
+function mapHttpError(config, phase, error) {
+    const status = statusFromError(error);
+    if (status === 401 || status === 403) {
+        return new McpAuthError('MCP HTTP authentication failed.', { tool_id: config.localToolId, auth_kind: config.auth?.kind ?? 'none', status }, error);
+    }
+    return new McpProtocolError('MCP HTTP transport failed.', { tool_id: config.localToolId, transport: 'http', phase }, error);
+}
+function statusFromError(error) {
+    if (typeof error === 'object' && error !== null) {
+        const maybe = error;
+        if (typeof maybe.status === 'number')
+            return maybe.status;
+        if (typeof maybe.code === 'number')
+            return maybe.code;
+        const causeStatus = statusFromError(maybe.cause);
+        if (causeStatus !== undefined)
+            return causeStatus;
+    }
+    if (error instanceof Error) {
+        if (/unauthorized/i.test(error.message))
+            return 401;
+        const match = /\b(401|403|4\d\d|5\d\d)\b/.exec(error.message);
+        if (match?.[1])
+            return Number(match[1]);
+    }
+    return undefined;
+}

package/dist/tools/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export * from './runner.js';
+export * from './schema.js';

package/dist/tools/mcp/index.js

@@ -0,0 +1,2 @@
+export * from './runner.js';
+export * from './schema.js';

package/dist/tools/mcp/runner.d.ts

@@ -0,0 +1,74 @@
+import type { McpHttpToolDefinition, McpStdioToolDefinition, ToolDefinition, ToolsConfig } from '../../harness/defineHarness.js';
+import type { JsonValue } from '../../models/json.js';
+import type { ModelToolSpec } from '../../ports/model-provider.js';
+import type { SandboxSession } from '../../sandbox/index.js';
+import { type McpSchemaWarning } from './schema.js';
+export type McpToolKind = 'mcp_stdio' | 'mcp_http';
+export type McpTransport = 'stdio' | 'http';
+export interface ResolvedMcpTool {
+    localToolId: string;
+    kind: McpToolKind;
+    description: string;
+    upstreamToolName: string;
+    timeoutMs: number;
+    serverKey: string;
+    inputAdapter?: (input: unknown) => unknown;
+    outputAdapter?: (output: unknown) => unknown;
+}
+export interface ResolvedMcpStdioTool extends ResolvedMcpTool {
+    kind: 'mcp_stdio';
+    command: string;
+    args?: readonly string[];
+    env?: Record<string, string>;
+    install?: McpStdioToolDefinition['install'];
+    sandbox: SandboxSession;
+}
+export interface ResolvedMcpHttpTool extends ResolvedMcpTool {
+    kind: 'mcp_http';
+    url: string;
+    auth?: McpHttpToolDefinition['auth'];
+    headers?: Record<string, string>;
+}
+export type ResolvedMcpToolConfig = ResolvedMcpStdioTool | ResolvedMcpHttpTool;
+export interface McpDiscoveredTool {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+}
+export interface McpTransportRunner {
+    listTools(options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<McpDiscoveredTool[]>;
+    callTool(name: string, input: unknown, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface McpRunnerRegistry {
+    getRunner(config: ResolvedMcpToolConfig): McpTransportRunner;
+    close(): Promise<void>;
+}
+export interface McpFacadeContext {
+    signal?: AbortSignal;
+    toolTimeoutMs?: number;
+    sandbox?: SandboxSession;
+    sandboxKey?: string;
+    registry?: McpRunnerRegistry;
+    warn?: (warning: McpSchemaWarning) => void;
+}
+export declare function getMcpToolSpecs(tools: ToolsConfig, allowlist: Iterable<string>, ctx?: McpFacadeContext): Promise<ModelToolSpec[]>;
+export declare function invokeMcpTool(toolId: string, tool: ToolDefinition, input: unknown, ctx: McpFacadeContext): Promise<JsonValue>;
+export declare function invokeMcpTool(config: ResolvedMcpToolConfig, runner: McpTransportRunner, input: unknown, signal?: AbortSignal): Promise<JsonValue>;
+export declare function getModelToolSpec(config: ResolvedMcpToolConfig, runner: McpTransportRunner, signal?: AbortSignal): Promise<ModelToolSpec>;
+export declare function createMcpRunnerRegistry(): McpRunnerRegistry;
+export declare function normalizeMcpOutput(result: unknown): JsonValue;
+export declare function toMcpTransport(kind: McpToolKind): McpTransport;
+export declare function isMcpToolDefinition(tool: ToolDefinition | McpTransportRunner): tool is McpStdioToolDefinition | McpHttpToolDefinition;
+export declare function withMcpTimeout<T>(opts: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    scope: 'tool';
+}, fn: (signal?: AbortSignal) => Promise<T>): Promise<T>;

package/dist/tools/mcp/runner.js

@@ -0,0 +1,238 @@
+import { McpProtocolError, OperationCancelledError, OperationTimeoutError, ToolError, ToolNotFoundError, ValidationError } from '../../errors/index.js';
+import { assertMcpJsonSchema, validateMcpJsonSchema } from './schema.js';
+const discoveredCache = new WeakMap();
+export async function getMcpToolSpecs(tools, allowlist, ctx = {}) {
+    const allowed = new Set(allowlist);
+    const specs = [];
+    const registry = ctx.registry ?? createMcpRunnerRegistry();
+    for (const [toolId, tool] of Object.entries(tools)) {
+        if (!allowed.has(toolId) || !isMcpToolDefinition(tool))
+            continue;
+        const config = resolveMcpTool(toolId, tool, ctx);
+        specs.push(await getResolvedModelToolSpec(config, registry.getRunner(config), ctx.signal, ctx.warn));
+    }
+    return specs;
+}
+export async function invokeMcpTool(first, second, input, fourth) {
+    if (typeof first === 'string') {
+        if (!isMcpToolDefinition(second))
+            throw new ToolNotFoundError('Tool is not an MCP tool.', { tool_id: first, where: 'registry' });
+        const ctx = isAbortSignal(fourth) ? { signal: fourth } : fourth ?? {};
+        const registry = ctx.registry ?? createMcpRunnerRegistry();
+        const config = resolveMcpTool(first, second, ctx);
+        return invokeResolvedMcpTool(config, registry.getRunner(config), input, ctx.signal, ctx.warn);
+    }
+    return invokeResolvedMcpTool(first, second, input, isAbortSignal(fourth) ? fourth : fourth?.signal, isAbortSignal(fourth) ? undefined : fourth?.warn);
+}
+export async function getModelToolSpec(config, runner, signal) {
+    return getResolvedModelToolSpec(config, runner, signal);
+}
+export function createMcpRunnerRegistry() {
+    const runners = new Map();
+    return {
+        getRunner(config) {
+            const existing = runners.get(config.localToolId);
+            if (existing)
+                return existing;
+            const runner = config.kind === 'mcp_stdio'
+                ? createDynamicStdioRunner(config)
+                : createDynamicHttpRunner(config);
+            runners.set(config.localToolId, runner);
+            return runner;
+        },
+        async close() {
+            await Promise.all([...runners.values()].map((runner) => runner.close()));
+            runners.clear();
+        }
+    };
+}
+export function normalizeMcpOutput(result) {
+    if (isRecord(result) && isJsonValue(result.structuredContent))
+        return result.structuredContent;
+    if (!isRecord(result) || !Array.isArray(result.content))
+        return isJsonValue(result) ? result : null;
+    const normalized = result.content.map(normalizeContentBlock);
+    if (normalized.length === 0)
+        return null;
+    if (normalized.every((item) => typeof item === 'string'))
+        return normalized.join('\n');
+    if (normalized.length === 1)
+        return normalized[0] ?? null;
+    return { content: normalized.filter(isJsonValue) };
+}
+export function toMcpTransport(kind) {
+    return kind === 'mcp_stdio' ? 'stdio' : 'http';
+}
+async function getResolvedModelToolSpec(config, runner, signal, warn) {
+    const tool = await discoverConfiguredTool(config, runner, signal, warn);
+    const description = tool.description ? `${config.description}\n\n${tool.description}` : config.description;
+    return { name: config.localToolId, description, parameters: tool.inputSchema };
+}
+async function invokeResolvedMcpTool(config, runner, input, signal, warn) {
+    const tool = await discoverConfiguredTool(config, runner, signal, warn);
+    const adaptedInput = config.inputAdapter ? config.inputAdapter(input) : input;
+    const validatedInput = validateMcpJsonSchema({ toolId: config.localToolId, where: 'mcp_input', schema: tool.inputSchema, value: adaptedInput, ...(warn ? { warn } : {}) });
+    const result = await runner.callTool(config.upstreamToolName, validatedInput, { ...(signal ? { signal } : {}), timeoutMs: config.timeoutMs });
+    if (isRecord(result) && result.isError === true) {
+        throw new ToolError('MCP tool returned an error.', { tool_id: config.localToolId, tool_kind: config.kind });
+    }
+    const normalized = normalizeMcpOutput(result);
+    const validatedOutput = tool.outputSchema
+        ? validateMcpJsonSchema({ toolId: config.localToolId, where: 'mcp_output', schema: tool.outputSchema, value: normalized, ...(warn ? { warn } : {}) })
+        : normalized;
+    const adaptedOutput = config.outputAdapter ? config.outputAdapter(validatedOutput) : validatedOutput;
+    if (!isJsonValue(adaptedOutput)) {
+        throw new ValidationError('MCP output adapter returned a non-JSON value.', { where: 'mcp_output', issues: [{ path: '', message: 'Value must be JSON serializable.' }] });
+    }
+    return adaptedOutput;
+}
+async function discoverConfiguredTool(config, runner, signal, warn) {
+    let promise = discoveredCache.get(runner);
+    if (!promise) {
+        promise = runner.listTools({ ...(signal ? { signal } : {}), timeoutMs: config.timeoutMs });
+        discoveredCache.set(runner, promise);
+    }
+    const tools = await promise;
+    const tool = tools.find((candidate) => candidate.name === config.upstreamToolName);
+    if (!tool)
+        throw new ToolNotFoundError('MCP upstream tool was not found.', { tool_id: config.localToolId, where: 'registry' });
+    try {
+        assertMcpJsonSchema(config.localToolId, tool.inputSchema, 'mcp_input', warn);
+        if (tool.outputSchema !== undefined)
+            assertMcpJsonSchema(config.localToolId, tool.outputSchema, 'mcp_output', warn);
+    }
+    catch (error) {
+        if (error instanceof ValidationError)
+            throw new McpProtocolError('MCP tool schema is malformed.', { tool_id: config.localToolId, transport: toMcpTransport(config.kind), phase: 'list' }, error);
+        throw error;
+    }
+    return tool;
+}
+function resolveMcpTool(toolId, tool, ctx) {
+    const base = {
+        localToolId: toolId,
+        description: tool.description,
+        upstreamToolName: tool.tool,
+        timeoutMs: ctx.toolTimeoutMs ?? 120_000,
+        serverKey: toolId,
+        ...(tool.inputAdapter ? { inputAdapter: tool.inputAdapter } : {}),
+        ...(tool.outputAdapter ? { outputAdapter: tool.outputAdapter } : {})
+    };
+    if (tool.kind === 'mcp_stdio') {
+        if (!ctx.sandbox)
+            throw new ToolNotFoundError('MCP stdio tool requires a sandbox session.', { tool_id: toolId, where: 'registry' });
+        return {
+            ...base,
+            kind: 'mcp_stdio',
+            serverKey: `${toolId}:${ctx.sandboxKey ?? 'sandbox'}`,
+            command: tool.command,
+            ...(tool.args ? { args: tool.args } : {}),
+            ...(tool.env ? { env: tool.env } : {}),
+            ...(tool.install ? { install: tool.install } : {}),
+            sandbox: ctx.sandbox
+        };
+    }
+    return {
+        ...base,
+        kind: 'mcp_http',
+        url: tool.url,
+        ...(tool.auth ? { auth: tool.auth } : {}),
+        ...(tool.headers ? { headers: tool.headers } : {})
+    };
+}
+export function isMcpToolDefinition(tool) {
+    return isRecord(tool) && (tool.kind === 'mcp_stdio' || tool.kind === 'mcp_http');
+}
+function createDynamicStdioRunner(config) {
+    let runnerPromise;
+    return dynamicRunner(() => {
+        runnerPromise ??= import('./stdio.js').then((module) => module.createStdioMcpTransportRunner(config));
+        return runnerPromise;
+    });
+}
+function createDynamicHttpRunner(config) {
+    let runnerPromise;
+    return dynamicRunner(() => {
+        runnerPromise ??= import('./http.js').then((module) => module.createHttpMcpTransportRunner(config));
+        return runnerPromise;
+    });
+}
+function dynamicRunner(load) {
+    return {
+        async listTools(options) { return (await load()).listTools(options); },
+        async callTool(name, input, options) { return (await load()).callTool(name, input, options); },
+        async close() { await (await load()).close(); }
+    };
+}
+function normalizeContentBlock(block) {
+    if (!isRecord(block))
+        return null;
+    if (block.type === 'text' && typeof block.text === 'string')
+        return block.text;
+    if ((block.type === 'image' || block.type === 'audio') && typeof block.mimeType === 'string') {
+        return { contentType: block.mimeType, ...(typeof block.data === 'string' ? { data: block.data } : {}) };
+    }
+    if (block.type === 'resource' && isRecord(block.resource)) {
+        const resource = block.resource;
+        return {
+            ...(typeof resource.mimeType === 'string' ? { contentType: resource.mimeType } : {}),
+            ...(typeof resource.uri === 'string' ? { uri: resource.uri } : {}),
+            ...(typeof resource.text === 'string' ? { data: resource.text } : {}),
+            ...(typeof resource.blob === 'string' ? { data: resource.blob } : {})
+        };
+    }
+    if (block.type === 'resource_link') {
+        return {
+            ...(typeof block.mimeType === 'string' ? { contentType: block.mimeType } : {}),
+            ...(typeof block.uri === 'string' ? { uri: block.uri } : {})
+        };
+    }
+    return isJsonValue(block) ? block : null;
+}
+export async function withMcpTimeout(opts, fn) {
+    opts.signal?.throwIfAborted();
+    if (!opts.timeoutMs || opts.timeoutMs <= 0)
+        return fn(opts.signal);
+    const controller = new AbortController();
+    const relay = () => controller.abort(opts.signal?.reason);
+    opts.signal?.addEventListener('abort', relay, { once: true });
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            const error = new OperationTimeoutError('MCP tool operation timed out.', { scope: opts.scope, timeout_ms: opts.timeoutMs });
+            controller.abort(error);
+            reject(error);
+        }, opts.timeoutMs);
+    });
+    try {
+        return await Promise.race([fn(controller.signal), timeout]);
+    }
+    catch (error) {
+        if (controller.signal.aborted && !(controller.signal.reason instanceof OperationTimeoutError)) {
+            throw new OperationCancelledError('MCP tool operation was cancelled.', { scope: 'tool' }, controller.signal.reason ?? error);
+        }
+        throw error;
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        opts.signal?.removeEventListener('abort', relay);
+    }
+}
+function isAbortSignal(value) {
+    return isRecord(value) && typeof value.aborted === 'boolean' && typeof value.addEventListener === 'function';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isJsonValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (isRecord(value))
+        return Object.values(value).every(isJsonValue);
+    return false;
+}

package/dist/tools/mcp/schema.d.ts

@@ -0,0 +1,41 @@
+import type { JsonValue } from '../../models/json.js';
+export type McpSchemaValidationWhere = 'mcp_input' | 'mcp_output';
+export interface McpSchemaWarning {
+    toolId: string;
+    keyword: string;
+    path: string;
+    message: string;
+}
+export interface ValidateMcpJsonSchemaOptions {
+    toolId: string;
+    where: McpSchemaValidationWhere;
+    schema: unknown;
+    value: unknown;
+    warn?: (warning: McpSchemaWarning) => void;
+}
+export declare function validateMcpJsonSchema(opts: ValidateMcpJsonSchemaOptions): JsonValue;
+export declare function assertMcpJsonSchema(toolId: string, schema: unknown, where: McpSchemaValidationWhere, warn?: (warning: McpSchemaWarning) => void): asserts schema is JsonSchema;
+type JsonSchema = {
+    [key: string]: unknown;
+    $schema?: unknown;
+    additionalProperties?: unknown;
+    allOf?: unknown;
+    anyOf?: unknown;
+    const?: unknown;
+    enum?: unknown;
+    format?: unknown;
+    items?: unknown;
+    maximum?: unknown;
+    maxItems?: unknown;
+    maxLength?: unknown;
+    minimum?: unknown;
+    minItems?: unknown;
+    minLength?: unknown;
+    not?: unknown;
+    oneOf?: unknown;
+    pattern?: unknown;
+    properties?: unknown;
+    required?: unknown;
+    type?: unknown;
+};
+export {};