@growthub/cli 0.9.14 → 0.9.17

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/globals.css

@@ -4054,16 +4054,68 @@ code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0
 .dm-record-drawer-head h2 { margin: 0; color: #111827; font-size: 16px; font-weight: 650; }
 .dm-record-testbar { display: flex; align-items: center; gap: 8px; padding: 10px 18px; border-bottom: 1px solid #edf0f3; background: #fbfdff; }
 .dm-record-testbar > span:last-child { min-width: 0; color: #64748b; font-size: 12px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.dm-record-fields { display: grid; gap: 12px; padding: 16px 18px 28px; overflow-y: auto; }
+.dm-record-fields { display: grid; gap: 8px; padding: 14px 16px 28px; overflow-y: auto; }
 .dm-record-field { display: grid; gap: 5px; }
-.dm-record-field span { color: #475569; font-size: 12px; font-weight: 650; }
+.dm-record-field span { color: #475569; font-size: 11px; font-weight: 650; }
 .dm-record-field input,
-.dm-record-field textarea { width: 100%; border: 1px solid #cbd5e1; border-radius: 6px; background: #fff; color: #111827; font: inherit; font-size: 13px; padding: 8px 9px; box-sizing: border-box; }
+.dm-record-field textarea { width: 100%; border: 1px solid #cbd5e1; border-radius: 6px; background: #fff; color: #111827; font: inherit; font-size: 12px; padding: 7px 9px; box-sizing: border-box; }
 .dm-record-field textarea { resize: vertical; font-family: ui-monospace,SFMono-Regular,Menlo,monospace; line-height: 1.45; }
 .dm-record-field input:focus,
 .dm-record-field textarea:focus { outline: none; border-color: #64748b; box-shadow: 0 0 0 3px rgba(100,116,139,.12); }
 .dm-record-field input:disabled,
 .dm-record-field textarea:disabled { background: #f8fafc; color: #64748b; }
+.dm-record-field input { width: 100%; border: 1px solid #cbd5e1; border-radius: 6px; background: #fff; color: #111827; font: inherit; font-size: 12px; padding: 7px 9px; box-sizing: border-box; }
+.dm-drawer-section { border: 1px solid #e2e8f0; border-radius: 8px; background: #fff; overflow: visible; }
+.dm-drawer-section-toggle { width: 100%; min-height: 36px; display: flex; align-items: center; gap: 8px; border: 0; border-radius: 8px; background: #f8fafc; color: #334155; font: inherit; font-size: 12px; font-weight: 700; padding: 0 11px; text-align: left; cursor: pointer; }
+.dm-drawer-section-toggle svg { flex: 0 0 auto; color: #64748b; transition: transform .12s; }
+.dm-drawer-section.open .dm-drawer-section-toggle { border-bottom: 1px solid #e2e8f0; border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
+.dm-drawer-section.open .dm-drawer-section-toggle svg { transform: rotate(90deg); }
+.dm-drawer-section-body { display: grid; gap: 10px; padding: 11px; }
+.dm-sandbox-config { display: grid; gap: 8px; }
+.dm-radio-row { display: grid; gap: 8px; }
+.dm-radio-row label, .dm-check-row { display: grid; grid-template-columns: 16px minmax(0,1fr); align-items: start; column-gap: 8px; color: #1f2937; font-size: 12px; line-height: 1.35; }
+.dm-radio-row input[type="radio"], .dm-check-row input[type="checkbox"] { width: 14px; height: 14px; margin: 1px 0 0; padding: 0; box-shadow: none; accent-color: #111827; }
+.dm-radio-row span, .dm-check-row span { color: #1f2937; font-size: 12px; font-weight: 500; }
+.dm-check-row { cursor: pointer; }
+.dm-select { position: relative; width: 100%; min-width: 180px; font-size: 11px; }
+.dm-select-trigger { width: 100%; min-height: 32px; display: flex; align-items: center; justify-content: space-between; gap: 8px; border: 1px solid #cbd5e1; border-radius: 7px; background: #fff; color: #111827; box-shadow: 0 1px 2px rgba(15,23,42,.05); font: inherit; font-size: 11px; padding: 6px 10px; text-align: left; cursor: pointer; transition: border-color .12s, box-shadow .12s, background .12s; }
+.dm-select-trigger:hover:not(:disabled) { border-color: #94a3b8; box-shadow: 0 2px 8px rgba(15,23,42,.08); }
+.dm-select.open .dm-select-trigger { border-color: #64748b; box-shadow: 0 0 0 3px rgba(100,116,139,.12), 0 2px 8px rgba(15,23,42,.08); }
+.dm-select-trigger:disabled { background: #f8fafc; color: #64748b; cursor: not-allowed; }
+.dm-select-trigger span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: #111827; font-size: 11px; font-weight: 600; }
+.dm-select-trigger span.empty { color: #94a3b8; }
+.dm-select-trigger svg { flex: 0 0 auto; color: #64748b; transition: transform .12s; }
+.dm-select.open .dm-select-trigger svg { transform: rotate(180deg); }
+.dm-select-popover { position: absolute; left: 0; right: 0; top: calc(100% + 6px); z-index: 120; display: grid; gap: 6px; min-width: 240px; padding: 8px; border: 1px solid #dbe2ea; border-radius: 8px; background: #fff; box-shadow: 0 18px 42px rgba(15,23,42,.18), 0 3px 10px rgba(15,23,42,.08); }
+.dm-select-search { display: flex; align-items: center; gap: 6px; height: 32px; border: 1px solid #e2e8f0; border-radius: 7px; background: #f8fafc; padding: 0 8px; color: #64748b; }
+.dm-select-search input { min-width: 0; flex: 1; border: 0; padding: 0; background: transparent; box-shadow: none; color: #111827; font: inherit; font-size: 11px; outline: none; }
+.dm-select-list { display: grid; gap: 2px; max-height: 232px; overflow-y: auto; padding: 2px 2px 2px 0; scrollbar-width: thin; scrollbar-color: #cbd5e1 transparent; }
+.dm-select-list::-webkit-scrollbar { width: 8px; }
+.dm-select-list::-webkit-scrollbar-thumb { border-radius: 999px; background: #cbd5e1; }
+.dm-select-option { display: grid; gap: 1px; width: 100%; border: 0; border-radius: 6px; background: transparent; color: #111827; font: inherit; font-size: 11px; line-height: 1.25; padding: 7px 9px; text-align: left; cursor: pointer; }
+.dm-select-option:hover { background: #f1f5f9; }
+.dm-select-option.selected { background: #eef2ff; color: #3730a3; font-weight: 650; }
+.dm-select-option span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 11px; font-weight: inherit; color: inherit; }
+.dm-select-option em { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: #64748b; font-size: 11px; font-style: normal; font-weight: 500; }
+.dm-select-empty { margin: 0; padding: 10px 8px; color: #94a3b8; font-size: 12px; }
+.dm-select-pager { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding-top: 4px; border-top: 1px solid #f1f5f9; }
+.dm-select-pager button { height: 26px; border: 1px solid #e2e8f0; border-radius: 6px; background: #fff; color: #334155; font: inherit; font-size: 12px; padding: 0 8px; cursor: pointer; }
+.dm-select-pager button:disabled { opacity: .45; cursor: not-allowed; }
+.dm-select-pager span { color: #64748b; font-size: 12px; font-weight: 650; }
+.dm-db-grid td:has(.dm-select) { overflow: visible; padding-top: 5px; padding-bottom: 5px; }
+.dm-db-grid td .dm-select { min-width: 230px; }
+.dm-json-field { position: relative; }
+.dm-json-field > span { padding-right: 34px; }
+.dm-json-expand { position: absolute; top: 0; right: 0; display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 24px; border: 1px solid #e2e8f0; border-radius: 6px; background: #fff; color: #64748b; box-shadow: 0 1px 2px rgba(15,23,42,.05); opacity: 0; cursor: pointer; transition: opacity .12s, border-color .12s, color .12s, box-shadow .12s; }
+.dm-json-field:hover .dm-json-expand, .dm-json-expand:focus-visible { opacity: 1; }
+.dm-json-expand:hover:not(:disabled) { border-color: #94a3b8; color: #111827; box-shadow: 0 3px 10px rgba(15,23,42,.1); }
+.dm-json-expand:disabled { cursor: not-allowed; opacity: 0; }
+.dm-json-modal-backdrop { position: fixed; inset: 0; z-index: 140; display: grid; place-items: center; padding: 24px; background: rgba(15,23,42,.38); }
+.dm-json-modal { width: min(920px, 96vw); max-height: min(760px, 90vh); display: flex; flex-direction: column; overflow: hidden; border: 1px solid #dbe2ea; border-radius: 8px; background: #fff; box-shadow: 0 28px 80px rgba(15,23,42,.28); }
+.dm-json-modal header { display: flex; align-items: center; justify-content: space-between; gap: 14px; padding: 14px 16px; border-bottom: 1px solid #edf0f3; background: #fbfdff; }
+.dm-json-modal header p { margin: 0 0 2px; color: #94a3b8; font-size: 11px; font-weight: 700; letter-spacing: .05em; text-transform: uppercase; }
+.dm-json-modal header h2 { margin: 0; color: #111827; font-size: 15px; font-weight: 650; }
+.dm-json-modal pre { margin: 0; flex: 1; overflow: auto; padding: 16px; background: #0f172a; color: #e5edf8; font: 12px/1.55 ui-monospace,SFMono-Regular,Menlo,monospace; white-space: pre-wrap; word-break: break-word; scrollbar-width: thin; scrollbar-color: #64748b transparent; }
 
 /* Relations tab */
 .dm-relations-tab { display: grid; gap: 16px; }

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/workspace-builder.jsx

@@ -126,6 +126,7 @@ function hasTestedSavedRow(table) {
 function isSelectableDataModelSource(table) {
   if (table?.storage !== "manual-object") return false;
   if (table.objectType === "api-registry") return false;
+  if (table.objectType === "sandbox-environment") return hasTestedSavedRow(table);
   if (table.objectType === "data-source") return hasTestedSavedRow(table);
   const hasStatusField = (table.columns || []).some((column) => String(column).toLowerCase() === "status");
   return hasStatusField ? hasTestedSavedRow(table) : true;

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/docs/data-sources-api-registry.md

@@ -88,6 +88,8 @@ Data Source objects are selectable only when at least one row is:
 
 This ensures widgets bind only to tested, configured sources with a known returned shape.
 
+Sandbox Environment rows are execution records, **not** widget sources. Workspace Builder excludes `objectType: "sandbox-environment"` from source pickers. For serverless sandbox runs, reuse an API Registry integration as the **scheduler webhook** by setting `schedulerRegistryId` on the sandbox row to that row’s `integrationId` (`runLocality: serverless`). See `sandbox-environment-primitive.md` in this folder.
+
 ## LeadShark Example
 
 LeadShark uses:

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/docs/sandbox-environment-primitive.md

@@ -0,0 +1,32 @@
+# Sandbox Environment (governed data object)
+
+`objectType: "sandbox-environment"` is an execution-plane manual object alongside Data Source, API Registry, People, Tasks, and Custom tables. Rows live in **`growthub.config.json#dataModel.objects[]`** — the same PATCH allowlist (`dataModel`) and validator (`apps/workspace/lib/workspace-schema.js`) as every other governed object.
+
+## Persistence and upgrades
+
+Deployed workspaces that adopted an older sandbox preset **without** `runLocality` / `schedulerRegistryId` columns keep working: `POST /api/workspace/sandbox-run` treats blank or unknown `runLocality` as **`local`** (`normalizeRunLocality` + `DEFAULT_SANDBOX_RUN_LOCALITY`). Persisted rows pick up defaults at **read time**, so operators do not have to replay migrations for existing JSON on disk until they decide to expose the new controls in the table.
+
+Operators who want the radios and scheduler FK in the Data Model grid should add columns `runLocality` and `schedulerRegistryId` to the object (matching the preset) and save via the normal PATCH path.
+
+## Where it runs (`runLocality`)
+
+| Value | Behaviour |
+| --- | --- |
+| **`local`** (default when unset / empty / unknown) | `lib/adapters/sandboxes/` resolves an adapter (`local-process`, `local-agent-host`, drop-zone). Spawn + capture happen on the Next.js host. Secrets come only from server-resolved **`envRefs`** / env. |
+| **`serverless`** | No local agent-host spawn. Outbound **`POST`** to the URL merged from API Registry row identified by **`schedulerRegistryId`** (same pattern as Data Source **`registryId`**: `integrationId`, `authRef`, `baseUrl`, `endpoint`, headers resolved server-side). Body kind **`growthub-sandbox-run-v1`**. **`local-agent-host`** is rejected in this locality. Responses map to **`stdout`** / **`stderr`** / **`exitCode`** so `lastResponse` and **`growthub.source-records.json`** stay uniform. |
+
+The scheduler webhook is deliberately thin **any** reachable HTTPS handler (Supabase Edge, Upstash/QStash-queued worker, `vercel.json` cron hitting your URL, DIY). Postgres / KV-backed workflow queues in workspace config describe *where persistence lives*, not the sandbox row itself; the **`schedulerRegistryId`** row is only the outbound HTTP binding.
+
+Agents and streamed APIs elsewhere in the sandbox stay orthogonal: serverless swaps **who invokes** the sandbox run boundary, not the rest of workspace networking.
+
+## Credential surface
+
+Sandbox rows reference **`authRef` / named env refs** — never literals in browser or config records. Scheduling uses the referenced API Registry row’s **`authRef`** merge rules identical to **`/api/workspace/test-source`**.
+
+## Not a widget source
+
+Workspace Builder excludes **`sandbox-environment`** from View widget bindings (execution records, not tabular KPI sources). See **`data-sources-api-registry.md`** in this folder.
+
+## Extension points
+
+- Custom adapters: `apps/workspace/lib/adapters/sandboxes/adapters/` (see `README.md` there).

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

@@ -0,0 +1,58 @@
+/**
+ * Sandbox adapter dynamic loader — filesystem-safe, ESM-compatible.
+ *
+ * Reads every `.js` file from `lib/adapters/sandboxes/adapters/` and
+ * side-effect-imports it so each file can call `registerSandboxAdapter()`.
+ *
+ * Mirrors `lib/adapters/integrations/resolver-loader.js` exactly so operators
+ * recognize the drop-zone pattern. Server-side only — the browser never sees
+ * this module.
+ *
+ * The default `local-process` adapter ships under
+ * `lib/adapters/sandboxes/default-local-process.js` and is loaded eagerly by
+ * `index.js`; this loader is for additional drop-zone adapters added by
+ * forks (e.g. `fly-machines.js`, `e2b.js`, `modal.js`).
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const loaded = new Set();
+let loadAttempted = false;
+
+async function loadAllSandboxAdapters() {
+  if (loadAttempted) return;
+  loadAttempted = true;
+  const adaptersDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), "lib/adapters/sandboxes/adapters");
+  try {
+    const entries = await fs.readdir(adaptersDir);
+    const jsFiles = entries.filter((f) => f.endsWith(".js") && !f.startsWith("_") && !f.startsWith("."));
+    await Promise.all(
+      jsFiles.map(async (file) => {
+        if (loaded.has(file)) return;
+        try {
+          const absolutePath = path.join(adaptersDir, file);
+          await import(/*turbopackIgnore: true*/ pathToFileURL(absolutePath).href);
+          loaded.add(file);
+        } catch {
+          // Malformed adapter — skip silently; operator needs to fix the file
+        }
+      })
+    );
+  } catch {
+    // adapters drop-zone missing or empty — normal for fresh upstream kit
+  }
+}
+
+async function listSandboxAdapterFiles() {
+  const adaptersDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), "lib/adapters/sandboxes/adapters");
+  try {
+    const entries = await fs.readdir(adaptersDir);
+    return entries.filter((f) => f.endsWith(".js") && !f.startsWith("_") && !f.startsWith("."));
+  } catch {
+    return [];
+  }
+}
+
+export { loadAllSandboxAdapters, listSandboxAdapterFiles };

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 };