fix(studio/flow): wire decision branches to edges, expand screen config, align simulator (#1927)

* fix(studio/flow): wire decision branches to edges, expand screen config, align simulator

Found dogfooding the Studio Flow Builder as a business user:

- Decision branches now mirror onto the node's outgoing edges (FlowCanvas.addNode
  carries the matching branch onto a new edge; FlowNodeInspector re-syncs existing
  edges when branches change). A decision built in Studio now routes at runtime
  instead of running every branch (engine/simulator branch on edge.condition).
- Screen config form now edits title/description/waitForInput + object-form keys
  (objectName/idVariable/mode/defaults), not just fields.
- Simulator applies assignment nodes (was a no-op) using the engine's shapes +
  {var} interpolation, and only pauses screens that collect input (engine parity).
- Tests: flow-simulator screen-pause + assignment coverage updated/added.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(studio/flow): de-duplicate HTTP node in palette (canonical http)

The base palette hardcoded the deprecated http_request alias while the engine
publishes the canonical http, so the Add-node palette listed two HTTP entries.
Base now uses http (merges with the engine descriptor into one), aliased to the
http_request config group so the inspector form is unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/studio-flow-builder-gaps.md

@@ -0,0 +1,29 @@
+---
+"@object-ui/app-shell": patch
+---
+
+fix(studio/flow): wire decision branches to edges, expand screen config, align simulator with engine
+
+Four fixes for the Studio Flow Builder, found dogfooding it as a business user:
+
+- **Decision branches now route.** The "Branches" editor wrote `node.config.conditions`
+  but never the outgoing edges, so a decision built entirely in Studio left every
+  out-edge unconditional — the engine and simulator (which branch on `edge.condition`)
+  ran *all* branches. Branches now mirror onto the node's out-edges (by order):
+  `FlowCanvas.addNode` carries the matching branch onto a newly-connected edge, and
+  `FlowNodeInspector` re-syncs existing edges when branches are edited (a `true`
+  expression marks the default/else edge).
+- **Screen node config expanded.** The form exposed only `fields`; it now also edits
+  `title`, `description` (interpolates `{var}`), `waitForInput`, and the object-form
+  keys (`objectName`, `idVariable`, `mode`, `defaults`) — so a message screen or an
+  object-form wizard step no longer requires dropping to Advanced JSON.
+- **Simulator applies assignment nodes.** Assignment was a no-op pass-through, so a
+  Debug run never reflected `Set variables`. It now normalizes the same shapes the
+  engine accepts (`assignments` map/array + flat) and interpolates `{var}`.
+- **Simulator screen-pause parity.** The simulator paused on every screen; it now
+  pauses only when the screen collects input (`fields`) or sets `waitForInput`,
+  matching the engine's `shouldPause` — a field-less screen passes through.
+- **Palette HTTP de-duplicated.** The base palette hardcoded the deprecated
+  `http_request` alias while the engine publishes the canonical `http`, showing
+  two HTTP entries. The base now uses `http` (merging into one), aliased to the
+  `http_request` config form so the inspector is unchanged.

packages/app-shell/src/views/metadata-admin/inspectors/FlowNodeInspector.tsx

@@ -44,6 +44,54 @@ interface FlowNode {
   [k: string]: unknown;
 }
 
+interface FlowEdge {
+  id?: string;
+  source: string;
+  target: string;
+  condition?: unknown;
+  label?: string;
+  isDefault?: boolean;
+  type?: string;
+  [k: string]: unknown;
+}
+
+/**
+ * Mirror a decision node's `conditions` (branches) onto its outgoing sequence
+ * edges, in declared order: branch i -> the i-th out-edge. A branch whose
+ * expression is `true` marks its edge as the default/else path; an empty
+ * expression clears the guard. Fault / back edges are left untouched.
+ *
+ * This is what lets a decision authored entirely in Studio actually route at
+ * runtime: the engine and the simulator branch on `edge.condition`, NOT on
+ * `node.config.conditions` (which is only a node-local branch list). Without
+ * the mirror, every out-edge stays unconditional and all branches fire.
+ */
+function syncDecisionEdges(decisionId: string, conditions: unknown, edges: FlowEdge[]): FlowEdge[] {
+  const branches = Array.isArray(conditions) ? conditions : [];
+  let bi = 0;
+  return edges.map((e) => {
+    if (e.source !== decisionId || e.type === 'fault' || e.type === 'back') return e;
+    const branch = branches[bi++] as Record<string, unknown> | undefined;
+    if (!branch || typeof branch !== 'object') return e;
+    const expr = typeof branch.expression === 'string' ? branch.expression.trim() : '';
+    const label = typeof branch.label === 'string' ? branch.label.trim() : '';
+    const next: FlowEdge = { ...e };
+    if (label) next.label = label;
+    else delete next.label;
+    if (expr && expr !== 'true') {
+      next.condition = expr;
+      delete next.isDefault;
+    } else if (expr === 'true') {
+      next.isDefault = true;
+      delete next.condition;
+    } else {
+      delete next.condition;
+      delete next.isDefault;
+    }
+    return next;
+  });
+}
+
 function asConfig(node: FlowNode | null): Record<string, unknown> {
   const c = node?.config;
   return c && typeof c === 'object' && !Array.isArray(c) ? (c as Record<string, unknown>) : {};
@@ -134,7 +182,17 @@ export function FlowNodeInspector({ selection, draft, onPatch, onClearSelection,
 
   const setField = (path: string[], value: unknown) => {
     const nextNode = setAtPath(node, path, value);
-    onPatch({ nodes: spliceArray(nodes, index, nextNode) });
+    const patch: Record<string, unknown> = { nodes: spliceArray(nodes, index, nextNode) };
+    // Decision branches drive routing — mirror them onto the node's outgoing
+    // edges so the engine/simulator can actually branch (they read
+    // edge.condition, not node.config.conditions).
+    if (node.type === 'decision' && path.length === 2 && path[0] === 'config' && path[1] === 'conditions') {
+      const draftEdges = Array.isArray((draft as { edges?: unknown }).edges)
+        ? ((draft as { edges: FlowEdge[] }).edges)
+        : [];
+      patch.edges = syncDecisionEdges(node.id, value, draftEdges);
+    }
+    onPatch(patch);
   };
 
   const commitAdvanced = () => {

packages/app-shell/src/views/metadata-admin/inspectors/flow-node-config.ts

@@ -325,9 +325,19 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
     }),
     { id: 'timeoutMs', path: ['timeoutMs'], label: 'Timeout (ms)', kind: 'number', placeholder: '30000' },
   ],
+  // Screen — collect input (a flat `fields` list) OR render an object's full
+  // create/edit form (`objectName`, master-detail). `title`/`description`
+  // head the screen (description interpolates {var}); `waitForInput` forces a
+  // pause on a field-less message/confirmation screen. All optional and shown
+  // together so neither a message screen nor an object-form step needs JSON.
   screen: [
+    cfg('title', 'Title', 'text', { placeholder: 'Request a discount', help: 'Heading shown above the screen.' }),
+    cfg('description', 'Description', 'textarea', {
+      placeholder: 'Enter the deal amount and the discount you want.',
+      help: 'Body text. Interpolates {var} references (e.g. {approval_path}).',
+    }),
     cfg('fields', 'Fields', 'objectList', {
-      help: 'Fields presented on this screen.',
+      help: 'Input fields collected on this screen. Leave empty for a message-only screen.',
       columns: [
         { key: 'name', label: 'Name', kind: 'text', placeholder: 'discount' },
         { key: 'label', label: 'Label', kind: 'text', placeholder: 'Discount %' },
@@ -336,6 +346,29 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
         { key: 'visibleWhen', label: 'Visible when', kind: 'expression', placeholder: 'stage == "review"' },
       ],
     }),
+    cfg('waitForInput', 'Wait for input', 'boolean', {
+      help: 'Pause to show this screen even with no fields (a message / confirmation). A field-less screen with this off is a server pass-through.',
+    }),
+    cfg('objectName', 'Object form', 'reference', {
+      ref: { kind: 'object' },
+      placeholder: 'crm_account',
+      help: 'Render this object\u2019s full create/edit form (incl. master-detail) instead of a flat field list.',
+    }),
+    cfg('idVariable', 'Saved-record variable', 'text', {
+      placeholder: 'account_id',
+      help: 'Object form only: variable bound to the saved record\u2019s id, for later steps.',
+    }),
+    cfg('mode', 'Form mode', 'select', {
+      options: [
+        { value: 'create', label: 'Create' },
+        { value: 'edit', label: 'Edit' },
+      ],
+      defaultValue: 'create',
+      help: 'Object form only.',
+    }),
+    cfg('defaults', 'Form defaults', 'keyValue', {
+      help: 'Object form only: prefilled values (e.g. account \u2192 {account_id}).',
+    }),
   ],
   // Approval node (ADR-0019). The node opens an approval request on entry,
   // suspends the run, and resumes down its `approve` / `reject` out-edge once a
@@ -526,6 +559,7 @@ const FLOW_NODE_CONFIG: Record<string, FlowConfigField[]> = {
  */
 const TYPE_ALIASES: Record<string, string> = {
   action: 'legacy_action',
+  http: 'http_request',
   branch: 'decision',
   gateway: 'decision',
   condition: 'decision',

packages/app-shell/src/views/metadata-admin/previews/FlowCanvas.tsx

@@ -164,6 +164,25 @@ export function FlowCanvas({
           source: opts.from,
           target: id,
         };
+        // When the source is a decision, carry its matching branch (by order:
+        // the k-th out-edge takes the k-th branch) onto the new edge so it
+        // actually routes. The decision's config.conditions are otherwise
+        // disconnected from the edges, leaving every branch unconditional.
+        const fromNode = nodes.find((n) => n.id === opts.from);
+        if (fromNode?.type === 'decision') {
+          const branches = Array.isArray(fromNode.config?.conditions)
+            ? (fromNode.config!.conditions as Array<Record<string, unknown>>)
+            : [];
+          const outCount = edges.filter((e) => e.source === opts.from).length;
+          const branch = branches[outCount];
+          if (branch && typeof branch === 'object') {
+            const expr = typeof branch.expression === 'string' ? branch.expression.trim() : '';
+            const label = typeof branch.label === 'string' ? branch.label.trim() : '';
+            if (label) newEdge.label = label;
+            if (expr === 'true') newEdge.isDefault = true;
+            else if (expr) newEdge.condition = expr;
+          }
+        }
         patch.edges = appendArray(edges, newEdge);
       }
       onPatch(patch);

packages/app-shell/src/views/metadata-admin/previews/flow-canvas-parts.tsx

@@ -227,6 +227,7 @@ export function nodeTone(type: string): NodeTone {
     case 'delete_record':
     case 'get_record':
       return TONES.record;
+    case 'http':
     case 'http_request':
     case 'connector_action':
     case 'script':
@@ -290,6 +291,7 @@ export function nodeCategory(type: string): NodeCategory {
     case 'screen':
     case 'user_task':
       return 'Human';
+    case 'http':
     case 'http_request':
     case 'connector_action':
     case 'script':
@@ -319,7 +321,7 @@ export const NODE_PALETTE: PaletteItem[] = [
   { type: 'try_catch', label: 'Try / Catch', hint: 'Protect steps with error handling and retry', category: 'Logic' },
   { type: 'approval', label: 'Approval', hint: 'Pause for a human decision', category: 'Human' },
   { type: 'screen', label: 'Screen', hint: 'Collect input from a user', category: 'Human' },
-  { type: 'http_request', label: 'HTTP request', hint: 'Call an external API', category: 'Integration' },
+  { type: 'http', label: 'HTTP request', hint: 'Call an external API', category: 'Integration' },
   { type: 'connector_action', label: 'Connector', hint: 'Run an integration action', category: 'Integration' },
   { type: 'script', label: 'Script', hint: 'Run custom code', category: 'Integration' },
   { type: 'subflow', label: 'Subflow', hint: 'Invoke another flow', category: 'Flow' },
@@ -356,6 +358,7 @@ export function defaultNodeExtras(type: string): Record<string, unknown> {
       // Seed a node-model approval: at least one approver + spec defaults. The
       // author wires the out-edges with labels `approve` / `reject`.
       return { config: { approvers: [{ type: 'manager' }], behavior: 'first_response', lockRecord: true } };
+    case 'http':
     case 'http_request':
       return { config: { method: 'GET' } };
     case 'script':

packages/app-shell/src/views/metadata-admin/previews/simulator/__tests__/flow-simulator.test.ts

@@ -179,11 +179,11 @@ describe('FlowSimulator', () => {
     expect(sim.state.visitedNodeIds).toContain('e');
   });
 
-  it('pauses on a screen node and merges provided outputs on resume', () => {
+  it('pauses on an input-bearing screen and merges provided outputs on resume', () => {
     const sim = new FlowSimulator(
       [
         { id: 's', type: 'start' },
-        { id: 'scr', type: 'screen' },
+        { id: 'scr', type: 'screen', config: { fields: [{ name: 'discount', label: 'Discount' }] } },
         { id: 'e', type: 'end' },
       ],
       [
@@ -200,6 +200,44 @@ describe('FlowSimulator', () => {
     expect(sim.state.status).toBe('done');
   });
 
+  it('passes a field-less screen through without pausing (engine parity)', () => {
+    const sim = new FlowSimulator(
+      [
+        { id: 's', type: 'start' },
+        { id: 'scr', type: 'screen' },
+        { id: 'e', type: 'end' },
+      ],
+      [
+        { source: 's', target: 'scr' },
+        { source: 'scr', target: 'e' },
+      ],
+    );
+    sim.reset();
+    sim.runToEnd();
+    expect(sim.state.status).toBe('done');
+    expect(sim.state.visitedNodeIds).toContain('e');
+    expect(sim.state.steps.find((st) => st.nodeId === 'scr')?.status).toBe('ok');
+  });
+
+  it('applies assignment config (assignments map + {var} interpolation) to variables', () => {
+    const sim = new FlowSimulator(
+      [
+        { id: 's', type: 'start' },
+        { id: 'a', type: 'assignment', config: { assignments: { who: 'Ada', greeting: 'hi {who}' } } },
+        { id: 'e', type: 'end' },
+      ],
+      [
+        { source: 's', target: 'a' },
+        { source: 'a', target: 'e' },
+      ],
+    );
+    sim.reset();
+    sim.runToEnd();
+    expect(sim.state.variables.who).toBe('Ada');
+    expect(sim.state.variables.greeting).toBe('hi Ada');
+    expect(sim.state.status).toBe('done');
+  });
+
   it('guards against infinite loops with a step ceiling', () => {
     const sim = new FlowSimulator(
       [

packages/app-shell/src/views/metadata-admin/previews/simulator/flow-simulator.ts

@@ -28,7 +28,7 @@ import { evalCondition, validateFlowDraft } from './flow-sim-validate';
 
 const MAX_STEPS = 500;
 
-const PASS_THROUGH = new Set(['start', 'assignment']);
+const PASS_THROUGH = new Set(['start']);
 const MOCKED_SIDE_EFFECT = new Set([
   'create_record',
   'update_record',
@@ -161,6 +161,8 @@ export class FlowSimulator {
 
     if (type === 'decision') return this.executeDecision(node);
 
+    if (type === 'assignment') return this.executeAssignment(node);
+
     if (UNSUPPORTED.has(type)) {
       this.enqueueSuccessors(node);
       return this.record(node.id, type, node.label, 'skipped', {
@@ -182,9 +184,19 @@ export class FlowSimulator {
     }
 
     if (type === 'screen') {
-      this.state.status = 'paused';
-      this.state.pausedReason = 'screen';
-      return this.record(node.id, type, node.label, 'paused', { note: 'Screen reached — provide inputs, then continue.' });
+      // Mirror the engine's `shouldPause`: a screen suspends only when it
+      // collects input (`fields`) or explicitly opts in (`waitForInput`).
+      // A field-less / `waitForInput:false` screen is a server pass-through.
+      const fields = Array.isArray(node.config?.fields) ? (node.config!.fields as unknown[]) : [];
+      const waitForInput = node.config?.waitForInput;
+      const shouldPause = waitForInput === true || (fields.length > 0 && waitForInput !== false);
+      if (shouldPause) {
+        this.state.status = 'paused';
+        this.state.pausedReason = 'screen';
+        return this.record(node.id, type, node.label, 'paused', { note: 'Screen reached — provide inputs, then continue.' });
+      }
+      this.enqueueSuccessors(node);
+      return this.record(node.id, type, node.label, 'ok', { note: 'Screen has no input — passed through (matches runtime).' });
     }
 
     if (type === 'loop') {
@@ -251,6 +263,57 @@ export class FlowSimulator {
     });
   }
 
+  /**
+   * assignment node — set flow variables. Normalizes the three authoring
+   * shapes the engine accepts (Studio's `{ assignments: { var: value } }`
+   * map, the example `{ assignments: [{ variable, value }] }` array, and the
+   * legacy flat `{ var: value }`) and interpolates `{var}` templates — so the
+   * Debug run mirrors runtime instead of silently no-oping.
+   */
+  private executeAssignment(node: SimNode): SimStep {
+    const cfg = node.config ?? {};
+    const raw = cfg.assignments;
+    const pairs: Array<[string, unknown]> = [];
+    if (Array.isArray(raw)) {
+      for (const item of raw) {
+        if (item && typeof item === 'object') {
+          const e = item as Record<string, unknown>;
+          const name = e.variable ?? e.name ?? e.key;
+          if (typeof name === 'string' && name) pairs.push([name, e.value]);
+        }
+      }
+    } else if (raw && typeof raw === 'object') {
+      for (const [k, v] of Object.entries(raw as Record<string, unknown>)) pairs.push([k, v]);
+    } else {
+      for (const [k, v] of Object.entries(cfg)) pairs.push([k, v]);
+    }
+    const wrote: Record<string, unknown> = {};
+    for (const [key, value] of pairs) {
+      const resolved = this.interpolateValue(value);
+      this.state.variables[key] = resolved;
+      wrote[key] = resolved;
+    }
+    this.enqueueSuccessors(node);
+    return this.record(node.id, 'assignment', node.label, 'ok', {
+      wrote: Object.keys(wrote).length ? wrote : undefined,
+      note: Object.keys(wrote).length ? undefined : 'No assignments defined.',
+    });
+  }
+
+  /** Resolve `{var}` templates in an assignment value against live variables. */
+  private interpolateValue(value: unknown): unknown {
+    if (typeof value !== 'string') return value;
+    const whole = value.match(/^\{([^}]+)\}$/);
+    if (whole) {
+      const v = this.state.variables[whole[1].trim()];
+      return v !== undefined ? v : value;
+    }
+    return value.replace(/\{([^}]+)\}/g, (_m, k) => {
+      const v = this.state.variables[String(k).trim()];
+      return v === undefined || v === null ? '' : String(v);
+    });
+  }
+
   private executeLoop(node: SimNode): SimStep {
     const ref = str(node.config?.collection);
     const iterVar = str(node.config?.iteratorVariable);