@lizard-build/sdk 0.1.47 → 0.1.48

package/README.md

@@ -59,6 +59,24 @@ const result = await sandbox.process.exec('printf "hello\\n"', {
 if (result.exitCode !== 0) throw new Error(result.stderr)
 ```
 
+## Desktop (computer use)
+
+The `desktop` template runs XFCE and Chromium you can watch in a browser and an agent can drive:
+
+```ts
+import { Sandbox } from '@lizard-build/sdk'
+
+const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+const { url, viewOnlyUrl } = await sandbox.desktop.start() // open `url` in a browser
+await sandbox.desktop.openUrl('https://example.com')
+await sandbox.desktop.click(640, 400)
+await sandbox.desktop.type('hello')
+await sandbox.desktop.press('Return')
+const png: Uint8Array = await sandbox.desktop.screenshot()
+```
+
+Treat `url` like a credential: anyone with it can see and control the desktop. Share `viewOnlyUrl` when someone only needs to watch. See the [desktop guide](../../docs/sandboxes.md#desktop-computer-use).
+
 ## Run Python
 
 Run Python with the `interpreter` template. Each process command starts a separate Python process, so Python variables do not survive between calls. Save intermediate results to files. The API returns stdout, stderr, and an exit code; it does not return typed notebook results or chart objects.

package/dist/index.d.mts

@@ -401,6 +401,8 @@ interface ProcessResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /** Set when the platform cut the output off at its per-stream limit (512 KiB). */
+    truncated?: boolean;
 }
 interface ProcessOpts {
     timeoutMs?: number;
@@ -432,7 +434,9 @@ declare class Process {
      * The command runs in a shell inside the Lizard sandbox and returns
      * stdout, stderr, and the exit code when it finishes.
      *
-     * @param cmd Shell command to run inside the sandbox.
+     * @param cmd Shell command to run inside the sandbox, or an argv array that is
+     *   executed directly with no shell — nothing in it is interpreted, so it is the
+     *   safe way to pass untrusted text as an argument.
      * @param opts Optional execution options — environment variables, working
      *   directory, user, and timeout.
      *
@@ -442,6 +446,11 @@ declare class Process {
      * console.log(result.stdout)
      * ```
      *
+     * @example Pass untrusted text as an argument, not through a shell:
+     * ```ts
+     * await sandbox.process.exec(['grep', '-rn', '--', userQuery, '/workspace'])
+     * ```
+     *
      * @example Run with a custom working directory and env vars:
      * ```ts
      * const result = await sandbox.process.exec('npm test', {
@@ -450,7 +459,7 @@ declare class Process {
      * })
      * ```
      */
-    exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    exec(cmd: string | 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
@@ -642,6 +651,119 @@ declare class Watcher {
     close(): Promise<void>;
 }
 
+/**
+ * State of a sandbox's desktop, and the URLs that stream it.
+ *
+ * **Both URLs are credentials.** The port is published on a public hostname, and each
+ * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
+ * put them anywhere you would not put an API key.
+ */
+interface DesktopInfo {
+    running: boolean;
+    /** Screen width in pixels, or `null` when the desktop has never been started. */
+    width: number | null;
+    height: number | null;
+    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    url: string;
+    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    viewOnlyUrl: string;
+}
+interface DesktopStartOpts {
+    /** Screen width, 640–3840. Pass together with `height`; default 1280x800. */
+    width?: number;
+    /** Screen height, 480–2160. */
+    height?: number;
+}
+type MouseButton = 'left' | 'right' | 'middle';
+type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+interface ClickOpts {
+    /** Default `'left'`. */
+    button?: MouseButton;
+    /** Double-click instead of a single click. */
+    double?: boolean;
+}
+/**
+ * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
+ *
+ * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
+ * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ *
+ * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
+ * argument goes to the sandbox as an argv array and is never parsed by a shell, so
+ * text typed on behalf of a model or a user cannot run commands.
+ *
+ * Access via `sandbox.desktop`.
+ *
+ * @example
+ * ```ts
+ * const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+ * const { url } = await sandbox.desktop.start()   // open in a browser to watch/drive
+ * await sandbox.desktop.openUrl('https://example.com')
+ * await sandbox.desktop.click(640, 400)
+ * await sandbox.desktop.type('hello')
+ * await sandbox.desktop.press('Return')
+ * const png = await sandbox.desktop.screenshot()
+ * ```
+ */
+declare class Desktop {
+    private readonly sandboxId;
+    private readonly config;
+    private readonly process;
+    constructor(sandboxId: string, config: ConnectionConfig, process: Process);
+    private get client();
+    private get path();
+    /**
+     * Start the desktop, publish its stream and return the URLs. Idempotent: calling
+     * it on a running desktop returns the same URLs (the size of a running desktop is
+     * not changed).
+     */
+    start(opts?: DesktopStartOpts): Promise<DesktopInfo>;
+    /** The desktop's state and URLs, without starting it. */
+    info(): Promise<DesktopInfo>;
+    /** Stop the desktop and unpublish its stream. Its URLs stay the same for the next start. */
+    stop(): Promise<void>;
+    /**
+     * A PNG of the whole screen. The desktop must be running.
+     *
+     * @example
+     * ```ts
+     * import { writeFileSync } from 'node:fs'
+     * writeFileSync('screen.png', await sandbox.desktop.screenshot())
+     * ```
+     */
+    screenshot(): Promise<Uint8Array>;
+    /** Click at (x, y). */
+    click(x: number, y: number, opts?: ClickOpts): Promise<void>;
+    /** Move the pointer to (x, y) without clicking. */
+    moveMouse(x: number, y: number): Promise<void>;
+    /** Press the left button at (fromX, fromY), move to (toX, toY) and release. */
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    /**
+     * Type text into the focused window, as keystrokes. The text is passed as a
+     * single argument after `--`, never through a shell.
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Press a key or a chord, in xdotool keysym syntax: `'Return'`, `'ctrl+l'`,
+     * `'alt+Tab'`. An array presses them one after another.
+     */
+    press(keys: string | string[]): Promise<void>;
+    /** Scroll with the mouse wheel at the pointer's current position. `amount` is wheel clicks. */
+    scroll(direction: ScrollDirection, amount?: number): Promise<void>;
+    /** Where the pointer is now. */
+    cursorPosition(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Open a URL in a new Chromium window on the desktop. Returns once Chromium has
+     * been launched, not when the page has loaded — take a screenshot to see it.
+     */
+    openUrl(url: string): Promise<void>;
+    private run;
+}
+
 interface SandboxInfo {
     sandboxId: string;
     template: string;
@@ -837,6 +959,19 @@ declare class Sandbox extends SandboxClient {
      * ```
      */
     readonly process: Process;
+    /**
+     * Drive the graphical desktop of a `desktop`-template sandbox: stream it to a
+     * browser, take screenshots, click and type.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+     * const { url } = await sandbox.desktop.start() // a credential: anyone with it controls the desktop
+     * await sandbox.desktop.click(100, 200)
+     * const png = await sandbox.desktop.screenshot()
+     * ```
+     */
+    readonly desktop: Desktop;
     protected readonly connectionConfig: ConnectionConfig;
     constructor(opts: {
         sandboxId: string;
@@ -1813,4 +1948,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type ClickOpts, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, Desktop, type DesktopInfo, type DesktopStartOpts, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, type MouseButton, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type ScrollDirection, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.d.ts

@@ -401,6 +401,8 @@ interface ProcessResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /** Set when the platform cut the output off at its per-stream limit (512 KiB). */
+    truncated?: boolean;
 }
 interface ProcessOpts {
     timeoutMs?: number;
@@ -432,7 +434,9 @@ declare class Process {
      * The command runs in a shell inside the Lizard sandbox and returns
      * stdout, stderr, and the exit code when it finishes.
      *
-     * @param cmd Shell command to run inside the sandbox.
+     * @param cmd Shell command to run inside the sandbox, or an argv array that is
+     *   executed directly with no shell — nothing in it is interpreted, so it is the
+     *   safe way to pass untrusted text as an argument.
      * @param opts Optional execution options — environment variables, working
      *   directory, user, and timeout.
      *
@@ -442,6 +446,11 @@ declare class Process {
      * console.log(result.stdout)
      * ```
      *
+     * @example Pass untrusted text as an argument, not through a shell:
+     * ```ts
+     * await sandbox.process.exec(['grep', '-rn', '--', userQuery, '/workspace'])
+     * ```
+     *
      * @example Run with a custom working directory and env vars:
      * ```ts
      * const result = await sandbox.process.exec('npm test', {
@@ -450,7 +459,7 @@ declare class Process {
      * })
      * ```
      */
-    exec(cmd: string, opts?: ProcessOpts): Promise<ProcessResult>;
+    exec(cmd: string | 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
@@ -642,6 +651,119 @@ declare class Watcher {
     close(): Promise<void>;
 }
 
+/**
+ * State of a sandbox's desktop, and the URLs that stream it.
+ *
+ * **Both URLs are credentials.** The port is published on a public hostname, and each
+ * URL carries the stream token and a VNC password. Anyone holding `url` can see and
+ * control the desktop; anyone holding `viewOnlyUrl` can watch it. Do not log them or
+ * put them anywhere you would not put an API key.
+ */
+interface DesktopInfo {
+    running: boolean;
+    /** Screen width in pixels, or `null` when the desktop has never been started. */
+    width: number | null;
+    height: number | null;
+    /** noVNC page with full control (mouse and keyboard). Treat like a credential. */
+    url: string;
+    /** noVNC page that can only watch; enforced by the VNC server, not the page. */
+    viewOnlyUrl: string;
+}
+interface DesktopStartOpts {
+    /** Screen width, 640–3840. Pass together with `height`; default 1280x800. */
+    width?: number;
+    /** Screen height, 480–2160. */
+    height?: number;
+}
+type MouseButton = 'left' | 'right' | 'middle';
+type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+interface ClickOpts {
+    /** Default `'left'`. */
+    button?: MouseButton;
+    /** Double-click instead of a single click. */
+    double?: boolean;
+}
+/**
+ * A graphical desktop in the sandbox, for computer-use agents and for people to watch.
+ *
+ * Only the `desktop` template has one (Xvfb + XFCE + Chromium on `DISPLAY=:1`); on
+ * any other template the calls fail with `code === 'DESKTOP_NOT_SUPPORTED'`.
+ *
+ * Input and screenshots run inside the sandbox with `xdotool` and `scrot`. Every
+ * argument goes to the sandbox as an argv array and is never parsed by a shell, so
+ * text typed on behalf of a model or a user cannot run commands.
+ *
+ * Access via `sandbox.desktop`.
+ *
+ * @example
+ * ```ts
+ * const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+ * const { url } = await sandbox.desktop.start()   // open in a browser to watch/drive
+ * await sandbox.desktop.openUrl('https://example.com')
+ * await sandbox.desktop.click(640, 400)
+ * await sandbox.desktop.type('hello')
+ * await sandbox.desktop.press('Return')
+ * const png = await sandbox.desktop.screenshot()
+ * ```
+ */
+declare class Desktop {
+    private readonly sandboxId;
+    private readonly config;
+    private readonly process;
+    constructor(sandboxId: string, config: ConnectionConfig, process: Process);
+    private get client();
+    private get path();
+    /**
+     * Start the desktop, publish its stream and return the URLs. Idempotent: calling
+     * it on a running desktop returns the same URLs (the size of a running desktop is
+     * not changed).
+     */
+    start(opts?: DesktopStartOpts): Promise<DesktopInfo>;
+    /** The desktop's state and URLs, without starting it. */
+    info(): Promise<DesktopInfo>;
+    /** Stop the desktop and unpublish its stream. Its URLs stay the same for the next start. */
+    stop(): Promise<void>;
+    /**
+     * A PNG of the whole screen. The desktop must be running.
+     *
+     * @example
+     * ```ts
+     * import { writeFileSync } from 'node:fs'
+     * writeFileSync('screen.png', await sandbox.desktop.screenshot())
+     * ```
+     */
+    screenshot(): Promise<Uint8Array>;
+    /** Click at (x, y). */
+    click(x: number, y: number, opts?: ClickOpts): Promise<void>;
+    /** Move the pointer to (x, y) without clicking. */
+    moveMouse(x: number, y: number): Promise<void>;
+    /** Press the left button at (fromX, fromY), move to (toX, toY) and release. */
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    /**
+     * Type text into the focused window, as keystrokes. The text is passed as a
+     * single argument after `--`, never through a shell.
+     */
+    type(text: string): Promise<void>;
+    /**
+     * Press a key or a chord, in xdotool keysym syntax: `'Return'`, `'ctrl+l'`,
+     * `'alt+Tab'`. An array presses them one after another.
+     */
+    press(keys: string | string[]): Promise<void>;
+    /** Scroll with the mouse wheel at the pointer's current position. `amount` is wheel clicks. */
+    scroll(direction: ScrollDirection, amount?: number): Promise<void>;
+    /** Where the pointer is now. */
+    cursorPosition(): Promise<{
+        x: number;
+        y: number;
+    }>;
+    /**
+     * Open a URL in a new Chromium window on the desktop. Returns once Chromium has
+     * been launched, not when the page has loaded — take a screenshot to see it.
+     */
+    openUrl(url: string): Promise<void>;
+    private run;
+}
+
 interface SandboxInfo {
     sandboxId: string;
     template: string;
@@ -837,6 +959,19 @@ declare class Sandbox extends SandboxClient {
      * ```
      */
     readonly process: Process;
+    /**
+     * Drive the graphical desktop of a `desktop`-template sandbox: stream it to a
+     * browser, take screenshots, click and type.
+     *
+     * @example
+     * ```ts
+     * const sandbox = await Sandbox.create('desktop', { project: 'my-project' })
+     * const { url } = await sandbox.desktop.start() // a credential: anyone with it controls the desktop
+     * await sandbox.desktop.click(100, 200)
+     * const png = await sandbox.desktop.screenshot()
+     * ```
+     */
+    readonly desktop: Desktop;
     protected readonly connectionConfig: ConnectionConfig;
     constructor(opts: {
         sandboxId: string;
@@ -1813,4 +1948,4 @@ declare class LizardCLI {
     }): Promise<CLIResult>;
 }
 
-export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };
+export { type Account, type Addon, type AddonType, AddonsAPI, type ApiKey, type ApiKeyScope, ApiKeysAPI, AuthenticationError, type Balance, BillingAPI, type CLIOptions, type CLIResult, type ClickOpts, type CodeContext, CodeSandbox, ConfigApplyError, type ConfigResult, ConflictError, type ConnectionOpts, type CostMetrics, type CreateAddonOpts, type CreateApiKeyOpts, type CreateContextOpts, type CreateProjectOpts, type CreateServiceOpts, type CreateVolumeOpts, type CreateWorkspaceOpts, type CreatedApiKey, type DeployEvent, DeployHandle, Desktop, type DesktopInfo, type DesktopStartOpts, type DomainInfo, type DomainStatus, DomainsAPI, Execution, ExecutionError, type FileInfo, type FsOpts, GitHubAPI, type ListTransactionsOpts, Lizard, LizardCLI, LizardError, type LizardOpts, type LogLine, type MetricPoint, type MetricRange, MetricsAPI, type MouseButton, NotFoundError, PlatformClient, type ProcessOpts, type ProcessResult, type Project, type ProjectConfig, type ProjectCost, ProjectsAPI, type RawMetrics, type Region, RegionsAPI, type RunCodeLanguage, type RunCodeOpts, Sandbox, type SandboxInfo, type SandboxOpts, type SandboxSnapshot, type ScaleOpts, type ScrollDirection, type Secret, SecretsAPI, type Service, type ServiceMetrics, type ServiceUpdate, ServicesAPI, type SetSecretOpts, type SnapshotOpts, type SnapshotWaitOpts, StorageAPI, type StreamEvent, TimeoutError, type Transaction, type TransactionPage, Volume, type VolumeInfo, type Workspace, WorkspacesAPI, resolveProjectId };

package/dist/index.js

@@ -28,6 +28,7 @@ __export(index_exports, {
   ConfigApplyError: () => ConfigApplyError,
   ConflictError: () => ConflictError,
   DeployHandle: () => DeployHandle,
+  Desktop: () => Desktop,
   DomainsAPI: () => DomainsAPI,
   GitHubAPI: () => GitHubAPI,
   Lizard: () => Lizard,
@@ -512,7 +513,9 @@ var Process = class {
    * The command runs in a shell inside the Lizard sandbox and returns
    * stdout, stderr, and the exit code when it finishes.
    *
-   * @param cmd Shell command to run inside the sandbox.
+   * @param cmd Shell command to run inside the sandbox, or an argv array that is
+   *   executed directly with no shell — nothing in it is interpreted, so it is the
+   *   safe way to pass untrusted text as an argument.
    * @param opts Optional execution options — environment variables, working
    *   directory, user, and timeout.
    *
@@ -522,6 +525,11 @@ var Process = class {
    * console.log(result.stdout)
    * ```
    *
+   * @example Pass untrusted text as an argument, not through a shell:
+   * ```ts
+   * await sandbox.process.exec(['grep', '-rn', '--', userQuery, '/workspace'])
+   * ```
+   *
    * @example Run with a custom working directory and env vars:
    * ```ts
    * const result = await sandbox.process.exec('npm test', {
@@ -838,6 +846,157 @@ var Watcher = class {
   }
 };
 
+// src/sandbox/desktop.ts
+var BUTTONS = { left: "1", middle: "2", right: "3" };
+var SCROLL_BUTTONS = { up: "4", down: "5", left: "6", right: "7" };
+var TYPE_DELAY_MS = 12;
+var Desktop = class {
+  constructor(sandboxId, config, process2) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+    this.process = process2;
+  }
+  get client() {
+    return new PlatformClient(this.config);
+  }
+  get path() {
+    return `/api/sandboxes/${encodeURIComponent(this.sandboxId)}/desktop`;
+  }
+  /**
+   * Start the desktop, publish its stream and return the URLs. Idempotent: calling
+   * it on a running desktop returns the same URLs (the size of a running desktop is
+   * not changed).
+   */
+  start(opts = {}) {
+    const body = {};
+    if (opts.width !== void 0) body.width = opts.width;
+    if (opts.height !== void 0) body.height = opts.height;
+    return this.client.post(this.path, body);
+  }
+  /** The desktop's state and URLs, without starting it. */
+  info() {
+    return this.client.get(this.path);
+  }
+  /** Stop the desktop and unpublish its stream. Its URLs stay the same for the next start. */
+  async stop() {
+    await this.client.delete(this.path);
+  }
+  /**
+   * A PNG of the whole screen. The desktop must be running.
+   *
+   * @example
+   * ```ts
+   * import { writeFileSync } from 'node:fs'
+   * writeFileSync('screen.png', await sandbox.desktop.screenshot())
+   * ```
+   */
+  async screenshot() {
+    const r = await this.run(["lizard-desktop", "screenshot"]);
+    if (r.truncated) {
+      throw new LizardError("Screenshot is larger than the exec output limit; start the desktop at a smaller size");
+    }
+    return decodeBase64(r.stdout.trim());
+  }
+  /** Click at (x, y). */
+  async click(x, y, opts = {}) {
+    const button = BUTTONS[opts.button ?? "left"];
+    if (!button) throw new LizardError(`Unknown mouse button: ${String(opts.button)}`);
+    const repeat = opts.double ? ["--repeat", "2", "--delay", "100"] : [];
+    await this.run(["xdotool", "mousemove", coord(x), coord(y), "click", ...repeat, button]);
+  }
+  /** Move the pointer to (x, y) without clicking. */
+  async moveMouse(x, y) {
+    await this.run(["xdotool", "mousemove", coord(x), coord(y)]);
+  }
+  /** Press the left button at (fromX, fromY), move to (toX, toY) and release. */
+  async drag(fromX, fromY, toX, toY) {
+    await this.run([
+      "xdotool",
+      "mousemove",
+      coord(fromX),
+      coord(fromY),
+      "mousedown",
+      "1",
+      "sleep",
+      "0.1",
+      "mousemove",
+      coord(toX),
+      coord(toY),
+      "sleep",
+      "0.1",
+      "mouseup",
+      "1"
+    ]);
+  }
+  /**
+   * Type text into the focused window, as keystrokes. The text is passed as a
+   * single argument after `--`, never through a shell.
+   */
+  async type(text) {
+    if (!text) return;
+    const timeoutMs = Math.min(6e5, Math.max(6e4, text.length * TYPE_DELAY_MS * 3));
+    await this.run(["xdotool", "type", "--delay", String(TYPE_DELAY_MS), "--", text], timeoutMs);
+  }
+  /**
+   * Press a key or a chord, in xdotool keysym syntax: `'Return'`, `'ctrl+l'`,
+   * `'alt+Tab'`. An array presses them one after another.
+   */
+  async press(keys) {
+    const list = Array.isArray(keys) ? keys : [keys];
+    if (list.length === 0 || list.some((k) => typeof k !== "string" || !k)) {
+      throw new LizardError("press() needs at least one non-empty key");
+    }
+    await this.run(["xdotool", "key", "--", ...list]);
+  }
+  /** Scroll with the mouse wheel at the pointer's current position. `amount` is wheel clicks. */
+  async scroll(direction, amount = 3) {
+    const button = SCROLL_BUTTONS[direction];
+    if (!button) throw new LizardError(`Unknown scroll direction: ${String(direction)}`);
+    if (!Number.isInteger(amount) || amount < 1) throw new LizardError("scroll amount must be a positive integer");
+    await this.run(["xdotool", "click", "--repeat", String(amount), "--delay", "30", button]);
+  }
+  /** Where the pointer is now. */
+  async cursorPosition() {
+    const r = await this.run(["xdotool", "getmouselocation", "--shell"]);
+    const x = /^X=(\d+)$/m.exec(r.stdout);
+    const y = /^Y=(\d+)$/m.exec(r.stdout);
+    if (!x || !y) throw new LizardError(`Unexpected xdotool output: ${r.stdout.trim()}`);
+    return { x: Number(x[1]), y: Number(y[1]) };
+  }
+  /**
+   * Open a URL in a new Chromium window on the desktop. Returns once Chromium has
+   * been launched, not when the page has loaded — take a screenshot to see it.
+   */
+  async openUrl(url) {
+    await this.run([
+      "sh",
+      "-c",
+      'setsid chromium --new-window "$1" >/dev/null 2>&1 < /dev/null &',
+      "sh",
+      url
+    ]);
+  }
+  async run(argv, timeoutMs) {
+    const r = await this.process.exec(argv, timeoutMs ? { timeoutMs } : void 0);
+    if (r.exitCode !== 0) {
+      const err = new LizardError(`${argv[0]} ${argv[1] ?? ""} failed (exit ${r.exitCode}): ${(r.stderr || r.stdout).trim()}`);
+      if (r.exitCode === 127) err.code = "DESKTOP_NOT_SUPPORTED";
+      throw err;
+    }
+    return r;
+  }
+};
+function coord(n) {
+  if (!Number.isFinite(n) || n < 0) throw new LizardError(`Invalid screen coordinate: ${n}`);
+  return String(Math.round(n));
+}
+function decodeBase64(b64) {
+  if (!b64 || !/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) {
+    throw new LizardError("Screenshot returned no image");
+  }
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
 // src/sandbox/client.ts
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
@@ -939,6 +1098,7 @@ var Sandbox = class extends SandboxClient {
     this.connectionConfig = new ConnectionConfig(opts);
     this.fs = new Fs(this.sandboxId, this.connectionConfig);
     this.process = new Process(this.sandboxId, this.connectionConfig);
+    this.desktop = new Desktop(this.sandboxId, this.connectionConfig, this.process);
   }
   static async create(templateOrOpts, opts) {
     const template = typeof templateOrOpts === "string" ? templateOrOpts : templateOrOpts?.template ?? this.defaultTemplate;
@@ -1988,6 +2148,7 @@ async function* readLines(body) {
   ConfigApplyError,
   ConflictError,
   DeployHandle,
+  Desktop,
   DomainsAPI,
   GitHubAPI,
   Lizard,

package/dist/index.mjs

@@ -461,7 +461,9 @@ var Process = class {
    * The command runs in a shell inside the Lizard sandbox and returns
    * stdout, stderr, and the exit code when it finishes.
    *
-   * @param cmd Shell command to run inside the sandbox.
+   * @param cmd Shell command to run inside the sandbox, or an argv array that is
+   *   executed directly with no shell — nothing in it is interpreted, so it is the
+   *   safe way to pass untrusted text as an argument.
    * @param opts Optional execution options — environment variables, working
    *   directory, user, and timeout.
    *
@@ -471,6 +473,11 @@ var Process = class {
    * console.log(result.stdout)
    * ```
    *
+   * @example Pass untrusted text as an argument, not through a shell:
+   * ```ts
+   * await sandbox.process.exec(['grep', '-rn', '--', userQuery, '/workspace'])
+   * ```
+   *
    * @example Run with a custom working directory and env vars:
    * ```ts
    * const result = await sandbox.process.exec('npm test', {
@@ -787,6 +794,157 @@ var Watcher = class {
   }
 };
 
+// src/sandbox/desktop.ts
+var BUTTONS = { left: "1", middle: "2", right: "3" };
+var SCROLL_BUTTONS = { up: "4", down: "5", left: "6", right: "7" };
+var TYPE_DELAY_MS = 12;
+var Desktop = class {
+  constructor(sandboxId, config, process2) {
+    this.sandboxId = sandboxId;
+    this.config = config;
+    this.process = process2;
+  }
+  get client() {
+    return new PlatformClient(this.config);
+  }
+  get path() {
+    return `/api/sandboxes/${encodeURIComponent(this.sandboxId)}/desktop`;
+  }
+  /**
+   * Start the desktop, publish its stream and return the URLs. Idempotent: calling
+   * it on a running desktop returns the same URLs (the size of a running desktop is
+   * not changed).
+   */
+  start(opts = {}) {
+    const body = {};
+    if (opts.width !== void 0) body.width = opts.width;
+    if (opts.height !== void 0) body.height = opts.height;
+    return this.client.post(this.path, body);
+  }
+  /** The desktop's state and URLs, without starting it. */
+  info() {
+    return this.client.get(this.path);
+  }
+  /** Stop the desktop and unpublish its stream. Its URLs stay the same for the next start. */
+  async stop() {
+    await this.client.delete(this.path);
+  }
+  /**
+   * A PNG of the whole screen. The desktop must be running.
+   *
+   * @example
+   * ```ts
+   * import { writeFileSync } from 'node:fs'
+   * writeFileSync('screen.png', await sandbox.desktop.screenshot())
+   * ```
+   */
+  async screenshot() {
+    const r = await this.run(["lizard-desktop", "screenshot"]);
+    if (r.truncated) {
+      throw new LizardError("Screenshot is larger than the exec output limit; start the desktop at a smaller size");
+    }
+    return decodeBase64(r.stdout.trim());
+  }
+  /** Click at (x, y). */
+  async click(x, y, opts = {}) {
+    const button = BUTTONS[opts.button ?? "left"];
+    if (!button) throw new LizardError(`Unknown mouse button: ${String(opts.button)}`);
+    const repeat = opts.double ? ["--repeat", "2", "--delay", "100"] : [];
+    await this.run(["xdotool", "mousemove", coord(x), coord(y), "click", ...repeat, button]);
+  }
+  /** Move the pointer to (x, y) without clicking. */
+  async moveMouse(x, y) {
+    await this.run(["xdotool", "mousemove", coord(x), coord(y)]);
+  }
+  /** Press the left button at (fromX, fromY), move to (toX, toY) and release. */
+  async drag(fromX, fromY, toX, toY) {
+    await this.run([
+      "xdotool",
+      "mousemove",
+      coord(fromX),
+      coord(fromY),
+      "mousedown",
+      "1",
+      "sleep",
+      "0.1",
+      "mousemove",
+      coord(toX),
+      coord(toY),
+      "sleep",
+      "0.1",
+      "mouseup",
+      "1"
+    ]);
+  }
+  /**
+   * Type text into the focused window, as keystrokes. The text is passed as a
+   * single argument after `--`, never through a shell.
+   */
+  async type(text) {
+    if (!text) return;
+    const timeoutMs = Math.min(6e5, Math.max(6e4, text.length * TYPE_DELAY_MS * 3));
+    await this.run(["xdotool", "type", "--delay", String(TYPE_DELAY_MS), "--", text], timeoutMs);
+  }
+  /**
+   * Press a key or a chord, in xdotool keysym syntax: `'Return'`, `'ctrl+l'`,
+   * `'alt+Tab'`. An array presses them one after another.
+   */
+  async press(keys) {
+    const list = Array.isArray(keys) ? keys : [keys];
+    if (list.length === 0 || list.some((k) => typeof k !== "string" || !k)) {
+      throw new LizardError("press() needs at least one non-empty key");
+    }
+    await this.run(["xdotool", "key", "--", ...list]);
+  }
+  /** Scroll with the mouse wheel at the pointer's current position. `amount` is wheel clicks. */
+  async scroll(direction, amount = 3) {
+    const button = SCROLL_BUTTONS[direction];
+    if (!button) throw new LizardError(`Unknown scroll direction: ${String(direction)}`);
+    if (!Number.isInteger(amount) || amount < 1) throw new LizardError("scroll amount must be a positive integer");
+    await this.run(["xdotool", "click", "--repeat", String(amount), "--delay", "30", button]);
+  }
+  /** Where the pointer is now. */
+  async cursorPosition() {
+    const r = await this.run(["xdotool", "getmouselocation", "--shell"]);
+    const x = /^X=(\d+)$/m.exec(r.stdout);
+    const y = /^Y=(\d+)$/m.exec(r.stdout);
+    if (!x || !y) throw new LizardError(`Unexpected xdotool output: ${r.stdout.trim()}`);
+    return { x: Number(x[1]), y: Number(y[1]) };
+  }
+  /**
+   * Open a URL in a new Chromium window on the desktop. Returns once Chromium has
+   * been launched, not when the page has loaded — take a screenshot to see it.
+   */
+  async openUrl(url) {
+    await this.run([
+      "sh",
+      "-c",
+      'setsid chromium --new-window "$1" >/dev/null 2>&1 < /dev/null &',
+      "sh",
+      url
+    ]);
+  }
+  async run(argv, timeoutMs) {
+    const r = await this.process.exec(argv, timeoutMs ? { timeoutMs } : void 0);
+    if (r.exitCode !== 0) {
+      const err = new LizardError(`${argv[0]} ${argv[1] ?? ""} failed (exit ${r.exitCode}): ${(r.stderr || r.stdout).trim()}`);
+      if (r.exitCode === 127) err.code = "DESKTOP_NOT_SUPPORTED";
+      throw err;
+    }
+    return r;
+  }
+};
+function coord(n) {
+  if (!Number.isFinite(n) || n < 0) throw new LizardError(`Invalid screen coordinate: ${n}`);
+  return String(Math.round(n));
+}
+function decodeBase64(b64) {
+  if (!b64 || !/^[A-Za-z0-9+/]+={0,2}$/.test(b64)) {
+    throw new LizardError("Screenshot returned no image");
+  }
+  return new Uint8Array(Buffer.from(b64, "base64"));
+}
+
 // src/sandbox/client.ts
 var SandboxClient = class {
   static async createSandbox(template, timeoutMs, opts) {
@@ -888,6 +1046,7 @@ var Sandbox = class extends SandboxClient {
     this.connectionConfig = new ConnectionConfig(opts);
     this.fs = new Fs(this.sandboxId, this.connectionConfig);
     this.process = new Process(this.sandboxId, this.connectionConfig);
+    this.desktop = new Desktop(this.sandboxId, this.connectionConfig, this.process);
   }
   static async create(templateOrOpts, opts) {
     const template = typeof templateOrOpts === "string" ? templateOrOpts : templateOrOpts?.template ?? this.defaultTemplate;
@@ -1936,6 +2095,7 @@ export {
   ConfigApplyError,
   ConflictError,
   DeployHandle,
+  Desktop,
   DomainsAPI,
   GitHubAPI,
   Lizard,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "TypeScript SDK for Lizard: Kubernetes sandboxes, code execution and cloud apps.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",