Add sandbox environment support (#4415)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The environment/runtime layer decides where agent work executes and
how the control plane reaches those runtimes.
> - Today Paperclip can run locally and over SSH, but sandboxed
execution needs a first-class environment model instead of one-off
adapter behavior.
> - We also want sandbox providers to be pluggable so the core does not
hardcode every provider implementation.
> - This branch adds the Sandbox environment path, the provider
contract, and a deterministic fake provider plugin.
> - That required synchronized changes across shared contracts, plugin
SDK surfaces, server runtime orchestration, and the UI
environment/workspace flows.
> - The result is that sandbox execution becomes a core control-plane
capability while keeping provider implementations extensible and
testable.

## What Changed

- Added sandbox runtime support to the environment execution path,
including runtime URL discovery, sandbox execution targeting,
orchestration, and heartbeat integration.
- Added plugin-provider support for sandbox environments so providers
can be supplied via plugins instead of hardcoded server logic.
- Added the fake sandbox provider plugin with deterministic behavior
suitable for local and automated testing.
- Updated shared types, validators, plugin protocol definitions, and SDK
helpers to carry sandbox provider and workspace-runtime contracts across
package boundaries.
- Updated server routes and services so companies can create sandbox
environments, select them for work, and execute work through the sandbox
runtime path.
- Updated the UI environment and workspace surfaces to expose sandbox
environment configuration and selection.
- Added test coverage for sandbox runtime behavior, provider seams,
environment route guards, orchestration, and the fake provider plugin.

## Verification

- Ran locally before the final fixture-only scrub:
  - `pnpm -r typecheck`
  - `pnpm test:run`
  - `pnpm build`
- Ran locally after the final scrub amend:
  - `pnpm vitest run server/src/__tests__/runtime-api.test.ts`
- Reviewer spot checks:
  - create a sandbox environment backed by the fake provider plugin
  - run work through that environment
- confirm sandbox provider execution does not inherit host secrets
implicitly

## Risks

- This touches shared contracts, plugin SDK plumbing, server runtime
orchestration, and UI environment/workspace flows, so regressions would
likely show up as cross-layer mismatches rather than isolated type
errors.
- Runtime URL discovery and sandbox callback selection are sensitive to
host/bind configuration; if that logic is wrong, sandbox-backed
callbacks may fail even when execution succeeds.
- The fake provider plugin is intentionally deterministic and
test-oriented; future providers may expose capability gaps that this
branch does not yet cover.

## Model Used

- OpenAI Codex coding agent on a GPT-5-class backend in the
Paperclip/Codex harness. Exact backend model ID is not exposed
in-session. Tool-assisted workflow with shell execution, file editing,
git history inspection, and local test execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

packages/plugins/paperclip-plugin-fake-sandbox/src/index.ts

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as plugin } from "./plugin.js";

packages/plugins/paperclip-plugin-fake-sandbox/src/manifest.ts

@@ -0,0 +1,50 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_ID = "paperclip.fake-sandbox-provider";
+const PLUGIN_VERSION = "0.1.0";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "Fake Sandbox Provider",
+  description:
+    "First-party deterministic sandbox provider plugin for exercising Paperclip provider-plugin integration without external infrastructure.",
+  author: "Paperclip",
+  categories: ["automation"],
+  capabilities: ["environment.drivers.register"],
+  entrypoints: {
+    worker: "./dist/worker.js",
+  },
+  environmentDrivers: [
+    {
+      driverKey: "fake-plugin",
+      kind: "sandbox_provider",
+      displayName: "Fake Sandbox Provider",
+      description:
+        "Runs commands in an isolated local temporary directory while exercising the sandbox provider plugin lifecycle.",
+      configSchema: {
+        type: "object",
+        properties: {
+          image: {
+            type: "string",
+            description: "Deterministic fake image label for metadata and matching.",
+            default: "fake:latest",
+          },
+          timeoutMs: {
+            type: "number",
+            description: "Command timeout in milliseconds.",
+            default: 300000,
+          },
+          reuseLease: {
+            type: "boolean",
+            description: "Whether to reuse fake leases by environment id.",
+            default: false,
+          },
+        },
+      },
+    },
+  ],
+};
+
+export default manifest;

packages/plugins/paperclip-plugin-fake-sandbox/src/plugin.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+import {
+  assertEnvironmentEventOrder,
+  createEnvironmentTestHarness,
+} from "@paperclipai/plugin-sdk/testing";
+import manifest from "./manifest.js";
+import plugin from "./plugin.js";
+
+describe("fake sandbox provider plugin", () => {
+  it("runs a deterministic provider lifecycle through environment hooks", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onValidateConfig: definition.onEnvironmentValidateConfig,
+        onProbe: definition.onEnvironmentProbe,
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onResumeLease: definition.onEnvironmentResumeLease,
+        onReleaseLease: definition.onEnvironmentReleaseLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+
+    const validation = await harness.validateConfig({
+      driverKey: "fake-plugin",
+      config: base.config,
+    });
+    expect(validation).toMatchObject({
+      ok: true,
+      normalizedConfig: { image: "fake:test", reuseLease: false },
+    });
+
+    const probe = await harness.probe(base);
+    expect(probe).toMatchObject({
+      ok: true,
+      metadata: { provider: "fake-plugin", image: "fake:test" },
+    });
+
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    expect(lease.providerLeaseId).toContain("fake-plugin://run-1/");
+
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+    expect(realized.cwd).toContain("paperclip-fake-sandbox-");
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "printf fake-plugin-ok"],
+      cwd: realized.cwd,
+      timeoutMs: 10_000,
+    });
+    expect(executed).toMatchObject({
+      exitCode: 0,
+      timedOut: false,
+      stdout: "fake-plugin-ok",
+    });
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+
+    assertEnvironmentEventOrder(harness.environmentEvents, [
+      "validateConfig",
+      "probe",
+      "acquireLease",
+      "realizeWorkspace",
+      "execute",
+      "destroyLease",
+    ]);
+  });
+
+  it("does not expose host-only environment variables to executed commands", async () => {
+    const previousSecret = process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET;
+    process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET = "should-not-leak";
+    try {
+      const definition = plugin.definition;
+      const harness = createEnvironmentTestHarness({
+        manifest,
+        environmentDriver: {
+          driverKey: "fake-plugin",
+          onAcquireLease: definition.onEnvironmentAcquireLease,
+          onDestroyLease: definition.onEnvironmentDestroyLease,
+          onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+          onExecute: definition.onEnvironmentExecute,
+        },
+      });
+      const base = {
+        driverKey: "fake-plugin",
+        companyId: "company-1",
+        environmentId: "env-1",
+        config: { image: "fake:test", reuseLease: false },
+      };
+      const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+      const realized = await harness.realizeWorkspace({
+        ...base,
+        lease,
+        workspace: { mode: "isolated_workspace" },
+      });
+
+      const executed = await harness.execute({
+        ...base,
+        lease,
+        command: "sh",
+        args: ["-lc", "test -z \"${PAPERCLIP_FAKE_PLUGIN_HOST_SECRET+x}\" && printf \"$EXPLICIT_ONLY\""],
+        cwd: realized.cwd,
+        env: { EXPLICIT_ONLY: "visible" },
+        timeoutMs: 10_000,
+      });
+
+      expect(executed).toMatchObject({
+        exitCode: 0,
+        timedOut: false,
+        stdout: "visible",
+      });
+
+      await harness.destroyLease({
+        ...base,
+        providerLeaseId: lease.providerLeaseId,
+      });
+    } finally {
+      if (previousSecret === undefined) {
+        delete process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET;
+      } else {
+        process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET = previousSecret;
+      }
+    }
+  });
+
+  it("includes /usr/local/bin in the default PATH when no PATH override is provided", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "printf %s \"$PATH\""],
+      cwd: realized.cwd,
+      timeoutMs: 10_000,
+    });
+
+    expect(executed.stdout).toContain("/usr/local/bin");
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+  });
+
+  it("escalates to SIGKILL after timeout if the child ignores SIGTERM", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "trap '' TERM; while :; do sleep 1; done"],
+      cwd: realized.cwd,
+      timeoutMs: 100,
+    });
+
+    expect(executed.timedOut).toBe(true);
+    expect(executed.exitCode).toBeNull();
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+  });
+});

packages/plugins/paperclip-plugin-fake-sandbox/src/plugin.ts

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { definePlugin } from "@paperclipai/plugin-sdk";
+import type {
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+} from "@paperclipai/plugin-sdk";
+
+interface FakeDriverConfig {
+  image: string;
+  timeoutMs: number;
+  reuseLease: boolean;
+}
+
+interface FakeLeaseState {
+  providerLeaseId: string;
+  rootDir: string;
+  remoteCwd: string;
+  image: string;
+  reuseLease: boolean;
+}
+
+const leases = new Map<string, FakeLeaseState>();
+const DEFAULT_FAKE_SANDBOX_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+const FAKE_SANDBOX_SIGKILL_GRACE_MS = 250;
+
+function parseConfig(raw: Record<string, unknown>): FakeDriverConfig {
+  return {
+    image: typeof raw.image === "string" && raw.image.trim().length > 0 ? raw.image.trim() : "fake:latest",
+    timeoutMs: typeof raw.timeoutMs === "number" && Number.isFinite(raw.timeoutMs) ? raw.timeoutMs : 300_000,
+    reuseLease: raw.reuseLease === true,
+  };
+}
+
+async function createLeaseState(input: {
+  providerLeaseId: string;
+  image: string;
+  reuseLease: boolean;
+}): Promise<FakeLeaseState> {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-fake-sandbox-"));
+  const remoteCwd = path.join(rootDir, "workspace");
+  await mkdir(remoteCwd, { recursive: true });
+  const state = {
+    providerLeaseId: input.providerLeaseId,
+    rootDir,
+    remoteCwd,
+    image: input.image,
+    reuseLease: input.reuseLease,
+  };
+  leases.set(input.providerLeaseId, state);
+  return state;
+}
+
+function leaseMetadata(state: FakeLeaseState) {
+  return {
+    provider: "fake-plugin",
+    image: state.image,
+    reuseLease: state.reuseLease,
+    remoteCwd: state.remoteCwd,
+    fakeRootDir: state.rootDir,
+  };
+}
+
+async function removeLease(providerLeaseId: string | null | undefined): Promise<void> {
+  if (!providerLeaseId) return;
+  const state = leases.get(providerLeaseId);
+  leases.delete(providerLeaseId);
+  if (state) {
+    await rm(state.rootDir, { recursive: true, force: true });
+  }
+}
+
+function buildCommandLine(command: string, args: string[] | undefined): string {
+  return [command, ...(args ?? [])].join(" ");
+}
+
+function buildCommandEnvironment(explicitEnv: Record<string, string> | undefined): Record<string, string> {
+  return {
+    PATH: explicitEnv?.PATH ?? DEFAULT_FAKE_SANDBOX_PATH,
+    ...(explicitEnv ?? {}),
+  };
+}
+
+async function runCommand(params: PluginEnvironmentExecuteParams, timeoutMs: number): Promise<PluginEnvironmentExecuteResult> {
+  const cwd = typeof params.cwd === "string" && params.cwd.length > 0 ? params.cwd : process.cwd();
+  const startedAt = new Date().toISOString();
+
+  return await new Promise((resolve, reject) => {
+    const child = spawn(params.command, params.args ?? [], {
+      cwd,
+      env: buildCommandEnvironment(params.env),
+      shell: false,
+      stdio: [params.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let killTimer: NodeJS.Timeout | null = null;
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGTERM");
+          killTimer = setTimeout(() => {
+            child.kill("SIGKILL");
+          }, FAKE_SANDBOX_SIGKILL_GRACE_MS);
+        }, timeoutMs)
+      : null;
+
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      if (timer) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        exitCode: timedOut ? null : code,
+        signal,
+        timedOut,
+        stdout,
+        stderr,
+        metadata: {
+          startedAt,
+          commandLine: buildCommandLine(params.command, params.args),
+        },
+      });
+    });
+
+    if (params.stdin != null && child.stdin) {
+      child.stdin.write(params.stdin);
+      child.stdin.end();
+    }
+  });
+}
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    ctx.logger.info("Fake sandbox provider plugin ready");
+  },
+
+  async onHealth() {
+    return { status: "ok", message: "Fake sandbox provider plugin healthy" };
+  },
+
+  async onEnvironmentValidateConfig(
+    params: PluginEnvironmentValidateConfigParams,
+  ): Promise<PluginEnvironmentValidationResult> {
+    const config = parseConfig(params.config);
+    return {
+      ok: true,
+      normalizedConfig: { ...config },
+    };
+  },
+
+  async onEnvironmentProbe(
+    params: PluginEnvironmentProbeParams,
+  ): Promise<PluginEnvironmentProbeResult> {
+    const config = parseConfig(params.config);
+    return {
+      ok: true,
+      summary: `Fake sandbox provider is ready for image ${config.image}.`,
+      metadata: {
+        provider: "fake-plugin",
+        image: config.image,
+        timeoutMs: config.timeoutMs,
+        reuseLease: config.reuseLease,
+      },
+    };
+  },
+
+  async onEnvironmentAcquireLease(
+    params: PluginEnvironmentAcquireLeaseParams,
+  ): Promise<PluginEnvironmentLease> {
+    const config = parseConfig(params.config);
+    const providerLeaseId = config.reuseLease
+      ? `fake-plugin://${params.environmentId}`
+      : `fake-plugin://${params.runId}/${randomUUID()}`;
+    const existing = leases.get(providerLeaseId);
+    const state = existing ?? await createLeaseState({
+      providerLeaseId,
+      image: config.image,
+      reuseLease: config.reuseLease,
+    });
+
+    return {
+      providerLeaseId,
+      metadata: {
+        ...leaseMetadata(state),
+        resumedLease: Boolean(existing),
+      },
+    };
+  },
+
+  async onEnvironmentResumeLease(
+    params: PluginEnvironmentResumeLeaseParams,
+  ): Promise<PluginEnvironmentLease> {
+    const config = parseConfig(params.config);
+    const existing = leases.get(params.providerLeaseId);
+    const state = existing ?? await createLeaseState({
+      providerLeaseId: params.providerLeaseId,
+      image: config.image,
+      reuseLease: config.reuseLease,
+    });
+
+    return {
+      providerLeaseId: state.providerLeaseId,
+      metadata: {
+        ...leaseMetadata(state),
+        resumedLease: true,
+      },
+    };
+  },
+
+  async onEnvironmentReleaseLease(
+    params: PluginEnvironmentReleaseLeaseParams,
+  ): Promise<void> {
+    const config = parseConfig(params.config);
+    if (!config.reuseLease) {
+      await removeLease(params.providerLeaseId);
+    }
+  },
+
+  async onEnvironmentDestroyLease(
+    params: PluginEnvironmentDestroyLeaseParams,
+  ): Promise<void> {
+    await removeLease(params.providerLeaseId);
+  },
+
+  async onEnvironmentRealizeWorkspace(
+    params: PluginEnvironmentRealizeWorkspaceParams,
+  ): Promise<PluginEnvironmentRealizeWorkspaceResult> {
+    const state = params.lease.providerLeaseId
+      ? leases.get(params.lease.providerLeaseId)
+      : null;
+    const remoteCwd =
+      state?.remoteCwd ??
+      (typeof params.lease.metadata?.remoteCwd === "string" ? params.lease.metadata.remoteCwd : null) ??
+      params.workspace.remotePath ??
+      params.workspace.localPath ??
+      path.join(os.tmpdir(), "paperclip-fake-sandbox-workspace");
+
+    await mkdir(remoteCwd, { recursive: true });
+
+    return {
+      cwd: remoteCwd,
+      metadata: {
+        provider: "fake-plugin",
+        remoteCwd,
+      },
+    };
+  },
+
+  async onEnvironmentExecute(
+    params: PluginEnvironmentExecuteParams,
+  ): Promise<PluginEnvironmentExecuteResult> {
+    const config = parseConfig(params.config);
+    return await runCommand(params, params.timeoutMs ?? config.timeoutMs);
+  },
+});
+
+export default plugin;

packages/plugins/paperclip-plugin-fake-sandbox/src/worker.ts

@@ -0,0 +1,5 @@
+import { runWorker } from "@paperclipai/plugin-sdk";
+import plugin from "./plugin.js";
+
+export default plugin;
+runWorker(plugin, import.meta.url);