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

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

package/lib/types.d.ts

@@ -65,6 +65,27 @@ export interface ModelCatalogEntry {
     readonly name: string;
     readonly summary: string;
     readonly capability: string;
+    /**
+     * The standard contract this model implements, or null when none exists yet.
+     *
+     * This is what makes tool identity independent of model identity (BASE-02): the
+     * contract decides the tool name a caller sees, so a second model implementing
+     * the same contract joins the existing tool instead of creating a duplicate. A
+     * model with no contract keeps a per-model tool under its own name.
+     */
+    readonly contract: string | null;
+    /**
+     * The extension package that implements this model (BASE-09).
+     *
+     * A binding held as DATA, not a switch on the model name. The host loads
+     * whatever package this names through the PUBLIC extension API, so a first-party
+     * package takes the same route as a third-party one and adding a vendor means
+     * publishing a package plus adding this field — with no host change.
+     */
+    readonly provider?: {
+        readonly extension: string;
+        readonly modelId: string;
+    };
     readonly input: ModelInput;
     readonly output: string;
     readonly languages: number | null;

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAA;AAEvF;;;;GAIG;AACH,MAAM,MAAM,cAAc;AACxB,8EAA8E;AAC5E,aAAa;AACf,6EAA6E;GAC3E,kBAAkB;AACpB,6EAA6E;GAC3E,YAAY;AACd,mEAAmE;GACjE,cAAc;AAChB,kDAAkD;GAChD,QAAQ,CAAA;AAEZ,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAA;CAC/B;AAED,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAEhD,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IACrD,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAA;IAC3C,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAC/B;AAED,kDAAkD;AAClD,MAAM,MAAM,UAAU;AACpB,6CAA6C;AAC3C,YAAY;AACd,iEAAiE;GAC/D,iBAAiB;AACnB,oEAAoE;GAClE,KAAK;AACP,+CAA+C;GAC7C,QAAQ;AACV,0CAA0C;GACxC,aAAa,CAAA;AAEjB,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@try-works/dsh-model-as-tool",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Install Desert Ant Labs on-device models as DSH tools and skills, with per-platform capability gating",
   "keywords": [
     "dsh",
@@ -48,7 +48,8 @@
     "catalog/desert-ant-models.json",
     "catalog/playbooks.json",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "bin"
   ],
   "dsh": {
     "bundle": {
@@ -81,5 +82,11 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "@try-works/tool-mode-contracts": "^0.1.0"
+  },
+  "bin": {
+    "dsh-tool-mode-mcp-stdio": "./bin/dsh-tool-mode-mcp-stdio.mjs"
   }
 }