@moldesk/runtime 0.0.4 → 0.0.6

package/dist/cloud/credentials.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Cloud API credentials. The OS credential store is the default. An explicit provider environment
+ * variable (e.g. RUNPOD_API_KEY) is accepted as a documented development override and takes
+ * precedence when set. Files such as `.env` are never read automatically, and there is no
+ * plaintext-file fallback: if neither source holds a key, the caller is told to connect one.
+ * Secrets are never written to run records, the cloud journal, error messages or command arguments.
+ */
+export declare const KEYRING_SERVICE = "moldesk";
+export declare const DEFAULT_ACCOUNT_REF = "default";
+/** Environment variable that carries each provider's key. */
+export declare const PROVIDER_ENV_VARS: Readonly<Record<string, string>>;
+export interface SecretBackend {
+    get(service: string, account: string): Promise<string | null>;
+    set(service: string, account: string, secret: string): Promise<void>;
+    /** Returns whether an entry existed. */
+    delete(service: string, account: string): Promise<boolean>;
+}
+/** OS keychain via a maintained N-API binding; loaded lazily so unsupported platforms only lose this feature. */
+export declare function createKeyringBackend(): SecretBackend;
+/** A key must be a single printable token; anything else is almost certainly a paste mistake. */
+export declare function validateSecretShape(secret: string): void;
+export type CredentialSource = "env" | "keyring";
+export interface ResolvedCredential {
+    /** The secret itself. Hand it to a client; never log or persist it. */
+    key: string;
+    source: CredentialSource;
+}
+export interface CredentialStoreOptions {
+    backend?: SecretBackend;
+    /** Development override source. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class CredentialStore {
+    private readonly backend;
+    private readonly env;
+    constructor(options?: CredentialStoreOptions);
+    private envVar;
+    private account;
+    /** Explicit environment override first, then the OS store. Returns null when nothing is configured. */
+    resolve(provider: string, accountRef?: string): Promise<ResolvedCredential | null>;
+    /** Like `resolve` but throws an actionable error when no credential exists. */
+    require(provider: string, accountRef?: string): Promise<ResolvedCredential>;
+    /** Where the key would come from, without returning it. */
+    status(provider: string, accountRef?: string): Promise<{
+        source: CredentialSource | "none";
+    }>;
+    /** Shape-check a candidate key for a supported provider without storing it. */
+    validate(provider: string, key: string): Promise<void>;
+    set(provider: string, key: string, accountRef?: string): Promise<void>;
+    /** Removes the stored key. An environment variable is the user's own and is never touched. */
+    delete(provider: string, accountRef?: string): Promise<boolean>;
+    private checked;
+}
+/**
+ * Stable, non-reversible identifier for a credential, used only as a conservative account scope
+ * when the provider exposes no account identity. Keyed so the stored value cannot be matched
+ * against a guessed key without the per-installation salt.
+ */
+export declare function credentialFingerprint(key: string, installationSalt: string): string;
+/** Replaces every occurrence of each secret (and its URL-encoded form) with a fixed marker. */
+export declare function redactSecrets(text: string, secrets: readonly string[]): string;

package/dist/cloud/credentials.js

@@ -0,0 +1,161 @@
+import { createHmac } from "node:crypto";
+import { createRequire } from "node:module";
+import { MoldeskError } from "../providers.js";
+/**
+ * Cloud API credentials. The OS credential store is the default. An explicit provider environment
+ * variable (e.g. RUNPOD_API_KEY) is accepted as a documented development override and takes
+ * precedence when set. Files such as `.env` are never read automatically, and there is no
+ * plaintext-file fallback: if neither source holds a key, the caller is told to connect one.
+ * Secrets are never written to run records, the cloud journal, error messages or command arguments.
+ */
+export const KEYRING_SERVICE = "moldesk";
+export const DEFAULT_ACCOUNT_REF = "default";
+/** Environment variable that carries each provider's key. */
+export const PROVIDER_ENV_VARS = { runpod: "RUNPOD_API_KEY" };
+const SECRET_MIN_LENGTH = 8;
+const SECRET_MAX_LENGTH = 512;
+function storeUnavailable(action, cause) {
+    return new MoldeskError({
+        code: "CREDENTIAL_STORE_UNAVAILABLE",
+        message: `The operating system credential store is unavailable (${action}).`,
+        remediation: "Unlock your keychain/secret service, or provide the key through the provider environment variable for this session.",
+        cause,
+    });
+}
+/** OS keychain via a maintained N-API binding; loaded lazily so unsupported platforms only lose this feature. */
+export function createKeyringBackend() {
+    let ctor;
+    const entry = (service, account, action) => {
+        try {
+            ctor ??= createRequire(import.meta.url)("@napi-rs/keyring").Entry;
+            return new ctor(service, account);
+        }
+        catch (error) {
+            throw storeUnavailable(action, error);
+        }
+    };
+    return {
+        async get(service, account) {
+            const target = entry(service, account, "read");
+            try {
+                return target.getPassword() ?? null;
+            }
+            catch (error) {
+                throw storeUnavailable("read", error);
+            }
+        },
+        async set(service, account, secret) {
+            const target = entry(service, account, "write");
+            try {
+                target.setPassword(secret);
+            }
+            catch (error) {
+                throw storeUnavailable("write", error);
+            }
+        },
+        async delete(service, account) {
+            const target = entry(service, account, "delete");
+            try {
+                return target.deletePassword();
+            }
+            catch (error) {
+                throw storeUnavailable("delete", error);
+            }
+        },
+    };
+}
+/** A key must be a single printable token; anything else is almost certainly a paste mistake. */
+export function validateSecretShape(secret) {
+    const trimmed = secret.trim();
+    if (trimmed !== secret || secret.length < SECRET_MIN_LENGTH || secret.length > SECRET_MAX_LENGTH || /[\s\u0000-\u001f\u007f]/.test(secret)) {
+        throw new MoldeskError({
+            code: "CREDENTIAL_INVALID",
+            message: "The API key is malformed (empty, too short/long, or contains whitespace or control characters).",
+            remediation: "Copy the key again from the provider console without surrounding spaces or newlines.",
+        });
+    }
+}
+export class CredentialStore {
+    backend;
+    env;
+    constructor(options = {}) {
+        this.backend = options.backend ?? createKeyringBackend();
+        this.env = options.env ?? process.env;
+    }
+    envVar(provider) {
+        const name = PROVIDER_ENV_VARS[provider];
+        if (!name)
+            throw new MoldeskError({ code: "CREDENTIAL_UNSUPPORTED_PROVIDER", message: `Unknown cloud provider "${provider}".`, remediation: "Use a supported provider, e.g. runpod." });
+        return name;
+    }
+    account(provider, accountRef) {
+        if (!/^[A-Za-z0-9._-]{1,64}$/.test(accountRef)) {
+            throw new MoldeskError({ code: "CREDENTIAL_INVALID", message: `Unsafe account reference ${JSON.stringify(accountRef)}.`, remediation: "Use letters, digits, '.', '_' or '-'." });
+        }
+        return `${provider}:${accountRef}`;
+    }
+    /** Explicit environment override first, then the OS store. Returns null when nothing is configured. */
+    async resolve(provider, accountRef = DEFAULT_ACCOUNT_REF) {
+        const name = this.envVar(provider);
+        const fromEnv = this.env[name];
+        if (fromEnv)
+            return this.checked({ key: fromEnv, source: "env" });
+        const stored = await this.backend.get(KEYRING_SERVICE, this.account(provider, accountRef));
+        return stored ? this.checked({ key: stored, source: "keyring" }) : null;
+    }
+    /** Like `resolve` but throws an actionable error when no credential exists. */
+    async require(provider, accountRef = DEFAULT_ACCOUNT_REF) {
+        const resolved = await this.resolve(provider, accountRef);
+        if (!resolved) {
+            throw new MoldeskError({
+                code: "CREDENTIAL_MISSING",
+                message: `No ${provider} API key is configured.`,
+                remediation: `Run \`moldesk cloud connect ${provider}\`, or set ${this.envVar(provider)} in the environment (development override).`,
+            });
+        }
+        return resolved;
+    }
+    /** Where the key would come from, without returning it. */
+    async status(provider, accountRef = DEFAULT_ACCOUNT_REF) {
+        const resolved = await this.resolve(provider, accountRef);
+        return { source: resolved?.source ?? "none" };
+    }
+    /** Shape-check a candidate key for a supported provider without storing it. */
+    async validate(provider, key) {
+        this.envVar(provider);
+        validateSecretShape(key);
+    }
+    async set(provider, key, accountRef = DEFAULT_ACCOUNT_REF) {
+        this.envVar(provider);
+        validateSecretShape(key);
+        await this.backend.set(KEYRING_SERVICE, this.account(provider, accountRef), key);
+    }
+    /** Removes the stored key. An environment variable is the user's own and is never touched. */
+    async delete(provider, accountRef = DEFAULT_ACCOUNT_REF) {
+        this.envVar(provider);
+        return this.backend.delete(KEYRING_SERVICE, this.account(provider, accountRef));
+    }
+    checked(credential) {
+        validateSecretShape(credential.key);
+        return credential;
+    }
+}
+/**
+ * Stable, non-reversible identifier for a credential, used only as a conservative account scope
+ * when the provider exposes no account identity. Keyed so the stored value cannot be matched
+ * against a guessed key without the per-installation salt.
+ */
+export function credentialFingerprint(key, installationSalt) {
+    return createHmac("sha256", installationSalt).update(key).digest("hex").slice(0, 32);
+}
+/** Replaces every occurrence of each secret (and its URL-encoded form) with a fixed marker. */
+export function redactSecrets(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        if (secret.length < SECRET_MIN_LENGTH)
+            continue;
+        for (const variant of new Set([secret, encodeURIComponent(secret)]))
+            out = out.split(variant).join("[REDACTED]");
+    }
+    return out;
+}

package/dist/cloud/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cloud/credentials.test.js

@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { CredentialStore, KEYRING_SERVICE, credentialFingerprint, redactSecrets, validateSecretShape, } from "./credentials.js";
+const KEY = "rpa_TESTKEY0123456789";
+const dirs = [];
+function emptyDir() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk cred "));
+    dirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+function memoryBackend(initial = {}) {
+    const data = new Map(Object.entries(initial));
+    return {
+        data,
+        async get(service, account) {
+            return data.get(`${service}/${account}`) ?? null;
+        },
+        async set(service, account, secret) {
+            data.set(`${service}/${account}`, secret);
+        },
+        async delete(service, account) {
+            return data.delete(`${service}/${account}`);
+        },
+    };
+}
+describe("CredentialStore", () => {
+    it("stores in the OS backend under a namespaced account and resolves it", async () => {
+        const backend = memoryBackend();
+        const store = new CredentialStore({ backend, env: {} });
+        await store.set("runpod", KEY);
+        expect([...backend.data.keys()]).toEqual([`${KEYRING_SERVICE}/runpod:default`]);
+        expect(await store.resolve("runpod")).toEqual({ key: KEY, source: "keyring" });
+        expect(await store.status("runpod")).toEqual({ source: "keyring" });
+    });
+    it("prefers an explicit environment override, then the keyring", async () => {
+        const backend = memoryBackend({ [`${KEYRING_SERVICE}/runpod:default`]: `${KEY}-keyring` });
+        const withEnv = new CredentialStore({ backend, env: { RUNPOD_API_KEY: `${KEY}-env` } });
+        expect(await withEnv.resolve("runpod")).toEqual({ key: `${KEY}-env`, source: "env" });
+        const keyringOnly = new CredentialStore({ backend, env: {} });
+        expect(await keyringOnly.resolve("runpod")).toEqual({ key: `${KEY}-keyring`, source: "keyring" });
+    });
+    it("never reads a .env file from the working directory or anywhere else", async () => {
+        const dir = emptyDir();
+        fs.writeFileSync(path.join(dir, ".env"), `RUNPOD_API_KEY=${KEY}-dotenv\n`);
+        const original = process.cwd();
+        process.chdir(dir);
+        try {
+            const store = new CredentialStore({ backend: memoryBackend(), env: {} });
+            expect(await store.resolve("runpod")).toBeNull();
+            expect(await store.status("runpod")).toEqual({ source: "none" });
+        }
+        finally {
+            process.chdir(original);
+        }
+    });
+    it("has no plaintext fallback: with nothing configured it reports none and require() is actionable", async () => {
+        const store = new CredentialStore({ backend: memoryBackend(), env: {} });
+        expect(await store.resolve("runpod")).toBeNull();
+        expect(await store.status("runpod")).toEqual({ source: "none" });
+        await expect(store.require("runpod")).rejects.toMatchObject({ code: "CREDENTIAL_MISSING" });
+    });
+    it("deletes only the stored key, never the environment override", async () => {
+        const backend = memoryBackend();
+        const store = new CredentialStore({ backend, env: { RUNPOD_API_KEY: KEY } });
+        await store.set("runpod", `${KEY}-stored`);
+        expect(await store.delete("runpod")).toBe(true);
+        expect(await store.delete("runpod")).toBe(false);
+        expect(await store.resolve("runpod")).toMatchObject({ source: "env", key: KEY });
+    });
+    it("separates accounts and rejects unsafe references and unknown providers", async () => {
+        const backend = memoryBackend();
+        const store = new CredentialStore({ backend, env: {} });
+        await store.set("runpod", `${KEY}-a`, "work");
+        await store.set("runpod", `${KEY}-b`, "home");
+        expect((await store.resolve("runpod", "work"))?.key).toBe(`${KEY}-a`);
+        expect((await store.resolve("runpod", "home"))?.key).toBe(`${KEY}-b`);
+        await expect(store.set("runpod", KEY, "../escape")).rejects.toMatchObject({ code: "CREDENTIAL_INVALID" });
+        await expect(store.resolve("nope")).rejects.toMatchObject({ code: "CREDENTIAL_UNSUPPORTED_PROVIDER" });
+    });
+    it("rejects malformed keys on write and when found in the environment", async () => {
+        const store = new CredentialStore({ backend: memoryBackend(), env: { RUNPOD_API_KEY: "has space in it" } });
+        await expect(store.set("runpod", "short")).rejects.toMatchObject({ code: "CREDENTIAL_INVALID" });
+        await expect(store.set("runpod", `${KEY}\n`)).rejects.toMatchObject({ code: "CREDENTIAL_INVALID" });
+        await expect(store.resolve("runpod")).rejects.toMatchObject({ code: "CREDENTIAL_INVALID" });
+    });
+    it("surfaces a backend failure as CREDENTIAL_STORE_UNAVAILABLE without falling back", async () => {
+        const failing = {
+            async get() {
+                throw Object.assign(new Error("locked"), { code: "CREDENTIAL_STORE_UNAVAILABLE" });
+            },
+            async set() { },
+            async delete() {
+                return false;
+            },
+        };
+        const store = new CredentialStore({ backend: failing, env: {} });
+        await expect(store.resolve("runpod")).rejects.toMatchObject({ code: "CREDENTIAL_STORE_UNAVAILABLE" });
+    });
+});
+describe("helpers", () => {
+    it("validates secret shape", () => {
+        expect(() => validateSecretShape(KEY)).not.toThrow();
+        expect(() => validateSecretShape("")).toThrow();
+        expect(() => validateSecretShape("a b c d e f g h")).toThrow();
+    });
+    it("fingerprints deterministically per salt without exposing the key", () => {
+        const one = credentialFingerprint(KEY, "salt-1");
+        expect(one).toBe(credentialFingerprint(KEY, "salt-1"));
+        expect(one).not.toBe(credentialFingerprint(KEY, "salt-2"));
+        expect(one).not.toContain(KEY);
+        expect(one).toMatch(/^[0-9a-f]{32}$/);
+    });
+    it("redacts secrets and their URL-encoded form, ignoring tiny strings", () => {
+        const text = `token ${KEY} and ${encodeURIComponent("a/b+c=d-secret")} ok`;
+        expect(redactSecrets(text, [KEY, "a/b+c=d-secret"])).toBe("token [REDACTED] and [REDACTED] ok");
+        expect(redactSecrets("abc abc", ["abc"])).toBe("abc abc");
+    });
+});

package/dist/cloud/execution.d.ts

@@ -0,0 +1,197 @@
+import type { CloudResourceRoleName } from "./types.js";
+/**
+ * Wire and journal contract between the core orchestrator and a remote execution backend. All
+ * types are plain JSON and versioned, so a restarted client can reconstruct a job from the journal
+ * and a worker of a different release can reject what it does not understand.
+ */
+export declare const EXECUTION_CONTRACT_VERSION = 1;
+export type CachePolicy = "ephemeral" | "persistent";
+export interface JobInputFile {
+    /** `"job"` for the primary input, or the adapter-declared companion id. */
+    role: string;
+    /** Path relative to the job's `input/` directory; never absolute and never containing `..`. */
+    relativePath: string;
+    sha256: string;
+    sizeBytes: number;
+    /** Client-local source. Never sent to the worker or written to the journal. */
+    sourcePath: string;
+}
+export interface ApprovedJob {
+    version: typeof EXECUTION_CONTRACT_VERSION;
+    runId: string;
+    model: string;
+    modelVersion: string;
+    manifestDigest: string;
+    cachePolicy: CachePolicy;
+    gpuId: string;
+    datacenterId: string;
+    /** Digest-pinned worker images from the manifest's `cloud` block. */
+    images: {
+        gpu: string;
+        cpu: string;
+    };
+    containerDiskGb: number;
+    volumeGb: number;
+    assetLayoutRevision: string;
+    cpuAssetPreparation: boolean;
+    /** Validated, defaulted adapter params. */
+    params: Record<string, unknown>;
+    inputs: JobInputFile[];
+    /** After this instant every resource of the job must be gone. */
+    deadlineAt: string;
+    /** Digest of model, source revision, asset list and layout revision; names the on-volume cache. */
+    cacheKey: string;
+    /** Existing persistent volume to reuse, when one is known and compatible. */
+    reuseVolumeId?: string;
+}
+/** What a backend returns once the worker is executing; JSON-serializable. */
+export interface JobHandle {
+    version: typeof EXECUTION_CONTRACT_VERSION;
+    runId: string;
+    podId: string;
+    volumeId?: string;
+    /** Verified HTTPS worker endpoint. The per-job token is held in the credential store, not here. */
+    endpoint: string;
+}
+export type JobStage = "provisioning" | "booting" | "uploading" | "preparing_assets" | "installing_runtime" | "verifying_runtime" | "running" | "collecting";
+export type JobState = "pending" | "running" | "succeeded" | "failed" | "cancelled";
+export interface RemoteRuntimeReport {
+    pythonVersion?: string;
+    /** `uv pip freeze` output lines. */
+    dependencyFreeze: string[];
+    sourceRevision?: string;
+    gpu?: {
+        name: string;
+        memoryMb?: number;
+        driverVersion?: string;
+        cudaVersion?: string;
+    };
+    /** The command the worker ran; `cwd` is a POSIX path on the worker. */
+    command?: {
+        executable: string;
+        args: string[];
+        cwd: string;
+    };
+    installationFingerprint?: string;
+    /** Persistent-cache details reported by `prepare-assets` jobs. */
+    cache?: {
+        checksumManifestSha256: string;
+        sizeBytes: number;
+        fileCount: number;
+        reused: boolean;
+    };
+}
+export interface JobSnapshot {
+    stage: JobStage;
+    state: JobState;
+    exitCode?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+    /**
+     * Resumable log window: pass `cursor` back as `after` to continue. The worker keeps only a bounded
+     * tail, so `lostEntries` counts chunks after `after` that were evicted before they could be fetched
+     * (exact: chunks are numbered contiguously). `evictedBytes` is the worker's cumulative evicted size.
+     */
+    logs: {
+        cursor: number;
+        stdout: string;
+        stderr: string;
+        lostEntries?: number;
+        evictedBytes?: number;
+    };
+    runtime?: RemoteRuntimeReport;
+}
+export interface InventoryFile {
+    /** POSIX path relative to the job's `output/` directory. */
+    path: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export interface ArtifactInventory {
+    version: typeof EXECUTION_CONTRACT_VERSION;
+    files: InventoryFile[];
+}
+/**
+ * Journals paid-resource intent for a backend. The backend must call `beginCreate` before asking a
+ * provider to create anything, `created` immediately after the response, `beginDelete` before a
+ * delete and `deleted` only once the provider confirmed deletion or absence.
+ */
+export interface ResourceLedger {
+    beginCreate(role: CloudResourceRoleName): {
+        intentId: string;
+        name: string;
+    };
+    created(intentId: string, providerId: string): void;
+    beginDelete(intentId: string): void;
+    deleted(intentId: string): void;
+}
+/** Journals persistent-cache state for a backend. Only used for the `persistent` policy. */
+export interface CacheLedger {
+    /** A cache the journal believes is READY for this job's key, if any. */
+    lookup(): {
+        volumeId: string;
+        datacenterId: string;
+    } | undefined;
+    /** Record the volume and a PREPARING cache row. */
+    begin(volume: {
+        volumeId: string;
+        datacenterId: string;
+    }): void;
+    verifying(): void;
+    ready(details: {
+        sizeBytes: number;
+        checksumManifestDigest: string;
+    }): void;
+    failed(): void;
+    /** Same-client lease around preparation; false when another process holds it. */
+    acquireLease(ttlSeconds: number): boolean;
+    releaseLease(): void;
+}
+export interface BackendContext {
+    ledger: ResourceLedger;
+    cache?: CacheLedger;
+    signal?: AbortSignal;
+    onProgress?: (event: {
+        stage: JobStage;
+        message?: string;
+    }) => void;
+}
+export interface ExecutionBackend {
+    /** Provision, bootstrap the worker, upload inputs, prepare assets and runtime, and begin execution. */
+    start(job: ApprovedJob, context: BackendContext): Promise<JobHandle>;
+    /** Rebuild a handle for a Pod this client created earlier (e.g. after a restart) so results can still be fetched. */
+    reconnect?(runId: string, podId: string, volumeId?: string): JobHandle;
+    observe(handle: JobHandle, after?: number): Promise<JobSnapshot>;
+    cancel(handle: JobHandle): Promise<void>;
+    /** Download and verify every inventory file into `localOutputDir`; never reruns inference. */
+    collect(handle: JobHandle, localOutputDir: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactInventory>;
+    /**
+     * Terminate every paid resource this job owns (GPU/CPU pods; never the persistent volume) and
+     * confirm via the provider. Safe to call repeatedly; absence is success.
+     */
+    release(handle: JobHandle | {
+        runId: string;
+    }, context: Pick<BackendContext, "ledger">): Promise<void>;
+}
+export type WorkerMode = "execute" | "prepare-assets";
+/** Job description sent to the worker: the approved job without client-local paths. */
+export type WireJob = Omit<ApprovedJob, "inputs" | "reuseVolumeId"> & {
+    inputs: Array<Omit<JobInputFile, "sourcePath">>;
+    /** `prepare-assets` runs only asset preparation (CPU Pod); `execute` runs the model. */
+    mode: WorkerMode;
+    /** Where the persistent network volume is mounted in this Pod; absent for ephemeral runs. */
+    volumeMount?: string;
+    /** Lets a worker reclaim an expired on-volume cache lock; set only after the client confirmed the old owner is gone. */
+    reclaimStaleLock?: boolean;
+};
+export declare function toWireJob(job: ApprovedJob, extra?: {
+    mode?: WorkerMode;
+    volumeMount?: string;
+    reclaimStaleLock?: boolean;
+}): WireJob;
+/** Port the worker listens on inside the Pod; the provider proxy exposes it over HTTPS. */
+export declare const WORKER_PORT = 8000;

package/dist/cloud/execution.js

@@ -0,0 +1,18 @@
+/**
+ * Wire and journal contract between the core orchestrator and a remote execution backend. All
+ * types are plain JSON and versioned, so a restarted client can reconstruct a job from the journal
+ * and a worker of a different release can reject what it does not understand.
+ */
+export const EXECUTION_CONTRACT_VERSION = 1;
+export function toWireJob(job, extra = {}) {
+    const { inputs, reuseVolumeId: _reuse, ...rest } = job;
+    return {
+        ...rest,
+        inputs: inputs.map(({ sourcePath: _sourcePath, ...file }) => file),
+        mode: extra.mode ?? "execute",
+        ...(extra.volumeMount ? { volumeMount: extra.volumeMount } : {}),
+        ...(extra.reclaimStaleLock ? { reclaimStaleLock: true } : {}),
+    };
+}
+/** Port the worker listens on inside the Pod; the provider proxy exposes it over HTTPS. */
+export const WORKER_PORT = 8000;

package/dist/cloud/runpod-backend.d.ts

@@ -0,0 +1,73 @@
+import { type SecretBackend } from "./credentials.js";
+import { type ApprovedJob, type ArtifactInventory, type BackendContext, type ExecutionBackend, type JobHandle, type JobSnapshot } from "./execution.js";
+import type { CloudProvider } from "./types.js";
+import { WorkerClient } from "./worker-client.js";
+export declare const MIN_WORKER_READY_TIMEOUT_MS: number;
+export declare const VOLUME_MOUNT = "/workspace";
+export interface WorkerBundle {
+    /** HTTPS URL of the release-pinned worker bundle (a .tar.gz containing `worker/main.js`). */
+    url: string;
+    sha256: string;
+}
+/** Per-job reconnect tokens belong in the OS credential store, never in the journal or run record. */
+export interface TokenStore {
+    set(runId: string, token: string): Promise<void>;
+    get(runId: string): Promise<string | null>;
+    delete(runId: string): Promise<void>;
+}
+export declare function createKeyringTokenStore(backend?: SecretBackend): TokenStore;
+/**
+ * Container start command: fetch the pinned bundle, verify its checksum, and run it. The image must
+ * provide Node 20+, curl, tar and sha256sum. Nothing here comes from the user's input.
+ */
+export declare const WORKER_BOOTSTRAP_SCRIPT: string;
+export interface RunpodBackendOptions {
+    provider: CloudProvider;
+    tokenStore: TokenStore;
+    workerBundle?: WorkerBundle;
+    /** Builds the worker's HTTPS endpoint for a Pod. Defaults to Runpod's proxy. */
+    endpointFor?: (podId: string) => string;
+    createClient?: (endpoint: string, token: string) => WorkerClient;
+    sleep?: (ms: number) => Promise<void>;
+    /** Clamped to at least 5 minutes: cold image pulls were observed taking ~100 s or more. */
+    readyTimeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Persistent: how long to wait for a terminated CPU Pod to disappear before the GPU Pod starts. */
+    terminationWaitMs?: number;
+    /** Test hook. */
+    now?: () => number;
+}
+export declare class RunpodExecutionBackend implements ExecutionBackend {
+    private readonly options;
+    private readonly clients;
+    private readonly tracked;
+    /** Intents already confirmed deleted, so release() stays idempotent. */
+    private readonly deletedIntents;
+    private readonly sleep;
+    private readonly readyTimeoutMs;
+    constructor(options: RunpodBackendOptions);
+    private endpoint;
+    private client;
+    private clientFor;
+    start(job: ApprovedJob, context: BackendContext): Promise<JobHandle>;
+    private startPersistent;
+    /** Cold path: CPU Pod prepares the volume, is terminated and confirmed gone, then capacity is rechecked. */
+    private prepareOnCpu;
+    private createWorkerPod;
+    /** Returns a reason string when the Pod can never serve (so booting should stop waiting). */
+    private podFatal;
+    private waitForTerminal;
+    /** Starts a GPU worker. With `watchCacheFailure`, a cache-missing/invalid failure returns no handle so the caller can rebuild. */
+    private startGpu;
+    /** Terminate through the provider, then require the provider to show the Pod gone before marking it deleted. */
+    private terminateAndConfirm;
+    reconnect(runId: string, podId: string, volumeId?: string): JobHandle;
+    observe(handle: JobHandle, after?: number): Promise<JobSnapshot>;
+    cancel(handle: JobHandle): Promise<void>;
+    collect(handle: JobHandle, localOutputDir: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArtifactInventory>;
+    release(handle: JobHandle | {
+        runId: string;
+    }, context: Pick<BackendContext, "ledger">): Promise<void>;
+}