@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/skills/skill-registry.d.ts

@@ -0,0 +1,85 @@
+/** Metadata for a skill discovered from an MCP server. */
+export interface McpSkillMetadata {
+    /** Skill name from SKILL.md frontmatter. */
+    name: string;
+    /** Short description from SKILL.md frontmatter. */
+    description: string;
+    /** The skill:// URI for the SKILL.md resource. */
+    uri: string;
+    /** Which MCP server this skill came from. */
+    serverName: string;
+    /** Tool names this skill gates via allowed-tools frontmatter. */
+    allowedTools: string[];
+    /**
+     * Which contract this skill was discovered over.
+     *
+     * `"sep2640"` skills were negotiated through the draft skills extension and
+     * carry verifiable digests; `"legacy"` skills came from plain `skill://`
+     * resource listing and have no integrity metadata at all. Loading code needs
+     * to tell them apart because only the former can be verified.
+     *
+     * Absent means legacy, so existing callers keep working unchanged.
+     */
+    origin?: "sep2640" | "legacy";
+    /**
+     * Digest of the skill's declared resource set, when known.
+     *
+     * SEP-2640 makes tool approval content-bound: if a later listing advertises a
+     * different resource set, prior approval is revoked. This value is what the
+     * policy hashes into the grant key to make that happen.
+     */
+    contentFingerprint?: string;
+}
+/**
+ * Registry for MCP-discovered skills.
+ *
+ * Holds skill metadata discovered from MCP servers. Skills are registered
+ * during MCP connection and looked up when the model invokes load_skill.
+ *
+ * Names live in a per-origin namespace. Re-registering the same skill (same
+ * server and URI) replaces it, but a *different* origin claiming an
+ * already-taken name never silently wins: the newcomer is kept under a
+ * server-qualified name so both stay reachable. SEP-2640 requires collisions to
+ * be disambiguated rather than dropped or preferred.
+ */
+export declare class SkillRegistry {
+    private skills;
+    private collisions;
+    /**
+     * Register a skill.
+     *
+     * Replaces an entry from the same origin. On a cross-origin name collision
+     * the incumbent keeps the bare name and this skill is stored under
+     * `<serverName>/<name>`; the collision is recorded for reporting.
+     */
+    register(skill: McpSkillMetadata): void;
+    /** Register multiple skills at once. */
+    registerAll(skills: McpSkillMetadata[]): void;
+    /** Get a skill by name. */
+    get(name: string): McpSkillMetadata | undefined;
+    /** Get all registered skills. */
+    getAll(): McpSkillMetadata[];
+    /** Name collisions resolved by qualification, oldest first. */
+    getCollisions(): SkillNameCollision[];
+    /** Remove a skill by name. */
+    unregister(name: string): boolean;
+    /** Remove all skills from a specific MCP server. */
+    unregisterByServer(serverName: string): void;
+    /** Remove all skills. */
+    clear(): void;
+    /** Number of registered skills. */
+    get size(): number;
+}
+/** A name claimed by two different origins, and how it was resolved. */
+export interface SkillNameCollision {
+    readonly name: string;
+    readonly incumbent: {
+        readonly serverName: string;
+        readonly uri: string;
+    };
+    readonly challenger: {
+        readonly serverName: string;
+        readonly uri: string;
+    };
+    readonly registeredAs: string;
+}

package/dist/skills/skill-registry.js

@@ -0,0 +1,85 @@
+/**
+ * Registry for MCP-discovered skills.
+ *
+ * Holds skill metadata discovered from MCP servers. Skills are registered
+ * during MCP connection and looked up when the model invokes load_skill.
+ *
+ * Names live in a per-origin namespace. Re-registering the same skill (same
+ * server and URI) replaces it, but a *different* origin claiming an
+ * already-taken name never silently wins: the newcomer is kept under a
+ * server-qualified name so both stay reachable. SEP-2640 requires collisions to
+ * be disambiguated rather than dropped or preferred.
+ */
+export class SkillRegistry {
+    skills = new Map();
+    collisions = [];
+    /**
+     * Register a skill.
+     *
+     * Replaces an entry from the same origin. On a cross-origin name collision
+     * the incumbent keeps the bare name and this skill is stored under
+     * `<serverName>/<name>`; the collision is recorded for reporting.
+     */
+    register(skill) {
+        const existing = this.skills.get(skill.name);
+        if (existing && !isSameOrigin(existing, skill)) {
+            const qualified = qualifiedName(skill);
+            this.collisions.push({
+                name: skill.name,
+                incumbent: { serverName: existing.serverName, uri: existing.uri },
+                challenger: { serverName: skill.serverName, uri: skill.uri },
+                registeredAs: qualified,
+            });
+            this.skills.set(qualified, { ...skill, name: qualified });
+            return;
+        }
+        this.skills.set(skill.name, skill);
+    }
+    /** Register multiple skills at once. */
+    registerAll(skills) {
+        for (const skill of skills) {
+            this.register(skill);
+        }
+    }
+    /** Get a skill by name. */
+    get(name) {
+        return this.skills.get(name);
+    }
+    /** Get all registered skills. */
+    getAll() {
+        return [...this.skills.values()].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    }
+    /** Name collisions resolved by qualification, oldest first. */
+    getCollisions() {
+        return [...this.collisions];
+    }
+    /** Remove a skill by name. */
+    unregister(name) {
+        return this.skills.delete(name);
+    }
+    /** Remove all skills from a specific MCP server. */
+    unregisterByServer(serverName) {
+        for (const [name, skill] of this.skills) {
+            if (skill.serverName === serverName) {
+                this.skills.delete(name);
+            }
+        }
+        this.collisions = this.collisions.filter((collision) => collision.incumbent.serverName !== serverName &&
+            collision.challenger.serverName !== serverName);
+    }
+    /** Remove all skills. */
+    clear() {
+        this.skills.clear();
+        this.collisions = [];
+    }
+    /** Number of registered skills. */
+    get size() {
+        return this.skills.size;
+    }
+}
+function isSameOrigin(left, right) {
+    return left.serverName === right.serverName && left.uri === right.uri;
+}
+function qualifiedName(skill) {
+    return `${skill.serverName}/${skill.name}`;
+}

package/dist/tool-cli/bridge.d.ts

@@ -0,0 +1,14 @@
+import { type BridgeInfo } from "@sammorrowdrums/tool-cli/client";
+export declare const TOOL_CLI_HOST_ENV_VAR = "TOOL_CLI_HOST";
+export declare const TOOL_CLI_LOCAL_HOST = "127.0.0.1";
+export interface ToolCliBridgeEndpoint {
+    port: number;
+    token: string;
+}
+/**
+ * Authenticate to the newly started bridge and verify the complete v1 surface
+ * before exposing its endpoint to agent-spawned shell commands.
+ */
+export declare function verifyToolCliBridge(endpoint: ToolCliBridgeEndpoint, timeoutMs?: number): Promise<BridgeInfo>;
+export declare function formatToolCliBridgeError(error: unknown): string;
+export declare function isToolCliCompatibilityError(error: unknown): boolean;

package/dist/tool-cli/bridge.js

@@ -0,0 +1,196 @@
+import { BRIDGE_PROTOCOL_MAJOR, BRIDGE_PROTOCOL_NAME, BRIDGE_RPC_OPERATIONS, BridgeCompatibilityError, PORT_ENV_VAR, RpcAbortError, RpcHttpError, RpcInvalidResponseError, RpcNonJsonResponseError, RpcProtocolError, RpcTimeoutError, RpcTransportError, TOKEN_ENV_VAR, getBridgeInfo, } from "@sammorrowdrums/tool-cli/client";
+const HANDSHAKE_TIMEOUT_MS = 5_000;
+export const TOOL_CLI_HOST_ENV_VAR = "TOOL_CLI_HOST";
+export const TOOL_CLI_LOCAL_HOST = "127.0.0.1";
+const REQUIRED_JSON_SCHEMA_DIALECTS = [
+    "https://json-schema.org/draft/2020-12/schema",
+    "https://json-schema.org/draft/2019-09/schema",
+    "http://json-schema.org/draft-07/schema#",
+];
+let handshakeEnvironmentTail = Promise.resolve();
+/**
+ * Authenticate to the newly started bridge and verify the complete v1 surface
+ * before exposing its endpoint to agent-spawned shell commands.
+ */
+export async function verifyToolCliBridge(endpoint, timeoutMs = HANDSHAKE_TIMEOUT_MS) {
+    return withExclusiveClientEnvironment(endpoint, async () => {
+        const info = await getBridgeInfo({ timeoutMs });
+        assertRequiredV1Surface(info);
+        return info;
+    });
+}
+async function withExclusiveClientEnvironment(endpoint, operation) {
+    const previous = handshakeEnvironmentTail;
+    let release;
+    handshakeEnvironmentTail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    let restore;
+    try {
+        restore = installTemporaryClientEnvironment(endpoint);
+        return await operation();
+    }
+    finally {
+        restore?.();
+        release();
+    }
+}
+export function formatToolCliBridgeError(error) {
+    if (error instanceof BridgeCompatibilityError) {
+        return `Tool-cli bridge compatibility error: ${error.message}. Install matching tool-cli and mcpi-ext major versions.`;
+    }
+    if (error instanceof RpcTimeoutError) {
+        return `Tool-cli bridge handshake timed out after ${error.timeoutMs}ms. Check bridge responsiveness and version compatibility.`;
+    }
+    if (error instanceof RpcHttpError) {
+        const auth = error.status === 401
+            ? " The bridge rejected the bearer token; restart the bridge to obtain fresh credentials."
+            : "";
+        return `Tool-cli bridge ${error.message}.${auth}`;
+    }
+    if (error instanceof RpcProtocolError) {
+        return `Tool-cli bridge RPC ${error.code}: ${error.message}${formatErrorData(error.data)}`;
+    }
+    if (error instanceof RpcNonJsonResponseError) {
+        return `Tool-cli bridge returned non-JSON HTTP ${error.status}: ${error.message}`;
+    }
+    if (error instanceof RpcInvalidResponseError) {
+        return `Tool-cli bridge returned an invalid JSON-RPC response: ${error.message}`;
+    }
+    if (error instanceof RpcAbortError) {
+        return `Tool-cli bridge handshake was cancelled${formatErrorData(error.reason)}`;
+    }
+    if (error instanceof RpcTransportError) {
+        return `Tool-cli bridge transport error: ${error.message}. Confirm the local bridge is listening and reachable.`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+export function isToolCliCompatibilityError(error) {
+    return error instanceof BridgeCompatibilityError;
+}
+function assertRequiredV1Surface(info) {
+    const value = info;
+    const root = requireRecord(value, "bridge metadata", value);
+    const protocol = requireRecord(root.bridgeProtocol, "bridgeProtocol metadata", value);
+    if (protocol.name !== BRIDGE_PROTOCOL_NAME ||
+        protocol.major !== BRIDGE_PROTOCOL_MAJOR ||
+        typeof protocol.version !== "string" ||
+        protocol.version.length === 0 ||
+        Number(protocol.version.split(".", 1)[0]) !== BRIDGE_PROTOCOL_MAJOR) {
+        throw new BridgeCompatibilityError(`tool-cli bridge did not report a valid ${BRIDGE_PROTOCOL_NAME} v${BRIDGE_PROTOCOL_MAJOR} protocol version`, value);
+    }
+    const implementation = requireRecord(root.serverImplementation, "serverImplementation metadata", value);
+    if (typeof implementation.name !== "string" ||
+        implementation.name.length === 0 ||
+        typeof implementation.version !== "string" ||
+        implementation.version.length === 0) {
+        throw new BridgeCompatibilityError("tool-cli bridge did not report a valid implementation name and version", value);
+    }
+    if (!isStringArray(root.operations) || new Set(root.operations).size !== root.operations.length) {
+        throw new BridgeCompatibilityError("tool-cli bridge did not report a valid deterministic operation list", value);
+    }
+    const operations = root.operations;
+    const missingOperations = BRIDGE_RPC_OPERATIONS.filter((operation) => !operations.includes(operation));
+    if (missingOperations.length > 0) {
+        throw new BridgeCompatibilityError(`tool-cli bridge v1 is missing required operation(s): ${missingOperations.join(", ")}`, value);
+    }
+    const operationOrder = BRIDGE_RPC_OPERATIONS.map((operation) => operations.indexOf(operation));
+    if (operationOrder.some((index, position) => position > 0 && index < operationOrder[position - 1])) {
+        throw new BridgeCompatibilityError("tool-cli bridge v1 reported required operations in a non-deterministic order", value);
+    }
+    const capabilities = requireRecord(root.capabilities, "capabilities metadata", value);
+    const authentication = requireRecord(capabilities.authentication, "authentication capabilities", value);
+    const tools = requireRecord(capabilities.tools, "tool capabilities", value);
+    const resources = requireRecord(capabilities.resources, "resource capabilities", value);
+    const cancellation = requireRecord(capabilities.cancellation, "cancellation capabilities", value);
+    const supportedDialects = tools.supportedJsonSchemaDialects;
+    const missingCapabilities = [
+        authentication.required !== true || authentication.scheme !== "bearer"
+            ? "bearer authentication"
+            : undefined,
+        tools.discovery !== true ? "tool discovery" : undefined,
+        tools.calls !== true ? "tool calls" : undefined,
+        tools.inputSchemaValidation !== true ? "input schema validation" : undefined,
+        tools.jsonSchemaDialect !== REQUIRED_JSON_SCHEMA_DIALECTS[0]
+            ? "JSON Schema 2020-12 default dialect"
+            : undefined,
+        !isStringArray(supportedDialects) ||
+            REQUIRED_JSON_SCHEMA_DIALECTS.some((dialect) => !supportedDialects.includes(dialect))
+            ? "supported JSON Schema dialects"
+            : undefined,
+        resources.list !== true ? "resource listing" : undefined,
+        resources.templates !== true ? "resource template listing" : undefined,
+        resources.read !== true ? "resource reads" : undefined,
+        cancellation.providerAbortSignal !== true ? "provider cancellation" : undefined,
+    ].filter((capability) => capability !== undefined);
+    if (missingCapabilities.length > 0) {
+        throw new BridgeCompatibilityError(`tool-cli bridge v1 is missing required capability(s): ${missingCapabilities.join(", ")}`, value);
+    }
+    if (!isRecord(root.upstreamMcp)) {
+        throw new BridgeCompatibilityError("tool-cli bridge did not report the required upstream MCP diagnostics summary", value);
+    }
+    const upstream = root.upstreamMcp;
+    if (!isNonNegativeInteger(upstream.serverCount) ||
+        !Array.isArray(upstream.servers) ||
+        upstream.servers.length !== upstream.serverCount) {
+        throw new BridgeCompatibilityError("tool-cli bridge reported an invalid upstream MCP server summary", value);
+    }
+    let previousServerName;
+    for (const server of upstream.servers) {
+        const entry = requireRecord(server, "upstream MCP server diagnostics", value);
+        if (typeof entry.name !== "string" ||
+            entry.name.length === 0 ||
+            !isNonNegativeInteger(entry.toolCount) ||
+            (previousServerName !== undefined && entry.name <= previousServerName)) {
+            throw new BridgeCompatibilityError("tool-cli bridge reported invalid or non-deterministic upstream MCP server diagnostics", value);
+        }
+        previousServerName = entry.name;
+    }
+}
+function requireRecord(value, description, bridgeInfo) {
+    if (!isRecord(value)) {
+        throw new BridgeCompatibilityError(`tool-cli bridge did not report valid ${description}`, bridgeInfo);
+    }
+    return value;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function installTemporaryClientEnvironment(endpoint) {
+    const previousPort = process.env[PORT_ENV_VAR];
+    const previousToken = process.env[TOKEN_ENV_VAR];
+    const previousHost = process.env[TOOL_CLI_HOST_ENV_VAR];
+    process.env[PORT_ENV_VAR] = String(endpoint.port);
+    process.env[TOKEN_ENV_VAR] = endpoint.token;
+    process.env[TOOL_CLI_HOST_ENV_VAR] = TOOL_CLI_LOCAL_HOST;
+    return () => {
+        restoreEnvironment(PORT_ENV_VAR, previousPort);
+        restoreEnvironment(TOKEN_ENV_VAR, previousToken);
+        restoreEnvironment(TOOL_CLI_HOST_ENV_VAR, previousHost);
+    };
+}
+function restoreEnvironment(name, previous) {
+    if (previous !== undefined) {
+        process.env[name] = previous;
+    }
+    else {
+        Reflect.deleteProperty(process.env, name);
+    }
+}
+function formatErrorData(data) {
+    if (data === undefined)
+        return "";
+    try {
+        return ` (${JSON.stringify(data)})`;
+    }
+    catch {
+        return ` (${String(data)})`;
+    }
+}

package/dist/tool-cli/format.d.ts

@@ -0,0 +1,20 @@
+import type { BashState, ToolCliState } from "../routing/facilities.js";
+/**
+ * Usage documentation for tool-cli.
+ *
+ * This is the "how", not the "when" — the `<execution_routing>` section decides
+ * which facility suits a task, and this section explains how to drive tool-cli
+ * once it has been chosen.
+ *
+ * Only emitted once the local RPC server has actually started. Advertising the
+ * commands before that would teach an agent an invocation it cannot perform.
+ * The routing section still reports tool-cli's availability either way, so
+ * nothing is silently omitted.
+ */
+export interface ToolCliPromptState {
+    /** Authenticated bridge state, including the verified v1 handshake metadata. */
+    toolCli: ToolCliState;
+    /** tool-cli is a shell program, so a registered bash tool is mandatory. */
+    bash: BashState;
+}
+export declare function formatToolCliForPrompt(state: ToolCliPromptState): string;

package/dist/tool-cli/format.js

@@ -0,0 +1,73 @@
+export function formatToolCliForPrompt(state) {
+    if (state.toolCli.kind !== "verified" || state.bash.kind !== "registered")
+        return "";
+    const { bridgeInfo } = state.toolCli;
+    const upstreamServerCount = readUpstreamServerCount(bridgeInfo.upstreamMcp);
+    return `
+
+<tool_cli_usage_docs>
+Use when you need to reach a specific MCP tool from the shell, or to discover which servers and
+tools exist before committing to an approach.
+
+\`tool-cli\` is a program, not a tool you can call. Invoke the bash tool with a command of the form
+\`tool-cli ...\`. Never emit \`<tool_cli...>\` markup, a pseudo-call, or any other text that imitates a
+tool invocation, and never write out what you expect a command would have printed — run it with the
+bash tool and use the real output.
+
+Discovery (progressive — only fetch what you need):
+  tool-cli --help                            # List MCP servers with tool counts
+  tool-cli <server>                          # List all tools on a server
+  tool-cli <server> <tool>                   # Show full schema for a tool
+
+Calling tools:
+  tool-cli <server> <tool> '{"key":"value"}' # Call a tool with JSON arguments
+  tool-cli <server> <tool> '{}' --out /tmp/result.json  # Save large output to file
+
+Resources:
+  tool-cli resource list --server <server>
+  tool-cli resource templates --server <server>
+  tool-cli resource read --server <server> <uri>
+  tool-cli resource read --server <server> <uri> --out /tmp/resource.bin
+
+tool-cli outputs plain text or JSON. When a tool provides structured output (typed JSON),
+tool-cli returns it directly as JSON — use \`jq\` to query fields.
+Chain calls, filter, and transform results using pipes and bash idioms:
+
+  # Search across tool results
+  tool-cli myserver search_docs '{"query":"auth"}' | grep -i "token"
+
+  # Query structured JSON output with jq
+  tool-cli myserver list_issues '{"repo":"owner/repo"}' | jq '.[].title'
+
+  # Chain tool calls — feed one result into another
+  tool-cli myserver list_items '{}' | jq -r '.[0].id' | xargs -I{} tool-cli myserver get_item '{"id":"{}"}'
+
+  # Process multiple items
+  for city in London Tokyo Paris; do
+    echo "=== $city ==="; tool-cli weather check_weather '{"city":"'$city'"}';
+  done
+
+  # Combine with standard tools
+  tool-cli myserver export_csv '{"table":"users"}' | sort -t, -k2 | head -20
+
+Because tool-cli runs inside a bash command, filtering, joining, or writing results to disk with
+ordinary programs is part of the same invocation — prefer one piped command over many separate
+calls when processing collections.
+Errors go to stderr with exit code 1 — use \`&&\` or \`set -e\` for safe chaining.
+Verified bridge: ${bridgeInfo.serverImplementation.name}@${bridgeInfo.serverImplementation.version};
+protocol ${bridgeInfo.bridgeProtocol.name} v${bridgeInfo.bridgeProtocol.version}; authenticated bearer RPC;
+operations ${bridgeInfo.operations.join(", ")}.
+Verified capabilities: tool discovery=${bridgeInfo.capabilities.tools.discovery}, calls=${bridgeInfo.capabilities.tools.calls},
+schema validation=${bridgeInfo.capabilities.tools.inputSchemaValidation}; resource list=${bridgeInfo.capabilities.resources.list},
+templates=${bridgeInfo.capabilities.resources.templates}, read=${bridgeInfo.capabilities.resources.read};
+provider cancellation=${bridgeInfo.capabilities.cancellation.providerAbortSignal}.
+Upstream MCP summary: ${upstreamServerCount} server(s) reported by the verified bridge handshake.
+</tool_cli_usage_docs>`;
+}
+function readUpstreamServerCount(upstream) {
+    if (upstream === null || typeof upstream !== "object" || Array.isArray(upstream)) {
+        return "unknown";
+    }
+    const count = Reflect.get(upstream, "serverCount");
+    return typeof count === "number" && Number.isInteger(count) && count >= 0 ? count : "unknown";
+}

package/dist/tool-cli/index.d.ts

@@ -0,0 +1,7 @@
+export { ToolCliServer } from "@sammorrowdrums/tool-cli/server";
+export type { BridgeInfo, ToolProvider } from "@sammorrowdrums/tool-cli/server";
+export { formatToolCliBridgeError, isToolCliCompatibilityError, verifyToolCliBridge, type ToolCliBridgeEndpoint, } from "./bridge.js";
+export { formatToolCliForPrompt } from "./format.js";
+export { buildUpstreamMcpSummary, createPolicyToolProvider, type PolicyToolProviderOptions, } from "./provider.js";
+export { startToolCliBridge, withholdToolCliCredentials } from "./startup.js";
+export type { StartToolCliBridgeOptions, ToolCliBridgeServer, ToolCliEnvironment, } from "./startup.js";

package/dist/tool-cli/index.js

@@ -0,0 +1,5 @@
+export { ToolCliServer } from "@sammorrowdrums/tool-cli/server";
+export { formatToolCliBridgeError, isToolCliCompatibilityError, verifyToolCliBridge, } from "./bridge.js";
+export { formatToolCliForPrompt } from "./format.js";
+export { buildUpstreamMcpSummary, createPolicyToolProvider, } from "./provider.js";
+export { startToolCliBridge, withholdToolCliCredentials } from "./startup.js";

package/dist/tool-cli/provider.d.ts

@@ -0,0 +1,21 @@
+import type { ToolProvider, UpstreamMcpSummary } from "@sammorrowdrums/tool-cli/server";
+import type { McpClientManager } from "../mcp/client-manager.js";
+import type { McpPolicy } from "../mcp/policy.js";
+export interface PolicyToolProviderOptions {
+    upstream?: Pick<McpClientManager, "getConnectedServers" | "getToolsForServer" | "getDiagnostics">;
+}
+/**
+ * Bridge the shared MCP policy boundary to tool-cli's `ToolProvider` interface.
+ *
+ * tool-cli's RPC server derives `listTools` and `describeTool` from
+ * `getTools`, so restricting discovery here restricts what the CLI can learn.
+ * More importantly, `callTool` does not check membership against the
+ * discovered set before forwarding, which means a caller can name a tool the
+ * CLI never advertised. Routing every call back through {@link McpPolicy}
+ * closes that gap: the same dispatcher that gates the proxy and Code Mode
+ * paths re-authorizes each RPC call, so naming a hidden tool is refused before
+ * the upstream server is contacted.
+ */
+export declare function createPolicyToolProvider(policy: McpPolicy, options?: PolicyToolProviderOptions): ToolProvider;
+/** Build a deterministic bridge summary from the manager's live per-server diagnostics. */
+export declare function buildUpstreamMcpSummary(upstream: NonNullable<PolicyToolProviderOptions["upstream"]>): UpstreamMcpSummary;

package/dist/tool-cli/provider.js

@@ -0,0 +1,114 @@
+import { toToolCliCallToolResult } from "../mcp/call-tool-result.js";
+import { MCP_CLIENT_IDENTITY } from "../mcp/client-factory.js";
+/**
+ * Bridge the shared MCP policy boundary to tool-cli's `ToolProvider` interface.
+ *
+ * tool-cli's RPC server derives `listTools` and `describeTool` from
+ * `getTools`, so restricting discovery here restricts what the CLI can learn.
+ * More importantly, `callTool` does not check membership against the
+ * discovered set before forwarding, which means a caller can name a tool the
+ * CLI never advertised. Routing every call back through {@link McpPolicy}
+ * closes that gap: the same dispatcher that gates the proxy and Code Mode
+ * paths re-authorizes each RPC call, so naming a hidden tool is refused before
+ * the upstream server is contacted.
+ */
+export function createPolicyToolProvider(policy, options = {}) {
+    const provider = {
+        getServerNames: () => policy.getVisibleServers(),
+        getTools: (server) => policy.getVisibleTools(server).map(toToolInfo),
+        async callTool(server, tool, args, context) {
+            const terminal = await policy.callTool({
+                source: "tool-cli",
+                serverName: server,
+                toolName: tool,
+                args,
+                ...(context?.signal !== undefined ? { signal: context.signal } : {}),
+            });
+            return toToolCliCallToolResult(terminal);
+        },
+        async listResources(server, context) {
+            const resources = await policy.listResources({
+                source: "tool-cli",
+                serverName: server,
+                ...(context?.signal !== undefined ? { signal: context.signal } : {}),
+            });
+            return resources.map((resource) => ({ ...resource }));
+        },
+        async listResourceTemplates(server, context) {
+            const templates = await policy.listResourceTemplates({
+                source: "tool-cli",
+                serverName: server,
+                ...(context?.signal !== undefined ? { signal: context.signal } : {}),
+            });
+            return templates.map((template) => ({ ...template }));
+        },
+        async readResource(server, uri, context) {
+            const result = await policy.readResource({
+                source: "tool-cli",
+                serverName: server,
+                uri,
+                ...(context?.signal !== undefined ? { signal: context.signal } : {}),
+            });
+            return {
+                ...result,
+                contents: result.contents.map((content) => ({ ...content })),
+            };
+        },
+    };
+    const upstream = options.upstream;
+    if (upstream !== undefined) {
+        provider.getUpstreamMcpSummary = () => buildUpstreamMcpSummary(upstream);
+    }
+    return provider;
+}
+/** Build a deterministic bridge summary from the manager's live per-server diagnostics. */
+export function buildUpstreamMcpSummary(upstream) {
+    const servers = upstream
+        .getConnectedServers()
+        .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+        .map((name) => {
+        const diagnostics = upstream.getDiagnostics(name);
+        return {
+            name,
+            toolCount: upstream.getToolsForServer(name).length,
+            ...(diagnostics?.protocolVersion !== undefined
+                ? { protocolVersion: diagnostics.protocolVersion }
+                : {}),
+            ...(diagnostics?.protocolEra !== undefined ? { protocolEra: diagnostics.protocolEra } : {}),
+            ...(diagnostics?.serverImplementation !== undefined
+                ? { implementation: diagnostics.serverImplementation }
+                : {}),
+            ...(diagnostics?.serverCapabilities !== undefined
+                ? { capabilities: diagnostics.serverCapabilities }
+                : {}),
+            ...(diagnostics?.discoverResult !== undefined
+                ? { discoverResult: diagnostics.discoverResult }
+                : {}),
+            ...(diagnostics !== undefined ? { skillsExtension: diagnostics.skillsExtension } : {}),
+        };
+    });
+    const protocolVersions = [
+        ...new Set(servers.flatMap((server) => server.protocolVersion !== undefined ? [server.protocolVersion] : [])),
+    ];
+    return {
+        ...(protocolVersions.length === 1 ? { protocolVersion: protocolVersions[0] } : {}),
+        implementation: { ...MCP_CLIENT_IDENTITY },
+        capabilities: {
+            multiplexedServers: true,
+            tools: {
+                serverCount: servers.filter((server) => server.toolCount > 0).length,
+            },
+            resources: {
+                serverCount: servers.filter((server) => server.capabilities?.resources !== undefined)
+                    .length,
+            },
+        },
+        serverCount: servers.length,
+        servers,
+    };
+}
+function toToolInfo(tool) {
+    const info = { ...tool };
+    Reflect.deleteProperty(info, "serverName");
+    return info;
+}

package/dist/tool-cli/startup.d.ts

@@ -0,0 +1,22 @@
+import type { BridgeInfo } from "@sammorrowdrums/tool-cli/client";
+import type { BashState, ToolCliState } from "../routing/facilities.js";
+import { type ToolCliBridgeEndpoint } from "./bridge.js";
+export interface ToolCliBridgeServer {
+    start(log?: (message: string) => void): Promise<ToolCliBridgeEndpoint>;
+    stop(): Promise<void>;
+}
+export interface ToolCliEnvironment {
+    setEnv(name: string, value: string): void;
+    unsetEnv(name: string): void;
+}
+export interface StartToolCliBridgeOptions {
+    bash: BashState;
+    server: ToolCliBridgeServer;
+    environment: ToolCliEnvironment;
+    log: (message: string) => void;
+    verify?: (endpoint: ToolCliBridgeEndpoint) => Promise<BridgeInfo>;
+}
+/** Mask inherited credentials until this session has verified its own bridge endpoint. */
+export declare function withholdToolCliCredentials(environment: ToolCliEnvironment): void;
+/** Start, authenticate, and expose tool-cli only when both bridge and bash are usable. */
+export declare function startToolCliBridge(options: StartToolCliBridgeOptions): Promise<ToolCliState>;