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

package/src/system/tabLoader.tsx

@@ -16,29 +16,34 @@ import { HistoryPanel } from '@/components/panels/history';
 import { HotKeys } from '@/components/hotKeys';
 import { NodePickerPanel } from '@/components/panels/nodePicker';
 import { PanelPanel } from '@/components/panels/panel';
-import { ConversationPanel } from '@/components/panels/conversation';
 import { LayersPanel } from '@/components/panels/layers';
+import { GraphPropertiesPanel } from '@/components/panels/graphProperties';
+import { GraphProvider } from './provider';
+import { useStore } from 'zustand';
+import type { GraphSession } from './graphSession';
+import {
+  DEFAULT_GRAPH_ID,
+  isGraphTabId,
+  sessionIdFromTabId,
+  tabIdForSession
+} from '@/components/layoutController/utils';
+
+/** Live graph tab title , re-renders when the graph is renamed. */
+const GraphTabTitle = ({ session }: { session: GraphSession }) => {
+  const name = useStore(session.metaStore, (s) => s.name);
+  return <>{name}</>;
+};
 
 export class TabLoader {
   public readonly tabs: Record<string, () => TabData> = {};
+  private readonly system: System;
 
-  constructor(_system: System) {
-    this.register('graph', () => {
-      return {
-        id: 'graph',
-        closable: true,
-        cached: true,
-        group: 'graph',
-        title: 'Graph',
-        content: () => (
-          <ErrorBoundary fallback={'whoops'}>
-            <HotKeys>
-              <Flow />
-            </HotKeys>
-          </ErrorBoundary>
-        )
-      };
-    });
+  constructor(system: System) {
+    this.system = system;
+
+    // The default graph tab. Other graphs are loaded dynamically by id
+    // (see `loadGraphTab`).
+    this.register(DEFAULT_GRAPH_ID, () => this.buildGraphTab(DEFAULT_GRAPH_ID));
 
     this.register('system:settings', () => {
       return {
@@ -95,6 +100,20 @@ export class TabLoader {
         )
       };
     });
+
+    this.register('graphProperties', () => {
+      return {
+        id: 'graphProperties',
+        closable: true,
+        title: 'Graph Properties',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <GraphPropertiesPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
     this.register('find', () => {
       return {
         id: 'find',
@@ -236,30 +255,49 @@ export class TabLoader {
       };
     });
 
-    this.register('conversation', () => {
-      return {
-        id: 'conversation',
-        closable: true,
-        cached: true,
-        title: 'Conversation',
-        group: 'default',
-        content: () => (
-          <ErrorBoundary fallback={'whoops'}>
-            <ConversationPanel />
-          </ErrorBoundary>
-        )
-      };
-    });
+    // The 'conversation' tab is provided by the AI nodes package's editor
+    // plugin (`@kiberon-labs/behave-graph-nodes-ai/ui`), which owns the chat
+    // store and panel.
   }
 
   load(tab: TabBase): TabData | undefined {
     if (!tab.id) {
       return;
     }
+    // Dynamic per-graph tabs (`graph:<sessionId>`) are not in the registry.
+    if (isGraphTabId(tab.id) && tab.id !== DEFAULT_GRAPH_ID) {
+      return this.buildGraphTab(tab.id);
+    }
     return this.tabs[tab.id]?.();
   }
 
   register(id: string, loader: () => TabData) {
     this.tabs[id] = loader;
   }
+
+  /**
+   * Build the TabData for a graph tab, resolving (or lazily creating) its
+   * session and wrapping the canvas in a {@link GraphProvider} so it stays bound
+   * to its own graph regardless of which tab is focused.
+   */
+  private buildGraphTab(tabId: string): TabData {
+    const sessionId = sessionIdFromTabId(tabId);
+    const session = this.system.getOrCreateSession(sessionId);
+    return {
+      id: tabIdForSession(sessionId),
+      closable: true,
+      cached: true,
+      group: 'graph',
+      title: <GraphTabTitle session={session} />,
+      content: () => (
+        <ErrorBoundary fallback={'whoops'}>
+          <GraphProvider value={session}>
+            <HotKeys>
+              <Flow />
+            </HotKeys>
+          </GraphProvider>
+        </ErrorBoundary>
+      )
+    };
+  }
 }

package/src/system/undoRedo.ts

@@ -27,7 +27,7 @@ export type UndoStore = {
   }) => void;
 };
 
-export const undoStoreFactory = () =>
+const undoStoreFactory = () =>
   create<UndoStore>((set) => ({
     canUndo: false,
     canRedo: false,

package/src/transformers/Uigraph.ts

@@ -1,4 +1,4 @@
-import type { System } from '@/system/system';
+import type { GraphSession } from '@/system/graphSession';
 import { annotatedTitle, uiVersion } from '@/annotations';
 import type { UIGraphJSON } from '@/types/graph';
 
@@ -18,7 +18,7 @@ function getStringAnnotation(
 /**
  * Assembles the full UI graph definition for saving.
  */
-export function buildUIGraphJSON(system: System): UIGraphJSON {
+export function buildUIGraphJSON(system: GraphSession): UIGraphJSON {
   system.flowStore.getState().invalidateCache();
 
   const flow = system.flowStore.getState().getGraph();
@@ -34,8 +34,9 @@ export function buildUIGraphJSON(system: System): UIGraphJSON {
   const graphVersion =
     getStringAnnotation(annotations, uiVersion) ?? DEFAULT_UI_GRAPH_VERSION;
   const graphName =
-    getStringAnnotation(annotations, annotatedTitle) ??
-    flow.name ??
+    system.metaStore.getState().name ||
+    getStringAnnotation(annotations, annotatedTitle) ||
+    flow.name ||
     DEFAULT_UI_GRAPH_NAME;
 
   const viewports = system.graph.viewports.length

package/src/transformers/contract.ts

@@ -0,0 +1,87 @@
+import type { Node } from 'reactflow';
+import type { GraphSocketJSON } from '@kiberon-labs/behave-graph';
+import type { Socket } from '@/types';
+
+export const GRAPH_INPUT_TYPE = 'graph/input';
+export const GRAPH_OUTPUT_TYPE = 'graph/output';
+export const CALL_SUBGRAPH_TYPE = 'flow/callSubgraph';
+
+export type ContractParam = {
+  /** Stable identifier (socket key / contract key). Independent of the name. */
+  id?: string;
+  /** User-facing display name; editable without breaking wiring. */
+  name: string;
+  valueTypeName: string;
+  defaultValue?: any;
+};
+
+export type GraphContract = {
+  graphInputs: GraphSocketJSON[];
+  graphOutputs: GraphSocketJSON[];
+};
+
+/** Stable identity of a param , its id, falling back to name for legacy data. */
+export const paramId = (param: ContractParam): string => param.id ?? param.name;
+
+const readParams = (node: Node): ContractParam[] => {
+  const params = (node.data as any)?.configuration?.parameters;
+  return Array.isArray(params) ? (params as ContractParam[]) : [];
+};
+
+const toSocket = (param: ContractParam): GraphSocketJSON => ({
+  key: paramId(param),
+  valueType: param.valueTypeName,
+  ...(param.defaultValue !== undefined
+    ? { defaultValue: param.defaultValue }
+    : {}),
+  label: param.name
+});
+
+/**
+ * Derive a graph's contract from its boundary nodes. The `graph/input` /
+ * `graph/output` nodes are the source of truth; their configured parameters
+ * become the graph's `graphInputs` / `graphOutputs`.
+ */
+export const deriveContract = (nodes: Node[]): GraphContract => {
+  const graphInputs: GraphSocketJSON[] = [];
+  const graphOutputs: GraphSocketJSON[] = [];
+
+  for (const node of nodes) {
+    const type = (node.data as any)?.type;
+    if (type === GRAPH_INPUT_TYPE) {
+      graphInputs.push(...readParams(node).map(toSocket));
+    } else if (type === GRAPH_OUTPUT_TYPE) {
+      graphOutputs.push(...readParams(node).map(toSocket));
+    }
+  }
+
+  return { graphInputs, graphOutputs };
+};
+
+/**
+ * Convert a derived contract's sockets back into editable {@link ContractParam}s
+ * , the form stored in a Call Subgraph node's configuration. The socket `key`
+ * is the stable param id; its `label` is the display name.
+ */
+export const contractToParams = (sockets: GraphSocketJSON[]): ContractParam[] =>
+  sockets.map((s) => ({
+    id: s.key,
+    name: s.label ?? s.key,
+    valueTypeName: s.valueType,
+    ...(s.defaultValue !== undefined ? { defaultValue: s.defaultValue } : {})
+  }));
+
+/**
+ * Convert contract params into dynamic-port sockets. The socket identity
+ * (name/key/handle id) is the stable param id; the display label is the name.
+ */
+export const paramsToSockets = (params: ContractParam[]): Socket[] =>
+  params.map((p) => {
+    const id = paramId(p);
+    return {
+      name: id,
+      key: id,
+      label: p.name || id,
+      valueType: p.valueTypeName || 'string'
+    };
+  });

package/src/transformers/flowToBehave.ts

@@ -4,15 +4,16 @@ import type {
   NodeSpecJSON
 } from '@kiberon-labs/behave-graph';
 import type { Edge, Node } from 'reactflow';
-import { System } from '../system/system';
+import type { GraphSession } from '../system/graphSession';
 import { writeVariablesToJSON } from '../util/serializeVariables';
 import { isBehaveNode } from '@/util/isBehaveNode';
+import { deriveContract } from './contract';
 
 const isNullish = (value: any): value is null | undefined =>
   value === undefined || value === null;
 
 export const flowToBehave = (
-  system: System,
+  session: GraphSession,
   nodes: Node[],
   edges: Edge[],
   nodeSpecJSON: NodeSpecJSON[]
@@ -20,11 +21,11 @@ export const flowToBehave = (
   const graph: GraphJSON = {
     nodes: [],
     variables: [],
-    customEvents: system.eventsStore.getState().getCustomEvents()
+    customEvents: session.eventsStore.getState().getCustomEvents()
   };
 
-  const registry = system.registry.getState();
-  const varStore = system.variableStore.getState().variables;
+  const registry = session.editor.registry.getState();
+  const varStore = session.variableStore.getState().variables;
 
   nodes.forEach((node) => {
     if (!isBehaveNode(node)) return;
@@ -109,5 +110,12 @@ export const flowToBehave = (
   if (Object.keys(varStore).length > 0) {
     graph.variables = writeVariablesToJSON(registry, varStore);
   }
+
+  // Derive the graph's contract (inputs/outputs) from its boundary nodes so
+  // callers and the runtime can read it.
+  const { graphInputs, graphOutputs } = deriveContract(nodes);
+  if (graphInputs.length > 0) graph.graphInputs = graphInputs;
+  if (graphOutputs.length > 0) graph.graphOutputs = graphOutputs;
+
   return graph;
 };

package/src/types/nodes.ts

@@ -15,8 +15,13 @@ export type IBehaveNode = Omit<Node, 'data' | 'type'> & {
   };
 };
 
-export type ICommentNode = Omit<Node, 'data' | 'type'> & {
-  type: 'commentNode';
+/**
+ * Presentational markdown note, contributed by the notes plugin
+ * (`@/plugin/notes`). `commentNode` is the legacy type string notes carried
+ * when they lived in the core editor.
+ */
+export type INoteNode = Omit<Node, 'data' | 'type'> & {
+  type: 'noteNode' | 'commentNode';
   data: {
     annotations?: Record<string, any>;
     text: string;
@@ -41,5 +46,5 @@ export type IAINode = Omit<Node, 'data' | 'type'> & {
   };
 };
 
-export type AnyNode = IBehaveNode | ICommentNode | IAINode | IGroupNode;
+export type AnyNode = IBehaveNode | INoteNode | IAINode | IGroupNode;
 export type AnyNodeType = AnyNode['type'];

package/src/types.ts

@@ -3,6 +3,8 @@ import type { ChoiceJSON } from '@kiberon-labs/behave-graph';
 export interface SocketBase {
   name: string;
   key: string;
+  /** Optional display label; falls back to `name` when absent. */
+  label?: string;
   choices?: ChoiceJSON;
   valueType: string;
   defaultValue?: any;

package/src/util/autoConvert.ts

@@ -0,0 +1,200 @@
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+import type { Connection, Edge, Node, XYPosition } from 'reactflow';
+import { v4 as uuidv4 } from 'uuid';
+import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
+import { mergeSockets } from './mergeSockets.js';
+import type { ConversionRule } from '@/store/conversions';
+import type { IBehaveNode } from '@/types/nodes.js';
+
+/**
+ * Find a node spec that converts `sourceType` to `targetType` , a pure value
+ * function with exactly one value input of the source type and one value output
+ * of the target type, and no flow sockets (e.g. `math/toString/integer`).
+ */
+export const findConverterSpec = (
+  specs: NodeSpecJSON[],
+  sourceType: string,
+  targetType: string
+): NodeSpecJSON | undefined =>
+  specs.find((spec) => {
+    const valueIns = spec.inputs.filter((i) => i.valueType !== 'flow');
+    const valueOuts = spec.outputs.filter((o) => o.valueType !== 'flow');
+    const hasFlow =
+      spec.inputs.some((i) => i.valueType === 'flow') ||
+      spec.outputs.some((o) => o.valueType === 'flow');
+    return (
+      !hasFlow &&
+      valueIns.length === 1 &&
+      valueOuts.length === 1 &&
+      valueIns[0]!.valueType === sourceType &&
+      valueOuts[0]!.valueType === targetType
+    );
+  });
+
+export type ResolvedConverter = {
+  nodeType: string;
+  inputName: string;
+  outputName: string;
+};
+
+const firstValueSocketName = (
+  sockets: { name: string; valueType: string }[]
+): string | undefined => sockets.find((s) => s.valueType !== 'flow')?.name;
+
+/**
+ * Pick the socket that should carry a value of `valueType`: prefer one whose type
+ * matches exactly (so multi-port converter nodes resolve the *right* port), then
+ * fall back to the first non-flow socket for single-port nodes.
+ */
+const socketNameForType = (
+  sockets: { name: string; valueType: string }[],
+  valueType: string
+): string | undefined =>
+  sockets.find((s) => s.valueType === valueType)?.name ??
+  firstValueSocketName(sockets);
+
+/**
+ * Resolve which converter to use for `from`→`to`. A registered
+ * {@link ConversionRule} (e.g. from a custom profile) takes precedence; otherwise
+ * fall back to scanning the specs for a generic single-in/single-out converter.
+ *
+ * A rule's `inputKey`/`outputKey` pin the exact ports to wire (required for
+ * converter nodes with more than one input or output). When omitted they are
+ * resolved by matching the port's value type to `from`/`to`.
+ */
+export const resolveConverter = (
+  specs: NodeSpecJSON[],
+  from: string,
+  to: string,
+  conversions?: ConversionRule[]
+): ResolvedConverter | undefined => {
+  const rule = conversions?.find((c) => c.from === from && c.to === to);
+  if (rule) {
+    const spec = specs.find((s) => s.type === rule.nodeType);
+    const inputName =
+      rule.inputKey ?? socketNameForType(spec?.inputs ?? [], from);
+    const outputName =
+      rule.outputKey ?? socketNameForType(spec?.outputs ?? [], to);
+    if (inputName && outputName) {
+      return { nodeType: rule.nodeType, inputName, outputName };
+    }
+    return undefined;
+  }
+
+  const spec = findConverterSpec(specs, from, to);
+  if (!spec) return undefined;
+  const inputName = firstValueSocketName(spec.inputs);
+  const outputName = firstValueSocketName(spec.outputs);
+  if (!inputName || !outputName) return undefined;
+  return { nodeType: spec.type, inputName, outputName };
+};
+
+/** Resolve a node socket's value type (spec sockets merged with dynamic ports). */
+const getSocketValueType = (
+  node: IBehaveNode,
+  handleId: string | null | undefined,
+  handleType: 'source' | 'target',
+  specs: NodeSpecJSON[]
+): string | undefined => {
+  if (!handleId) return undefined;
+  const specSockets = getSocketsByNodeTypeAndHandleType(
+    specs,
+    node.data?.type,
+    handleType
+  );
+  if (!specSockets) return undefined;
+  const dynamic =
+    handleType === 'source'
+      ? node.data.dynamicPorts?.outputs
+      : node.data.dynamicPorts?.inputs;
+  const sockets = mergeSockets(specSockets, dynamic);
+  return sockets.find((s) => s.name === handleId)?.valueType;
+};
+
+export type ConverterInsertion = { node: IBehaveNode; edges: Edge[] };
+
+/**
+ * If a connection joins different-but-convertible value types, build the
+ * converter node and the two edges needed to splice it in between source and
+ * target. Returns null when the types match, can't be resolved, or no converter
+ * is registered.
+ */
+export const buildConverterInsertion = (
+  connection: Connection,
+  nodes: Node[],
+  specs: NodeSpecJSON[],
+  conversions?: ConversionRule[]
+): ConverterInsertion | null => {
+  if (!connection.source || !connection.target) return null;
+
+  const sourceNode = nodes.find((n) => n.id === connection.source) as
+    | IBehaveNode
+    | undefined;
+  const targetNode = nodes.find((n) => n.id === connection.target) as
+    | IBehaveNode
+    | undefined;
+  if (!sourceNode || !targetNode) return null;
+
+  const sourceType = getSocketValueType(
+    sourceNode,
+    connection.sourceHandle,
+    'source',
+    specs
+  );
+  const targetType = getSocketValueType(
+    targetNode,
+    connection.targetHandle,
+    'target',
+    specs
+  );
+  if (!sourceType || !targetType) return null;
+  if (sourceType === targetType) return null;
+  if (sourceType === 'flow' || targetType === 'flow') return null;
+
+  const converter = resolveConverter(
+    specs,
+    sourceType,
+    targetType,
+    conversions
+  );
+  if (!converter) return null;
+
+  const { nodeType, inputName: inName, outputName: outName } = converter;
+
+  const position: XYPosition = {
+    x: (sourceNode.position.x + targetNode.position.x) / 2,
+    y: (sourceNode.position.y + targetNode.position.y) / 2
+  };
+
+  const convId = uuidv4();
+  const node: IBehaveNode = {
+    id: convId,
+    type: 'behaveNode',
+    position,
+    data: {
+      type: nodeType,
+      configuration: {},
+      ports: {},
+      dynamicPorts: {}
+    }
+  };
+
+  const edges: Edge[] = [
+    {
+      id: uuidv4(),
+      source: connection.source,
+      sourceHandle: connection.sourceHandle ?? undefined,
+      target: convId,
+      targetHandle: inName
+    },
+    {
+      id: uuidv4(),
+      source: convId,
+      sourceHandle: outName,
+      target: connection.target,
+      targetHandle: connection.targetHandle ?? undefined
+    }
+  ];
+
+  return { node, edges };
+};

package/src/util/isValidConnection.ts

@@ -3,12 +3,15 @@ import type { Connection, ReactFlowInstance } from 'reactflow';
 import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
 import { isHandleConnected } from './isHandleConnected.js';
 import { mergeSockets } from './mergeSockets.js';
+import { resolveConverter } from './autoConvert.js';
+import type { ConversionRule } from '@/store/conversions';
 import type { IBehaveNode } from '@/types/nodes.js';
 
 export const isValidConnection = (
   connection: Connection,
   instance: ReactFlowInstance,
-  specJSON: NodeSpecJSON[]
+  specJSON: NodeSpecJSON[],
+  options?: { autoConvert?: boolean; conversions?: ConversionRule[] }
 ) => {
   if (connection.source === null || connection.target === null) return false;
 
@@ -60,5 +63,23 @@ export const isValidConnection = (
     return false;
   }
 
-  return sourceSocket.valueType === targetSocket.valueType;
+  if (sourceSocket.valueType === targetSocket.valueType) return true;
+
+  // Different value types are allowed when auto-convert can splice in a
+  // converter node (handled on connect).
+  if (
+    options?.autoConvert &&
+    sourceSocket.valueType !== 'flow' &&
+    targetSocket.valueType !== 'flow' &&
+    resolveConverter(
+      specJSON,
+      sourceSocket.valueType,
+      targetSocket.valueType,
+      options.conversions
+    )
+  ) {
+    return true;
+  }
+
+  return false;
 };

package/stories/defaults/defaultStoryProvider.tsx

@@ -1,16 +1,14 @@
-import { docsPlugin } from '@/plugin/docs';
-
-import { SystemProvider } from '@/system/provider';
+import { SystemProvider, GraphProvider } from '@/system/provider';
 import { System } from '@/system/system';
 import {
   registerCoreProfile,
   type ValueType
 } from '@kiberon-labs/behave-graph';
 
-import { alignmentPlugin } from '@/plugin/alignment';
-import { downloadJson, localGraphRunnerPlugin } from '@/index';
+import { kitchenSinkPlugin } from '@/plugin/kitchen-sink';
+import { localGraphRunnerPlugin } from '@/index';
 
-export const ColorValue: ValueType = {
+const ColorValue: ValueType = {
   name: 'color',
   creator: () => '#000000',
   deserialize: (value: string) => value,
@@ -37,13 +35,14 @@ const nodeRegistry = {
 //Basic system generator for tests and stories
 export const systemGenerator = () => {
   const defaultSys = new System(nodeRegistry);
+  defaultSys.registerPlugin(kitchenSinkPlugin);
   return defaultSys;
 };
 
 const defaultSys = new System(nodeRegistry);
+const defaultSession = defaultSys.createSession('graph');
 
-defaultSys.registerPlugin(alignmentPlugin);
-defaultSys.registerPlugin(docsPlugin);
+defaultSys.registerPlugin(kitchenSinkPlugin);
 defaultSys.registerPlugin(localGraphRunnerPlugin, {
   registry: coreRegistry,
   events: [
@@ -73,11 +72,11 @@ defaultSys.registerPlugin(localGraphRunnerPlugin, {
   ]
 });
 
-defaultSys.pubsub.subscribe('graph:saved', (_, graph) => {
-  downloadJson('graph.json', graph);
-});
+// Saving is wired by default on the System (download-to-file); no per-story
+// subscription is needed. Override with defaultSys.enablePersistence(...) only
+// when a story needs to demonstrate a custom sink.
 
-defaultSys.flowStore.getState().setGraph({
+defaultSession.flowStore.getState().setGraph({
   nodes: [
     {
       type: 'lifecycle/onStart',
@@ -151,7 +150,7 @@ const exampleLogTime = (h: number, m: number, s: number, ms: number) =>
     message: 'debug/log: failed to resolve socket "value" on node 3.'
   }
 ].forEach((entry, index) => {
-  defaultSys.logsStore.getState().append({
+  defaultSession.logsStore.getState().append({
     type: entry.type,
     data: { message: entry.message },
     time: exampleLogTime(13, 45, 30 + index, 120 + index * 37)
@@ -163,5 +162,9 @@ export const DefaultSystemProvider = ({
 }: {
   children: React.ReactElement;
 }) => {
-  return <SystemProvider value={defaultSys}>{children}</SystemProvider>;
+  return (
+    <SystemProvider value={defaultSys}>
+      <GraphProvider value={defaultSession}>{children}</GraphProvider>
+    </SystemProvider>
+  );
 };

package/stories/defaults/systemGenerator.ts

@@ -1,11 +1,12 @@
 import { System } from '@/system/system';
+import { kitchenSinkPlugin } from '@/plugin/kitchen-sink';
 import {
   registerCoreProfile,
   writeNodeSpecsToJSON,
   type ValueType
 } from '@kiberon-labs/behave-graph';
 
-export const ColorValue: ValueType = {
+const ColorValue: ValueType = {
   name: 'color',
   creator: () => '#000000',
   deserialize: (value: string) => value,
@@ -34,5 +35,9 @@ const nodeRegistry = {
 //Basic system generator for tests and stories
 export const systemGenerator = () => {
   const defaultSys = new System(nodeRegistry);
+  defaultSys.createSession('graph');
+  // Standard editor UI bundle (docs, alignment, layout, notes) so stories built
+  // on this generator get the full editor without wiring plugins per story.
+  defaultSys.registerPlugin(kitchenSinkPlugin);
   return defaultSys;
 };