@try-works/dsh-model-as-tool 0.1.1 → 0.1.3

package/lib/resource-governance.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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-model-as-tool/resource-governance
+ */
+/**
+ * The eight readiness/residency states (RES-04).
+ *
+ * Named `Readiness` rather than `Residency` because it holds both dimensions; the
+ * two derived functions below are what separate them.
+ */
+export type Readiness = 
+/** No compatible implementation exists on this host. */
+'unavailable'
+/** Compatible, but its assets have not been prepared. */
+ | 'needs-preparation'
+/** Preparation is under way. */
+ | 'preparing'
+/** Prepared and not loaded: a call will load first. */
+ | 'prepared-cold'
+/** Currently loading. */
+ | 'loading'
+/** Loaded and idle. */
+ | 'ready'
+/** Loaded and serving; further calls queue. */
+ | 'busy'
+/** Preparation or loading failed. */
+ | 'failed';
+/**
+ * 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 declare function isCallable(state: Readiness): boolean;
+/**
+ * Whether assets are prepared (RES-04).
+ * @param state - the current state.
+ * @returns whether preparation has completed.
+ */
+export declare function isPrepared(state: Readiness): boolean;
+/** How a call is admitted in a given state (RES-04). */
+export type Admission = 
+/** Runs now. */
+'immediate'
+/** Will load first, so it takes longer. */
+ | 'loads-first'
+/** Waits for the current call to finish. */
+ | 'queued';
+/**
+ * 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 declare function admissionOf(state: Readiness): Admission | 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 declare function descriptionMayVaryWithResidency(): boolean;
+/** A budgeted resource (RES-09). */
+export type BudgetKind = 'sourceBytes' | 'decodedPixels' | 'audioSamples' | 'videoSeconds' | 'videoFrames' | 'processorTokens' | 'batch' | 'outputVectors';
+/** Limits for one input class. `null` means the constraint does not apply. */
+export type Budget = Partial<Record<BudgetKind, number | null>>;
+/**
+ * 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 declare const DEFAULT_BUDGETS: Readonly<Record<'image' | 'video' | 'audio' | 'text', Budget>>;
+/** A measured input. */
+export type Measurement = Partial<Record<BudgetKind, number>>;
+/** The outcome of admitting an input. */
+export type AdmissionDecision = {
+    readonly admitted: true;
+} | {
+    readonly admitted: false;
+    /** Every exceeded budget, with the actual limit. */
+    readonly exceeded: readonly {
+        readonly kind: BudgetKind;
+        readonly measured: number;
+        readonly limit: number;
+    }[];
+};
+/**
+ * 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 declare function admit(measurement: Measurement, budget: Budget): AdmissionDecision;
+/**
+ * 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 declare function describeRejection(decision: Extract<AdmissionDecision, {
+    admitted: false;
+}>): string;
+/** An explicit sampling instruction (RES-09). */
+export interface SamplingPlan {
+    /** What was sampled, in the caller's terms. */
+    readonly instruction: string;
+    /** The budget that forced sampling, when one did. */
+    readonly forcedBy: BudgetKind | null;
+}
+/** What was actually processed, returned so coverage is never implied. */
+export interface Coverage {
+    /** Whether every unit of the source was processed. */
+    readonly complete: boolean;
+    /** Units processed. */
+    readonly processed: number;
+    /** Units in the source. */
+    readonly total: number;
+    /** The sampling that was applied, when any was. */
+    readonly sampling: SamplingPlan | null;
+    /** Why coverage is incomplete. */
+    readonly reason: string | null;
+}
+/**
+ * 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 declare function coverageOf(processed: number, total: number, sampling: SamplingPlan | null): Coverage;
+/** How a cancellation actually ended (RES-06). */
+export type CancellationOutcome = 
+/** The work stopped and released its resources. */
+{
+    readonly stopped: true;
+}
+/**
+ * The work could not be interrupted. It continues to completion, and its result
+ * is discarded rather than delivered.
+ */
+ | {
+    readonly stopped: false;
+    readonly reason: string;
+};
+/**
+ * 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 declare function cancellationOutcome(interruptible: boolean, subject: string): CancellationOutcome;
+/**
+ * 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 declare function isExpansionBomb(declaredBytes: number, limit: number): boolean;
+//# sourceMappingURL=resource-governance.d.ts.map

package/lib/resource-governance.d.ts.map

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

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-model-as-tool/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-model-as-tool/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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"}