pi-microsandbox 0.1.0

package/extensions/pi-msb/operations.ts

@@ -0,0 +1,321 @@
+import type {
+  EditOperations,
+  LsOperations,
+  ReadOperations,
+  WriteOperations,
+} from "@earendil-works/pi-coding-agent";
+import type { SandboxTransport } from "./types.ts";
+
+export interface FileOpsOptions {
+  /** The absolute project root mounted in the sandbox. */
+  projectRoot: string;
+}
+
+const SUPPORTED_IMAGE_MIME_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/bmp",
+  // `file` uses this spelling on some distributions for BMP files.
+  "image/x-ms-bmp",
+]);
+
+interface CodedError extends Error {
+  code?: string | number;
+}
+
+function errorCode(error: unknown): string | number | undefined {
+  if (typeof error !== "object" || error === null) return undefined;
+  const value = (error as { code?: unknown }).code;
+  return typeof value === "string" || typeof value === "number" ? value : undefined;
+}
+
+function isNotFound(error: unknown): boolean {
+  const code = errorCode(error);
+  return code === "NOT_FOUND" || code === "ENOENT";
+}
+
+function isOutsideProjectRoot(filePath: string, projectRoot: string): boolean {
+  // Do not use this to rewrite paths. It is only an error-classification check.
+  const root = resolveLexically(projectRoot);
+  const candidate = resolveLexically(filePath);
+  if (root === "/" || candidate === root) return false;
+  return !candidate.startsWith(`${root}/`);
+}
+
+function resolveLexically(filePath: string): string {
+  if (filePath === "/") return "/";
+  const normalized = filePath.replace(/\\/g, "/").replace(/\/+/g, "/");
+  const absolute = normalized.startsWith("/") ? normalized : `/${normalized}`;
+  const parts: string[] = [];
+  for (const part of absolute.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return `/${parts.join("/")}` || "/";
+}
+
+function sandboxPathError(filePath: string, projectRoot: string): Error {
+  return new Error(
+    `Path is not available in the sandbox: ${filePath}. ` +
+      `The sandbox project root is ${projectRoot}; use a path mounted inside it.`,
+  );
+}
+
+function withPathError<T>(
+  filePath: string,
+  options: FileOpsOptions,
+  operation: () => Promise<T>,
+): Promise<T> {
+  return operation().catch((error: unknown) => {
+    if (
+      isNotFound(error) &&
+      isOutsideProjectRoot(filePath, options.projectRoot)
+    ) {
+      throw sandboxPathError(filePath, options.projectRoot);
+    }
+    throw error;
+  });
+}
+
+function commandError(
+  command: string,
+  args: readonly string[],
+  exitCode: number,
+  stderr: Buffer,
+): CodedError {
+  const detail = stderr.toString("utf8").trim();
+  const error = new Error(
+    detail || `${command} exited with code ${exitCode}`,
+  ) as CodedError;
+  // 127 means the executable/shell command is missing, not that the path was
+  // absent. Keep that distinct so outside-root classification cannot rewrite it.
+  error.code = exitCode === 127 ? "COMMAND_NOT_FOUND" : "EIO";
+  // Keep the command in the fallback message useful without joining user input
+  // into a shell command. Paths are deliberately not interpreted or executed.
+  if (!detail && args.length === 0) error.message = `${command}: ${error.message}`;
+  return error;
+}
+
+async function execChecked(
+  transport: SandboxTransport,
+  command: string,
+  args: string[],
+): Promise<void> {
+  const result = await transport.exec(command, args);
+  if (result.exitCode !== 0) {
+    throw commandError(command, args, result.exitCode, result.stderr);
+  }
+}
+
+async function testAccess(
+  transport: SandboxTransport,
+  script: string,
+  filePath: string,
+): Promise<void> {
+  // The script is fixed; the path is a quoted positional shell argument. This
+  // handles spaces and leading dashes without interpolating user input.
+  const args = ["-c", script, "pi-msb-test", filePath];
+  const result = await transport.exec("sh", args);
+  if (result.exitCode === 0) return;
+
+  const error = commandError("sh", args, result.exitCode, result.stderr);
+  // `test` deliberately has a boolean exit status, so recover the useful
+  // missing-vs-permission distinction from the transport's filesystem probe.
+  // This probe is only made after a failed access check and never reads host fs.
+  try {
+    const exists = await transport.exists(filePath);
+    if (!exists && result.exitCode !== 127) {
+      error.code = "ENOENT";
+      if (!result.stderr.length) {
+        error.message = `ENOENT: no such file or directory, access '${filePath}'`;
+      }
+    } else if (exists && result.exitCode !== 127 && !result.stderr.length) {
+      error.code = "EACCES";
+      error.message = `EACCES: permission denied, access '${filePath}'`;
+    }
+  } catch {
+    // Keep the original command error when the diagnostic probe is unavailable.
+  }
+  throw error;
+}
+
+async function testReadable(
+  transport: SandboxTransport,
+  filePath: string,
+): Promise<void> {
+  await testAccess(transport, 'test -r "$1"', filePath);
+}
+
+async function testWritable(
+  transport: SandboxTransport,
+  filePath: string,
+): Promise<void> {
+  await testAccess(transport, 'test -w "$1"', filePath);
+}
+
+async function testReadableAndWritable(
+  transport: SandboxTransport,
+  filePath: string,
+): Promise<void> {
+  await testAccess(transport, 'test -r "$1" && test -w "$1"', filePath);
+}
+
+async function diagnoseFileCapability(transport: SandboxTransport): Promise<void> {
+  // `command` is a shell builtin on the supported images. The fixed script and
+  // separate argv[0] make this a capability probe, not a path-bearing shell call.
+  try {
+    await transport.exec("sh", [
+      "-c",
+      "command -v file >/dev/null 2>&1",
+      "pi-msb-file-capability",
+    ]);
+  } catch {
+    // A missing shell is itself a capability failure; image detection remains
+    // optional and the caller will treat the file as text.
+  }
+}
+
+function isMissingFileCommand(error: unknown): boolean {
+  const code = errorCode(error);
+  if (
+    code === "NOT_FOUND" ||
+    code === "ENOENT" ||
+    code === "COMMAND_NOT_FOUND" ||
+    code === 127
+  ) return true;
+  return error instanceof Error && /(?:file: command not found|file not found)/i.test(error.message);
+}
+
+async function detectImageMimeType(
+  transport: SandboxTransport,
+  filePath: string,
+): Promise<string | null> {
+  let result;
+  try {
+    result = await transport.exec("file", ["--mime-type", "-b", "--", filePath]);
+  } catch (error) {
+    if (!isMissingFileCommand(error)) throw error;
+    await diagnoseFileCapability(transport);
+    return null;
+  }
+
+  if (result.exitCode !== 0) {
+    if (result.exitCode === 127) await diagnoseFileCapability(transport);
+    return null;
+  }
+
+  const mimeType = result.stdout.toString("utf8").trim().toLowerCase();
+  if (!SUPPORTED_IMAGE_MIME_TYPES.has(mimeType)) return null;
+  return mimeType === "image/x-ms-bmp" ? "image/bmp" : mimeType;
+}
+
+export function createReadOps(
+  transport: SandboxTransport,
+  options: FileOpsOptions,
+): ReadOperations {
+  return {
+    access: (absolutePath) =>
+      withPathError(absolutePath, options, () =>
+        testReadable(transport, absolutePath),
+      ),
+    readFile: (absolutePath) =>
+      withPathError(absolutePath, options, () => transport.readFile(absolutePath)),
+    detectImageMimeType: (absolutePath) =>
+      withPathError(absolutePath, options, () =>
+        detectImageMimeType(transport, absolutePath),
+      ),
+  };
+}
+
+export function createWriteOps(
+  transport: SandboxTransport,
+  options: FileOpsOptions,
+): WriteOperations {
+  return {
+    mkdir: (directory) =>
+      withPathError(directory, options, () =>
+        execChecked(transport, "mkdir", ["-p", "--", directory]),
+      ),
+    writeFile: (absolutePath, content) =>
+      withPathError(absolutePath, options, () =>
+        transport.writeFile(absolutePath, content),
+      ),
+  };
+}
+
+export function createEditOps(
+  transport: SandboxTransport,
+  options: FileOpsOptions,
+): EditOperations {
+  const read = createReadOps(transport, options);
+  const write = createWriteOps(transport, options);
+  return {
+    readFile: read.readFile,
+    writeFile: write.writeFile,
+    access: (absolutePath) =>
+      withPathError(absolutePath, options, async () => {
+        // Equivalent to `test -r path && test -w path`, with each path kept in
+        // its own argument and no shell interpolation.
+        await testReadableAndWritable(transport, absolutePath);
+      }),
+  };
+}
+
+async function isDirectory(
+  transport: SandboxTransport,
+  absolutePath: string,
+): Promise<boolean> {
+  const stat = await transport.stat(absolutePath);
+  if (stat.kind === "directory") return true;
+
+  // Some SDK stat implementations report a symlink as `other` instead of
+  // following it. `test -d` supplies the same follow-symlink behavior as Node's
+  // fs.stat used by Pi's built-in ls operation.
+  const args = ["-c", 'test -d "$1"', "pi-msb-test", absolutePath];
+  try {
+    const result = await transport.exec("sh", args);
+    // Exit 1 is the intended negative probe: missing/non-directory. Exit 127
+    // means the shell/test command is unavailable and must remain an error.
+    if (result.exitCode === 127) {
+      throw commandError("sh", args, result.exitCode, result.stderr);
+    }
+    return result.exitCode === 0;
+  } catch (error) {
+    // Only a typed missing-path result is an intended negative probe. Transport
+    // failures such as ACCESS, IO, TIMEOUT, or SANDBOX_DOWN must remain visible.
+    if (isNotFound(error)) return false;
+    throw error;
+  }
+}
+
+export function createLsOps(
+  transport: SandboxTransport,
+  options: FileOpsOptions,
+): LsOperations {
+  return {
+    exists: (absolutePath) =>
+      withPathError(absolutePath, options, async () => {
+        const exists = await transport.exists(absolutePath);
+        if (
+          !exists &&
+          isOutsideProjectRoot(absolutePath, options.projectRoot)
+        ) {
+          throw sandboxPathError(absolutePath, options.projectRoot);
+        }
+        return exists;
+      }),
+    stat: (absolutePath) =>
+      withPathError(absolutePath, options, async () => {
+        const directory = await isDirectory(transport, absolutePath);
+        return { isDirectory: () => directory };
+      }),
+    readdir: (absolutePath) =>
+      withPathError(absolutePath, options, async () => {
+        const entries = await transport.list(absolutePath);
+        return entries.map((entry) => entry.name);
+      }),
+  };
+}

package/extensions/pi-msb/prune.ts

@@ -0,0 +1,232 @@
+import {
+  LABEL_KEYS,
+  STATE_SCHEMA_VERSION,
+} from "./types.ts";
+import type {
+  LocksPort,
+  ManagedSandboxRecord,
+  PruneReport,
+} from "./types.ts";
+
+/**
+ * The prune adapter deliberately exposes only sandbox operations. Keeping the
+ * port this narrow makes retention structural: prune has no volume mutation
+ * capability to accidentally call.
+ */
+export interface PrunePort {
+  listPage(input: { labels: Record<string, string>; cursor?: string }): Promise<{
+    sandboxes: ManagedSandboxRecord[];
+    nextCursor?: string;
+  }>;
+  stop(name: string, timeoutMs: number): Promise<void>;
+  remove(name: string): Promise<void>;
+}
+
+const MANAGED_LABELS: Readonly<Record<string, string>> = Object.freeze({
+  [LABEL_KEYS.managed]: "true",
+});
+
+const REQUIRED_LABELS = [
+  LABEL_KEYS.managed,
+  LABEL_KEYS.schema,
+  LABEL_KEYS.session,
+  LABEL_KEYS.mode,
+  LABEL_KEYS.cwd,
+  LABEL_KEYS.pid,
+  LABEL_KEYS.image,
+  LABEL_KEYS.keep,
+] as const;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function recordName(value: unknown): string | undefined {
+  if (!isObject(value) || typeof value.name !== "string" || value.name.length === 0) {
+    return undefined;
+  }
+  return value.name;
+}
+
+function validateRecord(value: unknown): ManagedSandboxRecord | null {
+  if (!isObject(value) || typeof value.name !== "string" || value.name.length === 0) {
+    return null;
+  }
+  if (!isObject(value.labels)) return null;
+  if (value.status !== undefined && typeof value.status !== "string") return null;
+  if (value.createdAt !== undefined && typeof value.createdAt !== "number") return null;
+
+  const labels: Record<string, string> = {};
+  for (const [key, label] of Object.entries(value.labels)) {
+    if (typeof label !== "string") return null;
+    labels[key] = label;
+  }
+
+  for (const key of REQUIRED_LABELS) {
+    if (typeof labels[key] !== "string" || labels[key].length === 0) return null;
+  }
+  if (labels[LABEL_KEYS.managed] !== "true") return null;
+  if (labels[LABEL_KEYS.schema] !== String(STATE_SCHEMA_VERSION)) return null;
+  if (!/^\d+$/.test(labels[LABEL_KEYS.pid])) return null;
+  if (!Number.isSafeInteger(Number(labels[LABEL_KEYS.pid]))) return null;
+  if (labels[LABEL_KEYS.keep] !== "true") return null;
+  if (!["git", "direct", "none"].includes(labels[LABEL_KEYS.mode])) return null;
+  if (labels[LABEL_KEYS.mode] === "git" && !labels[LABEL_KEYS.volume]) return null;
+  if (labels[LABEL_KEYS.mode] !== "git" && labels[LABEL_KEYS.volume] !== undefined) return null;
+
+  return {
+    name: value.name,
+    ...(value.status === undefined ? {} : { status: value.status }),
+    labels,
+    ...(value.createdAt === undefined ? {} : { createdAt: value.createdAt }),
+  };
+}
+
+function errorText(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  return String(error);
+}
+
+function isRunning(record: ManagedSandboxRecord): boolean {
+  const status = record.status?.trim().toLowerCase();
+  return status === "running" || status === "started" || status === "up" || status === "active";
+}
+
+function pageFingerprint(records: ManagedSandboxRecord[]): string | undefined {
+  if (records.length === 0) return undefined;
+  return records.map((record) => record.name).sort().join("\u0000");
+}
+
+/**
+ * Remove only managed sandboxes whose owner lock can be acquired. This is
+ * intentionally best-effort: an individual SDK failure must not prevent the
+ * next session from pruning other orphaned sandboxes.
+ */
+export async function pruneStale(input: {
+  port: PrunePort;
+  locks: LocksPort;
+  currentSessionId?: string;
+  stopTimeoutMs: number;
+}): Promise<PruneReport> {
+  const report: PruneReport = {
+    inspected: 0,
+    removed: [],
+    kept: [],
+    errors: [],
+  };
+
+  let cursor: string | undefined;
+  let pageNumber = 0;
+  const requestedCursors = new Set<string>();
+  const pageFingerprints = new Set<string>();
+  const seenNames = new Set<string>();
+
+  while (true) {
+    const requestKey = cursor ?? "<first>";
+    if (requestedCursors.has(requestKey)) {
+      report.errors.push(`duplicate prune page cursor: ${requestKey}`);
+      break;
+    }
+    requestedCursors.add(requestKey);
+
+    let page: { sandboxes: ManagedSandboxRecord[]; nextCursor?: string };
+    try {
+      page = await input.port.listPage(
+        cursor === undefined
+          ? { labels: MANAGED_LABELS }
+          : { labels: MANAGED_LABELS, cursor },
+      );
+    } catch (error) {
+      report.errors.push(`list page ${pageNumber + 1} failed: ${errorText(error)}`);
+      break;
+    }
+    pageNumber += 1;
+
+    if (!isObject(page) || !Array.isArray(page.sandboxes)) {
+      report.errors.push(`list page ${pageNumber} returned malformed data`);
+      break;
+    }
+    if (page.nextCursor !== undefined && typeof page.nextCursor !== "string") {
+      report.errors.push(`list page ${pageNumber} returned an invalid cursor`);
+      break;
+    }
+
+    const validPage = page.sandboxes
+      .map((value) => validateRecord(value))
+      .filter((value): value is ManagedSandboxRecord => value !== null);
+    const fingerprint = pageFingerprint(validPage);
+    if (fingerprint !== undefined) {
+      if (pageFingerprints.has(fingerprint)) {
+        report.errors.push(`duplicate prune page ${pageNumber}`);
+        break;
+      }
+      pageFingerprints.add(fingerprint);
+    }
+
+    for (let index = 0; index < page.sandboxes.length; index += 1) {
+      const rawRecord = page.sandboxes[index];
+      report.inspected += 1;
+      const record = validateRecord(rawRecord);
+      if (record === null) {
+        const name = recordName(rawRecord);
+        report.errors.push(
+          `skipped malformed managed sandbox record${name === undefined ? "" : ` ${name}`}`,
+        );
+        continue;
+      }
+      if (seenNames.has(record.name)) continue;
+      seenNames.add(record.name);
+
+      const sessionId = record.labels[LABEL_KEYS.session];
+      if (sessionId === input.currentSessionId) {
+        report.kept.push(record.name);
+        continue;
+      }
+
+      let orphanLock;
+      try {
+        orphanLock = await input.locks.tryAcquire(sessionId);
+      } catch (error) {
+        report.errors.push(`${record.name}: lock check failed: ${errorText(error)}`);
+        continue;
+      }
+      if (orphanLock === null) {
+        report.kept.push(record.name);
+        continue;
+      }
+
+      try {
+        if (isRunning(record)) {
+          try {
+            await input.port.stop(record.name, input.stopTimeoutMs);
+          } catch (error) {
+            report.errors.push(`${record.name}: stop failed: ${errorText(error)}`);
+            continue;
+          }
+        }
+
+        try {
+          await input.port.remove(record.name);
+          report.removed.push(record.name);
+        } catch (error) {
+          report.errors.push(`${record.name}: remove failed: ${errorText(error)}`);
+        }
+      } finally {
+        try {
+          await orphanLock.release();
+        } catch (error) {
+          report.errors.push(`${record.name}: lock release failed: ${errorText(error)}`);
+        }
+      }
+    }
+
+    if (page.nextCursor === undefined) break;
+    if (page.nextCursor.length === 0) {
+      report.errors.push(`list page ${pageNumber} returned an empty cursor`);
+      break;
+    }
+    cursor = page.nextCursor;
+  }
+
+  return report;
+}