@growthub/cli 0.9.13 → 0.9.16

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/sandboxes/adapters/README.md

@@ -0,0 +1,63 @@
+# Sandbox Adapters
+
+Drop one `.js` file per execution target here. Each file calls `registerSandboxAdapter()` once at module load.
+
+This is the thin agnostic extension point for the **`sandbox-environment` governed Data Model object**. Two default adapters ship eagerly with every workspace, loaded by `lib/adapters/sandboxes/index.js`:
+
+- **`local-process`** (`default-local-process.js`) — spawns python3 / node / bash inside an isolated `/tmp/growthub-sandbox-*` workdir with timeout + captured stdio. Use this when the row is a deterministic script.
+- **`local-agent-host`** (`default-local-agent-host.js`) — Paperclip thin local adapter. Routes the row through whichever local agent host CLI the operator has on PATH (Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, Qwen, Hermes, OpenClaw Gateway). Cross-platform — works on macOS, Windows, and Linux. Slugs mirror the canonical `AGENT_ADAPTER_TYPES` enum so a row is portable to the upstream Paperclip server adapter registry without translation.
+
+Files added to this drop-zone are loaded by `adapter-loader.js` on the first sandbox-run route invocation. Use the drop-zone for hardened isolation primitives (firejail, gVisor, Docker, Fly Machines, e2b, modal.com) or for additional agent host targets the canonical catalog does not yet cover.
+
+## Adapter shape
+
+```js
+import { registerSandboxAdapter } from "../sandbox-adapter-registry.js";
+
+registerSandboxAdapter({
+  id: "your-target-slug",                // stable adapter slug, must match the row's `adapter` column
+  label: "Human-readable label",
+  description: "1-line capability hint for the drawer dropdown",
+  locality: "local" | "serverless" | "remote",
+  supportedRuntimes: ["python", "node"],
+  run: async (request) => RunResult
+});
+```
+
+`request` is a sealed envelope minted by the sandbox-run route. It includes a freshly-created workdir (under `/tmp/growthub-sandbox-*`), the user's `command`, the `runtime`, the `timeoutMs`, the `networkAllow` boolean, the explicit `allowList`, and a server-resolved `env` object plus the audit-only `envRefSlugs` / `envRefsMissing` arrays. **Never** reach outside `request.env` for credentials and never log secret values, even on error paths.
+
+`RunResult` must include `{ ok, exitCode, durationMs, stdout, stderr, error?, adapterMeta? }`. The route writes the full result into `growthub.source-records.json` keyed by the sandbox row's stable sourceId, and also stamps `status` / `lastTested` / `lastResponse` on the row in `growthub.config.json` via the standard governed PATCH path.
+
+## Hard rules
+
+1. **No credential resolution inside the adapter** — the route already resolved env refs server-side. Adapters consume `request.env` only.
+2. **No filesystem writes outside the workdir** — workdir is the single owned scratch space; the route cleans it after the run.
+3. **No mutation of `growthub.config.json` or `growthub.source-records.json`** — the route owns versioned record persistence.
+4. **No browser-side execution** — adapters run server-side only. The browser never imports this folder.
+5. **No silent secret logging** — even on stderr, redact env values before returning.
+
+## Agent CLI commands
+
+```bash
+# List registered sandbox adapters (id + label + locality + supported runtimes)
+curl -s http://localhost:3000/api/workspace/sandbox-adapters
+
+# Run a single sandbox row by objectId + sandbox name
+curl -s -X POST http://localhost:3000/api/workspace/sandbox-run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "objectId": "my-sandboxes",
+    "name": "data-prep"
+  }'
+```
+
+Versioned run history lives in `growthub.source-records.json` under `sandbox:<objectId>:<slug(name)>` and survives fork export/import alongside the rest of the workspace artifact.
+
+## Serverless scheduling (`runLocality === "serverless"`)
+
+When the sandbox row’s **`runLocality`** is **`serverless`**, the sandbox-run route does **not** call `run()` on `local-process` / `local-agent-host`. Execution is delegated to an HTTP scheduler:
+
+1. **`schedulerRegistryId`** must equal an API Registry row’s **`integrationId`** (webhook-capable deployment URL + method + **`authRef`**).
+2. The route mints **`growthub-sandbox-run-v1`** JSON (no secrets inline) and **POST**s using the merged registry/request shape (parity with outbound test routes).
+3. The handler translates its own queue (KV, Postgres, cron tick, etc.) into a normal JSON or text reply; the route maps that reply into **`stdout`**, optional **`stderr`**, and **`exitCode`** — same **`lastResponse`** / sidecar semantics as **local**.
+4. Drop-zone adapters labelled **`locality: "serverless"`** are **not** used for delegation today; outbound HTTP replaces them so operators wire **already-supported** integrations + infra without a second resolver graph.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/sandboxes/default-local-agent-host.js

@@ -0,0 +1,284 @@
+/**
+ * Default sandbox adapter — local-agent-host (Paperclip thin local adapter).
+ *
+ * Routes a sandbox-environment row through whichever local agent host CLI the
+ * user has on PATH on their machine — Claude Code, Codex, Cursor, Gemini,
+ * OpenCode, Pi, Qwen, Hermes, OpenClaw Gateway. The host slugs mirror the
+ * canonical `AGENT_ADAPTER_TYPES` enum in `packages/shared/src/constants.ts`,
+ * so a sandbox configured here is portable to the upstream Paperclip server
+ * adapter registry without translation.
+ *
+ * The standalone `growthub-custom-workspace-starter-v1` ships without any
+ * @paperclipai/adapter-* workspace package import (it's a portable Next.js
+ * app that runs on a fresh user machine). Instead this adapter spawns the
+ * host CLI binary directly with the user's command. Cross-platform: works on
+ * macOS, Windows, and Linux as long as the host CLI is installed.
+ *
+ * The adapter is intentionally thin:
+ *   - it does NOT manage the host's auth state, model selection, or context window
+ *   - it does NOT mutate any host config file
+ *   - it does NOT route through the upstream Paperclip server (use the
+ *     hosted bridge for that)
+ *   - it ONLY captures stdout/stderr/exit code and returns a standard RunResult
+ *
+ * The catalog below maps each canonical host slug to the binary the operator
+ * is expected to have on PATH. Forks extend this by dropping a sibling file
+ * under `lib/adapters/sandboxes/adapters/` that calls
+ * `registerSandboxAdapter()` with their own dispatch logic — this default
+ * adapter does not need to know about every possible host.
+ */
+
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { registerSandboxAdapter } from "./sandbox-adapter-registry.js";
+
+const MAX_OUTPUT_BYTES = 1024 * 256;
+
+/**
+ * Canonical Paperclip host catalog — slugs mirror `AGENT_ADAPTER_TYPES`.
+ *
+ * Each entry declares the binary the operator must have on PATH and how to
+ * invoke it for one-shot prompt execution. `argv` returns the argv array the
+ * adapter should pass; `inputMode` chooses whether the user's command is sent
+ * via stdin or as a positional argument. `installHint` is surfaced verbatim
+ * when the binary is not found, so operators get an actionable error.
+ */
+const HOST_CATALOG = {
+  claude_local: {
+    label: "Claude Code (local)",
+    binary: "claude",
+    argv: () => ["-p", "--output-format", "text"],
+    inputMode: "stdin",
+    installHint: "Install Claude Code: npm i -g @anthropic-ai/claude-code"
+  },
+  codex_local: {
+    label: "Codex CLI (local)",
+    binary: "codex",
+    argv: () => ["exec", "--skip-git-repo-check", "--sandbox", "read-only", "-"],
+    inputMode: "stdin",
+    installHint: "Install Codex CLI: npm i -g @openai/codex"
+  },
+  cursor: {
+    label: "Cursor Agent (local)",
+    binary: "cursor-agent",
+    argv: () => ["--print"],
+    inputMode: "stdin",
+    installHint: "Install Cursor Agent CLI: curl https://cursor.com/install -fsS | bash"
+  },
+  gemini_local: {
+    label: "Gemini CLI (local)",
+    binary: "gemini",
+    argv: () => ["-p", "-"],
+    inputMode: "stdin",
+    installHint: "Install Gemini CLI: npm i -g @google/gemini-cli"
+  },
+  opencode_local: {
+    label: "OpenCode (local)",
+    binary: "opencode",
+    argv: () => ["run", "--quiet"],
+    inputMode: "stdin",
+    installHint: "Install OpenCode: npm i -g opencode-ai"
+  },
+  pi_local: {
+    label: "Pi (local)",
+    binary: "pi",
+    argv: () => ["run", "--stdin"],
+    inputMode: "stdin",
+    installHint: "Install Pi CLI: refer to your Paperclip Pi distribution"
+  },
+  qwen_local: {
+    label: "Qwen Code (local)",
+    binary: "qwen",
+    argv: () => ["-p"],
+    inputMode: "stdin",
+    installHint: "Install Qwen Code CLI: refer to your Qwen distribution"
+  },
+  hermes_local: {
+    label: "Hermes Paperclip (local)",
+    binary: "hermes",
+    argv: () => ["run", "--stdin"],
+    inputMode: "stdin",
+    installHint: "Install Hermes Paperclip adapter: npm i -g hermes-paperclip-adapter"
+  },
+  openclaw_gateway: {
+    label: "OpenClaw Gateway (local)",
+    binary: "openclaw",
+    argv: () => ["gateway", "exec", "--stdin"],
+    inputMode: "stdin",
+    installHint: "Install OpenClaw Gateway: refer to your Paperclip distribution"
+  }
+};
+
+const SUPPORTED_HOSTS = Object.keys(HOST_CATALOG);
+
+function clampStream(buffer) {
+  if (buffer.length <= MAX_OUTPUT_BYTES) return buffer.toString("utf8");
+  const head = buffer.slice(0, MAX_OUTPUT_BYTES);
+  return `${head.toString("utf8")}\n…\n[output truncated at ${MAX_OUTPUT_BYTES} bytes]`;
+}
+
+async function run(request) {
+  const hostSlug = typeof request.agentHost === "string" ? request.agentHost.trim() : "";
+  const host = HOST_CATALOG[hostSlug];
+  if (!host) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      stdout: "",
+      stderr: "",
+      error: `agentHost is required for local-agent-host adapter; pick one of ${SUPPORTED_HOSTS.join(", ")}`,
+      adapterMeta: { adapter: "local-agent-host" }
+    };
+  }
+
+  const command = typeof request.command === "string" ? request.command : "";
+  const workdir = request.workdir;
+  if (typeof workdir !== "string" || !workdir) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      stdout: "",
+      stderr: "",
+      error: "workdir is required",
+      adapterMeta: { adapter: "local-agent-host", agentHost: hostSlug }
+    };
+  }
+
+  const promptPath = path.join(workdir, "prompt.txt");
+  try {
+    await fs.writeFile(promptPath, command, "utf8");
+  } catch {
+    // Best-effort audit copy of the prompt — execution still continues
+  }
+
+  const env = {
+    PATH: process.env.PATH || "",
+    HOME: process.env.HOME || workdir,
+    TMPDIR: workdir,
+    GROWTHUB_SANDBOX: "1",
+    GROWTHUB_SANDBOX_RUN_ID: request.runId || "",
+    GROWTHUB_SANDBOX_AGENT_HOST: hostSlug,
+    GROWTHUB_SANDBOX_NET_ALLOW: request.networkAllow ? "1" : "0",
+    GROWTHUB_SANDBOX_NET_ALLOWLIST: Array.isArray(request.allowList) ? request.allowList.join(",") : "",
+    ...(request.env || {})
+  };
+
+  const timeoutMs = Number.isFinite(request.timeoutMs) && request.timeoutMs > 0 ? request.timeoutMs : 60000;
+  const startedAt = Date.now();
+  const argv = host.argv(command);
+
+  return await new Promise((resolve) => {
+    let stdout = Buffer.alloc(0);
+    let stderr = Buffer.alloc(0);
+    let timedOut = false;
+    let resolved = false;
+
+    let child;
+    try {
+      child = spawn(host.binary, argv, {
+        cwd: workdir,
+        env,
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+    } catch (error) {
+      resolve({
+        ok: false,
+        exitCode: null,
+        durationMs: Date.now() - startedAt,
+        stdout: "",
+        stderr: "",
+        error: error?.message || `failed to spawn ${host.binary}`,
+        adapterMeta: { adapter: "local-agent-host", agentHost: hostSlug, binary: host.binary, installHint: host.installHint }
+      });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill("SIGKILL"); } catch {}
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      if (stdout.length < MAX_OUTPUT_BYTES) stdout = Buffer.concat([stdout, chunk]);
+    });
+    child.stderr.on("data", (chunk) => {
+      if (stderr.length < MAX_OUTPUT_BYTES) stderr = Buffer.concat([stderr, chunk]);
+    });
+
+    child.on("error", (error) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      const notFound = error?.code === "ENOENT";
+      resolve({
+        ok: false,
+        exitCode: null,
+        durationMs: Date.now() - startedAt,
+        stdout: clampStream(stdout),
+        stderr: clampStream(stderr),
+        error: notFound
+          ? `${host.binary} not found on PATH. ${host.installHint}`
+          : (error?.message || "spawn failed"),
+        adapterMeta: {
+          adapter: "local-agent-host",
+          agentHost: hostSlug,
+          binary: host.binary,
+          installHint: host.installHint,
+          notFound
+        }
+      });
+    });
+
+    child.on("close", (exitCode, signal) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      const durationMs = Date.now() - startedAt;
+      const ok = !timedOut && exitCode === 0;
+      resolve({
+        ok,
+        exitCode: typeof exitCode === "number" ? exitCode : null,
+        durationMs,
+        stdout: clampStream(stdout),
+        stderr: clampStream(stderr),
+        error: timedOut
+          ? `timed out after ${timeoutMs}ms`
+          : (ok ? undefined : `exit ${exitCode ?? signal ?? "unknown"}`),
+        adapterMeta: {
+          adapter: "local-agent-host",
+          agentHost: hostSlug,
+          binary: host.binary,
+          argv,
+          inputMode: host.inputMode,
+          timedOut,
+          signal: signal || null
+        }
+      });
+    });
+
+    if (host.inputMode === "stdin") {
+      try {
+        child.stdin.write(command);
+      } catch {
+        // child may have already exited via spawn error — ignore
+      }
+      try { child.stdin.end(); } catch {}
+    }
+  });
+}
+
+registerSandboxAdapter({
+  id: "local-agent-host",
+  label: "Local agent host (Paperclip thin adapter)",
+  description: "Spawns a local agent host CLI on the operator's machine — Claude Code, Codex, Cursor, Gemini, OpenCode, Pi, Qwen, Hermes, OpenClaw Gateway. Cross-platform (macOS / Windows / Linux). Slugs mirror Paperclip AGENT_ADAPTER_TYPES so the row is portable to the upstream server adapter registry.",
+  locality: "local",
+  supportedRuntimes: ["bash", "node", "python"],
+  supportedHosts: SUPPORTED_HOSTS,
+  hostCatalog: HOST_CATALOG,
+  run
+});
+
+export { HOST_CATALOG, SUPPORTED_HOSTS };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/sandboxes/default-local-process.js

@@ -0,0 +1,194 @@
+/**
+ * Default sandbox adapter — local-process.
+ *
+ * Thin agnostic execution surface. For each invocation:
+ *   1. The sandbox-run route mints a fresh /tmp/growthub-sandbox-<runId>/ workdir
+ *      and resolves env refs server-side (browser never sees secrets).
+ *   2. This adapter writes the user-supplied command to a runtime-specific
+ *      entry file inside the workdir, then spawns the appropriate interpreter
+ *      with strict timeout + captured stdio.
+ *   3. After the child exits (or is killed for timeout), the route cleans the
+ *      workdir and persists a versioned record into
+ *      `growthub.source-records.json` keyed by sandbox sourceId.
+ *
+ * The adapter intentionally does NOT:
+ *   - read or write outside the supplied workdir
+ *   - persist state across runs
+ *   - expand env refs (the route already resolved them)
+ *   - log secret values, even on stderr (only stream the child's own stderr)
+ *   - enforce OS-level network isolation (the operator runtime owns that;
+ *     this adapter simply forwards `networkAllow` + `allowList` into
+ *     adapterMeta and into a `GROWTHUB_SANDBOX_NET_ALLOW`/`_ALLOWLIST` env
+ *     pair the user's script can consult.)
+ *
+ * Forks that need a hardened isolation primitive (firejail, gVisor, Docker,
+ * Fly Machines, e2b, modal.com, etc.) ship a sibling adapter file under
+ * `lib/adapters/sandboxes/adapters/` and call `registerSandboxAdapter()`.
+ */
+
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { registerSandboxAdapter } from "./sandbox-adapter-registry.js";
+
+const ENTRY_FILE_BY_RUNTIME = {
+  python: "entry.py",
+  node: "entry.js",
+  bash: "entry.sh"
+};
+
+const INTERPRETER_BY_RUNTIME = {
+  python: { command: "python3", argv: (entry) => [entry] },
+  node: { command: "node", argv: (entry) => [entry] },
+  bash: { command: "bash", argv: (entry) => [entry] }
+};
+
+const MAX_OUTPUT_BYTES = 1024 * 256; // 256 KiB per stream — enough for diagnostics, prevents runaway capture
+
+function clampStream(buffer) {
+  if (buffer.length <= MAX_OUTPUT_BYTES) return buffer.toString("utf8");
+  const head = buffer.slice(0, MAX_OUTPUT_BYTES);
+  return `${head.toString("utf8")}\n…\n[output truncated at ${MAX_OUTPUT_BYTES} bytes]`;
+}
+
+async function run(request) {
+  const runtime = request?.runtime;
+  const interpreter = INTERPRETER_BY_RUNTIME[runtime];
+  const entryName = ENTRY_FILE_BY_RUNTIME[runtime];
+  if (!interpreter || !entryName) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      stdout: "",
+      stderr: "",
+      error: `unsupported runtime: ${String(runtime)}`,
+      adapterMeta: { adapter: "local-process" }
+    };
+  }
+
+  const workdir = request.workdir;
+  if (typeof workdir !== "string" || !workdir) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      stdout: "",
+      stderr: "",
+      error: "workdir is required",
+      adapterMeta: { adapter: "local-process" }
+    };
+  }
+
+  const entryPath = path.join(workdir, entryName);
+  const command = typeof request.command === "string" ? request.command : "";
+
+  try {
+    await fs.writeFile(entryPath, command, "utf8");
+    if (runtime === "bash") {
+      await fs.chmod(entryPath, 0o700);
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      exitCode: null,
+      durationMs: 0,
+      stdout: "",
+      stderr: "",
+      error: `failed to write entry file: ${error.message || "unknown"}`,
+      adapterMeta: { adapter: "local-process" }
+    };
+  }
+
+  const env = {
+    PATH: process.env.PATH || "",
+    HOME: workdir,
+    TMPDIR: workdir,
+    GROWTHUB_SANDBOX: "1",
+    GROWTHUB_SANDBOX_RUN_ID: request.runId || "",
+    GROWTHUB_SANDBOX_NET_ALLOW: request.networkAllow ? "1" : "0",
+    GROWTHUB_SANDBOX_NET_ALLOWLIST: Array.isArray(request.allowList) ? request.allowList.join(",") : "",
+    ...(request.env || {})
+  };
+
+  const timeoutMs = Number.isFinite(request.timeoutMs) && request.timeoutMs > 0 ? request.timeoutMs : 60000;
+  const startedAt = Date.now();
+
+  return await new Promise((resolve) => {
+    let stdout = Buffer.alloc(0);
+    let stderr = Buffer.alloc(0);
+    let timedOut = false;
+    let resolved = false;
+
+    const child = spawn(interpreter.command, interpreter.argv(entryPath), {
+      cwd: workdir,
+      env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill("SIGKILL"); } catch {}
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      if (stdout.length < MAX_OUTPUT_BYTES) stdout = Buffer.concat([stdout, chunk]);
+    });
+    child.stderr.on("data", (chunk) => {
+      if (stderr.length < MAX_OUTPUT_BYTES) stderr = Buffer.concat([stderr, chunk]);
+    });
+
+    child.on("error", (error) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve({
+        ok: false,
+        exitCode: null,
+        durationMs: Date.now() - startedAt,
+        stdout: clampStream(stdout),
+        stderr: clampStream(stderr),
+        error: error.code === "ENOENT"
+          ? `interpreter not found: ${interpreter.command} (install ${runtime} runtime on the host)`
+          : error.message || "spawn failed",
+        adapterMeta: { adapter: "local-process", runtime, timedOut: false }
+      });
+    });
+
+    child.on("close", (exitCode, signal) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      const durationMs = Date.now() - startedAt;
+      const ok = !timedOut && exitCode === 0;
+      resolve({
+        ok,
+        exitCode: typeof exitCode === "number" ? exitCode : null,
+        durationMs,
+        stdout: clampStream(stdout),
+        stderr: clampStream(stderr),
+        error: timedOut
+          ? `timed out after ${timeoutMs}ms`
+          : (ok ? undefined : `exit ${exitCode ?? signal ?? "unknown"}`),
+        adapterMeta: {
+          adapter: "local-process",
+          runtime,
+          interpreter: interpreter.command,
+          timedOut,
+          signal: signal || null,
+          networkAllow: Boolean(request.networkAllow),
+          allowList: Array.isArray(request.allowList) ? request.allowList : []
+        }
+      });
+    });
+  });
+}
+
+registerSandboxAdapter({
+  id: "local-process",
+  label: "Local process (default)",
+  description: "Spawns python3/node/bash inside an isolated /tmp/growthub-sandbox-* workdir with timeout + captured stdio. Operator runtime is responsible for OS-level network isolation; allow list is published to the script via GROWTHUB_SANDBOX_NET_ALLOW(LIST).",
+  locality: "local",
+  supportedRuntimes: ["python", "node", "bash"],
+  run
+});

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/sandboxes/index.js

@@ -0,0 +1,33 @@
+/**
+ * Sandbox adapter facade.
+ *
+ * Eagerly registers the default `local-process` adapter so the workspace works
+ * out of the box, then loads any drop-zone adapter files added by the fork.
+ * Routes import `ensureSandboxAdaptersLoaded()` once before they call
+ * `getSandboxAdapter(id)`.
+ */
+
+import "./default-local-process.js";
+import "./default-local-agent-host.js";
+import { loadAllSandboxAdapters } from "./adapter-loader.js";
+
+let baseLoaded = true; // default-local-process registered via static import
+let dropZoneLoadStarted = false;
+let dropZoneLoadComplete = null;
+
+async function ensureSandboxAdaptersLoaded() {
+  if (!baseLoaded) baseLoaded = true;
+  if (!dropZoneLoadStarted) {
+    dropZoneLoadStarted = true;
+    dropZoneLoadComplete = loadAllSandboxAdapters();
+  }
+  await dropZoneLoadComplete;
+}
+
+export { ensureSandboxAdaptersLoaded };
+export {
+  describeRegisteredSandboxAdapters,
+  getSandboxAdapter,
+  listRegisteredSandboxAdapters,
+  registerSandboxAdapter
+} from "./sandbox-adapter-registry.js";

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/sandboxes/sandbox-adapter-registry.js

@@ -0,0 +1,113 @@
+/**
+ * Sandbox Adapter Registry — execution-target-agnostic dispatch layer.
+ *
+ * The sandbox-environment governed Data Model object selects an adapter by id.
+ * Each adapter is a thin, opinion-free execution target that takes a sealed
+ * RunRequest and returns a RunResult. Adapters are dropped into
+ * `lib/adapters/sandboxes/adapters/` and loaded by `adapter-loader.js`.
+ *
+ * Contract — every adapter must call `registerSandboxAdapter()` once at module
+ * load with the following shape:
+ *
+ *   {
+ *     id:           string,                              // stable adapter slug, e.g. "local-process", "fly-machines", "e2b"
+ *     label:        string,                              // human-readable name for the drawer dropdown
+ *     description:  string,                              // 1-line capability hint
+ *     locality:     "local" | "serverless" | "remote",   // surfacing hint for the drawer
+ *     supportedRuntimes: string[],                       // e.g. ["python", "node", "bash"]
+ *     run: async (request, options?) => RunResult        // the execution function
+ *   }
+ *
+ * RunRequest (sealed envelope passed to `run`):
+ *   {
+ *     runId:           string,            // stable id for the record
+ *     name:            string,            // sandbox row name (display only)
+ *     runtime:         string,            // KNOWN_SANDBOX_RUNTIMES member
+ *     command:         string,            // bash script / entry script (server-resolved)
+ *     timeoutMs:       number,            // hard cap, capped at SANDBOX_MAX_TIMEOUT_MS
+ *     networkAllow:    boolean,           // allow outbound network from inside the sandbox
+ *     allowList:       string[],          // hostnames the user explicitly allowed
+ *     env:             Record<string,string>, // server-resolved env (NEVER sent to browser)
+ *     envRefSlugs:     string[],          // ref slugs resolved (kept for record metadata)
+ *     envRefsMissing:  string[],          // slugs the server could not resolve (audit-only)
+ *     workdir:         string,            // freshly-minted /tmp/growthub-sandbox-* path
+ *     ranAt:           string             // ISO timestamp
+ *   }
+ *
+ * RunResult (returned by `run`):
+ *   {
+ *     ok:        boolean,
+ *     exitCode:  number | null,
+ *     durationMs: number,
+ *     stdout:    string,
+ *     stderr:    string,
+ *     error?:    string,
+ *     adapterMeta?: Record<string, unknown>
+ *   }
+ *
+ * Adapters MUST NOT:
+ *   - read or persist files inside the workspace cwd; use the supplied workdir
+ *   - log secret values, even on error paths
+ *   - reach outside `request.env` for credential resolution
+ *   - mutate `growthub.config.json` or `growthub.source-records.json` directly
+ *     (the sandbox-run route handles versioned record persistence)
+ *
+ * The route and the data-model drawer reference this registry only — they have
+ * zero knowledge of any specific execution target. This keeps the adapter
+ * surface infinitely composable while preserving the governed integration
+ * substrate (server-side credential boundary, sidecar persistence,
+ * fork-sync-safe drop-zone extensibility).
+ */
+
+if (!globalThis.__growthubSandboxAdapterRegistry) {
+  globalThis.__growthubSandboxAdapterRegistry = new Map();
+}
+const registry = globalThis.__growthubSandboxAdapterRegistry;
+
+function registerSandboxAdapter(adapter) {
+  if (!adapter || typeof adapter !== "object") {
+    throw new Error("registerSandboxAdapter: adapter must be a plain object");
+  }
+  if (typeof adapter.id !== "string" || !adapter.id.trim()) {
+    throw new Error("registerSandboxAdapter: adapter.id must be a non-empty string");
+  }
+  if (typeof adapter.run !== "function") {
+    throw new Error(`registerSandboxAdapter(${adapter.id}): adapter.run must be a function`);
+  }
+  registry.set(adapter.id.trim(), adapter);
+}
+
+function getSandboxAdapter(id) {
+  if (typeof id !== "string" || !id.trim()) return null;
+  return registry.get(id.trim()) || null;
+}
+
+function listRegisteredSandboxAdapters() {
+  return Array.from(registry.keys());
+}
+
+function describeRegisteredSandboxAdapters() {
+  return Array.from(registry.entries()).map(([id, adapter]) => ({
+    id,
+    label: typeof adapter.label === "string" ? adapter.label : id,
+    description: typeof adapter.description === "string" ? adapter.description : "",
+    locality: ["local", "serverless", "remote"].includes(adapter.locality) ? adapter.locality : "local",
+    supportedRuntimes: Array.isArray(adapter.supportedRuntimes) ? adapter.supportedRuntimes : [],
+    supportedHosts: Array.isArray(adapter.supportedHosts) ? adapter.supportedHosts : null,
+    hostCatalog: adapter.hostCatalog && typeof adapter.hostCatalog === "object"
+      ? Object.entries(adapter.hostCatalog).map(([slug, host]) => ({
+          slug,
+          label: host?.label || slug,
+          binary: host?.binary || null,
+          installHint: host?.installHint || null
+        }))
+      : null
+  }));
+}
+
+export {
+  describeRegisteredSandboxAdapters,
+  getSandboxAdapter,
+  listRegisteredSandboxAdapters,
+  registerSandboxAdapter
+};