@nodetool-ai/compute 0.8.1

package/dist/providers/types.js

@@ -0,0 +1,18 @@
+// Shared provider contract for the worker provisioning subsystem.
+//
+// A `WorkerProvider` is the per-target driver (RunPod pod, Vast.ai) that the
+// `WorkerManager` delegates to. It deals only in provider-native handles
+// (`providerRef`) and the attach handoff (`wsUrl` + optional `token`); all
+// persistence and identity (profiles, instances) live above it in the manager.
+/**
+ * Persistent-volume conventions shared by all providers. The volume survives a
+ * stop/resume (only a terminate deletes it), so HF model downloads cached under
+ * `WORKER_HF_HOME` persist across pauses — that's the whole point of feature.
+ */
+export const WORKER_VOLUME_MOUNT = "/workspace";
+export const WORKER_HF_HOME = `${WORKER_VOLUME_MOUNT}/huggingface`;
+/** Default persistent volume size — big enough for several HF image models. */
+export const DEFAULT_VOLUME_GB = 100;
+/** Default ephemeral container disk (image + temp); not persisted. */
+export const DEFAULT_CONTAINER_DISK_GB = 30;
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAqB/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;AAChD,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,mBAAmB,cAAc,CAAC;AACnE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AACrC,sEAAsE;AACtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC"}

package/dist/providers/vast.d.ts

@@ -0,0 +1,27 @@
+import { type ProviderInstance, type ProvisionResult, type WorkerProvider, type WorkerSpec, type WorkerStatus } from "./types.js";
+export declare class VastProvider implements WorkerProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    provision(spec: WorkerSpec): Promise<ProvisionResult>;
+    status(ref: string): Promise<WorkerStatus>;
+    /** Pause: stop the instance but keep its disk (and model cache). */
+    stop(ref: string): Promise<void>;
+    /** Resume a stopped instance and re-derive its (possibly new) endpoint. */
+    resume(ref: string): Promise<ProvisionResult>;
+    /** Destroy the instance and its disk — real teardown, stops all billing. */
+    terminate(ref: string): Promise<void>;
+    list(): Promise<ProviderInstance[]>;
+    /**
+     * Search the marketplace for the cheapest rentable offer matching the spec's
+     * GPU, GPU count and vCPU floor. Returns the offer id plus its `dph_total`
+     * (total dollars-per-hour), the estimated cost the cost guard records on the
+     * instance.
+     */
+    private findOffer;
+    /** Launch the worker image on the chosen offer; return the new contract id. */
+    private launch;
+    /** Poll GET /instances/{id}/ until `running`. */
+    private waitForReady;
+    private getInstance;
+}
+//# sourceMappingURL=vast.d.ts.map

package/dist/providers/vast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vast.d.ts","sourceRoot":"","sources":["../../src/providers/vast.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AA4EpB,qBAAa,YAAa,YAAW,cAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,MAAM,EAAI;IAEzC,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAiC1D;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAG/C;IAED,oEAAoE;IAC9D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIrC;IAED,2EAA2E;IACrE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBlD;IAED,4EAA4E;IACtE,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1C;IAEK,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAQxC;IAID;;;;;OAKG;YACW,SAAS;IAwCvB,+EAA+E;YACjE,MAAM;IA0CpB,iDAAiD;YACnC,YAAY;YAyBZ,WAAW;CAK1B"}

package/dist/providers/vast.js

@@ -0,0 +1,243 @@
+// Vast.ai-backed `WorkerProvider`.
+//
+// Launches the NodeTool worker image on a Vast.ai GPU offer over the Vast HTTP
+// API (https://console.vast.ai/api/v0), polls the instance to `running`, and
+// derives the direct `ws://<ip>:<port>` URL the bridge attaches to.
+//
+// Lifecycle mirrors RunPod: `stop` PAUSES the instance (state→stopped, its disk
+// and model cache are retained), `resume` brings it back (state→running), and
+// `terminate` DELETEs it for good — the real teardown that stops all billing.
+//
+// The API key is injected via the constructor (sourced from the secret store /
+// env by the `WorkerManager`); this provider never reads `process.env`.
+import { DEFAULT_VOLUME_GB, WORKER_HF_HOME, } from "./types.js";
+const VAST_API_BASE_URL = "https://console.vast.ai/api/v0";
+/** Internal port the worker serves on. */
+const WORKER_PORT = 7777;
+/** Internal sshd port, published only when the spec carries a public key. */
+const SSH_PORT = 22;
+/**
+ * Call the Vast HTTP API with an explicitly-supplied key. Mirrors the RunPod
+ * REST transport: explicit key (never `process.env`), bearer auth, JSON body.
+ */
+async function vastApi(apiKey, endpoint, method = "GET", data) {
+    if (!apiKey)
+        throw new Error("Vast.ai API key is required");
+    const init = {
+        method,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        signal: AbortSignal.timeout(60_000),
+    };
+    if (data && method !== "GET")
+        init.body = JSON.stringify(data);
+    const response = await fetch(`${VAST_API_BASE_URL}/${endpoint}`, init);
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Vast.ai ${method} /${endpoint} failed (${response.status}): ${body}`);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+}
+/** Map a Vast instance's `actual_status` to the shared `WorkerStatus`. */
+function mapInstanceStatus(status) {
+    switch (status) {
+        case "running":
+            return "running";
+        case "exited":
+        case "stopped":
+            return "stopped";
+        default:
+            return "provisioning";
+    }
+}
+/** Resolve the host port mapped to the worker's internal port, if exposed. */
+function externalPort(instance) {
+    const binding = instance.ports?.[`${WORKER_PORT}/tcp`];
+    return binding?.[0]?.HostPort ?? null;
+}
+export class VastProvider {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async provision(spec) {
+        const offer = await this.findOffer(spec);
+        const instanceId = await this.launch(offer.id, spec);
+        // `launch` created a billing instance. Any failure past this point must
+        // DESTROY it, otherwise the orphaned GPU bills until the reconcile scan
+        // detects it — its `provider_ref` is never persisted, so the manager can't
+        // tear it down.
+        try {
+            const instance = await this.waitForReady(instanceId);
+            const ip = instance.public_ipaddr;
+            const port = externalPort(instance);
+            if (!ip || !port) {
+                throw new Error(`Vast instance ${instanceId} became running without a reachable ` +
+                    `${WORKER_PORT} port mapping`);
+            }
+            return {
+                providerRef: instanceId,
+                wsUrl: `ws://${ip}:${port}`,
+                token: spec.token,
+                status: "running",
+                costUsd: offer.dphTotal,
+            };
+        }
+        catch (err) {
+            await this.terminate(instanceId).catch(() => {
+                // Best-effort teardown; surface the original provision failure below.
+            });
+            throw err;
+        }
+    }
+    async status(ref) {
+        const instance = await this.getInstance(ref);
+        return mapInstanceStatus(instance.actual_status);
+    }
+    /** Pause: stop the instance but keep its disk (and model cache). */
+    async stop(ref) {
+        await vastApi(this.apiKey, `instances/${ref}/`, "PUT", {
+            state: "stopped",
+        });
+    }
+    /** Resume a stopped instance and re-derive its (possibly new) endpoint. */
+    async resume(ref) {
+        await vastApi(this.apiKey, `instances/${ref}/`, "PUT", {
+            state: "running",
+        });
+        const instance = await this.waitForReady(ref);
+        const ip = instance.public_ipaddr;
+        const port = externalPort(instance);
+        if (!ip || !port) {
+            throw new Error(`Vast instance ${ref} resumed without a reachable ${WORKER_PORT} port`);
+        }
+        return {
+            providerRef: ref,
+            wsUrl: `ws://${ip}:${port}`,
+            status: "running",
+        };
+    }
+    /** Destroy the instance and its disk — real teardown, stops all billing. */
+    async terminate(ref) {
+        await vastApi(this.apiKey, `instances/${ref}/`, "DELETE");
+    }
+    async list() {
+        const res = await vastApi(this.apiKey, "instances/");
+        const arr = res.instances;
+        const instances = Array.isArray(arr) ? arr : [];
+        return instances.map((instance) => ({
+            providerRef: String(instance.id),
+            status: mapInstanceStatus(instance.actual_status),
+        }));
+    }
+    // --- Internals ----------------------------------------------------------
+    /**
+     * Search the marketplace for the cheapest rentable offer matching the spec's
+     * GPU, GPU count and vCPU floor. Returns the offer id plus its `dph_total`
+     * (total dollars-per-hour), the estimated cost the cost guard records on the
+     * instance.
+     */
+    async findOffer(spec) {
+        // Require the offer to have at least the disk we intend to allocate;
+        // otherwise the cheapest offer may not fit the requested disk and the
+        // subsequent launch is rejected.
+        const diskGb = spec.disk ?? DEFAULT_VOLUME_GB;
+        const query = {
+            rentable: { eq: true },
+            verified: { eq: true },
+            rented: { eq: false },
+            disk_space: { gte: diskGb },
+        };
+        if (spec.gpu) {
+            query.gpu_name = { eq: spec.gpu };
+        }
+        // A multi-GPU request must constrain the search: the cheapest offer is a
+        // single-GPU machine, so without this the launch silently under-delivers.
+        if (spec.gpuCount !== undefined) {
+            query.num_gpus = { gte: spec.gpuCount };
+        }
+        if (spec.vcpu !== undefined) {
+            query.cpu_cores_effective = { gte: spec.vcpu };
+        }
+        const res = await vastApi(this.apiKey, "bundles/", "PUT", {
+            q: query,
+            order: [["dph_total", "asc"]],
+        });
+        const offers = res.offers;
+        const first = Array.isArray(offers)
+            ? offers[0]
+            : undefined;
+        if (!first?.id) {
+            throw new Error(`No rentable Vast.ai offer found for GPU "${spec.gpu ?? "any"}"`);
+        }
+        return { id: String(first.id), dphTotal: first.dph_total };
+    }
+    /** Launch the worker image on the chosen offer; return the new contract id. */
+    async launch(offerId, spec) {
+        const env = { ...(spec.env ?? {}) };
+        if (spec.token)
+            env.NODETOOL_WORKER_TOKEN = spec.token;
+        // Cache HF models on the instance disk so they survive a stop/resume.
+        env.HF_HOME = WORKER_HF_HOME;
+        // Vast takes port mappings as Docker flags *inside* `env`, keyed by the
+        // flag with a dummy value — `args` goes to the image entrypoint instead and
+        // would never publish the port. Map the worker port out for the ws attach.
+        env[`-p ${WORKER_PORT}:${WORKER_PORT}`] = "1";
+        const sshKey = spec.sshPublicKey?.trim();
+        if (sshKey) {
+            // Same contract as RunPod: the key is an *image* convention — the worker
+            // entrypoint installs PUBLIC_KEY and starts sshd — so it carries over to
+            // Vast unchanged. Vast's account-level keys only apply to its own `ssh`
+            // runtypes, and we run the image's entrypoint (`args`).
+            env.PUBLIC_KEY = sshKey;
+            env[`-p ${SSH_PORT}:${SSH_PORT}`] = "1";
+        }
+        const res = await vastApi(this.apiKey, `asks/${offerId}/`, "PUT", {
+            image: spec.image,
+            // Names the instance in the Vast console, so a rented worker can be
+            // matched to its profile by hand during a reconcile.
+            label: spec.name,
+            disk: spec.disk ?? DEFAULT_VOLUME_GB,
+            env,
+            // Run the image's own entrypoint (the worker), not Vast's ssh/jupyter.
+            runtype: "args",
+        });
+        // The launch response is `{success, new_contract}` per the Vast HTTP API
+        // (https://console.vast.ai/api/v0). On failure it carries `error`/`message`
+        // instead, so include the whole body to keep the failure debuggable.
+        const contract = res.new_contract;
+        if (!contract) {
+            throw new Error(`Vast.ai launch returned no instance id: ${JSON.stringify(res)}`);
+        }
+        return String(contract);
+    }
+    /** Poll GET /instances/{id}/ until `running`. */
+    async waitForReady(id, opts = {}) {
+        const deadline = Date.now() + (opts.timeoutMs ?? 240_000);
+        const intervalMs = opts.intervalMs ?? 5_000;
+        let last;
+        while (Date.now() < deadline) {
+            const instance = await this.getInstance(id);
+            last = instance;
+            const status = mapInstanceStatus(instance.actual_status);
+            if (status === "running")
+                return instance;
+            if (status === "stopped") {
+                throw new Error(`Vast instance ${id} reached terminal status ${instance.actual_status}`);
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new Error(`Vast instance ${id} did not become reachable within the timeout ` +
+            `(last status: ${last?.actual_status ?? "unknown"})`);
+    }
+    async getInstance(id) {
+        const res = await vastApi(this.apiKey, `instances/${id}/`);
+        const instance = res.instances;
+        return (instance ?? {});
+    }
+}
+//# sourceMappingURL=vast.js.map

package/dist/providers/vast.js.map

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

package/dist/reaper.d.ts

@@ -0,0 +1,37 @@
+import type { WorkerInstance, WorkerProfile } from "@nodetool-ai/models";
+/**
+ * The slice of `WorkerManager` the reaper drives: it reads the registry and
+ * tears instances down through the manager (never the provider directly).
+ */
+export interface ReaperManager {
+    list(): Promise<WorkerInstance[]>;
+    /** Pause (idle path) — frees the GPU, keeps the volume. */
+    stop(instanceId: string): Promise<WorkerInstance>;
+    /** Destroy (hard-TTL path) — deletes the pod and its volume. */
+    terminate(instanceId: string): Promise<WorkerInstance>;
+}
+/**
+ * Reaper dependencies. `manager` reads/stops instances; `getProfile` resolves
+ * an instance's profile (for its limits); `now` returns the current epoch ms
+ * (injected so idle/TTL windows are deterministic in tests).
+ */
+export interface ReaperDeps {
+    manager: ReaperManager;
+    getProfile: (name: string) => Promise<WorkerProfile | null>;
+    now: () => number;
+}
+/** A handle that cancels a running `startReaper` timer. */
+export type ReaperHandle = () => void;
+/**
+ * Run one reaping pass: stop every non-stopped instance that is past its
+ * profile's idle window or hard TTL. Instances whose profile is missing or
+ * sets neither limit are left untouched.
+ */
+export declare function runReaperOnce(deps: ReaperDeps): Promise<void>;
+/**
+ * Schedule `runReaperOnce` on a fixed interval (used by the server). The timer
+ * itself is not unit-tested; the returned handle clears it. A pass that throws
+ * is swallowed so a transient provider/DB error doesn't kill the loop.
+ */
+export declare function startReaper(deps: ReaperDeps, intervalMs: number): ReaperHandle;
+//# sourceMappingURL=reaper.d.ts.map

package/dist/reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.d.ts","sourceRoot":"","sources":["../src/reaper.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAClC,2DAA2D;IAC3D,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAClD,gEAAgE;IAChE,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC5D,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC;AAItC;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBnE;AA+BD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAS9E"}

package/dist/reaper.js

@@ -0,0 +1,88 @@
+// Reaper — the cost guard's time-based teardown loop.
+//
+// GPU pods/Vast instances bill continuously, the laptop sleeps, the app
+// crashes. The reaper enforces two profile-declared limits so a forgotten
+// worker can't quietly bill for hours, with deliberately different actions:
+//
+//   - idle auto-stop: PAUSE an instance after `idle_timeout_minutes` of bridge
+//     inactivity (the bridge touches `last_activity_at`). Pausing frees the
+//     expensive GPU but keeps the volume, so resuming is fast and the model
+//     cache survives — the common, recoverable case.
+//   - hard TTL: TERMINATE an instance older than `max_lifetime_minutes`
+//     regardless of activity — an absolute kill switch that destroys the volume
+//     too, so a forgotten pod can't bill volume storage forever.
+//
+// Both go through the manager (`stop`/`terminate`), so the real provider work
+// and the status update happen as one. A profile that sets neither limit opts
+// its instances out. The clock and the manager are injected so the windows can
+// be exercised deterministically with a fake clock.
+//
+// Orphan reconcile (diffing the DB against `provider.list()`) is a separate
+// concern handled by `WorkerManager.reconcile()` in Task D4.
+const MINUTE_MS = 60_000;
+/**
+ * Run one reaping pass: stop every non-stopped instance that is past its
+ * profile's idle window or hard TTL. Instances whose profile is missing or
+ * sets neither limit are left untouched.
+ */
+export async function runReaperOnce(deps) {
+    const nowMs = deps.now();
+    const instances = await deps.manager.list();
+    for (const instance of instances) {
+        // Already-paused or already-destroyed instances are done.
+        if (instance.status === "stopped" || instance.status === "terminated") {
+            continue;
+        }
+        const profile = await deps.getProfile(instance.profile_name);
+        if (!profile) {
+            continue;
+        }
+        // Hard TTL wins over idle: if both fire, destroy (the stronger action)
+        // rather than merely pause.
+        const action = reapAction(instance, profile, nowMs);
+        if (action === "terminate") {
+            await deps.manager.terminate(instance.id);
+        }
+        else if (action === "stop") {
+            await deps.manager.stop(instance.id);
+        }
+    }
+}
+/**
+ * Which teardown (if any) an instance is due for: `terminate` past its hard TTL
+ * (destroy, incl. volume), `stop` past its idle window (pause, keep volume), or
+ * `null` when neither limit has fired.
+ */
+function reapAction(instance, profile, nowMs) {
+    const ttl = profile.max_lifetime_minutes;
+    if (ttl != null) {
+        const ageMs = nowMs - Date.parse(instance.created_at);
+        if (ageMs > ttl * MINUTE_MS) {
+            return "terminate";
+        }
+    }
+    const idle = profile.idle_timeout_minutes;
+    if (idle != null) {
+        const idleMs = nowMs - Date.parse(instance.last_activity_at);
+        if (idleMs > idle * MINUTE_MS) {
+            return "stop";
+        }
+    }
+    return null;
+}
+/**
+ * Schedule `runReaperOnce` on a fixed interval (used by the server). The timer
+ * itself is not unit-tested; the returned handle clears it. A pass that throws
+ * is swallowed so a transient provider/DB error doesn't kill the loop.
+ */
+export function startReaper(deps, intervalMs) {
+    const timer = setInterval(() => {
+        void runReaperOnce(deps).catch(() => { });
+    }, intervalMs);
+    // Don't keep the process alive solely for the reaper.
+    if (typeof timer.unref === "function") {
+        timer.unref();
+    }
+    return () => clearInterval(timer);
+}
+//# sourceMappingURL=reaper.js.map

package/dist/reaper.js.map

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

package/dist/worker-heartbeat.d.ts

@@ -0,0 +1,49 @@
+import { type WorkerInstance } from "@nodetool-ai/models";
+/**
+ * The slice of a Python bridge the heartbeat needs: the `"activity"` event the
+ * remote WebSocket bridge emits on every frame it sends or receives. A local
+ * stdio bridge never emits it, so attaching to one is inert.
+ */
+export interface WorkerActivitySource {
+    on(event: "activity", listener: () => void): void;
+    off?(event: "activity", listener: () => void): void;
+}
+/** Options for {@link attachWorkerActivityHeartbeat}. */
+export interface WorkerActivityHeartbeatOptions {
+    /**
+     * Resolve the instance whose clock this bridge's traffic belongs to.
+     * Returning null skips the touch (no worker attached).
+     */
+    resolveInstanceId: () => Promise<string | null>;
+    /** Write the timestamp. Injected for tests; defaults to the model accessor. */
+    touch?: (id: string) => Promise<WorkerInstance | void>;
+    /** Current epoch ms. Injected for tests. */
+    now?: () => number;
+    /** Throttle window in ms. Injected for tests. */
+    throttleMs?: number;
+}
+/**
+ * Keep a worker's `last_activity_at` fresh from real bridge traffic.
+ *
+ * Returns a function that detaches the listener. Every touch is best-effort:
+ * a rejected resolve or write is swallowed, because keeping a cost-guard clock
+ * fresh must never break the execution it is observing.
+ */
+export declare function attachWorkerActivityHeartbeat(bridge: WorkerActivitySource, options: WorkerActivityHeartbeatOptions): () => void;
+/**
+ * A host's hook for observing every Python bridge it creates —
+ * `onPythonBridgeCreated` from `@nodetool-ai/runtime`. Taken as a parameter so
+ * this package keeps no runtime dependency.
+ */
+export type BridgeCreationRegistrar = (observer: (bridge: WorkerActivitySource) => void) => () => void;
+/**
+ * Install the heartbeat on every bridge the host creates from now on, resolving
+ * the attached worker through a lazily-built {@link WorkerManager}. Returns a
+ * function that uninstalls it.
+ *
+ * This is what a host without its own long-lived bridge — the CLI — calls once
+ * at startup. It opens no database and builds no bridge; the manager appears
+ * only when a bridge first reports traffic.
+ */
+export declare function installWorkerActivityHeartbeat(register: BridgeCreationRegistrar, overrides?: Partial<WorkerActivityHeartbeatOptions>): () => void;
+//# sourceMappingURL=worker-heartbeat.d.ts.map

package/dist/worker-heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-heartbeat.d.ts","sourceRoot":"","sources":["../src/worker-heartbeat.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAI7B;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAClD,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACrD;AASD,yDAAyD;AACzD,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAChD,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,8BAA8B,GACtC,MAAM,IAAI,CAqBZ;AAED;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,KAC7C,MAAM,IAAI,CAAC;AAEhB;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,uBAAuB,EACjC,SAAS,GAAE,OAAO,CAAC,8BAA8B,CAAM,GACtD,MAAM,IAAI,CASZ"}

package/dist/worker-heartbeat.js

@@ -0,0 +1,68 @@
+// Worker idle-clock heartbeat.
+//
+// The reaper pauses an instance after `idle_timeout_minutes` of inactivity,
+// measured from `last_activity_at`. That column only moves when something
+// touches it, and the only thing that can is a host with database access that
+// is watching the Python bridge. This module is that wiring, kept out of any
+// single host so every DB-having host — the websocket server, the CLI —
+// installs the same behaviour instead of each reimplementing it.
+//
+// The bridge is taken structurally (an event emitter with an `"activity"`
+// event) so `@nodetool-ai/compute` stays free of a `@nodetool-ai/runtime`
+// dependency, the same way `WorkerManager` does.
+import { touchWorkerInstance, } from "@nodetool-ai/models";
+import { WorkerManager } from "./manager.js";
+/**
+ * How often a burst of bridge traffic is allowed to become a DB write. The
+ * reaper runs once a minute and its windows are measured in minutes, so
+ * second-level freshness is ample and one write per frame is waste.
+ */
+const TOUCH_THROTTLE_MS = 10_000;
+/**
+ * Keep a worker's `last_activity_at` fresh from real bridge traffic.
+ *
+ * Returns a function that detaches the listener. Every touch is best-effort:
+ * a rejected resolve or write is swallowed, because keeping a cost-guard clock
+ * fresh must never break the execution it is observing.
+ */
+export function attachWorkerActivityHeartbeat(bridge, options) {
+    const now = options.now ?? Date.now;
+    const touch = options.touch ?? touchWorkerInstance;
+    const throttleMs = options.throttleMs ?? TOUCH_THROTTLE_MS;
+    // -Infinity, not 0: the first beat must fire whatever the clock reads.
+    let lastTouchAt = Number.NEGATIVE_INFINITY;
+    const listener = () => {
+        const nowMs = now();
+        if (nowMs - lastTouchAt < throttleMs)
+            return;
+        lastTouchAt = nowMs;
+        void options
+            .resolveInstanceId()
+            .then((id) => (id ? touch(id) : undefined))
+            .catch(() => {
+            // best-effort: the idle clock must not crash the run it measures
+        });
+    };
+    bridge.on("activity", listener);
+    return () => bridge.off?.("activity", listener);
+}
+/**
+ * Install the heartbeat on every bridge the host creates from now on, resolving
+ * the attached worker through a lazily-built {@link WorkerManager}. Returns a
+ * function that uninstalls it.
+ *
+ * This is what a host without its own long-lived bridge — the CLI — calls once
+ * at startup. It opens no database and builds no bridge; the manager appears
+ * only when a bridge first reports traffic.
+ */
+export function installWorkerActivityHeartbeat(register, overrides = {}) {
+    let manager = null;
+    const resolveInstanceId = async () => {
+        manager ??= new WorkerManager();
+        return (await manager.getActiveWorker())?.id ?? null;
+    };
+    return register((bridge) => {
+        attachWorkerActivityHeartbeat(bridge, { resolveInstanceId, ...overrides });
+    });
+}
+//# sourceMappingURL=worker-heartbeat.js.map

package/dist/worker-heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-heartbeat.js","sourceRoot":"","sources":["../src/worker-heartbeat.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,wEAAwE;AACxE,iEAAiE;AACjE,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,iDAAiD;AAEjD,OAAO,EACL,mBAAmB,GAEpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAY7C;;;;GAIG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAiBjC;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAA4B,EAC5B,OAAuC;IAEvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,mBAAmB,CAAC;IACnD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAE3D,uEAAuE;IACvE,IAAI,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC3C,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;QACpB,IAAI,KAAK,GAAG,WAAW,GAAG,UAAU;YAAE,OAAO;QAC7C,WAAW,GAAG,KAAK,CAAC;QACpB,KAAK,OAAO;aACT,iBAAiB,EAAE;aACnB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;aAC1C,KAAK,CAAC,GAAG,EAAE;YACV,iEAAiE;QACnE,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IAEF,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAChC,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AAClD,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAC5C,QAAiC,EACjC,SAAS,GAA4C,EAAE;IAEvD,IAAI,OAAO,GAAyB,IAAI,CAAC;IACzC,MAAM,iBAAiB,GAAG,KAAK,IAA4B,EAAE;QAC3D,OAAO,KAAK,IAAI,aAAa,EAAE,CAAC;QAChC,OAAO,CAAC,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC;IACvD,CAAC,CAAC;IACF,OAAO,QAAQ,CAAC,CAAC,MAAM,EAAE,EAAE;QACzB,6BAA6B,CAAC,MAAM,EAAE,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nodetool-ai/compute",
+  "version": "0.8.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/build-typescript-workspace.mjs",
+    "test": "node ../../scripts/run-vitest.mjs run",
+    "test:watch": "node ../../scripts/run-vitest.mjs",
+    "lint": "node ../../scripts/run-tsc.mjs --noEmit"
+  },
+  "dependencies": {
+    "@nodetool-ai/config": "^0.8.1",
+    "@nodetool-ai/models": "^0.8.1",
+    "@nodetool-ai/security": "^0.8.1"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vitest": "^5.0.1"
+  },
+  "exports": {
+    ".": {
+      "nodetool-dev": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nodetool-ai/nodetool.git",
+    "directory": "packages/compute"
+  },
+  "homepage": "https://nodetool.ai",
+  "bugs": {
+    "url": "https://github.com/nodetool-ai/nodetool/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "description": "Remote compute orchestration for NodeTool — provisions and reaps GPU workers on RunPod and Vast.ai",
+  "keywords": [
+    "nodetool",
+    "ai",
+    "workflow",
+    "workflow-automation",
+    "typescript",
+    "gpu",
+    "runpod",
+    "vast-ai",
+    "compute",
+    "gpu-workers",
+    "orchestration"
+  ]
+}