natureco-cli 5.63.0 → 5.64.0

package/src/tools/agentic-runner.js

@@ -15,6 +15,8 @@
  * bu modda KAPALIDIR (onay katmanini atlamamak icin).
  */
 const path = require('path');
+const { executeThroughGateway } = require('../utils/tool-execution-gateway');
+const { assessToolPath } = require('../utils/tool-path-policy');
 const os = require('os');
 
 // Agentic dongude izin verilen araclar. bash BURADA ama guvenli: bash.js kendi
@@ -64,21 +66,9 @@ function expandHome(p) {
 // Hassas dosya yolu koruması (safe modda). Coding-agent proje dosyalarina serbest erisir
 // ama kimlik/secret yollari prompt-injection ile suistimal edilebilir (SSH backdoor,
 // credential sizintisi). Full modda (sahibin opt-in'i) bypass edilir.
-const SENSITIVE_READ = [
-  /(^|[\\/])\.ssh[\\/]/i, /id_rsa|id_ed25519|id_ecdsa|id_dsa/i, /\.pem$|\.ppk$|\.key$/i,
-  /(^|[\\/])\.aws[\\/]/i, /gcloud[\\/].*(credential|token)/i, /(^|[\\/])\.npmrc$/i,
-  /(^|[\\/])\.git-credentials$/i, /\.natureco[\\/]config\.json$/i, /(^|[\\/])\.netrc$/i,
-];
-const SENSITIVE_WRITE = [
-  /(^|[\\/])\.ssh[\\/]/i,                 // authorized_keys/config yazma = backdoor
-  /^\/(etc|usr|bin|sbin|boot|sys)[\\/]/i, // mutlak sistem yollari
-  /(^|[\\/])etc[\\/](passwd|shadow|sudoers|hosts|crontab|ssh)/i, // goreceli traversal dahil (../../etc/shadow)
-  /System32[\\/]drivers[\\/]etc/i, /\.aws[\\/]credentials/i,
-];
 function sensitivePathBlocked(p, mode) {
-  const s = String(p || '');
-  const pats = mode === 'write' ? SENSITIVE_WRITE : SENSITIVE_READ;
-  return pats.some((re) => re.test(s));
+  const toolName = mode === 'write' ? 'write_file' : 'read_file';
+  return !assessToolPath(toolName, { path: p }).allowed;
 }
 
 // Ajanin urettigi komutlar icin ekstra koruma. bash.js kendi politikasini uygular
@@ -315,19 +305,34 @@ async function executeCall(call, opts = {}) {
   let files = call.args && call.args.files;
   if (typeof files === 'string') { try { files = JSON.parse(files); } catch { files = null; } }
   if (Array.isArray(files) && (/bulk/i.test(rawTool) || /file/i.test(rawTool) || norm === 'write_file')) {
+    // Bulk writes are still write_file operations. Apply the same allowlist and
+    // protected-path policy before loading or executing the tool; otherwise the
+    // early return below would bypass the normal checks later in this function.
+    if (!opts.execFull && !allowed.has('write_file')) {
+      records.push({ tool: rawTool, status: 'error', error: 'Guvenli modda write_file kapali' });
+      return { records, feedback: `${rawTool}: guvenli modda write_file izni yok.` };
+    }
     let wf;
     try { wf = loadTool('write_file'); } catch { wf = null; }
     for (const f of files) {
       if (!wf || !f || !f.path) { records.push({ tool: 'write_file', status: 'error', error: 'gecersiz dosya girisi' }); feedbacks.push('write_file HATA: gecersiz giris'); continue; }
-      try {
-        const res = await wf.execute({ path: expandHome(f.path), content: f.content != null ? String(f.content) : '' });
-        const ok = res && res.success !== false;
-        records.push({ tool: 'write_file', status: ok ? 'done' : 'error', args: { path: f.path }, result: res, error: ok ? undefined : (res && res.error) });
-        feedbacks.push(ok ? `write_file OK: ${res.path || f.path} (${res.size != null ? res.size : '?'} bytes)` : `write_file HATA: ${res && res.error}`);
-      } catch (e) {
-        records.push({ tool: 'write_file', status: 'error', args: { path: f.path }, error: e.message });
-        feedbacks.push(`write_file HATA: ${e.message}`);
+      const targetPath = expandHome(String(f.path).trim());
+      if (!opts.execFull && sensitivePathBlocked(targetPath, 'write')) {
+        records.push({ tool: 'write_file', status: 'error', args: { path: targetPath }, error: 'Hassas dosya yolu (guvenli modda engellendi)' });
+        feedbacks.push(`write_file: "${targetPath}" hassas bir yol oldugu icin CALISTIRILMADI.`);
+        continue;
       }
+      const res = await executeThroughGateway({
+        toolName: 'write_file',
+        args: { path: targetPath, content: f.content != null ? String(f.content) : '' },
+        resolveTool: () => wf,
+        normalizeSuccess: value => value,
+        normalizeError: error => ({ success: false, error }),
+        allowSensitivePaths: !!opts.execFull,
+      });
+      const ok = res && res.success !== false;
+      records.push({ tool: 'write_file', status: ok ? 'done' : 'error', args: { path: targetPath }, result: res, error: ok ? undefined : (res && res.error) });
+      feedbacks.push(ok ? `write_file OK: ${res.path || targetPath} (${res.size != null ? res.size : '?'} bytes)` : `write_file HATA: ${res && res.error}`);
     }
     return { records, feedback: feedbacks.join('\n') };
   }
@@ -384,17 +389,20 @@ async function executeCall(call, opts = {}) {
     records.push({ tool: norm, status: 'error', error: 'execute yok' });
     return { records, feedback: `${norm} HATA: execute fonksiyonu yok` };
   }
-  try {
-    const res = await fn(args);
-    const ok = typeof res === 'string' ? true : (res && res.success !== false);
-    const status = ok ? 'done' : 'error';
-    const feedback = buildFeedback(norm, res);
-    records.push({ tool: norm, status, args: sanitizeArgs(args), result: res });
-    return { records, feedback };
-  } catch (e) {
-    records.push({ tool: norm, status: 'error', args: sanitizeArgs(args), error: e.message });
-    return { records, feedback: `${norm} HATA: ${e.message}` };
-  }
+  const res = await executeThroughGateway({
+    toolName: norm,
+    args,
+    resolveTool: () => mod,
+    execute: fn,
+    normalizeSuccess: value => value,
+    normalizeError: error => ({ success: false, error }),
+    allowSensitivePaths: !!opts.execFull,
+  });
+  const ok = typeof res === 'string' ? true : (res && res.success !== false);
+  const status = ok ? 'done' : 'error';
+  const feedback = buildFeedback(norm, res);
+  records.push({ tool: norm, status, args: sanitizeArgs(args), result: res, error: ok ? undefined : res.error });
+  return { records, feedback };
 }
 
 /**

package/src/tools/memory_write.js

@@ -9,6 +9,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const { writeJsonAtomicSync, readJsonSafeSync } = require("../utils/atomic-file");
+const { createMemoryRecord, resolveConflict, factKey } = require("../utils/memory-record");
 
 const MEMORY_DIR = path.join(os.homedir(), ".natureco", "memory");
 
@@ -131,7 +132,7 @@ function verifyMemoryWrite(username, expectedFact, expectedBotName) {
 }
 
 
-function addMemory({ username, fact, score = 5, category = "general", botName, nickname, name }) {
+function addMemory({ username, fact, score = 5, category = "general", botName, nickname, name, source = "tool", confidence = 0.5, ttlMs, userConfirmed = false }) {
   // Username yoksa ve 'name' parametresi varsa, onu username olarak kullan
   // (hitap bicimi icin)
   const effectiveUsername = username || (name && name.toLowerCase()) || 'default';
@@ -149,18 +150,17 @@ function addMemory({ username, fact, score = 5, category = "general", botName, n
 
   if (fact) {
     // duplicate kontrol
-    const existing = memory.facts.find(f => (f.value || f).toLowerCase() === fact.toLowerCase());
+    const incoming = createMemoryRecord({ value: fact, score, category, source, confidence, ttlMs, userConfirmed, verified: true });
+    const key = factKey(fact, category);
+    const existing = memory.facts.find(f => factKey(f.value || f, f.category || category) === key);
     if (existing) {
-      existing.score = Math.min(10, (existing.score || 5) + 2);
-      existing.updatedAt = new Date().toISOString();
+      const sameValue = String(existing.value || existing).toLowerCase() === fact.toLowerCase();
+      const previousScore = existing.score || 5;
+      const resolved = resolveConflict(existing, incoming);
+      Object.assign(existing, resolved.winner);
+      if (sameValue) existing.score = Math.min(10, previousScore + 2);
     } else {
-      memory.facts.push({
-        value: fact,
-        score,
-        category,
-        updatedAt: new Date().toISOString(),
-        createdAt: new Date().toISOString(),
-      });
+      memory.facts.push(incoming);
     }
     // Limit'i ZIM push'tan sonra uygula → yeni eklenen fact düşürülmez.
     memory = enforceFactLimit(memory, { recentValue: fact });
@@ -236,6 +236,10 @@ module.exports = {
       fact: { type: "string", description: 'Yeni fact (ornek: "Kullanici kahve seviyor", "Istanbul\'da yasiyor")' },
       score: { type: "number", description: "Onem derecesi 1-10 (default 5)" },
       category: { type: "string", description: "Kategori: personal, preference, work, hobby, fact (default general)" },
+      source: { type: "string", description: "Bilginin kaynağı (user, tool, import, inference)" },
+      confidence: { type: "number", description: "Güven puanı 0-1" },
+      ttlMs: { type: "number", description: "İsteğe bağlı yaşam süresi (milisaniye)" },
+      userConfirmed: { type: "boolean", description: "Kullanıcı tarafından açıkça doğrulandı mı" },
       botName: { type: "string", description: "Bot adini degistir (memory.botName)" },
       nickname: { type: "string", description: "Kullanici nickname'i" },
       name: { type: "string", description: "Kullanici gercek adi" },
@@ -249,4 +253,4 @@ module.exports = {
     if (action === "show") return showMemory(params);
     return addMemory(params);
   },
-};
+};

package/src/tools/structural_patch.js

@@ -0,0 +1,25 @@
+const { StructuralPatchEngine } = require('../utils/structural-patch');
+const engine = new StructuralPatchEngine();
+
+module.exports = {
+  name: 'structural_patch',
+  description: 'Apply conflict-safe anchored text patches with preview and rollback support.',
+  inputSchema: {
+    type: 'object', required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ['preview', 'apply', 'rollback'] },
+      path: { type: 'string' }, expectedHash: { type: 'string' }, patchId: { type: 'string' }, dryRun: { type: 'boolean' },
+      operations: { type: 'array', items: { type: 'object', required: ['search'], properties: {
+        search: { type: 'string' }, replace: { type: 'string' }, replaceAll: { type: 'boolean' },
+      } } },
+    },
+  },
+  async execute(params) {
+    if (params.action === 'rollback') return engine.rollback(params.patchId);
+    if (!params.path) return { success: false, error: 'path is required' };
+    const result = params.action === 'preview'
+      ? engine.preview(params.path, params.operations, { expectedHash: params.expectedHash, dryRun: true })
+      : engine.apply(params.path, params.operations, { expectedHash: params.expectedHash, dryRun: params.dryRun });
+    return result.ok ? { success: true, ...result } : { success: false, ...result };
+  },
+};

package/src/tools/workflow.js

@@ -1,6 +1,7 @@
 const https = require('https');
 const fs = require('fs');
-const path = require('path');
+const path = require('path');
+const { executeThroughGateway } = require('../utils/tool-execution-gateway');
 const os = require('os');
 
 const WORKFLOW_DIR = path.join(os.homedir(), '.natureco', 'workflows');
@@ -517,7 +518,14 @@ async function workflow(params) {
           const toolMod = require(path.join(__dirname, '..', 'tools', step.tool + '.js'));
           const fn = toolMod.execute || (toolMod.default && toolMod.default.execute);
           if (!fn) { throw new Error(step.tool + ' toolunda execute fonksiyonu bulunamadi'); }
-          const toolResult = await fn(args);
+          const toolResult = await executeThroughGateway({
+            toolName: step.tool,
+            args,
+            resolveTool: () => toolMod,
+            execute: fn,
+            normalizeSuccess: value => value,
+            normalizeError: error => ({ success: false, error }),
+          });
           stepResults.push({ step: step.step, tool: step.tool, status: 'done', args, result: toolResult });
         } else if (msg.content) {
           stepResults.push({ step: step.step, tool: step.tool, status: 'done', note: 'Tool cagrilmadi, model dogrudan yanit verdi', content: msg.content.slice(0, 500) });

package/src/utils/agent-core.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { ToolGuardrails } = require('./tool-guardrails');
+const { standardToolResult } = require('./tool-result');
+
+class AgentCore {
+  constructor(options = {}) {
+    this.guardrails = options.guardrails || new ToolGuardrails({ hardStopEnabled: true });
+    this.maxIterations = options.maxIterations || 10;
+    this.iteration = 0;
+  }
+
+  startRequest() {
+    this.iteration = 0;
+    this.guardrails.reset();
+  }
+
+  startIteration() {
+    this.iteration++;
+    this.guardrails.startIteration();
+    return { iteration: this.iteration, maxIterations: this.maxIterations, allowed: this.iteration <= this.maxIterations };
+  }
+
+  parseToolCalls(toolCalls = []) {
+    return toolCalls.map((call, index) => {
+      const name = call.function?.name || call.name;
+      const raw = call.function?.arguments ?? call.input ?? call.args ?? {};
+      let input = raw;
+      let parseError = null;
+      if (typeof raw === 'string') {
+        try { input = JSON.parse(raw || '{}'); }
+        catch (error) { input = {}; parseError = error.message; }
+      }
+      return { id: call.id || `call_${this.iteration}_${index}`, name, input, parseError, original: call };
+    });
+  }
+
+  assess(call) {
+    if (!call?.name) return { blocked: true, reason: 'Araç adı eksik' };
+    if (call.parseError) return { blocked: true, reason: `Araç argümanları JSON değil: ${call.parseError}` };
+    return this.guardrails.check(call.name, call.input || {});
+  }
+
+  record(call, result) {
+    const standard = standardToolResult(result, { tool: call.name, iteration: this.iteration });
+    this.guardrails.record(call.name, call.input || {}, standard.ok);
+    return standard;
+  }
+}
+
+module.exports = { AgentCore };

package/src/utils/agent-workspace.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { Worktree } = require('./worktree');
+
+class AgentWorkspaceManager {
+  constructor(options = {}) { this.createWorktree = options.createWorktree || (() => new Worktree()); }
+
+  async run(agentId, task, options = {}) {
+    const worktree = this.createWorktree();
+    if (options.gitRepo !== undefined) worktree._mockGitRepo = options.gitRepo;
+    const entered = worktree.enter({ id: `agent-${agentId}` });
+    if (entered.error) throw new Error(entered.error);
+    try {
+      const result = await task({ id: agentId, cwd: entered.worktreeDir, worktree });
+      const exited = worktree.exit({ merge: options.merge === true });
+      return { ok: true, result, workspace: entered.worktreeDir, merged: !!exited.merged };
+    } catch (error) {
+      try { worktree.exit({ merge: false }); } catch {}
+      return { ok: false, error: error.message, workspace: entered.worktreeDir, merged: false };
+    }
+  }
+}
+
+module.exports = { AgentWorkspaceManager };

package/src/utils/api.js

@@ -9,9 +9,8 @@ const { getConfig } = require('./config');
 const { getToolDefinitions, executeToolCalls } = require('./tool-runner');
 const { MCPClient } = require('./mcp-client');
 const TB = require('./token-budget');
-const { accumulateToolCallDeltas } = require('./streaming-tools');
-const { ToolGuardrails } = require('./tool-guardrails');
-const guardrails = new ToolGuardrails();
+const { accumulateToolCallDeltas } = require('./streaming-tools');
+const { AgentCore } = require('./agent-core');
 
 /**
  * v5.5.0: Provider-specific format detection
@@ -671,7 +670,12 @@ async function sendMessageAnthropic(providerConfig, messages, tools) {
 /**
  * Send message with tool support (universal)
  */
-async function sendMessageToProvider(apiKey, message, conversationId = null, systemPrompt = null, options = {}) {
+async function sendMessageToProvider(apiKey, message, conversationId = null, systemPrompt = null, options = {}) {
+  // Per-request state prevents concurrent conversations from contaminating one
+  // another while preserving failure/no-progress counters across tool rounds.
+  const agentCore = new AgentCore({ maxIterations: 10 });
+  agentCore.startRequest();
+  const guardrails = agentCore.guardrails;
   const providerConfig = getProviderConfig();
   
   if (!providerConfig) {
@@ -784,8 +788,7 @@ async function sendMessageToProvider(apiKey, message, conversationId = null, sys
       const localCalls = toolCalls.filter(tc => !mcpTools.find(t => t.name === tc.name));
 
       // Guardrails: filter blocked tools
-      guardrails.reset();
-      guardrails.startIteration();
+      agentCore.startIteration();
       const blockedMcp = mcpCalls.filter(tc => {
         const check = guardrails.check(tc.name, tc.input);
         return check.blocked;
@@ -803,8 +806,9 @@ async function sendMessageToProvider(apiKey, message, conversationId = null, sys
           localCalls.filter(tc => !blockedLocal.includes(tc)),
           { toolDefinitions: getToolDefinitions() }
         );
-        for (const r of localResults) {
-          guardrails.record(r.name, {}, r.result?.success !== false);
+        for (const r of localResults) {
+          const original = localCalls.find(tc => tc.id === r.id);
+          guardrails.record(r.name, original?.input || {}, r.result?.success !== false && !r.result?.error);
         }
       }
 

package/src/utils/channel-sdk.js

@@ -0,0 +1,212 @@
+'use strict';
+
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+
+function deliveryId(channel, target, payload, explicitKey) {
+  if (explicitKey) return String(explicitKey);
+  return crypto.createHash('sha256').update(`${channel}\0${target}\0${JSON.stringify(payload)}`).digest('hex').slice(0, 24);
+}
+
+class ChannelAdapter extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    if (!options.name) throw new Error('channel adapter name is required');
+    this.name = options.name;
+    this.connectFn = options.connect;
+    this.disconnectFn = options.disconnect;
+    this.sendFn = options.send;
+    this.healthFn = options.health;
+    this.state = 'disconnected';
+    this.lastError = null;
+    this.connectedAt = null;
+  }
+
+  async connect() {
+    if (this.state === 'connected') return { ok: true, reused: true };
+    this.state = 'connecting';
+    try {
+      if (this.connectFn) await this.connectFn();
+      this.state = 'connected'; this.connectedAt = new Date().toISOString(); this.lastError = null;
+      this.emit('state', this.state);
+      return { ok: true };
+    } catch (error) {
+      this.state = 'degraded'; this.lastError = error.message; this.emit('state', this.state);
+      return { ok: false, error: error.message };
+    }
+  }
+
+  async disconnect() {
+    try { if (this.disconnectFn) await this.disconnectFn(); } finally { this.state = 'disconnected'; this.emit('state', this.state); }
+  }
+
+  async send(delivery) {
+    if (typeof this.sendFn !== 'function') throw new Error(`channel ${this.name} cannot send`);
+    if (this.state !== 'connected') {
+      const connected = await this.connect();
+      if (!connected.ok) throw new Error(connected.error);
+    }
+    return this.sendFn(delivery);
+  }
+
+  async health() {
+    try {
+      const detail = this.healthFn ? await this.healthFn() : { ok: this.state === 'connected' };
+      return { channel: this.name, state: this.state, connectedAt: this.connectedAt, lastError: this.lastError, ...detail };
+    } catch (error) { return { channel: this.name, state: 'degraded', ok: false, error: error.message }; }
+  }
+}
+
+class ChannelDeliveryManager extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.adapters = new Map();
+    this.queue = [];
+    this.completed = new Map();
+    this.inFlight = new Map();
+    this.maxAttempts = options.maxAttempts || 4;
+    this.baseDelayMs = options.baseDelayMs ?? 250;
+    this.maxCompleted = options.maxCompleted || 10000;
+    this.sleep = options.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    this.store = options.store || null;
+    this.deadLetters = [];
+    this.metrics = { enqueued: 0, delivered: 0, failed: 0, retried: 0, deduplicated: 0, byChannel: {} };
+    if (this.store) {
+      const persisted = this.store.load();
+      this.queue = persisted.queue || [];
+      this.deadLetters = persisted.deadLetters || [];
+    }
+  }
+
+  register(adapter) { if (!(adapter instanceof ChannelAdapter)) throw new Error('ChannelAdapter required'); this.adapters.set(adapter.name, adapter); return adapter; }
+
+  enqueue(channel, target, payload, options = {}) {
+    const id = deliveryId(channel, target, payload, options.idempotencyKey);
+    if (this.completed.has(id) || this.inFlight.has(id) || this.queue.some(item => item.id === id)) {
+      this.metrics.deduplicated++; return { ok: true, id, duplicate: true };
+    }
+    const item = { id, channel, target, payload, attempt: 0, createdAt: new Date().toISOString(), metadata: options.metadata || {} };
+    this.queue.push(item); this.metrics.enqueued++; this._channel(channel).enqueued++;
+    this._persist();
+    this.emit('queued', item);
+    return { ok: true, id, duplicate: false };
+  }
+
+  async drain() {
+    const results = [];
+    while (this.queue.length) {
+      const item = this.queue.shift();
+      this._persist();
+      results.push(await this._deliver(item));
+    }
+    return results;
+  }
+
+  async _deliver(item) {
+    const adapter = this.adapters.get(item.channel);
+    if (!adapter) return this._failure(item, `channel adapter not registered: ${item.channel}`);
+    this.inFlight.set(item.id, item);
+    while (item.attempt < this.maxAttempts) {
+      item.attempt++;
+      try {
+        const result = await adapter.send(item);
+        const record = { ok: true, id: item.id, attempts: item.attempt, result, deliveredAt: new Date().toISOString() };
+        this.inFlight.delete(item.id); this.completed.set(item.id, record);
+        while (this.completed.size > this.maxCompleted) this.completed.delete(this.completed.keys().next().value);
+        this.metrics.delivered++; this._channel(item.channel).delivered++; this.emit('delivered', record);
+        this._persist();
+        return record;
+      } catch (error) {
+        item.lastError = error.message;
+        if (item.attempt < this.maxAttempts) {
+          this.metrics.retried++; this._channel(item.channel).retried++;
+          await this.sleep(Math.min(this.baseDelayMs * (2 ** (item.attempt - 1)), 30000));
+        }
+      }
+    }
+    this.inFlight.delete(item.id);
+    return this._failure(item, item.lastError || 'delivery failed');
+  }
+
+  _failure(item, error) {
+    const record = { ok: false, id: item.id, attempts: item.attempt, error };
+    this.deadLetters.push({ ...item, failedAt: new Date().toISOString(), error });
+    if (this.deadLetters.length > 10000) this.deadLetters.shift();
+    this.metrics.failed++; this._channel(item.channel).failed++; this.emit('failed', record); this._persist(); return record;
+  }
+
+  _channel(name) {
+    if (!this.metrics.byChannel[name]) this.metrics.byChannel[name] = { enqueued: 0, delivered: 0, failed: 0, retried: 0 };
+    return this.metrics.byChannel[name];
+  }
+
+  snapshotMetrics() { return JSON.parse(JSON.stringify({ ...this.metrics, queueDepth: this.queue.length, inFlight: this.inFlight.size })); }
+  async health() { return Promise.all([...this.adapters.values()].map(adapter => adapter.health())); }
+  _persist() { if (this.store) this.store.save({ queue: this.queue, deadLetters: this.deadLetters }); }
+  requeueDeadLetter(id) {
+    const index = this.deadLetters.findIndex(item => item.id === id);
+    if (index === -1) return { ok: false, error: 'dead letter not found' };
+    const [item] = this.deadLetters.splice(index, 1);
+    item.attempt = 0; delete item.error; delete item.failedAt;
+    this.queue.push(item); this._persist();
+    return { ok: true, id };
+  }
+}
+
+class ReconnectSupervisor extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.baseDelayMs = options.baseDelayMs ?? 1000;
+    this.maxDelayMs = options.maxDelayMs ?? 60000;
+    this.maxAttempts = options.maxAttempts ?? Infinity;
+    this.jitter = options.jitter ?? 0.2;
+    this.sleep = options.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    this.random = options.random || Math.random;
+    this.jobs = new Map();
+    this.metrics = { attempts: 0, reconnected: 0, exhausted: 0, cancelled: 0 };
+  }
+
+  reconnect(adapter) {
+    if (!(adapter instanceof ChannelAdapter)) return Promise.reject(new Error('ChannelAdapter required'));
+    if (this.jobs.has(adapter.name)) return this.jobs.get(adapter.name).promise;
+    const job = { cancelled: false, attempt: 0, promise: null };
+    job.promise = this._run(adapter, job).finally(() => this.jobs.delete(adapter.name));
+    this.jobs.set(adapter.name, job);
+    return job.promise;
+  }
+
+  cancel(name) {
+    const job = this.jobs.get(name);
+    if (!job) return false;
+    job.cancelled = true; this.metrics.cancelled++; this.emit('cancelled', { channel: name }); return true;
+  }
+
+  async _run(adapter, job) {
+    while (!job.cancelled && job.attempt < this.maxAttempts) {
+      job.attempt++; this.metrics.attempts++;
+      if (job.attempt > 1) await this.sleep(this._delay(job.attempt - 1));
+      if (job.cancelled) break;
+      const result = await adapter.connect();
+      this.emit('attempt', { channel: adapter.name, attempt: job.attempt, result });
+      if (result.ok) {
+        this.metrics.reconnected++; this.emit('reconnected', { channel: adapter.name, attempts: job.attempt });
+        return { ok: true, channel: adapter.name, attempts: job.attempt };
+      }
+      // connect() leaves degraded state; reset so the next attempt calls connectFn.
+      adapter.state = 'disconnected';
+    }
+    if (job.cancelled) return { ok: false, channel: adapter.name, stopped: 'cancelled', attempts: job.attempt };
+    this.metrics.exhausted++; this.emit('exhausted', { channel: adapter.name, attempts: job.attempt });
+    return { ok: false, channel: adapter.name, stopped: 'exhausted', attempts: job.attempt };
+  }
+
+  _delay(attempt) {
+    const raw = Math.min(this.baseDelayMs * (2 ** Math.max(0, attempt - 1)), this.maxDelayMs);
+    const spread = raw * this.jitter;
+    return Math.max(0, Math.round(raw - spread + this.random() * spread * 2));
+  }
+
+  snapshotMetrics() { return { ...this.metrics, active: this.jobs.size }; }
+}
+
+module.exports = { ChannelAdapter, ChannelDeliveryManager, ReconnectSupervisor, deliveryId };

package/src/utils/code-intelligence.js

@@ -0,0 +1,69 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CODE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java']);
+const DEFINITION_PATTERNS = [
+  /\b(?:function|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/g,
+  /^\s*def\s+([A-Za-z_]\w*)/gm,
+  /^\s*(?:func|type)\s+([A-Za-z_]\w*)/gm,
+];
+
+function walkCodeFiles(root, limit = 5000) {
+  const files = [];
+  const ignored = new Set(['node_modules', '.git', '.natureco', 'dist', 'build', 'coverage']);
+  function walk(dir) {
+    if (files.length >= limit) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (ignored.has(entry.name)) continue;
+      const target = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(target);
+      else if (entry.isFile() && CODE_EXTENSIONS.has(path.extname(entry.name))) files.push(target);
+    }
+  }
+  walk(path.resolve(root));
+  return files;
+}
+
+class CodeIntelligence {
+  constructor(root = process.cwd()) { this.root = path.resolve(root); this.files = []; this.definitions = new Map(); }
+
+  index() {
+    this.files = walkCodeFiles(this.root);
+    this.definitions.clear();
+    for (const file of this.files) {
+      const text = fs.readFileSync(file, 'utf8');
+      for (const pattern of DEFINITION_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text))) {
+          const line = text.slice(0, match.index).split('\n').length;
+          const item = { symbol: match[1], file, line };
+          if (!this.definitions.has(match[1])) this.definitions.set(match[1], []);
+          this.definitions.get(match[1]).push(item);
+        }
+      }
+    }
+    return { files: this.files.length, symbols: this.definitions.size };
+  }
+
+  findDefinitions(symbol) { return this.definitions.get(symbol) || []; }
+
+  findReferences(symbol, limit = 200) {
+    if (!symbol || !/^[A-Za-z_$][\w$]*$/.test(symbol)) return [];
+    const regex = new RegExp(`\\b${symbol.replace(/[$]/g, '\\$&')}\\b`, 'g');
+    const results = [];
+    for (const file of this.files) {
+      const lines = fs.readFileSync(file, 'utf8').split('\n');
+      lines.forEach((text, index) => {
+        regex.lastIndex = 0;
+        if (regex.test(text)) results.push({ symbol, file, line: index + 1, text: text.trim().slice(0, 240) });
+      });
+      if (results.length >= limit) break;
+    }
+    return results.slice(0, limit);
+  }
+}
+
+module.exports = { CodeIntelligence, walkCodeFiles };