project-graph-mcp 2.3.1 → 2.3.2

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

@@ -0,0 +1,314 @@
+/**
+ * Graph.js - Universal graph data model
+ *
+ * Stores nodes and connections. Provides CRUD operations
+ * for AI agents and programmatic graph construction.
+ *
+ * @module symbiote-node/Graph */
+
+import { nanoid } from './nanoid.js';
+import { getNodeType, registerCustomDrivers } from './Registry.js';
+import { areSocketsCompatible } from './SocketTypes.js';
+
+/**
+ * @typedef {object} GraphNode
+ * @property {string} id - Unique node ID (nd_ prefix)
+ * @property {string} type - Node type identifier
+ * @property {string} [name] - Human-readable label
+ * @property {object} params - Node parameters
+ * @property {'auto'|'freeze'|'force'} [cacheMode='auto'] - Cache behavior mode
+ * @property {object} [_output] - Cached execution output
+ * @property {object} [_meta] - Metadata (variant flags, etc.)
+ */
+
+/**
+ * @typedef {object} Connection
+ * @property {string} from - Source node ID
+ * @property {string} out - Source output socket name
+ * @property {string} to - Target node ID
+ * @property {string} in - Target input socket name
+ * @property {string} [type] - Semantic connection type (for knowledge graphs)
+ * @property {string} [label] - Human-readable connection label
+ */
+
+export class Graph {
+
+  /**
+   * @param {object} [data] - Optional workflow JSON to load
+   */
+  constructor(data) {
+    /** @type {string} */
+    this.id = `wf_${nanoid()}`;
+
+    /** @type {string} */
+    this.name = 'Untitled';
+
+    /** @type {number} */
+    this.version = 1;
+
+    /** @type {object} */
+    this.execution = { mode: 'sync', cache: true };
+
+    /** @type {Map<string, GraphNode>} */
+    this.nodes = new Map();
+
+    /** @type {Connection[]} */
+    this.connections = [];
+
+    /** @type {object} */
+    this.ui = { positions: {}, zoom: 1.0, pan: [0, 0] };
+
+    if (data) {
+      this.fromJSON(data);
+    }
+  }
+
+  /**
+   * Add a node to the graph
+   * @param {string} type - Node type (e.g., 'ai/llm')
+   * @param {object} [params={}] - Node parameters
+   * @param {object} [options={}] - Additional options
+   * @param {string} [options.id] - Custom node ID
+   * @param {string} [options.name] - Human-readable name
+   * @param {number[]} [options.position] - [x, y] position for UI
+   * @param {'auto'|'freeze'|'force'} [options.cacheMode='auto'] - Cache mode
+   * @returns {string} Node ID
+   */
+  addNode(type, params = {}, options = {}) {
+    const id = options.id || `nd_${nanoid()}`;
+
+    const typeDef = getNodeType(type);
+
+    // Merge defaults from driver
+    let mergedParams = { ...params };
+    if (typeDef?.driver?.params) {
+      for (const [key, paramDef] of Object.entries(typeDef.driver.params)) {
+        if (mergedParams[key] === undefined && paramDef.default !== undefined) {
+          mergedParams[key] = paramDef.default;
+        }
+      }
+    }
+
+    /** @type {GraphNode} */
+    const node = {
+      id,
+      type,
+      name: options.name || typeDef?.driver?.description?.slice(0, 30) || type,
+      params: mergedParams,
+      cacheMode: options.cacheMode || 'auto',
+    };
+
+    this.nodes.set(id, node);
+
+    if (options.position) {
+      this.ui.positions[id] = options.position;
+    }
+
+    return id;
+  }
+
+  /**
+   * Remove a node and all its connections
+   * @param {string} id - Node ID
+   * @returns {boolean}
+   */
+  removeNode(id) {
+    if (!this.nodes.has(id)) return false;
+    this.nodes.delete(id);
+    this.connections = this.connections.filter(c => c.from !== id && c.to !== id);
+    delete this.ui.positions[id];
+    return true;
+  }
+
+  /**
+   * Connect two nodes
+   * @param {string} fromNode - Source node ID
+   * @param {string} fromSocket - Source output socket name
+   * @param {string} toNode - Target node ID
+   * @param {string} toSocket - Target input socket name
+   * @param {object} [options={}]
+   * @param {string} [options.type] - Semantic connection type
+   * @param {string} [options.label] - Human-readable label
+   * @returns {Connection}
+   */
+  connect(fromNode, fromSocket, toNode, toSocket, options = {}) {
+    if (!this.nodes.has(fromNode)) throw new Error(`Source node "${fromNode}" not found`);
+    if (!this.nodes.has(toNode)) throw new Error(`Target node "${toNode}" not found`);
+
+    // Validate socket compatibility if drivers available
+    const fromType = getNodeType(this.nodes.get(fromNode).type);
+    const toType = getNodeType(this.nodes.get(toNode).type);
+
+    if (fromType?.driver?.outputs && toType?.driver?.inputs) {
+      const outDef = fromType.driver.outputs.find(o => o.name === fromSocket);
+      const inDef = toType.driver.inputs.find(i => i.name === toSocket);
+
+      if (outDef && inDef && !areSocketsCompatible(outDef.type, inDef.type)) {
+        throw new Error(`Socket type mismatch: ${outDef.type} → ${inDef.type} (${fromNode}.${fromSocket} → ${toNode}.${toSocket})`);
+      }
+    }
+
+    /** @type {Connection} */
+    const conn = {
+      from: fromNode,
+      out: fromSocket,
+      to: toNode,
+      in: toSocket,
+    };
+
+    if (options.type) conn.type = options.type;
+    if (options.label) conn.label = options.label;
+
+    this.connections.push(conn);
+    return conn;
+  }
+
+  /**
+   * Disconnect two nodes
+   * @param {string} fromNode
+   * @param {string} fromSocket
+   * @param {string} toNode
+   * @param {string} toSocket
+   * @returns {boolean}
+   */
+  disconnect(fromNode, fromSocket, toNode, toSocket) {
+    const idx = this.connections.findIndex(c =>
+      c.from === fromNode && c.out === fromSocket &&
+      c.to === toNode && c.in === toSocket
+    );
+    if (idx === -1) return false;
+    this.connections.splice(idx, 1);
+    return true;
+  }
+
+  /**
+   * Get a node by ID
+   * @param {string} id
+   * @returns {GraphNode|undefined}
+   */
+  getNode(id) {
+    return this.nodes.get(id);
+  }
+
+  /**
+   * Update node parameters
+   * @param {string} id
+   * @param {object} params - Params to merge
+   * @returns {GraphNode}
+   */
+  updateParams(id, params) {
+    const node = this.nodes.get(id);
+    if (!node) throw new Error(`Node "${id}" not found`);
+    node.params = { ...node.params, ...params };
+    return node;
+  }
+
+  /**
+   * Set cache mode for a node
+   * @param {string} id - Node ID
+   * @param {'auto'|'freeze'|'force'} mode
+   */
+  setCacheMode(id, mode) {
+    const node = this.nodes.get(id);
+    if (!node) throw new Error(`Node "${id}" not found`);
+    if (!['auto', 'freeze', 'force'].includes(mode)) {
+      throw new Error(`Invalid cache mode: ${mode}. Must be auto, freeze, or force`);
+    }
+    node.cacheMode = mode;
+  }
+
+  /**
+   * Get orphan nodes (not connected to anything)
+   * @returns {GraphNode[]}
+   */
+  getOrphans() {
+    const connected = new Set();
+    for (const c of this.connections) {
+      connected.add(c.from);
+      connected.add(c.to);
+    }
+    return [...this.nodes.values()].filter(n => !connected.has(n.id));
+  }
+
+  /**
+   * Serialize graph to JSON
+   * @returns {object}
+   */
+  toJSON() {
+    return {
+      version: this.version,
+      id: this.id,
+      name: this.name,
+      execution: this.execution,
+      nodes: [...this.nodes.values()].map(n => {
+        const obj = { id: n.id, type: n.type, name: n.name, params: n.params };
+        if (n.cacheMode && n.cacheMode !== 'auto') obj.cacheMode = n.cacheMode;
+        if (n._output) obj._output = n._output;
+        if (n._meta) obj._meta = n._meta;
+        if (n.driver) obj.driver = n.driver;
+        if (n.subgraph) obj.subgraph = n.subgraph;
+        return obj;
+      }),
+      connections: this.connections,
+      ui: this.ui,
+    };
+  }
+
+  /**
+   * Load graph from JSON
+   * @param {object} data - Workflow JSON
+   * @returns {Graph} this
+   */
+  fromJSON(data) {
+    this.version = data.version || 1;
+    this.id = data.id || this.id;
+    this.name = data.name || 'Untitled';
+    this.execution = data.execution || { mode: 'sync', cache: true };
+    this.ui = data.ui || { positions: {}, zoom: 1.0, pan: [0, 0] };
+
+    // Register custom drivers if present
+    if (data.customDrivers) {
+      registerCustomDrivers(data.customDrivers);
+    }
+
+    // Load nodes
+    this.nodes.clear();
+    for (const n of (data.nodes || [])) {
+      const node = { id: n.id, type: n.type, name: n.name, params: n.params || {}, cacheMode: n.cacheMode || 'auto' };
+      if (n._output) node._output = n._output;
+      if (n._meta) node._meta = n._meta;
+      if (n.driver) node.driver = n.driver;
+      if (n.subgraph) node.subgraph = n.subgraph;
+      this.nodes.set(n.id, node);
+    }
+
+    // Load connections (handle both {out, in} and {fromSocket, toSocket} DB formats)
+    this.connections = (data.connections || []).map(c => {
+      const conn = {
+        from: c.from,
+        out: c.out || c.fromSocket,
+        to: c.to,
+        in: c.in || c.toSocket,
+      };      if (c.type) conn.type = c.type;
+      if (c.label) conn.label = c.label;
+      return conn;
+    });
+
+    return this;
+  }
+
+  /**
+   * Get execution statistics
+   * @returns {object}
+   */
+  stats() {
+    const types = new Set();
+    for (const n of this.nodes.values()) types.add(n.type);
+    return {
+      totalNodes: this.nodes.size,
+      totalConnections: this.connections.length,
+      orphans: this.getOrphans().length,
+      uniqueTypes: types.size,
+    };
+  }
+}

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

@@ -0,0 +1,353 @@
+/**
+ * GraphServer.js - WebSocket + HTTP server for symbiote-node *
+ * Provides real-time graph synchronization between server and UI clients.
+ * Supports file-based workflow watching, handler hot-reload, and server-side execution.
+ *
+ * Protocol messages follow SPEC.md P23 Agent Bridge specification.
+ *
+ * @module symbiote-node/GraphServer */
+
+import { createServer as createHttpServer } from 'node:http';
+import { readFile, writeFile, watch as fsWatch } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import { WebSocketServer } from 'ws';
+
+import { Graph } from './Graph.js';
+import { Executor } from './Executor.js';
+import { getNodeType, listDrivers } from './Registry.js';
+import { loadHandlers, watchHandlers } from './HandlerLoader.js';
+
+/**
+ * @typedef {object} ServerOptions
+ * @property {number} [port=3100] - HTTP/WebSocket port
+ * @property {string} [handlersDir] - Directory for .handler.js files
+ * @property {string} [workflowFile] - Path to .workflow.json
+ * @property {boolean} [watchFiles=true] - Enable file watching
+ * @property {boolean} [verbose=false] - Verbose logging
+ */
+
+/**
+ * Create an symbiote-node server instance * @param {ServerOptions} options
+ * @returns {Promise<{server: import('http').Server, wss: WebSocketServer, graph: Graph, close: () => Promise<void>}>}
+ */
+export async function createServer(options = {}) {
+  const {
+    port = 3100,
+    handlersDir,
+    workflowFile,
+    watchFiles = true,
+    verbose = false,
+  } = options;
+
+  let graph = new Graph();
+  const executor = new Executor();
+  const watchers = [];
+  const log = verbose ? console.log.bind(console) : () => { };
+
+  // Load initial workflow
+  if (workflowFile) {
+    try {
+      const json = await readFile(resolve(workflowFile), 'utf-8');
+      const data = JSON.parse(json);
+      graph = deserialize(data);
+      log(`📄 Loaded workflow: ${workflowFile} (${graph.nodes.size} nodes)`);
+    } catch (err) {
+      log(`⚠️  Could not load workflow: ${err.message}`);
+    }
+  }
+
+  // Load handler files
+  if (handlersDir) {
+    const dir = resolve(handlersDir);
+    const registered = await loadHandlers(dir);
+    log(`🔧 Loaded ${registered.length} handler(s) from ${handlersDir}`);
+
+    if (watchFiles) {
+      const stopWatch = watchHandlers(dir, (type) => {
+        log(`♻️  Handler reloaded: ${type}`);
+        broadcast({ type: 'registry:add', payload: { type, category: type.split('/')[0] } });
+      });
+      watchers.push(stopWatch);
+    }
+  }
+
+  // ─── HTTP Server ────────────────────────────────────
+
+  const httpServer = createHttpServer(async (req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+
+    // CORS headers
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    try {
+      if (url.pathname === '/api/graph' && req.method === 'GET') {
+        const data = graph.toJSON();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(data));
+        return;
+      }
+
+      if (url.pathname === '/api/graph' && req.method === 'POST') {
+        const body = await readBody(req);
+        const data = JSON.parse(body);
+        graph = new Graph();
+        graph.fromJSON(data);
+        broadcast({ type: 'graph:update', payload: graph.toJSON() });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+
+      if (url.pathname === '/api/graph/execute' && req.method === 'POST') {
+        await executeGraph(res);
+        return;
+      }
+
+      if (url.pathname === '/api/registry' && req.method === 'GET') {
+        const drivers = listDrivers();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(drivers));
+        return;
+      }
+
+      // Health check
+      if (url.pathname === '/api/health') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', nodes: graph.nodes.size }));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end('Not Found');
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  });
+
+  // ─── WebSocket Server ────────────────────────────────
+
+  const wss = new WebSocketServer({ server: httpServer });
+  /** @type {Set<import('ws').WebSocket>} */
+  const clients = new Set();
+
+  wss.on('connection', (ws) => {
+    clients.add(ws);
+    log(`🔌 Client connected (${clients.size} total)`);
+
+    // Send current state on connect
+    ws.send(JSON.stringify({ type: 'graph:update', payload: graph.toJSON() }));
+
+    ws.on('message', async (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        await handleWsMessage(msg, ws);
+      } catch (err) {
+        ws.send(JSON.stringify({ type: 'error', payload: { message: err.message } }));
+      }
+    });
+
+    ws.on('close', () => {
+      clients.delete(ws);
+      log(`🔌 Client disconnected (${clients.size} total)`);
+    });
+  });
+
+  /**
+   * Broadcast message to all connected clients
+   * @param {object} msg
+   * @param {import('ws').WebSocket} [exclude] - Client to exclude
+   */
+  function broadcast(msg, exclude) {
+    const json = JSON.stringify(msg);
+    for (const client of clients) {
+      if (client !== exclude && client.readyState === 1) {
+        client.send(json);
+      }
+    }
+  }
+
+  /**
+   * Handle incoming WebSocket message
+   * @param {{type: string, payload: object}} msg
+   * @param {import('ws').WebSocket} ws
+   */
+  async function handleWsMessage(msg, ws) {
+    const { type, payload } = msg;
+
+    switch (type) {
+      case 'graph:action': {
+        const { action, nodeId, data } = payload;
+
+        switch (action) {
+          case 'addNode': {
+            const id = graph.addNode(data.type, data.params, data.options);
+            broadcast({ type: 'graph:update', payload: graph.toJSON() }, ws);
+            ws.send(JSON.stringify({ type: 'graph:actionResult', payload: { action, nodeId: id } }));
+            break;
+          }
+          case 'removeNode': {
+            graph.removeNode(nodeId);
+            broadcast({ type: 'graph:update', payload: graph.toJSON() }, ws);
+            break;
+          }
+          case 'connect': {
+            const { from, out, to, in: inp } = data;
+            graph.connect(from, out, to, inp);
+            broadcast({ type: 'graph:update', payload: graph.toJSON() }, ws);
+            break;
+          }
+          case 'updateParams': {
+            graph.updateParams(nodeId, data.params);
+            broadcast({ type: 'graph:update', payload: graph.toJSON() }, ws);
+            break;
+          }
+          case 'execute': {
+            await executeAndStream();
+            break;
+          }
+          default:
+            ws.send(JSON.stringify({ type: 'error', payload: { message: `Unknown action: ${action}` } }));
+        }
+        break;
+      }
+
+      // Agent UI commands — forward to all other clients
+      case 'ui:layout':
+      case 'ui:focus':
+      case 'ui:select':
+      case 'ui:navigate':
+      case 'ui:playback':
+      case 'ui:notify':
+      case 'ui:cursor':
+        broadcast(msg, ws);
+        break;
+
+      default:
+        ws.send(JSON.stringify({ type: 'error', payload: { message: `Unknown message type: ${type}` } }));
+    }
+  }
+
+  /**
+   * Execute graph and stream progress via WebSocket
+   */
+  async function executeAndStream() {
+    const result = await executor.run(graph, {
+      onNodeStart: (nodeId) => {
+        broadcast({ type: 'node:progress', payload: { nodeId, progress: 0, phase: 'start' } });
+      },
+      onNodeComplete: (nodeId, output, timeMs) => {
+        const cached = !!(output && output._fromCache);
+        broadcast({ type: 'node:result', payload: { nodeId, status: 'done', cached, timeMs } });
+      },
+      onNodeSkipped: (nodeId) => {
+        broadcast({ type: 'node:result', payload: { nodeId, status: 'skipped' } });
+      },
+    });
+
+    broadcast({ type: 'graph:executed', payload: { totalTime: result.totalTime, log: result.log } });
+
+    // Save to workflow file if configured
+    if (workflowFile) {
+      try {
+        await writeFile(resolve(workflowFile), JSON.stringify(graph.toJSON(), null, 2));
+      } catch (err) {
+        log(`⚠️  Could not save workflow: ${err.message}`);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute graph via HTTP and return result
+   * @param {import('http').ServerResponse} res
+   */
+  async function executeGraph(res) {
+    try {
+      const result = await executeAndStream();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: true,
+        totalTime: result.totalTime,
+        outputs: result.outputs,
+        log: result.log,
+      }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  }
+
+  // ─── File Watching ────────────────────────────────
+
+  if (watchFiles && workflowFile) {
+    const wfPath = resolve(workflowFile);
+    let debounce = null;
+    const ac = new AbortController();
+
+    (async () => {
+      try {
+        const watcher = fsWatch(wfPath, { signal: ac.signal });
+        for await (const event of watcher) {
+          if (debounce) clearTimeout(debounce);
+          debounce = setTimeout(async () => {
+            try {
+              const json = await readFile(wfPath, 'utf-8');
+              const data = JSON.parse(json);
+              graph = deserialize(data);
+              broadcast({ type: 'graph:update', payload: data });
+              log(`📄 Workflow reloaded: ${workflowFile}`);
+            } catch (err) {
+              log(`⚠️  Workflow reload error: ${err.message}`);
+            }
+          }, 200);
+        }
+      } catch (err) {
+        if (err.name !== 'AbortError') log(`⚠️  Workflow watch error: ${err.message}`);
+      }
+    })();
+
+    watchers.push(() => ac.abort());
+  }
+
+  // ─── Start & Close ────────────────────────────────
+
+  await new Promise((resolve) => httpServer.listen(port, resolve));
+  log(`🚀 symbiote-node server on http://localhost:${port}`);
+  async function close() {
+    for (const stop of watchers) {
+      if (typeof stop === 'function') stop();
+    }
+    for (const client of clients) {
+      client.close();
+    }
+    wss.close();
+    await new Promise((resolve) => httpServer.close(resolve));
+    log('🛑 Server stopped');
+  }
+
+  return { server: httpServer, wss, graph, executor, broadcast, close };
+}
+
+/**
+ * Read HTTP request body
+ * @param {import('http').IncomingMessage} req
+ * @returns {Promise<string>}
+ */
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => resolve(body));
+    req.on('error', reject);
+  });
+}