@growthub/cli 0.9.14 → 0.9.17

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

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-data-model.js

@@ -370,6 +370,42 @@ const OBJECT_TYPE_PRESETS = {
     columns: ["Name", "Status", "DueDate", "Assignee", "Priority"],
     relations: []
   },
+  "sandbox-environment": {
+    label: "Sandbox Environment",
+    icon: "Terminal",
+    description: "Execution locality: local (process sandbox or Paperclip thin local agent-host CLI) or serverless (delegates to an API Registry HTTP target: Edge/QStash/cron webhook). Env refs resolve server-side; run history in growthub.source-records.json. Not a widget binding source.",
+    columns: [
+      "Name",
+      "lifecycleStatus",
+      "version",
+      "runLocality",
+      "schedulerRegistryId",
+      "runtime",
+      "adapter",
+      "agentHost",
+      "envRefs",
+      "networkAllow",
+      "allowList",
+      "instructions",
+      "command",
+      "timeoutMs",
+      "status",
+      "lastTested",
+      "lastRunId",
+      "lastSourceId",
+      "lastResponse"
+    ],
+    relations: [
+      {
+        id: "scheduler-registry-binding",
+        name: "Scheduler (serverless)",
+        field: "schedulerRegistryId",
+        targetObjectType: "api-registry",
+        type: "belongs-to",
+        description: "When runLocality is serverless, POST /api/workspace/sandbox-run sends growthub-sandbox-run-v1 to this API Registry record (METHOD, baseUrl, endpoint, authRef resolved server-side). Use for Supabase Edge URL, QStash forwarder, Vercel-exposed webhook, cron targets, etc."
+      }
+    ]
+  },
   "custom": {
     label: "Custom",
     icon: "Plus",
@@ -510,6 +546,73 @@ function describeBindingLane(binding) {
   return "manual";
 }
 
+/**
+ * Saved env-key references — name-only projection of workspace integrations[].
+ *
+ * Used by the sandbox-environment drawer's env-ref multi-select. The browser
+ * receives the `endpointRef` slug only (never the secret value); the sandbox
+ * run route resolves the slug to a server-side env value using the same
+ * `envKeyCandidates(authRef)` pattern as `test-api-record/route.js`.
+ *
+ * Returns: [{ id, endpointRef, kind, hasSecret }]
+ */
+function listSavedEnvRefs(workspaceConfig) {
+  const integrations = Array.isArray(workspaceConfig?.integrations) ? workspaceConfig.integrations : [];
+  return integrations
+    .filter((entry) => entry?.sourceType === "custom-api-webhooks" && typeof entry.endpointRef === "string" && entry.endpointRef.trim())
+    .map((entry) => ({
+      id: entry.id || entry.endpointRef,
+      endpointRef: entry.endpointRef,
+      kind: entry.kind === "webhook" ? "webhook" : "api",
+      hasSecret: entry.hasSecret === true
+    }));
+}
+
+/**
+ * Parse a sandbox-environment row's `envRefs` column into a clean string array.
+ * Stored as a comma-separated string in the row to keep the column flat under
+ * the existing governed Data Model schema; rendered as a multi-select chip
+ * group in the drawer. The server reads the same comma-separated form.
+ */
+function parseSandboxEnvRefs(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+  if (typeof value !== "string") return [];
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Parse a sandbox-environment row's `allowList` column into a clean array of
+ * domain hostnames. Stored as comma-separated string for governed flatness;
+ * the run route enforces the list when `networkAllow` is truthy.
+ */
+function parseSandboxAllowList(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item || "").trim().toLowerCase()).filter(Boolean);
+  }
+  if (typeof value !== "string") return [];
+  return value
+    .split(",")
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+/**
+ * Stable sourceId for a sandbox-environment row's run history sidecar.
+ * Keyed by object id + slugified Name so the key survives reorder of rows
+ * inside the same object. The sandbox-run route uses this id to read/write
+ * `growthub.source-records.json`.
+ */
+function sandboxRunSourceId(objectId, name) {
+  const slug = String(name || "").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!objectId || !slug) return null;
+  return `sandbox:${objectId}:${slug}`;
+}
+
 function describeBindingMode(binding) {
   const lane = describeBindingLane(binding);
   if (lane === "data-source") return { label: "Data source scope", description: "Integration reference selected in the existing widget source flow. Dynamic data resolves through the governed server-side integration path." };
@@ -531,7 +634,11 @@ export {
   duplicateTableRow,
   exportTableAsCsv,
   importTableFromCsv,
+  listSavedEnvRefs,
   listWorkspaceDataModelTables,
+  parseSandboxAllowList,
+  parseSandboxEnvRefs,
   replaceTableContent,
+  sandboxRunSourceId,
   updateTableCell
 };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/workspace-schema.js

@@ -47,6 +47,35 @@ const KNOWN_FILTER_OPERATORS = ["eq", "ne", "contains", "gt", "lt", "isEmpty", "
 const KNOWN_FILTER_CONJUNCTIONS = ["and", "or"];
 const KNOWN_SORT_DIRECTIONS = ["asc", "desc"];
 const KNOWN_AGGREGATIONS = ["sum", "avg", "count", "min", "max"];
+const KNOWN_SANDBOX_RUNTIMES = ["python", "node", "bash"];
+/** Where execution is delegated: locally (process / agent-host CLI) or to a scheduler webhook (Supabase Edge, QStash, Vercel cron hitting your URL, etc.). */
+const KNOWN_SANDBOX_RUN_LOCALITY = ["local", "serverless"];
+const KNOWN_SANDBOX_LIFECYCLE_STATUSES = ["draft", "live"];
+const DEFAULT_SANDBOX_RUN_LOCALITY = "local";
+const DEFAULT_SANDBOX_ADAPTER = "local-process";
+const SANDBOX_DEFAULT_TIMEOUT_MS = 60000;
+const SANDBOX_MAX_TIMEOUT_MS = 600000;
+/**
+ * Canonical Paperclip local agent-host slugs — mirrors the upstream
+ * `AGENT_ADAPTER_TYPES` enum in `packages/shared/src/constants.ts`. The
+ * sandbox-environment row's `agentHost` column accepts any of these values
+ * when `adapter === "local-agent-host"`. The standalone workspace starter
+ * does NOT import the @paperclipai/adapter-* packages directly — instead the
+ * default `local-agent-host` adapter spawns the host CLI binary the user has
+ * on PATH (cross-platform: macOS / Windows / Linux), keeping the workspace
+ * starter portable and thin.
+ */
+const KNOWN_SANDBOX_AGENT_HOSTS = [
+  "claude_local",
+  "codex_local",
+  "cursor",
+  "gemini_local",
+  "opencode_local",
+  "pi_local",
+  "qwen_local",
+  "openclaw_gateway",
+  "hermes_local"
+];
 
 const NORMALIZED_OBJECT_FIELD_IDS = ["id", "label", "secondaryLabel", "entityType", "provider", "lane", "status"];
 const WORKSPACE_TEMPLATE_KIND = "growthub-workspace-template";
@@ -791,6 +820,65 @@ function validateCanvasConfig(canvas, errors) {
   }
 }
 
+function validateSandboxEnvironmentRow(row, path, errors) {
+  if (!isPlainObject(row)) return;
+  const lifecycleStatus = String(row.lifecycleStatus || "").trim().toLowerCase();
+  if (row.lifecycleStatus !== undefined && row.lifecycleStatus !== "" && !KNOWN_SANDBOX_LIFECYCLE_STATUSES.includes(lifecycleStatus)) {
+    errors.push(`${path}.lifecycleStatus must be one of ${KNOWN_SANDBOX_LIFECYCLE_STATUSES.join(", ")}`);
+  }
+  if (row.version !== undefined && typeof row.version !== "string" && typeof row.version !== "number") {
+    errors.push(`${path}.version must be a string or number`);
+  }
+  const runLocalityNorm = String(row.runLocality || "").trim().toLowerCase();
+  if (row.runLocality !== undefined && row.runLocality !== "" && !KNOWN_SANDBOX_RUN_LOCALITY.includes(runLocalityNorm)) {
+    errors.push(`${path}.runLocality must be one of ${KNOWN_SANDBOX_RUN_LOCALITY.join(", ")}`);
+  }
+  if (runLocalityNorm === "serverless") {
+    if (typeof row.schedulerRegistryId !== "string" || !row.schedulerRegistryId.trim()) {
+      errors.push(`${path}.schedulerRegistryId must reference an API Registry integrationId when runLocality is serverless`);
+    }
+  }
+  if (runLocalityNorm === "local" && row.runtime !== undefined && row.runtime !== "" && !KNOWN_SANDBOX_RUNTIMES.includes(row.runtime)) {
+    errors.push(`${path}.runtime must be one of ${KNOWN_SANDBOX_RUNTIMES.join(", ")}`);
+  }
+  if (row.adapter !== undefined && typeof row.adapter !== "string") {
+    errors.push(`${path}.adapter must be a string`);
+  }
+  if (row.agentHost !== undefined && row.agentHost !== "" && !KNOWN_SANDBOX_AGENT_HOSTS.includes(row.agentHost)) {
+    errors.push(`${path}.agentHost must be one of ${KNOWN_SANDBOX_AGENT_HOSTS.join(", ")}`);
+  }
+  if (row.envRefs !== undefined && typeof row.envRefs !== "string" && !Array.isArray(row.envRefs)) {
+    errors.push(`${path}.envRefs must be a comma-separated string or array of env-ref slugs (never values)`);
+  }
+  if (row.networkAllow !== undefined) {
+    const value = String(row.networkAllow).trim().toLowerCase();
+    if (!["", "true", "false", "0", "1", "on", "off"].includes(value)) {
+      errors.push(`${path}.networkAllow must coerce to a boolean (true/false/on/off)`);
+    }
+  }
+  if (row.allowList !== undefined && typeof row.allowList !== "string" && !Array.isArray(row.allowList)) {
+    errors.push(`${path}.allowList must be a comma-separated string or array of hostnames`);
+  }
+  if (row.instructions !== undefined && typeof row.instructions !== "string") {
+    errors.push(`${path}.instructions must be a string`);
+  }
+  if (row.command !== undefined && typeof row.command !== "string") {
+    errors.push(`${path}.command must be a string`);
+  }
+  if (row.lastRunId !== undefined && typeof row.lastRunId !== "string") {
+    errors.push(`${path}.lastRunId must be a string`);
+  }
+  if (row.lastSourceId !== undefined && typeof row.lastSourceId !== "string") {
+    errors.push(`${path}.lastSourceId must be a string`);
+  }
+  if (row.timeoutMs !== undefined && row.timeoutMs !== "") {
+    const ms = Number(row.timeoutMs);
+    if (!Number.isFinite(ms) || ms < 0 || ms > SANDBOX_MAX_TIMEOUT_MS) {
+      errors.push(`${path}.timeoutMs must be a finite number between 0 and ${SANDBOX_MAX_TIMEOUT_MS}`);
+    }
+  }
+}
+
 function validateDataModelConfig(dataModel, errors) {
   if (dataModel === undefined) return;
   if (!isPlainObject(dataModel)) {
@@ -824,7 +912,13 @@ function validateDataModelConfig(dataModel, errors) {
       errors.push(`${prefix}.rows must be an array`);
     } else {
       object.rows.forEach((row, rowIndex) => {
-        if (!isPlainObject(row)) errors.push(`${prefix}.rows[${rowIndex}] must be a plain object`);
+        if (!isPlainObject(row)) {
+          errors.push(`${prefix}.rows[${rowIndex}] must be a plain object`);
+          return;
+        }
+        if (object.objectType === "sandbox-environment") {
+          validateSandboxEnvironmentRow(row, `${prefix}.rows[${rowIndex}]`, errors);
+        }
       });
     }
     validateStaticDataBinding(object.binding, `${prefix}.binding`, errors);
@@ -1079,11 +1173,19 @@ export {
   KNOWN_AGGREGATIONS,
   KNOWN_CHART_TYPES,
   KNOWN_DATA_BINDING_MODES,
+  DEFAULT_SANDBOX_RUN_LOCALITY,
+  KNOWN_SANDBOX_LIFECYCLE_STATUSES,
   KNOWN_FIELDS,
   KNOWN_FILTER_CONJUNCTIONS,
   KNOWN_FILTER_OPERATORS,
+  KNOWN_SANDBOX_AGENT_HOSTS,
+  KNOWN_SANDBOX_RUN_LOCALITY,
+  KNOWN_SANDBOX_RUNTIMES,
   KNOWN_SORT_DIRECTIONS,
   KNOWN_WIDGET_KINDS,
+  DEFAULT_SANDBOX_ADAPTER,
+  SANDBOX_DEFAULT_TIMEOUT_MS,
+  SANDBOX_MAX_TIMEOUT_MS,
   NORMALIZED_OBJECT_FIELD_IDS,
   SAMPLE_DATA_BINDINGS,
   SAMPLE_VIEW_ROWS,

package/assets/worker-kits/growthub-custom-workspace-starter-v1/kit.json

@@ -61,6 +61,7 @@
     "studio/src/main.jsx",
     "studio/src/App.jsx",
     "studio/src/app.css",
+    "apps/workspace/docs/sandbox-environment-primitive.md",
     "apps/workspace/README.md",
     "apps/workspace/.env.example",
     "apps/workspace/package.json",
@@ -80,6 +81,8 @@
     "apps/workspace/app/api/workspace/test-source/route.js",
     "apps/workspace/app/api/workspace/register-resolver/route.js",
     "apps/workspace/app/api/workspace/resolvers/route.js",
+    "apps/workspace/app/api/workspace/sandbox-adapters/route.js",
+    "apps/workspace/app/api/workspace/sandbox-run/route.js",
     "apps/workspace/app/api/settings/integrations/route.js",
     "apps/workspace/lib/workspace-schema.js",
     "apps/workspace/lib/workspace-config.js",
@@ -92,6 +95,12 @@
     "apps/workspace/lib/adapters/integrations/source-resolver-registry.js",
     "apps/workspace/lib/adapters/integrations/resolver-loader.js",
     "apps/workspace/lib/adapters/integrations/resolvers/README.md",
+    "apps/workspace/lib/adapters/sandboxes/adapter-loader.js",
+    "apps/workspace/lib/adapters/sandboxes/adapters/README.md",
+    "apps/workspace/lib/adapters/sandboxes/default-local-agent-host.js",
+    "apps/workspace/lib/adapters/sandboxes/default-local-process.js",
+    "apps/workspace/lib/adapters/sandboxes/index.js",
+    "apps/workspace/lib/adapters/sandboxes/sandbox-adapter-registry.js",
     "apps/workspace/lib/adapters/payments/index.js",
     "apps/workspace/lib/adapters/persistence/index.js",
     "apps/workspace/lib/adapters/persistence/postgres.js",