@zibby/core 0.1.0

package/src/framework/graph.js

@@ -0,0 +1,610 @@
+/**
+ * Graph execution engine
+ * Similar to LangGraph's StateGraph
+ */
+
+import { WorkflowState } from './state.js';
+import { Node, ConditionalNode } from './node.js';
+import { ContextLoader } from './context-loader.js';
+import { mkdirSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { config as loadDotenv } from 'dotenv';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import Handlebars from 'handlebars';
+import { invokeAgent as coreInvokeAgent } from './agents/index.js';
+import { DEFAULT_OUTPUT_BASE, SESSIONS_DIR, SESSION_INFO_FILE, CI_ENV_VARS } from './constants.js';
+import { timeline } from '../utils/timeline.js';
+
+export class WorkflowGraph {
+  constructor(options = {}) {
+    this.nodes = new Map();
+    this.edges = new Map();
+    this.entryPoint = null;
+    this.middleware = Array.isArray(options.middleware) ? [...options.middleware] : [];
+    if (options.nodeMiddleware) this.middleware.push(options.nodeMiddleware);
+    this.nodeTypeMap = new Map();
+    this.conditionalCodeMap = new Map();
+    this.stateSchema = options.stateSchema || null;
+    this.nodePrompts = new Map();
+    this.nodeOptions = new Map();
+  }
+
+  /**
+   * Set the state schema for this graph
+   * @param {Object} schema - Schema definition
+   */
+  setStateSchema(schema) {
+    this.stateSchema = schema;
+    return this;
+  }
+
+  /**
+   * Get the state schema
+   */
+  getStateSchema() {
+    return this.stateSchema;
+  }
+
+  addNode(name, nodeOrConfig, options = {}) {
+    const node = nodeOrConfig instanceof Node ? nodeOrConfig : new Node(nodeOrConfig);
+    node.name = name;  // Ensure name is set
+    this.nodes.set(name, node);
+    
+    // Store prompt if provided
+    if (options.prompt) {
+      this.nodePrompts.set(name, options.prompt);
+    }
+    
+    // Store other options
+    if (Object.keys(options).length > 0) {
+      this.nodeOptions.set(name, options);
+    }
+    
+    return this;
+  }
+
+  addConditionalNode(name, config) {
+    const node = new ConditionalNode({ ...config, name });
+    this.nodes.set(name, node);
+    return this;
+  }
+
+  addEdge(from, to) {
+    this.edges.set(from, to);
+    return this;
+  }
+
+  setNodeType(name, nodeType) {
+    this.nodeTypeMap.set(name, nodeType);
+    return this;
+  }
+
+  addConditionalEdges(from, routes, { labels } = {}) {
+    this.edges.set(from, { conditional: true, routes, labels });
+    if (typeof routes === 'function') {
+      this.conditionalCodeMap.set(from, routes.toString());
+    }
+    return this;
+  }
+
+  setEntryPoint(nodeName) {
+    this.entryPoint = nodeName;
+    return this;
+  }
+
+  use(middlewareFn) {
+    if (typeof middlewareFn === 'function') {
+      this.middleware.push(middlewareFn);
+    }
+    return this;
+  }
+
+  _composeMiddleware(nodeName, coreFn, stateValues, state) {
+    let fn = coreFn;
+    for (let i = this.middleware.length - 1; i >= 0; i--) {
+      const mw = this.middleware[i];
+      const next = fn;
+      fn = () => mw(nodeName, next, stateValues, state);
+    }
+    return fn();
+  }
+
+  serialize() {
+    const nodes = [];
+    const nodeConfigs = {};
+
+    for (const [nodeId, node] of this.nodes) {
+      const nodeType = this.nodeTypeMap.get(nodeId) || nodeId;
+      nodes.push({ id: nodeId, type: nodeType, data: { nodeType, label: nodeId } });
+
+      const isCustom = node._isCustomCode || false;
+      const config = {};
+
+      if (isCustom && typeof node.execute === 'function') {
+        config.customCode = node.execute.toString();
+      }
+
+      // Include prompt in config
+      const prompt = this.nodePrompts.get(nodeId);
+      if (prompt) {
+        config.prompt = prompt;
+      }
+      
+      // Include execute code for all nodes (for UI display)
+      // Use customExecute (the node's actual implementation) not the base class execute
+      if (typeof node.customExecute === 'function') {
+        config.executeCode = node.customExecute.toString();
+      }
+      
+      // Include output schema for UI (Zod → JSON Schema)
+      if (node.outputSchema) {
+        try {
+          // Check if it's a Zod schema
+          const isZodSchema = typeof node.outputSchema._def !== 'undefined';
+          
+          if (isZodSchema) {
+            // Convert Zod to JSON Schema for frontend
+            const jsonSchema = zodToJsonSchema(node.outputSchema, { target: 'openApi3' });
+            
+            // Also generate flattened variable paths for Variable Inspector
+            const variables = this._flattenJsonSchemaToVariables(jsonSchema);
+            
+            config.outputSchema = {
+              jsonSchema,
+              variables
+            };
+          } else {
+            // Legacy non-Zod schema (will be deprecated)
+            config.outputSchema = { schema: node.outputSchema };
+          }
+        } catch (error) {
+          console.warn(`Failed to convert schema for ${nodeId}:`, error.message);
+        }
+      }
+
+      const toolDefs = (this.resolvedToolsMap || {})[nodeId];
+      if (toolDefs?.toolIds) {
+        config.tools = toolDefs.toolIds;
+      }
+
+      if (Object.keys(config).length > 0) {
+        nodeConfigs[nodeId] = config;
+      }
+    }
+
+    const edges = [];
+    for (const [from, target] of this.edges) {
+      if (typeof target === 'string') {
+        edges.push({ source: from, target });
+      } else if (target.conditional) {
+        const codeStr = this.conditionalCodeMap.get(from) || target.routes.toString();
+        const possibleTargets = this._inferConditionalTargets(target.routes);
+        const labels = target.labels || {};
+        for (const t of possibleTargets) {
+          const edge = {
+            source: from,
+            target: t,
+            data: { conditionalCode: codeStr }
+          };
+          if (labels[t]) {
+            edge.label = labels[t];
+          }
+          edges.push(edge);
+        }
+      }
+    }
+
+    // Convert Zod schema to JSON Schema for serialization
+    let jsonSchema = null;
+    if (this.stateSchema) {
+      try {
+        jsonSchema = zodToJsonSchema(this.stateSchema, { target: 'openApi3' });
+      } catch {
+        jsonSchema = this.stateSchema;
+      }
+    }
+    
+    return { 
+      nodes, 
+      edges, 
+      nodeConfigs,
+      stateSchema: jsonSchema
+    };
+  }
+
+  _inferConditionalTargets(routeFn) {
+    const fnStr = routeFn.toString();
+    const targets = new Set();
+    const returnPattern = /return\s+['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = returnPattern.exec(fnStr)) !== null) {
+      targets.add(match[1]);
+    }
+    return [...targets];
+  }
+
+  /**
+   * Flatten JSON Schema to variable paths for Variable Inspector
+   * @param {Object} jsonSchema - JSON Schema object (may have $ref/definitions from zodToJsonSchema)
+   * @param {string} prefix - Path prefix for nested properties
+   * @returns {Array} Array of { path, type, label, optional } objects
+   */
+  _flattenJsonSchemaToVariables(jsonSchema, prefix = '') {
+    // Handle zodToJsonSchema format with $ref and definitions
+    // Example: { $ref: "#/definitions/node_name", definitions: { node_name: { type: 'object', properties: {...} } } }
+    let rootSchema = jsonSchema;
+    
+    if (jsonSchema.$ref && jsonSchema.definitions) {
+      // Extract the referenced definition
+      const refName = jsonSchema.$ref.replace('#/definitions/', '');
+      rootSchema = jsonSchema.definitions[refName] || jsonSchema;
+    }
+    
+    return this._flattenSchema(rootSchema, prefix);
+  }
+  
+  /**
+   * Internal recursive schema flattener
+   */
+  _flattenSchema(schema, prefix = '') {
+    if (!schema || typeof schema !== 'object') {
+      return [];
+    }
+    
+    const variables = [];
+    const properties = schema.properties || {};
+    const required = schema.required || [];
+
+    for (const [key, propSchema] of Object.entries(properties)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      const isOptional = !required.includes(key);
+      
+      // Add this property
+      variables.push({
+        path,
+        type: propSchema.type || 'unknown',
+        label: propSchema.description || this._formatLabel(key),
+        optional: isOptional
+      });
+
+      // Recurse into nested objects
+      if (propSchema.type === 'object' && propSchema.properties) {
+        const nested = this._flattenSchema(propSchema, path);
+        variables.push(...nested);
+      }
+
+      // Recurse into arrays with object items
+      if (propSchema.type === 'array' && propSchema.items?.type === 'object' && propSchema.items.properties) {
+        const nested = this._flattenSchema(propSchema.items, `${path}[]`);
+        variables.push(...nested);
+      }
+    }
+
+    return variables;
+  }
+
+  /**
+   * Format camelCase to Title Case
+   */
+  _formatLabel(str) {
+    return str
+      .replace(/([A-Z])/g, ' $1')
+      .replace(/^./, s => s.toUpperCase())
+      .trim();
+  }
+
+  /**
+   * Generate session ID with CI environment awareness
+   * Priority: CI_JOB_ID > GITHUB_RUN_ID > CIRCLE_WORKFLOW_ID > BUILD_ID > Date.now()
+   */
+  _getSessionId(config = {}) {
+    // Detect CI environment by checking all known CI env vars
+    const ciSessionId = CI_ENV_VARS
+      .map(envVar => process.env[envVar])
+      .find(val => val);
+    
+    const baseId = ciSessionId || Date.now().toString();
+    
+    // Apply prefix if configured
+    const prefix = config.paths?.sessionPrefix;
+    return prefix ? `${prefix}_${baseId}` : baseId;
+  }
+
+  _summarizeNodeOutput(nodeName, output) {
+    if (!output || typeof output !== 'object') return [];
+    const details = [];
+
+    if (output.success !== undefined) {
+      details.push(`Result: ${output.success ? 'passed' : 'failed'}`);
+    }
+
+    for (const [key, value] of Object.entries(output)) {
+      if (key === 'success' || key === 'raw' || key === 'nextNode') continue;
+      if (typeof value === 'string' && value.length <= 80) {
+        details.push(`${key}: ${value}`);
+      } else if (Array.isArray(value)) {
+        const total = value.length;
+        const passed = value.filter(v => v?.passed === true).length;
+        const hasPassed = value.some(v => v?.passed !== undefined);
+        if (hasPassed) {
+          const failed = total - passed;
+          details.push(`${key}: ${passed}/${total} passed${failed ? `, ${failed} failed` : ''}`);
+        } else {
+          details.push(`${key}: ${total} items`);
+        }
+      }
+      if (details.length >= 4) break;
+    }
+    return details;
+  }
+
+  async run(agent, initialState = {}) {
+    if (!this.entryPoint) {
+      throw new Error('No entry point set for graph');
+    }
+
+    const cwd = initialState.cwd || process.cwd();
+
+    loadDotenv({ path: join(cwd, '.env') });
+
+    // Auto-resolve config if not provided
+    let config = initialState.config || {};
+    if (!config || Object.keys(config).length === 0) {
+      try {
+        const configPath = join(cwd, '.zibby.config.js');
+        if (existsSync(configPath)) {
+          const configModule = await import(configPath);
+          config = configModule.default || {};
+        }
+      } catch { /* no config file */ }
+    }
+
+    // ECS/CI: enable strictMode by default for reliable structured output
+    if (process.env.EXECUTION_ID && !config.agent?.strictMode) {
+      config.agent = { ...config.agent, strictMode: true };
+    }
+
+    // Auto-infer agent type: initialState > config > AGENT_TYPE env > default
+    let agentType = initialState.agentType;
+    if (!agentType) {
+      const ac = config?.agent;
+      if (ac?.provider) agentType = ac.provider;
+      else if (ac?.claude) agentType = 'claude';
+      else if (ac?.cursor) agentType = 'cursor';
+      else agentType = process.env.AGENT_TYPE || 'cursor';
+    }
+
+    // Auto-resolve context config from agent constructor config
+    const contextConfig = initialState.contextConfig || agent?.config?.contextConfig || agent?.config?.context || config?.context || {};
+
+    // Validate initial state against Zod schema if defined
+    if (this.stateSchema) {
+      const result = this.stateSchema.safeParse(initialState);
+      if (!result.success) {
+        const errors = result.error.issues.map(i => `${i.path.join('.')}: ${i.message}`);
+        console.error('❌ Initial state validation failed:');
+        errors.forEach(e => console.error(`   - ${e}`));
+        throw new Error(`State validation failed: ${errors.join(', ')}`);
+      }
+      timeline.step('State validated against schema');
+    }
+
+    let sessionPath = initialState.sessionPath;
+    let sessionTimestamp = initialState.sessionTimestamp;
+    let sessionId;
+    
+    if (!sessionPath) {
+      sessionId = this._getSessionId(config);
+      sessionTimestamp = sessionTimestamp || Date.now();
+      
+      const outputBase = config.paths?.output || DEFAULT_OUTPUT_BASE;
+      sessionPath = join(cwd, outputBase, SESSIONS_DIR, sessionId);
+      
+      if (!existsSync(sessionPath)) {
+        mkdirSync(sessionPath, { recursive: true });
+      }
+      
+      timeline.step(`Session ${sessionId}`);
+    } else {
+      sessionId = sessionPath.split('/').pop();
+      timeline.step(`Session ${sessionId}`);
+    }
+
+    const context = await ContextLoader.loadContext(
+      initialState.specPath || '',
+      cwd,
+      contextConfig
+    );
+    
+    if (Object.keys(context).length > 0) {
+      timeline.step(`Context loaded: ${Object.keys(context).join(', ')}`);
+    }
+
+    let outputPath = initialState.outputPath;
+    if (!outputPath && initialState.specPath) {
+      if (agent?.calculateOutputPath) {
+        outputPath = agent.calculateOutputPath(initialState.specPath);
+      } else {
+        console.warn(`⚠️  outputPath not resolved (specPath=${initialState.specPath})`);
+      }
+    }
+
+    const state = new WorkflowState({ 
+      ...initialState, 
+      config,
+      agentType,
+      outputPath,
+      sessionPath, 
+      sessionTimestamp,
+      context,
+      resolvedTools: this.resolvedToolsMap || {}
+    });
+    let currentNode = this.entryPoint;
+    const executionLog = [];
+
+    while (currentNode && currentNode !== 'END') {
+      const node = this.nodes.get(currentNode);
+      if (!node) {
+        throw new Error(`Node '${currentNode}' not found in graph`);
+      }
+
+      // Update session info with current node for MCP recorder
+      const outputBase = (state.get('config')?.paths?.output || DEFAULT_OUTPUT_BASE);
+      const sessionInfoPath = join(cwd, outputBase, SESSION_INFO_FILE);
+      mkdirSync(join(cwd, outputBase), { recursive: true });
+      writeFileSync(sessionInfoPath, JSON.stringify({
+        sessionPath,
+        sessionTimestamp,
+        currentNode,
+        createdAt: new Date().toISOString(),
+        config: state.get('config') // Pass full config to MCP recorder (for playwrightArtifacts, etc)
+      }), 'utf-8');
+
+      const nodeTools = (this.resolvedToolsMap || {})[currentNode] || null;
+      state.set('_currentNodeTools', nodeTools);
+
+      const allNodeConfigs = state.get('nodeConfigs') || {};
+      state.set('_currentNodeConfig', allNodeConfigs[currentNode] || {});
+
+      timeline.nodeStart(currentNode);
+      const startTime = Date.now();
+      
+      // Get prompt template for this node
+      const promptTemplate = this.nodePrompts.get(currentNode);
+      
+      // Create invokeAgent wrapper with template rendering
+      const invokeAgent = async (promptValues = {}, options = {}) => {
+        let finalPrompt = options.prompt || '';
+        
+        // If node has a template, render it with provided values
+        if (promptTemplate) {
+          try {
+            const template = Handlebars.compile(promptTemplate, { noEscape: true });
+            finalPrompt = template(promptValues);
+          } catch (err) {
+            console.error(`❌ Template rendering failed for node '${currentNode}':`, err.message);
+            throw new Error(`Template rendering failed: ${err.message}`, { cause: err });
+          }
+        } else if (!finalPrompt) {
+          throw new Error(`No prompt template configured for node '${currentNode}' and no prompt provided in options`);
+        }
+        
+        const agentContext = {
+          state: state.getAll(),
+          images: options.images || [],
+        };
+        
+        const agentOptions = {
+          model: options.model || state.get('model'),
+          workspace: state.get('workspace'),
+          schema: options.schema,
+          ...options
+        };
+        
+        return coreInvokeAgent(finalPrompt, agentContext, agentOptions);
+      };
+      
+      // Create context object for node execution
+      // New unified signature: execute(context) where context has { state, invokeAgent, agent, ... }
+      // plus backward-compatible spread of state values
+      const nodeContext = {
+        // New unified API
+        state,
+        invokeAgent,
+        agent,  // Add agent for base Node class LLM execution path
+        nodeId: currentNode,
+        promptTemplate,
+        getPromptTemplate: () => promptTemplate,
+        // Spread state values so nodes can destructure: const { workspace, ...rest } = context;
+        ...state.getAll()
+      };
+
+      try {
+        // Execute node with context
+        // Node.execute() still expects (agent, state) signature for internal processing
+        // For nodes with customExecute, it will call customExecute(state.getAll())
+        // We pass nodeContext as "agent" for nodes that define their own execute method
+        let result;
+        if (this.middleware.length > 0) {
+          result = await this._composeMiddleware(currentNode, async () => {
+            return node.execute(nodeContext, state);
+          }, state.getAll(), state);
+        } else {
+          result = await node.execute(nodeContext, state);
+        }
+        
+        const duration = Date.now() - startTime;
+
+        executionLog.push({
+          node: currentNode,
+          success: result.success,
+          duration,
+          timestamp: new Date().toISOString()
+        });
+
+        if (!result.success) {
+          state.append('errors', { node: currentNode, error: result.error });
+          
+          const maxRetries = node.config?.retries || 0;
+          const retryKey = `${currentNode}_retries`;
+          const currentRetries = state.getAll()[retryKey] || 0;
+          
+          if (currentRetries < maxRetries) {
+            timeline.stepInfo(`Retrying (attempt ${currentRetries + 1}/${maxRetries})`);
+            state.update({
+              [retryKey]: currentRetries + 1,
+              [`${currentNode}_raw`]: result.raw
+            });
+            continue;
+          }
+          
+          timeline.nodeFailed(currentNode, result.error, { duration });
+          throw new Error(`Node '${currentNode}' failed after ${currentRetries} attempts: ${result.error}`);
+        }
+
+        state.update({
+          [currentNode]: result.output
+        });
+
+        const details = this._summarizeNodeOutput(currentNode, result.output);
+        timeline.nodeComplete(currentNode, { duration, details });
+
+        const edge = this.edges.get(currentNode);
+        if (!edge) {
+          currentNode = 'END';
+        } else if (edge.conditional) {
+          const currentState = state.getAll();
+          const nextNode = edge.routes(currentState);
+          
+          timeline.route(currentNode, nextNode);
+          currentNode = nextNode;
+        } else {
+          // Direct edge
+          currentNode = edge;
+        }
+      } catch (error) {
+        if (timeline.isInsideNode) {
+          timeline.nodeFailed(currentNode, error.message, { duration: Date.now() - startTime });
+        }
+        
+        state.set('failed', true);
+        state.set('failedAt', currentNode);
+        throw error;
+      }
+    }
+
+    timeline.graphComplete();
+    const result = {
+      success: true,
+      state: state.getAll(),
+      executionLog
+    };
+
+    if (agent && typeof agent.onComplete === 'function') {
+      await agent.onComplete(result);
+    }
+
+    return result;
+  }
+}
+

package/src/framework/index.js

@@ -0,0 +1,28 @@
+/**
+ * Zibby Workflow Framework
+ * A graph-based orchestration system for AI agents
+ * Inspired by LangGraph, but agent-agnostic
+ */
+
+export { WorkflowGraph } from './graph.js';
+export { Node, ConditionalNode } from './node.js';
+export { WorkflowState } from './state.js';
+export { OutputParser, SchemaTypes } from './output-parser.js';
+
+// Graph compiler (serialized config -> executable WorkflowGraph)
+export { compileGraph, validateGraphConfig, extractSteps, CompilationError } from './graph-compiler.js';
+
+export { registerNode, getNodeImpl, hasNode, listNodeTypes, getNodeTemplate } from './node-registry.js';
+export { resolveNodeTools, getResolvedToolDefinitions, NODE_DEFAULT_TOOLS } from './tool-resolver.js';
+export { registerSkill, getSkill, hasSkill, getAllSkills, listSkillIds } from './skill-registry.js';
+export { generateWorkflowCode, generateNodeConfigsJson } from './code-generator.js';
+export { hasAgentCall } from '../utils/ast-utils.js';
+
+// Agent strategies (core framework capability)
+export { 
+  invokeAgent, 
+  getAgentStrategy,
+  CursorAgentStrategy,
+  ClaudeAgentStrategy,
+  AgentStrategy
+} from './agents/index.js';