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

package/lib/ptc-runtime.d.ts

@@ -0,0 +1,166 @@
+/**
+ * PTC runtime integration: a guarded mount and the ONE authorized tool pipeline.
+ *
+ * The directive is explicit that this is repository work, not a missing upstream product:
+ *
+ *   "Use the existing `@deepseek-ai/dsh-ptc-runtime` interface and a compatible
+ *    `@deepseek-ai/dsh-ptc-runtime-node` backend. Compose its filesystem, subprocess,
+ *    sandbox, and policy dependencies. **Do not call `ctx.ptcRuntime` without mounting a
+ *    provider and then report the missing service as an unavailable upstream product.**"
+ *
+ *   "Native DSH PTC and external `tool_mode_run` must use the SAME authorized tool
+ *    pipeline."
+ *
+ * Two facts shape the mount, both discovered by reading the DSH source rather than guessed:
+ *
+ * 1. **The base bundle already mounts a provider.** `packages/bundle/base/cordis.patch.yml`
+ *    registers `@deepseek-ai/dsh-ptc-runtime-node`, so an UNGUARDED `ctx.plugin(...)`
+ *    throws `service "ptcRuntime" has been registered at <...>`. The guard is mandatory in
+ *    both outcomes, so it is not conditional on which host this finds.
+ * 2. **The composed services are the inject list**, not something the plugin supplies:
+ *    `static inject = ['fs','subprocess','sandbox','sandboxPolicy']`. Mounting them here
+ *    would hit the same duplicate-service throw.
+ *
+ * Everything that touches Cordis or DSH is INJECTED, so the guard logic and the authorized
+ * pipeline are testable without a live runtime.
+ *
+ * @module @try-works/dsh-tool-mode/ptc-runtime
+ */
+import { type ProgramAuthority, type ToolBinding } from './ptc-authority.ts';
+/** The service key the abstract runtime registers itself under. */
+export declare const PTC_SERVICE = "ptcRuntime";
+/** A Cordis-like context, narrowed to what this module needs. */
+export interface PtcHostContext {
+    /** Resolve a service, or `undefined` when nothing provides it. */
+    get(service: string): unknown;
+    /** Mount a plugin. */
+    plugin(plugin: unknown, config?: Record<string, unknown>): Promise<unknown> | unknown;
+}
+/** What a mount attempt did. */
+export interface MountOutcome {
+    /**
+     * Whether this call performed the mount.
+     *
+     * `false` means the host ALREADY had a provider, which is the expected case inside a
+     * full DSH deployment and is a SUCCESS rather than a skip — the distinction is what
+     * stops "already present" being reported as "unavailable".
+     */
+    readonly mounted: boolean;
+    /** Why it did not mount, when it did not. */
+    readonly reason?: 'already-provided' | 'backend-unavailable';
+    /** The service that is now usable, whichever path produced it. */
+    readonly service: string;
+}
+/**
+ * Mount the Node PTC backend, but only when nothing already provides the service.
+ *
+ * @param ctx - the host context.
+ * @param backend - the backend plugin, or `undefined` when it could not be resolved.
+ * @param config - backend configuration.
+ * @returns what happened.
+ */
+export declare function mountPtcRuntimeIfAbsent(ctx: PtcHostContext, backend: unknown, config?: Record<string, unknown>): Promise<MountOutcome>;
+/** The default budgets, mirroring the backend's own documented defaults. */
+export declare const PTC_DEFAULT_BUDGETS: {
+    readonly timeoutMs: 120000;
+    readonly maxTimeoutMs: 600000;
+    readonly maxOutputBytes: number;
+    readonly maxOldGenerationSizeMb: 512;
+};
+/** One authorized binding, ready to expose to a program. */
+export interface BindingNamespace {
+    /** The global the program sees, e.g. `tools`. */
+    readonly global: string;
+    readonly functions: Record<string, ToolBinding>;
+}
+/** A request to build the program-visible bindings. */
+export interface BindingRequest {
+    /** The tool names the program declares it will call. */
+    readonly requested: readonly string[];
+    /** What is granted and what is visible. */
+    readonly authority: ProgramAuthority;
+    /** The global identifier the program sees. */
+    readonly global?: string;
+    /**
+     * Resolves one tool name to a binding.
+     *
+     * The CALLER supplies this so that native PTC and external `tool_mode_run` reach tools
+     * through the same execution function rather than through two implementations of it.
+     */
+    readonly resolve: (name: string) => ToolBinding | undefined;
+}
+/** The outcome of building bindings. */
+export type BindingOutcome = {
+    readonly ok: true;
+    readonly namespace: BindingNamespace;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Build the namespace a program may call (CODE-03, SEC-03).
+ *
+ * Refuses the WHOLE request when any name is unattainable, so a program never runs against
+ * a smaller namespace than it declares.
+ *
+ * @param request - what to bind.
+ * @returns the namespace, or the refusal message.
+ */
+export declare function buildToolBindings(request: BindingRequest): BindingOutcome;
+/**
+ * The budgets a run is admitted with (RES-10).
+ *
+ * A requested budget is clamped to the ceiling rather than refused: a caller asking for
+ * longer than policy allows gets policy's figure, which is the direction that cannot be
+ * widened by asking.
+ * @param requestedMs - what the caller asked for, if anything.
+ * @returns the admitted budget.
+ */
+export declare function admitTimeout(requestedMs: number | null | undefined): number;
+/** Drop the cached artifact reading (tests change the environment between cases). */
+export declare function resetConfinementEvidenceCacheForTest(): void;
+/** The current confinement evidence (CODE-09). */
+export declare function confinementDemonstrated(): boolean;
+/**
+ * Why the evidence half of the gate is closed, or undefined when it is open.
+ *
+ * The row and the refusal text use this so "no evidence configured", "recorded for a
+ * different version" and "the recorded run failed" are distinguishable.
+ * @returns the reason, or undefined when evidence exists.
+ */
+export declare function confinementEvidenceReason(): string | undefined;
+/**
+ * Set the confinement evidence (TEST SEAM, CODE-09).
+ *
+ * The setter is the seam the acceptance test uses. It is inert — throws without
+ * moving anything — unless the process carries the explicit environment marker,
+ * so the built artifact cannot have the gate opened by code that merely imports
+ * it. A production build never sets the marker.
+ * @param value - the evidence state to adopt.
+ */
+export declare function setConfinementDemonstratedForTest(value: boolean): void;
+/**
+ * Whether generated-code execution may be exposed to callers (CODE-08, CODE-10).
+ *
+ * Exposure is the CONJUNCTION of two independent facts, and neither can stand in
+ * for the other:
+ *
+ * - CODE-09: the specification's confinement tests must have passed. They have
+ *   not run here, so this half is false — no configuration can open it.
+ * - CODE-10: the OPERATOR must have granted hosted code execution, which is a
+ *   separate consent from ordinary model-tool access. The caller passes the
+ *   operator's grant in, so the gate has a real input rather than being a literal.
+ *
+ * A host with the grant flipped but no confinement evidence stays closed; a host
+ * with confinement evidence but no operator grant stays closed too.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns whether a caller may be served.
+ */
+export declare function mayExposeToClients(operatorGranted: boolean): boolean;
+/**
+ * Describe why generated-code execution is withheld, naming WHICH fact is unmet.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns the reason callers are given.
+ */
+export declare function exposureWithheldReason(operatorGranted: boolean): string;
+//# sourceMappingURL=ptc-runtime.d.ts.map

package/lib/ptc-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ptc-runtime.d.ts","sourceRoot":"","sources":["../src/ptc-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAA;AAO3B,mEAAmE;AACnE,eAAO,MAAM,WAAW,eAAe,CAAA;AAEvC,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B,sBAAsB;IACtB,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;CACtF;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,qBAAqB,CAAA;IAC5D,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAED,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAA;AAEV,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CAChD;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAA;CAC5D;AAED,wCAAwC;AACxC,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAkBzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAS3E;AAmCD,qFAAqF;AACrF,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAED,kDAAkD;AAClD,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,GAAG,SAAS,CAE9D;AAeD;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAQtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,CASvE"}

package/lib/ptc-runtime.js

@@ -0,0 +1,231 @@
+/**
+ * PTC runtime integration: a guarded mount and the ONE authorized tool pipeline.
+ *
+ * The directive is explicit that this is repository work, not a missing upstream product:
+ *
+ *   "Use the existing `@deepseek-ai/dsh-ptc-runtime` interface and a compatible
+ *    `@deepseek-ai/dsh-ptc-runtime-node` backend. Compose its filesystem, subprocess,
+ *    sandbox, and policy dependencies. **Do not call `ctx.ptcRuntime` without mounting a
+ *    provider and then report the missing service as an unavailable upstream product.**"
+ *
+ *   "Native DSH PTC and external `tool_mode_run` must use the SAME authorized tool
+ *    pipeline."
+ *
+ * Two facts shape the mount, both discovered by reading the DSH source rather than guessed:
+ *
+ * 1. **The base bundle already mounts a provider.** `packages/bundle/base/cordis.patch.yml`
+ *    registers `@deepseek-ai/dsh-ptc-runtime-node`, so an UNGUARDED `ctx.plugin(...)`
+ *    throws `service "ptcRuntime" has been registered at <...>`. The guard is mandatory in
+ *    both outcomes, so it is not conditional on which host this finds.
+ * 2. **The composed services are the inject list**, not something the plugin supplies:
+ *    `static inject = ['fs','subprocess','sandbox','sandboxPolicy']`. Mounting them here
+ *    would hit the same duplicate-service throw.
+ *
+ * Everything that touches Cordis or DSH is INJECTED, so the guard logic and the authorized
+ * pipeline are testable without a live runtime.
+ *
+ * @module @try-works/dsh-tool-mode/ptc-runtime
+ */
+import { authorizeProgramTools, describeRejections, } from "./ptc-authority.js";
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { checkConfinementEvidence } from "./ptc-confinement.js";
+import { PACKAGE_VERSION } from "./version.js";
+/** The service key the abstract runtime registers itself under. */
+export const PTC_SERVICE = 'ptcRuntime';
+/**
+ * Mount the Node PTC backend, but only when nothing already provides the service.
+ *
+ * @param ctx - the host context.
+ * @param backend - the backend plugin, or `undefined` when it could not be resolved.
+ * @param config - backend configuration.
+ * @returns what happened.
+ */
+export async function mountPtcRuntimeIfAbsent(ctx, backend, config = {}) {
+    /**
+     * THE GUARD. Checked first, because the base bundle mounts a provider and an unguarded
+     * `ctx.plugin` throws rather than being idempotent.
+     */
+    if (ctx.get(PTC_SERVICE) !== undefined) {
+        return { mounted: false, reason: 'already-provided', service: PTC_SERVICE };
+    }
+    if (backend === undefined || backend === null) {
+        /**
+         * Reported as a REASON, not an exception: a deployment without the backend can still
+         * run native tools, and failing the whole plugin load would remove working
+         * functionality because an optional one is absent.
+         */
+        return { mounted: false, reason: 'backend-unavailable', service: PTC_SERVICE };
+    }
+    await ctx.plugin(backend, config);
+    return { mounted: true, service: PTC_SERVICE };
+}
+/** The default budgets, mirroring the backend's own documented defaults. */
+export const PTC_DEFAULT_BUDGETS = {
+    timeoutMs: 120_000,
+    maxTimeoutMs: 600_000,
+    maxOutputBytes: 64 * 1024 * 1024,
+    maxOldGenerationSizeMb: 512,
+};
+/**
+ * Build the namespace a program may call (CODE-03, SEC-03).
+ *
+ * Refuses the WHOLE request when any name is unattainable, so a program never runs against
+ * a smaller namespace than it declares.
+ *
+ * @param request - what to bind.
+ * @returns the namespace, or the refusal message.
+ */
+export function buildToolBindings(request) {
+    const decision = authorizeProgramTools({ requested: request.requested }, request.authority, request.resolve);
+    if (!decision.ok) {
+        return { ok: false, message: describeRejections(decision.rejections) };
+    }
+    const global = request.global ?? 'tools';
+    /**
+     * The namespace global obeys the same portability rule the backend enforces, so an
+     * invalid one is refused here with a clear reason rather than by the runtime later.
+     */
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(global)) {
+        return {
+            ok: false,
+            message: `the binding namespace "${global}" is not a language-portable identifier; `
+                + 'the same namespace list must work against every backend',
+        };
+    }
+    return { ok: true, namespace: { global, functions: decision.bindings } };
+}
+/**
+ * The budgets a run is admitted with (RES-10).
+ *
+ * A requested budget is clamped to the ceiling rather than refused: a caller asking for
+ * longer than policy allows gets policy's figure, which is the direction that cannot be
+ * widened by asking.
+ * @param requestedMs - what the caller asked for, if anything.
+ * @returns the admitted budget.
+ */
+export function admitTimeout(requestedMs) {
+    if (requestedMs === null) {
+        // `null` means "no deadline". That is a request to REMOVE a limit, so it is clamped to
+        // the ceiling rather than honoured — otherwise a caller could opt out of budgeting.
+        return PTC_DEFAULT_BUDGETS.maxTimeoutMs;
+    }
+    if (requestedMs === undefined)
+        return PTC_DEFAULT_BUDGETS.timeoutMs;
+    if (!Number.isFinite(requestedMs) || requestedMs <= 0)
+        return PTC_DEFAULT_BUDGETS.timeoutMs;
+    return Math.min(requestedMs, PTC_DEFAULT_BUDGETS.maxTimeoutMs);
+}
+/**
+ * Whether the confinement acceptance tests have passed on this deployment
+ * (CODE-09).
+ *
+ * Two sources, both deliberate:
+ *
+ * - the durable EVIDENCE ARTIFACT named by `DSH_PTC_CONFINEMENT_EVIDENCE`, written by
+ *   `scripts/record-confinement-evidence.mjs` only when the real confinement suite
+ *   passed on this package version and platform. This is the operator's release path;
+ * - the TEST SEAM flag below, which only the acceptance test may move, so the
+ *   "export appears when the gate opens" case stays executable.
+ *
+ * A missing, malformed, failed or stale artifact is REFUSED with its reason (see
+ * {@link confinementEvidenceReason}); it is never treated as evidence.
+ */
+let confinementEvidence = false;
+/** The cached artifact check, so one process reads and validates the file once. */
+let artifactCheck;
+/** Read and cache the evidence artifact for this process. */
+function artifactOutcome() {
+    if (artifactCheck !== undefined)
+        return artifactCheck;
+    const check = checkConfinementEvidence({
+        expectedVersion: PACKAGE_VERSION,
+        // The recorder writes this standard local artifact, so a host started normally (no
+        // wrapper launcher, no environment variable) still has a release path.
+        defaultPath: join(homedir(), '.dsh', 'ptc-confinement-evidence.json'),
+    });
+    artifactCheck = check.ok ? { ok: true, reason: '' } : { ok: false, reason: check.reason };
+    return artifactCheck;
+}
+/** Drop the cached artifact reading (tests change the environment between cases). */
+export function resetConfinementEvidenceCacheForTest() {
+    artifactCheck = undefined;
+}
+/** The current confinement evidence (CODE-09). */
+export function confinementDemonstrated() {
+    return confinementEvidence || artifactOutcome().ok;
+}
+/**
+ * Why the evidence half of the gate is closed, or undefined when it is open.
+ *
+ * The row and the refusal text use this so "no evidence configured", "recorded for a
+ * different version" and "the recorded run failed" are distinguishable.
+ * @returns the reason, or undefined when evidence exists.
+ */
+export function confinementEvidenceReason() {
+    return artifactOutcome().ok ? undefined : artifactOutcome().reason;
+}
+/**
+ * The environment marker that arms the test seam (CODE-09).
+ *
+ * The setter below SHIPS in the built artifact (there is no separate test
+ * bundle), so it must be inert in every normal process. It therefore refuses to
+ * move the gate unless the OPERATOR started this process with an explicit
+ * marker — which is itself an operator action, so opening the gate always costs
+ * an operator decision and never happens by config, by import or by accident.
+ * The acceptance test sets the marker; production never does.
+ */
+const CONFINEMENT_SEAM_ENV = 'DSH_PTC_CONFINEMENT_SEAM';
+const CONFINEMENT_SEAM_TOKEN = 'open-for-acceptance-test';
+/**
+ * Set the confinement evidence (TEST SEAM, CODE-09).
+ *
+ * The setter is the seam the acceptance test uses. It is inert — throws without
+ * moving anything — unless the process carries the explicit environment marker,
+ * so the built artifact cannot have the gate opened by code that merely imports
+ * it. A production build never sets the marker.
+ * @param value - the evidence state to adopt.
+ */
+export function setConfinementDemonstratedForTest(value) {
+    if (process.env[CONFINEMENT_SEAM_ENV] !== CONFINEMENT_SEAM_TOKEN) {
+        throw new Error('the confinement evidence is a release gate; the acceptance-test seam is '
+            + 'closed in this process because the operator marker is absent');
+    }
+    confinementEvidence = value;
+}
+/**
+ * Whether generated-code execution may be exposed to callers (CODE-08, CODE-10).
+ *
+ * Exposure is the CONJUNCTION of two independent facts, and neither can stand in
+ * for the other:
+ *
+ * - CODE-09: the specification's confinement tests must have passed. They have
+ *   not run here, so this half is false — no configuration can open it.
+ * - CODE-10: the OPERATOR must have granted hosted code execution, which is a
+ *   separate consent from ordinary model-tool access. The caller passes the
+ *   operator's grant in, so the gate has a real input rather than being a literal.
+ *
+ * A host with the grant flipped but no confinement evidence stays closed; a host
+ * with confinement evidence but no operator grant stays closed too.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns whether a caller may be served.
+ */
+export function mayExposeToClients(operatorGranted) {
+    return operatorGranted && confinementDemonstrated();
+}
+/**
+ * Describe why generated-code execution is withheld, naming WHICH fact is unmet.
+ * @param operatorGranted - whether the operator granted hosted code execution.
+ * @returns the reason callers are given.
+ */
+export function exposureWithheldReason(operatorGranted) {
+    if (!operatorGranted) {
+        return 'generated-code execution is disabled: the operator has not granted hosted '
+            + 'code execution (CODE-10); it is a separate consent from model-tool access';
+    }
+    const evidence = confinementEvidenceReason();
+    return 'generated-code execution is withheld until the confinement tests pass'
+        + (evidence === undefined ? '' : ` (${evidence})`)
+        + '; the runtime is mounted and usable in-process, and no production client is served it';
+}
+//# sourceMappingURL=ptc-runtime.js.map

package/lib/publication.d.ts

@@ -0,0 +1,161 @@
+/**
+ * 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-tool-mode/publication
+ */
+import type { ModelReadiness } from '@try-works/tool-mode-extension-sdk';
+/** 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: ModelReadiness;
+    /** 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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"}