@try-works/dsh-model-as-tool 0.1.0 → 0.1.2

package/lib/mcp/server.js

@@ -0,0 +1,200 @@
+/**
+ * MCP method dispatch (MCP-05, MCP-06, MCP-08, MCP-09, MCP-13).
+ *
+ * The server is STATELESS by construction, which is what P26-01 requires: a
+ * `tools/list` or `tools/call` must be processable as the first application
+ * request. There is no session table here to require one, so the requirement is
+ * satisfied by the shape of the code rather than by remembering to skip a check.
+ *
+ * Dispatch resolves ONE authorized definition and calls it through the host's
+ * execution path (MCP-08), rather than reaching into a registry by name — the
+ * difference matters because the host's path applies the grant, the receipt and
+ * the result policy, while a direct lookup would bypass all three.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/server
+ */
+import { assertHeadersMatch, cacheableResultFields, implementedCapabilities, SUPPORTED_PROTOCOL_VERSIONS, ERROR_CODES, errorResponse, negotiateVersion, parseRequestMetadata, successResult, toolErrorResult, unsupportedRequiredCapabilities, WireError, } from "./protocol.js";
+/**
+ * Project a definition into the MCP tool shape.
+ *
+ * `outputSchema` is taken from the resolved definition rather than from DSH's
+ * model-facing `schemas()` projection, which intentionally omits `output`: a
+ * schema-only export built from that projection would be missing the very field
+ * MCP-09 requires.
+ * @param definition - the resolved definition.
+ * @returns the MCP tool descriptor.
+ */
+export function toMcpTool(definition) {
+    return {
+        name: definition.name,
+        ...definition.title === undefined ? {} : { title: definition.title },
+        description: definition.description,
+        inputSchema: definition.inputSchema,
+        outputSchema: definition.outputSchema,
+    };
+}
+/**
+ * Dispatch one request.
+ *
+ * Stateless: nothing is retained between calls, so a valid request works as the
+ * first one.
+ * @param request - the parsed request.
+ * @param host - the host surface.
+ * @param options - headers and the caller's abort signal.
+ * @returns the response and the HTTP status.
+ */
+export async function dispatch(request, host, options = {}) {
+    const id = request.id ?? null;
+    try {
+        if (options.checkHeaders === true && options.headers !== undefined) {
+            assertHeadersMatch(options.headers, request);
+        }
+        const metadata = parseRequestMetadata(request.params);
+        negotiateVersion(metadata);
+        // Capabilities the CLIENT requires. A requirement this server cannot meet is
+        // -32021 rather than a silent partial service.
+        const required = requiredCapabilities(metadata.clientCapabilities);
+        const unsupported = unsupportedRequiredCapabilities(required);
+        if (unsupported.length > 0) {
+            throw new WireError(ERROR_CODES.unsupportedClientCapability, `the client requires unsupported capability: ${unsupported.join(', ')}`, { unsupported });
+        }
+        switch (request.method) {
+            case 'server/discover':
+                return {
+                    response: { jsonrpc: '2.0', id, result: successResult(discoverResult(), host.serverInfo) },
+                    httpStatus: 200,
+                };
+            case 'tools/list':
+                return {
+                    response: {
+                        jsonrpc: '2.0',
+                        id,
+                        result: successResult({
+                            // Deterministic ordering (MCP-06): the caller sees a stable list, so
+                            // a client diffing two listings does not see spurious changes.
+                            tools: [...host.listTools()]
+                                .sort((left, right) => left.name.localeCompare(right.name))
+                                .map(toMcpTool),
+                            // Required by the schema's CacheableResult; omitting them makes the
+                            // result non-conformant even though the tool list is correct.
+                            ...cacheableResultFields(),
+                        }, host.serverInfo),
+                    },
+                    httpStatus: 200,
+                };
+            case 'subscriptions/listen': {
+                // P26-09. The acknowledgement is returned WITH the result rather than after
+                // it, so the client cannot observe an event before being told what the server
+                // agreed to send.
+                //
+                // A host with no registry reports the method as unsupported rather than
+                // accepting a subscription it cannot serve: an acknowledged subscription that
+                // never fires is indistinguishable from a broken server.
+                if (options.subscriptions === undefined) {
+                    throw new WireError(ERROR_CODES.methodNotFound, 'this server does not offer catalog subscriptions');
+                }
+                const subscription = options.subscriptions.listen(request, options.clientId ?? 'unknown');
+                return {
+                    response: { jsonrpc: '2.0', id, result: successResult(subscription.result, host.serverInfo) },
+                    httpStatus: 200,
+                    followUp: [subscription.acknowledgement],
+                };
+            }
+            case 'tools/call':
+                return await callTool(request, id, host, options.signal ?? new AbortController().signal);
+            default:
+                throw new WireError(ERROR_CODES.methodNotFound, `unknown method ${JSON.stringify(request.method)}`);
+        }
+    }
+    catch (error) {
+        const wire = error instanceof WireError
+            ? error
+            : new WireError(ERROR_CODES.internalError, error instanceof Error ? error.message : String(error));
+        // An infrastructure failure must never be turned into a successful domain
+        // payload (MCP-10), so it leaves as a JSON-RPC error.
+        return {
+            response: errorResponse(id, wire),
+            // Header problems are a transport-level rejection as well as a JSON-RPC error.
+            httpStatus: wire.code === ERROR_CODES.headerMismatch || wire.code === ERROR_CODES.invalidParams ? 400 : 200,
+        };
+    }
+}
+/** Handle `tools/call`. */
+async function callTool(request, id, host, signal) {
+    const name = request.params?.name;
+    if (typeof name !== 'string' || name.length === 0) {
+        throw new WireError(ERROR_CODES.invalidParams, 'tools/call requires params.name');
+    }
+    const args = request.params?.arguments;
+    if (args !== undefined && (typeof args !== 'object' || args === null || Array.isArray(args))) {
+        throw new WireError(ERROR_CODES.invalidParams, 'tools/call arguments must be an object');
+    }
+    const definition = host.listTools().find(tool => tool.name === name);
+    if (definition === undefined) {
+        // An unknown name is invalid params, not a tool error: nothing was invoked, so
+        // reporting a domain failure would be a fabrication.
+        throw new WireError(ERROR_CODES.invalidParams, `unknown tool ${JSON.stringify(name)}`);
+    }
+    // MCP-13: never re-export an imported MCP tool, or a server could delegate back
+    // into itself through a loop that no caller can see.
+    if (definition.importedFromMcp) {
+        throw new WireError(ERROR_CODES.invalidParams, `tool ${JSON.stringify(name)} was imported from MCP and is not re-exported`);
+    }
+    const outcome = await host.callTool(name, (args ?? {}), signal);
+    const result = outcome.isError === true
+        // An application failure is a tool-error RESULT (P26-04), so the protocol
+        // exchange still succeeded.
+        ? toolErrorResult(outcome.text)
+        : {
+            content: [{ type: 'text', text: outcome.text }],
+            // The finalized, post-policy canonical value (MCP-10).
+            structuredContent: outcome.structured,
+        };
+    return {
+        response: { jsonrpc: '2.0', id, result: successResult(result, host.serverInfo) },
+        httpStatus: 200,
+    };
+}
+/** The `server/discover` result, in the shape the pinned schema requires. */
+function discoverResult() {
+    return {
+        // `supportedVersions` is the field the schema defines; there is no
+        // `protocolVersion` on a DiscoverResult, which is the mistake pinning the schema
+        // caught. A client learns the versions the server speaks, not one it picked.
+        supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: serverCapabilities(),
+        ...cacheableResultFields(),
+    };
+}
+/**
+ * The capabilities this server advertises.
+ *
+ * Derived from the feature matrix rather than restated, so the matrix a client
+ * reads and the capabilities it is offered cannot disagree. P26-12: a feature is
+ * advertised only when it is genuinely implemented.
+ * @returns the `ServerCapabilities` object.
+ */
+function serverCapabilities() {
+    const implemented = new Set(implementedCapabilities());
+    return {
+        ...implemented.has('tools') ? { tools: {} } : {},
+        ...implemented.has('prompts') ? { prompts: {} } : {},
+        ...implemented.has('resources/subscribe') ? { resources: {} } : {},
+        ...implemented.has('logging') ? { logging: {} } : {},
+    };
+}
+/**
+ * Read the capabilities a client declared as REQUIRED.
+ *
+ * A client may declare capabilities it merely supports; only the required ones can
+ * make a request unserviceable.
+ * @param capabilities - the parsed capability object.
+ * @returns the required capability names.
+ */
+function requiredCapabilities(capabilities) {
+    const required = capabilities.required;
+    if (!Array.isArray(required))
+        return [];
+    return required.filter((name) => typeof name === 'string');
+}
+//# sourceMappingURL=server.js.map

package/lib/mcp/stdio.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The stdio bridge (MCP-03, P26-05, P26-06, P26-08).
+ *
+ * `P26-05` is explicit that the bridge IS AN HTTP CLIENT, not a second protocol
+ * implementation: it must generate the modern per-request headers correctly and
+ * talk to the same endpoint a network client uses. So there is no second
+ * interpretation of the protocol here to drift out of step with the first.
+ *
+ * What P26-08 requires, and how each is met:
+ *
+ * - **Stdout is exclusively protocol traffic; diagnostics go to stderr.** The two
+ *   sinks are separate parameters, so a diagnostic cannot reach stdout by being
+ *   written to "the output" — there is no single output to confuse.
+ * - **Request IDs and per-request metadata are preserved.** The body is forwarded
+ *   verbatim; the bridge regenerates only the HEADERS, which is the one thing the
+ *   transport requires it to derive.
+ * - **One stdio process is not one conversation.** Nothing is retained between
+ *   requests except in-flight cancellation state, which is keyed by request id and
+ *   removed when the request settles.
+ * - **EOF shuts down bridge-owned requests without killing the host.** Closing
+ *   aborts what this bridge has in flight; the host is a separate process.
+ * - **Cancellation is per request.** `notifications/cancelled` aborts exactly the
+ *   referenced request, so cancelling one call cannot cancel another sharing the
+ *   worker.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/stdio
+ */
+import { type WireRequest } from './protocol.ts';
+/** Where the bridge writes. Two sinks, deliberately not one. */
+export interface BridgeIo {
+    /** Protocol traffic. Newline-delimited JSON and nothing else. */
+    protocol(line: string): void;
+    /** Diagnostics. Never protocol traffic. */
+    diagnostic(line: string): void;
+}
+/** How the bridge reaches the endpoint. */
+export interface BridgeEndpoint {
+    /** The URL to POST to. */
+    readonly url: string;
+    /** The bearer token, from the operator's configuration and never from a client. */
+    readonly token: string;
+    /**
+     * The request function. Injected so a test can drive the bridge without a socket
+     * and without a real host.
+     */
+    readonly fetch: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+        signal: AbortSignal;
+    }) => Promise<{
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+}
+/** A running bridge. */
+export interface StdioBridge {
+    /**
+     * Handle one line of stdin.
+     * @param line - the raw line, with or without its newline.
+     * @returns the protocol line to emit, or undefined when none is due.
+     */
+    handleLine(line: string): Promise<string | undefined>;
+    /** Abort every request this bridge owns, as EOF does. */
+    close(): void;
+    /** How many requests this bridge currently owns in flight. */
+    readonly inFlight: number;
+}
+/** Build the headers for one request (P26-05). */
+export declare function headersFor(request: WireRequest, token: string): Record<string, string>;
+/**
+ * Create a bridge to a running MCP endpoint.
+ *
+ * @param endpoint - the endpoint and its injected request function.
+ * @param io - the protocol and diagnostic sinks.
+ * @returns the bridge.
+ */
+export declare function createStdioBridge(endpoint: BridgeEndpoint, io: BridgeIo): StdioBridge;
+//# sourceMappingURL=stdio.d.ts.map

package/lib/mcp/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/mcp/stdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAA;AAElE,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,2CAA2C;IAC3C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,2CAA2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,CACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KACzF,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAChF;AAED,wBAAwB;AACxB,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IACrD,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAAA;IACb,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBtF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,GAAG,WAAW,CAyGrF"}

package/lib/mcp/stdio.js

@@ -0,0 +1,176 @@
+/**
+ * The stdio bridge (MCP-03, P26-05, P26-06, P26-08).
+ *
+ * `P26-05` is explicit that the bridge IS AN HTTP CLIENT, not a second protocol
+ * implementation: it must generate the modern per-request headers correctly and
+ * talk to the same endpoint a network client uses. So there is no second
+ * interpretation of the protocol here to drift out of step with the first.
+ *
+ * What P26-08 requires, and how each is met:
+ *
+ * - **Stdout is exclusively protocol traffic; diagnostics go to stderr.** The two
+ *   sinks are separate parameters, so a diagnostic cannot reach stdout by being
+ *   written to "the output" — there is no single output to confuse.
+ * - **Request IDs and per-request metadata are preserved.** The body is forwarded
+ *   verbatim; the bridge regenerates only the HEADERS, which is the one thing the
+ *   transport requires it to derive.
+ * - **One stdio process is not one conversation.** Nothing is retained between
+ *   requests except in-flight cancellation state, which is keyed by request id and
+ *   removed when the request settles.
+ * - **EOF shuts down bridge-owned requests without killing the host.** Closing
+ *   aborts what this bridge has in flight; the host is a separate process.
+ * - **Cancellation is per request.** `notifications/cancelled` aborts exactly the
+ *   referenced request, so cancelling one call cannot cancel another sharing the
+ *   worker.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/stdio
+ */
+import { PROTOCOL_VERSION } from "./protocol.js";
+/** Build the headers for one request (P26-05). */
+export function headersFor(request, token) {
+    // The version comes from the BODY, not from a constant, so a request declaring an
+    // unsupported version is refused by the endpoint's header check rather than being
+    // silently relabelled by the bridge.
+    const bodyVersion = request.params?._meta?.['io.modelcontextprotocol/protocolVersion'];
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        authorization: `Bearer ${token}`,
+        'mcp-protocol-version': typeof bodyVersion === 'string' ? bodyVersion : PROTOCOL_VERSION,
+        'mcp-method': request.method,
+    };
+    // `Mcp-Name` is required for a named call and must match the body, so it is
+    // derived from the body rather than guessed.
+    if (request.method === 'tools/call' && typeof request.params?.name === 'string') {
+        headers['mcp-name'] = request.params.name;
+    }
+    return headers;
+}
+/**
+ * Create a bridge to a running MCP endpoint.
+ *
+ * @param endpoint - the endpoint and its injected request function.
+ * @param io - the protocol and diagnostic sinks.
+ * @returns the bridge.
+ */
+export function createStdioBridge(endpoint, io) {
+    /** In-flight requests, keyed by request id, so cancellation is per request. */
+    const inFlight = new Map();
+    return {
+        get inFlight() {
+            return inFlight.size;
+        },
+        async handleLine(line) {
+            const trimmed = line.trim();
+            // A blank line is a keep-alive, not a malformed frame: skipping it is correct
+            // and reporting it would spam a diagnostic channel for no reason.
+            if (trimmed.length === 0)
+                return undefined;
+            let request;
+            try {
+                request = JSON.parse(trimmed);
+            }
+            catch {
+                // A malformed frame is answered on the PROTOCOL channel, because the client
+                // is waiting for a response and a diagnostic would not reach it.
+                return frame({
+                    jsonrpc: '2.0',
+                    id: null,
+                    error: { code: -32700, message: 'the frame is not valid JSON' },
+                });
+            }
+            // P26-06: a cancellation names the request it cancels and nothing else.
+            if (request.method === 'notifications/cancelled') {
+                const target = request.params?.requestId;
+                const key = target === undefined ? undefined : String(target);
+                if (key !== undefined) {
+                    const controller = inFlight.get(key);
+                    if (controller === undefined) {
+                        // Reported, not ignored: a cancellation for an unknown request usually
+                        // means the client and bridge disagree about what is in flight.
+                        io.diagnostic(`cancellation for unknown request ${key}`);
+                    }
+                    else {
+                        controller.abort(new Error('cancelled by the client'));
+                        inFlight.delete(key);
+                        io.diagnostic(`cancelled request ${key}`);
+                    }
+                }
+                // A notification is acknowledged with nothing at all.
+                return undefined;
+            }
+            const controller = new AbortController();
+            const key = request.id === undefined || request.id === null ? undefined : String(request.id);
+            if (key !== undefined)
+                inFlight.set(key, controller);
+            try {
+                const response = await endpoint.fetch(endpoint.url, {
+                    method: 'POST',
+                    headers: headersFor(request, endpoint.token),
+                    // The body is forwarded VERBATIM: ids and per-request metadata survive
+                    // exactly, because the bridge regenerates only the headers.
+                    body: trimmed,
+                    signal: controller.signal,
+                });
+                if (response.status === 202 || response.body.length === 0) {
+                    // A notification has no response to forward.
+                    return undefined;
+                }
+                if (response.status >= 400 && !looksLikeJsonRpc(response.body)) {
+                    // A transport-level failure has no JSON-RPC body to forward, so it is
+                    // reported as a diagnostic AND as a protocol error: a client waiting for a
+                    // response must not be left waiting because the failure was transport.
+                    io.diagnostic(`the endpoint returned HTTP ${response.status}`);
+                    return frame({
+                        jsonrpc: '2.0',
+                        id: request.id ?? null,
+                        error: { code: -32603, message: `the endpoint returned HTTP ${response.status}` },
+                    });
+                }
+                return frame(JSON.parse(response.body));
+            }
+            catch (error) {
+                if (controller.signal.aborted) {
+                    // Cancellation is not a failure to report: the client asked for it.
+                    io.diagnostic(`request ${key ?? '(unknown)'} ended by cancellation`);
+                    return undefined;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                io.diagnostic(`the request to the endpoint failed: ${message}`);
+                return frame({
+                    jsonrpc: '2.0',
+                    id: request.id ?? null,
+                    error: { code: -32603, message: `the bridge could not reach the endpoint: ${message}` },
+                });
+            }
+            finally {
+                if (key !== undefined)
+                    inFlight.delete(key);
+            }
+        },
+        close() {
+            // P26-08: EOF shuts down BRIDGE-OWNED requests. The host is a separate
+            // process and is not touched here.
+            for (const [key, controller] of inFlight) {
+                controller.abort(new Error('the bridge is closing'));
+                io.diagnostic(`aborted in-flight request ${key} on close`);
+            }
+            inFlight.clear();
+        },
+    };
+}
+/** Serialize one protocol frame. */
+function frame(message) {
+    return JSON.stringify(message);
+}
+/** Whether a body is a JSON-RPC message rather than a transport error page. */
+function looksLikeJsonRpc(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.jsonrpc === '2.0';
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=stdio.js.map

package/lib/mcp/subscriptions.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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-model-as-tool/mcp/subscriptions
+ */
+import type { WireRequest } from './protocol.ts';
+/** The notification types the revision defines for catalog changes. */
+export type SubscriptionFilterKey = 'toolsListChanged' | 'promptsListChanged' | 'resourcesListChanged' | 'resourceSubscriptions';
+/** The filter a client requested, or the subset the server acknowledged. */
+export type SubscriptionFilter = Partial<Record<SubscriptionFilterKey, boolean>> & {
+    readonly resourceSubscriptions?: readonly string[];
+};
+/**
+ * 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 declare const SUPPORTED_FILTERS: readonly SubscriptionFilterKey[];
+/** The official metadata key carrying the subscription's request id. */
+export declare const SUBSCRIPTION_ID_KEY = "io.modelcontextprotocol/subscriptionId";
+/** One active subscription. */
+export interface Subscription {
+    /** The id of the `subscriptions/listen` request that established it. */
+    readonly subscriptionId: string;
+    /** The client it belongs to. Every event is filtered through this. */
+    readonly clientId: string;
+    /** The filter the server ACKNOWLEDGED, which is the supported subset. */
+    readonly acknowledged: SubscriptionFilter;
+    /**
+     * Whether the acknowledgement has been emitted.
+     *
+     * Nothing is published before it is true, which is how P26-09 requirement that no
+     * event precede the acknowledgement is enforced rather than remembered.
+     */
+    announced: boolean;
+}
+/** A message the transport should deliver to one client. */
+export interface SubscriptionMessage {
+    /** The client it is for. */
+    readonly clientId: string;
+    /** The notification to send. */
+    readonly notification: Record<string, unknown>;
+}
+/**
+ * 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 declare function acknowledgeFilter(requested: SubscriptionFilter): SubscriptionFilter;
+/** Manages the active catalog subscriptions. */
+export declare class SubscriptionRegistry {
+    #private;
+    /** Active subscriptions, for diagnostics. */
+    get active(): readonly Subscription[];
+    /**
+     * 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: WireRequest, clientId: string): {
+        readonly result: Record<string, unknown>;
+        readonly acknowledgement: Record<string, unknown>;
+        readonly subscriptionId: string;
+    };
+    /**
+     * 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: number): readonly SubscriptionMessage[];
+    /**
+     * 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: string): readonly SubscriptionMessage[];
+    /**
+     * 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: string, clientId: string): boolean;
+    /** Every subscription belonging to one client. */
+    forClient(clientId: string): readonly Subscription[];
+}
+/**
+ * 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 declare function cancelSubscription(subscriptionId: string): Record<string, unknown>;
+//# sourceMappingURL=subscriptions.d.ts.map

package/lib/mcp/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../src/mcp/subscriptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,CAAA;AAE3B,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC,GAAG;IACjF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,qBAAqB,EAAyB,CAAA;AAEvF,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,2CAA2C,CAAA;AAE3E,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAA;IACzC;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,gCAAgC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,GAAG,kBAAkB,CAQnF;AAED,gDAAgD;AAChD,qBAAa,oBAAoB;;IAK/B,6CAA6C;IAC7C,IAAI,MAAM,IAAI,SAAS,YAAY,EAAE,CAEpC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG;QAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACxC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAChC;IA+BD;;;;;;OAMG;IACH,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IA0B1E;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,mBAAmB,EAAE;IAyBxD;;;;;OAKG;IACH,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IASxD,kDAAkD;IAClD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,YAAY,EAAE;CAGrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlF"}