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

package/lib/resource-governance.js

@@ -0,0 +1,213 @@
+/**
+ * Resource governance (RES-01, RES-04, RES-06, RES-09).
+ *
+ * Three distinctions here are easy to collapse and expensive to get wrong.
+ *
+ * **Readiness is not residency** (RES-04). The state vocabulary has eight members,
+ * and they answer two DIFFERENT questions: `unavailable` and `needs-preparation` say
+ * a call is not possible at all, while `prepared-cold`, `loading`, `ready` and `busy`
+ * say it is possible and merely describe how the call will be admitted. Treating
+ * `prepared-cold` as uncallable withdraws a tool that works, and — worse — makes the
+ * tool surface change on every warm/cold transition, which RES-04 explicitly forbids
+ * because an agent's view of its tools must not flicker with a cache.
+ *
+ * **A budget is a rejection, not a truncation** (RES-01, RES-09). Over-budget input
+ * is refused WITH THE ACTUAL LIMITS, because a caller that cannot see the limit
+ * cannot choose a smaller input. Silently trimming source data is the failure both
+ * requirements name.
+ *
+ * **Cancellation is a claim about behaviour** (RES-06). Where a backend cannot be
+ * interrupted, saying "cancelled" while its work continues is worse than admitting
+ * the work is still running, so the outcome says which of the two happened.
+ *
+ * @module @try-works/dsh-tool-mode/resource-governance
+ */
+/** The states in which a call is possible at all (RES-04). */
+const CALLABLE = new Set([
+    // A cold but PREPARED deployment is callable: preparation, not residency, is what
+    // makes a call possible.
+    'prepared-cold',
+    'loading',
+    'ready',
+    'busy',
+]);
+/** The states that imply assets are on disk (RES-04). */
+const PREPARED = new Set([
+    'prepared-cold',
+    'loading',
+    'ready',
+    'busy',
+]);
+/**
+ * Whether a call is possible in this state (RES-04).
+ *
+ * Determined by compatibility, authorization and PREPARATION — never by residency.
+ * @param state - the current state.
+ * @returns whether the tool can be called.
+ */
+export function isCallable(state) {
+    return CALLABLE.has(state);
+}
+/**
+ * Whether assets are prepared (RES-04).
+ * @param state - the current state.
+ * @returns whether preparation has completed.
+ */
+export function isPrepared(state) {
+    return PREPARED.has(state);
+}
+/**
+ * How residency affects admission (RES-04).
+ *
+ * This is the half that residency legitimately controls: not WHETHER a tool exists,
+ * but what a call to it costs.
+ * @param state - the current state.
+ * @returns the admission behaviour, or undefined when no call is possible.
+ */
+export function admissionOf(state) {
+    switch (state) {
+        case 'ready': return 'immediate';
+        case 'prepared-cold': return 'loads-first';
+        // `loading` and `busy` both mean work is in progress, so a new call waits for it
+        // rather than starting a second load of the same deployment.
+        case 'loading':
+        case 'busy': return 'queued';
+        default: return undefined;
+    }
+}
+/**
+ * Whether a tool DESCRIPTION may vary with this state (RES-04).
+ *
+ * Always false. RES-04 forbids changing agent tool descriptions on every warm/cold
+ * transition, so this exists to be asserted rather than to be consulted: a caller
+ * that branches on residency when building a description has found a bug.
+ * @returns always false.
+ */
+export function descriptionMayVaryWithResidency() {
+    return false;
+}
+/**
+ * The product defaults the requirement names verbatim (RES-09).
+ *
+ * These are PRODUCT limits, not guarantees that every input within them fits: the
+ * requirement says model context limits may force lower admission, so a successful
+ * check here is necessary and not sufficient.
+ */
+export const DEFAULT_BUDGETS = {
+    image: {
+        sourceBytes: 8 * 1024 * 1024,
+        decodedPixels: 16_000_000,
+    },
+    video: {
+        sourceBytes: 128 * 1024 * 1024,
+        videoSeconds: 120,
+        videoFrames: 32,
+    },
+    audio: {
+        // 16 kHz mono for an hour, matching the transcription contract's admission.
+        audioSamples: 16_000 * 3600,
+    },
+    text: {
+        sourceBytes: 1024 * 1024,
+        processorTokens: 8192,
+    },
+};
+/**
+ * Decide whether an input fits its budget (RES-01, RES-09).
+ *
+ * Over-budget input is REJECTED with the actual limits. It is never truncated and
+ * never sampled down, because the caller cannot otherwise tell that what it supplied
+ * is not what was processed.
+ * @param measurement - what the input actually is.
+ * @param budget - the limits in force.
+ * @returns the decision, naming every exceeded budget.
+ */
+export function admit(measurement, budget) {
+    const exceeded = [];
+    for (const [kind, limit] of Object.entries(budget)) {
+        if (limit === null || limit === undefined)
+            continue;
+        const measured = measurement[kind];
+        // An unmeasured budget cannot be enforced, and pretending it passed would be a
+        // silent acceptance. It is reported as exceeded by zero only if actually over, so
+        // an absent measurement is treated as "not applicable" rather than as "fits".
+        if (measured === undefined)
+            continue;
+        if (measured > limit)
+            exceeded.push({ kind, measured, limit });
+    }
+    return exceeded.length === 0 ? { admitted: true } : { admitted: false, exceeded };
+}
+/**
+ * Render a rejection the caller can act on (RES-01).
+ *
+ * The requirement says to reject with ACTUAL LIMITS: a caller told only "too large"
+ * cannot choose a smaller input.
+ * @param decision - a rejection.
+ * @returns the message.
+ */
+export function describeRejection(decision) {
+    return decision.exceeded
+        .map(entry => `${entry.kind} is ${entry.measured}, over the limit of ${entry.limit}`)
+        .join('; ');
+}
+/**
+ * Build the coverage report for an input that had to be sampled (RES-09).
+ *
+ * Sampling is only legitimate when it is EXPLICIT and its coverage is REPORTED. An
+ * implementation that quietly processed 32 of 900 frames and reported success has
+ * told the caller something false about the input it supplied.
+ * @param processed - units processed.
+ * @param total - units in the source.
+ * @param sampling - the instruction applied, when one was.
+ * @returns the coverage report.
+ */
+export function coverageOf(processed, total, sampling) {
+    const complete = processed >= total;
+    return {
+        complete,
+        processed,
+        total,
+        sampling,
+        reason: complete
+            ? null
+            : sampling === null
+                // Incomplete WITHOUT a sampling instruction is a defect, not a policy: the
+                // requirement forbids silent sampling, so this case is named rather than
+                // dressed up as intentional.
+                ? 'the source was not fully processed and no sampling instruction was recorded'
+                : `sampled by instruction: ${sampling.instruction}`,
+    };
+}
+/**
+ * Describe a cancellation honestly (RES-06).
+ *
+ * RES-06 forbids claiming cancellation while uncontrolled work continues
+ * indefinitely. Where a backend cannot be interrupted safely, the honest report is
+ * that it is still running and its result will be discarded — which is also why the
+ * requirement prefers isolating such a backend in an owned worker.
+ * @param interruptible - whether the backend can be interrupted safely.
+ * @param subject - what is being cancelled, for the message.
+ * @returns the outcome to report.
+ */
+export function cancellationOutcome(interruptible, subject) {
+    return interruptible
+        ? { stopped: true }
+        : {
+            stopped: false,
+            reason: `${subject} cannot be interrupted safely; it will run to completion and its result discarded`,
+        };
+}
+/**
+ * Whether a decompression bomb must be rejected before allocation (RES-09).
+ *
+ * The check is on the DECLARED expanded size, before any allocation: a check that
+ * runs after decompression has already lost.
+ * @param declaredBytes - the expansion the container declares.
+ * @param limit - the budget for this input class.
+ * @returns whether to reject.
+ */
+export function isExpansionBomb(declaredBytes, limit) {
+    return declaredBytes > limit;
+}
+//# sourceMappingURL=resource-governance.js.map

package/lib/server-lifecycle.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Server and plugin lifecycle (RUN-01, RUN-02, RUN-05, RUN-06, RUN-07).
+ *
+ * Almost every rule here is about what must NOT happen:
+ *
+ * - **Do not announce readiness before it is true** (RUN-06). A listener that reports
+ *   ready before its bind or its initialisation succeeded sends a client to a port
+ *   that is not answering. Readiness is therefore a STATE derived from both, not a flag
+ *   set by whoever got there first.
+ * - **Do not resolve a port conflict by force or by stealth** (RUN-06). Taking the port
+ *   from another process, or silently moving to a different one, both break a client
+ *   that was told where to connect. The conflict is reported.
+ * - **Do not let a failed start take the host with it** (RUN-06). The MCP endpoint is
+ *   one feature of a much larger host; a port clash must leave the rest running.
+ * - **Do not kill work you do not own** (RUN-07). A model process serving another
+ *   still-authorized owner is not this lifecycle's to terminate.
+ * - **Do not prepare anything at startup** (RUN-05). Nothing downloads because a plugin
+ *   loaded or a client listed tools.
+ *
+ * @module @try-works/dsh-tool-mode/server-lifecycle
+ */
+/** Where the server is in its lifecycle. */
+export type ServerState = 'stopped' | 'starting' | 'ready' | 'stopping' | 'failed';
+/** Why a start failed. */
+export interface StartFailure {
+    /** A stable code, so a caller can branch without matching a message. */
+    readonly code: 'PORT_IN_USE' | 'BIND_FAILED' | 'INIT_FAILED' | 'ALREADY_STARTED';
+    readonly message: string;
+    /** What to do about it, because a bare failure leaves an operator stuck. */
+    readonly remedy: string;
+}
+/** One piece of work the server owns (RUN-07). */
+export interface OwnedWork {
+    /** An identity for diagnostics. */
+    readonly id: string;
+    /**
+     * The owner this work serves.
+     *
+     * Shutdown cancels work THIS lifecycle owns, and the owner is recorded so a model
+     * process serving another still-authorized owner is never terminated by mistake.
+     */
+    readonly owner: string;
+    /** Ask the work to stop. */
+    cancel(): Promise<void> | void;
+    /** Force it to stop after the grace period. */
+    terminate?(): void;
+}
+/** What the lifecycle needs from its environment. */
+export interface LifecycleHost {
+    /**
+     * Bind the listener.
+     *
+     * Implementations throw with a `code` of `EADDRINUSE` for a port conflict; the
+     * lifecycle reports it rather than trying to resolve it.
+     */
+    bind(): Promise<{
+        readonly port: number;
+        readonly close: () => Promise<void>;
+    }>;
+    /** Initialise whatever must be ready before the endpoint serves. */
+    initialise(): Promise<void>;
+    /** Called once, and only once, when both bind and initialise have succeeded. */
+    onReady(port: number): void;
+    /** Log a non-fatal diagnostic. */
+    log(message: string): void;
+}
+/** The documented grace period for cleanup (RUN-07). */
+export declare const DEFAULT_GRACE_MS = 5000;
+/** How a shutdown ended. */
+export interface ShutdownReport {
+    /** Work that stopped within the grace period. */
+    readonly cancelled: readonly string[];
+    /** Work that had to be terminated after it. */
+    readonly terminated: readonly string[];
+    /** Work that was NOT touched because this lifecycle does not own it. */
+    readonly untouched: readonly string[];
+    /** Whether the port was released. */
+    readonly portReleased: boolean;
+    /** Whether cleanup finished inside the grace period. */
+    readonly withinGrace: boolean;
+}
+/**
+ * Manages one MCP listener's lifecycle.
+ *
+ * Deliberately separate from the DSH plugin's own lifecycle: RUN-01 requires disabling
+ * the SERVER to stop its listener and owned work without disabling unrelated DSH tools,
+ * so the two must be independently stoppable.
+ */
+export declare class ServerLifecycle {
+    #private;
+    constructor(host: LifecycleHost, options?: {
+        readonly graceMs?: number;
+    });
+    /** The current state. */
+    get state(): ServerState;
+    /** The bound port, once one exists. */
+    get port(): number | null;
+    /**
+     * Whether the endpoint is serving (RUN-06).
+     *
+     * True only after BOTH bind and initialise succeeded. A caller asking "can I connect"
+     * gets one answer, and it is not derived from a flag somebody set early.
+     */
+    get ready(): boolean;
+    /** Work currently owned, for diagnostics. */
+    get owned(): readonly OwnedWork[];
+    /**
+     * Start the listener.
+     *
+     * @returns nothing on success, or the failure — never a thrown exception, because
+     *   RUN-06 requires a failed start not to crash the unrelated host.
+     */
+    start(): Promise<{
+        readonly ok: true;
+        readonly port: number;
+    } | {
+        readonly ok: false;
+        readonly failure: StartFailure;
+    }>;
+    /**
+     * Register work this lifecycle owns (RUN-07).
+     *
+     * Refused once shutdown has begun, so a call racing a stop cannot slip into the
+     * cleanup window and be left running.
+     * @param work - the work to own.
+     * @returns whether it was accepted.
+     */
+    adopt(work: OwnedWork): boolean;
+    /** Release work that finished on its own. */
+    release(id: string): void;
+    /**
+     * Stop the listener and everything it owns (RUN-07).
+     *
+     * The order is the requirement's: refuse new work, cancel owned foreground
+     * invocations, wait within the grace period, terminate what remains, close the
+     * transport and release the port. Work belonging to another owner is LEFT ALONE.
+     * @param options - `ownedBy` selects the owner whose work may be stopped.
+     * @returns the report.
+     */
+    stop(options?: {
+        readonly ownedBy?: string;
+    }): Promise<ShutdownReport>;
+}
+/** What startup may and may not do (RUN-05). */
+export interface StartupPolicy {
+    /**
+     * Whether model preparation may run at startup.
+     *
+     * Always false. The type carries it so the prohibition is visible at the call site
+     * rather than only in the requirement.
+     */
+    readonly preparesModels: false;
+    /** Whether package resolution may run at startup. Always false. */
+    readonly resolvesPackages: false;
+    /** Whether discovery is read-only. Always true. */
+    readonly discoveryIsReadOnly: true;
+}
+/** The only startup policy this implementation permits (RUN-05). */
+export declare const READ_ONLY_STARTUP: StartupPolicy;
+/**
+ * Whether a startup action is permitted (RUN-05).
+ *
+ * @param action - what the startup wants to do.
+ * @returns whether it may.
+ */
+export declare function startupPermits(action: 'restore-active' | 'inspect-assets' | 'read-manifests' | 'prepare-model' | 'resolve-package' | 'download-weights'): boolean;
+/**
+ * Whether disabling the MCP server must also disable unrelated DSH tools (RUN-01).
+ *
+ * It must not. The server and the plugin are independently stoppable, which is why the
+ * lifecycle is a separate object from the plugin's own registration state.
+ * @returns always false.
+ */
+export declare function disablingServerDisablesOtherTools(): boolean;
+//# sourceMappingURL=server-lifecycle.d.ts.map

package/lib/server-lifecycle.d.ts.map

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

package/lib/server-lifecycle.js

@@ -0,0 +1,269 @@
+/**
+ * Server and plugin lifecycle (RUN-01, RUN-02, RUN-05, RUN-06, RUN-07).
+ *
+ * Almost every rule here is about what must NOT happen:
+ *
+ * - **Do not announce readiness before it is true** (RUN-06). A listener that reports
+ *   ready before its bind or its initialisation succeeded sends a client to a port
+ *   that is not answering. Readiness is therefore a STATE derived from both, not a flag
+ *   set by whoever got there first.
+ * - **Do not resolve a port conflict by force or by stealth** (RUN-06). Taking the port
+ *   from another process, or silently moving to a different one, both break a client
+ *   that was told where to connect. The conflict is reported.
+ * - **Do not let a failed start take the host with it** (RUN-06). The MCP endpoint is
+ *   one feature of a much larger host; a port clash must leave the rest running.
+ * - **Do not kill work you do not own** (RUN-07). A model process serving another
+ *   still-authorized owner is not this lifecycle's to terminate.
+ * - **Do not prepare anything at startup** (RUN-05). Nothing downloads because a plugin
+ *   loaded or a client listed tools.
+ *
+ * @module @try-works/dsh-tool-mode/server-lifecycle
+ */
+/** The documented grace period for cleanup (RUN-07). */
+export const DEFAULT_GRACE_MS = 5000;
+/**
+ * Manages one MCP listener's lifecycle.
+ *
+ * Deliberately separate from the DSH plugin's own lifecycle: RUN-01 requires disabling
+ * the SERVER to stop its listener and owned work without disabling unrelated DSH tools,
+ * so the two must be independently stoppable.
+ */
+export class ServerLifecycle {
+    #state = 'stopped';
+    #port = null;
+    #closeListener = null;
+    #work = new Map();
+    #host;
+    #graceMs;
+    /** Set once shutdown begins, so new work is refused from that moment. */
+    #acceptingWork = true;
+    constructor(host, options = {}) {
+        this.#host = host;
+        this.#graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
+    }
+    /** The current state. */
+    get state() {
+        return this.#state;
+    }
+    /** The bound port, once one exists. */
+    get port() {
+        return this.#port;
+    }
+    /**
+     * Whether the endpoint is serving (RUN-06).
+     *
+     * True only after BOTH bind and initialise succeeded. A caller asking "can I connect"
+     * gets one answer, and it is not derived from a flag somebody set early.
+     */
+    get ready() {
+        return this.#state === 'ready';
+    }
+    /** Work currently owned, for diagnostics. */
+    get owned() {
+        return [...this.#work.values()];
+    }
+    /**
+     * Start the listener.
+     *
+     * @returns nothing on success, or the failure — never a thrown exception, because
+     *   RUN-06 requires a failed start not to crash the unrelated host.
+     */
+    async start() {
+        if (this.#state === 'ready' || this.#state === 'starting') {
+            return {
+                ok: false,
+                failure: {
+                    code: 'ALREADY_STARTED',
+                    message: `the server is already ${this.#state}`,
+                    remedy: 'Call stop() before starting again.',
+                },
+            };
+        }
+        this.#state = 'starting';
+        try {
+            const listener = await this.#host.bind();
+            this.#port = listener.port;
+            this.#closeListener = listener.close;
+        }
+        catch (error) {
+            const code = error.code;
+            this.#state = 'failed';
+            if (code === 'EADDRINUSE') {
+                // Reported, NOT resolved. Taking the port from another process or silently
+                // moving to a different one both break a client told where to connect.
+                return {
+                    ok: false,
+                    failure: {
+                        code: 'PORT_IN_USE',
+                        message: `port ${String(error.message)} is already in use`,
+                        remedy: 'Choose a different port in the configuration, or stop the process holding it. This server will not take it by force or move silently.',
+                    },
+                };
+            }
+            return {
+                ok: false,
+                failure: {
+                    code: 'BIND_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                    remedy: 'Check that the bind address is a loopback address and that the port is permitted.',
+                },
+            };
+        }
+        try {
+            await this.#host.initialise();
+        }
+        catch (error) {
+            this.#state = 'failed';
+            // The listener bound but cannot serve, so it is CLOSED rather than left open:
+            // an open port that answers nothing is worse than no port.
+            await this.#closeListener?.().catch(() => undefined);
+            this.#closeListener = null;
+            this.#port = null;
+            return {
+                ok: false,
+                failure: {
+                    code: 'INIT_FAILED',
+                    message: error instanceof Error ? error.message : String(error),
+                    remedy: 'Check the server diagnostics; the host itself is unaffected.',
+                },
+            };
+        }
+        // Only now. Readiness after BOTH succeed, and never before.
+        this.#state = 'ready';
+        this.#host.onReady(this.#port);
+        return { ok: true, port: this.#port };
+    }
+    /**
+     * Register work this lifecycle owns (RUN-07).
+     *
+     * Refused once shutdown has begun, so a call racing a stop cannot slip into the
+     * cleanup window and be left running.
+     * @param work - the work to own.
+     * @returns whether it was accepted.
+     */
+    adopt(work) {
+        if (!this.#acceptingWork)
+            return false;
+        this.#work.set(work.id, work);
+        return true;
+    }
+    /** Release work that finished on its own. */
+    release(id) {
+        this.#work.delete(id);
+    }
+    /**
+     * Stop the listener and everything it owns (RUN-07).
+     *
+     * The order is the requirement's: refuse new work, cancel owned foreground
+     * invocations, wait within the grace period, terminate what remains, close the
+     * transport and release the port. Work belonging to another owner is LEFT ALONE.
+     * @param options - `ownedBy` selects the owner whose work may be stopped.
+     * @returns the report.
+     */
+    async stop(options = {}) {
+        // 1. Refuse new work FIRST, so nothing is adopted during cleanup.
+        this.#acceptingWork = false;
+        if (this.#state === 'stopped') {
+            return { cancelled: [], terminated: [], untouched: [], portReleased: true, withinGrace: true };
+        }
+        this.#state = 'stopping';
+        const mine = [];
+        const untouched = [];
+        for (const work of this.#work.values()) {
+            // RUN-07: never kill a model process serving another still-authorized owner.
+            if (options.ownedBy !== undefined && work.owner !== options.ownedBy) {
+                untouched.push(work.id);
+                continue;
+            }
+            mine.push(work);
+        }
+        // 2. Cancel owned foreground invocations, and wait for them WITHIN the grace
+        // period. Racing each cancel against one shared deadline is what makes the grace
+        // period mean something: a cancel that never resolves must not hold shutdown open
+        // forever, and it must not be reported as stopped either.
+        const deadline = Date.now() + this.#graceMs;
+        const cancelled = [];
+        const terminated = [];
+        const outcomes = await Promise.all(mine.map(async (work) => {
+            const remaining = Math.max(0, deadline - Date.now());
+            const settled = await Promise.race([
+                Promise.resolve(work.cancel()).then(() => true).catch(() => false),
+                new Promise(resolve => setTimeout(() => resolve(false), remaining)),
+            ]);
+            return { work, settled };
+        }));
+        for (const { work, settled } of outcomes) {
+            if (settled)
+                cancelled.push(work.id);
+        }
+        const withinGrace = outcomes.every(outcome => outcome.settled);
+        // 3. Terminate whatever outlived the grace period.
+        for (const { work, settled } of outcomes) {
+            if (settled)
+                continue;
+            try {
+                work.terminate?.();
+                terminated.push(work.id);
+            }
+            catch {
+                // A terminate that throws is logged rather than fatal: shutdown must complete
+                // even when one piece of work refuses to die.
+                this.#host.log(`work ${work.id} could not be terminated`);
+            }
+        }
+        this.#work.clear();
+        // 4. Close the transport and release the port.
+        let portReleased = false;
+        try {
+            await this.#closeListener?.();
+            portReleased = true;
+        }
+        catch {
+            this.#host.log('the listener could not be closed cleanly');
+        }
+        this.#closeListener = null;
+        this.#port = null;
+        this.#state = 'stopped';
+        this.#acceptingWork = true;
+        return { cancelled, terminated, untouched, portReleased, withinGrace };
+    }
+}
+/** The only startup policy this implementation permits (RUN-05). */
+export const READ_ONLY_STARTUP = {
+    preparesModels: false,
+    resolvesPackages: false,
+    discoveryIsReadOnly: true,
+};
+/**
+ * Whether a startup action is permitted (RUN-05).
+ *
+ * @param action - what the startup wants to do.
+ * @returns whether it may.
+ */
+export function startupPermits(action) {
+    switch (action) {
+        // Restoring an explicitly approved activation and inspecting local state are the
+        // two things startup MAY do.
+        case 'restore-active':
+        case 'inspect-assets':
+        case 'read-manifests':
+            return true;
+        // Preparation and resolution are refused, because RUN-05 is explicit that nothing
+        // downloads because a plugin loaded or a client listed tools.
+        case 'prepare-model':
+        case 'resolve-package':
+        case 'download-weights':
+            return false;
+    }
+}
+/**
+ * Whether disabling the MCP server must also disable unrelated DSH tools (RUN-01).
+ *
+ * It must not. The server and the plugin are independently stoppable, which is why the
+ * lifecycle is a separate object from the plugin's own registration state.
+ * @returns always false.
+ */
+export function disablingServerDisablesOtherTools() {
+    return false;
+}
+//# sourceMappingURL=server-lifecycle.js.map