@kosa8/sdk 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -33,7 +33,12 @@ __export(index_exports, {
   ACTOR_HEADER: () => ACTOR_HEADER,
   AGENT_TOKEN_HEADER: () => AGENT_TOKEN_HEADER,
   APPROVAL_HEADER: () => APPROVAL_HEADER,
+  CLOUD_KEY_PREFIX: () => CLOUD_KEY_PREFIX,
   CheckpointBook: () => CheckpointBook,
+  CloudFunctions: () => CloudFunctions,
+  CloudSandbox: () => CloudSandbox,
+  CloudSandboxes: () => CloudSandboxes,
+  DEFAULT_CLOUD_URL: () => DEFAULT_CLOUD_URL,
   FileCheckpointStore: () => FileCheckpointStore,
   Kosa8ApiError: () => Kosa8ApiError,
   Kosa8ApprovalRequiredError: () => Kosa8ApprovalRequiredError,
@@ -41,20 +46,26 @@ __export(index_exports, {
   Kosa8BadRequestError: () => Kosa8BadRequestError,
   Kosa8CheckpointError: () => Kosa8CheckpointError,
   Kosa8Client: () => Kosa8Client,
+  Kosa8Cloud: () => Kosa8Cloud,
   Kosa8ConflictError: () => Kosa8ConflictError,
   Kosa8ConnectionError: () => Kosa8ConnectionError,
   Kosa8Error: () => Kosa8Error,
   Kosa8NotFoundError: () => Kosa8NotFoundError,
+  Kosa8PaymentRequiredError: () => Kosa8PaymentRequiredError,
   Kosa8PolicyError: () => Kosa8PolicyError,
+  Kosa8RateLimitError: () => Kosa8RateLimitError,
   Kosa8StreamError: () => Kosa8StreamError,
+  Kosa8TimeoutError: () => Kosa8TimeoutError,
   Kosa8UnsupportedError: () => Kosa8UnsupportedError,
   MAX_CHECKPOINTS_PER_SANDBOX: () => MAX_CHECKPOINTS_PER_SANDBOX,
   MemoryCheckpointStore: () => MemoryCheckpointStore,
   SandboxHandle: () => SandboxHandle,
   Transport: () => Transport,
   defaultSocketPath: () => defaultSocketPath,
+  defaultWorkerFile: () => defaultWorkerFile,
   errorFromResponse: () => errorFromResponse,
   resolveEndpoint: () => resolveEndpoint,
+  tarContext: () => tarContext,
   validateSandboxName: () => validateSandboxName
 });
 module.exports = __toCommonJS(index_exports);
@@ -76,6 +87,8 @@ var Kosa8Error = class extends Error {
   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;
@@ -85,10 +98,13 @@ var Kosa8Error = class extends Error {
     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 {
@@ -119,6 +135,10 @@ var Kosa8StreamError = class extends Kosa8Error {
     this.stderr = out.stderr;
   }
 };
+var Kosa8PaymentRequiredError = class extends Kosa8ApiError {
+};
+var Kosa8RateLimitError = class extends Kosa8ApiError {
+};
 var Kosa8CheckpointError = class extends Kosa8Error {
 };
 function isRefusal(v) {
@@ -152,8 +172,12 @@ function errorFromResponse(status, body, ctx = {}) {
       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:
@@ -331,16 +355,136 @@ var CheckpointBook = class {
   }
 };
 
+// src/tar.ts
+var import_node_fs2 = require("fs");
+var path2 = __toESM(require("path"), 1);
+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 import_node_fs2.promises.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 import_node_fs2.promises.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 import_node_fs2.promises.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 import_node_fs2.promises.lstat(full);
+      const mtime = Math.floor(st.mtimeMs / 1e3);
+      if (st.isSymbolicLink()) {
+        entry(out, r, "2", st.mode, mtime, void 0, await import_node_fs2.promises.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 import_node_fs2.promises.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
+var fs2 = __toESM(require("fs"), 1);
 var http = __toESM(require("http"), 1);
 var https = __toESM(require("https"), 1);
 var os2 = __toESM(require("os"), 1);
-var path2 = __toESM(require("path"), 1);
+var path3 = __toESM(require("path"), 1);
 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");
+  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, "");
@@ -349,11 +493,20 @@ function isLoopback(hostname) {
 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() };
+  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);
   }
-  let h = raw;
+  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://")) {
@@ -369,13 +522,11 @@ function resolveEndpoint(opts) {
     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 {
@@ -467,7 +618,7 @@ var Transport = class {
         }
         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`)" : ""),
+            `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 }
           )
         );
@@ -580,6 +731,12 @@ function envList(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;
@@ -624,6 +781,11 @@ var Kosa8Client = class {
     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,
@@ -920,6 +1082,315 @@ var Kosa8Client = class {
     }
     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) {
@@ -1019,13 +1490,275 @@ var SandboxHandle = class {
   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);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACTOR_HEADER,
   AGENT_TOKEN_HEADER,
   APPROVAL_HEADER,
+  CLOUD_KEY_PREFIX,
   CheckpointBook,
+  CloudFunctions,
+  CloudSandbox,
+  CloudSandboxes,
+  DEFAULT_CLOUD_URL,
   FileCheckpointStore,
   Kosa8ApiError,
   Kosa8ApprovalRequiredError,
@@ -1033,20 +1766,26 @@ var SandboxHandle = class {
   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.cjs.map