From f49489c099df10681e2348eb167eff1539645440 Mon Sep 17 00:00:00 2001 From: admin Date: Fri, 22 May 2026 16:35:08 +0400 Subject: [PATCH] =?UTF-8?q?README:=20Intelligence=20Routing=20=E2=80=94=20?= =?UTF-8?q?Phase=208=20dev=20journey=20+=20features=20+=20troubleshooting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/README.md b/README.md index 8f87093..92b4f1d 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ +

@@ -130,6 +131,19 @@ A three-component system: - **ErrorAnalyzer** — learns from 4xx errors, retries with adjusted parameters (max 2 retries) - **Schema cache** with 24h staleness TTL for provider capabilities +### Intelligence Routing (v3.7.0) +- **Three-layer self-healing system** — the agent loop never stalls, even when the model speaks gibberish +- **Layer 1 — Deep URL Extraction**: When `` hides URLs inside nested JSON (`messages: [{"content": "https://..."}]`), the parser drills into the JSON structure to find them. Module-level `_build_explore_cmd()` is reused across parser + stream path. +- **Layer 2 — Escalation Auto-Proceed**: `` and `` blocks are detected and auto-resolved — the model doesn't get stuck waiting for permissions that don't exist. +- **Layer 3 — Intent-Based Command Synthesis**: When ALL parsers fail, 5 heuristics analyze the model's plain-text output and synthesize a working command: + 1. URL detected → `curl` it + 2. File path mentioned → `cat` or `ls` it + 3. Shell command in quotes → extract and run it + 4. "explore"/"fetch" intent → use the last URL the user mentioned + 5. "I need to"/"let me" intent → echo a diagnostic so the loop continues +- **Session URL memory** — `_last_user_urls` deque (20 entries) tracks URLs from user messages across the session, giving the synthesizer context to work with +- **54 self-test patterns** — comprehensive coverage of all three layers + ### GTK Launcher (`codex-launcher-gui`) - **Endpoint manager** — add, edit, delete, set default providers - **Provider presets** — one-click setup for 15+ providers with pre-filled URLs and model lists @@ -324,6 +338,83 @@ Built a cascading parser chain (`DSML → bash → explore → tool_call → XML **Verification:** `--self-test` flag runs 19 automated tests covering all edge cases. Debug logging to `~/.cache/codex-proxy/cc-debug.log` captures every parser decision for troubleshooting. +### Phase 8: Intelligence Routing — When the Model Refuses to Speak Machine + +**Problem:** The 17-fix parser chain from Phase 7 was powerful — it could handle DSML, XML, JSON, bash blocks, explore tags, you name it. But there was one edge case it couldn't crack: **when the model doesn't produce a parseable tool-call format at all**. + +In production, `deepseek/deepseek-v4-flash` via Command Code kept doing things like: + +``` + +messages: [{"content": "Understand the Z.AI-Chat-for-Android repo at https://..."}] + +``` + +or: + +``` + +I need elevated permissions to access the repository. + +``` + +or just plain English: *"I need to fetch the README from the repository to understand the app structure."* + +In every case, `parsed_tool_calls=0`. No tool to execute. The Codex agent loop ground to a halt. The user saw "thinking..." forever. + +**The insight:** The model is trying to communicate *intent*, just not in a format we can parse. Instead of adding more regex patterns, what if we could **read the model's mind** — understand what it *wants* to do, and synthesize the command for it? + +**Intelligence Routing — Three Layers of Escalation:** + +``` +Layer 1: "Fix the input" — Can we extract more from what the model gave us? +Layer 2: "Handle the intent" — Is the model asking for something we can auto-resolve? +Layer 3: "Read the mind" — What is the model trying to do? Just do it for it. +``` + +**Layer 1 — Deep URL Extraction (FIX 23):** + +The `` handler had a URL regex, but the URL was trapped inside `{"content": "https://..."}` — the trailing `"` broke matching. The fix: after the initial regex fails, `json.loads()` the entire block, walk the JSON tree, and pull URLs out of `content` fields. The `_build_explore_cmd()` function was extracted to module level so both the parser and the stream handler could use it. + +```python +# Before: regex fails, URL lost +# After: json.loads -> iterate items -> extract content -> find URL +``` + +**Layer 2 — Escalation Auto-Proceed (FIX 24):** + +`` blocks are the model's way of saying "I need more permissions." The CC adapter doesn't have an escalation mechanism — these blocks were silently dropped. The fix: detect them (both closed `...` and bare `` forms), extract any URL inside them, and auto-proceed with an explore command or a diagnostic echo. + +```python +# Model: Please let me run curl +# Proxy: Okay, here's your curl command → exec_command synthesized +``` + +**Layer 3 — Intent-Based Command Synthesis (FIX 25):** + +The crown jewel. When ALL parsers return empty — no DSML, no XML, no JSON, no fallback regex matches — the system doesn't give up. It analyzes the model's raw text through **5 heuristic lenses** in priority order: + +| Priority | Signal | Synthesized Command | +|:--------:|--------|---------------------| +| 1 | URL in text | `curl` to fetch it | +| 2 | File path reference | `cat` or `ls` the file | +| 3 | Shell command in backticks/quotes | Extract and run it | +| 4 | "explore"/"fetch" + last user URL | Full explore command | +| 5 | "I need to"/"let me" intent | Echo diagnostic | + +The system also maintains a **session URL memory** (`_last_user_urls`, a deque of the last 20 URLs from user messages) so heuristic 4 always has a URL to work with, even when the model's text doesn't contain one. + +```python +# Model: "I should explore the repository to understand its structure." +# Parser: empty (no parseable format) +# Layer 3 heuristic 4: "explore" detected, pulling URL from session memory... +# Result: exec_command with full curl pipeline +``` + +**The result:** Before Intelligence Routing, `parsed_tool_calls=0` meant **game over** — the agent loop stalled permanently. After Intelligence Routing, `parsed_tool_calls=0` triggers the self-healing chain and the loop **always** gets a tool call to execute. The model can speak in tongues and the system still works. + +**Test coverage:** 54 self-test patterns (up from 41), with 13 new tests specifically for Intelligence Routing layers. + --- ## Architecture Deep Dive @@ -454,6 +545,9 @@ README.md # This file | CC tool calls have wrong args | Double-wrapped arguments | V3.5 three-tier parser + recursive unwrapping | | Proxy crashes mid-session | Unhandled streaming error | V3.5 self-revive watchdog auto-restarts | | CC 403 upgrade_required | Missing version header | V3.5 always sends `x-command-code-version` | +| CC explore_agent can't find URL | URL hidden inside JSON messages | V3.7 Layer 1 drills into JSON to extract URLs | +| CC agent stalls on escalation blocks | `` not handled | V3.7 Layer 2 auto-proceeds past escalation requests | +| CC agent stalls — no tool calls at all | Model output format unrecognized | V3.7 Layer 3 synthesizes command from text intent | ---