Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

23.9 KB
Raw Blame
/**
 * Pure conversion between the tinyflows `WorkflowGraph` wire model
 * (`./types.ts`) and `@xyflow/react`'s `Node`/`Edge` shapes, plus a
 * dependency-free auto-layout for graphs saved without canvas positions.
 *
 * No React here — kept pure so it's trivially unit-testable and reusable by
 * both the read-only canvas (issue B5b.1, `FlowCanvas.tsx`) and the future
 * editable canvas (B5b.2+, which will call `xyflowToWorkflowGraph` on save).
 *
 * Deviation from the B5b.1 plan sketch: `autoLayout` takes `(nodes, edges)`,
 * not `(nodes)` alone. A BFS-from-trigger layer assignment is only
 * meaningful with the edges to walk — a node-only signature would have
 * nothing to traverse and could only ever produce a flat single row.
 */
import type { Edge, Node } from '@xyflow/react';
import createDebug from 'debug';

import type { NodeKind, Port, WorkflowEdge, WorkflowGraph, WorkflowNode } from './types';

const log = createDebug('flows:graphAdapter');

/** The `nodeTypes` key every flow node renders as (see `FlowCanvas.tsx`). */
export const FLOW_NODE_TYPE = 'flowNode';

/**
 * Data carried by every xyflow node's `data` prop. Beyond the raw `kind` /
 * `name` / `config` / `ports` the plan calls for, this also carries the
 * *effective* input/output port names — computed from a union of the node's
 * declared `ports` (output-only, per `types.ts`'s module doc) and whatever
 * port names its edges actually reference — since a `switch` node's live
 * case ports are computed at runtime from config and are not guaranteed to
 * be declared in `ports` at all. `FlowNodeComponent` renders one `Handle`
 * per entry so no wired connection is ever left dangling with no handle to
 * land on.
 */
export interface FlowNodeData extends Record<string, unknown> {
  kind: NodeKind;
  /** `Node.type_version` — carried through so `xyflowToWorkflowGraph` doesn't
   * silently downgrade a node saved with a non-default config version. */
  type_version?: number;
  name: string;
  config: Record<string, unknown>;
  ports: Port[];
  /** Effective input port names, derived from incoming edges (`['main']` if none). */
  inputPorts: string[];
  /** Effective output port names: declared `ports` ∪ outgoing edges' `from_port` (`['main']` if neither). */
  outputPorts: string[];
}

export type FlowNode = Node<FlowNodeData>;
export type FlowEdge = Edge;

interface Point {
  x: number;
  y: number;
}

const DEFAULT_PORT = 'main';
// Sized against the node card, which is 224px wide and ~76px tall (title band
// + summary): 240 leaves a 16px gutter between siblings, and 132 leaves ~56px
// of visible edge between layers — enough for the drop plus a `condition`'s
// `true` / `false` labels, which hang ~20px below their card. These were 280 /
// 160, set when the card was 264px wide and its ports sat on the left and
// right edges.
const LAYOUT_COLUMN_WIDTH = 240;
const LAYOUT_ROW_HEIGHT = 132;

/**
 * Stable, collision-free xyflow edge id for one `WorkflowEdge`. Node ids and
 * port names are free-form strings that may themselves contain `-`, so a
 * plain `${a}-${b}-${c}-${d}` join can collide (e.g. node `"a-b"`/port `"c"`
 * targeting node `"d"`/port `"e"` produces the same joined string as node
 * `"a"`/port `"b-c"` targeting the same target) — and React Flow requires
 * every edge id to be unique. `JSON.stringify` on the 4-tuple escapes any
 * embedded delimiter-like characters and round-trips distinct tuples to
 * distinct strings.
 */
export function edgeId(edge: WorkflowEdge): string {
  return JSON.stringify([edge.from_node, edge.from_port, edge.to_node, edge.to_port]);
}

/** Unique, order-preserving string list. */
function dedupe(values: string[]): string[] {
  return Array.from(new Set(values));
}

/**
 * Effective input port names for `node`: every distinct `to_port` an edge
 * uses to target it, defaulting to `['main']` when nothing targets it (the
 * common case — a plain single-input node, or a trigger with no input at
 * all, still gets a default handle so the canvas reads consistently).
 */
function effectiveInputPorts(node: WorkflowNode, edges: WorkflowEdge[]): string[] {
  const wired = edges.filter(e => e.to_node === node.id).map(e => e.to_port || DEFAULT_PORT);
  return wired.length > 0 ? dedupe(wired) : [DEFAULT_PORT];
}

/**
 * Effective output port names for `node`: the union of its declared `ports`
 * (output-only per the tinyflows model) and every distinct `from_port` an
 * edge uses leaving it — covering dynamically-cased nodes (e.g. `switch`)
 * whose live ports aren't necessarily declared. Defaults to `['main']` when
 * neither source yields anything.
 */
function effectiveOutputPorts(node: WorkflowNode, edges: WorkflowEdge[]): string[] {
  const declared = node.ports.map(p => p.name);
  const wired = edges.filter(e => e.from_node === node.id).map(e => e.from_port || DEFAULT_PORT);
  const combined = dedupe([...declared, ...wired]);
  return combined.length > 0 ? combined : [DEFAULT_PORT];
}

/**
 * Converts a `WorkflowGraph` into xyflow's `{ nodes, edges }` shape for
 * read-only rendering. Nodes missing a saved `position` are laid out via
 * {@link autoLayout} (BFS depth from the trigger). Edge ids/handles are
 * derived directly from the graph's `from_node`/`from_port`/`to_node`/`to_port`.
 */
export function workflowGraphToXyflow(graph: WorkflowGraph): {
  nodes: FlowNode[];
  edges: FlowEdge[];
} {
  log('workflowGraphToXyflow: nodes=%d edges=%d', graph.nodes.length, graph.edges.length);

  const laidOut = autoLayout(graph.nodes, graph.edges);

  const nodes: FlowNode[] = graph.nodes.map(node => {
    const position = node.position ?? laidOut.get(node.id) ?? { x: 0, y: 0 };
    return {
      id: node.id,
      type: FLOW_NODE_TYPE,
      position,
      data: {
        kind: node.kind,
        type_version: node.type_version,
        name: node.name,
        config: node.config ?? {},
        ports: node.ports,
        inputPorts: effectiveInputPorts(node, graph.edges),
        outputPorts: effectiveOutputPorts(node, graph.edges),
      },
    };
  });

  const edges: FlowEdge[] = graph.edges.map(edge => ({
    id: edgeId(edge),
    source: edge.from_node,
    target: edge.to_node,
    sourceHandle: edge.from_port,
    targetHandle: edge.to_port,
  }));

  log(
    'workflowGraphToXyflow: produced %d xyflow nodes, %d xyflow edges',
    nodes.length,
    edges.length
  );
  return { nodes, edges };
}

/**
 * A React-Flow connection candidate (what `onConnect` / `isValidConnection`
 * receive). `sourceHandle`/`targetHandle` are the `Handle` ids — i.e. the
 * effective port names `FlowNodeComponent` renders — and may be `null` when a
 * node exposes a single unnamed handle, in which case they default to `main`.
 */
interface FlowConnectionCandidate {
  source?: string | null;
  target?: string | null;
  sourceHandle?: string | null;
  targetHandle?: string | null;
}

/**
 * Port-aware validity check for a candidate connection on the editable canvas.
 * Rejects (returns `false`) when:
 *  - either endpoint is missing;
 *  - the connection is a self-loop (`source === target`) — tinyflows graphs
 *    are DAG-ish and a node wiring to itself is never meaningful here;
 *  - either endpoint node isn't in `nodes`;
 *  - the source handle isn't one of the source node's effective *output*
 *    ports, or the target handle isn't one of the target node's effective
 *    *input* ports (reusing the same `inputPorts`/`outputPorts` the canvas
 *    already derived in {@link workflowGraphToXyflow} / {@link createFlowNode});
 *  - an identical edge (same 4-tuple) already exists in `edges` — React Flow
 *    would happily add a duplicate otherwise.
 *
 * Pure and dependency-free so both `<ReactFlow isValidConnection>` (live drag
 * feedback) and `onConnect` (the commit) can share one source of truth, and so
 * it's trivially unit-testable.
 */
export function isValidFlowConnection(
  connection: FlowConnectionCandidate,
  nodes: FlowNode[],
  edges: FlowEdge[] = []
): boolean {
  const { source, target } = connection;
  if (!source || !target) {
    log('isValidFlowConnection: reject — missing endpoint');
    return false;
  }
  if (source === target) {
    log('isValidFlowConnection: reject — self-loop on %s', source);
    return false;
  }
  const sourceNode = nodes.find(n => n.id === source);
  const targetNode = nodes.find(n => n.id === target);
  if (!sourceNode || !targetNode) {
    log('isValidFlowConnection: reject — endpoint node not found');
    return false;
  }
  const sourceHandle = connection.sourceHandle || DEFAULT_PORT;
  const targetHandle = connection.targetHandle || DEFAULT_PORT;
  if (!sourceNode.data.outputPorts.includes(sourceHandle)) {
    log('isValidFlowConnection: reject — %s has no output port %s', source, sourceHandle);
    return false;
  }
  if (!targetNode.data.inputPorts.includes(targetHandle)) {
    log('isValidFlowConnection: reject — %s has no input port %s', target, targetHandle);
    return false;
  }
  const duplicate = edges.some(
    e =>
      e.source === source &&
      e.target === target &&
      (e.sourceHandle || DEFAULT_PORT) === sourceHandle &&
      (e.targetHandle || DEFAULT_PORT) === targetHandle
  );
  if (duplicate) {
    log('isValidFlowConnection: reject — duplicate edge');
    return false;
  }
  return true;
}

/**
 * Stable {@link edgeId} for a live React Flow `Connection` candidate (what
 * `onConnect` receives once {@link isValidFlowConnection} has approved it),
 * applying the same `main` port default used throughout this module.
 *
 * `EditableFlowCanvas`'s `onConnect` must pass this to `addEdge` explicitly —
 * left to its own default, `addEdge` mints React Flow's built-in
 * `${source}${sourceHandle}-${target}${targetHandle}` id, which is exactly
 * the plain-concatenation scheme {@link edgeId} exists to avoid (see its
 * doc). Without this, an edge created by drawing a connection on the canvas
 * gets a different id than the same edge would get after a reload (which
 * goes through {@link workflowGraphToXyflow} → {@link edgeId}), and two
 * connections that collide under plain concatenation would produce duplicate
 * React keys.
 */
export function connectionEdgeId(connection: FlowConnectionCandidate): string {
  return edgeId({
    from_node: connection.source ?? '',
    from_port: connection.sourceHandle || DEFAULT_PORT,
    to_node: connection.target ?? '',
    to_port: connection.targetHandle || DEFAULT_PORT,
  });
}

/**
 * Declared output `ports` a freshly-added node of `kind` needs at creation
 * time, for kinds whose runtime routing is fixed and NOT derivable from
 * config or wired edges. A `condition` node always routes through `true`/
 * `false` (`vendor/tinyflows/src/nodes/control_flow/condition.rs`), but the
 * config drawer has no port editor — so unlike `switch` (whose case ports
 * are config-driven and materialize once the author wires an edge, per
 * {@link effectiveOutputPorts}'s doc comment), a new `condition` node must be
 * seeded with both ports up front or its second branch is never wireable
 * from the canvas. A `loop` node is the same shape: it always routes through
 * `body`/`done` (`vendor/tinyflows/src/nodes/control_flow/loop_node.rs`), and
 * the canvas has no port editor to derive them from later — without seeding
 * both here, a palette-added loop renders a single `main` output and neither
 * required loop edge (back to the loop head, and onward past it) can be
 * wired.
 */
function defaultPortsForKind(kind: NodeKind): Port[] {
  if (kind === 'condition') {
    return [{ name: 'true' }, { name: 'false' }];
  }
  if (kind === 'loop') {
    return [{ name: 'body' }, { name: 'done' }];
  }
  return [];
}

/**
 * Build a fresh xyflow node for a palette-added `kind` at `position`. Newly
 * dropped nodes start with a single default `main` input handle (no wired
 * edges yet) plus whatever {@link defaultPortsForKind} declares for `kind` —
 * empty for most kinds, which fall back to the single default `main` output
 * handle exactly as {@link effectiveInputPorts}/{@link effectiveOutputPorts}
 * would derive for a node with no edges yet — so it round-trips cleanly
 * through {@link xyflowToWorkflowGraph} and immediately accepts connections.
 * `id` must be unique within the canvas; `name` defaults to `kind` when
 * omitted.
 */
export function createFlowNode(
  kind: NodeKind,
  position: Point,
  id: string,
  name?: string
): FlowNode {
  const ports = defaultPortsForKind(kind);
  const outputPorts = ports.length > 0 ? ports.map(p => p.name) : [DEFAULT_PORT];
  return {
    id,
    type: FLOW_NODE_TYPE,
    position,
    data: { kind, name: name ?? kind, config: {}, ports, inputPorts: [DEFAULT_PORT], outputPorts },
  };
}

/** Metadata not carried by xyflow nodes/edges, needed to reassemble a full `WorkflowGraph`. */
export interface WorkflowGraphMeta {
  schema_version: number;
  id?: string | null;
  name: string;
}

/**
 * Reverses {@link workflowGraphToXyflow}: reassembles a `WorkflowGraph` from
 * xyflow's `nodes`/`edges` plus the graph-level metadata xyflow doesn't
 * carry (`schema_version`/`id`/`name`). Defined now — read-only B5b.1 has no
 * editor UI to call it from yet — so it's co-located with its inverse ahead
 * of B5b.4's save path, and so its round-trip behavior is locked in by tests
 * from day one.
 *
 * Every field `workflowGraphToXyflow` carries over from the source
 * `WorkflowNode` — including `type_version` — round-trips back out here;
 * `node.position` always comes out concrete (never `undefined`) since by the
 * time a node exists on an editable canvas it has a real position, which
 * matches a freshly-authored node too. `inputPorts`/`outputPorts` are
 * canvas-only derived fields (see `FlowNodeData`'s doc comment) and are
 * intentionally not written back — only the *declared* `ports` round-trip.
 */
export function xyflowToWorkflowGraph(
  nodes: FlowNode[],
  edges: FlowEdge[],
  meta: WorkflowGraphMeta
): WorkflowGraph {
  const workflowNodes: WorkflowNode[] = nodes.map(node => ({
    id: node.id,
    kind: node.data.kind,
    type_version: node.data.type_version,
    name: node.data.name,
    config: node.data.config,
    ports: node.data.ports,
    position: { x: node.position.x, y: node.position.y },
  }));

  const workflowEdges: WorkflowEdge[] = edges.map(edge => ({
    from_node: edge.source,
    from_port: edge.sourceHandle ?? DEFAULT_PORT,
    to_node: edge.target,
    to_port: edge.targetHandle ?? DEFAULT_PORT,
  }));

  return {
    schema_version: meta.schema_version,
    id: meta.id,
    name: meta.name,
    nodes: workflowNodes,
    edges: workflowEdges,
  };
}

/**
 * Round-trips `graph` through {@link workflowGraphToXyflow} /
 * {@link xyflowToWorkflowGraph} — the exact conversion the editable canvas
 * itself performs on mount — so a caller comparing `graph` against a LATER
 * canvas serialization (to decide "is this dirty?") compares like with like.
 *
 * F-m3 fix: a graph saved without per-node `position` (e.g. authored by the
 * agent, which never sets one) gets concrete auto-layout coordinates baked in
 * the moment the canvas mounts it (`workflowGraphToXyflow`'s `autoLayout`
 * fallback) — `EditableFlowCanvas`'s mount-time `onGraphChange` reports that
 * position-filled graph immediately. A dirty check that diffs the canvas's
 * report against the RAW, positionless server graph reads that fill-in as an
 * edit and shows "Unsaved" with zero real changes. Normalizing the baseline
 * through this same round-trip before comparing eliminates that false
 * positive, since both sides then agree on where every node landed.
 */
export function normalizeWorkflowGraphForDirtyCheck(
  graph: WorkflowGraph,
  meta: WorkflowGraphMeta
): WorkflowGraph {
  const { nodes, edges } = workflowGraphToXyflow(graph);
  return xyflowToWorkflowGraph(nodes, edges, meta);
}

/**
 * Assigns a `{x, y}` position to every node in `nodes`, via a simple BFS
 * layering over `edges`: `y = depth * 132`, `x = column * 240` where
 * `column` is the node's index within its depth layer (assigned in
 * declaration order). Roots are nodes with no incoming edge (normally just
 * the trigger); disconnected sub-graphs and cycles still terminate — any
 * node the BFS doesn't reach is appended one layer past the deepest reached
 * node, so nothing is ever silently dropped. No extra dependency (no
 * `dagre`) — good enough for a read-only first render; a real editor can
 * offer manual repositioning later.
 *
 * Returns a `Map<nodeId, Point>` for every node passed in (not just the ones
 * missing a saved position), so callers can use it as a uniform fallback
 * source; `workflowGraphToXyflow` only consults it for nodes lacking
 * `position`.
 */
export function autoLayout(nodes: WorkflowNode[], edges: WorkflowEdge[]): Map<string, Point> {
  const positions = new Map<string, Point>();
  if (nodes.length === 0) return positions;

  const nodeIds = new Set(nodes.map(n => n.id));
  const incoming = new Map<string, number>(nodes.map(n => [n.id, 0]));
  const adjacency = new Map<string, string[]>(nodes.map(n => [n.id, []]));

  for (const edge of edges) {
    // Ignore edges referencing ids outside this node set — defensive only;
    // a validated graph never has these, but layout should never throw.
    if (!nodeIds.has(edge.from_node) || !nodeIds.has(edge.to_node)) continue;
    adjacency.get(edge.from_node)?.push(edge.to_node);
    incoming.set(edge.to_node, (incoming.get(edge.to_node) ?? 0) + 1);
  }

  // Roots: nodes with no incoming edge (usually just the trigger), in
  // declaration order for determinism. Falls back to every node if the
  // graph has no such root (a cycle, or every node has an incoming edge).
  const roots = nodes.filter(n => (incoming.get(n.id) ?? 0) === 0);
  const startIds = (roots.length > 0 ? roots : nodes).map(n => n.id);

  const depth = new Map<string, number>();
  const queue: string[] = [];
  for (const id of startIds) {
    if (depth.has(id)) continue;
    depth.set(id, 0);
    queue.push(id);
  }

  let head = 0;
  while (head < queue.length) {
    const id = queue[head++];
    const currentDepth = depth.get(id) ?? 0;
    for (const nextId of adjacency.get(id) ?? []) {
      if (depth.has(nextId)) continue;
      depth.set(nextId, currentDepth + 1);
      queue.push(nextId);
    }
  }

  // Any node unreached by the BFS (disconnected sub-graph, or a cycle with
  // no zero-in-degree entry point) still gets a depth so it renders
  // somewhere rather than being silently dropped.
  let maxDepth = 0;
  for (const d of depth.values()) maxDepth = Math.max(maxDepth, d);
  for (const node of nodes) {
    if (!depth.has(node.id)) depth.set(node.id, ++maxDepth);
  }

  const columnByDepth = new Map<number, number>();
  for (const node of nodes) {
    const d = depth.get(node.id) ?? 0;
    const column = columnByDepth.get(d) ?? 0;
    columnByDepth.set(d, column + 1);
    positions.set(node.id, { x: column * LAYOUT_COLUMN_WIDTH, y: d * LAYOUT_ROW_HEIGHT });
  }

  return positions;
}

/**
 * Assigns each node a 1-based execution-order index for display ("3. Fetch
 * Unread Emails").
 *
 * Uses the same breadth-first walk as {@link autoLayout} — chain-starting roots
 * (no incoming edge but at least one outgoing, normally just the trigger)
 * first, then each successor as it is reached — so a card's number always
 * agrees with its position in the laid-out graph rather than with declaration
 * order, which is arbitrary for a graph the agent authored.
 *
 * A DAG has no single "correct" ordering once it branches: two parallel
 * branches genuinely run concurrently, so any numbering imposes an order that
 * execution does not guarantee. BFS is chosen because it numbers breadth-first
 * across a fan-out (both branches' first steps get adjacent numbers) rather
 * than running one branch to its end before starting the next, which is what a
 * depth-first walk would do and reads as wrong beside a two-column layout.
 *
 * Independent chains are kept contiguous rather than interleaved: each root's
 * component is drained completely before the next root is seeded. Otherwise
 * `a → b` plus `c → d` would number a=1, c=2, b=3, d=4, and drawing a second
 * chain would renumber the first one's steps.
 *
 * Every node gets a number, including ones the walk cannot reach — a node not
 * yet wired up, or a cycle with no zero-in-degree entry. Those are appended in
 * declaration order after the reachable ones, so no card renders without an
 * index and, crucially, adding disconnected work to the canvas never renumbers
 * the flow it has not joined yet.
 */
export function stepNumbers(nodes: WorkflowNode[], edges: WorkflowEdge[]): Map<string, number> {
  return stepNumbersFor(
    nodes.map(n => n.id),
    edges.map(e => [e.from_node, e.to_node])
  );
}

/**
 * {@link stepNumbers} for the xyflow shape — the live editing state.
 *
 * The editable canvas holds its graph in `useNodesState`/`useEdgesState` and
 * mutates it directly (`addNode` builds a node with `createFlowNode`,
 * `onConnect` only calls `setEdges`), so `workflowGraphToXyflow` runs once at
 * mount and never again. Numbering must therefore be derived from the live
 * arrays on every change rather than baked into node `data` at adapt time — a
 * node added mid-edit has no adapter-supplied number at all, and every existing
 * number goes stale the moment the topology changes.
 */
export function stepNumbersForFlow(nodes: FlowNode[], edges: FlowEdge[]): Map<string, number> {
  return stepNumbersFor(
    nodes.map(n => n.id),
    edges.map(e => [e.source, e.target])
  );
}

/**
 * Shared BFS behind both public entry points, over bare ids and `[from, to]`
 * pairs so the two graph shapes cannot drift in ordering behaviour.
 */
function stepNumbersFor(ids: string[], pairs: Array<[string, string]>): Map<string, number> {
  const order = new Map<string, number>();
  if (ids.length === 0) return order;

  const known = new Set(ids);
  const incoming = new Map<string, number>(ids.map(id => [id, 0]));
  const adjacency = new Map<string, string[]>(ids.map(id => [id, []]));
  for (const [from, to] of pairs) {
    if (!known.has(from) || !known.has(to)) continue;
    adjacency.get(from)?.push(to);
    incoming.set(to, (incoming.get(to) ?? 0) + 1);
  }

  // Seed only with roots that actually start a chain — in-degree 0 AND at
  // least one outgoing edge. A node with no edges at all is *not* step 2 just
  // because it has no incoming one: on the editable canvas a node dropped from
  // the palette is unwired for as long as it takes to connect it, and seeding
  // it as a root would renumber the entire flow underneath the user each time
  // they added one. Such nodes fall through to the trailing pass below and are
  // numbered after the wired flow instead.
  const roots = ids.filter(
    id => (incoming.get(id) ?? 0) === 0 && (adjacency.get(id)?.length ?? 0) > 0
  );

  const seen = new Set<string>();
  let next = 1;

  // One component at a time: drain each root's BFS completely before seeding
  // the next. Seeding every root at once would interleave independent chains —
  // for `a → b` and `c → d` that yields a=1, c=2, b=3, d=4, so drawing a second
  // chain on the canvas renumbers the first one's steps. That is the same
  // renumbering-underneath-the-user problem the root filter above avoids for
  // lone nodes, and it would contradict this function's contract that
  // disconnected work is numbered *after* the flow it has not joined.
  //
  // BFS still applies *within* a component, so a fan-out's sibling branches
  // keep adjacent numbers; only whole components are kept contiguous.
  for (const root of roots) {
    if (seen.has(root)) continue;
    const queue: string[] = [root];
    seen.add(root);
    let head = 0;
    while (head < queue.length) {
      const id = queue[head++];
      order.set(id, next++);
      for (const nextId of adjacency.get(id) ?? []) {
        if (seen.has(nextId)) continue;
        seen.add(nextId);
        queue.push(nextId);
      }
    }
  }

  // Everything the walk never reached: unwired nodes, disconnected sub-graphs,
  // and cycles with no zero-in-degree entry. Numbered in declaration order so
  // every card still shows an index.
  for (const id of ids) {
    if (!order.has(id)) order.set(id, next++);
  }
  return order;
}