@mcoda/codali 0.1.108 → 0.1.109

package/dist/connectors/http/HttpToolDefinition.js

@@ -0,0 +1,190 @@
+import { ToolExecutionError } from "../../tools/ToolTypes.js";
+import { refreshAccessToken } from "../oauth/DeviceCodeAuth.js";
+import { truncateToolResult } from "../../tools/TruncateResult.js";
+/**
+ * Access tokens minted from refresh tokens, cached until shortly before expiry.
+ *
+ * Graph access tokens live about an hour. Without caching every tool call would
+ * spend a network round trip on a token it already holds; without the safety
+ * margin a call can start valid and arrive expired.
+ */
+const accessTokenCache = new Map();
+const TOKEN_EXPIRY_MARGIN_MS = 60000;
+export const resetAccessTokenCache = () => accessTokenCache.clear();
+const oauthAccessToken = async (auth, fetchImpl) => {
+    if (!auth.tokenUrl || !auth.clientId || !auth.refreshToken) {
+        throw new ToolExecutionError("missing_credentials", "oauth2_refresh requires tokenUrl, clientId and refreshToken. Run `codali auth microsoft`.", { retryable: false });
+    }
+    const key = `${auth.tokenUrl}|${auth.clientId}|${auth.refreshToken.slice(-16)}`;
+    const cached = accessTokenCache.get(key);
+    if (cached && cached.expiresAtMs > Date.now()) {
+        return cached.token;
+    }
+    try {
+        const tokens = await refreshAccessToken({ tokenUrl: auth.tokenUrl, clientId: auth.clientId, scope: auth.scope ?? "" }, auth.refreshToken, fetchImpl);
+        accessTokenCache.set(key, {
+            token: tokens.accessToken,
+            expiresAtMs: Date.now() + tokens.expiresInSeconds * 1000 - TOKEN_EXPIRY_MARGIN_MS,
+        });
+        return tokens.accessToken;
+    }
+    catch (error) {
+        throw new ToolExecutionError("missing_credentials", `Could not refresh the access token: ${error instanceof Error ? error.message : String(error)}. Re-run \`codali auth microsoft\`.`, { retryable: false });
+    }
+};
+const DEFAULT_TIMEOUT_MS = 20000;
+const DEFAULT_MAX_RESPONSE_CHARS = 12000;
+/**
+ * Only non-mutating verbs. A connector cannot opt into POST here — write access
+ * is a separate decision with its own approval story, not a config flag.
+ */
+const ALLOWED_METHODS = new Set(["GET", "HEAD"]);
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Substitutes `{name}` placeholders and appends anything left over as query
+ * parameters. Placeholder values are URL-encoded, so a model cannot inject a
+ * path segment or escape the connector's base URL.
+ */
+export const buildHttpUrl = (baseUrl, template, args) => {
+    const consumed = new Set();
+    const path = template.replace(/\{(\w+)\}/g, (_match, key) => {
+        const value = args[key];
+        if (value === undefined || value === null) {
+            throw new ToolExecutionError("tool_invalid_args", `Missing required path parameter "${key}".`, { retryable: false, details: { parameter: key } });
+        }
+        consumed.add(key);
+        return encodeURIComponent(String(value));
+    });
+    const url = new URL(path.replace(/^\//, ""), baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    for (const [key, value] of Object.entries(args)) {
+        if (consumed.has(key) || value === undefined || value === null)
+            continue;
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+};
+/**
+ * Projects a response down to what was asked for. `items[].name` maps over an
+ * array; a plain dotted path drills in.
+ */
+export const applyResponseSelector = (payload, selector) => {
+    if (!selector)
+        return payload;
+    let current = payload;
+    for (const segment of selector.split(".")) {
+        if (current === undefined || current === null)
+            return undefined;
+        const arrayMatch = segment.match(/^(\w+)\[\]$/);
+        if (arrayMatch) {
+            const key = arrayMatch[1];
+            const value = isRecord(current) ? current[key] : undefined;
+            if (!Array.isArray(value))
+                return undefined;
+            current = value;
+            continue;
+        }
+        if (Array.isArray(current)) {
+            current = current.map((entry) => (isRecord(entry) ? entry[segment] : undefined));
+            continue;
+        }
+        current = isRecord(current) ? current[segment] : undefined;
+    }
+    return current;
+};
+const buildAuthHeaders = (auth) => {
+    if (!auth || auth.type === "none")
+        return {};
+    if (auth.type === "bearer" && auth.token) {
+        return { Authorization: `Bearer ${auth.token}` };
+    }
+    if (auth.type === "basic" && auth.username) {
+        const encoded = Buffer.from(`${auth.username}:${auth.password ?? ""}`).toString("base64");
+        return { Authorization: `Basic ${encoded}` };
+    }
+    if (auth.type === "header" && auth.headerName && auth.token) {
+        return { [auth.headerName]: auth.token };
+    }
+    return {};
+};
+const truncate = (value, limit) => value.length > limit
+    ? `${value.slice(0, limit)}\n…[truncated ${value.length - limit} characters]`
+    : value;
+export const httpToolName = (connector, tool) => `http:${connector}:${tool}`;
+export const httpToolToDefinition = (declaration, options) => {
+    const { connector } = options;
+    if (!ALLOWED_METHODS.has(declaration.method)) {
+        throw new Error(`HTTP tool ${declaration.id} declares method ${declaration.method}; only GET and HEAD are permitted.`);
+    }
+    const qualified = httpToolName(connector.name, declaration.id);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = connector.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxChars = declaration.maxResponseChars ?? DEFAULT_MAX_RESPONSE_CHARS;
+    return {
+        name: qualified,
+        description: declaration.description,
+        inputSchema: declaration.inputSchema ?? {
+            type: "object",
+            properties: {},
+            additionalProperties: true,
+        },
+        // GET/HEAD only, enforced above.
+        readOnly: true,
+        capability: connector.name,
+        handler: async (args) => {
+            const record = isRecord(args) ? args : {};
+            const url = buildHttpUrl(connector.baseUrl, declaration.urlTemplate, record);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            // OAuth needs an await, so it is resolved before the request is built.
+            const authHeaders = connector.auth?.type === "oauth2_refresh"
+                ? { Authorization: `Bearer ${await oauthAccessToken(connector.auth, fetchImpl)}` }
+                : buildAuthHeaders(connector.auth);
+            let response;
+            try {
+                response = await fetchImpl(url, {
+                    method: declaration.method,
+                    headers: {
+                        Accept: "application/json",
+                        ...(connector.headers ?? {}),
+                        ...authHeaders,
+                    },
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                throw new ToolExecutionError("tool_execution_failed", `${qualified} request failed: ${error instanceof Error ? error.message : String(error)}`, { retryable: true, details: { tool: qualified } });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!response.ok) {
+                // The status is what a model needs to decide whether to try something
+                // else; the body may carry a credential, so it is not forwarded.
+                throw new ToolExecutionError(response.status === 401 || response.status === 403
+                    ? "tool_permission_denied"
+                    : "tool_execution_failed", `${qualified} returned HTTP ${response.status}.`, {
+                    retryable: response.status >= 500 || response.status === 429,
+                    details: { tool: qualified, status: response.status },
+                });
+            }
+            const text = await response.text();
+            let payload = text;
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                // Not JSON; the raw text is the payload.
+            }
+            const selected = applyResponseSelector(payload, declaration.responseSelector);
+            const serialized = typeof selected === "string" ? selected : JSON.stringify(selected, null, 2);
+            const trimmed = truncateToolResult(selected, serialized ?? "", maxChars);
+            return {
+                output: trimmed.text || "(empty response)",
+                data: selected,
+            };
+        },
+    };
+};
+export const httpConnectorToDefinitions = (options) => options.connector.enabled === false
+    ? []
+    : options.connector.tools.map((declaration) => httpToolToDefinition(declaration, options));

package/dist/connectors/http/HttpToolSource.d.ts

@@ -0,0 +1,18 @@
+import type { RunContext } from "../../runcontext/RunContextResolver.js";
+import type { ToolRegistry } from "../../tools/ToolRegistry.js";
+/**
+ * Registers a run's declared HTTP connectors into its existing tool registry,
+ * the same way MCP tools are attached. One registry remains the single source
+ * of truth regardless of where a tool came from.
+ */
+export interface HttpAttachResult {
+    registered: string[];
+    warnings: string[];
+}
+export interface HttpAttachOptions {
+    context: RunContext;
+    toolRegistry: ToolRegistry;
+    fetchImpl?: typeof fetch;
+}
+export declare const attachHttpTools: (options: HttpAttachOptions) => HttpAttachResult;
+//# sourceMappingURL=HttpToolSource.d.ts.map

package/dist/connectors/http/HttpToolSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpToolSource.d.ts","sourceRoot":"","sources":["../../../src/connectors/http/HttpToolSource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE;;;;GAIG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,eAAO,MAAM,eAAe,GAAI,SAAS,iBAAiB,KAAG,gBAoC5D,CAAC"}

package/dist/connectors/http/HttpToolSource.js

@@ -0,0 +1,29 @@
+import { httpConnectorToDefinitions } from "./HttpToolDefinition.js";
+export const attachHttpTools = (options) => {
+    const connectors = options.context.httpConnectors ?? [];
+    const registered = [];
+    const warnings = [];
+    for (const connector of connectors) {
+        let definitions;
+        try {
+            definitions = httpConnectorToDefinitions({ connector, fetchImpl: options.fetchImpl });
+        }
+        catch (error) {
+            // A connector declaring a mutating method is a configuration error, not a
+            // runtime one. Reject the connector and say why rather than silently
+            // dropping it or, worse, allowing the write.
+            warnings.push(`http_connector_rejected:${connector.name}:${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        for (const definition of definitions) {
+            try {
+                options.toolRegistry.register(definition);
+                registered.push(definition.name);
+            }
+            catch (error) {
+                warnings.push(`http_tool_registration_failed:${definition.name}:${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    return { registered, warnings };
+};

package/dist/connectors/mcp/McpClient.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Minimal MCP client.
+ *
+ * Deliberately covers only `tools/list` and `tools/call`. Resources and prompts
+ * are deferred because no requirement in `codali_workflow.txt` needs them, and
+ * an unused surface is still a surface to maintain and secure.
+ *
+ * The transports come from the official SDK rather than being hand-rolled, so
+ * protocol lifecycle, framing, and session handling stay the SDK's problem.
+ * Only the two transports the spec currently defines are offered — stdio and
+ * Streamable HTTP. There is no separate legacy HTTP+SSE transport: current MCP
+ * carries SSE *within* Streamable HTTP where it is needed.
+ */
+/**
+ * Protocol version this build was written and tested against. Asserted in
+ * tests so an SDK bump that changes the wire protocol fails loudly here rather
+ * than silently against a live server.
+ */
+export declare const CODALI_MCP_PROTOCOL_VERSION = "2025-11-25";
+export declare const CODALI_MCP_CLIENT_INFO: {
+    readonly name: "codali";
+    readonly version: "1.0.0";
+};
+export type McpTransportKind = "stdio" | "http";
+export interface McpStdioTransportConfig {
+    transport: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface McpHttpTransportConfig {
+    transport: "http";
+    url: string;
+    headers?: Record<string, string>;
+}
+export type McpTransportConfig = McpStdioTransportConfig | McpHttpTransportConfig;
+export interface McpServerConfig {
+    name: string;
+    enabled?: boolean;
+    timeoutMs?: number;
+    /**
+     * Operator's declaration that this server's exposed tools are read-only.
+     *
+     * Defaults to `false`, and that default is deliberate. A server's own
+     * `readOnlyHint` cannot be trusted — it is the party being constrained
+     * vouching for itself — and Codali has no other way to know whether
+     * `edit_file` edits a file. So an unvetted server's tools are treated as
+     * capable of mutation, which keeps them out of the default tool set until an
+     * operator either declares the server read-only or names the specific tools
+     * to expose via `allowTools`.
+     */
+    readOnly?: boolean;
+    /**
+     * Tools to expose from this server. Absent means all discovered tools.
+     * Deny always wins over allow.
+     */
+    allowTools?: string[];
+    denyTools?: string[];
+}
+export type McpServerDefinition = McpServerConfig & McpTransportConfig;
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Server-supplied hints (`readOnlyHint`, `destructiveHint`, …).
+     *
+     * Retained for display and diagnostics only. These are **not** trusted for
+     * security decisions: a server declaring itself read-only is an assertion by
+     * the very party being constrained. Codali policy decides what may run.
+     */
+    annotations?: Record<string, unknown>;
+}
+export interface McpCallResult {
+    ok: boolean;
+    text: string;
+    structured?: unknown;
+    raw: unknown;
+}
+export declare class McpClientError extends Error {
+    readonly code: string;
+    readonly server: string;
+    readonly retryable: boolean;
+    constructor(code: string, server: string, message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * Flattens MCP content blocks into text the model can read. Non-text blocks are
+ * described rather than dropped, so a run never silently loses a result it
+ * cannot render.
+ */
+export declare const flattenMcpContent: (content: unknown) => string;
+export interface McpClientOptions {
+    definition: McpServerDefinition;
+    /** Injected in tests to avoid spawning processes or opening sockets. */
+    createClient?: () => Promise<McpTransportClient>;
+}
+/** The slice of the SDK client this wrapper depends on. */
+export interface McpTransportClient {
+    listTools(params?: Record<string, unknown>, options?: {
+        timeout?: number;
+    }): Promise<{
+        tools: unknown[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }, resultSchema?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare class McpClient {
+    private readonly options;
+    private client?;
+    private connecting?;
+    constructor(options: McpClientOptions);
+    get name(): string;
+    private get timeoutMs();
+    /** Connects lazily; concurrent callers share one in-flight connection. */
+    private ensureClient;
+    private connect;
+    listTools(): Promise<McpToolDefinition[]>;
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+export declare const createMcpClient: (options: McpClientOptions) => McpClient;
+//# sourceMappingURL=McpClient.d.ts.map

package/dist/connectors/mcp/McpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpClient.d.ts","sourceRoot":"","sources":["../../../src/connectors/mcp/McpClient.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAkCxD,eAAO,MAAM,sBAAsB;;;CAGzB,CAAC;AAIX,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,kBAAkB,GAAG,uBAAuB,GAAG,sBAAsB,CAAC;AAElF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,kBAAkB,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAG1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAWzD;AAKD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,KAAG,MAkBpD,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,mBAAmB,CAAC;IAChC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAClD;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,SAAS,CACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;IACjC,QAAQ,CACN,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAC7D,YAAY,CAAC,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,MAAM,CAAC,CAAqB;IACpC,OAAO,CAAC,UAAU,CAAC,CAA8B;gBAEpB,OAAO,EAAE,gBAAgB;IAEtD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,OAAO,KAAK,SAAS,GAEpB;IAED,0EAA0E;YAC5D,YAAY;YAWZ,OAAO;IA6Cf,SAAS,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAqCzC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAmC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B;AAED,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SACpC,CAAC"}

package/dist/connectors/mcp/McpClient.js

@@ -0,0 +1,215 @@
+/**
+ * Minimal MCP client.
+ *
+ * Deliberately covers only `tools/list` and `tools/call`. Resources and prompts
+ * are deferred because no requirement in `codali_workflow.txt` needs them, and
+ * an unused surface is still a surface to maintain and secure.
+ *
+ * The transports come from the official SDK rather than being hand-rolled, so
+ * protocol lifecycle, framing, and session handling stay the SDK's problem.
+ * Only the two transports the spec currently defines are offered — stdio and
+ * Streamable HTTP. There is no separate legacy HTTP+SSE transport: current MCP
+ * carries SSE *within* Streamable HTTP where it is needed.
+ */
+/**
+ * Protocol version this build was written and tested against. Asserted in
+ * tests so an SDK bump that changes the wire protocol fails loudly here rather
+ * than silently against a live server.
+ */
+export const CODALI_MCP_PROTOCOL_VERSION = "2025-11-25";
+/**
+ * The SDK is imported lazily, only when a run actually connects to an MCP
+ * server.
+ *
+ * mswarm vendors Codali's built output and does not depend on the SDK itself,
+ * so a top-level import broke every mswarm test with a module-resolution error
+ * for a package its cloud path never uses. Loading on demand keeps the
+ * dependency where it belongs: paid for by whoever configures a server.
+ */
+const loadMcpSdk = async () => {
+    try {
+        const [clientModule, stdioModule, httpModule] = await Promise.all([
+            import("@modelcontextprotocol/sdk/client/index.js"),
+            import("@modelcontextprotocol/sdk/client/stdio.js"),
+            import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+        ]);
+        return {
+            Client: clientModule.Client,
+            StdioClientTransport: stdioModule.StdioClientTransport,
+            StreamableHTTPClientTransport: httpModule.StreamableHTTPClientTransport,
+        };
+    }
+    catch (error) {
+        throw new McpClientError("mcp_sdk_unavailable", "sdk", "MCP support needs @modelcontextprotocol/sdk, which is not installed in this build. " +
+            "Remove the configured mcpServers, or install the package.", { cause: error });
+    }
+};
+export const CODALI_MCP_CLIENT_INFO = {
+    name: "codali",
+    version: "1.0.0",
+};
+const DEFAULT_TIMEOUT_MS = 30000;
+export class McpClientError extends Error {
+    constructor(code, server, message, options = {}) {
+        super(message);
+        this.name = "McpClientError";
+        this.code = code;
+        this.server = server;
+        this.retryable = options.retryable ?? false;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Flattens MCP content blocks into text the model can read. Non-text blocks are
+ * described rather than dropped, so a run never silently loses a result it
+ * cannot render.
+ */
+export const flattenMcpContent = (content) => {
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (!isRecord(block))
+            continue;
+        const type = typeof block.type === "string" ? block.type : "";
+        if (type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+        else if (type === "resource" && isRecord(block.resource)) {
+            const resource = block.resource;
+            const text = typeof resource.text === "string" ? resource.text : undefined;
+            const uri = typeof resource.uri === "string" ? resource.uri : "unknown";
+            parts.push(text ?? `[resource ${uri}]`);
+        }
+        else if (type) {
+            parts.push(`[${type} content omitted]`);
+        }
+    }
+    return parts.join("\n").trim();
+};
+export class McpClient {
+    constructor(options) {
+        this.options = options;
+    }
+    get name() {
+        return this.options.definition.name;
+    }
+    get timeoutMs() {
+        return this.options.definition.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** Connects lazily; concurrent callers share one in-flight connection. */
+    async ensureClient() {
+        if (this.client)
+            return this.client;
+        this.connecting ?? (this.connecting = this.connect());
+        try {
+            this.client = await this.connecting;
+            return this.client;
+        }
+        finally {
+            this.connecting = undefined;
+        }
+    }
+    async connect() {
+        if (this.options.createClient) {
+            return this.options.createClient();
+        }
+        const definition = this.options.definition;
+        const sdk = await loadMcpSdk();
+        const client = new sdk.Client(CODALI_MCP_CLIENT_INFO, {
+            capabilities: {},
+        });
+        try {
+            if (definition.transport === "stdio") {
+                await client.connect(new sdk.StdioClientTransport({
+                    command: definition.command,
+                    args: definition.args,
+                    env: definition.env,
+                    cwd: definition.cwd,
+                    // Server diagnostics must not be interleaved into Codali's own
+                    // stdout, which carries the answer.
+                    stderr: "pipe",
+                }));
+            }
+            else {
+                await client.connect(new sdk.StreamableHTTPClientTransport(new URL(definition.url), {
+                    requestInit: definition.headers ? { headers: definition.headers } : undefined,
+                }));
+            }
+        }
+        catch (error) {
+            throw new McpClientError("mcp_connect_failed", definition.name, `Could not connect to MCP server "${definition.name}": ${error instanceof Error ? error.message : String(error)}`, { retryable: true, cause: error });
+        }
+        return client;
+    }
+    async listTools() {
+        const client = await this.ensureClient();
+        let response;
+        try {
+            response = await client.listTools(undefined, { timeout: this.timeoutMs });
+        }
+        catch (error) {
+            throw new McpClientError("mcp_list_tools_failed", this.name, `tools/list failed for "${this.name}": ${error instanceof Error ? error.message : String(error)}`, { retryable: true, cause: error });
+        }
+        const definition = this.options.definition;
+        const allow = definition.allowTools ? new Set(definition.allowTools) : undefined;
+        const deny = new Set(definition.denyTools ?? []);
+        const tools = [];
+        for (const entry of response.tools ?? []) {
+            if (!isRecord(entry) || typeof entry.name !== "string")
+                continue;
+            // Deny wins over allow, always.
+            if (deny.has(entry.name))
+                continue;
+            if (allow && !allow.has(entry.name))
+                continue;
+            tools.push({
+                name: entry.name,
+                description: typeof entry.description === "string" ? entry.description : undefined,
+                inputSchema: isRecord(entry.inputSchema) ? entry.inputSchema : undefined,
+                outputSchema: isRecord(entry.outputSchema) ? entry.outputSchema : undefined,
+                annotations: isRecord(entry.annotations) ? entry.annotations : undefined,
+            });
+        }
+        return tools;
+    }
+    async callTool(name, args) {
+        const client = await this.ensureClient();
+        let raw;
+        try {
+            raw = await client.callTool({ name, arguments: isRecord(args) ? args : {} }, undefined, { timeout: this.timeoutMs });
+        }
+        catch (error) {
+            throw new McpClientError("mcp_call_tool_failed", this.name, `tools/call ${name} failed on "${this.name}": ${error instanceof Error ? error.message : String(error)}`, { retryable: true, cause: error });
+        }
+        const record = isRecord(raw) ? raw : {};
+        // MCP reports tool-level failures in-band via isError rather than as a
+        // protocol error, so a successful transport round trip can still be a
+        // failed call.
+        const isError = record.isError === true;
+        const text = flattenMcpContent(record.content);
+        return {
+            ok: !isError,
+            text: text || (isError ? "Tool reported an error with no message." : ""),
+            structured: record.structuredContent,
+            raw,
+        };
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        if (!client)
+            return;
+        try {
+            await client.close();
+        }
+        catch {
+            // A server that fails to close cleanly must not fail the run; the process
+            // is exiting or the connection is already gone.
+        }
+    }
+}
+export const createMcpClient = (options) => new McpClient(options);

package/dist/connectors/mcp/McpServerRegistry.d.ts

@@ -0,0 +1,75 @@
+import type { ToolDefinition } from "../../tools/ToolTypes.js";
+import { McpClient, type McpServerDefinition } from "./McpClient.js";
+/**
+ * Owns the lifetime of every configured MCP server.
+ *
+ * Three properties matter more than features here:
+ *
+ *   - **Isolation.** One broken server degrades its own tools to unavailable
+ *     and never fails the run or affects another server.
+ *   - **Boundedness.** Every call has a timeout, at most one retry, and
+ *     competes for a global concurrency budget, so a slow server cannot
+ *     monopolise a run.
+ *   - **Cleanup.** stdio servers are child processes. They must be shut down
+ *     even when a run fails, or the CLI leaves orphans behind.
+ */
+/** Concurrent in-flight MCP calls across all servers. */
+export declare const DEFAULT_MAX_CONCURRENT_CALLS = 4;
+export interface McpServerHealth {
+    name: string;
+    status: "connected" | "failed" | "disabled";
+    toolCount: number;
+    error?: string;
+    discoveryMs?: number;
+}
+export interface McpServerRegistryOptions {
+    servers: readonly McpServerDefinition[];
+    maxConcurrentCalls?: number;
+    /** Injected in tests. */
+    createClient?: (definition: McpServerDefinition) => McpClient;
+    onEvent?: (event: McpRegistryEvent) => void;
+}
+export type McpRegistryEvent = {
+    type: "server_connected";
+    server: string;
+    toolCount: number;
+    durationMs: number;
+} | {
+    type: "server_failed";
+    server: string;
+    error: string;
+} | {
+    type: "server_skipped";
+    server: string;
+    reason: string;
+};
+export declare class McpServerRegistry {
+    private readonly options;
+    private readonly clients;
+    private readonly health;
+    private readonly semaphore;
+    private discovered;
+    constructor(options: McpServerRegistryOptions);
+    /**
+     * Connects to every enabled server and returns their tools as Codali tool
+     * definitions. Servers are contacted in parallel; a failure is recorded as
+     * unhealthy rather than thrown, so one bad entry in a tenant's config cannot
+     * take down the run.
+     */
+    discoverTools(): Promise<ToolDefinition[]>;
+    /**
+     * Wraps a client so every tool call is bounded by the concurrency budget and
+     * retried once on a transport failure. Retrying is safe here because Phase 2
+     * connectors are read-only.
+     */
+    private wrapClient;
+    healthReport(): McpServerHealth[];
+    get isDiscovered(): boolean;
+    /**
+     * Shuts down every connection. Must run even when a run fails: stdio servers
+     * are child processes and would otherwise be orphaned.
+     */
+    close(): Promise<void>;
+}
+export declare const createMcpServerRegistry: (options: McpServerRegistryOptions) => McpServerRegistry;
+//# sourceMappingURL=McpServerRegistry.d.ts.map

package/dist/connectors/mcp/McpServerRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpServerRegistry.d.ts","sourceRoot":"","sources":["../../../src/connectors/mcp/McpServerRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EACL,SAAS,EAET,KAAK,mBAAmB,EAEzB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;;;;;;GAYG;AAEH,yDAAyD;AACzD,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAK9C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,SAAS,CAAC;IAC9D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACnF;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA0B/D,qBAAa,iBAAiB;IAMhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,UAAU,CAAS;gBAEE,OAAO,EAAE,wBAAwB;IAM9D;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAmFhD;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA4BlB,YAAY,IAAI,eAAe,EAAE;IAIjC,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAED,eAAO,MAAM,uBAAuB,GAClC,SAAS,wBAAwB,KAChC,iBAAmD,CAAC"}