@kiberon-labs/behave-graph-flow 2.0.0 → 3.0.0

package/src/plugin/graphrunner-local/transport.ts

@@ -26,29 +26,43 @@ import type {
   RemoveLinkMessage,
   DirectExecuteNodeMessage
 } from '../graphrunner/types.js';
-import type { ITransport, TransportState } from '../graphrunner/transport.js';
+import type {
+  ITransport,
+  IExecutionControl,
+  TransportState
+} from '../graphrunner/transport.js';
 import {
   Engine,
   type GraphInstance,
   type ILifecycleEventEmitter,
   readGraphFromJSON,
   validateGraph,
-  ManualLifecycleEventEmitter,
   DefaultLogger,
   type ILogger,
   Link,
-  makeGraphApi
+  makeGraphApi,
+  runSubgraph,
+  DEFAULT_SUBGRAPH_MAX_DEPTH
+} from '@kiberon-labs/behave-graph';
+import type {
+  IRegistry,
+  IGraphApi,
+  GraphJSON
 } from '@kiberon-labs/behave-graph';
-import type { IRegistry } from '@kiberon-labs/behave-graph';
 import type { StoreApi } from 'zustand';
 import type { LocalGraphRunnerStore } from './store.js';
 import { sleep } from '@kiberon-labs/behave-graph';
 import {
+  setupTracing,
   setupVariableChangeTracking,
+  prepareRegistryWithDependencies,
   handleGetServerVariables,
   handleGetServerEvents,
   handleGetSocketConstraints,
-  handleGetNodeTypes
+  handleGetNodeTypes,
+  executeGraphLifecycle,
+  type ActiveRun as BaseActiveRun,
+  type MessageContext
 } from './execution-utils.js';
 import {
   SessionManager,
@@ -58,31 +72,22 @@ import {
 } from '../graphrunner/session.js';
 import { createNode } from '@kiberon-labs/behave-graph';
 
-interface ActiveRun {
-  runId: string;
-  graphId: string;
+/**
+ * Local run record. Extends the shared {@link BaseActiveRun} (used by both the
+ * local and worker runners) with the session + tick bookkeeping that only the
+ * local, interactively-controllable transport needs.
+ */
+interface ActiveRun extends BaseActiveRun {
   sessionId: string;
-  engine: Engine;
-  graphInstance: GraphInstance;
-  registry: IRegistry;
-  status: RunStatus;
-  startedAt: number;
-  performance: {
-    nodesExecuted: number;
-    eventsEmitted: number;
-    variableChanges: number;
-  };
-  // Step execution control
-  isPaused: boolean;
-  executionPhase: 'start' | 'tick' | 'end' | 'completed';
-  currentTick: number;
   maxTicks: number;
+  /** Whether this run finalizes when its flows drain (default: stay alive). */
+  autoEnd: boolean;
 }
 
 /**
  * Local transport that executes graphs in the browser using the Engine
  */
-export class LocalTransport implements ITransport {
+export class LocalTransport implements ITransport, IExecutionControl {
   private state: TransportState = 'disconnected';
   private messageHandlers: Array<(message: ServerGraphRunnerMessage) => void> =
     [];
@@ -94,6 +99,7 @@ export class LocalTransport implements ITransport {
   private store: StoreApi<LocalGraphRunnerStore> | null = null;
   private variables: ServerVariable[];
   private serverEvents: ServerEvent[];
+  private resolveGraph?: (id: string) => GraphJSON | undefined;
 
   constructor(
     registry: IRegistry,
@@ -102,6 +108,10 @@ export class LocalTransport implements ITransport {
       variables?: ServerVariable[];
       serverEvents?: ServerEvent[];
       sessionFactory?: SessionFactory;
+      /**
+       * Resolve a referenced graph's JSON by id, enabling Call Subgraph nodes.
+       */
+      resolveGraph?: (id: string) => GraphJSON | undefined;
     }
   ) {
     this.registry = registry;
@@ -109,6 +119,7 @@ export class LocalTransport implements ITransport {
     this.variables = options?.variables ?? [];
     this.serverEvents = options?.serverEvents ?? [];
     this.sessionManager = new SessionManager(options?.sessionFactory);
+    this.resolveGraph = options?.resolveGraph;
   }
 
   /**
@@ -438,29 +449,40 @@ export class LocalTransport implements ITransport {
         };
       }
 
-      if (
-        !registryToUse.dependencies?.ILifecycleEventEmitter ||
-        !registryToUse.dependencies?.ILogger
-      ) {
-        // Create a new registry with required dependencies injected
-        registryToUse = {
-          ...registryToUse,
-          dependencies: {
-            ...registryToUse.dependencies,
-            ILifecycleEventEmitter:
-              registryToUse.dependencies?.ILifecycleEventEmitter ||
-              new ManualLifecycleEventEmitter(),
-            ILogger: transportLogger
+      // Inject the lifecycle event emitter (if absent) and the forwarding logger
+      // , shared with the worker runner.
+      registryToUse = prepareRegistryWithDependencies(
+        registryToUse,
+        transportLogger
+      );
+
+      // Inject the subgraph resolver so Call Subgraph nodes can run referenced
+      // graphs. runSubgraph builds a cycle/depth-guarded IGraphApi for nested
+      // calls; the active graph id seeds the call stack so a graph calling back
+      // to the active graph (or itself) is detected as a cycle and refused.
+      if (this.resolveGraph) {
+        const resolveGraph = this.resolveGraph;
+        const activeGraphId = message.graphId;
+        const graphApi: IGraphApi = {
+          getGraph: (id) => resolveGraph(id),
+          runGraph: (id, inputs) => {
+            const childGraph = resolveGraph(id);
+            return childGraph
+              ? runSubgraph({
+                  graphJson: childGraph,
+                  registry: registryToUse,
+                  inputs,
+                  resolveGraph,
+                  graphId: id,
+                  stack: [activeGraphId],
+                  maxDepth: DEFAULT_SUBGRAPH_MAX_DEPTH
+                })
+              : Promise.resolve({});
           }
         };
-      } else {
-        // Replace the existing logger with the transport logger
         registryToUse = {
           ...registryToUse,
-          dependencies: {
-            ...registryToUse.dependencies,
-            ILogger: transportLogger
-          }
+          dependencies: { ...registryToUse.dependencies, IGraphApi: graphApi }
         };
       }
 
@@ -508,7 +530,11 @@ export class LocalTransport implements ITransport {
         isPaused: false,
         executionPhase: 'start',
         currentTick: 0,
-        maxTicks: Infinity // No limit - tick events run until stopped
+        maxTicks: Infinity, // No limit - tick events run until stopped
+        // Runs stay alive by default so event subscriptions (ai/onToolCall
+        // etc.) keep firing after the start flow drains; opting into autoEnd
+        // restores fire-and-forget completion.
+        autoEnd: executionOptions.autoEnd ?? false
       };
 
       this.activeRuns.set(runId, run);
@@ -541,37 +567,17 @@ export class LocalTransport implements ITransport {
         sendError: (code, msg, details) => this.sendError(code, msg, details)
       });
 
-      // Set up tracing
+      // Set up tracing , shared with the worker runner so the trace event shape
+      // and timestamps stay consistent across runners.
       if (executionOptions.trace) {
-        engine.onNodeExecutionStart.addListener((node) => {
-          run.performance.nodesExecuted++;
-          this.notifyMessage({
-            type: 'trace',
-            runId,
-            graphId: message.graphId,
-            nodeId: node.id,
-            event: 'start',
-            data: { typeName: node.description.typeName },
-            timestamp: Date.now() - run.startedAt
-          });
-        });
-
-        engine.onNodeExecutionEnd.addListener((node) => {
-          this.notifyMessage({
-            type: 'trace',
-            runId,
-            graphId: message.graphId,
-            nodeId: node.id,
-            event: 'end',
-            data: { typeName: node.description.typeName },
-            timestamp: Date.now() - run.startedAt
-          });
+        setupTracing(run, message.graphId, {
+          sendMessage: this.notifyMessage.bind(this),
+          sendError: (code, msg, details) => this.sendError(code, msg, details)
         });
       }
 
       // Execute graph asynchronously
-      const autoEnd = executionOptions.autoEnd ?? true;
-      this.executeGraph(run, message.graphId, autoEnd, session);
+      this.executeGraph(run, message.graphId, run.autoEnd, session);
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
@@ -600,124 +606,64 @@ export class LocalTransport implements ITransport {
     autoEnd: boolean,
     session: Session
   ): Promise<void> {
-    try {
-      // Get lifecycle event emitter from the registry dependencies
-      const eventEmitter = run.registry.dependencies?.ILifecycleEventEmitter as
-        | ILifecycleEventEmitter
-        | undefined;
-
-      // Execute start event
-      if (run.executionPhase === 'start') {
-        if (
-          eventEmitter?.startEvent &&
-          eventEmitter.startEvent.listenerCount > 0
-        ) {
-          eventEmitter.startEvent.emit();
-          await this.executeWithPauseSupport(run);
-        }
-        run.executionPhase = 'tick';
-      }
-
-      // Execute tick events (runs indefinitely until stopped)
-      if (run.executionPhase === 'tick') {
-        if (
-          eventEmitter?.tickEvent &&
-          eventEmitter.tickEvent.listenerCount > 0
-        ) {
-          // Get tick strategy hook or create default
-          const tickStrategy =
-            session.config.tickStrategy ||
-            this.createSleepTickStrategy(
-              session.config.executionSettings?.tickInterval ??
-                this.getTickInterval()
-            );
-
-          while (!run.isPaused && run.status === 'running') {
-            eventEmitter.tickEvent.emit();
-            await this.executeWithPauseSupport(run);
-            run.currentTick++;
-
-            if (run.isPaused || run.status !== 'running') {
-              return; // Exit early if paused or stopped
-            }
-
-            // Call the tick strategy hook to handle timing
-            await tickStrategy();
-          }
-        } else {
-          // No tick event listeners, move to end phase
-          run.executionPhase = 'end';
-        }
-      }
-
-      // Execute end event
-      if (run.executionPhase === 'end' && !run.isPaused) {
-        if (eventEmitter?.endEvent && eventEmitter.endEvent.listenerCount > 0) {
-          eventEmitter.endEvent.emit();
-          await this.executeWithPauseSupport(run);
-        }
-        run.executionPhase = 'completed';
-      }
-
-      // Only complete if not paused
-      if (!run.isPaused && !autoEnd) {
-        // Run completed successfully
-        run.status = 'completed';
-        const elapsedMs = Date.now() - run.startedAt;
-        const result = null; // Placeholder for result
-
-        // Call session hook for run completed
-        if (session.config.hooks?.onRunCompleted) {
-          await session.config.hooks.onRunCompleted(
-            session,
-            run.runId,
-            graphId,
-            result
-          );
-        }
-
-        this.notifyMessage({
-          type: 'completed',
-          runId: run.runId,
-          graphId,
-          completedAt: Date.now(),
-          elapsedMs,
-          result,
-          performance: run.performance
-        });
-
-        // Cleanup
-        run.engine.dispose();
-        this.activeRuns.delete(run.runId);
-        this.sessionManager.removeRunFromSession(run.sessionId, run.runId);
-        this.updateStoreActiveRuns();
-        this.updateStoreExecutionState(false, false);
-      }
-    } catch (error) {
-      run.status = 'error';
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-
-      // Call session hook for run error
-      if (session.config.hooks?.onRunError) {
-        await session.config.hooks.onRunError(
-          session,
-          run.runId,
-          graphId,
-          error instanceof Error ? error : new Error(errorMessage)
-        );
-      }
+    const ctx: MessageContext = {
+      sendMessage: this.notifyMessage.bind(this),
+      sendError: (code, message, details) =>
+        this.sendError(code, message, details)
+    };
 
-      this.sendError('NODE_EXECUTION_ERROR', errorMessage, {
-        runId: run.runId,
-        graphId
-      });
+    // Tick timing: the session's custom strategy if provided, else a sleep based
+    // on the configured tick interval.
+    const tickStrategy =
+      session.config.tickStrategy ||
+      this.createSleepTickStrategy(
+        session.config.executionSettings?.tickInterval ?? this.getTickInterval()
+      );
 
-      run.engine.dispose();
+    // Tear the run down and re-sync the panel's running / active-runs state.
+    const cleanup = (): void => {
       this.activeRuns.delete(run.runId);
       this.sessionManager.removeRunFromSession(run.sessionId, run.runId);
       this.updateStoreActiveRuns();
       this.updateStoreExecutionState(false, false);
+    };
+
+    try {
+      await executeGraphLifecycle(run, graphId, ctx, {
+        autoEnd,
+        // Pause-aware executor that also honours the local step-delay / speed.
+        executeStep: () => this.executeWithPauseSupport(run),
+        tickStrategy,
+        onComplete: async () => {
+          if (session.config.hooks?.onRunCompleted) {
+            await session.config.hooks.onRunCompleted(
+              session,
+              run.runId,
+              graphId,
+              null
+            );
+          }
+          cleanup();
+        },
+        onError: async (error) => {
+          if (session.config.hooks?.onRunError) {
+            await session.config.hooks.onRunError(
+              session,
+              run.runId,
+              graphId,
+              error
+            );
+          }
+          this.sendError('NODE_EXECUTION_ERROR', error.message, {
+            runId: run.runId,
+            graphId
+          });
+          cleanup();
+        }
+      });
+    } catch {
+      // The error was already reported + cleaned up by the onError hook; this
+      // method is fire-and-forget, so swallow the lifecycle's rethrow.
     }
   }
 
@@ -737,11 +683,26 @@ export class LocalTransport implements ITransport {
       this.store?.getState().executionSpeed ??
       1.0;
 
-    const stepLimit = this.getExecutionStepLimit();
     const delay =
       stepDelay + (executionSpeed < 1.0 ? (1.0 - executionSpeed) * 100 : 0);
 
-    // Loop while engine has pending work and not paused
+    // Full-speed path: no artificial delay requested, so drain in large chunks.
+    // The single-step limit below exists only to interleave the step delay; at
+    // full speed it forced an executeAllAsync call (time checks, promise churn)
+    // per node, which dominated the per-tick cost. Chunking keeps pause
+    // responsive (checked between chunks) while the engine's sync fast path
+    // runs unhindered within a chunk.
+    if (delay <= 0) {
+      const CHUNK_STEPS = 8192;
+      while (run.engine.hasPending() && !run.isPaused) {
+        await run.engine.executeAllAsync(5, CHUNK_STEPS);
+      }
+      return;
+    }
+
+    const stepLimit = this.getExecutionStepLimit();
+
+    // Slow-motion path: execute step by step, sleeping between steps.
     while (run.engine.hasPending() && !run.isPaused) {
       // Execute limited number of steps
       await run.engine.executeAllAsync(5, stepLimit);
@@ -783,7 +744,7 @@ export class LocalTransport implements ITransport {
 
     run.isPaused = false;
     // Continue execution from where we left off
-    await this.executeGraph(run, run.graphId, true, session);
+    await this.executeGraph(run, run.graphId, run.autoEnd, session);
   }
 
   /**
@@ -853,6 +814,7 @@ export class LocalTransport implements ITransport {
 
         // Run completed successfully
         run.status = 'completed';
+        run.flushTracing?.();
         const elapsedMs = Date.now() - run.startedAt;
         const result = null;
 
@@ -881,6 +843,10 @@ export class LocalTransport implements ITransport {
         run.engine.dispose();
         this.activeRuns.delete(run.runId);
         this.sessionManager.removeRunFromSession(run.sessionId, run.runId);
+        // Keep the panel's running/active-runs state in sync when stepping
+        // reaches the end of the graph.
+        this.updateStoreActiveRuns();
+        this.updateStoreExecutionState(false, false);
       }
     }
   }
@@ -903,6 +869,7 @@ export class LocalTransport implements ITransport {
     }
 
     run.status = 'stopped';
+    run.flushTracing?.();
     this.updateStoreActiveRuns();
     this.updateStoreExecutionState(false, false);
     run.engine.dispose();

package/src/plugin/graphrunner-webworker/graph-executor.worker.ts

@@ -411,6 +411,7 @@ export function initializeGraphWorker(options: GraphWorkerOptions): void {
     }
 
     run.status = 'stopped';
+    run.flushTracing?.();
     run.engine.dispose();
     activeRuns.delete(message.runId);
 
@@ -570,6 +571,7 @@ export function initializeGraphWorker(options: GraphWorkerOptions): void {
     }
 
     run.status = 'stopped';
+    run.flushTracing?.();
     run.engine.dispose();
     activeRuns.delete(message.runId);
 

package/src/plugin/graphrunner-webworker/index.tsx

@@ -12,7 +12,6 @@ import { webWorkerGraphRunnerStoreFactory } from './store.js';
 import { WebWorkerGraphRunnerPanel } from './panel.js';
 import { MenuItemElement } from '../../components/menubar/menuItem.js';
 import { ErrorBoundary } from 'react-error-boundary';
-import { setupClientEventListeners } from '../graphrunner/actions.js';
 
 export * from './worker-transport.js';
 export * from './store.js';
@@ -76,20 +75,15 @@ export async function webWorkerGraphRunnerPluginLoader(
     }
   });
 
-  // Register the graph runner client plugin
-  // This will create the graphRunnerClientStore and decorate it on the system
+  // Register the graph runner client plugin. With skipAutoConnect:false the
+  // plugin calls runner.connect(), which wires the persistent client event
+  // listeners (trace/logs/lifecycle) on this same client , so we must NOT wire
+  // them again here, or every trace span would be recorded twice.
   await system.registerPlugin(graphRunnerClientPlugin, {
     client,
     skipAutoConnect: false
   });
 
-  // Setup persistent event listeners for trace, logs, and run completion
-  // Access the store from the system after it's been registered by the plugin
-  const graphRunnerStore = system.runner.store;
-  if (graphRunnerStore) {
-    setupClientEventListeners(client, system, graphRunnerStore);
-  }
-
   // Register the web worker graph runner panel
   system.tabLoader.register('webWorkerGraphRunner', () => {
     return {

package/src/plugin/graphrunner-webworker/store.ts

@@ -87,3 +87,12 @@ export const webWorkerGraphRunnerStoreFactory =
       setStepDelay: (delay) => set({ stepDelay: delay }),
       setExecutionSpeed: (speed) => set({ executionSpeed: speed })
     }));
+
+declare module '@/system/system' {
+  interface System {
+    /**
+     * Web Worker Graph Runner store
+     */
+    webWorkerGraphRunnerStore: StoreApi<WebWorkerGraphRunnerStore>;
+  }
+}

package/src/plugin/kitchen-sink/index.ts

@@ -0,0 +1,38 @@
+import { plugin } from '@/system/plugin';
+import type { System } from '@/system/system';
+import { docsPlugin } from '@/plugin/docs';
+import { alignmentPlugin } from '@/plugin/alignment';
+import { layoutPlugin } from '@/plugin/layout';
+import { notesPlugin } from '@/plugin/notes';
+import { autosavePlugin } from '@/plugin/autosave';
+
+/**
+ * Batteries-included bundle of the standard editor plugins. Register this once
+ * instead of wiring each plugin by hand:
+ *
+ * ```ts
+ * const system = new System(registry);
+ * system.registerPlugin(kitchenSinkPlugin);
+ * ```
+ *
+ * It currently pulls in:
+ * - {@link docsPlugin} — the in-editor node documentation browser;
+ * - {@link alignmentPlugin} — node alignment + distribution;
+ * - {@link layoutPlugin} — Dagre/ELK auto-layout (heavy deps, opt-in);
+ * - {@link notesPlugin} — markdown note nodes (tiptap/prosemirror, opt-in);
+ * - {@link autosavePlugin} — client-side local backups of open graphs.
+ *
+ * It intentionally does **not** register a graph runner: runners
+ * ({@link localGraphRunnerPlugin}, the remote client, ...) need host-specific
+ * options (a node registry, transport, ...) so hosts wire those themselves.
+ */
+export const kitchenSinkPlugin = plugin(
+  async (system: System) => {
+    await system.registerPlugin(docsPlugin);
+    await system.registerPlugin(alignmentPlugin);
+    await system.registerPlugin(layoutPlugin);
+    await system.registerPlugin(notesPlugin);
+    await system.registerPlugin(autosavePlugin);
+  },
+  { name: 'kitchen-sink' }
+);

package/src/{layout/dagre.tsx → plugin/layout/dagre.ts}

@@ -1,6 +1,6 @@
 import { Position } from 'reactflow';
 import type { Edge, Node } from 'reactflow';
-import dagre from 'dagre';
+import type dagreNS from 'dagre';
 import type { System } from '@/system';
 import { pinned } from '@/annotations';
 
@@ -11,6 +11,18 @@ export type Options = {
   direction: Direction;
 };
 
+/**
+ * dagre is only needed when the user actually runs a Dagre layout, so load it
+ * lazily (a dynamic import the bundler code-splits into a separate chunk). This
+ * keeps it out of the initial load even for hosts that register the layout
+ * plugin. The module is fetched once and reused.
+ */
+let dagrePromise: Promise<typeof dagreNS> | undefined;
+const getDagre = () => {
+  dagrePromise ??= import('dagre').then((m) => m.default ?? m);
+  return dagrePromise;
+};
+
 const getDimensions = (node: Node) => {
   return {
     width: node.style?.width ?? node.width ?? 300,
@@ -18,9 +30,6 @@ const getDimensions = (node: Node) => {
   };
 };
 
-const dagreGraph = new dagre.graphlib!.Graph();
-dagreGraph.setDefaultEdgeLabel(() => ({}));
-
 const positionMap: Record<string, Position> = {
   T: Position.Top,
   L: Position.Left,
@@ -28,7 +37,7 @@ const positionMap: Record<string, Position> = {
   B: Position.Bottom
 };
 
-export function applyDagreLayout(
+export async function applyDagreLayout(
   system: System,
   options: Options | undefined = { direction: 'LR' }
 ) {
@@ -40,6 +49,9 @@ export function applyDagreLayout(
     return;
   }
 
+  const dagre = await getDagre();
+  const dagreGraph = new dagre.graphlib!.Graph();
+  dagreGraph.setDefaultEdgeLabel(() => ({}));
   dagreGraph.setGraph({ rankdir: direction });
 
   // Add nodes to layout: exclude pinned nodes and child nodes inside groups

package/src/{layout → plugin/layout}/elk.ts

@@ -1,12 +1,29 @@
 import type { System } from '@/system';
-import ELK, {
-  type ElkExtendedEdge,
-  type ElkNode,
-  type ElkPort
+import type {
+  ElkExtendedEdge,
+  ElkNode,
+  ElkPort
 } from 'elkjs/lib/elk.bundled.js';
 import type { Edge, Node } from 'reactflow';
 import { pinned } from '@/annotations';
 
+/**
+ * elkjs is ~1.4 MB — by far the largest dependency the editor can pull in, yet
+ * it is only used when the user explicitly runs an ELK layout. Load it lazily (a
+ * dynamic import the bundler code-splits into a separate chunk) so it stays out
+ * of the initial load even for consumers of this layout plugin. The instance is
+ * created once and reused.
+ */
+let elkPromise:
+  | Promise<{ layout: (graph: ElkNode) => Promise<ElkNode> }>
+  | undefined;
+const getElk = () => {
+  elkPromise ??= import('elkjs/lib/elk.bundled.js').then(
+    (m) => new m.default()
+  );
+  return elkPromise;
+};
+
 const layoutOptions = {
   // 'elk.algorithm': 'layered',
   'elk.direction': 'RIGHT',
@@ -20,8 +37,6 @@ export type LayoutAlgorithm =
   | 'org.eclipse.elk.force'
   | 'org.eclipse.elk.rectpacking';
 
-const elk = new ELK();
-
 const getLayoutedNodes = async (
   nodes: Node[],
   edges: Edge[],
@@ -107,6 +122,7 @@ const getLayoutedNodes = async (
     )
   };
 
+  const elk = await getElk();
   const layoutedGraph = await elk.layout(graph);
 
   const layoutedNodes = nodes.map((node) => {