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

package/lib/mcp/subscriptions.js

@@ -0,0 +1,207 @@
+/**
+ * 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
+ */
+/**
+ * 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. */
+    #issued = 0;
+    /** 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) {
+        const requested = (request.params?.notifications ?? {});
+        const acknowledged = acknowledgeFilter(requested);
+        // Server-issued. A caller-chosen id would let one client address another
+        // client's subscription in a later cancellation.
+        const subscriptionId = `sub_${Date.now().toString(36)}_${(++this.#issued).toString(36)}`;
+        const subscription = { subscriptionId, clientId, acknowledged, announced: true };
+        this.#subscriptions.set(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,
+        };
+    }
+    /**
+     * 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 },
+    };
+}
+//# sourceMappingURL=subscriptions.js.map

package/lib/provider-bridge.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Extension provider bridge.
+ *
+ * This is the ONLY route from a catalog entry to model code (BASE-09). The host
+ * no longer imports an adapter for any model: it resolves the extension that
+ * DECLARES the model, loads that extension through its public `./tool-mode`
+ * entry, and asks it for a provider. A first-party package and a third-party
+ * package take the same path, so there is no private built-in adapter route that
+ * only first-party code can use — which is precisely what BASE-09 forbids.
+ *
+ * The binding from a catalog model to an extension is DATA, held in the model's
+ * own catalog entry, not a switch on the model name. Adding a vendor therefore
+ * means publishing a package and adding a catalog row, with no host change.
+ *
+ * @module @try-works/dsh-model-as-tool/provider-bridge
+ */
+import { type ToolGrant } from './authority.ts';
+import type { ModelCatalogEntry } from './types.ts';
+import type { ModelAdapter } from './adapters/types.ts';
+/** How a model's provider is obtained. */
+export interface ProviderBinding {
+    /**
+     * The extension package that implements the model, resolved like any other
+     * dependency. A relative path is admitted so a first-party package can be used
+     * from a checkout before it is published.
+     */
+    readonly extension: string;
+    /** The `modelId` the extension declares for this model. */
+    readonly modelId: string;
+}
+/** Raised when a model cannot be served through its declared extension. */
+export declare class ProviderBridgeError extends Error {
+    readonly name = "ProviderBridgeError";
+}
+/**
+ * Loads extensions and adapts their providers to the host's adapter interface.
+ *
+ * One bridge per plugin activation, so an extension is imported and activated
+ * once no matter how many tools it serves.
+ */
+export declare class ProviderBridge {
+    #private;
+    constructor(options: {
+        readonly grant: ToolGrant;
+        readonly activationGeneration: number;
+        readonly log?: (message: string, fields?: Record<string, unknown>) => void;
+    });
+    /** The extensions currently activated, for diagnostics. */
+    get activatedExtensions(): readonly string[];
+    /**
+     * Build an adapter for one catalog entry.
+     *
+     * Returns undefined when the entry declares no provider binding, which is the
+     * correct outcome for a model reached through a command transport instead.
+     *
+     * The adapter is LAZY: it does not import or activate the extension until the
+     * first invocation. Two reasons, and the second is the important one:
+     * registering a tool must not run somebody else's package code (EXT-19 requires
+     * import and `create()` to stay lightweight), and a package that fails to load
+     * must fail the CALL it was needed for rather than the registration of every
+     * other tool in the catalog.
+     * @param entry - the catalog entry.
+     * @returns the adapter, or undefined when no extension implements this model.
+     */
+    adapterFor(entry: ModelCatalogEntry): ModelAdapter | undefined;
+    /** Release every activated extension. */
+    dispose(reason?: 'deactivate' | 'upgrade' | 'uninstall' | 'shutdown' | 'fault'): Promise<void>;
+}
+//# sourceMappingURL=provider-bridge.d.ts.map

package/lib/provider-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-bridge.d.ts","sourceRoot":"","sources":["../src/provider-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AACnD,OAAO,KAAK,EAAgC,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAErF,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAeD,2EAA2E;AAC3E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;CAC/C;AAED;;;;;GAKG;AACH,qBAAa,cAAc;;gBAMb,OAAO,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;QACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;KAC3E;IAMD,2DAA2D;IAC3D,IAAI,mBAAmB,IAAI,SAAS,MAAM,EAAE,CAE3C;IAED;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS;IAyB9D,yCAAyC;IACnC,OAAO,CAAC,MAAM,GAAE,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,OAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAoHjH"}

package/lib/provider-bridge.js

@@ -0,0 +1,218 @@
+/**
+ * Extension provider bridge.
+ *
+ * This is the ONLY route from a catalog entry to model code (BASE-09). The host
+ * no longer imports an adapter for any model: it resolves the extension that
+ * DECLARES the model, loads that extension through its public `./tool-mode`
+ * entry, and asks it for a provider. A first-party package and a third-party
+ * package take the same path, so there is no private built-in adapter route that
+ * only first-party code can use — which is precisely what BASE-09 forbids.
+ *
+ * The binding from a catalog model to an extension is DATA, held in the model's
+ * own catalog entry, not a switch on the model name. Adding a vendor therefore
+ * means publishing a package and adding a catalog row, with no host change.
+ *
+ * @module @try-works/dsh-model-as-tool/provider-bridge
+ */
+import { activateExtension, assertNoReservedMeta, EXTENSION_ENTRY, loadExtensionModule, } from '@try-works/tool-mode-extension-sdk';
+import { createInvocationAuthority } from "./authority.js";
+/** Raised when a model cannot be served through its declared extension. */
+export class ProviderBridgeError extends Error {
+    name = 'ProviderBridgeError';
+}
+/**
+ * Loads extensions and adapts their providers to the host's adapter interface.
+ *
+ * One bridge per plugin activation, so an extension is imported and activated
+ * once no matter how many tools it serves.
+ */
+export class ProviderBridge {
+    #activated = new Map();
+    #grant;
+    #generation;
+    #log;
+    constructor(options) {
+        this.#grant = options.grant;
+        this.#generation = options.activationGeneration;
+        this.#log = options.log ?? (() => { });
+    }
+    /** The extensions currently activated, for diagnostics. */
+    get activatedExtensions() {
+        return [...this.#activated.keys()];
+    }
+    /**
+     * Build an adapter for one catalog entry.
+     *
+     * Returns undefined when the entry declares no provider binding, which is the
+     * correct outcome for a model reached through a command transport instead.
+     *
+     * The adapter is LAZY: it does not import or activate the extension until the
+     * first invocation. Two reasons, and the second is the important one:
+     * registering a tool must not run somebody else's package code (EXT-19 requires
+     * import and `create()` to stay lightweight), and a package that fails to load
+     * must fail the CALL it was needed for rather than the registration of every
+     * other tool in the catalog.
+     * @param entry - the catalog entry.
+     * @returns the adapter, or undefined when no extension implements this model.
+     */
+    adapterFor(entry) {
+        const binding = entry.provider;
+        if (binding === undefined)
+            return undefined;
+        return {
+            modelId: entry.id,
+            invoke: async (invocation) => {
+                const activated = await this.#activate(binding.extension, entry);
+                const provider = await this.#providerFor(activated, binding);
+                return this.#invoke(provider, binding, invocation);
+            },
+            // An arrow function, not a method: a method's `this` would be the adapter
+            // object literal rather than the bridge, so `#activated` would not resolve.
+            dispose: async () => {
+                // Provider-level disposal only when a provider was actually created:
+                // disposing a model that was never called must not activate its extension
+                // merely in order to shut it down.
+                const activated = this.#activated.get(binding.extension);
+                if (activated === undefined)
+                    return;
+                const provider = (await activated).providers.get(binding.modelId);
+                if (provider !== undefined)
+                    await (await provider).dispose();
+            },
+        };
+    }
+    /** Release every activated extension. */
+    async dispose(reason = 'shutdown') {
+        const extensions = [...this.#activated.values()];
+        this.#activated.clear();
+        for (const pending of extensions) {
+            try {
+                const activated = await pending;
+                for (const provider of activated.providers.values()) {
+                    await (await provider).dispose();
+                }
+                await activated.instance.dispose(reason);
+            }
+            catch (error) {
+                // One extension failing to stop must not prevent the others from being
+                // released, or a single bad package would leak every process it shares.
+                this.#log('extension disposal failed', { error: String(error) });
+            }
+        }
+    }
+    /** Activate an extension package once, and reuse it. */
+    async #activate(specifier, entry) {
+        const existing = this.#activated.get(specifier);
+        if (existing !== undefined)
+            return existing;
+        const pending = (async () => {
+            const loaded = await loadExtensionPackage(specifier, entry);
+            const instance = await activateExtension(loaded, this.#contextFor(specifier));
+            return { instance, providers: new Map() };
+        })();
+        this.#activated.set(specifier, pending);
+        return pending;
+    }
+    /** Create or reuse the provider for one model. */
+    async #providerFor(activated, binding) {
+        const existing = activated.providers.get(binding.modelId);
+        if (existing !== undefined)
+            return existing;
+        const pending = activated.instance.createProvider({
+            modelId: binding.modelId,
+            configuration: {},
+        });
+        activated.providers.set(binding.modelId, pending);
+        return pending;
+    }
+    /** Run one invocation through the provider. */
+    async #invoke(provider, binding, invocation) {
+        const authority = invocation.authority ?? createInvocationAuthority(this.#grant, 'interactive');
+        /**
+         * The load is deliberately NOT coordinated here.
+         *
+         * An earlier version routed `provider.load()` through the DeploymentCoordinator at
+         * this point, and the suite caught the consequence: loading then happened BEFORE
+         * the implementation authorized its inputs, so a call with a denied path loaded
+         * ~349 MB of weights before refusing. SEC-06 wants the denial first, and the
+         * extension performs path resolution inside `invoke`, so the coordinator cannot be
+         * placed here without inverting that.
+         *
+         * The coordinator is therefore a tested, standalone component (RES-02/03/05) whose
+         * place is INSIDE an implementation's own load path, where it can sit after the
+         * checks that must precede a load. Wiring it here would have traded a security
+         * property for a resource optimisation.
+         */
+        const input = {};
+        for (const [key, value] of Object.entries(invocation.args)) {
+            input[key] = value;
+        }
+        const payload = await provider.invoke({
+            implementationId: binding.modelId,
+            input,
+            context: {
+                invocationId: `inv_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`,
+                signal: invocation.signal,
+                limits: authority.limits,
+                resolvePath: candidate => authority.resolvePath(candidate),
+            },
+        });
+        // The host authors the reserved root `meta` (EXT-17). An extension supplying one
+        // is asserting its own provenance, which it does not get to do.
+        assertNoReservedMeta(payload, binding.modelId);
+        return payload;
+    }
+    /** Build the context an extension receives, which carries no host internals. */
+    #contextFor(extensionId) {
+        const controller = new AbortController();
+        return {
+            extensionId,
+            extensionVersion: '0.0.0',
+            activationGeneration: this.#generation,
+            storage: {
+                // The host grants a directory it owns; the extension never receives a
+                // path into the operator's own filesystem.
+                directory: '',
+                async read() { return undefined; },
+                async write() { },
+            },
+            logger: {
+                log: (level, message, fields) => {
+                    this.#log(`${level}: ${message}`, fields);
+                },
+            },
+            signal: controller.signal,
+            configuration: {},
+        };
+    }
+}
+/**
+ * Import an extension package's public entry.
+ *
+ * The specifier is resolved by Node like any other dependency, then the package's
+ * own discovery runs so the entry comes from its real `exports` map rather than
+ * from a host-side convention.
+ * @param specifier - the package name or path.
+ * @param entry - the catalog entry, for diagnostics.
+ * @returns the validated extension module.
+ * @throws ProviderBridgeError when the package cannot be resolved or has no entry.
+ */
+async function loadExtensionPackage(specifier, entry) {
+    let packageJsonPath;
+    try {
+        // `import.meta.resolve` is the resolver the runtime itself uses, so the
+        // extension is found exactly as Node would find it at call time.
+        packageJsonPath = import.meta.resolve(`${specifier}/package.json`);
+    }
+    catch (error) {
+        throw new ProviderBridgeError(`model "${entry.id}" declares the extension "${specifier}", which could not be resolved: `
+            + `${error instanceof Error ? error.message : String(error)}. Install it, or correct the catalog binding.`);
+    }
+    const { discoverExtension } = await import('@try-works/tool-mode-extension-sdk');
+    const discovery = discoverExtension(new URL('.', packageJsonPath).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
+    if (discovery.entryPath === undefined) {
+        throw new ProviderBridgeError(`extension "${specifier}" declares no ${EXTENSION_ENTRY} entry, so it cannot provide model "${entry.id}"`);
+    }
+    return loadExtensionModule(discovery.entryPath);
+}
+//# sourceMappingURL=provider-bridge.js.map

package/lib/publication.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Coherent publication from one versioned generation (EXT-24).
+ *
+ * EXT-24 forbids two observable states: an available tool WITHOUT its executable
+ * binding, and a new schema served by an old handler. The way to avoid both is to
+ * build the whole surface first, check it for internal consistency, and only then
+ * make it visible — staging plus a single switch, which is what the requirement
+ * asks for rather than an invented transactional registry API.
+ *
+ * The rules encoded here, each with a reason:
+ *
+ * - A tool is advertised only when a real implementation binding exists. A schema
+ *   alone is a promise nothing can keep, and EXT-24 states that no contract is
+ *   automatically callable merely because its schema is installed.
+ * - An ACTIVE package whose model is unprepared publishes readiness information and
+ *   a preparation skill, but NOT a working inference tool. Advertising a callable
+ *   tool that will fail on first use is worse than advertising nothing, because the
+ *   caller has no way to tell the difference until it fails.
+ * - A usage skill appears only when every tool it requires is visible. A skill that
+ *   instructs an agent to call a tool that is not there produces a confident
+ *   failure.
+ * - Every skill carries its owning extension, so it can be withdrawn with that
+ *   package rather than outliving it.
+ *
+ * @module @try-works/dsh-model-as-tool/publication
+ */
+/** Why a candidate contribution did not reach the published surface. */
+export interface WithheldContribution {
+    /** Stable reason code. */
+    readonly code: 'no-implementation' | 'needs-preparation' | 'unregistered-contribution' | 'model-failed';
+    /** Human-readable explanation. */
+    readonly message: string;
+    /** The tool or skill that was withheld. */
+    readonly subject: string;
+    /** The extension that owns it. */
+    readonly extensionId: string;
+}
+/** One implementation offered for a contract. */
+export interface ImplementationCandidate {
+    /** The extension providing it. */
+    readonly extensionId: string;
+    /** The catalog model backing it. */
+    readonly modelId: string;
+    /** Whether the model is prepared and callable right now. */
+    readonly readiness: 'unprepared' | 'preparing' | 'ready' | 'failed';
+    /** Whether the model can run on this host at all. */
+    readonly runnable: boolean;
+}
+/** One contract offered for publication. */
+export interface ToolCandidate {
+    /** The caller-facing tool name. */
+    readonly name: string;
+    /** The contract it implements. */
+    readonly contractId: string;
+    /** The model the operator selected to serve it. */
+    readonly selectedModelId: string;
+    /** Every implementation that could serve it. */
+    readonly implementations: readonly ImplementationCandidate[];
+}
+/** One skill offered for publication. */
+export interface SkillCandidate {
+    /** The skill name. */
+    readonly name: string;
+    /** The extension that owns it. */
+    readonly extensionId: string;
+    /** Tool NAMES the skill depends on. An absent list means it depends on nothing. */
+    readonly requiresTools?: readonly string[];
+    /**
+     * Whether this skill exists to explain preparation rather than usage.
+     *
+     * A preparation skill is published even when nothing is callable, because its
+     * whole purpose is to tell an operator what to do about that.
+     */
+    readonly purpose?: 'usage' | 'preparation';
+}
+/** A published tool, which by construction has an executable binding. */
+export interface PublishedTool {
+    readonly name: string;
+    readonly contractId: string;
+    readonly extensionId: string;
+    readonly modelId: string;
+    readonly readiness: ImplementationCandidate['readiness'];
+    /** The other implementations a caller could be switched to. */
+    readonly alternatives: readonly string[];
+}
+/** A published skill. */
+export interface PublishedSkill {
+    readonly name: string;
+    readonly extensionId: string;
+    readonly purpose: 'usage' | 'preparation';
+    readonly requiresTools: readonly string[];
+}
+/** One model deployment's readiness, published for operator visibility. */
+export interface ReadinessNotice {
+    readonly extensionId: string;
+    readonly modelId: string;
+    readonly readiness: ImplementationCandidate['readiness'];
+    readonly callable: boolean;
+    readonly reason: string;
+}
+/** A complete, internally consistent surface. */
+export interface CatalogGeneration {
+    /** The generation this surface belongs to. */
+    readonly generation: number;
+    readonly tools: readonly PublishedTool[];
+    readonly skills: readonly PublishedSkill[];
+    readonly readiness: readonly ReadinessNotice[];
+    /** Everything withheld, with the reason. Never silently dropped. */
+    readonly withheld: readonly WithheldContribution[];
+}
+/**
+ * Build a coherent surface from the candidates available now.
+ *
+ * Pure: it decides what MAY be published, and the caller makes the result visible.
+ * Keeping the decision separate from the switch is what allows a surface to be
+ * rejected before anything observes it.
+ * @param options - the candidates and the generation they belong to.
+ * @returns the complete surface, including what was withheld and why.
+ * @throws Error when the candidates are internally inconsistent in a way that
+ *   cannot be resolved by withholding, such as two tools sharing a name.
+ */
+export declare function buildSurface(options: {
+    readonly generation: number;
+    readonly tools: readonly ToolCandidate[];
+    readonly skills: readonly SkillCandidate[];
+}): CatalogGeneration;
+/**
+ * The published surface, swapped only as a whole (EXT-24).
+ *
+ * `publish` refuses a surface that would retire a tool without retiring the skill
+ * that teaches it, which is the "new schema with the old handler" failure seen from
+ * the other side.
+ */
+export declare class PublicationSurface {
+    #private;
+    constructor(options?: {
+        readonly generation?: number;
+        readonly onSwap?: (next: CatalogGeneration, previous: CatalogGeneration) => void;
+    });
+    /** The generation currently visible. */
+    get current(): CatalogGeneration;
+    /**
+     * Replace the visible surface.
+     *
+     * The callback receives the whole change at once, so a consumer can update its
+     * declarations without ever seeing an intermediate state.
+     * @param next - the surface to make visible.
+     */
+    publish(next: CatalogGeneration): void;
+    /**
+     * Skills that must be withdrawn because their owning extension is gone.
+     *
+     * EXT-24 requires the host to track skill provenance and remove a skill with the
+     * package or tool that owns it, rather than leaving orphaned guidance behind.
+     * @param liveExtensionIds - the extensions still installed and active.
+     * @returns the skills that should no longer be visible.
+     */
+    orphanedSkills(liveExtensionIds: readonly string[]): readonly PublishedSkill[];
+}
+//# sourceMappingURL=publication.d.ts.map

package/lib/publication.d.ts.map

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