@growthub/cli 0.13.9 → 0.14.1

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

@@ -0,0 +1,100 @@
+/**
+ * Env Status V1 — the honest, secret-safe "which referenced env keys actually
+ * resolve right now" signal.
+ *
+ * The creation cockpit (api-registry drawer) cannot read process.env in the
+ * browser, so auth readiness must come from a server signal. This module is the
+ * pure core of `GET /api/workspace/env-status`: given the governed config and
+ * the runtime environment it returns the set of *referenced* auth/env ref slugs
+ * whose candidate keys resolve to a value — slugs only, never a value.
+ *
+ * Pure + env-injectable so it is deterministically testable.
+ */
+
+import { describePostgresAdapter } from "./adapters/persistence/postgres.js";
+import { describeQstashKvAdapter } from "./adapters/persistence/qstash-kv.js";
+import { describeProviderManagedAdapter } from "./adapters/persistence/provider-managed.js";
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** Canonical UPPER_SNAKE candidate expansion for a logical ref. */
+function envKeyCandidates(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`]));
+}
+
+/**
+ * Collect every auth/env ref slug referenced by the governed config:
+ *   - api-registry rows: authRef
+ *   - data-source rows:  authRef
+ *   - sandbox-environment rows: envRefs (comma-separated)
+ * Returns the original ref strings (deduped), preserving the operator's casing
+ * so the cockpit can match them against a registry row's authRef.
+ */
+function collectReferencedRefs(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const refs = new Set();
+  for (const object of objects) {
+    const rows = Array.isArray(object?.rows) ? object.rows : [];
+    if (object?.objectType === "api-registry" || object?.objectType === "data-source") {
+      for (const row of rows) {
+        const ref = clean(row?.authRef);
+        if (ref) refs.add(ref);
+      }
+    }
+    if (object?.objectType === "sandbox-environment") {
+      for (const row of rows) {
+        for (const part of clean(row?.envRefs).split(",")) {
+          const ref = clean(part);
+          if (ref) refs.add(ref);
+        }
+      }
+    }
+  }
+  return Array.from(refs);
+}
+
+/**
+ * Return the referenced refs whose candidate keys resolve in `env`.
+ * `env` is injectable (defaults to process.env). Never returns a value.
+ */
+function computeConfiguredEnvRefs(workspaceConfig, env = process.env) {
+  const source = env && typeof env === "object" ? env : {};
+  const resolves = (ref) => envKeyCandidates(ref).some((key) => Boolean(source[key]));
+  return collectReferencedRefs(workspaceConfig).filter(resolves);
+}
+
+/**
+ * Persistence/serverless adapter env-readiness — single-sourced from the real
+ * thin-adapter descriptors (postgres / qstash-kv / provider-managed). These are
+ * the durable-runtime layers a serverless workflow needs; the cockpit surfaces
+ * exactly which are env-ready so "make this workflow persistent + scheduled"
+ * has an honest, actionable signal. Slugs/booleans only — never a value.
+ */
+function listPersistenceAdapterReadiness(env = process.env) {
+  const source = env && typeof env === "object" ? env : {};
+  const descriptors = [describePostgresAdapter(), describeQstashKvAdapter(), describeProviderManagedAdapter()];
+  return descriptors.map((d) => {
+    const requiredEnv = Array.isArray(d.requiredEnv) ? d.requiredEnv : [];
+    const missingEnv = requiredEnv.filter((k) => !source[k]);
+    return {
+      id: d.id,
+      label: d.label,
+      mode: d.mode,
+      requiredEnv,
+      // provider-managed needs no env (the deploy provider owns persistence).
+      configured: requiredEnv.length === 0 ? true : missingEnv.length === 0,
+      missingEnv,
+    };
+  });
+}
+
+export {
+  envKeyCandidates,
+  collectReferencedRefs,
+  computeConfiguredEnvRefs,
+  listPersistenceAdapterReadiness,
+};

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

@@ -63,6 +63,44 @@ const MAX_SUBAGENT_OUTPUT_FOR_SYNTH = 4096;
 const PROMPT_CAPABLE_ADAPTERS = new Set(["local-agent-host", "local-intelligence"]);
 const OUTCOME_SCORE_RE = /OUTCOME_SCORE\s*[:=]\s*([01](?:\.\d+)?|\.\d+)/i;
 
+function cleanEventString(value) {
+  return redactSecretsFromText(String(value ?? "").trim());
+}
+
+function emitSwarmDelta(executionContext, payload) {
+  const emit = executionContext?.onEvent;
+  if (typeof emit !== "function") return;
+  try {
+    emit({
+      kind: "growthub-sandbox-run-delta-v1",
+      emittedAt: new Date().toISOString(),
+      runId: executionContext.runId || "",
+      ...payload
+    });
+  } catch {
+    // Observability is best-effort; execution must not fail because the
+    // browser disconnected or a cosmetic stream consumer rejected an event.
+  }
+}
+
+function taskDeltaFromResult(task) {
+  return {
+    taskId: cleanEventString(task?.taskId || task?.nodeId || ""),
+    nodeId: cleanEventString(task?.nodeId || task?.taskId || ""),
+    role: cleanEventString(task?.role || "Subagent"),
+    phaseId: cleanEventString(task?.phaseId || "dispatch") || "dispatch",
+    status: cleanEventString(task?.status || "unknown") || "unknown",
+    adapter: cleanEventString(task?.adapter || ""),
+    agentHost: cleanEventString(task?.agentHost || ""),
+    durationMs: Number.isFinite(Number(task?.durationMs)) ? Number(task.durationMs) : 0,
+    tokens: task?.tokens ?? null,
+    tools: task?.tools ?? null,
+    startedAt: cleanEventString(task?.startedAt || ""),
+    endedAt: cleanEventString(task?.endedAt || ""),
+    error: cleanEventString(task?.error || "")
+  };
+}
+
 function clampPositiveInt(value, fallback) {
   const n = Number(value);
   if (!Number.isFinite(n) || n <= 0) return fallback;
@@ -114,6 +152,21 @@ function chooseAdapterIdForSubagent({ subagentConfig, fallbackAdapterId, fallbac
   };
 }
 
+/**
+ * Truthful telemetry extraction (SWARM_RUN_CONTRACT_V1). Tokens / tool counts
+ * come ONLY from the adapter's reported metadata — when the adapter does not
+ * report a number the value is null, never an estimate.
+ */
+function extractAdapterTelemetry(result) {
+  const meta = result?.adapterMeta && typeof result.adapterMeta === "object" ? result.adapterMeta : {};
+  const tokens = meta.tokens == null || meta.tokens === "" ? null : Number(meta.tokens);
+  const tools = meta.tools == null || meta.tools === "" ? null : Number(meta.tools);
+  return {
+    tokens: Number.isFinite(tokens) && tokens >= 0 ? tokens : null,
+    tools: Number.isFinite(tools) && tools >= 0 ? tools : null
+  };
+}
+
 function describeSubagent(node) {
   const cfg = node?.config || {};
   const role = String(cfg.role || node?.label || node?.id || "subagent").trim();
@@ -240,7 +293,8 @@ async function runThroughAdapter({
   envRefsMissing,
   runId,
   name,
-  ranAt
+  ranAt,
+  intelligence
 }) {
   const adapter = getSandboxAdapter(adapterId);
   if (!adapter) {
@@ -281,7 +335,20 @@ async function runThroughAdapter({
       envRefSlugs,
       envRefsMissing,
       workdir,
-      ranAt: ranAt || new Date(startedAt).toISOString()
+      ranAt: ranAt || new Date(startedAt).toISOString(),
+      // local-intelligence speaks the intelligenceSandbox envelope — the
+      // phase prompt travels as userIntent; model/endpoint settings come
+      // from the governed row (slugs/URLs only, never secret values).
+      ...(adapterId === "local-intelligence"
+        ? {
+            intelligenceSandbox: {
+              userIntent: command,
+              localModel: String(intelligence?.localModel || "").trim(),
+              localEndpoint: String(intelligence?.localEndpoint || "").trim(),
+              intelligenceAdapterMode: String(intelligence?.intelligenceAdapterMode || "ollama").trim() || "ollama"
+            }
+          }
+        : {})
     });
   } catch (error) {
     return {
@@ -324,6 +391,7 @@ async function runOrchestratorPhase({ orchestratorNode, subagents, inputPayload,
   const command = buildOrchestratorCommand({ orchestratorNode, subagents, inputPayload });
   const env = { ...(executionContext.env || {}), GROWTHUB_SWARM_PHASE: "orchestrator" };
   const startedAt = Date.now();
+  const startedAtIso = new Date(startedAt).toISOString();
   const result = await runThroughAdapter({
     adapterId: resolved.adapterId,
     agentHost: resolved.agentHost,
@@ -335,11 +403,13 @@ async function runOrchestratorPhase({ orchestratorNode, subagents, inputPayload,
     env,
     envRefSlugs: executionContext.envRefSlugs || [],
     envRefsMissing: executionContext.envRefsMissing || [],
+    intelligence: executionContext.intelligence,
     runId: `${executionContext.runId}_orchestrator`,
     name: `${executionContext.sandboxName || "swarm"}::orchestrator`
   });
   const stdout = redactSecretsFromText(result?.stdout || "");
   const errorText = redactSecretsFromText(result?.error || "");
+  const telemetry = extractAdapterTelemetry(result);
   return {
     status: result?.ok === true && !errorText ? "completed" : "failed",
     error: errorText,
@@ -349,6 +419,11 @@ async function runOrchestratorPhase({ orchestratorNode, subagents, inputPayload,
     output: stdout,
     stderr: redactSecretsFromText(result?.stderr || ""),
     plan: stdout,
+    tokens: telemetry.tokens,
+    tools: telemetry.tools,
+    startedAt: startedAtIso,
+    endedAt: new Date().toISOString(),
+    phaseId: "plan",
     adapterMeta: { ...(result?.adapterMeta || {}), swarmPhase: "orchestrator" }
   };
 }
@@ -364,6 +439,10 @@ async function dispatchSubagentTask({
   const required = subagentConfig.required !== false;
   const taskId = subagentNode?.id || `task-${taskIndex + 1}`;
   const role = String(subagentConfig.role || subagentNode?.label || "subagent");
+  // Author-named phase (config.phase / config.phaseId) travels onto the task
+  // so the record projection groups under the same phases the declared
+  // skeleton shows. Absent → "dispatch", exactly as before.
+  const phaseId = String(subagentConfig.phase || subagentConfig.phaseId || "").trim().toLowerCase() || "dispatch";
 
   const resolved = chooseAdapterIdForSubagent({
     subagentConfig,
@@ -371,6 +450,7 @@ async function dispatchSubagentTask({
     fallbackAgentHost: executionContext.agentHost
   });
   if (!resolved.adapterId || resolved.error) {
+    const gateAt = new Date().toISOString();
     return {
       taskId,
       nodeId: taskId,
@@ -383,6 +463,11 @@ async function dispatchSubagentTask({
       stdout: "",
       stderr: "",
       error: resolved.error || "no prompt-capable adapter resolved for subagent",
+      tokens: null,
+      tools: null,
+      startedAt: gateAt,
+      endedAt: gateAt,
+      phaseId,
       adapterMeta: { swarmSubagent: true, reason: "adapter-gate" }
     };
   }
@@ -407,11 +492,13 @@ async function dispatchSubagentTask({
     env,
     envRefSlugs: executionContext.envRefSlugs || [],
     envRefsMissing: executionContext.envRefsMissing || [],
+    intelligence: executionContext.intelligence,
     runId: `${executionContext.runId}_${taskId}`,
     name: `${executionContext.sandboxName || "swarm"}::${taskId}`
   });
   const errorText = redactSecretsFromText(result?.error || "");
   const ok = result?.ok === true && !errorText;
+  const telemetry = extractAdapterTelemetry(result);
   return {
     taskId,
     nodeId: taskId,
@@ -425,6 +512,11 @@ async function dispatchSubagentTask({
     stdout: redactSecretsFromText(result?.stdout || ""),
     stderr: redactSecretsFromText(result?.stderr || ""),
     error: errorText,
+    tokens: telemetry.tokens,
+    tools: telemetry.tools,
+    startedAt: new Date(startedAt).toISOString(),
+    endedAt: new Date().toISOString(),
+    phaseId,
     adapterMeta: { ...(result?.adapterMeta || {}), swarmSubagent: true }
   };
 }
@@ -467,6 +559,7 @@ async function runSynthesisPhase({ synthesisNode, swarmConfig, tasks, inputPaylo
   const command = buildSynthesisCommand({ synthesisNode, swarmConfig, tasks, inputPayload });
   const env = { ...(executionContext.env || {}), GROWTHUB_SWARM_PHASE: "synthesis" };
   const startedAt = Date.now();
+  const startedAtIso = new Date(startedAt).toISOString();
   const result = await runThroughAdapter({
     adapterId: resolved.adapterId,
     agentHost: resolved.agentHost,
@@ -478,6 +571,7 @@ async function runSynthesisPhase({ synthesisNode, swarmConfig, tasks, inputPaylo
     env,
     envRefSlugs: executionContext.envRefSlugs || [],
     envRefsMissing: executionContext.envRefsMissing || [],
+    intelligence: executionContext.intelligence,
     runId: `${executionContext.runId}_synthesis`,
     name: `${executionContext.sandboxName || "swarm"}::synthesis`
   });
@@ -485,6 +579,7 @@ async function runSynthesisPhase({ synthesisNode, swarmConfig, tasks, inputPaylo
   const errorText = redactSecretsFromText(result?.error || "");
   const match = stdout.match(OUTCOME_SCORE_RE);
   const parsedOutcomeScore = match ? clamp01(match[1]) : null;
+  const telemetry = extractAdapterTelemetry(result);
   return {
     status: result?.ok === true && !errorText ? "completed" : "failed",
     ranSynthesis: true,
@@ -495,6 +590,11 @@ async function runSynthesisPhase({ synthesisNode, swarmConfig, tasks, inputPaylo
     adapter: resolved.adapterId,
     agentHost: resolved.agentHost || "",
     parsedOutcomeScore,
+    tokens: telemetry.tokens,
+    tools: telemetry.tools,
+    startedAt: startedAtIso,
+    endedAt: new Date().toISOString(),
+    phaseId: "synthesize",
     adapterMeta: { ...(result?.adapterMeta || {}), swarmPhase: "synthesis" }
   };
 }
@@ -723,18 +823,63 @@ async function runAgentSwarmGraphIfPresent({
     networkAllow: executionContext?.networkAllow === true,
     allowList: executionContext?.allowList || [],
     timeoutMs: clampPositiveInt(timeoutMs, DEFAULT_SUBAGENT_TIMEOUT_MS),
-    sandboxName: executionContext?.sandboxName || row?.Name || "swarm"
+    sandboxName: executionContext?.sandboxName || row?.Name || "swarm",
+    onEvent: executionContext?.onEvent,
+    // Row-configured local-intelligence settings (model id, endpoint URL,
+    // adapter mode) — configuration only, never secret values.
+    intelligence: {
+      localModel: String(row?.localModel || "").trim(),
+      localEndpoint: String(row?.localEndpoint || "").trim(),
+      intelligenceAdapterMode: String(row?.intelligenceAdapterMode || "").trim() || "ollama"
+    }
   };
 
   const startedAt = Date.now();
+  emitSwarmDelta(ctx, {
+    type: "swarm.run.started",
+    status: "running",
+    name: cleanEventString(ctx.sandboxName),
+    adapter: cleanEventString(ctx.adapterId),
+    agentHost: cleanEventString(ctx.agentHost),
+    maxConcurrency,
+    phaseCount: 3,
+    taskCount: subagents.length
+  });
 
   // Phase 1: Plan ----------------------------------------------------------
+  emitSwarmDelta(ctx, {
+    type: "swarm.phase.started",
+    phaseId: "plan",
+    label: "Plan",
+    status: "running"
+  });
   const orchestratorResult = await runOrchestratorPhase({
     orchestratorNode: orchestrator,
     subagents,
     inputPayload: manualPayload,
     executionContext: ctx
   });
+  emitSwarmDelta(ctx, {
+    type: orchestratorResult.status === "failed" ? "swarm.phase.failed" : "swarm.phase.completed",
+    phaseId: "plan",
+    label: "Plan",
+    status: orchestratorResult.status,
+    agent: {
+      taskId: cleanEventString(orchestrator.id || "orchestrator"),
+      nodeId: cleanEventString(orchestrator.id || "orchestrator"),
+      role: cleanEventString(orchestrator?.config?.role || "Orchestrator"),
+      phaseId: "plan",
+      status: orchestratorResult.status,
+      adapter: cleanEventString(orchestratorResult.adapter || ""),
+      agentHost: cleanEventString(orchestratorResult.agentHost || ""),
+      durationMs: Number(orchestratorResult.durationMs) || 0,
+      tokens: orchestratorResult.tokens ?? null,
+      tools: orchestratorResult.tools ?? null,
+      startedAt: cleanEventString(orchestratorResult.startedAt || ""),
+      endedAt: cleanEventString(orchestratorResult.endedAt || ""),
+      error: cleanEventString(orchestratorResult.error || "")
+    }
+  });
 
   if (orchestratorResult.status === "failed" && String(orchestratorResult.error || "").length > 0) {
     const durationMs = Date.now() - startedAt;
@@ -747,6 +892,13 @@ async function runAgentSwarmGraphIfPresent({
       outcomeOk: false,
       synthesisResult: null
     });
+    emitSwarmDelta(ctx, {
+      type: "swarm.run.failed",
+      status: "failed",
+      phaseFailed: "plan",
+      durationMs,
+      error: cleanEventString(orchestratorResult.error || "")
+    });
     return {
       ok: false,
       exitCode: 1,
@@ -790,23 +942,68 @@ async function runAgentSwarmGraphIfPresent({
   // Phase 2: Dispatch ------------------------------------------------------
   let observedParallelism = 0;
   let activeNow = 0;
+  emitSwarmDelta(ctx, {
+    type: "swarm.phase.started",
+    phaseId: "dispatch",
+    label: "Dispatch",
+    status: "running",
+    taskCount: subagents.length
+  });
   const tasks = await runSubagentsWithConcurrency(subagents, maxConcurrency, async (subagentNode, index) => {
     activeNow += 1;
     if (activeNow > observedParallelism) observedParallelism = activeNow;
+    const subagentConfig = subagentNode?.config || {};
+    const taskId = subagentNode?.id || `task-${index + 1}`;
+    const phaseId = String(subagentConfig.phase || subagentConfig.phaseId || "").trim().toLowerCase() || "dispatch";
+    emitSwarmDelta(ctx, {
+      type: "swarm.task.started",
+      phaseId,
+      taskId: cleanEventString(taskId),
+      nodeId: cleanEventString(taskId),
+      role: cleanEventString(subagentConfig.role || subagentNode?.label || `Agent ${index + 1}`),
+      status: "running",
+      active: activeNow,
+      observedParallelism
+    });
     try {
-      return await dispatchSubagentTask({
+      const task = await dispatchSubagentTask({
         subagentNode,
         orchestratorPlan: orchestratorResult.plan,
         inputPayload: manualPayload,
         executionContext: ctx,
         taskIndex: index
       });
+      emitSwarmDelta(ctx, {
+        type: task.status === "completed" ? "swarm.task.completed" : "swarm.task.failed",
+        phaseId: task.phaseId || phaseId,
+        task: taskDeltaFromResult(task)
+      });
+      return task;
     } finally {
       activeNow -= 1;
     }
   });
+  const dispatchStatus = tasks.length > 0 && tasks.every((t) => t.status === "completed")
+    ? "completed"
+    : tasks.some((t) => t.status === "failed")
+      ? "failed"
+      : "completed";
+  emitSwarmDelta(ctx, {
+    type: dispatchStatus === "failed" ? "swarm.phase.failed" : "swarm.phase.completed",
+    phaseId: "dispatch",
+    label: "Dispatch",
+    status: dispatchStatus,
+    taskCount: tasks.length,
+    observedParallelism
+  });
 
   // Phase 3: Synthesize ----------------------------------------------------
+  emitSwarmDelta(ctx, {
+    type: "swarm.phase.started",
+    phaseId: "synthesize",
+    label: "Synthesize",
+    status: "running"
+  });
   const synthesisResult = await runSynthesisPhase({
     synthesisNode: synthesis,
     swarmConfig,
@@ -814,6 +1011,29 @@ async function runAgentSwarmGraphIfPresent({
     inputPayload: manualPayload,
     executionContext: ctx
   });
+  emitSwarmDelta(ctx, {
+    type: synthesisResult.status === "failed" ? "swarm.phase.failed" : "swarm.phase.completed",
+    phaseId: "synthesize",
+    label: "Synthesize",
+    status: synthesisResult.status,
+    agent: synthesisResult.ranSynthesis
+      ? {
+          taskId: cleanEventString(synthesis?.id || "synthesis"),
+          nodeId: cleanEventString(synthesis?.id || "synthesis"),
+          role: cleanEventString(synthesis?.label || "Synthesizer"),
+          phaseId: "synthesize",
+          status: synthesisResult.status,
+          adapter: cleanEventString(synthesisResult.adapter || ""),
+          agentHost: cleanEventString(synthesisResult.agentHost || ""),
+          durationMs: Number(synthesisResult.durationMs) || 0,
+          tokens: synthesisResult.tokens ?? null,
+          tools: synthesisResult.tools ?? null,
+          startedAt: cleanEventString(synthesisResult.startedAt || ""),
+          endedAt: cleanEventString(synthesisResult.endedAt || ""),
+          error: cleanEventString(synthesisResult.error || "")
+        }
+      : null
+  });
 
   const durationMs = Date.now() - startedAt;
   const requiredTasks = tasks.filter((t) => t.required);
@@ -863,6 +1083,15 @@ async function runAgentSwarmGraphIfPresent({
     errorText = `synthesizer returned OUTCOME_SCORE ${semanticScore} (< 0.5)`;
   }
 
+  emitSwarmDelta(ctx, {
+    type: outcomeOk ? "swarm.run.completed" : "swarm.run.failed",
+    status: swarmStatus,
+    durationMs,
+    observedParallelism: observedParallelism || (subagents.length === 1 ? 1 : 0),
+    reward,
+    error: cleanEventString(errorText || "")
+  });
+
   return {
     ok: outcomeOk,
     exitCode: outcomeOk ? 0 : 1,
@@ -888,6 +1117,12 @@ async function runAgentSwarmGraphIfPresent({
         adapter: orchestratorResult.adapter,
         agentHost: orchestratorResult.agentHost,
         durationMs: orchestratorResult.durationMs,
+        adapterMeta: orchestratorResult.adapterMeta || null,
+        tokens: orchestratorResult.tokens ?? null,
+        tools: orchestratorResult.tools ?? null,
+        startedAt: orchestratorResult.startedAt || "",
+        endedAt: orchestratorResult.endedAt || "",
+        phaseId: "plan",
         plan: clampText(orchestratorResult.plan, 4000)
       },
       tasks,
@@ -902,6 +1137,12 @@ async function runAgentSwarmGraphIfPresent({
             adapter: synthesisResult.adapter,
             agentHost: synthesisResult.agentHost,
             durationMs: synthesisResult.durationMs,
+            adapterMeta: synthesisResult.adapterMeta || null,
+            tokens: synthesisResult.tokens ?? null,
+            tools: synthesisResult.tools ?? null,
+            startedAt: synthesisResult.startedAt || "",
+            endedAt: synthesisResult.endedAt || "",
+            phaseId: "synthesize",
             answer: clampText(synthesisResult.output, 4000),
             parsedOutcomeScore: synthesisResult.parsedOutcomeScore
           }
@@ -914,6 +1155,7 @@ async function runAgentSwarmGraphIfPresent({
 export {
   runAgentSwarmGraphIfPresent,
   computeRewardTelemetry,
+  extractAdapterTelemetry,
   buildOrchestratorCommand,
   buildSubtaskCommand,
   buildSynthesisCommand,

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

@@ -364,6 +364,67 @@ function buildSandboxRowFromApiRegistry(workspaceConfig, registryRow, options =
   };
 }
 
+/**
+ * Find existing data-source rows that already resolve through a given API
+ * Registry integration (by `registryId`). Mirrors findSandboxRowsForRegistry so
+ * the drawer can refuse to create a duplicate Data Source for the same API.
+ */
+function findDataSourceRowsForRegistry(workspaceConfig, integrationId) {
+  const id = String(integrationId || "").trim();
+  if (!id) return [];
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const rows = [];
+  for (const object of objects) {
+    if (object?.objectType !== "data-source") continue;
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      if (String(row?.registryId || "").trim() === id) rows.push(row);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Build a governed Data Source row from a tested API Registry row. The Data
+ * Source references the registry entry by `registryId` (the existing
+ * resolver-binding relation) and keeps auth as an `authRef` slug only — the
+ * secret never lands on the row. Shape matches the OBJECT_TYPE_PRESETS
+ * "data-source" columns so it slots straight into the data-source table.
+ */
+function buildDataSourceRowFromApiRegistry(workspaceConfig, registryRow, options = {}) {
+  const integrationId = String(registryRow?.integrationId || "").trim();
+  const baseName = String(options.name || registryRow?.Name || integrationId || "Data Source").trim();
+  const name = baseName.endsWith(" Source") ? baseName : `${baseName} Source`;
+  const entityType = String(
+    options.entityType || registryRow?.entityTypes || "records"
+  ).split(",")[0].trim() || "records";
+  const sourceId = String(
+    options.sourceId || slugifyName(`${integrationId || baseName}-${entityType}`) || slugifyName(baseName)
+  ).trim();
+  const sourceStorage = String(options.sourceStorage || "workspace-source-records").trim();
+  return {
+    Name: name,
+    slug: options.slug || slugifyName(name) || slugifyName(integrationId),
+    objectType: "data-source",
+    registryId: integrationId,
+    endpoint: String(registryRow?.endpoint || "").trim(),
+    authRef: String(options.authRef || registryRow?.authRef || integrationId).trim(),
+    baseUrl: String(registryRow?.baseUrl || "").trim(),
+    method: String(registryRow?.method || "GET").trim().toUpperCase(),
+    status: "draft",
+    lastTested: "",
+    lastResponse: "",
+    entityType,
+    sourceId,
+    sourceStorage,
+    resolverTemplateId: String(options.resolverTemplateId || registryRow?.resolverTemplateId || "").trim(),
+    description: String(
+      options.description
+        || registryRow?.description
+        || `Data Source for ${integrationId || baseName} — resolves ${entityType} through the API Registry resolver. authRef ${String(options.authRef || registryRow?.authRef || integrationId).trim()} only; secrets resolve server-side.`
+    ).trim()
+  };
+}
+
 function extractNodeByType(graph, type) {
   const parsed = parseOrchestrationGraph(graph) || graph;
   if (!parsed?.nodes) return null;
@@ -783,6 +844,12 @@ function buildDefaultAgentSwarmGraph(options = {}) {
         role: String(agent.role || agent.id || "Subagent"),
         description: String(agent.description || "").trim(),
         taskPrompt: String(agent.taskPrompt || "").trim(),
+        // Optional author-named phase — groups this subagent in the cockpit
+        // (e.g. "ping" / "echo" / "verify"). Absent → the single Dispatch
+        // phase, exactly as before.
+        ...(String(agent.phase || agent.phaseId || "").trim()
+          ? { phase: String(agent.phase || agent.phaseId).trim().toLowerCase() }
+          : {}),
         tools: Array.isArray(agent.tools) ? agent.tools.map((t) => String(t || "").trim()).filter(Boolean) : [],
         agentHost: String(agent.agentHost || agentHost || "").trim(),
         adapter: String(agent.adapter || "").trim(),
@@ -918,6 +985,8 @@ export {
   getNextCanonicalNodeId,
   addCanonicalNodeToGraph,
   buildSandboxRowFromApiRegistry,
+  buildDataSourceRowFromApiRegistry,
+  findDataSourceRowsForRegistry,
   extractApiRegistryCallNode,
   extractInputNode,
   extractTransformConfig,