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

package/src/plugin/graphrunner/runController.ts

@@ -0,0 +1,283 @@
+import { createStore, type StoreApi } from 'zustand';
+import type { GraphSession } from '@/system/graphSession';
+import type { GraphRunner } from './runner';
+import { buildUIGraphJSON } from '../../transformers/Uigraph';
+import { isBehaveNode } from '@/util/isBehaveNode';
+import { supportsExecutionControl } from './transport';
+
+// Contribute the per-session run controller to the graph session as a typed,
+// plugin-owned property. Core no longer declares this field , the graph runner
+// plugin attaches it via `session.decorate('runController', …)` from a session
+// extension (see ./index.tsx).
+declare module '@/system/graphSession' {
+  interface IGraphSession {
+    runController?: GraphRunController;
+  }
+}
+
+/**
+ * Per-run state for a single graph. Each {@link GraphSession} owns one of these,
+ * so multiple graphs can run independently and concurrently.
+ */
+export interface RunControllerStore {
+  currentRunId: string | null;
+  currentGraphId: string | null;
+  isExecuting: boolean;
+  isPaused: boolean;
+  setCurrentRunId: (runId: string | null) => void;
+  setCurrentGraphId: (graphId: string | null) => void;
+  setIsExecuting: (isExecuting: boolean) => void;
+  setIsPaused: (isPaused: boolean) => void;
+}
+
+const runControllerStoreFactory = (): StoreApi<RunControllerStore> =>
+  createStore<RunControllerStore>((set) => ({
+    currentRunId: null,
+    currentGraphId: null,
+    isExecuting: false,
+    isPaused: false,
+    setCurrentRunId: (currentRunId) => set({ currentRunId }),
+    setCurrentGraphId: (currentGraphId) => set({ currentGraphId }),
+    setIsExecuting: (isExecuting) => set({ isExecuting }),
+    setIsPaused: (isPaused) => set({ isPaused })
+  }));
+
+/**
+ * Drives execution for a single graph session. Run lifecycle and run state are
+ * per-session; the underlying connection/client is shared via {@link GraphRunner}.
+ * Incoming server messages are routed back to the originating controller by run
+ * id (see `GraphRunner.runIndex`).
+ */
+export class GraphRunController {
+  public readonly session: GraphSession;
+  public readonly runner: GraphRunner;
+  public readonly store: StoreApi<RunControllerStore> =
+    runControllerStoreFactory();
+  private readonly disposers: Array<() => void> = [];
+
+  constructor(session: GraphSession, runner: GraphRunner) {
+    this.session = session;
+    this.runner = runner;
+    this.setupRealtimeForwarding();
+  }
+
+  private get notifications() {
+    return this.session.editor.notifications;
+  }
+
+  /** Run the graph for this session. */
+  async play(): Promise<void> {
+    const { clearLogsOnRun, clearTracesOnRun } = this.runner.store.getState();
+
+    if (clearLogsOnRun) {
+      this.session.logsStore.getState().clear();
+    }
+    if (clearTracesOnRun) {
+      this.session.traceStore.getState().clear();
+    }
+
+    const graphId = this.session.id;
+    const uiGraphData = buildUIGraphJSON(this.session);
+    try {
+      await this.runRemotely(graphId, { graph: uiGraphData.flow });
+    } catch {
+      // Error already surfaced in runRemotely
+    }
+  }
+
+  async runRemotely(
+    graphId: string,
+    options?: { graph?: unknown; inputs?: unknown }
+  ): Promise<void> {
+    const client = this.runner.store.getState().client;
+    const { enableTracing } = this.runner.store.getState();
+    const { setCurrentRunId, setCurrentGraphId, setIsExecuting, setIsPaused } =
+      this.store.getState();
+
+    if (!client) {
+      this.notifications.error('No graph runner connection');
+      throw new Error('No graph runner connection');
+    }
+    if (this.store.getState().isExecuting) {
+      return;
+    }
+
+    try {
+      const runId = await client.runGraph(graphId, {
+        ...options,
+        trace: enableTracing
+      });
+
+      setCurrentRunId(runId);
+      setCurrentGraphId(graphId);
+      setIsExecuting(true);
+      setIsPaused(false);
+      this.runner.registerRun(runId, this);
+
+      this.notifications.info(`Graph execution started: ${graphId}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      setIsExecuting(false);
+      setIsPaused(false);
+      setCurrentRunId(null);
+      setCurrentGraphId(null);
+      this.notifications.error(`Failed to run graph: ${message}`);
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    const client = this.runner.store.getState().client;
+    const { currentRunId } = this.store.getState();
+    if (!client || !currentRunId) return;
+
+    try {
+      await client.stopGraph(currentRunId);
+      this.notifications.info('Stopping graph execution');
+      this.finishRun();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.notifications.error(`Failed to stop graph: ${message}`);
+    }
+  }
+
+  async pause(): Promise<void> {
+    const client = this.runner.store.getState().client;
+    const { currentRunId, setIsPaused } = this.store.getState();
+    if (!client || !currentRunId) return;
+
+    try {
+      const transport = client.transport;
+      if (supportsExecutionControl(transport)) {
+        transport.pauseExecution(currentRunId);
+        setIsPaused(true);
+        this.notifications.info('Execution paused');
+      } else {
+        await this.stop();
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.notifications.error(`Failed to pause graph: ${message}`);
+    }
+  }
+
+  async resume(): Promise<void> {
+    const client = this.runner.store.getState().client;
+    const { currentRunId, setIsPaused } = this.store.getState();
+    if (!client || !currentRunId) return;
+
+    try {
+      const transport = client.transport;
+      if (supportsExecutionControl(transport)) {
+        setIsPaused(false);
+        this.notifications.info('Resuming execution');
+        await transport.resumeExecution(currentRunId);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.notifications.error(`Failed to resume graph: ${message}`);
+    }
+  }
+
+  async step(): Promise<void> {
+    const client = this.runner.store.getState().client;
+    const { currentRunId, setIsPaused } = this.store.getState();
+    if (!client || !currentRunId) return;
+
+    try {
+      const transport = client.transport;
+      if (supportsExecutionControl(transport)) {
+        setIsPaused(true);
+        await transport.stepExecution(currentRunId);
+      } else {
+        this.notifications.info(
+          'Step execution not supported for this transport'
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.notifications.error(`Failed to step graph: ${message}`);
+    }
+  }
+
+  /** Reset run state after completion/stop/error and unregister the run. */
+  finishRun(): void {
+    const runId = this.store.getState().currentRunId;
+    if (runId) this.runner.unregisterRun(runId);
+    const s = this.store.getState();
+    s.setIsExecuting(false);
+    s.setIsPaused(false);
+    s.setCurrentRunId(null);
+    s.setCurrentGraphId(null);
+  }
+
+  /**
+   * Forward live graph edits to the server while this graph is running, tagged
+   * with this controller's run id so concurrent graphs stay isolated.
+   */
+  private setupRealtimeForwarding(): void {
+    const pubsub = this.session.pubsub;
+    const canForward = () => {
+      const client = this.runner.store.getState().client;
+      const runId = this.store.getState().currentRunId;
+      const caps = this.runner.store.getState().connectionInfo.capabilities;
+      return client && runId && caps?.realtime ? { client, runId } : null;
+    };
+
+    const tokens = [
+      pubsub.subscribe('node:added', (_, node) => {
+        if (!isBehaveNode(node)) return;
+        const ctx = canForward();
+        if (!ctx) return;
+        ctx.client.addNode(
+          ctx.runId,
+          node.id,
+          node.data.type,
+          node.data as Record<string, unknown>,
+          node.position
+        );
+      }),
+      pubsub.subscribe('edge:added', (_, edge) => {
+        const ctx = canForward();
+        if (!ctx || !edge.source || !edge.target) return;
+        ctx.client.createLink(
+          ctx.runId,
+          edge.source,
+          edge.sourceHandle || '',
+          edge.target,
+          edge.targetHandle || ''
+        );
+      }),
+      pubsub.subscribe('edge:removed', (_, edge) => {
+        const ctx = canForward();
+        if (!ctx || !edge.source || !edge.target) return;
+        ctx.client.removeLink(
+          ctx.runId,
+          edge.source,
+          edge.sourceHandle || '',
+          edge.target,
+          edge.targetHandle || ''
+        );
+      }),
+      pubsub.subscribe('node:removed', (_, node) => {
+        if (!isBehaveNode(node)) return;
+        const ctx = canForward();
+        if (!ctx) return;
+        ctx.client.removeNode(ctx.runId, node.id);
+      })
+    ];
+
+    for (const token of tokens) {
+      if (typeof token === 'string') {
+        this.disposers.push(() => pubsub.unsubscribe(token));
+      }
+    }
+  }
+
+  dispose(): void {
+    const runId = this.store.getState().currentRunId;
+    if (runId) this.runner.unregisterRun(runId);
+    this.disposers.forEach((d) => d());
+    this.disposers.length = 0;
+  }
+}

package/src/plugin/graphrunner/runner.ts

@@ -0,0 +1,187 @@
+import type { System } from '../../system/system';
+import type { StoreApi } from 'zustand';
+import type { GraphRunnerClientStore } from './store';
+import { GraphRunnerClient } from './client';
+import { setupClientEventListeners } from './actions';
+import type { GraphRunController } from './runController';
+
+declare module '@/system/system' {
+  interface System {
+    runner: GraphRunner;
+  }
+}
+
+/**
+ * Shared connection to the graph runner server. Owns the client, connection
+ * lifecycle and server metadata; per-graph run state and run lifecycle live on
+ * {@link GraphRunController}. Incoming server messages are dispatched back to the
+ * owning controller via {@link GraphRunner.runIndex}, keyed by run id, so
+ * multiple graphs can run concurrently and independently.
+ */
+export class GraphRunner {
+  private system: System;
+  public readonly store: StoreApi<GraphRunnerClientStore>;
+  /** runId -> the controller that started it. */
+  public readonly runIndex = new Map<string, GraphRunController>();
+
+  constructor(system: System, store: StoreApi<GraphRunnerClientStore>) {
+    this.system = system;
+    this.store = store;
+  }
+
+  registerRun(runId: string, controller: GraphRunController): void {
+    this.runIndex.set(runId, controller);
+  }
+
+  unregisterRun(runId: string): void {
+    this.runIndex.delete(runId);
+  }
+
+  /**
+   * Connect to the graph runner server
+   */
+  async connect(): Promise<void> {
+    const {
+      client,
+      connectionConfig,
+      setClient,
+      setConnectionState,
+      setConnectionInfo,
+      setError,
+      clearServerMetadata,
+      addMessageActivity
+    } = this.store.getState();
+
+    try {
+      setError(null);
+      setConnectionState('connecting');
+
+      const theClient =
+        client ??
+        new GraphRunnerClient({
+          url: connectionConfig.url,
+          auth: connectionConfig.auth,
+          autoReconnect: connectionConfig.autoReconnect,
+          onMessageActivity: (direction, message) => {
+            addMessageActivity(direction, message);
+          }
+        });
+
+      setClient(theClient);
+
+      await theClient.connect();
+
+      // Setup persistent event listeners for trace, logs, and run completion.
+      // Messages are routed to the originating session by run id.
+      setupClientEventListeners(theClient, this);
+
+      setConnectionState('connected');
+      setConnectionInfo({
+        serverId: theClient.getServerId(),
+        userId: theClient.getUserId(),
+        sessionId: null,
+        authenticated: theClient.isAuthenticated(),
+        capabilities: null
+      });
+
+      // Create session
+      const sessionId = await theClient.createSession();
+      setConnectionInfo({ sessionId });
+
+      // Get capabilities
+      const capabilities = await theClient.getCapabilities();
+      setConnectionInfo({ capabilities });
+
+      // Fetch metadata if supported
+      if (capabilities.runtimeMetadata) {
+        await this.refreshMetadata();
+      }
+
+      // Notify successful connection
+      this.system.notifications.success(
+        `Connected to ${theClient.getServerId() || 'graph runner server'}`
+      );
+    } catch (error) {
+      setConnectionState('disconnected');
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      setError(errorMessage);
+      setClient(null);
+      clearServerMetadata();
+
+      // Notify connection error
+      this.system.notifications.error(`Failed to connect: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Disconnect from the graph runner server
+   */
+  async disconnect(): Promise<void> {
+    const {
+      client,
+      setClient,
+      setConnectionState,
+      setConnectionInfo,
+      clearServerMetadata
+    } = this.store.getState();
+
+    console.log('Disconnecting from graph runner server...');
+    if (client) {
+      try {
+        await client.closeSession();
+        client.disconnect();
+      } catch (error) {
+        console.error('Error disconnecting:', error);
+      }
+    }
+
+    setClient(null);
+    setConnectionState('disconnected');
+    setConnectionInfo({
+      serverId: null,
+      userId: null,
+      sessionId: null,
+      authenticated: false,
+      capabilities: null
+    });
+    clearServerMetadata();
+  }
+
+  /**
+   * Refresh server metadata (variables, events, node types)
+   */
+  async refreshMetadata(): Promise<void> {
+    const {
+      client,
+      setServerVariables,
+      setServerEvents,
+      setNodeTypes,
+      setError
+    } = this.store.getState();
+    if (!client) {
+      return;
+    }
+
+    try {
+      const capabilities = client.getCachedCapabilities();
+      if (!capabilities?.runtimeMetadata) {
+        return;
+      }
+
+      const [variables, events, nodeTypes] = await Promise.all([
+        client.getServerVariables(),
+        client.getServerEvents(),
+        client.getNodeTypes()
+      ]);
+
+      setServerVariables(variables);
+      setServerEvents(events);
+      setNodeTypes(nodeTypes);
+
+      setError(null);
+    } catch (error) {
+      setError(error instanceof Error ? error.message : String(error));
+    }
+  }
+}

package/src/plugin/graphrunner/session.ts

@@ -0,0 +1,243 @@
+/**
+ * Session management for local graph runner
+ * Allows customization of execution context and configuration per session
+ */
+
+import type { IRegistry } from '@kiberon-labs/behave-graph';
+import type {
+  GraphRunnerCapabilities,
+  EventFilter
+} from '../graphrunner/types.js';
+
+/**
+ * Session configuration for graph execution
+ */
+export interface SessionConfig {
+  /** Custom metadata attached to the session */
+  metadata?: Record<string, unknown>;
+  /** Default execution options for all runs in this session */
+  defaultExecutionOptions?: {
+    autoEnd?: boolean;
+    trace?: boolean;
+    eventFilter?: EventFilter;
+    maxExecutionTimeMs?: number;
+  };
+  /** Session-level execution settings */
+  executionSettings?: {
+    /** Delay between execution steps in milliseconds */
+    stepDelay?: number;
+    /** Execution speed multiplier (0.1 to 2.0) */
+    executionSpeed?: number;
+    /** Interval between tick events in milliseconds */
+    tickInterval?: number;
+    /** Maximum number of concurrent runs allowed */
+    maxConcurrentRuns?: number;
+  };
+  /** Custom hook for handling tick timing/delays */
+  tickStrategy?: () => Promise<void>;
+  /** Custom registry overrides for this session */
+  registryOverrides?: Partial<IRegistry>;
+  /** Session lifecycle hooks */
+  hooks?: SessionHooks;
+  /** Session-specific capabilities override */
+  capabilities?: Partial<GraphRunnerCapabilities>;
+}
+
+/**
+ * Lifecycle hooks for session events
+ */
+export interface SessionHooks {
+  /** Called when the session is created */
+  onSessionCreated?: (session: Session) => void | Promise<void>;
+  /** Called when a run starts in this session */
+  onRunStarted?: (
+    session: Session,
+    runId: string,
+    graphId: string
+  ) => void | Promise<void>;
+  /** Called when a run completes in this session */
+  onRunCompleted?: (
+    session: Session,
+    runId: string,
+    graphId: string,
+    result: unknown
+  ) => void | Promise<void>;
+  /** Called when a run fails in this session */
+  onRunError?: (
+    session: Session,
+    runId: string,
+    graphId: string,
+    error: Error
+  ) => void | Promise<void>;
+  /** Called when the session is closed */
+  onSessionClosed?: (session: Session) => void | Promise<void>;
+}
+
+/**
+ * Session state
+ */
+export interface Session {
+  /** Unique session identifier */
+  readonly sessionId: string;
+  /** Session expiration timestamp */
+  readonly expiresAt: number;
+  /** Session creation timestamp */
+  readonly createdAt: number;
+  /** Session configuration */
+  readonly config: SessionConfig;
+  /** Active run IDs in this session */
+  readonly activeRuns: Set<string>;
+  /** Custom session state (user-definable) */
+  state: Record<string, unknown>;
+  /** Session metadata */
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Factory for creating sessions with custom configuration
+ */
+export interface SessionFactory {
+  /**
+   * Create a new session with optional configuration
+   */
+  createSession(sessionId: string, config?: SessionConfig): Session;
+}
+
+/**
+ * Default session factory implementation
+ */
+export class DefaultSessionFactory implements SessionFactory {
+  private defaultConfig?: SessionConfig;
+
+  constructor(defaultConfig?: SessionConfig) {
+    this.defaultConfig = defaultConfig;
+  }
+
+  createSession(sessionId: string, config?: SessionConfig): Session {
+    const mergedConfig: SessionConfig = {
+      ...this.defaultConfig,
+      ...config,
+      metadata: {
+        ...this.defaultConfig?.metadata,
+        ...config?.metadata
+      },
+      defaultExecutionOptions: {
+        ...this.defaultConfig?.defaultExecutionOptions,
+        ...config?.defaultExecutionOptions
+      },
+      executionSettings: {
+        ...this.defaultConfig?.executionSettings,
+        ...config?.executionSettings
+      },
+      hooks: {
+        ...this.defaultConfig?.hooks,
+        ...config?.hooks
+      }
+    };
+
+    const session: Session = {
+      sessionId,
+      expiresAt: Date.now() + 24 * 60 * 60 * 1000, // 24 hours default
+      createdAt: Date.now(),
+      config: mergedConfig,
+      activeRuns: new Set(),
+      state: {},
+      metadata: mergedConfig.metadata ?? {}
+    };
+
+    // Call creation hook
+    if (mergedConfig.hooks?.onSessionCreated) {
+      void mergedConfig.hooks.onSessionCreated(session);
+    }
+
+    return session;
+  }
+}
+
+/**
+ * Session manager to track and manage multiple sessions
+ */
+export class SessionManager {
+  private sessions = new Map<string, Session>();
+  private sessionFactory: SessionFactory;
+
+  constructor(sessionFactory?: SessionFactory) {
+    this.sessionFactory = sessionFactory ?? new DefaultSessionFactory();
+  }
+
+  /**
+   * Create a new session
+   */
+  createSession(sessionId: string, config?: SessionConfig): Session {
+    const session = this.sessionFactory.createSession(sessionId, config);
+    this.sessions.set(sessionId, session);
+    return session;
+  }
+
+  /**
+   * Get an existing session
+   */
+  getSession(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * Check if a session exists
+   */
+  hasSession(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
+  }
+
+  /**
+   * Close and remove a session
+   */
+  async closeSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      // Call close hook
+      if (session.config.hooks?.onSessionClosed) {
+        await session.config.hooks.onSessionClosed(session);
+      }
+      this.sessions.delete(sessionId);
+    }
+  }
+
+  /**
+   * Add a run to a session
+   */
+  addRunToSession(sessionId: string, runId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.activeRuns.add(runId);
+    }
+  }
+
+  /**
+   * Remove a run from a session
+   */
+  removeRunFromSession(sessionId: string, runId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.activeRuns.delete(runId);
+    }
+  }
+
+  /**
+   * Get all active sessions
+   */
+  getActiveSessions(): Session[] {
+    return Array.from(this.sessions.values());
+  }
+
+  /**
+   * Clean up expired sessions
+   */
+  cleanupExpiredSessions(): void {
+    const now = Date.now();
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (session.expiresAt < now) {
+        void this.closeSession(sessionId);
+      }
+    }
+  }
+}