@growthub/cli 0.13.9 → 0.14.1

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/orchestration-run-console.js

@@ -16,7 +16,12 @@
  *   - lib/orchestration-run-trace.js           (lower-level record parser)
  */
 
-import { redactSecretsFromText } from "./orchestration-graph.js";
+import {
+  extractSwarmNodes,
+  isAgentSwarmGraph,
+  parseOrchestrationGraph,
+  redactSecretsFromText
+} from "./orchestration-graph.js";
 import { redactRunInputsEnvelope, summarizeRunInputs } from "./orchestration-run-inputs.js";
 
 const RUN_LOG_BUNDLE_KIND = "growthub-sandbox-run-log-v1";
@@ -202,6 +207,388 @@ function buildExportsForRecord(record, stdoutText, stderrText, outputText) {
   return { available, external: [] };
 }
 
+/**
+ * Swarm cockpit projection (SWARM_RUN_CONTRACT_V1).
+ *
+ * Pure transformation of a sandbox run record carrying a `swarm` block
+ * (written by the agent-swarm-v1 runtime through sandbox-run) into the
+ * phase/agent tree the helper sidecar cockpit renders. Returns `null` for
+ * non-swarm records so existing runs are untouched.
+ *
+ * Telemetry is truthful: tokens/tools are null when the adapter did not
+ * report them — the UI renders "—", never an estimate. Totals are null when
+ * no agent reported a number.
+ *
+ * Same module rules as the rest of this file: no React, no fetch, no config
+ * writes, no localStorage, no CSS.
+ */
+// Truthful counts only: null/undefined (adapter reported nothing) stays
+// null — clampNumber would coerce null to 0, which would be a fake metric.
+function toTruthfulCount(value) {
+  if (value == null) return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+function toAdapterReportedCount(entry, field) {
+  const meta = entry?.adapterMeta && typeof entry.adapterMeta === "object" ? entry.adapterMeta : null;
+  if (meta?.telemetrySource === "unreported" && meta?.[field] == null) return null;
+  if (entry?.[field] === 0 && meta && meta[field] == null) return null;
+  if (entry?.[field] === 0 && !meta && safeString(entry?.adapter).trim() === "local-agent-host") return null;
+  return toTruthfulCount(entry?.[field]);
+}
+
+function parsePersistedAgentHostTelemetry(entry) {
+  const stderr = safeString(entry?.stderr);
+  const total = stderr.match(/\b(?:total\s+tokens|tokens\s+used)\s*(?:[:=]|\r?\n)\s*([0-9][0-9,]*)/i);
+  const input = stderr.match(/\b(?:input|prompt)\s+tokens\s*[:=]\s*([0-9][0-9,]*)/i);
+  const output = stderr.match(/\b(?:output|completion)\s+tokens\s*[:=]\s*([0-9][0-9,]*)/i);
+  const tools = stderr.match(/\b(?:tool\s+calls?|tools\s+used)\s*[:=]\s*([0-9][0-9,]*)/i);
+  const toInt = (value) => {
+    if (value == null || value === "") return null;
+    const n = Number(String(value).replace(/,/g, ""));
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+  };
+  const inputTokens = toInt(input?.[1]);
+  const outputTokens = toInt(output?.[1]);
+  const summed = inputTokens != null || outputTokens != null
+    ? (inputTokens || 0) + (outputTokens || 0)
+    : null;
+  const tokens = toInt(total?.[1]) ?? summed;
+  return {
+    tokens,
+    tools: toInt(tools?.[1]) ?? (tokens != null ? 0 : null)
+  };
+}
+
+function titleizePhaseId(id) {
+  const text = safeString(id).trim() || "dispatch";
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+function sumReportedOrNull(values) {
+  const reported = values.filter((n) => n != null);
+  return reported.length > 0 ? reported.reduce((sum, n) => sum + n, 0) : null;
+}
+
+function deriveSwarmRunProjection(record) {
+  if (!record || typeof record !== "object") return null;
+  const swarm = record.swarm;
+  if (!swarm || typeof swarm !== "object") return null;
+
+  const summary = deriveRunSummary(record);
+  const tasks = Array.isArray(swarm.tasks) ? swarm.tasks.filter((t) => t && typeof t === "object") : [];
+
+  // Agents projected from a persisted record are terminal: `pending: false`
+  // means a missing count is "ran but never reported" → the UI shows "—".
+  // (Pending agents — from the graph skeleton or a live stream — show blank.)
+  const toAgent = (entry, fallbackId, fallbackLabel, transcriptParts, logNodeId) => {
+    const persistedTelemetry = parsePersistedAgentHostTelemetry(entry);
+    const tokens = persistedTelemetry.tokens ?? toAdapterReportedCount(entry, "tokens");
+    const tools = persistedTelemetry.tools ?? toAdapterReportedCount(entry, "tools");
+    return {
+      id: safeString(entry?.taskId || entry?.nodeId || fallbackId).trim() || fallbackId,
+      label: safeString(entry?.role || entry?.label || fallbackLabel).trim() || fallbackLabel,
+      status: safeString(entry?.status || "unknown").trim() || "unknown",
+      pending: false,
+      tokens,
+      tools,
+      durationMs: clampNumber(entry?.durationMs) ?? 0,
+      transcript: redactSecretsFromText(
+        transcriptParts.map((part) => safeString(part).trim()).filter(Boolean).join("\n\n")
+      ),
+      logNodeId
+    };
+  };
+
+  const phases = [];
+  const orchestrator = swarm.orchestrator && typeof swarm.orchestrator === "object" ? swarm.orchestrator : null;
+  if (orchestrator) {
+    phases.push({
+      id: "plan",
+      label: "Plan",
+      status: safeString(orchestrator.status || "unknown").trim() || "unknown",
+      agents: [
+        toAgent(
+          orchestrator,
+          "orchestrator",
+          "Orchestrator",
+          [orchestrator.error, orchestrator.plan],
+          "phase-orchestrator"
+        )
+      ]
+    });
+  }
+
+  // Group dispatch tasks by their declared phase id (author-named phases),
+  // falling back to the single "Dispatch" group for legacy records whose
+  // tasks carry no phaseId — those project identically to before.
+  const dispatchGroups = new Map();
+  tasks.forEach((task, index) => {
+    const phaseId = safeString(task.phaseId).trim() || "dispatch";
+    if (!dispatchGroups.has(phaseId)) dispatchGroups.set(phaseId, []);
+    dispatchGroups.get(phaseId).push(
+      toAgent(
+        task,
+        `task-${index + 1}`,
+        `Agent ${index + 1}`,
+        [task.error, task.stdout, task.stderr],
+        safeString(task.taskId || task.nodeId || `task-${index + 1}`).trim()
+      )
+    );
+  });
+  if (dispatchGroups.size === 0) dispatchGroups.set("dispatch", []);
+  for (const [phaseId, agents] of dispatchGroups) {
+    const status = agents.length === 0
+      ? "failed"
+      : agents.every((a) => a.status === "completed")
+        ? "completed"
+        : agents.some((a) => a.status === "failed")
+          ? "failed"
+          : "info";
+    phases.push({ id: phaseId, label: titleizePhaseId(phaseId), status, agents });
+  }
+
+  const synthesis = swarm.synthesis && typeof swarm.synthesis === "object" ? swarm.synthesis : null;
+  if (synthesis) {
+    phases.push({
+      id: "synthesize",
+      label: "Synthesize",
+      status: safeString(synthesis.status || "unknown").trim() || "unknown",
+      agents: [
+        toAgent(
+          synthesis,
+          "synthesis",
+          synthesis.label || "Synthesizer",
+          [synthesis.error, synthesis.answer],
+          "phase-synthesis"
+        )
+      ]
+    });
+  }
+
+  const allAgents = phases.flatMap((phase) => phase.agents);
+
+  return {
+    runId: safeString(record.runId).trim(),
+    title: safeString(record.name || record.sandboxName).trim() || "agent-swarm",
+    status: summary.status,
+    elapsedMs: clampNumber(record.durationMs) ?? 0,
+    agentCount: allAgents.length,
+    totalTokens: sumReportedOrNull(allAgents.map((a) => a.tokens)),
+    totalTools: sumReportedOrNull(allAgents.map((a) => a.tools)),
+    phases
+  };
+}
+
+/**
+ * Declared-phase skeleton (SWARM_RUN_CONTRACT_V1, parity P1).
+ *
+ * Projects the SAME projection shape as deriveSwarmRunProjection from the
+ * governed row's agent-swarm-v1 graph alone — before any run exists. Every
+ * phase and agent renders upfront with `status: "pending"`, `pending: true`
+ * (UI shows hollow dots and BLANK cells, reserving "—" for terminal
+ * never-reported). Author-named phases come from each subagent node's
+ * `config.phase` / `config.phaseId`; graphs that declare none fall back to
+ * the Plan / Dispatch / Synthesize derivation, converging exactly with the
+ * record projection for the same workflow.
+ *
+ * Pure: no React, no fetch, no config writes, no localStorage, no CSS.
+ */
+function deriveSwarmGraphProjection(graphLike, { title = "", runId = "" } = {}) {
+  const graph = parseOrchestrationGraph(graphLike);
+  if (!graph || !isAgentSwarmGraph(graph)) return null;
+  const extracted = extractSwarmNodes(graph);
+  if (!extracted) return null;
+  const { orchestrator, subagents, synthesis } = extracted;
+
+  const pendingAgent = (id, label) => ({
+    id: safeString(id).trim() || "agent",
+    label: safeString(label).trim() || "Agent",
+    status: "pending",
+    pending: true,
+    tokens: null,
+    tools: null,
+    durationMs: 0,
+    transcript: "",
+    logNodeId: ""
+  });
+
+  const phases = [];
+  if (orchestrator) {
+    phases.push({
+      id: "plan",
+      label: "Plan",
+      status: "pending",
+      agents: [pendingAgent(orchestrator.id || "orchestrator", orchestrator.config?.role || "Orchestrator")]
+    });
+  }
+
+  const dispatchGroups = new Map();
+  subagents.forEach((node, index) => {
+    const phaseId = safeString(node?.config?.phase || node?.config?.phaseId).trim().toLowerCase() || "dispatch";
+    if (!dispatchGroups.has(phaseId)) dispatchGroups.set(phaseId, []);
+    dispatchGroups.get(phaseId).push(
+      pendingAgent(node?.id || `task-${index + 1}`, node?.config?.role || node?.label || `Agent ${index + 1}`)
+    );
+  });
+  if (dispatchGroups.size === 0) dispatchGroups.set("dispatch", []);
+  for (const [phaseId, agents] of dispatchGroups) {
+    phases.push({ id: phaseId, label: titleizePhaseId(phaseId), status: "pending", agents });
+  }
+
+  if (synthesis) {
+    phases.push({
+      id: "synthesize",
+      label: "Synthesize",
+      status: "pending",
+      agents: [pendingAgent(synthesis.id || "synthesis", synthesis.label || "Synthesizer")]
+    });
+  }
+
+  return {
+    runId: safeString(runId).trim(),
+    title: safeString(title).trim() || "agent-swarm",
+    status: "pending",
+    elapsedMs: 0,
+    agentCount: phases.reduce((sum, phase) => sum + phase.agents.length, 0),
+    totalTokens: null,
+    totalTools: null,
+    phases
+  };
+}
+
+function cloneSwarmProjection(projection) {
+  if (!projection || typeof projection !== "object") return null;
+  return {
+    ...projection,
+    phases: Array.isArray(projection.phases)
+      ? projection.phases.map((phase) => ({
+          ...phase,
+          agents: Array.isArray(phase.agents)
+            ? phase.agents.map((agent) => ({ ...agent }))
+            : []
+        }))
+      : []
+  };
+}
+
+function findOrCreateLivePhase(projection, phaseId, label) {
+  const id = safeString(phaseId).trim() || "dispatch";
+  let phase = projection.phases.find((entry) => entry.id === id);
+  if (!phase) {
+    phase = { id, label: safeString(label).trim() || titleizePhaseId(id), status: "pending", agents: [] };
+    projection.phases.push(phase);
+  }
+  return phase;
+}
+
+function upsertLiveAgent(phase, incoming) {
+  if (!phase) return;
+  const fallbackId = safeString(incoming?.taskId || incoming?.nodeId || incoming?.id).trim() || "agent";
+  const id = fallbackId;
+  const label = safeString(incoming?.role || incoming?.label).trim() || "Agent";
+  const index = phase.agents.findIndex((agent) => agent.id === id || agent.logNodeId === id);
+  const prior = index >= 0 ? phase.agents[index] : {};
+  const status = safeString(incoming?.status || prior.status || "running").trim() || "running";
+  const next = {
+    id,
+    label: label || prior.label || "Agent",
+    status,
+    pending: status === "pending" || status === "running" || status === "executing",
+    tokens: toTruthfulCount(incoming?.tokens ?? prior.tokens),
+    tools: toTruthfulCount(incoming?.tools ?? prior.tools),
+    durationMs: clampNumber(incoming?.durationMs) ?? prior.durationMs ?? 0,
+    transcript: prior.transcript || "",
+    logNodeId: safeString(incoming?.nodeId || prior.logNodeId || id).trim() || id
+  };
+  if (index >= 0) phase.agents[index] = next;
+  else phase.agents.push(next);
+}
+
+function derivePhaseStatusFromAgents(phase) {
+  const agents = Array.isArray(phase?.agents) ? phase.agents : [];
+  if (agents.some((agent) => agent.status === "running" || agent.status === "executing")) return "running";
+  if (agents.some((agent) => agent.status === "failed")) return "failed";
+  if (agents.length > 0 && agents.every((agent) => agent.status === "completed")) return "completed";
+  return phase?.status || "pending";
+}
+
+/**
+ * Live swarm delta projection.
+ *
+ * This consumes the optional NDJSON events from POST /api/workspace/sandbox-run
+ * and returns the exact same shape as persisted-record projection. The final
+ * source of truth remains deriveSwarmRunProjection(record); this only hydrates
+ * the cosmetic Background Tasks card while the POST is still open.
+ */
+function deriveSwarmDeltaProjection(graphLike, events, { title = "", runId = "", elapsedMs = 0 } = {}) {
+  const base = cloneSwarmProjection(deriveSwarmGraphProjection(graphLike, { title, runId }));
+  if (!base) return null;
+  const list = Array.isArray(events) ? events.filter((event) => event && typeof event === "object") : [];
+  let status = "running";
+  let latestRunId = safeString(runId).trim() || base.runId;
+
+  for (const event of list) {
+    if (event.runId) latestRunId = safeString(event.runId).trim() || latestRunId;
+    const type = safeString(event.type).trim();
+    if (type === "swarm.run.started") {
+      status = "running";
+      continue;
+    }
+    if (type === "swarm.run.completed" || type === "swarm.run.failed") {
+      status = safeString(event.status || (type.endsWith("completed") ? "completed" : "failed")).trim() || status;
+      continue;
+    }
+    if (type === "swarm.phase.started") {
+      const phase = findOrCreateLivePhase(base, event.phaseId, event.label);
+      phase.status = "running";
+      continue;
+    }
+    if (type === "swarm.phase.completed" || type === "swarm.phase.failed") {
+      const phase = findOrCreateLivePhase(base, event.phaseId, event.label);
+      phase.status = safeString(event.status || (type.endsWith("completed") ? "completed" : "failed")).trim() || phase.status;
+      if (event.agent && typeof event.agent === "object") upsertLiveAgent(phase, event.agent);
+      continue;
+    }
+    if (type === "swarm.task.started") {
+      const phase = findOrCreateLivePhase(base, event.phaseId, titleizePhaseId(event.phaseId));
+      phase.status = "running";
+      upsertLiveAgent(phase, {
+        taskId: event.taskId,
+        nodeId: event.nodeId,
+        role: event.role,
+        status: "running",
+        phaseId: event.phaseId
+      });
+      continue;
+    }
+    if (type === "swarm.task.completed" || type === "swarm.task.failed") {
+      const task = event.task && typeof event.task === "object" ? event.task : event;
+      const phase = findOrCreateLivePhase(base, task.phaseId || event.phaseId, titleizePhaseId(task.phaseId || event.phaseId));
+      upsertLiveAgent(phase, task);
+      phase.status = derivePhaseStatusFromAgents(phase);
+    }
+  }
+
+  for (const phase of base.phases) {
+    if (phase.status === "running") continue;
+    phase.status = derivePhaseStatusFromAgents(phase);
+  }
+
+  const allAgents = base.phases.flatMap((phase) => phase.agents);
+  return {
+    ...base,
+    runId: latestRunId,
+    status,
+    elapsedMs: clampNumber(elapsedMs) ?? base.elapsedMs ?? 0,
+    agentCount: allAgents.length,
+    totalTokens: sumReportedOrNull(allAgents.map((agent) => agent.tokens)),
+    totalTools: sumReportedOrNull(allAgents.map((agent) => agent.tools)),
+    phases: base.phases
+  };
+}
+
 function normalizeRunConsoleRecord(record) {
   if (!record || typeof record !== "object") return null;
   const summary = deriveRunSummary(record);
@@ -303,6 +690,7 @@ function normalizeRunConsoleRecord(record) {
     },
     lineage,
     swarm: record.swarm && typeof record.swarm === "object" ? record.swarm : null,
+    swarmRun: deriveSwarmRunProjection(record),
     logTree: buildRunLogTree(record)
   };
 }
@@ -387,6 +775,24 @@ function formatRunDuration(ms) {
   return `${minutes}m ${seconds}s`;
 }
 
+/**
+ * Compact zero-padded duration for the swarm cockpit tables and cards —
+ * Claude Code Background-tasks format: "04s", "15s", "1m 04s". A separate
+ * formatter (not a change to formatRunDuration) so existing non-swarm
+ * run-console surfaces keep their ms-precision rendering untouched.
+ */
+function formatCompactRunDuration(ms) {
+  if (ms == null) return "—";
+  const n = clampNumber(ms);
+  if (n == null) return "—";
+  const totalSeconds = Math.max(0, Math.round(n / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const padded = String(seconds).padStart(2, "0");
+  if (minutes <= 0) return `${padded}s`;
+  return `${minutes}m ${padded}s`;
+}
+
 function downloadRunBundle({ record, runId, sourceId } = {}) {
   const normalized = normalizeRunConsoleRecord(record || {});
   return {
@@ -403,6 +809,10 @@ export {
   DEFAULT_EXPORT_TARGETS,
   normalizeRunConsoleRecord,
   deriveRunSummary,
+  deriveSwarmRunProjection,
+  deriveSwarmGraphProjection,
+  deriveSwarmDeltaProjection,
+  formatCompactRunDuration,
   deriveRunLifecycle,
   buildRunLogTree,
   buildRunTimeline,

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/sandbox-serverless-flow.js

@@ -0,0 +1,215 @@
+/**
+ * Sandbox Serverless Flow V1 — the governed persistence + scheduling journey for
+ * one sandbox-environment workflow row, expressed in the EXACT same step shape
+ * as the API Registry creation cockpit (lib/api-registry-creation-flow.js) so it
+ * renders through the same cockpit interface and mental model.
+ *
+ * It connects the dots that already exist:
+ *   - runLocality local|serverless toggle (sandbox row)
+ *   - execution adapter (sandbox-adapter-registry)
+ *   - schedulerRegistryId reference field → an API Registry row that delegates
+ *     the serverless run (sandbox-run's registry-delegation mode)
+ *   - the scheduler row's authRef → resolved via env-status configuredEnvRefs
+ *   - durable persistence via the real thin adapters (postgres / qstash-kv /
+ *     provider-managed) surfaced by env-status persistenceAdapters
+ *
+ * Pure + deterministic; never reads process.env, never throws. Secret-safe
+ * (slugs/ids/booleans only).
+ */
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** Exact env keys a ref resolves through (runtime/.env.local), surfaced so the
+ *  config loop is concrete — same model as the NANGO_SECRET_KEY activation step. */
+function envCandidates(ref) {
+  const token = clean(ref).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+  if (!token) return [];
+  return Array.from(new Set([token, `${token}_API_KEY`, `${token}_TOKEN`]));
+}
+
+const SCHEDULER_OK_STATUSES = new Set(["connected", "approved", "ok", "success", "live", "tested"]);
+const STATE_KIND = "growthub-sandbox-serverless-state-v1";
+
+function findApiRegistryRow(workspaceConfig, integrationId) {
+  const id = clean(integrationId);
+  if (!id) return null;
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  for (const object of objects) {
+    if (object?.objectType !== "api-registry") continue;
+    const match = (object.rows || []).find((r) => clean(r?.integrationId) === id);
+    if (match) return match;
+  }
+  return null;
+}
+
+/**
+ * Derive the serverless/scheduling/persistence journey for a sandbox row.
+ *
+ * @param {object} input
+ * @param {object} input.sandboxRow          the row being edited (drawer draft)
+ * @param {object} [input.workspaceConfig]   for scheduler row lookup
+ * @param {string[]} [input.configuredEnvRefs] auth/env slugs that resolve (env-status)
+ * @param {object[]} [input.persistenceAdapters] [{id,label,mode,configured,missingEnv}]
+ */
+function deriveSandboxServerlessState(input = {}) {
+  const row = isPlainObject(input.sandboxRow) ? input.sandboxRow : {};
+  const workspaceConfig = isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {};
+  const configuredRefs = new Set((Array.isArray(input.configuredEnvRefs) ? input.configuredEnvRefs : []).map((s) => clean(s).toUpperCase()));
+  const adapters = Array.isArray(input.persistenceAdapters) ? input.persistenceAdapters : [];
+  // When the cockpit is rendered above the drawer's own editable fields
+  // (locality toggle, adapter picker, scheduler reference dropdown), those steps
+  // show status only — the inline field is the editor (no duplicate button).
+  const inlineEditing = input.inlineEditing === true;
+  const inline = (action) => (inlineEditing ? null : action);
+
+  const locality = clean(row.runLocality).toLowerCase() === "serverless" ? "serverless" : "local";
+  const isServerless = locality === "serverless";
+  const adapterId = clean(row.adapter);
+  const adapterChosen = Boolean(adapterId);
+
+  const schedulerId = clean(row.schedulerRegistryId);
+  const schedulerRow = isServerless ? findApiRegistryRow(workspaceConfig, schedulerId) : null;
+  const schedulerLinked = isServerless ? Boolean(schedulerId) : true;
+  const schedulerHealthy = Boolean(schedulerRow) && SCHEDULER_OK_STATUSES.has(clean(schedulerRow.status).toLowerCase());
+  const schedulerAuthRef = clean(schedulerRow?.authRef).toUpperCase();
+  const schedulerAuthConfigured = !schedulerAuthRef || configuredRefs.has(schedulerAuthRef);
+
+  // Durable persistence: any real adapter that is env-ready. provider-managed is
+  // always "ready" (the deploy provider owns persistence). qstash-kv/postgres
+  // require their env keys — surfaced honestly with the missing keys.
+  const durableAdapters = adapters.filter((a) => a && a.configured);
+  const durableReady = durableAdapters.length > 0;
+  const envBackedAdapter = durableAdapters.find((a) => Array.isArray(a.requiredEnv) && a.requiredEnv.length > 0) || durableAdapters[0] || null;
+
+  const steps = [];
+
+  steps.push({
+    id: "locality",
+    label: "Choose run locality",
+    status: isServerless ? "complete" : "active",
+    description: isServerless
+      ? "Serverless — runs are delegated to a scheduler and persist across redeploy."
+      : "Local — runs execute in-process on this machine.",
+    action: inline({ id: "toggle-locality", label: isServerless ? "Switch to local" : "Switch to serverless" }),
+  });
+
+  steps.push({
+    id: "adapter",
+    label: "Pick an execution adapter",
+    status: adapterChosen ? "complete" : "active",
+    description: adapterChosen
+      ? `Adapter "${adapterId}".`
+      : "Select the execution adapter for this workflow.",
+    action: adapterChosen ? null : inline({ id: "edit-adapter", label: "Choose adapter" }),
+  });
+
+  if (isServerless) {
+    steps.push({
+      id: "scheduler",
+      label: "Link a scheduler",
+      status: schedulerLinked ? (schedulerHealthy ? "complete" : "pending") : "active",
+      description: !schedulerLinked
+        ? "Set schedulerRegistryId to an API Registry row that delegates the serverless run."
+        : schedulerHealthy
+          ? `Scheduler "${schedulerId}" is connected.`
+          : `Scheduler "${schedulerId}" is linked but not connected yet — test that API Registry row.`,
+      hint: schedulerLinked && !schedulerRow ? "The referenced API Registry row was not found." : undefined,
+      action: inline({ id: "link-scheduler", label: schedulerLinked ? "Review scheduler" : "Link scheduler" }),
+    });
+
+    steps.push({
+      id: "scheduler-auth",
+      label: "Scheduler auth resolves",
+      status: !schedulerAuthRef
+        ? "complete"
+        : schedulerAuthConfigured
+          ? "complete"
+          : (schedulerLinked ? "pending" : "blocked"),
+      description: !schedulerAuthRef
+        ? "The scheduler needs no secret."
+        : schedulerAuthConfigured
+          ? `Scheduler secret ${schedulerAuthRef} resolves in this runtime.`
+          : `Set one of ${envCandidates(schedulerAuthRef).join(" / ")} in .env.local (or your hosted runtime), then reopen.`,
+      action: schedulerAuthRef && !schedulerAuthConfigured ? { id: "open-settings", label: "Manage in Settings", href: "/settings/apis-webhooks" } : null,
+    });
+
+    steps.push({
+      id: "persistence",
+      label: "Enable durable persistence",
+      status: durableReady ? "complete" : "active",
+      description: durableReady
+        ? `Durable store ready (${(envBackedAdapter || durableAdapters[0]).label}).`
+        : "Set a durable store's env keys in .env.local (or your hosted runtime) so serverless runs survive redeploy.",
+      // Fully surface every thin adapter + its exact env keys + readiness, so no
+      // adapter is assumed server-side without being shown to the operator.
+      hint: durableReady
+        ? undefined
+        : adapters.length
+          ? adapters.map((a) => `${a.label}: ${(a.requiredEnv || []).length ? a.requiredEnv.join(", ") : "no env"}${a.configured ? " ✓" : ""}`).join(" · ")
+          : "No persistence adapter signal yet — open env-status.",
+      action: durableReady ? null : { id: "open-settings", label: "Manage in Settings", href: "/settings" },
+    });
+  }
+
+  steps.push({
+    id: "run",
+    label: isServerless ? "Run on the scheduler" : "Run locally",
+    status: "optional",
+    description: isServerless
+      ? "Once the scheduler, auth, and store are ready, run delegates to the serverless scheduler."
+      : "Run this workflow in-process.",
+    action: inline({ id: "run-sandbox", label: "Run" }),
+  });
+
+  for (const s of steps) { if (!s.hint) delete s.hint; }
+
+  const required = steps.filter((s) => s.status !== "optional");
+  const completedCount = required.filter((s) => s.status === "complete").length;
+  const totalCount = required.length;
+  const complete = completedCount >= totalCount;
+  const nextStep = steps.find((s) => s.status === "active")
+    || steps.find((s) => s.status === "pending")
+    || steps.find((s) => s.status === "blocked")
+    || null;
+
+  // Milestone score tied to evidence.
+  let score = isServerless ? 10 : 40;
+  if (adapterChosen) score = Math.max(score, isServerless ? 25 : 70);
+  if (isServerless && schedulerLinked) score = Math.max(score, 45);
+  if (isServerless && schedulerHealthy) score = Math.max(score, 60);
+  if (isServerless && schedulerAuthConfigured && schedulerLinked) score = Math.max(score, 75);
+  if (isServerless && durableReady) score = Math.max(score, 90);
+  if (complete) score = 100;
+
+  return {
+    kind: STATE_KIND,
+    version: 1,
+    locality,
+    isServerless,
+    adapterChosen,
+    schedulerLinked,
+    schedulerHealthy,
+    schedulerAuthConfigured,
+    durableReady,
+    completedCount,
+    totalCount,
+    complete,
+    score,
+    nextStepId: nextStep ? nextStep.id : null,
+    nextAction: nextStep && nextStep.action ? { stepId: nextStep.id, ...nextStep.action } : null,
+    headline: !isServerless
+      ? "This workflow runs locally."
+      : complete
+        ? "This workflow is scheduled and durable."
+        : "Make this workflow persistent and scheduled.",
+    steps,
+  };
+}
+
+export { STATE_KIND, deriveSandboxServerlessState };