@zibby/core 0.1.0

package/src/framework/node-registry.js

@@ -0,0 +1,163 @@
+
+const registry = new Map();
+
+export function registerNode(type, impl) {
+  registry.set(type, impl);
+}
+
+export function getNodeImpl(type) {
+  return registry.get(type);
+}
+
+export function hasNode(type) {
+  return registry.has(type);
+}
+
+export function listNodeTypes() {
+  return Array.from(registry.keys());
+}
+
+export function getNodeTemplate(type) {
+  const impl = registry.get(type);
+  if (!impl) return null;
+
+  if (impl.factory && typeof impl.create === 'function') {
+    return impl.create.toString();
+  }
+
+  if (typeof impl.execute === 'function') {
+    return impl.execute.toString();
+  }
+
+  if (typeof impl === 'function') {
+    return impl.toString();
+  }
+
+  return null;
+}
+
+// ------------------------------------------------------------------
+// Dynamic / factory nodes (framework-provided)
+// ------------------------------------------------------------------
+registerNode('ai_agent', {
+  name: 'ai_agent',
+  factory: true,
+  create: (nodeId, nodeConfig = {}) => ({
+    name: nodeId,
+    execute: async (state) => {
+      const { invokeAgent } = await import('./agents/index.js');
+
+      const prompt = nodeConfig.extraPromptInstructions || 'Execute the task based on the current state.';
+      const fullPrompt = buildAIAgentPrompt(prompt, state);
+
+      const result = await invokeAgent(fullPrompt, {
+        cwd: state.workspace || process.cwd(),
+        model: state.model,
+        tools: nodeConfig.resolvedTools || null
+      });
+
+      return {
+        success: true,
+        output: { raw: result, nodeId },
+        raw: typeof result === 'string' ? result : result.raw
+      };
+    }
+  })
+});
+
+/**
+ * Parse @variable references from prompt text
+ * @param {string} prompt - The prompt containing @references
+ * @returns {string[]} Array of unique variable paths (e.g., ["context.summary", "previous_node_output"])
+ */
+function parseVariableReferences(prompt) {
+  const refRegex = /@([\w.]+)/g;
+  const refs = new Set();
+  let match;
+  while ((match = refRegex.exec(prompt)) !== null) {
+    refs.add(match[1]);
+  }
+  return Array.from(refs);
+}
+
+/**
+ * Get a value from state using dot notation path
+ * @param {Object} state - The state object
+ * @param {string} path - Dot-notation path (e.g., "context.summary")
+ * @returns {*} The value at the path, or undefined if not found
+ */
+function getStateValue(state, path) {
+  const parts = path.split('.');
+  let value = state;
+  for (const part of parts) {
+    if (value == null) return undefined;
+    value = value[part];
+  }
+  return value;
+}
+
+/**
+ * Format a value for inclusion in the prompt
+ * @param {*} value - The value to format
+ * @returns {string} Formatted string representation
+ */
+function formatValueForPrompt(value) {
+  if (value === undefined || value === null) {
+    return '[not available]';
+  }
+  
+  if (typeof value === 'string') {
+    return value;
+  }
+  
+  if (typeof value === 'object') {
+    if (value.raw && typeof value.raw === 'string') {
+      return value.raw;
+    }
+    return JSON.stringify(value, null, 2);
+  }
+  
+  return String(value);
+}
+
+/**
+ * Build AI agent prompt with explicit variable references
+ * Only includes context that is explicitly referenced with @variable syntax
+ * @param {string} basePrompt - The user's prompt with @references
+ * @param {Object} state - The workflow state
+ * @returns {string} The full prompt with referenced context appended
+ */
+function buildAIAgentPrompt(basePrompt, state) {
+  const refs = parseVariableReferences(basePrompt);
+  
+  if (refs.length === 0) {
+    return basePrompt;
+  }
+  
+  const contextParts = [];
+  const processedRefs = new Set();
+  
+  for (const ref of refs) {
+    const rootPath = ref.split('.')[0];
+    if (processedRefs.has(rootPath)) continue;
+    
+    const value = getStateValue(state, ref);
+    if (value !== undefined) {
+      const formatted = formatValueForPrompt(value);
+      
+      const label = ref.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+      
+      contextParts.push(`## ${label}\n${formatted}`);
+      
+      if (!ref.includes('.')) {
+        processedRefs.add(rootPath);
+      }
+    }
+  }
+  
+  if (contextParts.length === 0) {
+    return basePrompt;
+  }
+  
+  return `${basePrompt}\n\n---\n# Referenced Context\n\n${contextParts.join('\n\n')}`;
+}

package/src/framework/node.js

@@ -0,0 +1,259 @@
+/**
+ * Base Node class for workflow graph
+ * Each node = one agent execution with a specific prompt
+ */
+
+import { OutputParser } from './output-parser.js';
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import chalk from 'chalk';
+import { DEFAULT_MODELS } from '../constants.js';
+import { invokeAgent } from './agents/index.js';
+import { logger } from '../utils/logger.js';
+import { timeline } from '../utils/timeline.js';
+import { SESSION_INFO_FILE } from './constants.js';
+
+export class Node {
+  constructor(config) {
+    this.config = config;  // Store full config for timeout access
+    this.name = config.name;
+    this.prompt = config.prompt;
+    this.outputSchema = config.outputSchema;
+    
+    // Enforce outputSchema requirement (allow both Zod schemas and JSON Schema from runtime compilation)
+    if (!this.outputSchema) {
+      // Only enforce for non-custom code (registry nodes must have schema)
+      if (!config._isCustomCode) {
+        throw new Error(`Node '${this.name}' must define outputSchema (Zod schema). This defines the contract for what the node returns to state.`);
+      }
+      // Custom code from graph-compiler gets a pass (already validated in UI)
+    }
+    
+    this.isZodSchema = this.outputSchema && typeof this.outputSchema._def !== 'undefined';
+    this.parser = config.outputSchema && !this.isZodSchema ? new OutputParser(config.outputSchema) : null;
+    this.retries = config.retries || 0;
+    this.onComplete = config.onComplete;
+    this.customExecute = config.execute;
+  }
+
+  async execute(context, state) {
+    const _agent = context?.agent || context;
+    
+    // Helpers to get state values - works with both old and new call patterns
+    // context may be: 1) nodeContext object from unified graph.run, or 2) agent from old calls
+    // state may be: 1) WorkflowState instance, or 2) undefined (for inline test nodes)
+    const getAllState = () => {
+      if (state && typeof state.getAll === 'function') {
+        return state.getAll();
+      }
+      return context;
+    };
+    
+    const _getState = (key) => {
+      if (state && typeof state.get === 'function') {
+        return state.get(key);
+      }
+      return context?.[key];
+    };
+    
+    if (typeof this.customExecute === 'function') {
+      logger.info(`⚡ Using custom execute method (skipping LLM)`);
+      try {
+        const result = await this.customExecute(context);
+        
+        // Propagate inner failure (e.g. from wrapCustomCode's catch)
+        if (typeof result === 'object' && result !== null && result.success === false) {
+          return { success: false, error: result.error || 'Node execution failed', raw: result.raw || null };
+        }
+        
+        if (this.isZodSchema) {
+          logger.debug(`Validating return value against outputSchema...`);
+          const validated = this.outputSchema.parse(result);
+          return { success: true, output: validated, raw: null };
+        }
+        
+        return { success: true, output: result, raw: null };
+      } catch (error) {
+        logger.error(`❌ Node '${this.name}' execution failed: ${error.message}`);
+        if (error.name === 'ZodError') {
+          logger.error(`Schema validation errors: ${JSON.stringify(error.errors, null, 2)}`);
+        }
+        return { success: false, error: error.message, raw: null };
+      }
+    }
+    
+    let prompt = typeof this.prompt === 'function' 
+      ? this.prompt(getAllState()) 
+      : this.prompt;
+
+    const skillHints = _getState('_skillHints');
+    if (skillHints) {
+      prompt = `${skillHints}\n\n${prompt}`;
+    }
+
+    const allState = getAllState();
+    const cwd = allState.cwd || process.cwd();
+    const sessionPath = allState.sessionPath;
+
+    try {
+      if (sessionPath) {
+        const sessionInfoPath = join(sessionPath, '..', SESSION_INFO_FILE);
+        if (existsSync(sessionInfoPath)) {
+          const sessionInfo = JSON.parse(readFileSync(sessionInfoPath, 'utf-8'));
+          sessionInfo.currentNode = this.name;
+          writeFileSync(sessionInfoPath, JSON.stringify(sessionInfo, null, 2), 'utf-8');
+        }
+      }
+    } catch (err) {
+      logger.debug(`Could not update session info: ${err.message}`);
+    }
+
+    console.log(`\n${chalk.bold('Prompt sent to LLM:')}`);
+    console.log(chalk.dim('─'.repeat(60)));
+    console.log(chalk.dim(prompt));
+    console.log(chalk.dim('─'.repeat(60)));
+
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        logger.debug(`Node.execute attempt ${attempt} for '${this.name}'`);
+        
+        const _timeout = this.config?.timeout || 300000;
+        
+        // Model resolution priority:
+        // 1. Node-specific override: config.models[nodeName]
+        // 2. Global default: config.models.default
+        // 3. Agent-specific: config.agent.claude.model or config.agent.cursor.model
+        // 4. Fallback: DEFAULT_MODELS.CLAUDE or 'auto'
+        const currentAllState = getAllState();
+        const zibbyConfig = currentAllState.config || {};
+        const modelsConfig = zibbyConfig.models || {};
+        
+        // Infer provider from agent config (claude/cursor key presence)
+        const inferProvider = (agentConfig) => {
+          if (agentConfig?.provider) return agentConfig.provider;
+          if (agentConfig?.claude) return 'claude';
+          if (agentConfig?.cursor) return 'cursor';
+          return 'unknown';
+        };
+        
+        const agentType = inferProvider(zibbyConfig?.agent) || currentAllState.agentType || 'unknown';
+        const agentModel = agentType && zibbyConfig.agent?.[agentType]?.model;
+        
+        let model = modelsConfig[this.name] || modelsConfig.default || null;
+        
+        if (!model || model === 'auto') {
+          model = agentModel || null;
+        }
+        
+        if (!model) {
+          model = agentType === 'claude' ? DEFAULT_MODELS.CLAUDE : 'auto';
+        }
+        
+        const agentDisplay = agentType === 'claude' ? 'Claude (Anthropic API)' : agentType === 'cursor' ? 'Cursor (CLI)' : agentType;
+        
+        {
+          const displayModel = (model && model !== 'auto') ? model : (agentType === 'claude' ? DEFAULT_MODELS.CLAUDE : 'agent default');
+          const skills = this.config.skills || [];
+          const skillsSuffix = skills.length > 0 ? ` → skills: [${skills.join(', ')}]` : '';
+          timeline.step(`${agentDisplay} (${displayModel})${skillsSuffix}`);
+        }
+        
+        const agentContext = {
+          state: getAllState()
+        };
+        
+        const agentOptions = {
+          model,
+          workspace: cwd,
+          schema: this.isZodSchema ? this.outputSchema : null,
+          skills: this.config.skills || null,
+          sessionPath,
+          config: zibbyConfig
+        };
+        
+        const result = await invokeAgent(prompt, agentContext, agentOptions);
+        
+        let rawOutput, extractedJson;
+        
+        if (typeof result === 'string') {
+          rawOutput = result;
+          extractedJson = null;
+        } else if (result.structured) {
+          rawOutput = result.raw || JSON.stringify(result.structured, null, 2);
+          extractedJson = result.structured;
+        } else {
+          rawOutput = result.raw || JSON.stringify(result, null, 2);
+          extractedJson = result.extracted || null;
+        }
+        
+        if (sessionPath) {
+          try {
+            const debugPath = join(sessionPath, this.name, 'raw_stream_output.txt');
+            mkdirSync(dirname(debugPath), { recursive: true });
+            writeFileSync(debugPath, typeof rawOutput === 'string' ? rawOutput : JSON.stringify(rawOutput), 'utf-8');
+          } catch (err) {
+            logger.debug(`Could not save raw output: ${err.message}`);
+          }
+        }
+        
+        if (this.isZodSchema && extractedJson) {
+          console.log(`\n🔍 ${chalk.cyan('Validated output:')} ${chalk.white(JSON.stringify(extractedJson, null, 2))}`);
+          
+          let finalOutput = extractedJson;
+          if (typeof this.onComplete === 'function') {
+            try {
+              finalOutput = await this.onComplete(getAllState(), extractedJson);
+            } catch (err) {
+              logger.warn(`onComplete hook failed: ${err.message}`);
+            }
+          }
+          
+          return { success: true, output: finalOutput, raw: rawOutput };
+        }
+        
+        if (typeof this.onComplete === 'function') {
+          try {
+            const onCompleteResult = await this.onComplete(getAllState(), { raw: rawOutput });
+            return { success: true, output: onCompleteResult, raw: rawOutput };
+          } catch (err) {
+            throw new Error(`onComplete failed: ${err.message}`, { cause: err });
+          }
+        }
+        
+        if (this.parser) {
+          const parsed = this.parser.parse(rawOutput);
+          console.log(`\n🔍 ${chalk.cyan('Parsed output:')} ${chalk.white(JSON.stringify(parsed, null, 2))}`);
+          timeline.step('Output parsed');
+          return { success: true, output: parsed, raw: rawOutput };
+        }
+        
+        return { success: true, output: rawOutput, raw: rawOutput };
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.retries) {
+          logger.info(`Node '${this.name}' failed, retrying (${attempt + 1}/${this.retries})...`);
+        }
+      }
+    }
+
+    return { success: false, error: lastError.message, raw: null };
+  }
+
+}
+
+export class ConditionalNode extends Node {
+  constructor(config) {
+    super({ ...config, _isCustomCode: true });
+    this.condition = config.condition;
+  }
+
+  async execute(context, state) {
+    const stateValues = (state && typeof state.getAll === 'function') 
+      ? state.getAll() 
+      : context;
+    const nextNode = this.condition(stateValues);
+    return { success: true, output: { nextNode }, raw: null };
+  }
+}
+

package/src/framework/output-parser.js

@@ -0,0 +1,71 @@
+/**
+ * Structured output parsing with validation
+ * Similar to LangChain's StructuredOutputParser
+ */
+
+export class OutputParser {
+  constructor(schema) {
+    this.schema = schema;
+  }
+
+  parse(text) {
+    // Try to extract JSON from markdown code blocks
+    const jsonMatch = text.match(/```json\s*([\s\S]*?)\s*```/);
+    if (jsonMatch) {
+      return this.validate(JSON.parse(jsonMatch[1]));
+    }
+
+    // Try to find JSON object in text
+    const objectMatch = text.match(/\{[\s\S]*\}/);
+    if (objectMatch) {
+      return this.validate(JSON.parse(objectMatch[0]));
+    }
+
+    // Fallback: return raw text if no JSON found
+    return this.validate({ result: text.trim() });
+  }
+
+  validate(data) {
+    const errors = [];
+    
+    for (const [key, validator] of Object.entries(this.schema)) {
+      if (validator.required && !(key in data)) {
+        errors.push(`Missing required field: ${key}`);
+      }
+
+      if (key in data && validator.type) {
+        const actualType = typeof data[key];
+        if (actualType !== validator.type) {
+          errors.push(`Field '${key}' expected ${validator.type}, got ${actualType}`);
+        }
+      }
+
+      if (validator.validate && key in data) {
+        const validationError = validator.validate(data[key]);
+        if (validationError) {
+          errors.push(`Field '${key}': ${validationError}`);
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new Error(`Output validation failed:\n${errors.join('\n')}`);
+    }
+
+    return data;
+  }
+}
+
+// Helper to create common schemas
+export const SchemaTypes = {
+  string: (required = true) => ({ type: 'string', required }),
+  number: (required = true) => ({ type: 'number', required }),
+  boolean: (required = true) => ({ type: 'boolean', required }),
+  array: (required = true) => ({ type: 'object', required, validate: (v) => Array.isArray(v) ? null : 'must be an array' }),
+  enum: (values, required = true) => ({
+    type: 'string',
+    required,
+    validate: (v) => values.includes(v) ? null : `must be one of: ${values.join(', ')}`
+  }),
+};
+

package/src/framework/skill-registry.js

@@ -0,0 +1,55 @@
+/**
+ * Skill Registry
+ *
+ * Central registry for skill definitions. A skill describes an MCP server
+ * and the tool schemas it exposes. The framework resolves skills generically
+ * at runtime -- no skill is referenced by name in agent strategies.
+ *
+ * Built-in skills are registered by importing @zibby/skills (side-effect).
+ * Community / user skills call registerSkill() directly.
+ *
+ * See @zibby/skills/README.md for the full skill authoring guide.
+ */
+
+const _registry = new Map();
+
+/**
+ * Register a skill definition.
+ * @param {Object} skill
+ * @param {string} skill.id                 - Unique identifier (used in node `skills` arrays)
+ * @param {'mcp'|'function'} [skill.type]   - Skill type: 'mcp' (default) or 'function' (auto-bridged)
+ * @param {string} skill.serverName         - MCP server name (key in mcpServers config)
+ * @param {string[]} skill.allowedTools     - Tool patterns for Claude SDK (e.g. ['mcp__playwright__*'])
+ * @param {Function} [skill.resolve]        - (options?) => { command, args, env? } | null
+ * @param {string[]} [skill.envKeys]        - Required environment variable names
+ * @param {string} [skill.description]      - Human-readable description
+ * @param {Object[]} [skill.tools]          - Tool schemas for compile-time validation
+ * @param {string} [skill.cursorKey]        - Override key for ~/.cursor/mcp.json
+ * @param {string} [skill.sessionEnvKey]    - Env var injected with session info path (Cursor only)
+ */
+export function registerSkill(skill) {
+  if (!skill || typeof skill.id !== 'string') {
+    throw new Error('Skill definition must include a string id');
+  }
+  _registry.set(skill.id, Object.freeze({ ...skill }));
+}
+
+/** @returns {object|null} */
+export function getSkill(id) {
+  return _registry.get(id) || null;
+}
+
+/** @returns {boolean} */
+export function hasSkill(id) {
+  return _registry.has(id);
+}
+
+/** @returns {Map<string, object>} shallow copy */
+export function getAllSkills() {
+  return new Map(_registry);
+}
+
+/** @returns {string[]} */
+export function listSkillIds() {
+  return Array.from(_registry.keys());
+}

package/src/framework/state-utils.js

@@ -0,0 +1,52 @@
+/**
+ * State Schema Utility Functions
+ * Helper functions for working with Zod state schemas
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+/**
+ * Get JSON Schema for frontend/API docs
+ * @param {import('zod').ZodSchema} zodSchema - Zod schema to convert
+ * @returns {Object} JSON Schema in OpenAPI 3 format
+ */
+export function getJsonSchema(zodSchema) {
+  if (!zodSchema) return null;
+  return zodToJsonSchema(zodSchema, { target: 'openApi3' });
+}
+
+/**
+ * Convert Zod schema to Variable Inspector format
+ * @param {import('zod').ZodSchema} zodSchema - Zod schema to convert
+ * @param {string} prefix - Optional prefix for nested paths
+ * @returns {Array} Flattened variable definitions
+ */
+export function schemaToVariables(zodSchema, prefix = '') {
+  const jsonSchema = zodToJsonSchema(zodSchema);
+  return flattenJsonSchema(jsonSchema, prefix);
+}
+
+function flattenJsonSchema(schema, prefix = '') {
+  const variables = [];
+  
+  if (schema.type === 'object' && schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      const isRequired = schema.required?.includes(key) ?? false;
+      
+      variables.push({
+        name: key,
+        path,
+        type: propSchema.type || 'unknown',
+        description: propSchema.description,
+        optional: !isRequired,
+      });
+      
+      if (propSchema.type === 'object' && propSchema.properties) {
+        variables.push(...flattenJsonSchema(propSchema, path));
+      }
+    }
+  }
+  
+  return variables;
+}

package/src/framework/state.js

@@ -0,0 +1,67 @@
+/**
+ * State management for agent workflow graphs
+ * Similar to LangGraph's state annotation
+ */
+
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function assertSafeKey(key) {
+  if (UNSAFE_KEYS.has(key)) {
+    throw new Error(`Invalid state key: "${key}"`);
+  }
+}
+
+export class WorkflowState {
+  constructor(initialState = {}) {
+    this._state = Object.create(null);
+    Object.assign(this._state, {
+      messages: [],
+      errors: [],
+      artifacts: {},
+      metadata: {},
+      ...initialState
+    });
+    this._history = [];
+  }
+
+  get(key) {
+    return this._state[key];
+  }
+
+  set(key, value) {
+    assertSafeKey(key);
+    this._history.push({ ...this._state });
+    this._state[key] = value;
+  }
+
+  update(updates) {
+    const keys = Object.getOwnPropertyNames(updates);
+    for (const key of keys) {
+      assertSafeKey(key);
+    }
+    this._history.push({ ...this._state });
+    for (const key of keys) {
+      this._state[key] = updates[key];
+    }
+  }
+
+  append(key, value) {
+    assertSafeKey(key);
+    this._history.push({ ...this._state });
+    if (!Array.isArray(this._state[key])) {
+      this._state[key] = [];
+    }
+    this._state[key].push(value);
+  }
+
+  getAll() {
+    return { ...this._state };
+  }
+
+  rollback() {
+    if (this._history.length > 0) {
+      this._state = this._history.pop();
+    }
+  }
+}
+