Merge pull request #73 from dmoliveira/my_opencode-e12-routing-trace

feat: add persisted model-routing fallback traces

Author: dmoliveira

CHANGELOG.md

@@ -37,6 +37,7 @@ All notable changes to this project are documented in this file.
 - Added `scripts/context_resilience_command.py` with `/resilience status` and `/resilience doctor` stress diagnostics.
 - Added `instructions/context_resilience_tuning.md` with practical tuning guidance and operating playbook.
 - Added `instructions/model_fallback_explanation_model.md` defining provider/model fallback trace structure, output levels, and redaction rules for Epic 12 Task 12.1.
+- Added persistent model-routing trace runtime support with `/model-routing trace --json` for latest requested/attempted/selected fallback diagnostics.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.
@@ -71,6 +72,7 @@ All notable changes to this project are documented in this file.
 - Expanded selftest coverage for context resilience policy validation and pruning behavior (dedupe, superseded writes, stale error purge, protected evidence retention).
 - Expanded selftest coverage for context recovery outcomes, including resume hints and fallback-path diagnostics.
 - Expanded doctor summary coverage to include context resilience subsystem health checks.
+- Expanded selftest coverage for model-routing trace persistence and runtime fallback-chain reporting.
 
 ## v0.2.0 - 2026-02-12
 

IMPLEMENTATION_ROADMAP.md

@@ -48,7 +48,7 @@ Use this map to avoid overlapping implementations.
 | E9 | Conditional Rules Injector | done | High | E1 | bd-1q8, bd-3rj, bd-fo8, bd-2ik | Enforce project conventions with scoped rules |
 | E10 | Auto Slash Command Detector | paused | Medium | E1, E8 | TBD | Resume only if intent precision stays high in prototypes |
 | E11 | Context-Window Resilience Toolkit | done | High | E4 | bd-2tj, bd-n9y, bd-2t0, bd-18e | Improve long-session stability and recovery |
-| E12 | Provider/Model Fallback Visibility | in_progress | Medium | E5 | bd-1jq | Explain why model routing decisions happen |
+| E12 | Provider/Model Fallback Visibility | in_progress | Medium | E5 | bd-1jq, bd-298 | Explain why model routing decisions happen |
 | E13 | Browser Automation Profile Switching | planned | Medium | E1 | TBD | Toggle Playwright/agent-browser with checks |
 | E14 | Plan-to-Execution Bridge Command | planned | Medium | E2, E3 | TBD | Execute validated plans with progress tracking |
 | E15 | Todo Enforcer and Plan Compliance | planned | High | E14 | TBD | Keep execution aligned with approved checklists |
@@ -509,10 +509,11 @@ Every command-oriented epic must ship all of the following:
   - [x] Subtask 12.1.2: Define compact vs verbose output levels
   - [x] Subtask 12.1.3: Define redaction rules for sensitive provider details
   - [x] Notes: Added `instructions/model_fallback_explanation_model.md` defining fallback trace shape, output levels, redaction policy, and deterministic reason-code requirements.
-- [ ] Task 12.2: Implement resolution tracing
-  - [ ] Subtask 12.2.1: Capture fallback chain attempts in runtime
-  - [ ] Subtask 12.2.2: Store latest trace per command/session
-  - [ ] Subtask 12.2.3: Expose trace to doctor and debug commands
+- [x] Task 12.2: Implement resolution tracing
+  - [x] Subtask 12.2.1: Capture fallback chain attempts in runtime
+  - [x] Subtask 12.2.2: Store latest trace per command/session
+  - [x] Subtask 12.2.3: Expose trace to doctor and debug commands
+  - [x] Notes: Extended `scripts/model_routing_schema.py` with requested/attempted/selected runtime trace payloads and added persisted latest-trace support plus `/model-routing trace` in `scripts/model_routing_command.py`.
 - [ ] Task 12.3: User-facing command surface
   - [ ] Subtask 12.3.1: Add `/routing status` and `/routing explain` commands
   - [ ] Subtask 12.3.2: Add examples for category-driven routing outcomes

README.md

@@ -455,8 +455,11 @@ Use:
 /model-routing status
 /model-routing set-category deep
 /model-routing resolve --category deep --override-model openai/gpt-5.3-codex --json
+/model-routing trace --json
 ```
 
+`/model-routing resolve` now emits a structured fallback trace (`requested -> attempted -> selected`) and persists the latest trace for `/model-routing trace` debug introspection.
+
 Model-profile aliases:
 ```text
 /model-profile status

opencode.json

@@ -131,7 +131,7 @@
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/hooks_command.py\" doctor --json`\nShow only the command output."
     },
     "model-routing": {
-      "description": "Manage model routing (status|set-category|resolve)",
+      "description": "Manage model routing (status|set-category|resolve|trace)",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/model_routing_command.py\" $ARGUMENTS`\nShow only the command output."
     },
     "model-routing-status": {
@@ -154,6 +154,10 @@
       "description": "Resolve effective model settings in JSON",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/model_routing_command.py\" resolve $ARGUMENTS --json`\nShow only the command output."
     },
+    "model-routing-trace": {
+      "description": "Show latest routing trace in JSON",
+      "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/model_routing_command.py\" trace --json`\nShow only the command output."
+    },
     "keyword-mode": {
       "description": "Detect and apply keyword-triggered execution modes",
       "template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/keyword_mode_command.py\" $ARGUMENTS`\nShow only the command output."

scripts/model_routing_command.py

@@ -33,12 +33,13 @@
         "reasoning": "medium",
         "verbosity": "medium",
     },
+    "latest_trace": {},
 }
 
 
 def usage() -> int:
     print(
-        "usage: /model-routing status [--json] | /model-routing set-category <quick|deep|visual|writing> | /model-routing resolve [--category <name>] [--override-model <id>] [--override-temperature <value>] [--override-reasoning <value>] [--override-verbosity <value>] [--available-models <csv>] [--json]"
+        "usage: /model-routing status [--json] | /model-routing set-category <quick|deep|visual|writing> | /model-routing resolve [--category <name>] [--override-model <id>] [--override-temperature <value>] [--override-reasoning <value>] [--override-verbosity <value>] [--available-models <csv>] [--json] | /model-routing trace [--json]"
     )
     return 2
 
@@ -60,6 +61,7 @@ def save_state(config: dict[str, Any], state: dict[str, Any], write_path: Path)
     config[SECTION] = {
         "active_category": state.get("active_category", "quick"),
         "system_defaults": state.get("system_defaults", {}),
+        "latest_trace": state.get("latest_trace", {}),
     }
     save_config_file(config, write_path)
 
@@ -133,13 +135,15 @@ def command_status(argv: list[str]) -> int:
     payload = {
         "active_category": state.get("active_category"),
         "system_defaults": state.get("system_defaults"),
+        "has_latest_trace": bool(state.get("latest_trace")),
         "config": str(write_path),
     }
     if json_output:
         print(json.dumps(payload, indent=2))
     else:
         print(f"active_category: {payload['active_category']}")
         print(f"system_defaults: {json.dumps(payload['system_defaults'])}")
+        print(f"has_latest_trace: {'yes' if payload['has_latest_trace'] else 'no'}")
         print(f"config: {payload['config']}")
     return 0
 
@@ -163,11 +167,17 @@ def command_set_category(argv: list[str]) -> int:
 def command_resolve(argv: list[str]) -> int:
     json_output = "--json" in argv
     filtered = [arg for arg in argv if arg != "--json"]
-    _, state, _ = load_state()
+    config, state, write_path = load_state()
     report = run_resolve(state, filtered)
     if report.get("result") != "PASS":
         print(json.dumps(report, indent=2))
         return 1
+
+    resolution_trace = report.get("resolution_trace")
+    if isinstance(resolution_trace, dict):
+        state["latest_trace"] = resolution_trace
+        save_state(config, state, write_path)
+
     if json_output:
         print(json.dumps(report, indent=2))
         return 0
@@ -181,13 +191,37 @@ def command_resolve(argv: list[str]) -> int:
     return 0
 
 
+def command_trace(argv: list[str]) -> int:
+    if any(arg not in ("--json",) for arg in argv):
+        return usage()
+    json_output = "--json" in argv
+    _, state, _ = load_state()
+    trace = state.get("latest_trace")
+    payload = {
+        "result": "PASS",
+        "has_trace": isinstance(trace, dict) and bool(trace),
+        "trace": trace if isinstance(trace, dict) else {},
+    }
+    if json_output:
+        print(json.dumps(payload, indent=2))
+        return 0
+    print(f"has_trace: {'yes' if payload['has_trace'] else 'no'}")
+    if payload["has_trace"]:
+        selected = payload["trace"].get("selected", {})
+        print(f"selected_model: {selected.get('model')}")
+        print(f"selected_reason: {selected.get('reason')}")
+    return 0
+
+
 def main(argv: list[str]) -> int:
     if not argv or argv[0] == "status":
         return command_status(argv[1:] if argv else [])
     if argv[0] == "set-category":
         return command_set_category(argv[1:])
     if argv[0] == "resolve":
         return command_resolve(argv[1:])
+    if argv[0] == "trace":
+        return command_trace(argv[1:])
     if argv[0] == "help":
         return usage()
     return usage()

scripts/model_routing_schema.py

@@ -14,6 +14,13 @@
 }
 
 
+def _provider_from_model(model: Any) -> str:
+    value = str(model or "").strip()
+    if "/" in value:
+        return value.split("/", 1)[0]
+    return "unknown"
+
+
 def default_schema() -> dict[str, Any]:
     return {
         "default_category": DEFAULT_CATEGORY,
@@ -192,8 +199,60 @@ def resolve_model_settings(
             }
         )
 
+    requested_model = overrides.get("model")
+    if not isinstance(requested_model, str) or not requested_model.strip():
+        requested_model = category_settings.get("model")
+    if not isinstance(requested_model, str) or not requested_model.strip():
+        requested_model = base_system.get("model")
+
+    attempted: list[dict[str, Any]] = []
+    first_model = requested_model
+    first_available = available_models is None or first_model in available_models
+    attempted.append(
+        {
+            "rank": 1,
+            "model": first_model,
+            "provider": _provider_from_model(first_model),
+            "result": "accepted" if first_available else "unavailable",
+            "reason": "requested_or_override_candidate",
+        }
+    )
+
+    final_model = resolved.get("model")
+    if final_model != first_model:
+        attempted.append(
+            {
+                "rank": 2,
+                "model": final_model,
+                "provider": _provider_from_model(final_model),
+                "result": "accepted",
+                "reason": trace[-1].get("reason") if trace else "fallback_selected",
+            }
+        )
+
+    resolution_trace = {
+        "requested": {
+            "category": requested_category,
+            "model": requested_model,
+            "source": (
+                "user_override"
+                if isinstance(overrides.get("model"), str)
+                and str(overrides.get("model")).strip()
+                else "category_default"
+            ),
+        },
+        "attempted": attempted,
+        "selected": {
+            "category": category_result.get("category"),
+            "model": final_model,
+            "provider": _provider_from_model(final_model),
+            "reason": trace[-1].get("reason") if trace else "selected",
+        },
+    }
+
     return {
         "category": category_result.get("category"),
         "settings": resolved,
         "trace": trace,
+        "resolution_trace": resolution_trace,
     }

scripts/selftest.py

@@ -1386,6 +1386,33 @@ def run_bg(*args: str) -> subprocess.CompletedProcess[str]:
             == "openai/gpt-5.3-codex",
             "model-routing resolve should keep active category and apply model fallback",
         )
+        expect(
+            isinstance(model_routing_report.get("resolution_trace"), dict),
+            "model-routing resolve should emit requested/attempted/selected trace payload",
+        )
+
+        model_routing_trace = subprocess.run(
+            [sys.executable, str(MODEL_ROUTING_SCRIPT), "trace", "--json"],
+            capture_output=True,
+            text=True,
+            env=refactor_env,
+            check=False,
+            cwd=REPO_ROOT,
+        )
+        expect(
+            model_routing_trace.returncode == 0,
+            "model-routing trace should succeed",
+        )
+        model_routing_trace_report = parse_json_output(model_routing_trace.stdout)
+        expect(
+            model_routing_trace_report.get("has_trace") is True,
+            "model-routing trace should persist latest resolution trace",
+        )
+        expect(
+            model_routing_trace_report.get("trace", {}).get("selected", {}).get("model")
+            == "openai/gpt-5.3-codex",
+            "model-routing trace should expose selected model from latest resolve",
+        )
 
         keyword_report = resolve_prompt_modes(
             "Please safe-apply and deep-analyze this migration; ulw can wait.",