@zocomputer/agent-sdk 0.5.0

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@zocomputer/agent-sdk",
+  "version": "0.5.0",
+  "description": "A standard library for eve agents: workspace file tools (read/edit/write/glob/grep), a backgroundable bash with bounded output, async task orchestration, and rich-filetype reads (PDF, DOCX, spreadsheets) — one createStdlib call.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zocomputer/agent-sdk.git"
+  },
+  "homepage": "https://github.com/zocomputer/agent-sdk#readme",
+  "type": "module",
+  "keywords": [
+    "eve",
+    "agent",
+    "ai",
+    "tools",
+    "llm"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./attachments": {
+      "types": "./src/attachments.ts",
+      "import": "./dist/attachments.js"
+    },
+    "./gateway-fetch": {
+      "types": "./src/gateway-fetch.ts",
+      "import": "./dist/gateway-fetch.js"
+    },
+    "./initiator-auth": {
+      "types": "./src/initiator-auth.ts",
+      "import": "./dist/initiator-auth.js"
+    },
+    "./state": {
+      "types": "./src/state.ts",
+      "import": "./dist/state.js"
+    },
+    "./state-files": {
+      "types": "./src/state-files.ts",
+      "import": "./dist/state-files.js"
+    },
+    "./state-sandbox": {
+      "types": "./src/state-sandbox.ts",
+      "import": "./dist/state-sandbox.js"
+    },
+    "./steer": {
+      "types": "./src/steer.ts",
+      "import": "./dist/steer.js"
+    },
+    "./steer-inbox": {
+      "types": "./src/steer-inbox.ts",
+      "import": "./dist/steer-inbox.js"
+    },
+    "./runtime-auth": {
+      "types": "./platform/runtime-auth/index.ts",
+      "import": "./dist/platform/runtime-auth/index.js"
+    },
+    "./sandbox": {
+      "types": "./platform/agent-sandbox/index.ts",
+      "import": "./dist/platform/agent-sandbox/index.js"
+    },
+    "./ai": {
+      "types": "./platform/runtime-ai/index.ts",
+      "import": "./dist/platform/runtime-ai/index.js"
+    },
+    "./ai/gateway": {
+      "types": "./platform/runtime-ai/gateway.ts",
+      "import": "./dist/platform/runtime-ai/gateway.js"
+    },
+    "./ai/register": {
+      "types": "./platform/runtime-ai/register.ts",
+      "import": "./dist/platform/runtime-ai/register.js"
+    },
+    "./ai/session-fetch": {
+      "types": "./platform/runtime-ai/session-fetch.ts",
+      "import": "./dist/platform/runtime-ai/session-fetch.js"
+    },
+    "./cloud-tools": {
+      "types": "./platform/cloud-tools/index.ts",
+      "import": "./dist/platform/cloud-tools/index.js"
+    },
+    "./cloud-tools/image": {
+      "types": "./platform/cloud-tools/image.ts",
+      "import": "./dist/platform/cloud-tools/image.js"
+    },
+    "./cloud-tools/web-search": {
+      "types": "./platform/cloud-tools/web-search.ts",
+      "import": "./dist/platform/cloud-tools/web-search.js"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-helpers.ts",
+    "!src/extract/fixtures",
+    "!src/**/AGENTS.md",
+    "!src/**/CLAUDE.md",
+    "platform",
+    "!platform/**/*.test.ts",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/provider-utils": "5.0.1",
+    "clawpdf": "0.3.0",
+    "defuddle": "^0.19.1",
+    "htmlparser2": "^12.0.0",
+    "ignore": "^7.0.5",
+    "image-size": "2.0.2",
+    "jose": "^6.2.3",
+    "linkedom": "^0.18.12",
+    "mammoth": "1.12.0",
+    "ssh2": "^1.17.0",
+    "turndown": "^7.2.4",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.2",
+    "eve": "^0.16.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@ai-sdk/provider": "^4.0.1",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^20",
+    "@types/ssh2": "^1.15.5",
+    "@types/turndown": "^5.0.6",
+    "ai": "^7.0.2",
+    "eslint": "^9",
+    "eve": "^0.16.0",
+    "fast-check": "^4.8.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  }
+}

package/platform/agent-sandbox/api-client.ts

@@ -0,0 +1,196 @@
+import {
+  AGENT_TOKEN_ENV,
+  AGENT_TOKEN_HEADER,
+  EVE_SESSION_HEADER,
+} from "../runtime-auth/index.ts";
+import type { SshSandboxAccess } from "./ssh-session";
+
+// The runtime's thin HTTP client to the control plane (apps/api) STATE BROKER.
+// The runtime has no Daytona key; it asks the broker to resolve its session's
+// `scratch` sandbox state (POST /state/handles) and hand back scoped SSH access,
+// then connects over SSH. The org-wide Daytona key lives only in apps/api.
+//
+// This is design-doc D10: the default per-session runtime sandbox is now the
+// `scratch` external-state declaration, resolved through the SAME broker every
+// other state uses — there is no bespoke POST /sandbox/session route anymore.
+// The broker zero-configs an unbound `scratch` declaration onto the sandbox
+// engine, so we send `suggestedDefaults.engine = "sandbox-daytona"` to keep it
+// off the broker's R2 default; a user rebinding `scratch` (e.g. to a durable
+// `user` partition) takes precedence over these hints. See
+// plans/dcosson/external-state-sandbox.md.
+//
+// Auth: the runtime carries its **agent token** — a short-lived, apps/api-minted
+// JWT identifying the actor, injected into the runtime env (`ZO_AGENT_TOKEN`) the
+// same way the AI gateway key is. It rides a dedicated header (off `Authorization`,
+// so it never shadows a WorkOS session), and the eve session rides its own header
+// so apps/api carries it onto the resolved auth context. The header names + env
+// var come from `@zocomputer/runtime-auth` (the one source of truth). apps/api is
+// the sole verifier. POST /state/handles is AGENT-TOKEN-ONLY: it rejects a human
+// session with 403 `unsupported_actor`, so every caller must present an agent token.
+// See plans/rc2/runtime-auth-context.md and plans/dcosson/external-state-sandbox.md.
+
+// Re-export the contract constants this client uses, so a consumer importing the
+// client surface gets them without reaching into @zocomputer/runtime-auth directly.
+export { AGENT_TOKEN_ENV, AGENT_TOKEN_HEADER, EVE_SESSION_HEADER };
+
+/** The seed `scratch` declaration the default runtime sandbox resolves through. */
+export const SCRATCH_DECLARATION = "scratch";
+
+/** The broker path the runtime resolves its sandbox state handle through. */
+const STATE_HANDLE_PATH = "/state/handles";
+
+/** The slice of `fetch` we use — narrower than `typeof fetch` so a test can stub it. */
+export type FetchLike = (
+  input: string,
+  init?: RequestInit,
+) => Promise<Response>;
+
+/** The scoped SSH access the broker's sandbox state handle carries — host/user + expiry. */
+export type SandboxSessionResponse = SshSandboxAccess;
+
+/**
+ * A typed broker failure. `code` is the broker's error-taxonomy string (e.g.
+ * `unsupported_actor`, `eve_session_required`, `provisioning_failed`); `status`
+ * the HTTP status. Callers can branch on `code` rather than parse the message.
+ */
+export class SandboxBrokerError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+
+  constructor(message: string, options: { status: number; code?: string | null }) {
+    super(message);
+    this.name = "SandboxBrokerError";
+    this.status = options.status;
+    this.code = options.code ?? null;
+  }
+}
+
+/**
+ * Parse-then-narrow the scoped SSH access, rather than asserting it inward: the
+ * parsed value is fed straight into the SSH connect path (host/user), so a
+ * shape-divergent value (a renamed field, a null) must fail here at the boundary,
+ * not flow in as a bad host/username. Returns `null` on mismatch.
+ */
+export function parseSandboxAccess(value: unknown): SshSandboxAccess | null {
+  if (typeof value !== "object" || value === null) return null;
+  const v = value as Record<string, unknown>;
+  const { sandboxId, sshHost, sshUser, expiresAt } = v;
+  if (
+    typeof sandboxId === "string" &&
+    typeof sshHost === "string" &&
+    typeof sshUser === "string" &&
+    typeof expiresAt === "string"
+  ) {
+    return { sandboxId, sshHost, sshUser, expiresAt };
+  }
+  return null;
+}
+
+/**
+ * Extract scoped SSH access from a broker state-handle response. The sandbox
+ * engine's handle nests access under `sandbox`; a non-sandbox handle (e.g. an
+ * R2 `files` handle, which the broker returns if `scratch` ever resolved onto
+ * the R2 default engine) has no sandbox access and fails here at the boundary,
+ * rather than flowing in as a missing host. Returns `null` on mismatch.
+ */
+export function parseSandboxHandleAccess(value: unknown): SshSandboxAccess | null {
+  if (typeof value !== "object" || value === null) return null;
+  const v = value as Record<string, unknown>;
+  if (v.engine !== "sandbox-daytona") return null;
+  return parseSandboxAccess(v.sandbox);
+}
+
+export interface RequestSandboxInput {
+  /** Base URL of the control-plane API (e.g. http://api.zo.localhost:4000). */
+  readonly apiBaseUrl: string;
+  /**
+   * Stable per-eve-session key. Sent as the `x-zo-eve-session` header; the broker
+   * keys the session-partitioned `scratch` instance off it (+ the caller's org),
+   * so a reply reattaches the same sandbox.
+   */
+  readonly eveSessionKey: string;
+  /**
+   * The agent token to authenticate with. Injectable for tests; defaults to
+   * `process.env[AGENT_TOKEN_ENV]`. When absent the call is sent without the
+   * header, and the broker rejects it with 403 `unsupported_actor` (the route is
+   * agent-token-only) — a clear failure rather than a silent fallthrough.
+   */
+  readonly agentToken?: string;
+  /** Injectable for tests; defaults to global fetch. */
+  readonly fetch?: FetchLike;
+}
+
+/**
+ * Resolve this session's `scratch` sandbox through the state broker and return
+ * scoped SSH access. The broker recovers the subject from the agent token +
+ * eve-session header, resolves (or zero-configs) the `scratch` binding onto the
+ * sandbox engine, and mints a short-lived SSH token for the session's sandbox —
+ * creating it, reattaching a live one, or reviving a stopped one as needed.
+ *
+ * Throws `SandboxBrokerError` on any non-2xx, carrying the broker's error code
+ * (`unsupported_actor`, `eve_session_required`, `provisioning_failed`, …) and
+ * HTTP status.
+ */
+export async function requestScratchSandboxAccess(
+  input: RequestSandboxInput,
+): Promise<SshSandboxAccess> {
+  const doFetch = input.fetch ?? fetch;
+  // Treat a blank/whitespace token as absent (don't send the header) — apps/api
+  // trims and ignores a blank agent-token header. Send the trimmed token, matching
+  // the exact bytes apps/api verifies.
+  const agentToken = (input.agentToken ?? process.env[AGENT_TOKEN_ENV])?.trim() || undefined;
+  const eveSessionKey = input.eveSessionKey.trim() || undefined;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (agentToken) headers[AGENT_TOKEN_HEADER] = agentToken;
+  if (eveSessionKey) headers[EVE_SESSION_HEADER] = eveSessionKey;
+  // Header-only eve session — no body `eveSessionKey`, so we never trip the
+  // route's header/body mismatch guard (the header IS the trusted session key).
+  const res = await doFetch(`${input.apiBaseUrl}${STATE_HANDLE_PATH}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      declarationName: SCRATCH_DECLARATION,
+      interface: "exec",
+      access: "rw",
+      suggestedDefaults: { engine: "sandbox-daytona", partition: "session" },
+    }),
+  });
+  const json: unknown = await res.json().catch(() => null);
+  if (!res.ok) {
+    const { code, message } = parseBrokerError(json);
+    throw new SandboxBrokerError(describeBrokerError(res.status, code, message), {
+      status: res.status,
+      code,
+    });
+  }
+  const access = parseSandboxHandleAccess(json);
+  if (access === null) {
+    throw new SandboxBrokerError(
+      "sandbox broker returned a non-sandbox or malformed state handle",
+      { status: res.status, code: "malformed_handle" },
+    );
+  }
+  return access;
+}
+
+/** Read the broker's `{ error, message }` failure envelope; both may be absent. */
+function parseBrokerError(value: unknown): { code: string | null; message: string | null } {
+  if (typeof value !== "object" || value === null) return { code: null, message: null };
+  const v = value as Record<string, unknown>;
+  return {
+    code: typeof v.error === "string" ? v.error : null,
+    message: typeof v.message === "string" ? v.message : null,
+  };
+}
+
+/** Map the broker's error taxonomy to an actionable message for the two flip-novel codes. */
+function describeBrokerError(status: number, code: string | null, message: string | null): string {
+  if (code === "unsupported_actor") {
+    return "sandbox broker rejected the caller: POST /state/handles requires an agent token, not a human session (unsupported_actor). Ensure ZO_AGENT_TOKEN is set.";
+  }
+  if (code === "eve_session_required") {
+    return "sandbox broker requires an eve session: send the x-zo-eve-session header (eve_session_required).";
+  }
+  const detail = [code, message].filter((s): s is string => s !== null && s.length > 0).join(" — ");
+  return `sandbox provisioning failed: ${status}${detail ? ` ${detail}` : ""}`.trim();
+}

package/platform/agent-sandbox/index.ts

@@ -0,0 +1,27 @@
+// @zocomputer/agent-sandbox — the Zo built-in sandbox for eve agents.
+//
+// Agents author against `zoSandbox()` and never name the provider; the runtime
+// never holds the Daytona key — it asks the Zo control plane (apps/api) to
+// provision its sandbox and connects over SSH with a scoped token. `zoBackend()`
+// is exported for callers that want the raw eve `SandboxBackend` directly.
+
+export { zoSandbox, type ZoSandboxOptions } from "./zo-sandbox";
+export { zoBackend, type ZoBackendOptions } from "./zo-backend";
+
+// The connect-a-sandbox-by-eve-session-key primitives `zoBackend` composes
+// internally, exported for a caller that needs a standalone `SandboxSession`
+// OUTSIDE eve's own ALS-scoped tool/hook context — e.g. an eve channel HTTP
+// route, which gets no `ctx.getSandbox()` (see the Builder's `agent/channels/
+// flush.ts`, plans/sachin/code-storage-phase3-implementation.md).
+export {
+  requestScratchSandboxAccess,
+  SandboxBrokerError,
+  type FetchLike,
+  type RequestSandboxInput,
+  type SandboxSessionResponse,
+} from "./api-client";
+export {
+  sshSandboxSession,
+  type SshSandboxAccess,
+  type SshSession,
+} from "./ssh-session";

package/platform/agent-sandbox/pure.ts

@@ -0,0 +1,83 @@
+import { Buffer } from "node:buffer";
+import path from "node:path";
+
+// Pure, dependency-free helpers shared by the backend and session layers.
+// Kept here (no SSH/eve runtime objects) so they're unit-testable in isolation —
+// see `pure.test.ts`.
+
+/**
+ * Anchor a sandbox path to the work dir: relative paths resolve under
+ * `workDir`, absolute paths pass through unchanged.
+ *
+ * A relative path that escapes `workDir` via `..` (e.g. `../../etc/passwd`) is
+ * rejected — `path.posix.join` would otherwise normalize it to a location
+ * outside the workspace, which the file methods would then read/write.
+ */
+export function resolveSandboxPath(workDir: string, p: string): string {
+  if (path.posix.isAbsolute(p)) return p;
+  const resolved = path.posix.join(workDir, p);
+  // Stay within workDir: either the dir itself or a path beneath it.
+  const prefix = workDir.endsWith("/") ? workDir : `${workDir}/`;
+  if (resolved !== workDir && !resolved.startsWith(prefix)) {
+    throw new Error(`sandbox path escapes the work dir: ${p}`);
+  }
+  return resolved;
+}
+
+/**
+ * POSIX single-quote a string for safe interpolation into a shell command —
+ * wraps in `'…'` and escapes embedded single quotes as `'\''`. Used to quote a
+ * path (e.g. a `cd` target) so shell metacharacters in it are treated literally,
+ * not interpreted. (The model-supplied command itself is intentionally shell.)
+ */
+export function shellSingleQuote(s: string): string {
+  return `'${s.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * The reconnect metadata we persist on the eve session. `daytonaSandboxId` is
+ * the provider sandbox id; eve hands it back as `existingMetadata` on a reply so
+ * the control plane reattaches the same sandbox.
+ */
+export interface DaytonaSessionMetadata {
+  readonly daytonaSandboxId: string;
+}
+
+/** Narrow persisted metadata to a non-empty `daytonaSandboxId`, else `null`. */
+export function readSandboxId(
+  metadata: Record<string, unknown> | undefined,
+): string | null {
+  const id = metadata?.daytonaSandboxId;
+  return typeof id === "string" && id !== "" ? id : null;
+}
+
+/**
+ * Resolve a caller-supplied encoding to a Node `BufferEncoding`, or throw a
+ * clear error. `undefined`/`utf-8`/`utf8` → `"utf8"` (eve's default); anything
+ * else is validated with `Buffer.isEncoding` (a type guard, so no cast) and
+ * rejected if unknown — rather than letting an arbitrary string reach
+ * `Buffer.from(…, badEncoding)` as an unchecked cast / opaque TypeError.
+ */
+export function resolveEncoding(encoding?: string): BufferEncoding {
+  if (encoding === undefined || /^utf-?8$/i.test(encoding)) return "utf8";
+  if (Buffer.isEncoding(encoding)) return encoding;
+  throw new Error(`zo sandbox: unsupported text encoding ${JSON.stringify(encoding)}`);
+}
+
+/** Decode bytes as text. utf-8 uses fatal mode (invalid bytes throw, not replace). */
+export function decodeText(bytes: Uint8Array, encoding?: string): string {
+  const enc = resolveEncoding(encoding);
+  if (enc === "utf8") return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  return Buffer.from(bytes).toString(enc);
+}
+
+/** Encode text to bytes for the given encoding (utf-8 default). */
+export function encodeText(text: string, encoding?: string): Uint8Array {
+  const enc = resolveEncoding(encoding);
+  if (enc === "utf8") return new TextEncoder().encode(text);
+  return new Uint8Array(Buffer.from(text, enc));
+}
+
+// Line-range slicing is NOT implemented here — readTextFile uses the AI-SDK's
+// extractLines (the exact impl eve uses), so we don't own that edge-case-laden
+// logic. See ssh-session.ts.

package/platform/agent-sandbox/sftp.ts

@@ -0,0 +1,141 @@
+import path from "node:path";
+import type { Client, SFTPWrapper } from "ssh2";
+import { shellSingleQuote } from "./pure";
+import { awaitCommand } from "./ssh-exec";
+
+// File/process operations over an established ssh2 `Client`, backing the eve
+// `SandboxSession` file methods + `spawn`. Byte transfer rides SFTP (binary-safe,
+// no shell-escaping of content); directory creation and removal ride `exec`
+// (SFTP has no recursive mkdir/rm). The session wraps these with the AI-SDK
+// text/stream/encoding contract; this module stays bytes-and-paths.
+
+/** SFTP status code for "no such file" (per the SFTP protocol). */
+const SFTP_NO_SUCH_FILE = 2;
+
+/**
+ * Did an ssh2 SFTP error mean "the file doesn't exist"? (→ read methods return
+ * null). ssh2 reliably sets `err.code` to the SFTP status code on the error, so
+ * we match the code exactly rather than sniffing the message — a message-regex
+ * would risk treating an unrelated failure as "absent".
+ */
+function isNoSuchFile(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { code?: unknown }).code === SFTP_NO_SUCH_FILE
+  );
+}
+
+// One SFTP channel per connection, opened lazily and reused across operations —
+// opening a fresh channel per read/write (and never closing it) leaks channels
+// until the connection hits sshd's MaxSessions. Keyed by Client so it's scoped
+// to the connection's life and GC'd with it; evicted on close/error so the next
+// op reopens (e.g. after the connection manager reconnects with a new Client).
+const sftpByClient = new WeakMap<Client, Promise<SFTPWrapper>>();
+
+function getSftp(client: Client): Promise<SFTPWrapper> {
+  const existing = sftpByClient.get(client);
+  if (existing !== undefined) return existing;
+  const opening = new Promise<SFTPWrapper>((resolve, reject) => {
+    client.sftp((err, sftp) => {
+      if (err) { reject(err); return; }
+      // Drop the cache entry if this channel dies, so we reopen next time.
+      const evict = (): void => {
+        if (sftpByClient.get(client) === opening) sftpByClient.delete(client);
+      };
+      sftp.on("close", evict).on("error", evict);
+      resolve(sftp);
+    });
+  });
+  // Don't cache a failed open.
+  opening.catch(() => {
+    if (sftpByClient.get(client) === opening) sftpByClient.delete(client);
+  });
+  sftpByClient.set(client, opening);
+  return opening;
+}
+
+/**
+ * Run a command to completion over exec, returning its exit code + stderr. Exit
+ * reconciliation (signal→nonzero, so a killed mkdir/rm isn't a false 0, and
+ * channel-error→reject so we never hang) is shared via awaitCommand.
+ */
+function exec(
+  client: Client,
+  command: string,
+): Promise<{ exitCode: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    client.exec(command, (err, stream) => {
+      if (err) { reject(err); return; }
+      let stderr = "";
+      stream.on("data", () => {}).stderr.on("data", (d: Buffer) => (stderr += d.toString()));
+      awaitCommand(stream).then(
+        ({ exitCode }) => resolve({ exitCode, stderr }),
+        reject,
+      );
+    });
+  });
+}
+
+/** Ensure a file's parent directory exists (SFTP can't mkdir -p). */
+async function ensureParentDir(client: Client, filePath: string): Promise<void> {
+  const dir = path.posix.dirname(filePath);
+  if (dir === "" || dir === "." || dir === "/") return;
+  const r = await exec(client, `mkdir -p ${shellSingleQuote(dir)}`);
+  if (r.exitCode !== 0) {
+    throw new Error(`sandbox: mkdir -p ${dir} failed (exit ${r.exitCode}): ${r.stderr.trim()}`);
+  }
+}
+
+/** Read a file's bytes, or `null` if it doesn't exist. */
+export async function sftpReadBytes(
+  client: Client,
+  remotePath: string,
+): Promise<Uint8Array | null> {
+  const sftp = await getSftp(client);
+  return await new Promise<Uint8Array | null>((resolve, reject) => {
+    sftp.readFile(remotePath, (err, buf) => {
+      if (err) {
+        if (isNoSuchFile(err)) resolve(null);
+        else reject(err);
+        return;
+      }
+      resolve(new Uint8Array(buf));
+    });
+  });
+}
+
+/** Write bytes to a file, creating parent dirs and overwriting any existing file. */
+export async function sftpWriteBytes(
+  client: Client,
+  remotePath: string,
+  bytes: Uint8Array,
+): Promise<void> {
+  await ensureParentDir(client, remotePath);
+  const sftp = await getSftp(client);
+  await new Promise<void>((resolve, reject) => {
+    sftp.writeFile(remotePath, Buffer.from(bytes), (err) =>
+      err ? reject(err) : resolve(),
+    );
+  });
+}
+
+/**
+ * Remove a path. `recursive` allows non-empty dirs; `force` (→ `rm -f`) makes a
+ * MISSING path a success. A non-zero exit is always an error: with `-f`, `rm`
+ * itself already exits 0 for a missing path, so a remaining non-zero means a
+ * real failure (permission denied, non-empty dir without `recursive`, …) we must
+ * surface rather than swallow.
+ */
+export async function removePath(
+  client: Client,
+  remotePath: string,
+  opts: { recursive?: boolean | undefined; force?: boolean | undefined } = {},
+): Promise<void> {
+  const flags = `${opts.recursive ? "r" : ""}${opts.force ? "f" : ""}`;
+  const rm = flags === "" ? "rm" : `rm -${flags}`;
+  const r = await exec(client, `${rm} ${shellSingleQuote(remotePath)}`);
+  if (r.exitCode !== 0) {
+    throw new Error(`sandbox: ${rm} ${remotePath} failed (exit ${r.exitCode}): ${r.stderr.trim()}`);
+  }
+}