@lizard-build/sdk 0.1.31 → 0.1.33

package/dist/index.d.mts

@@ -12,6 +12,15 @@ declare class ConnectionConfig {
     get headers(): Record<string, string>;
 }
 
+/** A process this sandbox is currently running. */
+interface ProcessInfo {
+    pid: number;
+    cmd: string[];
+    /** When the process started, unix milliseconds. */
+    startedAt: number;
+}
+/** Signals accepted by {@link Process.kill}. */
+type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
 /**
  * The result of a process execution inside a Lizard microVM.
  */
@@ -25,8 +34,15 @@ interface ProcessOpts {
     envs?: Record<string, string>;
     user?: string;
     workdir?: string;
+    /** Called with each stdout line as it is produced, rather than at the end. */
     onStdout?: (data: string) => void;
+    /** Called with each stderr line as it is produced, rather than at the end. */
     onStderr?: (data: string) => void;
+    /**
+     * Called once with the process's pid, before any output. Gives a streaming
+     * `exec` something to pass to {@link Process.kill}.
+     */
+    onPid?: (pid: number) => void;
 }
 /**
  * Runs processes inside a Lizard sandbox microVM.
@@ -62,11 +78,55 @@ declare class Process {
      * ```
      */
     exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    /**
+     * Read an SSE exec stream, handing each line to the caller as it arrives while
+     * still accumulating the full result. Events are `{stream, line}` for output and
+     * `{exitCode}` at the end.
+     */
+    /**
+     * List the processes this sandbox is currently running.
+     *
+     * Only processes started through `exec` — not every process in the guest.
+     * Those are the ones you can act on; the rest are the image's own business.
+     *
+     * @example
+     * ```ts
+     * for (const p of await sandbox.process.list()) {
+     *   console.log(p.pid, p.cmd.join(' '))
+     * }
+     * ```
+     */
+    list(): Promise<ProcessInfo[]>;
+    /**
+     * Signal a running process. Defaults to `SIGTERM`.
+     *
+     * The signal goes to the process group, so a shell's children die with it —
+     * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+     *
+     * The pid comes from {@link list}, or from the `pid` event at the start of a
+     * streaming `exec`.
+     *
+     * @example Stop a long build:
+     * ```ts
+     * const [build] = await sandbox.process.list()
+     * await sandbox.process.kill(build.pid)
+     * ```
+     */
+    kill(pid: number, signal?: ProcessSignal): Promise<void>;
+    private consumeStream;
 }
 
 interface FsOpts {
     user?: string;
 }
+/** A filesystem change reported by a {@link Watcher}. */
+interface FsEvent {
+    type: 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+    /** The entry's name within its directory. */
+    name: string;
+    /** Full path inside the sandbox. */
+    path: string;
+}
 interface FileInfo {
     name: string;
     path: string;
@@ -159,8 +219,52 @@ declare class Fs {
      * `LizardError` (501) — recreate the sandbox to use it.
      */
     move(from: string, to: string): Promise<void>;
+    /**
+     * Watch a directory for changes.
+     *
+     * Polling rather than a push stream: the events cross two proxy hops, and a
+     * long-lived stream through both is exactly what breaks first. Call
+     * {@link Watcher.getEvents} on whatever interval suits you — each call drains
+     * everything queued since the last one, so nothing is missed between polls.
+     *
+     * Remember to {@link Watcher.close} it; an abandoned watcher keeps queueing
+     * events in the guest until the sandbox ends (bounded, but wasted).
+     *
+     * @example
+     * ```ts
+     * const w = await sandbox.fs.watch('/app', { recursive: true })
+     * setInterval(async () => {
+     *   for (const e of await w.getEvents()) console.log(e.type, e.path)
+     * }, 1000)
+     * ```
+     *
+     * Sandboxes created before this shipped run a guest agent without it and throw
+     * `LizardError` (501) — recreate the sandbox to use it.
+     */
+    watch(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<Watcher>;
     private execInternal;
 }
+/**
+ * A handle to a directory watch inside a sandbox. Created by {@link Fs.watch}.
+ */
+declare class Watcher {
+    private readonly sandboxId;
+    private readonly config;
+    /** Server-side id for this watch. */
+    readonly watcherId: string;
+    constructor(sandboxId: string, config: ConnectionConfig, 
+    /** Server-side id for this watch. */
+    watcherId: string);
+    /**
+     * Drain every change since the last call. Returns an empty array when nothing
+     * has happened — that is not an error, just a quiet interval.
+     */
+    getEvents(): Promise<FsEvent[]>;
+    /** Stop watching and release the guest-side queue. */
+    close(): Promise<void>;
+}
 
 interface SandboxInfo {
     sandboxId: string;

package/dist/index.d.ts

@@ -12,6 +12,15 @@ declare class ConnectionConfig {
     get headers(): Record<string, string>;
 }
 
+/** A process this sandbox is currently running. */
+interface ProcessInfo {
+    pid: number;
+    cmd: string[];
+    /** When the process started, unix milliseconds. */
+    startedAt: number;
+}
+/** Signals accepted by {@link Process.kill}. */
+type ProcessSignal = 'SIGTERM' | 'SIGKILL' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR1' | 'SIGUSR2';
 /**
  * The result of a process execution inside a Lizard microVM.
  */
@@ -25,8 +34,15 @@ interface ProcessOpts {
     envs?: Record<string, string>;
     user?: string;
     workdir?: string;
+    /** Called with each stdout line as it is produced, rather than at the end. */
     onStdout?: (data: string) => void;
+    /** Called with each stderr line as it is produced, rather than at the end. */
     onStderr?: (data: string) => void;
+    /**
+     * Called once with the process's pid, before any output. Gives a streaming
+     * `exec` something to pass to {@link Process.kill}.
+     */
+    onPid?: (pid: number) => void;
 }
 /**
  * Runs processes inside a Lizard sandbox microVM.
@@ -62,11 +78,55 @@ declare class Process {
      * ```
      */
     exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    /**
+     * Read an SSE exec stream, handing each line to the caller as it arrives while
+     * still accumulating the full result. Events are `{stream, line}` for output and
+     * `{exitCode}` at the end.
+     */
+    /**
+     * List the processes this sandbox is currently running.
+     *
+     * Only processes started through `exec` — not every process in the guest.
+     * Those are the ones you can act on; the rest are the image's own business.
+     *
+     * @example
+     * ```ts
+     * for (const p of await sandbox.process.list()) {
+     *   console.log(p.pid, p.cmd.join(' '))
+     * }
+     * ```
+     */
+    list(): Promise<ProcessInfo[]>;
+    /**
+     * Signal a running process. Defaults to `SIGTERM`.
+     *
+     * The signal goes to the process group, so a shell's children die with it —
+     * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+     *
+     * The pid comes from {@link list}, or from the `pid` event at the start of a
+     * streaming `exec`.
+     *
+     * @example Stop a long build:
+     * ```ts
+     * const [build] = await sandbox.process.list()
+     * await sandbox.process.kill(build.pid)
+     * ```
+     */
+    kill(pid: number, signal?: ProcessSignal): Promise<void>;
+    private consumeStream;
 }
 
 interface FsOpts {
     user?: string;
 }
+/** A filesystem change reported by a {@link Watcher}. */
+interface FsEvent {
+    type: 'create' | 'write' | 'remove' | 'rename' | 'chmod';
+    /** The entry's name within its directory. */
+    name: string;
+    /** Full path inside the sandbox. */
+    path: string;
+}
 interface FileInfo {
     name: string;
     path: string;
@@ -159,8 +219,52 @@ declare class Fs {
      * `LizardError` (501) — recreate the sandbox to use it.
      */
     move(from: string, to: string): Promise<void>;
+    /**
+     * Watch a directory for changes.
+     *
+     * Polling rather than a push stream: the events cross two proxy hops, and a
+     * long-lived stream through both is exactly what breaks first. Call
+     * {@link Watcher.getEvents} on whatever interval suits you — each call drains
+     * everything queued since the last one, so nothing is missed between polls.
+     *
+     * Remember to {@link Watcher.close} it; an abandoned watcher keeps queueing
+     * events in the guest until the sandbox ends (bounded, but wasted).
+     *
+     * @example
+     * ```ts
+     * const w = await sandbox.fs.watch('/app', { recursive: true })
+     * setInterval(async () => {
+     *   for (const e of await w.getEvents()) console.log(e.type, e.path)
+     * }, 1000)
+     * ```
+     *
+     * Sandboxes created before this shipped run a guest agent without it and throw
+     * `LizardError` (501) — recreate the sandbox to use it.
+     */
+    watch(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<Watcher>;
     private execInternal;
 }
+/**
+ * A handle to a directory watch inside a sandbox. Created by {@link Fs.watch}.
+ */
+declare class Watcher {
+    private readonly sandboxId;
+    private readonly config;
+    /** Server-side id for this watch. */
+    readonly watcherId: string;
+    constructor(sandboxId: string, config: ConnectionConfig, 
+    /** Server-side id for this watch. */
+    watcherId: string);
+    /**
+     * Drain every change since the last call. Returns an empty array when nothing
+     * has happened — that is not an error, just a quiet interval.
+     */
+    getEvents(): Promise<FsEvent[]>;
+    /** Stop watching and release the guest-side queue. */
+    close(): Promise<void>;
+}
 
 interface SandboxInfo {
     sandboxId: string;

package/dist/index.js

@@ -163,9 +163,10 @@ var Process = class {
    * ```
    */
   async exec(cmd, opts) {
+    const streaming = Boolean(opts?.onStdout || opts?.onStderr || opts?.onPid);
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
-      headers: this.config.headers,
+      headers: streaming ? { ...this.config.headers, Accept: "text/event-stream" } : this.config.headers,
       body: JSON.stringify({
         cmd,
         envs: opts?.envs,
@@ -176,8 +177,96 @@ var Process = class {
       signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
     });
     if (!res.ok) await handleApiError(res);
+    if (!streaming) return res.json();
+    return this.consumeStream(res, opts);
+  }
+  /**
+   * Read an SSE exec stream, handing each line to the caller as it arrives while
+   * still accumulating the full result. Events are `{stream, line}` for output and
+   * `{exitCode}` at the end.
+   */
+  /**
+   * List the processes this sandbox is currently running.
+   *
+   * Only processes started through `exec` — not every process in the guest.
+   * Those are the ones you can act on; the rest are the image's own business.
+   *
+   * @example
+   * ```ts
+   * for (const p of await sandbox.process.list()) {
+   *   console.log(p.pid, p.cmd.join(' '))
+   * }
+   * ```
+   */
+  async list() {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/processes`, {
+      headers: this.config.headers
+    });
+    if (!res.ok) await handleApiError(res);
     return res.json();
   }
+  /**
+   * Signal a running process. Defaults to `SIGTERM`.
+   *
+   * The signal goes to the process group, so a shell's children die with it —
+   * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+   *
+   * The pid comes from {@link list}, or from the `pid` event at the start of a
+   * streaming `exec`.
+   *
+   * @example Stop a long build:
+   * ```ts
+   * const [build] = await sandbox.process.list()
+   * await sandbox.process.kill(build.pid)
+   * ```
+   */
+  async kill(pid, signal = "SIGTERM") {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/processes/signal`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ pid, signal })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+  async consumeStream(res, opts) {
+    const reader = res.body?.getReader();
+    if (!reader) return { stdout: "", stderr: "", exitCode: 0 };
+    const decoder = new TextDecoder();
+    let buf = "";
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    const handle = (raw) => {
+      if (!raw.startsWith("data:")) return;
+      let ev;
+      try {
+        ev = JSON.parse(raw.slice(5).trim());
+      } catch {
+        return;
+      }
+      if (ev.line !== void 0) {
+        if (ev.stream === "stderr") {
+          stderr += ev.line + "\n";
+          opts.onStderr?.(ev.line);
+        } else {
+          stdout += ev.line + "\n";
+          opts.onStdout?.(ev.line);
+        }
+      }
+      if (ev.pid !== void 0) opts.onPid?.(ev.pid);
+      if (ev.exitCode !== void 0) exitCode = ev.exitCode;
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const l of lines) handle(l);
+    }
+    if (buf) handle(buf);
+    return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode };
+  }
 };
 
 // src/sandbox/fs.ts
@@ -304,6 +393,38 @@ var Fs = class {
     });
     if (!res.ok) await handleApiError(res);
   }
+  /**
+   * Watch a directory for changes.
+   *
+   * Polling rather than a push stream: the events cross two proxy hops, and a
+   * long-lived stream through both is exactly what breaks first. Call
+   * {@link Watcher.getEvents} on whatever interval suits you — each call drains
+   * everything queued since the last one, so nothing is missed between polls.
+   *
+   * Remember to {@link Watcher.close} it; an abandoned watcher keeps queueing
+   * events in the guest until the sandbox ends (bounded, but wasted).
+   *
+   * @example
+   * ```ts
+   * const w = await sandbox.fs.watch('/app', { recursive: true })
+   * setInterval(async () => {
+   *   for (const e of await w.getEvents()) console.log(e.type, e.path)
+   * }, 1000)
+   * ```
+   *
+   * Sandboxes created before this shipped run a guest agent without it and throw
+   * `LizardError` (501) — recreate the sandbox to use it.
+   */
+  async watch(path, opts) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ path, recursive: opts?.recursive ?? false })
+    });
+    if (!res.ok) await handleApiError(res);
+    const { watcherId } = await res.json();
+    return new Watcher(this.sandboxId, this.config, watcherId);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
@@ -313,6 +434,31 @@ var Fs = class {
     if (!res.ok) await handleApiError(res);
   }
 };
+var Watcher = class {
+  constructor(sandboxId, config, watcherId) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+    this.watcherId = watcherId;
+  }
+  /**
+   * Drain every change since the last call. Returns an empty array when nothing
+   * has happened — that is not an error, just a quiet interval.
+   */
+  async getEvents() {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch/events`);
+    url.searchParams.set("watcherId", this.watcherId);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /** Stop watching and release the guest-side queue. */
+  async close() {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`);
+    url.searchParams.set("watcherId", this.watcherId);
+    const res = await fetch(url.toString(), { method: "DELETE", headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+  }
+};
 
 // src/sandbox/client.ts
 var SandboxClient = class {

package/dist/index.mjs

@@ -127,9 +127,10 @@ var Process = class {
    * ```
    */
   async exec(cmd, opts) {
+    const streaming = Boolean(opts?.onStdout || opts?.onStderr || opts?.onPid);
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
-      headers: this.config.headers,
+      headers: streaming ? { ...this.config.headers, Accept: "text/event-stream" } : this.config.headers,
       body: JSON.stringify({
         cmd,
         envs: opts?.envs,
@@ -140,8 +141,96 @@ var Process = class {
       signal: AbortSignal.timeout(opts?.timeoutMs ?? 6e4)
     });
     if (!res.ok) await handleApiError(res);
+    if (!streaming) return res.json();
+    return this.consumeStream(res, opts);
+  }
+  /**
+   * Read an SSE exec stream, handing each line to the caller as it arrives while
+   * still accumulating the full result. Events are `{stream, line}` for output and
+   * `{exitCode}` at the end.
+   */
+  /**
+   * List the processes this sandbox is currently running.
+   *
+   * Only processes started through `exec` — not every process in the guest.
+   * Those are the ones you can act on; the rest are the image's own business.
+   *
+   * @example
+   * ```ts
+   * for (const p of await sandbox.process.list()) {
+   *   console.log(p.pid, p.cmd.join(' '))
+   * }
+   * ```
+   */
+  async list() {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/processes`, {
+      headers: this.config.headers
+    });
+    if (!res.ok) await handleApiError(res);
     return res.json();
   }
+  /**
+   * Signal a running process. Defaults to `SIGTERM`.
+   *
+   * The signal goes to the process group, so a shell's children die with it —
+   * killing `sh -c 'sleep 100'` otherwise leaves the sleep running.
+   *
+   * The pid comes from {@link list}, or from the `pid` event at the start of a
+   * streaming `exec`.
+   *
+   * @example Stop a long build:
+   * ```ts
+   * const [build] = await sandbox.process.list()
+   * await sandbox.process.kill(build.pid)
+   * ```
+   */
+  async kill(pid, signal = "SIGTERM") {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/processes/signal`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ pid, signal })
+    });
+    if (!res.ok) await handleApiError(res);
+  }
+  async consumeStream(res, opts) {
+    const reader = res.body?.getReader();
+    if (!reader) return { stdout: "", stderr: "", exitCode: 0 };
+    const decoder = new TextDecoder();
+    let buf = "";
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    const handle = (raw) => {
+      if (!raw.startsWith("data:")) return;
+      let ev;
+      try {
+        ev = JSON.parse(raw.slice(5).trim());
+      } catch {
+        return;
+      }
+      if (ev.line !== void 0) {
+        if (ev.stream === "stderr") {
+          stderr += ev.line + "\n";
+          opts.onStderr?.(ev.line);
+        } else {
+          stdout += ev.line + "\n";
+          opts.onStdout?.(ev.line);
+        }
+      }
+      if (ev.pid !== void 0) opts.onPid?.(ev.pid);
+      if (ev.exitCode !== void 0) exitCode = ev.exitCode;
+    };
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const lines = buf.split("\n");
+      buf = lines.pop() ?? "";
+      for (const l of lines) handle(l);
+    }
+    if (buf) handle(buf);
+    return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), exitCode };
+  }
 };
 
 // src/sandbox/fs.ts
@@ -268,6 +357,38 @@ var Fs = class {
     });
     if (!res.ok) await handleApiError(res);
   }
+  /**
+   * Watch a directory for changes.
+   *
+   * Polling rather than a push stream: the events cross two proxy hops, and a
+   * long-lived stream through both is exactly what breaks first. Call
+   * {@link Watcher.getEvents} on whatever interval suits you — each call drains
+   * everything queued since the last one, so nothing is missed between polls.
+   *
+   * Remember to {@link Watcher.close} it; an abandoned watcher keeps queueing
+   * events in the guest until the sandbox ends (bounded, but wasted).
+   *
+   * @example
+   * ```ts
+   * const w = await sandbox.fs.watch('/app', { recursive: true })
+   * setInterval(async () => {
+   *   for (const e of await w.getEvents()) console.log(e.type, e.path)
+   * }, 1000)
+   * ```
+   *
+   * Sandboxes created before this shipped run a guest agent without it and throw
+   * `LizardError` (501) — recreate the sandbox to use it.
+   */
+  async watch(path, opts) {
+    const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`, {
+      method: "POST",
+      headers: this.config.headers,
+      body: JSON.stringify({ path, recursive: opts?.recursive ?? false })
+    });
+    if (!res.ok) await handleApiError(res);
+    const { watcherId } = await res.json();
+    return new Watcher(this.sandboxId, this.config, watcherId);
+  }
   async execInternal(cmd, user) {
     const res = await fetch(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/exec`, {
       method: "POST",
@@ -277,6 +398,31 @@ var Fs = class {
     if (!res.ok) await handleApiError(res);
   }
 };
+var Watcher = class {
+  constructor(sandboxId, config, watcherId) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+    this.watcherId = watcherId;
+  }
+  /**
+   * Drain every change since the last call. Returns an empty array when nothing
+   * has happened — that is not an error, just a quiet interval.
+   */
+  async getEvents() {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch/events`);
+    url.searchParams.set("watcherId", this.watcherId);
+    const res = await fetch(url.toString(), { headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+    return res.json();
+  }
+  /** Stop watching and release the guest-side queue. */
+  async close() {
+    const url = new URL(`${this.config.apiUrl}/api/sandboxes/${this.sandboxId}/files/watch`);
+    url.searchParams.set("watcherId", this.watcherId);
+    const res = await fetch(url.toString(), { method: "DELETE", headers: this.config.headers });
+    if (!res.ok) await handleApiError(res);
+  }
+};
 
 // src/sandbox/client.ts
 var SandboxClient = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Firecracker microVM sandboxes for AI agents — boot Linux in milliseconds, run code, write files, expose ports over HTTPS, then pause a session with memory intact and resume it later. TypeScript SDK for Lizard Sandboxes (lizard.build).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",