@kosa8/sdk 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,990 @@
+// src/checkpoints.ts
+import { promises as fs } from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// src/errors.ts
+var Kosa8Error = class extends Error {
+  /** HTTP status the daemon answered with, when there was an answer. */
+  status;
+  /** The daemon's `error` text, verbatim. */
+  daemonMessage;
+  /** The daemon's `remediation` text: what to do about it. */
+  remediation;
+  method;
+  path;
+  /** The decoded response body, when there was one. */
+  body;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = new.target.name;
+    this.status = options.status;
+    this.daemonMessage = options.daemonMessage;
+    this.remediation = options.remediation;
+    this.method = options.method;
+    this.path = options.path;
+    this.body = options.body;
+  }
+};
+var Kosa8ConnectionError = class extends Kosa8Error {
+};
+var Kosa8ApiError = class extends Kosa8Error {
+};
+var Kosa8BadRequestError = class extends Kosa8ApiError {
+};
+var Kosa8AuthError = class extends Kosa8ApiError {
+};
+var Kosa8PolicyError = class extends Kosa8ApiError {
+};
+var Kosa8ApprovalRequiredError = class extends Kosa8PolicyError {
+  approval;
+  constructor(message, approval, options = {}) {
+    super(message, options);
+    this.approval = approval;
+  }
+};
+var Kosa8NotFoundError = class extends Kosa8ApiError {
+};
+var Kosa8ConflictError = class extends Kosa8ApiError {
+};
+var Kosa8UnsupportedError = class extends Kosa8ApiError {
+};
+var Kosa8StreamError = class extends Kosa8Error {
+  stdout;
+  stderr;
+  constructor(message, out, options = {}) {
+    super(message, options);
+    this.stdout = out.stdout;
+    this.stderr = out.stderr;
+  }
+};
+var Kosa8CheckpointError = class extends Kosa8Error {
+};
+function isRefusal(v) {
+  return typeof v === "object" && v !== null && typeof v.why === "string";
+}
+function errorFromResponse(status, body, ctx = {}) {
+  let daemonMessage;
+  let remediation;
+  let approval;
+  if (typeof body === "object" && body !== null) {
+    const b = body;
+    if (typeof b.error === "string" && b.error !== "") daemonMessage = b.error;
+    else if (typeof b.message === "string" && b.message !== "") daemonMessage = b.message;
+    if (typeof b.remediation === "string" && b.remediation !== "") remediation = b.remediation;
+    approval = b.approval;
+  } else if (typeof body === "string" && body.trim() !== "") {
+    daemonMessage = body.trim();
+  }
+  const base = daemonMessage ?? `request failed with HTTP ${status}`;
+  const message = remediation ? `${base} (${remediation})` : base;
+  const opts = { status, daemonMessage, remediation, body, ...ctx };
+  if (status === 403 && isRefusal(approval)) {
+    return new Kosa8ApprovalRequiredError(message, approval, opts);
+  }
+  switch (status) {
+    case 400:
+      return new Kosa8BadRequestError(message, opts);
+    case 401:
+      return new Kosa8AuthError(message, opts);
+    case 403:
+      return new Kosa8PolicyError(message, opts);
+    case 404:
+      return new Kosa8NotFoundError(message, opts);
+    case 409:
+      return new Kosa8ConflictError(message, opts);
+    case 501:
+      return new Kosa8UnsupportedError(message, opts);
+    default:
+      return new Kosa8ApiError(message, opts);
+  }
+}
+
+// src/checkpoints.ts
+var MAX_CHECKPOINTS_PER_SANDBOX = 10;
+function validateSandboxName(name) {
+  if (name === "" || name === "." || name === ".." || /[/\\]/.test(name) || name.startsWith(".")) {
+    throw new Kosa8CheckpointError(`invalid sandbox name ${JSON.stringify(name)}`);
+  }
+}
+var MemoryCheckpointStore = class {
+  data = {};
+  queue = Promise.resolve();
+  async load() {
+    return structuredClone(this.data);
+  }
+  update(fn) {
+    const run = this.queue.then(async () => {
+      const copy = structuredClone(this.data);
+      const out = await fn(copy);
+      this.data = copy;
+      return out;
+    });
+    this.queue = run.catch(() => void 0);
+    return run;
+  }
+};
+var FileCheckpointStore = class {
+  path;
+  queue = Promise.resolve();
+  constructor(filePath) {
+    this.path = filePath ?? path.join(os.homedir(), ".kosa8", "checkpoints.json");
+  }
+  async load() {
+    let buf;
+    try {
+      buf = await fs.readFile(this.path, "utf8");
+    } catch (err) {
+      if (err.code === "ENOENT") return {};
+      throw err;
+    }
+    try {
+      const parsed = JSON.parse(buf);
+      return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  update(fn) {
+    const run = this.queue.then(() => this.locked(fn));
+    this.queue = run.catch(() => void 0);
+    return run;
+  }
+  async locked(fn) {
+    await fs.mkdir(path.dirname(this.path), { recursive: true, mode: 448 });
+    const lock = this.path + ".node.lock";
+    const deadline = Date.now() + 1e4;
+    for (; ; ) {
+      try {
+        const h = await fs.open(lock, "wx", 384);
+        await h.close();
+        break;
+      } catch (err) {
+        if (err.code !== "EEXIST") throw err;
+        try {
+          const st = await fs.stat(lock);
+          if (Date.now() - st.mtimeMs > 3e4) {
+            await fs.rm(lock, { force: true });
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() > deadline) throw new Kosa8CheckpointError(`timed out waiting for the checkpoint store lock ${lock}`);
+        await new Promise((r) => setTimeout(r, 25));
+      }
+    }
+    try {
+      const data = await this.load();
+      const out = await fn(data);
+      const tmp = this.path + ".tmp";
+      await fs.writeFile(tmp, JSON.stringify(data, null, 2), { mode: 384 });
+      await fs.rename(tmp, this.path);
+      return out;
+    } finally {
+      await fs.rm(lock, { force: true });
+    }
+  }
+};
+function seqOf(id, sandbox) {
+  const pre = sandbox + "-ckpt-";
+  if (!id.startsWith(pre)) return 0;
+  const m = /^(\d+)/.exec(id.slice(pre.length));
+  return m ? Number(m[1]) : 0;
+}
+function sorted(list) {
+  return list.map((c, i) => ({ c, i, t: Date.parse(c.created) || 0 })).sort((a, b) => a.t - b.t || a.i - b.i).map((x) => x.c);
+}
+var CheckpointBook = class {
+  constructor(store) {
+    this.store = store;
+  }
+  /** The snapshot id the next checkpoint should use, and ids to evict to stay under the cap. */
+  async nextId(sandbox) {
+    validateSandboxName(sandbox);
+    const list = (await this.store.load())[sandbox] ?? [];
+    let n = list.length + 1;
+    for (const c of list) {
+      const v = seqOf(c.id, sandbox);
+      if (v >= n) n = v + 1;
+    }
+    const evict = [];
+    const over = list.length + 1 - MAX_CHECKPOINTS_PER_SANDBOX;
+    if (over > 0) for (const c of list.slice(0, over)) evict.push(c.id);
+    return { id: `${sandbox}-ckpt-${n}`, evict };
+  }
+  async record(c, evicted = []) {
+    validateSandboxName(c.sandbox);
+    const rec = {
+      id: c.id,
+      sandbox: c.sandbox,
+      label: c.label ?? "",
+      ...c.auto ? { auto: true } : {},
+      created: c.created ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.store.update((s) => {
+      const drop = new Set(evicted);
+      s[c.sandbox] = [...(s[c.sandbox] ?? []).filter((e) => !drop.has(e.id)), rec];
+    });
+    return rec;
+  }
+  async list(sandbox) {
+    return sorted([...(await this.store.load())[sandbox] ?? []]);
+  }
+  async latest(sandbox) {
+    const list = await this.list(sandbox);
+    if (list.length === 0) {
+      throw new Kosa8CheckpointError(
+        `no checkpoints for ${JSON.stringify(sandbox)} \u2014 take one with checkpoint() or \`kosa8 checkpoint ${sandbox}\``
+      );
+    }
+    return list[list.length - 1];
+  }
+  /** Find by id or (case-insensitive) label, newest match first. */
+  async resolve(sandbox, ref) {
+    const list = await this.list(sandbox);
+    for (let i = list.length - 1; i >= 0; i--) {
+      const c = list[i];
+      if (c.id === ref || c.label.toLowerCase() === ref.toLowerCase()) return c;
+    }
+    throw new Kosa8CheckpointError(`no checkpoint ${JSON.stringify(ref)} for sandbox ${JSON.stringify(sandbox)}`);
+  }
+  /** Keep `id` as the top of the stack; return the ids taken after it (now meaningless). */
+  async pop(sandbox, id) {
+    return this.store.update((s) => {
+      const list = s[sandbox] ?? [];
+      const idx = list.findIndex((c) => c.id === id);
+      if (idx < 0) throw new Kosa8CheckpointError(`no checkpoint ${JSON.stringify(id)} for sandbox ${JSON.stringify(sandbox)}`);
+      const orphaned = list.slice(idx + 1).map((c) => c.id);
+      s[sandbox] = list.slice(0, idx + 1);
+      return orphaned;
+    });
+  }
+  /** Drop every checkpoint of a sandbox; return the snapshot ids to delete. */
+  async forget(sandbox) {
+    return this.store.update((s) => {
+      const ids = (s[sandbox] ?? []).map((c) => c.id);
+      delete s[sandbox];
+      return ids;
+    });
+  }
+};
+
+// src/transport.ts
+import * as http from "http";
+import * as https from "https";
+import * as os2 from "os";
+import * as path2 from "path";
+var APPROVAL_HEADER = "X-Kosa8-Approval";
+var ACTOR_HEADER = "X-Kosa8-Actor";
+var AGENT_TOKEN_HEADER = "X-Kosa8-Agent-Token";
+function defaultSocketPath() {
+  return path2.join(os2.homedir(), ".kosa8", "run", "kosa8.sock");
+}
+function isLoopback(hostname) {
+  const h = hostname.replace(/^\[|\]$/g, "");
+  return h === "localhost" || h === "::1" || /^127\./.test(h);
+}
+function resolveEndpoint(opts) {
+  const env = opts.env ?? process.env;
+  const fromEnv = (env.KOSA8_HOST ?? "").trim();
+  const raw = (opts.host ?? fromEnv).trim().replace(/\/+$/, "");
+  if (raw === "") {
+    return { kind: "unix", socketPath: opts.socketPath ?? defaultSocketPath() };
+  }
+  let h = raw;
+  const i = h.indexOf("://");
+  if (i > 0) h = h.slice(0, i).toLowerCase() + h.slice(i);
+  if (h.startsWith("unix://")) {
+    return { kind: "unix", socketPath: h.slice("unix://".length) };
+  }
+  if (h.startsWith("tcp://")) h = "http://" + h.slice("tcp://".length);
+  else if (!h.startsWith("http://") && !h.startsWith("https://")) {
+    if (h.includes("://")) {
+      throw new Kosa8Error(
+        `KOSA8_HOST scheme "${h.slice(0, h.indexOf("://"))}" is not supported; use http://, https://, tcp:// or unix://`
+      );
+    }
+    h = "http://" + h;
+  }
+  const url = new URL(h);
+  const insecure = opts.insecure === true || env.KOSA8_INSECURE === "1";
+  if (url.protocol === "http:" && !insecure && !isLoopback(url.hostname)) {
+    throw new Kosa8Error(
+      `refusing to talk to ${url.host} over plain http: the token and every request would cross the network unencrypted. Use https://${url.host} (a worker behind a TLS-terminating tunnel or proxy), or set insecure: true / KOSA8_INSECURE=1 if this link is already private and trusted`
+    );
+  }
+  const token = opts.token ?? (opts.host === void 0 && fromEnv !== "" ? env.KOSA8_TOKEN : void 0);
+  return { kind: "tcp", url, token: token || void 0 };
+}
+var Transport = class {
+  endpoint;
+  actor;
+  agentToken;
+  extraHeaders;
+  constructor(opts = {}) {
+    this.endpoint = resolveEndpoint(opts);
+    this.actor = opts.actor ?? "tool";
+    const env = opts.env ?? process.env;
+    this.agentToken = opts.agentToken ?? (env.KOSA8_AGENT_TOKEN || void 0);
+    this.extraHeaders = { ...opts.headers ?? {} };
+  }
+  /** Human-readable description of where requests go. */
+  get target() {
+    return this.endpoint.kind === "unix" ? `unix://${this.endpoint.socketPath}` : this.endpoint.url.origin;
+  }
+  buildPath(p, query) {
+    const base = this.endpoint.kind === "tcp" ? this.endpoint.url.pathname.replace(/\/+$/, "") : "";
+    let out = base + p;
+    if (query) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (v === void 0 || v === false) continue;
+        qs.set(k, v === true ? "1" : String(v));
+      }
+      const s = qs.toString();
+      if (s) out += "?" + s;
+    }
+    return out;
+  }
+  /** Send a request and return the raw response once headers arrive. */
+  raw(method, p, opts = {}) {
+    const headers = {
+      Accept: "application/json",
+      [ACTOR_HEADER]: this.actor,
+      ...this.extraHeaders,
+      ...opts.headers ?? {}
+    };
+    if (opts.approval && opts.approval.trim() !== "") headers[APPROVAL_HEADER] = opts.approval.trim();
+    if (this.agentToken) headers[AGENT_TOKEN_HEADER] = this.agentToken;
+    let payload;
+    let streamBody;
+    if (opts.rawBody !== void 0) {
+      headers["Content-Type"] = "application/octet-stream";
+      if (typeof opts.rawBody === "string" || opts.rawBody instanceof Uint8Array) {
+        payload = Buffer.from(opts.rawBody);
+        headers["Content-Length"] = String(payload.length);
+      } else {
+        streamBody = opts.rawBody;
+      }
+    } else if (opts.body !== void 0) {
+      payload = Buffer.from(JSON.stringify(opts.body));
+      headers["Content-Type"] = "application/json";
+      headers["Content-Length"] = String(payload.length);
+    } else if (method !== "GET" && method !== "HEAD") {
+      headers["Content-Length"] = "0";
+    }
+    const reqPath = this.buildPath(p, opts.query);
+    let reqOpts;
+    let mod = http;
+    if (this.endpoint.kind === "unix") {
+      reqOpts = { socketPath: this.endpoint.socketPath, path: reqPath, method, headers: { Host: "kosa8", ...headers } };
+    } else {
+      const u = this.endpoint.url;
+      if (this.endpoint.token) headers.Authorization = `Bearer ${this.endpoint.token}`;
+      mod = u.protocol === "https:" ? https : http;
+      reqOpts = { protocol: u.protocol, hostname: u.hostname, port: u.port || void 0, path: reqPath, method, headers };
+    }
+    return new Promise((resolve, reject) => {
+      const signal = opts.signal;
+      if (signal?.aborted) {
+        reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+        return;
+      }
+      const req = mod.request(reqOpts, (res) => {
+        resolve({ status: res.statusCode ?? 0, headers: res.headers, stream: res });
+      });
+      const onAbort = () => {
+        req.destroy(signal?.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError"));
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      req.on("close", () => signal?.removeEventListener("abort", onAbort));
+      req.on("error", (err) => {
+        if (signal?.aborted) {
+          reject(signal.reason ?? err);
+          return;
+        }
+        reject(
+          new Kosa8ConnectionError(
+            `kosa8 daemon unreachable at ${this.target}: ${err.message}` + (err.code === "ENOENT" || err.code === "ECONNREFUSED" ? " (is kosa8 installed and its daemon running? start it with `kosa8 daemon start`)" : ""),
+            { method, path: p, cause: err }
+          )
+        );
+      });
+      if (streamBody) {
+        const src = streamBody;
+        void (async () => {
+          try {
+            for await (const chunk of src) {
+              if (!req.write(chunk)) await new Promise((r) => req.once("drain", r));
+            }
+            req.end();
+          } catch (err) {
+            req.destroy(err);
+          }
+        })();
+        return;
+      }
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+  /** Send a request and decode a JSON answer; HTTP errors become typed errors. */
+  async json(method, p, opts = {}) {
+    const res = await this.raw(method, p, opts);
+    const text = (await readAll(res.stream, opts.signal)).toString("utf8");
+    let body = void 0;
+    if (text.trim() !== "") {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+    }
+    if (res.status >= 400) throw errorFromResponse(res.status, body, { method, path: p });
+    return body;
+  }
+  /**
+   * Send a request whose answer is a stream of NDJSON frames (run, exec,
+   * attach). HTTP errors (a refusal before streaming began) become typed
+   * errors; each frame's base64 `data` is decoded to a Buffer.
+   */
+  async *frames(method, p, opts = {}) {
+    const res = await this.raw(method, p, opts);
+    if (res.status >= 400) {
+      const text = (await readAll(res.stream, opts.signal)).toString("utf8");
+      let body = text;
+      try {
+        body = JSON.parse(text);
+      } catch {
+      }
+      throw errorFromResponse(res.status, body, { method, path: p });
+    }
+    let buf = "";
+    try {
+      for await (const chunk of res.stream) {
+        buf += chunk.toString("utf8");
+        let nl;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (line !== "") yield decodeFrame(line);
+        }
+      }
+    } catch (err) {
+      if (opts.signal?.aborted) throw opts.signal.reason ?? err;
+      throw err;
+    } finally {
+      res.stream.destroy();
+    }
+    const rest = buf.trim();
+    if (rest !== "") yield decodeFrame(rest);
+  }
+};
+function decodeFrame(line) {
+  const f = JSON.parse(line);
+  const out = { ...f };
+  if (typeof f.data === "string") out.data = Buffer.from(f.data, "base64");
+  return out;
+}
+async function readAll(stream, signal) {
+  const chunks = [];
+  try {
+    for await (const c of stream) chunks.push(c);
+  } catch (err) {
+    if (signal?.aborted) throw signal.reason ?? err;
+    throw err;
+  }
+  return Buffer.concat(chunks);
+}
+
+// src/client.ts
+function egressString(egress, allow) {
+  if (allow && allow.length > 0) {
+    if (egress !== void 0 && egress !== "deny") {
+      throw new Kosa8Error("egressAllow already limits the network to the hosts it lists; do not also set egress");
+    }
+    return "allow:" + allow.map((h) => h.trim()).join(",");
+  }
+  if (egress === void 0) return void 0;
+  if (typeof egress === "string") return egress;
+  if (egress.allow.length === 0) {
+    throw new Kosa8Error('an egress allow-list needs at least one host; use egress: "deny" for no network');
+  }
+  return "allow:" + egress.allow.map((h) => h.trim()).join(",");
+}
+function envList(env) {
+  if (!env) return void 0;
+  if (Array.isArray(env)) return env;
+  return Object.entries(env).map(([k, v]) => `${k}=${v}`);
+}
+var enc = encodeURIComponent;
+var Kosa8Client = class {
+  transport;
+  checkpoints;
+  constructor(options = {}) {
+    this.transport = new Transport(options);
+    this.checkpoints = new CheckpointBook(options.checkpointStore ?? new FileCheckpointStore());
+  }
+  // --- status ---------------------------------------------------------------
+  /** GET /kosa8/v1/health: daemon status and version. */
+  health(opts = {}) {
+    return this.transport.json("GET", "/kosa8/v1/health", opts);
+  }
+  /** The daemon's version string. */
+  async version(opts = {}) {
+    return (await this.health(opts)).version;
+  }
+  // --- host engine ------------------------------------------------------------
+  /** POST /kosa8/v1/pull: pull an image into the host engine (checked against the registry allow-list). */
+  pull(ref, opts = {}) {
+    return this.transport.json("POST", "/kosa8/v1/pull", { ...opts, body: { ref } });
+  }
+  // --- sandboxes ---------------------------------------------------------------
+  /** GET /kosa8/v1/sandboxes */
+  listSandboxes(opts = {}) {
+    return this.transport.json("GET", "/kosa8/v1/sandboxes", opts);
+  }
+  /** Find one sandbox by id or name (from the list; there is no single-sandbox GET). */
+  async getSandbox(idOrName, opts = {}) {
+    const list = await this.listSandboxes(opts);
+    return list.find((s) => s.id === idOrName) ?? list.find((s) => s.name === idOrName);
+  }
+  /** POST /kosa8/v1/sandboxes: boot a microVM sandbox. */
+  async createSandbox(options = {}) {
+    const body = {};
+    if (options.name) body.name = options.name;
+    if (options.cpus) body.cpus = options.cpus;
+    if (options.memMb) body.mem_mb = options.memMb;
+    if (options.diskGb) body.disk_gb = options.diskGb;
+    if (options.mounts) body.mounts = options.mounts;
+    const egress = egressString(options.egress, options.egressAllow);
+    if (egress !== void 0) body.egress = egress;
+    if (options.capture) body.capture = options.capture;
+    if (options.labels) body.labels = options.labels;
+    if (options.broker) body.broker = options.broker;
+    return this.transport.json("POST", "/kosa8/v1/sandboxes", {
+      body,
+      approval: options.approval,
+      signal: options.signal
+    });
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/up: boot a stopped sandbox from its own disk. */
+  startSandbox(id, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/up`, opts);
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/down: stop without deleting (disk kept). */
+  stopSandbox(id, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/down`, opts);
+  }
+  /**
+   * DELETE /kosa8/v1/sandboxes/{id}. Like `kosa8 sandbox rm`, the sandbox's
+   * checkpoints and their snapshots are dropped too unless
+   * `keepCheckpoints` is set.
+   */
+  async deleteSandbox(id, opts = {}) {
+    const out = await this.transport.json("DELETE", `/kosa8/v1/sandboxes/${enc(id)}`, {
+      query: { wipe: opts.wipe },
+      approval: opts.approval,
+      signal: opts.signal
+    });
+    let dropped = 0;
+    if (!opts.keepCheckpoints) {
+      try {
+        const ids = await this.checkpoints.forget(id);
+        for (const sid of ids) {
+          await this.deleteSnapshot(sid, { wipe: opts.wipe, approval: opts.approval }).catch(() => void 0);
+        }
+        dropped = ids.length;
+      } catch {
+      }
+    }
+    return { ...out, checkpoints_dropped: dropped };
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/pull: pull an image into the sandbox's private engine (fetched on the host). */
+  pullIntoSandbox(id, ref, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/pull`, { ...opts, body: { ref } });
+  }
+  /** GET /kosa8/v1/sandboxes/{id}/images */
+  sandboxImages(id, opts = {}) {
+    return this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/images`, opts);
+  }
+  /** GET /kosa8/v1/sandboxes/{id}/containers */
+  sandboxContainers(id, opts = {}) {
+    return this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/containers`, opts);
+  }
+  /** GET /kosa8/v1/sandboxes/{id}/egress: the policy the host enforces and what it decided. */
+  sandboxEgress(id, opts = {}) {
+    return this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/egress`, opts);
+  }
+  /**
+   * POST /kosa8/v1/sandboxes/{id}/run: run a container to completion inside
+   * the sandbox's engine. The image must already be in the sandbox
+   * (`pullIntoSandbox`). Resolves with the exit code; a non-zero exit is not
+   * an error.
+   */
+  run(id, image, args = [], opts = {}) {
+    return this.collect(
+      this.transport.frames("POST", `/kosa8/v1/sandboxes/${enc(id)}/run`, {
+        body: { image, args, env: envList(opts.env) },
+        approval: opts.approval,
+        signal: opts.signal
+      }),
+      opts
+    );
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/start: start a detached container; resolves with its id. */
+  async startContainer(id, image, args = [], opts = {}) {
+    const out = await this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/start`, {
+      ...opts,
+      body: { image, args }
+    });
+    return out.id;
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/exec: run a command in a running container of the sandbox. */
+  exec(id, container, args, opts = {}) {
+    return this.collect(this.execFrames(id, container, args, opts), opts);
+  }
+  /** The raw frame stream of an exec, for callers that want to process output as it arrives. */
+  execFrames(id, container, args, opts = {}) {
+    return this.transport.frames("POST", `/kosa8/v1/sandboxes/${enc(id)}/exec`, {
+      body: { container, args },
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/start-interactive: start a container with stdin held open. */
+  async startInteractive(id, image, args = [], opts = {}) {
+    const out = await this.transport.json(
+      "POST",
+      `/kosa8/v1/sandboxes/${enc(id)}/start-interactive`,
+      { body: { image, args, env: envList(opts.env), tty: opts.tty ?? false }, approval: opts.approval, signal: opts.signal }
+    );
+    return out.id;
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/containers/{cid}/stdin: stream bytes into an interactive container's stdin. */
+  writeStdin(id, container, data, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/containers/${enc(container)}/stdin`, {
+      ...opts,
+      rawBody: data
+    });
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/containers/{cid}/attach: follow a container's output until it exits. */
+  attach(id, container, opts = {}) {
+    return this.collect(
+      this.transport.frames("POST", `/kosa8/v1/sandboxes/${enc(id)}/containers/${enc(container)}/attach`, {
+        approval: opts.approval,
+        signal: opts.signal
+      }),
+      opts
+    );
+  }
+  // --- snapshots, fork, explore -------------------------------------------------
+  /** POST /kosa8/v1/sandboxes/{id}/snapshot: capture memory, processes and disks. */
+  snapshot(id, opts = {}) {
+    const body = {};
+    if (opts.id) body.id = opts.id;
+    if (opts.encrypt) body.encrypt = true;
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/snapshot`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** GET /kosa8/v1/snapshots */
+  listSnapshots(opts = {}) {
+    return this.transport.json("GET", "/kosa8/v1/snapshots", opts);
+  }
+  /** POST /kosa8/v1/snapshots/{id}/restore: boot a sandbox from a snapshot, processes resumed. */
+  restoreSnapshot(snapshotId, opts = {}) {
+    const body = {};
+    if (opts.name) body.name = opts.name;
+    if (opts.label) body.label = opts.label;
+    if (opts.allowTampered) body.allow_tampered = true;
+    return this.transport.json("POST", `/kosa8/v1/snapshots/${enc(snapshotId)}/restore`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** DELETE /kosa8/v1/snapshots/{id} */
+  deleteSnapshot(snapshotId, opts = {}) {
+    return this.transport.json("DELETE", `/kosa8/v1/snapshots/${enc(snapshotId)}`, {
+      query: { wipe: opts.wipe, force: opts.force },
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** POST /kosa8/v1/sandboxes/{id}/fork: N live copies of a running sandbox. */
+  fork(id, opts = {}) {
+    const body = { n: opts.n ?? 1 };
+    if (opts.prefix) body.prefix = opts.prefix;
+    if (opts.label) body.label = opts.label;
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/fork`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /**
+   * Best-of-N, as `kosa8 explore`: fork the sandbox once per variant, run
+   * each variant (`sh -c VARIANT` in `image`) in its own branch
+   * concurrently, keep the fastest successful branch and delete the rest.
+   */
+  async explore(id, opts) {
+    const variants = opts.variants ?? [];
+    if (variants.length < 2) {
+      throw new Kosa8Error("give at least two variants; with one there is nothing to compare");
+    }
+    const image = opts.image ?? "alpine:latest";
+    const call = { approval: opts.approval, signal: opts.signal };
+    if (opts.pull !== false) await this.pullIntoSandbox(id, image, call);
+    const prefix = opts.prefix ?? `${id}-explore-${Math.floor(Date.now() / 1e3) % 1e5}`;
+    const forked = await this.fork(id, { n: variants.length, prefix, ...call });
+    const names = forked.forks.map((f) => f.id).filter((x) => typeof x === "string");
+    if (names.length < variants.length) {
+      throw new Kosa8Error(`forked ${names.length} branches for ${variants.length} variants; see listSandboxes() for what was created`);
+    }
+    const timeoutMs = opts.timeoutMs ?? 12e4;
+    const branches = await Promise.all(
+      variants.map((v, i) => this.runBranch(names[i], image, v, timeoutMs, opts))
+    );
+    let winner = "";
+    let best = Infinity;
+    for (const b of branches) {
+      if (!b.error && b.exit === 0 && b.duration_ms < best) {
+        winner = b.name;
+        best = b.duration_ms;
+      }
+    }
+    if (opts.keep !== void 0) {
+      if (!names.includes(opts.keep)) {
+        throw new Kosa8Error(`keep ${opts.keep} is not one of the branches (${names.join(", ")}); all of them were kept`);
+      }
+      winner = opts.keep;
+    }
+    let removed = 0;
+    if (!opts.keepAll) {
+      for (const b of branches) {
+        if (b.name !== winner) {
+          try {
+            await this.transport.json("DELETE", `/kosa8/v1/sandboxes/${enc(b.name)}`, { approval: opts.approval });
+            removed++;
+          } catch {
+          }
+        }
+      }
+    }
+    return { parent: id, branches, winner, removed };
+  }
+  async runBranch(name, image, variant, timeoutMs, opts) {
+    const start = Date.now();
+    const r = { name, variant, exit: 0, output: "", duration_ms: 0 };
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const ctl = new AbortController();
+      const timer = setTimeout(() => ctl.abort(new Error(`branch timed out after ${timeoutMs}ms`)), timeoutMs);
+      const onAbort = () => ctl.abort(opts.signal?.reason);
+      opts.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        let out = "";
+        const res = await this.run(name, image, ["sh", "-c", variant], {
+          approval: opts.approval,
+          signal: ctl.signal,
+          onStdout: (c) => out += c.toString("utf8"),
+          onStderr: (c) => out += c.toString("utf8")
+        });
+        r.exit = res.exitCode;
+        r.output = out.replace(/\n+$/, "");
+        delete r.error;
+        break;
+      } catch (err) {
+        r.error = err instanceof Error ? err.message : String(err);
+        if (err instanceof Kosa8StreamError) r.output = (err.stdout + err.stderr).replace(/\n+$/, "");
+        const transient = /connection refused|EOF|connection reset|broken pipe|no such file or directory|stream ended|ECONNREFUSED|ECONNRESET|socket hang up/i.test(
+          r.error
+        );
+        if (!transient || ctl.signal.aborted) break;
+        await new Promise((res) => setTimeout(res, (attempt + 1) * 500));
+      } finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener("abort", onAbort);
+      }
+    }
+    r.duration_ms = Date.now() - start;
+    return r;
+  }
+  // --- checkpoints (client-side over snapshots, as pkg/checkpoint) ---------------
+  /**
+   * Save a restore point: a snapshot with id `<sandbox>-ckpt-<n>`, recorded on
+   * the sandbox's checkpoint stack (the same store `kosa8 checkpoint` uses).
+   * The oldest is evicted past 10.
+   */
+  async checkpoint(sandbox, opts = {}) {
+    const { id, evict } = await this.checkpoints.nextId(sandbox);
+    const snap = await this.snapshot(sandbox, { id, approval: opts.approval, signal: opts.signal });
+    for (const old of evict) {
+      await this.deleteSnapshot(old, { approval: opts.approval }).catch(() => void 0);
+    }
+    const checkpoint = await this.checkpoints.record({ id, sandbox, label: opts.label ?? "" }, evict);
+    return { checkpoint, evicted: evict, snapshot: snap };
+  }
+  /** A sandbox's restore points, oldest first. */
+  listCheckpoints(sandbox) {
+    return this.checkpoints.list(sandbox);
+  }
+  /**
+   * Undo: put the sandbox back to a checkpoint under the same name, processes
+   * resumed. Deletes the sandbox, then restores the snapshot with its name;
+   * checkpoints taken after the target are discarded. Current state is lost.
+   */
+  async rewind(sandbox, opts = {}) {
+    const target = opts.to ? await this.checkpoints.resolve(sandbox, opts.to) : await this.checkpoints.latest(sandbox);
+    const call = { approval: opts.approval, signal: opts.signal };
+    await this.transport.json("DELETE", `/kosa8/v1/sandboxes/${enc(sandbox)}`, call);
+    let restored;
+    try {
+      restored = await this.restoreSnapshot(target.id, { name: sandbox, ...call });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Kosa8Error(
+        `restore failed and ${sandbox} is now stopped: ${msg} \u2014 recover with restoreSnapshot(${JSON.stringify(target.id)}, { name: ${JSON.stringify(sandbox)} })`,
+        { cause: err }
+      );
+    }
+    let dropped = [];
+    try {
+      dropped = await this.checkpoints.pop(sandbox, target.id);
+      for (const sid of dropped) await this.deleteSnapshot(sid, { approval: opts.approval }).catch(() => void 0);
+    } catch {
+    }
+    return { sandbox: restored.sandbox, checkpoint: target, dropped, restore_ms: restored.restore_ms };
+  }
+  // --- helpers -------------------------------------------------------------------
+  /** A handle bound to one sandbox. */
+  sandbox(id) {
+    return new SandboxHandle(this, id);
+  }
+  async collect(frames, opts) {
+    const out = [];
+    const err = [];
+    for await (const f of frames) {
+      if (f.done) {
+        const stdoutBytes = Buffer.concat(out);
+        const stderrBytes = Buffer.concat(err);
+        if (f.error) {
+          throw new Kosa8StreamError(f.error, {
+            stdout: stdoutBytes.toString("utf8"),
+            stderr: stderrBytes.toString("utf8")
+          }, { daemonMessage: f.error });
+        }
+        return {
+          exitCode: typeof f.exit === "number" ? f.exit : 0,
+          stdout: stdoutBytes.toString("utf8"),
+          stderr: stderrBytes.toString("utf8"),
+          stdoutBytes,
+          stderrBytes
+        };
+      }
+      if (!f.data) continue;
+      if (f.stream === "stderr") {
+        err.push(f.data);
+        opts.onStderr?.(f.data);
+      } else if (f.stream === "status") {
+        opts.onStatus?.(f.data);
+      } else {
+        out.push(f.data);
+        opts.onStdout?.(f.data);
+      }
+    }
+    throw new Kosa8StreamError("stream ended unexpectedly (no final frame)", {
+      stdout: Buffer.concat(out).toString("utf8"),
+      stderr: Buffer.concat(err).toString("utf8")
+    });
+  }
+};
+var SandboxHandle = class {
+  constructor(client, id) {
+    this.client = client;
+    this.id = id;
+  }
+  info(opts) {
+    return this.client.getSandbox(this.id, opts);
+  }
+  start(opts) {
+    return this.client.startSandbox(this.id, opts);
+  }
+  stop(opts) {
+    return this.client.stopSandbox(this.id, opts);
+  }
+  delete(opts) {
+    return this.client.deleteSandbox(this.id, opts);
+  }
+  pull(ref, opts) {
+    return this.client.pullIntoSandbox(this.id, ref, opts);
+  }
+  run(image, args, opts) {
+    return this.client.run(this.id, image, args, opts);
+  }
+  startContainer(image, args, opts) {
+    return this.client.startContainer(this.id, image, args, opts);
+  }
+  exec(container, args, opts) {
+    return this.client.exec(this.id, container, args, opts);
+  }
+  containers(opts) {
+    return this.client.sandboxContainers(this.id, opts);
+  }
+  images(opts) {
+    return this.client.sandboxImages(this.id, opts);
+  }
+  egress(opts) {
+    return this.client.sandboxEgress(this.id, opts);
+  }
+  snapshot(opts) {
+    return this.client.snapshot(this.id, opts);
+  }
+  fork(opts) {
+    return this.client.fork(this.id, opts);
+  }
+  explore(opts) {
+    return this.client.explore(this.id, opts);
+  }
+  checkpoint(opts) {
+    return this.client.checkpoint(this.id, opts);
+  }
+  checkpoints() {
+    return this.client.listCheckpoints(this.id);
+  }
+  rewind(opts) {
+    return this.client.rewind(this.id, opts);
+  }
+};
+export {
+  ACTOR_HEADER,
+  AGENT_TOKEN_HEADER,
+  APPROVAL_HEADER,
+  CheckpointBook,
+  FileCheckpointStore,
+  Kosa8ApiError,
+  Kosa8ApprovalRequiredError,
+  Kosa8AuthError,
+  Kosa8BadRequestError,
+  Kosa8CheckpointError,
+  Kosa8Client,
+  Kosa8ConflictError,
+  Kosa8ConnectionError,
+  Kosa8Error,
+  Kosa8NotFoundError,
+  Kosa8PolicyError,
+  Kosa8StreamError,
+  Kosa8UnsupportedError,
+  MAX_CHECKPOINTS_PER_SANDBOX,
+  MemoryCheckpointStore,
+  SandboxHandle,
+  Transport,
+  defaultSocketPath,
+  errorFromResponse,
+  resolveEndpoint,
+  validateSandboxName
+};
+//# sourceMappingURL=index.js.map