@zibby/core 0.1.0

package/src/framework/agents/cursor-strategy.js

@@ -0,0 +1,459 @@
+import { AgentStrategy } from './base.js';
+import { spawn, execSync } from 'child_process';
+import { writeFileSync, unlinkSync, mkdtempSync, readFileSync, mkdirSync, existsSync, accessSync, constants } from 'fs';
+import { join } from 'path';
+import { tmpdir, homedir } from 'os';
+import { logger } from '../../utils/logger.js';
+import { DEFAULT_MODELS, TIMEOUTS } from '../../constants.js';
+import { DEFAULT_OUTPUT_BASE, SESSION_INFO_FILE } from '../constants.js';
+import { getAllSkills } from '../skill-registry.js';
+import { StreamingParser } from '../../utils/streaming-parser.js';
+import { CursorOutputFormatter } from './utils/cursor-output-formatter.js';
+import { formatWithOpenAIProxy } from './utils/openai-proxy-formatter.js';
+import { timeline } from '../../utils/timeline.js';
+
+export class CursorAgentStrategy extends AgentStrategy {
+  constructor() {
+    super(
+      'cursor',
+      'Cursor Agent (Local IDE Agent)',
+      100
+    );
+  }
+
+  canHandle(_context) {
+    const paths = [
+      'agent',
+      '/usr/local/bin/agent',
+      '/usr/local/bin/cursor-agent',
+      '/Applications/Cursor.app/Contents/Resources/app/bin/cursor'
+    ];
+    
+    for (const path of paths) {
+      try {
+        if (path.startsWith('/')) {
+          accessSync(path, constants.X_OK);
+          logger.debug(`[Cursor] Found agent at: ${path}`);
+          return true;
+        }
+        execSync(`${path} --version 2>/dev/null`, { stdio: 'ignore', timeout: 2000 });
+        logger.debug(`[Cursor] Found '${path}' in PATH`);
+        return true;
+      } catch (_e) {
+        continue;
+      }
+    }
+    
+    logger.warn('[Cursor] ❌ Cursor Agent CLI not found');
+    return false;
+  }
+
+  async invoke(prompt, options = {}) {
+    const {
+      workspace = process.cwd(),
+      print: _print = false,
+      schema = null,
+      skills = null,
+      sessionPath = null,
+      timeout = TIMEOUTS.CURSOR_AGENT_DEFAULT,
+      config = {}
+    } = options;
+
+    const strictMode = config?.agent?.strictMode || false;
+
+    // Model: prefer .zibby.config.js agent.cursor.model so CLI uses it instead of IDE default
+    const model = options.model ?? config?.agent?.cursor?.model ?? DEFAULT_MODELS.CURSOR;
+
+    logger.debug(`[Cursor] Invoking (model: ${model}, timeout: ${timeout / 1000}s, skills: ${JSON.stringify(skills)})`);
+
+    this._setupMcpConfig(sessionPath, workspace, config);
+
+    const possibleBins = [
+      'agent',
+      '/usr/local/bin/agent',
+      '/usr/local/bin/cursor-agent',
+      '/Applications/Cursor.app/Contents/Resources/app/bin/cursor'
+    ];
+    
+    let cursorBin = 'agent';
+    for (const bin of possibleBins) {
+      if (bin === 'agent') {
+        cursorBin = bin;
+        break;
+      }
+      if (existsSync(bin)) {
+        cursorBin = bin;
+        break;
+      }
+    }
+    
+    // File-based structured output: agent writes JSON to this file
+    let resultFilePath = null;
+    if (schema) {
+      const resultFileName = `zibby-result-${Date.now()}.json`;
+      resultFilePath = join(workspace, '.zibby', 'tmp', resultFileName);
+      const tmpDir = join(workspace, '.zibby', 'tmp');
+      if (!existsSync(tmpDir)) mkdirSync(tmpDir, { recursive: true });
+
+      const formatInstructions = CursorOutputFormatter.generateFileOutputInstructions(schema, resultFilePath);
+      prompt = `${prompt}\n\n${formatInstructions}`;
+    }
+    
+    const promptTmpDir = mkdtempSync(join(tmpdir(), 'zibby-prompt-'));
+    const promptFile = join(promptTmpDir, 'prompt.md');
+    writeFileSync(promptFile, prompt, 'utf-8');
+    logger.debug(`📝 [Agent] Prompt written to ${promptFile} (${prompt.length} chars)`);
+    
+    let args;
+    if (cursorBin === 'agent') {
+      args = [
+        'chat', 
+        '--print', 
+        '--force', 
+        '--approve-mcps',
+        '--output-format', 'stream-json',
+        '--stream-partial-output',
+        '--model', model || 'auto', 
+      ];
+      if (process.env.CURSOR_API_KEY) {
+        args.push('--api-key', process.env.CURSOR_API_KEY);
+      }
+      args.push(`@${promptFile}`);
+    } else {
+      args = ['agent', '--print', '--force', '--trust', '--approve-mcps'];
+      if (process.env.CURSOR_API_KEY) {
+        args.push('--api-key', process.env.CURSOR_API_KEY);
+      }
+      args.push('--model', model || 'auto', `@${promptFile}`);
+    }
+    
+    const fullCmd = [cursorBin, ...args].join(' ');
+    logger.debug(`[Agent] Executing: ${fullCmd.slice(0, 200)}`);
+    logger.debug(`[Agent] Workspace: ${workspace}`);
+    if (process.env.LOG_LEVEL === 'debug' || process.env.ZIBBY_LOG_CURSOR_CLI === '1') {
+      console.log(`\n🔧 Cursor CLI --model ${model || 'auto'} (from .zibby.config.js agent.cursor.model)\n`);
+      if (process.env.ZIBBY_LOG_CURSOR_CLI === '1') {
+        console.log(`   Full command: ${fullCmd}\n`);
+      }
+    }
+    
+    let spawnResult;
+    let spawnError = null;
+    try {
+      spawnResult = await this._spawnWithStreaming(cursorBin, args, workspace, timeout, prompt);
+    } catch (err) {
+      spawnError = err;
+    } finally {
+      try { unlinkSync(promptFile); } catch {}
+    }
+
+    const rawOutput = spawnResult?.stdout || '';
+
+    if (schema) {
+      const isZodSchema = typeof schema.parse === 'function';
+
+      // Step 1: Read the file the agent was told to write (even if agent crashed)
+      let fileContent = null;
+      if (resultFilePath && existsSync(resultFilePath)) {
+        try {
+          const raw = readFileSync(resultFilePath, 'utf-8').trim();
+          fileContent = JSON.parse(raw);
+          logger.debug(`[Agent] Read structured output file (${raw.length} chars)`);
+          if (spawnError) {
+            logger.debug(`[Agent] Agent exited non-zero but result file was written — recovering`);
+          }
+        } catch (parseErr) {
+          logger.warn(`⚠️  [Agent] Result file exists but failed to parse: ${parseErr.message}`);
+        }
+      } else if (!spawnError) {
+        logger.warn(`⚠️  [Agent] Result file not found at ${resultFilePath}`);
+      }
+
+      // Step 2: Validate with Zod if we got parsed JSON
+      if (fileContent && isZodSchema) {
+        try {
+          const validated = schema.parse(fileContent);
+          logger.debug(`✅ [Agent] File-based output validated with Zod — done`);
+          return { raw: rawOutput, structured: validated };
+        } catch (zodErr) {
+          logger.warn(`⚠️  [Agent] File JSON failed Zod validation: ${zodErr.message?.slice(0, 300)}`);
+        }
+      } else if (fileContent) {
+        logger.debug(`✅ [Agent] File-based output extracted (no Zod schema) — done`);
+        return { raw: rawOutput, structured: fileContent };
+      }
+
+      // Step 3: If strict mode, fall back to OpenAI proxy to enforce schema
+      if (strictMode && !spawnError) {
+        const parsedText = spawnResult.parsedText;
+        const proxyInput = fileContent ? JSON.stringify(fileContent) : parsedText;
+        logger.debug(`[Agent] strictMode — falling back to OpenAI proxy (${proxyInput.length} chars)`);
+        const result = await formatWithOpenAIProxy(proxyInput, schema);
+        if (isZodSchema) {
+          const validated = schema.parse(result.structured);
+          return { raw: rawOutput, structured: validated };
+        }
+        return { raw: rawOutput, ...result };
+      }
+
+      // If agent crashed and we couldn't salvage from file, re-throw original error
+      if (spawnError) throw spawnError;
+
+      logger.error(`❌ [Agent] No structured output extracted from file`);
+      logger.error(`💡 Tip: Set strictMode=true in .zibby.config.js for OpenAI proxy fallback`);
+      throw new Error(`Agent did not produce a valid result file at ${resultFilePath}. Enable strictMode for proxy fallback.`);
+    }
+
+    // No schema — non-zero exit is a real failure
+    if (spawnError) throw spawnError;
+
+    return rawOutput;
+  }
+
+  _setupMcpConfig(sessionPath, workspace, config) {
+    const cursorDir = join(homedir(), '.cursor');
+    const mcpConfigPath = join(cursorDir, 'mcp.json');
+    
+    let existing = {};
+    if (existsSync(mcpConfigPath)) {
+      try {
+        existing = JSON.parse(readFileSync(mcpConfigPath, 'utf-8'));
+      } catch { /* start fresh */ }
+    }
+    const mcpServers = existing.mcpServers || {};
+
+    const outputBase = config?.paths?.output || DEFAULT_OUTPUT_BASE;
+    const sessionInfoPath = join(workspace || process.cwd(), outputBase, SESSION_INFO_FILE);
+
+    const configured = new Set();
+    for (const [, skill] of getAllSkills()) {
+      if (typeof skill.resolve !== 'function') continue;
+      if (configured.has(skill.serverName)) continue;
+      configured.add(skill.serverName);
+      this._ensureSkillConfigured(mcpServers, skill, sessionPath, sessionInfoPath);
+    }
+
+    if (Object.keys(mcpServers).length === 0) {
+      logger.debug(`[MCP] No MCP servers configured - agent will run without tool access`);
+      return;
+    }
+    
+    if (!existsSync(cursorDir)) {
+      mkdirSync(cursorDir, { recursive: true });
+    }
+    
+    writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers }, null, 2));
+    logger.debug(`[MCP] Config: ${Object.keys(mcpServers).join(', ')}`);
+  }
+
+  _ensureSkillConfigured(mcpServers, skill, sessionPath, sessionInfoPath) {
+    const preferredKey = skill.cursorKey || skill.serverName;
+    const existingKey = mcpServers[preferredKey] ? preferredKey
+      : mcpServers[skill.serverName] ? skill.serverName
+      : null;
+
+    if (existingKey && sessionPath) {
+      mcpServers[existingKey].args = (mcpServers[existingKey].args || []).map(arg =>
+        arg.startsWith('--output-dir=') ? `--output-dir=${sessionPath}` : arg
+      );
+      if (skill.sessionEnvKey) {
+        mcpServers[existingKey].env = {
+          ...(mcpServers[existingKey].env || {}),
+          [skill.sessionEnvKey]: sessionInfoPath,
+        };
+      }
+      logger.debug(`[MCP] Updated ${existingKey} session → ${sessionPath}`);
+      return;
+    }
+
+    if (existingKey) return;
+
+    const resolved = skill.resolve({ sessionPath });
+    if (!resolved) return;
+
+    mcpServers[preferredKey] = {
+      ...resolved,
+      ...(skill.sessionEnvKey && {
+        env: { ...(resolved.env || {}), [skill.sessionEnvKey]: sessionInfoPath },
+      }),
+    };
+    logger.debug(`[MCP] Configured ${preferredKey}`);
+  }
+
+  _spawnWithStreaming(bin, args, cwd, timeout, stdinPrompt = null) {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+      let stdout = '';
+      let stderr = '';
+      let lastOutputTime = Date.now();
+      let lineCount = 0;
+      let killed = false;
+
+      const proc = spawn(bin, args, {
+        cwd,
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      logger.debug(`[Agent] PID: ${proc.pid}`);
+
+      if (stdinPrompt) {
+        proc.stdin.write(stdinPrompt);
+        proc.stdin.end();
+        logger.debug(`[Agent] Prompt also piped to stdin (${stdinPrompt.length} chars)`);
+      } else {
+        proc.stdin.end();
+      }
+
+      const modifiedFiles = new Set();
+      const _startIso = new Date(startTime).toISOString().replace(/\.\d+Z$/, '');
+
+      const heartbeat = setInterval(() => {
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        const _silent = Math.round((Date.now() - lastOutputTime) / 1000);
+        
+        const newFiles = [];
+        try {
+          const elapsedMin = Math.ceil(elapsed / 60) + 1;
+          const raw = execSync(
+            `find "${cwd}" -type f -mmin -${elapsedMin} -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/target/*' 2>/dev/null | head -20`,
+            { encoding: 'utf-8', timeout: 5000 }
+          ).trim();
+          if (raw) {
+            for (const f of raw.split('\n')) {
+              const rel = f.replace(`${cwd  }/`, '');
+              if (!modifiedFiles.has(rel)) {
+                modifiedFiles.add(rel);
+                newFiles.push(rel);
+              }
+            }
+          }
+        } catch {}
+
+        let activity = '';
+        if (newFiles.length > 0) {
+          const short = newFiles.map(f => f.split('/').pop());
+          activity = ` | 📁 new: ${short.join(', ')}`;
+        }
+        if (modifiedFiles.size > 0) {
+          activity += ` | 📦 total: ${modifiedFiles.size} files`;
+        }
+
+        logger.debug(`💓 [Agent] Running for ${elapsed}s | ${lineCount} lines output${activity}`);
+
+        if (lineCount === 0 && elapsed >= 90 && elapsed < 120 && modifiedFiles.size === 0) {
+          logger.warn(`⚠️  [Agent] No output and no file changes after ${elapsed}s — agent may be stuck.`);
+          try {
+            const procInfo = execSync(`ps -p ${proc.pid} -o pid,stat,rss,time 2>/dev/null || echo "Process info unavailable"`, { encoding: 'utf-8', timeout: 5000 });
+            logger.warn(`⚠️  [Agent] Process: ${procInfo.trim()}`);
+          } catch {}
+        }
+      }, 30000);
+
+      const timer = setTimeout(() => {
+        killed = true;
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        logger.error(`⏱️  [Agent] Timeout after ${elapsed}s — killing process (PID: ${proc.pid})`);
+        if (stdout.trim()) {
+          logger.warn(`📤 [Agent] Partial output (${stdout.length} chars) before timeout:\n${stdout.slice(-2000)}`);
+        }
+        proc.kill('SIGTERM');
+        setTimeout(() => {
+          if (!proc.killed) proc.kill('SIGKILL');
+        }, 5000);
+      }, timeout);
+
+      const streamParser = new StreamingParser();
+      streamParser.onToolCall = (name, input) => {
+        let displayName = name;
+        let displayInput = input;
+        if (name === 'mcpToolCall' && input?.name) {
+          displayName = input.name.replace(/^mcp_+[^_]+_+/, '');
+          if (displayName.includes('-') && displayName.split('-')[0] === displayName.split('-')[1]) {
+            displayName = displayName.split('-')[0];
+          }
+          displayInput = input.args ?? input.input ?? input;
+        } else if (name === 'readToolCall' || name === 'editToolCall' || name === 'writeToolCall') {
+          return;
+        } else if (name.startsWith('mcp__') || name.includes('ToolCall')) {
+          displayName = name.replace(/^mcp_+[^_]+_+/, '').replace(/ToolCall$/, '');
+        }
+        const isMemoryTool = displayName.includes('memory');
+        if (isMemoryTool) {
+          timeline.stepMemory(`Tool: ${displayName}`);
+        } else {
+          timeline.stepTool(`Tool: ${displayName}`);
+        }
+        if (displayInput != null && typeof displayInput === 'object' && Object.keys(displayInput).length > 0) {
+          const raw = JSON.stringify(displayInput);
+          const preview = raw.length > 100 ? `${raw.substring(0, 100)}...` : raw;
+          console.log(`  Input: ${preview}`);
+        }
+      };
+      
+      proc.stdout.on('data', (data) => {
+        const chunk = data.toString();
+        stdout += chunk;
+        lastOutputTime = Date.now();
+        
+        const displayText = streamParser.processChunk(chunk);
+        if (displayText) {
+          process.stdout.write(displayText);
+        }
+        
+        const lines = chunk.split('\n').filter(l => l.trim());
+        lineCount += lines.length;
+      });
+
+      proc.stderr.on('data', (data) => {
+        const chunk = data.toString();
+        stderr += chunk;
+        lastOutputTime = Date.now();
+        
+        const lines = chunk.split('\n').filter(l => l.trim());
+        for (const line of lines) {
+          logger.warn(`⚠️  [Agent stderr] ${line}`);
+        }
+      });
+
+      proc.on('close', (code, signal) => {
+        clearTimeout(timer);
+        clearInterval(heartbeat);
+        streamParser.flush();
+        const elapsed = Math.round((Date.now() - startTime) / 1000);
+        logger.debug(`[Agent] Exited: code=${code}, signal=${signal}, elapsed=${elapsed}s, output=${stdout.length} chars`);
+        timeline.step(`Agent completed (${elapsed}s)`);
+
+        if (killed) {
+          reject(new Error(
+            `Cursor Agent timed out after ${elapsed}s (limit: ${timeout / 1000}s). ` +
+            `${lineCount} lines produced. Last output ${Math.round((Date.now() - lastOutputTime) / 1000)}s ago. ${ 
+            stdout.trim() ? `\nPartial output (last 500 chars):\n${stdout.slice(-500)}` : 'No output captured.'}`
+          ));
+          return;
+        }
+
+        if (code !== 0) {
+          reject(new Error(
+            `Cursor Agent failed: exit code ${code}, signal ${signal}. ${ 
+            stderr.trim() ? `\nStderr: ${stderr.slice(-1000)}` : '' 
+            }${stdout.trim() ? `\nStdout (last 500 chars): ${stdout.slice(-500)}` : ''}`
+          ));
+          return;
+        }
+
+        const extractedJson = streamParser.getResult();
+        const parsedText = extractedJson
+          ? JSON.stringify(extractedJson, null, 2)
+          : (streamParser.getRawText() || stdout || '');
+        resolve({ stdout: stdout || stderr || '', parsedText });
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timer);
+        clearInterval(heartbeat);
+        reject(new Error(`Cursor Agent spawn error: ${err.message}`));
+      });
+    });
+  }
+}

package/src/framework/agents/index.js

@@ -0,0 +1,105 @@
+/**
+ * Agent Strategy Factory
+ * 
+ * Selects the best available agent strategy based on:
+ * 1. User preference (state.agentType or AGENT_TYPE env)
+ * 2. Availability (can the strategy be used?)
+ * 3. Priority (which strategy is preferred?)
+ */
+
+import { CursorAgentStrategy } from './cursor-strategy.js';
+import { ClaudeAgentStrategy } from './claude-strategy.js';
+import { logger } from '../../utils/logger.js';
+
+// Registry of all available agent strategies
+const AGENT_STRATEGIES = [
+  new CursorAgentStrategy(),
+  new ClaudeAgentStrategy()
+];
+
+/**
+ * Get the best available agent strategy
+ * @param {Object} context - Context containing state, env, etc.
+ * @returns {AgentStrategy}
+ */
+export function getAgentStrategy(context = {}) {
+  const { state = {}, preferredAgent = null } = context;
+  
+  // Agent must be explicitly specified - no auto-selection
+  const requestedAgent = preferredAgent || 
+                         state.agentType || 
+                         process.env.AGENT_TYPE;
+
+  if (!requestedAgent) {
+    throw new Error('No agent specified. Set agent.claude or agent.cursor in .zibby.config.js');
+  }
+
+  logger.debug(`Agent selection: requested=${requestedAgent}`);
+
+  const strategy = AGENT_STRATEGIES.find(s => s.getName() === requestedAgent);
+  
+  if (!strategy) {
+    throw new Error(`Unknown agent '${requestedAgent}'. Available: ${AGENT_STRATEGIES.map(s => s.getName()).join(', ')}`);
+  }
+  
+  logger.debug(`Checking if ${requestedAgent} can handle this environment...`);
+  if (!strategy.canHandle(context)) {
+    const hint = requestedAgent === 'claude' 
+      ? 'Set ANTHROPIC_API_KEY in .env' 
+      : 'Install cursor-agent CLI or set CURSOR_API_KEY';
+    throw new Error(`Agent '${requestedAgent}' is not available. ${hint}`);
+  }
+
+  logger.debug(`Using agent: ${strategy.getName()}`);
+  return strategy;
+}
+
+/**
+ * Invoke an agent with automatic strategy selection
+ * @param {string} prompt - The prompt to send
+ * @param {Object} context - Context for strategy selection
+ * @param {Object} options - Options for invoke (model, workspace, etc.)
+ * @returns {Promise<string>}
+ */
+export async function invokeAgent(prompt, context = {}, options = {}) {
+  const strategy = getAgentStrategy(context);
+
+  const config = context.state?.config || options.config || {};
+  const finalOptions = {
+    model: options.model ?? context.state?.model ?? config?.agent?.claude?.model ?? config?.agent?.cursor?.model,
+    workspace: context.state?.workspace || options.workspace,
+    schema: options.schema || context.schema,
+    images: options.images || context.images || [],
+    skills: options.skills || context.skills || null,
+    config,
+    ...options
+  };
+  if (!finalOptions.model) {
+    finalOptions.model = finalOptions.config?.agent?.cursor ? (finalOptions.config.agent.cursor.model ?? 'auto') : (finalOptions.config?.agent?.claude?.model ?? 'auto');
+  }
+
+  const extraInstructions = context.state?._currentNodeConfig?.extraPromptInstructions?.trim();
+  if (extraInstructions) {
+    prompt += `\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚠️ PRIORITY OVERRIDE — THE FOLLOWING INSTRUCTIONS TAKE PRECEDENCE OVER ALL PREVIOUS CONTENT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+${extraInstructions}
+`;
+  }
+
+  logger.debug(`Prompt length: ${prompt.length} chars`);
+  if (process.env.STAGE !== 'prod') {
+    logger.debug(`Full prompt:\n${prompt}`);
+  }
+
+  const rawOutput = await strategy.invoke(prompt, finalOptions);
+  
+  // Return the output as-is (strategy handles formatting)
+  // For schemas: { raw: string, structured: object }
+  // For text: string
+  return rawOutput;
+}
+
+export { CursorAgentStrategy, ClaudeAgentStrategy };
+export { AgentStrategy } from './base.js';

package/src/framework/agents/utils/cursor-output-formatter.js

@@ -0,0 +1,67 @@
+/**
+ * Cursor Output Formatter
+ * Generates prompt instructions for file-based structured output from Cursor agent
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+export class CursorOutputFormatter {
+  /**
+   * Generate prompt instructions telling the agent to write structured JSON to a file.
+   * @param {Object} schema - Zod schema
+   * @param {string} outputFilePath - Absolute path the agent must write to
+   * @returns {string} Prompt instructions to append
+   */
+  static generateFileOutputInstructions(schema, outputFilePath) {
+    let jsonSchema;
+    if (typeof schema?.parse === 'function') {
+      jsonSchema = zodToJsonSchema(schema, { target: 'openApi3' });
+    } else {
+      jsonSchema = schema;
+    }
+
+    const example = this._buildExample(jsonSchema);
+
+    return `
+[OUTPUT INSTRUCTIONS]
+Write your result as pure JSON to this file: ${outputFilePath}
+Exact structure (follow types and nesting precisely):
+${JSON.stringify(example, null, 2)}
+Rules: valid JSON only, no markdown wrapping, no extra text. Stop after writing.`;
+  }
+
+  /**
+   * Build a representative example object from a JSON Schema,
+   * showing correct types and nesting so the agent knows the exact shape.
+   */
+  static _buildExample(schema) {
+    if (!schema) return {};
+    const type = schema.type;
+
+    if (type === 'object' && schema.properties) {
+      const obj = {};
+      for (const [key, prop] of Object.entries(schema.properties)) {
+        obj[key] = this._buildExample(prop);
+      }
+      return obj;
+    }
+
+    if (type === 'array' && schema.items) {
+      return [this._buildExample(schema.items)];
+    }
+
+    if (schema.description) return `<${schema.description}>`;
+    if (type === 'string') return '<string>';
+    if (type === 'number' || type === 'integer') return 0;
+    if (type === 'boolean') return false;
+
+    if (schema.nullable || schema.oneOf || schema.anyOf) {
+      const inner = schema.oneOf?.find(s => s.type !== 'null') ||
+                    schema.anyOf?.find(s => s.type !== 'null');
+      if (inner) return this._buildExample(inner);
+      return null;
+    }
+
+    return '<value>';
+  }
+}