@unbrained/pm-cli 2026.8.25 → 2026.8.26

package/dist/sdk/mcp/subscriptions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @module sdk/mcp/subscriptions
+ *
+ * Implements transport-neutral MCP 2026-07-28 subscription filtering,
+ * acknowledgment, notification correlation, and graceful closure.
+ */
+import { type PmMcpImplementation, type PmMcpServerCapabilities } from "./protocol.js";
+/** Notification/result metadata key that correlates a subscription stream. */
+export declare const PM_MCP_SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId";
+/** JSON-RPC identifiers permitted for long-lived subscription requests. */
+export type PmMcpSubscriptionId = string | number;
+/** Notification families a client may opt into on one listen stream. */
+export interface PmMcpSubscriptionFilter {
+    /** Receive notifications when the tool list changes. */
+    toolsListChanged?: boolean;
+    /** Receive notifications when the prompt list changes. */
+    promptsListChanged?: boolean;
+    /** Receive notifications when the resource list changes. */
+    resourcesListChanged?: boolean;
+    /** Receive updates for these exact resource URIs. */
+    resourceSubscriptions?: string[];
+}
+/** One JSON-RPC notification emitted by a subscription. */
+export interface PmMcpSubscriptionNotification {
+    /** JSON-RPC revision. */
+    jsonrpc: "2.0";
+    /** Notification method. */
+    method: string;
+    /** Correlated notification parameters. */
+    params: Record<string, unknown>;
+}
+/** Sink used by stdio and HTTP adapters to write subscription messages. */
+export type PmMcpSubscriptionSink = (notification: PmMcpSubscriptionNotification) => void | Promise<void>;
+/** Validate and clone one subscription notification filter. */
+export declare function parseMcpSubscriptionFilter(value: unknown): PmMcpSubscriptionFilter;
+/** Intersect a requested filter with notification capabilities the server advertises. */
+export declare function resolveMcpAcknowledgedSubscriptionFilter(requested: PmMcpSubscriptionFilter, capabilities: PmMcpServerCapabilities): PmMcpSubscriptionFilter;
+/** Manage concurrent stateless subscriptions without retaining client sessions. */
+export declare class PmMcpSubscriptionRegistry {
+    #private;
+    /** Create a registry shared by one concrete transport process. */
+    constructor(input: {
+        capabilities: PmMcpServerCapabilities;
+        serverInfo: PmMcpImplementation;
+    });
+    /** Number of currently open request-scoped subscription streams. */
+    get size(): number;
+    /** Open a subscription and emit its required first acknowledgment. */
+    open(input: {
+        id: PmMcpSubscriptionId;
+        notifications: unknown;
+        sink: PmMcpSubscriptionSink;
+    }): Promise<PmMcpSubscriptionFilter>;
+    /** Emit one list-change notification only to streams that opted into it. */
+    emitListChanged(family: "tools" | "prompts" | "resources"): Promise<number>;
+    /** Emit a resource update only to streams that opted into the exact URI. */
+    emitResourceUpdated(uri: string): Promise<number>;
+    /** Gracefully close one subscription and return its final modern result. */
+    close(id: PmMcpSubscriptionId): Record<string, unknown> | undefined;
+    /** Gracefully close every stream and preserve stable creation order. */
+    closeAll(): Array<{
+        id: PmMcpSubscriptionId;
+        result: Record<string, unknown>;
+    }>;
+}

package/dist/sdk/mcp/subscriptions.js

@@ -0,0 +1,212 @@
+/**
+ * @module sdk/mcp/subscriptions
+ *
+ * Implements transport-neutral MCP 2026-07-28 subscription filtering,
+ * acknowledgment, notification correlation, and graceful closure.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cb791784-bde2-5b1d-b5df-038282816043")}catch(e){}}();
+import { PM_MCP_ERROR_CODES, PmMcpProtocolError, attachMcpServerInfo, isMcpRecord, } from "./protocol.js";
+/** Notification/result metadata key that correlates a subscription stream. */
+export const PM_MCP_SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId";
+const MAX_RESOURCE_SUBSCRIPTIONS = 256;
+const MAX_RESOURCE_URI_BYTES = 2_048;
+const MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS = 5_000;
+function writeSubscriptionNotification(sink, notification) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("MCP subscription sink write timed out")), MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS);
+        timer.unref();
+        Promise.resolve()
+            .then(() => sink(notification))
+            .then(() => {
+            clearTimeout(timer);
+            resolve();
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function validateOptionalBoolean(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new PmMcpProtocolError("Invalid MCP subscription filter", PM_MCP_ERROR_CODES.invalidParams, { field: `notifications.${field}`, expected: "boolean" });
+    }
+    return value || undefined;
+}
+/** Validate and clone one subscription notification filter. */
+export function parseMcpSubscriptionFilter(value) {
+    if (!isMcpRecord(value)) {
+        throw new PmMcpProtocolError("Invalid MCP subscription filter", PM_MCP_ERROR_CODES.invalidParams, { field: "notifications", expected: "object" });
+    }
+    const toolsListChanged = validateOptionalBoolean(value.toolsListChanged, "toolsListChanged");
+    const promptsListChanged = validateOptionalBoolean(value.promptsListChanged, "promptsListChanged");
+    const resourcesListChanged = validateOptionalBoolean(value.resourcesListChanged, "resourcesListChanged");
+    let resourceSubscriptions;
+    if (value.resourceSubscriptions !== undefined) {
+        if (!Array.isArray(value.resourceSubscriptions) ||
+            value.resourceSubscriptions.length > MAX_RESOURCE_SUBSCRIPTIONS) {
+            throw new PmMcpProtocolError("Invalid MCP resource subscriptions", PM_MCP_ERROR_CODES.invalidParams, {
+                field: "notifications.resourceSubscriptions",
+                maximum: MAX_RESOURCE_SUBSCRIPTIONS,
+            });
+        }
+        const unique = new Set();
+        for (const entry of value.resourceSubscriptions) {
+            if (typeof entry !== "string" ||
+                entry.trim().length === 0 ||
+                Buffer.byteLength(entry, "utf8") > MAX_RESOURCE_URI_BYTES) {
+                throw new PmMcpProtocolError("Invalid MCP resource subscription URI", PM_MCP_ERROR_CODES.invalidParams, {
+                    field: "notifications.resourceSubscriptions",
+                    maximumBytes: MAX_RESOURCE_URI_BYTES,
+                });
+            }
+            unique.add(entry);
+        }
+        if (unique.size > 0)
+            resourceSubscriptions = [...unique].sort();
+    }
+    return {
+        ...(toolsListChanged ? { toolsListChanged } : {}),
+        ...(promptsListChanged ? { promptsListChanged } : {}),
+        ...(resourcesListChanged ? { resourcesListChanged } : {}),
+        ...(resourceSubscriptions ? { resourceSubscriptions } : {}),
+    };
+}
+/** Intersect a requested filter with notification capabilities the server advertises. */
+export function resolveMcpAcknowledgedSubscriptionFilter(requested, capabilities) {
+    return {
+        ...(requested.toolsListChanged && capabilities.tools?.listChanged
+            ? { toolsListChanged: true }
+            : {}),
+        ...(requested.promptsListChanged && capabilities.prompts?.listChanged
+            ? { promptsListChanged: true }
+            : {}),
+        ...(requested.resourcesListChanged && capabilities.resources?.listChanged
+            ? { resourcesListChanged: true }
+            : {}),
+        ...(requested.resourceSubscriptions && capabilities.resources?.subscribe
+            ? { resourceSubscriptions: [...requested.resourceSubscriptions] }
+            : {}),
+    };
+}
+/** Manage concurrent stateless subscriptions without retaining client sessions. */
+export class PmMcpSubscriptionRegistry {
+    #capabilities;
+    #records = new Map();
+    #serverInfo;
+    /** Create a registry shared by one concrete transport process. */
+    constructor(input) {
+        this.#capabilities = structuredClone(input.capabilities);
+        this.#serverInfo = { ...input.serverInfo };
+    }
+    /** Number of currently open request-scoped subscription streams. */
+    get size() {
+        return this.#records.size;
+    }
+    /** Open a subscription and emit its required first acknowledgment. */
+    async open(input) {
+        if (this.#records.has(input.id)) {
+            throw new PmMcpProtocolError("MCP subscription id is already active", PM_MCP_ERROR_CODES.invalidParams, { subscriptionId: input.id });
+        }
+        const filter = resolveMcpAcknowledgedSubscriptionFilter(parseMcpSubscriptionFilter(input.notifications), this.#capabilities);
+        const record = {
+            filter,
+            sink: input.sink,
+            writeQueue: Promise.resolve(),
+        };
+        this.#records.set(input.id, record);
+        try {
+            await this.#deliver(input.id, record, {
+                jsonrpc: "2.0",
+                method: "notifications/subscriptions/acknowledged",
+                params: {
+                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: input.id },
+                    notifications: structuredClone(filter),
+                },
+            }, true);
+        }
+        catch (error) {
+            this.#records.delete(input.id);
+            throw error;
+        }
+        return structuredClone(filter);
+    }
+    /** Emit one list-change notification only to streams that opted into it. */
+    async emitListChanged(family) {
+        const field = `${family}ListChanged`;
+        const method = `notifications/${family}/list_changed`;
+        const writes = [];
+        for (const [id, record] of this.#records) {
+            if (record.filter[field] !== true)
+                continue;
+            writes.push(this.#deliver(id, record, {
+                jsonrpc: "2.0",
+                method,
+                params: {
+                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
+                },
+            }));
+        }
+        return (await Promise.all(writes)).filter(Boolean).length;
+    }
+    /** Emit a resource update only to streams that opted into the exact URI. */
+    async emitResourceUpdated(uri) {
+        const writes = [];
+        for (const [id, record] of this.#records) {
+            if (!record.filter.resourceSubscriptions?.includes(uri))
+                continue;
+            writes.push(this.#deliver(id, record, {
+                jsonrpc: "2.0",
+                method: "notifications/resources/updated",
+                params: {
+                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
+                    uri,
+                },
+            }));
+        }
+        return (await Promise.all(writes)).filter(Boolean).length;
+    }
+    async #deliver(id, record, notification, propagateFailure = false) {
+        const pending = record.writeQueue.then(async () => {
+            if (this.#records.get(id) !== record)
+                return false;
+            try {
+                await writeSubscriptionNotification(record.sink, notification);
+                return true;
+            }
+            catch (error) {
+                if (this.#records.get(id) === record)
+                    this.#records.delete(id);
+                if (propagateFailure)
+                    throw error;
+                return false;
+            }
+        });
+        record.writeQueue = pending.then(() => undefined, () => undefined);
+        return pending;
+    }
+    /** Gracefully close one subscription and return its final modern result. */
+    close(id) {
+        if (!this.#records.delete(id))
+            return undefined;
+        return {
+            ...attachMcpServerInfo({
+                resultType: "complete",
+                _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
+            }, this.#serverInfo),
+        };
+    }
+    /** Gracefully close every stream and preserve stable creation order. */
+    closeAll() {
+        const closed = [];
+        for (const id of this.#records.keys()) {
+            const result = this.close(id);
+            closed.push({ id, result });
+        }
+        return closed;
+    }
+}
+//# sourceMappingURL=subscriptions.js.map
+//# debugId=cb791784-bde2-5b1d-b5df-038282816043

package/dist/sdk/mcp/tasks.d.ts

@@ -0,0 +1,107 @@
+import { type PmMcpRequestContext } from "./protocol.js";
+import { type PmMcpInputRequests, type PmMcpInputResponses } from "./interactions.js";
+/** Standard identifier used to negotiate the official MCP tasks extension. */
+export declare const PM_MCP_TASKS_EXTENSION: "io.modelcontextprotocol/tasks";
+/** Lifecycle states defined by the official MCP tasks extension. */
+export declare const PM_MCP_TASK_STATUSES: readonly ["working", "input_required", "completed", "failed", "cancelled"];
+/** Current state of a durable MCP task. */
+export type PmMcpTaskStatus = (typeof PM_MCP_TASK_STATUSES)[number];
+/** JSON-RPC error retained by a failed task. */
+export interface PmMcpTaskError {
+    /** JSON-RPC or MCP error code. */
+    code: number;
+    /** Bounded human-readable failure summary. */
+    message: string;
+    /** Optional structured diagnostics. */
+    data?: Record<string, unknown>;
+}
+/** Common public fields returned for every task state. */
+export interface PmMcpTask {
+    /** Stable server-minted task identifier. */
+    taskId: string;
+    /** Current extension lifecycle state. */
+    status: PmMcpTaskStatus;
+    /** Optional bounded human-readable state summary. */
+    statusMessage?: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last mutation timestamp. */
+    lastUpdatedAt: string;
+    /** Milliseconds from creation before server retention may end. */
+    ttlMs: number | null;
+    /** Suggested client polling interval. */
+    pollIntervalMs?: number;
+    /** Additional forward-compatible extension fields. */
+    [key: string]: unknown;
+}
+/** Detailed public task state returned by `tasks/get`. */
+export type PmMcpDetailedTask = (PmMcpTask & {
+    status: "working";
+}) | (PmMcpTask & {
+    status: "input_required";
+    inputRequests: PmMcpInputRequests;
+}) | (PmMcpTask & {
+    status: "completed";
+    result: Record<string, unknown>;
+}) | (PmMcpTask & {
+    status: "failed";
+    error: PmMcpTaskError;
+}) | (PmMcpTask & {
+    status: "cancelled";
+});
+/** Task handle returned instead of a synchronous tool result. */
+export type PmMcpCreateTaskResult = PmMcpTask & {
+    /** Official extension result discriminator. */
+    resultType: "task";
+};
+/** Construction options for one filesystem-backed task provider. */
+export interface PmMcpTaskStoreOptions {
+    /** Tracker root whose ignored runtime area owns task records. */
+    pmRoot: string;
+    /** Lock owner retained in diagnostics. */
+    owner?: string;
+    /** Deterministic clock seam used by conformance tests. */
+    now?: () => Date;
+    /** Deterministic task-id seam used by conformance tests. */
+    taskIdFactory?: () => string;
+    /** Process identifier used for restart recovery. */
+    workerPid?: number;
+}
+/** Filesystem-backed provider for official MCP task methods and state changes. */
+export declare class PmMcpTaskStore {
+    #private;
+    /** Create one task store scoped to a tracker runtime directory. */
+    constructor(options: PmMcpTaskStoreOptions);
+    /** Durably create a working task before returning its public handle. */
+    create(input: {
+        principal: string;
+        ttlMs?: number | null;
+        pollIntervalMs?: number;
+        statusMessage?: string;
+    }): Promise<PmMcpCreateTaskResult>;
+    /** Return authoritative task state, applying expiry and restart recovery. */
+    get(taskId: string, principal: string): Promise<PmMcpDetailedTask>;
+    /** Transition a nonterminal task to an MRTR input-required state. */
+    requireInput(input: {
+        taskId: string;
+        principal: string;
+        requestContext: PmMcpRequestContext;
+        inputRequests: unknown;
+        statusMessage?: string;
+    }): Promise<PmMcpDetailedTask>;
+    /** Accept outstanding task inputs, ignoring unknown and duplicate response keys. */
+    update(taskId: string, principal: string, inputResponses: unknown): Promise<{
+        acceptedKeys: string[];
+        remainingKeys: string[];
+    }>;
+    /** Retrieve and clear accepted task inputs for a resumed worker. */
+    takeInputResponses(taskId: string, principal: string): Promise<PmMcpInputResponses>;
+    /** Record one immutable successful terminal result. */
+    complete(taskId: string, principal: string, result: Record<string, unknown>): Promise<PmMcpDetailedTask>;
+    /** Record one immutable JSON-RPC terminal failure. */
+    fail(taskId: string, principal: string, error: PmMcpTaskError): Promise<PmMcpDetailedTask>;
+    /** Cooperatively cancel a nonterminal task and acknowledge terminal tasks idempotently. */
+    cancel(taskId: string, principal: string): Promise<PmMcpDetailedTask>;
+}
+/** Build a filesystem-backed task provider for a tracker runtime root. */
+export declare function createMcpTaskStore(options: PmMcpTaskStoreOptions): PmMcpTaskStore;