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

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

@@ -0,0 +1,172 @@
+/**
+ * Local graph runner plugin for in-browser graph execution
+ * Uses the local Engine instead of a remote server
+ */
+
+import type { System } from '../../system/system.js';
+import { plugin } from '../../system/plugin.js';
+import type { IRegistry } from '@kiberon-labs/behave-graph';
+import { buildUIGraphJSON } from '../../transformers/Uigraph.js';
+import { GraphRunnerClient } from '../graphrunner/client.js';
+import { LocalTransport } from './transport.js';
+import {
+  graphRunnerClientPlugin,
+  type ServerEvent,
+  type ServerVariable,
+  type SessionFactory
+} from '../graphrunner/index.js';
+import { DefaultSessionFactory } from '../graphrunner/session.js';
+import { localGraphRunnerStoreFactory } from './store.js';
+import { LocalGraphRunnerPanel } from './panel.js';
+import { MenuItemElement } from '../../components/menubar/menuItem.js';
+import { ErrorBoundary } from 'react-error-boundary';
+
+export * from './transport.js';
+export * from './store.js';
+export * from './panel.js';
+export * from './types.js';
+
+/**
+ * Options for the local graph runner plugin
+ */
+export interface LocalGraphRunnerPluginOptions {
+  /**
+   * Node registry with registered nodes, values, and dependencies.
+   * Required for graph execution.
+   */
+  registry: IRegistry;
+  variables?: ServerVariable[];
+  events?: ServerEvent[];
+  sessionFactory?: SessionFactory;
+
+  /**
+   * Custom tick strategy hook for controlling timing between tick events.
+   * If not provided, defaults to requestAnimationFrame for smooth browser refresh sync.
+   */
+  tickStrategy?: () => Promise<void>;
+
+  /**
+   * Whether to skip automatic connection.
+   * Default: false (will attempt to connect immediately)
+   */
+  skipAutoConnect?: boolean;
+
+  /**
+   * Whether to add the menu item to the Window menu.
+   * Default: true
+   */
+  addMenuItem?: boolean;
+}
+
+/**
+ * Default RAF-based tick strategy for smooth browser animation frame sync
+ */
+const defaultRafTickStrategy = (): Promise<void> => {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+};
+
+/**
+ * Plugin initialization function for local graph execution
+ * Registers a GraphRunnerClient with a local transport that executes graphs in-browser
+ */
+export async function localGraphRunnerPluginLoader(
+  system: System,
+  options: LocalGraphRunnerPluginOptions
+): Promise<void> {
+  // Create local graph runner store
+  const localStore = localGraphRunnerStoreFactory();
+  system.decorate('localGraphRunnerStore', localStore);
+
+  // Create or use provided session factory with tick strategy
+  const tickStrategy = options.tickStrategy ?? defaultRafTickStrategy;
+  const sessionFactory =
+    options.sessionFactory ??
+    new DefaultSessionFactory({
+      tickStrategy
+    });
+
+  // Create local transport with access to the node registry and store.
+  // `resolveGraph` lets Call Subgraph nodes run other open graphs by id.
+  const transport = new LocalTransport(options.registry, {
+    ...options,
+    store: localStore,
+    sessionFactory,
+    resolveGraph: (id) => {
+      const target = system.activeGraph.getState().sessions[id];
+      return target ? buildUIGraphJSON(target).flow : undefined;
+    }
+  });
+
+  // Create client with the local transport and message activity tracking
+  const client = new GraphRunnerClient({
+    transport,
+    protocolVersion: '1.0.0',
+    auth: { type: 'none' },
+    onMessageActivity: (direction, message) => {
+      // Access the store from the system after it's registered
+      const graphRunnerStore = system.runner.store;
+      if (graphRunnerStore) {
+        graphRunnerStore.getState().addMessageActivity(direction, message);
+      }
+    }
+  });
+
+  // Register the graph runner client plugin
+  // This will create the graphRunnerClientStore and decorate it on the system
+  system.registerPlugin(graphRunnerClientPlugin, {
+    client
+  });
+
+  // Register the local graph runner panel
+  system.tabLoader.register('localGraphRunner', () => {
+    return {
+      id: 'localGraphRunner',
+      closable: true,
+      title: 'Local Graph Runner',
+      group: 'default',
+      content: () => (
+        <ErrorBoundary
+          fallback={<div>Error loading Local Graph Runner panel</div>}
+        >
+          <LocalGraphRunnerPanel />
+        </ErrorBoundary>
+      )
+    };
+  });
+
+  // Add menu item to Window menu (unless disabled)
+  if (options.addMenuItem !== false) {
+    const menuStore = system.menubarStore;
+    const currentItems = menuStore.getState().items;
+    const windowMenu = currentItems.find((menu) => menu.name === 'window');
+
+    if (windowMenu) {
+      // Add the Local Graph Runner menu item to the Window menu
+      const newMenuItem = {
+        name: 'localGraphRunner',
+        render: function LocalGraphRunnerMenuItem() {
+          return (
+            <MenuItemElement
+              onClick={() =>
+                system.tabStore.getState().openTab('localGraphRunner')
+              }
+              key="localGraphRunner"
+            >
+              Local Graph Runner
+            </MenuItemElement>
+          );
+        }
+      };
+
+      menuStore
+        .getState()
+        .setSubMenuItems('window', [...windowMenu.items, newMenuItem]);
+    }
+  }
+}
+
+export const localGraphRunnerPlugin = plugin(localGraphRunnerPluginLoader, {
+  name: 'graphrunner-local'
+});

package/src/plugin/graphrunner-local/panel.tsx

@@ -0,0 +1,187 @@
+import { useState } from 'react';
+import { useStore } from 'zustand';
+import {
+  VscodeButton,
+  VscodeTextfield,
+  VscodeBadge,
+  VscodeDivider
+} from '@vscode-elements/react-elements';
+
+import styles from './styles.module.css';
+import { useSystem } from '@/system/index.js';
+import { BasePanel } from '@/components/panels/base';
+import { SectionTitle } from '@/components/panels/common/SectionTitle';
+
+/** A labelled numeric field with a hint, an Apply button, and the current value. */
+const NumberControl = ({
+  label,
+  hint,
+  value,
+  current,
+  onChange,
+  onApply,
+  ...inputProps
+}: {
+  label: string;
+  hint: string;
+  value: string;
+  current: string;
+  onChange: (value: string) => void;
+  onApply: () => void;
+} & Record<string, unknown>) => (
+  <div className={styles.field}>
+    <span className={styles.label}>{label}</span>
+    <span className={styles.description}>{hint}</span>
+    <div className={styles.inputRow}>
+      <VscodeTextfield
+        className={styles.input}
+        type="number"
+        value={value}
+        onChange={(e: any) => onChange(e.target.value)}
+        {...inputProps}
+      />
+      <VscodeButton onClick={onApply}>Apply</VscodeButton>
+    </div>
+    <span className={styles.current}>Current: {current}</span>
+  </div>
+);
+
+export const LocalGraphRunnerPanel = () => {
+  const system = useSystem();
+  const store = system.localGraphRunnerStore;
+  const executionSpeed = useStore(store, (state) => state.executionSpeed);
+  const stepDelay = useStore(store, (state) => state.stepDelay);
+  const tickInterval = useStore(store, (state) => state.tickInterval);
+  const isExecuting = useStore(store, (state) => state.isExecuting);
+  const isPaused = useStore(store, (state) => state.isPaused);
+  const activeRuns = useStore(store, (state) => state.activeRuns);
+
+  const [speedInput, setSpeedInput] = useState(executionSpeed.toString());
+  const [delayInput, setDelayInput] = useState(stepDelay.toString());
+  const [tickIntervalInput, setTickIntervalInput] = useState(
+    tickInterval.toString()
+  );
+
+  const handleSetSpeed = () => {
+    const speed = parseFloat(speedInput);
+    if (!isNaN(speed) && speed > 0) {
+      store.getState().setExecutionSpeed(speed);
+    }
+  };
+
+  const handleSetDelay = () => {
+    const delay = parseInt(delayInput, 10);
+    if (!isNaN(delay) && delay >= 0) {
+      store.getState().setStepDelay(delay);
+    }
+  };
+
+  const handleSetTickInterval = () => {
+    const interval = parseInt(tickIntervalInput, 10);
+    if (!isNaN(interval) && interval >= 0) {
+      store.getState().setTickInterval(interval);
+    }
+  };
+
+  const applyPreset = (speed: number, delay: number, tick: number) => {
+    store.getState().setExecutionSpeed(speed);
+    store.getState().setStepDelay(delay);
+    store.getState().setTickInterval(tick);
+    setSpeedInput(speed.toString());
+    setDelayInput(delay.toString());
+    setTickIntervalInput(tick.toString());
+  };
+
+  const statusLabel = isExecuting ? (isPaused ? 'Paused' : 'Running') : 'Idle';
+
+  return (
+    <BasePanel>
+      <SectionTitle>Status</SectionTitle>
+      <div className={styles.statusRow}>
+        <span className={styles.label}>Status</span>
+        <VscodeBadge>{statusLabel}</VscodeBadge>
+      </div>
+      <div className={styles.statusRow}>
+        <span className={styles.label}>Active runs</span>
+        <span className={styles.statusValue}>{activeRuns}</span>
+      </div>
+
+      <VscodeDivider className={styles.divider} />
+      <SectionTitle>Execution Speed</SectionTitle>
+
+      <NumberControl
+        label="Speed Multiplier"
+        hint="0.1 = slow, 1.0 = normal, 10 = fast"
+        value={speedInput}
+        current={`${executionSpeed}x`}
+        onChange={setSpeedInput}
+        onApply={handleSetSpeed}
+        placeholder="1.0"
+        min={0.01}
+        max={10}
+        step={0.01}
+      />
+
+      <NumberControl
+        label="Step Delay (ms)"
+        hint="delay between execution steps"
+        value={delayInput}
+        current={`${stepDelay}ms`}
+        onChange={setDelayInput}
+        onApply={handleSetDelay}
+        placeholder="0"
+        min={0}
+      />
+
+      <NumberControl
+        label="Tick Interval (ms)"
+        hint="delay between tick events"
+        value={tickIntervalInput}
+        current={`${tickInterval}ms`}
+        onChange={setTickIntervalInput}
+        onApply={handleSetTickInterval}
+        placeholder="50"
+        min={0}
+      />
+
+      <div className={styles.field}>
+        <span className={styles.label}>Quick Presets</span>
+        <div className={styles.presets}>
+          <VscodeButton secondary onClick={() => applyPreset(0.1, 500, 1000)}>
+            Very Slow
+          </VscodeButton>
+          <VscodeButton secondary onClick={() => applyPreset(0.5, 100, 200)}>
+            Slow
+          </VscodeButton>
+          <VscodeButton secondary onClick={() => applyPreset(1.0, 0, 50)}>
+            Normal
+          </VscodeButton>
+          <VscodeButton secondary onClick={() => applyPreset(5.0, 0, 16)}>
+            Fast
+          </VscodeButton>
+        </div>
+      </div>
+
+      <VscodeDivider className={styles.divider} />
+      <SectionTitle>How to Use</SectionTitle>
+      <ul className={styles.helpList}>
+        <li>
+          <strong>Speed Multiplier:</strong> Controls how fast the engine
+          executes. Lower values = slower execution, good for debugging.
+        </li>
+        <li>
+          <strong>Step Delay:</strong> Adds a delay between each execution step.
+          Useful for visualizing graph execution flow.
+        </li>
+        <li>
+          <strong>Tick Interval:</strong> Controls the delay between tick events
+          (default 50ms). Lower values = faster ticks.
+        </li>
+        <li>
+          <strong>Pause/Step:</strong> Use the toolbar buttons to pause
+          execution and step through one node at a time.
+        </li>
+      </ul>
+    </BasePanel>
+  );
+};

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

@@ -0,0 +1,41 @@
+import { createStore } from 'zustand';
+
+export interface LocalGraphRunnerStore {
+  // Execution settings
+  executionSpeed: number; // Multiplier for execution speed (1.0 = normal)
+  stepDelay: number; // Delay in milliseconds between steps
+  tickInterval: number; // Delay in milliseconds between tick events
+
+  // Runtime state
+  isExecuting: boolean;
+  isPaused: boolean;
+  activeRuns: number;
+
+  // Actions
+  setExecutionSpeed: (speed: number) => void;
+  setStepDelay: (delay: number) => void;
+  setTickInterval: (interval: number) => void;
+  setIsExecuting: (isExecuting: boolean) => void;
+  setIsPaused: (isPaused: boolean) => void;
+  setActiveRuns: (count: number) => void;
+}
+
+export const localGraphRunnerStoreFactory = () => {
+  return createStore<LocalGraphRunnerStore>((set) => ({
+    // Initial state
+    executionSpeed: 1.0,
+    stepDelay: 0,
+    tickInterval: 50,
+    isExecuting: false,
+    isPaused: false,
+    activeRuns: 0,
+
+    // Actions
+    setExecutionSpeed: (executionSpeed) => set({ executionSpeed }),
+    setStepDelay: (stepDelay) => set({ stepDelay }),
+    setTickInterval: (tickInterval) => set({ tickInterval }),
+    setIsExecuting: (isExecuting) => set({ isExecuting }),
+    setIsPaused: (isPaused) => set({ isPaused }),
+    setActiveRuns: (activeRuns) => set({ activeRuns })
+  }));
+};

package/src/plugin/graphrunner-local/styles.module.css

@@ -0,0 +1,82 @@
+/* Local Graph Runner panel — follows the shared panel conventions: BasePanel
+   chrome, SectionTitle headers, VscodeDivider separators, and the design
+   system's spacing/type scale (no card backgrounds or bespoke pixel values). */
+
+.divider {
+    margin: 0.4rem 0;
+}
+
+/* Status rows */
+.statusRow {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2, 0.5rem);
+    padding: 0.1rem 0;
+}
+
+.statusValue {
+    font-size: var(--fs-label, 0.8rem);
+    font-variant-numeric: tabular-nums;
+    color: var(--ds-fg);
+}
+
+/* Labelled control rows (mirrors the Settings panel) */
+.field {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    padding: var(--space-1, 0.25rem) 0;
+}
+
+.label {
+    font-size: var(--fs-label, 0.8rem);
+    color: var(--ds-fg);
+    line-height: 1.3;
+}
+
+.description {
+    font-size: var(--fs-desc, 0.72rem);
+    color: var(--ds-fg-muted);
+    line-height: 1.35;
+}
+
+.inputRow {
+    display: flex;
+    gap: var(--space-2, 0.5rem);
+    align-items: center;
+    margin-top: 0.15rem;
+}
+
+.input {
+    flex: 1;
+    min-width: 0;
+}
+
+.current {
+    font-size: var(--fs-desc, 0.72rem);
+    color: var(--ds-fg-muted);
+}
+
+.presets {
+    display: flex;
+    gap: var(--space-2, 0.5rem);
+    flex-wrap: wrap;
+    margin-top: 0.15rem;
+}
+
+/* How-to-use list */
+.helpList {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2, 0.5rem);
+    margin: 0.25rem 0 0;
+    padding-left: 1.1rem;
+    font-size: var(--fs-desc, 0.72rem);
+    line-height: 1.5;
+    color: var(--ds-fg-muted);
+}
+
+.helpList strong {
+    color: var(--ds-fg);
+    font-weight: 600;
+}