natureco-cli 5.19.0 → 5.20.1

package/src/tools/search_provider.js

@@ -0,0 +1,79 @@
+const loadConfig = () => {
+  try { return JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(), '.natureco', 'config.json'), 'utf8')); } catch { return {}; }
+};
+
+require('../providers/search/tavily');
+require('../providers/search/duckduckgo');
+require('../providers/search/searxng');
+require('../providers/search/exa');
+
+const name = 'search_provider';
+const description = 'Unified search backend with pluggable providers. search/status/switch/list. Supports Tavily, DuckDuckGo, SearXNG, Exa. Switch via NATURECO_SEARCH_PROVIDER env or config.searchProvider. Default: tavily (falls back to others if no API key).';
+const parameters = {
+  type: 'object',
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['search', 'status', 'list', 'switch'],
+      description: 'Operation: search, status, list, or switch',
+    },
+    query: { type: 'string', description: '(search) Search query' },
+    maxResults: { type: 'number', description: '(search) Max results (default: 5)' },
+    provider: { type: 'string', description: '(search/switch) Provider name to use or switch to' },
+  },
+  required: ['action'],
+};
+
+async function execute(params) {
+  const cfg = loadConfig();
+  const { getActiveProvider, getProviderNames, resolveProviderConfig, getProvider } = require('../utils/search-provider');
+
+  switch (params.action) {
+    case 'search': {
+      if (!params.query) return { success: false, error: 'query gerekli' };
+      const providerName = params.provider || process.env.NATURECO_SEARCH_PROVIDER || cfg.searchProvider;
+      let Provider;
+      if (providerName) Provider = getProvider(providerName);
+      if (!Provider) Provider = getActiveProvider(cfg);
+      const provider = new Provider(cfg);
+      return provider.search(params.query, { maxResults: params.maxResults || 5 });
+    }
+
+    case 'status': {
+      const active = resolveProviderConfig(cfg);
+      const avail = getProviderNames().sort();
+      return {
+        active,
+        available: avail,
+        config: cfg.searchProvider || '(not set, using default)',
+        env: process.env.NATURECO_SEARCH_PROVIDER || '(not set)',
+        default: 'tavily',
+      };
+    }
+
+    case 'list': {
+      const avail = getProviderNames().sort();
+      return {
+        success: true,
+        providers: avail.map(name => {
+          const Provider = getProvider(name);
+          const inst = new Provider(cfg);
+          const hasKey = name === 'duckduckgo' || name === 'searxng' || !!(cfg[name + 'ApiKey'] || process.env[name.toUpperCase() + '_API_KEY']);
+          return { name, available: hasKey };
+        }),
+      };
+    }
+
+    case 'switch': {
+      if (!params.provider) return { success: false, error: 'provider (name) gerekli' };
+      const { setConfigValue } = require('../utils/config');
+      setConfigValue('searchProvider', params.provider);
+      return { success: true, message: `Search provider switched to: ${params.provider}` };
+    }
+
+    default:
+      return { success: false, error: `Unknown action: ${params.action}` };
+  }
+}
+
+module.exports = { name, description, parameters, execute };

package/src/tools/web_search.js

@@ -1,82 +1,62 @@
 const { getConfig } = require('../utils/config');
+const { getActiveProvider, getProviderNames, DEFAULT_PROVIDER } = require('../utils/search-provider');
+require('../providers/search/tavily');
+require('../providers/search/duckduckgo');
+require('../providers/search/searxng');
+require('../providers/search/exa');
 
 module.exports = {
   name: 'web_search',
-  description: 'Search the web for current information using Tavily',
+  description: 'Search the web for current information using the configured search provider (Tavily, DuckDuckGo, SearXNG, Exa). Switch via NATURECO_SEARCH_PROVIDER env or config.searchProvider.',
   inputSchema: {
     type: 'object',
     properties: {
-      query: {
-        type: 'string',
-        description: 'Search query'
-      }
+      query: { type: 'string', description: 'Search query' },
+      maxResults: { type: 'number', description: 'Maximum results (default: 5)' },
+      provider: { type: 'string', description: 'Override provider: tavily, duckduckgo, searxng, exa (default: configured or tavily)' },
     },
     required: ['query']
   },
-  
+
   async execute(params) {
     try {
       const config = getConfig();
-      const apiKey = config.tavilyApiKey || process.env.TAVILY_API_KEY;
-      
-      if (!apiKey) {
-        return {
-          success: false,
-          error: 'Tavily API key gerekli. Kur: natureco config set tavilyApiKey tvly_xxx\nÜcretsiz key: https://tavily.com'
-        };
-      }
-      
-      const response = await fetch('https://api.tavily.com/search', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          api_key: apiKey,
-          query: params.query,
-          search_depth: 'basic',
-          max_results: 5
-        })
-      });
-      
-      if (!response.ok) {
-        return {
-          success: false,
-          error: `Tavily API error: ${response.status} ${response.statusText}`
-        };
+      const providerName = params.provider || process.env.NATURECO_SEARCH_PROVIDER || config.searchProvider;
+      let Provider;
+
+      if (providerName) {
+        const { getProvider } = require('../utils/search-provider');
+        Provider = getProvider(providerName);
       }
-      
-      const data = await response.json();
-      
-      if (data.error) {
-        return {
-          success: false,
-          error: data.error
-        };
+      if (!Provider) {
+        Provider = getActiveProvider(config);
       }
-      
-      if (!data.results || data.results.length === 0) {
-        return {
-          success: true,
-          message: 'Sonuç bulunamadı',
-          query: params.query,
-          results: []
-        };
+
+      const provider = new Provider(config);
+      const result = await provider.search(params.query, {
+        maxResults: params.maxResults || 5,
+      });
+
+      if (!result.success && providerName && !params.provider) {
+        const allProviders = getProviderNames();
+        for (const name of allProviders) {
+          if (name === providerName) continue;
+          const { getProvider } = require('../utils/search-provider');
+          const FallbackProvider = getProvider(name);
+          if (!FallbackProvider) continue;
+          const fallback = new FallbackProvider(config);
+          const fallbackResult = await fallback.search(params.query, { maxResults: params.maxResults || 5 });
+          if (fallbackResult.success) {
+            fallbackResult.fallback = true;
+            fallbackResult.fallbackReason = result.error;
+            return fallbackResult;
+          }
+        }
       }
-      
-      return {
-        success: true,
-        query: params.query,
-        results: data.results.map(r => ({
-          title: r.title,
-          snippet: r.content,
-          url: r.url
-        })),
-        count: data.results.length
-      };
+
+      return result;
     } catch (error) {
-      return {
-        success: false,
-        error: error.message
-      };
+      return { success: false, error: error.message };
     }
   }
 };

package/src/tools/workflow.js

@@ -6,6 +6,8 @@ const os = require('os');
 const WORKFLOW_DIR = path.join(os.homedir(), '.natureco', 'workflows');
 const WORKFLOW_HISTORY = path.join(os.homedir(), '.natureco', 'workflow-history.json');
 
+const { buildSkillIndex } = require('../utils/skill-index');
+
 function ensureDir(dir) { try { fs.mkdirSync(dir, { recursive: true }); } catch {} }
 function loadConfig() {
   try { return JSON.parse(fs.readFileSync(path.join(os.homedir(), '.natureco', 'config.json'), 'utf8')); } catch { return {}; }
@@ -94,6 +96,8 @@ async function workflow(params) {
     return { success: false, error: 'Provider ayarli degil. Once: natureco setup' };
   }
 
+  const skillsIndexBlock = buildSkillIndex();
+
   // ── RUN: Execute a complete workflow ──────────────────────────────────
   if (action === 'run') {
     if (!task) return { success: false, error: 'task gerekli' };
@@ -114,7 +118,7 @@ async function workflow(params) {
     if (isSimple) {
       // Passthrough: just chat with LLM, no tools — include user memory
       const memCtx = memoryContext();
-      const sysMsg = 'Sen yardimci bir asistansin. Kisa ve oz yanit ver.' + (memCtx ? '\n\nKullanici bilgisi:\n' + memCtx : '');
+      const sysMsg = 'Sen yardimci bir asistansin. Kisa ve oz yanit ver.' + (memCtx ? '\n\nKullanici bilgisi:\n' + memCtx : '') + '\n\n' + skillsIndexBlock;
       const chatBody = { model, stream: false, messages: [{ role: 'system', content: sysMsg }, { role: 'user', content: task }], temperature: 0.7, max_tokens: 1000 };
       try {
         const chatResult = await apiCall(providerUrl, providerApiKey, chatBody);
@@ -127,12 +131,13 @@ async function workflow(params) {
 
     // Phase 1: LLM plans the workflow
     const memCtx = memoryContext();
-    const planPrompt = {
-      role: 'system',
-      content: 'Sen bir workflow planlama asistanisin. Verilen gorev icin hangi tool\'larin kullanilacagini ve hangi sirayla calisacagini belirle. SADECE JSON formatinda yanit ver, baska bir sey yazma.\n\nKullanilabilir tool\'lar:\n' +
-        tools.map(t => '- ' + t).join('\n') +
-        (memCtx ? '\n\nKullanici bilgisi:\n' + memCtx : '') +
-        '\n\nJSON format:\n{\n  "workflowName": "...",\n  "description": "...",\n  "steps": [\n    { "step": 1, "tool": "tool_name", "purpose": "...", "params": { ... } }\n  ]\n}\n\nHer adim icin params kismina tool\'un gerektirdigi parametreleri ekle. Adimlar birbirine bagimli olabilir, onceki adimin outputu sonraki adimin inputu olarak kullanilabilir.'
+      const planPrompt = {
+        role: 'system',
+        content: 'Sen bir workflow planlama asistanisin. Verilen gorev icin hangi tool\'larin kullanilacagini ve hangi sirayla calisacagini belirle. SADECE JSON formatinda yanit ver, baska bir sey yazma.\n\nKullanilabilir tool\'lar:\n' +
+          tools.map(t => '- ' + t).join('\n') +
+          '\n\nKullanilabilir skill\'ler (gorevle ilgili skill varsa plana skill_view adimi olarak ekle):\n' + skillsIndexBlock +
+          (memCtx ? '\n\nKullanici bilgisi:\n' + memCtx : '') +
+          '\n\nJSON format:\n{\n  "workflowName": "...",\n  "description": "...",\n  "skillsLoaded": ["..."],\n  "steps": [\n    { "step": 1, "tool": "tool_name", "purpose": "...", "params": { ... } }\n  ]\n}\n\nHer adim icin params kismina tool\'un gerektirdigi parametreleri ekle. Adimlar birbirine bagimli olabilir, onceki adimin outputu sonraki adimin inputu olarak kullanilabilir.\n\nGorevle ilgili skill varsa ILK adim olarak skill_view ile yukle, ardindan diger adimlara gec.'
     };
     const planBody = {
       model, stream: false,
@@ -172,7 +177,12 @@ async function workflow(params) {
       plan = JSON.parse(jsonStr);
       if (!plan.steps || !Array.isArray(plan.steps)) throw new Error('Steps bulunamadi');
     } catch (e) {
-      return { success: false, error: 'Plan cozumlenemedi: ' + e.message, raw: planResult.choices?.[0]?.message?.content?.slice(0, 500) };
+      // JSON parse hatasi — modelin ham ciktisini passthrough chat olarak goster
+      const rawReply = planResult.choices?.[0]?.message?.content || '';
+      if (rawReply) {
+        return { success: true, workflowId: 'passthrough', name: 'Direct Chat', status: 'completed', totalSteps: 0, completedSteps: 0, results: [{ step: 0, tool: 'chat', status: 'done', result: { reply: rawReply } }], passthrough: true, reply: rawReply };
+      }
+      return { success: false, error: 'Plan cozumlenemedi: ' + e.message, raw: rawReply.slice(0, 500) };
     }
 
     // Save plan
@@ -203,7 +213,8 @@ async function workflow(params) {
         role: 'system',
         content: 'Bir sonraki adimi calistiriyorsun. Sana verilen tool\'u ve parametreleri kullanarak islemi gerceklestir. Tool cagrisini dogru formatta yap.\n\nTool: ' + step.tool + '\nAmac: ' + (step.purpose || '') + '\nPlanlanan parametreler: ' + JSON.stringify(step.params || {}) +
           '\n\nOnceki adim sonuclari:\n' + stepResults.map(r => 'Adim ' + r.step + ' (' + r.tool + '): ' + (r.status === 'done' ? JSON.stringify(r.result).slice(0, 300) : r.status)).join('\n') +
-          '\n\nTek bir tool cagrisi yap ve sonucu bekle. Tool cagrisi yaparken Onceki adim sonuclarindaki gerekli verileri parametre olarak kullan.'
+          '\n\nKullanilabilir skill\'ler:\n' + skillsIndexBlock +
+          '\n\nTek bir tool cagrisi yap ve sonucu bekle. Tool cagrisi yaparken Onceki adim sonuclarindaki gerekli verileri parametre olarak kullan. Ilgili skill varsa once skill_view ile yukle, sonra asil tool\'u cagir.'
       };
       const executeBody = {
         model, stream: false,
@@ -251,6 +262,10 @@ async function workflow(params) {
     history.unshift({ id: wfId, name: plan.workflowName || task.slice(0, 50), task, status: wfEntry.status, steps: plan.steps.length, completedAt: wfEntry.completedAt });
     fs.writeFileSync(WORKFLOW_HISTORY, JSON.stringify(history.slice(0, 50), null, 2));
 
+    const skillsLoaded = stepResults
+      .filter(r => r.tool === 'skill_view' && r.status === 'done')
+      .map(r => r.args?.name || 'bilinmeyen-skill');
+
     return {
       success: true,
       workflowId: wfId,
@@ -260,6 +275,7 @@ async function workflow(params) {
       completedSteps: stepResults.filter(r => r.status === 'done').length,
       failedSteps: stepResults.filter(r => r.status === 'error' || r.status === 'skipped').length,
       status: wfEntry.status,
+      skillsLoaded: skillsLoaded.length > 0 ? skillsLoaded : undefined,
       plan: plan.steps.map(s => ({ step: s.step, tool: s.tool, purpose: s.purpose })),
       results: stepResults.map(r => ({
         step: r.step, tool: r.tool, status: r.status,
@@ -276,7 +292,8 @@ async function workflow(params) {
     const planPrompt = {
       role: 'system',
       content: 'Kullanilabilir tool\'lar:\n' + tools.map(t => '- ' + t).join('\n') +
-        '\n\nGorev icin bir workflow plani JSON formatinda olustur. JSON disinda hicbir sey yazma.\nFormat: { "workflowName": "...", "description": "...", "estimatedSteps": N, "steps": [{ "step": 1, "tool": "...", "purpose": "...", "params": {...}, "expectedOutput": "..." }] }'
+        '\n\nKullanilabilir skill\'ler:\n' + skillsIndexBlock +
+        '\n\nGorev icin bir workflow plani JSON formatinda olustur. JSON disinda hicbir sey yazma.\nFormat: { "workflowName": "...", "description": "...", "estimatedSteps": N, "skillsLoaded": ["..."], "steps": [{ "step": 1, "tool": "...", "purpose": "...", "params": {...}, "expectedOutput": "..." }] }\n\nGorevle ilgili skill varsa plana skill_view adimi olarak ekle.'
     };
     const planBody = {
       model, stream: false,

package/src/utils/cron.js

@@ -1,126 +1,82 @@
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const cron = require('node-cron');
-
-const CRON_FILE = path.join(os.homedir(), '.natureco', 'cron.json');
-const CRON_LOGS_DIR = path.join(os.homedir(), '.natureco', 'cron-logs');
-
-function ensureCronDirs() {
-  const dir = path.dirname(CRON_FILE);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  if (!fs.existsSync(CRON_LOGS_DIR)) {
-    fs.mkdirSync(CRON_LOGS_DIR, { recursive: true });
-  }
-}
-
-function loadCronJobs() {
-  ensureCronDirs();
-  if (!fs.existsSync(CRON_FILE)) {
-    return [];
-  }
-  try {
-    const data = fs.readFileSync(CRON_FILE, 'utf-8');
-    return JSON.parse(data);
-  } catch {
-    return [];
-  }
-}
-
-function saveCronJobs(jobs) {
-  ensureCronDirs();
-  fs.writeFileSync(CRON_FILE, JSON.stringify(jobs, null, 2), 'utf-8');
-}
-
-function addCronJob(job) {
-  const jobs = loadCronJobs();
-  const id = Date.now().toString(36) + Math.random().toString(36).slice(2);
-  const newJob = {
-    id,
-    ...job,
-    enabled: true,
-    createdAt: new Date().toISOString(),
-  };
-  jobs.push(newJob);
-  saveCronJobs(jobs);
-  return newJob;
-}
-
-function removeCronJob(id) {
-  const jobs = loadCronJobs();
-  const filtered = jobs.filter(j => j.id !== id);
-  saveCronJobs(filtered);
-  return filtered.length < jobs.length;
-}
-
-function updateCronJob(id, updates) {
-  const jobs = loadCronJobs();
-  const index = jobs.findIndex(j => j.id === id);
-  if (index === -1) return false;
-  jobs[index] = { ...jobs[index], ...updates };
-  saveCronJobs(jobs);
-  return true;
-}
-
-function getCronJob(id) {
-  const jobs = loadCronJobs();
-  return jobs.find(j => j.id === id);
-}
-
-function parseCronSchedule(schedule) {
-  // Basit zamanlama formatlarını cron expression'a çevir
-  if (schedule.startsWith('every ')) {
-    const parts = schedule.split(' ');
-    if (parts[2] === 'hours') {
-      const hours = parseInt(parts[1]);
-      return `0 */${hours} * * *`;
-    }
-    if (parts[2] === 'minutes') {
-      const minutes = parseInt(parts[1]);
-      return `*/${minutes} * * * *`;
-    }
-  }
-  
-  if (schedule.startsWith('daily at ')) {
-    const time = schedule.replace('daily at ', '');
-    const [hour, minute = '0'] = time.split(':');
-    return `${minute} ${hour} * * *`;
-  }
-  
-  // Zaten cron expression ise olduğu gibi döndür
-  return schedule;
-}
-
-function validateCronExpression(expression) {
-  return cron.validate(expression);
-}
-
-function logCronOutput(jobId, output) {
-  const logFile = path.join(CRON_LOGS_DIR, `${jobId}.log`);
-  const timestamp = new Date().toISOString();
-  const logEntry = `[${timestamp}]\n${output}\n\n`;
-  fs.appendFileSync(logFile, logEntry, 'utf-8');
-}
-
-function getCronLog(jobId) {
-  const logFile = path.join(CRON_LOGS_DIR, `${jobId}.log`);
-  if (!fs.existsSync(logFile)) {
-    return null;
-  }
-  return fs.readFileSync(logFile, 'utf-8');
-}
-
-module.exports = {
-  loadCronJobs,
-  saveCronJobs,
-  addCronJob,
-  removeCronJob,
-  updateCronJob,
-  getCronJob,
-  parseCronSchedule,
-  validateCronExpression,
-  logCronOutput,
-  getCronLog,
-};
+/**
+ * cron — Scheduled task monitoring (cron-like expressions)
+ *
+ * Format (standard cron): min hour dom mon dow
+ *   e.g., "every 5 min" -> minute field = "star/5"
+ * Checks if a task should run based on its schedule.
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const CRON_FILE = path.join(os.homedir(), '.natureco', 'cron-jobs.json');
+
+function parseCron(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length !== 5) return null;
+  const [min, hour, dom, mon, dow] = parts;
+  return { min, hour, dom, mon, dow };
+}
+
+function matchesField(value, pattern) {
+  if (pattern === '*') return true;
+  if (pattern.startsWith('*/')) {
+    const step = parseInt(pattern.slice(2), 10);
+    return value % step === 0;
+  }
+  if (pattern.includes(',')) return pattern.split(',').some(p => matchesField(value, p));
+  if (pattern.includes('-')) {
+    const [lo, hi] = pattern.split('-').map(Number);
+    return value >= lo && value <= hi;
+  }
+  return parseInt(pattern, 10) === value;
+}
+
+function shouldRun(expr) {
+  const parsed = parseCron(expr);
+  if (!parsed) return false;
+  const now = new Date();
+  return (
+    matchesField(now.getMinutes(), parsed.min) &&
+    matchesField(now.getHours(), parsed.hour) &&
+    matchesField(now.getDate(), parsed.dom) &&
+    matchesField(now.getMonth() + 1, parsed.mon) &&
+    matchesField(now.getDay(), parsed.dow)
+  );
+}
+
+function loadJobs() {
+  try {
+    if (fs.existsSync(CRON_FILE)) return JSON.parse(fs.readFileSync(CRON_FILE, 'utf8'));
+  } catch {}
+  return [];
+}
+
+function addJob(job) {
+  const jobs = loadJobs();
+  const entry = {
+    id: `cron_${Date.now()}`,
+    schedule: job.schedule,
+    command: job.command,
+    description: job.description || '',
+    createdAt: Date.now(),
+    lastRun: null,
+    enabled: true,
+  };
+  jobs.push(entry);
+  const dir = path.dirname(CRON_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(CRON_FILE, JSON.stringify(jobs, null, 2));
+  return entry;
+}
+
+function removeJob(id) {
+  const jobs = loadJobs().filter(j => j.id !== id);
+  const dir = path.dirname(CRON_FILE);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(CRON_FILE, JSON.stringify(jobs, null, 2));
+  return true;
+}
+
+module.exports = { parseCron, shouldRun, loadJobs, addJob, removeJob };

package/src/utils/effort-levels.js

@@ -0,0 +1,42 @@
+/**
+ * effort-levels — Effort level control (Claude Code: low/medium/high)
+ *
+ * Controls token budget, iteration limits, and tool breadth:
+ *   low:    quick answers, 2 tool iterations, 1024 max_tokens, minimal tools
+ *   medium: balanced, 5 iterations, 2048 max_tokens, standard tools (default)
+ *   high:   thorough, 12 iterations, 4096 max_tokens, all tools
+ */
+
+const LEVELS = { low: 'low', medium: 'medium', high: 'high' };
+
+const CONFIG = {
+  low: {
+    maxTokens: 1024,
+    maxToolIterations: 2,
+    temperature: 0.1,
+    toolBreadth: 'minimal',
+  },
+  medium: {
+    maxTokens: 2048,
+    maxToolIterations: 5,
+    temperature: 0.3,
+    toolBreadth: 'standard',
+  },
+  high: {
+    maxTokens: 4096,
+    maxToolIterations: 12,
+    temperature: 0.5,
+    toolBreadth: 'all',
+  },
+};
+
+function getLevel(cfg = {}) {
+  const level = (cfg.effort || cfg.effortLevel || 'medium').toLowerCase();
+  return LEVELS[level] || 'medium';
+}
+
+function getConfig(level) {
+  return CONFIG[level] || CONFIG.medium;
+}
+
+module.exports = { LEVELS, CONFIG, getLevel, getConfig };

package/src/utils/fallback-chain.js

@@ -0,0 +1,72 @@
+/**
+ * fallback-chain — Multi-model fallback chain (3 models max)
+ *
+ * Config:
+ *   "models": ["gpt-4", "claude-3", "gemini-pro"]
+ *   "fallback": {
+ *     "enabled": true,
+ *     "onError": true,
+ *     "onRateLimit": true,
+ *     "onTimeout": true
+ *   }
+ *
+ * Returns which model to use for each turn, rotating through the chain
+ * when errors occur.
+ */
+
+class FallbackChain {
+  constructor() {
+    this.models = [];
+    this.currentIndex = 0;
+    this.config = { onError: true, onRateLimit: true, onTimeout: true };
+    this.fallbacksUsed = 0;
+    this.history = [];
+  }
+
+  configure(models, config = {}) {
+    this.models = Array.isArray(models) ? models.filter(Boolean) : [];
+    this.currentIndex = 0;
+    this.fallbacksUsed = 0;
+    this.config = { ...this.config, ...config };
+    this.history = [];
+  }
+
+  get current() {
+    return this.models[this.currentIndex] || null;
+  }
+
+  get hasFallback() {
+    return this.currentIndex < this.models.length - 1;
+  }
+
+  get remaining() {
+    return Math.max(0, this.models.length - this.currentIndex - 1);
+  }
+
+  get list() {
+    return [...this.models];
+  }
+
+  recordError(model, error) {
+    this.history.push({ model, error: error.message || String(error), at: Date.now() });
+    if (this.hasFallback) {
+      this.currentIndex++;
+      this.fallbacksUsed++;
+      return { fallback: true, nextModel: this.current, from: model };
+    }
+    return { fallback: false, nextModel: null, from: model };
+  }
+
+  reset() {
+    this.currentIndex = 0;
+    this.fallbacksUsed = 0;
+  }
+}
+
+let _instance = null;
+function getFallbackChain() {
+  if (!_instance) _instance = new FallbackChain();
+  return _instance;
+}
+
+module.exports = { FallbackChain, getFallbackChain };