free-coding-models 0.5.54 → 0.5.56

package/changelog/v0.5.55.md

@@ -0,0 +1,17 @@
+# Changelog v0.5.55 - 2026-07-25
+
+### Fixed
+- 🐳 **Docker "Tool mode save failed" — clear root cause + actionable fix** ([#119](https://github.com/vava-nessa/free-coding-models/issues/119)) — when the `fcm-data` volume was created with files owned by a different UID (older images, host bind-mounts), `chmod -R 777` had no effect because Linux checks file ownership, not mode bits. Two-layer fix:
+  1. `src/core/config.js` — `saveConfig()` now detects `EACCES` / `EPERM` and surfaces a friendly hint via the new exported `formatPermissionHint()` function. The hint explains *why* `chmod` is the wrong tool and gives the exact `docker compose down && docker volume rm <vol> && docker compose up` fix.
+  2. `docker-entrypoint.sh` — proactive ownership check at container startup. If a config file is owned by a different UID than the running `fcm` user, the entrypoint logs a loud `⚠️ WARNING` block *before* the first save attempt fails with a confusing error.
+
+### Closed (upstream, no FCM-side fix possible)
+- 📌 **Caveman CLI install fails on Node 26** ([#101](https://github.com/vava-nessa/free-coding-models/issues/101)) — this is upstream in `@juliusbrussee/caveman-code`. `better-sqlite3 v11.10.0` doesn't compile against Node.js v26 (V8 API churn: `GetPrototype` → `GetPrototypeV2`, etc.). FCM surfaces the npm error verbatim but cannot fix caveman-code's deps. Workaround: use Node v22 or v24 (both LTS, both supported by `better-sqlite3@11`).
+
+### Maintenance
+- 🧪 **+6 new unit tests** for `formatPermissionHint()` (`test/config-permission-hint.test.js`) — covers empty string for non-permission errors, EACCES/EPERM detection, Docker volume mention, "chmod is not the fix" wording, multi-line output.
+
+### Pre-flight checks
+- 590/590 tests pass (`pnpm test`)
+- `vite build` succeeds
+- All three surfaces (CLI, web dashboard, Docker) compatible

package/changelog/v0.5.56.md

@@ -0,0 +1,28 @@
+# Changelog v0.5.56 - 2026-07-25
+
+### Fixed
+- 🔁 **Router stream-stall failover after partial response** ([#137](https://github.com/vava-nessa/free-coding-models/issues/137)) — previously, if a model streamed some data then stalled (per-chunk timeout), the client received a truncated response with no automatic retry. Now the router:
+  1. Emits a synthetic SSE error event in OpenAI format (`code: fcm_stream_failover`) so the client knows the stream was truncated and that failover is happening.
+  2. Returns `failoverToNext: true` to the outer retry loop, which tries the next model on a fresh upstream connection.
+  3. The new model's chunks are appended to the same response object — the client sees one continuous stream with a clear mid-stream error marker.
+  4. On a mid-stream failover the router skips `res.writeHead()` (headers were already sent by the previous model) and emits an SSE comment `: fcm-router-failover-from=<oldKey>` so debuggers can see which model served which segment.
+
+  **Scope of the fix:** only `stream_stall_timeout` and `timeout` errors trigger mid-stream failover. Generic upstream errors (malformed JSON, connection reset, destroy) still close cleanly with no failover — their partial data is more likely to be invalid, so re-streaming from another model wouldn't help.
+
+### Maintenance
+- 🧪 **+1 regression test** (`test/test.js`) locking in the new failover behavior with a stalled-stream mock provider. The existing "does not retry after partial output" test still passes — it uses `res.destroy()` which is *not* a stall, so it correctly keeps the old behaviour.
+- 🧪 **591/591 tests pass** (`pnpm test`).
+- 🧹 `vite build` succeeds.
+
+### How clients see this
+A streaming request that stalls now produces something like:
+```
+data: {"choices":[{"delta":{"content":"partial"}}]}
+
+data: {"error":{"message":"Stream truncated by router due to upstream stream_stall_timeout; failing over to next model.","type":"stream_error","code":"fcm_stream_failover","reason":"stream_stall_timeout"}}
+
+data: {"choices":[{"delta":{"content":"fresh answer from fallback"}}]}
+
+data: [DONE]
+```
+Plus an SSE comment marker on each failover segment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.5.54",
+  "version": "0.5.56",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",
@@ -53,7 +53,7 @@
   ],
   "scripts": {
     "start": "node bin/free-coding-models.js",
-    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js",
+    "test": "node --test test/test.js test/fcm-agent-core.test.js test/patch-openclaw.test.js test/provider-metadata.test.js test/config-permission-hint.test.js",
     "prepack": "npm run build:web",
     "dev": "node scripts/dev-web.mjs",
     "dev:web": "node scripts/dev-web.mjs",

package/src/core/config.js

@@ -760,7 +760,16 @@ export function saveConfig(config, options = {}) {
     // 📖 Write failed - explicit error instead of silent failure
     let errorMsg = `Failed to write config: ${writeError.message}`
     try { unlinkSync(tempPath) } catch { /* ignore temp cleanup failures */ }
-    
+
+    // 📖 Detect permission errors and surface a Docker-specific hint. This
+    // 📖 happens when a volume was created with files owned by another UID
+    // 📖 (e.g. older images running as root, or a host bind-mount where the
+    // 📖 directory is owned by a different user). chmod 777 does NOT fix this
+    // 📖 because Linux checks file ownership, not mode bits, for write access.
+    if (writeError?.code === 'EACCES' || writeError?.code === 'EPERM') {
+      errorMsg += formatPermissionHint(writeError)
+    }
+
     // 📖 Try to restore from backup if we have one
     if (backupCreated) {
       try {
@@ -775,6 +784,37 @@ export function saveConfig(config, options = {}) {
   }
 }
 
+/**
+ * 📖 formatPermissionHint — build a friendly hint for the most common Docker
+ * 📖 permission failure (config file owned by a different UID than the running
+ * 📖 process). Returns an empty string for non-permission errors.
+ *
+ * 📖 Common symptom (issue #119): "Tool mode save failed" in the web dashboard
+ * 📖 even after `chmod -R 777`, because chmod doesn't change ownership.
+ */
+export function formatPermissionHint(writeError) {
+  // 📖 Only emit the hint for actual permission errors — silently no-op for
+  // 📖 anything else so the caller can safely concatenate the result.
+  if (writeError?.code !== 'EACCES' && writeError?.code !== 'EPERM') return ''
+  const lines = []
+  lines.push('')
+  lines.push('  💡 This is almost always a file-ownership issue, not a chmod issue.')
+  lines.push('     The config file is owned by a different user than the one running FCM.')
+  try {
+    const stat = statSync(CONFIG_PATH)
+    lines.push(`     File owner UID: ${stat.uid}, current process UID: ${process.getuid?.() ?? 'n/a'}`)
+  } catch { /* stat may also fail */ }
+  lines.push('')
+  lines.push('  Fix in Docker:')
+  lines.push('     docker compose down')
+  lines.push('     docker volume rm <project>_fcm-data   # or the volume name from `docker volume ls`')
+  lines.push('     docker compose up                    # recreates the volume with the right UID')
+  lines.push('')
+  lines.push('  Fix on host (bind mount):')
+  lines.push('     sudo chown $(id -u):$(id -g) ~/.free-coding-models.json')
+  return '\n' + lines.join('\n')
+}
+
 /**
  * 📖 createBackup: Creates a timestamped backup of the current config file.
  * 📖 Keeps only the 5 most recent backups to avoid disk space issues.

package/src/core/router-daemon.js

@@ -2194,11 +2194,23 @@ class RouterRuntime {
       }
 
       if (res.writableEnded) return { done: true }
-      res.writeHead(response.status, {
-        ...headerEntries(response.headers),
-        'x-fcm-router-model': key,
-        'x-request-id': requestId,
-      })
+      // 📖 Issue #137: when the previous model sent partial data, headers are
+      // 📖 already on the wire — re-calling writeHead throws ERR_HTTP_HEADERS_SENT.
+      // 📖 On a mid-stream failover we just append chunks to the existing response.
+      if (!res.headersSent) {
+        res.writeHead(response.status, {
+          ...headerEntries(response.headers),
+          'x-fcm-router-model': key,
+          'x-request-id': requestId,
+        })
+      } else {
+        // 📖 Reflect the new model in trailer-ish debug headers. Node won't let
+        // 📖 us add new headers after send, but we still update x-fcm-router-model
+        // 📖 semantics via a leading SSE comment so clients can see the switch.
+        try {
+          res.write(`: fcm-router-failover-from=${key}\n\n`)
+        } catch { /* best-effort */ }
+      }
       sentToClient = true
       res.write(firstChunkBuffer)
 
@@ -2230,6 +2242,12 @@ class RouterRuntime {
         return { done: true }
       }
       const reason = error.name === 'AbortError' ? 'timeout' : (error.message || String(error))
+      // 📖 Issue #137: stream-stall timeouts get a special tag so we can
+      // 📖 distinguish them from generic upstream errors below. Only stalls
+      // 📖 should trigger failover after a partial response — generic errors
+      // 📖 (malformed JSON, network reset, etc.) usually mean the partial
+      // 📖 data is invalid anyway, so closing cleanly is safer.
+      const isStall = reason === 'stream_stall_timeout' || reason === 'timeout'
       this.markFailure(key, reason)
       if (reason !== 'timeout') {
         this.recordRouterError('upstream_stream_error', requestId, { model: key, reason, partial: sentToClient })
@@ -2238,6 +2256,31 @@ class RouterRuntime {
       }
       this.addRequestLog({ request_id: requestId, model: key, status: 'ERR', latency_ms: null, tokens: 0, failover: attemptIndex > 0, error: reason, stream: true })
       if (sentToClient) {
+        if (isStall) {
+          // 📖 Issue #137: failover even after a partial response. Emit a
+          // 📖 synthetic SSE error event in OpenAI format so clients know the
+          // 📖 stream was truncated and that the router is failing over. The
+          // 📖 outer retry loop will then try the next model on a fresh
+          // 📖 upstream connection; its chunks are appended to the same
+          // 📖 response object so the client sees one continuous stream.
+          this.logger.warn(`Stream stall after partial response from ${key}, attempting failover`, { request_id: requestId, reason })
+          if (!res.writableEnded) {
+            try {
+              const errorPayload = JSON.stringify({
+                error: {
+                  message: `Stream truncated by router due to upstream ${reason}; failing over to next model.`,
+                  type: 'stream_error',
+                  code: 'fcm_stream_failover',
+                  reason,
+                },
+              })
+              res.write(`data: ${errorPayload}\n\n`)
+            } catch { /* best-effort */ }
+          }
+          return { done: false, failoverToNext: true, reason: `stream_stall_${reason}` }
+        }
+        // 📖 Non-stall errors after partial output: keep existing behaviour
+        // 📖 (close cleanly, no failover) to avoid sending malformed data.
         this.logger.warn(`Streaming failure after partial response from ${key}`, { request_id: requestId, reason })
         try { if (!res.writableEnded) res.end() } catch {}
         return { done: true }