mindforge-cc 11.4.0 → 11.5.1

package/bin/learning/lib/ssrf-guard.js

@@ -0,0 +1,252 @@
+'use strict';
+
+/**
+ * MindForge — SSRF + path-traversal + id-validation guards for instinct import.
+ *
+ * Ported from ECC's instinct-cli.py (_validate_import_url / _fetch_import_url /
+ * _validate_file_path / _validate_instinct_id). Node has no stdlib IP
+ * classification (Python used `ipaddress`), so isPublicAddress is hand-written
+ * to cover IPv4 + IPv6 private/loopback/link-local/multicast/reserved/
+ * unspecified, INCLUDING IPv4-mapped IPv6 (::ffff:x) and IPv6 ULA/link-local.
+ *
+ * Layer-3 hardening OVER the donor: 3xx redirects are REJECTED (the donor's
+ * urlopen followed them, so an allowed host could 302 to a private one).
+ */
+
+const dns = require('dns').promises;
+const https = require('https');
+const net = require('net');
+const path = require('path');
+const fs = require('fs');
+
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024; // 2 MB
+const DEFAULT_TIMEOUT_MS = 15000;
+
+// A remote instinct import is plain HTTPS, so only the standard HTTPS port is
+// meaningful. Allowing an explicit non-standard port would let an allowed
+// public host be used to reach an internal service co-located on it
+// (e.g. https://public-host:6379/) — the destination port is otherwise carried
+// through unchecked. An empty port means the URL uses the https default (443).
+const ALLOWED_IMPORT_PORTS = new Set(['', '443']);
+
+// System dirs an import/export path must never target (port of the py list;
+// macOS resolves /etc -> /private/etc, so both forms are blocked).
+const BLOCKED_PREFIXES = [
+  '/etc', '/usr', '/bin', '/sbin', '/proc', '/sys',
+  '/var/log', '/var/run', '/var/lib', '/var/spool',
+  '/private/etc', '/private/var/log', '/private/var/run', '/private/var/db',
+];
+
+/**
+ * True if `ip` is a public, routable address (NOT private/loopback/link-local/
+ * multicast/reserved/unspecified). Handles IPv4, IPv6, and IPv4-mapped IPv6.
+ */
+function isPublicAddress(ip) {
+  const v = net.isIP(ip);
+  if (v === 4) return isPublicV4(ip);
+  if (v === 6) {
+    // Unwrap IPv4-mapped IPv6 (::ffff:127.0.0.1) and classify the V4 part.
+    const mapped = ip.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mapped) return isPublicV4(mapped[1]);
+    return isPublicV6(ip);
+  }
+  return false; // not a valid IP literal → treat as non-public (fail closed)
+}
+
+function isPublicV4(ip) {
+  const o = ip.split('.').map(Number);
+  if (o.length !== 4 || o.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return false;
+  const [a, b] = o;
+  if (a === 10) return false;                          // 10/8 private
+  if (a === 172 && b >= 16 && b <= 31) return false;   // 172.16/12 private
+  if (a === 192 && b === 168) return false;            // 192.168/16 private
+  if (a === 127) return false;                         // 127/8 loopback
+  if (a === 169 && b === 254) return false;            // 169.254/16 link-local
+  if (a === 0) return false;                           // 0.0.0.0/8 unspecified/reserved
+  if (a >= 224) return false;                          // 224/4 multicast + 240/4 reserved
+  if (a === 100 && b >= 64 && b <= 127) return false;  // 100.64/10 CGNAT (treat as non-public)
+  return true;
+}
+
+function isPublicV6(ip) {
+  const lower = ip.toLowerCase();
+  if (lower === '::1') return false;                   // loopback
+  if (lower === '::') return false;                    // unspecified
+  // Classify by the FIRST 16-bit hextet as a NUMBER, not a string prefix.
+  // String prefixes silently miss sub-ranges: e.g. fe80::/10 spans fe80-febf,
+  // and `startsWith('fe9'|'fea'|'feb')` left fe81-fe8f (fe8x) reachable as
+  // "public" — an SSRF hole. Numeric masks check the actual bit ranges.
+  const firstHextet = lower.startsWith('::') ? 0 : parseInt(lower.split(':')[0] || '0', 16);
+  if (Number.isNaN(firstHextet)) return false;         // unparseable → fail closed
+  if ((firstHextet & 0xffc0) === 0xfe80) return false; // fe80::/10 link-local (fe80-febf)
+  if ((firstHextet & 0xffc0) === 0xfec0) return false; // fec0::/10 site-local (deprecated, non-routable)
+  if ((firstHextet & 0xfe00) === 0xfc00) return false; // fc00::/7  unique-local (fc00-fdff)
+  if ((firstHextet & 0xff00) === 0xff00) return false; // ff00::/8  multicast
+  return true;
+}
+
+/**
+ * Validate a remote import URL: https only, resolvable hostname, and EVERY
+ * resolved address must be public. Returns the normalized URL string.
+ */
+async function validateImportUrl(source) {
+  let parsed;
+  try {
+    parsed = new URL(source);
+  } catch {
+    throw new Error('invalid import URL');
+  }
+  if (parsed.protocol !== 'https:') {
+    throw new Error('remote instinct imports require https URLs');
+  }
+  if (!parsed.hostname) {
+    throw new Error('remote import URL is missing a hostname');
+  }
+  // Port allowlist: only the standard HTTPS port (or none) is permitted. This
+  // blocks using an allowed public host to reach an internal service port
+  // (6379/27017/8080/...) without maintaining a per-service blocklist.
+  if (!ALLOWED_IMPORT_PORTS.has(parsed.port)) {
+    throw new Error(`remote import port not allowed: ${parsed.port} (only the standard https port is permitted)`);
+  }
+
+  let addrs;
+  try {
+    addrs = await dns.lookup(parsed.hostname, { all: true });
+  } catch {
+    throw new Error(`remote import host could not be resolved: ${parsed.hostname}`);
+  }
+  if (!addrs.length) {
+    throw new Error(`remote import host could not be resolved: ${parsed.hostname}`);
+  }
+  for (const { address } of addrs) {
+    if (!isPublicAddress(address)) {
+      throw new Error(`remote import host resolves to a non-public address: ${address}`);
+    }
+  }
+  return parsed.toString();
+}
+
+/**
+ * Fetch a validated remote instinct file with bounded size + timeout, an allowed
+ * Content-Type, and NO redirect following (3xx is rejected). Resolves the body.
+ */
+async function fetchImportUrl(source, opts = {}) {
+  const maxBytes = opts.maxBytes || DEFAULT_MAX_BYTES;
+  const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+  const url = await validateImportUrl(source);
+
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers: { 'User-Agent': 'MindForge-instinct-import/1' } }, res => {
+      const status = res.statusCode || 0;
+      if (status >= 300 && status < 400) {
+        res.destroy();
+        return reject(new Error(`remote import returned a ${status} redirect — refusing to follow (SSRF guard)`));
+      }
+      if (status !== 200) {
+        res.destroy();
+        return reject(new Error(`remote import failed with status ${status}`));
+      }
+      const ctype = (res.headers['content-type'] || '').toLowerCase();
+      const allowed = ['text/', 'markdown', 'yaml', 'json', 'octet-stream'];
+      if (ctype && !allowed.some(a => ctype.includes(a))) {
+        res.destroy();
+        return reject(new Error(`unsupported remote content type: ${ctype}`));
+      }
+      let bytes = 0;
+      const chunks = [];
+      res.on('data', chunk => {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          res.destroy();
+          return reject(new Error(`remote import exceeds ${maxBytes} bytes`));
+        }
+        chunks.push(chunk);
+      });
+      res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error(`remote import timed out after ${timeoutMs}ms`));
+    });
+    req.on('error', err => reject(new Error(`remote import failed: ${err.message}`)));
+  });
+}
+
+/**
+ * Resolve + validate a filesystem path, blocking system dirs (both import-from
+ * and export-to). Returns the resolved absolute path.
+ */
+function validateFilePath(pathStr, { mustExist = false } = {}) {
+  if (typeof pathStr !== 'string' || !pathStr) {
+    throw new Error('path must be a non-empty string');
+  }
+  // expanduser
+  const expanded = pathStr.startsWith('~')
+    ? path.join(require('os').homedir(), pathStr.slice(1))
+    : pathStr;
+  const lexical = path.resolve(expanded);
+
+  // Canonicalize BEFORE the system-dir check. path.resolve() only normalizes
+  // lexically — it does NOT follow symlinks — so a symlink planted in a writable
+  // dir (e.g. /tmp/x -> /etc) would pass the prefix check while the subsequent
+  // fs.read/writeFileSync followed the link into a blocked dir. Resolve the real
+  // path so the check sees the actual on-disk target. Export targets may not
+  // exist yet, so fall back to realpath-ing the deepest existing ancestor and
+  // re-joining the not-yet-created tail (a symlinked ancestor is still caught).
+  const resolved = canonicalize(lexical);
+
+  for (const prefix of BLOCKED_PREFIXES) {
+    if (resolved === prefix || resolved.startsWith(prefix + path.sep)) {
+      throw new Error(`path '${resolved}' targets a system directory`);
+    }
+  }
+  if (mustExist && !fs.existsSync(resolved)) {
+    throw new Error(`path does not exist: ${resolved}`);
+  }
+  return resolved;
+}
+
+/**
+ * Resolve symlinks in an absolute path, tolerating a not-yet-created tail.
+ * Walks up to the deepest existing ancestor, realpath()s THAT (catching a
+ * symlinked parent), then re-appends the non-existent remainder.
+ */
+function canonicalize(absPath) {
+  let existing = absPath;
+  const tail = [];
+  // Find the deepest ancestor that exists on disk.
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) break; // reached filesystem root
+    tail.unshift(path.basename(existing));
+    existing = parent;
+  }
+  try {
+    const realExisting = fs.realpathSync(existing);
+    return tail.length ? path.join(realExisting, ...tail) : realExisting;
+  } catch {
+    return absPath; // realpath failed (race/permission) → fall back, fail closed downstream
+  }
+}
+
+/**
+ * Validate an instinct id before using it anywhere id-sensitive.
+ */
+function validateInstinctId(id) {
+  if (typeof id !== 'string' || !id || id.length > 128) return false;
+  if (id.includes('/') || id.includes('\\')) return false;
+  if (id.includes('..')) return false;
+  if (id.startsWith('.')) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id);
+}
+
+module.exports = {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_TIMEOUT_MS,
+  BLOCKED_PREFIXES,
+  isPublicAddress,
+  validateImportUrl,
+  fetchImportUrl,
+  validateFilePath,
+  validateInstinctId,
+};

package/bin/memory/eis-client.js

@@ -150,20 +150,41 @@ class EISClient {
   }
 
   /**
-   * [HARDEN] Generates a cryptographically signed auth header using the agent's DID.
-   * This attaches OUTBOUND provenance to locally-originated requests (it signs
-   * what this node sends). It does NOT verify the provenance of inbound remote
-   * entries — that is verifyRemoteProvenance's job, which fails closed unless a
-   * signature is cryptographically verified against a resolvable public key.
+   * Lazily registers (once) this client's outbound node identity in the ZTAI
+   * trust registry and returns its DID. ZTAI is a SINGLETON instance (exported
+   * as `new ZTAIManager()`), so we call it directly — never `new ZTAI()`. The
+   * DID is cached so every header from this client shares one resolvable key.
+   */
+  async _getNodeDid() {
+    if (!this._nodeDid) {
+      // Tier 3: the enclave provider signs with real Ed25519 (see ztai-manager).
+      this._nodeDid = await ZTAI.registerAgent(`eis-client:${this.orgId}`, 3);
+    }
+    return this._nodeDid;
+  }
+
+  /**
+   * [HARDEN] Generates a cryptographically signed auth header using this node's
+   * DID. Attaches OUTBOUND provenance to locally-originated requests (it signs
+   * what this node sends). It does NOT verify inbound remote entries — that is
+   * verifyRemoteProvenance's job, which fails closed unless a signature is
+   * cryptographically verified against a resolvable public key.
+   *
+   * FAIL-CLOSED: uses the real ZTAI API (registerAgent -> signData) and asserts
+   * the produced signature is a non-empty string. A signing failure THROWS
+   * rather than shipping a malformed `ZTAI-v5 <did>:` header with an empty sig.
    */
   async getAuthHeader(action, resource) {
-    const manager = new ZTAI();
-    const identity = manager.getIdentity();
+    const did = await this._getNodeDid();
     const payload = `${this.orgId}:${action}:${resource}:${Date.now()}`;
-    const signature = manager.sign(payload);
-    
+    const signature = await ZTAI.signData(did, payload);
+
+    if (typeof signature !== 'string' || signature.length === 0) {
+      throw new Error('EIS auth header signing failed: ZTAI produced an empty signature');
+    }
+
     return {
-      'Authorization': `ZTAI-v5 ${identity.did}:${signature}`,
+      'Authorization': `ZTAI-v5 ${did}:${signature}`,
       'X-MF-Org': this.orgId,
       'X-MF-Timestamp': Date.now().toString()
     };

package/bin/memory/federated-sync.js

@@ -58,7 +58,11 @@ class FederatedSync {
     const statsPath = path.join(this.localStore.getPaths().MEMORY_DIR, 'sync-stats.json');
     let stats = { failures: 0 };
     if (fs.existsSync(statsPath)) {
-      stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'));
+      try {
+        stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'));
+      } catch {
+        stats = { failures: 0 };
+      }
     }
     stats.failures = (stats.failures || 0) + 1;
     stats.last_error = err.message;
@@ -122,7 +126,12 @@ class FederatedSync {
   resetFailures() {
     const statsPath = path.join(this.localStore.getPaths().MEMORY_DIR, 'sync-stats.json');
     if (fs.existsSync(statsPath)) {
-      const stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'));
+      let stats = { failures: 0 };
+      try {
+        stats = JSON.parse(fs.readFileSync(statsPath, 'utf8'));
+      } catch {
+        stats = { failures: 0 };
+      }
       stats.failures = 0;
       fs.writeFileSync(statsPath, JSON.stringify(stats, null, 2));
     }

package/bin/memory/knowledge-capture.js

@@ -238,7 +238,16 @@ function captureFromPhaseCompletion(phaseNum) {
 function captureFromCompaction(handoffPath) {
   if (!fs.existsSync(handoffPath)) return [];
 
-  const handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+  let handoff;
+  try {
+    handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+  } catch (err) {
+    // Malformed handoff.json must not crash the capture pipeline — mirror the
+    // missing-file path and return [] after logging the parse failure.
+    console.error(`[knowledge-capture] Failed to parse handoff file ${handoffPath}: ${err.message}`);
+    return [];
+  }
+
   const items   = handoff.implicit_knowledge || [];
   const project = getProjectName();
   const captured = [];

package/bin/memory/pillar-health-tracker.js

@@ -18,7 +18,15 @@ class PillarHealthTracker {
     if (!fs.existsSync(auditPath)) return null;
 
     const lines = fs.readFileSync(auditPath, 'utf8').trim().split('\n');
-    const events = lines.map(l => JSON.parse(l));
+    const events = lines
+      .map(l => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null; // Skip malformed lines rather than crashing the pipeline.
+        }
+      })
+      .filter(Boolean);
 
     // 1. RSA (Mission Fidelity) Analysis
     const rsaEvents = events.filter(e => e.type === 'mission_fidelity' || e.event === 'scs_homing_injected');

package/bin/models/llm-errors.js

@@ -0,0 +1,79 @@
+/**
+ * MindForge — Typed cross-provider LLM error taxonomy.
+ *
+ * Adapted from ECC (src/llm/core/interface.py LLMError hierarchy). Named error
+ * classes carrying { provider, code, retryable } so the model-client fallback /
+ * circuit breaker can branch on error TYPE instead of a raw count:
+ *   - ContextLengthError -> escalate to a larger-context model
+ *   - AuthenticationError -> skip this provider permanently (bad/missing key)
+ *   - RateLimitError      -> circuit-break + back off, retryable
+ *   - ModelNotFoundError  -> skip the model, try fallback
+ *
+ * mapHttpStatus() turns a provider HTTP status into the right typed error so all
+ * providers classify failures consistently.
+ */
+'use strict';
+
+class LLMError extends Error {
+  constructor(message, { provider = null, code = null, retryable = false, status = null } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.provider = provider;
+    this.code = code;
+    this.retryable = retryable;
+    this.status = status;
+  }
+}
+
+class AuthenticationError extends LLMError {
+  constructor(message, opts = {}) { super(message, { ...opts, retryable: false }); }
+}
+class RateLimitError extends LLMError {
+  constructor(message, opts = {}) { super(message, { ...opts, retryable: true }); }
+}
+class ContextLengthError extends LLMError {
+  constructor(message, opts = {}) { super(message, { ...opts, retryable: false }); }
+}
+class ModelNotFoundError extends LLMError {
+  constructor(message, opts = {}) { super(message, { ...opts, retryable: false }); }
+}
+class ServiceUnavailableError extends LLMError {
+  constructor(message, opts = {}) { super(message, { ...opts, retryable: true }); }
+}
+
+/**
+ * Classify a provider failure into a typed error. Prefers HTTP status, then
+ * falls back to string heuristics on the message (ECC astraflow.py approach) for
+ * providers that don't surface a clean status.
+ */
+function classifyError(message, { provider = null, status = null } = {}) {
+  const msg = String(message || '');
+  const lower = msg.toLowerCase();
+
+  if (status === 401 || status === 403 || /\b401\b|\b403\b|unauthorized|invalid api key|authentication/.test(lower)) {
+    return new AuthenticationError(msg, { provider, code: 'auth', status });
+  }
+  if (status === 429 || /\b429\b|rate.?limit|too many requests/.test(lower)) {
+    return new RateLimitError(msg, { provider, code: 'rate_limit', status });
+  }
+  if (status === 404 || /\b404\b|model.*not.*found|no such model/.test(lower)) {
+    return new ModelNotFoundError(msg, { provider, code: 'model_not_found', status });
+  }
+  if (/context.*length|maximum context|context window|too long|token limit/.test(lower)) {
+    return new ContextLengthError(msg, { provider, code: 'context_length', status });
+  }
+  if (status === 503 || status === 502 || status === 408 || /\b50[23]\b|timeout|unavailable|connection/.test(lower)) {
+    return new ServiceUnavailableError(msg, { provider, code: 'unavailable', status });
+  }
+  return new LLMError(msg, { provider, code: 'unknown', status, retryable: false });
+}
+
+module.exports = {
+  LLMError,
+  AuthenticationError,
+  RateLimitError,
+  ContextLengthError,
+  ModelNotFoundError,
+  ServiceUnavailableError,
+  classifyError,
+};

package/bin/models/model-client.js

@@ -9,11 +9,17 @@ const CostTracker = require('./cost-tracker');
 const AnthropicProvider = require('./anthropic-provider');
 const OpenAIProvider = require('./openai-provider');
 const GeminiProvider = require('./gemini-provider');
-
-// v9: Fallback chains aligned to Claude 4.x family
+const OllamaProvider = require('./ollama-provider');
+const { resolveProvider } = require('./provider-registry');
+const { LLMError } = require('./llm-errors');
+
+// v9: Fallback chains aligned to Claude 4.x family.
+// llama-3-70b-local is the sovereign last-resort — only reachable when
+// OLLAMA_BASE_URL is set (see _getProvider); otherwise _getProvider returns
+// null and the chain skips it, leaving cloud routing unchanged.
 const FALLBACK_CHAINS = {
   'claude-opus-4-7': ['claude-sonnet-4-6', 'gemini-2.5-pro'],
-  'claude-sonnet-4-6': ['claude-haiku-4-5', 'gemini-2.5-pro'],
+  'claude-sonnet-4-6': ['claude-haiku-4-5', 'gemini-2.5-pro', 'llama-3-70b-local'],
   'gemini-2.5-pro': ['claude-sonnet-4-6'],
 };
 
@@ -72,10 +78,27 @@ class ModelClient {
 
       } catch (err) {
         const safeMsg = (err.message || '').replace(/sk-[a-zA-Z0-9_-]+/g, 'sk-***').replace(/key-[a-zA-Z0-9_-]+/g, 'key-***');
-        process.stderr.write(`[model-client] ${currentModel} failed: ${safeMsg}\n`);
+        process.stderr.write(`[model-client] ${currentModel} failed (${err.name || 'Error'}/${err.code || 'unknown'}): ${safeMsg}\n`);
+
+        // Context-aware fallback: branch on the typed-error taxonomy instead of
+        // blindly trying the next model.
+        //  - ContextLengthError: this model's window is too small — keep trying
+        //    the chain (later entries may have larger context); don't abort.
+        //  - AuthenticationError: the provider's key is bad/missing — trying it
+        //    again is pointless, but other providers in the chain may work, so
+        //    continue to the next attempt.
+        //  - Otherwise: continue through the chain as before.
+        const isTyped = err instanceof LLMError;
+        const isAuth = isTyped && err.name === 'AuthenticationError';
+        if (isAuth) {
+          process.stderr.write(`[model-client] ${currentModel}: auth failure — skipping this provider for the rest of this call\n`);
+        }
+
         if (attempts.indexOf(currentModel) === attempts.length - 1) {
           const safeErr = new Error(safeMsg);
           safeErr.code = err.code;
+          safeErr.name = err.name;
+          safeErr.retryable = isTyped ? err.retryable : undefined;
           throw safeErr;
         }
       }
@@ -103,6 +126,12 @@ class ModelClient {
   }
 
   static _getProvider(modelId) {
+    // Consult the pluggable registry first (honors MINDFORGE_LLM_PROVIDER
+    // override for sovereignty/offline test isolation). Falls through to the
+    // built-in prefix routing when nothing is registered.
+    const registered = resolveProvider(modelId);
+    if (registered) return registered;
+
     if (modelId.startsWith('claude') || modelId.startsWith('anthropic.claude')) {
       if (!process.env.ANTHROPIC_API_KEY) return null;
       return new AnthropicProvider(process.env.ANTHROPIC_API_KEY);
@@ -115,6 +144,12 @@ class ModelClient {
       if (!process.env.GOOGLE_API_KEY) return null;
       return new GeminiProvider(process.env.GOOGLE_API_KEY);
     }
+    // Sovereign local models (e.g. llama-3-70b-local). Gated on OLLAMA_BASE_URL
+    // being explicitly set, so cloud routing is unchanged unless opted in.
+    if (modelId.includes('local') || modelId.includes('llama')) {
+      if (!process.env.OLLAMA_BASE_URL) return null;
+      return new OllamaProvider(process.env.OLLAMA_BASE_URL);
+    }
     return null;
   }
 }

package/bin/models/ollama-provider.js

@@ -0,0 +1,115 @@
+/**
+ * MindForge — Ollama / local-model Provider
+ *
+ * Adapted from ECC (src/llm/providers/ollama.py). Talks to a local Ollama
+ * server (default http://localhost:11434) so the sovereign `llama-3-70b-local`
+ * entry in revops.market_registry is actually reachable — previously a dead
+ * link the MIR cost-arbitrage math could pick but never execute.
+ *
+ * Mirrors AnthropicProvider.complete() return shape so it drops into
+ * model-client.js unchanged. GATED on OLLAMA_BASE_URL: model-client only
+ * constructs this provider when OLLAMA_BASE_URL is set, so cloud routing is
+ * unchanged unless the operator explicitly opts in.
+ */
+'use strict';
+
+const http = require('http');
+const { URL } = require('url');
+
+class OllamaProvider {
+  constructor(baseUrl) {
+    this.baseUrl = baseUrl || process.env.OLLAMA_BASE_URL || 'http://localhost:11434';
+  }
+
+  async complete(params) {
+    const { model, systemPrompt, userMessage, temperature = 0.7 } = params;
+
+    const messages = [];
+    if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
+    messages.push({ role: 'user', content: userMessage });
+
+    const payload = JSON.stringify({
+      model,
+      messages,
+      stream: false,
+      options: temperature !== 1.0 ? { temperature } : undefined,
+    });
+
+    const url = new URL('/api/chat', this.baseUrl);
+
+    return new Promise((resolve, reject) => {
+      const req = http.request({
+        hostname: url.hostname,
+        port: url.port || 11434,
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+        },
+        timeout: 120_000,
+      }, res => {
+        let body = '';
+        res.on('data', chunk => body += chunk);
+        res.on('end', () => {
+          try {
+            if (res.statusCode !== 200) {
+              return reject(Object.assign(
+                new Error(`Ollama API error (${res.statusCode})`),
+                { status: res.statusCode }
+              ));
+            }
+            const json = JSON.parse(body);
+            const content = json.message?.content || '';
+
+            // Ollama reports token counts as prompt_eval_count / eval_count.
+            const inputTokens = json.prompt_eval_count || 0;
+            const outputTokens = json.eval_count || 0;
+
+            // Price via the registry id (e.g. llama-3-70b-local). Local models
+            // are effectively free, but we still record for MIR/ROI accounting.
+            let cost = 0;
+            try {
+              const { priceCall } = require('./pricing-registry');
+              cost = priceCall(model, { input_tokens: inputTokens, output_tokens: outputTokens });
+            } catch (_e) {
+              cost = 0;
+            }
+
+            resolve({
+              model,
+              content,
+              input_tokens: inputTokens,
+              output_tokens: outputTokens,
+              cost_usd: cost,
+              provider: 'ollama',
+            });
+          } catch (e) {
+            reject(new Error('Failed to parse Ollama response: ' + e.message));
+          }
+        });
+      });
+
+      req.on('error', err => {
+        // Connection refused = local server not running. Surface as a clear,
+        // retryable-by-fallback error rather than a cryptic ECONNREFUSED.
+        reject(Object.assign(
+          new Error(`Ollama connection failed (${this.baseUrl}): ${err.message}`),
+          { status: 503 }
+        ));
+      });
+      req.on('timeout', () => {
+        req.destroy();
+        reject(Object.assign(new Error('Ollama timeout'), { status: 408 }));
+      });
+      req.write(payload);
+      req.end();
+    });
+  }
+
+  validateConfig() {
+    return Boolean(this.baseUrl);
+  }
+}
+
+module.exports = OllamaProvider;