@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/mcp/subscriptions.js

@@ -0,0 +1,288 @@
+/**
+ * Catalog subscriptions (P26-09, P26-10).
+ *
+ * The rules that make this more than an event emitter, each of which a naive
+ * implementation gets wrong:
+ *
+ * - **Acknowledge first, and acknowledge only what is SUPPORTED.** The ack carries
+ *   the filter the server will actually honour, not the one the client asked for. A
+ *   client that requested four notification types and is sent back one is being told
+ *   the truth; echoing all four and then sending one is a silent lie the client
+ *   cannot detect until it waits forever.
+ * - **No event before the acknowledgement.** So the ack is emitted synchronously as
+ *   part of establishing the subscription, and the subscription only becomes
+ *   eligible for real events afterwards.
+ * - **Every event carries the subscription id** in the revision's notification
+ *   metadata, because a client with several subscriptions cannot otherwise tell
+ *   which one an event belongs to.
+ * - **Filter per caller.** Each subscription belongs to one client and sees only its
+ *   own catalog. One client's private package changes are never delivered to
+ *   another, which is the leakage the requirement names.
+ * - **Teardown is announced.** Revoking a grant sends `notifications/cancelled`
+ *   referencing the subscription request BEFORE the stream closes, so a client can
+ *   distinguish "your access ended" from "the connection dropped".
+ * - **Progress does not travel here** (P26-10). Progress belongs on the response
+ *   stream of the call that produced it; routing it onto the catalog stream would
+ *   deliver one call's progress to every subscriber.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/subscriptions
+ */
+import { ERROR_CODES, WireError } from "./protocol.js";
+/**
+ * The notification types this server actually emits.
+ *
+ * Only tool-catalog changes exist, because only tools are published. Declaring the
+ * others unsupported is what makes the acknowledgement honest.
+ */
+export const SUPPORTED_FILTERS = ['toolsListChanged'];
+/** The official metadata key carrying the subscription's request id. */
+export const SUBSCRIPTION_ID_KEY = 'io.modelcontextprotocol/subscriptionId';
+/**
+ * Narrow a requested filter to what this server supports.
+ *
+ * P26-09 says to acknowledge only supported requested filters. A requested type
+ * that is not supported is DROPPED rather than acknowledged-and-ignored: an
+ * acknowledged type that never fires is indistinguishable from a broken server.
+ * @param requested - the filter the client asked for.
+ * @returns the acknowledged filter.
+ */
+export function acknowledgeFilter(requested) {
+    const acknowledged = {};
+    for (const key of SUPPORTED_FILTERS) {
+        // Only a type the client actually REQUESTED can be acknowledged: granting a
+        // type nobody asked for would start sending an unrequested notification.
+        if (requested[key] === true)
+            acknowledged[key] = true;
+    }
+    return acknowledged;
+}
+/** Manages the active catalog subscriptions. */
+export class SubscriptionRegistry {
+    #subscriptions = new Map();
+    /** Counter for ids this server issues, so an id is never caller-chosen. */
+    /** Active subscriptions, for diagnostics. */
+    get active() {
+        return [...this.#subscriptions.values()];
+    }
+    /**
+     * Establish a subscription.
+     *
+     * The acknowledgement notification is returned as part of the result and is
+     * marked sent before anything can be published, so no event can precede it.
+     * @param request - the `subscriptions/listen` request.
+     * @param clientId - the authenticated client, which the subscription is bound to.
+     * @returns the result envelope, the acknowledgement, and the subscription id.
+     */
+    listen(request, clientId) {
+        /**
+         * `notifications` IS REQUIRED, and this used to default it.
+         *
+         * The pinned schema's `SubscriptionsListenRequestParams` declares
+         * `required: ["_meta","notifications"]`. Defaulting an absent filter to `{}` and
+         * returning SUCCESS contradicted that AND contradicted this module's own rule that a
+         * missing required field is `invalidParams` rather than a defaulted value — a client
+         * would receive an acknowledgement for a subscription it never described, and the
+         * filter it believed it had sent would be silently empty.
+         */
+        const requested = request.params?.notifications;
+        if (requested === undefined || requested === null || typeof requested !== 'object' || Array.isArray(requested)) {
+            throw new WireError(ERROR_CODES.invalidParams, 'subscriptions/listen requires params.notifications; a missing filter is invalid rather than defaulted');
+        }
+        const filter = requested;
+        const acknowledged = acknowledgeFilter(filter);
+        /**
+         * THE SUBSCRIPTION IS IDENTIFIED BY THE LISTEN REQUEST'S OWN ID.
+         *
+         * This used to invent `sub_<time>_<n>`, which was WRONG, and the pinned schema says so
+         * in as many words. `CancelledNotification` states that the server's stream-terminating
+         * cancellation "references the ID of the `subscriptions/listen` request that opened the
+         * stream", and `SubscriptionsListenResultMetaObject` types its required
+         * `io.modelcontextprotocol/subscriptionId` as a **`RequestId`** — the same type as a
+         * request id — "so the client can correlate it with the originating subscription".
+         *
+         * A server-invented id that the client never saw cannot be correlated with anything, so
+         * a client could neither match the acknowledgement to its request nor recognise the
+         * cancellation that ends the stream.
+         *
+         * The original comment claimed a caller-chosen id would let one client address
+         * another's subscription. That concern is real but it is NOT addressed by inventing an
+         * id: subscriptions are keyed by this id and BOUND to `clientId`, and the binding is
+         * what prevents cross-client addressing.
+         */
+        const subscriptionId = request.id;
+        if (typeof subscriptionId !== 'string' && typeof subscriptionId !== 'number') {
+            throw new WireError(ERROR_CODES.invalidParams, 'subscriptions/listen requires a string or integer request id, which IS the subscription id');
+        }
+        const subscription = { subscriptionId: String(subscriptionId), clientId, acknowledged, announced: true };
+        this.#subscriptions.set(String(subscriptionId), subscription);
+        return {
+            result: {
+                resultType: 'complete',
+                // The revision REQUIRES the subscription id in this result's metadata.
+                _meta: { [SUBSCRIPTION_ID_KEY]: subscriptionId },
+            },
+            acknowledgement: {
+                jsonrpc: '2.0',
+                method: 'notifications/subscriptions/acknowledged',
+                params: {
+                    // The filter the server will HONOUR, not the one requested.
+                    notifications: acknowledged,
+                    // The subscription id is what lets a client with several subscriptions
+                    // tell which one an event belongs to.
+                    _meta: { [SUBSCRIPTION_ID_KEY]: subscriptionId },
+                },
+            },
+            subscriptionId: String(subscriptionId),
+        };
+    }
+    /**
+     * Publish a tool-catalog change.
+     *
+     * @param generation - the catalog generation that changed, carried so a client
+     *   can tell a real change from a duplicate delivery.
+     * @returns one message per eligible subscriber, and nothing for anyone else.
+     */
+    publishToolListChanged(generation) {
+        const messages = [];
+        for (const subscription of this.#subscriptions.values()) {
+            // Two independent conditions: the client asked for this type, and it is
+            // still active. A revoked subscription is removed outright, so there is no
+            // window in which it receives one last event.
+            if (subscription.acknowledged.toolsListChanged !== true)
+                continue;
+            if (!subscription.announced)
+                continue;
+            messages.push({
+                clientId: subscription.clientId,
+                notification: {
+                    jsonrpc: '2.0',
+                    method: 'notifications/tools/list_changed',
+                    params: {
+                        _meta: { [SUBSCRIPTION_ID_KEY]: subscription.subscriptionId },
+                        generation,
+                    },
+                },
+            });
+        }
+        // Deliberately one message per subscriber rather than one broadcast: the
+        // transport must address each client, so a shared object would make cross-client
+        // leakage a matter of how the transport happened to iterate.
+        return messages;
+    }
+    /**
+     * Revoke every subscription belonging to a client, announcing each first.
+     *
+     * P26-09 requires the teardown notification BEFORE the stream closes, so the
+     * client learns its access ended rather than inferring it from a dropped socket.
+     * @param clientId - the client whose grant was revoked.
+     * @returns the teardown messages, already ordered cancellation-first.
+     */
+    revoke(clientId) {
+        const messages = [];
+        for (const [id, subscription] of [...this.#subscriptions]) {
+            if (subscription.clientId !== clientId)
+                continue;
+            messages.push({
+                clientId,
+                notification: {
+                    jsonrpc: '2.0',
+                    method: 'notifications/cancelled',
+                    params: {
+                        // References the SUBSCRIPTION request, so the client can match it to
+                        // the listen call it made.
+                        requestId: subscription.subscriptionId,
+                        reason: 'the grant for this subscription was revoked',
+                        _meta: { [SUBSCRIPTION_ID_KEY]: id },
+                    },
+                },
+            });
+            // Removed AFTER its teardown is queued, and before returning, so a publish
+            // racing this call cannot deliver one more event to a revoked client.
+            this.#subscriptions.delete(id);
+        }
+        return messages;
+    }
+    /**
+     * Close one subscription at the client's request.
+     * @param subscriptionId - the subscription to close.
+     * @param clientId - the caller, which must own it.
+     * @returns whether it was closed.
+     */
+    close(subscriptionId, clientId) {
+        const subscription = this.#subscriptions.get(subscriptionId);
+        // Ownership is checked, not assumed: without it one client could close
+        // another's subscription by guessing an id.
+        if (subscription === undefined || subscription.clientId !== clientId)
+            return false;
+        this.#subscriptions.delete(subscriptionId);
+        return true;
+    }
+    /** Every subscription belonging to one client. */
+    forClient(clientId) {
+        return [...this.#subscriptions.values()].filter(subscription => subscription.clientId === clientId);
+    }
+}
+/**
+ * Build the `notifications/cancelled` a client sends to stop a subscription.
+ *
+ * `CancelledNotificationParams` requires only `requestId`, so the notification
+ * carries exactly that: adding a `_meta` with an undefined version would put a
+ * meaningless member on the wire.
+ * @param subscriptionId - the subscription to cancel.
+ * @returns the notification.
+ */
+export function cancelSubscription(subscriptionId) {
+    return {
+        jsonrpc: '2.0',
+        method: 'notifications/cancelled',
+        params: { requestId: subscriptionId },
+    };
+}
+/**
+ * Run one catalog-change publication through the delivery consumer: the
+ * registry's per-caller filtering decides WHO gets the event, and the sink
+ * carries it to each client's stream. Acknowledgement ordering is the
+ * registry's own guarantee — an acknowledgement is marked sent before any
+ * publish can run, so no event can precede it.
+ * @param registry - the subscription state.
+ * @param generation - the catalog generation that changed.
+ * @param sink - the delivery transport.
+ * @returns how many subscribers received the change.
+ */
+export function deliverCatalogChange(registry, generation, sink) {
+    const messages = registry.publishToolListChanged(generation);
+    for (const message of messages)
+        sink.deliver(message);
+    return messages.length;
+}
+/**
+ * The memory sink: one per-client queue, used by the tests to exercise the
+ * consumer and by the host as the transport seam until a streaming endpoint
+ * injects its writer. It honours the same contract a real transport must:
+ * delivery only to the addressed client, and closeClient stops that client's
+ * queue entirely.
+ */
+export class MemoryDeliverySink {
+    #queues = new Map();
+    #closed = new Map();
+    /** The delivered messages for one client, in delivery order. */
+    forClient(clientId) {
+        return [...(this.#queues.get(clientId) ?? [])];
+    }
+    /** Whether the sink closed a client, and why. */
+    closeReason(clientId) {
+        return this.#closed.get(clientId);
+    }
+    deliver(message) {
+        if (this.#closed.has(message.clientId))
+            return;
+        const queue = this.#queues.get(message.clientId) ?? [];
+        queue.push(message);
+        this.#queues.set(message.clientId, queue);
+    }
+    closeClient(clientId, reason) {
+        this.#closed.set(clientId, reason);
+        this.#queues.delete(clientId);
+    }
+}
+//# sourceMappingURL=subscriptions.js.map

package/lib/mcp-status.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The MCP surface status (plan §3.4, MCP tab).
+ *
+ * Everything here is a fact the host already holds: the BOUND endpoint (or that none
+ * was bound), the configured `mcpV3` values, the credential store's client identities,
+ * the external ledger's observed clients and the export surface. The page must not
+ * invent a listening state, a port, or a client name — so this module has no defaults
+ * that guess: a missing endpoint is `null`, an unobserved client has zero calls, and
+ * the token VALUE has no field to travel in (only the file path).
+ *
+ * @module @try-works/dsh-tool-mode/mcp-status
+ */
+import type { McpUsageSummary } from './mcp-usage.ts';
+/** The supported authentication modes, named as the transport names them. */
+export type McpAuthMode = 'static-token' | 'oauth-resource-server' | 'none';
+/** A bound endpoint, as the transport reported it. */
+export interface McpBoundEndpoint {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+}
+/** The configured endpoint values (a config fact, not a listening claim). */
+export interface McpConfiguredEndpoint {
+    readonly host: string;
+    readonly port: number;
+    readonly path: string;
+}
+/** Everything the status view may read. */
+export interface McpStatusInput {
+    readonly enabled: boolean;
+    readonly configured: McpConfiguredEndpoint | null;
+    /** The BOUND endpoint, or null when nothing is listening. */
+    readonly endpoint: McpBoundEndpoint | null;
+    readonly authMode: McpAuthMode;
+    /** The operator token file path, never the token. */
+    readonly tokenFile: string | null;
+    /** Tool names the export surface actually publishes. */
+    readonly published: readonly string[];
+    /** Tool names withheld by the export policy, with reasons owned by the host. */
+    readonly withheld: readonly string[];
+    /** Client identities the credential store holds. */
+    readonly credentialClients: readonly string[];
+    /** The static-token client identity, present only when that mode is enabled. */
+    readonly staticClientId: string | null;
+    /** When the endpoint started listening, or null when it never bound. */
+    readonly startedAt: number | null;
+    /** The clock used for `uptimeMs` (injectable so a test is deterministic). */
+    readonly now?: number;
+    readonly ledger: McpUsageSummary;
+}
+/** One client identity on the MCP tab. */
+export interface McpStatusClient {
+    readonly clientId: string;
+    /** Alias of {@link McpStatusClient.clientId} for the client's flat contract. */
+    readonly id: string;
+    /** A display label; only the ledger/credential identity is known, so it equals the id. */
+    readonly label: string;
+    /** The client's own grant identity observed in the ledger, or null. */
+    readonly grantId: string | null;
+    readonly calls: number;
+    readonly errors: number;
+    readonly lastSeen: number | null;
+}
+/** The status view (flat client contract). */
+export interface McpStatusView {
+    readonly enabled: boolean;
+    readonly listening: boolean;
+    /** The bound endpoint, null whenever MCP is not serving. */
+    readonly endpoint: {
+        readonly host: string;
+        readonly port: number;
+        readonly path: string;
+        readonly url: string;
+    } | null;
+    readonly configured: McpConfiguredEndpoint | null;
+    readonly transport: 'http';
+    readonly auth: {
+        readonly scheme: McpAuthMode;
+        readonly mode: McpAuthMode;
+        readonly tokenFile: string | null;
+    };
+    /** Wall time since the endpoint bound; 0 while nothing is listening. */
+    readonly uptimeMs: number;
+    readonly clients: readonly McpStatusClient[];
+    readonly exposed: readonly string[];
+    readonly withheld: readonly string[];
+    readonly exposedCount: number;
+    readonly withheldCount: number;
+}
+/**
+ * Build the MCP status view.
+ * @param input - the bound/configured facts, identities, surface and ledger summary.
+ * @returns the status; every absent fact stays explicit.
+ */
+export declare function buildMcpStatus(input: McpStatusInput): McpStatusView;
+//# sourceMappingURL=mcp-status.d.ts.map

package/lib/mcp-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-status.d.ts","sourceRoot":"","sources":["../src/mcp-status.ts"],"names":[],"mappings":"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"}

package/lib/mcp-status.js

@@ -0,0 +1,70 @@
+/**
+ * The MCP surface status (plan §3.4, MCP tab).
+ *
+ * Everything here is a fact the host already holds: the BOUND endpoint (or that none
+ * was bound), the configured `mcpV3` values, the credential store's client identities,
+ * the external ledger's observed clients and the export surface. The page must not
+ * invent a listening state, a port, or a client name — so this module has no defaults
+ * that guess: a missing endpoint is `null`, an unobserved client has zero calls, and
+ * the token VALUE has no field to travel in (only the file path).
+ *
+ * @module @try-works/dsh-tool-mode/mcp-status
+ */
+/** `model_tools` is host-local and can never be exported over MCP. */
+const ALWAYS_WITHHELD = 'model_tools';
+/**
+ * Build the MCP status view.
+ * @param input - the bound/configured facts, identities, surface and ledger summary.
+ * @returns the status; every absent fact stays explicit.
+ */
+export function buildMcpStatus(input) {
+    const listening = input.enabled && input.endpoint !== null;
+    const withheldSet = new Set(input.withheld);
+    withheldSet.add(ALWAYS_WITHHELD);
+    const exposed = listening
+        ? input.published.filter(name => name !== ALWAYS_WITHHELD && !withheldSet.has(name)).sort((left, right) => left.localeCompare(right))
+        : [];
+    const withheld = listening
+        ? [...withheldSet].sort((left, right) => left.localeCompare(right))
+        // Nothing is served while disabled: every published tool is withheld, and the
+        // host-local tool stays withheld regardless.
+        : [...new Set([...input.published, ...input.withheld, ALWAYS_WITHHELD])].sort((left, right) => left.localeCompare(right));
+    const clients = new Map();
+    const ledgerClient = (clientId) => input.ledger.clients.find(client => client.clientId === clientId);
+    const identities = [input.authMode === 'static-token' ? input.staticClientId : null, ...input.credentialClients, ...input.ledger.clients.map(client => client.clientId)]
+        .filter((clientId) => clientId !== null && clientId.length > 0);
+    for (const clientId of identities) {
+        if (clients.has(clientId))
+            continue;
+        const observed = ledgerClient(clientId);
+        clients.set(clientId, {
+            clientId,
+            id: clientId,
+            // No name store exists: the authenticated identity IS the only truthful label.
+            label: clientId,
+            grantId: observed?.grantId ?? null,
+            calls: observed?.calls ?? 0,
+            errors: observed?.errors ?? 0,
+            lastSeen: observed === undefined ? null : observed.lastSeen,
+        });
+    }
+    const start = input.startedAt;
+    const now = input.now ?? Date.now();
+    return {
+        enabled: input.enabled,
+        listening,
+        endpoint: listening && input.endpoint !== null
+            ? { host: input.endpoint.host, port: input.endpoint.port, path: input.configured?.path ?? '/mcp', url: input.endpoint.url }
+            : null,
+        configured: input.configured,
+        transport: 'http',
+        auth: { scheme: input.authMode, mode: input.authMode, tokenFile: input.tokenFile },
+        uptimeMs: listening && start !== null ? Math.max(0, now - start) : 0,
+        clients: [...clients.values()].sort((left, right) => left.clientId.localeCompare(right.clientId)),
+        exposed,
+        withheld,
+        exposedCount: exposed.length,
+        withheldCount: withheld.length,
+    };
+}
+//# sourceMappingURL=mcp-status.js.map

package/lib/mcp-usage.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The bounded external-MCP call ledger (plan §3.4).
+ *
+ * External MCP `tools/call`s are not session events, so the only honest way to answer
+ * "MCP was used, by whom, how often" is to persist them. One JSONL row per call, trimmed
+ * at a bound, written beside the host state.
+ *
+ * The record TYPE is the privacy boundary: it has identity, timings, failure class,
+ * sizes and the receipt id, and deliberately nowhere to put arguments, results,
+ * credentials or the bearer token. A future change cannot start logging payloads by
+ * accident without changing this type.
+ *
+ * @module @try-works/dsh-tool-mode/mcp-usage
+ */
+import type { InvocationAccounting } from './invocation-accounting.ts';
+/** How many rows the ledger retains. */
+export declare const MCP_USAGE_MAX_ROWS = 5000;
+/** The default page size for a call-log request. */
+export declare const MCP_USAGE_DEFAULT_PAGE_SIZE = 50;
+/** One external call, as persisted. */
+export interface McpCallRecord {
+    /** Epoch milliseconds when the call settled. */
+    readonly time: number;
+    /** The tool that was invoked (the accounting hook now carries it). */
+    readonly tool: string;
+    /** The authenticated client identity. */
+    readonly clientId: string;
+    /** The client's own grant identity, when one was derived. */
+    readonly grantId: string | null;
+    readonly totalMs: number;
+    readonly queuedMs: number;
+    readonly loadMs: number;
+    readonly inferenceMs: number;
+    /** The closed failure-class vocabulary (`invocation-accounting.ts`). */
+    readonly failureClass: string;
+    /** A class-level reason; never a payload. */
+    readonly reason: string | null;
+    readonly inputBytes: number;
+    readonly outputBytes: number;
+    /** The native receipt id the call is correlatable by. */
+    readonly receiptId: string;
+}
+/** A page of the external call log, newest first. */
+export interface McpCallsPage {
+    readonly calls: readonly McpCallRecord[];
+    /** Matching rows before pagination. */
+    readonly total: number;
+    readonly page: number;
+    readonly pageSize: number;
+    /** Distinct client identities present in the ledger (all rows, not just the page). */
+    readonly clients: readonly string[];
+}
+/** One client's external activity. */
+export interface McpUsageClient {
+    readonly clientId: string;
+    /** The client's own grant identity, when a ledger row carried one. */
+    readonly grantId: string | null;
+    readonly calls: number;
+    readonly errors: number;
+    readonly lastSeen: number;
+}
+/** One tool's external activity. */
+export interface McpUsageTool {
+    readonly tool: string;
+    readonly calls: number;
+}
+/** The ledger's aggregate view. */
+export interface McpUsageSummary {
+    readonly total: number;
+    readonly clients: readonly McpUsageClient[];
+    readonly tools: readonly McpUsageTool[];
+}
+/** What the accounting hook supplies, plus the tool name it now carries. */
+export declare function recordFromAccounting(toolName: string, accounting: InvocationAccounting, time?: number): McpCallRecord;
+/**
+ * A bounded JSONL ledger over one file.
+ *
+ * Operations are synchronous and defensive: an unreadable or corrupt line contributes
+ * nothing, and a rotated file keeps the newest rows rather than failing the append.
+ */
+export declare class McpUsageLedger {
+    #private;
+    /**
+     * @param file - the JSONL path.
+     * @param options - `maxRows` defaults to {@link MCP_USAGE_MAX_ROWS}.
+     */
+    constructor(file: string, options?: {
+        readonly maxRows?: number;
+    });
+    /** The ledger path (the MCP status surface names it, never its contents). */
+    get file(): string;
+    /**
+     * Append one call, trimming at the bound.
+     * @param call - the record to persist.
+     */
+    record(call: McpCallRecord): void;
+    /**
+     * Read one page, newest first.
+     * @param query - optional client filter and 1-based page.
+     * @returns the page plus the matching total and the ledger's client identities.
+     */
+    read(query?: {
+        readonly clientId?: string;
+        readonly page?: number;
+        readonly pageSize?: number;
+    }): McpCallsPage;
+    /** Aggregate the ledger by client and tool. */
+    summarize(): McpUsageSummary;
+}
+//# sourceMappingURL=mcp-usage.d.ts.map

package/lib/mcp-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-usage.d.ts","sourceRoot":"","sources":["../src/mcp-usage.ts"],"names":[],"mappings":"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"}