project-graph-mcp 2.3.0 → 2.3.2

package/vendor/symbiote-node/engine/HandlerLoader.js

@@ -0,0 +1,145 @@
+/**
+ * HandlerLoader.js - File-based node handler loader
+ *
+ * Scans directories for .handler.js files and registers them
+ * as node types. Supports hot reload via fs.watch.
+ *
+ * Handler file convention:
+ *   export default {
+ *     type: 'category/name',
+ *     category: 'category',
+ *     icon: 'icon_name',
+ *     driver: { inputs, outputs, params, ... },
+ *     lifecycle: { validate, cacheKey, execute, postProcess },
+ *   };
+ *
+ * @module symbiote-node/HandlerLoader */
+
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, extname } from 'node:path';
+import { watch } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { registerNodeType } from './Registry.js';
+
+/**
+ * Recursively find all .handler.js files in a directory
+ * @param {string} dir - Directory to scan
+ * @returns {Promise<string[]>} Absolute file paths
+ */
+async function findHandlerFiles(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await findHandlerFiles(fullPath);
+      results.push(...nested);
+    } else if (entry.name.endsWith('.handler.js')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Load a single handler file and register it
+ * @param {string} filePath - Absolute path to .handler.js file
+ * @returns {Promise<string|null>} Registered type name or null on error
+ */
+async function loadHandler(filePath) {
+  const fileUrl = pathToFileURL(filePath).href;
+  // Cache-bust for hot reload
+  const url = `${fileUrl}?t=${Date.now()}`;
+
+  const module = await import(url);
+  const handler = module.default;
+
+  if (!handler?.type) {
+    throw new Error(`Handler file ${filePath} missing 'type' field in default export`);
+  }
+
+  // Build node type definition from handler
+  const nodeDef = {
+    type: handler.type,
+    category: handler.category || handler.type.split('/')[0],
+    icon: handler.icon,
+    driver: handler.driver || {},
+  };
+
+  // Attach lifecycle hooks if present
+  if (handler.lifecycle) {
+    nodeDef.lifecycle = handler.lifecycle;
+  }
+
+  // Attach process function if present (legacy mode)
+  if (handler.process) {
+    nodeDef.process = handler.process;
+  }
+
+  registerNodeType(nodeDef);
+  return handler.type;
+}
+
+/**
+ * Scan a directory for .handler.js files and register them
+ * @param {string} dir - Directory to scan (e.g., 'nodes/')
+ * @returns {Promise<string[]>} List of registered type names
+ */
+export async function loadHandlers(dir) {
+  const files = await findHandlerFiles(dir);
+  const registered = [];
+
+  for (const file of files) {
+    try {
+      const type = await loadHandler(file);
+      if (type) registered.push(type);
+    } catch (err) {
+      console.error(`[symbiote-node] Failed to load handler ${relative(dir, file)}: ${err.message}`);    }
+  }
+
+  return registered;
+}
+
+/**
+ * Watch a directory for new/changed .handler.js files
+ * Auto-registers them on change.
+ *
+ * @param {string} dir - Directory to watch
+ * @param {object} [options={}]
+ * @param {function} [options.onRegister] - Callback(type, filePath)
+ * @param {function} [options.onError] - Callback(filePath, error)
+ * @returns {{close: function}} Watcher handle
+ */
+export function watchHandlers(dir, options = {}) {
+  const { onRegister, onError } = options;
+
+  const watcher = watch(dir, { recursive: true }, async (eventType, filename) => {
+    if (!filename?.endsWith('.handler.js')) return;
+
+    const filePath = join(dir, filename);
+
+    // Verify file exists (could be a delete event)
+    try {
+      await stat(filePath);
+    } catch {
+      return; // File deleted, ignore
+    }
+
+    try {
+      const type = await loadHandler(filePath);
+      if (type && onRegister) onRegister(type, filePath);
+    } catch (err) {
+      if (onError) onError(filePath, err);
+      else console.error(`[symbiote-node] Watch error for ${filename}: ${err.message}`);    }
+  });
+
+  return {
+    close: () => watcher.close(),
+  };
+}

package/vendor/symbiote-node/engine/History.js

@@ -0,0 +1,83 @@
+/**
+ * History.js - Snapshot-based undo/redo for graphs
+ *
+ * Stores deep-cloned snapshots of nodes and connections.
+ * Framework-agnostic — works with any graph data.
+ *
+ * @module agi-graph/History
+ */
+
+const MAX_HISTORY = 50;
+
+export class History {
+
+  /** @type {Array<{nodes: object[], connections: object[]}>} */
+  _states = [];
+
+  /** @type {number} */
+  _index = -1;
+
+  /**
+   * Push a new state snapshot
+   * @param {object[]} nodes
+   * @param {object[]} connections
+   */
+  push(nodes, connections) {
+    this._states.length = this._index + 1;
+    this._states.push({
+      nodes: JSON.parse(JSON.stringify(nodes)),
+      connections: JSON.parse(JSON.stringify(connections)),
+    });
+    if (this._states.length > MAX_HISTORY) {
+      this._states.shift();
+    }
+    this._index = this._states.length - 1;
+  }
+
+  /**
+   * Undo — return previous state
+   * @returns {{nodes: object[], connections: object[]}|null}
+   */
+  undo() {
+    if (!this.canUndo) return null;
+    this._index--;
+    return this._clone(this._states[this._index]);
+  }
+
+  /**
+   * Redo — return next state
+   * @returns {{nodes: object[], connections: object[]}|null}
+   */
+  redo() {
+    if (!this.canRedo) return null;
+    this._index++;
+    return this._clone(this._states[this._index]);
+  }
+
+  /** @returns {boolean} */
+  get canUndo() { return this._index > 0; }
+
+  /** @returns {boolean} */
+  get canRedo() { return this._index < this._states.length - 1; }
+
+  /** @returns {number} */
+  get depth() { return this._states.length; }
+
+  /** @returns {number} */
+  get index() { return this._index; }
+
+  /** Clear all history */
+  clear() {
+    this._states = [];
+    this._index = -1;
+  }
+
+  /**
+   * @param {{nodes: object[], connections: object[]}} state
+   * @returns {{nodes: object[], connections: object[]}}
+   * @private
+   */
+  _clone(state) {
+    return JSON.parse(JSON.stringify(state));
+  }
+}

package/vendor/symbiote-node/engine/Lifecycle.js

@@ -0,0 +1,118 @@
+/**
+ * Lifecycle.js - Node lifecycle pipeline
+ *
+ * Every node can define lifecycle hooks: validate, cacheKey, execute, postProcess.
+ * The lifecycle runner orchestrates these steps with cache awareness.
+ *
+ * @module agi-graph/Lifecycle
+ */
+
+/**
+ * @typedef {object} LifecycleHooks
+ * @property {function} [validate] - (inputs) => boolean — return false to abort
+ * @property {function} [cacheKey] - (inputs, params) => string — custom cache key
+ * @property {function} [execute] - (inputs, params) => outputs — main processing (async)
+ * @property {function} [postProcess] - (outputs) => outputs — transform before output
+ */
+
+/**
+ * @typedef {object} CacheState
+ * @property {'auto'|'freeze'|'force'} mode - Cache behavior mode
+ * @property {Map<string, {key: string, outputs: object}>} store - Cache storage
+ * @property {string} nodeId - Current node ID
+ */
+
+/**
+ * @typedef {object} LifecycleResult
+ * @property {object} outputs - Final outputs from the node
+ * @property {boolean} cached - Whether result came from cache
+ * @property {string|null} error - Error message if validation failed
+ * @property {string|null} cacheHash - Cache key used (for UI display)
+ */
+
+/**
+ * Default cache key: JSON hash of inputs + params
+ * @param {object} inputs
+ * @param {object} params
+ * @returns {string}
+ */
+function defaultCacheKey(inputs, params) {
+  return JSON.stringify({ i: inputs, p: params });
+}
+
+/**
+ * Run lifecycle pipeline for a node
+ *
+ * Flow:
+ * 1. validate(inputs) → false = abort with error
+ * 2. cacheKey(inputs, params) → compute hash
+ * 3. Check mode: freeze → return cached; force → skip; auto → check hash
+ * 4. execute(inputs, params) → outputs
+ * 5. postProcess(outputs) → final outputs
+ * 6. Store in cache
+ *
+ * @param {LifecycleHooks} hooks - Lifecycle hooks from driver
+ * @param {object} inputs - Resolved inputs from upstream
+ * @param {object} params - Node parameters
+ * @param {CacheState} cacheState - Cache state for this node
+ * @returns {Promise<LifecycleResult>}
+ */
+export async function runLifecycle(hooks, inputs, params, cacheState) {
+  const { mode = 'auto', store, nodeId } = cacheState;
+
+  // Step 1: Validate
+  if (hooks.validate) {
+    try {
+      const valid = hooks.validate(inputs);
+      if (valid === false) {
+        return { outputs: null, cached: false, error: 'Validation failed', cacheHash: null };
+      }
+    } catch (err) {
+      return { outputs: null, cached: false, error: `Validation error: ${err.message}`, cacheHash: null };
+    }
+  }
+
+  // Step 2: Compute cache key
+  const cacheKeyFn = hooks.cacheKey || defaultCacheKey;
+  const cacheHash = cacheKeyFn(inputs, params);
+
+  // Step 3: Check cache based on mode
+  const cached = store.get(nodeId);
+
+  if (mode === 'freeze' && cached) {
+    return { outputs: cached.outputs, cached: true, error: null, cacheHash: cached.key };
+  }
+
+  if (mode === 'auto' && cached && cached.key === cacheHash) {
+    return { outputs: cached.outputs, cached: true, error: null, cacheHash };
+  }
+
+  // mode === 'force' → skip cache check entirely
+
+  // Step 4: Execute
+  const executeFn = hooks.execute;
+  if (!executeFn) {
+    return { outputs: null, cached: false, error: 'No execute hook defined', cacheHash };
+  }
+
+  let outputs;
+  try {
+    outputs = await executeFn(inputs, params);
+  } catch (err) {
+    return { outputs: null, cached: false, error: `Execution error: ${err.message}`, cacheHash };
+  }
+
+  // Step 5: PostProcess
+  if (hooks.postProcess) {
+    try {
+      outputs = hooks.postProcess(outputs);
+    } catch (err) {
+      return { outputs: null, cached: false, error: `PostProcess error: ${err.message}`, cacheHash };
+    }
+  }
+
+  // Step 6: Store in cache
+  store.set(nodeId, { key: cacheHash, outputs });
+
+  return { outputs, cached: false, error: null, cacheHash };
+}

package/vendor/symbiote-node/engine/Persistence.js

@@ -0,0 +1,84 @@
+/**
+ * Persistence.js - File-based graph save/load
+ *
+ * Serializes Graph to .workflow.json and loads it back.
+ * Works in Node.js (fs) and browser (Blob/FileReader).
+ *
+ * @module agi-graph/Persistence
+ */
+
+import { Graph } from './Graph.js';
+
+/**
+ * Save graph to JSON string
+ * @param {Graph} graph
+ * @param {object} [options={}]
+ * @param {boolean} [options.pretty=true] - Pretty-print JSON
+ * @param {boolean} [options.includeOutput=false] - Include _output cache in export
+ * @returns {string} JSON string
+ */
+export function serialize(graph, options = {}) {
+  const { pretty = true, includeOutput = false } = options;
+  const data = graph.toJSON();
+
+  // Strip _output unless explicitly requested
+  if (!includeOutput) {
+    data.nodes = data.nodes.map(n => {
+      const { _output, ...rest } = n;
+      return rest;
+    });
+  }
+
+  return JSON.stringify(data, null, pretty ? 2 : 0);
+}
+
+/**
+ * Load graph from JSON string
+ * @param {string} json
+ * @returns {Graph}
+ */
+export function deserialize(json) {
+  const data = JSON.parse(json);
+  return new Graph(data);
+}
+
+/**
+ * Save graph to file (Node.js)
+ * @param {Graph} graph
+ * @param {string} filePath
+ * @param {object} [options]
+ * @returns {Promise<void>}
+ */
+export async function saveToFile(graph, filePath, options) {
+  const json = serialize(graph, options);
+  const { writeFile } = await import('node:fs/promises');
+  await writeFile(filePath, json, 'utf-8');
+}
+
+/**
+ * Load graph from file (Node.js)
+ * @param {string} filePath
+ * @returns {Promise<Graph>}
+ */
+export async function loadFromFile(filePath) {
+  const { readFile } = await import('node:fs/promises');
+  const json = await readFile(filePath, 'utf-8');
+  return deserialize(json);
+}
+
+/**
+ * Download graph as file (Browser)
+ * @param {Graph} graph
+ * @param {string} [filename='graph.workflow.json']
+ * @param {object} [options]
+ */
+export function downloadGraph(graph, filename = 'graph.workflow.json', options) {
+  const json = serialize(graph, options);
+  const blob = new Blob([json], { type: 'application/json' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}

package/vendor/symbiote-node/engine/Registry.js

@@ -0,0 +1,264 @@
+/**
+ * Registry.js - Node type and driver registry
+ *
+ * Central registry for node types, drivers, and domain packs.
+ * AI agents use this to discover, compose, and validate nodes.
+ *
+ * @module agi-graph/Registry
+ */
+
+import { areSocketsCompatible, registerSocketTypes } from './SocketTypes.js';
+
+/**
+ * @typedef {object} SocketDef
+ * @property {string} name - Socket name
+ * @property {string} type - Socket type (must be registered in SocketTypes)
+ * @property {boolean} [required] - Whether this input is required
+ * @property {string} [description] - Human-readable description for AI
+ */
+
+/**
+ * @typedef {object} ParamDef
+ * @property {string} type - Parameter type (string, int, float, boolean, object, array)
+ * @property {*} [default] - Default value
+ * @property {number} [min] - Min value (for numeric types)
+ * @property {number} [max] - Max value (for numeric types)
+ * @property {Array} [enum] - Allowed values
+ * @property {boolean} [required] - Whether this param is required
+ * @property {string} [description] - Human-readable description
+ */
+
+/**
+ * @typedef {object} Driver
+ * @property {string} description - What this node type does (for AI discovery)
+ * @property {string[]} [capabilities] - Tags for AI search
+ * @property {SocketDef[]} inputs - Input socket definitions
+ * @property {SocketDef[]} outputs - Output socket definitions
+ * @property {Record<string, ParamDef>} [params] - Parameter definitions
+ * @property {object} [dynamicOutputs] - Dynamic socket pattern definition
+ * @property {object} [constraints] - Requirements (secrets, SSH, etc.)
+ */
+
+/**
+ * @typedef {object} NodeTypeDef
+ * @property {string} type - Unique node type identifier (e.g., 'ai/llm')
+ * @property {Driver} driver - Self-describing driver manifest
+ * @property {function} [process] - Execution function: (inputs, params) => outputs
+ * @property {string} [icon] - Material icon name for UI
+ * @property {string} [category] - Category for UI grouping
+ */
+
+/** @type {Map<string, NodeTypeDef>} */
+const _nodeTypes = new Map();
+
+/** @type {Map<string, object>} */
+const _packs = new Map();
+
+/**
+ * Register a single node type
+ * @param {NodeTypeDef} def
+ */
+export function registerNodeType(def) {
+  if (!def.type) throw new Error('Node type definition must have a "type" field');
+  if (!def.driver) throw new Error(`Node type "${def.type}" must have a "driver" field`);
+  _nodeTypes.set(def.type, def);
+}
+
+/**
+ * Register a domain pack (batch registration of node types + socket types)
+ * @param {object} pack
+ * @param {string} pack.name - Pack name
+ * @param {Record<string, import('./SocketTypes.js').SocketTypeDef>} [pack.socketTypes]
+ * @param {NodeTypeDef[]} pack.nodes - Array of node type definitions
+ */
+export function registerPack(pack) {
+  if (!pack.name) throw new Error('Pack must have a "name" field');
+
+  if (pack.socketTypes) {
+    registerSocketTypes(pack.socketTypes);
+  }
+
+  for (const nodeDef of pack.nodes) {
+    registerNodeType(nodeDef);
+  }
+
+  _packs.set(pack.name, pack);
+}
+
+/**
+ * Get a node type definition
+ * @param {string} type
+ * @returns {NodeTypeDef|undefined}
+ */
+export function getNodeType(type) {
+  return _nodeTypes.get(type);
+}
+
+/**
+ * List all registered node types
+ * @returns {Array<{type: string, driver: Driver}>}
+ */
+export function listDrivers() {
+  return [..._nodeTypes.values()].map(def => ({
+    type: def.type,
+    driver: def.driver,
+    icon: def.icon,
+    category: def.category,
+  }));
+}
+
+/**
+ * Find node types compatible with a given output type
+ * @param {string} outputType - Socket type to match against inputs
+ * @returns {Array<{type: string, inputSocket: string, driver: Driver}>}
+ */
+export function findCompatible(outputType) {
+  const results = [];
+  for (const [type, def] of _nodeTypes) {
+    for (const input of def.driver.inputs) {
+      if (areSocketsCompatible(outputType, input.type)) {
+        results.push({ type, inputSocket: input.name, driver: def.driver });
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Find node types by capability tag
+ * @param {string} capability
+ * @returns {Array<{type: string, driver: Driver}>}
+ */
+export function findByCapability(capability) {
+  return [..._nodeTypes.values()]
+    .filter(def => def.driver.capabilities?.includes(capability))
+    .map(def => ({ type: def.type, driver: def.driver }));
+}
+
+/**
+ * Get node menu grouped by category (for UI context menus)
+ * @returns {Array<{category: string, nodes: Array<{type: string, icon: string, description: string}>}>}
+ */
+export function getNodeMenu() {
+  const grouped = {};
+  for (const [type, def] of _nodeTypes) {
+    const cat = def.category || type.split('/')[0];
+    if (!grouped[cat]) grouped[cat] = [];
+    grouped[cat].push({
+      type,
+      icon: def.icon,
+      description: def.driver.description,
+    });
+  }
+  return Object.entries(grouped).map(([category, nodes]) => ({ category, nodes }));
+}
+
+/**
+ * Register custom drivers from workflow JSON (AI-generated nodes)
+ * @param {Array<{type: string, driver: Driver, process: string}>} customDrivers
+ */
+export function registerCustomDrivers(customDrivers) {
+  for (const cd of customDrivers) {
+    registerNodeType({
+      type: cd.type,
+      driver: cd.driver,
+      category: cd.type.split('/')[0],
+      // Process stored as string in JSON — needs eval (sandboxed in production)
+      process: cd.process ? new Function('inputs', 'params', cd.process) : null,
+    });
+  }
+}
+
+/**
+ * Validate node params against driver schema
+ * @param {string} type - Node type
+ * @param {object} params - Params to validate
+ * @returns {{valid: boolean, errors: string[]}}
+ */
+export function validateParams(type, params) {
+  const def = _nodeTypes.get(type);
+  if (!def) return { valid: false, errors: [`Unknown node type: ${type}`] };
+
+  const validationErrors = [];
+  const schema = def.driver.params || {};
+
+  for (const [key, paramDef] of Object.entries(schema)) {
+    const val = params[key];
+
+    if (paramDef.required && (val === undefined || val === null)) {
+      validationErrors.push(`Missing required param: ${key}`);
+      continue;
+    }
+
+    if (val === undefined) continue;
+
+    if (paramDef.enum && !paramDef.enum.includes(val)) {
+      validationErrors.push(`Param "${key}" must be one of: ${paramDef.enum.join(', ')}. Got: ${val}`);
+    }
+
+    if (paramDef.min !== undefined && val < paramDef.min) {
+      validationErrors.push(`Param "${key}" must be >= ${paramDef.min}. Got: ${val}`);
+    }
+
+    if (paramDef.max !== undefined && val > paramDef.max) {
+      validationErrors.push(`Param "${key}" must be <= ${paramDef.max}. Got: ${val}`);
+    }
+  }
+
+  return { valid: validationErrors.length === 0, errors: validationErrors };
+}
+
+/**
+ * Get all registered packs
+ * @returns {string[]}
+ */
+export function listPacks() {
+  return [..._packs.keys()];
+}
+
+/**
+ * Clear all registrations (for testing)
+ */
+export function clearRegistry() {
+  _nodeTypes.clear();
+  _packs.clear();
+  // Re-register built-in types
+  _registerBuiltins();
+}
+
+/**
+ * Register built-in node types (compound infrastructure)
+ * @private
+ */
+function _registerBuiltins() {
+  _nodeTypes.set('compound/input', {
+    type: 'compound/input',
+    category: 'compound',
+    icon: 'input',
+    driver: {
+      description: 'Input bridge for compound nodes — receives data from parent graph',
+      capabilities: ['compound'],
+      inputs: [],
+      outputs: [{ name: 'data', type: 'any' }],
+      params: {},
+    },
+    process: (_inputs, params) => ({ ...params }),
+  });
+
+  _nodeTypes.set('compound/output', {
+    type: 'compound/output',
+    category: 'compound',
+    icon: 'output',
+    driver: {
+      description: 'Output bridge for compound nodes — sends data to parent graph',
+      capabilities: ['compound'],
+      inputs: [{ name: 'data', type: 'any' }],
+      outputs: [{ name: 'data', type: 'any' }],
+      params: {},
+    },
+    process: (inputs) => ({ ...inputs }),
+  });
+}
+
+// Register built-ins on module load
+_registerBuiltins();