@kilogent/runner 0.1.6 → 0.1.8

package/dist/kg-session-launcher.mjs

@@ -0,0 +1,1047 @@
+#!/usr/bin/env node
+
+// src/launcher/main.ts
+import { spawnSync } from "node:child_process";
+import fs2 from "node:fs";
+
+// src/launcher/handler.ts
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// src/engines/runCommand.ts
+import { execFile } from "node:child_process";
+var COMMAND_TIMEOUT_MS = 1e4;
+function runCommand(command, args, opts = {}) {
+  return new Promise((resolve) => {
+    try {
+      const child = execFile(
+        command,
+        [...args],
+        { env: opts.env ?? process.env, timeout: opts.timeoutMs ?? COMMAND_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024, encoding: "utf8" },
+        (error, stdout, stderr) => {
+          resolve({ ok: !error, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") || (error ? error.message : "") });
+        }
+      );
+      if (opts.input !== void 0) {
+        child.stdin?.on("error", () => {
+        });
+        child.stdin?.end(opts.input);
+      }
+    } catch (e) {
+      resolve({ ok: false, stdout: "", stderr: e instanceof Error ? e.message : String(e) });
+    }
+  });
+}
+
+// src/image/dockerApi.ts
+import http from "node:http";
+
+// src/image/ref.ts
+var DIGEST_REF = /^([a-z0-9-]+-docker\.pkg\.dev)\/([a-z0-9][a-z0-9-]{4,62}\/[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*)@(sha256:[a-f0-9]{64})$/;
+var LOCAL_DIGEST_REF = /^((?:127\.0\.0\.1|localhost):\d{2,5})\/([a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*)@(sha256:[a-f0-9]{64})$/;
+function parseDigestRef(value, opts = {}) {
+  if (typeof value !== "string") return null;
+  const match = DIGEST_REF.exec(value) ?? (opts.allowLocalRegistry ? LOCAL_DIGEST_REF.exec(value) : null);
+  if (!match) return null;
+  return { registry: match[1], repository: match[2], digest: match[3], ref: value };
+}
+function registryAuthHeader(token, registry) {
+  return Buffer.from(JSON.stringify({ registrytoken: token, serveraddress: registry })).toString("base64url");
+}
+function classifyPullError(message, code) {
+  if (code === "ECONNREFUSED" || code === "ENOENT" || code === "EACCES" || /cannot connect to the docker daemon/i.test(message)) {
+    return "docker";
+  }
+  if (/unauthori[sz]ed|denied|forbidden|\b401\b|\b403\b|authentication required/i.test(message)) return "auth";
+  if (/manifest unknown|not found|no such manifest|name unknown|\b404\b/i.test(message)) return "registry";
+  return "network";
+}
+
+// src/image/dockerApi.ts
+function request(socketPath, method, apiPath, opts) {
+  return new Promise((resolve, reject) => {
+    const body = opts.json === void 0 ? null : JSON.stringify(opts.json);
+    const headers = { ...opts.headers ?? {}, ...body === null ? {} : { "Content-Type": "application/json", "Content-Length": String(Buffer.byteLength(body)) } };
+    const req = http.request({ socketPath, method, path: apiPath, headers, ...opts.signal ? { signal: opts.signal } : {} }, (res) => {
+      let body2 = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        opts.onChunk?.(chunk);
+        body2 = (body2 + chunk).slice(-64e3);
+      });
+      res.on("end", () => resolve({ status: res.statusCode ?? 0, body: body2 }));
+      res.on("error", reject);
+    });
+    req.setTimeout(opts.timeoutMs, () => req.destroy(Object.assign(new Error(`Docker did not answer within ${opts.timeoutMs} ms`), { code: "ETIMEDOUT" })));
+    req.on("error", reject);
+    req.end(body ?? void 0);
+  });
+}
+async function imagePresent(socketPath, image2) {
+  try {
+    const res = await request(socketPath, "GET", `/images/${encodeURIComponent(image2)}/json`, { timeoutMs: 1e4 });
+    if (res.status === 200) return true;
+    if (res.status === 404) return false;
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function listRepositoryImages(socketPath, repository) {
+  try {
+    const filters = encodeURIComponent(JSON.stringify({ reference: [repository] }));
+    const res = await request(socketPath, "GET", `/images/json?filters=${filters}`, { timeoutMs: 15e3 });
+    if (res.status !== 200) return [];
+    const images = JSON.parse(res.body);
+    return images.flatMap((image2) => Array.isArray(image2.RepoDigests) ? image2.RepoDigests : []).filter((ref) => typeof ref === "string" && ref.startsWith(`${repository}@sha256:`));
+  } catch {
+    return [];
+  }
+}
+async function removeImage(socketPath, ref) {
+  try {
+    const res = await request(socketPath, "DELETE", `/images/${encodeURIComponent(ref)}`, { timeoutMs: 6e4 });
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+async function pullByDigest(input) {
+  const query = `fromImage=${encodeURIComponent(`${input.image.registry}/${input.image.repository}@${input.image.digest}`)}`;
+  try {
+    const res = await request(input.socketPath, "POST", `/images/create?${query}`, {
+      headers: { "X-Registry-Auth": registryAuthHeader(input.token, input.image.registry) },
+      timeoutMs: input.timeoutMs ?? 15 * 6e4
+    });
+    const streamed = lastStreamError(res.body);
+    if (res.status !== 200 || streamed) {
+      const message = streamed ?? (res.body.trim().slice(0, 300) || `Docker answered ${res.status}`);
+      return { ok: false, kind: classifyPullError(message), message };
+    }
+    return { ok: true };
+  } catch (e) {
+    const err = e;
+    return { ok: false, kind: classifyPullError(err.message ?? String(e), err.code), message: err.message ?? String(e) };
+  }
+}
+function lastStreamError(body) {
+  let found = null;
+  for (const line of body.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      const doc = JSON.parse(trimmed);
+      const message = typeof doc.errorDetail?.message === "string" ? doc.errorDetail.message : typeof doc.error === "string" ? doc.error : null;
+      if (message) found = message;
+    } catch {
+    }
+  }
+  return found;
+}
+var MIB = 1024 * 1024;
+function memoryFromStats(body) {
+  let doc;
+  try {
+    doc = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  const m = doc.memory_stats;
+  if (!m || typeof m.usage !== "number") return null;
+  const inactive = typeof m.stats?.inactive_file === "number" ? m.stats.inactive_file : typeof m.stats?.total_inactive_file === "number" ? m.stats.total_inactive_file : 0;
+  return {
+    usedMb: Math.max(0, (m.usage - inactive) / MIB),
+    limitMb: typeof m.limit === "number" ? m.limit / MIB : 0
+  };
+}
+async function containerMemory(socketPath, container) {
+  try {
+    const res = await request(socketPath, "GET", `/containers/${encodeURIComponent(container)}/stats?stream=false&one-shot=true`, { timeoutMs: 5e3 });
+    return res.status === 200 ? memoryFromStats(res.body) : null;
+  } catch {
+    return null;
+  }
+}
+async function updateContainerMemory(socketPath, container, limitMb) {
+  const bytes = Math.round(limitMb) * MIB;
+  try {
+    const res = await request(socketPath, "POST", `/containers/${encodeURIComponent(container)}/update`, {
+      timeoutMs: 1e4,
+      json: { Memory: bytes, MemorySwap: bytes }
+    });
+    return res.status === 200;
+  } catch {
+    return false;
+  }
+}
+function watchContainerOom(socketPath, container, signal) {
+  let seen = false;
+  const filters = encodeURIComponent(JSON.stringify({ type: ["container"], container: [container], event: ["oom"] }));
+  request(socketPath, "GET", `/events?filters=${filters}`, {
+    timeoutMs: 24 * 60 * 6e4,
+    signal,
+    onChunk: (text) => {
+      if (/"(status|Action)"\s*:\s*"oom"/.test(text)) seen = true;
+    }
+  }).catch(() => void 0);
+  return { seen: () => seen };
+}
+
+// src/image/retention.ts
+function repositoryOf(ref) {
+  const at = ref.indexOf("@sha256:");
+  return at > 0 && /^[a-f0-9]{64}$/.test(ref.slice(at + "@sha256:".length)) ? ref.slice(0, at) : null;
+}
+function imagesToRemove(present, keep) {
+  const repositories = new Set(keep.map(repositoryOf).filter((r) => r !== null));
+  return present.filter((ref) => {
+    const repository = repositoryOf(ref);
+    return repository !== null && repositories.has(repository) && !keep.includes(ref);
+  });
+}
+
+// src/launcher/memoryWatch.ts
+var RUNSC_LIVE_MEMORY_MIN = "release-20260202.0";
+var MAX_RAISE_FAILURES = 5;
+var OOM_NEAR_LIMIT_PCT = 90;
+var GROW_PLAN_BOUNDS = Object.freeze({
+  startMb: [256, 4096],
+  stepMb: [50, 1024],
+  maxMb: [256, 4096],
+  growAtPct: [50, 95],
+  pollMs: [100, 5e3]
+});
+function parseGrowPlan(raw, ceilingMb) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const d = raw;
+  const out = {};
+  for (const [key, [min, max]] of Object.entries(GROW_PLAN_BOUNDS)) {
+    const v = d[key];
+    if (typeof v !== "number" || !Number.isInteger(v) || v < min || v > max) return null;
+    out[key] = v;
+  }
+  const plan = out;
+  if (plan.maxMb > ceilingMb || plan.startMb > plan.maxMb) return null;
+  return plan;
+}
+function nextLimit(usedMb, appliedMb, plan) {
+  if (!Number.isFinite(usedMb) || appliedMb >= plan.maxMb) return null;
+  const over = (limit) => usedMb >= limit * plan.growAtPct / 100;
+  if (!over(appliedMb)) return null;
+  let next = appliedMb + plan.stepMb;
+  while (next < plan.maxMb && over(next)) next += plan.stepMb;
+  return Math.min(plan.maxMb, next);
+}
+function nodeHeapMb(plan) {
+  return Math.max(128, Math.min(Math.round(plan.maxMb * 0.75), plan.maxMb - 128));
+}
+function nodeOptionsFor(plan) {
+  return `--max-old-space-size=${nodeHeapMb(plan)}`;
+}
+function classifyExit(input) {
+  const nearLimit = input.limitMb > 0 && input.lastUsedMb >= input.limitMb * OOM_NEAR_LIMIT_PCT / 100;
+  const killed = input.oomEvent || input.exitCode === 137 && !input.stopped && nearLimit;
+  if (!killed) return "none";
+  return input.limitMb >= input.maxMb ? "limitAtMax" : "limitBelowMax";
+}
+function initialMemoryState(input) {
+  const startMb = input.plan ? input.plan.startMb : input.ceilingMb;
+  const maxMb = input.plan ? input.plan.maxMb : input.ceilingMb;
+  return {
+    tier: input.tier,
+    growable: input.plan !== null,
+    reason: input.plan ? null : input.reason,
+    startMb,
+    limitMb: startMb,
+    maxMb,
+    usedMb: 0,
+    peakMb: 0,
+    raises: 0,
+    refused: 0,
+    atMax: startMb >= maxMb,
+    running: true,
+    oom: "none",
+    updatedAt: input.now
+  };
+}
+var RECORD_EVERY_MS = 2e3;
+async function watchMemory(input) {
+  const { plan, port, signal } = input;
+  const state = { ...input.state };
+  let failures = 0;
+  let lastRecorded = 0;
+  const record = (force) => {
+    const now = port.now();
+    if (!force && now - lastRecorded < RECORD_EVERY_MS) return;
+    lastRecorded = now;
+    state.updatedAt = now;
+    try {
+      port.onChange({ ...state });
+    } catch {
+    }
+  };
+  record(true);
+  while (!signal.aborted) {
+    let changed = false;
+    const sample = await port.sample().catch(() => null);
+    if (sample && !signal.aborted) {
+      state.usedMb = Math.max(0, Math.round(sample.usedMb));
+      state.peakMb = Math.max(state.peakMb, state.usedMb);
+      if (plan && failures < MAX_RAISE_FAILURES) {
+        if (sample.limitMb > 0 && Math.abs(sample.limitMb - state.limitMb) >= 1) {
+          if (await port.apply(state.limitMb).catch(() => false)) failures = 0;
+          else failures += 1;
+        }
+        const next = nextLimit(state.usedMb, state.limitMb, plan);
+        if (next !== null) {
+          const room = port.mayRaise ? await port.mayRaise(state.limitMb, next).catch(() => false) : true;
+          if (!room) {
+            state.refused += 1;
+            changed = true;
+          } else if (await port.apply(next).catch(() => false)) {
+            state.limitMb = next;
+            state.raises += 1;
+            state.atMax = next >= state.maxMb;
+            failures = 0;
+            changed = true;
+          } else {
+            failures += 1;
+          }
+        }
+        if (failures >= MAX_RAISE_FAILURES && !state.reason) {
+          state.reason = "Docker refused its raises, so this session stopped growing.";
+          changed = true;
+        }
+      }
+    }
+    record(changed);
+    await port.sleep(plan ? plan.pollMs : input.idlePollMs ?? 1e3, signal).catch(() => void 0);
+  }
+  return state;
+}
+function abortableSleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    timer.unref?.();
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+// src/launcher/protocol.ts
+var LAUNCHER_PROTOCOL = 2;
+var LAUNCHER_SECURITY = 1;
+var MEMORY_WATCH_REVISION = 1;
+var SESSION_ENV_REVISION = 1;
+var LAUNCHER_SETTINGS_PATH = "/etc/kilogent/launcher.json";
+var MAX_REQUEST_BYTES = 1024 * 1024;
+var SESSION_ENV_NAMES = Object.freeze([
+  "ANTHROPIC_BASE_URL",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  "GOOGLE_API_KEY",
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GIT_CONFIG_COUNT",
+  "GIT_CONFIG_KEY_0",
+  "GIT_CONFIG_VALUE_0",
+  "GIT_CONFIG_KEY_1",
+  "GIT_CONFIG_VALUE_1",
+  "GIT_CONFIG_KEY_2",
+  "GIT_CONFIG_VALUE_2",
+  "CREW_JOB_ID",
+  "CREW_MODEL_INPUT"
+]);
+var SESSION_ENV_SINCE = Object.freeze({ CREW_MODEL_INPUT: 1 });
+var TIERS = {
+  "no-shell": { memoryMb: 1024, cpus: 0.5, pids: 256 },
+  shell: { memoryMb: 4096, cpus: 1, pids: 2048 }
+};
+var LauncherRefusal = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LauncherRefusal";
+  }
+};
+var LEASE = /^[a-f0-9]{20}$/;
+var ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
+var MAX_ARGS = 256;
+var MAX_ARG_BYTES = 256 * 1024;
+function refuse(message) {
+  throw new LauncherRefusal(message);
+}
+function onlyKeys(doc, allowed) {
+  for (const key of Object.keys(doc)) if (!allowed.includes(key)) refuse(`Unknown field '${key}'.`);
+}
+function lease(value) {
+  return typeof value === "string" && LEASE.test(value) ? value : refuse("A lease id is 20 lowercase hex characters.");
+}
+function image(value, settings) {
+  if (typeof value !== "string") refuse("An image is required.");
+  const expected = new RegExp(`^${escapeRegExp(settings.repository)}@sha256:[a-f0-9]{64}$`);
+  return expected.test(value) ? value : refuse(`The image must be ${settings.repository}@sha256:<digest>.`);
+}
+function parseRequest(raw, settings) {
+  if (Buffer.byteLength(raw, "utf8") > MAX_REQUEST_BYTES) refuse("The request is larger than 1 MiB.");
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    refuse("The request is not JSON.");
+  }
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) refuse("The request must be a JSON object.");
+  const d = doc;
+  switch (d.op) {
+    case "info":
+    case "reap":
+      onlyKeys(d, ["op"]);
+      return { op: d.op };
+    case "prepare":
+    case "stop":
+    case "kill":
+    case "cleanup":
+      onlyKeys(d, ["op", "lease"]);
+      return { op: d.op, lease: lease(d.lease) };
+    case "inspect":
+      onlyKeys(d, ["op", "image"]);
+      return { op: "inspect", image: image(d.image, settings) };
+    case "prune": {
+      onlyKeys(d, ["op", "keep"]);
+      if (!Array.isArray(d.keep) || d.keep.length < 1 || d.keep.length > 4) refuse("keep must list one to four images.");
+      return { op: "prune", keep: d.keep.map((k) => image(k, settings)) };
+    }
+    case "pull":
+      onlyKeys(d, ["op", "image", "token"]);
+      if (typeof d.token !== "string" || !/^[A-Za-z0-9._-]{16,4096}$/.test(d.token)) refuse("A pull token is required.");
+      return { op: "pull", image: image(d.image, settings), token: d.token };
+    case "probe": {
+      onlyKeys(d, ["op", "image", "mcpUrl"]);
+      if (typeof d.mcpUrl !== "string" || !/^https?:\/\/[A-Za-z0-9.-]+(:\d+)?(\/[A-Za-z0-9._~/-]*)?$/.test(d.mcpUrl)) refuse("The MCP URL is not a plain URL.");
+      return { op: "probe", image: image(d.image, settings), mcpUrl: d.mcpUrl };
+    }
+    case "run": {
+      onlyKeys(d, ["op", "lease", "image", "bin", "args", "env", "tier", "memory"]);
+      const bin = d.bin === "claude" || d.bin === "deepagents-session" ? d.bin : refuse("The engine must be claude or deepagents-session.");
+      const tier = d.tier === "shell" || d.tier === "no-shell" ? d.tier : refuse("The tier must be shell or no-shell.");
+      if (!Array.isArray(d.args) || d.args.length > MAX_ARGS || !d.args.every((a) => typeof a === "string")) refuse("The args must be a list of strings.");
+      const args = d.args;
+      if (args.reduce((n, a) => n + Buffer.byteLength(a, "utf8"), 0) > MAX_ARG_BYTES) refuse("The args are too long.");
+      if (!d.env || typeof d.env !== "object" || Array.isArray(d.env)) refuse("The env must be an object.");
+      const env = {};
+      for (const [name, value] of Object.entries(d.env)) {
+        if (!ENV_NAME.test(name) || !SESSION_ENV_NAMES.includes(name)) refuse(`A session may not be given ${name}.`);
+        if (typeof value !== "string") refuse(`The value of ${name} must be a string.`);
+        env[name] = value;
+      }
+      let memory;
+      if (d.memory !== void 0) {
+        memory = parseGrowPlan(d.memory, TIERS[tier].memoryMb) ?? refuse(`The memory plan is not sound for a ${tier} session.`);
+      }
+      return { op: "run", lease: lease(d.lease), image: image(d.image, settings), bin, args, env, tier, ...memory ? { memory } : {} };
+    }
+    default:
+      refuse("Unknown op.");
+  }
+}
+function leaseDirs(settings, lease2) {
+  const base = `${settings.sessionsRoot.replace(/\/+$/, "")}/${settings.ownerUid}/${lease2}`;
+  return { base, work: `${base}/work`, cfg: `${base}/cfg`, home: `${base}/home`, resolv: `${base}/resolv.conf` };
+}
+var CONTAINER_WORK = "/session";
+var CONTAINER_CFG = "/session-config";
+var CONTAINER_HOME = "/home/session";
+function containerName(settings, lease2) {
+  return `kg-${settings.ownerUid}-${lease2}`;
+}
+function buildRunArgv(req, settings, opts = { resolvConf: false }) {
+  if (settings.requireRuntime && settings.runtime !== "runsc") refuse("This server requires gVisor, and its launcher is not set to runsc.");
+  const dirs = leaseDirs(settings, req.lease);
+  const tier = TIERS[req.tier];
+  const memoryMb = opts.startMb !== void 0 ? Math.min(tier.memoryMb, opts.startMb) : tier.memoryMb;
+  const argv = [
+    "run",
+    "--rm",
+    "--init",
+    "--pull",
+    "never",
+    "--name",
+    containerName(settings, req.lease),
+    "--label",
+    "com.kilogent.session=1",
+    "--label",
+    `com.kilogent.owner=${settings.ownerUid}`,
+    "--label",
+    `com.kilogent.lease=${req.lease}`,
+    "--runtime",
+    settings.runtime,
+    "--network",
+    settings.network,
+    "--user",
+    `${settings.sessionUid}:${settings.sessionGid}`,
+    "--memory",
+    `${memoryMb}m`,
+    "--memory-swap",
+    `${memoryMb}m`,
+    // If the MACHINE runs short, the kernel takes a session before the launcher, the daemon or Docker.
+    "--oom-score-adj",
+    "500",
+    "--cpus",
+    String(tier.cpus),
+    "--pids-limit",
+    String(tier.pids),
+    "--security-opt",
+    "no-new-privileges",
+    "--cap-drop",
+    "ALL"
+  ];
+  for (const name of Object.keys(req.env).sort()) argv.push("-e", name);
+  if (req.memory && opts.startMb !== void 0) argv.push("-e", `NODE_OPTIONS=${nodeOptionsFor(req.memory)}`);
+  argv.push("-e", `HOME=${CONTAINER_HOME}`, "-v", `${dirs.home}:${CONTAINER_HOME}`);
+  if (opts.resolvConf) argv.push("-v", `${dirs.resolv}:/etc/resolv.conf:ro`);
+  argv.push("-v", `${dirs.work}:${CONTAINER_WORK}`, "-v", `${dirs.cfg}:${CONTAINER_CFG}:ro`, "-w", CONTAINER_WORK);
+  const remap = (a) => a.split(dirs.cfg).join(CONTAINER_CFG).split(dirs.work).join(CONTAINER_WORK);
+  argv.push(req.image, req.bin, ...req.args.map(remap));
+  return argv;
+}
+function parseSettings(text) {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    refuse("launcher.json is not JSON.");
+  }
+  const int = (v, what) => Number.isInteger(v) && v > 0 ? v : refuse(`launcher.json: ${what} must be a positive integer.`);
+  const str = (v, re, what) => typeof v === "string" && re.test(v) ? v : refuse(`launcher.json: ${what} is not valid.`);
+  return {
+    repository: str(doc.repository, /^[a-z0-9.-]+(:\d+)?\/[a-z0-9._/-]+$/, "repository"),
+    runtime: str(doc.runtime, /^[a-z0-9-]{1,32}$/, "runtime"),
+    network: str(doc.network, /^[a-z0-9_-]{1,64}$/, "network"),
+    sessionUid: int(doc.sessionUid, "sessionUid"),
+    sessionGid: int(doc.sessionGid, "sessionGid"),
+    ownerUid: int(doc.ownerUid, "ownerUid"),
+    sessionsRoot: str(doc.sessionsRoot, /^\/[A-Za-z0-9._/-]+$/, "sessionsRoot"),
+    requireRuntime: doc.requireRuntime === true,
+    ...Number.isInteger(doc.sessionCapMb) && doc.sessionCapMb > 0 ? { sessionCapMb: doc.sessionCapMb } : {}
+  };
+}
+function runscOlder(version, min) {
+  const parse = (v) => {
+    const m = /^release-(\d{8})\.(\d+)$/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2])] : null;
+  };
+  const a = parse(version);
+  const b = parse(min);
+  if (!a || !b) return null;
+  return a[0] < b[0] || a[0] === b[0] && a[1] < b[1];
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/engines/sandbox.ts
+var DOCKER_CLI_ENV = [
+  "PATH",
+  "HOME",
+  "DOCKER_HOST",
+  "DOCKER_CONTEXT",
+  "DOCKER_CONFIG",
+  "DOCKER_CERT_PATH",
+  "DOCKER_TLS_VERIFY"
+];
+function dockerCliEnv(hostEnv) {
+  return Object.fromEntries(
+    DOCKER_CLI_ENV.filter((k) => hostEnv[k] !== void 0).map((k) => [k, hostEnv[k]])
+  );
+}
+
+// src/image/probe.ts
+function probeScript(input) {
+  return `
+const out = { cli: null, home: null, mcp: null, isolation: null };
+const cp = require('node:child_process');
+const fs = require('node:fs');
+const net = require('node:net');
+const dns = require('node:dns');
+try { cp.execFileSync('claude', ['--version'], { stdio: 'pipe', timeout: 60000 }); out.cli = true; } catch { out.cli = false; }
+try { const f = (process.env.HOME || '/nonexistent') + '/.kg-probe'; fs.writeFileSync(f, 'x'); fs.unlinkSync(f); out.home = true; } catch { out.home = false; }
+const reach = (host, port) => new Promise((resolve) => {
+  const s = net.connect({ host, port, timeout: 2500 });
+  s.on('connect', () => { s.destroy(); resolve(true); });
+  s.on('timeout', () => { s.destroy(); resolve(false); });
+  s.on('error', () => resolve(false));
+});
+(async () => {
+  try {
+    const url = new URL(${JSON.stringify(input.mcpUrl)});
+    await dns.promises.lookup(url.hostname);
+    const res = await fetch(url, { method: 'GET', signal: AbortSignal.timeout(10000) });
+    out.mcp = res.status > 0;
+  } catch { out.mcp = false; }
+  if (${input.isolation ? "true" : "false"}) {
+    const gateway = (() => { try { const line = fs.readFileSync('/proc/net/route', 'utf8').split('\\n').find((l) => l.split(/\\s+/)[1] === '00000000'); const hex = line.split(/\\s+/)[2]; return [3, 2, 1, 0].map((i) => parseInt(hex.slice(i * 2, i * 2 + 2), 16)).join('.'); } catch { return '172.17.0.1'; } })();
+    const reached = await Promise.all([reach('169.254.169.254', 80), reach('10.0.0.1', 80), reach('192.168.0.1', 80), reach(gateway, 22), reach(gateway, 80)]);
+    out.isolation = reached.every((r) => !r);
+  }
+  process.stdout.write(JSON.stringify(out) + '\\n');
+})();
+`;
+}
+function parseProbeOutput(stdout, now) {
+  const line = stdout.trim().split("\n").reverse().find((l) => l.trim().startsWith("{"));
+  if (!line) return null;
+  try {
+    const doc = JSON.parse(line);
+    const tri = (v) => v === true ? true : v === false ? false : null;
+    return { cli: tri(doc.cli), home: tri(doc.home), mcp: tri(doc.mcp), isolation: tri(doc.isolation), at: now, detail: "" };
+  } catch {
+    return null;
+  }
+}
+async function probeImage(input) {
+  const now = input.now ?? Date.now;
+  const args = [
+    "run",
+    "--rm",
+    "--init",
+    "--pull",
+    "never",
+    "--label",
+    "com.kilogent.probe=1",
+    "--user",
+    input.user,
+    "--memory",
+    "512m",
+    "--memory-swap",
+    "512m",
+    ...input.runtime ? ["--runtime", input.runtime] : [],
+    ...input.network ? ["--network", input.network] : [],
+    ...input.extraArgs ?? [],
+    input.image,
+    "node",
+    "-e",
+    probeScript({ mcpUrl: input.mcpUrl, isolation: input.isolation })
+  ];
+  const result = await runCommand("docker", args, { env: dockerCliEnv(input.env ?? process.env), timeoutMs: 12e4 });
+  const parsed = parseProbeOutput(result.stdout, now());
+  if (parsed) return parsed;
+  return {
+    cli: false,
+    home: null,
+    mcp: null,
+    isolation: null,
+    at: now(),
+    detail: (result.stderr || "The probe container did not answer.").trim().split("\n")[0]?.slice(0, 200) ?? ""
+  };
+}
+
+// src/provision/host.ts
+var SUPPORTED_HOSTS = Object.freeze([
+  { id: "ubuntu", versionId: "22.04", codename: "jammy" },
+  { id: "ubuntu", versionId: "24.04", codename: "noble" },
+  { id: "debian", versionId: "12", codename: "bookworm" }
+]);
+var SESSION_BRIDGE = "kg-sessions";
+var FIREWALL_CHAIN = "KG-SESSIONS";
+var BLOCKED_RANGES = Object.freeze(["169.254.0.0/16", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16", "100.64.0.0/10"]);
+function firewallStatus(iptablesS, resolvers, bridge = SESSION_BRIDGE) {
+  const rules = iptablesS.split("\n").map((l) => l.trim().split(/\s+/)).filter((t) => t.length > 1);
+  const has = (tokens, flag, value) => tokens.some((t, i) => t === flag && tokens[i + 1] === value);
+  const chain = rules.some((t) => t[0] === "-N" && t[1] === FIREWALL_CHAIN);
+  const ruleIn = (chain2, target) => rules.some((t) => t[0] === "-A" && t[1] === chain2 && has(t, "-i", bridge) && has(t, "-j", target));
+  const own = rules.filter((t) => t[0] === "-A" && t[1] === FIREWALL_CHAIN);
+  const dnsFor = (r, proto) => own.some((t) => has(t, "-d", `${r}/32`) && has(t, "-p", proto) && has(t, "--dport", "53") && has(t, "-j", "RETURN"));
+  const drops = BLOCKED_RANGES.every((range) => own.some((t) => has(t, "-d", range) && has(t, "-j", "DROP")));
+  return {
+    chain: chain && drops,
+    jumps: ruleIn("DOCKER-USER", FIREWALL_CHAIN) && ruleIn("INPUT", "DROP"),
+    dns: resolvers.length > 0 && resolvers.every((r) => dnsFor(r, "udp") && dnsFor(r, "tcp"))
+  };
+}
+function resolversFrom(resolvConf) {
+  return resolvConf.split("\n").map((l) => /^\s*nameserver\s+(\d{1,3}(?:\.\d{1,3}){3})\s*$/.exec(l)?.[1]).filter((r) => Boolean(r) && !r.startsWith("127."));
+}
+function sessionResolvConf(resolvers) {
+  const unique = [...new Set(resolvers)].slice(0, 3);
+  return unique.length ? `${unique.map((r) => `nameserver ${r}`).join("\n")}
+options ndots:0
+` : null;
+}
+
+// src/launcher/handler.ts
+function rootOwnedDir(dir) {
+  try {
+    const st = fs.lstatSync(dir);
+    return st.isDirectory() && !st.isSymbolicLink() && st.uid === 0 && (st.mode & 18) === 0;
+  } catch {
+    return false;
+  }
+}
+var HandlerFailure = class extends Error {
+};
+function prepare(settings, lease2, ctx) {
+  if (ctx.root && !rootOwnedDir(settings.sessionsRoot)) {
+    throw new HandlerFailure(`${settings.sessionsRoot} must be a root-owned directory that only root can write.`);
+  }
+  if (!ctx.root) fs.mkdirSync(settings.sessionsRoot, { recursive: true, mode: 493 });
+  const ownerDir = path.join(settings.sessionsRoot, String(settings.ownerUid));
+  if (!fs.existsSync(ownerDir)) fs.mkdirSync(ownerDir, { mode: 493 });
+  if (ctx.root && !rootOwnedDir(ownerDir)) throw new HandlerFailure(`${ownerDir} must be a root-owned directory that only root can write.`);
+  const dirs = leaseDirs(settings, lease2);
+  fs.rmSync(dirs.base, { recursive: true, force: true });
+  fs.mkdirSync(dirs.base, { mode: 493 });
+  fs.mkdirSync(dirs.work);
+  fs.mkdirSync(dirs.cfg);
+  fs.mkdirSync(dirs.home);
+  fs.chmodSync(dirs.home, 448);
+  fs.chmodSync(dirs.work, 1528);
+  fs.chmodSync(dirs.cfg, 1512);
+  if (ctx.root) {
+    fs.chownSync(dirs.work, settings.sessionUid, ctx.ownerGid);
+    fs.chownSync(dirs.cfg, settings.ownerUid, settings.sessionGid);
+    fs.chownSync(dirs.home, settings.sessionUid, settings.sessionGid);
+  }
+  writeResolvConf(dirs.resolv, ctx);
+  return { workdir: dirs.work, configDir: dirs.cfg };
+}
+function writeResolvConf(file, ctx) {
+  let resolvers = [];
+  try {
+    resolvers = resolversFrom(ctx.resolvConf());
+  } catch {
+    resolvers = [];
+  }
+  const text = sessionResolvConf(resolvers);
+  if (!text) return false;
+  fs.writeFileSync(file, text, { mode: 420 });
+  return true;
+}
+async function docker(args, ctx, timeoutMs = 6e4) {
+  return runCommand("docker", args, { env: ctx.dockerEnv, timeoutMs });
+}
+function goneOrRemoved(result) {
+  return result.ok || /no such container/i.test(result.stderr);
+}
+async function info(settings, ctx) {
+  const out = {
+    protocol: LAUNCHER_PROTOCOL,
+    security: LAUNCHER_SECURITY,
+    memoryWatch: MEMORY_WATCH_REVISION,
+    sessionEnv: SESSION_ENV_REVISION,
+    runtime: settings.runtime,
+    network: settings.network,
+    repository: settings.repository,
+    requireRuntime: settings.requireRuntime,
+    docker: { answers: false, detail: "" },
+    firewall: null,
+    runsc: null
+  };
+  const dockerInfo = await docker(["info", "--format", "{{json .}}"], ctx, 15e3);
+  if (!dockerInfo.ok) {
+    out.docker = { answers: false, detail: dockerInfo.stderr.trim().split("\n")[0]?.slice(0, 200) || "docker info did not answer." };
+  } else {
+    let doc = {};
+    try {
+      doc = JSON.parse(dockerInfo.stdout);
+    } catch {
+    }
+    out.docker = {
+      answers: true,
+      detail: "Docker answered.",
+      ...typeof doc.ServerVersion === "string" ? { serverVersion: doc.ServerVersion } : {},
+      ...doc.Runtimes && typeof doc.Runtimes === "object" ? { runtimes: Object.keys(doc.Runtimes).sort() } : {},
+      ...typeof doc.LiveRestoreEnabled === "boolean" ? { liveRestore: doc.LiveRestoreEnabled } : {},
+      ...typeof doc.MemTotal === "number" ? { memTotalBytes: doc.MemTotal } : {}
+    };
+    const version = await docker(["version", "--format", "{{json .Server.Components}}"], ctx, 15e3);
+    try {
+      const components = JSON.parse(version.stdout);
+      const containerd = components?.find((c) => c.Name === "containerd")?.Version;
+      if (containerd) out.docker.containerd = containerd.replace(/^v/, "");
+    } catch {
+    }
+    const network = await docker(["network", "inspect", settings.network, "--format", "{{json .Options}}"], ctx, 15e3);
+    out.docker.sessionNetwork = network.ok;
+    if (network.ok) {
+      try {
+        const options = JSON.parse(network.stdout);
+        out.docker.iccDisabled = options?.["com.docker.network.bridge.enable_icc"] === "false";
+      } catch {
+        out.docker.iccDisabled = false;
+      }
+    }
+  }
+  if (ctx.root) {
+    const saved = await runCommand("iptables", ["-S"], { env: ctx.dockerEnv, timeoutMs: 15e3 });
+    if (saved.ok) {
+      let resolvers = [];
+      try {
+        resolvers = resolversFrom(ctx.resolvConf());
+      } catch {
+        resolvers = [];
+      }
+      out.firewall = firewallStatus(saved.stdout, resolvers, settings.network);
+    }
+  }
+  const runsc = await runCommand("runsc", ["--version"], { env: ctx.dockerEnv, timeoutMs: 15e3 });
+  const match = runsc.ok ? /runsc version (\S+)/.exec(runsc.stdout) : null;
+  out.runsc = match?.[1] ?? null;
+  return out;
+}
+function memoryFilePath(settings, lease2) {
+  return path.join(leaseDirs(settings, lease2).base, "memory.json");
+}
+function writeMemoryFile(file, state) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.rmSync(tmp, { force: true });
+    const fd = fs.openSync(tmp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 420);
+    try {
+      fs.writeSync(fd, `${JSON.stringify(state)}
+`);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, file);
+  } catch {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+var MEMORY_FILE_FRESH_MS = 3e4;
+function sessionsUsedMb(settings, now) {
+  const owner = path.join(settings.sessionsRoot, String(settings.ownerUid));
+  let sum = 0;
+  let leases = [];
+  try {
+    leases = fs.readdirSync(owner);
+  } catch {
+    return 0;
+  }
+  for (const lease2 of leases) {
+    try {
+      const doc = JSON.parse(fs.readFileSync(path.join(owner, lease2, "memory.json"), "utf8"));
+      if (doc.running !== true || typeof doc.updatedAt !== "number" || now - doc.updatedAt > MEMORY_FILE_FRESH_MS) continue;
+      sum += typeof doc.peakMb === "number" && doc.peakMb > 0 ? Number(doc.usedMb) || 0 : Number(doc.startMb) || 0;
+    } catch {
+    }
+  }
+  return sum;
+}
+async function growDecision(req, settings, ctx) {
+  if (!req.memory) return { plan: null, reason: "Sessions do not grow on this server." };
+  if (settings.runtime === "runsc") {
+    const out = await runCommand("runsc", ["--version"], { env: ctx.dockerEnv, timeoutMs: 15e3 });
+    const version = out.ok ? /runsc version (\S+)/.exec(out.stdout)?.[1] : void 0;
+    if (!version || runscOlder(version, RUNSC_LIVE_MEMORY_MIN) !== false) {
+      return { plan: null, reason: `gVisor ${version ?? "(unknown)"} cannot raise a running session's memory; it needs ${RUNSC_LIVE_MEMORY_MIN}.` };
+    }
+  }
+  return { plan: req.memory, reason: null };
+}
+async function run(req, settings, ctx) {
+  const decision = await growDecision(req, settings, ctx);
+  const argv = buildRunArgv(req, settings, {
+    resolvConf: fs.existsSync(leaseDirs(settings, req.lease).resolv),
+    ...decision.plan ? { startMb: decision.plan.startMb } : {}
+  });
+  const name = containerName(settings, req.lease);
+  const file = memoryFilePath(settings, req.lease);
+  const state = initialMemoryState({ tier: req.tier, plan: decision.plan, ceilingMb: TIERS[req.tier].memoryMb, reason: decision.reason, now: Date.now() });
+  writeMemoryFile(file, state);
+  const controller = new AbortController();
+  const oom = watchContainerOom(ctx.dockerSocket, name, controller.signal);
+  let stopped = false;
+  const cap = settings.sessionCapMb;
+  const watching = watchMemory({
+    state,
+    plan: decision.plan,
+    signal: controller.signal,
+    port: {
+      sample: () => containerMemory(ctx.dockerSocket, name),
+      apply: (mb) => updateContainerMemory(ctx.dockerSocket, name, mb),
+      ...cap ? { mayRaise: async (fromMb, toMb) => toMb <= fromMb || sessionsUsedMb(settings, Date.now()) + (toMb - fromMb) <= cap } : {},
+      onChange: (next) => writeMemoryFile(file, next),
+      now: Date.now,
+      sleep: abortableSleep
+    }
+  });
+  const code = await new Promise((resolve) => {
+    const child = spawn("docker", argv, { stdio: ["ignore", "inherit", "inherit"], env: { ...ctx.dockerEnv, ...req.env } });
+    const forward = (signal) => () => {
+      stopped = true;
+      child.kill(signal);
+    };
+    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(signal, forward(signal));
+    child.on("error", (e) => {
+      process.stderr.write(`kg-session-launcher: docker did not start: ${e.message}
+`);
+      resolve(127);
+    });
+    child.on("exit", (exit, signal) => resolve(exit ?? (signal ? 143 : 1)));
+  });
+  controller.abort();
+  const last = await watching;
+  writeMemoryFile(file, {
+    ...last,
+    running: false,
+    oom: classifyExit({ exitCode: code, oomEvent: oom.seen(), stopped, lastUsedMb: last.usedMb, limitMb: last.limitMb, maxMb: last.maxMb }),
+    updatedAt: Date.now()
+  });
+  return code;
+}
+async function handleRequest(req, settings, ctx, out) {
+  try {
+    switch (req.op) {
+      case "info":
+        out.write(JSON.stringify(await info(settings, ctx)));
+        return 0;
+      case "prepare":
+        out.write(JSON.stringify(prepare(settings, req.lease, ctx)));
+        return 0;
+      case "run": {
+        await docker(["rm", "--force", containerName(settings, req.lease)], ctx);
+        return await run(req, settings, ctx);
+      }
+      case "stop":
+        return goneOrRemoved(await docker(["stop", "--time", "10", containerName(settings, req.lease)], ctx)) ? 0 : 1;
+      case "kill":
+        return goneOrRemoved(await docker(["rm", "--force", containerName(settings, req.lease)], ctx)) ? 0 : 1;
+      case "reap": {
+        const listed = await docker(["ps", "--all", "--quiet", "--filter", "label=com.kilogent.session=1", "--filter", `label=com.kilogent.owner=${settings.ownerUid}`], ctx);
+        const ids = listed.stdout.split("\n").map((l) => l.trim()).filter((l) => /^[a-f0-9]{12,64}$/.test(l));
+        const removed = ids.length ? await docker(["rm", "--force", ...ids], ctx) : { ok: true };
+        out.write(JSON.stringify({ removed: removed.ok ? ids.length : 0, found: ids.length }));
+        return listed.ok && removed.ok ? 0 : 1;
+      }
+      case "cleanup":
+        fs.rmSync(leaseDirs(settings, req.lease).base, { recursive: true, force: true });
+        return 0;
+      case "inspect": {
+        const present = await imagePresent(ctx.dockerSocket, req.image);
+        out.write(JSON.stringify({ present }));
+        return present === null ? 1 : 0;
+      }
+      case "prune": {
+        const present = await listRepositoryImages(ctx.dockerSocket, settings.repository);
+        let removed = 0;
+        for (const ref of imagesToRemove(present, req.keep)) if (await removeImage(ctx.dockerSocket, ref)) removed += 1;
+        out.write(JSON.stringify({ removed }));
+        return 0;
+      }
+      case "pull": {
+        const ref = parseDigestRef(req.image, { allowLocalRegistry: ctx.allowLocalRegistry });
+        if (!ref) {
+          out.write(JSON.stringify({ ok: false, kind: "registry", message: "The image is not a digest reference." }));
+          return 1;
+        }
+        const result = await pullByDigest({ socketPath: ctx.dockerSocket, image: ref, token: req.token });
+        out.write(JSON.stringify(result));
+        return result.ok ? 0 : 1;
+      }
+      case "probe": {
+        const home = path.join(settings.sessionsRoot, String(settings.ownerUid), `probe-home-${process.pid}`);
+        fs.rmSync(home, { recursive: true, force: true });
+        fs.mkdirSync(home, { recursive: true, mode: 448 });
+        fs.chmodSync(home, 448);
+        if (ctx.root) fs.chownSync(home, settings.sessionUid, settings.sessionGid);
+        const resolv = `${home}.resolv.conf`;
+        const dns = writeResolvConf(resolv, ctx) ? ["-v", `${resolv}:/etc/resolv.conf:ro`] : [];
+        try {
+          const result = await probeImage({
+            image: req.image,
+            mcpUrl: req.mcpUrl,
+            user: `${settings.sessionUid}:${settings.sessionGid}`,
+            runtime: settings.runtime,
+            network: settings.network,
+            isolation: true,
+            env: ctx.dockerEnv,
+            extraArgs: ["-e", `HOME=${CONTAINER_HOME}`, "-v", `${home}:${CONTAINER_HOME}`, ...dns]
+          });
+          out.write(JSON.stringify(result));
+          return 0;
+        } finally {
+          fs.rmSync(home, { recursive: true, force: true });
+          fs.rmSync(resolv, { force: true });
+        }
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`kg-session-launcher: ${e instanceof Error ? e.message : String(e)}
+`);
+    return 2;
+  }
+}
+async function readRequestText(max) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    total += buf.length;
+    if (total > max) throw new HandlerFailure("The request is larger than 1 MiB.");
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// src/launcher/main.ts
+var ROOT_PATH = "/usr/sbin:/usr/bin:/sbin:/bin";
+function fail(message, code = 2) {
+  process.stderr.write(`kg-session-launcher: ${message}
+`);
+  process.exit(code);
+}
+function ownerGid(uid) {
+  const out = spawnSync("id", ["-g", String(uid)], { encoding: "utf8", env: { PATH: ROOT_PATH } });
+  const gid = Number(out.stdout.trim());
+  return Number.isInteger(gid) && gid > 0 ? gid : fail("Could not read the service user\u2019s group.");
+}
+async function main() {
+  if (typeof process.getuid !== "function" || process.getuid() !== 0) fail("This runs as root, through sudo.");
+  process.umask(18);
+  let settings;
+  try {
+    settings = parseSettings(fs2.readFileSync(LAUNCHER_SETTINGS_PATH, "utf8"));
+  } catch (e) {
+    fail(e instanceof Error ? e.message : String(e));
+  }
+  const caller = Number(process.env.SUDO_UID);
+  if (!Number.isInteger(caller) || caller !== settings.ownerUid) fail("Only the Kilogent service user may ask this launcher for anything.");
+  let req;
+  try {
+    req = parseRequest(await readRequestText(MAX_REQUEST_BYTES), settings);
+  } catch (e) {
+    fail(e instanceof LauncherRefusal ? e.message : e instanceof Error ? e.message : String(e));
+  }
+  const code = await handleRequest(
+    req,
+    settings,
+    {
+      root: true,
+      dockerSocket: "/var/run/docker.sock",
+      dockerEnv: { PATH: ROOT_PATH },
+      allowLocalRegistry: false,
+      ownerGid: ownerGid(settings.ownerUid),
+      // The same two files provision reads: on Ubuntu `/etc/resolv.conf` names only systemd-resolved's local
+      // stub, and the real upstream resolvers are in the other one.
+      resolvConf: () => ["/run/systemd/resolve/resolv.conf", "/etc/resolv.conf"].map((file) => {
+        try {
+          return fs2.readFileSync(file, "utf8");
+        } catch {
+          return "";
+        }
+      }).join("\n")
+    },
+    { write: (line) => process.stdout.write(`${line}
+`) }
+  );
+  process.exit(code);
+}
+void main();