@sienklogic/plan-build-run 2.22.2 → 2.23.0

package/plugins/pbr/agents/researcher.md

@@ -62,6 +62,26 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
 
+## Local LLM Source Scoring (Optional)
+
+If local LLM offload is configured, you MAY use it to score source credibility instead of manually assigning S-levels. This is advisory — never wait on it or fail if it returns null.
+
+Check availability first:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" llm status 2>/dev/null
+```
+
+If `enabled: true`, score a source excerpt:
+
+```bash
+echo "Source URL and content excerpt" > /tmp/source-excerpt.txt
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" llm score-source "https://example.com/docs" /tmp/source-excerpt.txt 2>/dev/null
+# Returns: {"level":"S2","confidence":0.87,"reason":"Official library documentation page"}
+```
+
+Use the returned `level` to set your source tag. If the call fails or returns `null`, assign the level manually per the hierarchy table above.
+
 ---
 
 ## Confidence Levels

package/plugins/pbr/agents/synthesizer.md

@@ -100,6 +100,18 @@ conflicts: N
 - **Research gaps**: Add `[RESEARCH GAP]` flag, add to Open Questions with high impact, never fabricate
 - **Duplicates**: Consolidate into one entry, note multi-source agreement, reference all documents
 
+## Local LLM Context Summarization (Optional)
+
+When input research documents are large (>2000 words combined), you MAY use the local LLM to pre-summarize each document before synthesis. This reduces your own context consumption. Advisory only — if unavailable, read documents normally.
+
+```bash
+# Pre-summarize a large research document to ~150 words:
+node "${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js" llm summarize /path/to/RESEARCH.md 150 2>/dev/null
+# Returns: {"summary":"...plain text summary under 150 words...","latency_ms":2100,"fallback_used":false}
+```
+
+Use the returned `summary` string as your working copy of that document's findings. Still read the original for any specific version numbers, code examples, or direct quotes needed in the output.
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns

package/plugins/pbr/references/config-reference.md

@@ -439,3 +439,92 @@ Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
 | `tdd_mode: true` + `depth: quick` | quick depth skips verification, which conflicts with TDD's verify-first approach |
 | `git.mode: disabled` + `atomic_commits: true` | atomic_commits has no effect when git is disabled |
 | `git.branching: phase` + `git.mode: disabled` | Branching settings are ignored when git is disabled |
+
+---
+
+## local_llm
+
+Offloads selected PBR inference tasks to a locally running Ollama instance, reducing frontier model usage and latency for fast classification calls. The key `enabled` defaults to `false`, so users without Ollama see no change — all LLM calls continue routing to Claude as normal. When enabled, PBR uses a `local_first` routing strategy: fast tasks (artifact classification, task validation) go to the local model; complex tasks (planning, execution) stay on the frontier model.
+
+### Quick setup
+
+1. Install Ollama:
+   - **Linux/macOS**: `curl -fsSL https://ollama.com/install.sh | sh`
+   - **Windows**: Download from [ollama.com/download](https://ollama.com/download) and run the installer
+2. Pull the recommended model: `ollama pull qwen2.5-coder:7b`
+3. Add to `.planning/config.json`:
+
+   ```json
+   "local_llm": {
+     "enabled": true,
+     "model": "qwen2.5-coder:7b"
+   }
+   ```
+
+4. Verify connectivity: `node /path/to/plugins/pbr/scripts/pbr-tools.js llm health`
+
+### Field reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `local_llm.enabled` | boolean | `false` | Enable local LLM offloading; `false` = all calls use frontier |
+| `local_llm.provider` | string | `"ollama"` | Backend provider; only `"ollama"` is supported |
+| `local_llm.endpoint` | string | `"http://localhost:11434"` | Ollama API base URL |
+| `local_llm.model` | string | `"qwen2.5-coder:7b"` | Model tag to use for local inference |
+| `local_llm.timeout_ms` | integer | `3000` | Per-request timeout in milliseconds; >= 500 |
+| `local_llm.max_retries` | integer | `1` | Number of retry attempts on failure before falling back |
+| `local_llm.fallback` | string | `"frontier"` | What to use when local LLM fails: `"frontier"` or `"skip"` |
+| `local_llm.routing_strategy` | string | `"local_first"` | `"local_first"` sends fast tasks local; `"always_local"` routes everything |
+
+### features sub-table
+
+Controls which PBR tasks are eligible for local LLM offloading.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `artifact_classification` | `true` | Classify artifact types (PLAN, SUMMARY, VERIFICATION) locally |
+| `task_validation` | `true` | Validate task scope and completeness locally |
+| `context_summarization` | `false` | Summarize context windows locally (higher token demand) |
+| `source_scoring` | `false` | Score source files by relevance locally |
+
+### advanced sub-table
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `confidence_threshold` | `0.9` | Minimum confidence (0–1) for local output to be accepted; below this, falls back to frontier |
+| `shadow_mode` | `false` | Run local LLM in parallel with frontier but discard local results — useful for tuning confidence thresholds without affecting output |
+| `max_input_tokens` | `2000` | Truncate inputs longer than this before sending to local model |
+| `keep_alive` | `"30m"` | How long Ollama keeps the model loaded between requests (Ollama format: `"5m"`, `"1h"`) |
+| `num_ctx` | `4096` | Context window size passed to Ollama; **must be 4096 on Windows** (see Windows gotchas) |
+| `disable_after_failures` | `3` | Automatically disable local LLM for the session after this many consecutive failures |
+
+### Hardware requirements
+
+| Tier | Hardware | Notes |
+|------|----------|-------|
+| Recommended | RTX 3060+ with 8 GB VRAM | Full GPU acceleration; qwen2.5-coder:7b loads entirely in VRAM |
+| Functional | GTX 1660+ with 6 GB VRAM | GPU acceleration with slight layer offload to RAM |
+| Marginal | CPU only, 32 GB RAM | Works but adds 5-20s latency per call; disable context-heavy features |
+
+For GPU acceleration, ensure NVIDIA drivers are 520+ and CUDA 11.8+ is installed. AMD GPU support is available via ROCm on Linux only.
+
+### Windows gotchas
+
+- **Smart App Control**: May block `ollama_llama_server.exe` on first run. Allow it via Security settings or disable Smart App Control.
+- **Windows Defender**: Add an exclusion for `%LOCALAPPDATA%\Programs\Ollama\ollama_llama_server.exe` to prevent Defender from scanning inference calls in real time.
+- **`num_ctx` must be 4096**: Higher values cause GPU memory fragmentation on Windows and result in OOM errors mid-session. Always set `advanced.num_ctx: 4096` in your config.
+- **Firewall**: Ollama listens on `localhost:11434` by default. If you see connection refused errors, check that Windows Firewall is not blocking loopback connections.
+
+### Viewing metrics
+
+After enabling local LLM, PBR logs per-call metrics to `.planning/logs/local-llm-metrics.jsonl`. Use the built-in subcommands to inspect them:
+
+```bash
+# Show session summary (calls routed, latency, token savings)
+node plugins/pbr/scripts/pbr-tools.js llm metrics
+
+# Suggest routing threshold adjustments based on recent accuracy
+node plugins/pbr/scripts/pbr-tools.js llm adjust-thresholds
+```
+
+Metrics include: routing decision, model used, latency ms, confidence score, whether the frontier fallback was triggered, and estimated tokens saved.

package/plugins/pbr/scripts/check-config-change.js

@@ -64,6 +64,18 @@ function validateConfig(configPath) {
     }
   }
 
+  // Advisory: suggest local_llm defaults if the key is absent
+  if (!config.local_llm) {
+    warnings.push(
+      'local_llm config missing. To enable local LLM offload, add to config.json:\n' +
+      '"local_llm": {\n' +
+      '  "enabled": false,\n' +
+      '  "model": "qwen2.5-coder:7b",\n' +
+      '  "endpoint": "http://localhost:11434"\n' +
+      '} (set enabled: true after running: ollama pull qwen2.5-coder:7b)'
+    );
+  }
+
   // Check version
   if (config.version && config.version < 2) {
     warnings.push(`Config version ${config.version} is outdated — expected version 2+`);
@@ -90,6 +102,27 @@ function validateConfig(configPath) {
     }
   }
 
+  // Validate local_llm block
+  if (config.local_llm !== undefined) {
+    const llm = config.local_llm;
+    if (llm.enabled !== undefined && typeof llm.enabled !== 'boolean') {
+      warnings.push('local_llm.enabled must be a boolean');
+    }
+    if (llm.provider !== undefined && llm.provider !== 'ollama') {
+      warnings.push(`local_llm.provider "${llm.provider}" is not supported — use "ollama"`);
+    }
+    if (llm.timeout_ms !== undefined && (typeof llm.timeout_ms !== 'number' || llm.timeout_ms < 500)) {
+      warnings.push('local_llm.timeout_ms must be a number >= 500');
+    }
+    if (llm.advanced && llm.advanced.num_ctx !== undefined && llm.advanced.num_ctx !== 4096) {
+      warnings.push(`local_llm.advanced.num_ctx is ${llm.advanced.num_ctx} — strongly recommend 4096 to avoid GPU memory issues on Windows`);
+    }
+    if (llm.advanced && llm.advanced.disable_after_failures !== undefined &&
+        (typeof llm.advanced.disable_after_failures !== 'number' || llm.advanced.disable_after_failures < 1)) {
+      warnings.push('local_llm.advanced.disable_after_failures must be a number >= 1');
+    }
+  }
+
   return warnings;
 }
 

package/plugins/pbr/scripts/check-plan-format.js

@@ -25,13 +25,29 @@ const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
 const { atomicWrite } = require('./pbr-tools');
+const { resolveConfig } = require('./local-llm/health');
+const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
 
-function main() {
+/**
+ * Load and resolve the local_llm config block from .planning/config.json.
+ * Returns a resolved config (always safe to use — disabled by default on error).
+ */
+function loadLocalLlmConfig() {
+  try {
+    const configPath = path.join(process.cwd(), '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_e) {
+    return resolveConfig(undefined);
+  }
+}
+
+async function main() {
   let input = '';
 
   process.stdin.setEncoding('utf8');
   process.stdin.on('data', (chunk) => { input += chunk; });
-  process.stdin.on('end', () => {
+  process.stdin.on('end', async () => {
     try {
       const data = JSON.parse(input);
 
@@ -62,6 +78,22 @@ function main() {
             ? validateRoadmap(content, filePath)
             : validateSummary(content, filePath);
 
+      // LLM advisory enrichment — advisory only, never blocks
+      if ((isPlan || isSummary) && result.errors.length === 0) {
+        try {
+          const llmConfig = loadLocalLlmConfig();
+          const planningDir = path.join(process.cwd(), '.planning');
+          const fileType = isPlan ? 'PLAN' : 'SUMMARY';
+          const llmResult = await classifyArtifact(llmConfig, planningDir, content, fileType, undefined);
+          if (llmResult && llmResult.classification) {
+            const llmNote = `Local LLM: ${fileType} classified as "${llmResult.classification}" (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)${llmResult.reason ? ' — ' + llmResult.reason : ''}`;
+            result.warnings.push(llmNote);
+          }
+        } catch (_llmErr) {
+          // Never propagate LLM errors
+        }
+      }
+
       const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : isRoadmap ? 'roadmap-validated' : 'summary-validated';
 
       if (result.errors.length > 0) {
@@ -227,9 +259,9 @@ function validateSummary(content, _filePath) {
 /**
  * Core plan/summary check logic for use by dispatchers.
  * @param {Object} data - Parsed hook input (tool_input, etc.)
- * @returns {null|{output: Object}} null if pass or not applicable, result otherwise
+ * @returns {Promise<null|{output: Object}>} null if pass or not applicable, result otherwise
  */
-function checkPlanWrite(data) {
+async function checkPlanWrite(data) {
   const filePath = data.tool_input?.file_path || data.tool_input?.path || '';
   const basename = path.basename(filePath);
   const isPlan = basename.endsWith('PLAN.md');
@@ -249,6 +281,22 @@ function checkPlanWrite(data) {
         ? validateRoadmap(content, filePath)
         : validateSummary(content, filePath);
 
+  // LLM advisory enrichment — advisory only, never blocks
+  if ((isPlan || isSummary) && result.errors.length === 0) {
+    try {
+      const llmConfig = loadLocalLlmConfig();
+      const planningDir = path.join(process.cwd(), '.planning');
+      const fileType = isPlan ? 'PLAN' : 'SUMMARY';
+      const llmResult = await classifyArtifact(llmConfig, planningDir, content, fileType, undefined);
+      if (llmResult && llmResult.classification) {
+        const llmNote = `Local LLM: ${fileType} classified as "${llmResult.classification}" (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)${llmResult.reason ? ' — ' + llmResult.reason : ''}`;
+        result.warnings.push(llmNote);
+      }
+    } catch (_llmErr) {
+      // Never propagate LLM errors
+    }
+  }
+
   const eventType = isPlan ? 'plan-validated' : isVerification ? 'verification-validated' : isRoadmap ? 'roadmap-validated' : 'summary-validated';
 
   if (result.errors.length > 0) {

package/plugins/pbr/scripts/check-subagent-output.js

@@ -20,6 +20,8 @@
 const fs = require('fs');
 const path = require('path');
 const { logHook } = require('./hook-logger');
+const { resolveConfig } = require('./local-llm/health');
+const { classifyError } = require('./local-llm/operations/classify-error');
 
 /**
  * Check if a file was modified recently (within thresholdMs).
@@ -310,7 +312,17 @@ function readStdin() {
   return {};
 }
 
-function main() {
+function loadLocalLlmConfig(cwd) {
+  try {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return resolveConfig(parsed.local_llm);
+  } catch (_) {
+    return resolveConfig(undefined);
+  }
+}
+
+async function main() {
   const data = readStdin();
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
@@ -426,8 +438,22 @@ function main() {
       agent_type: agentType,
       warnings: skillWarnings
     });
+    // LLM error classification — advisory enrichment
+    let llmCategoryNote = '';
+    try {
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (errorText) {
+        const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, undefined);
+        if (llmResult && llmResult.category) {
+          llmCategoryNote = `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+        }
+      }
+    } catch (_llmErr) {
+      // Never propagate
+    }
     const msg = `Warning: Agent ${agentType} completed but no ${outputSpec.description} was found.\nSkill-specific warnings:\n` +
-      skillWarnings.map(w => `- ${w}`).join('\n');
+      skillWarnings.map(w => `- ${w}`).join('\n') + llmCategoryNote;
     process.stdout.write(JSON.stringify({ additionalContext: msg }));
   } else if (genericMissing) {
     logHook('check-subagent-output', 'PostToolUse', 'warning', {
@@ -435,8 +461,22 @@ function main() {
       expected: outputSpec.description,
       found: 'none'
     });
+    // LLM error classification — advisory enrichment
+    let llmCategoryNote = '';
+    try {
+      const llmConfig = loadLocalLlmConfig(cwd);
+      const errorText = (data.tool_output || '').substring(0, 500);
+      if (errorText) {
+        const llmResult = await classifyError(llmConfig, planningDir, errorText, agentType, undefined);
+        if (llmResult && llmResult.category) {
+          llmCategoryNote = `\nLLM error category: ${llmResult.category} (confidence: ${(llmResult.confidence * 100).toFixed(0)}%)`;
+        }
+      }
+    } catch (_llmErr) {
+      // Never propagate
+    }
     const output = {
-      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.`
+      additionalContext: `[WARN] Agent ${agentType} completed but no ${outputSpec.description} was found. Likely causes: (1) agent hit an error mid-run, (2) wrong working directory. To fix: re-run the parent skill — the executor gate will block until the output is present. Check the Task() output above for error details.` + llmCategoryNote
     };
     process.stdout.write(JSON.stringify(output));
   } else if (skillWarnings.length > 0) {

package/plugins/pbr/scripts/config-schema.json

@@ -253,6 +253,54 @@
         }
       },
       "additionalProperties": false
+    },
+    "local_llm": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "provider": { "type": "string", "enum": ["ollama"] },
+        "endpoint": { "type": "string", "format": "uri" },
+        "model": { "type": "string" },
+        "timeout_ms": { "type": "integer", "minimum": 500 },
+        "max_retries": { "type": "integer", "minimum": 0, "maximum": 3 },
+        "fallback": { "type": "string", "enum": ["frontier", "skip"] },
+        "routing_strategy": { "type": "string", "enum": ["local_first", "frontier_first"] },
+        "features": {
+          "type": "object",
+          "properties": {
+            "artifact_classification": { "type": "boolean" },
+            "task_validation": { "type": "boolean" },
+            "plan_adequacy": { "type": "boolean" },
+            "gap_detection": { "type": "boolean" },
+            "context_summarization": { "type": "boolean" },
+            "source_scoring": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        },
+        "metrics": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "log_file": { "type": "string" },
+            "show_session_summary": { "type": "boolean" },
+            "frontier_token_rate": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "advanced": {
+          "type": "object",
+          "properties": {
+            "confidence_threshold": { "type": "number", "minimum": 0, "maximum": 1 },
+            "max_input_tokens": { "type": "integer", "minimum": 100 },
+            "keep_alive": { "type": "string" },
+            "num_ctx": { "type": "integer", "minimum": 512 },
+            "disable_after_failures": { "type": "integer", "minimum": 1 },
+            "shadow_mode": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false

package/plugins/pbr/scripts/local-llm/client.js

@@ -0,0 +1,214 @@
+/* global fetch, AbortSignal, performance */
+'use strict';
+
+// Circuit breaker: Map<operationType, { failures: number, disabled: boolean }>
+const circuitState = new Map();
+
+/**
+ * Attempts to parse JSON from text that may be raw JSON or wrapped in a markdown code block.
+ * @param {string} text
+ * @returns {{ ok: true, data: any } | { ok: false, raw: string }}
+ */
+function tryParseJSON(text) {
+  // Attempt 1: direct parse
+  try {
+    const data = JSON.parse(text);
+    return { ok: true, data };
+  } catch (_) {
+    // fall through
+  }
+
+  // Attempt 2: extract from markdown code block
+  const codeBlockMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+  if (codeBlockMatch) {
+    try {
+      const data = JSON.parse(codeBlockMatch[1].trim());
+      return { ok: true, data };
+    } catch (_) {
+      // fall through
+    }
+  }
+
+  // Attempt 3: find first {...}
+  const objectMatch = text.match(/\{[\s\S]*\}/);
+  if (objectMatch) {
+    try {
+      const data = JSON.parse(objectMatch[0]);
+      return { ok: true, data };
+    } catch (_) {
+      // fall through
+    }
+  }
+
+  return { ok: false, raw: text };
+}
+
+/**
+ * Maps an error to one of 5 canonical types.
+ * @param {Error} err
+ * @returns {{ type: string, message: string }}
+ */
+function categorizeError(err) {
+  if (
+    (err.cause && err.cause.code === 'ECONNREFUSED') ||
+    (err.message && err.message.includes('ECONNREFUSED'))
+  ) {
+    return { type: 'ECONNREFUSED', message: err.message };
+  }
+  if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+    return { type: 'timeout', message: err.message };
+  }
+  if (err.message && err.message.startsWith('HTTP ')) {
+    return { type: 'http_error', message: err.message };
+  }
+  if (err instanceof SyntaxError) {
+    return { type: 'json_parse', message: err.message };
+  }
+  return { type: 'wrong_answer', message: err.message };
+}
+
+/**
+ * Returns true if the circuit is open (operation should be skipped).
+ * @param {string} operationType
+ * @param {number} maxFailures
+ * @returns {boolean}
+ */
+function isDisabled(operationType, maxFailures) {
+  const entry = circuitState.get(operationType);
+  if (!entry) return false;
+  return entry.disabled || entry.failures >= maxFailures;
+}
+
+/**
+ * Records a failure for an operation type. Disables the circuit if maxFailures is reached.
+ * @param {string} operationType
+ * @param {number} maxFailures
+ */
+function recordFailure(operationType, maxFailures) {
+  const entry = circuitState.get(operationType) || { failures: 0, disabled: false };
+  entry.failures += 1;
+  if (entry.failures >= maxFailures) {
+    entry.disabled = true;
+  }
+  circuitState.set(operationType, entry);
+}
+
+/**
+ * Resets the circuit breaker for an operation type.
+ * @param {string} operationType
+ */
+function resetCircuit(operationType) {
+  circuitState.delete(operationType);
+}
+
+/**
+ * Sends a chat completion request to a local LLM endpoint with retry and circuit-breaker logic.
+ *
+ * @param {object} config - local_llm config block (resolved)
+ * @param {string} prompt - user message to send
+ * @param {string} operationType - operation identifier for circuit breaker tracking
+ * @param {object} [options={}] - optional parameters
+ * @param {boolean} [options.logprobs] - if true, request logprobs from the API
+ * @returns {Promise<{ content: string, latency_ms: number, tokens: number, logprobsData: Array<{token: string, logprob: number}>|null }>}
+ */
+async function complete(config, prompt, operationType, options = {}) {
+  const endpoint = config.endpoint || 'http://localhost:11434';
+  const model = config.model || 'qwen2.5-coder:7b';
+  const timeoutMs = config.timeout_ms || 3000;
+  const maxRetries = config.max_retries != null ? config.max_retries : 1;
+  const numCtx = (config.advanced && config.advanced.num_ctx) || 4096;
+  const keepAlive = (config.advanced && config.advanced.keep_alive) || '30m';
+  const maxFailures = (config.advanced && config.advanced.disable_after_failures) || 3;
+
+  if (isDisabled(operationType, maxFailures)) {
+    const err = new Error('Circuit open for operation: ' + operationType);
+    err.type = 'circuit_open';
+    throw err;
+  }
+
+  const bodyObj = {
+    model,
+    messages: [
+      {
+        role: 'system',
+        content:
+          'You are a precise classification assistant. Always respond with valid JSON only. No explanations outside the JSON.'
+      },
+      { role: 'user', content: prompt }
+    ],
+    response_format: { type: 'json_object' },
+    temperature: 0.1,
+    max_tokens: 200,
+    keep_alive: keepAlive,
+    num_ctx: numCtx
+  };
+  if (options.logprobs === true) {
+    bodyObj.logprobs = true;
+    bodyObj.top_logprobs = 3;
+  }
+  const body = JSON.stringify(bodyObj);
+
+  const url = endpoint + '/v1/chat/completions';
+  const totalAttempts = maxRetries + 1;
+
+  let lastErr;
+  for (let attempt = 0; attempt < totalAttempts; attempt++) {
+    const start = performance.now();
+    try {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+
+      if (!res.ok) {
+        const errText = await res.text().catch(() => '');
+        throw new Error('HTTP ' + res.status + ': ' + errText);
+      }
+
+      const json = await res.json();
+      const content = json.choices[0].message.content;
+      const completionTokens = (json.usage && json.usage.completion_tokens) || 0;
+      const latency_ms = performance.now() - start;
+      const logprobsData = (options.logprobs && json.choices[0].logprobs)
+        ? json.choices[0].logprobs.content
+        : null;
+
+      return { content, latency_ms, tokens: completionTokens, logprobsData };
+    } catch (err) {
+      lastErr = err;
+      const isConnRefused =
+        (err.cause && err.cause.code === 'ECONNREFUSED') ||
+        (err.message && err.message.includes('ECONNREFUSED'));
+
+      if (isConnRefused) {
+        // Server not running — no point retrying
+        recordFailure(operationType, maxFailures);
+        throw err;
+      }
+
+      const isTimeout = err.name === 'TimeoutError' || err.name === 'AbortError';
+      const isHttpError = err.message && err.message.startsWith('HTTP ');
+
+      if ((isTimeout || isHttpError) && attempt < totalAttempts - 1) {
+        // Retry
+        continue;
+      }
+
+      // Final attempt or non-retryable error
+      if (attempt === totalAttempts - 1) {
+        recordFailure(operationType, maxFailures);
+      } else {
+        recordFailure(operationType, maxFailures);
+      }
+      throw err;
+    }
+  }
+
+  // Should not reach here, but guard anyway
+  recordFailure(operationType, maxFailures);
+  throw lastErr;
+}
+
+module.exports = { tryParseJSON, categorizeError, isDisabled, recordFailure, resetCircuit, complete };