@slicervm/sdk 0.1.4 → 0.1.6

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) q.set("uid", String(req.uid));
+    if (req.gid !== void 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 {
@@ -1124,8 +1289,153 @@ var SlicerClient = class _SlicerClient {
   }
 };
 
+// src/shell.ts
+var FRAME_TYPE_DATA = 1;
+var FRAME_TYPE_WINDOW_SIZE = 2;
+var FRAME_TYPE_SHUTDOWN = 3;
+var FRAME_TYPE_HEARTBEAT = 4;
+var FRAME_TYPE_SESSION_CLOSE = 5;
+var HEADER_SIZE = 5;
+function encodeFrame(frameType, payload) {
+  const payloadLen = payload ? payload.byteLength : 0;
+  const buf = new Uint8Array(HEADER_SIZE + payloadLen);
+  const view = new DataView(buf.buffer);
+  view.setUint8(0, frameType);
+  view.setUint32(1, payloadLen, false);
+  if (payload) buf.set(payload, HEADER_SIZE);
+  return buf;
+}
+function parseFrame(data) {
+  if (data.byteLength < HEADER_SIZE) return null;
+  const view = new DataView(data);
+  const frameType = view.getUint8(0);
+  const payloadLen = view.getUint32(1, false);
+  if (data.byteLength < HEADER_SIZE + payloadLen) return null;
+  const payload = new Uint8Array(data, HEADER_SIZE, payloadLen);
+  return { frameType, payload };
+}
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var SlicerShellSession = class {
+  constructor(terminal, options) {
+    this.terminal = terminal;
+    this.options = options;
+  }
+  terminal;
+  options;
+  ws = null;
+  heartbeatTimer = null;
+  dataDisposable = null;
+  /** True when the WebSocket is open and relaying. */
+  get connected() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /** Open the WebSocket and begin relaying. */
+  connect() {
+    if (this.ws) return;
+    this.options.onStateChange?.("connecting");
+    const ws = new WebSocket(this.options.url);
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+    ws.onopen = () => {
+      this.options.onStateChange?.("connected");
+      this.terminal.reset();
+      this.sendResize(this.terminal.cols, this.terminal.rows);
+      this.startHeartbeat();
+    };
+    ws.onmessage = (ev) => {
+      if (!(ev.data instanceof ArrayBuffer)) return;
+      const frame = parseFrame(ev.data);
+      if (!frame) return;
+      switch (frame.frameType) {
+        case FRAME_TYPE_DATA:
+          this.terminal.write(decoder.decode(frame.payload));
+          break;
+        case FRAME_TYPE_SHUTDOWN:
+        case FRAME_TYPE_SESSION_CLOSE:
+          this.teardown();
+          break;
+      }
+    };
+    ws.onclose = () => {
+      this.teardown();
+    };
+    ws.onerror = () => {
+      this.options.onError?.("WebSocket error");
+      this.teardown();
+    };
+    this.dataDisposable = this.terminal.onData((data) => {
+      if (!this.connected) return;
+      const payload = encoder.encode(data);
+      this.ws.send(encodeFrame(FRAME_TYPE_DATA, payload));
+    });
+  }
+  /** Send a graceful shutdown frame and close. */
+  disconnect() {
+    if (this.ws) {
+      try {
+        this.ws.send(encodeFrame(FRAME_TYPE_SHUTDOWN));
+      } catch {
+      }
+    }
+    this.teardown();
+  }
+  /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+  resize(cols, rows) {
+    if (!this.connected) return;
+    this.sendResize(cols, rows);
+  }
+  // --- internals -------------------------------------------------------------
+  sendResize(cols, rows) {
+    const payload = new Uint8Array(8);
+    const view = new DataView(payload.buffer);
+    view.setUint32(0, cols, false);
+    view.setUint32(4, rows, false);
+    this.ws.send(encodeFrame(FRAME_TYPE_WINDOW_SIZE, payload));
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    const intervalMs = this.options.heartbeatIntervalMs ?? 3e4;
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.connected) return;
+      this.ws.send(encodeFrame(FRAME_TYPE_HEARTBEAT));
+    }, intervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer !== null) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  teardown() {
+    this.stopHeartbeat();
+    if (this.dataDisposable) {
+      this.dataDisposable.dispose();
+      this.dataDisposable = null;
+    }
+    if (this.ws) {
+      const ws = this.ws;
+      this.ws = null;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      try {
+        ws.close();
+      } catch {
+      }
+    }
+    this.options.onStateChange?.("disconnected");
+  }
+};
+
 exports.ExecStdioBase64 = ExecStdioBase64;
 exports.ExecStdioText = ExecStdioText;
+exports.FRAME_TYPE_DATA = FRAME_TYPE_DATA;
+exports.FRAME_TYPE_HEARTBEAT = FRAME_TYPE_HEARTBEAT;
+exports.FRAME_TYPE_SESSION_CLOSE = FRAME_TYPE_SESSION_CLOSE;
+exports.FRAME_TYPE_SHUTDOWN = FRAME_TYPE_SHUTDOWN;
+exports.FRAME_TYPE_WINDOW_SIZE = FRAME_TYPE_WINDOW_SIZE;
 exports.Forwarder = Forwarder;
 exports.GiB = GiB;
 exports.HostGroupsAPI = HostGroupsAPI;
@@ -1135,10 +1445,14 @@ exports.SecretExistsError = SecretExistsError;
 exports.SecretsAPI = SecretsAPI;
 exports.SlicerAPIError = SlicerAPIError;
 exports.SlicerClient = SlicerClient;
+exports.SlicerShellSession = SlicerShellSession;
 exports.VM = VM;
+exports.VMBg = VMBg;
 exports.VMFileSystem = VMFileSystem;
 exports.VMsAPI = VMsAPI;
+exports.encodeFrame = encodeFrame;
 exports.parseAddressMapping = parseAddressMapping;
+exports.parseFrame = parseFrame;
 exports.resolveTransport = resolveTransport;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map