Persist heuristic fallback results in cache

Author: Denis Ermilov

PROJECT.md

@@ -653,7 +653,7 @@ FastAPI server wrapping local AI CLIs. Runs on port 8765 (configurable via `PORT
 4. Only tabs without fresh coverage are formatted into compact prompts and analyzed in batches of 30 via the configured CLI provider
 5. If the primary CLI fails or hits a usage limit, the server retries the batch with the fallback CLI provider
 6. The extension persists partial/final run state with per-tab statuses in `analysis_runs`, so stop/resume survives reloads
-7. If a batch finishes via heuristic fallback in the extension, those per-URL results are imported back through `/url-analysis/import`
+7. If a batch falls back to heuristics, those per-URL results are still persisted to `url_analysis` either directly on the server or via `/url-analysis/import`, so per-tab coverage stays in sync with what the user just analyzed
 8. The server stores per-URL results + session metrics in SQLite, then returns the aggregated `AnalyzeResponse`
 9. The Search dialog uses `/chat` to retrieve SQLite candidates and, when useful, summarize/rank them with the same provider/model chain as AI Analysis
 

SETUP.md

@@ -199,7 +199,7 @@ The AI server is a FastAPI application that proxies tab analysis requests to CLI
 3. Server checks `tab_analysis.db` for fresh per-URL cache hits (180-day TTL, namespaced by provider/model settings)
 4. Only tabs without fresh SQLite coverage are sent to the configured CLI provider, in batches of 30, unless `Re-analyze` is used
 5. If the primary provider fails or hits a usage limit, the server automatically tries the fallback CLI provider
-6. If both configured providers fail, heuristic recommendations keep the batch moving and the UI still receives structured results
+6. If both configured providers fail, the server saves heuristic recommendations into `url_analysis`, so the batch still produces structured results and the same tabs stop appearing as "not yet analyzed"
 7. After each batch, the extension persists partial/final analysis run state in SQLite (`analysis_runs`) with per-tab statuses so stop/resume survives extension reloads
 8. If a batch finishes through the client-side heuristic fallback, those per-URL results are imported back into SQLite through `/url-analysis/import`, so coverage stays accurate
 9. Server stores per-URL results + session metrics in SQLite, then returns the aggregated result, metadata, and cache stats

agent.py

@@ -2272,30 +2272,46 @@ async def analyze(request: AnalyzeRequest, req: Request) -> AnalyzeResponse:
                     error_msg = summarize_provider_error(provider_error) if provider_error else "No provider configured"
                     fallback_notice = classify_fallback_issue(provider_error or RuntimeError("No provider configured"))
                     fallback_notices.append(fallback_notice)
+                    heuristic_reason = f"{fallback_notice} Original provider error: {error_msg}."
+                    heuristic_recommendations = build_heuristic_recommendations(batch, heuristic_reason)
+                    now = time.time()
+                    db_entries = []
+                    for rec in heuristic_recommendations:
+                        tab = next((t for t in batch if t.id == rec.get("tabId")), None)
+                        if tab:
+                            db_entries.append({
+                                "url": f"{cache_namespace}::{tab.url}",
+                                "action": rec["action"],
+                                "confidence": rec["confidence"],
+                                "reason": rec["reason"],
+                                "suggestedGroupName": rec.get("suggestedGroupName"),
+                                "analyzedAt": now,
+                                "analysisSource": "heuristic",
+                                "provider": None,
+                                "model": None,
+                            })
+                        all_recommendations.append(rec)
+
+                    await save_url_analyses(db, db_entries)
+                    tabs_saved += len(db_entries)
+
                     failed_urls = [tab.url for tab in batch]
                     logger.error(
-                        "Batch %s/%s FAILED (not saved to DB): %s. Failed URLs: %s",
+                        "Batch %s/%s provider fallback saved as heuristics: %s. Failed URLs: %s",
                         batch_idx + 1,
                         len(batches),
                         error_msg,
                         ", ".join(url[:80] for url in failed_urls[:5]) + (f" (+{len(failed_urls)-5} more)" if len(failed_urls) > 5 else ""),
                     )
                     await add_runtime_log(
                         db,
-                        "error",
+                        "warning",
                         "provider",
                         f"Batch {batch_idx + 1}/{len(batches)}: all providers failed — {error_msg}. "
-                        f"{len(batch)} URLs skipped (not saved): "
+                        f"{len(db_entries)} heuristic URL analysis record(s) saved instead: "
                         + ", ".join(url[:60] for url in failed_urls[:5])
                         + (f" (+{len(failed_urls)-5} more)" if len(failed_urls) > 5 else ""),
                     )
-                    for tab in batch:
-                        all_recommendations.append({
-                            "tabId": tab.id,
-                            "action": "keep",
-                            "confidence": 0.0,
-                            "reason": f"Error: {error_msg}. This tab was not analyzed.",
-                        })
 
         # Step 4: Build full result
         fallback_summary = fallback_notices[0] if fallback_notices else None

docs/testing/TEST_PLAN.md

@@ -105,7 +105,7 @@ Each test function gets a fresh in-memory SQLite database via the `client` fixtu
 | R18 | Invalid URL | No exception thrown for non-URL string |
 | R19 | Invalid URL near-dup | Invalid URL tab not flagged as near-duplicate of valid tab |
 
-### 3.3 Python — FastAPI server + runtime behavior (28 tests)
+### 3.3 Python — FastAPI server + runtime behavior (29 tests)
 
 | ID | Endpoint | Description |
 |---|---|---|
@@ -119,6 +119,7 @@ Each test function gets a fresh in-memory SQLite database via the `client` fixtu
 | P08 | `POST /url-analysis/import` | Single result saved (saved ≥ 1) |
 | P09 | `POST /url-analysis/import` | Empty payload returns `{ saved: 0 }` |
 | P10 | `POST /url-analysis/import` | Multiple results counted correctly |
+| P10a | `POST /analyze` + `POST /tab-analysis-status` | Provider timeout falls back to heuristics, saves results to SQLite, and marks tabs as cached on the next coverage check |
 | P11 | `GET /clusters` | Empty database returns `{ clusters: [] }` |
 | P12 | `POST /clusters/merge` | Creates a new cluster, visible in list |
 | P13 | `PUT /clusters/{id}` | Renames cluster, name reflected in list |

tests/test_runtime_behavior.py

@@ -143,3 +143,44 @@ async def fake_analyze_batch_via_provider(provider: str, batch: list[agent.TabIn
     response = client.post("/analyze", json={"tabs": tabs, "forceRefresh": True})
     assert response.status_code == 200
     assert calls == ["claude_code", "codex_cli", "codex_cli"]
+
+
+def test_analyze_saves_heuristic_fallback_results_to_cache(client, monkeypatch):
+    client.post("/settings", json={"settings": {"serverAiProvider": "codex_cli", "fallbackAiProvider": "none"}})
+
+    async def fake_analyze_batch_via_provider(provider: str, batch: list[agent.TabInput], settings: agent.AppSettings, **kwargs):
+        raise RuntimeError("Codex CLI timed out after 60s")
+
+    monkeypatch.setattr(agent, "analyze_batch_via_provider", fake_analyze_batch_via_provider)
+
+    tabs = [
+        {
+            "id": 1,
+            "url": "https://example.com/a",
+            "title": "Tab A",
+            "domain": "example.com",
+            "pinned": False,
+            "active": False,
+        },
+        {
+            "id": 2,
+            "url": "https://example.com/b",
+            "title": "Tab B",
+            "domain": "example.com",
+            "pinned": False,
+            "active": True,
+        },
+    ]
+
+    response = client.post("/analyze", json={"tabs": tabs, "forceRefresh": True})
+    assert response.status_code == 200
+    data = response.json()
+    assert data["cacheStats"]["tabsSaved"] == 2
+    assert len(data["result"]["tabRecommendations"]) == 2
+
+    status_response = client.post("/tab-analysis-status", json={"tabs": tabs})
+    assert status_response.status_code == 200
+    status_data = status_response.json()
+    assert status_data["summary"]["pending"] == 0
+    assert status_data["summary"]["cached"] == 2
+    assert all(status["status"] == "cached" for status in status_data["statuses"])