@slicervm/sdk 0.1.4 → 0.1.5

package/README.md

@@ -23,6 +23,13 @@ console.log(result.stdout);
 await vm.fs.writeFile('/tmp/hello.txt', 'hi');
 console.log((await vm.fs.readFile('/tmp/hello.txt')).toString());
 
+// Background exec — detached, survives disconnect, logs into an agent-side
+// ring buffer. Manage via vm.bg.list/info/logs/kill/wait/remove.
+const bg = await vm.bg.exec({ command: 'npm', args: ['run', 'dev'], cwd: '/app' });
+for await (const f of vm.bg.logs(bg.execId, { follow: true })) {
+  if (f.stdoutBytes) process.stdout.write(f.stdoutBytes);
+}
+
 await vm.delete();
 ```
 

package/dist/index.cjs

@@ -745,6 +745,7 @@ var VM = class {
   createdAt;
   arch;
   fs;
+  bg;
   transport;
   constructor(transport, init) {
     this.transport = transport;
@@ -754,6 +755,7 @@ var VM = class {
     if (init.createdAt !== void 0) this.createdAt = init.createdAt;
     if (init.arch !== void 0) this.arch = init.arch;
     this.fs = new VMFileSystem(transport, this.hostname);
+    this.bg = new VMBg(transport, this.hostname);
   }
   // --- lifecycle --------------------------------------------------------
   async delete() {
@@ -955,6 +957,169 @@ function sleep(ms) {
 function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
+var VMBg = class {
+  constructor(transport, hostname) {
+    this.transport = transport;
+    this.hostname = hostname;
+  }
+  transport;
+  hostname;
+  /**
+   * Launch a long-running process. `command` + `args` is the deterministic
+   * exec form (no shell). Set `shell: '/bin/bash'` (or similar) to opt in
+   * to shell semantics — `$VAR` expansion, globs, `&&`/`||`, etc.
+   */
+  async exec(req) {
+    if (!req.command) throw new Error("vm.bg.exec: command is required");
+    const q = new URLSearchParams();
+    q.set("background", "true");
+    q.set("cmd", req.command);
+    for (const a of req.args ?? []) q.append("args", a);
+    for (const e of req.env ?? []) q.append("env", e);
+    if (req.uid !== void 0 && req.uid !== 0) q.set("uid", String(req.uid));
+    if (req.gid !== void 0 && req.gid !== 0) q.set("gid", String(req.gid));
+    if (req.shell) q.set("shell", req.shell);
+    if (req.cwd) q.set("cwd", req.cwd);
+    if (req.ringBytes !== void 0 && req.ringBytes > 0) {
+      q.set("ring_bytes", String(req.ringBytes));
+    }
+    q.set("stdio", "base64");
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec?${q.toString()}`;
+    const wire = await this.transport.request("POST", path3);
+    return bgExecResponseFromWire(wire);
+  }
+  /** All background execs the agent currently tracks (running + exited-not-reaped). */
+  async list() {
+    const wire = await this.transport.request(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/exec`
+    );
+    return (wire ?? []).map(bgExecInfoFromWire);
+  }
+  /** Latest status snapshot for one bg exec. Throws 404 if reaped or never existed. */
+  async info(execId) {
+    const wire = await this.transport.request(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}`
+    );
+    return bgExecInfoFromWire(wire);
+  }
+  /**
+   * NDJSON log stream. Yields one frame per log line — `started`, `stdout`,
+   * `stderr`, `exit`, plus optional `gap` frames if the ring evicted history
+   * before the requested cursor. Frames carry `data` base64-encoded; the SDK
+   * also populates `dataBytes` / `stdoutBytes` / `stderrBytes` Buffers.
+   *
+   * `follow: false` (default) replays from the cursor and ends when the ring
+   * is drained. `follow: true` keeps the stream open until the child exits or
+   * the caller breaks out.
+   */
+  async *logs(execId, opts = {}) {
+    const q = new URLSearchParams();
+    if (opts.follow) q.set("follow", "true");
+    if (opts.fromId !== void 0 && opts.fromId > 0) q.set("from_id", String(opts.fromId));
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/logs` + (q.toString() ? `?${q.toString()}` : "");
+    for await (const raw of this.transport.requestNDJSON("GET", path3)) {
+      const frame = normalizeExecFrame(raw);
+      if (frame.encoding === "base64") {
+        if (frame.data) frame.dataBytes = Buffer.from(frame.data, "base64");
+        if (frame.stdout) frame.stdoutBytes = Buffer.from(frame.stdout, "base64");
+        if (frame.stderr) frame.stderrBytes = Buffer.from(frame.stderr, "base64");
+      }
+      yield frame;
+    }
+  }
+  /**
+   * Signal a running bg exec. Default: SIGTERM with a 5 s grace period before
+   * the agent escalates to SIGKILL. No-op (running=false) if the child has
+   * already exited.
+   */
+  async kill(execId, opts = {}) {
+    const body = {};
+    if (opts.signal) body.signal = opts.signal;
+    if (opts.graceMs !== void 0) body.grace_ms = opts.graceMs;
+    const wire = await this.transport.request(
+      "POST",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/kill`,
+      body
+    );
+    return bgKillResponseFromWire(wire);
+  }
+  /**
+   * Long-poll until the child exits or `timeoutSec` elapses. Returns
+   * `timedOut: true` if the deadline hit. Server default for `timeoutSec=0`
+   * is 30 s.
+   */
+  async wait(execId, timeoutSec = 0) {
+    const q = new URLSearchParams();
+    if (timeoutSec > 0) q.set("timeout", String(timeoutSec));
+    const path3 = `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}/wait-exit` + (q.toString() ? `?${q.toString()}` : "");
+    const wire = await this.transport.request("GET", path3);
+    return bgWaitExitFromWire(wire);
+  }
+  /**
+   * Reap a bg exec's ring buffer + registry entry. Does NOT kill a running
+   * process — pair with `kill()` for "stop and clean up". After remove,
+   * info/logs/kill/wait return 410 Gone.
+   */
+  async remove(execId) {
+    const wire = await this.transport.request(
+      "DELETE",
+      `/vm/${encodeURIComponent(this.hostname)}/exec/${encodeURIComponent(execId)}`
+    );
+    return bgDeleteFromWire(wire);
+  }
+};
+function bgExecResponseFromWire(w) {
+  return {
+    execId: w.exec_id,
+    pid: w.pid,
+    startedAt: w.started_at,
+    ringBytes: w.ring_bytes
+  };
+}
+function bgExecInfoFromWire(w) {
+  const out = {
+    execId: w.exec_id,
+    pid: w.pid,
+    command: w.command,
+    startedAt: w.started_at,
+    running: w.running,
+    bytesWritten: w.bytes_written,
+    bytesDropped: w.bytes_dropped,
+    nextId: w.next_id,
+    ringBytes: w.ring_bytes
+  };
+  if (w.args !== void 0) out.args = w.args;
+  if (w.cwd !== void 0) out.cwd = w.cwd;
+  if (w.uid !== void 0) out.uid = w.uid;
+  if (w.exit_code !== void 0) out.exitCode = w.exit_code;
+  if (w.signal !== void 0) out.signal = w.signal;
+  if (w.ended_at !== void 0) out.endedAt = w.ended_at;
+  return out;
+}
+function bgKillResponseFromWire(w) {
+  return {
+    execId: w.exec_id,
+    pid: w.pid,
+    running: w.running,
+    signalSent: w.signal_sent
+  };
+}
+function bgWaitExitFromWire(w) {
+  const out = {
+    execId: w.exec_id,
+    running: w.running,
+    timedOut: w.timed_out
+  };
+  if (w.exit_code !== void 0) out.exitCode = w.exit_code;
+  if (w.signal !== void 0) out.signal = w.signal;
+  if (w.ended_at !== void 0) out.endedAt = w.ended_at;
+  return out;
+}
+function bgDeleteFromWire(w) {
+  return { execId: w.exec_id, reaped: w.reaped };
+}
 
 // src/namespaces.ts
 var HostGroupsAPI = class {
@@ -1136,6 +1301,7 @@ exports.SecretsAPI = SecretsAPI;
 exports.SlicerAPIError = SlicerAPIError;
 exports.SlicerClient = SlicerClient;
 exports.VM = VM;
+exports.VMBg = VMBg;
 exports.VMFileSystem = VMFileSystem;
 exports.VMsAPI = VMsAPI;
 exports.parseAddressMapping = parseAddressMapping;