@kosa8/sdk 0.0.0-stage → 0.3.0

package/dist/index.js

@@ -0,0 +1,1718 @@
+// 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;
+  /** kosa8 Cloud's stable error code (payment_required, quota_exceeded, ...). */
+  code;
+  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;
+    this.code = options.code;
+  }
+};
+var Kosa8ConnectionError = class extends Kosa8Error {
+};
+var Kosa8TimeoutError = class extends Kosa8ConnectionError {
+};
+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 Kosa8PaymentRequiredError = class extends Kosa8ApiError {
+};
+var Kosa8RateLimitError = class extends Kosa8ApiError {
+};
+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 402:
+      return new Kosa8PaymentRequiredError(message, opts);
+    case 409:
+      return new Kosa8ConflictError(message, opts);
+    case 429:
+      return new Kosa8RateLimitError(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/tar.ts
+import { promises as fsp } from "fs";
+import * as path2 from "path";
+var BLOCK = 512;
+function octal(buf, off, len, n) {
+  buf.write(n.toString(8).padStart(len - 1, "0") + "\0", off, len, "ascii");
+}
+function header(name, type, size, mode, mtime, link = "") {
+  const h = Buffer.alloc(BLOCK);
+  h.write(name, 0, 100, "utf8");
+  octal(h, 100, 8, mode & 4095);
+  octal(h, 108, 8, 0);
+  octal(h, 116, 8, 0);
+  octal(h, 124, 12, size);
+  octal(h, 136, 12, mtime);
+  h.fill(" ", 148, 156);
+  h.write(type, 156, 1, "ascii");
+  h.write(link, 157, 100, "utf8");
+  h.write("ustar\0", 257, 6, "ascii");
+  h.write("00", 263, 2, "ascii");
+  let sum = 0;
+  for (const b of h) sum += b;
+  h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8, "ascii");
+  return h;
+}
+function paxRecord(key, value) {
+  const body = ` ${key}=${value}
+`;
+  let n = Buffer.byteLength(body);
+  let len = n + String(n).length;
+  if (String(len).length !== String(n).length) len = n + String(len).length;
+  return `${len}${body}`;
+}
+function pad(n) {
+  const r = n % BLOCK;
+  return Buffer.alloc(r === 0 ? 0 : BLOCK - r);
+}
+function entry(out, name, type, mode, mtime, data, link = "") {
+  let pax = "";
+  if (Buffer.byteLength(name) > 100) pax += paxRecord("path", name);
+  if (Buffer.byteLength(link) > 100) pax += paxRecord("linkpath", link);
+  if (pax !== "") {
+    const p = Buffer.from(pax, "utf8");
+    out.push(header("PaxHeader", "x", p.length, 420, mtime), p, pad(p.length));
+  }
+  const size = data?.length ?? 0;
+  out.push(header(name.slice(0, 100), type, size, mode, mtime, link.slice(0, 100)));
+  if (data) out.push(data, pad(size));
+}
+async function readIgnore(dir) {
+  let text;
+  try {
+    text = await fsp.readFile(path2.join(dir, ".dockerignore"), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const l = line.trim();
+    if (l === "" || line.startsWith("#")) continue;
+    out.push(path2.posix.normalize(l.replace(/\\/g, "/")).replace(/\/+$/, "") || ".");
+  }
+  return out;
+}
+async function tarContext(dir, dockerfile = "Dockerfile") {
+  try {
+    await fsp.access(path2.join(dir, dockerfile));
+  } catch {
+    throw new Kosa8Error(`no ${dockerfile} in ${dir}`);
+  }
+  const ignore = await readIgnore(dir);
+  const skip = (rel) => ignore.some((p) => rel === p || rel.startsWith(p + "/"));
+  const out = [];
+  const walk = async (rel) => {
+    const ents = await fsp.readdir(path2.join(dir, rel), { withFileTypes: true });
+    ents.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const subdirs = [];
+    for (const e of ents) {
+      const r = rel === "" ? e.name : `${rel}/${e.name}`;
+      if (skip(r)) continue;
+      const full = path2.join(dir, r);
+      const st = await fsp.lstat(full);
+      const mtime = Math.floor(st.mtimeMs / 1e3);
+      if (st.isSymbolicLink()) {
+        entry(out, r, "2", st.mode, mtime, void 0, await fsp.readlink(full));
+      } else if (st.isDirectory()) {
+        entry(out, r + "/", "5", st.mode, mtime);
+        subdirs.push(r);
+      } else if (st.isFile()) {
+        entry(out, r, "0", st.mode, mtime, await fsp.readFile(full));
+      }
+    }
+    for (const s of subdirs) await walk(s);
+  };
+  await walk("");
+  out.push(Buffer.alloc(BLOCK * 2));
+  return Buffer.concat(out);
+}
+
+// src/transport.ts
+import * as fs2 from "fs";
+import * as http from "http";
+import * as https from "https";
+import * as os2 from "os";
+import * as path3 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 path3.join(os2.homedir(), ".kosa8", "run", "kosa8.sock");
+}
+function defaultWorkerFile() {
+  return path3.join(os2.homedir(), ".kosa8", "worker.json");
+}
+function loadSavedWorker(file) {
+  let w;
+  try {
+    w = JSON.parse(fs2.readFileSync(file, "utf8"));
+  } catch {
+    return void 0;
+  }
+  if (!w || typeof w !== "object") return void 0;
+  const o = w;
+  const host = typeof o.host === "string" ? o.host.trim() : "";
+  if (host === "") return void 0;
+  return {
+    host,
+    token: typeof o.token === "string" && o.token !== "" ? o.token : void 0,
+    insecure: o.insecure === true
+  };
+}
+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();
+  const envInsecure = opts.insecure === true || env.KOSA8_INSECURE === "1";
+  if (raw !== "") {
+    const token = opts.token ?? (opts.host === void 0 && fromEnv !== "" ? env.KOSA8_TOKEN : void 0);
+    return parseHost(raw, envInsecure, token);
+  }
+  if (opts.socketPath === void 0 && opts.workerFile !== null) {
+    const saved = loadSavedWorker(opts.workerFile ?? defaultWorkerFile());
+    if (saved) return parseHost(saved.host, envInsecure || saved.insecure, opts.token ?? saved.token);
+  }
+  return { kind: "unix", socketPath: opts.socketPath ?? defaultSocketPath() };
+}
+function parseHost(raw, insecure, token) {
+  let h = raw.replace(/\/+$/, "");
+  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);
+  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`
+    );
+  }
+  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" ? this.endpoint.kind === "unix" && process.platform === "win32" ? " (on Windows the engine runs in WSL2: run `kosa8 wsl setup`, or set KOSA8_HOST)" : " (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;
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+function num(v) {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+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;
+    if (options.autoStopMin) body.auto_stop_min = options.autoStopMin;
+    if (options.autoDeleteMin) body.auto_delete_min = options.autoDeleteMin;
+    if (options.ttlMin) body.ttl_min = options.ttlMin;
+    if (options.ephemeral) body.ephemeral = true;
+    if (options.template) body.template = options.template;
+    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 };
+  }
+  // --- toolbox: code -------------------------------------------------------------
+  /**
+   * POST /kosa8/v1/sandboxes/{id}/code: run a Python, JavaScript or
+   * TypeScript snippet. It starts in `/workspace`. Charts a Python snippet
+   * draws with matplotlib come back in `artifacts` as PNG bytes.
+   */
+  async runCode(id, code, opts = {}) {
+    const body = { language: opts.language ?? "python", code };
+    if (opts.image) body.image = opts.image;
+    if (opts.env && Object.keys(opts.env).length > 0) body.env = opts.env;
+    if (opts.timeoutS) body.timeout_s = opts.timeoutS;
+    const d = await this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/code`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+    const exitCode = num(d.exit);
+    const timedOut = d.timed_out === true;
+    const arts = Array.isArray(d.artifacts) ? d.artifacts : [];
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout: str(d.stdout),
+      stderr: str(d.stderr),
+      language: str(d.language),
+      image: str(d.image),
+      artifacts: arts.map((a) => ({ type: str(a.type), name: str(a.name), data: Buffer.from(str(a.data), "base64") })),
+      durationMs: num(d.duration_ms),
+      timedOut,
+      truncated: d.truncated === true
+    };
+  }
+  // --- toolbox: files ------------------------------------------------------------
+  /** GET …/files: a folder in the workspace (default `/workspace`), or one entry. */
+  async listFiles(id, path4 = "/workspace", opts = {}) {
+    const d = await this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/files`, {
+      ...opts,
+      query: { path: path4 }
+    });
+    return d?.files ?? [];
+  }
+  /** GET …/files/stat: one entry, not following a symlink. */
+  statFile(id, path4, opts = {}) {
+    return this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/files/stat`, { ...opts, query: { path: path4 } });
+  }
+  /** GET …/files/content: a file's bytes. A body cut short is a Kosa8StreamError. */
+  async readFile(id, path4, opts = {}) {
+    const p = `/kosa8/v1/sandboxes/${enc(id)}/files/content`;
+    const res = await this.transport.raw("GET", p, { query: { path: path4 }, signal: opts.signal, approval: opts.approval });
+    let data;
+    try {
+      data = await readAll(res.stream, opts.signal);
+    } catch (err) {
+      if (opts.signal?.aborted) throw err;
+      throw new Kosa8StreamError(
+        `${path4}: read cut short: ${err instanceof Error ? err.message : String(err)}`,
+        { stdout: "", stderr: "" },
+        { method: "GET", path: p, cause: err }
+      );
+    }
+    if (res.status >= 400) {
+      const text = data.toString("utf8");
+      let body = text;
+      try {
+        body = JSON.parse(text);
+      } catch {
+      }
+      throw errorFromResponse(res.status, body, { method: "GET", path: p });
+    }
+    const want = res.headers["content-length"];
+    if (want !== void 0 && Number(want) !== data.length) {
+      throw new Kosa8StreamError(`${path4}: got ${data.length} of ${want} bytes`, { stdout: "", stderr: "" }, { method: "GET", path: p });
+    }
+    return data;
+  }
+  /** A file's contents as text (UTF-8 by default). */
+  async readText(id, path4, opts = {}) {
+    return (await this.readFile(id, path4, opts)).toString(opts.encoding ?? "utf8");
+  }
+  /** PUT …/files/content: replace a file, making its folders. Answers the new entry. */
+  writeFile(id, path4, data, opts = {}) {
+    return this.transport.json("PUT", `/kosa8/v1/sandboxes/${enc(id)}/files/content`, {
+      query: { path: path4, mode: opts.mode },
+      rawBody: data,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** DELETE …/files: a file, or with `recursive` a folder and everything in it. */
+  deleteFile(id, path4, opts = {}) {
+    return this.transport.json("DELETE", `/kosa8/v1/sandboxes/${enc(id)}/files`, {
+      query: { path: path4, recursive: opts.recursive },
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** POST …/files/mkdir: a folder, with its parents. */
+  makeDir(id, path4, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/files/mkdir`, { ...opts, body: { path: path4 } });
+  }
+  /** POST …/files/move: rename or move a file or folder. Answers the entry at `to`. */
+  moveFile(id, from, to, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/files/move`, { ...opts, body: { from, to } });
+  }
+  // --- toolbox: git ----------------------------------------------------------------
+  /**
+   * POST …/git: one git operation in the workspace. A git failure resolves
+   * with `ok: false`; only a refusal (bad op, no sandbox, policy) throws.
+   */
+  async git(id, op, opts = {}) {
+    const { approval, signal, authorName, authorEmail, ...fields } = opts;
+    const body = { op };
+    for (const [k, v] of Object.entries(fields)) if (v !== void 0) body[k] = v;
+    if (authorName !== void 0) body.author_name = authorName;
+    if (authorEmail !== void 0) body.author_email = authorEmail;
+    const d = await this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/git`, {
+      body,
+      approval,
+      signal
+    });
+    const out = {
+      op: str(d.op) || op,
+      ok: d.ok === true,
+      exitCode: num(d.exit),
+      stdout: str(d.stdout),
+      stderr: str(d.stderr),
+      path: str(d.path)
+    };
+    if (d.status) out.status = d.status;
+    if (d.log) out.log = d.log;
+    if (d.branches) out.branches = d.branches;
+    return out;
+  }
+  /** Clone `url` into the workspace (into `path`, else a folder named after the repo). */
+  gitClone(id, url, opts = {}) {
+    return this.git(id, "clone", { ...opts, url });
+  }
+  /** `git status` of the repository at `path`, parsed into `status`. */
+  gitStatus(id, path4, opts = {}) {
+    return this.git(id, "status", { ...opts, path: path4 });
+  }
+  /** Stage everything (unless `addAll: false`) and commit. A failed add is returned as is. */
+  async gitCommit(id, path4, message, opts = {}) {
+    const { addAll = true, ...rest } = opts;
+    if (addAll) {
+      const r = await this.git(id, "add", { path: path4, image: rest.image, approval: rest.approval, signal: rest.signal });
+      if (!r.ok) return r;
+    }
+    return this.git(id, "commit", { ...rest, path: path4, message });
+  }
+  // --- toolbox: shell sessions -------------------------------------------------------
+  /** POST …/sessions: a shell that keeps `cd` and `export` between commands. */
+  createSession(id, name, opts = {}) {
+    const body = {};
+    if (name) body.name = name;
+    if (opts.image) body.image = opts.image;
+    if (opts.env && Object.keys(opts.env).length > 0) body.env = opts.env;
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/sessions`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** GET …/sessions */
+  async listSessions(id, opts = {}) {
+    return await this.transport.json("GET", `/kosa8/v1/sandboxes/${enc(id)}/sessions`, opts) ?? [];
+  }
+  /** POST …/sessions/{name}/exec: run one command line in the session. */
+  async sessionExec(id, session, command, opts = {}) {
+    const body = { command };
+    if (opts.timeoutS) body.timeout_s = opts.timeoutS;
+    const d = await this.transport.json(
+      "POST",
+      `/kosa8/v1/sandboxes/${enc(id)}/sessions/${enc(session)}/exec`,
+      { body, approval: opts.approval, signal: opts.signal }
+    );
+    const exitCode = num(d.exit);
+    const timedOut = d.timed_out === true;
+    return {
+      ok: exitCode === 0 && !timedOut,
+      exitCode,
+      stdout: str(d.stdout),
+      stderr: str(d.stderr),
+      cwd: str(d.cwd),
+      durationMs: num(d.duration_ms),
+      timedOut,
+      truncated: d.truncated === true
+    };
+  }
+  /** Run a command in a session (default `main`), making the session on first use. */
+  async shell(id, command, opts = {}) {
+    const { session = "main", ...rest } = opts;
+    try {
+      return await this.sessionExec(id, session, command, rest);
+    } catch (err) {
+      if (!(err instanceof Kosa8NotFoundError) || !err.message.includes("no such session")) throw err;
+    }
+    await this.createSession(id, session, { approval: rest.approval, signal: rest.signal });
+    return this.sessionExec(id, session, command, rest);
+  }
+  /** DELETE …/sessions/{name} */
+  deleteSession(id, session, opts = {}) {
+    return this.transport.json("DELETE", `/kosa8/v1/sandboxes/${enc(id)}/sessions/${enc(session)}`, opts);
+  }
+  // --- toolbox: terminals ----------------------------------------------------------
+  /**
+   * POST …/pty: a container with a terminal; resolves with its id. Connect
+   * to `/kosa8/v1/sandboxes/{id}/containers/{cid}/tty` with any WebSocket
+   * client: binary messages are the terminal, text messages JSON control.
+   */
+  async startPty(id, opts = {}) {
+    const body = {};
+    if (opts.image) body.image = opts.image;
+    if (opts.command && opts.command.length > 0) body.command = opts.command;
+    if (opts.cols && opts.rows) {
+      body.cols = opts.cols;
+      body.rows = opts.rows;
+    }
+    if (opts.env && Object.keys(opts.env).length > 0) body.env = opts.env;
+    const out = await this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/pty`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+    return out.id;
+  }
+  /** POST …/containers/{cid}/resize: set a terminal's size. */
+  resizePty(id, container, cols, rows, opts = {}) {
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/containers/${enc(container)}/resize`, {
+      ...opts,
+      body: { cols, rows }
+    });
+  }
+  // --- toolbox: previews -----------------------------------------------------------
+  /** POST …/previews: a signed link, which expires, to a web server in the sandbox. */
+  createPreview(id, port, opts = {}) {
+    const body = { port };
+    if (opts.session) body.session = opts.session;
+    if (opts.container) body.container = opts.container;
+    if (opts.expiresInS) body.expires_in_s = opts.expiresInS;
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/previews`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  /** POST /kosa8/v1/previews/rotate: end every preview link at once. */
+  revokePreviews(opts = {}) {
+    return this.transport.json("POST", "/kosa8/v1/previews/rotate", opts);
+  }
+  // --- toolbox: lifecycle ----------------------------------------------------------
+  /**
+   * POST …/lifecycle: change auto-stop, auto-delete, TTL or ephemeral.
+   * Options left out keep their value; 0 (or `false`) turns one off.
+   */
+  setLifecycle(id, opts = {}) {
+    const body = {};
+    if (opts.autoStopMin !== void 0) body.auto_stop_min = opts.autoStopMin;
+    if (opts.autoDeleteMin !== void 0) body.auto_delete_min = opts.autoDeleteMin;
+    if (opts.ttlMin !== void 0) body.ttl_min = opts.ttlMin;
+    if (opts.ephemeral !== void 0) body.ephemeral = opts.ephemeral;
+    return this.transport.json("POST", `/kosa8/v1/sandboxes/${enc(id)}/lifecycle`, {
+      body,
+      approval: opts.approval,
+      signal: opts.signal
+    });
+  }
+  // --- toolbox: templates ----------------------------------------------------------
+  /** GET /kosa8/v1/templates */
+  async listTemplates(opts = {}) {
+    return await this.transport.json("GET", "/kosa8/v1/templates", opts) ?? [];
+  }
+  /** DELETE /kosa8/v1/templates/{name}. Sandboxes made from it keep their copy. */
+  deleteTemplate(name, opts = {}) {
+    return this.transport.json("DELETE", `/kosa8/v1/templates/${enc(name)}`, opts);
+  }
+  /**
+   * POST /kosa8/v1/templates: build `contextDir`'s Dockerfile in a throwaway
+   * sandbox and keep the image as a template, for `createSandbox({ template })`.
+   * The context is packed honouring `.dockerignore`. Resolves with the final
+   * frame (`{ done, ok, image }`); a failed build throws Kosa8StreamError.
+   */
+  async buildTemplate(name, contextDir = ".", opts = {}) {
+    const dockerfile = opts.dockerfile ?? "Dockerfile";
+    const q = new URLSearchParams();
+    q.append("name", name);
+    q.append("dockerfile", dockerfile);
+    for (const [k, v] of Object.entries(opts.buildArgs ?? {})) q.append("buildarg", `${k}=${v}`);
+    const egress = egressString(opts.egress);
+    if (egress) q.append("egress", egress);
+    if (opts.replace) q.append("replace", "1");
+    const ctx = await tarContext(contextDir, dockerfile);
+    let out = "";
+    for await (const f of this.transport.frames("POST", `/kosa8/v1/templates?${q.toString()}`, {
+      rawBody: ctx,
+      approval: opts.approval,
+      signal: opts.signal
+    })) {
+      if (f.done) {
+        if (f.error) throw new Kosa8StreamError(f.error, { stdout: out, stderr: "" }, { daemonMessage: f.error });
+        return f;
+      }
+      if (f.data) {
+        out += f.data.toString("utf8");
+        opts.onOutput?.(f.data, f.stream ?? "stdout");
+      }
+    }
+    throw new Kosa8StreamError("template build stream ended without a final frame", { stdout: out, stderr: "" });
+  }
+  // --- 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);
+  }
+  runCode(code, opts) {
+    return this.client.runCode(this.id, code, opts);
+  }
+  listFiles(path4, opts) {
+    return this.client.listFiles(this.id, path4, opts);
+  }
+  statFile(path4, opts) {
+    return this.client.statFile(this.id, path4, opts);
+  }
+  readFile(path4, opts) {
+    return this.client.readFile(this.id, path4, opts);
+  }
+  readText(path4, opts) {
+    return this.client.readText(this.id, path4, opts);
+  }
+  writeFile(path4, data, opts) {
+    return this.client.writeFile(this.id, path4, data, opts);
+  }
+  deleteFile(path4, opts) {
+    return this.client.deleteFile(this.id, path4, opts);
+  }
+  makeDir(path4, opts) {
+    return this.client.makeDir(this.id, path4, opts);
+  }
+  moveFile(from, to, opts) {
+    return this.client.moveFile(this.id, from, to, opts);
+  }
+  git(op, opts) {
+    return this.client.git(this.id, op, opts);
+  }
+  gitClone(url, opts) {
+    return this.client.gitClone(this.id, url, opts);
+  }
+  gitStatus(path4, opts) {
+    return this.client.gitStatus(this.id, path4, opts);
+  }
+  gitCommit(path4, message, opts) {
+    return this.client.gitCommit(this.id, path4, message, opts);
+  }
+  createSession(name, opts) {
+    return this.client.createSession(this.id, name, opts);
+  }
+  sessions(opts) {
+    return this.client.listSessions(this.id, opts);
+  }
+  sessionExec(session, command, opts) {
+    return this.client.sessionExec(this.id, session, command, opts);
+  }
+  shell(command, opts) {
+    return this.client.shell(this.id, command, opts);
+  }
+  deleteSession(session, opts) {
+    return this.client.deleteSession(this.id, session, opts);
+  }
+  startPty(opts) {
+    return this.client.startPty(this.id, opts);
+  }
+  resizePty(container, cols, rows, opts) {
+    return this.client.resizePty(this.id, container, cols, rows, opts);
+  }
+  createPreview(port, opts) {
+    return this.client.createPreview(this.id, port, opts);
+  }
+  setLifecycle(opts) {
+    return this.client.setLifecycle(this.id, opts);
+  }
+};
+
+// src/cloud.ts
+var DEFAULT_CLOUD_URL = "https://api.kosa8.cloud";
+var CLOUD_KEY_PREFIX = "k8c_live_";
+function trimSlash(s) {
+  return s.replace(/\/+$/, "");
+}
+function checkBase(url) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    throw new Kosa8Error(`kosa8 Cloud address is not a URL: ${url}`);
+  }
+  const local = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "[::1]";
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && local)) {
+    throw new Kosa8Error(`kosa8 Cloud address must use https: ${url}`);
+  }
+  return trimSlash(u.toString());
+}
+var Kosa8Cloud = class {
+  baseUrl;
+  sandboxes;
+  functions;
+  apiKey;
+  fetchImpl;
+  timeoutMs;
+  constructor(options = {}) {
+    const env = options.env ?? (typeof process !== "undefined" ? process.env : {});
+    const key = (options.apiKey ?? env.KOSA8_API_KEY ?? "").trim();
+    if (!key) throw new Kosa8Error("no kosa8 Cloud API key: pass apiKey or set KOSA8_API_KEY");
+    if (!key.startsWith(CLOUD_KEY_PREFIX)) throw new Kosa8Error(`a kosa8 Cloud API key starts with ${CLOUD_KEY_PREFIX}`);
+    this.apiKey = key;
+    this.baseUrl = checkBase(options.baseUrl ?? env.KOSA8_CLOUD_URL ?? DEFAULT_CLOUD_URL);
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") throw new Kosa8Error("no fetch available; pass options.fetch");
+    this.fetchImpl = f;
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.sandboxes = new CloudSandboxes(this);
+    this.functions = new CloudFunctions(this);
+  }
+  /** The org, the key in use and, for a member's key, the member. */
+  me() {
+    return this.request("GET", "/v1/me");
+  }
+  /** This month's usage, bill estimate and whether work is paused for payment. */
+  usage() {
+    return this.request("GET", "/v1/usage");
+  }
+  /** @internal */
+  async request(method, path4, body) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await this.fetchImpl(`${this.baseUrl}${path4}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          ...body !== void 0 ? { "Content-Type": "application/json" } : {}
+        },
+        body: body !== void 0 ? JSON.stringify(body) : void 0,
+        signal: ctl.signal
+      });
+    } catch (e) {
+      if (ctl.signal.aborted) {
+        throw new Kosa8TimeoutError(`kosa8 Cloud did not answer within ${this.timeoutMs} ms`, { method, path: path4, cause: e });
+      }
+      throw new Kosa8ConnectionError(`could not reach kosa8 Cloud at ${this.baseUrl}: ${String(e?.message ?? e)}`, { method, path: path4, cause: e });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await resp.text();
+    let data = text;
+    try {
+      data = text === "" ? null : JSON.parse(text);
+    } catch {
+    }
+    if (!resp.ok) throw cloudError(resp.status, data, { method, path: path4 });
+    return data;
+  }
+};
+function cloudError(status, body, ctx) {
+  let code;
+  let msgBody = body;
+  if (typeof body === "object" && body !== null) {
+    const b = body;
+    if (typeof b.error === "string") code = b.error;
+    msgBody = { error: typeof b.message === "string" && b.message ? b.message : b.error };
+  }
+  return errorFromResponse(status, msgBody, { ...ctx, code });
+}
+var CloudSandboxes = class {
+  constructor(cloud) {
+    this.cloud = cloud;
+  }
+  /** Start a sandbox; resolves once it is running. */
+  async create(opts = {}) {
+    const body = {};
+    if (opts.template !== void 0) body.template = opts.template;
+    if (opts.region !== void 0) body.region = opts.region;
+    if (opts.sleepAfterS !== void 0) body.sleep_after_s = opts.sleepAfterS;
+    const r = await this.cloud.request("POST", "/v1/sandboxes", body);
+    return new CloudSandbox(this.cloud, r.sandbox);
+  }
+  /** The org's sandboxes; with all, deleted ones too. */
+  async list(opts = {}) {
+    const r = await this.cloud.request("GET", `/v1/sandboxes${opts.all ? "?all=1" : ""}`);
+    return r.sandboxes.map((s) => new CloudSandbox(this.cloud, s));
+  }
+  async get(id) {
+    const r = await this.cloud.request("GET", `/v1/sandboxes/${encodeURIComponent(id)}`);
+    return new CloudSandbox(this.cloud, r.sandbox);
+  }
+};
+var CloudSandbox = class {
+  constructor(cloud, info) {
+    this.cloud = cloud;
+    this.info = info;
+  }
+  get id() {
+    return this.info.id;
+  }
+  path(suffix = "") {
+    return `/v1/sandboxes/${encodeURIComponent(this.info.id)}${suffix}`;
+  }
+  /**
+   * Run a command and wait for it. A string runs through `sh -c`. A
+   * sleeping sandbox wakes for it.
+   */
+  async exec(cmd, opts = {}) {
+    const argv = typeof cmd === "string" ? ["sh", "-c", cmd] : cmd;
+    const body = { cmd: argv };
+    if (opts.image !== void 0) body.image = opts.image;
+    if (opts.env) body.env = Object.entries(opts.env).map(([k, v]) => `${k}=${v}`);
+    const r = await this.cloud.request(
+      "POST",
+      this.path("/exec"),
+      body
+    );
+    const out = { exitCode: r.exit, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    if (typeof r.woke_ms === "number") out.wokeMs = r.woke_ms;
+    return out;
+  }
+  /** Snapshot it and free its VM; it then costs only snapshot storage. */
+  async sleep() {
+    this.info = (await this.cloud.request("POST", this.path("/sleep"))).sandbox;
+    return this;
+  }
+  /** Restore a sleeping sandbox, files and all. */
+  async wake() {
+    this.info = (await this.cloud.request("POST", this.path("/wake"))).sandbox;
+    return this;
+  }
+  async refresh() {
+    this.info = (await this.cloud.request("GET", this.path())).sandbox;
+    return this;
+  }
+  async delete() {
+    await this.cloud.request("DELETE", this.path());
+  }
+};
+var CloudFunctions = class {
+  constructor(cloud) {
+    this.cloud = cloud;
+  }
+  /** Deploy (create or replace) a function; every deploy bumps its version. */
+  deploy(name, spec) {
+    return this.cloud.request("PUT", `/v1/functions/${encodeURIComponent(name)}`, spec);
+  }
+  async list() {
+    return (await this.cloud.request("GET", "/v1/functions")).functions;
+  }
+  get(name) {
+    return this.cloud.request("GET", `/v1/functions/${encodeURIComponent(name)}`);
+  }
+  async delete(name) {
+    await this.cloud.request("DELETE", `/v1/functions/${encodeURIComponent(name)}`);
+  }
+  /** Call it once. A handler that raises resolves with ok: false, not a throw. */
+  invoke(name, event = null) {
+    return this.cloud.request("POST", `/v1/functions/${encodeURIComponent(name)}/invoke`, { event });
+  }
+  /** One call per event, results in input order. */
+  map(name, events, opts = {}) {
+    const body = { events };
+    if (opts.concurrency !== void 0) body.concurrency = opts.concurrency;
+    return this.cloud.request("POST", `/v1/functions/${encodeURIComponent(name)}/map`, body);
+  }
+};
+export {
+  ACTOR_HEADER,
+  AGENT_TOKEN_HEADER,
+  APPROVAL_HEADER,
+  CLOUD_KEY_PREFIX,
+  CheckpointBook,
+  CloudFunctions,
+  CloudSandbox,
+  CloudSandboxes,
+  DEFAULT_CLOUD_URL,
+  FileCheckpointStore,
+  Kosa8ApiError,
+  Kosa8ApprovalRequiredError,
+  Kosa8AuthError,
+  Kosa8BadRequestError,
+  Kosa8CheckpointError,
+  Kosa8Client,
+  Kosa8Cloud,
+  Kosa8ConflictError,
+  Kosa8ConnectionError,
+  Kosa8Error,
+  Kosa8NotFoundError,
+  Kosa8PaymentRequiredError,
+  Kosa8PolicyError,
+  Kosa8RateLimitError,
+  Kosa8StreamError,
+  Kosa8TimeoutError,
+  Kosa8UnsupportedError,
+  MAX_CHECKPOINTS_PER_SANDBOX,
+  MemoryCheckpointStore,
+  SandboxHandle,
+  Transport,
+  defaultSocketPath,
+  defaultWorkerFile,
+  errorFromResponse,
+  resolveEndpoint,
+  tarContext,
+  validateSandboxName
+};
+//# sourceMappingURL=index.js.map