@stigmer/react 1.0.4 → 2.0.1

package/src/workflow/kind-metadata.ts

@@ -0,0 +1,108 @@
+import type { TopologyNodeCategory } from "./useWorkflowTopology";
+
+/**
+ * Canonical kind → category mapping, aligned with sidecar YAML metadata
+ * in `apis/ai/stigmer/agentic/workflow/v1/tasks/meta/*.yaml`.
+ *
+ * This is the single source of truth for client-side category classification.
+ * When the API registry is loaded, prefer `descriptor.category` from the
+ * registry; this map serves as a reliable fallback during loading or for
+ * offline rendering.
+ */
+const CATEGORY_FOR_KIND: ReadonlyMap<string, TopologyNodeCategory> = new Map([
+  // ai
+  ["agent_call", "ai"],
+  ["llm_call", "ai"],
+  ["eval", "ai"],
+
+  // control_flow
+  ["switch_case", "control_flow"],
+  ["for_each", "control_flow"],
+  ["fork", "control_flow"],
+  ["try_catch", "control_flow"],
+  ["wait", "control_flow"],
+
+  // invocation
+  ["http_call", "invocation"],
+  ["grpc_call", "invocation"],
+  ["activity_call", "invocation"],
+  ["run_workflow", "invocation"],
+
+  // data
+  ["set_vars", "data"],
+  ["transform", "data"],
+  ["validate", "data"],
+
+  // governance
+  ["human_input", "governance"],
+
+  // event
+  ["listen", "event"],
+  ["emit_event", "event"],
+  ["notification", "event"],
+  ["raise_error", "event"],
+]);
+
+/**
+ * Canonical kind → display name mapping, aligned with sidecar YAML
+ * `display_name` values.
+ *
+ * Used as a static fallback when the API registry is not yet loaded.
+ * When the registry is available, prefer `descriptor.displayName`.
+ */
+const DISPLAY_NAME_FOR_KIND: ReadonlyMap<string, string> = new Map([
+  ["set_vars", "Set Variables"],
+  ["http_call", "HTTP Call"],
+  ["grpc_call", "gRPC Call"],
+  ["activity_call", "Activity Call"],
+  ["switch_case", "Switch Case"],
+  ["for_each", "For Each"],
+  ["fork", "Fork"],
+  ["try_catch", "Try/Catch"],
+  ["listen", "Listen"],
+  ["wait", "Wait"],
+  ["raise_error", "Raise Error"],
+  ["run_workflow", "Run Workflow"],
+  ["agent_call", "Agent Call"],
+  ["llm_call", "LLM Call"],
+  ["transform", "Transform"],
+  ["human_input", "Human Input"],
+  ["validate", "Validate"],
+  ["emit_event", "Emit Event"],
+  ["notification", "Notification"],
+  ["eval", "Evaluate (LLM Judge)"],
+]);
+
+/**
+ * Returns the functional category for a given task kind string.
+ *
+ * Replaces the three duplicated `categorizeKind` implementations that
+ * previously existed in `workflow-graph-conversions.ts`,
+ * `useWorkflowTopology.ts`, and `topologyFromTasks.ts`.
+ *
+ * Categories align with the proto `TaskKindCategory` enum and the
+ * sidecar YAML `category` field — not the drifted client-side Sets
+ * that previously classified `validate` as `governance` and `wait`
+ * as `event`.
+ */
+export function categorizeKind(kind: string): TopologyNodeCategory {
+  return CATEGORY_FOR_KIND.get(kind) ?? "unspecified";
+}
+
+/**
+ * Returns the human-readable display name for a task kind.
+ *
+ * Falls back to title-casing the kind string (e.g. `"my_task"` →
+ * `"My Task"`) for unknown kinds, ensuring a reasonable label is
+ * always available even before the API registry loads.
+ */
+export function kindToDisplayName(kind: string): string {
+  return DISPLAY_NAME_FOR_KIND.get(kind) ?? titleCaseKind(kind);
+}
+
+function titleCaseKind(kind: string): string {
+  return kind
+    .split("_")
+    .map((w) => (w.length === 0 ? "" : w[0].toUpperCase() + w.slice(1)))
+    .join(" ");
+}

package/src/workflow/layout/__tests__/dagre-layout-engine.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "vitest";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
+import type { WorkflowGraphModel, WorkflowGraphNode, WorkflowGraphEdge } from "../../workflow-graph-model";
+import { START_NODE_ID, END_NODE_ID } from "../../workflow-graph-model";
+import { createDagreLayoutEngine } from "../dagre-layout-engine";
+
+function makeLinearGraph(count: number): WorkflowGraphModel {
+  const nodes: WorkflowGraphNode[] = [
+    {
+      id: START_NODE_ID,
+      taskName: "Start",
+      kind: WorkflowTaskKind.workflow_task_kind_unspecified,
+      category: "start",
+      config: {} as JsonObject,
+      position: { x: 0, y: 0 },
+    },
+  ];
+
+  const edges: WorkflowGraphEdge[] = [];
+
+  let prev: string = START_NODE_ID;
+  for (let i = 0; i < count; i++) {
+    const id = `task_${i}`;
+    nodes.push({
+      id,
+      taskName: id,
+      kind: WorkflowTaskKind.http_call,
+      category: "invocation",
+      config: {} as JsonObject,
+      position: { x: 0, y: 0 },
+    });
+    edges.push({ id: `e_${prev}_${id}`, source: prev, target: id });
+    prev = id;
+  }
+
+  nodes.push({
+    id: END_NODE_ID,
+    taskName: "End",
+    kind: WorkflowTaskKind.workflow_task_kind_unspecified,
+    category: "end",
+    config: {} as JsonObject,
+    position: { x: 0, y: 0 },
+  });
+  edges.push({ id: `e_${prev}_end`, source: prev, target: END_NODE_ID });
+
+  return {
+    document: { dsl: "1.0.0", namespace: "", name: "test", version: "0.0.1" },
+    nodes,
+    edges,
+  };
+}
+
+describe("dagre-layout-engine", () => {
+  it("produces positions for all nodes in a linear graph", async () => {
+    const engine = createDagreLayoutEngine();
+    const graph = makeLinearGraph(5);
+
+    const result = await engine.layout({ graph, scope: { type: "whole-graph" } });
+
+    expect(result.positions.size).toBe(7); // start + 5 tasks + end
+    expect(result.engine).toBe("dagre");
+    expect(result.durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("produces no overlapping nodes", async () => {
+    const engine = createDagreLayoutEngine();
+    const graph = makeLinearGraph(10);
+
+    const result = await engine.layout({ graph, scope: { type: "whole-graph" } });
+
+    const positions = Array.from(result.positions.entries()).map(([id, pos]) => ({
+      id,
+      ...pos,
+      width: 220,
+      height: 56,
+    }));
+
+    for (let i = 0; i < positions.length; i++) {
+      for (let j = i + 1; j < positions.length; j++) {
+        const a = positions[i];
+        const b = positions[j];
+        const overlapX = a.x < b.x + b.width && a.x + a.width > b.x;
+        const overlapY = a.y < b.y + b.height && a.y + a.height > b.y;
+        expect(
+          overlapX && overlapY,
+          `Nodes "${a.id}" and "${b.id}" overlap`,
+        ).toBe(false);
+      }
+    }
+  });
+
+  it("is deterministic (two runs produce identical results)", async () => {
+    const engine = createDagreLayoutEngine();
+    const graph = makeLinearGraph(5);
+
+    const result1 = await engine.layout({ graph, scope: { type: "whole-graph" } });
+    const result2 = await engine.layout({ graph, scope: { type: "whole-graph" } });
+
+    for (const [id, pos1] of result1.positions) {
+      const pos2 = result2.positions.get(id);
+      expect(pos2).toBeDefined();
+      expect(pos1.x).toBeCloseTo(pos2!.x, 5);
+      expect(pos1.y).toBeCloseTo(pos2!.y, 5);
+    }
+  });
+
+  it("respects custom node dimensions via vertical spacing", async () => {
+    const engine = createDagreLayoutEngine();
+    const graph = makeLinearGraph(3);
+
+    const small = await engine.layout({
+      graph,
+      scope: { type: "whole-graph" },
+      getNodeDimensions: () => ({ width: 100, height: 30 }),
+    });
+    const large = await engine.layout({
+      graph,
+      scope: { type: "whole-graph" },
+      getNodeDimensions: () => ({ width: 400, height: 100 }),
+    });
+
+    const smallGap = small.positions.get("task_1")!.y - small.positions.get("task_0")!.y;
+    const largeGap = large.positions.get("task_1")!.y - large.positions.get("task_0")!.y;
+    expect(largeGap).toBeGreaterThan(smallGap);
+  });
+});

package/src/workflow/layout/__tests__/layout-postprocessor.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from "vitest";
+import type { WorkflowGraphModel, WorkflowGraphEdge } from "../../workflow-graph-model";
+import { START_NODE_ID, END_NODE_ID } from "../../workflow-graph-model";
+import type { ElkLayoutResult, LayoutScope } from "../types";
+import { postprocessElkResult } from "../layout-postprocessor";
+
+function makeGraph(nodeIds: string[], edges: WorkflowGraphEdge[] = []): WorkflowGraphModel {
+  return {
+    document: { dsl: "1.0.0", namespace: "", name: "test", version: "0.0.1" },
+    nodes: nodeIds.map((id) => ({
+      id,
+      taskName: id,
+      kind: 0 as any,
+      category: "unspecified" as const,
+      config: {} as any,
+      position: { x: 0, y: 0 },
+    })),
+    edges,
+  };
+}
+
+function makeElkResult(positions: Record<string, { x: number; y: number }>): ElkLayoutResult {
+  return {
+    id: "root",
+    children: Object.entries(positions).map(([id, pos]) => ({
+      id,
+      x: pos.x,
+      y: pos.y,
+      width: 220,
+      height: 56,
+    })),
+  };
+}
+
+describe("layout-postprocessor", () => {
+  describe("position extraction", () => {
+    it("maps ELK child positions to result positions", () => {
+      const elkResult = makeElkResult({
+        a: { x: 10, y: 20 },
+        b: { x: 100, y: 200 },
+      });
+      const graph = makeGraph(["a", "b"]);
+
+      const result = postprocessElkResult(elkResult, { type: "whole-graph" }, graph, 5, "elk");
+
+      expect(result.positions.get("a")).toEqual({ x: 10, y: 20 });
+      expect(result.positions.get("b")).toEqual({ x: 100, y: 200 });
+    });
+
+    it("includes duration and engine name", () => {
+      const elkResult = makeElkResult({ a: { x: 0, y: 0 } });
+      const graph = makeGraph(["a"]);
+
+      const result = postprocessElkResult(elkResult, { type: "whole-graph" }, graph, 42, "elk-layered");
+
+      expect(result.durationMs).toBe(42);
+      expect(result.engine).toBe("elk-layered");
+    });
+
+    it("handles empty ELK result gracefully", () => {
+      const elkResult: ElkLayoutResult = { id: "root" };
+      const graph = makeGraph(["a"]);
+
+      const result = postprocessElkResult(elkResult, { type: "whole-graph" }, graph, 1, "elk");
+
+      expect(result.positions.size).toBe(0);
+    });
+  });
+
+  describe("scope: whole-graph", () => {
+    it("includes all node positions", () => {
+      const elkResult = makeElkResult({
+        a: { x: 10, y: 20 },
+        b: { x: 30, y: 40 },
+        c: { x: 50, y: 60 },
+      });
+      const graph = makeGraph(["a", "b", "c"]);
+
+      const result = postprocessElkResult(elkResult, { type: "whole-graph" }, graph, 1, "elk");
+
+      expect(result.positions.size).toBe(3);
+    });
+  });
+
+  describe("scope: selected", () => {
+    it("only includes positions for nodes in the selection set", () => {
+      const elkResult = makeElkResult({
+        a: { x: 10, y: 20 },
+        b: { x: 30, y: 40 },
+        c: { x: 50, y: 60 },
+      });
+      const graph = makeGraph(["a", "b", "c"]);
+      const scope: LayoutScope = { type: "selected", nodeIds: new Set(["a", "c"]) };
+
+      const result = postprocessElkResult(elkResult, scope, graph, 1, "elk");
+
+      expect(result.positions.size).toBe(2);
+      expect(result.positions.has("a")).toBe(true);
+      expect(result.positions.has("b")).toBe(false);
+      expect(result.positions.has("c")).toBe(true);
+    });
+  });
+
+  describe("scope: downstream", () => {
+    it("includes the starting node and all reachable downstream nodes", () => {
+      const edges: WorkflowGraphEdge[] = [
+        { id: "e1", source: "a", target: "b" },
+        { id: "e2", source: "b", target: "c" },
+        { id: "e3", source: "b", target: "d" },
+        { id: "e4", source: "x", target: "y" },
+      ];
+      const elkResult = makeElkResult({
+        a: { x: 0, y: 0 },
+        b: { x: 0, y: 60 },
+        c: { x: -50, y: 120 },
+        d: { x: 50, y: 120 },
+        x: { x: 200, y: 0 },
+        y: { x: 200, y: 60 },
+      });
+      const graph = makeGraph(["a", "b", "c", "d", "x", "y"], edges);
+      const scope: LayoutScope = { type: "downstream", fromNodeId: "b" };
+
+      const result = postprocessElkResult(elkResult, scope, graph, 1, "elk");
+
+      expect(result.positions.has("b")).toBe(true);
+      expect(result.positions.has("c")).toBe(true);
+      expect(result.positions.has("d")).toBe(true);
+      expect(result.positions.has("a")).toBe(false);
+      expect(result.positions.has("x")).toBe(false);
+      expect(result.positions.has("y")).toBe(false);
+    });
+
+    it("handles a node with no downstream neighbors", () => {
+      const edges: WorkflowGraphEdge[] = [{ id: "e1", source: "a", target: "b" }];
+      const elkResult = makeElkResult({
+        a: { x: 0, y: 0 },
+        b: { x: 0, y: 60 },
+      });
+      const graph = makeGraph(["a", "b"], edges);
+      const scope: LayoutScope = { type: "downstream", fromNodeId: "b" };
+
+      const result = postprocessElkResult(elkResult, scope, graph, 1, "elk");
+
+      expect(result.positions.size).toBe(1);
+      expect(result.positions.has("b")).toBe(true);
+    });
+  });
+});

package/src/workflow/layout/__tests__/port-assignment.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "vitest";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
+import type { WorkflowGraphNode, WorkflowGraphEdge } from "../../workflow-graph-model";
+import { computePortAssignments, computeNodePorts } from "../port-assignment";
+import { START_NODE_ID, END_NODE_ID } from "../../workflow-graph-model";
+
+function makeNode(
+  id: string,
+  kind: WorkflowTaskKind,
+  config: Record<string, unknown> = {},
+): WorkflowGraphNode {
+  return {
+    id,
+    taskName: id,
+    kind,
+    category: "unspecified",
+    config: config as JsonObject,
+    position: { x: 0, y: 0 },
+  };
+}
+
+function makeEdge(source: string, target: string, sourceHandle?: string): WorkflowGraphEdge {
+  return {
+    id: `${source}->${target}`,
+    source,
+    target,
+    ...(sourceHandle && { sourceHandle }),
+  };
+}
+
+describe("port-assignment", () => {
+  describe("sentinel nodes", () => {
+    it("__start__ has no input ports and one output port on SOUTH", () => {
+      const node = makeNode(START_NODE_ID, WorkflowTaskKind.workflow_task_kind_unspecified);
+      const result = computeNodePorts(node, []);
+
+      expect(result.inputPorts).toHaveLength(0);
+      expect(result.outputPorts).toHaveLength(1);
+      expect(result.outputPorts[0].id).toBe(`${START_NODE_ID}__out`);
+      expect(result.outputPorts[0].side).toBe("SOUTH");
+    });
+
+    it("__end__ has one input port on NORTH and no output ports", () => {
+      const node = makeNode(END_NODE_ID, WorkflowTaskKind.workflow_task_kind_unspecified);
+      const result = computeNodePorts(node, []);
+
+      expect(result.inputPorts).toHaveLength(1);
+      expect(result.inputPorts[0].id).toBe(`${END_NODE_ID}__in`);
+      expect(result.inputPorts[0].side).toBe("NORTH");
+      expect(result.outputPorts).toHaveLength(0);
+    });
+  });
+
+  describe("default task kinds", () => {
+    it("produces 1 input NORTH and 1 output SOUTH for a regular task", () => {
+      const node = makeNode("my_task", WorkflowTaskKind.http_call);
+      const result = computeNodePorts(node, []);
+
+      expect(result.inputPorts).toHaveLength(1);
+      expect(result.inputPorts[0]).toEqual({ id: "my_task__in", side: "NORTH", index: 0 });
+      expect(result.outputPorts).toHaveLength(1);
+      expect(result.outputPorts[0]).toEqual({ id: "my_task__out", side: "SOUTH", index: 0 });
+    });
+
+    it("produces same result for set_vars, agent_call, llm_call etc.", () => {
+      const kinds = [
+        WorkflowTaskKind.set_vars,
+        WorkflowTaskKind.agent_call,
+        WorkflowTaskKind.llm_call,
+        WorkflowTaskKind.grpc_call,
+        WorkflowTaskKind.transform,
+      ];
+
+      for (const kind of kinds) {
+        const node = makeNode("task", kind);
+        const result = computeNodePorts(node, []);
+        expect(result.outputPorts).toHaveLength(1);
+        expect(result.outputPorts[0].id).toBe("task__out");
+      }
+    });
+  });
+
+  describe("switch_case", () => {
+    it("produces one output port per case, ordered by definition", () => {
+      const node = makeNode("route", WorkflowTaskKind.switch_case, {
+        cases: [
+          { name: "approved", when: "${status == 'ok'}", then: "process" },
+          { name: "rejected", when: "${status == 'bad'}", then: "notify" },
+          { name: "default", then: "fallback" },
+        ],
+      });
+
+      const result = computeNodePorts(node, []);
+
+      expect(result.inputPorts).toHaveLength(1);
+      expect(result.outputPorts).toHaveLength(3);
+      expect(result.outputPorts[0]).toEqual({
+        id: "route__case_approved",
+        side: "SOUTH",
+        index: 0,
+        label: "approved",
+      });
+      expect(result.outputPorts[1]).toEqual({
+        id: "route__case_rejected",
+        side: "SOUTH",
+        index: 1,
+        label: "rejected",
+      });
+      expect(result.outputPorts[2]).toEqual({
+        id: "route__case_default",
+        side: "SOUTH",
+        index: 2,
+        label: "default",
+      });
+    });
+
+    it("falls back to single output when cases array is empty", () => {
+      const node = makeNode("route", WorkflowTaskKind.switch_case, { cases: [] });
+      const result = computeNodePorts(node, []);
+
+      expect(result.outputPorts).toHaveLength(1);
+      expect(result.outputPorts[0].id).toBe("route__out");
+    });
+
+    it("falls back to single output when no config", () => {
+      const node = makeNode("route", WorkflowTaskKind.switch_case);
+      const result = computeNodePorts(node, []);
+
+      expect(result.outputPorts).toHaveLength(1);
+      expect(result.outputPorts[0].id).toBe("route__out");
+    });
+  });
+
+  describe("human_input", () => {
+    it("produces one output port per outcome, ordered by definition", () => {
+      const node = makeNode("approval", WorkflowTaskKind.human_input, {
+        outcomes: [
+          { name: "approve" },
+          { name: "deny" },
+        ],
+      });
+
+      const result = computeNodePorts(node, []);
+
+      expect(result.outputPorts).toHaveLength(2);
+      expect(result.outputPorts[0]).toEqual({
+        id: "approval__outcome_approve",
+        side: "SOUTH",
+        index: 0,
+        label: "approve",
+      });
+      expect(result.outputPorts[1]).toEqual({
+        id: "approval__outcome_deny",
+        side: "SOUTH",
+        index: 1,
+        label: "deny",
+      });
+    });
+  });
+
+  describe("fork", () => {
+    it("produces one output port per outgoing edge", () => {
+      const node = makeNode("split", WorkflowTaskKind.fork);
+      const edges: WorkflowGraphEdge[] = [
+        makeEdge("split", "branch_a"),
+        makeEdge("split", "branch_b"),
+        makeEdge("split", "branch_c"),
+      ];
+
+      const result = computeNodePorts(node, edges);
+
+      expect(result.outputPorts).toHaveLength(3);
+      expect(result.outputPorts[0].id).toBe("split__branch_0");
+      expect(result.outputPorts[1].id).toBe("split__branch_1");
+      expect(result.outputPorts[2].id).toBe("split__branch_2");
+    });
+
+    it("uses sourceHandle from edge when available", () => {
+      const node = makeNode("split", WorkflowTaskKind.fork);
+      const edges: WorkflowGraphEdge[] = [
+        makeEdge("split", "a", "parallel_a"),
+        makeEdge("split", "b", "parallel_b"),
+      ];
+
+      const result = computeNodePorts(node, edges);
+
+      expect(result.outputPorts[0].id).toBe("split__parallel_a");
+      expect(result.outputPorts[1].id).toBe("split__parallel_b");
+    });
+
+    it("falls back to single output when only one outgoing edge", () => {
+      const node = makeNode("split", WorkflowTaskKind.fork);
+      const edges: WorkflowGraphEdge[] = [makeEdge("split", "target")];
+
+      const result = computeNodePorts(node, edges);
+      expect(result.outputPorts).toHaveLength(1);
+      expect(result.outputPorts[0].id).toBe("split__out");
+    });
+  });
+
+  describe("computePortAssignments (batch)", () => {
+    it("returns assignments for all nodes in the graph", () => {
+      const nodes = [
+        makeNode(START_NODE_ID, WorkflowTaskKind.workflow_task_kind_unspecified),
+        makeNode("task_a", WorkflowTaskKind.http_call),
+        makeNode("task_b", WorkflowTaskKind.set_vars),
+        makeNode(END_NODE_ID, WorkflowTaskKind.workflow_task_kind_unspecified),
+      ];
+      const edges: WorkflowGraphEdge[] = [
+        makeEdge(START_NODE_ID, "task_a"),
+        makeEdge("task_a", "task_b"),
+        makeEdge("task_b", END_NODE_ID),
+      ];
+
+      const assignments = computePortAssignments(nodes, edges);
+
+      expect(assignments.size).toBe(4);
+      expect(assignments.get(START_NODE_ID)!.outputPorts).toHaveLength(1);
+      expect(assignments.get(END_NODE_ID)!.inputPorts).toHaveLength(1);
+      expect(assignments.get("task_a")!.inputPorts).toHaveLength(1);
+      expect(assignments.get("task_a")!.outputPorts).toHaveLength(1);
+    });
+
+    it("produces deterministic results (same input = same output)", () => {
+      const nodes = [
+        makeNode("a", WorkflowTaskKind.switch_case, {
+          cases: [{ name: "x" }, { name: "y" }],
+        }),
+      ];
+      const edges: WorkflowGraphEdge[] = [];
+
+      const result1 = computePortAssignments(nodes, edges);
+      const result2 = computePortAssignments(nodes, edges);
+
+      expect(result1.get("a")!.outputPorts).toEqual(result2.get("a")!.outputPorts);
+    });
+  });
+});