feat(FN-4636): complete Step 1 — define sandbox backend interface

Fusion-Task-Id: FN-4636
Fusion-Task-Lineage: 38ff2f48-4cb1-42c2-8f64-eb3b8d3d7f2c

packages/engine/src/sandbox/__tests__/types.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+
+import type { SandboxBackend, SandboxCapabilities, SandboxPolicy, SandboxRunOptions, SandboxRunResult } from "../types.js";
+
+describe("SandboxBackend types", () => {
+  it("accepts a minimal mock backend", async () => {
+    const backend: SandboxBackend = {
+      capabilities(): SandboxCapabilities {
+        return {
+          id: "native",
+          supportsNetworkPolicy: false,
+          supportsFilesystemPolicy: false,
+          platform: "any",
+        };
+      },
+      async prepare(_policy: SandboxPolicy): Promise<void> {},
+      async run(_command: string, _options: SandboxRunOptions): Promise<SandboxRunResult> {
+        return {
+          stdout: "",
+          stderr: "",
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          bufferExceeded: false,
+        };
+      },
+      async dispose(): Promise<void> {},
+    };
+
+    await expect(backend.prepare({ allowNetwork: true })).resolves.toBeUndefined();
+    await expect(backend.dispose()).resolves.toBeUndefined();
+  });
+});

packages/engine/src/sandbox/types.ts

@@ -0,0 +1,46 @@
+export interface SandboxPolicy {
+  allowNetwork: boolean;
+  /** @future Backends with filesystem isolation will enforce this. */
+  allowedReadPaths?: string[];
+  /** @future Backends with filesystem isolation will enforce this. */
+  allowedWritePaths?: string[];
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface SandboxRunOptions {
+  cwd: string;
+  timeoutMs: number;
+  maxBuffer: number;
+  shell?: string | boolean;
+  env?: NodeJS.ProcessEnv;
+  encoding?: BufferEncoding;
+  signal?: AbortSignal;
+}
+
+export interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  timedOut: boolean;
+  bufferExceeded: boolean;
+  spawnError?: Error;
+}
+
+export interface SandboxCapabilities {
+  id: "native" | "sandbox-exec" | "bubblewrap" | "firejail" | "docker" | "podman" | "custom";
+  supportsNetworkPolicy: boolean;
+  supportsFilesystemPolicy: boolean;
+  platform: NodeJS.Platform[] | "any";
+}
+
+export interface SandboxBackend {
+  /** Hot-path capability descriptor for backend selection/routing. */
+  capabilities(): SandboxCapabilities;
+  /** Prepare backend state for a policy. Must be idempotent. */
+  prepare(policy: SandboxPolicy): Promise<void>;
+  /** Execute a command in the backend's environment. */
+  run(command: string, options: SandboxRunOptions): Promise<SandboxRunResult>;
+  /** Best-effort cleanup hook for backend-owned resources. */
+  dispose(): Promise<void>;
+}