@geminixiang/mikan 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/sandbox/gondolin-remote.js

@@ -0,0 +1,325 @@
+import { readFileSync, statSync } from "node:fs";
+import { request as httpsRequest } from "node:https";
+import { relative, isAbsolute, join } from "node:path";
+import * as log from "../log.js";
+import { SandboxError } from "./errors.js";
+import { createSessionFrameParser, encodeSessionMessage, } from "./gondolin-contract.js";
+import { GondolinRuntimeGoneError, isLeaseFencedStatus } from "./gondolin-recovery.js";
+import { execOverSessionConnect, } from "./gondolin-worker-client.js";
+const LEASE_TTL_SECONDS = 300;
+const REQUEST_TIMEOUT_MS = 15_000;
+/** VM boot happens inside this request; the daemon's own handshake cap is 2 min. */
+const ENSURE_TIMEOUT_MS = 150_000;
+/** A request that never reached the daemon (network/TLS/timeout failure). */
+export class GondolinWorkerUnreachableError extends Error {
+}
+// The framing lives with the rest of the wire contract; re-exported here for
+// existing importers.
+export { createSessionFrameParser, encodeSessionMessage };
+/**
+ * One mikan-worker daemon as seen from mikan: mTLS requests, per-instance
+ * fenced leases with heartbeat renewal, and per-command upgraded tunnels.
+ * Commands travel through one tunnel each, so abort semantics match the local
+ * transport exactly.
+ */
+export class GondolinRemoteConnection {
+    constructor(settings, overrides = {}) {
+        this.settings = settings;
+        this.overrides = overrides;
+        this.leases = new Map();
+        this.leaseTtlSeconds = overrides.leaseTtlSeconds ?? LEASE_TTL_SECONDS;
+        this.requestTimeoutMs = overrides.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+    }
+    /** Drop lease timers and caches (does not touch the daemon). */
+    dispose() {
+        for (const lease of this.leases.values())
+            clearInterval(lease.renewTimer);
+        this.leases.clear();
+    }
+    async health() {
+        const response = await this.request("GET", "/v1/health");
+        if (response.status !== 200) {
+            throw new SandboxError(`Error: gondolin remote worker health check failed (${response.status})`);
+        }
+        return response.json;
+    }
+    async ensure(instanceId, spec) {
+        const { mounts, credentialFiles } = this.translateMounts(spec);
+        const body = {
+            instanceId,
+            imageSelector: spec.image,
+            mounts,
+            credentialFiles,
+            cpus: spec.cpus ?? "",
+            memory: spec.memory ?? "",
+            fingerprint: spec.fingerprint,
+        };
+        const idempotencyKey = `${instanceId}:${spec.fingerprint}:${Date.now()}`;
+        for (let attempt = 0;; attempt += 1) {
+            const lease = await this.leaseFor(instanceId);
+            const response = await this.request("POST", "/v1/runtimes", body, { ...this.leaseHeaders(lease), "Idempotency-Key": idempotencyKey }, ENSURE_TIMEOUT_MS);
+            if (response.status === 200) {
+                const runtime = response.json;
+                return {
+                    sessionId: runtime.sessionId ?? "",
+                    instanceId,
+                    workerPid: runtime.workerPid ?? 0,
+                    fingerprint: spec.fingerprint,
+                };
+            }
+            if (isLeaseFencedStatus(response.status) && attempt === 0) {
+                this.dropLease(instanceId);
+                continue;
+            }
+            throw new SandboxError(`Error: remote worker refused runtime (${response.status}): ${String(response.json.message ?? "")}`);
+        }
+    }
+    async stop(handle) {
+        const lease = await this.leaseFor(handle.instanceId);
+        const response = await this.request("DELETE", `/v1/runtimes/${handle.sessionId}`, undefined, this.leaseHeaders(lease));
+        if (isLeaseFencedStatus(response.status)) {
+            this.dropLease(handle.instanceId);
+        }
+        this.releaseLease(handle.instanceId);
+    }
+    async isRuntimeAlive(handle) {
+        try {
+            const response = await this.request("GET", `/v1/runtimes/${handle.sessionId}`);
+            return response.status === 200;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Live runtimes hosted by this worker (fleet reconciliation). */
+    async listRuntimes() {
+        const response = await this.request("GET", "/v1/runtimes");
+        if (response.status !== 200)
+            return [];
+        const runtimes = response.json.runtimes;
+        return Array.isArray(runtimes)
+            ? runtimes
+            : [];
+    }
+    async exec(handle, command, options = {}) {
+        const lease = this.leases.get(handle.instanceId);
+        if (!lease) {
+            // the lease lapsed (e.g. mikan slept); recreate the session cleanly
+            throw new GondolinRuntimeGoneError("no live lease for this runtime");
+        }
+        return execOverSessionConnect((callbacks) => this.openTunnel(handle.instanceId, `/v1/runtimes/${handle.sessionId}/session`, this.leaseHeaders(lease), callbacks), command, options);
+    }
+    /**
+     * Split mounts for the remote worker:
+     * - sources under the mikan-host workspace are translated to the worker's
+     *   shared `workspaceRoot` (shared POSIX storage), and
+     * - sources outside it that are files (vault credentials, which live in the
+     *   host state dir, not the shared workspace) are read and shipped as
+     *   content payloads for the worker to project into the guest.
+     * A non-file source outside the workspace has nowhere to go and is dropped.
+     */
+    translateMounts(spec) {
+        const root = this.settings.workspaceRoot;
+        if (!root || !spec.workspacePath) {
+            return { mounts: spec.mounts, credentialFiles: [] };
+        }
+        const mounts = [];
+        const credentialFiles = [];
+        for (const mount of spec.mounts) {
+            const suffix = relative(spec.workspacePath, mount.source);
+            if (!suffix.startsWith("..") && !isAbsolute(suffix)) {
+                mounts.push({ source: join(root, suffix), target: mount.target });
+                continue;
+            }
+            try {
+                if (!statSync(mount.source).isFile()) {
+                    log.logWarning(`Skipping directory mount outside the shared workspace for remote runtime: ${mount.source}`);
+                    continue;
+                }
+                credentialFiles.push({
+                    target: mount.target,
+                    contentBase64: readFileSync(mount.source).toString("base64"),
+                });
+            }
+            catch {
+                // missing source: skip, matching the local worker's behavior
+            }
+        }
+        return { mounts, credentialFiles };
+    }
+    async leaseFor(instanceId) {
+        const cached = this.leases.get(instanceId);
+        if (cached)
+            return cached;
+        const response = await this.request("POST", "/v1/leases", {
+            instanceId,
+            ttlSeconds: this.leaseTtlSeconds,
+        });
+        if (response.status !== 200) {
+            throw new SandboxError(`Error: remote worker refused lease (${response.status}): ${String(response.json.message ?? "")}`);
+        }
+        const lease = {
+            leaseId: response.json.id,
+            epoch: response.json.epoch,
+            renewTimer: setInterval(() => void this.renew(instanceId), (this.leaseTtlSeconds * 1000) / 3),
+        };
+        lease.renewTimer.unref?.();
+        this.leases.set(instanceId, lease);
+        this.reportLeaseActivity(instanceId);
+        return lease;
+    }
+    async renew(instanceId) {
+        const lease = this.leases.get(instanceId);
+        if (!lease)
+            return;
+        try {
+            const response = await this.request("POST", `/v1/leases/${lease.leaseId}/renew`, {
+                ttlSeconds: this.leaseTtlSeconds,
+            });
+            if (response.status === 200)
+                this.reportLeaseActivity(instanceId);
+            else
+                this.dropLease(instanceId);
+        }
+        catch (err) {
+            log.logWarning(`Failed to renew remote worker lease for '${instanceId}'`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    reportLeaseActivity(instanceId) {
+        // fencing watermark by mikan's own clock: the worker-side lease cannot
+        // outlive this moment plus its ttl, no matter whose clock is skewed
+        this.overrides.onLeaseActivity?.(instanceId, Date.now() + this.leaseTtlSeconds * 1000);
+    }
+    releaseLease(instanceId) {
+        const lease = this.leases.get(instanceId);
+        if (!lease)
+            return;
+        this.dropLease(instanceId);
+        void this.request("DELETE", `/v1/leases/${lease.leaseId}`).catch(() => { });
+    }
+    dropLease(instanceId) {
+        const lease = this.leases.get(instanceId);
+        if (!lease)
+            return;
+        clearInterval(lease.renewTimer);
+        this.leases.delete(instanceId);
+    }
+    leaseHeaders(lease) {
+        return { "X-Mikan-Lease": lease.leaseId, "X-Mikan-Epoch": String(lease.epoch) };
+    }
+    request(method, path, body, headers, timeoutMs = this.requestTimeoutMs) {
+        if (this.overrides.request)
+            return this.overrides.request(method, path, body, headers);
+        const url = new URL(path, this.settings.url);
+        const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body));
+        return new Promise((resolve, reject) => {
+            const request = httpsRequest({
+                method,
+                host: url.hostname,
+                port: url.port,
+                path: url.pathname + url.search,
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: {
+                    ...(payload
+                        ? { "Content-Type": "application/json", "Content-Length": payload.length }
+                        : {}),
+                    ...headers,
+                },
+                ...this.tlsOptions(),
+            }, (response) => {
+                let raw = "";
+                response.setEncoding("utf8");
+                response.on("data", (chunk) => {
+                    raw += chunk;
+                });
+                response.on("end", () => {
+                    let json = {};
+                    try {
+                        json = raw ? JSON.parse(raw) : {};
+                    }
+                    catch {
+                        // non-JSON body; status carries the outcome
+                    }
+                    resolve({ status: response.statusCode ?? 0, json });
+                });
+            });
+            request.on("error", (error) => reject(new GondolinWorkerUnreachableError(error.message)));
+            if (payload)
+                request.write(payload);
+            request.end();
+        });
+    }
+    openTunnel(instanceId, path, headers, callbacks) {
+        if (this.overrides.tunnel)
+            return this.overrides.tunnel(path, headers, callbacks);
+        const url = new URL(path, this.settings.url);
+        return new Promise((resolve, reject) => {
+            const request = httpsRequest({
+                method: "GET",
+                host: url.hostname,
+                port: url.port,
+                path: url.pathname,
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+                headers: { ...headers, Connection: "Upgrade", Upgrade: "gondolin-session" },
+                ...this.tlsOptions(),
+            });
+            request.on("upgrade", (_response, socket) => {
+                socket.setNoDelay(true);
+                let closed = false;
+                const parse = createSessionFrameParser(callbacks);
+                socket.on("data", parse);
+                socket.on("error", (error) => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    callbacks.onClose(error);
+                });
+                socket.on("close", () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    callbacks.onClose();
+                });
+                resolve({
+                    send: (message) => {
+                        if (!closed)
+                            socket.write(encodeSessionMessage(message));
+                    },
+                    close: () => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        socket.destroy();
+                    },
+                });
+            });
+            request.on("response", (response) => {
+                if (isLeaseFencedStatus(response.statusCode)) {
+                    this.dropLease(instanceId);
+                }
+                const error = new Error(`tunnel refused: HTTP ${response.statusCode}`);
+                error.code = "ECONNREFUSED"; // nothing executed — safe to recreate and retry
+                reject(error);
+            });
+            request.on("error", (error) => {
+                error.code ??= "ECONNREFUSED";
+                reject(error);
+            });
+            request.end();
+        });
+    }
+    tlsOptions() {
+        if (this.tls)
+            return this.tls;
+        if (!this.settings.certFile || !this.settings.keyFile) {
+            throw new SandboxError(`Error: gondolin remote worker '${this.settings.name ?? this.settings.url}' needs certFile and keyFile`);
+        }
+        this.tls = {
+            ...(this.settings.caFile ? { ca: readFileSync(this.settings.caFile) } : {}),
+            cert: readFileSync(this.settings.certFile),
+            key: readFileSync(this.settings.keyFile),
+        };
+        return this.tls;
+    }
+}
+//# sourceMappingURL=gondolin-remote.js.map

package/dist/sandbox/gondolin-remote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-remote.js","sourceRoot":"","sources":["../../src/sandbox/gondolin-remote.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync, statSync } from \"node:fs\";\nimport { request as httpsRequest } from \"node:https\";\nimport { relative, isAbsolute, join } from \"node:path\";\nimport * as log from \"../log.js\";\nimport type { GondolinRemoteWorkerSettings } from \"../types.js\";\nimport { SandboxError } from \"./errors.js\";\nimport {\n  createSessionFrameParser,\n  encodeSessionMessage,\n  type GondolinCredentialFile,\n  type GondolinEnsureRuntimeRequest,\n  type GondolinRemoteRuntime,\n} from \"./gondolin-contract.js\";\nimport { GondolinRuntimeGoneError, isLeaseFencedStatus } from \"./gondolin-recovery.js\";\nimport {\n  execOverSessionConnect,\n  type GondolinRuntimeHandle,\n  type GondolinRuntimeSpec,\n  type SessionClient,\n  type SessionClientCallbacks,\n} from \"./gondolin-worker-client.js\";\nimport type { ExecResult } from \"./types.js\";\n\nconst LEASE_TTL_SECONDS = 300;\nconst REQUEST_TIMEOUT_MS = 15_000;\n/** VM boot happens inside this request; the daemon's own handshake cap is 2 min. */\nconst ENSURE_TIMEOUT_MS = 150_000;\n\ninterface RemoteLease {\n  leaseId: string;\n  epoch: number;\n  renewTimer: NodeJS.Timeout;\n}\n\ninterface RemoteResponse {\n  status: number;\n  json: Record<string, unknown>;\n}\n\n/** A request that never reached the daemon (network/TLS/timeout failure). */\nexport class GondolinWorkerUnreachableError extends Error {}\n\nexport interface GondolinRemoteOverrides {\n  request?: (\n    method: string,\n    path: string,\n    body?: object,\n    headers?: Record<string, string>,\n  ) => Promise<RemoteResponse>;\n  tunnel?: (\n    path: string,\n    headers: Record<string, string>,\n    callbacks: SessionClientCallbacks,\n  ) => SessionClient | Promise<SessionClient>;\n  leaseTtlSeconds?: number;\n  requestTimeoutMs?: number;\n  /** Reports lease grants/renewals so the fleet can persist fencing watermarks. */\n  onLeaseActivity?: (instanceId: string, expiresAtMs: number) => void;\n}\n\n// The framing lives with the rest of the wire contract; re-exported here for\n// existing importers.\nexport { createSessionFrameParser, encodeSessionMessage };\n\n/**\n * One mikan-worker daemon as seen from mikan: mTLS requests, per-instance\n * fenced leases with heartbeat renewal, and per-command upgraded tunnels.\n * Commands travel through one tunnel each, so abort semantics match the local\n * transport exactly.\n */\nexport class GondolinRemoteConnection {\n  private readonly leases = new Map<string, RemoteLease>();\n  private readonly leaseTtlSeconds: number;\n  private readonly requestTimeoutMs: number;\n  private tls?: { ca?: Buffer; cert: Buffer; key: Buffer };\n\n  constructor(\n    private readonly settings: GondolinRemoteWorkerSettings,\n    private readonly overrides: GondolinRemoteOverrides = {},\n  ) {\n    this.leaseTtlSeconds = overrides.leaseTtlSeconds ?? LEASE_TTL_SECONDS;\n    this.requestTimeoutMs = overrides.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;\n  }\n\n  /** Drop lease timers and caches (does not touch the daemon). */\n  dispose(): void {\n    for (const lease of this.leases.values()) clearInterval(lease.renewTimer);\n    this.leases.clear();\n  }\n\n  async health(): Promise<Record<string, unknown>> {\n    const response = await this.request(\"GET\", \"/v1/health\");\n    if (response.status !== 200) {\n      throw new SandboxError(\n        `Error: gondolin remote worker health check failed (${response.status})`,\n      );\n    }\n    return response.json;\n  }\n\n  async ensure(instanceId: string, spec: GondolinRuntimeSpec): Promise<GondolinRuntimeHandle> {\n    const { mounts, credentialFiles } = this.translateMounts(spec);\n    const body: GondolinEnsureRuntimeRequest = {\n      instanceId,\n      imageSelector: spec.image,\n      mounts,\n      credentialFiles,\n      cpus: spec.cpus ?? \"\",\n      memory: spec.memory ?? \"\",\n      fingerprint: spec.fingerprint,\n    };\n    const idempotencyKey = `${instanceId}:${spec.fingerprint}:${Date.now()}`;\n    for (let attempt = 0; ; attempt += 1) {\n      const lease = await this.leaseFor(instanceId);\n      const response = await this.request(\n        \"POST\",\n        \"/v1/runtimes\",\n        body,\n        { ...this.leaseHeaders(lease), \"Idempotency-Key\": idempotencyKey },\n        ENSURE_TIMEOUT_MS,\n      );\n      if (response.status === 200) {\n        const runtime = response.json as Partial<GondolinRemoteRuntime>;\n        return {\n          sessionId: runtime.sessionId ?? \"\",\n          instanceId,\n          workerPid: runtime.workerPid ?? 0,\n          fingerprint: spec.fingerprint,\n        };\n      }\n      if (isLeaseFencedStatus(response.status) && attempt === 0) {\n        this.dropLease(instanceId);\n        continue;\n      }\n      throw new SandboxError(\n        `Error: remote worker refused runtime (${response.status}): ${String(response.json.message ?? \"\")}`,\n      );\n    }\n  }\n\n  async stop(\n    handle: Pick<GondolinRuntimeHandle, \"workerPid\" | \"sessionId\" | \"instanceId\">,\n  ): Promise<void> {\n    const lease = await this.leaseFor(handle.instanceId);\n    const response = await this.request(\n      \"DELETE\",\n      `/v1/runtimes/${handle.sessionId}`,\n      undefined,\n      this.leaseHeaders(lease),\n    );\n    if (isLeaseFencedStatus(response.status)) {\n      this.dropLease(handle.instanceId);\n    }\n    this.releaseLease(handle.instanceId);\n  }\n\n  async isRuntimeAlive(handle: GondolinRuntimeHandle): Promise<boolean> {\n    try {\n      const response = await this.request(\"GET\", `/v1/runtimes/${handle.sessionId}`);\n      return response.status === 200;\n    } catch {\n      return false;\n    }\n  }\n\n  /** Live runtimes hosted by this worker (fleet reconciliation). */\n  async listRuntimes(): Promise<Array<{ sessionId: string; instanceId: string }>> {\n    const response = await this.request(\"GET\", \"/v1/runtimes\");\n    if (response.status !== 200) return [];\n    const runtimes = response.json.runtimes;\n    return Array.isArray(runtimes)\n      ? (runtimes as Array<{ sessionId: string; instanceId: string }>)\n      : [];\n  }\n\n  async exec(\n    handle: GondolinRuntimeHandle,\n    command: string,\n    options: { env?: Record<string, string>; signal?: AbortSignal } = {},\n  ): Promise<ExecResult> {\n    const lease = this.leases.get(handle.instanceId);\n    if (!lease) {\n      // the lease lapsed (e.g. mikan slept); recreate the session cleanly\n      throw new GondolinRuntimeGoneError(\"no live lease for this runtime\");\n    }\n    return execOverSessionConnect(\n      (callbacks) =>\n        this.openTunnel(\n          handle.instanceId,\n          `/v1/runtimes/${handle.sessionId}/session`,\n          this.leaseHeaders(lease),\n          callbacks,\n        ),\n      command,\n      options,\n    );\n  }\n\n  /**\n   * Split mounts for the remote worker:\n   * - sources under the mikan-host workspace are translated to the worker's\n   *   shared `workspaceRoot` (shared POSIX storage), and\n   * - sources outside it that are files (vault credentials, which live in the\n   *   host state dir, not the shared workspace) are read and shipped as\n   *   content payloads for the worker to project into the guest.\n   * A non-file source outside the workspace has nowhere to go and is dropped.\n   */\n  private translateMounts(spec: GondolinRuntimeSpec): {\n    mounts: Array<{ source: string; target: string }>;\n    credentialFiles: GondolinCredentialFile[];\n  } {\n    const root = this.settings.workspaceRoot;\n    if (!root || !spec.workspacePath) {\n      return { mounts: spec.mounts, credentialFiles: [] };\n    }\n    const mounts: Array<{ source: string; target: string }> = [];\n    const credentialFiles: GondolinCredentialFile[] = [];\n    for (const mount of spec.mounts) {\n      const suffix = relative(spec.workspacePath, mount.source);\n      if (!suffix.startsWith(\"..\") && !isAbsolute(suffix)) {\n        mounts.push({ source: join(root, suffix), target: mount.target });\n        continue;\n      }\n      try {\n        if (!statSync(mount.source).isFile()) {\n          log.logWarning(\n            `Skipping directory mount outside the shared workspace for remote runtime: ${mount.source}`,\n          );\n          continue;\n        }\n        credentialFiles.push({\n          target: mount.target,\n          contentBase64: readFileSync(mount.source).toString(\"base64\"),\n        });\n      } catch {\n        // missing source: skip, matching the local worker's behavior\n      }\n    }\n    return { mounts, credentialFiles };\n  }\n\n  private async leaseFor(instanceId: string): Promise<RemoteLease> {\n    const cached = this.leases.get(instanceId);\n    if (cached) return cached;\n    const response = await this.request(\"POST\", \"/v1/leases\", {\n      instanceId,\n      ttlSeconds: this.leaseTtlSeconds,\n    });\n    if (response.status !== 200) {\n      throw new SandboxError(\n        `Error: remote worker refused lease (${response.status}): ${String(response.json.message ?? \"\")}`,\n      );\n    }\n    const lease: RemoteLease = {\n      leaseId: response.json.id as string,\n      epoch: response.json.epoch as number,\n      renewTimer: setInterval(() => void this.renew(instanceId), (this.leaseTtlSeconds * 1000) / 3),\n    };\n    lease.renewTimer.unref?.();\n    this.leases.set(instanceId, lease);\n    this.reportLeaseActivity(instanceId);\n    return lease;\n  }\n\n  private async renew(instanceId: string): Promise<void> {\n    const lease = this.leases.get(instanceId);\n    if (!lease) return;\n    try {\n      const response = await this.request(\"POST\", `/v1/leases/${lease.leaseId}/renew`, {\n        ttlSeconds: this.leaseTtlSeconds,\n      });\n      if (response.status === 200) this.reportLeaseActivity(instanceId);\n      else this.dropLease(instanceId);\n    } catch (err) {\n      log.logWarning(\n        `Failed to renew remote worker lease for '${instanceId}'`,\n        err instanceof Error ? err.message : String(err),\n      );\n    }\n  }\n\n  private reportLeaseActivity(instanceId: string): void {\n    // fencing watermark by mikan's own clock: the worker-side lease cannot\n    // outlive this moment plus its ttl, no matter whose clock is skewed\n    this.overrides.onLeaseActivity?.(instanceId, Date.now() + this.leaseTtlSeconds * 1000);\n  }\n\n  private releaseLease(instanceId: string): void {\n    const lease = this.leases.get(instanceId);\n    if (!lease) return;\n    this.dropLease(instanceId);\n    void this.request(\"DELETE\", `/v1/leases/${lease.leaseId}`).catch(() => {});\n  }\n\n  private dropLease(instanceId: string): void {\n    const lease = this.leases.get(instanceId);\n    if (!lease) return;\n    clearInterval(lease.renewTimer);\n    this.leases.delete(instanceId);\n  }\n\n  private leaseHeaders(lease: RemoteLease): Record<string, string> {\n    return { \"X-Mikan-Lease\": lease.leaseId, \"X-Mikan-Epoch\": String(lease.epoch) };\n  }\n\n  private request(\n    method: string,\n    path: string,\n    body?: object,\n    headers?: Record<string, string>,\n    timeoutMs = this.requestTimeoutMs,\n  ): Promise<RemoteResponse> {\n    if (this.overrides.request) return this.overrides.request(method, path, body, headers);\n    const url = new URL(path, this.settings.url);\n    const payload = body === undefined ? undefined : Buffer.from(JSON.stringify(body));\n    return new Promise((resolve, reject) => {\n      const request = httpsRequest(\n        {\n          method,\n          host: url.hostname,\n          port: url.port,\n          path: url.pathname + url.search,\n          signal: AbortSignal.timeout(timeoutMs),\n          headers: {\n            ...(payload\n              ? { \"Content-Type\": \"application/json\", \"Content-Length\": payload.length }\n              : {}),\n            ...headers,\n          },\n          ...this.tlsOptions(),\n        },\n        (response) => {\n          let raw = \"\";\n          response.setEncoding(\"utf8\");\n          response.on(\"data\", (chunk: string) => {\n            raw += chunk;\n          });\n          response.on(\"end\", () => {\n            let json: Record<string, unknown> = {};\n            try {\n              json = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};\n            } catch {\n              // non-JSON body; status carries the outcome\n            }\n            resolve({ status: response.statusCode ?? 0, json });\n          });\n        },\n      );\n      request.on(\"error\", (error: Error) =>\n        reject(new GondolinWorkerUnreachableError(error.message)),\n      );\n      if (payload) request.write(payload);\n      request.end();\n    });\n  }\n\n  private openTunnel(\n    instanceId: string,\n    path: string,\n    headers: Record<string, string>,\n    callbacks: SessionClientCallbacks,\n  ): SessionClient | Promise<SessionClient> {\n    if (this.overrides.tunnel) return this.overrides.tunnel(path, headers, callbacks);\n    const url = new URL(path, this.settings.url);\n    return new Promise((resolve, reject) => {\n      const request = httpsRequest({\n        method: \"GET\",\n        host: url.hostname,\n        port: url.port,\n        path: url.pathname,\n        signal: AbortSignal.timeout(this.requestTimeoutMs),\n        headers: { ...headers, Connection: \"Upgrade\", Upgrade: \"gondolin-session\" },\n        ...this.tlsOptions(),\n      });\n      request.on(\"upgrade\", (_response, socket) => {\n        socket.setNoDelay(true);\n        let closed = false;\n        const parse = createSessionFrameParser(callbacks);\n        socket.on(\"data\", parse);\n        socket.on(\"error\", (error: Error) => {\n          if (closed) return;\n          closed = true;\n          callbacks.onClose(error);\n        });\n        socket.on(\"close\", () => {\n          if (closed) return;\n          closed = true;\n          callbacks.onClose();\n        });\n        resolve({\n          send: (message) => {\n            if (!closed) socket.write(encodeSessionMessage(message));\n          },\n          close: () => {\n            if (closed) return;\n            closed = true;\n            socket.destroy();\n          },\n        });\n      });\n      request.on(\"response\", (response) => {\n        if (isLeaseFencedStatus(response.statusCode)) {\n          this.dropLease(instanceId);\n        }\n        const error = new Error(\n          `tunnel refused: HTTP ${response.statusCode}`,\n        ) as NodeJS.ErrnoException;\n        error.code = \"ECONNREFUSED\"; // nothing executed — safe to recreate and retry\n        reject(error);\n      });\n      request.on(\"error\", (error: NodeJS.ErrnoException) => {\n        error.code ??= \"ECONNREFUSED\";\n        reject(error);\n      });\n      request.end();\n    });\n  }\n\n  private tlsOptions(): { ca?: Buffer; cert: Buffer; key: Buffer } {\n    if (this.tls) return this.tls;\n    if (!this.settings.certFile || !this.settings.keyFile) {\n      throw new SandboxError(\n        `Error: gondolin remote worker '${this.settings.name ?? this.settings.url}' needs certFile and keyFile`,\n      );\n    }\n    this.tls = {\n      ...(this.settings.caFile ? { ca: readFileSync(this.settings.caFile) } : {}),\n      cert: readFileSync(this.settings.certFile),\n      key: readFileSync(this.settings.keyFile),\n    };\n    return this.tls;\n  }\n}\n"]}

package/dist/sandbox/gondolin-worker-client.d.ts

@@ -0,0 +1,135 @@
+import type { Readable } from "node:stream";
+import type { GondolinWorkerConfig } from "./gondolin-worker.js";
+import type { ExecResult } from "./types.js";
+/**
+ * A live worker-hosted runtime as seen from mikan: identity plus fleet
+ * routing only. Transport-private connection details (the local worker's
+ * session socket, the remote worker's lease/tunnel) stay inside the owning
+ * transport — a handle never carries another transport's address fields.
+ */
+export interface GondolinRuntimeHandle {
+    sessionId: string;
+    instanceId: string;
+    workerPid: number;
+    fingerprint: string;
+    /** Fleet identity of the worker hosting the runtime (remote transport). */
+    workerName?: string;
+}
+/**
+ * What a runtime should look like, resolved by the executor layer. `image` is
+ * a local asset directory for the local transport and an image selector for
+ * the remote one (resolved on the worker host).
+ */
+export interface GondolinRuntimeSpec {
+    image: string;
+    mounts: Array<{
+        source: string;
+        target: string;
+    }>;
+    /** Raw fractional CPU limit (cgroup enforcement on remote Linux workers). */
+    cpus?: string;
+    /** Whole vCPUs given to the VM. */
+    vmCpus?: number;
+    memory?: string;
+    fingerprint: string;
+    /** mikan-host workspace root, for remote mount prefix translation. */
+    workspacePath?: string;
+}
+/** One way of running Gondolin runtimes: in local workers or on a remote fleet. */
+export interface GondolinRuntimeTransport {
+    ensure(instanceId: string, spec: GondolinRuntimeSpec): Promise<GondolinRuntimeHandle>;
+    stop(handle: Pick<GondolinRuntimeHandle, "workerPid" | "sessionId" | "instanceId" | "workerName">): Promise<void>;
+    exec(handle: GondolinRuntimeHandle, command: string, options?: {
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<ExecResult>;
+    isRuntimeAlive(handle: GondolinRuntimeHandle): Promise<boolean>;
+}
+interface WorkerProcessLike {
+    pid?: number;
+    stdout: Readable | null;
+    stderr: Readable | null;
+    once(event: "close", listener: (code: number | null) => void): unknown;
+    once(event: "error", listener: (error: Error) => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
+    unref(): void;
+}
+export interface SessionClientCallbacks {
+    onJson: (message: {
+        type: string;
+        id?: number;
+        exit_code?: number | null;
+        code?: string;
+        message?: string;
+    }) => void;
+    onBinary: (frame: Buffer) => void;
+    onClose: (error?: Error) => void;
+}
+export interface SessionClient {
+    send(message: object): void;
+    close(): void;
+}
+interface GondolinWorkerClientOverrides {
+    spawnProcess?: (command: string, args: string[]) => WorkerProcessLike;
+    connect?: (socketPath: string, callbacks: SessionClientCallbacks) => SessionClient;
+    kill?: (pid: number, signal: NodeJS.Signals | 0) => void;
+    handshakeTimeoutMs?: number;
+    stopWaitMs?: number;
+    stopPollIntervalMs?: number;
+}
+/**
+ * Run one command through a fresh session connection — the shared state
+ * machine for both transports. Closing the connection (abort, timeout, or the
+ * far side dying) kills the in-flight guest process.
+ */
+export declare function execOverSessionConnect(connect: (callbacks: SessionClientCallbacks) => SessionClient | Promise<SessionClient>, command: string, options?: {
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    idleTimeoutMs?: number;
+}): Promise<ExecResult>;
+declare class GondolinWorkerClient implements GondolinRuntimeTransport {
+    /** Session IPC socket per runtime — transport-private, never on the handle. */
+    private readonly socketPaths;
+    private spawnProcess;
+    private connectImpl;
+    private killImpl;
+    private handshakeTimeoutMs;
+    private stopWaitMs;
+    private stopPollIntervalMs;
+    configure(overrides?: GondolinWorkerClientOverrides): void;
+    /** Adopt a surviving local worker or spawn a fresh one for the spec. */
+    ensure(instanceId: string, spec: GondolinRuntimeSpec): Promise<GondolinRuntimeHandle>;
+    /** Whether the runtime's worker process is still alive. */
+    isRuntimeAlive(handle: GondolinRuntimeHandle): Promise<boolean>;
+    /** Spawn a detached worker for the config and wait for its ready handshake. */
+    spawn(config: GondolinWorkerConfig): Promise<GondolinRuntimeHandle>;
+    /**
+     * Adopt a runtime a previous mikan left running: newest live record for the
+     * key whose fingerprint still matches and whose session answers a probe.
+     * Anything stale — drifted fingerprint, unresponsive session — is stopped so
+     * the caller can spawn fresh.
+     */
+    adopt(instanceId: string, fingerprint: string): Promise<GondolinRuntimeHandle | undefined>;
+    /**
+     * Stop a worker and wait for it to clean up after itself; escalate to
+     * SIGKILL and reap its leftovers if it will not die.
+     */
+    stop(handle: Pick<GondolinRuntimeHandle, "workerPid" | "sessionId">): Promise<void>;
+    /** Whether the worker process behind a handle is still alive. */
+    /**
+     * Run one command over a dedicated session IPC connection. Aborting (or the
+     * caller's timeout signal firing) destroys the connection, which kills the
+     * in-flight guest process.
+     */
+    exec(handle: GondolinRuntimeHandle, command: string, options?: {
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<ExecResult>;
+    private signal;
+    private isPidAlive;
+    private waitForExit;
+    private readHandshake;
+}
+export declare const gondolinWorkers: GondolinWorkerClient;
+export {};
+//# sourceMappingURL=gondolin-worker-client.d.ts.map

package/dist/sandbox/gondolin-worker-client.d.ts.map

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