@zibby/core 0.1.0

package/src/framework/function-bridge.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Function Bridge — wraps plain handler functions in an MCP server.
+ *
+ * Usage: node function-bridge.js <modulePath> <skillId>
+ *
+ * 1. Dynamically imports the user's module (which calls functionSkill(),
+ *    populating the handler registry).
+ * 2. Reads the registered handlers and tool schemas.
+ * 3. Starts an MCP server over stdio so agent strategies can talk to it.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const [modulePath, skillId] = process.argv.slice(2);
+
+if (!modulePath || !skillId) {
+  console.error('Usage: node function-bridge.js <modulePath> <skillId>');
+  process.exit(1);
+}
+
+await import(modulePath);
+
+const { getHandlers } = await import('./function-skill-registry.js');
+const registration = getHandlers(skillId);
+
+if (!registration) {
+  console.error(`No handlers registered for skill "${skillId}". Did the module call functionSkill()?`);
+  process.exit(1);
+}
+
+const { handlers, tools } = registration;
+
+function jsonSchemaToZod(schema) {
+  if (!schema || schema.type !== 'object') return z.object({});
+
+  const shape = {};
+  for (const [key, prop] of Object.entries(schema.properties || {})) {
+    let field;
+    switch (prop.type) {
+      case 'number': case 'integer': field = z.number(); break;
+      case 'boolean': field = z.boolean(); break;
+      case 'array': field = z.array(z.any()); break;
+      default: field = z.string(); break;
+    }
+    if (prop.description) field = field.describe(prop.description);
+    if (!schema.required?.includes(key)) field = field.optional();
+    shape[key] = field;
+  }
+  return z.object(shape);
+}
+
+const server = new McpServer(
+  { name: `zibby-fn-${skillId}`, version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+for (const tool of tools) {
+  const zodSchema = jsonSchemaToZod(tool.input_schema);
+  server.registerTool(
+    tool.name,
+    { title: tool.name, description: tool.description || '', inputSchema: zodSchema },
+    async (args) => {
+      try {
+        const result = await handlers[tool.name](args);
+        const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+      }
+    }
+  );
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/framework/function-skill-registry.js

@@ -0,0 +1,20 @@
+/**
+ * Function Skill Handler Registry
+ *
+ * Shared in-memory store for function skill handlers. When a module calls
+ * functionSkill(), handlers are stored here. When the bridge imports that
+ * module, it reads the handlers from this registry.
+ *
+ * This works because Node.js module caching ensures both the user's module
+ * and the bridge resolve to the same instance of this registry.
+ */
+
+const _registry = new Map();
+
+export function registerHandlers(skillId, handlers, tools) {
+  _registry.set(skillId, { handlers, tools });
+}
+
+export function getHandlers(skillId) {
+  return _registry.get(skillId) || null;
+}

package/src/framework/graph-compiler.js

@@ -0,0 +1,342 @@
+/* global require */
+import { WorkflowGraph } from './graph.js';
+import { getNodeImpl, hasNode } from './node-registry.js';
+import { resolveNodeTools } from './tool-resolver.js';
+import { logger } from '../utils/logger.js';
+
+export function compileGraph(config, options = {}) {
+  const { nodes, edges, nodeConfigs = {} } = config;
+
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    throw new CompilationError('Graph must have at least one node');
+  }
+  if (!Array.isArray(edges)) {
+    throw new CompilationError('Graph edges must be an array');
+  }
+
+  const graph = new WorkflowGraph(options);
+  
+  if (options.stateSchema) {
+    graph.setStateSchema(options.stateSchema);
+  }
+  
+  const decisionNodeIds = new Set();
+  const nodeMap = new Map();
+  const resolvedToolsMap = {};
+
+  // Pass 1: Identify decision nodes (visual-only, not executable)
+  for (const node of nodes) {
+    const nodeType = resolveNodeType(node);
+    nodeMap.set(node.id, { ...node, resolvedType: nodeType });
+    if (nodeType === 'decision') {
+      decisionNodeIds.add(node.id);
+    }
+  }
+
+  // Pass 2: Add executable nodes and resolve tools
+  for (const [nodeId, node] of nodeMap) {
+    if (decisionNodeIds.has(nodeId)) continue;
+
+    const nodeType = node.resolvedType;
+    const nodeConfig = nodeConfigs[nodeId] || {};
+    const userToolIds = nodeConfig.tools;
+    const resolved = resolveNodeTools(nodeType, userToolIds);
+    if (resolved) {
+      resolvedToolsMap[nodeId] = resolved;
+    }
+
+    const nodeOptions = {};
+    if (nodeConfig.prompt) {
+      nodeOptions.prompt = nodeConfig.prompt;
+    }
+
+    const isRegistered = hasNode(nodeType);
+    logger.debug(`[compiler] Node "${nodeId}" type="${nodeType}" registered=${isRegistered} hasCustomCode=${!!nodeConfig.customCode} hasExecuteCode=${!!nodeConfig.executeCode}`);
+
+    if (nodeConfig.customCode && !isRegistered) {
+      logger.debug(`[compiler]   → using customCode (unregistered node)`);
+      graph.addNode(nodeId, wrapCustomCode(nodeId, nodeConfig.customCode, nodeConfig), nodeOptions);
+      graph.setNodeType(nodeId, nodeType);
+    } else if (isRegistered) {
+      logger.debug(`[compiler]   → using registered implementation`);
+      const impl = getNodeImpl(nodeType);
+      if (impl.factory) {
+        graph.addNode(nodeId, impl.create(nodeId, {
+          ...nodeConfig,
+          resolvedTools: resolved
+        }), nodeOptions);
+      } else {
+        graph.addNode(nodeId, impl, nodeOptions);
+      }
+      graph.setNodeType(nodeId, nodeType);
+    } else if (nodeConfig.executeCode) {
+      logger.debug(`[compiler]   → using executeCode (fallback)`);
+      graph.addNode(nodeId, wrapCustomCode(nodeId, nodeConfig.executeCode, nodeConfig), nodeOptions);
+      graph.setNodeType(nodeId, nodeType);
+    } else {
+      throw new CompilationError(
+        `Unknown node type "${nodeType}" for node "${nodeId}". ` +
+        `Did you forget to register it?`
+      );
+    }
+  }
+
+  graph.resolvedToolsMap = resolvedToolsMap;
+
+  // Pass 3: Determine entry point (node with no incoming non-decision edges)
+  const incomingTargets = new Set();
+  for (const edge of edges) {
+    if (!decisionNodeIds.has(edge.target)) {
+      incomingTargets.add(edge.target);
+    }
+  }
+  const entryNode = nodes.find(
+    n => !decisionNodeIds.has(n.id) && !incomingTargets.has(n.id)
+  );
+  if (!entryNode) {
+    throw new CompilationError('Could not determine entry point: no node without incoming edges found');
+  }
+  graph.setEntryPoint(entryNode.id);
+
+  // Pass 4: Wire edges, collapsing decision nodes into addConditionalEdges
+  const edgesBySource = groupBy(edges, 'source');
+
+  for (const edge of edges) {
+    const sourceIsDecision = decisionNodeIds.has(edge.source);
+    const targetIsDecision = decisionNodeIds.has(edge.target);
+
+    if (sourceIsDecision) {
+      // Edges FROM decision nodes are handled when we process the edge INTO the decision
+      continue;
+    }
+
+    if (targetIsDecision) {
+      // Edge goes into a decision node: find all outgoing edges from the decision
+      // and compile them into a single addConditionalEdges call
+      const decisionId = edge.target;
+      const outgoingEdges = edgesBySource.get(decisionId) || [];
+
+      if (outgoingEdges.length === 0) {
+        throw new CompilationError(
+          `Decision node "${decisionId}" has no outgoing edges`
+        );
+      }
+
+      const routeFn = compileConditionalRoutes(decisionId, outgoingEdges, decisionNodeIds);
+      graph.addConditionalEdges(edge.source, routeFn);
+    } else {
+      // Regular edge between two executable nodes
+      graph.addEdge(edge.source, edge.target);
+    }
+  }
+
+  return graph;
+}
+
+export function validateGraphConfig(config) {
+  const errors = [];
+
+  if (!config || typeof config !== 'object') {
+    return { valid: false, errors: ['Config must be a non-null object'] };
+  }
+  if (!Array.isArray(config.nodes) || config.nodes.length === 0) {
+    errors.push('Graph must have at least one node');
+  }
+  if (!Array.isArray(config.edges)) {
+    errors.push('Graph edges must be an array');
+  }
+
+  if (errors.length > 0) return { valid: false, errors };
+
+  const nodeConfigs = config.nodeConfigs || {};
+
+  for (const node of config.nodes) {
+    const nodeType = resolveNodeType(node);
+    if (nodeType === 'decision') continue;
+    if (hasNode(nodeType)) continue;
+
+    const nc = nodeConfigs[node.id] || {};
+    if (nc.customCode || nc.executeCode) continue;
+
+    errors.push(`Unknown node type "${nodeType}" for node "${node.id}". Register it or provide customCode/executeCode.`);
+  }
+
+  // Check edge references are valid
+  const nodeIds = new Set(config.nodes.map(n => n.id));
+  for (const edge of config.edges) {
+    if (!nodeIds.has(edge.source)) {
+      errors.push(`Edge references unknown source node "${edge.source}"`);
+    }
+    if (!nodeIds.has(edge.target)) {
+      errors.push(`Edge references unknown target node "${edge.target}"`);
+    }
+  }
+
+  // Check for exactly one entry point
+  const decisionIds = new Set(
+    config.nodes.filter(n => resolveNodeType(n) === 'decision').map(n => n.id)
+  );
+  const incomingTargets = new Set();
+  for (const edge of config.edges) {
+    if (!decisionIds.has(edge.target)) {
+      incomingTargets.add(edge.target);
+    }
+  }
+  const entryNodes = config.nodes.filter(
+    n => !decisionIds.has(n.id) && !incomingTargets.has(n.id)
+  );
+  if (entryNodes.length === 0) {
+    errors.push('No entry point found (every node has incoming edges)');
+  } else if (entryNodes.length > 1) {
+    errors.push(
+      `Multiple entry points found: ${entryNodes.map(n => n.id).join(', ')}. Graph must have exactly one.`
+    );
+  }
+
+  // Check decision nodes have outgoing edges with conditionalCode
+  for (const decisionId of decisionIds) {
+    const outgoing = config.edges.filter(e => e.source === decisionId);
+    if (outgoing.length === 0) {
+      errors.push(`Decision node "${decisionId}" has no outgoing edges`);
+    }
+    const hasCode = outgoing.some(
+      e => e.data?.conditionalCode || e.conditionalCode
+    );
+    if (!hasCode) {
+      errors.push(`Decision node "${decisionId}" outgoing edges have no conditionalCode`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function extractSteps(config) {
+  if (!config || !Array.isArray(config.nodes)) return [];
+  return config.nodes
+    .filter(n => resolveNodeType(n) !== 'decision')
+    .map(n => n.id);
+}
+
+// ---- Internal helpers ----
+
+function resolveNodeType(node) {
+  const raw = node.data?.nodeType || node.data?.type || node.type;
+  // React Flow stores UI component type (e.g. "workflowNode", "custom") — fall back to node id
+  if (raw === 'workflowNode' || raw === 'custom' || raw === 'default') {
+    return node.id;
+  }
+  return raw;
+}
+
+function groupBy(arr, key) {
+  const map = new Map();
+  for (const item of arr) {
+    const k = item[key];
+    if (!map.has(k)) map.set(k, []);
+    map.get(k).push(item);
+  }
+  return map;
+}
+
+function compileConditionalRoutes(decisionId, outgoingEdges, decisionNodeIds) {
+  // All outgoing edges from a decision share the same conditionalCode
+  // (the function returns a node name string to route to)
+  const edgeWithCode = outgoingEdges.find(
+    e => e.data?.conditionalCode || e.conditionalCode
+  );
+
+  if (!edgeWithCode) {
+    throw new CompilationError(
+      `Decision node "${decisionId}" has no conditionalCode on its outgoing edges`
+    );
+  }
+
+  const code = edgeWithCode.data?.conditionalCode || edgeWithCode.conditionalCode;
+  const validTargets = new Set(
+    outgoingEdges.map(e => e.target).filter(t => !decisionNodeIds.has(t))
+  );
+
+  // Compile the route function string into an actual function
+  // The code is expected to be: "function route(state) { ... return 'node_name'; }"
+  let routeFn;
+  try {
+     
+    const factory = new Function(`return (${code})`);
+    const compiled = factory();
+
+    routeFn = (state) => {
+      const result = compiled(state);
+      if (!validTargets.has(result)) {
+        logger.warn(
+          `Conditional route from "${decisionId}" returned "${result}" ` +
+          `which is not a valid target. Valid: ${[...validTargets].join(', ')}`
+        );
+      }
+      return result;
+    };
+  } catch (err) {
+    throw new CompilationError(
+      `Failed to compile conditionalCode for decision "${decisionId}": ${err.message}`
+    );
+  }
+
+  return routeFn;
+}
+
+function wrapCustomCode(nodeId, codeString, nodeConfig = {}) {
+  let executeFn;
+  try {
+     
+    executeFn = new Function(
+      'invokeAgent', 'require', 'console',
+      `return (${codeString})`
+    );
+  } catch (err) {
+    throw new CompilationError(
+      `Failed to compile customCode for node "${nodeId}": ${err.message}`
+    );
+  }
+
+  const boundExecute = executeFn(
+    async (...args) => {
+      const { invokeAgent } = await import('./agents/index.js');
+      return invokeAgent(...args);
+    },
+    typeof require !== 'undefined' ? require : undefined,
+    console
+  );
+
+  // Reconstruct outputSchema from nodeConfig if available
+  let outputSchema = null;
+  if (nodeConfig.outputSchema) {
+    // Schema is already in JSON format from the enrichment
+    // For runtime, we need it as a validation object
+    // For now, we'll store the JSON schema for later use
+    outputSchema = nodeConfig.outputSchema.jsonSchema || nodeConfig.outputSchema;
+  }
+
+  return {
+    name: nodeId,
+    _isCustomCode: true,
+    outputSchema,  // Include schema so Node constructor doesn't throw
+    execute: async (state) => {
+      try {
+        const result = await boundExecute(state);
+        return typeof result === 'object' && 'success' in result
+          ? result
+          : { success: true, output: result, raw: null };
+      } catch (err) {
+        return { success: false, error: err.message, raw: null };
+      }
+    }
+  };
+}
+
+class CompilationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CompilationError';
+  }
+}
+
+export { CompilationError };