@xdelivered/emberflow 0.2.0 → 0.5.0

package/src/store/builderStore.ts

@@ -1,15 +1,11 @@
 import { create } from 'zustand';
-import { InMemoryTraceSink, runOutput, startRun } from '../engine';
+import { InMemoryTraceSink } from '../engine/trace';
+import { NodeRegistry } from '../engine/registry';
+import type { FlowRun } from '../engine/executor';
 import type {
-  FieldMapping, FlowRun, LogLine, NodeRegistry, ScenarioDefinition, StartRunOptions,
-  SubflowResult, WorkflowDefinition, WorkflowNode, WorkflowRun,
-} from '../engine';
-import { createDefaultRegistry } from '../nodes';
-import { createLoginFlow } from '../flows/login-flow';
-import { createWeatherFlow } from '../flows/weather-flow';
-import { createAnomalyFlows } from '../flows/anomaly-flows';
-import { createCitySweepFlow } from '../flows/city-sweep-flow';
-import { createPradarFlows } from '../flows/pradar-flows';
+  FieldMapping, LogLine, ScenarioDefinition,
+  WorkflowDefinition, WorkflowNode, WorkflowRun,
+} from '../engine/types';
 import { loadWorkspace, parseFlow, saveWorkspace, serializeFlow } from './persistence';
 import { fetchNodeMeta } from './nodeMeta';
 import {
@@ -22,6 +18,7 @@ import {
   loginEnvironment as loginEnvironmentOnServer,
   putWorkflow,
   runnerHealthy,
+  runNodeOnServer,
   setEnvironmentAuth as setEnvironmentAuthOnServer,
   setEnvironmentSecret as setEnvironmentSecretOnServer,
   setServingMode as setServingModeOnServer,
@@ -31,12 +28,13 @@ import {
   testWorkflow as testWorkflowOnServer,
 } from './serverRunner';
 import type {
-  EnvAuth, ErrorHandlerTag, EnvironmentSummary, ScenarioTestReport, ServerRunOptions,
+  EnvAuth, ErrorHandlerTag, EnvironmentSummary, ScenarioTestReport, ServerRunOptions, StepResult,
 } from './serverRunner';
 import { cancelAgent, fetchAgentDiff, revertAgent, startAgent, streamAgent } from './agentClient';
 import type { AgentEvent, AgentIntent, AgentKind, StartAgentOptions } from './agentClient';
 import { fetchSetupStatus } from './setupClient';
 import type { SetupStatus } from './setupClient';
+import { extractGuidedQuestions } from '../lib/guidedQuestions';
 
 export interface WorkflowSummary {
   id: string;
@@ -48,6 +46,14 @@ export interface WorkflowSummary {
   http?: { method: string; path: string };
 }
 
+/** Configures the two entry points that share the create modal: "New API"
+ *  (name + first operation) and "New operation" (optionally scoped to an API
+ *  via `location`). Owned here so any surface — Sidebar, canvas empty state —
+ *  opens the SAME modal (hosted once by CreateModalHost). */
+export type CreateModalState =
+  | { mode: 'api'; initialGoal?: string }
+  | { mode: 'operation'; location?: string };
+
 /** Per-operation path/http metadata, keyed by id — sourced from the runner's
  *  `/workflows` `operations` array (the store's `WorkflowDefinition`s don't
  *  carry `path`, since path is a filesystem concept, not a flow field). */
@@ -65,6 +71,30 @@ function dropReport(
 }
 
 
+/**
+ * One level of the stepped-run drill stack: entered when a step response
+ * reports `entered` (execution moved inside a Subflow node), popped on
+ * `exited`. The parent's flow/run/selection are stashed here so the canvas
+ * can show the child while the parent keeps receiving its own SSE states
+ * (routed into `savedRun` by workflowId), and be restored intact on exit.
+ */
+export interface StepDrillEntry {
+  /** The child flow's id (the level the drill entered INTO). */
+  workflowId: string;
+  /** The PARENT's Subflow node id that execution entered through. */
+  viaNodeId: string;
+  /** The parent level's flow, restored on exit. */
+  savedFlow: WorkflowDefinition;
+  /** The parent level's run — still updated by routed nodeState events while drilled. */
+  savedRun: WorkflowRun | null;
+  savedSelectedNodeId: string | null;
+  /** True when the child flow wasn't found in the workspace: the view stayed
+   *  on the parent, but the level is still pushed so the client stack depth
+   *  mirrors the server's and the matching `exited` pops correctly. Popping a
+   *  placeholder leaves flow/run/selection untouched (they never changed). */
+  placeholder?: true;
+}
+
 /** A finished run plus builder-side context the engine doesn't track. */
 export type RunHistoryEntry = WorkflowRun & {
   scenarioName?: string;
@@ -116,12 +146,8 @@ interface BuilderState {
   activeRun: FlowRun | null;
   dockTab: 'logs' | 'output' | 'infra';
   setDockTab(tab: 'logs' | 'output' | 'infra'): void;
-  /** 'auto' resolves to the runner when it's reachable, browser otherwise. */
-  executionMode: 'auto' | 'browser' | 'server';
-  setExecutionMode(mode: 'auto' | 'browser' | 'server'): void;
-  /** Where the next run will actually execute. */
-  effectiveMode(): 'browser' | 'server';
-  /** null = not yet checked. */
+  /** null = not yet checked. Runs are always server-side; when the runner is
+   *  offline the studio surfaces a calm offline state instead of executing. */
   runnerOnline: boolean | null;
   /** True when the reachable runner is serving EMBERFLOW_MOCK responses
    *  (from /healthz's `mock` field) rather than live execution. False when
@@ -138,7 +164,7 @@ interface BuilderState {
   environments: EnvironmentSummary[];
   /** The runner's default environment name. */
   environmentsDefault: string;
-  /** The environment the next run points at (persisted, like executionMode). */
+  /** The environment the next run points at (persisted). */
   selectedEnvironment: string;
   /** When on, mutation nodes dry-run their writes (persisted). */
   safeMode: boolean;
@@ -180,6 +206,18 @@ interface BuilderState {
   /** True while a stepped run is in progress (started via Step, not Run) — drives
    * the toolbar's step-over affordance. Cleared when the run finishes or resets. */
   stepMode: boolean;
+  /** Stepped-run subflow drill stack, deepest last. Non-empty while execution
+   *  is inside one (or more, when nested) Subflow nodes and the canvas shows
+   *  the drilled child. Empty otherwise. */
+  stepDrill: StepDrillEntry[];
+  /** View-only peek back up the drill stack: an index into `stepDrill` shows
+   *  that ancestor level's stashed flow/run in the runbook WITHOUT popping the
+   *  stack or touching the server; null shows the deepest (live) level.
+   *  Reset to null whenever execution enters or exits a subflow. */
+  drillPeek: number | null;
+  /** Peek at ancestor level `index` of the drill stack (null = back to the
+   *  deepest level). Out-of-range indexes clear the peek. */
+  peekDrill(index: number | null): void;
   sidebarOpen: boolean;
   toggleSidebar(): void;
   /** Whether the bottom dock panel is mounted (persisted). */
@@ -199,12 +237,19 @@ interface BuilderState {
   beginEnvironmentSetup(): void;
   /** Dispatch the infrastructure scout (scout-infrastructure intent): reads the
    *  project's deps/config/ORM/env-refs and writes emberflow/infrastructure.json.
-   *  Shared by the Welcome checklist and the Dock's Infra tab empty state. */
-  beginInfrastructureScout(): void;
+   *  Shared by the Welcome checklist and the Dock's Infra tab empty state. An
+   *  optional free-text `instruction` (from the Infrastructure modal's "Update
+   *  with AI") amends the manifest; empty/omitted runs a full rescan. */
+  beginInfrastructureScout(instruction?: string): void;
   /** Whether the first-run Welcome/Setup checklist dialog is open. Auto-opened
    *  on a fresh project (see WelcomeDialog); always reachable from the Toolbar. */
   welcomeOpen: boolean;
   setWelcomeOpen(open: boolean): void;
+  /** The New API / New operation modal's open state. Lifted to the store so
+   *  surfaces outside the Sidebar (e.g. the canvas empty state) share the ONE
+   *  modal instead of duplicating it; null = closed. Hosted by CreateModalHost. */
+  createModal: CreateModalState | null;
+  setCreateModal(state: CreateModalState | null): void;
   /** Whether the Settings dialog is open. Lifted to the store so the Welcome
    *  checklist's "coding agent" row can deep-link into it. */
   settingsOpen: boolean;
@@ -295,12 +340,28 @@ interface BuilderState {
     instruction?: string;
     diff?: string;
     files?: string[];
+    /** True when this run is a `guided-setup` run OWNED by the WelcomeDialog's
+     *  two-pane phase machine. It suppresses the right-hand AgentConsole
+     *  auto-open (the dialog embeds the stream itself) and, since the run lives
+     *  in this single slot, lets the dialog re-attach after being closed
+     *  mid-run — the phase derives from this flag + `status`. */
+    guided?: boolean;
   } | null;
+  /** Prior guided-setup conversation (finished runs' events + the user's
+   *  answers), preserved across continuation runs — each continuation REPLACES
+   *  the agentRun slot, so without this the onboarding pane would wipe to
+   *  "Thinking…" on every answer. Cleared on a fresh (no-notes) start. */
+  guidedTranscript: AgentEvent[];
   /** Persisted agent+model picked in Settings; used as runAgent's default opts. */
   agentChoice: AgentChoice;
   setAgentChoice(choice: AgentChoice): void;
   /** Start a coding-agent run and stream its events into `agentRun`. */
   runAgent(intent: AgentIntent, opts?: StartAgentOptions): Promise<void>;
+  /** Kick off (or continue) the WelcomeDialog's guided-setup run: one agent run
+   *  that reads state, scouts/skips, installs skills, and interviews about
+   *  environments. Marks the run `guided` so the dialog owns its stream and the
+   *  right-hand console stays closed. */
+  beginGuidedSetup(instruction?: string): void;
   /**
    * The operation currently being scaffolded by the create flow. Its stub is
    * already selected; the canvas shows a "waiting for the agent" holding pattern
@@ -352,8 +413,9 @@ interface BuilderState {
   pinNodeOutput(nodeId: string, output: unknown): void;
   unpinNode(nodeId: string): void;
   /**
-   * Execute one node directly against the given input (browser-side),
-   * capturing logs and recording a trace sample. Does not touch run state.
+   * Execute one node in isolation against the given input on the runner (POST
+   * /node-run), capturing logs and recording a local trace sample. Does not
+   * touch run state. Requires the runner to be online.
    */
   runNodeIsolated(
     nodeId: string,
@@ -370,35 +432,11 @@ interface BuilderState {
   importFlow(json: string): void;
 }
 
-const registry = createDefaultRegistry();
-
-/** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
-export const SUBFLOW_DEPTH_CAP = 8;
-
-/**
- * A prefixed copy of a child-run log line, folded into the parent's stream:
- * label becomes "<ChildFlow> › <nodeLabel>" and the console id is namespaced
- * under the calling Subflow node so console clicks don't collide with parent
- * ids.
- */
-function prefixSubflowLog(line: LogLine, childName: string, callerNodeId: string): LogLine {
-  return {
-    ...line,
-    nodeLabel: `${childName} › ${line.nodeLabel ?? ''}`,
-    nodeId: line.nodeId ? `${callerNodeId}/${line.nodeId}` : callerNodeId,
-  };
-}
-
-/** Build the cycle/depth error a subflow guard reports for a given ancestry. */
-function subflowGuardError(ancestry: string[], workflowId: string): string | null {
-  if (ancestry.length >= SUBFLOW_DEPTH_CAP) {
-    return `subflow depth cap (${SUBFLOW_DEPTH_CAP}) exceeded`;
-  }
-  if (ancestry.includes(workflowId)) {
-    return `subflow cycle: ${[...ancestry, workflowId].join(' → ')}`;
-  }
-  return null;
-}
+// The studio registry is definitions-only: it carries node metadata (labels,
+// schemas, categories) synced from the runner via syncNodeMeta, never the node
+// implementations. All execution happens on the runner — the studio is a pure
+// client. syncNodeMeta populates this from GET /api/nodes.
+const registry = new NodeRegistry();
 
 function touched(flow: WorkflowDefinition): WorkflowDefinition {
   return { ...flow, updatedAt: new Date().toISOString() };
@@ -451,29 +489,15 @@ function emptyFlow(): WorkflowDefinition {
   };
 }
 
+// The workspace comes from the runner (adopted on first health check via
+// syncFromRunner). At boot we hydrate only from any locally-persisted workspace;
+// with none, we open an empty flow. No example flows are seeded client-side —
+// the studio bundles no node implementations, so it can't execute them anyway.
 const workspace = loadWorkspace();
-const exampleFlows = [
-  createWeatherFlow(),
-  createLoginFlow(),
-  ...createAnomalyFlows(),
-  createCitySweepFlow(),
-  ...createPradarFlows(),
-];
-// Saved flows win; example flows the workspace doesn't know yet are merged in.
-const exampleById = new Map(exampleFlows.map((f) => [f.id, f]));
-const savedFlows = (workspace?.flows ?? []).map((f) => {
-  // Backfill the preferred environment onto older saved copies of built-in
-  // flows that predate the field, without clobbering user edits.
-  if (f.environment === undefined && exampleById.get(f.id)?.environment) {
-    return { ...f, environment: exampleById.get(f.id)!.environment };
-  }
-  return f;
-});
-const savedIds = new Set(savedFlows.map((f) => f.id));
-const initialFlows = [...savedFlows, ...exampleFlows.filter((f) => !savedIds.has(f.id))];
+const savedFlows = workspace?.flows ?? [];
 const initialFlow =
-  initialFlows.find((f) => f.id === workspace?.activeId) ?? initialFlows[0];
-const initialShelf = initialFlows.filter((f) => f.id !== initialFlow.id);
+  savedFlows.find((f) => f.id === workspace?.activeId) ?? savedFlows[0] ?? emptyFlow();
+const initialShelf = savedFlows.filter((f) => f.id !== initialFlow.id);
 
 const ENV_KEY = 'emberflow.environment';
 const SAFE_KEY = 'emberflow.safeMode';
@@ -551,10 +575,6 @@ let flowEnvSynced = false;
 let stepFollow = false;
 
 export const useBuilderStore = create<BuilderState>((set, get) => {
-  const snapshotRun = (handle: FlowRun): void => {
-    set({ run: { ...handle.run, nodeStates: { ...handle.run.nodeStates } } });
-  };
-
   /** Whether the selected environment is protected (writes are expensive there). */
   const selectedEnvProtected = (): boolean => {
     const s = get();
@@ -594,126 +614,143 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
     get().selectEnvironment(preferred);
   };
 
-  // Selection follows the step cursor: pick the most recently completed node.
-  const selectLatestCompleted = () => {
-    const states = Object.entries(get().run?.nodeStates ?? {});
-    let latest: string | null = null;
-    let latestAt = '';
-    for (const [id, st] of states) {
-      if ((st.status === 'succeeded' || st.status === 'failed') && st.completedAt && st.completedAt >= latestAt) {
-        latestAt = st.completedAt;
-        latest = id;
-      }
-    }
-    if (latest) set({ selectedNodeId: latest });
+  const reportRunError = (message: string): void => {
+    set((s) => ({
+      logs: [
+        ...s.logs,
+        { timestamp: new Date().toISOString(), level: 'error', runId: 'runner', message },
+      ],
+    }));
   };
 
   /**
-   * Browser-side Subflow runner. Resolves the child workflow across the active
-   * flow + shelf, runs it to completion on the same registry (browser env:
-   * empty secrets/vars, honouring safe mode), forwards its logs into the parent
-   * stream (prefixed), and returns its collected Result output. The ancestry
-   * chain — threaded through this closure, not global state — enforces the
-   * depth cap and catches A→B→A cycles.
+   * Execution stepped INTO a Subflow node: stash the current level and show
+   * the child flow with a fresh synthetic run (status running, no node states
+   * yet — the child's first node executes on the NEXT step and lights up as
+   * its SSE states arrive). Logs are the root run's and keep streaming; the
+   * server run id and step mode are untouched. If the child flow isn't in the
+   * workspace (shouldn't happen for project flows), stay on the parent but
+   * push a placeholder level so stack depths stay aligned with the server.
    */
-  const makeSubflowRunner = (
-    ancestry: string[],
-  ): NonNullable<StartRunOptions['subflowRunner']> => {
-    return async (workflowId, input, callerNodeId): Promise<SubflowResult> => {
-      const guard = subflowGuardError(ancestry, workflowId);
-      if (guard) return { status: 'failed', error: guard };
-      const s = get();
-      const childFlow = [s.flow, ...s.shelf].find((f) => f.id === workflowId);
-      if (!childFlow) return { status: 'failed', error: `Unknown workflow: ${workflowId}` };
-      try {
-        const handle = startRun({
-          flow: childFlow,
-          registry: s.registry,
-          trace: s.trace,
-          pins: pinsOf(childFlow),
-          input,
-          environment: 'browser',
-          safeMode: s.safeMode,
-          subflowRunner: makeSubflowRunner([...ancestry, workflowId]),
-          events: {
-            onLog: (line) =>
-              set((st) => ({
-                logs: [...st.logs, prefixSubflowLog(line, childFlow.name, callerNodeId)],
-              })),
-          },
-        });
-        const childRun = await handle.runToEnd();
-        if (childRun.status !== 'succeeded') {
-          return { status: 'failed', error: `subflow "${childFlow.name}" ${childRun.status}` };
-        }
-        return { status: 'succeeded', output: runOutput(childRun, childFlow) };
-      } catch (err) {
-        return { status: 'failed', error: err instanceof Error ? err.message : String(err) };
-      }
+  const enterDrill = (entered: { workflowId: string; nodeId: string }): void => {
+    const s = get();
+    const child = s.shelf.find((f) => f.id === entered.workflowId);
+    if (!child || child.id === s.flow.id) {
+      // Unknown child — keep stepping the parent view rather than crash, but
+      // still push a PLACEHOLDER level: the server's drill stack grew, and
+      // the client's must stay depth-aligned so the matching `exited` pops
+      // the right level (and deeper enters keep routing correctly).
+      hydrating(() =>
+        set({
+          stepDrill: [
+            ...s.stepDrill,
+            {
+              workflowId: entered.workflowId,
+              viaNodeId: entered.nodeId,
+              savedFlow: s.flow,
+              savedRun: s.run,
+              savedSelectedNodeId: s.selectedNodeId,
+              placeholder: true,
+            },
+          ],
+          drillPeek: null,
+        }),
+      );
+      return;
+    }
+    const runId = s.activeServerRunId ?? s.run?.id;
+    if (!runId) return;
+    // Same id as the root run: child states stream on the root run's SSE, and
+    // the visible-run guard in onNodeState keys off this id.
+    const childRun: WorkflowRun = {
+      id: runId,
+      workflowId: child.id,
+      status: 'running',
+      startedAt: new Date().toISOString(),
+      nodeStates: {},
     };
-  };
-
-  const ensureRun = (
-    input?: Record<string, unknown>,
-    scenarioMocks?: Record<string, unknown>,
-  ): FlowRun | null => {
-    const existing = get().activeRun;
-    if (existing && existing.run.status === 'running') return existing;
-    const mockRun = get().runnerMock;
-    set({ activeRunMock: mockRun });
-    try {
-      const handle = startRun({
-        flow: get().flow,
-        registry: get().registry,
-        trace: get().trace,
-        pins: pinsOf(get().flow),
-        input,
-        // Browser-engine runs honour Mock mode the same way the runner does:
-        // op-level mocks under any scenario's own map, fail-loud at infra.
-        ...(mockRun ? { mockRun: true, mocks: { ...get().flow.mocks, ...scenarioMocks } } : {}),
-        // Browser execution has no env file: it runs as environment 'browser'
-        // (empty secrets/vars) but still honours safe mode over HTTP.
-        environment: 'browser',
-        safeMode: get().safeMode,
-        subflowRunner: makeSubflowRunner([get().flow.id]),
-        events: {
-          onNodeStateChange: () => snapshotRun(handle),
-          onLog: (line) => set((s) => ({ logs: [...s.logs, line] })),
-          onRunFinished: () => {
-            snapshotRun(handle);
-            get().recordRun({ ...handle.run, nodeStates: { ...handle.run.nodeStates } });
-            set({ activeRun: null });
-            revertUnsafeAfterRun();
-          },
-        },
-      });
-      set({ activeRun: handle, logs: [] });
-      snapshotRun(handle);
-      return handle;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      set((s) => ({
-        logs: [
-          ...s.logs,
+    // hydrating: a drill swap is a view change, not an edit — it must not
+    // trigger the autosave that a `flow` reference change normally implies.
+    hydrating(() =>
+      set({
+        stepDrill: [
+          ...s.stepDrill,
           {
-            timestamp: new Date().toISOString(),
-            level: 'error',
-            runId: 'validation',
-            message,
+            workflowId: child.id,
+            viaNodeId: entered.nodeId,
+            savedFlow: s.flow,
+            savedRun: s.run,
+            savedSelectedNodeId: s.selectedNodeId,
           },
         ],
-      }));
-      return null;
+        drillPeek: null,
+        flow: child,
+        run: childRun,
+        selectedNodeId: null,
+      }),
+    );
+  };
+
+  /** The drilled child completed: pop one level and restore the parent's
+   *  flow/run/selection (its run kept receiving its own routed SSE states —
+   *  including the Subflow node's terminal state — while we were inside). */
+  const exitDrill = (): void => {
+    const s = get();
+    const entry = s.stepDrill[s.stepDrill.length - 1];
+    if (!entry) return;
+    if (entry.placeholder) {
+      // The view never left the parent for this level — just drop it. The
+      // live flow/run kept receiving the parent's states while "inside".
+      hydrating(() => set({ stepDrill: s.stepDrill.slice(0, -1), drillPeek: null }));
+      return;
     }
+    hydrating(() =>
+      set({
+        stepDrill: s.stepDrill.slice(0, -1),
+        drillPeek: null,
+        flow: entry.savedFlow,
+        run: entry.savedRun,
+        selectedNodeId: entry.savedSelectedNodeId,
+      }),
+    );
   };
 
-  const reportRunError = (message: string): void => {
-    set((s) => ({
-      logs: [
-        ...s.logs,
-        { timestamp: new Date().toISOString(), level: 'error', runId: 'runner', message },
-      ],
-    }));
+  /** Unwind the whole drill stack back to the root level (run finish/reset/
+   *  flow switch): restore the root's flow/run/selection and drop the stack. */
+  const drainDrill = (): void => {
+    const s = get();
+    if (s.stepDrill.length === 0) {
+      if (s.drillPeek !== null) set({ drillPeek: null });
+      return;
+    }
+    // All-placeholder stack: the view never left the root, and the live run
+    // (not the stashes) kept receiving its states — just drop the levels.
+    if (s.stepDrill.every((d) => d.placeholder)) {
+      hydrating(() => set({ stepDrill: [], drillPeek: null }));
+      return;
+    }
+    const root = s.stepDrill[0];
+    hydrating(() =>
+      set({
+        stepDrill: [],
+        drillPeek: null,
+        flow: root.savedFlow,
+        run: root.savedRun,
+        selectedNodeId: root.savedSelectedNodeId,
+      }),
+    );
+  };
+
+  /** Consume one step response: drive the drill stack from entered/exited
+   *  markers and clear the live-run id when the run is done. `exited` can
+   *  co-occur with `done` (child was the last node, or the child failed). */
+  const handleStepResult = (result: StepResult): void => {
+    // Order matters when both markers co-occur: a retrying Subflow node pops
+    // its failed child AND re-enters a fresh one in the same step — the pop
+    // must apply before the push, or the exit would pop the new level.
+    if (result.exited) exitDrill();
+    if (result.entered) enterDrill(result.entered);
+    if (result.done) set({ activeServerRunId: null });
   };
 
   /** Start a server-side run (if none live) and wire its SSE events into the store. */
@@ -742,18 +779,40 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       };
       set({ activeServerRunId: runId, run: initial, logs: [] });
       subscribeServerRun(runId, {
-        onNodeState: (nodeId, state) => {
+        onNodeState: (workflowId, nodeId, state) => {
           set((s) => {
-            if (!s.run || s.run.id !== runId) return {};
-            const follow =
-              stepFollow && (state.status === 'succeeded' || state.status === 'failed')
-                ? { selectedNodeId: nodeId }
-                : {};
-            return { run: { ...s.run, nodeStates: { ...s.run.nodeStates, [nodeId]: state } }, ...follow };
+            const followed =
+              stepFollow && (state.status === 'succeeded' || state.status === 'failed');
+            // The level whose flow is loaded owns this event (deepest drilled
+            // level, or the root when not drilled) → apply to the live run.
+            if (s.flow.id === workflowId) {
+              if (!s.run || s.run.id !== runId) return {};
+              return {
+                run: { ...s.run, nodeStates: { ...s.run.nodeStates, [nodeId]: state } },
+                ...(followed ? { selectedNodeId: nodeId } : {}),
+              };
+            }
+            // A stashed drill level owns it (e.g. the parent's Subflow node
+            // updating while we're inside the child) → apply to its stashed
+            // run so nothing is lost when that level is restored or peeked.
+            const idx = s.stepDrill.findIndex((d) => d.savedFlow.id === workflowId);
+            if (idx === -1) return {}; // unknown workflowId — ignore
+            const entry = s.stepDrill[idx];
+            if (!entry.savedRun || entry.savedRun.id !== runId) return {};
+            const savedRun = {
+              ...entry.savedRun,
+              nodeStates: { ...entry.savedRun.nodeStates, [nodeId]: state },
+            };
+            return {
+              stepDrill: s.stepDrill.map((d, i) => (i === idx ? { ...d, savedRun } : d)),
+            };
           });
         },
         onLog: (line) => set((s) => ({ logs: [...s.logs, line] })),
         onFinished: (run, errorHandler) => {
+          // The final run is the ROOT run — unwind any remaining drill levels
+          // (cancel/failure can finish a run while drilled) before showing it.
+          drainDrill();
           set({ run });
           get().recordRun(run, errorHandler);
           set({ activeServerRunId: null });
@@ -789,6 +848,7 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
     agentPanelOpen: false,
     agentEnvSetup: false,
     welcomeOpen: false,
+    createModal: null,
     settingsOpen: false,
     settingsFromWelcome: false,
     setupStatus: null,
@@ -803,22 +863,26 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
     activeRunMock: false,
     scenarioTestPending: null,
     agentRun: null,
+    guidedTranscript: [],
     buildingOperationId: null,
     agentChoice: initialAgentChoice,
     setAgentChoice(choice) {
       set({ agentChoice: choice });
       persistAgentChoice(choice);
     },
-    executionMode: (() => {
-      const saved =
-        typeof localStorage !== 'undefined' ? localStorage.getItem('emberflow.mode') : null;
-      return saved === 'browser' || saved === 'server' ? saved : 'auto';
-    })(),
     runnerOnline: null,
     runnerMock: false,
     workspaceSource: 'local',
     activeServerRunId: null,
     stepMode: false,
+    stepDrill: [],
+    drillPeek: null,
+    peekDrill(index) {
+      set((s) => {
+        if (index === null || s.stepDrill.length === 0) return { drillPeek: null };
+        return { drillPeek: index >= 0 && index < s.stepDrill.length ? index : null };
+      });
+    },
     environments: [],
     environmentsDefault: '',
     selectedEnvironment: initialSelectedEnvironment,
@@ -906,18 +970,6 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       return true;
     },
 
-    setExecutionMode(mode) {
-      set({ executionMode: mode });
-      if (typeof localStorage !== 'undefined') localStorage.setItem('emberflow.mode', mode);
-      if (mode !== 'browser') void get().checkRunner();
-    },
-
-    effectiveMode() {
-      const s = get();
-      if (s.executionMode === 'auto') return s.runnerOnline ? 'server' : 'browser';
-      return s.executionMode;
-    },
-
     async setServingMode(mode) {
       await setServingModeOnServer(mode);
       await get().checkRunner();
@@ -942,8 +994,8 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       if (meta.length === 0) return;
       const registry = get().registry;
       for (const m of meta) {
-        const { source, ...definition } = m;
-        registry.registerDefinition(definition, source);
+        const { source, sourceRef, builtin, ...definition } = m;
+        registry.registerDefinition(definition, source, { sourceRef, builtin });
       }
       // Force palette/inspector consumers to re-read the registry: a new
       // top-level reference (Zustand uses Object.is) sharing the same node data.
@@ -971,6 +1023,8 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
           logs: [],
           activeRun: null,
           selectedNodeId: null,
+          stepDrill: [],
+          drillPeek: null,
         }),
       );
     },
@@ -1050,6 +1104,11 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
 
     async runAgent(intent, opts) {
       const effectiveOpts = opts ?? get().agentChoice;
+      // A guided-setup run is OWNED by the WelcomeDialog's embedded stream, so
+      // it must NOT auto-open the right-hand AgentConsole panel. The `guided`
+      // marker on the run slot drives both the suppression here and the dialog's
+      // phase machine (which re-attaches to this same slot when reopened).
+      const guided = intent.action === 'guided-setup';
       // If a build is in flight, remember the op being built + the op ids that
       // existed before the run. If the agent renames the op (the id changes),
       // syncFromRunner can't find the old id and falls back to flows[0], leaving
@@ -1067,18 +1126,22 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
             id: '',
             events: [{ type: 'error', text: err instanceof Error ? err.message : String(err) }],
             status: 'error',
+            guided,
           },
           // Open the panel so the failure is visible — without this, a start
           // error (e.g. no agent CLI on PATH) lands in a closed panel and the
-          // click appears to do nothing.
-          agentPanelOpen: true,
+          // click appears to do nothing. A guided run's failure surfaces in the
+          // WelcomeDialog's own pane, so it stays closed.
+          ...(guided ? {} : { agentPanelOpen: true }),
         });
         return;
       }
 
       set({
-        agentRun: { id: agentRunId, events: [], status: 'running', instruction: intent.instruction },
-        agentPanelOpen: true,
+        agentRun: { id: agentRunId, events: [], status: 'running', instruction: intent.instruction, guided },
+        // The WelcomeDialog embeds the stream for guided runs — don't also pop
+        // the right-hand console.
+        ...(guided ? {} : { agentPanelOpen: true }),
       });
 
       // Live canvas: while the agent works, poll the runner (GET /workflows reads
@@ -1210,18 +1273,55 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       set({ agentPanelOpen: true, agentEnvSetup: true });
     },
 
-    beginInfrastructureScout() {
+    beginInfrastructureScout(instruction) {
+      // Defensive: callers wired as onClick handlers leak a MouseEvent as the
+      // first arg — anything that isn't a string means "full rescan".
+      const amendment = typeof instruction === 'string' ? instruction.trim() : '';
       void get().runAgent({
         action: 'scout-infrastructure',
         instruction:
-          "Scan this project's dependencies, config files, ORM schemas, env-var references and HTTP clients, and write emberflow/infrastructure.json describing the databases, APIs and providers it already uses.",
+          amendment && amendment.length > 0
+            ? amendment
+            : "Scan this project's dependencies, config files, ORM schemas, env-var references and HTTP clients, and write emberflow/infrastructure.json describing the databases, APIs and providers it already uses.",
       });
     },
 
+    beginGuidedSetup(instruction) {
+      // onClick handlers leak a MouseEvent as the first arg — only a real string
+      // is a continuation answer; anything else means "start with no notes".
+      const notes = typeof instruction === 'string' ? instruction.trim() : '';
+      const prior = get().agentRun;
+      if (notes && prior?.guided) {
+        // Continuation: the new run REPLACES the agentRun slot, so fold the
+        // finished run's events plus the user's answer into the persistent
+        // transcript — otherwise the pane wipes to "Thinking…" and the whole
+        // conversation vanishes. Question blocks are stripped here (they were
+        // answered; re-rendering them as raw fences would be noise).
+        const stripped = prior.events.map((e) =>
+          e.type === 'message' && e.text ? { ...e, text: extractGuidedQuestions(e.text).stripped } : e,
+        );
+        set((s) => ({
+          guidedTranscript: [
+            ...s.guidedTranscript,
+            ...stripped,
+            { type: 'message', text: `**You:** ${notes}` },
+          ],
+        }));
+      } else if (!notes) {
+        // Fresh start: a brand-new guided run begins a brand-new conversation.
+        set({ guidedTranscript: [] });
+      }
+      void get().runAgent({ action: 'guided-setup', instruction: notes });
+    },
+
     setWelcomeOpen(open) {
       set({ welcomeOpen: open });
     },
 
+    setCreateModal(state) {
+      set({ createModal: state });
+    },
+
     setSettingsOpen(open) {
       set(open ? { settingsOpen: true } : { settingsOpen: false, settingsFromWelcome: false });
     },
@@ -1328,6 +1428,9 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
     },
 
     switchWorkflow(id) {
+      // Switching flows while drilled would strand the stashed parent — put
+      // the root level back first so flow/shelf are consistent again.
+      drainDrill();
       let switched = false;
       set((s) => {
         if (s.flow.id === id) return {};
@@ -1590,57 +1693,45 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       const s = get();
       const node = s.flow.nodes.find((n) => n.id === nodeId);
       if (!node) return { error: `Unknown node: ${nodeId}`, logs: [] };
-      if (!s.registry.has(node.type)) {
-        return { error: `Unknown node type: ${node.type}`, logs: [] };
-      }
-      const { implementation } = s.registry.get(node.type);
-      const logs: LogLine[] = [];
-      const runId = `isolated-${crypto.randomUUID().slice(0, 8)}`;
-      const log = (level: LogLine['level'], message: string): void => {
-        logs.push({
-          timestamp: new Date().toISOString(),
-          level,
-          runId,
-          nodeId: node.id,
-          nodeLabel: node.label,
-          message,
-        });
-      };
+      // Isolated node runs execute on the runner (POST /node-run) against the
+      // selected environment's secrets/vars, honouring safe mode — the studio
+      // bundles no implementations. Runner offline → surface the offline notice.
       const startedAt = new Date().toISOString();
-      const sample = (status: 'succeeded' | 'failed', output?: unknown) => {
-        s.trace.record({
-          id: crypto.randomUUID(),
-          workflowId: s.flow.id,
-          runId,
-          nodeId: node.id,
-          nodeType: node.type,
-          nodeLabel: node.label,
-          input,
-          output,
-          status,
-          startedAt,
-          completedAt: new Date().toISOString(),
-        });
-      };
+      let result: { output?: unknown; error?: string; logs: LogLine[] };
       try {
-        const output = await implementation({
+        result = await runNodeOnServer({
+          type: node.type,
           input,
-          config: node.config,
-          secrets: {},
-          vars: {},
-          safeMode: false,
-          runInput: {},
-          log,
-          runSubflow: (workflowId, subInput) =>
-            makeSubflowRunner([s.flow.id])(workflowId, subInput, node.id),
+          config: node.config ?? {},
+          ...(s.selectedEnvironment ? { environment: s.selectedEnvironment } : {}),
+          safeMode: s.safeMode,
+          ...(selectedEnvProtected() && !s.safeMode ? { confirm: s.selectedEnvironment } : {}),
         });
-        sample('succeeded', output);
-        return { output, logs };
       } catch (err) {
-        const error = err instanceof Error ? err.message : String(err);
-        sample('failed');
-        return { error, logs };
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          error: get().runnerOnline === false
+            ? 'Runner offline — start it with `npx emberflow dev`, then run this node again.'
+            : message,
+          logs: [],
+        };
       }
+      // Record a local trace sample so the modal's "previous executions" list
+      // and pin affordance keep working alongside runner-recorded samples.
+      s.trace.record({
+        id: crypto.randomUUID(),
+        workflowId: s.flow.id,
+        runId: `isolated-${crypto.randomUUID().slice(0, 8)}`,
+        nodeId: node.id,
+        nodeType: node.type,
+        nodeLabel: node.label,
+        input,
+        output: result.output,
+        status: result.error ? 'failed' : 'succeeded',
+        startedAt,
+        completedAt: new Date().toISOString(),
+      });
+      return { output: result.output, error: result.error, logs: result.logs ?? [] };
     },
 
     async testWorkflow(flowId, environment) {
@@ -1662,12 +1753,7 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       get().resetRun();
       set({ stepMode: false });
       set({ activeScenarioId: scenarioId });
-      if (get().effectiveMode() === 'server') {
-        await ensureServerRun('run', scenario.input, scenario.name);
-        return;
-      }
-      const handle = ensureRun(scenario.input, scenario.mocks);
-      if (handle) await handle.runToEnd();
+      await ensureServerRun('run', scenario.input, scenario.name);
     },
 
     async stepScenario(scenarioId) {
@@ -1677,22 +1763,13 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
       get().resetRun();
       set({ stepMode: true });
       set({ activeScenarioId: scenarioId });
-      if (get().effectiveMode() === 'server') {
-        const runId = await ensureServerRun('step', scenario.input, scenario.name);
-        if (runId) {
-          try {
-            const done = await stepServerRun(runId);
-            if (done) set({ activeServerRunId: null });
-          } catch (err) {
-            reportRunError(err instanceof Error ? err.message : String(err));
-          }
+      const runId = await ensureServerRun('step', scenario.input, scenario.name);
+      if (runId) {
+        try {
+          handleStepResult(await stepServerRun(runId));
+        } catch (err) {
+          reportRunError(err instanceof Error ? err.message : String(err));
         }
-        return;
-      }
-      const handle = ensureRun(scenario.input, scenario.mocks);
-      if (handle) {
-        await handle.step();
-        selectLatestCompleted();
       }
     },
 
@@ -1740,53 +1817,47 @@ export const useBuilderStore = create<BuilderState>((set, get) => {
     async stepRun() {
       // A plain step/run is not scenario-driven; only tag history for runs
       // started via runScenario.
-      if (!get().activeRun && !get().activeServerRunId) set({ activeScenarioId: null });
+      if (!get().activeServerRunId) set({ activeScenarioId: null });
       stepFollow = true;
       set({ stepMode: true, runConsoleDismissedId: null });
-      if (get().effectiveMode() === 'server') {
-        const runId = await ensureServerRun('step');
-        if (runId) {
-          try {
-            const done = await stepServerRun(runId);
-            if (done) set({ activeServerRunId: null });
-          } catch (err) {
-            reportRunError(err instanceof Error ? err.message : String(err));
-          }
+      const runId = await ensureServerRun('step');
+      if (runId) {
+        try {
+          handleStepResult(await stepServerRun(runId));
+        } catch (err) {
+          reportRunError(err instanceof Error ? err.message : String(err));
         }
-        return;
-      }
-      const handle = ensureRun();
-      if (handle) {
-        await handle.step();
-        selectLatestCompleted();
       }
     },
 
     async runToEnd() {
       stepFollow = false;
       set({ stepMode: false, runConsoleDismissedId: null });
-      if (!get().activeRun && !get().activeServerRunId) set({ activeScenarioId: null });
-      if (get().effectiveMode() === 'server') {
-        const existing = get().activeServerRunId;
-        if (existing) {
-          // A stepped run is already live on the runner — walk it to the end.
-          try {
-            let done = false;
-            while (!done) done = await stepServerRun(existing);
-            set({ activeServerRunId: null });
-          } catch (err) {
-            reportRunError(err instanceof Error ? err.message : String(err));
+      if (!get().activeServerRunId) set({ activeScenarioId: null });
+      const existing = get().activeServerRunId;
+      if (existing) {
+        // A stepped run is already live on the runner — walk it to the end.
+        // Drill markers still apply (entered/exited keep the view balanced;
+        // handleStepResult clears activeServerRunId on done).
+        try {
+          let done = false;
+          while (!done) {
+            const result = await stepServerRun(existing);
+            handleStepResult(result);
+            done = result.done;
           }
-          return;
+        } catch (err) {
+          reportRunError(err instanceof Error ? err.message : String(err));
         }
-        await ensureServerRun('run');
         return;
       }
-      const handle = ensureRun();
-      if (handle) await handle.runToEnd();
+      await ensureServerRun('run');
     },
 
     resetRun() {
+      // Unwind any subflow drill first so the root flow is back on the canvas
+      // before the run state clears.
+      drainDrill();
       get().activeRun?.cancel();
       const serverRunId = get().activeServerRunId;
       if (serverRunId) void cancelServerRun(serverRunId);