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

package/lib/deployment-coordinator.js

@@ -0,0 +1,274 @@
+/**
+ * Deployment coordination: preparation, single-flight loading and reference counting
+ * (RES-02, RES-03, RES-05).
+ *
+ * This is the module that makes readiness states PRODUCED rather than assigned. Before
+ * it, `prepared-cold` and `ready` were values a test could write; here they are values
+ * this coordinator derives from what actually happened.
+ *
+ * Three rules shape the design:
+ *
+ * - **One operation per EXACT deployment** (RES-05). The key that identifies a
+ *   deployment includes the model revision, engine version, quantization and
+ *   preprocessing recipe, not just a model name — two builds of "the same model" that
+ *   differ in quantization are different deployments and loading one must not satisfy
+ *   a request for the other.
+ * - **Concurrent callers JOIN** (RES-05). A second caller during a load awaits the
+ *   same promise rather than starting a second load, which is the difference between
+ *   sharing 349 MB and allocating it twice.
+ * - **A failed or interrupted preparation cannot become ready** (RES-03). Failure is
+ *   recorded as failure, and a later caller retries rather than inheriting a
+ *   half-prepared deployment that reports success.
+ *
+ * @module @try-works/dsh-tool-mode/deployment-coordinator
+ */
+/**
+ * The stable key for an exact deployment (RES-05).
+ *
+ * A delimiter that cannot appear in a component, so two different field combinations
+ * cannot collide into one key.
+ * @param identity - the deployment identity.
+ * @returns the key.
+ */
+export function deploymentKey(identity) {
+    return [
+        identity.extensionId,
+        identity.modelId,
+        identity.modelRevision,
+        identity.engineVersion,
+        identity.quantization,
+        identity.tokenizer,
+        identity.preprocessingRecipe,
+        // A unit separator is used rather than a printable character because a model id can
+        // legitimately contain most printable ones.
+    ].join('\u001f');
+}
+/**
+ * Build the pre-approval disclosure (RES-02).
+ *
+ * An operator approving a preparation is approving a specific download of a specific
+ * size under specific terms, so all three are computed here rather than discovered
+ * during the install.
+ * @param identity - the exact deployment.
+ * @param assets - the assets the lock resolves to.
+ * @param license - the pinned license.
+ * @returns the plan.
+ */
+export function planPreparation(identity, assets, license) {
+    const totalBytes = assets.reduce((sum, asset) => sum + asset.bytes, 0);
+    return {
+        identity,
+        assets,
+        totalBytes,
+        // Storage is stated separately from download because an operator approving
+        // bandwidth is not thereby approving disk.
+        storageBytes: totalBytes,
+        requiresExecutableApproval: assets.some(asset => asset.executable),
+        license,
+    };
+}
+/** Raised when a deployment cannot be prepared. */
+export class DeploymentError extends Error {
+    name = 'DeploymentError';
+    key;
+    constructor(key, message) {
+        super(message);
+        this.key = key;
+    }
+}
+/**
+ * Coordinates preparation, loading and reference counting per exact deployment.
+ *
+ * Not thread-safe in the language sense — Node is single-threaded — but
+ * single-flight with respect to `await`: two callers that reach `acquire` before the
+ * load settles both await ONE promise.
+ */
+export class DeploymentCoordinator {
+    #records = new Map();
+    /** The in-flight load per key, so concurrent callers join rather than duplicate. */
+    #loading = new Map();
+    /** Per-caller release handlers, so releasing is idempotent. */
+    #leases = new WeakSet();
+    /** Every tracked deployment, for diagnostics. */
+    get deployments() {
+        return [...this.#records.values()];
+    }
+    /** One deployment's record. */
+    record(key) {
+        return this.#records.get(key);
+    }
+    /**
+     * The state to report for a deployment that has not been touched yet.
+     * @param identity - the exact deployment.
+     * @returns the readiness.
+     */
+    readinessOf(identity) {
+        return this.#records.get(deploymentKey(identity))?.readiness ?? 'needs-preparation';
+    }
+    /**
+     * Prepare and load a deployment, joining an in-flight load if there is one.
+     *
+     * RES-05: "One preparation/load operation per exact provider deployment; concurrent
+     * callers join or queue."
+     * @param identity - the exact deployment.
+     * @param load - performs the load. Called AT MOST ONCE per concurrent group.
+     * @param options - cancellation for THIS caller.
+     * @returns the lease.
+     * @throws DeploymentError when the load fails.
+     */
+    async acquire(identity, load, options = {}) {
+        const key = deploymentKey(identity);
+        let record = this.#records.get(key);
+        if (record === undefined) {
+            record = {
+                key,
+                identity,
+                readiness: 'needs-preparation',
+                activeUsers: 0,
+                loadingSince: null,
+                failureReason: null,
+            };
+            this.#records.set(key, record);
+        }
+        // A previous failure must not be inherited as a success: RES-03 says a failed or
+        // interrupted preparation cannot become ready, so the next caller RETRIES.
+        if (record.readiness === 'failed') {
+            record.readiness = 'needs-preparation';
+            record.failureReason = null;
+        }
+        let joined = false;
+        if (record.readiness === 'ready') {
+            // Already loaded: nothing to join.
+        }
+        else {
+            let pending = this.#loading.get(key);
+            if (pending === undefined) {
+                pending = this.#startLoad(record, load);
+                this.#loading.set(key, pending);
+            }
+            else {
+                joined = true;
+            }
+            try {
+                await pending;
+            }
+            catch (error) {
+                // The caller is told WHY, and the record keeps the failure so a later caller
+                // retries rather than seeing a stale success.
+                throw new DeploymentError(key, `${identity.extensionId}/${identity.modelId} could not be prepared: `
+                    + `${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (options.signal?.aborted === true) {
+            // Cancellation is PER INVOCATION (RES-05): this caller gives up, and the
+            // deployment it just waited for is left loaded and available to whoever else
+            // wants it. Killing it here would destroy another caller's legitimate work.
+            throw new DeploymentError(key, 'the caller cancelled before the deployment could be used');
+        }
+        record.activeUsers += 1;
+        const lease = {
+            key,
+            readiness: record.readiness,
+            joined,
+            release: () => this.#release(key, lease),
+        };
+        return lease;
+    }
+    /** Start the single load for a key. */
+    #startLoad(record, load) {
+        record.readiness = 'loading';
+        record.loadingSince = Date.now();
+        const pending = (async () => {
+            try {
+                await load();
+                // A load that threw is not ready; a load that returned is.
+                record.readiness = 'ready';
+                record.failureReason = null;
+            }
+            catch (error) {
+                // RES-03: a failed or interrupted preparation CANNOT become ready.
+                record.readiness = 'failed';
+                record.failureReason = error instanceof Error ? error.message : String(error);
+                throw error;
+            }
+            finally {
+                record.loadingSince = null;
+                this.#loading.delete(record.key);
+            }
+        })();
+        return pending;
+    }
+    /** Decrement a caller's reference. */
+    #release(key, lease) {
+        if (this.#leases.has(lease))
+            return;
+        this.#leases.add(lease);
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return;
+        record.activeUsers = Math.max(0, record.activeUsers - 1);
+    }
+    /**
+     * Unload a deployment, but only when it is IDLE (RES-05).
+     *
+     * "Unload only idle resources or an explicitly revoked deployment after coordinated
+     * cleanup." Unloading a busy deployment would discard another caller's work.
+     * @param key - the deployment key.
+     * @param force - set only for an explicitly revoked deployment.
+     * @returns whether it was unloaded, and why not when it was not.
+     */
+    unload(key, force = false) {
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return { unloaded: false, reason: 'no such deployment' };
+        if (this.#loading.has(key)) {
+            return { unloaded: false, reason: 'a load is in progress' };
+        }
+        if (record.activeUsers > 0 && !force) {
+            // The count is the whole point: another caller is using this right now.
+            return { unloaded: false, reason: `${record.activeUsers} caller(s) are still using it` };
+        }
+        record.readiness = 'prepared-cold';
+        return { unloaded: true };
+    }
+    /**
+     * Revoke a deployment, discarding in-flight work after coordinated cleanup (RES-05).
+     * @param key - the deployment key.
+     * @returns whether it was revoked.
+     */
+    revoke(key) {
+        const record = this.#records.get(key);
+        if (record === undefined)
+            return false;
+        // Revocation is the one case that may discard a busy deployment, and it is
+        // explicit: the operator asked for it rather than a policy inferring it.
+        record.activeUsers = 0;
+        record.readiness = 'prepared-cold';
+        return true;
+    }
+}
+/**
+ * Decide which assets may be deleted (RES-03).
+ *
+ * RES-03: "Package uninstall and asset purge are separate operations; delete only
+ * unreferenced host-owned assets." So removing an owner does not delete anything, and
+ * an asset with another owner is never deleted.
+ * @param ownership - the current records.
+ * @param removedOwner - the owner being uninstalled.
+ * @returns the digests that are now unreferenced, and those still held.
+ */
+export function purgeCandidates(ownership, removedOwner) {
+    const deletable = [];
+    const retained = [];
+    for (const asset of ownership) {
+        const remaining = asset.owners.filter(owner => owner !== removedOwner);
+        // An asset with a remaining owner is RETAINED, because deleting it would break a
+        // deployment nobody uninstalled.
+        if (remaining.length === 0)
+            deletable.push(asset.digest);
+        else
+            retained.push(asset.digest);
+    }
+    return { deletable, retained };
+}
+//# sourceMappingURL=deployment-coordinator.js.map

package/lib/diagnostics.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The settings/diagnostic surface (OBS-04).
+ *
+ * OBS-04 names, item by item, what an operator must be able to SEE. A surface that answers
+ * "is it on?" but not "which client may call what, and exactly why is this not supported here?"
+ * leaves an operator guessing, so each item below is reported with the fact that makes it
+ * actionable rather than a bare boolean.
+ *
+ * DESIGN CONSTRAINTS, because a diagnostic surface is unusually easy to get wrong:
+ *
+ *  - **It reports STATE, never credentials.** It names authorized clients and grants; it
+ *    never echoes a token. A diagnostic surface is the single most likely place for a secret
+ *    to leak, because its whole purpose is to be displayed.
+ *  - **Unsupported is always paired with WHY.** OBS-04 asks for "exact unsupported-platform
+ *    reasons", and a bare `supported: false` sends an operator to the source to find out.
+ *  - **Unknown is its own state.** A fact that cannot be determined is reported as unknown
+ *    rather than defaulted to false, because "not supported" and "not checked" call for
+ *    different actions.
+ *
+ * @module @try-works/dsh-tool-mode/diagnostics
+ */
+/** One capability this deployment either has, lacks, or has not determined. */
+export interface CapabilityReport {
+    /** The capability, in the vocabulary OBS-04 uses. */
+    readonly capability: string;
+    /** Whether it is available HERE. */
+    readonly state: 'available' | 'unavailable' | 'unknown';
+    /**
+     * Why, whenever the state is not `available`.
+     *
+     * Never omitted for `unavailable`: an operator cannot act on a fact they cannot explain,
+     * and OBS-04 asks for the EXACT reason.
+     */
+    readonly reason?: string;
+}
+/** Inputs the surface reports on. */
+export interface DiagnosticInputs {
+    /** Whether the MCP surface is mounted. */
+    readonly mcpMounted: boolean;
+    /** Where it listens, when it does. */
+    readonly mcpEndpoint?: string;
+    /** Whether the endpoint requires a credential. */
+    readonly mcpRequiresCredential?: boolean;
+    /** Client identities currently authorized, if the deployment tracks them. */
+    readonly authorizedClients?: readonly string[];
+    /** Tool names exported to clients. */
+    readonly exportedTools: readonly string[];
+    /** Tools registered on the host but deliberately NOT exported. */
+    readonly withheldTools?: readonly string[];
+    /** Why each withheld tool is not exported, keyed by tool name. */
+    readonly withheldReasons?: Readonly<Record<string, string>>;
+    /** Per-model preparation state. */
+    readonly preparation?: readonly {
+        readonly modelId: string;
+        readonly prepared: boolean;
+        readonly reason?: string;
+    }[];
+    /** The implementation each contract currently resolves to. */
+    readonly selectedImplementations?: readonly {
+        readonly contractId: string;
+        readonly implementationId: string;
+    }[];
+    /** Installed extensions and whether they are active. */
+    readonly extensions?: readonly {
+        readonly extensionId: string;
+        readonly version: string;
+        readonly activation: string;
+    }[];
+    /** Whether the deployment can remove an extension, and whether it protects built-ins. */
+    readonly uninstall?: {
+        readonly available: boolean;
+        readonly builtInsProtected: boolean;
+        readonly reason?: string;
+    };
+    /** Location and network requirements. */
+    readonly requirements?: {
+        readonly localOnly: boolean;
+        readonly networkOrigins: readonly string[];
+    };
+    /** Code Mode permission and backend readiness. */
+    readonly codeMode?: {
+        readonly permitted: boolean;
+        readonly backendReady: boolean;
+        readonly reason?: string;
+    };
+    /** Platform facts, so an unsupported reason can name the platform it refers to. */
+    readonly platform: {
+        readonly os: string;
+        readonly arch: string;
+        readonly nodeVersion: string;
+    };
+}
+/** The reported surface. */
+export interface DiagnosticReport {
+    readonly platform: DiagnosticInputs['platform'];
+    readonly mcp: {
+        readonly mounted: boolean;
+        readonly endpoint: string | null;
+        readonly requiresCredential: boolean | null;
+        readonly authorizedClients: readonly string[];
+        readonly exportedTools: readonly string[];
+        readonly withheldTools: readonly string[];
+        readonly withheldReasons: Readonly<Record<string, string>>;
+    };
+    readonly preparation: readonly {
+        readonly modelId: string;
+        readonly prepared: boolean;
+        readonly reason: string | null;
+    }[];
+    readonly implementations: readonly {
+        readonly contractId: string;
+        readonly implementationId: string;
+    }[];
+    readonly extensions: readonly {
+        readonly extensionId: string;
+        readonly version: string;
+        readonly activation: string;
+    }[];
+    readonly capabilities: readonly CapabilityReport[];
+    readonly uninstall: DiagnosticInputs['uninstall'] | null;
+    readonly requirements: DiagnosticInputs['requirements'] | null;
+    readonly codeMode: DiagnosticInputs['codeMode'] | null;
+}
+/**
+ * Build the diagnostic report.
+ *
+ * @param inputs - the observed state.
+ * @returns everything OBS-04 names, with a reason wherever something is not available.
+ */
+export declare function buildDiagnostics(inputs: DiagnosticInputs): DiagnosticReport;
+/**
+ * The exact reason something is unsupported on THIS platform.
+ *
+ * Exists as a function because OBS-04 asks for the reason to be EXACT, and an exact reason has
+ * to name the platform it is about — "unsupported" against an unnamed platform sends an
+ * operator to compare their machine against a document.
+ *
+ * @param subject - what is unsupported.
+ * @param supportedOn - the platforms it does work on.
+ * @param platform - the platform being reported.
+ * @returns a reason naming both sides of the mismatch.
+ */
+export declare function unsupportedReason(subject: string, supportedOn: readonly {
+    readonly os: string;
+    readonly arch: string;
+}[], platform: {
+    readonly os: string;
+    readonly arch: string;
+}): string;
+/**
+ * Whether the deployment may retain request and response BODIES (OBS-03).
+ *
+ * OBS-03's operative sentence is a refusal, not a preference: where an operator's no-retention
+ * policy cannot be honoured together with DSH's requirement that model-visible inputs be
+ * reconstructable, harness-backed execution must be REFUSED rather than bodies silently
+ * logged or DSH bypassed. This returns the decision so the caller cannot soften it into a
+ * warning.
+ *
+ * @param policy - the deployment's retention policy.
+ * @returns whether harness-backed execution is permitted.
+ */
+export declare function harnessExecutionDecision(policy: {
+    readonly retainsBodies: boolean;
+    readonly requiresReconstructableInputs: boolean;
+}): {
+    readonly permitted: boolean;
+    readonly reason?: string;
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/diagnostics.d.ts.map

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

package/lib/diagnostics.js

@@ -0,0 +1,136 @@
+/**
+ * The settings/diagnostic surface (OBS-04).
+ *
+ * OBS-04 names, item by item, what an operator must be able to SEE. A surface that answers
+ * "is it on?" but not "which client may call what, and exactly why is this not supported here?"
+ * leaves an operator guessing, so each item below is reported with the fact that makes it
+ * actionable rather than a bare boolean.
+ *
+ * DESIGN CONSTRAINTS, because a diagnostic surface is unusually easy to get wrong:
+ *
+ *  - **It reports STATE, never credentials.** It names authorized clients and grants; it
+ *    never echoes a token. A diagnostic surface is the single most likely place for a secret
+ *    to leak, because its whole purpose is to be displayed.
+ *  - **Unsupported is always paired with WHY.** OBS-04 asks for "exact unsupported-platform
+ *    reasons", and a bare `supported: false` sends an operator to the source to find out.
+ *  - **Unknown is its own state.** A fact that cannot be determined is reported as unknown
+ *    rather than defaulted to false, because "not supported" and "not checked" call for
+ *    different actions.
+ *
+ * @module @try-works/dsh-tool-mode/diagnostics
+ */
+/**
+ * Build the diagnostic report.
+ *
+ * @param inputs - the observed state.
+ * @returns everything OBS-04 names, with a reason wherever something is not available.
+ */
+export function buildDiagnostics(inputs) {
+    const capabilities = [
+        inputs.mcpMounted
+            ? { capability: 'mcp', state: 'available' }
+            : {
+                capability: 'mcp',
+                state: 'unavailable',
+                reason: 'no MCP surface is mounted in this deployment, so no client can call these tools',
+            },
+        /*
+         * The endpoint is reported separately from `mcp` because a mounted surface with no
+         * endpoint is a real state: the host composes tools for its own agent and serves nothing.
+         */
+        inputs.mcpEndpoint === undefined
+            ? { capability: 'mcp-endpoint', state: 'unavailable', reason: 'the mounted MCP surface exposes no network endpoint' }
+            : { capability: 'mcp-endpoint', state: 'available' },
+        inputs.mcpRequiresCredential === true
+            ? { capability: 'mcp-authorization', state: 'available' }
+            : inputs.mcpRequiresCredential === false
+                ? {
+                    capability: 'mcp-authorization',
+                    state: 'unavailable',
+                    reason: 'the endpoint accepts unauthenticated requests, so any local caller may invoke these tools',
+                }
+                // `unknown` rather than `false`: a fact that was not determined is not a fact that is
+                // absent, and the two call for different actions.
+                : { capability: 'mcp-authorization', state: 'unknown', reason: 'the deployment did not report whether a credential is required' },
+    ];
+    if (inputs.codeMode !== undefined) {
+        capabilities.push(inputs.codeMode.permitted && inputs.codeMode.backendReady
+            ? { capability: 'code-mode', state: 'available' }
+            : {
+                capability: 'code-mode',
+                state: 'unavailable',
+                reason: inputs.codeMode.reason
+                    ?? (inputs.codeMode.permitted
+                        ? 'generated-code execution is permitted but no backend is ready to run it'
+                        : 'generated-code execution is not permitted in this deployment'),
+            });
+    }
+    return {
+        platform: inputs.platform,
+        mcp: {
+            mounted: inputs.mcpMounted,
+            endpoint: inputs.mcpEndpoint ?? null,
+            requiresCredential: inputs.mcpRequiresCredential ?? null,
+            authorizedClients: [...(inputs.authorizedClients ?? [])],
+            exportedTools: [...inputs.exportedTools],
+            withheldTools: [...(inputs.withheldTools ?? [])],
+            withheldReasons: { ...(inputs.withheldReasons ?? {}) },
+        },
+        preparation: (inputs.preparation ?? []).map(entry => ({
+            modelId: entry.modelId,
+            prepared: entry.prepared,
+            // A prepared model has nothing to explain; an unprepared one must say what is missing.
+            reason: entry.prepared ? null : entry.reason ?? 'no reason was reported, which is itself a defect in the caller',
+        })),
+        implementations: [...(inputs.selectedImplementations ?? [])],
+        extensions: [...(inputs.extensions ?? [])],
+        capabilities,
+        uninstall: inputs.uninstall ?? null,
+        requirements: inputs.requirements ?? null,
+        codeMode: inputs.codeMode ?? null,
+    };
+}
+/**
+ * The exact reason something is unsupported on THIS platform.
+ *
+ * Exists as a function because OBS-04 asks for the reason to be EXACT, and an exact reason has
+ * to name the platform it is about — "unsupported" against an unnamed platform sends an
+ * operator to compare their machine against a document.
+ *
+ * @param subject - what is unsupported.
+ * @param supportedOn - the platforms it does work on.
+ * @param platform - the platform being reported.
+ * @returns a reason naming both sides of the mismatch.
+ */
+export function unsupportedReason(subject, supportedOn, platform) {
+    const supported = supportedOn.map(entry => `${entry.os}/${entry.arch}`);
+    if (supported.length === 0) {
+        // A different sentence, because "no platform supports this" is not a mismatch.
+        return `${subject} declares no supported platform, so it cannot run anywhere`;
+    }
+    return `${subject} supports ${supported.join(', ')} but this host is ${platform.os}/${platform.arch}`;
+}
+/**
+ * Whether the deployment may retain request and response BODIES (OBS-03).
+ *
+ * OBS-03's operative sentence is a refusal, not a preference: where an operator's no-retention
+ * policy cannot be honoured together with DSH's requirement that model-visible inputs be
+ * reconstructable, harness-backed execution must be REFUSED rather than bodies silently
+ * logged or DSH bypassed. This returns the decision so the caller cannot soften it into a
+ * warning.
+ *
+ * @param policy - the deployment's retention policy.
+ * @returns whether harness-backed execution is permitted.
+ */
+export function harnessExecutionDecision(policy) {
+    if (!policy.retainsBodies && policy.requiresReconstructableInputs) {
+        return {
+            permitted: false,
+            reason: 'the deployment does not retain bodies while DSH requires model-visible inputs to be '
+                + 'reconstructable, so harness-backed execution is refused here rather than logging '
+                + 'bodies against the policy or bypassing DSH',
+        };
+    }
+    return { permitted: true };
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/discovery-contracts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * DECL-07 read-only discovery contracts.
+ *
+ * These tools were registered natively but withheld from MCP, so an authorized
+ * external caller could not read the catalogue or per-tool schemas. Their contracts
+ * are published independently of any model package; the execution path is the ordinary
+ * DSH tool runtime, not a private MCP-only handler.
+ */
+import type { ToolContract } from '@try-works/tool-mode-contracts';
+/** `tool_mode_list` — permitted tools, readiness and catalog revision. */
+export declare const TOOL_MODE_LIST_CONTRACT: ToolContract;
+/** `tool_mode_describe` — schemas, model facts, limits and catalog revision. */
+export declare const TOOL_MODE_DESCRIBE_CONTRACT: ToolContract;
+//# sourceMappingURL=discovery-contracts.d.ts.map

package/lib/discovery-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-contracts.d.ts","sourceRoot":"","sources":["../src/discovery-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AA+ClE,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,EAAE,YAiBrC,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,2BAA2B,EAAE,YAmBzC,CAAA"}