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

package/dist/sandbox/gondolin-worker.js

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { chmodSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { gondolinInventory } from "./gondolin-inventory.js";
+import { shellEscape } from "./utils.js";
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function warn(message) {
+    process.stderr.write(`[gondolin-worker] ${message}\n`);
+}
+function heartbeatFresh(path, since, staleMs) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(path).mtimeMs;
+    }
+    catch {
+        // no heartbeat yet — fall back to worker start time
+    }
+    return Date.now() - Math.max(mtimeMs, since) <= staleMs;
+}
+function restrictSocketAccess(socketPath) {
+    // The session socket grants arbitrary exec inside the VM (and through its
+    // mounts, the workspace) — keep it to this user even under a lax umask.
+    try {
+        chmodSync(dirname(socketPath), 0o700);
+        chmodSync(socketPath, 0o600);
+    }
+    catch {
+        // best-effort hardening
+    }
+}
+function partitionMounts(mounts) {
+    const directories = [];
+    const files = [];
+    for (const mount of mounts) {
+        let isDirectory;
+        try {
+            isDirectory = statSync(mount.source).isDirectory();
+        }
+        catch {
+            warn(`skipping missing mount source ${mount.source}`);
+            continue;
+        }
+        if (isDirectory) {
+            directories.push(mount);
+        }
+        else {
+            files.push({
+                ...mount,
+                syncBack: mount.target.startsWith("/workspace/"),
+                lastHash: "",
+            });
+        }
+    }
+    return { directories, files };
+}
+/**
+ * Host one Gondolin VM for its whole life: boot it, persist the inventory
+ * record other processes adopt it through, announce readiness on stdout, then
+ * watch the VM runner and shut down when it dies, when a SIGTERM arrives, or
+ * when every mikan that could adopt the runtime is gone (stale heartbeat).
+ */
+export async function runGondolinWorker(config, deps = {}) {
+    const announce = deps.announce ?? ((line) => process.stdout.write(line + "\n"));
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const pollIntervalMs = deps.pollIntervalMs ?? 2000;
+    const loadGondolin = deps.loadGondolin ?? (() => import("@earendil-works/gondolin"));
+    gondolinInventory.configure(config.inventoryDir);
+    const { VM, RealFSProvider, findSession, ensureImageSelector } = await loadGondolin();
+    let imagePath = config.image;
+    if (!imagePath) {
+        if (!config.imageSelector)
+            throw new Error("worker config needs image or imageSelector");
+        imagePath = (await ensureImageSelector(config.imageSelector)).assetDir;
+    }
+    const { directories, files } = partitionMounts(config.mounts);
+    const vm = await VM.create({
+        sandbox: { imagePath },
+        env: { TZ: "Asia/Taipei" },
+        sessionLabel: `mikan:${config.instanceId}`,
+        cpus: config.cpus,
+        memory: config.memory,
+        vfs: {
+            mounts: Object.fromEntries(directories.map(({ source, target }) => [target, new RealFSProvider(source)])),
+        },
+    });
+    let session;
+    try {
+        await vm.start();
+        await projectFiles(vm, files);
+        session = await findSession(vm.id);
+        if (!session)
+            throw new Error(`Gondolin session '${vm.id}' did not register`);
+    }
+    catch (error) {
+        // never leave a half-booted runner (and its overlay disk) behind
+        await vm.close().catch(() => { });
+        throw error;
+    }
+    restrictSocketAccess(session.socketPath);
+    gondolinInventory.record({
+        sessionId: vm.id,
+        instanceId: config.instanceId,
+        runnerPid: vm.getHostPid(),
+        socketPath: session.socketPath,
+        fingerprint: config.fingerprint,
+    });
+    const startedAt = Date.now();
+    let closing = false;
+    let syncing = false;
+    const syncProjections = async () => {
+        if (syncing)
+            return;
+        syncing = true;
+        try {
+            for (const projection of files) {
+                if (!projection.syncBack)
+                    continue;
+                try {
+                    const data = await vm.fs.readFile(projection.target);
+                    const content = Buffer.isBuffer(data) ? data : Buffer.from(String(data));
+                    const hash = sha256(content);
+                    if (hash === projection.lastHash)
+                        continue;
+                    // atomic host write: a crash mid-sync must not truncate the file
+                    const staged = `${projection.source}.mikan-sync`;
+                    writeFileSync(staged, content);
+                    renameSync(staged, projection.source);
+                    projection.lastHash = hash;
+                }
+                catch {
+                    // guest file missing or read raced a writer; next tick retries
+                }
+            }
+        }
+        finally {
+            syncing = false;
+        }
+    };
+    const shutdown = async (code) => {
+        if (closing)
+            return;
+        closing = true;
+        clearInterval(watchdog);
+        try {
+            await syncProjections();
+        }
+        catch {
+            // best effort; the periodic sync already captured earlier edits
+        }
+        try {
+            await vm.close();
+        }
+        catch {
+            // the runner may already be gone
+        }
+        gondolinInventory.release(vm.id);
+        exit(code);
+    };
+    const watchdog = setInterval(() => {
+        const runnerPid = vm.getHostPid();
+        if (runnerPid === null) {
+            // The VM runner died under us; exit so mikan sees the socket close and
+            // recreates the runtime instead of hanging on a silent session.
+            void shutdown(1);
+            return;
+        }
+        gondolinInventory.refresh(vm.id, runnerPid);
+        void syncProjections();
+        const heartbeat = gondolinInventory.heartbeatPath();
+        if (config.heartbeatStaleMs > 0 &&
+            heartbeat &&
+            !heartbeatFresh(heartbeat, startedAt, config.heartbeatStaleMs)) {
+            void shutdown(0);
+        }
+    }, pollIntervalMs);
+    process.on("SIGTERM", () => void shutdown(0));
+    process.on("SIGINT", () => void shutdown(0));
+    announce(JSON.stringify({
+        ready: true,
+        sessionId: vm.id,
+        socketPath: session.socketPath,
+        workerPid: process.pid,
+        runnerPid: vm.getHostPid(),
+    }));
+}
+/** Copy file mounts into the guest; credentials get user-only permissions. */
+async function projectFiles(vm, files) {
+    for (const projection of files) {
+        const content = readFileSync(projection.source);
+        await vm.fs.mkdir(dirname(projection.target), { recursive: true });
+        await vm.fs.writeFile(projection.target, content);
+        if (!projection.syncBack) {
+            // credential projection: no write-back, keep it owner-only
+            await vm.exec(`chmod 600 ${shellEscape(projection.target)}`);
+        }
+        projection.lastHash = sha256(content);
+    }
+}
+//# sourceMappingURL=gondolin-worker.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-worker.js","sourceRoot":"","sources":["../../src/sandbox/gondolin-worker.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { chmodSync, readFileSync, renameSync, statSync, writeFileSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { gondolinInventory } from \"./gondolin-inventory.js\";\nimport { shellEscape } from \"./utils.js\";\n\ntype GondolinModule = typeof import(\"@earendil-works/gondolin\");\n\n/**\n * Everything a worker process needs to host one Gondolin VM. Serialized as a\n * single JSON argv entry — it must stay free of secrets (vault env travels\n * per-exec over the session IPC socket, never through the worker command\n * line).\n */\nexport interface GondolinWorkerConfig {\n  /** mikan session key the runtime belongs to. */\n  instanceId: string;\n  /** Resolved guest image asset directory. */\n  image?: string;\n  /** Image selector resolved inside the worker (remote workers, where the\n   * spawning host has no image store). Ignored when `image` is set. */\n  imageSelector?: string;\n  mounts: Array<{ source: string; target: string }>;\n  cpus?: number;\n  memory?: string;\n  /** Desired-runtime fingerprint recorded for adoption checks. */\n  fingerprint: string;\n  /** Runtime inventory directory (shared with the spawning mikan). */\n  inventoryDir: string;\n  /**\n   * Self-stop when the mikan heartbeat file is older than this — no mikan is\n   * left to adopt the runtime. 0 disables the check.\n   */\n  heartbeatStaleMs: number;\n}\n\n/** First stdout line of a worker, consumed by the spawning mikan. */\nexport interface GondolinWorkerHandshake {\n  ready: boolean;\n  error?: string;\n  sessionId?: string;\n  socketPath?: string;\n  workerPid?: number;\n  runnerPid?: number | null;\n}\n\ninterface GondolinWorkerDeps {\n  loadGondolin?: () => Promise<GondolinModule>;\n  announce?: (line: string) => void;\n  exit?: (code: number) => void;\n  pollIntervalMs?: number;\n}\n\n/**\n * A single-file mount handled outside the VFS: Gondolin's guest prepares every\n * VFS mount point with `mkdir -p`, so a file target can never bind (the guest\n * ends up bind-mounting a file onto a directory and the VM refuses to start).\n * Files are copied in after boot instead; the ones under /workspace sync guest\n * edits back to the host so agent-maintained files like MEMORY.md persist.\n */\ninterface FileProjection {\n  source: string;\n  target: string;\n  syncBack: boolean;\n  lastHash: string;\n}\n\nfunction sha256(data: Buffer): string {\n  return createHash(\"sha256\").update(data).digest(\"hex\");\n}\n\nfunction warn(message: string): void {\n  process.stderr.write(`[gondolin-worker] ${message}\\n`);\n}\n\nfunction heartbeatFresh(path: string, since: number, staleMs: number): boolean {\n  let mtimeMs = 0;\n  try {\n    mtimeMs = statSync(path).mtimeMs;\n  } catch {\n    // no heartbeat yet — fall back to worker start time\n  }\n  return Date.now() - Math.max(mtimeMs, since) <= staleMs;\n}\n\nfunction restrictSocketAccess(socketPath: string): void {\n  // The session socket grants arbitrary exec inside the VM (and through its\n  // mounts, the workspace) — keep it to this user even under a lax umask.\n  try {\n    chmodSync(dirname(socketPath), 0o700);\n    chmodSync(socketPath, 0o600);\n  } catch {\n    // best-effort hardening\n  }\n}\n\nfunction partitionMounts(mounts: GondolinWorkerConfig[\"mounts\"]): {\n  directories: GondolinWorkerConfig[\"mounts\"];\n  files: FileProjection[];\n} {\n  const directories: GondolinWorkerConfig[\"mounts\"] = [];\n  const files: FileProjection[] = [];\n  for (const mount of mounts) {\n    let isDirectory: boolean;\n    try {\n      isDirectory = statSync(mount.source).isDirectory();\n    } catch {\n      warn(`skipping missing mount source ${mount.source}`);\n      continue;\n    }\n    if (isDirectory) {\n      directories.push(mount);\n    } else {\n      files.push({\n        ...mount,\n        syncBack: mount.target.startsWith(\"/workspace/\"),\n        lastHash: \"\",\n      });\n    }\n  }\n  return { directories, files };\n}\n\n/**\n * Host one Gondolin VM for its whole life: boot it, persist the inventory\n * record other processes adopt it through, announce readiness on stdout, then\n * watch the VM runner and shut down when it dies, when a SIGTERM arrives, or\n * when every mikan that could adopt the runtime is gone (stale heartbeat).\n */\nexport async function runGondolinWorker(\n  config: GondolinWorkerConfig,\n  deps: GondolinWorkerDeps = {},\n): Promise<void> {\n  const announce = deps.announce ?? ((line: string) => process.stdout.write(line + \"\\n\"));\n  const exit = deps.exit ?? ((code: number) => process.exit(code));\n  const pollIntervalMs = deps.pollIntervalMs ?? 2000;\n  const loadGondolin =\n    deps.loadGondolin ?? (() => import(\"@earendil-works/gondolin\") as Promise<GondolinModule>);\n\n  gondolinInventory.configure(config.inventoryDir);\n  const { VM, RealFSProvider, findSession, ensureImageSelector } = await loadGondolin();\n  let imagePath = config.image;\n  if (!imagePath) {\n    if (!config.imageSelector) throw new Error(\"worker config needs image or imageSelector\");\n    imagePath = (await ensureImageSelector(config.imageSelector)).assetDir;\n  }\n  const { directories, files } = partitionMounts(config.mounts);\n  const vm = await VM.create({\n    sandbox: { imagePath },\n    env: { TZ: \"Asia/Taipei\" },\n    sessionLabel: `mikan:${config.instanceId}`,\n    cpus: config.cpus,\n    memory: config.memory,\n    vfs: {\n      mounts: Object.fromEntries(\n        directories.map(({ source, target }) => [target, new RealFSProvider(source)]),\n      ),\n    },\n  });\n\n  let session: Awaited<ReturnType<typeof findSession>>;\n  try {\n    await vm.start();\n    await projectFiles(vm, files);\n    session = await findSession(vm.id);\n    if (!session) throw new Error(`Gondolin session '${vm.id}' did not register`);\n  } catch (error) {\n    // never leave a half-booted runner (and its overlay disk) behind\n    await vm.close().catch(() => {});\n    throw error;\n  }\n  restrictSocketAccess(session.socketPath);\n  gondolinInventory.record({\n    sessionId: vm.id,\n    instanceId: config.instanceId,\n    runnerPid: vm.getHostPid(),\n    socketPath: session.socketPath,\n    fingerprint: config.fingerprint,\n  });\n\n  const startedAt = Date.now();\n  let closing = false;\n  let syncing = false;\n  const syncProjections = async (): Promise<void> => {\n    if (syncing) return;\n    syncing = true;\n    try {\n      for (const projection of files) {\n        if (!projection.syncBack) continue;\n        try {\n          const data = await vm.fs.readFile(projection.target);\n          const content = Buffer.isBuffer(data) ? data : Buffer.from(String(data));\n          const hash = sha256(content);\n          if (hash === projection.lastHash) continue;\n          // atomic host write: a crash mid-sync must not truncate the file\n          const staged = `${projection.source}.mikan-sync`;\n          writeFileSync(staged, content);\n          renameSync(staged, projection.source);\n          projection.lastHash = hash;\n        } catch {\n          // guest file missing or read raced a writer; next tick retries\n        }\n      }\n    } finally {\n      syncing = false;\n    }\n  };\n\n  const shutdown = async (code: number): Promise<void> => {\n    if (closing) return;\n    closing = true;\n    clearInterval(watchdog);\n    try {\n      await syncProjections();\n    } catch {\n      // best effort; the periodic sync already captured earlier edits\n    }\n    try {\n      await vm.close();\n    } catch {\n      // the runner may already be gone\n    }\n    gondolinInventory.release(vm.id);\n    exit(code);\n  };\n\n  const watchdog = setInterval(() => {\n    const runnerPid = vm.getHostPid();\n    if (runnerPid === null) {\n      // The VM runner died under us; exit so mikan sees the socket close and\n      // recreates the runtime instead of hanging on a silent session.\n      void shutdown(1);\n      return;\n    }\n    gondolinInventory.refresh(vm.id, runnerPid);\n    void syncProjections();\n    const heartbeat = gondolinInventory.heartbeatPath();\n    if (\n      config.heartbeatStaleMs > 0 &&\n      heartbeat &&\n      !heartbeatFresh(heartbeat, startedAt, config.heartbeatStaleMs)\n    ) {\n      void shutdown(0);\n    }\n  }, pollIntervalMs);\n\n  process.on(\"SIGTERM\", () => void shutdown(0));\n  process.on(\"SIGINT\", () => void shutdown(0));\n\n  announce(\n    JSON.stringify({\n      ready: true,\n      sessionId: vm.id,\n      socketPath: session.socketPath,\n      workerPid: process.pid,\n      runnerPid: vm.getHostPid(),\n    } satisfies GondolinWorkerHandshake),\n  );\n}\n\n/** Copy file mounts into the guest; credentials get user-only permissions. */\nasync function projectFiles(\n  vm: {\n    fs: {\n      mkdir: (path: string, options?: { recursive?: boolean }) => Promise<void>;\n      writeFile: (path: string, data: Buffer) => Promise<void>;\n    };\n    exec: (command: string) => PromiseLike<unknown>;\n  },\n  files: FileProjection[],\n): Promise<void> {\n  for (const projection of files) {\n    const content = readFileSync(projection.source);\n    await vm.fs.mkdir(dirname(projection.target), { recursive: true });\n    await vm.fs.writeFile(projection.target, content);\n    if (!projection.syncBack) {\n      // credential projection: no write-back, keep it owner-only\n      await vm.exec(`chmod 600 ${shellEscape(projection.target)}`);\n    }\n    projection.lastHash = sha256(content);\n  }\n}\n"]}

package/dist/sandbox/gondolin.d.ts

@@ -0,0 +1,52 @@
+import type { ResourceLimits, SandboxLimitStatus, SandboxResourceController } from "../types.js";
+import type { ExecOptions, ExecResult, Executor, GondolinSandboxConfig, RuntimePathContext, SandboxAdapter } from "./types.js";
+declare class GondolinResourceManager implements SandboxResourceController {
+    private defaultLimits?;
+    private boostLimits?;
+    private readonly boostedKeys;
+    private readonly overrideLimits;
+    configure(defaultLimits?: ResourceLimits, boostLimits?: ResourceLimits): void;
+    boost(key: string): Promise<SandboxLimitStatus>;
+    setLimits(key: string, limits: ResourceLimits): Promise<SandboxLimitStatus>;
+    getLimitStatus(key: string): SandboxLimitStatus;
+    getDefaultLimits(): ResourceLimits | undefined;
+    getBoostLimits(): ResourceLimits | undefined;
+    clear(key: string): void;
+    private effectiveLimits;
+}
+export declare const gondolinResources: GondolinResourceManager;
+/**
+ * Fail fast when `gondolin:remote` is selected but no worker source is
+ * configured. Call after the fleet and gateway have been configured.
+ */
+export declare function assertRemoteConfigured(): void;
+export declare function stopIdleGondolinVms(maxIdleMs: number, now?: number): Promise<void>;
+/**
+ * Stop workers surviving from a previous mikan that no conversation has
+ * adopted — without this, a runtime whose conversation went quiet before the
+ * restart would idle forever (its worker only self-stops when every mikan is
+ * gone, and the in-memory idle sweep only tracks acquired sessions).
+ */
+export declare function sweepUnadoptedGondolinWorkers(): Promise<void>;
+/**
+ * Forget every session without stopping the workers: runtimes deliberately
+ * outlive the mikan process so the next one adopts them instead of paying a
+ * VM boot per conversation on every deploy.
+ */
+export declare function disconnectAllGondolinRuntimes(): Promise<void>;
+export declare class GondolinExecutor implements Executor {
+    private readonly config;
+    private readonly env?;
+    private readonly workspacePath;
+    private readonly instanceId;
+    constructor(config: GondolinSandboxConfig, env?: Record<string, string> | undefined);
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    getWorkspacePath(): string;
+    getPathContext(hostWorkspaceRoot: string): RuntimePathContext;
+    getSandboxConfig(): GondolinSandboxConfig;
+}
+export declare const gondolinSandboxAdapter: SandboxAdapter<GondolinSandboxConfig>;
+export {};
+//# sourceMappingURL=gondolin.d.ts.map

package/dist/sandbox/gondolin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin.d.ts","sourceRoot":"","sources":["../../src/sandbox/gondolin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAejG,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACf,MAAM,YAAY,CAAC;AA8BpB,cAAM,uBAAwB,YAAW,yBAAyB;IAChE,OAAO,CAAC,aAAa,CAAC,CAAiB;IACvC,OAAO,CAAC,WAAW,CAAC,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;IAEpE,SAAS,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,cAAc,GAAG,IAAI,CAK5E;IAEK,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAMpD;IAEK,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAIhF;IAED,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAE9C;IAED,gBAAgB,IAAI,cAAc,GAAG,SAAS,CAE7C;IAED,cAAc,IAAI,cAAc,GAAG,SAAS,CAE3C;IAED,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGvB;IAED,OAAO,CAAC,eAAe;CAMxB;AAED,eAAO,MAAM,iBAAiB,yBAAgC,CAAC;AAsC/D;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAe7C;AAwQD,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB5F;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAQnE;AAED;;;;GAIG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,IAAI,CAAC,CAcnE;AAWD,qBAAa,gBAAiB,YAAW,QAAQ;IAK7C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IALvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YACmB,MAAM,EAAE,qBAAqB,EAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,YAAA,EAO9C;IAEK,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAOtE;IAEK,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5C;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;IAED,gBAAgB,IAAI,MAAM,CAEzB;IAED,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,kBAAkB,CAE5D;IAED,gBAAgB,IAAI,qBAAqB,CAExC;CACF;AAED,eAAO,MAAM,sBAAsB,EAAE,cAAc,CAAC,qBAAqB,CAKxE,CAAC"}