@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-capability-catalog`.
+ * @module @khorsheed/dsh-capability-catalog/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "capability-catalog-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-capability-catalog`.
+ * @module @khorsheed/dsh-capability-catalog/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-capability-catalog';
+/** Cordis companion plugin name. */
+export const name = 'capability-catalog-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the catalog is read-only over existing registries
+ * (ctx.skills / ctx.tools) and the add-skill write path validates its inputs
+ * before touching disk. The unit tests exercise the channel attribution,
+ * skill decoding, and the wire projection.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/mcpConnector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * MCP connector backed by the official `@modelcontextprotocol/sdk` (the same
+ * library `@deepseek-ai/dsh-mcp-client` uses). Kept as a thin, swappable seam:
+ * the catalog owns the connection lifecycle (connect → list → register tools →
+ * call → close) and registers discovered tools on `ctx.tools`. If upstream later
+ * exposes a stable dynamic `connect(ctx, config)`, swap this adapter for it.
+ *
+ * v1 scope: stdio + streamable-http connect, paginated `tools/list`,
+ * `tools/call` passthrough, and close. Reconnect/atomic-replace/tool-filter are
+ * follow-ups.
+ * @module @khorsheed/dsh-capability-catalog/mcpConnector
+ */
+import type { CatalogMcpServerConfig, CatalogMcpTool } from './types.ts';
+/** One live MCP connection. */
+export interface McpConnection {
+    readonly tools: readonly CatalogMcpTool[];
+    call: (toolName: string, args: Record<string, unknown>) => Promise<unknown>;
+    close: () => Promise<void>;
+}
+/** Resolve a secretRef marker to its stored value (the catalog's ctx.credentials). */
+export type ResolveSecret = (ref: string) => Promise<string | undefined>;
+/** Connect, discover all tools (follow pagination), and return a live handle. */
+export declare function connectMcpServer(config: CatalogMcpServerConfig): Promise<McpConnection>;
+//# sourceMappingURL=mcpConnector.d.ts.map

package/lib/types/mcpConnector.js

@@ -0,0 +1,73 @@
+/**
+ * MCP connector backed by the official `@modelcontextprotocol/sdk` (the same
+ * library `@deepseek-ai/dsh-mcp-client` uses). Kept as a thin, swappable seam:
+ * the catalog owns the connection lifecycle (connect → list → register tools →
+ * call → close) and registers discovered tools on `ctx.tools`. If upstream later
+ * exposes a stable dynamic `connect(ctx, config)`, swap this adapter for it.
+ *
+ * v1 scope: stdio + streamable-http connect, paginated `tools/list`,
+ * `tools/call` passthrough, and close. Reconnect/atomic-replace/tool-filter are
+ * follow-ups.
+ * @module @khorsheed/dsh-capability-catalog/mcpConnector
+ */
+// The SDK is a third-party host dep the gen-typert overlay cannot resolve
+// (only @deepseek-ai/* + harness node_modules). @ts-ignore keeps generation
+// green; at runtime the host resolves these from node_modules.
+// @ts-ignore
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+// @ts-ignore
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+// @ts-ignore
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/** Build the transport for a config (secrets already resolved to plaintext). */
+function makeTransport(config) {
+    if (config.transport === 'stdio') {
+        const env = {};
+        for (const [k, v] of config.env ?? [])
+            env[k] = v;
+        return new StdioClientTransport({
+            command: config.command ?? 'npx',
+            args: [...(config.args ?? [])],
+            ...(Object.keys(env).length > 0 ? { env } : {}),
+            ...(config.cwd ? { cwd: config.cwd } : {}),
+        });
+    }
+    // streamable-http: the SDK transport takes headers via `requestInit` — without
+    // them an auth-bearing server (e.g. `Authorization`, `x-api-key`) is never
+    // authenticated. Plaintext header values arrive here after secret resolution.
+    const headers = config.headers ?? [];
+    if (headers.length > 0) {
+        return new StreamableHTTPClientTransport(new URL(config.url ?? ''), {
+            requestInit: { headers: Object.fromEntries(headers) },
+        });
+    }
+    return new StreamableHTTPClientTransport(new URL(config.url ?? ''));
+}
+/** Map an SDK tool to the catalog's tool row (enabled by default). */
+function toCatalogTool(sdkTool) {
+    return {
+        name: sdkTool.name,
+        description: sdkTool.description ?? '',
+        ...(sdkTool.inputSchema !== undefined ? { parameters: sdkTool.inputSchema } : {}),
+        enabled: true,
+    };
+}
+/** Connect, discover all tools (follow pagination), and return a live handle. */
+export async function connectMcpServer(config) {
+    const client = new Client({ name: 'dsh-capability-catalog', version: '0.1.0' });
+    const transport = makeTransport(config);
+    await client.connect(transport);
+    const tools = [];
+    let cursor;
+    do {
+        const page = await client.listTools(cursor === undefined ? undefined : { cursor });
+        for (const t of page.tools)
+            tools.push(toCatalogTool(t));
+        cursor = page.nextCursor;
+    } while (cursor !== undefined);
+    return {
+        tools,
+        call: async (toolName, args) => client.callTool({ name: toolName, arguments: args }),
+        close: async () => { await client.close().catch(() => { }); },
+    };
+}

package/lib/types/mcpStore.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Host-side MCP server store: keeps the user's configured MCP servers, their
+ * discovered tools, credential state, and enable flags. Persistence is a pluggable
+ * seam: the host hands the store an `onPersist` callback (backed by the settings
+ * namespace) and seeds it with `loadFrom` at boot, so servers survive a restart.
+ * Tool discovery connects via the SDK connector and caches the tool list.
+ */
+import type { CatalogMcpCredentialDecl, CatalogMcpServerConfig, CatalogMcpTool } from './types.ts';
+/** One tool's persisted record: the user's toggle choice only. Descriptions and
+ * parameter schemas are discovered at connect time and deliberately NOT persisted
+ * (they bloat settings.yaml and go stale); `reconnectAll` re-fills them at boot. */
+export interface PersistedMcpTool {
+    readonly name: string;
+    readonly enabled: boolean;
+}
+/** Wire/persisted form of one stored server (config + enabled + tool toggles). */
+export interface PersistedMcpServer {
+    readonly config: CatalogMcpServerConfig;
+    readonly tools: readonly PersistedMcpTool[];
+}
+/** The full persisted MCP state block (stored under the settings namespace `mcp` key). */
+export interface PersistedMcpState {
+    readonly servers?: readonly PersistedMcpServer[];
+    /** Namespaced credential ref -> value (the user's own config document). */
+    readonly credentials?: Readonly<Record<string, string>>;
+}
+/** The catalog's own MCP management store (one per process). */
+export declare class McpStore {
+    private readonly servers;
+    /** Persistence hook, set by the host after the settings scope is available. */
+    onPersist: (() => void) | undefined;
+    /** Seed the store from the persisted state (boot or external config edit). */
+    loadFrom(state: PersistedMcpState | undefined): void;
+    /** Serialize the current state for persistence. */
+    toPersisted(): PersistedMcpState;
+    private persist;
+    list(): CatalogMcpServerConfig[];
+    /** Discovered tool list per server (name → tools). */
+    toolsByServer(): Record<string, readonly CatalogMcpTool[]>;
+    /** Credential declarations for all servers (whether configured, never the value). */
+    credentials(): CatalogMcpCredentialDecl[];
+    /** Add / replace a server config (keeps its credentials if already present). */
+    add(config: CatalogMcpServerConfig): void;
+    remove(serverName: string): void;
+    /** Set server-level enable flag (discovery/registration is the caller's job). */
+    setEnabled(serverName: string, enabled: boolean): void;
+    /** Set one credential value (empty clears it). */
+    setCredential(ref: string, value: string): void;
+    /** Configure a tool's enable flag. */
+    setToolEnabled(serverName: string, toolName: string, enabled: boolean): void;
+    /** Connect + discover tools for a server; caches the list (connect errors surface). */
+    discover(serverName: string): Promise<readonly CatalogMcpTool[]>;
+    /** Re-connect + re-discover every enabled server — boot-time refill of the
+     * discovered descriptions/parameters (the persisted block stores only
+     * name+enabled). Preserves per-tool enable flags; per-server errors are
+     * recorded and do not stop the others. */
+    reconnectAll(): Promise<void>;
+    /** A server's most recent connection/dev error. */
+    errorOf(serverName: string): string | undefined;
+    /** Forward one tool call to a server (connect → call → close). Resolves secrets. */
+    callTool(serverName: string, rawName: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Extract credential reference paths from a config (env/header/url-query).
+     * Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */
+    private credentialRefsOf;
+}
+/** Whether a config value contains an unresolved secret marker (bare or scheme-prefixed). */
+export declare function isSecretRef(value: string): boolean;
+//# sourceMappingURL=mcpStore.d.ts.map

package/lib/types/mcpStore.js

@@ -0,0 +1,235 @@
+/**
+ * Host-side MCP server store: keeps the user's configured MCP servers, their
+ * discovered tools, credential state, and enable flags. Persistence is a pluggable
+ * seam: the host hands the store an `onPersist` callback (backed by the settings
+ * namespace) and seeds it with `loadFrom` at boot, so servers survive a restart.
+ * Tool discovery connects via the SDK connector and caches the tool list.
+ */
+import { resolveConfigSecrets } from './mcps.js';
+/** The catalog's own MCP management store (one per process). */
+export class McpStore {
+    servers = new Map();
+    /** Persistence hook, set by the host after the settings scope is available. */
+    onPersist = undefined;
+    /** Seed the store from the persisted state (boot or external config edit). */
+    loadFrom(state) {
+        if (state === undefined)
+            return;
+        for (const server of state.servers ?? []) {
+            const existing = this.servers.get(server.config.serverName);
+            // Keep descriptions/parameters already discovered in memory: the persisted
+            // block is authoritative only for the per-tool enabled flag (it stores just
+            // name+enabled), so a reload — e.g. after our own persist round-trips through
+            // the settings watch — must merge the toggle rather than wipe the tools.
+            const known = new Map((existing?.tools ?? []).map(t => [t.name, t]));
+            const tools = (server.tools ?? []).map(t => {
+                const prev = known.get(t.name);
+                return prev !== undefined
+                    ? { ...prev, enabled: t.enabled }
+                    : { name: t.name, description: '', enabled: t.enabled };
+            });
+            this.servers.set(server.config.serverName, {
+                config: server.config,
+                credentials: existing?.credentials ?? new Map(),
+                tools,
+                error: undefined,
+            });
+        }
+        for (const [ref, value] of Object.entries(state.credentials ?? {})) {
+            const s = this.servers.get(refServer(ref));
+            if (s !== undefined)
+                s.credentials.set(ref, value);
+        }
+    }
+    /** Serialize the current state for persistence. */
+    toPersisted() {
+        const servers = [...this.servers.values()]
+            .sort((a, b) => a.config.serverName.localeCompare(b.config.serverName))
+            .map(s => ({ config: s.config, tools: s.tools.map(t => ({ name: t.name, enabled: t.enabled })) }));
+        const credentials = {};
+        for (const s of this.servers.values())
+            for (const [ref, value] of s.credentials)
+                credentials[ref] = value;
+        return { servers, credentials };
+    }
+    persist() {
+        this.onPersist?.();
+    }
+    list() {
+        return [...this.servers.values()].map(s => ({ ...s.config, enabled: s.config.enabled })).sort((a, b) => a.serverName.localeCompare(b.serverName));
+    }
+    /** Discovered tool list per server (name → tools). */
+    toolsByServer() {
+        const out = {};
+        for (const [name, s] of this.servers)
+            out[name] = s.tools;
+        return out;
+    }
+    /** Credential declarations for all servers (whether configured, never the value). */
+    credentials() {
+        const out = [];
+        for (const [name, s] of this.servers) {
+            for (const ref of this.credentialRefsOf(s.config)) {
+                out.push({ ref, label: refLabel(ref), configured: s.credentials.has(ref) });
+            }
+            void name;
+        }
+        return out;
+    }
+    /** Add / replace a server config (keeps its credentials if already present). */
+    add(config) {
+        const existing = this.servers.get(config.serverName);
+        this.servers.set(config.serverName, {
+            config,
+            credentials: existing?.credentials ?? new Map(),
+            tools: existing?.tools ?? [],
+            error: existing?.error,
+        });
+        this.persist();
+    }
+    remove(serverName) {
+        if (this.servers.delete(serverName))
+            this.persist();
+    }
+    /** Set server-level enable flag (discovery/registration is the caller's job). */
+    setEnabled(serverName, enabled) {
+        const s = this.servers.get(serverName);
+        if (s === undefined)
+            return;
+        s.config = { ...s.config, enabled };
+        this.persist();
+    }
+    /** Set one credential value (empty clears it). */
+    setCredential(ref, value) {
+        const serverName = refServer(ref);
+        const s = this.servers.get(serverName);
+        if (s === undefined)
+            return;
+        if (value === '')
+            s.credentials.delete(ref);
+        else
+            s.credentials.set(ref, value);
+        this.persist();
+    }
+    /** Configure a tool's enable flag. */
+    setToolEnabled(serverName, toolName, enabled) {
+        const s = this.servers.get(serverName);
+        if (s === undefined)
+            return;
+        s.tools = s.tools.map(t => (t.name === toolName ? { ...t, enabled } : t));
+        this.persist();
+    }
+    /** Connect + discover tools for a server; caches the list (connect errors surface). */
+    async discover(serverName) {
+        const s = this.servers.get(serverName);
+        if (s === undefined)
+            return [];
+        try {
+            // Dynamic import keeps the SDK-backed connector out of the typert-analyzed
+            // host face (third-party SDK types aren't resolvable in the gen-typert overlay).
+            const { connectMcpServer } = await import('./mcpConnector.js');
+            // Resolve secretRef markers to the stored credential values before connecting,
+            // so a configured API key is sent as its real value (never the secretRef).
+            const resolved = await resolveConfigSecrets(s.config, async (ref) => {
+                const candidates = [
+                    `mcp.${serverName}.env.${ref}`,
+                    `mcp.${serverName}.header.${ref}`,
+                    `mcp.${serverName}.query.${ref}`,
+                ];
+                for (const candidate of candidates) {
+                    const value = s.credentials.get(candidate);
+                    if (value !== undefined)
+                        return value;
+                }
+                return undefined;
+            });
+            const connection = await connectMcpServer(resolved);
+            // Preserve the user's per-tool enable flags — re-discovering refreshes
+            // descriptions/parameters without resetting toggles (new tools default on).
+            const prevEnabled = new Map(s.tools.map(t => [t.name, t.enabled]));
+            s.tools = connection.tools.map(t => ({ ...t, enabled: prevEnabled.get(t.name) ?? true }));
+            s.error = undefined;
+            await connection.close();
+            this.persist();
+            return s.tools;
+        }
+        catch (error) {
+            s.error = String(error);
+            this.persist();
+            return s.tools;
+        }
+    }
+    /** Re-connect + re-discover every enabled server — boot-time refill of the
+     * discovered descriptions/parameters (the persisted block stores only
+     * name+enabled). Preserves per-tool enable flags; per-server errors are
+     * recorded and do not stop the others. */
+    async reconnectAll() {
+        for (const server of this.list()) {
+            if (!server.enabled)
+                continue;
+            await this.discover(server.serverName);
+        }
+    }
+    /** A server's most recent connection/dev error. */
+    errorOf(serverName) {
+        return this.servers.get(serverName)?.error;
+    }
+    /** Forward one tool call to a server (connect → call → close). Resolves secrets. */
+    async callTool(serverName, rawName, args) {
+        const s = this.servers.get(serverName);
+        if (s === undefined)
+            throw new Error(`unknown MCP server: ${serverName}`);
+        const resolved = await resolveConfigSecrets(s.config, async (ref) => {
+            const candidates = [
+                `mcp.${serverName}.env.${ref}`,
+                `mcp.${serverName}.header.${ref}`,
+                `mcp.${serverName}.query.${ref}`,
+            ];
+            for (const candidate of candidates) {
+                const value = s.credentials.get(candidate);
+                if (value !== undefined)
+                    return value;
+            }
+            return undefined;
+        });
+        const { connectMcpServer } = await import('./mcpConnector.js');
+        const connection = await connectMcpServer(resolved);
+        try {
+            return await connection.call(rawName, args);
+        }
+        finally {
+            await connection.close();
+        }
+    }
+    /** Extract credential reference paths from a config (env/header/url-query).
+     * Namespaced `mcp.<serverName>.env.<KEY>` so multiple servers don't collide. */
+    credentialRefsOf(config) {
+        const refs = [];
+        for (const [k, v] of config.env ?? [])
+            if (isSecretRef(v))
+                refs.push(`mcp.${config.serverName}.env.${k}`);
+        for (const [k, v] of config.headers ?? [])
+            if (isSecretRef(v))
+                refs.push(`mcp.${config.serverName}.header.${k}`);
+        if (config.url !== undefined) {
+            for (const m of config.url.matchAll(/secretRef:([A-Za-z0-9_.-]+)/g)) {
+                refs.push(`mcp.${config.serverName}.query.${m[1]}`);
+            }
+        }
+        return refs;
+    }
+}
+/** Whether a config value contains an unresolved secret marker (bare or scheme-prefixed). */
+export function isSecretRef(value) {
+    return value.includes('secretRef:');
+}
+/** Human label for a namespaced ref (strip the `mcp.<server>.` prefix). */
+function refLabel(ref) {
+    const idx = ref.indexOf('.');
+    return ref.slice(idx + 1);
+}
+/** The server name a namespaced credential ref belongs to (`mcp.<server>…`). */
+function refServer(ref) {
+    const m = /^mcp\.([A-Za-z0-9_-]+)\./.exec(ref);
+    return m?.[1] ?? '';
+}

package/lib/types/mcpTools.d.ts

@@ -0,0 +1,45 @@
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { CatalogJsonValue, CatalogMcpTool } from './types.ts';
+/** Deterministic model-facing name for `(serverName, rawName)`. */
+export declare function publicToolName(serverName: string, rawName: string): string;
+/** A tool-invocation forwarder (connects, resolves secrets, calls, closes). */
+export type McpToolCallFn = (serverName: string, rawName: string, args: Record<string, unknown>) => Promise<unknown>;
+/** Extract human-readable text from MCP content blocks (text blocks joined). */
+export declare function extractText(content: readonly unknown[] | undefined): string;
+/** Build a harness `ToolDefinition` for one discovered MCP tool. */
+export declare function mcpToolDefinition(opts: {
+    publicName: string;
+    serverName: string;
+    rawName: string;
+    description: string;
+    parameters: CatalogJsonValue | undefined;
+    callTool: McpToolCallFn;
+}): ToolDefinition;
+/** One desired registration during reconcile. */
+export interface DesiredMcpTool {
+    readonly publicName: string;
+    readonly serverName: string;
+    readonly rawName: string;
+    readonly description: string;
+    readonly parameters: CatalogJsonValue | undefined;
+}
+/**
+ * The tools registry seam. IMPORTANT: `register` must be invoked as a MEMBER
+ * call on `tools` (the traceable proxy) — never extracted to a standalone
+ * variable — so `this.ctx` (effect/scope ownership) resolves correctly.
+ */
+export interface McpToolRegistry {
+    register(definition: ToolDefinition): () => void;
+    onRegisterError?: (error: unknown) => void;
+}
+/**
+ * Reconcile registered MCP tools: dispose every previously-registered tool, then
+ * register the desired set. Registration failures are contained per tool.
+ */
+export declare function reconcileRegisteredMcpTools(desired: readonly DesiredMcpTool[], registry: McpToolRegistry, current: Map<string, () => void>, callTool: McpToolCallFn): void;
+/** Compute the desired set from enabled servers + their enabled tools. */
+export declare function desiredMcpTools(servers: readonly {
+    readonly serverName: string;
+    readonly enabled: boolean;
+}[], toolsByServer: Readonly<Record<string, readonly CatalogMcpTool[]>>): DesiredMcpTool[];
+//# sourceMappingURL=mcpTools.d.ts.map

package/lib/types/mcpTools.js

@@ -0,0 +1,125 @@
+/**
+ * MCP tool bridge: turns catalog-discovered MCP tools into harness `ToolDefinition`s
+ * registered on `ctx.tools` so the model can call them. A bounded subset of the
+ * official mcp-client bridge — the common text-result case (no image/attachment
+ * projection, no task execution). Model-facing names follow the stable
+ * `mcp__<serverName>__<rawName>` contract, normalized to the DeepSeek
+ * function-name constraints; the raw name is only ever sent on the wire.
+ *
+ * Registration must always invoke `ctx.tools.register(definition)` as a MEMBER
+ * call on the traceable service proxy (never extract `register` to a standalone
+ * variable) — the proxy resolves `this.ctx` (effect/scope ownership) from the
+ * calling context, which a bare function reference loses.
+ * @module @khorsheed/dsh-capability-catalog/mcpTools
+ */
+import { createHash } from 'node:crypto';
+/** DeepSeek function-name contract: at most 64 characters. */
+const MAX_PUBLIC_NAME_LENGTH = 64;
+/** DeepSeek function-name contract: only `[A-Za-z0-9_-]` is allowed. */
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
+/** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
+const HASH_LENGTH = 12;
+/** Deterministic model-facing name for `(serverName, rawName)`. */
+export function publicToolName(serverName, rawName) {
+    const joined = `mcp__${serverName}__${rawName}`;
+    const normalized = joined.replace(INVALID_NAME_CHARS, '_');
+    if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH)
+        return normalized;
+    const hash = createHash('sha256').update(joined).digest('hex').slice(0, HASH_LENGTH);
+    return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`;
+}
+/** Coerce a raw MCP inputSchema into a JSON Schema object the registry accepts. */
+function sanitizeParameters(parameters) {
+    if (parameters !== null && typeof parameters === 'object' && !Array.isArray(parameters)) {
+        return parameters;
+    }
+    return { type: 'object', properties: {} };
+}
+/** Map the SDK `callTool` result to the canonical `{ content, structuredContent }`. */
+function normalizeResult(result) {
+    const r = (result ?? {});
+    if (r.isError === true)
+        throw new Error(r.error ?? 'MCP tool reported an error');
+    return {
+        content: Array.isArray(r.content) ? r.content : [],
+        ...(r.structuredContent !== undefined ? { structuredContent: r.structuredContent } : {}),
+    };
+}
+/** Extract human-readable text from MCP content blocks (text blocks joined). */
+export function extractText(content) {
+    const blocks = Array.isArray(content) ? content : [];
+    const texts = blocks
+        .filter((b) => typeof b === 'object' && b !== null && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text);
+    return texts.length > 0 ? texts.join('\n') : JSON.stringify(blocks);
+}
+/** Build a harness `ToolDefinition` for one discovered MCP tool. */
+export function mcpToolDefinition(opts) {
+    const { publicName, rawName, serverName, description, parameters, callTool } = opts;
+    return {
+        name: publicName,
+        description,
+        parameters: sanitizeParameters(parameters),
+        output: {
+            schema: {
+                type: 'object',
+                properties: { content: { type: 'array', items: {} } },
+                required: ['content'],
+                additionalProperties: true,
+            },
+            render: (_args, value) => {
+                const result = value;
+                return [{ type: 'text', text: extractText(result.content) }];
+            },
+        },
+        execute: async (args) => {
+            const result = await callTool(serverName, rawName, (args ?? {}));
+            return normalizeResult(result);
+        },
+    };
+}
+/**
+ * Reconcile registered MCP tools: dispose every previously-registered tool, then
+ * register the desired set. Registration failures are contained per tool.
+ */
+export function reconcileRegisteredMcpTools(desired, registry, current, callTool) {
+    for (const dispose of [...current.values()])
+        dispose();
+    current.clear();
+    for (const d of desired) {
+        try {
+            const dispose = registry.register(mcpToolDefinition({
+                publicName: d.publicName,
+                serverName: d.serverName,
+                rawName: d.rawName,
+                description: d.description,
+                parameters: d.parameters,
+                callTool,
+            }));
+            current.set(d.publicName, dispose);
+        }
+        catch (error) {
+            registry.onRegisterError?.(error);
+        }
+    }
+}
+/** Compute the desired set from enabled servers + their enabled tools. */
+export function desiredMcpTools(servers, toolsByServer) {
+    const desired = [];
+    for (const server of servers) {
+        if (!server.enabled)
+            continue;
+        for (const tool of toolsByServer[server.serverName] ?? []) {
+            if (!tool.enabled)
+                continue;
+            desired.push({
+                publicName: publicToolName(server.serverName, tool.name),
+                serverName: server.serverName,
+                rawName: tool.name,
+                description: tool.description,
+                parameters: tool.parameters,
+            });
+        }
+    }
+    return desired;
+}