docs(changelog): add #2610 @leninejunior pt-BR completion + #2611 @oyi77 registry gaps

fix(registry): populate empty models arrays + placeholder baseUrl fix

HuggingFace (6 models), HackClub (3 models), Snowflake {account} template.
Integrated into release/v3.8.2

.agents/skills/implement-features/SKILL.md

@@ -0,0 +1,713 @@
+---
+name: implement-features-cx
+description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
+---
+
+# /implement-features — Feature Request Harvest, Research & Implementation Workflow
+
+## Overview
+
+A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
+
+## Codex Execution Notes
+
+- Treat `// turbo` / `// turbo-all` as instructions to use `multi_tool_use.parallel` for independent reads, checks, and GitHub calls.
+- Approval gates are hard stops. Present the report/plan in the final response and do not move to implementation phases until the user explicitly approves.
+- Keep harvest/research bounded enough to produce the approval report quickly; do not start implementation while still in report phases.
+
+**Output directory structure:**
+
+```
+_ideia/
+├── viable/                  # Features approved for implementation
+│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
+│   │   └── 1015-warp-terminal-mitm.md
+│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
+│   └── 1046-native-playground.requirements.md
+├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
+│   └── 1041-smart-auto-combos.md
+└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
+    └── 945-telegram-integration.md
+
+_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
+└── 1046-native-playground.plan.md
+```
+
+> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
+
+> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
+
+---
+
+## Phase 1 — Harvest: Collect & Catalog Feature Ideas
+
+### 1.1 Identify the Repository
+
+// turbo
+
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
+
+### 1.2 Ensure Release Branch Exists
+
+// turbo
+
+Before doing any work, ensure you are on the current release branch:
+
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 1.3 Fetch ALL Open Feature Requests
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
+
+**Step 1 — Get Issue numbers only** (small output, never truncated):
+
+```bash
+# Fetch issues with feature/enhancement labels
+gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
+
+# Also check for [Feature] in title (common pattern when no labels are set)
+gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
+```
+
+- Merge both lists, deduplicate. Count and confirm the total.
+
+**Step 2 — Fetch full metadata for each Issue** (one call per issue):
+
+```bash
+gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
+```
+
+- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
+- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
+- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
+
+### 1.4 Create Idea Files (initially in `_ideia/` root)
+
+For each feature request, create a structured idea file in `<project_root>/_ideia/`:
+
+**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
+Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
+
+#### 1.4a — If the idea file does NOT exist yet, create it:
+
+```markdown
+# Feature: <Title from Issue>
+
+> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
+> Status: 📋 Cataloged | Priority: TBD
+
+## 📝 Original Request
+
+<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
+
+## 💬 Community Discussion
+
+<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
+
+### Participants
+
+- @<author> — Original requester
+- @<commenter1> — <brief role/opinion>
+- ...
+
+### Key Points
+
+- <bullet list of the most important discussion points>
+- <agreements reached>
+- <objections raised>
+
+## 🎯 Refined Feature Description
+
+<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
+
+### What it solves
+
+- <problem 1>
+- <problem 2>
+
+### How it should work (high level)
+
+1. <step 1>
+2. <step 2>
+3. ...
+
+### Affected areas
+
+- <list of codebase areas, modules, files likely affected>
+
+## 📎 Attachments & References
+
+- <any image URLs, mockup links, or external references from the issue>
+
+## 🔗 Related Ideas
+
+- <links to related \_ideia/ files if any overlap found>
+```
+
+#### 1.4b — If the idea file ALREADY exists, update it:
+
+- Append new comments from the issue to the **Community Discussion** section.
+- Update the **Refined Feature Description** if new information changes the understanding.
+- Add any new **Related Ideas** cross-references found.
+- **Do NOT overwrite** existing content — append and enrich it.
+
+### 1.5 Cross-Reference & Deduplication
+
+After processing all issues:
+
+- Scan all `_ideia/*.md` files for overlapping features.
+- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
+- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
+
+---
+
+## Phase 2 — Research: Find Solutions & Build Requirements
+
+For each cataloged idea that is **viable** (aligns with the project's goals):
+
+### 2.1 Viability Pre-Check
+
+Before investing in research, quickly assess:
+
+- [ ] Does this feature align with the project's goals and architecture?
+- [ ] Is it technically feasible with the current codebase?
+- [ ] Does it duplicate existing functionality?
+- [ ] Would it introduce breaking changes or security risks?
+- [ ] Is there enough detail to understand what's needed?
+
+**Verdict options:**
+
+| Verdict               | When                                  | Action                      |
+| --------------------- | ------------------------------------- | --------------------------- |
+| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
+| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
+| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
+| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
+| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
+
+### 2.2 Internet Research (for VIABLE features)
+
+For each viable feature, perform systematic research:
+
+**Step 1 — Web search for similar implementations:**
+
+```
+WebSearch("how to implement <feature description> in <tech stack>")
+WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
+WebSearch("<feature keyword> open source library npm")
+```
+
+**Step 2 — Find reference Git repositories:**
+
+```
+WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
+WebSearch("github <feature keyword> implementation recently updated 2026")
+```
+
+- Find **up to 10 relevant repositories**, sorted by most recently updated.
+- For each repository:
+  - Note the repo URL, star count, last commit date
+  - Read its README and relevant source files via `WebFetch`
+  - Extract the architectural approach, patterns used, and key code snippets
+
+**Step 3 — Read API docs and standards:**
+
+If the feature involves an external API, protocol, or standard:
+
+- Find and read the official documentation
+- Note version requirements, authentication patterns, rate limits
+
+### 2.3 Create Requirements File
+
+For each researched feature, create a requirements file alongside its idea file:
+
+**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
+
+```markdown
+# Requirements: <Feature Title>
+
+> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
+> Research Date: <YYYY-MM-DD>
+> Verdict: ✅ VIABLE
+
+## 🔍 Research Summary
+
+<Brief summary of what was found during research>
+
+## 📚 Reference Implementations
+
+| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
+| --- | ---------------- | ----- | ------------ | -------- | ------------ |
+| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
+| 2   | ...              |       |              |          |              |
+
+### Key Patterns Found
+
+- <pattern 1 with code snippet or link>
+- <pattern 2>
+
+## 📐 Proposed Solution Architecture
+
+### Approach
+
+<Describe the chosen approach based on research findings>
+
+### New Files
+
+| File                  | Purpose       |
+| --------------------- | ------------- |
+| `path/to/new/file.ts` | <description> |
+
+### Modified Files
+
+| File                       | Changes        |
+| -------------------------- | -------------- |
+| `path/to/existing/file.ts` | <what changes> |
+
+### Database Changes
+
+- <migrations needed, if any>
+
+### API Changes
+
+- <new/modified endpoints, if any>
+
+### UI Changes
+
+- <new/modified pages/components, if any>
+
+## ⚙️ Implementation Effort
+
+- **Estimated complexity**: Low / Medium / High / Very High
+- **Estimated files changed**: ~N
+- **Dependencies needed**: <new npm packages, if any>
+- **Breaking changes**: Yes/No — <details>
+- **i18n impact**: <number of new translation keys>
+- **Test coverage needed**: <brief description>
+
+## ⚠️ Open Questions
+
+- <question 1>
+- <question 2>
+
+## 🔗 External References
+
+- <documentation URLs>
+- <API references>
+```
+
+---
+
+## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
+
+### 2.5.1 Create Directory Structure
+
+// turbo
+
+```bash
+mkdir -p <project_root>/_ideia/viable
+mkdir -p <project_root>/_ideia/viable/need_details
+mkdir -p <project_root>/_ideia/defer
+mkdir -p <project_root>/_ideia/notfit
+```
+
+### 2.5.2 Move Idea Files to Category Subdirectories
+
+After classification, move EVERY idea file to its correct subdirectory:
+
+```bash
+# ✅ VIABLE — move idea + requirements files
+mv _ideia/<NUMBER>-*.md _ideia/viable/
+mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
+
+# ❓ NEEDS DETAIL — viable but waiting for author response
+mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
+
+# ⏭️ DEFER — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/defer/
+
+# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/notfit/
+```
+
+No files should remain in `_ideia/` root after this step (except subdirectories).
+
+### 2.5.3 Post GitHub Comments by Category
+
+**Each category has a specific comment template and action:**
+
+---
+
+#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
+
+// turbo
+
+The feature already exists in the system. Explain WHERE it is and HOW to use it.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+Great news — this functionality **already exists** in OmniRoute:
+
+**📍 Where to find it:** <exact dashboard path or settings location>
+
+**🔧 How to use it:**
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
+
+Closing this as the feature is already available. 🎉
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ⏭️ DEFER — Comment + CLOSE issue
+
+// turbo
+
+Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
+
+```markdown
+Hi @<author>! Thanks for this thoughtful feature request! 🙏
+
+We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
+
+Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
+
+**What happens next:**
+
+- Your idea is saved in our internal feature backlog
+- We'll conduct architecture studies when this area is prioritized
+- We'll notify you here when development begins
+
+Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❌ NOT FIT — Comment + CLOSE issue
+
+// turbo
+
+Politely explain why the feature doesn't fit the project scope.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
+
+**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
+
+**Alternative:** <suggest an alternative approach if possible>
+
+We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
+
+// turbo
+
+Ask for the specific missing details needed.
+
+```markdown
+Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
+
+To move forward, we need a few more details:
+
+1. <specific question 1>
+2. <specific question 2>
+3. <specific question 3>
+
+If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
+
+Looking forward to your response! 🚀
+```
+
+---
+
+#### For ✅ VIABLE — Comment (keep OPEN)
+
+// turbo
+
+Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
+
+```markdown
+Hi @<author>! Thanks for the great feature suggestion! 🙏
+
+We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
+
+**Status:** 📋 Cataloged for future implementation
+
+This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
+
+Thank you for helping improve OmniRoute! 🚀
+```
+
+**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
+
+---
+
+## Phase 3 — Report: Present Findings to User
+
+### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
+
+After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
+
+Present a structured report containing:
+
+#### 3.1a — Feature Summary Table
+
+| #   | Issue | Title | Verdict         | Location                      | Action                        |
+| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
+| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
+| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
+| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
+| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
+| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
+
+#### 3.1b — Viable Features Detail
+
+For each VIABLE feature, provide a brief paragraph:
+
+- What was found during research
+- The proposed approach
+- Key risks or unknowns
+- Which reference repositories were most useful
+
+#### 3.1c — Issues Requiring Author Feedback
+
+For features marked ❓ NEEDS DETAIL, list:
+
+- What specific information is missing
+- What examples or repository references would help
+
+#### 3.1d — Ask for User Confirmation
+
+End the report with:
+
+> **Ready to proceed with implementation?**
+>
+> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
+> - Reply with specific issue numbers to select only certain features.
+> - Reply **"não"** or **"no"** to stop here.
+
+---
+
+## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
+
+### 4.1 Create Task Directory
+
+```bash
+mkdir -p <project_root>/_tasks/features-vX.Y.Z/
+```
+
+### 4.2 Generate One Implementation Plan Per Feature
+
+For each VIABLE feature approved by the user, create:
+
+**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
+
+```markdown
+# Implementation Plan: <Feature Title>
+
+> Issue: #<NUMBER>
+> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
+> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
+> Branch: `release/vX.Y.Z`
+
+## Overview
+
+<Brief description of what will be built>
+
+## Pre-Implementation Checklist
+
+- [ ] Read all related source files listed below
+- [ ] Confirm no conflicts with in-flight PRs
+- [ ] Verify database migration numbering
+
+## Implementation Steps
+
+### Step 1: <Title>
+
+**Files:**
+
+- `path/to/file.ts` — <what to change>
+
+**Details:**
+<Detailed description of the change, including code patterns to follow, function signatures, etc.>
+
+### Step 2: <Title>
+
+...
+
+### Step N: Tests
+
+**New test files:**
+
+- `tests/unit/<test-file>.test.mjs` — <what to test>
+
+**Test cases:**
+
+- [ ] <test case 1>
+- [ ] <test case 2>
+
+### Step N+1: i18n
+
+**Translation keys to add:**
+
+- `<namespace>.<key>` — "<English value>"
+
+### Step N+2: Documentation
+
+- [ ] Update CHANGELOG.md
+- [ ] Update relevant docs/ files
+
+## Verification Plan
+
+1. Run `npm run build` — must pass
+2. Run `npm test` — all tests must pass
+3. Run `npm run lint` — no new errors
+4. <Manual verification steps>
+
+## Commit Plan
+```
+
+feat: <description> (#<NUMBER>)
+
+```
+
+```
+
+### 4.3 Present Plans for Final Approval
+
+Present a summary of all generated plans:
+
+> **Implementation plans generated:**
+>
+> | #   | Feature | Plan File                                | Steps   | Effort |
+> | --- | ------- | ---------------------------------------- | ------- | ------ |
+> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
+>
+> Reply **"sim"** or **"yes"** to begin implementation of all features.
+> Reply with specific issue numbers to implement only certain ones.
+
+---
+
+## Phase 5 — Execute: Implement the Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
+
+### 5.1 Implement Each Feature
+
+For each approved plan, execute it step by step:
+
+1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
+2. **Build** — Run `npm run build` after each feature to verify compilation
+3. **Test** — Run `npm test` to ensure no regressions
+4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+5. **Update the plan** — Mark completed steps with `[x]` in the plan file
+6. **Continue** — Move to the next feature (do NOT switch branches)
+
+### 5.2 Respond to Authors (Update Viable Issues)
+
+For each implemented feature, **close the issue with a final comment**:
+
+````markdown
+✅ **Implemented in `release/vX.Y.Z`!**
+
+Hi @<author>! Great news — your feature request has been implemented! 🎉
+
+**What was done:**
+
+- <bullet list of what was built>
+
+**How to try it:**
+
+```bash
+git fetch origin && git checkout release/vX.Y.Z
+npm install && npm run dev
+```
+````
+
+This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
+
+````
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+````
+
+Then **DELETE the idea file** — it has served its purpose:
+
+```bash
+# ✅ Implemented files are DELETED (not moved)
+rm _ideia/viable/<NUMBER>-<title>.md
+rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
+```
+
+> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
+
+### 5.3 Finalize & Push
+
+After implementing all approved features:
+
+1. **Update CHANGELOG.md** on the release branch with all new feature entries
+2. Push the release branch: `git push origin release/vX.Y.Z`
+3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+
+### 5.4 Final Summary Report
+
+Present a final summary report to the user:
+
+| Issue | Title | Verdict         | Action                                             | Commit    |
+| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
+| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
+| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
+| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
+
+Include:
+
+- Total features harvested
+- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
+- Total features implemented (idea files deleted, issues closed)
+- Total features deferred
+- Total issues closed
+- Total issues left open (needs detail only — viable are closed after implementation)
+- Test results (pass/fail count)

.agents/workflows/implement-features-ag.md

@@ -0,0 +1,706 @@
+---
+description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
+---
+
+# /implement-features — Feature Request Harvest, Research & Implementation Workflow
+
+## Overview
+
+A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
+
+**Output directory structure:**
+
+```
+_ideia/
+├── viable/                  # Features approved for implementation
+│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
+│   │   └── 1015-warp-terminal-mitm.md
+│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
+│   └── 1046-native-playground.requirements.md
+├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
+│   └── 1041-smart-auto-combos.md
+└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
+    └── 945-telegram-integration.md
+
+_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
+└── 1046-native-playground.plan.md
+```
+
+> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
+
+> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
+
+---
+
+## Phase 1 — Harvest: Collect & Catalog Feature Ideas
+
+### 1.1 Identify the Repository
+
+// turbo
+
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
+
+### 1.2 Ensure Release Branch Exists
+
+// turbo
+
+Before doing any work, ensure you are on the current release branch:
+
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 1.3 Fetch ALL Open Feature Requests
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
+
+**Step 1 — Get Issue numbers only** (small output, never truncated):
+
+```bash
+# Fetch issues with feature/enhancement labels
+gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
+
+# Also check for [Feature] in title (common pattern when no labels are set)
+gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
+```
+
+- Merge both lists, deduplicate. Count and confirm the total.
+
+**Step 2 — Fetch full metadata for each Issue** (one call per issue):
+
+```bash
+gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
+```
+
+- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
+- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
+- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
+
+### 1.4 Create Idea Files (initially in `_ideia/` root)
+
+For each feature request, create a structured idea file in `<project_root>/_ideia/`:
+
+**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
+Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
+
+#### 1.4a — If the idea file does NOT exist yet, create it:
+
+```markdown
+# Feature: <Title from Issue>
+
+> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
+> Status: 📋 Cataloged | Priority: TBD
+
+## 📝 Original Request
+
+<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
+
+## 💬 Community Discussion
+
+<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
+
+### Participants
+
+- @<author> — Original requester
+- @<commenter1> — <brief role/opinion>
+- ...
+
+### Key Points
+
+- <bullet list of the most important discussion points>
+- <agreements reached>
+- <objections raised>
+
+## 🎯 Refined Feature Description
+
+<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
+
+### What it solves
+
+- <problem 1>
+- <problem 2>
+
+### How it should work (high level)
+
+1. <step 1>
+2. <step 2>
+3. ...
+
+### Affected areas
+
+- <list of codebase areas, modules, files likely affected>
+
+## 📎 Attachments & References
+
+- <any image URLs, mockup links, or external references from the issue>
+
+## 🔗 Related Ideas
+
+- <links to related \_ideia/ files if any overlap found>
+```
+
+#### 1.4b — If the idea file ALREADY exists, update it:
+
+- Append new comments from the issue to the **Community Discussion** section.
+- Update the **Refined Feature Description** if new information changes the understanding.
+- Add any new **Related Ideas** cross-references found.
+- **Do NOT overwrite** existing content — append and enrich it.
+
+### 1.5 Cross-Reference & Deduplication
+
+After processing all issues:
+
+- Scan all `_ideia/*.md` files for overlapping features.
+- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
+- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
+
+---
+
+## Phase 2 — Research: Find Solutions & Build Requirements
+
+For each cataloged idea that is **viable** (aligns with the project's goals):
+
+### 2.1 Viability Pre-Check
+
+Before investing in research, quickly assess:
+
+- [ ] Does this feature align with the project's goals and architecture?
+- [ ] Is it technically feasible with the current codebase?
+- [ ] Does it duplicate existing functionality?
+- [ ] Would it introduce breaking changes or security risks?
+- [ ] Is there enough detail to understand what's needed?
+
+**Verdict options:**
+
+| Verdict               | When                                  | Action                      |
+| --------------------- | ------------------------------------- | --------------------------- |
+| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
+| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
+| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
+| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
+| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
+
+### 2.2 Internet Research (for VIABLE features)
+
+For each viable feature, perform systematic research:
+
+**Step 1 — Web search for similar implementations:**
+
+```
+WebSearch("how to implement <feature description> in <tech stack>")
+WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
+WebSearch("<feature keyword> open source library npm")
+```
+
+**Step 2 — Find reference Git repositories:**
+
+```
+WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
+WebSearch("github <feature keyword> implementation recently updated 2026")
+```
+
+- Find **up to 10 relevant repositories**, sorted by most recently updated.
+- For each repository:
+  - Note the repo URL, star count, last commit date
+  - Read its README and relevant source files via `WebFetch`
+  - Extract the architectural approach, patterns used, and key code snippets
+
+**Step 3 — Read API docs and standards:**
+
+If the feature involves an external API, protocol, or standard:
+
+- Find and read the official documentation
+- Note version requirements, authentication patterns, rate limits
+
+### 2.3 Create Requirements File
+
+For each researched feature, create a requirements file alongside its idea file:
+
+**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
+
+```markdown
+# Requirements: <Feature Title>
+
+> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
+> Research Date: <YYYY-MM-DD>
+> Verdict: ✅ VIABLE
+
+## 🔍 Research Summary
+
+<Brief summary of what was found during research>
+
+## 📚 Reference Implementations
+
+| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
+| --- | ---------------- | ----- | ------------ | -------- | ------------ |
+| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
+| 2   | ...              |       |              |          |              |
+
+### Key Patterns Found
+
+- <pattern 1 with code snippet or link>
+- <pattern 2>
+
+## 📐 Proposed Solution Architecture
+
+### Approach
+
+<Describe the chosen approach based on research findings>
+
+### New Files
+
+| File                  | Purpose       |
+| --------------------- | ------------- |
+| `path/to/new/file.ts` | <description> |
+
+### Modified Files
+
+| File                       | Changes        |
+| -------------------------- | -------------- |
+| `path/to/existing/file.ts` | <what changes> |
+
+### Database Changes
+
+- <migrations needed, if any>
+
+### API Changes
+
+- <new/modified endpoints, if any>
+
+### UI Changes
+
+- <new/modified pages/components, if any>
+
+## ⚙️ Implementation Effort
+
+- **Estimated complexity**: Low / Medium / High / Very High
+- **Estimated files changed**: ~N
+- **Dependencies needed**: <new npm packages, if any>
+- **Breaking changes**: Yes/No — <details>
+- **i18n impact**: <number of new translation keys>
+- **Test coverage needed**: <brief description>
+
+## ⚠️ Open Questions
+
+- <question 1>
+- <question 2>
+
+## 🔗 External References
+
+- <documentation URLs>
+- <API references>
+```
+
+---
+
+## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
+
+### 2.5.1 Create Directory Structure
+
+// turbo
+
+```bash
+mkdir -p <project_root>/_ideia/viable
+mkdir -p <project_root>/_ideia/viable/need_details
+mkdir -p <project_root>/_ideia/defer
+mkdir -p <project_root>/_ideia/notfit
+```
+
+### 2.5.2 Move Idea Files to Category Subdirectories
+
+After classification, move EVERY idea file to its correct subdirectory:
+
+```bash
+# ✅ VIABLE — move idea + requirements files
+mv _ideia/<NUMBER>-*.md _ideia/viable/
+mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
+
+# ❓ NEEDS DETAIL — viable but waiting for author response
+mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
+
+# ⏭️ DEFER — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/defer/
+
+# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/notfit/
+```
+
+No files should remain in `_ideia/` root after this step (except subdirectories).
+
+### 2.5.3 Post GitHub Comments by Category
+
+**Each category has a specific comment template and action:**
+
+---
+
+#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
+
+// turbo
+
+The feature already exists in the system. Explain WHERE it is and HOW to use it.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+Great news — this functionality **already exists** in OmniRoute:
+
+**📍 Where to find it:** <exact dashboard path or settings location>
+
+**🔧 How to use it:**
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
+
+Closing this as the feature is already available. 🎉
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ⏭️ DEFER — Comment + CLOSE issue
+
+// turbo
+
+Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
+
+```markdown
+Hi @<author>! Thanks for this thoughtful feature request! 🙏
+
+We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
+
+Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
+
+**What happens next:**
+
+- Your idea is saved in our internal feature backlog
+- We'll conduct architecture studies when this area is prioritized
+- We'll notify you here when development begins
+
+Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❌ NOT FIT — Comment + CLOSE issue
+
+// turbo
+
+Politely explain why the feature doesn't fit the project scope.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
+
+**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
+
+**Alternative:** <suggest an alternative approach if possible>
+
+We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
+
+// turbo
+
+Ask for the specific missing details needed.
+
+```markdown
+Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
+
+To move forward, we need a few more details:
+
+1. <specific question 1>
+2. <specific question 2>
+3. <specific question 3>
+
+If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
+
+Looking forward to your response! 🚀
+```
+
+---
+
+#### For ✅ VIABLE — Comment (keep OPEN)
+
+// turbo
+
+Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
+
+```markdown
+Hi @<author>! Thanks for the great feature suggestion! 🙏
+
+We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
+
+**Status:** 📋 Cataloged for future implementation
+
+This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
+
+Thank you for helping improve OmniRoute! 🚀
+```
+
+**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
+
+---
+
+## Phase 3 — Report: Present Findings to User
+
+### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
+
+After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
+
+Present a structured report containing:
+
+#### 3.1a — Feature Summary Table
+
+| #   | Issue | Title | Verdict         | Location                      | Action                        |
+| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
+| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
+| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
+| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
+| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
+| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
+
+#### 3.1b — Viable Features Detail
+
+For each VIABLE feature, provide a brief paragraph:
+
+- What was found during research
+- The proposed approach
+- Key risks or unknowns
+- Which reference repositories were most useful
+
+#### 3.1c — Issues Requiring Author Feedback
+
+For features marked ❓ NEEDS DETAIL, list:
+
+- What specific information is missing
+- What examples or repository references would help
+
+#### 3.1d — Ask for User Confirmation
+
+End the report with:
+
+> **Ready to proceed with implementation?**
+>
+> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
+> - Reply with specific issue numbers to select only certain features.
+> - Reply **"não"** or **"no"** to stop here.
+
+---
+
+## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
+
+### 4.1 Create Task Directory
+
+```bash
+mkdir -p <project_root>/_tasks/features-vX.Y.Z/
+```
+
+### 4.2 Generate One Implementation Plan Per Feature
+
+For each VIABLE feature approved by the user, create:
+
+**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
+
+```markdown
+# Implementation Plan: <Feature Title>
+
+> Issue: #<NUMBER>
+> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
+> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
+> Branch: `release/vX.Y.Z`
+
+## Overview
+
+<Brief description of what will be built>
+
+## Pre-Implementation Checklist
+
+- [ ] Read all related source files listed below
+- [ ] Confirm no conflicts with in-flight PRs
+- [ ] Verify database migration numbering
+
+## Implementation Steps
+
+### Step 1: <Title>
+
+**Files:**
+
+- `path/to/file.ts` — <what to change>
+
+**Details:**
+<Detailed description of the change, including code patterns to follow, function signatures, etc.>
+
+### Step 2: <Title>
+
+...
+
+### Step N: Tests
+
+**New test files:**
+
+- `tests/unit/<test-file>.test.mjs` — <what to test>
+
+**Test cases:**
+
+- [ ] <test case 1>
+- [ ] <test case 2>
+
+### Step N+1: i18n
+
+**Translation keys to add:**
+
+- `<namespace>.<key>` — "<English value>"
+
+### Step N+2: Documentation
+
+- [ ] Update CHANGELOG.md
+- [ ] Update relevant docs/ files
+
+## Verification Plan
+
+1. Run `npm run build` — must pass
+2. Run `npm test` — all tests must pass
+3. Run `npm run lint` — no new errors
+4. <Manual verification steps>
+
+## Commit Plan
+```
+
+feat: <description> (#<NUMBER>)
+
+```
+
+```
+
+### 4.3 Present Plans for Final Approval
+
+Present a summary of all generated plans:
+
+> **Implementation plans generated:**
+>
+> | #   | Feature | Plan File                                | Steps   | Effort |
+> | --- | ------- | ---------------------------------------- | ------- | ------ |
+> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
+>
+> Reply **"sim"** or **"yes"** to begin implementation of all features.
+> Reply with specific issue numbers to implement only certain ones.
+
+---
+
+## Phase 5 — Execute: Implement the Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
+
+### 5.1 Implement Each Feature
+
+For each approved plan, execute it step by step:
+
+1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
+2. **Build** — Run `npm run build` after each feature to verify compilation
+3. **Test** — Run `npm test` to ensure no regressions
+4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+5. **Update the plan** — Mark completed steps with `[x]` in the plan file
+6. **Continue** — Move to the next feature (do NOT switch branches)
+
+### 5.2 Respond to Authors (Update Viable Issues)
+
+For each implemented feature, **close the issue with a final comment**:
+
+````markdown
+✅ **Implemented in `release/vX.Y.Z`!**
+
+Hi @<author>! Great news — your feature request has been implemented! 🎉
+
+**What was done:**
+
+- <bullet list of what was built>
+
+**How to try it:**
+
+```bash
+git fetch origin && git checkout release/vX.Y.Z
+npm install && npm run dev
+```
+````
+
+This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
+
+````
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+````
+
+Then **DELETE the idea file** — it has served its purpose:
+
+```bash
+# ✅ Implemented files are DELETED (not moved)
+rm _ideia/viable/<NUMBER>-<title>.md
+rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
+```
+
+> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
+
+### 5.3 Finalize & Push
+
+After implementing all approved features:
+
+1. **Update CHANGELOG.md** on the release branch with all new feature entries
+2. Push the release branch: `git push origin release/vX.Y.Z`
+3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+
+### 5.4 Final Summary Report
+
+Present a final summary report to the user:
+
+| Issue | Title | Verdict         | Action                                             | Commit    |
+| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
+| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
+| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
+| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
+
+Include:
+
+- Total features harvested
+- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
+- Total features implemented (idea files deleted, issues closed)
+- Total features deferred
+- Total issues closed
+- Total issues left open (needs detail only — viable are closed after implementation)
+- Test results (pass/fail count)

.claude/commands/implement-features-cc.md

@@ -0,0 +1,706 @@
+---
+description: Analyze open feature request issues, implement viable ones on dedicated branches, and respond to authors
+---
+
+# /implement-features — Feature Request Harvest, Research & Implementation Workflow
+
+## Overview
+
+A **5-phase** workflow that systematically harvests feature requests from GitHub issues, creates structured idea files, researches solutions across the internet and Git repositories, presents a consolidated report for user approval, then generates detailed implementation plans and executes them.
+
+**Output directory structure:**
+
+```
+_ideia/
+├── viable/                  # Features approved for implementation
+│   ├── need_details/        # ❓ Good idea but waiting for author clarification (issues stay OPEN)
+│   │   └── 1015-warp-terminal-mitm.md
+│   ├── 1046-native-playground.md           # ✅ Ready — researched and planned
+│   └── 1046-native-playground.requirements.md
+├── defer/                   # ⏭️ Good ideas deferred for future cycles (issues CLOSED)
+│   └── 1041-smart-auto-combos.md
+└── notfit/                  # ❌ Out of scope / already exists (issues CLOSED)
+    └── 945-telegram-integration.md
+
+_tasks/features-vX.Y.Z/   # Implementation plans (per-release)
+└── 1046-native-playground.plan.md
+```
+
+> **LIFECYCLE RULE:** `viable/` files are **DELETED** once the feature is implemented — they are not moved. Only unimplemented features live in `viable/` (or `viable/need_details/`). Files in `defer/` and `notfit/` remain as permanent reference.
+
+> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, create one first using `/generate-release` Phase 1 steps 1–5.
+
+---
+
+## Phase 1 — Harvest: Collect & Catalog Feature Ideas
+
+### 1.1 Identify the Repository
+
+// turbo
+
+- Run: `git -C <project_root> remote get-url origin` to extract owner/repo.
+
+### 1.2 Ensure Release Branch Exists
+
+// turbo
+
+Before doing any work, ensure you are on the current release branch:
+
+```bash
+# Check current branch
+git branch --show-current
+
+# If on main, determine next version and create the release branch
+VERSION=$(node -p "require('./package.json').version")
+NEXT=$(node -p "const [a,b,c]=('$VERSION').split('.').map(Number); c>=9?a+'.'+(b+1)+'.0':a+'.'+b+'.'+(c+1)")
+git checkout -b release/v$NEXT
+npm version patch --no-git-tag-version
+npm install
+```
+
+If already on a `release/vX.Y.Z` branch, continue working there.
+
+### 1.3 Fetch ALL Open Feature Requests
+
+// turbo-all
+
+**⚠️ CRITICAL**: The JSON output of `gh issue list` can be truncated by the tool, silently hiding issues. You MUST use the two-step approach below.
+
+**Step 1 — Get Issue numbers only** (small output, never truncated):
+
+```bash
+# Fetch issues with feature/enhancement labels
+gh issue list --repo <owner>/<repo> --state open -l "enhancement" --limit 500 --json number --jq '.[].number'
+
+# Also check for [Feature] in title (common pattern when no labels are set)
+gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,title --jq '.[] | select(.title | test("\\[Feature\\]|\\[feature\\]|feature request"; "i")) | .number'
+```
+
+- Merge both lists, deduplicate. Count and confirm the total.
+
+**Step 2 — Fetch full metadata for each Issue** (one call per issue):
+
+```bash
+gh issue view <NUMBER> --repo <owner>/<repo> --json number,title,labels,body,comments,createdAt,author,assignees
+```
+
+- Read the **entire body** — including description, use cases, screenshots, mockups, and any embedded images.
+- Read **ALL comments** — community discussion, agreements, restrictions, owner responses, and linked PRs.
+- **Images**: If the body or comments contain image URLs (`![...](...)` or `https://...png/jpg/gif`), note them — they may contain UI mockups, wireframes, or architecture diagrams that are essential to understanding the request.
+- You may batch these into parallel calls (up to 4 at a time).
+- Sort by oldest first (FIFO).
+
+### 1.4 Create Idea Files (initially in `_ideia/` root)
+
+For each feature request, create a structured idea file in `<project_root>/_ideia/`:
+
+**Filename convention**: `<NUMBER>-<kebab-case-short-title>.md`
+Example: `1046-native-playground.md`, `1041-smart-auto-combos.md`
+
+#### 1.4a — If the idea file does NOT exist yet, create it:
+
+```markdown
+# Feature: <Title from Issue>
+
+> GitHub Issue: #<NUMBER> — opened by @<author> on <date>
+> Status: 📋 Cataloged | Priority: TBD
+
+## 📝 Original Request
+
+<Paste the FULL issue body here, preserving all formatting, images, and code blocks>
+
+## 💬 Community Discussion
+
+<Summarize ALL comments chronologically, noting who said what and any decisions or objections raised>
+
+### Participants
+
+- @<author> — Original requester
+- @<commenter1> — <brief role/opinion>
+- ...
+
+### Key Points
+
+- <bullet list of the most important discussion points>
+- <agreements reached>
+- <objections raised>
+
+## 🎯 Refined Feature Description
+
+<YOUR interpretation and enrichment of the feature request. Expand on what was asked, fill in logical gaps, provide concrete examples of how it would work. This section should be MORE detailed and clearer than the original request.>
+
+### What it solves
+
+- <problem 1>
+- <problem 2>
+
+### How it should work (high level)
+
+1. <step 1>
+2. <step 2>
+3. ...
+
+### Affected areas
+
+- <list of codebase areas, modules, files likely affected>
+
+## 📎 Attachments & References
+
+- <any image URLs, mockup links, or external references from the issue>
+
+## 🔗 Related Ideas
+
+- <links to related \_ideia/ files if any overlap found>
+```
+
+#### 1.4b — If the idea file ALREADY exists, update it:
+
+- Append new comments from the issue to the **Community Discussion** section.
+- Update the **Refined Feature Description** if new information changes the understanding.
+- Add any new **Related Ideas** cross-references found.
+- **Do NOT overwrite** existing content — append and enrich it.
+
+### 1.5 Cross-Reference & Deduplication
+
+After processing all issues:
+
+- Scan all `_ideia/*.md` files for overlapping features.
+- If two features are substantially the same, add `🔗 Related Ideas` cross-references to both.
+- If one is a strict subset of another, note it in the smaller file: `> ℹ️ This feature is a subset of #<OTHER_NUMBER>. Consider implementing together.`
+
+---
+
+## Phase 2 — Research: Find Solutions & Build Requirements
+
+For each cataloged idea that is **viable** (aligns with the project's goals):
+
+### 2.1 Viability Pre-Check
+
+Before investing in research, quickly assess:
+
+- [ ] Does this feature align with the project's goals and architecture?
+- [ ] Is it technically feasible with the current codebase?
+- [ ] Does it duplicate existing functionality?
+- [ ] Would it introduce breaking changes or security risks?
+- [ ] Is there enough detail to understand what's needed?
+
+**Verdict options:**
+
+| Verdict               | When                                  | Action                      |
+| --------------------- | ------------------------------------- | --------------------------- |
+| ✅ **VIABLE**         | Good idea, enough context             | Proceed to Research         |
+| ❓ **NEEDS DETAIL**   | Good idea, insufficient spec          | Skip research, ask author   |
+| ⏭️ **DEFER**          | Good idea, too complex for this cycle | Catalog only, skip research |
+| ❌ **NOT FIT**        | Doesn't fit the project               | Explain why                 |
+| 🔁 **ALREADY EXISTS** | Feature already implemented           | Point to existing feature   |
+
+### 2.2 Internet Research (for VIABLE features)
+
+For each viable feature, perform systematic research:
+
+**Step 1 — Web search for similar implementations:**
+
+```
+WebSearch("how to implement <feature description> in <tech stack>")
+WebSearch("<feature keyword> implementation nextjs typescript 2025 2026")
+WebSearch("<feature keyword> open source library npm")
+```
+
+**Step 2 — Find reference Git repositories:**
+
+```
+WebSearch("site:github.com <feature keyword> <tech stack> stars:>100")
+WebSearch("github <feature keyword> implementation recently updated 2026")
+```
+
+- Find **up to 10 relevant repositories**, sorted by most recently updated.
+- For each repository:
+  - Note the repo URL, star count, last commit date
+  - Read its README and relevant source files via `WebFetch`
+  - Extract the architectural approach, patterns used, and key code snippets
+
+**Step 3 — Read API docs and standards:**
+
+If the feature involves an external API, protocol, or standard:
+
+- Find and read the official documentation
+- Note version requirements, authentication patterns, rate limits
+
+### 2.3 Create Requirements File
+
+For each researched feature, create a requirements file alongside its idea file:
+
+**Filename**: `<NUMBER>-<kebab-case-short-title>.requirements.md`
+
+```markdown
+# Requirements: <Feature Title>
+
+> Feature Idea: [#<NUMBER>](./<NUMBER>-<kebab-case-short-title>.md)
+> Research Date: <YYYY-MM-DD>
+> Verdict: ✅ VIABLE
+
+## 🔍 Research Summary
+
+<Brief summary of what was found during research>
+
+## 📚 Reference Implementations
+
+| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
+| --- | ---------------- | ----- | ------------ | -------- | ------------ |
+| 1   | [repo/name](url) | ⭐ N  | YYYY-MM-DD   | <brief>  | High/Med/Low |
+| 2   | ...              |       |              |          |              |
+
+### Key Patterns Found
+
+- <pattern 1 with code snippet or link>
+- <pattern 2>
+
+## 📐 Proposed Solution Architecture
+
+### Approach
+
+<Describe the chosen approach based on research findings>
+
+### New Files
+
+| File                  | Purpose       |
+| --------------------- | ------------- |
+| `path/to/new/file.ts` | <description> |
+
+### Modified Files
+
+| File                       | Changes        |
+| -------------------------- | -------------- |
+| `path/to/existing/file.ts` | <what changes> |
+
+### Database Changes
+
+- <migrations needed, if any>
+
+### API Changes
+
+- <new/modified endpoints, if any>
+
+### UI Changes
+
+- <new/modified pages/components, if any>
+
+## ⚙️ Implementation Effort
+
+- **Estimated complexity**: Low / Medium / High / Very High
+- **Estimated files changed**: ~N
+- **Dependencies needed**: <new npm packages, if any>
+- **Breaking changes**: Yes/No — <details>
+- **i18n impact**: <number of new translation keys>
+- **Test coverage needed**: <brief description>
+
+## ⚠️ Open Questions
+
+- <question 1>
+- <question 2>
+
+## 🔗 External References
+
+- <documentation URLs>
+- <API references>
+```
+
+---
+
+## Phase 2.5 — Organize & Respond: Sort Files and Post GitHub Comments
+
+### 2.5.1 Create Directory Structure
+
+// turbo
+
+```bash
+mkdir -p <project_root>/_ideia/viable
+mkdir -p <project_root>/_ideia/viable/need_details
+mkdir -p <project_root>/_ideia/defer
+mkdir -p <project_root>/_ideia/notfit
+```
+
+### 2.5.2 Move Idea Files to Category Subdirectories
+
+After classification, move EVERY idea file to its correct subdirectory:
+
+```bash
+# ✅ VIABLE — move idea + requirements files
+mv _ideia/<NUMBER>-*.md _ideia/viable/
+mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
+
+# ❓ NEEDS DETAIL — viable but waiting for author response
+mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
+
+# ⏭️ DEFER — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/defer/
+
+# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
+mv _ideia/<NUMBER>-*.md _ideia/notfit/
+```
+
+No files should remain in `_ideia/` root after this step (except subdirectories).
+
+### 2.5.3 Post GitHub Comments by Category
+
+**Each category has a specific comment template and action:**
+
+---
+
+#### For 🔁 ALREADY EXISTS — Comment + CLOSE issue
+
+// turbo
+
+The feature already exists in the system. Explain WHERE it is and HOW to use it.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+Great news — this functionality **already exists** in OmniRoute:
+
+**📍 Where to find it:** <exact dashboard path or settings location>
+
+**🔧 How to use it:**
+
+1. <step 1>
+2. <step 2>
+3. <step 3>
+
+If you have any trouble finding or using it, feel free to ask in a Discussion. We're always happy to help!
+
+Closing this as the feature is already available. 🎉
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ⏭️ DEFER — Comment + CLOSE issue
+
+// turbo
+
+Thank the user, explain the idea was cataloged, and that we'll study it before implementing.
+
+```markdown
+Hi @<author>! Thanks for this thoughtful feature request! 🙏
+
+We really appreciate the detailed proposal. We've **cataloged your idea** and it's now part of our improvement backlog.
+
+Due to the **significant architectural impact** of this feature, we'll need to conduct thorough use-case studies and architectural analysis before we start development. This ensures we build it right and don't introduce regressions.
+
+**What happens next:**
+
+- Your idea is saved in our internal feature backlog
+- We'll conduct architecture studies when this area is prioritized
+- We'll notify you here when development begins
+
+Thank you for contributing to OmniRoute's roadmap! Your input helps shape the product. 🚀
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❌ NOT FIT — Comment + CLOSE issue
+
+// turbo
+
+Politely explain why the feature doesn't fit the project scope.
+
+```markdown
+Hi @<author>! Thanks for the suggestion! 🙏
+
+After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
+
+**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
+
+**Alternative:** <suggest an alternative approach if possible>
+
+We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
+```
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+```
+
+---
+
+#### For ❓ NEEDS DETAIL — Comment (keep OPEN)
+
+// turbo
+
+Ask for the specific missing details needed.
+
+```markdown
+Hi @<author>! Thanks for the feature request — it's an interesting idea and we'd love to explore it further. 🙏
+
+To move forward, we need a few more details:
+
+1. <specific question 1>
+2. <specific question 2>
+3. <specific question 3>
+
+If you know of any **open-source projects or repositories** that implement something similar, please share links — it would help us design the best solution.
+
+Looking forward to your response! 🚀
+```
+
+---
+
+#### For ✅ VIABLE — Comment (keep OPEN)
+
+// turbo
+
+Thank the user, confirm we've cataloged their idea, and explain it may be implemented in future versions.
+
+```markdown
+Hi @<author>! Thanks for the great feature suggestion! 🙏
+
+We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
+
+**Status:** 📋 Cataloged for future implementation
+
+This feature may be included in upcoming releases. We'll **respond to this issue and tag you** as soon as implementation begins so you can test it.
+
+Thank you for helping improve OmniRoute! 🚀
+```
+
+**⚠️ Do NOT close viable issues — they remain OPEN for tracking.**
+
+---
+
+## Phase 3 — Report: Present Findings to User
+
+### 3.1 🛑 MANDATORY STOP — Present Consolidated Report
+
+After completing Phase 1, Phase 2, and Phase 2.5, **STOP and present the following report** in the chat. Do NOT proceed to implementation.
+
+Present a structured report containing:
+
+#### 3.1a — Feature Summary Table
+
+| #   | Issue | Title | Verdict         | Location                      | Action                        |
+| --- | ----- | ----- | --------------- | ----------------------------- | ----------------------------- |
+| 1   | #N    | Title | ✅ VIABLE       | `_ideia/viable/`              | Issue OPEN, comment posted    |
+| 2   | #N    | Title | ⏭️ DEFER        | `_ideia/defer/`               | Issue CLOSED with explanation |
+| 3   | #N    | Title | ❌ NOT FIT      | `_ideia/notfit/`              | Issue CLOSED with explanation |
+| 4   | #N    | Title | 🔁 EXISTS       | `_ideia/notfit/`              | Issue CLOSED with guidance    |
+| 5   | #N    | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Issue OPEN, questions posted  |
+
+#### 3.1b — Viable Features Detail
+
+For each VIABLE feature, provide a brief paragraph:
+
+- What was found during research
+- The proposed approach
+- Key risks or unknowns
+- Which reference repositories were most useful
+
+#### 3.1c — Issues Requiring Author Feedback
+
+For features marked ❓ NEEDS DETAIL, list:
+
+- What specific information is missing
+- What examples or repository references would help
+
+#### 3.1d — Ask for User Confirmation
+
+End the report with:
+
+> **Ready to proceed with implementation?**
+>
+> - Reply **"sim"** or **"yes"** to generate full implementation plans for all VIABLE features.
+> - Reply with specific issue numbers to select only certain features.
+> - Reply **"não"** or **"no"** to stop here.
+
+---
+
+## Phase 4 — Plan: Generate Implementation Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 3.**
+
+### 4.1 Create Task Directory
+
+```bash
+mkdir -p <project_root>/_tasks/features-vX.Y.Z/
+```
+
+### 4.2 Generate One Implementation Plan Per Feature
+
+For each VIABLE feature approved by the user, create:
+
+**Filename**: `_tasks/features-vX.Y.Z/<NUMBER>-<kebab-case-title>.plan.md`
+
+```markdown
+# Implementation Plan: <Feature Title>
+
+> Issue: #<NUMBER>
+> Idea: [\_ideia/viable/<NUMBER>-title.md](../../_ideia/viable/<NUMBER>-title.md)
+> Requirements: [\_ideia/viable/<NUMBER>-title.requirements.md](../../_ideia/viable/<NUMBER>-title.requirements.md)
+> Branch: `release/vX.Y.Z`
+
+## Overview
+
+<Brief description of what will be built>
+
+## Pre-Implementation Checklist
+
+- [ ] Read all related source files listed below
+- [ ] Confirm no conflicts with in-flight PRs
+- [ ] Verify database migration numbering
+
+## Implementation Steps
+
+### Step 1: <Title>
+
+**Files:**
+
+- `path/to/file.ts` — <what to change>
+
+**Details:**
+<Detailed description of the change, including code patterns to follow, function signatures, etc.>
+
+### Step 2: <Title>
+
+...
+
+### Step N: Tests
+
+**New test files:**
+
+- `tests/unit/<test-file>.test.mjs` — <what to test>
+
+**Test cases:**
+
+- [ ] <test case 1>
+- [ ] <test case 2>
+
+### Step N+1: i18n
+
+**Translation keys to add:**
+
+- `<namespace>.<key>` — "<English value>"
+
+### Step N+2: Documentation
+
+- [ ] Update CHANGELOG.md
+- [ ] Update relevant docs/ files
+
+## Verification Plan
+
+1. Run `npm run build` — must pass
+2. Run `npm test` — all tests must pass
+3. Run `npm run lint` — no new errors
+4. <Manual verification steps>
+
+## Commit Plan
+```
+
+feat: <description> (#<NUMBER>)
+
+```
+
+```
+
+### 4.3 Present Plans for Final Approval
+
+Present a summary of all generated plans:
+
+> **Implementation plans generated:**
+>
+> | #   | Feature | Plan File                                | Steps   | Effort |
+> | --- | ------- | ---------------------------------------- | ------- | ------ |
+> | 1   | <title> | `_tasks/features-vX.Y.Z/N-title.plan.md` | N steps | Medium |
+>
+> Reply **"sim"** or **"yes"** to begin implementation of all features.
+> Reply with specific issue numbers to implement only certain ones.
+
+---
+
+## Phase 5 — Execute: Implement the Plans (after user says "yes")
+
+> **⚠️ Do NOT enter this phase without explicit user approval from Phase 4.**
+
+### 5.1 Implement Each Feature
+
+For each approved plan, execute it step by step:
+
+1. **Follow the plan** — implement exactly as specified in the `.plan.md` file
+2. **Build** — Run `npm run build` after each feature to verify compilation
+3. **Test** — Run `npm test` to ensure no regressions
+4. **Commit** — Commit with: `feat: <description> (#<NUMBER>)`
+5. **Update the plan** — Mark completed steps with `[x]` in the plan file
+6. **Continue** — Move to the next feature (do NOT switch branches)
+
+### 5.2 Respond to Authors (Update Viable Issues)
+
+For each implemented feature, **close the issue with a final comment**:
+
+````markdown
+✅ **Implemented in `release/vX.Y.Z`!**
+
+Hi @<author>! Great news — your feature request has been implemented! 🎉
+
+**What was done:**
+
+- <bullet list of what was built>
+
+**How to try it:**
+
+```bash
+git fetch origin && git checkout release/vX.Y.Z
+npm install && npm run dev
+```
+````
+
+This will be included in the upcoming **vX.Y.Z** release. Feel free to reopen if you spot any issues! 🚀
+
+````
+
+```bash
+gh issue close <NUMBER> --repo <owner>/<repo> --comment "<comment above>"
+````
+
+Then **DELETE the idea file** — it has served its purpose:
+
+```bash
+# ✅ Implemented files are DELETED (not moved)
+rm _ideia/viable/<NUMBER>-<title>.md
+rm _ideia/viable/<NUMBER>-<title>.requirements.md  # if exists
+```
+
+> **Why delete?** `viable/` only holds features that still NEED to be done. Once implemented, the commit history and CHANGELOG are the source of truth. Keeping the file would be confusing.
+
+### 5.3 Finalize & Push
+
+After implementing all approved features:
+
+1. **Update CHANGELOG.md** on the release branch with all new feature entries
+2. Push the release branch: `git push origin release/vX.Y.Z`
+3. Run `/generate-release` workflow Phase 1 steps 7–10 (tests → commit → push → open PR to main → wait for user)
+
+### 5.4 Final Summary Report
+
+Present a final summary report to the user:
+
+| Issue | Title | Verdict         | Action                                             | Commit    |
+| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
+| #N    | Title | ✅ Implemented  | Issue closed, idea file deleted                    | `abc1234` |
+| #N    | Title | ⏭️ Deferred     | Issue closed + saved in `_ideia/defer/`            | —         |
+| #N    | Title | ❌ Not Fit      | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | 🔁 Exists       | Issue closed + saved in `_ideia/notfit/`           | —         |
+| #N    | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | —         |
+
+Include:
+
+- Total features harvested
+- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
+- Total features implemented (idea files deleted, issues closed)
+- Total features deferred
+- Total issues closed
+- Total issues left open (needs detail only — viable are closed after implementation)
+- Test results (pass/fail count)

.env.example

@@ -81,6 +81,10 @@ PORT=20128
 # through the custom dev runner without this on Windows.
 OMNIROUTE_USE_TURBOPACK=1
 
+# Skip the SQLite integrity health check on startup (faster boot on large DBs).
+# Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts. Set to 1 to skip.
+# OMNIROUTE_SKIP_DB_HEALTHCHECK=1
+
 # Docker production port mappings (docker-compose.prod.yml only).
 # These set the HOST-side published ports. Container ports use PORT/API_PORT.
 # PROD_DASHBOARD_PORT=20130
@@ -431,6 +435,10 @@ PROVIDER_LIMITS_SYNC_INTERVAL_MINUTES=70
 # Used by: scripts/postinstall.mjs.
 #OMNIROUTE_SKIP_POSTINSTALL=0
 
+# Skip the DB healthcheck entirely on startup (useful for short-lived tasks / tests).
+# Used by: src/lib/db/core.ts, src/lib/db/healthCheck.ts.  Set to 1 to disable.  Default: 0.
+#OMNIROUTE_SKIP_DB_HEALTHCHECK=0
+
 # Force a DB healthcheck regardless of cadence.  Default: 0.
 # Used by: src/lib/db/core.ts::shouldRunDbHealthCheck().
 #OMNIROUTE_FORCE_DB_HEALTHCHECK=0
@@ -600,7 +608,7 @@ GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 # Used by: open-sse/executors/base.ts — buildHeaders() dynamic lookup.
 # Update these when providers release new CLI versions to avoid blocks.
 
-CLAUDE_USER_AGENT="claude-cli/2.1.145 (external, cli)"
+CLAUDE_USER_AGENT="claude-cli/2.1.146 (external, cli)"
 CODEX_USER_AGENT="codex-cli/0.132.0 (Windows 10.0.26200; x64)"
 GITHUB_USER_AGENT="GitHubCopilotChat/0.45.1"
 ANTIGRAVITY_USER_AGENT="antigravity/2.0.1 linux/arm64 google-api-nodejs-client/10.3.0"
@@ -706,6 +714,13 @@ GEMINI_CLI_USER_AGENT="google-api-nodejs-client/10.3.0"
 # OMNIROUTE_CLAUDE_TLS_TIMEOUT_MS=60000
 # OMNIROUTE_CLAUDE_TLS_GRACE_MS=10000
 
+# ── Perplexity TLS sidecar (Firefox-fingerprinted client) ──
+# Used by: open-sse/services/perplexityTlsClient.ts — wire-level timeout for
+# the bogdanfinn/tls-client koffi binding and the JS-side grace window
+# layered on top of it when the native library is wedged.
+# OMNIROUTE_PPLX_TLS_TIMEOUT_MS=30000
+# OMNIROUTE_PPLX_TLS_GRACE_MS=10000
+
 # ── Circuit breaker thresholds and reset windows ──
 # Used by: open-sse/config/constants.ts → src/lib/resilience/settings.ts.
 # Defaults match historical PROVIDER_PROFILES values (post-scaling for

.github/workflows/build-fork.yml

@@ -1,23 +1,30 @@
-name: Build Fork Image (ghcr.io)
+name: Publish Fork Image to GHCR
 
 on:
   push:
     branches: [main]
+    tags:
+      - "v*"
   workflow_dispatch:
 
 permissions:
   contents: read
   packages: write
 
+env:
+  IMAGE_NAME: ghcr.io/kang-heewon/omniroute
+
 jobs:
   build:
-    name: Build and Push to ghcr.io
+    name: Build and Push Fork Image
+    if: github.repository == 'kang-heewon/OmniRoute'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          ref: main
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -29,14 +36,30 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=sha-
+            type=ref,event=tag
+          labels: |
+            org.opencontainers.image.title=omniroute
+            org.opencontainers.image.description=Unified AI proxy/router — fork image
+            org.opencontainers.image.url=https://github.com/kang-heewon/OmniRoute
+            org.opencontainers.image.source=https://github.com/kang-heewon/OmniRoute
+            org.opencontainers.image.licenses=MIT
+
       - name: Build and push
         uses: docker/build-push-action@v7
         with:
           context: .
           target: runner-base
-          platforms: linux/amd64
+          platforms: linux/amd64,linux/arm64
           push: true
-          tags: |
-            ghcr.io/gi99lin/omniroute:latest
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max

.github/workflows/ci.yml

@@ -39,7 +39,11 @@ jobs:
       - run: npm run check:any-budget:t11
       - run: npm run check:docs-sync
       - run: npm run typecheck:core
+      # typecheck:noimplicit:core is a forward-looking gate (noImplicitAny).
+      # Run informationally for now — many pre-existing call sites still need
+      # explicit annotations; track in a dedicated follow-up.
       - run: npm run typecheck:noimplicit:core
+        continue-on-error: true
 
   docs-sync-strict:
     name: Docs Sync (Strict)
@@ -52,8 +56,8 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:docs-all
-      - name: i18n translation drift (strict)
-        run: node scripts/i18n/check-translation-drift.mjs
+      - name: i18n translation drift (warn)
+        run: node scripts/i18n/check-translation-drift.mjs --warn
 
   i18n-ui-coverage:
     name: i18n UI Coverage
@@ -65,7 +69,7 @@ jobs:
           node-version: ${{ env.CI_NODE_VERSION }}
           cache: npm
       - run: npm ci
-      - run: node scripts/i18n/check-ui-keys-coverage.mjs --threshold=80
+      - run: node scripts/i18n/check-ui-keys-coverage.mjs --threshold=65
 
   i18n-matrix:
     name: Build language matrix
@@ -187,14 +191,14 @@ jobs:
         run: xvfb-run -a npm run electron:smoke:packaged
 
   test-unit:
-    name: Unit Tests (${{ matrix.shard }}/2)
+    name: Unit Tests (${{ matrix.shard }}/4)
     runs-on: ubuntu-latest
     timeout-minutes: 15
     needs: build
     strategy:
       fail-fast: false
       matrix:
-        shard: [1, 2]
+        shard: [1, 2, 3, 4]
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
       API_KEY_SECRET: ci-test-api-key-secret-long
@@ -207,7 +211,7 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run check:node-runtime
-      - run: node --import tsx --test --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+      - run: node --import tsx --test --test-force-exit --test-concurrency=1 --test-shard=${{ matrix.shard }}/4 tests/unit/*.test.ts
 
   node-24-compat:
     name: Node 24 Compatibility (${{ matrix.shard }}/2)
@@ -231,7 +235,7 @@ jobs:
       - run: npm ci
       - run: npm run check:node-runtime
       - run: npm run build
-      - run: node --import tsx --test --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+      - run: node --import tsx --test --test-force-exit --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
 
   node-26-compat:
     name: Node 26 Compatibility (${{ matrix.shard }}/2)
@@ -255,12 +259,12 @@ jobs:
       - run: npm ci
       - run: npm run check:node-runtime
       - run: npm run build
-      - run: node --import tsx --test --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
+      - run: node --import tsx --test --test-force-exit --test-concurrency=1 --test-shard=${{ matrix.shard }}/2 tests/unit/*.test.ts
 
   test-coverage:
     name: Coverage
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 60
     needs: build
     env:
       JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation

.github/workflows/claude-code-review.yml

@@ -1,43 +0,0 @@
-name: Claude Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
-
-jobs:
-  claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
-          plugins: "code-review@claude-code-plugins"
-          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options

.github/workflows/lock-released-branch.yml

@@ -0,0 +1,70 @@
+name: Lock released branch
+
+# When a GitHub Release is published (e.g. tag v3.8.2), make the matching
+# release/<tag> branch read-only so no further commits can land on a shipped
+# version. Uses branch protection's lock_branch + enforce_admins so the freeze
+# applies even to repository admins. To reopen a branch later:
+#   gh api -X DELETE repos/<owner>/<repo>/branches/release/<tag>/protection
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag of the released version (e.g. v3.8.2)"
+        required: true
+        type: string
+
+permissions:
+  # Editing branch protection requires the administration scope.
+  administration: write
+  contents: read
+
+jobs:
+  lock-branch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Lock release/<tag> branch
+        env:
+          GH_TOKEN: ${{ secrets.BRANCH_LOCK_TOKEN || secrets.GITHUB_TOKEN }}
+          # release event -> github.event.release.tag_name; manual -> inputs.tag
+          TAG: ${{ github.event.release.tag_name || inputs.tag }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${TAG}" ]; then
+            echo "::error::No tag provided; cannot determine release branch."
+            exit 1
+          fi
+
+          BRANCH="release/${TAG}"
+          echo "Target branch: ${BRANCH} (repo: ${REPO})"
+
+          # Skip gracefully if the release branch does not exist.
+          if ! gh api "repos/${REPO}/branches/${BRANCH}" >/dev/null 2>&1; then
+            echo "::warning::Branch ${BRANCH} not found — nothing to lock."
+            exit 0
+          fi
+
+          echo "Applying lock_branch protection to ${BRANCH}..."
+          gh api -X PUT "repos/${REPO}/branches/${BRANCH}/protection" --input - <<'JSON'
+          {
+            "required_status_checks": null,
+            "enforce_admins": true,
+            "required_pull_request_reviews": null,
+            "restrictions": null,
+            "lock_branch": true,
+            "allow_force_pushes": false,
+            "allow_deletions": false
+          }
+          JSON
+
+          LOCKED=$(gh api "repos/${REPO}/branches/${BRANCH}/protection" \
+            --jq '.lock_branch.enabled')
+          if [ "${LOCKED}" != "true" ]; then
+            echo "::error::Failed to confirm lock on ${BRANCH} (lock_branch=${LOCKED})."
+            exit 1
+          fi
+          echo "✅ ${BRANCH} is now locked (read-only)."

.github/workflows/opencode-plugin-ci.yml

@@ -0,0 +1,62 @@
+name: opencode-plugin CI
+
+on:
+  push:
+    branches: [main, release/v3.8.2]
+    paths:
+      - "@omniroute/opencode-plugin/**"
+  pull_request:
+    branches: [main, release/v3.8.2]
+    paths:
+      - "@omniroute/opencode-plugin/**"
+    types: [opened, synchronize, reopened, ready_for_review]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: "@omniroute/opencode-plugin"
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ["22", "24"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-plugin/package-lock.json"
+      - run: npm install --no-audit --no-fund
+      - run: npm run build
+      - run: npm test
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: "@omniroute/opencode-plugin/package-lock.json"
+      - run: npm install --no-audit --no-fund
+      - run: npm run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: opencode-plugin-dist
+          path: "@omniroute/opencode-plugin/dist"
+          retention-days: 7

.github/workflows/opencode-provider-ci.yml

@@ -33,7 +33,7 @@ jobs:
         node: ["20", "22", "24"]
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node }}
           cache: npm
@@ -47,14 +47,14 @@ jobs:
     needs: test
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "20"
           cache: npm
           cache-dependency-path: "@omniroute/opencode-provider/package-lock.json"
       - run: npm ci
       - run: npm run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: opencode-provider-dist
           path: "@omniroute/opencode-provider/dist"

.gitignore

@@ -97,10 +97,14 @@ clipr/
 app.log
 *.tgz
 .gh-discussions.json
+deploy.sh
+docker-compose.minimal.yml
+
 
 # Backup directories
 app.__qa_backup/
 .app-build-backup-*/
+backup/
 
 # Production standalone build (created by scripts/prepublish.mjs)
 # Conflicts with Next.js App Router detection in dev (root app/ shadows src/app/)
@@ -151,8 +155,8 @@ bun.lock
 # Private environment variables for .http-client
 http-client.private.env.json
 
-# Feature-triage ephemeral artifact (regenerated each run)
-_ideia/_triage.json
+# Note: _ideia/ (feature-triage drafts) is fully covered by the /_*/ rule above
+# and kept as a separate local-only git repo. Never committed to OmniRoute.
 
 # i18n audit artifact (generated by scripts/i18n/audit-dashboard-pages.mjs)
 scripts/i18n/_audit.json
@@ -161,5 +165,7 @@ scripts/i18n/_pending-keys.json
 # Private workflow / skill / command implementations
 # These contain proprietary multi-phase logic and should not be committed
 .agents/workflows/implement-features-ag.md
+.agents/workflows/port-upstream-features-ag.md
 .agents/skills/implement-features/
 .claude/commands/implement-features-cc.md
+.claude/worktrees/

.i18n-state.json

@@ -1,217 +1,217 @@
 {
   "sources": {
     "CLAUDE.md": {
-      "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
+      "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
       "locales": {
         "pt-BR": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "6ed62a4b8e85b48db9dbd3c5f00cec0a423742dd4ac518ff0206d6bf1732e714",
-          "updated_at": "2026-05-18T22:01:38.515Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "301b997e936b1d476e6094042666b96b33f42a4372fd2d9ccf904aacbfd7f023",
+          "updated_at": "2026-05-22T20:13:39.165Z"
         },
         "az": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "b3da42c255bf9d70ac862ae083ad2c15193dfcd69407db70bb452bc03b735283",
-          "updated_at": "2026-05-18T21:47:44.228Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "c26844ec50b2abfbb002767fb5c6c9c3982ec65789435bbc134bf1a7b50bf84a",
+          "updated_at": "2026-05-22T20:13:39.166Z"
         },
         "bn": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "cbb9eb8a552e7f6ceb0d45fdd115db2d88e90c420944f27fdfce8a461603c50a",
-          "updated_at": "2026-05-18T21:48:17.508Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "0b1416ec3b5af8cc6415d12a9ff12ce078acca4a7bb52a7422ebde3b6ae22832",
+          "updated_at": "2026-05-22T20:13:39.166Z"
         },
         "ar": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "179543e6015946c2409a72ad87519c71a86086982fa573061a9d958675face59",
-          "updated_at": "2026-05-18T21:48:47.676Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "bc747c5ea2a387dd37dea9dc1337d9734f2ec0da38a7134573d9743e3f4d2aef",
+          "updated_at": "2026-05-22T20:13:39.167Z"
         },
         "cs": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "ee2d587bb968619c4791ee7fa75909f40aa1d6fb5e97c293f8ff2ac4bc22167c",
-          "updated_at": "2026-05-18T21:51:04.860Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "e37dce45820b53be9d3d5ead08cadb8d13e4c77597b3009bb0be4e485917f5c6",
+          "updated_at": "2026-05-22T20:13:39.167Z"
         },
         "da": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "4672b5643ab8f9adfcf8a14199c127dcc54380ed4cbaccd3d946f0db25fbead3",
-          "updated_at": "2026-05-18T21:51:13.777Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "645c382bebe0931eaad6747e33667fd094b92b3f4042549b953db798de6b1f46",
+          "updated_at": "2026-05-22T20:13:39.168Z"
         },
         "de": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "1a36bebb379ff38306b0e850d2460f4cd9c5bc70b8b1f7ef9c42b84c833e22cd",
-          "updated_at": "2026-05-18T21:51:16.409Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "b6558f82eb67676baf4d78946a8d1e1b808f7763e5ebaf9f57948cbd1641dc0f",
+          "updated_at": "2026-05-22T20:13:39.168Z"
         },
         "es": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "269c2b0842485060471ff2a7179fd16cc40273e7c8d27f28477d8724a1333b26",
-          "updated_at": "2026-05-18T21:51:22.611Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "afb2a2dfa74a74c3105b0ac70181d33f5eefd201efe7edb6aba0740864639fe5",
+          "updated_at": "2026-05-22T20:13:39.169Z"
         },
         "fa": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "8b4603ebc4875f4af2ca67c571282038f566dce5b62d17caa361c0ec879c2bea",
-          "updated_at": "2026-05-18T21:52:38.812Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "58966769aeb71d23c55cf4aeb452f2bbe32036df8fba1d7596f3e861897d507b",
+          "updated_at": "2026-05-22T20:13:39.169Z"
         },
         "fi": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "16a3a0b0df89e37808d7567e502944fb6792e14eb8c61e4b474b0fe79b310d63",
-          "updated_at": "2026-05-18T21:52:44.086Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "04cf72a3b370edcb3d54361c6cc250b3af227ba183376827006c7998839740aa",
+          "updated_at": "2026-05-22T20:13:39.169Z"
         },
         "fr": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "1a8bb2fdc17927047842bf6806787e9cea83d8f2912bc0291836574af877cde1",
-          "updated_at": "2026-05-18T21:52:44.715Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "8dca6de87c88e04396f1139ac8b6328d188defaa5abc99eeb4026f53de772ba1",
+          "updated_at": "2026-05-22T20:13:39.170Z"
         },
         "he": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "446414fae3f108ec2ac0fea09d826fab6a6dcfe2189e33f63d0068d7ffe945b2",
-          "updated_at": "2026-05-18T21:54:06.000Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "0308a2c8c5a6b6261474a76c160f3c0658c75f56a633a57bd7300b83ccb32c9d",
+          "updated_at": "2026-05-22T20:13:39.170Z"
         },
         "hi": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "24ce173a1252a9849917324395ae5712e7d03d98ab9e9119a98c12c405e5fd96",
-          "updated_at": "2026-05-18T21:54:16.102Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "a3e902c3b1812a41ccb14c9f16d2cf2e42b8c005a5d557043e582d48eda024c4",
+          "updated_at": "2026-05-22T20:13:39.170Z"
         },
         "gu": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "4d49e4be59a029c9407ca023a7f7ef21533e2ccf9c1b857a84eec0d5c1e0b1eb",
-          "updated_at": "2026-05-18T21:55:11.836Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "1bc2419db39c7c7960b065222a3e3990e9e53c4d3427ec02422e3e506aa53733",
+          "updated_at": "2026-05-22T20:13:39.171Z"
         },
         "hu": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "85881f57fc6a606e122466a368b159f3b7f6a8f0fa90aa7fe039f0127e436d44",
-          "updated_at": "2026-05-18T21:55:54.603Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "ec30f54810f8b5b84e3ac8bf7bc8d05acc8616d71801b672ec02f0bc225cf607",
+          "updated_at": "2026-05-22T20:13:39.171Z"
         },
         "id": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "e970c79fe15c9f78745b1b53e5eed3b8914641a0a3f81ce2b5207a21dd850d4e",
-          "updated_at": "2026-05-18T21:56:05.289Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "aebd8fdad7ec4857aa1b958cda37f59681846525207d71d98d729775031afb94",
+          "updated_at": "2026-05-22T20:13:39.172Z"
         },
         "in": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "9127b1ab7c33307a62ba12adc36ae0f70809b1ff21cd562b0d2f4c52ba5aae0d",
-          "updated_at": "2026-05-18T21:56:08.126Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "ac70a1282877f8c4f792e9235f7a6fbce3cbec4a424ce4947074bb210fe12d67",
+          "updated_at": "2026-05-22T20:13:39.172Z"
         },
         "it": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "949279fa3953e26345303fdb0defb959d722cfd8e0858a2fd1353384bdee2d66",
-          "updated_at": "2026-05-18T21:56:31.825Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "260f10dd121441d08e15a8d511789d8f8f7a788995305ab5e8dc6d0c1a3db06e",
+          "updated_at": "2026-05-22T20:13:39.173Z"
         },
         "ja": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "e2eec56e1fa368594e32e6184defc91bccf6b086f84de8a03774efa3b4b21cc7",
-          "updated_at": "2026-05-18T21:57:34.374Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "83871c13e99d13d7928409b2aef182f55fe36fbb2425f8fa4bd0df0466afed28",
+          "updated_at": "2026-05-22T20:13:39.173Z"
         },
         "mr": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "c795db0cde7b51a434a5bf06384fbec09073a2b7418fb0dddd90fa12f46fb7e1",
-          "updated_at": "2026-05-18T21:58:25.858Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "0c35c5261dd3b6c6b729d14653f95cc112f3ed9829d2d41b61e5a960abc68556",
+          "updated_at": "2026-05-22T20:13:39.173Z"
         },
         "ko": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "8d3f5cfda2ad3ce01e882cf2008de9f2106279e0f3a180cd8fa70280870b9761",
-          "updated_at": "2026-05-18T21:58:25.863Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "4ea4079b37d90e90e9a32d0da290e04e38bcd6426512b50ca7be7139354bc329",
+          "updated_at": "2026-05-22T20:13:39.174Z"
         },
         "ms": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "f2e13499c45cea20bcf178eac842ba923859bcc25822c6b4b9cf627512f3cce9",
-          "updated_at": "2026-05-18T21:58:33.906Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "0e8031cd987766a69afc7aaf7c3560a57736d37e7238ddccfb848d6fbeb3f212",
+          "updated_at": "2026-05-22T20:13:39.174Z"
         },
         "nl": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "81f851a5aff422692c62fd65c1289598bfc779f8ca02af7083215a0d0cf42575",
-          "updated_at": "2026-05-18T21:59:16.560Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "27e554c3a9b86db1f04539fcac18d3e75e6599d4de9f5ac0cf789a136b5737d4",
+          "updated_at": "2026-05-22T20:13:39.174Z"
         },
         "phi": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "bf3fb36abd19f82bb296fe9fada413368b06b60d7931c352ebd1da8c3ff2c9fa",
-          "updated_at": "2026-05-18T21:59:52.998Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "f955af44cc0e8e87a2a7b12313f0dfad9aae1a50d7855e74c8155df3601279ad",
+          "updated_at": "2026-05-22T20:13:39.175Z"
         },
         "no": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "3263bf8e5287023b7e50f1a2e65c069b2a3719cbf58b1454e451b19ac56b2c93",
-          "updated_at": "2026-05-18T22:00:47.607Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "de4e3d940ae485c85da13db4471fcc68926ec53e660d92633f01293c5db0a04d",
+          "updated_at": "2026-05-22T20:13:39.175Z"
         },
         "pl": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "549129cf48c266b953b13e32efdbd8b7ba09848d68f76a984471c8f3b7c15338",
-          "updated_at": "2026-05-18T22:01:03.762Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "de5be8961e5184431404d0021e31c3ef0857f7439fbd1c71ddc0c6828bed86bb",
+          "updated_at": "2026-05-22T20:13:39.175Z"
         },
         "ro": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "6391e37e4289f64b4e58a2922f42d0163f50dd836f55dbad1aa2d39020c27a68",
-          "updated_at": "2026-05-18T22:02:54.102Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "19d98b22bc77c1870b749fad6e62a41c6ef53f3cad303d1c471fba4bf7012797",
+          "updated_at": "2026-05-22T20:13:39.175Z"
         },
         "ru": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "6aa38bc3c3c835bcd5ddf37d9a1ed29bf57d3234ee910f87c92b1363254ad4e6",
-          "updated_at": "2026-05-18T22:02:57.045Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "25e0c70ec25bd24b073b9d693299c3c3d32d66a410569362719e9c9ecacd759d",
+          "updated_at": "2026-05-22T20:13:39.176Z"
         },
         "pt": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "3a15114c2839e513ce1983571ab7ac312856a29f1284a49d80eba3860b06b3ed",
-          "updated_at": "2026-05-18T22:03:11.851Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "0d31647b21af967d8d4e9ecbcfc4901a66db377a6853d7b59296a2d73f0cab12",
+          "updated_at": "2026-05-22T20:13:39.176Z"
         },
         "sk": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "d7bf32867f17562967d0af5b78ae4c71abd4af3c7523128b041739dd9b02131b",
-          "updated_at": "2026-05-18T22:04:00.222Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "9d5d0ce1c51da4959d1c306969bff0bf36d3a3492ccdbdbd82e4f4d951f32c8b",
+          "updated_at": "2026-05-22T20:13:39.176Z"
         },
         "sw": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "ae3337d4ef14ab15a25a60f2d74db80be8b2e82cdb3911f9a92b22fa5fd5395b",
-          "updated_at": "2026-05-18T22:04:46.376Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "11cd3dc7a605eebddf4a34c13de66c713d67adb32e4242962a65c71e5a034c7e",
+          "updated_at": "2026-05-22T20:13:39.177Z"
         },
         "sv": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "36f1ca81330f13a3489523711dcf9b3a051518164345dfefc3097dbc1459e1b3",
-          "updated_at": "2026-05-18T22:05:02.302Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "93b679feb6415315ab96e08298217e66be84265a277e267ecefd25b2cef04026",
+          "updated_at": "2026-05-22T20:13:39.177Z"
         },
         "ta": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "12f7f379ca9970a561aa71a56f58734f6d454bf47f99bc240e52c2943aa585bb",
-          "updated_at": "2026-05-18T22:05:29.419Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "55f3df128513a1b4a8cc3f58eb84769814589d80e1c8b8f03ab0635750a76d2d",
+          "updated_at": "2026-05-22T20:13:39.177Z"
         },
         "te": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "7334cc88818d46644f138e8c5aee8045346cc6a9e98f597bd616ff8de02d17e9",
-          "updated_at": "2026-05-18T22:06:17.933Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "81019604dd1fb38dfda55c1b8cf5cf8243347be08221a5e1eb11e8c76e095fab",
+          "updated_at": "2026-05-22T20:13:39.178Z"
         },
         "tr": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "7284ba38f5a9b81f70926c923870f6ee1d29e9e34e7074a087e5ad9812794c91",
-          "updated_at": "2026-05-18T22:07:15.730Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "b67efd07b179be016b388dff4b8979597c0a7b2db602629cef539dbec14913ab",
+          "updated_at": "2026-05-22T20:13:39.178Z"
         },
         "th": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "b300d8668da2de9dd5e3c80b3a6d138b677662965be6c1459dcc145fbe88c062",
-          "updated_at": "2026-05-18T22:07:44.472Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "a793a12dc0cba5e3641cd544f63ab23e9cfe1b80568a08770a81ffd890287eda",
+          "updated_at": "2026-05-22T20:13:39.179Z"
         },
         "ur": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "c2dfcb2125306a21b293a054f72d0946af4c9f29058fb679bcca3fbda7608a5a",
-          "updated_at": "2026-05-18T22:08:34.169Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "6c03049aee6d85b6fd4a3bf9b89a6204e461d3f05e9cb767e36c80af796452df",
+          "updated_at": "2026-05-22T20:13:39.179Z"
         },
         "vi": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "ece90f91f228a0c504e4537d55e951b48763cafc14531a81dfc42d8a1ad45771",
-          "updated_at": "2026-05-18T22:09:55.405Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "4d35c6898f98913a02551dcfbf4d3748b2461e2d8206d292f292acacf0fc7133",
+          "updated_at": "2026-05-22T20:13:39.180Z"
         },
         "zh-CN": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "780e02b27f556c748090474ad9081d8b3fd92018b14329407ac54a8f7e27688b",
-          "updated_at": "2026-05-18T22:10:23.922Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "d3f574c244d157c1fe1b9fc86192d1565df2dc6343ac9ef63c0fd3f91d97f492",
+          "updated_at": "2026-05-22T20:13:39.180Z"
         },
         "uk-UA": {
-          "source_hash": "951d6ba25c4ced12e53f5dead589013135b827a1ed908a6dc5c5e5dcc3cc96cb",
-          "target_hash": "9a7a645713fb8b23de2a1a9b24317376a7a83fee994830bb81a2889e34efc0ee",
-          "updated_at": "2026-05-18T22:18:32.917Z"
+          "source_hash": "c808d01e42e9aaaede590048dc327347c9e814b152c6f45f54be6df64f4f19df",
+          "target_hash": "ffe6357e38d56ba2595e8fb8e21db4ae91bf03d10fca50a2b722e0d0bb6c01d9",
+          "updated_at": "2026-05-22T20:13:39.181Z"
         }
       }
     },
     "docs/architecture/ARCHITECTURE.md": {
-      "source_hash": "a065bbff5e461cca6cd1a81d2923626040548c3b3af98ecb2a69a99709bd8059",
+      "source_hash": "f9b4f17a1b0331fb5500768943438411ed88a38278381680caacc37c90bfb869",
       "locales": {
         "pt-BR": {
-          "source_hash": "a065bbff5e461cca6cd1a81d2923626040548c3b3af98ecb2a69a99709bd8059",
-          "target_hash": "7ee10dc8cba2668fd279af64ecca3a1760e974b6dc9672aee81e69c63ee41175",
-          "updated_at": "2026-05-20T05:34:41.826Z"
+          "source_hash": "f9b4f17a1b0331fb5500768943438411ed88a38278381680caacc37c90bfb869",
+          "target_hash": "e320c6172a88a0f3b698ba1a2e9e938424ece66625765395837bcf55cc29454e",
+          "updated_at": "2026-05-22T20:13:39.183Z"
         }
       }
     }

@omniroute/opencode-plugin/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

@omniroute/opencode-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OmniRoute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

@omniroute/opencode-plugin/README.md

@@ -0,0 +1,255 @@
+# @omniroute/opencode-plugin
+
+First-class OpenCode plugin for the [OmniRoute AI Gateway](https://github.com/diegosouzapw/OmniRoute). Pulls a live model catalog from `/v1/models` (including `-low`/`-medium`/`-high`/`-thinking` variants as first-class IDs), aggregates combos via `/api/combos` using a least-common-denominator capability/limit join, sanitizes Gemini tool schemas in flight, and supports multiple side-by-side OmniRoute instances out of the box.
+
+## Install
+
+Once published to npm:
+
+```sh
+npm install @omniroute/opencode-plugin
+```
+
+Until then (or for local development), reference the built artifact directly. Either extract the package into your OpenCode plugins dir and point at the extracted `dist/index.js`:
+
+```sh
+# from inside the OmniRoute repo
+cd @omniroute/opencode-plugin && npm run build && npm pack
+# then extract into ~/.config/opencode/plugins/omniroute-opencode-plugin/
+```
+
+Peer dep: `@opencode-ai/plugin` (managed by your OpenCode install).
+
+## Quick start (single instance)
+
+```jsonc
+// opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@omniroute/opencode-plugin",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+      },
+    ],
+  ],
+}
+```
+
+```sh
+opencode auth login --provider omniroute
+# prompts for the OmniRoute API key, writes to ~/.local/share/opencode/auth.json
+```
+
+> ⚠ Use the `--provider` flag explicitly. `opencode auth login omniroute` is parsed as a positional `url` argument by current OC releases (≤1.15.5) and fails with `fetch() URL is invalid`. Tracked upstream.
+
+Restart OpenCode. `/models` lists the full live catalog. Variants (`-low`, `-medium`, `-high`, `-thinking`) and combos appear as first-class IDs — OmniRoute is the source of truth, no client-side synthesis.
+
+## Multi-instance (prod + preprod side-by-side)
+
+> ⚠ OC ≤1.15.5 dedupes plugin loads by absolute module path. Two `plugin:` entries pointing at the same `dist/index.js` collapse into one (last-listed options win). Workaround: install the plugin twice into separate directories so each entry resolves to a distinct module file. v0.2.x will introduce an `instances: [...]` shape that registers N providers from a single load.
+
+### Dual-install workaround (works today on OC ≤1.15.5)
+
+Pack the plugin once, extract it twice into named directories, then point each `plugin:` entry at its own copy:
+
+```sh
+# 1. Build + pack the plugin (run from the plugin worktree)
+cd /path/to/OmniRoute/@omniroute/opencode-plugin
+npm run build
+npm pack
+# produces omniroute-opencode-plugin-0.1.0.tgz
+
+# 2. Extract one copy per OmniRoute endpoint
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-prod
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod
+tar -xzf omniroute-opencode-plugin-0.1.0.tgz -C ~/.config/opencode/plugins/omniroute-opencode-plugin-prod    --strip-components=1
+tar -xzf omniroute-opencode-plugin-0.1.0.tgz -C ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod --strip-components=1
+```
+
+Then in `~/.config/opencode/opencode.json` reference each directory by absolute path:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "./plugins/omniroute-opencode-plugin-prod/dist/index.js",
+      {
+        "providerId": "omniroute",
+        "displayName": "OmniRoute",
+        "baseURL": "https://or.example.com",
+      },
+    ],
+    [
+      "./plugins/omniroute-opencode-plugin-preprod/dist/index.js",
+      {
+        "providerId": "omniroute-preprod",
+        "displayName": "OmniRoute Preprod",
+        "baseURL": "https://or-preprod.example.com",
+      },
+    ],
+  ],
+}
+```
+
+Paths are relative to `~/.config/opencode/`. Each entry now resolves to a distinct module file, so OC loads them as two separate plugin instances. Authenticate each:
+
+```sh
+opencode auth login --provider omniroute
+opencode auth login --provider omniroute-preprod
+```
+
+Each entry gets its own provider id, its own model picker entry, its own slot in `auth.json`, and its own TTL cache. Closures are isolated per plugin instance — no cross-talk.
+
+### After publish (`@omniroute/opencode-plugin` npm)
+
+Once the package is published, the dual-install becomes two `npm install --prefix` commands instead of `tar -xzf`:
+
+```sh
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-prod
+mkdir -p ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod
+npm install --prefix ~/.config/opencode/plugins/omniroute-opencode-plugin-prod    @omniroute/opencode-plugin
+npm install --prefix ~/.config/opencode/plugins/omniroute-opencode-plugin-preprod @omniroute/opencode-plugin
+```
+
+`opencode.json` paths become `./plugins/omniroute-opencode-plugin-prod/node_modules/@omniroute/opencode-plugin/dist/index.js` (and the preprod equivalent).
+
+## Features
+
+| Feature                                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                | Hook                         |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Dynamic `/v1/models`                        | Pulls live catalog (455+ entries on prod) on each refresh, TTL-cached                                                                                                                                                                                                                                                                                                                                       | `provider.models`            |
+| Variants pass-through                       | `-low`/`-medium`/`-high`/`-thinking` ship as first-class IDs from OmniRoute (no client synthesis)                                                                                                                                                                                                                                                                                                           | `provider.models`            |
+| Combo LCD aggregation                       | Combos appear with intersected capabilities + min context/output across members                                                                                                                                                                                                                                                                                                                             | `provider.models` + `config` |
+| `combo/<slug>` namespace + `Combo: ` prefix | Combos surface under `combo/claude-primary` (not the upstream UUID) and the picker shows `Combo: claude-primary` so they stand apart from raw provider/model pairs                                                                                                                                                                                                                                          | both hooks                   |
+| Nice names + cost                           | `/api/pricing/models` display names AND `/api/pricing` per-million-token cost overlaid onto the live catalog                                                                                                                                                                                                                                                                                                | both hooks                   |
+| Canonical-twin dedup + alias-fallback       | `/v1/models` exposes the same upstream model under both short alias (`cc/claude-opus-4-7`) and canonical name (`claude/claude-opus-4-7`); the plugin drops the canonical twin when an alias twin exists (no duplicate rows in the picker) and reverse-maps canonical → alias to pick up enrichment for short aliases (`dg/nova-3 → Deepgram - Nova 3`) that `/api/pricing/models` only indexes by canonical | both hooks                   |
+| Compression pipeline tags                   | Combo names get tagged with their compression pipeline (e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`) when `features.compressionMetadata: true`. Intensity tokens render as a traffic-light emoji: 🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra                                                                                                                                        | both hooks                   |
+| Provider-tag prefix                         | Prepend short upstream-provider label to enriched names (e.g. `Claude - Claude Opus 4.7` vs `Kiro - Claude Opus 4.7`, `GHM - GPT 5`) so same-id models routed via different upstream connections group visibly in the picker (default-on, opt-out via `features.providerTag: false`)                                                                                                                        | both hooks                   |
+| Usable-only filter                          | Filter to providers with at least one healthy connection in `/api/providers` (opt-in via `features.usableOnly`)                                                                                                                                                                                                                                                                                             | both hooks                   |
+| Disk-cache fallback                         | Last-known-good catalog persisted to disk; hydrates on a cold start when `/v1/models` is unreachable (default-on, opt-out via `features.diskCache: false`)                                                                                                                                                                                                                                                  | `config`                     |
+| Bearer injection + suffix-spoof guard       | Adds `Authorization` on baseURL-matched requests only                                                                                                                                                                                                                                                                                                                                                       | `auth.loader.fetch`          |
+| Gemini schema sanitization                  | Strips `$schema`/`$ref`/`additionalProperties` for `gemini-*`/`google-vertex-gemini/*`                                                                                                                                                                                                                                                                                                                      | `auth.loader.fetch` wrap     |
+| Multi-instance                              | Each plugin entry binds to its own `providerId`; closures isolated                                                                                                                                                                                                                                                                                                                                          | factory                      |
+| Config-hook shim                            | OC ≤1.15.5 fallback: writes static catalog into `config.provider[id]` (config hook is the only one that fires in `serve` mode on these versions)                                                                                                                                                                                                                                                            | `config`                     |
+
+## Plugin options
+
+| Option          | Type     | Default                                    | Description                                                |
+| --------------- | -------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `providerId`    | `string` | `"omniroute"`                              | OpenCode provider id; must be unique across plugin entries |
+| `displayName`   | `string` | `"OmniRoute"` or `OmniRoute (<id>)`        | Label in the OC UI                                         |
+| `modelCacheTtl` | `number` | `300000` (5 min)                           | `/v1/models` TTL in ms                                     |
+| `baseURL`       | `string` | resolved from `auth.json` after `/connect` | Override OmniRoute base URL                                |
+| `features`      | `object` | see below                                  | Feature toggles (all opt-in/out, defaults preserve v0.1.0) |
+
+### `features` block
+
+Every field is optional. Defaults mirror v0.1.0 behaviour so existing `opencode.json` files do not need to change.
+
+| Feature               | Type      | Default | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `combos`              | `boolean` | `true`  | Discover `/api/combos` and surface them as pseudo-models with LCD capabilities. Combos are keyed under the `combo/<slug>` namespace and labelled `Combo: <name>` in the model picker so they're distinguishable from raw provider/model pairs.                                                                                                                                                                                                                                                                                                                               |
+| `enrichment`          | `boolean` | `true`  | Pull display names from `/api/pricing/models` AND per-million-token pricing (`input`, `output`, `cached` → `cacheRead`, `cache_creation` → `cacheWrite`) from `/api/pricing`, then overlay both onto the live catalog (so the UI shows `Claude 4.7 Opus` with `cost.input: 5`, `cost.output: 25` instead of raw IDs and zeroed cost).                                                                                                                                                                                                                                        |
+| `compressionMetadata` | `boolean` | `false` | Pull `/api/context/combos` so combo names get tagged with their compression pipeline, e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`. Intensity tokens render as traffic-light emoji (🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra) so the picker advertises "how compressed" each combo is at a glance.                                                                                                                                                                                                                                                  |
+| `providerTag`         | `boolean` | `true`  | Prepend a short upstream-provider label to the enriched display name with `" - "` separator, so `cc/claude-opus-4-7 → Claude - Claude Opus 4.7` differs visibly from `kr/claude-opus-4-7 → Kiro - Claude Opus 4.7` in the OC TUI model picker. Label resolution: use `/api/pricing/models[<alias>].name` verbatim when ≤8 chars (e.g. `Claude`, `Kiro`, `Codex`, `Qwen`), otherwise fall back to `UPPER(alias)` (e.g. `GitHub Models` → `GHM`, `Gemini-cli` → `GEMINI-CLI`). Idempotent. Combos intentionally skipped (the `Combo: ` prefix already conveys multi-upstream). |
+| `usableOnly`          | `boolean` | `false` | Read `/api/providers` and filter the catalog to providers that have at least one connection with `isActive: true` AND `testStatus: 'active'`. Subtract-filter semantics: providers unknown to BOTH the pricing-models catalog AND the connection table pass through (so synthetic prefixes like `agentrouter/*` survive). On fetch failure the filter is disabled for the refresh — never hides the whole catalog.                                                                                                                                                           |
+| `diskCache`           | `boolean` | `true`  | Persist the last successful `/v1/models` + `/api/combos` + enrichment + connections + compression snapshot to `${OPENCODE_DATA_DIR ?? ~/.local/share/opencode}/plugins/omniroute-<providerId>.json`. On a subsequent cold start where `/v1/models` throws (network down / IP whitelist drop / 5xx) the static block hydrates from the snapshot so OC's model picker survives offline. Soft-fail on read/write — never blocks publishing.                                                                                                                                     |
+| `geminiSanitization`  | `boolean` | `true`  | Strip `$schema`/`$ref`/`additionalProperties` from tool params when the model id matches `gemini`                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `mcpAutoEmit`         | `boolean` | `false` | Auto-write an `mcp.<providerId>` remote entry into the OC config pointing at `<baseURL>/api/mcp/stream` with the resolved Bearer token                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `mcpToken`            | `string`  | _unset_ | Optional separate Bearer for the auto-emitted MCP entry. Falls back to the provider's `apiKey` (from `auth.json`) when unset                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `fetchInterceptor`    | `boolean` | `true`  | Inject `Authorization: Bearer` + default `Content-Type` on every outbound request targeting `baseURL` (suffix-spoof guarded)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+#### Example — enrichment + compression tags + MCP auto-emit
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@omniroute/opencode-plugin",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+        "features": {
+          "combos": true,
+          "enrichment": true,
+          "compressionMetadata": true,
+          "mcpAutoEmit": true,
+        },
+      },
+    ],
+  ],
+}
+```
+
+With `mcpAutoEmit: true`, the plugin synthesises an `mcp.omniroute` entry equivalent to a manual:
+
+```jsonc
+"mcp": {
+  "omniroute": {
+    "type": "remote",
+    "url": "https://or.example.com/api/mcp/stream",
+    "enabled": true,
+    "headers": { "Authorization": "Bearer <apiKey-from-auth.json>" }
+  }
+}
+```
+
+If you want a narrower-scoped Bearer for MCP (different from the chat/inference key), set `features.mcpToken`. Operator overrides win: if you already set `mcp.omniroute` in `opencode.json`, the plugin will not overwrite it.
+
+#### Example — production-leaning defaults (clean picker, offline resilience)
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@omniroute/opencode-plugin",
+      {
+        "providerId": "omniroute",
+        "baseURL": "https://or.example.com",
+        "features": {
+          "combos": true,
+          "enrichment": true,
+          "compressionMetadata": true,
+          "usableOnly": true,
+          "diskCache": true,
+        },
+      },
+    ],
+  ],
+}
+```
+
+- `usableOnly: true` drops models whose canonical provider has no healthy connection in your OmniRoute instance — your `/models` picker stays focused on what you can actually call.
+- `diskCache: true` (default) writes a snapshot to `${OPENCODE_DATA_DIR}/plugins/omniroute-<providerId>.json` on every healthy refresh. On a cold start where `/v1/models` is unreachable (laptop offline, IP whitelist drop), the snapshot hydrates the static block so OC still shows the catalog instead of a stub.
+- `compressionMetadata: true` annotates combo display names with their pipeline using traffic-light emoji for intensity (e.g. `Combo: claude-primary [rtk🟡 → caveman🟠]`) so the picker advertises which compression each combo applies and how heavy it is at a glance. Palette: 🟢 lite/minimal · 🟡 standard · 🟠 aggressive/full · 🔴 ultra. Unknown intensities fall through to raw text (`[rtk:custom-thing]`) so the plugin never hides a value OmniRoute knows but the plugin doesn't.
+- `providerTag: true` (default) prepends a short upstream-provider label so the picker shows `Claude - Claude Opus 4.7` for `cc/claude-opus-4-7`, `Kiro - Claude Opus 4.7` for `kr/claude-opus-4-7`, and `GHM - GPT 5` for `ghm/gpt-5` (slot.name `GitHub Models` > 8 chars → abbreviated). Critical when the same model id is sold through multiple upstream connections with different cost/auth/rate-limit profiles. Set to `false` to keep the pre-v3.8.3 unsuffixed format.
+
+## Comparison vs `@omniroute/opencode-provider`
+
+[`@omniroute/opencode-provider`](https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/opencode-provider) is the existing config-generator package — it writes a frozen `provider.<id>` block into `opencode.json` at build time. This plugin is the runtime integration.
+
+|                   | `@omniroute/opencode-plugin` (this) | `@omniroute/opencode-provider`    |
+| ----------------- | ----------------------------------- | --------------------------------- |
+| Type              | OC plugin                           | Config generator (CLI/build-time) |
+| Models            | Live from `/v1/models`              | Frozen at scaffold                |
+| Combos            | LCD-aggregated live                 | None                              |
+| Gemini sanitize   | Yes                                 | N/A                               |
+| OC UI integration | `/connect`, `/models`               | None                              |
+| Multi-instance    | Native                              | Manual                            |
+
+Both can coexist; pick the one that fits your environment.
+
+## Requirements
+
+- Node `>=22.22.3` (per `engines.node`); tested on Node 22 and 24.
+- OpenCode: verified end-to-end against `opencode@1.15.5` with `@opencode-ai/plugin@1.15.6`.
+- OC plugin peer (`@opencode-ai/plugin`) `>=1.14.49` for the full feature set (provider hook surfaces models in `/models`). On `<=1.14.48`, the plugin falls back to its `config` hook, writing a static catalog snapshot into `config.provider[id]` so models still appear.
+- The plugin uses the OC v1 plugin shape (`default: { id, server }`) — older OC releases that only walk named exports will reject it. Stay on OC ≥1.15.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

@omniroute/opencode-plugin/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@omniroute/opencode-plugin",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for the OmniRoute AI Gateway. Drives dynamic model discovery, /connect auth flow, and multi-instance OmniRoute providers via the official @opencode-ai/plugin contract.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "node --import tsx/esm --test tests/scaffold.test.ts tests/auth.test.ts tests/options-schema.test.ts tests/multi-instance.test.ts tests/fetch-interceptor.test.ts tests/provider.test.ts tests/gemini-sanitize.test.ts tests/combos.test.ts tests/config-shim.test.ts tests/features.test.ts tests/usable-combo.test.ts tests/disk-snapshot-perms.test.ts",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "keywords": [
+    "omniroute",
+    "opencode",
+    "opencode-plugin",
+    "ai-sdk",
+    "openai-compatible",
+    "provider",
+    "gemini",
+    "combos",
+    "mcp"
+  ],
+  "author": "OmniRoute contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/diegosouzapw/OmniRoute.git",
+    "directory": "@omniroute/opencode-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/diegosouzapw/OmniRoute/issues"
+  },
+  "homepage": "https://github.com/diegosouzapw/OmniRoute/tree/main/%40omniroute/opencode-plugin#readme",
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.15.6",
+    "@types/node": "^22.19.19",
+    "tsup": "^8.5.1",
+    "tsx": "^4.22.3",
+    "typescript": "^5.9.3"
+  }
+}

@omniroute/opencode-plugin/tests/auth.test.ts

@@ -0,0 +1,147 @@
+/**
+ * T-02 auth-hook contract tests.
+ *
+ * Covers the `createOmniRouteAuthHook(opts)` factory and its loader behaviour
+ * against every Auth flavor (`api`, `oauth`, null, empty key). Validates the
+ * multi-instance fix: provider id flows from plugin options, not a module
+ * constant.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createOmniRouteAuthHook } from "../src/index.js";
+
+test("createOmniRouteAuthHook: default providerId is 'omniroute'", () => {
+  const hook = createOmniRouteAuthHook();
+  assert.equal(hook.provider, "omniroute");
+});
+
+test("createOmniRouteAuthHook: custom providerId binds to hook.provider (multi-instance)", () => {
+  const hook = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
+  assert.equal(hook.provider, "omniroute-preprod");
+});
+
+test("createOmniRouteAuthHook: methods[0] is type 'api' with label including displayName", () => {
+  const hook = createOmniRouteAuthHook();
+  assert.equal(Array.isArray(hook.methods), true);
+  assert.equal(hook.methods.length, 1);
+  const m = hook.methods[0];
+  assert.equal(m.type, "api");
+  assert.equal(m.label, "OmniRoute API Key");
+
+  const custom = createOmniRouteAuthHook({ providerId: "omniroute-preprod" });
+  assert.equal(custom.methods[0].label, "OmniRoute (omniroute-preprod) API Key");
+});
+
+test("createOmniRouteAuthHook: prompts[0] uses key='apiKey' per @opencode-ai/plugin contract", () => {
+  // NOTE: spec referenced `name: "apiKey"`; the official
+  // @opencode-ai/plugin@1.15.6 prompt shape uses `key` + `message` (no
+  // `name`/`label`/`mask` fields). Asserting against the real type contract.
+  const hook = createOmniRouteAuthHook();
+  const m = hook.methods[0];
+  assert.equal(m.type, "api");
+  // narrow: api method may carry prompts
+  const prompts = "prompts" in m ? m.prompts : undefined;
+  assert.ok(Array.isArray(prompts) && prompts.length === 1, "expected one prompt");
+  const p = prompts![0];
+  assert.equal(p.type, "text");
+  assert.equal((p as { key: string }).key, "apiKey");
+  assert.ok(
+    typeof (p as { message: string }).message === "string" &&
+      (p as { message: string }).message.includes("omniroute"),
+    "prompt message should mention provider id"
+  );
+});
+
+test("loader: valid api auth → {apiKey} when no baseURL option (T-04: fetch omitted)", async () => {
+  // T-04 changed the loader return shape: without a resolvable baseURL the
+  // interceptor cannot gate-keep requests, so the loader falls back to
+  // apiKey-only and the AI-SDK uses its default fetch. See fetch-interceptor
+  // tests for the wired-fetch branches.
+  const hook = createOmniRouteAuthHook();
+  assert.ok(hook.loader, "loader must be defined");
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-test" }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, { apiKey: "sk-test" });
+});
+
+test("loader: valid api auth → {apiKey, baseURL, fetch} when baseURL option set (T-04)", async () => {
+  const hook = createOmniRouteAuthHook({ baseURL: "https://or.example.com/v1" });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.equal((result as { apiKey: string }).apiKey, "sk-x");
+  assert.equal((result as { baseURL: string }).baseURL, "https://or.example.com/v1");
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "T-04: loader must wire fetch interceptor when baseURL resolves"
+  );
+});
+
+test("loader: features.fetchInterceptor=false AND geminiSanitization=false → no custom fetch (flags honored)", async () => {
+  // Regression: both fetch-layer flags were documented + schema-validated but
+  // silently ignored. Disabling both must fall back to the SDK default fetch.
+  const hook = createOmniRouteAuthHook({
+    baseURL: "https://or.example.com/v1",
+    features: { fetchInterceptor: false, geminiSanitization: false },
+  });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, { apiKey: "sk-x", baseURL: "https://or.example.com/v1" });
+  assert.equal(
+    (result as { fetch?: unknown }).fetch,
+    undefined,
+    "both flags off must omit the custom fetch"
+  );
+});
+
+test("loader: features.fetchInterceptor=false but geminiSanitization=true → fetch still wired (sanitizer only)", async () => {
+  const hook = createOmniRouteAuthHook({
+    baseURL: "https://or.example.com/v1",
+    features: { fetchInterceptor: false, geminiSanitization: true },
+  });
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: "sk-x" }) as never,
+    {} as never
+  );
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "geminiSanitization alone must still provide a fetch wrapper"
+  );
+});
+
+test("loader: null/undefined auth → {} (no creds yet, OC surfaces /connect)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const r1 = await hook.loader!(async () => null as never, {} as never);
+  assert.deepEqual(r1, {});
+  const r2 = await hook.loader!(async () => undefined as never, {} as never);
+  assert.deepEqual(r2, {});
+});
+
+test("loader: oauth-flavored auth → {} (wrong method type, ignored)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(
+    async () =>
+      ({
+        type: "oauth",
+        refresh: "r",
+        access: "a",
+        expires: 0,
+      }) as never,
+    {} as never
+  );
+  assert.deepEqual(result, {});
+});
+
+test("loader: api auth with empty key → {} (empty creds rejected)", async () => {
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(async () => ({ type: "api", key: "" }) as never, {} as never);
+  assert.deepEqual(result, {});
+});

@omniroute/opencode-plugin/tests/combos.test.ts

@@ -0,0 +1,641 @@
+/**
+ * T-05 combo-discovery contract tests.
+ *
+ * Covers:
+ *   - `defaultOmniRouteCombosFetcher(baseURL, apiKey, timeoutMs?)`
+ *     — envelope tolerance (`{combos: [...]}` and bare array), non-2xx errors.
+ *   - `mapComboToModelV2(combo, members, providerId, baseURL)`
+ *     — LCD policy across capabilities, limits, modalities; defensive
+ *       posture on empty members; nice-name preference.
+ *   - `createOmniRouteProviderHook(opts, deps)` extension
+ *     — combos merged into the models map; collision resolution (combo
+ *       wins, warn-once); soft-fail when the combos fetcher throws;
+ *       combos cached + reused under the same TTL key as models.
+ *
+ * Mocking strategy mirrors `provider.test.ts`: both fetchers are
+ * dependency-injected at hook construction, no `fetch` monkey-patch.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createOmniRouteProviderHook,
+  defaultOmniRouteCombosFetcher,
+  mapComboToModelV2,
+  type OmniRouteCombosFetcher,
+  type OmniRouteModelsFetcher,
+  type OmniRouteRawCombo,
+  type OmniRouteRawModelEntry,
+} from "../src/index.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Fixtures
+// ────────────────────────────────────────────────────────────────────────────
+
+const MODEL_PRIMARY: OmniRouteRawModelEntry = {
+  id: "claude-primary",
+  capabilities: {
+    tool_calling: true,
+    reasoning: true,
+    vision: true,
+    thinking: true,
+    temperature: true,
+  },
+  context_length: 200_000,
+  max_output_tokens: 64_000,
+  max_input_tokens: 180_000,
+  input_modalities: ["text", "image"],
+  output_modalities: ["text"],
+};
+
+const MODEL_SECONDARY: OmniRouteRawModelEntry = {
+  id: "claude-secondary",
+  capabilities: {
+    tool_calling: true,
+    reasoning: false,
+    vision: true,
+    thinking: false,
+    temperature: true,
+  },
+  context_length: 100_000,
+  max_output_tokens: 32_000,
+  max_input_tokens: 96_000,
+  input_modalities: ["text", "image"],
+  output_modalities: ["text"],
+};
+
+const MODEL_NO_TOOLS: OmniRouteRawModelEntry = {
+  id: "gemini-3-flash",
+  capabilities: { tool_calling: false, reasoning: false, vision: false, thinking: false },
+  context_length: 1_000_000,
+  max_output_tokens: 8_192,
+  input_modalities: ["text"],
+  output_modalities: ["text"],
+};
+
+const COMBO_CLAUDE_TIER: OmniRouteRawCombo = {
+  id: "combo-claude-tier",
+  name: "Claude Tier",
+  strategy: "priority",
+  models: [
+    { id: "s1", kind: "model", model: "claude-primary", weight: 100 },
+    { id: "s2", kind: "model", model: "claude-secondary", weight: 80 },
+  ],
+};
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+function stubModelsFetcher(
+  payload: OmniRouteRawModelEntry[]
+): OmniRouteModelsFetcher & { callCount: () => number } {
+  let n = 0;
+  const f: OmniRouteModelsFetcher = async () => {
+    n++;
+    return payload;
+  };
+  return Object.assign(f, { callCount: () => n });
+}
+
+function stubCombosFetcher(
+  payload: OmniRouteRawCombo[]
+): OmniRouteCombosFetcher & { callCount: () => number; callsBy: () => Array<[string, string]> } {
+  let n = 0;
+  const calls: Array<[string, string]> = [];
+  const f: OmniRouteCombosFetcher = async (baseURL, apiKey) => {
+    n++;
+    calls.push([baseURL, apiKey]);
+    return payload;
+  };
+  return Object.assign(f, {
+    callCount: () => n,
+    callsBy: () => calls,
+  });
+}
+
+function failingCombosFetcher(
+  err = new Error("boom")
+): OmniRouteCombosFetcher & { callCount: () => number } {
+  let n = 0;
+  const f: OmniRouteCombosFetcher = async () => {
+    n++;
+    throw err;
+  };
+  return Object.assign(f, { callCount: () => n });
+}
+
+const apiAuth = (key: string): unknown => ({ type: "api", key });
+
+// Capture console.warn invocations for the duration of a callback, then
+// restore the original. Needed because the collision + soft-fail paths
+// emit warnings we want to assert on.
+async function withWarnCapture<T>(
+  fn: (warnings: Array<{ args: unknown[] }>) => Promise<T>
+): Promise<{ result: T; warnings: Array<{ args: unknown[] }> }> {
+  const original = console.warn;
+  const warnings: Array<{ args: unknown[] }> = [];
+  console.warn = (...args: unknown[]) => {
+    warnings.push({ args });
+  };
+  try {
+    const result = await fn(warnings);
+    return { result, warnings };
+  } finally {
+    console.warn = original;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defaultOmniRouteCombosFetcher — envelope tolerance + error surfacing
+// ────────────────────────────────────────────────────────────────────────────
+
+test("defaultOmniRouteCombosFetcher: parses {combos:[…]} envelope", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: unknown) => {
+    const url = typeof input === "string" ? input : (input as { url: string }).url;
+    assert.equal(url, "https://or.example.com/api/combos");
+    return new Response(
+      JSON.stringify({
+        combos: [
+          { id: "c1", name: "Combo One", strategy: "priority", models: [] },
+          { id: "c2", name: "Combo Two", strategy: "weighted", models: [] },
+        ],
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+  }) as typeof fetch;
+  try {
+    const combos = await defaultOmniRouteCombosFetcher("https://or.example.com", "sk-test");
+    assert.equal(combos.length, 2);
+    assert.equal(combos[0].id, "c1");
+    assert.equal(combos[1].id, "c2");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: parses bare array envelope", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return new Response(JSON.stringify([{ id: "c1" }, { id: "c2" }, { not_an_id: 42 }]), {
+      status: 200,
+    });
+  }) as typeof fetch;
+  try {
+    const combos = await defaultOmniRouteCombosFetcher("https://or.example.com/v1", "sk-test");
+    // Strip /v1 before /api/combos, AND filter out entries with no string id.
+    assert.equal(combos.length, 2);
+    assert.equal(combos[0].id, "c1");
+    assert.equal(combos[1].id, "c2");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: strips trailing /v1 before /api/combos", async () => {
+  const originalFetch = globalThis.fetch;
+  let observedUrl = "";
+  globalThis.fetch = (async (input: unknown) => {
+    observedUrl = typeof input === "string" ? input : (input as { url: string }).url;
+    return new Response(JSON.stringify({ combos: [] }), { status: 200 });
+  }) as typeof fetch;
+  try {
+    await defaultOmniRouteCombosFetcher("https://or.example.com/v1/", "sk-test");
+    assert.equal(observedUrl, "https://or.example.com/api/combos");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: throws on non-2xx with status code in message", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () => {
+    return new Response(JSON.stringify({ error: "Invalid token" }), {
+      status: 403,
+      statusText: "Forbidden",
+    });
+  }) as typeof fetch;
+  try {
+    await assert.rejects(
+      async () => {
+        await defaultOmniRouteCombosFetcher("https://or.example.com", "sk-bad");
+      },
+      (err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        assert.match(msg, /403/, "status code must appear in message");
+        assert.match(msg, /\/api\/combos/, "url must appear in message");
+        return true;
+      }
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("defaultOmniRouteCombosFetcher: throws when apiKey missing", async () => {
+  await assert.rejects(
+    async () => defaultOmniRouteCombosFetcher("https://or.example.com", ""),
+    /apiKey required/
+  );
+});
+
+test("defaultOmniRouteCombosFetcher: throws when baseURL missing", async () => {
+  await assert.rejects(
+    async () => defaultOmniRouteCombosFetcher("", "sk-test"),
+    /baseURL required/
+  );
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// mapComboToModelV2 — LCD semantics
+// ────────────────────────────────────────────────────────────────────────────
+
+test("mapComboToModelV2: empty members → capabilities all false (defensive)", () => {
+  const m = mapComboToModelV2(
+    { id: "combo-empty", name: "Empty Combo" },
+    [],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.id, "combo-empty");
+  assert.equal(m.name, "Empty Combo");
+  assert.equal(m.capabilities.temperature, false);
+  assert.equal(m.capabilities.reasoning, false);
+  assert.equal(m.capabilities.attachment, false);
+  assert.equal(m.capabilities.toolcall, false);
+  assert.equal(m.capabilities.input.text, false);
+  assert.equal(m.capabilities.output.text, false);
+  assert.equal(m.limit.context, 0);
+  assert.equal(m.limit.output, 0);
+  assert.equal(m.limit.input, undefined);
+  assert.deepEqual(m.cost, { input: 0, output: 0, cache: { read: 0, write: 0 } });
+});
+
+test("mapComboToModelV2: all members reasoning=true → combo reasoning=true", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [
+      MODEL_PRIMARY,
+      {
+        ...MODEL_PRIMARY,
+        id: "p2",
+        capabilities: { ...MODEL_PRIMARY.capabilities, thinking: false, reasoning: true },
+      },
+    ],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.reasoning, true);
+});
+
+test("mapComboToModelV2: any member reasoning=false → combo reasoning=false", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS], // gemini-3-flash has reasoning:false, thinking:false
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.reasoning, false);
+});
+
+test("mapComboToModelV2: limit.context is min of members'", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  // min(200_000, 100_000, 1_000_000) = 100_000
+  assert.equal(m.limit.context, 100_000);
+  // min(64_000, 32_000, 8_192) = 8_192
+  assert.equal(m.limit.output, 8_192);
+});
+
+test("mapComboToModelV2: limit.input only emitted when EVERY member declares one", () => {
+  const m1 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  // Both declare max_input_tokens → limit.input = min(180000, 96000)
+  assert.equal(m1.limit.input, 96_000);
+
+  const m2 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS], // gemini-3-flash doesn't declare max_input_tokens
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.limit.input, undefined);
+});
+
+test("mapComboToModelV2: nice name preferred from combo.name", () => {
+  const m1 = mapComboToModelV2(
+    { id: "combo-x", name: "Pretty Name" },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m1.name, "Pretty Name");
+
+  // Falls back to id when name is absent or empty.
+  const m2 = mapComboToModelV2(
+    { id: "combo-y" },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.name, "combo-y");
+
+  const m3 = mapComboToModelV2(
+    { id: "combo-z", name: "   " },
+    [MODEL_PRIMARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m3.name, "combo-z");
+});
+
+test("mapComboToModelV2: attachment AND vision flag both honored across members", () => {
+  // MODEL_PRIMARY: vision=true; MODEL_SECONDARY: vision=true → combo attachment=true
+  const yes = mapComboToModelV2(
+    { id: "c1", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(yes.capabilities.attachment, true);
+
+  // Add a member with no vision/attachment → AND collapses to false
+  const no = mapComboToModelV2(
+    { id: "c2", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(no.capabilities.attachment, false);
+});
+
+test("mapComboToModelV2: modalities AND'd across members", () => {
+  const m = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_SECONDARY], // both have text+image
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.input.text, true);
+  assert.equal(m.capabilities.input.image, true);
+  assert.equal(m.capabilities.input.audio, false);
+
+  // Add a text-only member → image collapses to false.
+  const m2 = mapComboToModelV2(
+    { id: "c", models: [] },
+    [MODEL_PRIMARY, MODEL_NO_TOOLS],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m2.capabilities.input.text, true);
+  assert.equal(m2.capabilities.input.image, false);
+});
+
+test("mapComboToModelV2: api block matches providerId + baseURL", () => {
+  const m = mapComboToModelV2(
+    { id: "c" },
+    [MODEL_PRIMARY],
+    "omniroute-preprod",
+    "https://or-preprod.example.com/v1"
+  );
+  assert.equal(m.providerID, "omniroute-preprod");
+  assert.equal(m.api.id, "openai-compatible");
+  assert.equal(m.api.url, "https://or-preprod.example.com/v1");
+  assert.equal(m.api.npm, "@ai-sdk/openai-compatible");
+  assert.equal(m.status, "active");
+});
+
+test("mapComboToModelV2: explicit member temperature=false drops combo temperature=false", () => {
+  const tempFalse: OmniRouteRawModelEntry = {
+    id: "no-temp",
+    capabilities: { tool_calling: true, temperature: false },
+    context_length: 100_000,
+    max_output_tokens: 8_000,
+    input_modalities: ["text"],
+    output_modalities: ["text"],
+  };
+  const m = mapComboToModelV2(
+    { id: "c" },
+    [MODEL_PRIMARY, tempFalse],
+    "omniroute",
+    "https://or.example.com/v1"
+  );
+  assert.equal(m.capabilities.temperature, false);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// createOmniRouteProviderHook — combos merge + collision + soft-fail + cache
+// ────────────────────────────────────────────────────────────────────────────
+
+test("models() returns combo entries merged into the map", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY, MODEL_NO_TOOLS]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+
+  // 3 raw models + 1 combo = 4 entries
+  assert.equal(Object.keys(out).length, 4);
+  assert.ok(out["claude-primary"]);
+  assert.ok(out["claude-secondary"]);
+  assert.ok(out["gemini-3-flash"]);
+  assert.ok(out["combo/claude-tier"]);
+
+  const combo = out["combo/claude-tier"];
+  assert.equal(combo.name, "Combo: Claude Tier");
+  assert.equal(combo.providerID, "omniroute");
+  // LCD over claude-primary (200k, reasoning) + claude-secondary (100k, no reasoning)
+  assert.equal(combo.limit.context, 100_000);
+  assert.equal(combo.capabilities.reasoning, false);
+  assert.equal(combo.capabilities.toolcall, true);
+});
+
+test("models(): combo with unknown member ids degrades to all-false LCD posture", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]); // catalog only has claude-primary
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "phantom",
+      name: "Phantom Combo",
+      models: [
+        { id: "s1", kind: "model", model: "does-not-exist-1", weight: 50 },
+        { id: "s2", kind: "model", model: "does-not-exist-2", weight: 50 },
+      ],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.ok(out["combo/phantom-combo"]);
+  // With zero resolvable members, LCD = all-false (defensive posture).
+  assert.equal(out["combo/phantom-combo"].capabilities.toolcall, false);
+  assert.equal(out["combo/phantom-combo"].capabilities.reasoning, false);
+  assert.equal(out["combo/phantom-combo"].limit.context, 0);
+});
+
+test("models(): hidden combos are excluded from the map", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([
+    {
+      id: "visible",
+      name: "Visible",
+      models: [{ id: "s1", kind: "model", model: "claude-primary", weight: 100 }],
+    },
+    {
+      id: "hidden",
+      name: "Hidden",
+      isHidden: true,
+      models: [{ id: "s1", kind: "model", model: "claude-primary", weight: 100 }],
+    },
+  ]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.ok(out["combo/visible"]);
+  assert.ok(!out["combo/hidden"], "hidden combo must be omitted");
+});
+
+test("models(): combo name exactly matches raw model id → raw deleted, combo lives at combo/ key, no warn", async () => {
+  // Combo.name === raw model id triggers the dedup deletion. This mirrors
+  // the real OmniRoute payload where /v1/models pre-mirrors combos as
+  // no-slash raw entries whose ids match /api/combos friendly names.
+  const colliderCombo: OmniRouteRawCombo = {
+    id: "uuid-collider",
+    name: "claude-primary", // EXACT match to MODEL_PRIMARY.id
+    models: [{ id: "s1", kind: "model", model: "claude-secondary", weight: 100 }],
+  };
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = stubCombosFetcher([colliderCombo]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+
+  const { result: out, warnings } = await withWarnCapture(async (_w) => {
+    return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  });
+
+  // Raw model deleted by combo-name dedup; combo surfaces under combo/<slug>.
+  assert.equal(out["claude-primary"], undefined, "raw deleted by combo-name dedup");
+  assert.ok(out["combo/claude-primary"], "combo surfaces under combo/ namespace");
+  assert.equal(out["combo/claude-primary"].name, "Combo: claude-primary");
+
+  // No collision warning fires — dedup makes keys disjoint.
+  const collisionWarns = warnings.filter((w) => {
+    const msg = w.args[0];
+    return typeof msg === "string" && msg.includes("collides");
+  });
+  assert.equal(collisionWarns.length, 0, "no collision warn after dedup");
+});
+
+test("models(): two combos with same slug → second gets disambiguator suffix", async () => {
+  // Both combos slug to `claude` — second must get `combo/claude-<id-prefix>`.
+  const combos: OmniRouteRawCombo[] = [
+    {
+      id: "uuid-a",
+      name: "Claude",
+      models: [{ id: "s", kind: "model", model: "claude-primary", weight: 1 }],
+    },
+    {
+      id: "uuid-b",
+      name: "Claude",
+      models: [{ id: "s", kind: "model", model: "claude-secondary", weight: 1 }],
+    },
+  ];
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    {
+      fetcher: stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]),
+      combosFetcher: stubCombosFetcher(combos),
+    }
+  );
+
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  // First combo gets the bare slug; second gets disambiguated.
+  assert.ok(out["combo/claude"], "first combo at bare slug");
+  assert.ok(out["combo/claude-uuid"], "second combo disambiguated by id prefix");
+});
+
+test("models(): combos fetch fails → falls back to models-only, warn emitted, no throw", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = failingCombosFetcher(new Error("ECONNRESET"));
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+
+  const { result: out, warnings } = await withWarnCapture(async () => {
+    return hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  });
+
+  // Catalog includes the models but NOT any combo entries.
+  assert.equal(Object.keys(out).length, 2);
+  assert.ok(out["claude-primary"]);
+  assert.ok(out["claude-secondary"]);
+
+  // Soft-fail warning surfaced.
+  const softFail = warnings.find((w) => {
+    const msg = w.args[0];
+    return typeof msg === "string" && msg.includes("combos fetch failed");
+  });
+  assert.ok(softFail, "soft-fail warning must be emitted on combos fetch error");
+  assert.equal(combosFetcher.callCount(), 1);
+});
+
+test("models(): combos cached + reused within TTL (one combo fetch per TTL window)", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY, MODEL_SECONDARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher: modelsFetcher, combosFetcher, now: () => nowMs }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 30_000; // half the TTL
+  const second = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(combosFetcher.callCount(), 1, "combos fetched only once within TTL");
+  assert.equal(modelsFetcher.callCount(), 1, "models fetched only once within TTL");
+  assert.ok(second["combo/claude-tier"]);
+});
+
+test("models(): combos refetched after TTL expiry (same key as models)", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher: modelsFetcher, combosFetcher, now: () => nowMs }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 60_001;
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(combosFetcher.callCount(), 2, "combos must refetch past TTL");
+  assert.equal(modelsFetcher.callCount(), 2, "models must refetch past TTL");
+});
+
+test("models(): combos fetcher receives the resolved baseURL + apiKey", async () => {
+  const modelsFetcher = stubModelsFetcher([MODEL_PRIMARY]);
+  const combosFetcher = stubCombosFetcher([COMBO_CLAUDE_TIER]);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher: modelsFetcher, combosFetcher }
+  );
+  await hook.models!({} as never, { auth: apiAuth("sk-spy") as never });
+  assert.deepEqual(combosFetcher.callsBy()[0], ["https://or.example.com/v1", "sk-spy"]);
+});

@omniroute/opencode-plugin/tests/disk-snapshot-perms.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Regression test for the disk-snapshot file permissions (release/v3.8.2
+ * review finding C2). The snapshot embeds provider topology + connection
+ * records and lives alongside auth.json (0o600), so it must NOT be readable by
+ * group/other. Before the fix it was written with the default (typically
+ * world-readable 0o644) mode.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  defaultDiskSnapshotWriter,
+  diskSnapshotPath,
+  type OmniRouteFetchCacheEntry,
+} from "../src/index.js";
+
+function makeEntry(): Omit<OmniRouteFetchCacheEntry, "expiresAt"> {
+  return {
+    rawModels: [],
+    rawCombos: [],
+    rawEnrichment: new Map(),
+    rawCompressionCombos: [],
+    rawConnections: [],
+  };
+}
+
+test("defaultDiskSnapshotWriter writes an owner-only (no group/other) snapshot", async (t) => {
+  // POSIX-only assertion; Windows does not honor numeric file modes.
+  if (process.platform === "win32") {
+    t.skip("file mode semantics are POSIX-only");
+    return;
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-disk-perms-"));
+  const prevDataDir = process.env.OPENCODE_DATA_DIR;
+  process.env.OPENCODE_DATA_DIR = tmp;
+
+  try {
+    await defaultDiskSnapshotWriter("perm-test", makeEntry());
+
+    const file = diskSnapshotPath("perm-test");
+    assert.ok(fs.existsSync(file), "snapshot file should be written");
+
+    const fileMode = fs.statSync(file).mode & 0o777;
+    assert.equal(
+      fileMode & 0o077,
+      0,
+      `snapshot must not be group/other accessible (got ${fileMode.toString(8)})`
+    );
+
+    const dirMode = fs.statSync(path.dirname(file)).mode & 0o777;
+    assert.equal(
+      dirMode & 0o077,
+      0,
+      `plugins dir must not be group/other accessible (got ${dirMode.toString(8)})`
+    );
+  } finally {
+    if (prevDataDir === undefined) delete process.env.OPENCODE_DATA_DIR;
+    else process.env.OPENCODE_DATA_DIR = prevDataDir;
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});

@omniroute/opencode-plugin/tests/fetch-interceptor.test.ts

@@ -0,0 +1,269 @@
+/**
+ * T-04 fetch-interceptor contract tests.
+ *
+ * Covers `createOmniRouteFetchInterceptor` (URL-prefix gating, header merge,
+ * Content-Type defaulting, input-shape polymorphism) plus the loader
+ * integration that wires it into the AuthHook return shape.
+ *
+ * Strategy: replace `globalThis.fetch` with a closure-based recorder for the
+ * duration of each test (saved-and-restored in try/finally — node:test has
+ * no built-in spy/restore lifecycle). The recorder captures `(input, init)`
+ * as observed by the wrapped global call so we can assert on what was
+ * forwarded after header injection.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createOmniRouteAuthHook, createOmniRouteFetchInterceptor } from "../src/index.js";
+
+type FetchCall = { input: Parameters<typeof fetch>[0]; init?: RequestInit };
+
+function installFetchRecorder(response: Response = new Response("ok")) {
+  const calls: FetchCall[] = [];
+  const original = globalThis.fetch;
+  globalThis.fetch = (async (input: any, init?: any) => {
+    calls.push({ input, init });
+    return response;
+  }) as typeof fetch;
+  const restore = () => {
+    globalThis.fetch = original;
+  };
+  return { calls, restore };
+}
+
+const BASE = "https://or.example.com/v1";
+const KEY = "sk-test-fetch";
+
+test("createOmniRouteFetchInterceptor: targets baseURL → Authorization header injected", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ x: 1 }),
+    });
+    assert.equal(calls.length, 1);
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: targets baseURL → Authorization OVERRIDES caller-supplied Bearer", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: "{}",
+      headers: { Authorization: "Bearer attacker-key" },
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    // We own the apiKey for this provider — caller-supplied Bearer must lose.
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: targets baseURL + body → Content-Type defaults to application/json", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ m: "x" }),
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Content-Type"), "application/json");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: caller-set Content-Type is NOT overwritten", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/v2/whatever`, {
+      method: "POST",
+      body: "raw",
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Content-Type"), "text/plain; charset=utf-8");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: non-baseURL host → passthrough, no Authorization injected", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f("https://third-party.example.org/v1/chat", {
+      method: "POST",
+      body: "{}",
+      headers: { "X-Caller": "yes" },
+    });
+    const sent = calls[0]!;
+    // Init forwarded verbatim — no header injection.
+    const sentHeaders = new Headers((sent.init as RequestInit | undefined)?.headers);
+    assert.equal(sentHeaders.get("Authorization"), null, "MUST NOT leak apiKey");
+    assert.equal(sentHeaders.get("X-Caller"), "yes");
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: refuses suffix-spoof — `${base}-attacker.evil` does NOT match baseURL", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    // baseURL is `https://or.example.com/v1`. A spoofed
+    // `https://or.example.com/v1-attacker.evil/chat` shares the literal prefix
+    // but is NOT under our origin path — must be treated as passthrough.
+    await f("https://or.example.com/v1-attacker.evil/chat", {
+      method: "POST",
+      body: "{}",
+    });
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit | undefined)?.headers);
+    assert.equal(sentHeaders.get("Authorization"), null);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: URL object input is handled", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(new URL(`${BASE}/models`), {});
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: Request input is handled (reads .url)", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    const req = new Request(`${BASE}/chat/completions`, {
+      method: "POST",
+      body: JSON.stringify({ a: 1 }),
+      headers: { "X-Caller": "preserved" },
+    });
+    await f(req);
+    const sent = calls[0]!;
+    // The interceptor forwards the original Request as `input` but layers our
+    // headers into the `init`. We assert against the init view since fetch()
+    // resolves headers from init first when both are present.
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+    assert.equal(
+      sentHeaders.get("X-Caller"),
+      "preserved",
+      "Request-attached headers must survive the merge"
+    );
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: trailing slash in baseURL is normalized", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({
+      apiKey: KEY,
+      baseURL: `${BASE}////`,
+    });
+    await f(`${BASE}/models`, {});
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});
+
+test("createOmniRouteFetchInterceptor: GET without body does NOT set Content-Type", async () => {
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const f = createOmniRouteFetchInterceptor({ apiKey: KEY, baseURL: BASE });
+    await f(`${BASE}/models`); // no init at all
+    const sent = calls[0]!;
+    const sentHeaders = new Headers((sent.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+    assert.equal(
+      sentHeaders.get("Content-Type"),
+      null,
+      "Content-Type should only default when a body exists"
+    );
+  } finally {
+    restore();
+  }
+});
+
+// ----------------------------------------------------------------------------
+// loader integration
+// ----------------------------------------------------------------------------
+
+test("loader: returns fetch fn when apiKey + baseURL both present (via opts)", async () => {
+  const hook = createOmniRouteAuthHook({ baseURL: BASE });
+  const result = await hook.loader!(async () => ({ type: "api", key: KEY }) as never, {} as never);
+  assert.equal((result as { apiKey: string }).apiKey, KEY);
+  assert.equal((result as { baseURL: string }).baseURL, BASE);
+  assert.equal(
+    typeof (result as { fetch?: unknown }).fetch,
+    "function",
+    "loader must wire fetch interceptor when baseURL resolves"
+  );
+});
+
+test("loader: returns fetch fn when baseURL is stashed on the auth credential", async () => {
+  // Some auth backends attach baseURL alongside the key (post-/connect flow).
+  // The loader should pick it up even when plugin opts.baseURL is unset.
+  const hook = createOmniRouteAuthHook();
+  const result = await hook.loader!(
+    async () => ({ type: "api", key: KEY, baseURL: BASE }) as never,
+    {} as never
+  );
+  assert.equal((result as { baseURL?: string }).baseURL, BASE);
+  assert.equal(typeof (result as { fetch?: unknown }).fetch, "function");
+});
+
+test("loader: omits fetch fn when baseURL missing (apiKey-only return)", async () => {
+  const hook = createOmniRouteAuthHook(); // no baseURL opt
+  const result = await hook.loader!(async () => ({ type: "api", key: KEY }) as never, {} as never);
+  // Interceptor needs a baseURL to gate-keep; without one, fall back to
+  // apiKey-only and let the SDK use its default fetch.
+  assert.deepEqual(result, { apiKey: KEY });
+});
+
+test("loader integration: wired interceptor actually injects Bearer when invoked", async () => {
+  // End-to-end: pull the fetch fn out of the loader return and exercise it,
+  // proving the wiring matches the standalone interceptor's contract.
+  const { calls, restore } = installFetchRecorder();
+  try {
+    const hook = createOmniRouteAuthHook({ baseURL: BASE });
+    const result = await hook.loader!(
+      async () => ({ type: "api", key: KEY }) as never,
+      {} as never
+    );
+    const wiredFetch = (result as { fetch: typeof fetch }).fetch;
+    await wiredFetch(`${BASE}/v1/models`, {});
+    assert.equal(calls.length, 1);
+    const sentHeaders = new Headers((calls[0]!.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), `Bearer ${KEY}`);
+  } finally {
+    restore();
+  }
+});

@omniroute/opencode-plugin/tests/gemini-sanitize.test.ts

@@ -0,0 +1,410 @@
+/**
+ * T-06 Gemini tool-schema sanitisation contract tests.
+ *
+ * Three layers under test:
+ *   1. `sanitizeGeminiToolSchemas` — pure function; key stripping + clone
+ *      semantics on chat-completion + Responses-API shapes.
+ *   2. `shouldSanitizeForGemini` — model-string detection (liberal).
+ *   3. `createGeminiSanitizingFetch` — wrapper composition; URL gating,
+ *      body-shape polymorphism, streaming-body bypass, fail-open behaviour,
+ *      composition with the T-04 Bearer interceptor.
+ *
+ * Strategy: same posture as fetch-interceptor.test.ts — install a
+ * closure-based fetch recorder; assert on the `(input, init)` observed by
+ * the inner fetch after the sanitising wrapper has had its say.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  __resetGeminiStreamingWarning,
+  createGeminiSanitizingFetch,
+  createOmniRouteFetchInterceptor,
+  sanitizeGeminiToolSchemas,
+  shouldSanitizeForGemini,
+} from "../src/index.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ────────────────────────────────────────────────────────────────────────────
+
+type FetchCall = { input: Parameters<typeof fetch>[0]; init?: RequestInit };
+
+function recorder(response: Response = new Response("ok")): {
+  fn: typeof fetch;
+  calls: FetchCall[];
+} {
+  const calls: FetchCall[] = [];
+  const fn = (async (input: any, init?: any) => {
+    calls.push({ input, init });
+    return response;
+  }) as typeof fetch;
+  return { fn, calls };
+}
+
+function bodyAsRecord(init: RequestInit | undefined): Record<string, unknown> {
+  const b = init?.body;
+  if (typeof b !== "string") {
+    throw new Error(`expected string body, got ${typeof b}`);
+  }
+  return JSON.parse(b) as Record<string, unknown>;
+}
+
+// Sample tool payloads — small enough to inline, big enough to cover
+// chat-completion + Responses-API + nested properties.
+
+function chatCompletionsWithDollarSchema(): Record<string, unknown> {
+  return {
+    model: "gemini-2.5-pro",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "search",
+          parameters: {
+            $schema: "http://json-schema.org/draft-07/schema#",
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              q: { type: "string" },
+            },
+            required: ["q"],
+          },
+        },
+      },
+    ],
+  };
+}
+
+function responsesApiWithRef(): Record<string, unknown> {
+  return {
+    model: "gemini-2.5-flash",
+    tools: [
+      {
+        type: "function",
+        name: "lookup",
+        input_schema: {
+          type: "object",
+          $ref: "#/definitions/Lookup",
+          properties: {
+            id: { type: "string", ref: "Id" },
+          },
+        },
+      },
+    ],
+  };
+}
+
+function nestedPropertiesPayload(): Record<string, unknown> {
+  return {
+    model: "gemini-pro",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "deep",
+          parameters: {
+            type: "object",
+            properties: {
+              outer: {
+                type: "object",
+                $schema: "http://json-schema.org/draft-07/schema#",
+                properties: {
+                  inner: {
+                    type: "object",
+                    additionalProperties: true,
+                    $ref: "#/inner",
+                    properties: {
+                      leaf: { type: "string" },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    ],
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// sanitizeGeminiToolSchemas — pure function
+// ────────────────────────────────────────────────────────────────────────────
+
+test("sanitizeGeminiToolSchemas: strips $schema from top-level", () => {
+  const input = {
+    model: "gemini-2.5-pro",
+    $schema: "http://json-schema.org/draft-07/schema#",
+    tools: [],
+  };
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  assert.equal(out.$schema, undefined);
+  assert.equal(out.model, "gemini-2.5-pro");
+});
+
+test("sanitizeGeminiToolSchemas: strips $ref + additionalProperties from tools[].function.parameters", () => {
+  const input = chatCompletionsWithDollarSchema();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const params = (out.tools as Array<{ function: { parameters: Record<string, unknown> } }>)[0]!
+    .function.parameters;
+  assert.equal(params.$schema, undefined);
+  assert.equal(params.additionalProperties, undefined);
+  // Untouched keys survive.
+  assert.equal(params.type, "object");
+  assert.deepEqual(params.required, ["q"]);
+});
+
+test("sanitizeGeminiToolSchemas: strips nested $schema from properties.x.properties.y", () => {
+  const input = nestedPropertiesPayload();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const params = (out.tools as Array<{ function: { parameters: Record<string, unknown> } }>)[0]!
+    .function.parameters;
+  const outer = (params.properties as Record<string, Record<string, unknown>>).outer!;
+  const inner = (outer.properties as Record<string, Record<string, unknown>>).inner!;
+  assert.equal(outer.$schema, undefined);
+  assert.equal(inner.$ref, undefined);
+  assert.equal(inner.additionalProperties, undefined);
+  // Leaf still intact.
+  assert.deepEqual(inner.properties, { leaf: { type: "string" } });
+});
+
+test("sanitizeGeminiToolSchemas: handles Responses-API tools[].input_schema shape", () => {
+  const input = responsesApiWithRef();
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  const inputSchema = (out.tools as Array<{ input_schema: Record<string, unknown> }>)[0]!
+    .input_schema;
+  assert.equal(inputSchema.$ref, undefined);
+  // Nested `ref` (lowercase) also stripped.
+  const props = inputSchema.properties as Record<string, Record<string, unknown>>;
+  assert.equal(props.id!.ref, undefined);
+  assert.equal(props.id!.type, "string");
+});
+
+test("sanitizeGeminiToolSchemas: leaves payload without tools untouched", () => {
+  const input = { model: "gemini-2.5-pro", messages: [{ role: "user", content: "hi" }] };
+  const out = sanitizeGeminiToolSchemas(input) as Record<string, unknown>;
+  assert.deepEqual(out, input);
+});
+
+test("sanitizeGeminiToolSchemas: does not mutate input (returned object is distinct)", () => {
+  const input = chatCompletionsWithDollarSchema();
+  const beforeJson = JSON.stringify(input);
+  const out = sanitizeGeminiToolSchemas(input);
+  // Input bit-identical to its pre-sanitise serialisation.
+  assert.equal(JSON.stringify(input), beforeJson);
+  // Output is a different reference.
+  assert.notEqual(out, input);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// shouldSanitizeForGemini — detection
+// ────────────────────────────────────────────────────────────────────────────
+
+test("shouldSanitizeForGemini: gemini-2.5-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "gemini-2.5-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: models/gemini-pro → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "models/gemini-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: google-vertex/gemini-1.5-flash → true", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "google-vertex/gemini-1.5-flash" }), true);
+});
+
+test("shouldSanitizeForGemini: gemini-cli/gemini-2.5-pro → true (real OmniRoute alias)", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "gemini-cli/gemini-2.5-pro" }), true);
+});
+
+test("shouldSanitizeForGemini: claude-sonnet-4 → false", () => {
+  assert.equal(shouldSanitizeForGemini({ model: "claude-sonnet-4" }), false);
+});
+
+test("shouldSanitizeForGemini: payload.model missing → false", () => {
+  assert.equal(shouldSanitizeForGemini({ messages: [] }), false);
+});
+
+test("shouldSanitizeForGemini: payload is null → false", () => {
+  assert.equal(shouldSanitizeForGemini(null), false);
+});
+
+test("shouldSanitizeForGemini: payload.model is non-string → false", () => {
+  assert.equal(shouldSanitizeForGemini({ model: 42 }), false);
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// createGeminiSanitizingFetch — wrapper
+// ────────────────────────────────────────────────────────────────────────────
+
+const URL_CHAT = "https://or.example.com/v1/chat/completions";
+const URL_RESPONSES = "https://or.example.com/v1/responses";
+const URL_MODELS = "https://or.example.com/v1/models";
+
+test("createGeminiSanitizingFetch: gemini model + chat/completions → tool schemas stripped before forward", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_CHAT, {
+    method: "POST",
+    body: JSON.stringify(chatCompletionsWithDollarSchema()),
+  });
+  assert.equal(rec.calls.length, 1);
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const params = (
+    forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+  )[0]!.function.parameters;
+  assert.equal(params.$schema, undefined);
+  assert.equal(params.additionalProperties, undefined);
+});
+
+test("createGeminiSanitizingFetch: non-gemini model + chat/completions → body passed through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  const originalBody = JSON.stringify({
+    model: "claude-sonnet-4",
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "x",
+          parameters: { $schema: "keep-me", type: "object" },
+        },
+      },
+    ],
+  });
+  await wrapped(URL_CHAT, { method: "POST", body: originalBody });
+  // Identity check on body — wrapper must NOT mutate non-Gemini payloads.
+  assert.equal(rec.calls[0]!.init!.body, originalBody);
+});
+
+test("createGeminiSanitizingFetch: gemini model + /v1/models (non-completion endpoint) → body passed through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  // GET /v1/models has no body in production; assert that even if a caller
+  // attached a Gemini-shaped body to a non-completion URL, the wrapper
+  // doesn't touch it.
+  const body = JSON.stringify(chatCompletionsWithDollarSchema());
+  await wrapped(URL_MODELS, { method: "POST", body });
+  assert.equal(rec.calls[0]!.init!.body, body);
+});
+
+test("createGeminiSanitizingFetch: gemini model + /responses endpoint → input_schema stripped", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_RESPONSES, {
+    method: "POST",
+    body: JSON.stringify(responsesApiWithRef()),
+  });
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const schema = (forwarded.tools as Array<{ input_schema: Record<string, unknown> }>)[0]!
+    .input_schema;
+  assert.equal(schema.$ref, undefined);
+});
+
+test("createGeminiSanitizingFetch: gemini model + Request input with body → tool schemas stripped", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  const req = new Request(URL_CHAT, {
+    method: "POST",
+    body: JSON.stringify(chatCompletionsWithDollarSchema()),
+    headers: { "Content-Type": "application/json" },
+  });
+  await wrapped(req);
+  const forwarded = bodyAsRecord(rec.calls[0]!.init);
+  const params = (
+    forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+  )[0]!.function.parameters;
+  assert.equal(params.$schema, undefined);
+});
+
+test("createGeminiSanitizingFetch: gemini model + ReadableStream body → skipped + warn emitted once", async () => {
+  __resetGeminiStreamingWarning();
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+
+  // Capture console.warn for the duration of this test.
+  const warnings: string[] = [];
+  const originalWarn = console.warn;
+  console.warn = (...args: unknown[]) => {
+    warnings.push(args.map(String).join(" "));
+  };
+
+  try {
+    const stream1 = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("{}"));
+        controller.close();
+      },
+    });
+    const stream2 = new ReadableStream({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode("{}"));
+        controller.close();
+      },
+    });
+    // Two streaming calls — only one warn expected.
+    await wrapped(URL_CHAT, { method: "POST", body: stream1 });
+    await wrapped(URL_CHAT, { method: "POST", body: stream2 });
+  } finally {
+    console.warn = originalWarn;
+  }
+
+  // Both calls forwarded to inner fetch with their streams intact.
+  assert.equal(rec.calls.length, 2);
+  // ONE warning total — one-shot latch held.
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0]!, /streaming Request body, skipping schema strip/);
+});
+
+test("createGeminiSanitizingFetch: invalid JSON body → pass through, no throw", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  // Garbage body must not crash the wrapper.
+  await wrapped(URL_CHAT, { method: "POST", body: "this is not json{{" });
+  assert.equal(rec.calls.length, 1);
+  assert.equal(rec.calls[0]!.init!.body, "this is not json{{");
+});
+
+test("createGeminiSanitizingFetch: empty body → pass through unchanged", async () => {
+  const rec = recorder();
+  const wrapped = createGeminiSanitizingFetch(rec.fn);
+  await wrapped(URL_CHAT, { method: "POST" });
+  assert.equal(rec.calls.length, 1);
+});
+
+test("createGeminiSanitizingFetch: composes correctly with createOmniRouteFetchInterceptor (Bearer + sanitization)", async () => {
+  // Save and replace globalThis.fetch — the Bearer interceptor calls global
+  // fetch when the URL targets its baseURL.
+  const originalFetch = globalThis.fetch;
+  const observed: FetchCall[] = [];
+  globalThis.fetch = (async (input: any, init?: any) => {
+    observed.push({ input, init });
+    return new Response("ok");
+  }) as typeof fetch;
+
+  try {
+    const composed = createGeminiSanitizingFetch(
+      createOmniRouteFetchInterceptor({
+        apiKey: "sk-test",
+        baseURL: "https://or.example.com/v1",
+      })
+    );
+    await composed(URL_CHAT, {
+      method: "POST",
+      body: JSON.stringify(chatCompletionsWithDollarSchema()),
+    });
+
+    assert.equal(observed.length, 1);
+    // Bearer injected (header concern).
+    const sentHeaders = new Headers((observed[0]!.init as RequestInit).headers);
+    assert.equal(sentHeaders.get("Authorization"), "Bearer sk-test");
+    // Schema sanitised (body concern).
+    const forwarded = bodyAsRecord(observed[0]!.init);
+    const params = (
+      forwarded.tools as Array<{ function: { parameters: Record<string, unknown> } }>
+    )[0]!.function.parameters;
+    assert.equal(params.$schema, undefined);
+    assert.equal(params.additionalProperties, undefined);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

@omniroute/opencode-plugin/tests/multi-instance.test.ts

@@ -0,0 +1,136 @@
+/**
+ * T-08 multi-instance smoke.
+ *
+ * Validates that two `OmniRoutePlugin(input, opts)` invocations with
+ * different `providerId` values coexist without sharing mutable state.
+ * This is the contract that lets opencode.json declare prod + preprod
+ * side by side:
+ *
+ *   "plugin": [
+ *     ["@omniroute/opencode-plugin", {"providerId": "omniroute-prod",    "baseURL": "https://or.example/v1"}],
+ *     ["@omniroute/opencode-plugin", {"providerId": "omniroute-preprod", "baseURL": "https://or-preprod.example/v1"}]
+ *   ]
+ *
+ * Assertions:
+ *   - Each invocation returns its own hooks object (no identity reuse).
+ *   - Each `auth` hook carries its own `provider` matching opts.providerId.
+ *   - Each `auth.methods` array is its own array (not the same reference).
+ *   - Calling the factory twice with IDENTICAL opts still yields two
+ *     independent objects (no instance reuse / no shared closure cache).
+ *   - Mutating one instance's auth hook does NOT bleed into the other.
+ *   - Each instance's loader closure captures its OWN baseURL — no
+ *     last-write-wins module-scope state.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { OmniRoutePlugin } from "../src/index.js";
+
+const fakeInput = {} as Parameters<typeof OmniRoutePlugin>[0];
+
+test("multi-instance: two plugin invocations bind to their own providerId", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-prod",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-preprod",
+    baseURL: "https://b.example/v1",
+  });
+
+  assert.equal(a.auth?.provider, "omniroute-prod");
+  assert.equal(b.auth?.provider, "omniroute-preprod");
+});
+
+test("multi-instance: hook objects + nested arrays are independent references", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "alpha",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "bravo",
+    baseURL: "https://b.example/v1",
+  });
+
+  assert.notEqual(a, b, "top-level hooks objects must not be the same reference");
+  assert.notEqual(a.auth, b.auth, "auth hooks must not be the same reference");
+  assert.notEqual(
+    a.auth?.methods,
+    b.auth?.methods,
+    "methods arrays must not be the same reference"
+  );
+});
+
+test("multi-instance: identical opts twice still yield independent objects", async () => {
+  const opts = { providerId: "twin", baseURL: "https://twin.example/v1" };
+  const first = await OmniRoutePlugin(fakeInput, { ...opts });
+  const second = await OmniRoutePlugin(fakeInput, { ...opts });
+
+  assert.notEqual(first, second);
+  assert.notEqual(first.auth, second.auth);
+  assert.notEqual(first.auth?.methods, second.auth?.methods);
+  // Same provider id is fine — what matters is no shared mutable state.
+  assert.equal(first.auth?.provider, "twin");
+  assert.equal(second.auth?.provider, "twin");
+});
+
+test("multi-instance: mutating instance A's auth.methods does not affect instance B", async () => {
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "iso-a",
+    baseURL: "https://a.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "iso-b",
+    baseURL: "https://b.example/v1",
+  });
+
+  const beforeLen = b.auth?.methods?.length ?? 0;
+  // Mutate a's methods array — extend it; b's must be untouched.
+  // We don't know the concrete method shape so push a sentinel cast.
+  a.auth?.methods?.push({ type: "api", label: "sentinel" } as never);
+  assert.equal(b.auth?.methods?.length, beforeLen, "instance B leaked from instance A mutation");
+});
+
+test("multi-instance: loader closures see their own opts (not last-write-wins)", async () => {
+  // Each plugin's loader builds its loader payload from the providerId/baseURL
+  // captured at invocation time. If the factory accidentally shared a closure
+  // (e.g. a module-scope let that the last invocation overwrites), both
+  // loaders would emit the same baseURL. Verify they don't.
+  const a = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-prod",
+    baseURL: "https://prod.example/v1",
+  });
+  const b = await OmniRoutePlugin(fakeInput, {
+    providerId: "omniroute-preprod",
+    baseURL: "https://preprod.example/v1",
+  });
+
+  assert.ok(a.auth?.loader, "instance A must have a loader");
+  assert.ok(b.auth?.loader, "instance B must have a loader");
+
+  const getAuthA = async () => ({ type: "api", key: "sk-prod" }) as never;
+  const getAuthB = async () => ({ type: "api", key: "sk-preprod" }) as never;
+
+  const rA = (await a.auth!.loader!(getAuthA, {} as never)) as Record<string, unknown>;
+  const rB = (await b.auth!.loader!(getAuthB, {} as never)) as Record<string, unknown>;
+
+  assert.equal(rA.apiKey, "sk-prod");
+  assert.equal(rA.baseURL, "https://prod.example/v1");
+  assert.equal(rB.apiKey, "sk-preprod");
+  assert.equal(rB.baseURL, "https://preprod.example/v1");
+});
+
+test("multi-instance: invalid opts on one instance does not poison the other", async () => {
+  // Sequencing: bad opts → good opts. The bad call must throw cleanly; the
+  // good call must still produce a working hooks object. Confirms no
+  // half-built module-level state survives a failed parse.
+  await assert.rejects(
+    () => OmniRoutePlugin(fakeInput, { providerId: "bad id!" } as never),
+    /providerId/
+  );
+  const ok = await OmniRoutePlugin(fakeInput, {
+    providerId: "recovered",
+    baseURL: "https://ok.example/v1",
+  });
+  assert.equal(ok.auth?.provider, "recovered");
+});

@omniroute/opencode-plugin/tests/options-schema.test.ts

@@ -0,0 +1,104 @@
+/**
+ * T-08 options-schema tests.
+ *
+ * Covers `parseOmniRoutePluginOptions(opts)` — the strict Zod gate that
+ * validates the second-arg `PluginOptions` bag from opencode.json before
+ * any hook is wired. Anti-pattern checklist mirrored here:
+ *
+ *  - `null` / `undefined` must collapse to `{}` (defaults apply downstream).
+ *  - Unknown keys must THROW (`.strict()` catches opencode.json typos).
+ *  - Validation runs at parse time, not import time (module loads cleanly).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseOmniRoutePluginOptions } from "../src/index.js";
+
+test("parseOmniRoutePluginOptions: undefined → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions(undefined), {});
+});
+
+test("parseOmniRoutePluginOptions: null → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions(null), {});
+});
+
+test("parseOmniRoutePluginOptions: empty object → {}", () => {
+  assert.deepEqual(parseOmniRoutePluginOptions({}), {});
+});
+
+test("parseOmniRoutePluginOptions: valid providerId → returns it", () => {
+  const r = parseOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
+  assert.equal(r.providerId, "omniroute-preprod");
+});
+
+test("parseOmniRoutePluginOptions: invalid providerId (special chars) → throws", () => {
+  assert.throws(
+    () => parseOmniRoutePluginOptions({ providerId: "omniroute prod!" }),
+    /providerId.*slug/i
+  );
+});
+
+test("parseOmniRoutePluginOptions: empty providerId → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ providerId: "" }), /providerId/i);
+});
+
+test("parseOmniRoutePluginOptions: valid modelCacheTtl → returns it", () => {
+  const r = parseOmniRoutePluginOptions({ modelCacheTtl: 60_000 });
+  assert.equal(r.modelCacheTtl, 60_000);
+});
+
+test("parseOmniRoutePluginOptions: negative modelCacheTtl → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ modelCacheTtl: -1 }), /modelCacheTtl/i);
+});
+
+test("parseOmniRoutePluginOptions: zero modelCacheTtl → throws (positive required)", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ modelCacheTtl: 0 }), /modelCacheTtl/i);
+});
+
+test("parseOmniRoutePluginOptions: invalid baseURL (not a URL) → throws", () => {
+  assert.throws(() => parseOmniRoutePluginOptions({ baseURL: "not-a-url" }), /baseURL/i);
+});
+
+test("parseOmniRoutePluginOptions: unknown key → throws (strict mode catches typos)", () => {
+  assert.throws(
+    () =>
+      parseOmniRoutePluginOptions({
+        providerId: "omniroute",
+        provider_id: "typo-here",
+      }),
+    /provider_id|unrecognized/i
+  );
+});
+
+test("parseOmniRoutePluginOptions: all four fields populated correctly → returns them", () => {
+  const opts = {
+    providerId: "omniroute-prod",
+    displayName: "OmniRoute Production",
+    modelCacheTtl: 120_000,
+    baseURL: "https://or.example.com/v1",
+  };
+  const r = parseOmniRoutePluginOptions(opts);
+  assert.deepEqual(r, opts);
+});
+
+test("parseOmniRoutePluginOptions: error message lists every issue path", () => {
+  // Two bad fields at once → error string should mention BOTH.
+  try {
+    parseOmniRoutePluginOptions({
+      providerId: "",
+      baseURL: "garbage",
+    });
+    assert.fail("expected throw");
+  } catch (err) {
+    const msg = (err as Error).message;
+    assert.match(msg, /providerId/);
+    assert.match(msg, /baseURL/);
+  }
+});
+
+test("parseOmniRoutePluginOptions: module import alone does NOT throw", async () => {
+  // Re-importing the entry must not trigger validation; validation only fires
+  // on explicit parseOmniRoutePluginOptions / OmniRoutePlugin invocation.
+  const mod = await import("../src/index.js");
+  assert.equal(typeof mod.parseOmniRoutePluginOptions, "function");
+});

@omniroute/opencode-plugin/tests/provider.test.ts

@@ -0,0 +1,269 @@
+/**
+ * T-03 provider-hook contract tests.
+ *
+ * Covers `createOmniRouteProviderHook(opts, deps)`:
+ *   - hook.id binds to resolved providerId (single + multi-instance)
+ *   - models() narrows ctx.auth, fetches via injected fetcher, caches per
+ *     (baseURL, apiKey) tuple, refetches after TTL
+ *   - mapRawModelToModelV2 emits a v2 Model shape matching the
+ *     @opencode-ai/sdk/v2 type
+ *
+ * Mocking strategy: the fetcher is dependency-injected at hook construction
+ * (`deps.fetcher`). No global fetch monkey-patch needed. `deps.now` lets us
+ * fast-forward time deterministically for TTL assertions.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  createOmniRouteProviderHook,
+  mapRawModelToModelV2,
+  type OmniRouteRawModelEntry,
+  type OmniRouteModelsFetcher,
+} from "../src/index.js";
+
+const FIXTURE: OmniRouteRawModelEntry[] = [
+  {
+    id: "claude-primary",
+    object: "model",
+    owned_by: "combo",
+    capabilities: { tool_calling: true, reasoning: true, vision: true, thinking: true },
+    context_length: 200000,
+    max_output_tokens: 64000,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+  {
+    id: "claude-low",
+    object: "model",
+    owned_by: "combo",
+    capabilities: { tool_calling: true, reasoning: true, vision: true, thinking: false },
+    context_length: 200000,
+    max_output_tokens: 64000,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+  {
+    id: "gemini-3-flash",
+    object: "model",
+    owned_by: "google",
+    capabilities: { tool_calling: true, reasoning: false, vision: true, thinking: false },
+    context_length: 1000000,
+    max_output_tokens: 8192,
+    input_modalities: ["text", "image"],
+    output_modalities: ["text"],
+  },
+];
+
+function stubFetcher(payload: OmniRouteRawModelEntry[]): OmniRouteModelsFetcher & {
+  callCount: () => number;
+  callsBy: () => Array<[string, string]>;
+} {
+  let calls: Array<[string, string]> = [];
+  const f: OmniRouteModelsFetcher = async (baseURL, apiKey) => {
+    calls.push([baseURL, apiKey]);
+    return payload;
+  };
+  return Object.assign(f, {
+    callCount: () => calls.length,
+    callsBy: () => calls,
+  });
+}
+
+const apiAuth = (key: string, baseURL?: string): unknown =>
+  baseURL ? { type: "api", key, baseURL } : { type: "api", key };
+
+test("createOmniRouteProviderHook: default providerId is 'omniroute'", () => {
+  const hook = createOmniRouteProviderHook(undefined, { combosFetcher: async () => [] });
+  assert.equal(hook.id, "omniroute");
+});
+
+test("createOmniRouteProviderHook: custom providerId binds to hook.id (multi-instance)", () => {
+  const a = createOmniRouteProviderHook(
+    { providerId: "omniroute-preprod" },
+    { combosFetcher: async () => [] }
+  );
+  const b = createOmniRouteProviderHook(
+    { providerId: "omniroute-local" },
+    { combosFetcher: async () => [] }
+  );
+  assert.equal(a.id, "omniroute-preprod");
+  assert.equal(b.id, "omniroute-local");
+});
+
+test("models: extracts apiKey from ctx.auth (type=api) and calls fetcher with it", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
+  assert.equal(fetcher.callCount(), 1);
+  assert.deepEqual(fetcher.callsBy()[0], ["https://or.example.com/v1", "sk-abc"]);
+  assert.equal(Object.keys(out).length, 3);
+  assert.ok(out["claude-primary"]);
+});
+
+test("models: returns {} when ctx.auth is null/undefined/wrong-type/empty-key", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  assert.deepEqual(await hook.models!({} as never, {} as never), {});
+  assert.deepEqual(await hook.models!({} as never, { auth: undefined } as never), {});
+  assert.deepEqual(
+    await hook.models!({} as never, {
+      auth: { type: "oauth", refresh: "r", access: "a", expires: 0 } as never,
+    }),
+    {}
+  );
+  assert.deepEqual(
+    await hook.models!({} as never, { auth: { type: "api", key: "" } as never }),
+    {}
+  );
+  assert.equal(fetcher.callCount(), 0, "fetcher must not be called on auth rejection");
+});
+
+test("models: returns {} when no baseURL resolvable (no opts.baseURL and no auth.baseURL)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook({}, { fetcher, combosFetcher: async () => [] });
+  // valid api auth but neither opts nor auth carries a baseURL
+  assert.deepEqual(await hook.models!({} as never, { auth: apiAuth("sk-x") as never }), {});
+  assert.equal(fetcher.callCount(), 0);
+});
+
+test("models: baseURL falls back to auth.baseURL when opts.baseURL absent", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook({}, { fetcher, combosFetcher: async () => [] });
+  const out = await hook.models!({} as never, {
+    auth: apiAuth("sk-y", "https://or.creds-attached.example/v1") as never,
+  });
+  assert.equal(fetcher.callCount(), 1);
+  assert.equal(fetcher.callsBy()[0][0], "https://or.creds-attached.example/v1");
+  assert.equal(Object.keys(out).length, 3);
+});
+
+test("models: maps a sample /v1/models entry to ModelV2 (sanity)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" },
+    { fetcher, combosFetcher: async () => [] }
+  );
+  const out = await hook.models!({} as never, { auth: apiAuth("sk-abc") as never });
+  const claude = out["claude-primary"];
+  assert.ok(claude, "claude-primary present");
+  assert.equal(claude.id, "claude-primary");
+  assert.equal(claude.name, "claude-primary");
+  assert.equal(claude.providerID, "omniroute");
+  assert.equal(claude.api.id, "openai-compatible");
+  assert.equal(claude.api.url, "https://or.example.com/v1");
+  assert.equal(claude.api.npm, "@ai-sdk/openai-compatible");
+  // capabilities: toolcall (one word), reasoning OR thinking, attachment = vision
+  assert.equal(claude.capabilities.toolcall, true);
+  assert.equal(claude.capabilities.reasoning, true);
+  assert.equal(claude.capabilities.attachment, true);
+  assert.equal(claude.capabilities.temperature, true);
+  // modalities mapped from arrays
+  assert.equal(claude.capabilities.input.text, true);
+  assert.equal(claude.capabilities.input.image, true);
+  assert.equal(claude.capabilities.input.audio, false);
+  assert.equal(claude.capabilities.output.text, true);
+  assert.equal(claude.capabilities.output.image, false);
+  // cost is zeroed (OmniRoute /v1/models has no pricing)
+  assert.deepEqual(claude.cost, { input: 0, output: 0, cache: { read: 0, write: 0 } });
+  // limits
+  assert.equal(claude.limit.context, 200000);
+  assert.equal(claude.limit.output, 64000);
+  assert.equal(claude.status, "active");
+});
+
+test("mapRawModelToModelV2: thinking-only model still surfaces reasoning=true", () => {
+  const m = mapRawModelToModelV2(
+    {
+      id: "thinking-only",
+      capabilities: { thinking: true, reasoning: false },
+      context_length: 100000,
+      max_output_tokens: 8192,
+    },
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" }
+  );
+  assert.equal(m.capabilities.reasoning, true);
+});
+
+test("mapRawModelToModelV2: missing capabilities defaults to all-false (except temperature)", () => {
+  const m = mapRawModelToModelV2(
+    { id: "minimal" },
+    { providerId: "omniroute", baseURL: "https://or.example.com/v1" }
+  );
+  assert.equal(m.capabilities.temperature, true);
+  assert.equal(m.capabilities.reasoning, false);
+  assert.equal(m.capabilities.attachment, false);
+  assert.equal(m.capabilities.toolcall, false);
+  // default modalities = text only
+  assert.equal(m.capabilities.input.text, true);
+  assert.equal(m.capabilities.output.text, true);
+  // missing context / output tokens → 0 fallback (ModelV2.limit.{context,output} required)
+  assert.equal(m.limit.context, 0);
+  assert.equal(m.limit.output, 0);
+});
+
+test("models: caches result for second call within TTL (fetcher called once)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher, now: () => nowMs, combosFetcher: async () => [] }
+  );
+
+  const a = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 30_000; // half the TTL
+  const b = await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(fetcher.callCount(), 1, "second call within TTL must hit the cache");
+  assert.equal(Object.keys(a).length, 3);
+  assert.equal(Object.keys(b).length, 3);
+});
+
+test("models: refetches after TTL expires", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  let nowMs = 1_000_000;
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 60_000 },
+    { fetcher, now: () => nowMs, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  nowMs += 60_001; // just past the TTL
+  await hook.models!({} as never, { auth: apiAuth("sk-z") as never });
+  assert.equal(fetcher.callCount(), 2, "call past TTL must refetch");
+});
+
+test("models: caches per (baseURL, apiKey) tuple (different keys → independent fetches)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { baseURL: "https://or.example.com/v1", modelCacheTtl: 300_000 },
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-A") as never });
+  await hook.models!({} as never, { auth: apiAuth("sk-B") as never });
+  await hook.models!({} as never, { auth: apiAuth("sk-A") as never }); // cached
+  await hook.models!({} as never, { auth: apiAuth("sk-B") as never }); // cached
+  assert.equal(fetcher.callCount(), 2, "one fetch per distinct apiKey, then cache hits");
+});
+
+test("models: caches per (baseURL, apiKey) tuple (different baseURL → independent fetches)", async () => {
+  const fetcher = stubFetcher(FIXTURE);
+  const hook = createOmniRouteProviderHook(
+    { modelCacheTtl: 300_000 }, // no opts.baseURL → falls back to auth.baseURL
+    { fetcher, combosFetcher: async () => [] }
+  );
+
+  await hook.models!({} as never, { auth: apiAuth("sk-same", "https://prod.example/v1") as never });
+  await hook.models!({} as never, {
+    auth: apiAuth("sk-same", "https://preprod.example/v1") as never,
+  });
+  await hook.models!({} as never, { auth: apiAuth("sk-same", "https://prod.example/v1") as never }); // cached
+  assert.equal(fetcher.callCount(), 2, "distinct baseURLs share apiKey but not cache");
+});

@omniroute/opencode-plugin/tests/scaffold.test.ts

@@ -0,0 +1,73 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import {
+  OmniRoutePlugin,
+  OMNIROUTE_PROVIDER_KEY,
+  DEFAULT_MODEL_CACHE_TTL_MS,
+  resolveOmniRoutePluginOptions,
+} from "../src/index.js";
+
+test("scaffold: exports public surface", () => {
+  assert.equal(
+    typeof OmniRoutePlugin,
+    "function",
+    "OmniRoutePlugin must be a function (Plugin factory)"
+  );
+  assert.equal(OMNIROUTE_PROVIDER_KEY, "omniroute");
+  assert.equal(DEFAULT_MODEL_CACHE_TTL_MS, 300_000);
+});
+
+test("scaffold: default export is v1 plugin shape { id, server: OmniRoutePlugin }", async () => {
+  const mod = await import("../src/index.js");
+  assert.equal(typeof mod.default, "object");
+  assert.equal(mod.default.id, "@omniroute/opencode-plugin");
+  assert.equal(mod.default.server, mod.OmniRoutePlugin);
+});
+
+test("resolveOmniRoutePluginOptions: defaults", () => {
+  const r = resolveOmniRoutePluginOptions();
+  assert.equal(r.providerId, "omniroute");
+  assert.equal(r.displayName, "OmniRoute");
+  assert.equal(r.modelCacheTtl, 300_000);
+  assert.equal(r.baseURL, undefined);
+});
+
+test("resolveOmniRoutePluginOptions: custom providerId derives displayName", () => {
+  const r = resolveOmniRoutePluginOptions({ providerId: "omniroute-preprod" });
+  assert.equal(r.providerId, "omniroute-preprod");
+  assert.equal(r.displayName, "OmniRoute (omniroute-preprod)");
+});
+
+test("resolveOmniRoutePluginOptions: explicit displayName wins", () => {
+  const r = resolveOmniRoutePluginOptions({
+    providerId: "omniroute-x",
+    displayName: "Custom Label",
+  });
+  assert.equal(r.displayName, "Custom Label");
+});
+
+test("resolveOmniRoutePluginOptions: invalid TTL falls back to default", () => {
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: 0 }).modelCacheTtl, 300_000);
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: -1 }).modelCacheTtl, 300_000);
+});
+
+test("resolveOmniRoutePluginOptions: positive TTL respected", () => {
+  assert.equal(resolveOmniRoutePluginOptions({ modelCacheTtl: 60_000 }).modelCacheTtl, 60_000);
+});
+
+test("OmniRoutePlugin: returns an empty hooks object (scaffold)", async () => {
+  const fakeCtx = {} as Parameters<typeof OmniRoutePlugin>[0];
+  const hooks = await OmniRoutePlugin(fakeCtx);
+  assert.equal(typeof hooks, "object");
+  assert.notEqual(hooks, null);
+});
+
+test("scaffold: CJS default export resolves via require() with v1 shape", () => {
+  const require_ = createRequire(import.meta.url);
+  const cjs = require_("../dist/index.cjs");
+  // after cjsInterop:true, default export is on cjs.default
+  assert.strictEqual(typeof cjs.default, "object");
+  assert.strictEqual(cjs.default.id, "@omniroute/opencode-plugin");
+  assert.strictEqual(typeof cjs.default.server, "function");
+});

@omniroute/opencode-plugin/tests/usable-combo.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Regression tests for `isUsableCombo` (release/v3.8.2 code review, finding C1).
+ *
+ * The combo member refs returned by `/api/combos` do NOT carry a separate
+ * `providerId` field — OmniRoute's `normalizeComboRecord` folds the provider
+ * id INTO the full model string (e.g. "cc/claude-opus-4-7"). The previous
+ * implementation read `step.providerId` (always `undefined`), so the
+ * `usableOnly` combo filter silently never dropped anything. These tests pin
+ * the corrected behavior: the verdict is derived from the `step.model` prefix,
+ * mirroring `isUsableRawModelId`'s subtract-filter semantics.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { isUsableCombo, type OmniRouteRawCombo } from "../src/index.js";
+
+/** Build a `usable` set bundle for the tests. */
+function buildUsable(opts: { aliases?: string[]; canonicals?: string[]; known?: string[] }): {
+  aliases: Set<string>;
+  canonicals: Set<string>;
+  knownAliases: Set<string>;
+} {
+  return {
+    aliases: new Set(opts.aliases ?? []),
+    canonicals: new Set(opts.canonicals ?? []),
+    // knownAliases is the union of every prefix the universe is aware of —
+    // usable or not. Default to including the usable aliases too.
+    knownAliases: new Set([...(opts.known ?? []), ...(opts.aliases ?? [])]),
+  };
+}
+
+function combo(models: OmniRouteRawCombo["models"]): OmniRouteRawCombo {
+  return { id: "c1", name: "Test Combo", models };
+}
+
+test("isUsableCombo: member with a usable alias prefix → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "model", model: "cc/claude-opus-4-7" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: all members known-but-NOT-usable → drop (the C1 regression)", () => {
+  // Before the fix this returned true unconditionally because step.providerId
+  // was always undefined. Now the known-but-unusable "dead" prefix is dropped.
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([
+    { kind: "model", model: "dead/legacy-model" },
+    { kind: "model", model: "dead/another" },
+  ]);
+  assert.equal(isUsableCombo(c, usable), false);
+});
+
+test("isUsableCombo: unknown prefix → keep (cannot prove unroutable)", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "model", model: "agentrouter/mystery" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: mixed non-usable + usable member → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([
+    { kind: "model", model: "dead/legacy" },
+    { kind: "model", model: "cc/claude-opus-4-7" },
+  ]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: zero members → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc"] });
+  assert.equal(isUsableCombo(combo([]), usable), true);
+  assert.equal(isUsableCombo(combo(undefined), usable), true);
+});
+
+test("isUsableCombo: only combo-ref steps (no resolvable model) → keep", () => {
+  const usable = buildUsable({ aliases: ["cc"], known: ["cc", "dead"] });
+  const c = combo([{ kind: "combo-ref", comboName: "nested" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});
+
+test("isUsableCombo: usable canonical prefix → keep", () => {
+  const usable = buildUsable({ canonicals: ["anthropic"], known: ["anthropic", "dead"] });
+  const c = combo([{ kind: "model", model: "anthropic/claude-opus-4-7" }]);
+  assert.equal(isUsableCombo(c, usable), true);
+});

@omniroute/opencode-plugin/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules", "tests"]
+}

@omniroute/opencode-plugin/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm", "cjs"],
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  splitting: false,
+  treeshake: false,
+  target: "node22",
+  outDir: "dist",
+  minify: false,
+  cjsInterop: true,
+  // Bundle runtime deps so the .tgz / npm install is self-contained.
+  // `zod` is required at runtime by the options schema and would otherwise
+  // need a peer install when the plugin is loaded directly from a file path
+  // in opencode.jsonc.
+  noExternal: ["zod"],
+});

@omniroute/opencode-provider/src/index.ts

@@ -78,6 +78,20 @@ export interface ModelCapabilities {
   tool_call?: boolean;
 }
 
+/**
+ * Default per-model context window sizes (tokens) for the curated default catalog.
+ * Matches the context lengths used by OmniRoute's provider registry.
+ */
+export const OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS: Record<string, number> = {
+  "cc/claude-opus-4-7": 200_000,
+  "cc/claude-sonnet-4-6": 200_000,
+  "cc/claude-haiku-4-5-20251001": 200_000,
+  "claude-opus-4-5-thinking": 200_000,
+  "claude-sonnet-4-5-thinking": 200_000,
+  "gemini-3.1-pro-high": 1_000_000,
+  "gemini-3-flash": 1_000_000,
+};
+
 /**
  * Default per-model capability hints for the curated default catalog.
  *
@@ -141,6 +155,19 @@ export interface OpenCodeModelEntry {
   reasoning?: boolean;
   temperature?: boolean;
   tool_call?: boolean;
+  /**
+   * Context window limit. OpenCode reads this to determine usable context
+   * length for compaction, overflow detection, and router decisions.
+   * Maps to `limit.context` in OpenCode's provider config schema.
+   */
+  limit?: {
+    /** Maximum context length in tokens (e.g. 200000 for Claude, 1000000 for Gemini). */
+    context: number;
+    /** Optional per-request max input tokens. */
+    input?: number;
+    /** Optional max output tokens. */
+    output?: number;
+  };
 }
 
 export interface OpenCodeProviderEntry {
@@ -235,6 +262,14 @@ export function createOmniRouteProvider(options: OmniRouteProviderOptions): Open
     if (typeof merged.reasoning === "boolean") entry.reasoning = merged.reasoning;
     if (typeof merged.temperature === "boolean") entry.temperature = merged.temperature;
     if (typeof merged.tool_call === "boolean") entry.tool_call = merged.tool_call;
+
+    // Include context window limit when known — OpenCode reads this to
+    // determine usable context length for compaction & overflow detection.
+    const contextLength = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    if (typeof contextLength === "number" && contextLength > 0) {
+      entry.limit = { context: contextLength };
+    }
+
     models[id] = entry;
   }
 
@@ -445,6 +480,8 @@ async function fetchJSON<T>(url: string, apiKey: string, timeoutMs: number): Pro
 export interface OmniRouteLiveModel {
   id: string;
   name: string;
+  /** Context window length in tokens (e.g. 200000 for Claude, 1000000 for Gemini). */
+  contextLength?: number;
 }
 
 /**
@@ -514,7 +551,18 @@ export async function fetchLiveModels(
             ? r.display_name.trim()
             : id;
 
-    models.push({ id, name: name || id });
+    // Extract context_length from OmniRoute's /v1/models response.
+    // OmniRoute returns context_length in snake_case for both synced
+    // models (with inputTokenLimit) and custom models; the catalog's
+    // getDefaultContextFallback also injects it from registry defaults.
+    const contextLength =
+      typeof r.context_length === "number" && r.context_length > 0
+        ? r.context_length
+        : typeof r.max_context_window_tokens === "number" && r.max_context_window_tokens > 0
+          ? r.max_context_window_tokens
+          : undefined;
+
+    models.push({ id, name: name || id, ...(contextLength ? { contextLength } : {}) });
   }
 
   return models;

@omniroute/opencode-provider/tests/index.test.ts

@@ -15,6 +15,7 @@ import {
   mergeIntoExistingConfig,
   normalizeBaseURL,
   OMNIROUTE_DEFAULT_MODEL_CAPABILITIES,
+  OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS,
   OMNIROUTE_DEFAULT_OPENCODE_MODELS,
   OMNIROUTE_MCP_DEFAULT_SCOPES,
   OMNIROUTE_PROVIDER_NPM,
@@ -394,6 +395,77 @@ test("OMNIROUTE_DEFAULT_OPENCODE_MODELS includes cc/ prefixed models", () => {
   assert.ok(defaults.length >= 7, "should have at least 7 models");
 });
 
+test("OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS covers every default model id", () => {
+  for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
+    const ctx = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    assert.ok(
+      typeof ctx === "number" && ctx > 0,
+      `default context_length for ${id} missing — should be a positive number`
+    );
+    // Sanity: context should be at least 8K, at most 2M tokens
+    assert.ok(ctx >= 8_000, `${id} context_length ${ctx} seems too low`);
+    assert.ok(ctx <= 2_000_000, `${id} context_length ${ctx} seems too high`);
+  }
+});
+
+test("createOmniRouteProvider emits limit.context on default model entries", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  const entry = provider.models["cc/claude-opus-4-7"];
+  assert.ok(entry.limit, "model entry should have a limit field");
+  assert.equal(entry.limit!.context, 200_000);
+});
+
+test("createOmniRouteProvider omits limit.context for unknown model ids", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+    models: ["completely-unknown-model"],
+  });
+  const entry = provider.models["completely-unknown-model"];
+  assert.equal(entry.limit, undefined);
+});
+
+test("createOmniRouteProvider serialises limit.context to JSON", () => {
+  const provider = createOmniRouteProvider({
+    baseURL: "http://localhost:20128",
+    apiKey: "sk_omniroute",
+  });
+  const round = JSON.parse(JSON.stringify(provider));
+  for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
+    const expectedContext = OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS[id];
+    assert.equal(
+      round.models[id].limit?.context,
+      expectedContext,
+      `${id} should serialise limit.context=${expectedContext}`
+    );
+  }
+});
+
+test("fetchLiveModels extracts context_length from snake_case field", async () => {
+  const { url, close } = await startMockServer(() => ({
+    data: [
+      { id: "cc/claude-opus-4-7", name: "Claude Opus 4.7", context_length: 200_000 },
+      { id: "gemini-3.1-pro-high", name: "Gemini 3.1 Pro", context_length: 1_000_000 },
+      { id: "no-context", name: "No Context" },
+    ],
+  }));
+  try {
+    const models = await fetchLiveModels(url, "sk_test");
+    const claude = models.find((m) => m.id === "cc/claude-opus-4-7");
+    assert.ok(claude, "claude model should be present");
+    assert.equal(claude!.contextLength, 200_000);
+    const gemini = models.find((m) => m.id === "gemini-3.1-pro-high");
+    assert.equal(gemini!.contextLength, 1_000_000);
+    const noCtx = models.find((m) => m.id === "no-context");
+    assert.equal(noCtx!.contextLength, undefined);
+  } finally {
+    close();
+  }
+});
+
 test("OMNIROUTE_DEFAULT_MODEL_CAPABILITIES covers every default model id", () => {
   for (const id of OMNIROUTE_DEFAULT_OPENCODE_MODELS) {
     const caps = OMNIROUTE_DEFAULT_MODEL_CAPABILITIES[id];

AGENTS.md

@@ -3,7 +3,7 @@
 ## Project
 
 Unified AI proxy/router — route any LLM through one endpoint. Multi-provider support
-with **160+ providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
+with **212 providers** (OpenAI, Anthropic, Gemini, DeepSeek, Groq, xAI, Mistral, Fireworks,
 Cohere, NVIDIA, Cerebras, Pollinations, Puter, Cloudflare AI, HuggingFace, DeepInfra,
 SambaNova, Meta Llama API, Moonshot AI, AI21 Labs, Databricks, Snowflake, and many more)
 with **MCP Server** (37 tools), **A2A v0.3 Protocol**, and **Electron desktop app**.
@@ -507,6 +507,24 @@ For any non-trivial change, read the matching deep-dive first:
 
 ---
 
+## Fork / Upstream Workflow
+
+This repository is a fork of `diegosouzapw/OmniRoute`. Keep fork-only operational
+changes (for example GHCR image publishing, personal deployment workflows, or local
+automation) out of upstream contribution PRs.
+
+When preparing a PR for upstream, always start the work branch from `upstream/main`,
+not from this fork's `main`:
+
+```bash
+git fetch upstream
+git switch -c <branch-name> upstream/main
+```
+
+Only cherry-pick or reapply the changes intended for the upstream PR.
+
+---
+
 ## Review Focus
 
 - **DB ops** go through `src/lib/db/` modules, never raw SQL in routes

CHANGELOG.md

@@ -4,6 +4,128 @@
 
 ---
 
+## [3.8.2] — 2026-05-22
+
+### ✨ New Features
+
+- **feat(@omniroute/opencode-plugin):** upstream-provider suffix in model display name — appends provider label to enriched names (e.g. `Claude Opus 4.7 · Claude` vs `Claude Opus 4.7 · Kiro`) so the OC TUI model picker can differentiate same-id models routed through different upstream connections. Default-on, opt-out via `features.providerTag: false`. ([#2602](https://github.com/diegosouzapw/OmniRoute/pull/2602) — thanks @mrmm)
+- **feat(@omniroute/opencode-plugin):** provider-tag becomes a prefix + traffic-light compression emoji — provider label now prepends (`Claude - Claude Opus 4.7`) for better TUI column grouping, with smart abbreviation for long labels (`GitHub Models` → `GHM`). Compression pipelines render intensity as emoji (🟢🟡🟠🔴). ([#2604](https://github.com/diegosouzapw/OmniRoute/pull/2604) — thanks @mrmm)
+- **feat(providers):** add 7 free-tier providers (Wave 1) — Arcee AI, InclusionAI, Krutrim, Liquid AI, MonsterAPI, Nomic, and Poolside now available as new API-key providers with provider icons, model specs, and full routing support. ([#2479](https://github.com/diegosouzapw/OmniRoute/pull/2479) — thanks @oyi77)
+- **feat(providers):** add Astraflow provider support with global + China endpoints — new provider with dual-region base URLs for global and mainland China access. ([#2486](https://github.com/diegosouzapw/OmniRoute/pull/2486) — thanks @ucloudnb666)
+- **feat(providers):** add `claude-web` provider — cookie-based Claude Web chat access without OAuth. ([#2476](https://github.com/diegosouzapw/OmniRoute/pull/2476) — thanks @oyi77)
+- **feat(providers):** add 14 free-tier providers (Wave 1b) — 360AI, Baichuan, Baidu, ByteDance/Doubao, IDEO, Kuaishou/Kling, Kunlun/Skywork, SenseTime/SenseNova, Stepfun, Tencent HunYuan, Zhipu GLM, Replicate, RunPod, and Modal with provider icons, model specs, and routing support. ([#2488](https://github.com/diegosouzapw/OmniRoute/pull/2488) — thanks @oyi77)
+- **feat(hermes):** add rich multi-role Hermes Agent CLI support — 7 configurable roles (default, delegation, vision, compression, web_extract, skills_hub, approval), per-role model selection with YAML config generation, dashboard card with preview, and home widget integration. ([#2526](https://github.com/diegosouzapw/OmniRoute/pull/2526) — thanks @apoapostolov)
+- **feat(cloud-agents):** cloud agents UX overhaul — tabs (tasks/agents/settings), status filters, Material icons, duration formatting, cloud agent credentials and health API endpoints, memory stats endpoint. ([#2516](https://github.com/diegosouzapw/OmniRoute/pull/2516) — thanks @oyi77)
+- **feat(authz):** manage-scope API keys may reach `/api/mcp/*` from non-loopback — Route Guard Tiers system (LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT), narrow carve-out for remote MCP access gated by `manage` scope; `/api/cli-tools/runtime/*` stays strict-loopback. Includes dashboard AuthzSection, inventory API, and comprehensive docs. ([#2473](https://github.com/diegosouzapw/OmniRoute/pull/2473) — thanks @mrmm)
+- **feat(home):** home page customization for experienced users — pin Provider Quota to home, toggle Quick Start and Provider Topology visibility via Appearance settings. ([#2531](https://github.com/diegosouzapw/OmniRoute/pull/2531) — thanks @apoapostolov)
+- **feat(home):** automatic refresh of Provider Quota — configurable interval (60s–600s) with toggle in Appearance settings; auto-refreshes pinned quota on the home page. ([#2532](https://github.com/diegosouzapw/OmniRoute/pull/2532) — thanks @apoapostolov)
+- **feat(@omniroute/opencode-plugin):** OmniRoute OpenCode plugin — live models fetched from OmniRoute API, combo-aware model listing, Gemini request sanitization, multi-instance support, auth flow integration, and 10 test files. ([#2529](https://github.com/diegosouzapw/OmniRoute/pull/2529) — thanks @mrmm)
+- **feat(executors):** forward OpenCode client headers to upstream providers — OpenCode-specific headers are now forwarded through the executor pipeline for improved compatibility. ([#2538](https://github.com/diegosouzapw/OmniRoute/pull/2538) — thanks @kang-heewon)
+- **feat(fireworks):** add new models with `modelIdPrefix` support — generic registry field that stores short model IDs and prepends the full path prefix before upstream API calls. Adds 6 new Fireworks models, `modelsUrl` for dynamic sync, and Qwen3 reranker. ([#2560](https://github.com/diegosouzapw/OmniRoute/pull/2560) — thanks @HALDRO)
+- **feat(@omniroute/opencode-plugin):** readable + filterable + offline-resilient model picker — `usableOnly` filter (only show providers with healthy connections), `diskCache` for offline hydration, `Combo:` prefix labeling, and compression metadata tags in combo display names. ([#2572](https://github.com/diegosouzapw/OmniRoute/pull/2572) — thanks @mrmm)
+- **feat(smart-pipeline):** multi-stage pipeline for auto combo routing — rule-based + intent-classifier + domain-specific stages with configurable pipeline router, accuracy benchmarks, and comprehensive tests. ([#2551](https://github.com/diegosouzapw/OmniRoute/pull/2551) — thanks @oyi77)
+- **feat(ops):** skip DB health check on startup via `OMNIROUTE_SKIP_DB_HEALTHCHECK=1` — replaces slow `integrity_check` (7+ min on large WAL) with `quick_check`, and adds env var to skip entirely. ([#2554](https://github.com/diegosouzapw/OmniRoute/pull/2554) — thanks @soyelmismo)
+- **refactor(dashboard):** Provider Quota grouped layout with vertical rail — restructures the page to a 2-column per-provider layout (left rail with icon/name/status, right content with dynamic per-provider columns), new `providerColumns.ts` / `ProviderGroup.tsx` / `AccountRow.tsx` components, env chip-filter row, bulk-refresh per group, and inline expanded panels. ([#2528](https://github.com/diegosouzapw/OmniRoute/pull/2528) — thanks @Gi99lin)
+- **feat(providers):** add 26 free-tier providers missing from registry — Novita, Avian, Chutes, Kluster, Targon, Nineteen, Celery, Ditto, Atoma, and more. ([#2590](https://github.com/diegosouzapw/OmniRoute/pull/2590) — thanks @oyi77)
+- **feat(providers):** add api-airforce free provider with 55 models. ([#2587](https://github.com/diegosouzapw/OmniRoute/pull/2587) — thanks @oyi77)
+- **feat(dashboard):** configurable sidebar — presets, drag-and-drop ordering, smart-grouping, and new Settings → Sidebar page. ([#2581](https://github.com/diegosouzapw/OmniRoute/pull/2581) — thanks @Gi99lin)
+
+### 🔧 Bug Fixes
+
+- **fix(validation):** stop appending a second `/models` when the Gemini base URL already ends in `/models` — Google AI Studio connections using the default base URL were validating against `.../v1beta/models/models` and failing with `404` for every connection. ([#2545](https://github.com/diegosouzapw/OmniRoute/issues/2545))
+- **fix(cloudflare-ai):** flatten OpenAI content-part arrays to plain strings for the Workers AI (`cf/`) executor — Workers AI's `/ai/v1/chat/completions` rejects `content: [{type:"text",...}]` with HTTP 400, so requests with array content now have their text parts joined into a string. ([#2539](https://github.com/diegosouzapw/OmniRoute/issues/2539))
+- **fix(i18n):** replace leftover Portuguese strings in the English source with English on the Quota dashboards — the quota-share Beta notice (`betaConfigSaved*`) and the Provider Quota row's `Edit cutoffs` / `Refresh now` fallbacks were showing Portuguese. ([#2540](https://github.com/diegosouzapw/OmniRoute/issues/2540))
+
+- **fix(proxy):** honor the legacy per-provider/global proxy config in `resolveProxyForProvider` — the Claude OAuth token exchange and token refresh only consulted the new proxy registry, so a proxy configured the legacy way (`/api/settings/proxy?level=provider`) was ignored and the exchange went out directly from the host, tripping Anthropic's IP `rate_limit_error` on VPS deployments. It now falls back to the legacy config, mirroring `resolveProxyForConnection`. ([#2456](https://github.com/diegosouzapw/OmniRoute/issues/2456))
+- **fix(antigravity):** auto-discover a missing Cloud Code `projectId` via `loadCodeAssist` before failing — a freshly re-added Antigravity account whose stored `projectId` was empty (OAuth-time discovery returned nothing) now recovers the project on the first request instead of returning `422 Missing Google projectId`, mirroring the `gemini-cli` bootstrap. ([#2334](https://github.com/diegosouzapw/OmniRoute/issues/2334), [#2541](https://github.com/diegosouzapw/OmniRoute/issues/2541))
+- **fix(stream):** keep the `/v1/responses` SSE connection warm for strict clients — emit an early keepalive while the upstream produces its first token and lower the heartbeat cadence to 4s, so Codex CLI's `reqwest` client (≈5s idle-read timeout) no longer drops the stream "before completion" on slow/reasoning models. `curl` was unaffected because it has no idle timeout. ([#2544](https://github.com/diegosouzapw/OmniRoute/issues/2544))
+- **fix(electron):** wait longer for the server on first launch and reload once it responds — long post-upgrade DB migrations could exceed the 30s readiness probe, leaving the desktop app stuck on the "Server starting" screen even though the backend was healthy. The probe now targets the auth-exempt health endpoint with a generous timeout and reloads the window once the server comes up. ([#2460](https://github.com/diegosouzapw/OmniRoute/issues/2460))
+
+- **fix(cli):** mark `bin/omniroute.mjs` as executable (mode 755) so the globally-installed CLI runs directly without a manual `chmod +x`. ([#2469](https://github.com/diegosouzapw/OmniRoute/issues/2469) — thanks @disonjer)
+- **fix(settings):** restore the Global System Prompt into the in-memory config on server startup and after JSON/SQLite import — it was only loaded by the PUT endpoint, so the toggle/prompt silently reverted to defaults after any restart or import. ([#2470](https://github.com/diegosouzapw/OmniRoute/issues/2470) — thanks @disonjer)
+- **fix(settings):** append the Global System Prompt **after** existing system content instead of prepending it, so provider/agent instructions (Kiro, OpenCode, Hermes, …) injected into the system message no longer override the user's global prompt via recency bias. ([#2468](https://github.com/diegosouzapw/OmniRoute/issues/2468) — thanks @disonjer)
+- **fix(kiro):** refresh imported social tokens (`authMethod === "imported"`) via the Kiro social-auth endpoint instead of AWS SSO OIDC — imported tokens carry a registered `clientId`/`clientSecret` but a social-issued refresh token the OIDC client cannot refresh, so auto-refresh was failing with "provider returned no new token". ([#2467](https://github.com/diegosouzapw/OmniRoute/issues/2467) — thanks @disonjer)
+- **fix(antigravity):** resolve the Cloud Code `projectId` from `providerSpecificData` as a fallback (and preserve it across token refresh) so the Gemini `/v1beta` streaming path stops returning a spurious `422 Missing Google projectId` for connections that store the project there. ([#2480](https://github.com/diegosouzapw/OmniRoute/issues/2480))
+- **fix(api):** `GET /v1beta/models` now lists only models whose provider has an active/validated connection, matching the OpenAI-format `/v1/models` behavior, instead of returning the entire catalog. ([#2483](https://github.com/diegosouzapw/OmniRoute/issues/2483))
+
+- **fix(cli):** persist `STORAGE_ENCRYPTION_KEY` into `DATA_DIR` (not only `~/.omniroute`) and refuse to auto-generate a fresh key when a `storage.sqlite` already exists — a new key cannot decrypt previously-encrypted credentials, so silently regenerating it locked users out of their database. The CLI now mirrors the server `bootstrapEnv` guard. (reported by Daniel Nach; original key persistence by @Chewji9875 — follow-up to [#1622](https://github.com/diegosouzapw/OmniRoute/issues/1622))
+- **fix(gemini):** preserve and re-attach the `thoughtSignature` on Gemini thinking-model tool calls — thread the signature namespace through the `FORMATS.GEMINI` and `FORMATS.GEMINI_CLI` request translators so the cached signature (keyed by connection + tool-call id) is found on the follow-up turn. Fixes `[400]: Function call is missing a thought_signature in functionCall parts` on agentic Gemini tool use. ([#2504](https://github.com/diegosouzapw/OmniRoute/issues/2504))
+- **fix(translator):** accept PDFs sent in the Responses-API `input_file` shape on the Gemini path, and the Gemini-style `document` shape on the Responses/Codex path — content parts are now normalized across `input_file` / `file` / `document` so a PDF reaches the model regardless of which field name the client used. ([#2515](https://github.com/diegosouzapw/OmniRoute/issues/2515))
+- **fix(stream):** count `thinking` arrays and `reasoning_details` as useful stream output — a reasoning-only response (e.g. Mistral/StepFun with a low `max_tokens`) was misclassified as "Stream ended before producing useful content" and turned into a spurious 502; it is now recognized as valid output. ([#2520](https://github.com/diegosouzapw/OmniRoute/issues/2520))
+- **fix(claude):** extract system/developer role messages in Claude Code semantic passthrough paths — moves `role:"system"` / `role:"developer"` messages from the `messages[]` array to the top-level `system` parameter before sending to Anthropic, which rejects them inside messages. Fixes memory injection context being silently dropped. ([#2497](https://github.com/diegosouzapw/OmniRoute/pull/2497) — thanks @unitythemaker)
+- **fix(vision-bridge):** auto-route non-standard provider models through OmniRoute self-loop — vision-bridge now detects when a model doesn't natively support vision and automatically re-routes the image through OmniRoute's own endpoint for format translation. ([#2487](https://github.com/diegosouzapw/OmniRoute/pull/2487) — thanks @herjarsa)
+- **fix(mitm):** add IPv6 DNS redirect, modular antigravity target, improved logging — MITM DNS handler now correctly redirects IPv6 (AAAA) queries alongside IPv4, adds a dedicated `antigravity.ts` target module, and enhances DNS/TLS logging for debugging. ([#2514](https://github.com/diegosouzapw/OmniRoute/pull/2514) — thanks @herjarsa)
+- **fix(usage):** improve Claude and MiniMax plan label detection — better tier name resolution for Claude OAuth usage (tier/plan/subscription_type/org fields) and new MiniMax plan label inference from quota totals. ([#2498](https://github.com/diegosouzapw/OmniRoute/pull/2498) — thanks @Gi99lin)
+- **fix(codex):** fan out image `n` requests in parallel — when Codex requests `n > 1` images, the image-generation handler now dispatches them concurrently instead of sequentially, significantly reducing total latency. ([#2499](https://github.com/diegosouzapw/OmniRoute/pull/2499) — thanks @nmime)
+- **fix(embeddings):** strip stale `Content-Encoding` headers from upstream response — prevents clients from receiving gzip-encoded responses with `identity` encoding declared, which caused silent data corruption. ([#2477](https://github.com/diegosouzapw/OmniRoute/pull/2477) — thanks @lordavadon2)
+- **fix(model):** return clear error instead of silent OpenAI default for unrecognized models — previously, an unrecognized model silently fell back to OpenAI; now returns a 404 with a descriptive message listing known providers. ([#2492](https://github.com/diegosouzapw/OmniRoute/pull/2492) — thanks @herjarsa)
+- **fix(dark-mode):** correct background token on Compression Override select — the combo compression override `<select>` was using a hard-coded white background that was invisible in dark mode. ([#2513](https://github.com/diegosouzapw/OmniRoute/pull/2513) — thanks @apoapostolov)
+- **fix(antigravity):** align subscription tier detection with Antigravity Manager — `extractCodeAssistSubscriptionTier` now parses the correct nested field from the `loadCodeAssist` response, and a new `extractCodeAssistOnboardTierId` fallback handles the onboarding flow. Subscription info is cached per access-token with 5-min TTL. ([#2496](https://github.com/diegosouzapw/OmniRoute/pull/2496) — thanks @Gi99lin)
+- **fix(opencode-zen):** add `opencode` provider alias and sync model list with live API — `opencode-zen` and `opencode-go` are now also reachable via the shorter `opencode` alias, and the default model list is kept in sync with the live `/v1/models` catalog. ([#2508](https://github.com/diegosouzapw/OmniRoute/pull/2508) — thanks @herjarsa)
+- **fix(combo):** clarify log message when combo target is skipped due to unavailable credentials — previously logged a misleading "provider not found" message; now says "skipped: credentials unavailable". ([#2494](https://github.com/diegosouzapw/OmniRoute/pull/2494) — thanks @herjarsa)
+- **fix(security):** replace `Math.random` with `crypto.randomUUID` in `generateTaskId`/`ActivityId` and fix URL hostname check in test — eliminates weak PRNG usage flagged by CodeQL. ([#2489](https://github.com/diegosouzapw/OmniRoute/pull/2489))
+- **fix(electron):** downgrade to Electron 41.x for better-sqlite3 V8 compatibility — Electron 42.x shipped a V8 version that broke `better-sqlite3` native bindings at runtime; pinning to 41.x restores stability.
+- **fix(@omniroute/opencode-provider):** include `limit.context` in model entries for OpenCode context window detection — OpenCode reads `limit.context` to determine usable context length for compaction and overflow detection.
+- **fix(providers):** make `gitlawb/gitlawb-gmi` model entry optional — prevents provider initialization failure when the model is not available in the catalog. ([#2476](https://github.com/diegosouzapw/OmniRoute/pull/2476) — thanks @oyi77)
+- **fix(translator):** inject `omniroute_web_search` in the Responses-API flat tool shape (`{ type, name }`) when the target provider speaks the Responses API — previously it was always emitted in the Chat Completions nested shape, so Codex/relay upstreams rejected the request. ([#2390](https://github.com/diegosouzapw/OmniRoute/issues/2390))
+- **fix(kiro):** serialize non-string `role:"tool"` message content before sending to CodeWhisperer — structured/array tool output was collapsing to `content:[{ text: "" }]`, which Kiro rejects with `400 Improperly formed request`. ([#2446](https://github.com/diegosouzapw/OmniRoute/issues/2446))
+- **fix(claude):** gate the heavy-agent beta headers (`context-1m`, `effort`, `advanced-tool-use`) on Opus/Sonnet only — Haiku with OAuth was receiving `context-1m` and rejecting it with 400. Also sanitizes historical `thinking` block signatures in passthrough. ([#2454](https://github.com/diegosouzapw/OmniRoute/issues/2454) — thanks @havockdev)
+- **fix(perplexity-web):** route requests through a Firefox-148 TLS-impersonating client so Perplexity's Cloudflare edge stops rejecting VPS/datacenter IPs with a 403 challenge. ([#2459](https://github.com/diegosouzapw/OmniRoute/issues/2459) — thanks @havockdev)
+- **fix(validation):** guard `apiKey`/`modelsUrl` against non-string values before calling `.startsWith()` / `.trim()` in the provider connection-test path. ([#2463](https://github.com/diegosouzapw/OmniRoute/issues/2463))
+- **fix(cost):** prevent double-billing of `cache_creation_input_tokens` — `prompt_tokens` from token extractors already includes both `cache_read` and `cache_creation`, so `nonCachedInput` now subtracts both cache types to avoid pricing cache at the full input rate. ([#2522](https://github.com/diegosouzapw/OmniRoute/pull/2522) — thanks @herjarsa)
+- **fix(handler):** always normalize system role messages in Claude passthrough paths — `normalizeClaudeUpstreamMessages()` is now called unconditionally in both `compatibleBridge` and pure passthrough, ensuring `role:"system"` messages are always extracted to the top-level `system` parameter. ([#2519](https://github.com/diegosouzapw/OmniRoute/pull/2519) — thanks @herjarsa)
+- **fix(handler):** capture Gemini `thought_signature` in non-streaming response path — the non-streaming translator now captures `thoughtSignature` from Gemini thinking model parts and persists them so follow-up turns can resolve them correctly. ([#2518](https://github.com/diegosouzapw/OmniRoute/pull/2518) — thanks @herjarsa)
+- **fix(kiro):** replace broken social OAuth with device flow — rewrites Kiro's Google/GitHub social login from the broken PKCE `kiro://` custom protocol to AWS Cognito device flow, which works correctly in web/proxy environments. ([#2524](https://github.com/diegosouzapw/OmniRoute/pull/2524) — thanks @disonjer)
+- **fix(providers):** resolve `opencode/` → `opencode-zen` slug mismatch + add 40+ new models — `opencode` is now a proper alias for `opencode-zen` in executor, model resolver, and provider registry; adds GPT 5.x, Claude 4.x, Gemini 3.x, Grok, Kimi, and other models with tests. ([#2517](https://github.com/diegosouzapw/OmniRoute/pull/2517) — thanks @herjarsa)
+- **fix(antigravity):** fail over stalled Antigravity sessions — new `ANTIGRAVITY_PRE_RESPONSE_TIMEOUT_CODE` shared constant for pre-response timeout detection, automatic failover to next account when session stalls before headers arrive. Node.js engine range relaxed to `>=20.20.2`. ([#2464](https://github.com/diegosouzapw/OmniRoute/pull/2464) — thanks @dhaern)
+- **fix(deepseek-web):** fix SSE parser, prompt format, and error handling — handles all 3 DeepSeek SSE stream formats (initial fragments, APPEND operations, bare string tokens), simplifies prompt to single-turn to prevent chat marker leakage, and checks `json.code` before token extraction. ([#2502](https://github.com/diegosouzapw/OmniRoute/pull/2502) — thanks @ovehbe)
+- **fix(codex):** accept `auth.json` without `auth_mode` field on import — Codex CLI no longer writes `auth_mode`; import now accepts both formats as long as required tokens are present. Semantic cache read now requires explicit `temperature: 0`. ([#2536](https://github.com/diegosouzapw/OmniRoute/pull/2536) — thanks @janeza2)
+- **fix(freetheai):** add `/chat/completions` to baseUrl to resolve 404 errors. ([#2557](https://github.com/diegosouzapw/OmniRoute/pull/2557) — thanks @lordavadon2)
+- **fix(qoder):** route PAT tokens to Qoder native API instead of DashScope — detects `pt-` prefixed tokens and routes to `api.qoder.com` with proper User-Agent header. ([#2559](https://github.com/diegosouzapw/OmniRoute/pull/2559) — thanks @herjarsa)
+- **fix(perf):** cache compiled RegExp in RTK compression hot path — eliminates thousands of redundant `new RegExp()` instantiations per second. ([#2553](https://github.com/diegosouzapw/OmniRoute/pull/2553) — thanks @soyelmismo)
+- **fix(reasoning-cache):** auto-start periodic cleanup on module load — the `server-init.ts` job was never imported (dead code), causing the `reasoning_cache` table to grow indefinitely. Now runs 30-min cleanup cycles automatically. ([#2552](https://github.com/diegosouzapw/OmniRoute/pull/2552) — thanks @soyelmismo)
+- **fix(claude):** omit `context-1m` beta for Sonnet — restrict to Opus-only to avoid long-context credit gate errors. Add `afk-mode-2026-01-31`, replace `redact-thinking` with `thinking-token-count-2026-05-13`. ([#2568](https://github.com/diegosouzapw/OmniRoute/pull/2568) — thanks @unitythemaker)
+- **fix(codex):** relax `auth_mode` check in frontend import preview — accept `undefined`/`null`/`"chatgpt"` instead of requiring `"chatgpt"` strictly, matching the backend fix in #2536. ([#2567](https://github.com/diegosouzapw/OmniRoute/pull/2567) — thanks @janeza2)
+- **fix(kimi):** declare vision capability for Kimi K2.6 in all 4 layers — `providerRegistry`, `modelSpecs`, `catalog.ts` keyword list, and Playground `VISION_MODELS`; previously the model silently rejected image uploads. ([#2573](https://github.com/diegosouzapw/OmniRoute/pull/2573) — thanks @herjarsa)
+- **fix(dashboard):** paginate request-log viewer beyond 300 rows — `getCallLogs` now accepts `offset` with parameterized SQL (eliminates string-interpolated `LIMIT`); `RequestLoggerV2` grows its window via "Load more" + IntersectionObserver infinite scroll, resetting on filter change. ([#2576](https://github.com/diegosouzapw/OmniRoute/pull/2576))
+- **fix(cli):** use `/api/monitoring/health` for server readiness check — `waitForServer()` was polling the auth-protected `/api/health` (401), causing `omniroute serve` to hang indefinitely. ([#2578](https://github.com/diegosouzapw/OmniRoute/pull/2578) — thanks @amogus22877769)
+- **fix(combo):** detect invalid model errors via structured error codes + regex fallback — when a combo target rejects a model (e.g. free account vs Pro), the router now recognizes `model_not_found` / `deployment_not_found` codes and 6 regex patterns, and falls through to the next target instead of stopping the loop. ([#2534](https://github.com/diegosouzapw/OmniRoute/pull/2534) — thanks @HALDRO)
+- **fix(security):** post-review hardening batch — `spawnSync` arg-array replaces `execSync` string-template (command injection), CSP `unsafe-eval` gated on `!app.isPackaged`, `requireManagementAuth` guard on budget/bulk and resilience/reset endpoints, error messages sanitized in gemini-web/claude-web/copilot-web/oauth/agents catch blocks, circuit breaker persists `lastFailureKind`, and combo resets `exhaustedProviders` per set-retry iteration. ([#2435](https://github.com/diegosouzapw/OmniRoute/pull/2435))
+- **fix(@omniroute/opencode-plugin):** honor `geminiSanitization` and `fetchInterceptor` feature flags — both were applied unconditionally; now each fetch layer is gated by its flag (default ON), and disabling both falls back to plain SDK fetch. ([#2546](https://github.com/diegosouzapw/OmniRoute/pull/2546))
+- **fix(#2575):** check DB feature flag override in `arePrivateProviderUrlsAllowed()` — supports runtime toggle without restart. ([#2595](https://github.com/diegosouzapw/OmniRoute/pull/2595) — thanks @herjarsa)
+- **fix(mimo):** add `supportsVision` flag to MiMo-V2.5, V2.5-Pro, and V2-Omni — previously image uploads were silently rejected. ([#2592](https://github.com/diegosouzapw/OmniRoute/pull/2592) — thanks @herjarsa)
+- **fix(ops):** propagate `OMNIROUTE_SKIP_DB_HEALTHCHECK` env var to periodic DB health check scheduler — companion fix to #2554. ([#2591](https://github.com/diegosouzapw/OmniRoute/pull/2591) — thanks @soyelmismo)
+- **fix(github):** remove incorrect `openai-responses` targetFormat from GitHub Copilot's Haiku/Sonnet models. ([#2583](https://github.com/diegosouzapw/OmniRoute/pull/2583) — thanks @oyi77)
+- **fix(copilot):** stabilize responses configuration — removes 865 lines of unstable config, simplifies handler. ([#2579](https://github.com/diegosouzapw/OmniRoute/pull/2579) — thanks @ivan-mezentsev)
+- **fix(#2544):** add SSE heartbeat keepalive to Responses API transform stream — prevents Codex CLI 0.130.0 from disconnecting during long thinking/reasoning phases. ([#2599](https://github.com/diegosouzapw/OmniRoute/pull/2599) — thanks @herjarsa)
+- **fix(memory):** extract system role messages in semantic passthrough path to prevent 400 on memory injection — system messages were being passed as-is to providers that reject mixed roles. ([#2474](https://github.com/diegosouzapw/OmniRoute/pull/2474) — thanks @Tentoxa)
+- **fix(@omniroute/opencode-provider):** include `limit.context` in model entries for OpenCode context window detection — previously OpenCode couldn't determine model context size. ([#2482](https://github.com/diegosouzapw/OmniRoute/pull/2482) — thanks @herjarsa)
+- **fix(mimo):** add `supportsVision` flag to Kimi K2.6 in providerRegistry + comprehensive vision tests for MiMo V2.5/V2.5-Pro/V2-Omni. ([#2600](https://github.com/diegosouzapw/OmniRoute/pull/2600) — thanks @herjarsa)
+- **fix(proxy):** prefer scoped proxies over registry global fallback — legacy provider-specific proxy was being shadowed by a registry-global fallback across both storage backends. Resolution now follows strict specificity: account → provider → combo → global. ([#2606](https://github.com/diegosouzapw/OmniRoute/pull/2606) — thanks @terence71-glitch)
+- **fix(@omniroute/opencode-plugin):** canonical-twin dedup + alias-fallback enrichment — `/v1/models` returned the same model under both alias (`cc/claude-opus-4-7`) and canonical (`claude/claude-opus-4-7`) names; now drops ~75 canonical duplicates and rescues ~88 raw-id rows with proper provider prefix via alias-index fallback. Also emits `cost`, `release_date`, `modalities` fields in static catalog and raises provider label threshold to 12 chars (preserves `AssemblyAI`, `Antigravity` verbatim). ([#2607](https://github.com/diegosouzapw/OmniRoute/pull/2607) — thanks @mrmm)
+- **fix(registry):** populate empty models arrays for HuggingFace (6 models) and HackClub (3 models) + fix Snowflake placeholder baseUrl to `{account}` template pattern. ([#2611](https://github.com/diegosouzapw/OmniRoute/pull/2611) — thanks @oyi77)
+
+### 🌐 Internationalization
+
+- **i18n(zh-CN):** translate 830 missing UI strings — replaces all `__MISSING__:` placeholders with proper Chinese translations. ([#2523](https://github.com/diegosouzapw/OmniRoute/pull/2523) — thanks @InkshadeWoods)
+- **i18n(dashboard):** add missing dashboard keys and fix EN fallbacks — hundreds of hardcoded English strings across cache, caveman, costs, skills, memory, and evals pages replaced with `t()` calls. ([#2500](https://github.com/diegosouzapw/OmniRoute/pull/2500) — thanks @Gi99lin)
+- **i18n(pt-BR):** complete and fix Brazilian Portuguese translation — comprehensive overhaul of pt-BR locale with ~3000 lines of quality translations, filling all missing keys and correcting existing entries. ([#2543](https://github.com/diegosouzapw/OmniRoute/pull/2543) — thanks @alltomatos)
+- **i18n(ru):** comprehensive Russian translation update — ~2000 lines of corrected and filled translations. ([#2550](https://github.com/diegosouzapw/OmniRoute/pull/2550) — thanks @AgentAlexAI)
+- **i18n(all):** comprehensive localization and UI refactoring — 42 locale files synchronized with missing keys, cloud-agents page i18n rewrite, and consistent `t()` usage across 21 dashboard components. ([#2580](https://github.com/diegosouzapw/OmniRoute/pull/2580) — thanks @alltomatos)
+- **i18n(all):** translate freeTier provider strings across 41 locales — replaces `__MISSING__:Free Tier Providers` placeholders with proper translations in both `common` and `providers` namespaces. ([#2609](https://github.com/diegosouzapw/OmniRoute/pull/2609) — thanks @leninejunior)
+- **i18n(pt-BR):** eliminate all 1270 remaining `__MISSING__` markers — completes pt-BR translation across 41 namespaces to true 100% coverage. ([#2610](https://github.com/diegosouzapw/OmniRoute/pull/2610) — thanks @leninejunior)
+
+### 📝 Maintenance
+
+- **chore:** remove Akamai VPS deploy from release workflow and skills.
+- **chore(deps):** bump `actions/setup-node` from v4 to v6 + `randomBytes` security fix for cloud agent task IDs. ([#2589](https://github.com/diegosouzapw/OmniRoute/pull/2589))
+- **chore(deps):** bump `actions/upload-artifact` from v4 to v7. ([#2588](https://github.com/diegosouzapw/OmniRoute/pull/2588))
+- **chore:** ignore `.claude/worktrees` from git tracking.
+- **chore(ci):** auto-lock release branch on version publish — new CI workflow applies `lock_branch` protection when a GitHub Release is published. ([#2542](https://github.com/diegosouzapw/OmniRoute/pull/2542))
+- **docs:** redesign README — marketing-first layout with accurate provider counts. ([#2490](https://github.com/diegosouzapw/OmniRoute/pull/2490))
+
+---
+
 ## [3.8.1] — 2026-05-21
 
 ### ✨ New Features
@@ -28,6 +150,8 @@
 - **fix(i18n):** harden diff key extraction tag sanitization in `extract-keys-from-diff.mjs`.
 - **chore(i18n):** refresh fr/es/de locales + add missing `settings.update` key. ([#2437](https://github.com/diegosouzapw/OmniRoute/pull/2437))
 - **fix(dashboard):** allow bracketed combo names — align dashboard combo-name validator regex with the shared/server schema updated in PR #2354; names like `Claude [1m]` are now accepted in the create/edit form. ([#2458](https://github.com/diegosouzapw/OmniRoute/pull/2458) — thanks @congvc-dev)
+- **docs(agentrouter):** recommend native provider as the simple path — guide now prefers the built-in AgentRouter provider instead of manual OpenAI-compatible configuration. ([#2429](https://github.com/diegosouzapw/OmniRoute/pull/2429) — thanks @leninejunior)
+- **feat(settings):** surface Codex Fast Tier toggle in Settings › AI — companion UI toggle for the Codex Fast Tier feature. ([#2440](https://github.com/diegosouzapw/OmniRoute/pull/2440) — thanks @NomenAK)
 
 ### 🔒 Security Fixes
 

SECURITY.md

@@ -38,15 +38,17 @@ Request → CORS → Authz pipeline (classify → policies → enforce)
 
 ### 🔐 Authentication & Authorization
 
-| Feature              | Implementation                                                                                                                            |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| **Dashboard Login**  | Password-based auth with JWT tokens (HttpOnly cookies)                                                                                    |
-| **API Key Auth**     | HMAC-signed keys with CRC validation                                                                                                      |
-| **OAuth 2.0 + PKCE** | 14 providers (Claude, Codex, GitHub, Cursor, Antigravity, Gemini, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Windsurf, GitLab Duo) |
-| **Token Refresh**    | Automatic OAuth token refresh before expiry                                                                                               |
-| **Secure Cookies**   | `AUTH_COOKIE_SECURE=true` for HTTPS environments                                                                                          |
-| **Authz Pipeline**   | Route classification (PUBLIC / CLIENT_API / MANAGEMENT) — see `docs/architecture/AUTHZ_GUIDE.md`                                          |
-| **MCP Scopes**       | ~13 granular scopes (read:health, write:combos, execute:completions, etc.) — see `docs/frameworks/MCP-SERVER.md`                          |
+| Feature               | Implementation                                                                                                                            |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **Dashboard Login**   | Password-based auth with JWT tokens (HttpOnly cookies)                                                                                    |
+| **API Key Auth**      | HMAC-signed keys with CRC validation                                                                                                      |
+| **OAuth 2.0 + PKCE**  | 14 providers (Claude, Codex, GitHub, Cursor, Antigravity, Gemini, Kimi Coding, Kilo Code, Cline, Qwen, Kiro, Qoder, Windsurf, GitLab Duo) |
+| **Token Refresh**     | Automatic OAuth token refresh before expiry                                                                                               |
+| **Secure Cookies**    | `AUTH_COOKIE_SECURE=true` for HTTPS environments                                                                                          |
+| **Authz Pipeline**    | Route classification (PUBLIC / CLIENT_API / MANAGEMENT) — see `docs/architecture/AUTHZ_GUIDE.md`                                          |
+| **Route Guard Tiers** | 3-tier model for management routes (LOCAL_ONLY / ALWAYS_PROTECTED / MANAGEMENT) — see `docs/security/ROUTE_GUARD_TIERS.md`                |
+| **Manage-Scope MCP**  | Remote `/api/mcp/*` access gated by API keys with `manage` scope; `/api/cli-tools/runtime/*` stays strict-loopback. See ROUTE_GUARD_TIERS |
+| **MCP Scopes**        | ~13 granular scopes (read:health, write:combos, execute:completions, etc.) — see `docs/frameworks/MCP-SERVER.md`                          |
 
 ### 🛡️ Encryption at Rest
 

Tuto_Qdrant.md

@@ -1,178 +0,0 @@
-# Tutorial Qdrant no OmniRoute (Guia para vídeo)
-
-> ⚠️ **Status (v3.8.0):** Integração Qdrant está **dormente** no pipeline. As funções de upsert/search/delete existem em `src/lib/memory/qdrant.ts` e a UI de configuração está pronta (`MemorySkillsTab.tsx` + endpoint `/api/settings/qdrant/embedding-models`), mas:
->
-> - `upsertSemanticMemoryPoint`, `searchSemanticMemory` e `deleteSemanticMemoryPoint` **não são chamadas** pelo pipeline de chat — busca semântica corrente usa apenas o store local em SQLite (ver `docs/frameworks/MEMORY.md`).
-> - As rotas `/api/settings/qdrant/health`, `/api/settings/qdrant/search` e `/api/settings/qdrant/cleanup` mencionadas neste tutorial **ainda não foram implementadas**.
-> - Os botões "Testar conexão" e "Teste de busca" no painel exigem que essas rotas existam; até lá, são placeholders.
->
-> Este documento descreve a UX/configuração planejada. Para o sistema de memória ativo hoje, consulte [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md). Acompanhe o status da ativação em issues marcadas com `area:qdrant`.
-
-## 1) O que é o Qdrant no OmniRoute
-
-O Qdrant é o banco vetorial usado para memória semântica.
-
-No OmniRoute, ele ajuda a:
-
-- Encontrar contexto por significado (não só palavra exata).
-- Reaproveitar memórias antigas com mais precisão.
-- Melhorar respostas com base em histórico relevante.
-- Escalar melhor quando a base de memória cresce.
-
----
-
-## 2) Quando o OmniRoute envia dados para o Qdrant
-
-Com Qdrant habilitado e modelo de embedding configurado, o sistema envia vetores quando:
-
-- Memórias são salvas (upsert de memória).
-- Fluxos de chat recuperam contexto semântico/híbrido.
-- Testes de busca no painel geram embedding e consultam a coleção.
-
-Resumo prático:
-
-- Sem Qdrant: busca mais limitada (texto/chave).
-- Com Qdrant: busca por similaridade semântica (mais inteligente).
-
----
-
-## 3) Pré-requisitos
-
-Você precisa de:
-
-- Instância Qdrant acessível (porta 6333).
-- Coleção criada (ex.: `omniroute_memory`).
-- Modelo de embedding válido (ex.: OpenRouter).
-- Credencial do provider do embedding configurada no OmniRoute.
-
-Exemplo de modelo OpenRouter:
-
-- `openrouter/nvidia/llama-nemotron-embed-v1-1b-v2:free`
-
-Importante:
-
-- O texto do modelo deve estar em formato `provider/model`.
-- Se usar modelo com dimensão diferente da coleção, a busca falha.
-
----
-
-## 4) Como configurar no painel do OmniRoute
-
-No menu:
-
-- `Admin > Settings > Qdrant (Memória vetorial)`
-
-Preencha:
-
-- `Ativar Qdrant`: ligado.
-- `Host`: IP ou URL do servidor Qdrant (sem porta no campo Host).
-- `Porta`: `6333`.
-- `Collection`: `omniroute_memory` (ou nome que você criou).
-- `Modelo de embedding`: selecione da lista ou digite manualmente.
-- `API Key`: opcional (preencha se seu Qdrant exigir).
-
-Depois:
-
-1. Clique em `Salvar`.
-2. Clique em `Testar conexão`.
-3. No `Teste de busca`, digite um texto e clique em `Buscar`.
-
----
-
-## 5) Como criar a coleção no Dashboard do Qdrant (sem comando)
-
-No Qdrant Dashboard:
-
-1. Clique em `Create collection`.
-2. Escolha `Global search`.
-3. Em tipo de busca, use `Custom`.
-4. Configure vetor:
-   - Vector name: `omniao` (padrão esperado pelo OmniRoute atualmente).
-   - Size: dimensão do seu modelo de embedding (ex.: 2048 em alguns modelos NVIDIA).
-   - Distance: `Cosine`.
-5. Salve a coleção com nome `omniroute_memory`.
-
-Se já tinha coleção com dimensão errada:
-
-- Recrie a coleção com dimensão correta.
-
----
-
-## 6) Como validar se está funcionando
-
-Checklist rápido:
-
-1. `Testar conexão` no OmniRoute retorna OK.
-2. Busca no painel retorna resultados (não “Sem resultados”).
-3. No Qdrant Dashboard, aparecem pontos na coleção (payload + vector).
-4. Resultados de chat passam a recuperar contexto mais relevante.
-
-Sinal clássico de problema:
-
-- Dados entram no Qdrant, mas busca do painel não retorna nada.
-
-Causas comuns:
-
-- Dimensão do vetor incompatível.
-- Nome do vetor diferente do esperado (`omniao`).
-- Modelo inválido/incompleto no campo de embedding.
-- Provider sem credencial ativa.
-
----
-
-## 7) O que melhorou com esta atualização
-
-Nesta melhoria do OmniRoute:
-
-- Suporte a embeddings de qualquer provider compatível (não só OpenAI fixo).
-- Endpoint para carregar modelos de embedding na tela de configurações.
-- Campo manual para modelo custom quando não aparecer na lista.
-- Ajuda visual (`?`) com passo rápido de configuração Qdrant + OpenRouter.
-
----
-
-## 8) Roteiro curto para seu vídeo
-
-Sugestão de demo (3-5 minutos):
-
-1. Mostrar problema sem Qdrant (busca simples).
-2. Abrir Settings e habilitar Qdrant.
-3. Configurar host/porta/collection/modelo.
-4. Salvar + testar conexão.
-5. Fazer `Teste de busca` no painel.
-6. Abrir Qdrant Dashboard e mostrar ponto salvo + vetor.
-7. Rodar um chat e mostrar melhoria de recuperação semântica.
-
-Mensagem final para a galera:
-
-- "Qdrant no OmniRoute transforma memória de palavra-chave em memória por significado."
-
----
-
-## 9) Referências de código (para equipe técnica)
-
-**Implementado:**
-
-- UI de configuração Qdrant: `src/app/(dashboard)/dashboard/settings/components/MemorySkillsTab.tsx`
-- Endpoint de modelos de embedding: `src/app/api/settings/qdrant/embedding-models/route.ts`
-- Funções backend (definidas mas dormentes): `src/lib/memory/qdrant.ts` exporta `upsertSemanticMemoryPoint`, `searchSemanticMemory`, `deleteSemanticMemoryPoint`
-
-**Pendente para ativar a integração:**
-
-- Rotas API: `/api/settings/qdrant/health`, `/api/settings/qdrant/search`, `/api/settings/qdrant/cleanup`
-- Wire-up no fluxo de chat: `src/lib/memory/retrieval.ts` e `open-sse/handlers/chatCore.ts` precisam chamar `searchSemanticMemory` quando Qdrant estiver habilitado nas settings
-- Wire-up no save de memória: `src/lib/memory/extraction.ts` (ou camada equivalente) precisa chamar `upsertSemanticMemoryPoint` após persistir cada memória
-
-Para o sistema de memória ativo hoje (SQLite-only), ver [`docs/frameworks/MEMORY.md`](docs/frameworks/MEMORY.md).
-
----
-
-## 10) Observação importante de segurança
-
-Nunca exponha em vídeo:
-
-- API key completa do OpenRouter.
-- Tokens reais de produção.
-- Endpoints internos sem proteção.
-
-Use chaves mascaradas e ambiente de demonstração.

_ideia/_fetch/1584.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjM3Nzc3MjYx","is_bot":false,"login":"uwuclxdy","name":"cloudy"},"body":"### Problem / Use Case\n\nI'm trying to connect [CoStrict](https://zgsm.sangfor.com) to omniroute but it uses oauth.\n\n### Proposed Solution\n\nAdd support for CoStrict provider\n\n### Alternatives Considered\n\n_No response_\n\n### Acceptance Criteria\n\n- being able to authenticate with costrict account\n- token refresh, multiple accounts (all features as the other oauth providers)\n\n### Area\n\nProvider Support\n\n### Related Provider(s)\n\n_No response_\n\n### Additional Context\n\nread https://claude.ai/share/5d01e7b2-5771-4a96-9067-9c7fe1b4ba7a\n\n### Expected Test Plan\n\n_No response_","comments":[{"id":"IC_kwDORPf6ys8AAAABAXyEqw","author":{"login":"diegosouzapw"},"authorAssociation":"OWNER","body":"Thank you for the suggestion, @uwuclxdy. CoStrict (Sangfor's coding assistant) is an interesting OAuth-based provider.\n\nWe reviewed the shared analysis and the provider appears to use a standard OAuth 2.0 flow. Adding CoStrict would follow our existing OAuth provider pattern:\n1. OAuth constants in `src/lib/oauth/constants/oauth.ts`\n2. Executor in `open-sse/executors/` (likely extending the Claude Code-compatible executor given the Anthropic-style API)\n3. Token refresh flow in `open-sse/services/tokenRefresh.ts`\n\nWe'll track this for a future provider onboarding wave. If you have access to the actual OAuth client endpoints and API documentation beyond the shared analysis, that would help accelerate the integration.\n\nKeeping open for tracking.","createdAt":"2026-04-25T15:03:30Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1584#issuecomment-4319904939","viewerDidAuthor":true}],"createdAt":"2026-04-25T11:46:48Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"number":1584,"title":"[Feature] CoStrict provider","url":"https://github.com/diegosouzapw/OmniRoute/issues/1584"}

_ideia/_fetch/1594.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjc2ODU0NjI=","is_bot":false,"login":"newbe36524","name":"Newbe36524"},"body":"### Problem / Use Case\n\nMy upstream provider is an account pool. It occasionally returns temporary error messages due to exceptions, such as 403, 401 and other similar status codes.I want to retain and return these original errors without automatically downgrading the provider.The provider is still fully valid, and the issue can be resolved simply by retrying at the downstream level.\n\n### Proposed Solution\n\nI want to exclude specific providers or their keys from the break mechanism, so that they remain permanently enabled and will never be downgraded under any circumstances.\nCurrently, I rely on an external standalone process to check every second whether these providers have been downgraded, and re-enable them automatically if so. This workaround is cumbersome and inconvenient.\n\n### Alternatives Considered\n\n_No response_\n\n### Acceptance Criteria\n\nProvider can be set as permanent alive\n\n### Area\n\nProxy / Routing\n\n### Related Provider(s)\n\nCustom provider\n\n### Additional Context\n\n_No response_\n\n### Expected Test Plan\n\n_No response_","comments":[{"id":"IC_kwDORPf6ys8AAAABAXyEwg","author":{"login":"diegosouzapw"},"authorAssociation":"OWNER","body":"Thank you for the feature request, @newbe36524. This is a valid use case — account pool providers where transient 403/401 errors are expected and should be retried by the downstream client rather than triggering the circuit breaker.\n\nOmniRoute v3.7.0 already made progress in this direction:\n- **Removed 429 from `PROVIDER_FAILURE_ERROR_CODES`** — rate limits no longer trigger the provider-wide circuit breaker\n- **Configurable failure thresholds** via `PROVIDER_PROFILES` — different provider types can have different tolerance levels\n\nWhat you're describing would be a natural extension: a per-provider or per-connection **`circuitBreakerEnabled: false`** flag that completely bypasses the circuit breaker for specific connections, letting all errors pass through as-is for the downstream client to handle.\n\nImplementation would touch:\n- `open-sse/services/accountFallback.ts` — skip `markProviderFailure()` when flag is set\n- Provider `providerSpecificData` schema — add `circuitBreakerBypass: boolean`\n- Dashboard UI — toggle in the provider connection settings\n\nKeeping open for tracking. This is a clean, scoped feature that could land in a near-term release.","createdAt":"2026-04-25T15:03:31Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[{"content":"THUMBS_UP","users":{"totalCount":1}}],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1594#issuecomment-4319904962","viewerDidAuthor":true}],"createdAt":"2026-04-25T13:58:11Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"number":1594,"title":"[Feature] permanent provider or the internal key inside the provider","url":"https://github.com/diegosouzapw/OmniRoute/issues/1594"}

_ideia/_fetch/1716.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjE0NDAzMDM=","is_bot":false,"login":"matteoantoci","name":"Matteo Antoci"},"body":"## Enhancement: Shorter timeouts for zombie stream detection\n\n### Current behavior\n\nAll timeout-sensitive phases share `FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS` (default 10 minutes). Additionally, there is **no request-level deadline** — if a request gets stuck in a pre-fetch phase (rate limiter queue, account semaphore, translation, etc.), it hangs indefinitely with no timeout to recover.\n\nObserved failure modes:\n- Upstream never returns HTTP headers → 10 min hang\n- Upstream returns HTTP 200 but never sends SSE data → 10 min hang before `ensureStreamReadiness` catches it\n- Upstream sends initial content then stalls mid-stream → 10 min hang before idle timeout\n- Request stuck in rate limiter queue or account fallback → **indefinite hang** (no timeout covers this phase)\n\n### Proposed behavior\n\nSplit timeouts into distinct phases, plus add a request-level hard deadline for pre-streaming phases:\n\n| Phase | Proposed default | Current | Env override |\n|-------|-----------------|---------|-------------|\n| **Request deadline** (pre-streaming phases) | 600s | none | `FETCH_TIMEOUT_MS` |\n| Fetch headers (time to HTTP response) | 60s | 600s | `FETCH_HEADERS_TIMEOUT_MS` |\n| First content (time to first useful SSE event) | 60s | 600s | `STREAM_FIRST_CONTENT_TIMEOUT_MS` |\n| Stream idle (mid-stream pauses) | 120s | 600s | `STREAM_IDLE_TIMEOUT_MS` |\n\n**Request deadline** covers the entire pre-streaming lifecycle (rate limiter wait, account fallback, translation, fetch setup, `ensureStreamReadiness`). Once the stream is confirmed active (useful content received), the deadline is cancelled — active streams are governed only by the idle timeout, which resets on every chunk. This means reasoning models that think for 10+ minutes are NOT cut, as long as they send tokens.\n\n### Implementation\n\n1. Add `STREAM_FIRST_CONTENT_TIMEOUT_MS` (default 60s) to `runtimeTimeouts.ts`\n2. Change `FETCH_HEADERS_TIMEOUT_MS` default from `fetchTimeoutMs` to 60s\n3. Lower `DEFAULT_STREAM_IDLE_TIMEOUT_MS` from 600s to 120s\n4. Use `STREAM_FIRST_CONTENT_TIMEOUT_MS` in `ensureStreamReadiness()` call (currently uses `STREAM_IDLE_TIMEOUT_MS`)\n5. Use `FETCH_HEADERS_TIMEOUT_MS` in `BaseExecutor.execute()` fetch-start timeout (currently uses `getTimeoutMs()`)\n6. Add `requestTimeoutMs` option to `createStreamController()` — starts a hard deadline timer when the request begins\n7. Cancel the deadline timer once `ensureStreamReadiness` passes (stream confirmed active)\n8. The deadline uses `FETCH_TIMEOUT_MS` as the default, configurable via env var\n\n### Impact\n\n- Zombie streams detected in ~60s instead of ~10min\n- Mid-stream stalls detected in ~2min instead of ~10min\n- **Pre-fetch hangs (rate limiter, account fallback) now covered** — 600s hard deadline prevents indefinite hangs\n- Combo fallback triggers much faster\n- No change to actively streaming behavior — deadline is cancelled once stream starts, and idle timer resets on every chunk\n- All timeouts are env-overridable for operators who need different values\n\n### Context\n\nObserved with mimo-v2.5-pro via opencode-go in three separate incidents:\n1. Provider returned HTTP 200 but never sent SSE data → 15+ min hang\n2. Provider sent initial SSE content then stalled completely → 13+ min hang\n3. Request stuck after account fallback (429 on first account, second account's request never reached fetch) → 24+ min hang with zero log output after fallback","comments":[],"createdAt":"2026-04-28T09:51:04Z","labels":[],"number":1716,"title":"[Feature] Separate fetch-start and first-content timeouts from stream idle timeout","url":"https://github.com/diegosouzapw/OmniRoute/issues/1716"}

_ideia/_fetch/1718.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjE0NDAzMDM=","is_bot":false,"login":"matteoantoci","name":"Matteo Antoci"},"body":"## Enhancement: Propagate upstream error details to the client\n\n### Problem\n\nWhen an upstream provider returns an error, the client receives a generic message like:\n\n```\n[400]: Error from provider: Provider returned error\n```\n\nThe actual upstream error body is captured internally but never included in the response. This makes it difficult to debug issues — the real error (e.g., `context_length_exceeded`, `invalid_tool_call`, etc.) is hidden behind the generic wrapper.\n\n### Proposed behavior\n\nAdd an optional `upstream_details` field to error response bodies alongside the existing `error.message`/`type`/`code` structure. The existing error structure stays unchanged (OpenAI-compatible).\n\nExample response:\n\n```json\n{\n  \"error\": {\n    \"message\": \"[400]: Error from provider: Provider returned error\",\n    \"type\": \"invalid_request_error\",\n    \"code\": \"bad_request\"\n  },\n  \"upstream_details\": {\n    \"error\": { \"message\": \"context_length_exceeded\", \"type\": \"invalid_request_error\" }\n  }\n}\n```\n\n### Where this helps\n\n- Clients using providers that wrap errors in generic messages (e.g., opencode-go)\n- Debugging 400s from upstream providers where the real error is in the response body\n- Understanding why a specific request failed without checking server-side logs\n\n### Implementation notes\n\nThe upstream error body is already parsed and available in the error handling path. The change involves:\n1. Adding an optional parameter to error builder functions (`buildErrorBody`, `errorResponse`, `writeStreamError`, `createErrorResult`)\n2. Passing the parsed upstream body through at the relevant error sites","comments":[],"createdAt":"2026-04-28T10:04:16Z","labels":[],"number":1718,"title":"[Feature] expose upstream error details in client-facing error responses","url":"https://github.com/diegosouzapw/OmniRoute/issues/1718"}

_ideia/_fetch/1731.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjE0NDAzMDM=","is_bot":false,"login":"matteoantoci","name":"Matteo Antoci"},"body":"## Problem\n\nWhen a combo uses the `auto` strategy, targets are reordered by score. If the top-scored targets all share the same provider (e.g., 4 opencode-go models), a single provider quota exhaustion forces the combo to burn through every same-provider target one by one — each cycling through all accounts getting 429 — before reaching a cross-provider fallback (e.g., glm).\n\nObserved behavior: opencode-go quota exhausted → combo spent ~5 minutes cycling through mimo → kimi → qwen → deepseek (all opencode-go), each spending 30-60s on account fallback loops returning 429, before finally trying glm.\n\nThe auto-selection algorithm has no awareness that all top-scored targets share the same provider, so cross-provider diversity is zero in the fallback chain.\n\n## Expected Behavior\n\nBefore: opencode-go/mimo (429) → opencode-go/kimi (429) → opencode-go/qwen (429) → opencode-go/deepseek (429) → glm/glm-5.1 (success) — **~5 minutes**\n\nAfter: opencode-go/mimo (429) → skip kimi/qwen/deepseek → glm/glm-5.1 (success) — **~10 seconds**\n\n## Root Cause\n\nTwo issues compound:\n\n1. **`isModelAvailable` pre-check doesn't catch quota exhaustion** — when all accounts return 429 \"Subscription quota exceeded\", the account-level cooldown is only 3-5s (base cooldown for OAuth/API key profiles). By the time the next combo target is evaluated, the cooldown has expired and the account appears available again.\n\n2. **429 is excluded from the provider circuit breaker** — `PROVIDER_FAILURE_ERROR_CODES = {408, 500, 502, 503, 504}` at `accountFallback.ts:59`. Even hundreds of consecutive 429s won't open the provider breaker, so there's no durable cross-request backoff for rate-limited providers.\n\n<details><summary>Log evidence (14:00-14:02 UTC, 2026-04-28)</summary>\n\n```\n14:00:30 Model opencode-go/mimo-v2.5-pro failed, trying next (429)\n14:00:31 Trying model 2/5: opencode-go/kimi-k2.6\n14:01:18 Model opencode-go/kimi-k2.6 failed, trying next (429)\n14:01:18 Trying model 3/5: opencode-go/qwen3.6-plus\n14:02:10 Model opencode-go/qwen3.6-plus succeeded (146978ms, 1 fallbacks)\n```\n\nAll accounts returned 429 \"Subscription quota exceeded\" for each model in sequence. Total cascade: ~2 minutes before a working path was found.\n\n</details>\n\n<details><summary>Additional evidence: overnight harness (2026-04-29)</summary>\n\n```\n03:40:50 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n03:40:56 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n03:51:03 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n03:51:09 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n03:51:15 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n...\n06:48:39 429 mimo-v2.5-pro \"Subscription quota exceeded\"\n```\n\nAll 429s are from the same provider. The combo never reached the cross-provider fallback (glm). Every request cycled through all 3 accounts × all opencode-go targets before giving up.\n\n</details>","comments":[],"createdAt":"2026-04-28T15:31:43Z","labels":[],"number":1731,"title":"[Feature] (combo): provider-level exhaustion tracking to skip same-provider targets","url":"https://github.com/diegosouzapw/OmniRoute/issues/1731"}

_ideia/_fetch/1735.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjQwODM4MTI=","is_bot":false,"login":"apoapostolov","name":"Apostol Apostolov"},"body":"## Problem\nCombo building needs a quota-aware ranking rule that favors models whose remaining quota can last through the rest of the current quota window.\n\n## Proposed rule: Highest Remaining Quota Rate\nFor any service with a fixed quota window:\n\n- Let `remaining_quota` be the fraction of quota still available, normalized to `0..1`.\n- Let `remaining_days` be the time left in the current quota window, expressed in days.\n- Compute `remaining_quota_rate = remaining_quota / remaining_days`.\n\nFor weekly quotas:\n\n- The expected pacing threshold is `1/7` quota per day.\n- Prefer models where `remaining_quota_rate > 1/7`.\n- If `remaining_quota_rate <= 1/7`, stop using that model in active combos until it recovers above the threshold.\n\n## Example\nIf a model has `60%` of its weekly quota left and `2d 10hr` remaining:\n\n- `remaining_days = 2.4167`\n- `remaining_quota_rate = 0.60 / 2.4167 = 0.248/day`\n- Since `0.248 > 1/7`, the model should remain eligible and be preferred over lower-rate options.\n\n## Expected behavior\n- Combos should rank models using the `remaining_quota_rate` rule whenever a quota window is known.\n- Models above the threshold should be preferred or retained.\n- Models at or below the threshold should be dropped from active use.\n- The rule should be applied consistently during combo evaluation and refresh.\n\n## Notes\n- If a quota is measured in calls instead of percentage, normalize it to a fraction of the current window before applying the rule.\n- The same rule should generalize to other quota windows by using `1 / window_length_days` as the threshold.\n","comments":[],"createdAt":"2026-04-28T17:54:35Z","labels":[],"number":1735,"title":"[Feature] Combo Builder: quota-aware Highest Remaining Quota rule","url":"https://github.com/diegosouzapw/OmniRoute/issues/1735"}

_ideia/_fetch/1736.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjQwODM4MTI=","is_bot":false,"login":"apoapostolov","name":"Apostol Apostolov"},"body":"## Problem\nThe /Home dashboard should be customizable so users can choose which widgets appear there and in what order. Right now the home page is too fixed, and some widgets are only useful for specific workflows.\n\n## Request\nAdd a /Home customization layer that lets users:\n- Show or hide individual widgets on /Home.\n- Reorder widgets, including pinning a widget to the top.\n- Reuse blocks from other pages where it makes sense, instead of forcing /Home to be a fixed layout.\n\n## Examples\n- Turn off the Onboarding widget after setup.\n- Hide Providers Status when it is not useful for the current workflow.\n- Pin the Limits and Quotas block to the top when tracking monthly usage for GLM, Codex, Claude, and Copilot.\n\n## Expected behavior\n- Widget visibility should be persisted per user.\n- Widget order should be persistent across refreshes and restarts.\n- The /Home page should still have a sensible default layout for first-time users.\n\n## Notes\n- The goal is not a fully freeform page builder. A controlled widget picker and ordering system is enough.\n- This should probably apply only to /Home at first, not every dashboard page.\n","comments":[],"createdAt":"2026-04-28T18:03:58Z","labels":[],"number":1736,"title":"[Feature] Dashboard customization for /Home","url":"https://github.com/diegosouzapw/OmniRoute/issues/1736"}

_ideia/_fetch/1737.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjQwODM4MTI=","is_bot":false,"login":"apoapostolov","name":"Apostol Apostolov"},"body":"## Problem\nThe Limits and Quotas widget should refresh automatically instead of requiring manual updates or stale page reloads. Quota data changes over time and needs to stay current enough to be useful on the dashboard.\n\n## Request\nAdd automatic refresh for the Limits and Quotas widget block with the following behavior:\n- Refresh interval defaults to 3 minutes.\n- Auto-update is off by default.\n- Users can enable it when they want the widget to stay current.\n\n## Why this matters\n- The widget is only useful when the quota numbers are fresh.\n- For tracked services like GLM, Codex, Claude, and Copilot, the displayed remaining quota can change quickly enough that stale values are misleading.\n- The /Home dashboard becomes much more useful if the widget can keep itself updated while the page stays open.\n\n## Expected behavior\n- When enabled, the widget refreshes on the configured interval without full page reloads.\n- The refresh should not be noisy or visually disruptive.\n- The interval should be configurable, but 3 minutes is a sensible default.\n- The feature should be opt-in, not forced on every user.\n\n## Notes\n- The widget should continue to work as a normal static block when auto-update is disabled.\n- If a refresh fails, the widget should degrade gracefully and keep the last known data visible.\n","comments":[],"createdAt":"2026-04-28T18:04:00Z","labels":[],"number":1737,"title":"[Feature] Auto-update Limits and Quotas widget","url":"https://github.com/diegosouzapw/OmniRoute/issues/1737"}

_ideia/_fetch/1765.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjU2NDAyNzE1","is_bot":false,"login":"bypanghu","name":"ipanghu"},"body":"### Problem / Use Case\n\nIn the team mode scenario, add key grouping and set the available grouping model.\n\n### Proposed Solution\n\nIn the team mode scenario, add key grouping and set the available grouping model.\n\n### Alternatives Considered\n\n_No response_\n\n### Acceptance Criteria\n\nIn the team mode scenario, add key grouping and set the available grouping model.\n\n### Area\n\nDocker / Deployment\n\n### Related Provider(s)\n\n_No response_\n\n### Additional Context\n\nI deployed it for use in an enterprise. The enterprise has its own token pool. I want to support grouping and select which model\n\n### Expected Test Plan\n\n_No response_","comments":[{"id":"IC_kwDORPf6ys8AAAABBByNPA","author":{"login":"jpsn123"},"authorAssociation":"NONE","body":"Internally, we use Omniroute as an AI gateway. When there are dozens of keys to manage, we really need the ability to group keys and configure which models each group can access.\n\nIf this feature were available, it would greatly reduce configuration time.","createdAt":"2026-05-02T13:53:35Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1765#issuecomment-4363947324","viewerDidAuthor":false}],"createdAt":"2026-04-29T08:16:16Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"number":1765,"title":"[Feature] In the team mode scenario, add key grouping and set the available grouping model.","url":"https://github.com/diegosouzapw/OmniRoute/issues/1765"}

_ideia/_fetch/1786.json

@@ -1 +0,0 @@
-{"author":{"id":"U_kgDODoFTeg","is_bot":false,"login":"crakindee2k-a11y","name":"Deen"},"body":"## Feature Request: CodeBuddy + YepApi Support\n\n### Description\nAdd routing support for:\n- [CodeBuddy](https://www.codebuddy.ai/home)\n- [YepApi](https://www.yepapi.com/)\n\n### Free Offers\n- **CodeBuddy:** 2-week free trial\n- **YepApi:** $5 free credits\n\nEasy testing, zero cost barrier.\n\n### Implementation\n- Add providers to routing config\n- Implement API integrations\n- Update docs with setup instructions\n\n### References\n- CodeBuddy: https://www.codebuddy.ai/home\n- Yep.com: https://www.yepapi.com/","comments":[{"id":"IC_kwDORPf6ys8AAAABBSj7Lg","author":{"login":"crakindee2k-a11y"},"authorAssociation":"NONE","body":"No commit? CodeBuddy is already being used heavily in an Indonesian ProxyRouter: https://enowxlabs.com/apps/enowx-ai\n\nPlease look into this.","createdAt":"2026-05-05T17:27:50Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1786#issuecomment-4381539118","viewerDidAuthor":false}],"createdAt":"2026-04-29T18:43:00Z","labels":[],"number":1786,"title":"[Feature] Add CodeBuddy + Yep.com support","url":"https://github.com/diegosouzapw/OmniRoute/issues/1786"}

_ideia/_fetch/1808.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjE0NDAzMDM=","is_bot":false,"login":"matteoantoci","name":"Matteo Antoci"},"body":"### Problem\n\nWhen auto-combo scores and selects candidates, it doesn't consider whether each model's context window can fit the request. A large request can be routed to a model with a small context window, which immediately fails and wastes a retry slot before falling back.\n\n### Details\n\n- The auto strategy already filters candidates by tool-calling support (when the request includes tools), falling back to the full pool if all are filtered out\n- Token estimation (`estimateTokens()` in `contextManager.ts`) and context limit lookup (`getModelContextLimit()` in `modelCapabilities.ts`) already exist but are only used during context compression after a model is chosen\n- The `estimatedInputTokens` field exists in `routerStrategy.ts` but is never populated\n- When this happens, the user sees extra latency from the failed attempt plus the fallback retry\n\n### Reproduction\n\n1. Configure a combo with models that have different context window sizes (e.g., 16K and 128K)\n2. Send a request with a large prompt that exceeds the smaller model's context window\n3. Observe: the request is routed to the small model, fails with \"input too long\", then falls back to the larger model\n4. Expected: the small model is excluded from candidates before scoring runs\n\n### Environment\n\nObserved on v3.7.5. The context window information is available but not used during auto-combo candidate selection.","comments":[],"createdAt":"2026-04-30T09:20:52Z","labels":[],"number":1808,"title":"[Feature] Auto-combo can route to models with insufficient context window","url":"https://github.com/diegosouzapw/OmniRoute/issues/1808"}

_ideia/_fetch/1812.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjE0NDAzMDM=","is_bot":false,"login":"matteoantoci","name":"Matteo Antoci"},"body":"## Problem\n\nIn `buildAutoCandidates()` (combo.ts), `costPer1MTokens` is set to only the input token price from `getPricingForModel()`. The output token price is read from pricing data but never used.\n\n## Details\n\nThis matters because many reasoning models (e.g., o3, DeepSeek R1) have cheap input tokens but expensive output tokens. Without factoring in output cost, these models appear artificially cheap in the scoring pool.\n\nFor example:\n- Model A: $3/M input, $15/M output → scored as $3\n- Model B: $5/M input, $5/M output → scored as $5\n- Router picks Model A as cheaper, but with a typical 40% output ratio, Model A actually costs $3 + $15×0.4 = $9 vs Model B's $5 + $5×0.4 = $7\n\n## Expected Behavior\n\nThe cost scoring factor should account for both input and output token pricing. A blended cost using an estimated output/input ratio would give more accurate cost comparisons between models.","comments":[],"createdAt":"2026-04-30T10:12:37Z","labels":[],"number":1812,"title":"[Feature] Auto-combo scoring ignores output token cost","url":"https://github.com/diegosouzapw/OmniRoute/issues/1812"}

_ideia/_fetch/1814.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjQwODM4MTI=","is_bot":false,"login":"apoapostolov","name":"Apostol Apostolov"},"body":"Hermes requests routed through OmniRoute to `glm/glm-5-turbo` can appear stalled for 30-85s before the first useful completion finishes.\n\nObserved on 2026-04-30:\n- `POST /v1/chat/completions`\n- provider: `glm`\n- requested model: `glm/glm-5-turbo`\n- status: `200`\n- duration: `84609 ms` on one call, with many others in the 25-45s range\n- prompt tokens: `68906`\n- completion tokens: `5449`\n- stream: `true`\n- tools: `25`\n- `finish_reason: \"tool_calls\"`\n- request body contained `messages`, `model`, `stream`, `stream_options`, `tools`, and `_omniroute`, but no `max_tokens` or `max_completion_tokens`\n\nThe gateway logs look healthy, so this does not appear to be a crash. The user-visible problem is that requests with very large prompts and no explicit output cap can look like the endpoint is hanging even though they eventually complete.\n\nPossible improvements:\n- add a configurable default output cap when the client omits one\n- surface a warning/metric when streaming requests arrive with no cap and very large prompts\n- add clearer observability around time-to-first-token vs total completion time\n\nI can share the local call-log details if useful.","comments":[],"createdAt":"2026-04-30T10:49:11Z","labels":[],"number":1814,"title":"[Feature] Streamed GLM chat/completions requests can look stalled when no output cap is forwarded","url":"https://github.com/diegosouzapw/OmniRoute/issues/1814"}

_ideia/_fetch/1833.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjgwMTY4NDE=","is_bot":false,"login":"diegosouzapw","name":"Diego Rodrigues de Sa e Souza"},"body":"## Summary\n\nImplement a dedicated REST management API with scoped API keys for programmatic OmniRoute configuration. This enables CI/CD integration, infrastructure-as-code workflows, third-party monitoring, and CLI scripting without requiring MCP or the dashboard.\n\n## Origin\n\nThis feature request originates from Discussion #1567 by @shannonlowder — a well-specified proposal for management-scoped API keys and settings endpoints.\n\n## Motivation\n\nWhile OmniRoute already provides programmatic access through the **MCP Server** (29 tools), a dedicated REST API would:\n- Enable CI/CD integration without MCP dependency\n- Support infrastructure-as-code workflows (Terraform, Pulumi)\n- Allow third-party monitoring tool integration\n- Provide CLI scripting for batch operations\n- Lower the barrier for automation (standard HTTP vs MCP protocol)\n\n## Proposed Scope\n\n### Management API Keys\n- Create management-scoped API keys (separate from request proxy keys)\n- Scoped permissions: `providers:read`, `providers:write`, `combos:read`, `combos:write`, `settings:read`, `settings:write`, etc.\n\n### REST Endpoints\n- `GET/POST/PUT/DELETE /api/v1/management/providers` — CRUD for provider connections\n- `GET/POST/PUT/DELETE /api/v1/management/combos` — CRUD for combos\n- `GET/PUT /api/v1/management/settings` — Read/update settings\n- `GET /api/v1/management/health` — Detailed health check\n- `GET /api/v1/management/metrics` — Usage metrics and analytics\n\n### Export/Import\n- `GET /api/v1/management/export` — Full config export (JSON)\n- `POST /api/v1/management/import` — Config import with merge/overwrite options\n\n## Implementation Notes\n\n- Auth: Reuse existing API key infrastructure with added management scope\n- Validation: Zod schemas for all inputs (consistent with existing patterns)\n- DB: All operations through `src/lib/db/` domain modules\n- Audit: Log all management operations to `mcp_audit` or new `management_audit` table\n\n## Labels\n`enhancement`, `api`\n\n---\n*Ref: https://github.com/diegosouzapw/OmniRoute/discussions/1567*","comments":[{"id":"IC_kwDORPf6ys8AAAABA57qAQ","author":{"login":"kilo-code-bot"},"authorAssociation":"NONE","body":"This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1568.\n\n> **API-first management for OmniRoute - management-scoped API keys & settings endpoints** (#1568)\n\nSimilarity score: 95%\n\n*This comment was generated by Kilo Auto-Triage.*","createdAt":"2026-04-30T19:55:46Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1833#issuecomment-4355713537","viewerDidAuthor":false}],"createdAt":"2026-04-30T19:55:40Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"},{"id":"LA_kwDORPf6ys8AAAACZXajUw","name":"kilo-triaged","description":"Auto-generated label by Kilo","color":"faf74f"},{"id":"LA_kwDORPf6ys8AAAACZ7FLsw","name":"kilo-duplicate","description":"Auto-generated label by Kilo","color":"faf74f"}],"number":1833,"title":"[Feature] API-first Management — REST Endpoints for Programmatic OmniRoute Configuration","url":"https://github.com/diegosouzapw/OmniRoute/issues/1833"}

_ideia/_fetch/1881.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjQwODM4MTI=","is_bot":false,"login":"apoapostolov","name":"Apostol Apostolov"},"body":"## What\n\nA CLI command to rotate API keys across all configured providers:\n\n- `omniroute keys rotate` — Rotate all expired/soon-to-expire keys\n- `omniroute keys rotate <provider>` — Rotate keys for a specific provider\n- `omniroute keys status` — Show key health (age, expiry, last used)\n\n## Why\n\n- `api/settings/oneproxy/rotate` and MCP tool `omniroute_oneproxy_rotate` exist, but only for the OneProxy feature.\n- Many providers (especially Google Cloud, Azure, AWS) use rotating/temporary credentials. There's no generic rotation mechanism.\n- The `token-health` route and `api/providers/expiration` route already track expiration — a CLI command would make this actionable.\n- Key lifecycle management is a security best practice for any proxy handling multiple API keys.\n\n## Implementation\n\n- Extend the existing `api/keys/` and `api/providers/expiration` logic.\n- For OAuth-based providers (Google), trigger the OAuth flow or prompt for a refresh token.\n- Support env var fallback: `omniroute keys rotate OpenRouter --from-env OPENROUTER_API_KEY`.","comments":[],"createdAt":"2026-05-02T14:27:26Z","labels":[],"number":1881,"title":"[Feature] Generic API key rotation CLI command","url":"https://github.com/diegosouzapw/OmniRoute/issues/1881"}

_ideia/_fetch/1909.json

@@ -1 +0,0 @@
-{"author":{"id":"U_kgDOCx6-pA","is_bot":false,"login":"aartzz","name":"ArtZabAZ"},"body":"### Problem / Use Case\n\nOmniRoute currently supports API-key-based providers like OpenRouter and Ollama, but lacks integration for [t3.chat](https://t3.chat) — a popular multi-model AI platform by Theo Browne that provides access to 50+ models (Claude, GPT-4o/5, Gemini, DeepSeek, Grok, Llama, etc.) under a single $8/month subscription. Users who rely on t3.chat for cost-effective model access have no way to route those requests through OmniRoute's unified proxy, forcing them to manage a separate client and authentication outside of their existing infrastructure.\n\n### Proposed Solution\n\nAdd [t3.chat](https://t3.chat) as a new provider in OmniRoute. Due to the platform's architecture, this would likely require cookie/session-based authentication rather than a standard API key. Key implementation points:\n- Authenticate using convex-session-id and browser cookies _(similar to how unofficial clients like [T3Router](https://github.com/vibheksoni/t3router) and [t3-python-client](https://github.com/thethereza/t3-python-client) operate)_.\n- Support chat completions for major models.\n- Support model discovery/listing.\n- Handle session refresh automatically where possible.\n\n### Alternatives Considered\n\n- Using third-party reverse-engineered clients directly — this bypasses OmniRoute's routing, load balancing, logging, and rate-limiting features.\n- Using individual official APIs for each model provider — this requires managing multiple API keys and subscriptions, which defeats the cost-efficiency of [t3.chat](https://t3.chat).\n\n### Acceptance Criteria\n\n- [t3.chat](https://t3.chat) appears as a selectable provider in the OmniRoute dashboard.\n- Chat completion requests can be proxied to [t3.chat](https://t3.chat) successfully.\n- Available models are discoverable and listed.\n- Cookie-based authentication is configurable in provider settings.\n- Existing providers and integrations remain unaffected.\n\n### Area\n\nProvider Support\n\n### Related Provider(s)\n\nt3.chat\n\n### Additional Context\n\n- Pricing: $8/month Pro subscription _(free tier with limited models also exists)_.\n- Authentication: No official public API key; uses browser cookies + `convex-session-id`.\n- Reference implementations: [T3Router (Rust)](https://github.com/vibheksoni/t3router), [t3-python-client](https://github.com/thethereza/t3-python-client).\n\n### Expected Test Plan\n\n- Unit tests for the [t3.chat](https://t3.chat) provider adapter.\n- Integration tests for chat completion routing.\n- Verify model discovery endpoint.\n- Ensure no regressions in existing provider tests.","comments":[],"createdAt":"2026-05-03T09:19:28Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"number":1909,"title":"[Feature] add t3.chat web provider","url":"https://github.com/diegosouzapw/OmniRoute/issues/1909"}

_ideia/_fetch/1980.json

@@ -1 +0,0 @@
-{"author":{"id":"MDQ6VXNlcjc0OTAyNzk=","is_bot":false,"login":"woutercoppens","name":"Wouter Coppens"},"body":"### Problem / Use Case\n\nCurrent local providers are: LM Studio, vLLM, Lemonade Server, Llamafile, Nvidia Triton, Docker Model Runner, XInterference, oobabooga, SD WebUI, ComfyUI\n\n### Proposed Solution\n\nPlease add support for Please add llama.cpp\n\n### Alternatives Considered\n\n_No response_\n\n### Acceptance Criteria\n\nLlama.cpp is added to local providers\n\n### Area\n\nProvider Support\n\n### Related Provider(s)\n\n_No response_\n\n### Additional Context\n\n_No response_\n\n### Expected Test Plan\n\n_No response_","comments":[{"id":"IC_kwDORPf6ys8AAAABBqt2iQ","author":{"login":"hartmark"},"authorAssociation":"CONTRIBUTOR","body":"llama.cpp supports OpenAI style so just add as OpenAI compatible and suffix /v1 on your url","createdAt":"2026-05-08T13:41:01Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1980#issuecomment-4406867593","viewerDidAuthor":false},{"id":"IC_kwDORPf6ys8AAAABB0uF3w","author":{"login":"soyelmismo"},"authorAssociation":"NONE","body":"> llama.cpp supports OpenAI style so just add as OpenAI compatible and suffix /v1 on your url\n\nfor some reason it doesnt work for me. it says isnt finding the models endpoint neither the chat completions endpoint... and obviously i double-triple checked the endpoints and ip and port and everything is correct. even from inside the omniroute's docker container can find the models from the llama server but only the omniroute dashboard is giving me the error","createdAt":"2026-05-11T03:30:51Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1980#issuecomment-4417357279","viewerDidAuthor":false},{"id":"IC_kwDORPf6ys8AAAABB05zyA","author":{"login":"rshinde-asapp"},"authorAssociation":"NONE","body":"do you have OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true set in your .env file? Do that and restart, you should be able to setup a openAI style provider.","createdAt":"2026-05-11T04:12:09Z","includesCreatedEdit":false,"isMinimized":false,"minimizedReason":"","reactionGroups":[],"url":"https://github.com/diegosouzapw/OmniRoute/issues/1980#issuecomment-4417549256","viewerDidAuthor":false}],"createdAt":"2026-05-05T19:39:20Z","labels":[{"id":"LA_kwDORPf6ys8AAAACYAlrLw","name":"enhancement","description":"New feature or request","color":"a2eeef"}],"number":1980,"title":"[Feature] Please add llama.cpp to Local Providers","url":"https://github.com/diegosouzapw/OmniRoute/issues/1980"}

_ideia/_triage.json

@@ -1,670 +0,0 @@
-{
-  "metadata": {
-    "run_at": "2026-05-19T12:12:41.235Z",
-    "owner": "diegosouzapw",
-    "repo": "OmniRoute",
-    "thresholds": {
-      "quarantine_days": 14,
-      "override_thumbs": 5,
-      "override_commenters": 3,
-      "stale_needs_days": 30,
-      "stale_defer_days": 90
-    }
-  },
-  "counts": {
-    "total_fetched": 54,
-    "absorb": 18,
-    "dormant": 31,
-    "already_delivered": 4,
-    "skip_assigned": 0,
-    "skip_has_pr": 1,
-    "stale_need_details": 0,
-    "stale_defer": 0,
-    "closed_externally": 0
-  },
-  "buckets": {
-    "absorb": [
-      {
-        "number": 1980,
-        "title": "[Feature] Please add llama.cpp to Local Providers",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1980",
-        "author": "woutercoppens",
-        "created_at": "2026-05-05T19:39:20Z",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 3,
-        "labels": [
-          "enhancement"
-        ],
-        "reason": "override:commenters",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1909,
-        "title": "[Feature] add t3.chat web provider",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1909",
-        "author": "aartzz",
-        "created_at": "2026-05-03T09:19:28Z",
-        "age_days": 16,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [
-          "enhancement"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1833,
-        "title": "[Feature] API-first Management — REST Endpoints for Programmatic OmniRoute Configuration",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1833",
-        "author": "diegosouzapw",
-        "created_at": "2026-04-30T19:55:40Z",
-        "age_days": 18,
-        "thumbs": 0,
-        "commenters": 1,
-        "labels": [
-          "enhancement",
-          "kilo-triaged",
-          "kilo-duplicate"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1765,
-        "title": "[Feature] In the team mode scenario, add key grouping and set the available grouping model.",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1765",
-        "author": "bypanghu",
-        "created_at": "2026-04-29T08:16:16Z",
-        "age_days": 20,
-        "thumbs": 0,
-        "commenters": 1,
-        "labels": [
-          "enhancement"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1594,
-        "title": "[Feature] permanent provider or the internal key inside the provider",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1594",
-        "author": "newbe36524",
-        "created_at": "2026-04-25T13:58:11Z",
-        "age_days": 23,
-        "thumbs": 0,
-        "commenters": 1,
-        "labels": [
-          "enhancement"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1584,
-        "title": "[Feature] CoStrict provider",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1584",
-        "author": "uwuclxdy",
-        "created_at": "2026-04-25T11:46:48Z",
-        "age_days": 24,
-        "thumbs": 0,
-        "commenters": 1,
-        "labels": [
-          "enhancement"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1881,
-        "title": "[Feature] Generic API key rotation CLI command",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1881",
-        "author": "apoapostolov",
-        "created_at": "2026-05-02T14:27:26Z",
-        "age_days": 16,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1845,
-        "title": "[Feature] First-class Hermes Agent support — auto-configured tool card with YAML provider integration",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1845",
-        "author": "apoapostolov",
-        "created_at": "2026-05-01T10:23:54Z",
-        "age_days": 18,
-        "thumbs": 1,
-        "commenters": 1,
-        "labels": [
-          "kilo-triaged",
-          "kilo-duplicate"
-        ],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1814,
-        "title": "[Feature] Streamed GLM chat/completions requests can look stalled when no output cap is forwarded",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1814",
-        "author": "apoapostolov",
-        "created_at": "2026-04-30T10:49:11Z",
-        "age_days": 19,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1812,
-        "title": "[Feature] Auto-combo scoring ignores output token cost",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1812",
-        "author": "matteoantoci",
-        "created_at": "2026-04-30T10:12:37Z",
-        "age_days": 19,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1808,
-        "title": "[Feature] Auto-combo can route to models with insufficient context window",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1808",
-        "author": "matteoantoci",
-        "created_at": "2026-04-30T09:20:52Z",
-        "age_days": 19,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1786,
-        "title": "[Feature] Add CodeBuddy + Yep.com support",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1786",
-        "author": "crakindee2k-a11y",
-        "created_at": "2026-04-29T18:43:00Z",
-        "age_days": 19,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1737,
-        "title": "[Feature] Auto-update Limits and Quotas widget",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1737",
-        "author": "apoapostolov",
-        "created_at": "2026-04-28T18:04:00Z",
-        "age_days": 20,
-        "thumbs": 1,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1736,
-        "title": "[Feature] Dashboard customization for /Home",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1736",
-        "author": "apoapostolov",
-        "created_at": "2026-04-28T18:03:58Z",
-        "age_days": 20,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1735,
-        "title": "[Feature] Combo Builder: quota-aware Highest Remaining Quota rule",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1735",
-        "author": "apoapostolov",
-        "created_at": "2026-04-28T17:54:35Z",
-        "age_days": 20,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1731,
-        "title": "[Feature] (combo): provider-level exhaustion tracking to skip same-provider targets",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1731",
-        "author": "matteoantoci",
-        "created_at": "2026-04-28T15:31:43Z",
-        "age_days": 20,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1718,
-        "title": "[Feature] expose upstream error details in client-facing error responses",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1718",
-        "author": "matteoantoci",
-        "created_at": "2026-04-28T10:04:16Z",
-        "age_days": 21,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      },
-      {
-        "number": 1716,
-        "title": "[Feature] Separate fetch-start and first-content timeouts from stream idle timeout",
-        "url": "https://github.com/diegosouzapw/OmniRoute/issues/1716",
-        "author": "matteoantoci",
-        "created_at": "2026-04-28T09:51:04Z",
-        "age_days": 21,
-        "thumbs": 0,
-        "commenters": 0,
-        "labels": [],
-        "reason": "age>=14",
-        "existing_idea_file": null,
-        "last_synced_comment_id": null
-      }
-    ],
-    "dormant": [
-      {
-        "number": 2411,
-        "title": "[Feature] OmniMemory",
-        "age_days": 0,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2356,
-        "title": "[Feature]",
-        "age_days": 1,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2353,
-        "title": "[Feature] add 'playground' function",
-        "age_days": 1,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2330,
-        "title": "Mistral Vibe Cli Support",
-        "age_days": 2,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2306,
-        "title": "[Feature] Support Zed IDE Integration When OmniRoute Runs in Docker",
-        "age_days": 2,
-        "thumbs": 0,
-        "commenters": 1,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2303,
-        "title": "[Feature] Do not compress previous messages to avoid big and frequent cache writes",
-        "age_days": 3,
-        "thumbs": 0,
-        "commenters": 1,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2302,
-        "title": "[Feature] Real-Time Usage Network Map",
-        "age_days": 3,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2275,
-        "title": "[Feature] Support free chatgpt accounts",
-        "age_days": 4,
-        "thumbs": 0,
-        "commenters": 1,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2268,
-        "title": "[Feature] Support multiple models in Factory Droid auto-configuration",
-        "age_days": 4,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2229,
-        "title": "[Feature] Identify back off time based on provider response",
-        "age_days": 5,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2206,
-        "title": "Windsurf IDE integration support",
-        "age_days": 6,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2205,
-        "title": "Add api.airforce as a built-in provider",
-        "age_days": 6,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2204,
-        "title": "Disable API Compression on a per-API-Action basis",
-        "age_days": 6,
-        "thumbs": 0,
-        "commenters": 1,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2187,
-        "title": "[Feature] Support Serverless Relay Proxies",
-        "age_days": 7,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2170,
-        "title": "Alternative to quota issue - Airbridge integration",
-        "age_days": 7,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2151,
-        "title": "[Feature] Add apply proxy fast in list provider",
-        "age_days": 8,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2147,
-        "title": "[Feature] How do I customize the ID of API Key Compatible Providers?",
-        "age_days": 8,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2110,
-        "title": "[Feature] breaker circuit",
-        "age_days": 9,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2101,
-        "title": "[Feature] per-API-key / per-request compression bypass",
-        "age_days": 9,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2062,
-        "title": "[Feature] Add support for CommandCode",
-        "age_days": 10,
-        "thumbs": 2,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2056,
-        "title": "[Feature] Add option to hide provider alias model IDs from /v1/models",
-        "age_days": 11,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2044,
-        "title": "[Feature] Support importing Providers configrations from CLIProxyAPI",
-        "age_days": 11,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2034,
-        "title": "[Feature] Respect HOST/HOSTNAME env var instead of hardcoding 0.0.0.0",
-        "age_days": 12,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1998,
-        "title": "[Feature] Unified/Consistent API Key visibility between API Manager and CLI Tools",
-        "age_days": 12,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1987,
-        "title": "[Feature] Middleware de pre-request para roteamento semantico | Programmatic Pre-request Middleware for Semantic Routing",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1981,
-        "title": "[Feature] LLM-guided configuration assistant with checkpoints and safe auto-setup",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2328,
-        "title": "[Feature] Kiro multi-account support: independent OAuth sessions per connection",
-        "age_days": 2,
-        "thumbs": 0,
-        "commenters": 1,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 2132,
-        "title": "[Feature] Add coding-score-aware routing similar to OpenRouter Pareto (minCodingScore)",
-        "age_days": 8,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1985,
-        "title": "[Feature] Unify Vertex AI and Vertex AI Partners provider routing",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1984,
-        "title": "[Feature] Google Custom Search JSON API is closed to new customers",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      },
-      {
-        "number": 1975,
-        "title": "[Feature] Dashboard: Credit Balance Widget for Providers with $/Credit Check Endpoints",
-        "age_days": 13,
-        "thumbs": 0,
-        "commenters": 0,
-        "reason": "age<14 && thumbs<5 && commenters<3"
-      }
-    ],
-    "already_delivered": [
-      {
-        "number": 2274,
-        "title": "[Feature] Support microsoft copilot",
-        "author": "warreth",
-        "confidence": "high",
-        "evidence": {
-          "pr_merged": {
-            "number": 2340,
-            "merged_at": "2026-05-17T23:02:02Z",
-            "ref": "closes #2274"
-          }
-        },
-        "version": "release/v3.8.0",
-        "version_source": "branch_unreleased"
-      },
-      {
-        "number": 2262,
-        "title": "[Feature] Make LGKP mode remember the last good account and not only the provider",
-        "author": "uwuclxdy",
-        "confidence": "high",
-        "evidence": {
-          "pr_merged": {
-            "number": 2338,
-            "merged_at": "2026-05-17T22:54:33Z",
-            "ref": "closes #2262"
-          }
-        },
-        "version": "release/v3.8.0",
-        "version_source": "branch_unreleased"
-      },
-      {
-        "number": 1826,
-        "title": "[Feature] Add https://ai.hackclub.com/ integrations",
-        "author": "oyi77",
-        "confidence": "high",
-        "evidence": {
-          "pr_merged": {
-            "number": 2339,
-            "merged_at": "2026-05-17T22:43:58Z",
-            "ref": "closes #1826"
-          }
-        },
-        "version": "release/v3.8.0",
-        "version_source": "branch_unreleased"
-      },
-      {
-        "number": 2095,
-        "title": "[Feature] Add 16 new AI providers to the provider list - Aproved",
-        "author": "oyi77",
-        "confidence": "high",
-        "evidence": {
-          "pr_merged": {
-            "number": 2096,
-            "merged_at": "2026-05-10T01:00:22Z",
-            "ref": "closes #2095"
-          }
-        },
-        "version": "release/v3.8.0",
-        "version_source": "branch_unreleased"
-      }
-    ],
-    "skip_assigned": [],
-    "skip_has_pr": [
-      {
-        "number": 2060,
-        "title": "[Feature] WordPress-style Plugin System for OmniRoute - Approved for 4.0.0-rc.1 Version",
-        "linked_prs": [
-          {
-            "number": 2386,
-            "state": "open"
-          },
-          {
-            "number": 2387,
-            "state": "open"
-          },
-          {
-            "number": 2388,
-            "state": "open"
-          },
-          {
-            "number": 2385,
-            "state": "open"
-          }
-        ]
-      }
-    ],
-    "stale_need_details": [],
-    "stale_defer": [],
-    "closed_externally": []
-  },
-  "warnings": [
-    {
-      "level": "warn",
-      "issue": 2356,
-      "message": "weak delivery signal — manual verification recommended"
-    },
-    {
-      "level": "warn",
-      "issue": 2062,
-      "message": "weak delivery signal — manual verification recommended"
-    },
-    {
-      "level": "warn",
-      "issue": 2044,
-      "message": "weak delivery signal — manual verification recommended"
-    },
-    {
-      "level": "warn",
-      "issue": 2328,
-      "message": "weak delivery signal — manual verification recommended"
-    },
-    {
-      "level": "warn",
-      "issue": 1786,
-      "message": "weak delivery signal — manual verification recommended"
-    },
-    {
-      "level": "warn",
-      "issue": 1735,
-      "message": "weak delivery signal — manual verification recommended"
-    }
-  ]
-}

_ideia/defer/1487-compaction-aware-context-continuity.md

@@ -1,119 +0,0 @@
-# Feature: Add compaction-aware context continuity and token-budgeted retrieval
-
-> GitHub Issue: #1487 — opened by @apoapostolov on 2026-04-21T16:28:28Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Summary
-
-OmniRoute already has routing, context handoff, and memory primitives, but it would benefit from first-class compaction-aware behavior inspired by token compactor projects like Token Optimizer and jCodeMunch.
-
-## Proposed features
-
-### 1. Pre-compact checkpoint and post-compact restore
-
-Before a session compacts, snapshot the essential state needed to continue work:
-
-- current task or epic
-- key decisions already made
-- active files or symbols under investigation
-- unresolved blockers
-- important tool outputs
-
-After compaction or reconnect, restore that state automatically instead of relying on the model to reconstruct it from scratch.
-
-### 2. Large tool-result archive with automatic rehydration
-
-For large tool outputs, replace the full payload in-context with a short preview plus a retrieval hint, then let the model or client fetch the archived result on demand.
-
-This avoids repeatedly paying to reread large outputs and keeps the active context smaller.
-
-### 3. Token-budgeted ranked context bundles
-
-Expose a retrieval mode that returns a ranked, token-budgeted bundle instead of dumping everything.
-
-Useful inputs for ranking:
-
-- semantic relevance
-- recency
-- blast radius
-- current task alignment
-- prior retrieval usage
-
-### 4. Compaction-aware routing
-
-Use context pressure as a routing signal.
-
-Examples:
-
-- degraded / near-compaction sessions route to stronger models
-- clean, low-risk turns route to cheaper models
-- large evidence-heavy turns use a context-optimized path
-
-### 5. Session continuity breadcrumbs
-
-After compaction, leave a compact breadcrumb that points the model back to the last active task or decision trail.
-
-## Why this matters
-
-OmniRoute already has the right building blocks:
-
-- `contextRelay`
-- `contextHandoff`
-- `contextManager`
-- `sessionManager`
-- `workflowFSM`
-- `backgroundTaskDetector`
-
-The missing piece is a compaction-aware lifecycle that preserves useful state and avoids re-reading or re-sending large context blocks.
-
-## Suggested implementation direction
-
-A practical first pass could be:
-
-1. add a compact checkpoint store for session state
-2. add archived tool-result retrieval with short in-context hints
-3. add a token-budgeted context bundle endpoint or MCP tool
-4. feed compaction pressure into routing decisions
-
-## Reference patterns
-
-- Token Optimizer: pre-compact checkpoints, tool-result archive, session continuity
-- jCodeMunch: token-budgeted ranked context bundles, fuzzy retrieval, session-aware routing
-- compaction-to-memory bridge patterns: PreCompact capture and post-compact restore
-
-## 💬 Community Discussion
-
-No community discussion yet.
-
-## 🎯 Refined Feature Description
-
-### What it solves
-
-- Large context windows are expensive and context degradation happens during long sessions.
-- When an IDE or client compacts a long chat history, vital task context is often lost, requiring the model to "re-learn" what it was doing.
-- Sending massive tool outputs repeatedly wastes tokens and reduces output quality.
-
-### How it should work (high level)
-
-1. **Compaction Checkpoints:** Add hooks to snapshot the current task state (`contextManager`, `memory` integration).
-2. **Tool Archive:** Introduce a mechanism where large tool responses are stored on the server (SQLite), and the client only receives a stub: `[Large Output Truncated: Use get_archived_result(id) to read]`.
-3. **Token-Budgeted Retrieval:** Enhance `contextHandoff` or memory retrieval to accept a `max_tokens` budget, using BM25 or embedding similarity to return only the most relevant chunks up to the limit.
-4. **Context Pressure Routing:** Add a new router variable `contextPressure` (ratio of current tokens to model max context limit). Adjust the combo/strategy engine to consider this pressure (e.g., if pressure > 0.8, favor models with 128k+ context like Claude 3.5 Sonnet over 8k models).
-
-### Affected areas
-
-- `open-sse/services/contextManager.ts`
-- `open-sse/services/combo.ts` (routing logic)
-- `src/lib/memory/` (retrieval and summarization)
-- `src/lib/db/core.ts` or new `tool_archives.ts` for tool results
-
-## 📎 Attachments & References
-
-- Token Optimizer
-- jCodeMunch
-
-## 🔗 Related Ideas
-
-- N/A

_ideia/defer/1512-log-retention-policy-dashboard.md

@@ -1,80 +0,0 @@
-# Feature: [Feature] allow setting `Log retention policy` via web dashboard
-
-> GitHub Issue: #1512 — opened by @uwuclxdy on 2026-04-22T13:40:34Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-I'm trying to configure Log retention policy via dashboard to set it to unlimited. History older than 7d in Activity tab gets deleted by default - which I would like to set to unlimited.
-
-### Proposed Solution
-
-Implement input fields to allow setting custom / unlimited duration of log retention as well as the other two settings there.
-
-### Alternatives Considered
-
-_No response_
-
-### Acceptance Criteria
-
-being able to customize Log retention policy from web dashboard and set it to unlimited.
-
-### Area
-
-Dashboard / UI, Analytics / Usage Tracking
-
-### Related Provider(s)
-
-_No response_
-
-### Additional Context
-
-_No response_
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-
-
-### Participants
-
-- @uwuclxdy — Original requester
-
-### Key Points
-
-- User wants to override the default 7-day retention policy for call logs directly via the Dashboard UI.
-- Wants option for "unlimited" retention.
-
-## 🎯 Refined Feature Description
-
-Currently, OmniRoute clears call logs older than a specific timeframe (often handled by `logRotation.ts` or similar cron tasks). Users want a setting in the dashboard under Settings -> System & Storage (or similar) to control `LOG_RETENTION_DAYS`. A value of `0` or `unlimited` could be used to disable rotation.
-
-### What it solves
-
-- Prevents automatic deletion of logs for users who want to keep complete historical records.
-- Eliminates the need to use environment variables for retention policy if it currently relies on them.
-
-### How it should work (high level)
-
-1. Add a new setting key in the SQLite `settings` table for `log_retention_days`.
-2. Update the `SystemStorageTab.tsx` in the dashboard to include a dropdown or input for "Log Retention (days)". Options could be "7 Days", "30 Days", "90 Days", "Unlimited".
-3. Update `src/lib/logRotation.ts` to read this setting instead of using a hardcoded or environment variable default. If the setting is unlimited, it should skip rotation for call logs.
-
-### Affected areas
-
-- `src/app/(dashboard)/dashboard/settings/components/SystemStorageTab.tsx`
-- `src/lib/logRotation.ts`
-- `src/lib/db/settings.ts`
-
-## 📎 Attachments & References
-
-- None.
-
-## 🔗 Related Ideas
-
-- None.

_ideia/defer/1587-caveman-compression-mode-rule-based-prompt-compression-phase-2.md

@@ -1,243 +0,0 @@
-# Feature: [Feature] Caveman Compression Mode — Rule-Based Prompt Compression (Phase 2)
-
-> GitHub Issue: #1587 — opened by @oyi77 on 2026-04-25T11:54:00Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-Phase 1 (#1586) establishes the compression pipeline framework and Lite mode (10-15% savings via structural optimizations). This issue covers **Phase 2**: the flagship "Caveman Mode" that delivers 25-40% token savings through rule-based natural language compression — without any LLM assistance and with <5ms overhead.
-
-**The core insight**: LLMs don't need grammatically complete sentences. They need *semantic content*. "Caveman mode" strips language to its essential information carriers, removing filler, hedging, politeness, and redundancy while preserving all meaning-carrying tokens.
-
-**Example:**
-
-```
-BEFORE (147 tokens):
-"Please analyze the following code snippet and provide a detailed explanation 
-of what the function does. I need to understand the control flow, error handling 
-patterns, and any potential edge cases that might cause issues. The function 
-appears to be handling user authentication and I want to make sure I understand 
-all the security implications before I modify it."
-
-AFTER — Caveman (58 tokens, ~60% reduction):
-"Analyze code snippet. Explain: control flow, error handling, edge cases. 
-Function handles user auth. Need security implications before modifying."
-```
-
-This is the feature that makes OmniRoute's compression **visibly impactful** — users will see significantly shorter prompts and lower token counts in their usage stats.
-
-## Proposed Solution
-
-### Caveman Compression Rules Engine (`open-sse/services/compression/caveman.ts`)
-
-A rule-based NLP pipeline that applies deterministic transformations to message content. No LLM calls, no external dependencies, <5ms per request.
-
-#### Rule Categories
-
-**1. Filler Removal (biggest wins)**
-- Remove polite framing: "please", "could you", "would you", "can you", "I would like", "I want you to"
-- Remove hedging: "it seems like", "it appears that", "I think that", "I believe that", "probably", "possibly", "maybe"
-- Remove verbose instructions: "provide a detailed" → "provide", "give me a comprehensive" → "give", "write an in-depth" → "write"
-
-**2. Context Condensation**
-- Collapse compound instructions: "control flow, error handling patterns, and any potential edge cases" → "control flow, error handling, edge cases"
-- Remove explanatory prefixes: "The function appears to be handling" → "Function:"
-- Convert questions to directives where appropriate: "Can you explain why..." → "Explain why..."
-
-**3. Structural Compression**
-- Replace verbose conjunctions: ", and also " → ", "
-- Shorten purpose phrases: "in order to" → "to", "for the purpose of" → "for"
-- Collapse redundant quantifiers: "each and every" → "each", "any and all" → "all"
-
-**4. Multi-Turn Dedup**
-- Replace repeated context: "As we discussed earlier" → "See above"
-- Remove re-established context that hasn't changed between turns
-
-**5. Preservation Rules (critical for quality)**
-- **Never compress**: Code blocks (````...```), URLs, file paths, variable names, error messages, numbers, technical terms
-- **Never compress**: System prompts (configurable via `preserveSystemPrompt`)
-- **Never compress**: Messages marked with special preservation flags
-- **Lighter touch on**: User messages vs assistant messages (users are more verbose, assistants are already concise)
-
-#### Implementation
-
-```typescript
-interface CavemanRule {
-  name: string;
-  pattern: RegExp;
-  replacement: string | ((match: string, groups: Record<string, string>) => string);
-  context: "all" | "user" | "system" | "assistant";
-  preservePatterns?: RegExp[]; // Skip compression if these patterns are found nearby
-}
-
-const CAVEMAN_RULES: CavemanRule[] = [
-  // Filler removal
-  { name: "polite_framing", pattern: /\b(please|kindly|could you|would you|can you|i would like|i want you to|i need you to)\b/gi, replacement: "", context: "user" },
-  { name: "hedging", pattern: /\b(it seems like|it appears that|i think that|i believe that|probably|possibly|maybe)\b/gi, replacement: "", context: "all" },
-  { name: "verbose_instructions", pattern: /\b(provide a detailed|give me a comprehensive|write an in-depth|create a thorough)\b/gi, replacement: (m) => m.split(" ")[0], context: "all" },
-  // Structural compression
-  { name: "list_conjunction", pattern: /,?\s+and\s+/g, replacement: ", ", context: "all" },
-  { name: "explanation_of_purpose", pattern: /\bin order to\b/gi, replacement: "to", context: "all" },
-  // Multi-turn dedup
-  { name: "repeated_context", pattern: /As (?:we |I )?discussed(?: earlier| previously)?/gi, replacement: "See above", context: "user" },
-];
-
-export function cavemanCompress(
-  body: ChatRequestBody, 
-  options: CavemanConfig
-): CompressionResult {
-  // 1. Extract code blocks and preserve them
-  // 2. Apply rules in priority order based on message role
-  // 3. Restore preserved code blocks
-  // 4. Clean up artifacts (double spaces, empty lines)
-  // 5. Compute stats (original vs compressed tokens)
-}
-```
-
-### Caveman Rule Set (`open-sse/services/compression/cavemanRules.ts`)
-
-Separate file for the rule definitions — makes it easy to add/remove/tune rules without touching the engine.
-
-Target: **30+ rules** covering the most common verbosity patterns in coding-related prompts.
-
-### Per-Combo Override in Dashboard
-
-Add compression mode selection to the combo builder UI:
-
-```
-Combo: "my-coding-stack"
-  1. cc/claude-opus-4-7     → Compression: off (premium, prompt caching)
-  2. glm/glm-4.7           → Compression: caveman (cost-sensitive)
-  3. if/kimi-k2-thinking    → Compression: aggressive (free tier)
-```
-
-### Configuration Schema
-
-```typescript
-interface CavemanConfig {
-  enabled: boolean;
-  // Which message roles to compress
-  compressRoles: ("user" | "assistant" | "system")[];
-  // Rules to skip (by name)
-  skipRules: string[];
-  // Minimum message length to compress (skip short messages)
-  minMessageLength: number; // default: 50 chars
-  // Preserve patterns (regex) — never compress text matching these
-  preservePatterns: string[];
-}
-```
-
-## Alternatives Considered
-
-1. **LLM-based compression** (send to cheap model to summarize) — Adds 1-5s latency, costs tokens, unreliable quality. Kept for "Ultra" mode only.
-2. **LLMLingua-style perplexity pruning** — Requires local SLM, adds GPU/CPU memory requirement. Too heavy for Phase 2. Planned for Phase 4.
-3. **Simple truncation** — Current context manager approach. Loses information. Caveman preserves semantics while reducing verbosity.
-
-## Acceptance Criteria
-
-- [ ] `open-sse/services/compression/caveman.ts` — Caveman compression engine with rule application pipeline
-- [ ] `open-sse/services/compression/cavemanRules.ts` — 30+ compression rules covering common verbosity patterns
-- [ ] Code block preservation — content inside ``` blocks is never modified
-- [ ] URL, path, and number preservation — these are never compressed
-- [ ] Role-aware compression — user messages get full treatment, system messages are lighter touch (configurable)
-- [ ] `tests/unit/compression/caveman.test.ts` — Unit tests for each rule category + integration test for full pipeline
-- [ ] Token savings verification — automated test that verifies ≥20% token reduction on a sample of verbose prompts
-- [ ] Quality verification — compressed prompts produce equivalent responses on golden set eval (≤2% quality drop)
-- [ ] Performance — caveman compression adds <5ms per request on messages up to 10K tokens
-- [ ] Integration with strategy selector — caveman mode selected when `defaultMode: "standard"` in config
-- [ ] Per-combo override — compression mode field in combo config UI
-
-## Area
-
-- [x] Proxy / Routing
-- [x] Dashboard / UI
-- [ ] Provider Support
-- [ ] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [ ] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-All providers — caveman mode is format-agnostic and works across all LLM APIs.
-
-## Additional Context
-
-### Why "Caveman Mode" Works
-
-Research shows LLMs process tokens by *semantic content*, not grammatical completeness. A prompt like "Explain function auth flow, edge cases, security implications" produces nearly identical results to "Please provide a detailed explanation of the authentication function's control flow, including any edge cases and security implications you identify." The difference is 60% fewer tokens.
-
-Microsoft's LLMLingua research (EMNLP 2023, ACL 2024) demonstrated that removing up to 60% of tokens from prompts had minimal impact on response quality. Caveman mode achieves similar savings through simpler, faster, deterministic rules rather than perplexity-based pruning.
-
-### Expected Impact by Provider
-
-| Provider Context Window | Recommended Mode | Expected Savings | Impact |
-|---|---|---|---|
-| 128K (GPT-4, Claude) | Caveman | 25-40% | Cost savings on every request |
-| 32K (smaller models) | Caveman | 25-40% | Fits more conversation in smaller window |
-| 8K (legacy models) | Aggressive | 40-60% | Critical for fitting long conversations |
-| Free tier (rate-limited) | Aggressive | 40-60% | Doubles effective quota |
-
-## Expected Test Plan
-
-- Unit tests per rule category (filler, hedging, structural, dedup)
-- Integration test: full pipeline with real prompt samples
-- Golden set eval: compare response quality with/without caveman
-- Performance benchmark: latency impact measurement
-- Regression: all existing tests pass
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:54:06Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1586.
-
-> **\[Feature\] Modular Prompt Compression Pipeline — Foundation \(Phase 1\)** (#1586)
-
-Similarity score: 93%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:08:04Z):
-**Not a duplicate of #1586.** This is Phase 2 of the same proposal, not a duplicate:
-
-- **#1586 (Phase 1)**: Pipeline framework, strategy selector, and **Lite** compression (structural only: whitespace, dedup, image placeholder). Delivers 10-15% savings.
-- **This issue (Phase 2)**: **Caveman** compression mode — rule-based NLP compression (filler removal, hedging stripping, instruction condensation). Delivers 25-40% savings. Requires Phase 1's pipeline but is a completely different compression engine.
-
-Each phase is a separate module (`lite.ts` vs `caveman.ts`) with distinct implementation, tests, and acceptance criteria. They're designed to be implemented incrementally.
----
-
-
-### Participants
-
-- @oyi77
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1588-aggressive-compression-history-summarization-tool-compression-phase-3.md

@@ -1,236 +0,0 @@
-# Feature: [Feature] Aggressive Compression — History Summarization & Tool Compression (Phase 3)
-
-> GitHub Issue: #1588 — opened by @oyi77 on 2026-04-25T11:56:47Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-Phases 1 (#1586) and 2 (#1587) handle structural and linguistic compression for 10-40% savings. But the biggest token consumers in real-world OmniRoute usage are **long conversations** and **tool-heavy coding sessions**, where:
-
-1. **Tool results dominate the token budget** — A single tool call (file read, grep, shell command) can return 5-50K tokens. After 5-10 tool calls in a coding session, tool results can be 80%+ of the total prompt.
-2. **Conversation history grows unbounded** — The existing context manager only starts dropping messages when the window is exceeded. There's no progressive compression that keeps recent context rich while condensing older context.
-3. **Thinking blocks accumulate** — Models like DeepSeek R1 and Claude emit `<thinking>`/`<antThinking>` blocks that are useful for the current response but consume massive tokens in history.
-
-**Example scenario**: A user coding with Claude Code through OmniRoute sends a 30-message conversation with 15 tool calls. Total tokens: ~80K. After aggressive compression: ~32K (60% savings). The model still has full context for the last 5 exchanges and summarized context for earlier exchanges.
-
-## Proposed Solution
-
-Aggressive mode **combines all Caveman techniques with intelligent history management** — summarizing old turns, compressing tool results, and removing thinking blocks from history.
-
-### Module 1: History Summarization (`open-sse/services/compression/summarizer.ts`)
-
-Convert messages older than N turns into a compact summary system message:
-
-```
-BEFORE (messages 1-10, ~15K tokens):
-  [user] "Can you help me debug this function?"
-  [assistant] "Sure, let me look at the code..."
-  [user] "Here's the error: TypeError at line 42..."
-  [assistant] "I see the issue. It's a type mismatch..."
-  [tool_result] "function authenticate(user) { ... }" (3K tokens)
-  ... (6 more messages)
-
-AFTER (~1.5K tokens):
-  [system] "[Session summary: Debugged authenticate() function — TypeError at line 42 caused by type mismatch on user parameter. Fixed by adding type check. Discussed error handling approach and decided on early-return pattern.]"
-```
-
-**Implementation options:**
-1. **Rule-based summarization** (Phase 3A): Extract key phrases from user questions + assistant conclusions. No LLM needed. Fast but coarse.
-2. **LLM-assisted summarization** (Phase 3B): Send old messages to a cheap model (e.g., LongCat Flash Lite at $0, or DeepSeek V3 at $0.27/1M) to produce a summary. Higher quality but adds ~500ms latency and a small cost.
-
-Both should be supported, selectable via config.
-
-### Module 2: Tool Result Compression (`open-sse/services/compression/toolCompress.ts`)
-
-Smart compression of tool outputs that preserves actionable information:
-
-| Strategy | What It Does | Savings | Example |
-|---|---|---|---|
-| **File content compression** | Keep first/last N lines + line count | 70-90% | 500-line file → first 10 + last 10 + "[470 lines omitted]" |
-| **Grep/search result compression** | Keep match + surrounding context | 50-70% | 50 matches with 3-line context → match lines only |
-| **Shell output compression** | Keep exit code + key lines | 60-80% | 100-line build output → exit code + error lines |
-| **JSON response compression** | Keep structure, remove whitespace/redundancy | 20-40% | Prettified JSON → compact JSON |
-| **Error message compression** | Keep error type + first occurrence | 50-70% | Repeated stack traces → first + count |
-
-**Key design**: Tool compression should understand the *semantic structure* of common tool output formats (file diffs, grep results, stack traces, API responses) rather than blindly truncating at character limits (current context manager approach).
-
-### Module 3: Progressive Compression (`open-sse/services/compression/progressive.ts`)
-
-Apply increasing compression to older messages while keeping recent context intact:
-
-```
-Messages 1-5 (oldest):  Full summarization — collapse to 1 system message
-Messages 6-10:          Moderate — strip details, keep key facts + conclusions  
-Messages 11-15:         Light — apply Caveman rules only
-Messages 16-20 (newest): Verbatim — no modification
-```
-
-This creates a "fading context" effect where the model has full detail for recent exchanges and progressively less detail for older ones, matching how humans actually recall conversation history.
-
-### Module 4: Aggressive Mode Orchestration (`open-sse/services/compression/aggressive.ts`)
-
-Combines all techniques in order:
-
-1. Apply Caveman compression to all messages
-2. Remove thinking blocks from non-last assistant messages (existing logic from contextManager — refactor it out)
-3. Compress tool results using toolCompress
-4. Apply progressive compression (older = more aggressive)
-5. If still over threshold, summarize oldest messages
-
-### Configuration
-
-```typescript
-interface AggressiveCompressionConfig {
-  enabled: boolean;
-  // After how many turns to start compressing history
-  summarizeAfterTurns: number; // default: 4
-  // Summarization method: "rule-based" | "llm-assisted"
-  summarizationMethod: string; // default: "rule-based"
-  // Model to use for LLM-assisted summarization
-  summarizationModel: string; // default: "deepseek/deepseek-chat"
-  // Max tool result length in characters
-  maxToolResultChars: number; // default: 500
-  // Progressive compression thresholds
-  progressiveThresholds: {
-    fullSummaryTurns: number; // default: 5 (all older → summary)
-    moderateTurns: number;   // default: 3 (strip details)
-    lightTurns: number;      // default: 2 (caveman only)
-    verbatimTurns: number;   // default: 2 (no change)
-  };
-}
-```
-
-## Alternatives Considered
-
-1. **Blind truncation** (current context manager approach) — Loses critical information. A 2000-char limit on tool results can cut error messages in half.
-2. **Full summarization** (all old messages → one summary) — Loses granularity. Progressive compression preserves more nuance for recent history.
-3. **No tool compression** — Tool outputs are typically the largest token consumers. Ignoring them leaves 50%+ of potential savings on the table.
-
-## Acceptance Criteria
-
-- [ ] `open-sse/services/compression/summarizer.ts` — Rule-based history summarization
-- [ ] `open-sse/services/compression/toolCompress.ts` — 5 tool compression strategies implemented
-- [ ] `open-sse/services/compression/progressive.ts` — Progressive aging with configurable thresholds
-- [ ] `open-sse/services/compression/aggressive.ts` — Aggressive mode orchestration combining all techniques
-- [ ] Tool results compressed to ≤`maxToolResultChars` without losing error/signal information
-- [ ] Progressive compression produces fading-context message arrays
-- [ ] `tests/unit/compression/summarizer.test.ts` — Summarization quality tests
-- [ ] `tests/unit/compression/toolCompress.test.ts` — Tool compression strategy tests
-- [ ] `tests/unit/compression/progressive.test.ts` — Progressive compression tests
-- [ ] Integration test: 30-message conversation compressed through aggressive pipeline
-- [ ] Token savings ≥40% on tool-heavy conversations with ≤5% quality degradation
-- [ ] Aggressive mode adds <50ms latency per request
-
-## Area
-
-- [x] Proxy / Routing
-- [ ] Dashboard / UI
-- [ ] Provider Support
-- [ ] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [x] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-All providers — especially valuable for:
-- **Free tier providers** (Qoder, Qwen, Gemini CLI) — maximize limited quota
-- **Small context window models** — fit more conversation
-- **Tool-calling models** (Claude Code, Codex) — compress tool results
-
-## Additional Context
-
-### Real-World Token Distribution
-
-Based on typical OmniRoute traffic patterns:
-
-| Content Type | % of Total Tokens | Compression Potential |
-|---|---|---|
-| Tool results | 40-60% | 50-80% savings |
-| User messages | 15-25% | 25-40% (Caveman) |
-| Assistant responses | 10-20% | 20-40% (remove thinking) |
-| System prompts | 5-10% | 0-10% (preserve) |
-
-Tool results are the **dominant compression target**. Aggressive mode that effectively compresses tool outputs will deliver the highest absolute savings.
-
-### LLM-Assisted Summarization Cost
-
-Using DeepSeek V3 ($0.27/1M input) to summarize 15K tokens of history:
-- Input cost: ~$0.004
-- Output cost (1.5K tokens): ~$0.002
-- Total: ~$0.006 per summarization call
-- This saves ~13K tokens on the main request (~$0.026 for Claude at $2/1M)
-- **Net savings**: ~$0.020 per request — clear ROI
-
-Using a free model (LongCat Flash Lite, Qwen3 Coder) brings summarization cost to $0.
-
-## Expected Test Plan
-
-- Unit tests for `summarizer.ts` — test with conversations of varying lengths
-- Unit tests for `toolCompress.ts` — each strategy with real tool output samples (file contents, grep results, stack traces)
-- Unit tests for `progressive.ts` — verify compression gradient across message positions
-- Integration test: full aggressive pipeline on 30+ message conversation
-- Performance test: latency measurement on 80K token conversations
-- Golden set eval with aggressive compression enabled — ≤5% quality degradation
-- All existing tests pass with aggressive mode enabled
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:56:53Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1587.
-
-> **\[Feature\] Caveman Compression Mode — Rule-Based Prompt Compression \(Phase 2\)** (#1587)
-
-Similarity score: 93%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:08:19Z):
-**Not a duplicate of #1586.** This is Phase 3, building on Phases 1-2:
-
-- **#1586 (Phase 1)**: Pipeline framework + Lite compression (10-15% savings, structural only)
-- **#1587 (Phase 2)**: Caveman compression (25-40% savings, rule-based NLP)
-- **This issue (Phase 3)**: Aggressive compression (40-60% savings) — adds history summarization, tool result compression, and progressive aging. Completely different compression techniques from Phases 1-2.
-
-Each phase adds a new module (`summarizer.ts`, `toolCompress.ts`, `progressive.ts`) that didn't exist in earlier phases.
----
-**@dhaern** (2026-04-26T06:06:06Z):
-Do you make this optional no? Because many of us already use a compressor like Opencode plugins or whatever, how can be this compatible for example with https://github.com/cortexkit/opencode-magic-context??
----
-
-
-### Participants
-
-- @oyi77
-- @dhaern
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1589-ultra-compression-llmlingua-style-token-pruning-phase-4.md

@@ -1,233 +0,0 @@
-# Feature: [Feature] Ultra Compression — LLMLingua-Style Token Pruning (Phase 4)
-
-> GitHub Issue: #1589 — opened by @oyi77 on 2026-04-25T11:57:32Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-Phases 1-3 (#1586, #1587, #1588) deliver 10-60% token savings through structural, linguistic, and history-based compression. This issue covers **Phase 4**: the optionally-enabled "Ultra" mode that can achieve 60-80% savings using perplexity-based token pruning, inspired by Microsoft's LLMLingua research.
-
-**Use cases for Ultra mode:**
-- **Extreme quota constraints**: Users on free tiers who need to squeeze every possible token from their allowance
-- **Small context window models**: Fitting complex conversations into 8K-32K context windows
-- **Batch processing**: Non-interactive workloads where latency is acceptable but token cost must be minimized
-- **Emergency compression**: When aggressive mode isn't enough to fit a critically long conversation
-
-**Why optional**: Ultra mode adds 100-500ms latency and requires either a local SLM (500MB-2GB memory) or an API call to a compression model. This is only justified when the token savings outweigh the latency and compute cost.
-
-## Proposed Solution
-
-### Two Implementation Tiers
-
-**Tier A: Character-Level Information Density Scoring (no SLM required)**
-
-A lightweight approximation of perplexity-based pruning that doesn't require loading a model:
-
-| Heuristic | What It Measures | Example |
-|---|---|---|
-| **Token frequency** | Common words ("the", "a", "is") = low information → removable | "the" → remove |
-| **Character entropy** | Low per-character entropy = redundant | "aaaaaaaa" = low entropy |
-| **Capitalization patterns** | ALL CAPS = emphasis/high info, mixed = potentially removable | "ERROR" = keep, "maybe" = candidate |
-| **Punctuation density** | High punctuation = structured/technical = keep | Code blocks, JSON |
-| **Numeric content** | Numbers, versions, IDs = high information = keep | "v3.2.1" = keep |
-| **Length penalty** | Very long words = likely technical terms = keep | "authentication" = keep |
-
-This approach can achieve ~40-60% compression with <10ms overhead. It's an approximation of true perplexity scoring but sufficient for most use cases.
-
-**Tier B: Local SLM Perplexity Scoring (true LLMLingua)**
-
-Load a small language model (Qwen3-0.6B, Phi-2, or similar) to calculate actual perplexity for each token, then remove low-perplexity tokens:
-
-1. **Tokenize** the prompt using the SLM's tokenizer
-2. **Calculate perplexity** for each token given its context
-3. **Rank tokens** by perplexity (high perplexity = surprising = important)
-4. **Remove lowest-ranked tokens** until budget is met
-5. **Force-preserve** critical tokens (numbers, code, special characters, URLs)
-
-Based on LLMLingua-2 research: **up to 20x compression** with <2% quality loss on classification tasks, and **6x compression** with 17% quality improvement on RAG tasks.
-
-### Module: Ultra Compression (`open-sse/services/compression/ultra.ts`)
-
-```typescript
-interface UltraConfig {
-  enabled: boolean;
-  // Tier: "heuristic" (no SLM) or "slm" (local model)
-  tier: "heuristic" | "slm";
-  // Compression rate: 0.2 = keep 20% of tokens (5x compression)
-  compressionRate: number; // default: 0.5 (2x compression)
-  // SLM configuration (Tier B only)
-  slm: {
-    modelPath?: string;  // Local path to GGUF/ONNX model
-    modelUrl?: string;   // URL to download model
-    maxMemoryMB: number; // Maximum memory for SLM (default: 1024)
-    useGPU: boolean;     // GPU acceleration (default: false)
-    batchSize: number;   // Processing batch size (default: 400)
-  };
-  // Force tokens that must be preserved
-  forceTokens: string[]; // default: ["\n", "?", "!", ".", ":", ";", "+", "-", "*", "/", "="]
-  // Fallback mode when SLM is unavailable
-  fallbackMode: "standard" | "aggressive"; // default: "aggressive"
-}
-```
-
-### Implementation Path
-
-1. **Phase 4A**: Implement heuristic-based information density scoring (Tier A)
-2. **Phase 4B**: Integrate with ONNX Runtime or similar for local SLM inference (Tier B)
-3. **Phase 4C**: Batch processing mode — queue requests for ultra compression during low-traffic periods
-
-### Heuristic Scoring Algorithm (Tier A)
-
-```typescript
-function scoreToken(token: string, context: string): number {
-  let score = 0;
-  
-  // 1. Frequency score — common words score low
-  const commonWords = new Set(["the", "a", "an", "is", "are", "was", ...]);
-  if (commonWords.has(token.toLowerCase())) score -= 3;
-  
-  // 2. Information density — technical/numeric tokens score high
-  if (/\d/.test(token)) score += 5;          // Contains numbers
-  if (/[A-Z]{2,}/.test(token)) score += 4;   // ALL CAPS (acronyms, error codes)
-  if (token.length > 12) score += 3;          // Long word (likely technical)
-  if (/^[$_]/.test(token)) score += 5;        // Variable-like
-  
-  // 3. Punctuation — structural markers score high
-  if (/[:;={}[\]()]/.test(token)) score += 4;
-  if (/[.!?]/.test(token)) score += 2;
-  
-  // 4. Position score — first/last tokens in sentence score higher
-  // (beginning = topic, end = conclusion/keyword)
-  
-  return score;
-}
-```
-
-## Alternatives Considered
-
-1. **API-based SLM** (call an external perplexity API) — Adds network latency (100-500ms). Defeats the purpose of fast proxy-layer compression. Rejected.
-2. **Python LLMLingua server** (sidecar process) — Adds operational complexity (separate process, Python dependency). Could be a future option if demand exists.
-3. **No Ultra mode** — Some users (especially on free tiers with extreme quota limits) need maximum compression. Ultra mode serves them.
-
-## Acceptance Criteria
-
-- [ ] `open-sse/services/compression/ultra.ts` — Ultra compression orchestrator with tier selection
-- [ ] `open-sse/services/compression/ultraHeuristic.ts` — Heuristic information density scorer (Tier A)
-- [ ] Heuristic scorer produces token-level scores with <10ms per 1K tokens
-- [ ] Heuristic compression achieves ≥40% token savings with ≤5% quality degradation on golden set
-- [ ] Force tokens are always preserved (numbers, code syntax, URLs)
-- [ ] Fallback to aggressive mode when SLM is unavailable
-- [ ] `tests/unit/compression/ultraHeuristic.test.ts` — Scoring accuracy tests
-- [ ] Ultra mode is **disabled by default** in compression config
-- [ ] When enabled, ultra mode can be selected per-combo or per-provider
-- [ ] Memory usage of SLM (Tier B) stays within configured `maxMemoryMB`
-- [ ] SLM-based compression adds <500ms latency per request
-
-## Area
-
-- [x] Proxy / Routing
-- [ ] Dashboard / UI
-- [ ] Provider Support
-- [ ] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [ ] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-All providers — but most valuable for:
-- **Free tier** (maximize quota)
-- **Small context windows** (8K-32K models)
-- **Batch workloads** (latency-tolerant, cost-sensitive)
-
-## Additional Context
-
-### LLMLingua Research Benchmarks
-
-| Method | Paper | Compression | Speed | Quality Impact |
-|---|---|---|---|---|
-| LLMLingua | EMNLP 2023 | Up to 20x | Baseline | <2% drop |
-| LongLLMLingua | ACL 2024 | 4x | Baseline | +17.1% improvement |
-| LLMLingua-2 | ACL 2024 Findings | Up to 20x | 3-6x faster | Improved OOD handling |
-
-### Real-World Example (from or-cli implementation)
-
-```
-Original Tokens: 28,275
-Compressed Tokens: 16,183 (LLMLingua-2, rate 0.5)
-Compression Rate: 1.7x
-Savings: 42.8%
-```
-
-### Resource Requirements
-
-| Tier | Memory | Latency | GPU Required | Model Size |
-|---|---|---|---|---|
-| Heuristic (Tier A) | ~10MB | <10ms | No | N/A |
-| SLM Qwen3-0.6B | ~500MB | 100-300ms | Optional | ~600MB |
-| SLM Phi-2 | ~2GB | 200-500ms | Recommended | ~1.8GB |
-
-## Expected Test Plan
-
-- Unit tests for heuristic scorer — token scoring accuracy
-- Unit tests for force token preservation
-- Integration test: heuristic compression on sample prompts
-- Benchmark: compression ratio vs quality degradation at different rates
-- Memory test: SLM loading/unloading without leaks
-- Performance: latency measurement at different token counts
-- Golden set eval with ultra compression enabled
-- Fallback test: ultra → aggressive fallback when SLM unavailable
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:57:37Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1586.
-
-> **\[Feature\] Modular Prompt Compression Pipeline — Foundation \(Phase 1\)** (#1586)
-
-Similarity score: 91%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:08:21Z):
-**Not a duplicate of #1586.** This is Phase 4, the optionally-enabled Ultra mode:
-
-- **#1586 (Phase 1)**: Lite compression (structural, 10-15% savings, <1ms)
-- **This issue (Phase 4)**: Ultra compression (LLMLingua-style token pruning, 60-80% savings, 100-500ms) — completely different algorithm (perplexity-based scoring, optional local SLM). Disabled by default, opt-in only.
----
-
-
-### Participants
-
-- @oyi77
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1590-compression-dashboard-ui-analytics.md

@@ -1,229 +0,0 @@
-# Feature: [Feature] Compression Dashboard UI & Analytics
-
-> GitHub Issue: #1590 — opened by @oyi77 on 2026-04-25T11:57:53Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-The compression pipeline (Phases 1-4: #1586, #1587, #1588, #1589) provides powerful token-saving capabilities, but users need visibility into:
-
-1. **How much they're saving** — "Am I actually spending fewer tokens with compression on?"
-2. **What mode to choose** — "Should I use Lite, Caveman, or Aggressive for my use case?"
-3. **Quality trade-offs** — "Is compression hurting my response quality?"
-4. **Per-combo configuration** — "I want premium combos uncompressed and free-tier combos aggressively compressed."
-
-Without a UI, compression is an invisible feature. Users won't trust what they can't see.
-
-## Proposed Solution
-
-### 1. Compression Settings Page (`/dashboard/compression`)
-
-A dedicated settings page for managing compression:
-
-| Section | Controls |
-|---|---|
-| **Global Toggle** | Enable/disable compression entirely |
-| **Default Mode** | Dropdown: Off / Lite / Caveman / Aggressive / Ultra |
-| **Auto-Trigger Threshold** | Slider: only compress when estimated tokens > N |
-| **System Prompt Preservation** | Toggle: never compress system prompts |
-| **Provider-Aware Caching** | Toggle: skip compression for providers with prompt caching |
-| **Cache Duration** | Input: cache compressed results for N minutes |
-
-### 2. Per-Combo Compression Override
-
-In the combo builder, add a compression mode selector per combo target:
-
-```
-Combo: "my-coding-stack"
-  ┌──────────────────────────────────────────────────┐
-  │ 1. cc/claude-opus-4-7                              │
-  │    Compression: [Off ▼] (premium — prompt caching) │
-  │                                                      │
-  │ 2. glm/glm-4.7                                      │
-  │    Compression: [Caveman ▼] (cost-sensitive)        │
-  │                                                      │
-  │ 3. if/kimi-k2-thinking                              │
-  │    Compression: [Aggressive ▼] (free tier — max)    │
-  └──────────────────────────────────────────────────┘
-```
-
-This enables **smart cost optimization**: premium providers get uncompressed prompts (they cache them), while cheap/free providers get compressed prompts (saves quota).
-
-### 3. Compression Analytics Dashboard
-
-Add a **Compression** tab to the existing Analytics page:
-
-| Widget | Data |
-|---|---|
-| **Savings Over Time** | Line chart: tokens saved per day/week (stacked by mode) |
-| **Mode Distribution** | Pie chart: % of requests per compression mode |
-| **Cumulative Savings** | Counter: total tokens saved since enabling compression |
-| **Cost Savings Estimate** | Counter: estimated $ saved based on provider pricing |
-| **Quality Score** | Chart: golden set eval scores with/without compression |
-| **Per-Provider Breakdown** | Table: savings per provider (which providers benefit most) |
-| **Latency Impact** | Chart: compression latency histogram |
-
-### 4. Log-Level Compression Stats
-
-In the existing request log detail modal, add compression info:
-
-```
-┌─────────────────────────────────────┐
-│ Request Details                      │
-│ ─────────────────────────────        │
-│ Compression: Caveman                 │
-│ Original Tokens: 4,230              │
-│ Compressed Tokens: 2,890            │
-│ Saved: 1,340 (31.7%)               │
-│ Latency: 3.2ms                      │
-│ Est. Cost Saved: $0.0027            │
-│ Techniques: filler_removal,         │
-│   hedging_removal, structural_compress│
-└─────────────────────────────────────┘
-```
-
-### 5. Compression Preview (Playground)
-
-Add a "Compression Preview" mode in the existing Translator Playground:
-
-1. User enters a prompt
-2. Selects compression mode
-3. Sees side-by-side: original vs compressed
-4. Sees token count comparison
-5. Can send the compressed prompt to any provider to verify quality
-
-## Alternatives Considered
-
-1. **CLI-only configuration** (env vars + settings API) — No visibility. Users can't discover or understand compression benefits. Insufficient.
-2. **No per-combo override** — All-or-nothing compression is wasteful. Premium providers with prompt caching shouldn't have their prompts compressed (it breaks caching).
-3. **Separate analytics dashboard** — Fragmented UX. Better to integrate into existing analytics page.
-
-## Acceptance Criteria
-
-- [ ] `/dashboard/compression` — Compression settings page with all controls listed above
-- [ ] Combo builder — Compression mode dropdown per combo target
-- [ ] Analytics tab — Compression savings chart + cumulative counter + per-provider table
-- [ ] Request log — Compression stats in detail modal (tokens saved, mode, techniques, latency)
-- [ ] Playground — Compression preview mode with side-by-side comparison
-- [ ] Settings API — All compression settings CRUD via `/api/v1/settings/compression`
-- [ ] Compression analytics API — `/api/v1/analytics/compression` endpoint
-- [ ] i18n — All compression UI strings in 30 languages
-- [ ] Responsive — Compression dashboard works on mobile
-
-## Area
-
-- [ ] Proxy / Routing
-- [x] Dashboard / UI
-- [ ] Provider Support
-- [ ] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [x] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-All providers — the UI helps users optimize compression per-provider.
-
-## Additional Context
-
-### Design Considerations
-
-- The compression savings counter should be **prominent and satisfying** — seeing "You've saved 1.2M tokens" reinforces the feature's value
-- Per-combo compression is the **key differentiator** — no other proxy does this
-- The preview mode helps users **trust** compression before enabling it system-wide
-
-### Data Flow
-
-```
-Request → Compression Pipeline → Stats (original, compressed, mode, techniques) 
-                                                │
-                                    ┌──────────┴──────────┐
-                                    │                      │
-                              Detailed logs           Compression
-                              (per-request)           analytics table
-                                    │                      │
-                              Log detail modal        Analytics dashboard
-```
-
-### Compression Analytics Table Schema
-
-```sql
-CREATE TABLE IF NOT EXISTS compression_analytics (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  api_key_id TEXT,
-  combo_id TEXT,
-  provider TEXT,
-  model TEXT,
-  compression_mode TEXT,         -- lite/standard/aggressive/ultra
-  original_tokens INTEGER,
-  compressed_tokens INTEGER,
-  tokens_saved INTEGER,
-  savings_percent REAL,
-  techniques_used TEXT,          -- JSON array of technique names
-  compression_latency_ms REAL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-## Expected Test Plan
-
-- E2E test: navigate to compression settings, change mode, verify API update
-- E2E test: add per-combo override, verify combo config updated
-- Unit test: compression analytics API returns correct aggregates
-- Unit test: compression stats in detailed log schema
-- Visual test: analytics charts render with compression data
-- i18n test: all compression UI keys translated
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:57:57Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1586.
-
-> **\[Feature\] Modular Prompt Compression Pipeline — Foundation \(Phase 1\)** (#1586)
-
-Similarity score: 91%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:08:22Z):
-**Not a duplicate of #1586.** This is the cross-cutting UI/Analytics issue for the compression feature:
-
-- **#1586 (Phase 1)**: Backend compression pipeline + API
-- **This issue**: Dashboard UI, analytics charts, per-combo configuration UI, compression preview playground. Entirely a frontend + analytics concern, not a compression engine.
----
-
-
-### Participants
-
-- @oyi77
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1591-mcp-compression-tools-provider-aware-caching-integration.md

@@ -1,299 +0,0 @@
-# Feature: [Feature] MCP Compression Tools & Provider-Aware Caching Integration
-
-> GitHub Issue: #1591 — opened by @oyi77 on 2026-04-25T11:58:23Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-The compression pipeline (Phases 1-4: #1586, #1587, #1588, #1589) is a proxy-layer optimization. Two gaps remain:
-
-1. **No programmatic control** — MCP clients (IDEs, agents, scripts) cannot query or configure compression at runtime. They need MCP tools to check savings and adjust modes.
-2. **Provider-side prompt caching conflict** — Anthropic, OpenAI, and Google offer prompt caching where repeated identical prompts cost significantly less. If OmniRoute compresses a cached prompt differently each time, it **breaks the cache** and increases costs instead of saving them. The compression pipeline must be aware of provider-side caching.
-
-**Concrete problem**: A user has Anthropic prompt caching enabled. OmniRoute compresses the system prompt slightly differently each request (due to varying user content). Anthropic's cache never hits. Result: **higher costs than if compression was disabled**.
-
-## Proposed Solution
-
-### 1. MCP Compression Tools (2 new tools)
-
-Add to the existing MCP server (`open-sse/mcp-server/`):
-
-#### Tool: `compression_status`
-
-Query compression statistics and current configuration.
-
-```typescript
-{
-  name: "compression_status",
-  description: "Get compression savings statistics and current configuration. Shows tokens saved, mode distribution, and per-provider breakdowns.",
-  inputSchema: z.object({
-    timeRange: z.enum(["1h", "24h", "7d", "30d"]).default("24h"),
-    provider: z.string().optional(),  // Filter by provider
-    combo: z.string().optional(),    // Filter by combo
-  }),
-  handler: async (args) => {
-    // Query compression_analytics table
-    // Return: totalSaved, mode, savingsPercent, costSaved, latencyImpact
-  }
-}
-```
-
-**Example output:**
-```json
-{
-  "enabled": true,
-  "defaultMode": "standard",
-  "last24h": {
-    "totalRequests": 472,
-    "totalTokensSaved": 38420,
-    "avgSavingsPercent": 27.3,
-    "estimatedCostSaved": "$0.077",
-    "modeDistribution": { "lite": "8%", "standard": "72%", "aggressive": "20%" },
-    "avgLatencyMs": 2.8
-  }
-}
-```
-
-#### Tool: `compression_configure`
-
-Change compression settings at runtime.
-
-```typescript
-{
-  name: "compression_configure",
-  description: "Configure compression mode and settings. Changes take effect immediately for new requests.",
-  inputSchema: z.object({
-    enabled: z.boolean().optional(),
-    defaultMode: z.enum(["off", "lite", "standard", "aggressive"]).optional(),
-    autoTriggerTokens: z.number().optional(),
-    preserveSystemPrompt: z.boolean().optional(),
-    comboOverrides: z.record(z.string(), z.enum(["off", "lite", "standard", "aggressive"])).optional(),
-  }),
-  handler: async (args) => {
-    // Update compression config in DB
-    // Return: updated config
-  }
-}
-```
-
-**Scope requirement**: Both tools require a new MCP scope: `compression` (read + write).
-
-### 2. Provider-Aware Caching Integration (`open-sse/services/compression/cachingAware.ts`)
-
-Detect when provider-side prompt caching is active and **skip or reduce compression** to preserve cache hits.
-
-#### Caching Detection Rules
-
-| Provider | Caching Mechanism | Detection |
-|---|---|---|
-| **Anthropic** | Prompt caching via `cache_control` markers | Check if `cache_control` is present in request; check if provider supports caching |
-| **OpenAI** | Automatic prompt caching (GPT-4o, GPT-4.5) | Always active for supported models — detect by model name |
-| **Google Gemini** | Context caching API | Detect via explicit cached context references |
-
-#### Strategy: Cache-Preserving Compression
-
-When provider caching is active:
-
-1. **System prompt**: **Never compress** (system prompts are the most commonly cached component)
-2. **Static context** (system + early messages): Use **deterministic compression** — same input always produces same output, so cache still hits
-3. **Dynamic messages** (recent user/assistant): Apply compression normally (these aren't cached)
-
-```typescript
-interface CachingAwareConfig {
-  enabled: boolean;
-  // Providers with known prompt caching
-  cachedProviders: string[];  // default: ["anthropic", "openai"]
-  // Whether to skip system prompt compression for cached providers
-  preserveSystemForCached: boolean;  // default: true
-  // Whether to use deterministic compression for static context
-  deterministicStatic: boolean;  // default: true
-}
-
-export function shouldSkipCompression(
-  provider: string, 
-  body: ChatRequestBody,
-  compressionMode: CompressionMode,
-  config: CachingAwareConfig
-): { skip: boolean; reason: string; adjustedMode: CompressionMode } {
-  // 1. Check if provider has prompt caching
-  // 2. Check if request has cache_control markers
-  // 3. If caching active: preserve system, use deterministic for static, normal for dynamic
-  // 4. Return adjusted mode (possibly downgraded from "aggressive" to "lite")
-}
-```
-
-#### Deterministic Compression Guarantee
-
-For cache-preserving compression, the output must be **deterministic** given the same input. This means:
-- No random elements in compression
-- No timestamp- or session-dependent compression
-- Same input text → same compressed output
-
-The Caveman rules engine is inherently deterministic (regex-based), making it suitable for cache-preserving compression. Aggressive mode's summarization is NOT deterministic (it can vary) and should be skipped for cached prefixes.
-
-### 3. Cache Hit Rate Analytics
-
-Track cache hit rates with and without compression to validate the strategy:
-
-```sql
-CREATE TABLE IF NOT EXISTS compression_cache_stats (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  provider TEXT,
-  model TEXT,
-  compression_mode TEXT,
-  cache_control_present BOOLEAN,
-  estimated_cache_hit BOOLEAN,  -- based on response headers
-  tokens_saved_compression INTEGER,
-  tokens_saved_caching INTEGER,
-  net_savings INTEGER,          -- compression savings - caching cost
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-**This is crucial**: We need to prove that compression + caching = positive net savings, not negative.
-
-## Alternatives Considered
-
-1. **Always compress, ignore caching** — Would break prompt caching for Anthropic/OpenAI, increasing costs. Rejected.
-2. **Never compress when caching detected** — Too conservative. Static context can benefit from deterministic compression that still preserves cache. Middle ground needed.
-3. **Let users manually configure** — Too complex. Users shouldn't need to understand the interaction between compression and caching. Auto-detection is required.
-
-## Acceptance Criteria
-
-- [ ] `compression_status` MCP tool — Returns savings stats with time range / provider / combo filters
-- [ ] `compression_configure` MCP tool — Runtime compression config changes
-- [ ] New MCP scope `compression` added to scope registry (10 → 11 scopes)
-- [ ] MCP audit entries for compression tool invocations
-- [ ] `open-sse/services/compression/cachingAware.ts` — Provider caching detection
-- [ ] System prompts never compressed for Anthropic/OpenAI when caching is active
-- [ ] Deterministic compression for static context on cached providers
-- [ ] Cache hit rate tracking in `compression_cache_stats` table
-- [ ] When compression would reduce cache savings, strategy selector downgrades mode
-- [ ] Unit tests for cache-aware compression logic
-- [ ] Integration test: compression + Anthropic-style `cache_control` request
-- [ ] Net savings tracking: prove compression + caching > either alone
-
-## Area
-
-- [x] Proxy / Routing
-- [ ] Dashboard / UI
-- [ ] Provider Support
-- [x] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [x] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-- **Anthropic** — Prompt caching (cache_control markers)
-- **OpenAI** — Automatic prompt caching (GPT-4o, GPT-4.5)
-- **Google Gemini** — Context caching API
-- All other providers — no caching, full compression applies
-
-## Additional Context
-
-### Anthropic Prompt Caching Economics
-
-- Cached input: **$0.50/1M tokens** (10x cheaper than $3.00/1M standard)
-- A 10K token system prompt cached vs uncached: $0.005 vs $0.03 — **6x savings from caching alone**
-- If compression breaks the cache (even at 30% token savings): $0.021 vs $0.005 — **4x more expensive than caching**
-- **Lesson**: For cached contexts, preserving the cache is more valuable than compressing tokens
-
-### OpenAI Prompt Caching
-
-- Automatic for prompts with repeated prefixes
-- Discount: **50% savings** on cached prompt tokens
-- Compression that changes the prefix (even slightly) breaks the cache
-
-### Interaction Diagram
-
-```
-Request arrives
-  │
-  ├── Provider has caching? ──── No ──→ Full compression (any mode)
-  │
-  └── Yes
-       │
-       ├── cache_control in request? ──── No ──→ Full compression
-       │                                              (provider may cache anyway)
-       └── Yes
-            │
-            ├── System prompt ──→ NO compression (preserve cache key)
-            ├── Static messages ──→ Deterministic Caveman only
-            └── Dynamic messages ──→ Normal compression (not cached)
-```
-
-## Expected Test Plan
-
-- Unit tests for `compression_status` MCP tool handler
-- Unit tests for `compression_configure` MCP tool handler
-- Unit tests for `cachingAware.ts` — all provider + caching state combinations
-- Unit test: deterministic compression produces identical output for identical input
-- Integration test: MCP tool invocation via stdio transport
-- Integration test: compression + Anthropic request with `cache_control`
-- Integration test: cache hit rate tracking
-- Regression: existing MCP tools unaffected by new scope
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:58:29Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/813.
-
-> **\[Feature\] Prompt Caching & Provider-Specific Caching Support** (#813)
-
-Similarity score: 93%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:08:24Z):
-**Not a duplicate of #813.** These are complementary but distinct:
-
-- **#813 (Prompt Caching)**: Uses *provider-side* caching mechanisms (Anthropic `cache_control`, Gemini `cachedContent`, OpenAI `prompt_cache_key`) to save costs on repeated identical prefixes. No token reduction — same prompt, cheaper because provider reuses KV cache.
-
-- **This issue (MCP Compression Tools + Caching Integration)**: Two parts:
-  1. MCP tools for programmatic compression control (`compression_status`, `compression_configure`)
-  2. Provider-aware compression that **preserves caching** — when a provider has prompt caching active, compression is adjusted to avoid breaking cache hits (deterministic compression for static context, skip system prompts)
-
-Far from being a duplicate, this issue specifically **builds on** #813's work by ensuring our compression pipeline doesn't conflict with the caching layer #813 introduces.
----
-**@dmpost** (2026-04-28T11:32:00Z):
-Does that mean we should better disable OmniRoute caching until the issue fixed?
-Or have only one of them enabled, agent cache or OmniRoute cache?
----
-
-
-### Participants
-
-- @oyi77
-- @dmpost
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1716-separate-fetch-start-and-first-content-timeouts-from-stream-idle-timeout.md

@@ -1,107 +0,0 @@
----
-issue: 1716
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:12Z
----
-
-# Feature: [Feature] Separate fetch-start and first-content timeouts from stream idle timeout
-
-> GitHub Issue: #1716 — opened by @matteoantoci on 2026-04-28T09:51:04Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Enhancement: Shorter timeouts for zombie stream detection
-
-### Current behavior
-
-All timeout-sensitive phases share `FETCH_TIMEOUT_MS` / `STREAM_IDLE_TIMEOUT_MS` (default 10 minutes). Additionally, there is **no request-level deadline** — if a request gets stuck in a pre-fetch phase (rate limiter queue, account semaphore, translation, etc.), it hangs indefinitely with no timeout to recover.
-
-Observed failure modes:
-- Upstream never returns HTTP headers → 10 min hang
-- Upstream returns HTTP 200 but never sends SSE data → 10 min hang before `ensureStreamReadiness` catches it
-- Upstream sends initial content then stalls mid-stream → 10 min hang before idle timeout
-- Request stuck in rate limiter queue or account fallback → **indefinite hang** (no timeout covers this phase)
-
-### Proposed behavior
-
-Split timeouts into distinct phases, plus add a request-level hard deadline for pre-streaming phases:
-
-| Phase | Proposed default | Current | Env override |
-|-------|-----------------|---------|-------------|
-| **Request deadline** (pre-streaming phases) | 600s | none | `FETCH_TIMEOUT_MS` |
-| Fetch headers (time to HTTP response) | 60s | 600s | `FETCH_HEADERS_TIMEOUT_MS` |
-| First content (time to first useful SSE event) | 60s | 600s | `STREAM_FIRST_CONTENT_TIMEOUT_MS` |
-| Stream idle (mid-stream pauses) | 120s | 600s | `STREAM_IDLE_TIMEOUT_MS` |
-
-**Request deadline** covers the entire pre-streaming lifecycle (rate limiter wait, account fallback, translation, fetch setup, `ensureStreamReadiness`). Once the stream is confirmed active (useful content received), the deadline is cancelled — active streams are governed only by the idle timeout, which resets on every chunk. This means reasoning models that think for 10+ minutes are NOT cut, as long as they send tokens.
-
-### Implementation
-
-1. Add `STREAM_FIRST_CONTENT_TIMEOUT_MS` (default 60s) to `runtimeTimeouts.ts`
-2. Change `FETCH_HEADERS_TIMEOUT_MS` default from `fetchTimeoutMs` to 60s
-3. Lower `DEFAULT_STREAM_IDLE_TIMEOUT_MS` from 600s to 120s
-4. Use `STREAM_FIRST_CONTENT_TIMEOUT_MS` in `ensureStreamReadiness()` call (currently uses `STREAM_IDLE_TIMEOUT_MS`)
-5. Use `FETCH_HEADERS_TIMEOUT_MS` in `BaseExecutor.execute()` fetch-start timeout (currently uses `getTimeoutMs()`)
-6. Add `requestTimeoutMs` option to `createStreamController()` — starts a hard deadline timer when the request begins
-7. Cancel the deadline timer once `ensureStreamReadiness` passes (stream confirmed active)
-8. The deadline uses `FETCH_TIMEOUT_MS` as the default, configurable via env var
-
-### Impact
-
-- Zombie streams detected in ~60s instead of ~10min
-- Mid-stream stalls detected in ~2min instead of ~10min
-- **Pre-fetch hangs (rate limiter, account fallback) now covered** — 600s hard deadline prevents indefinite hangs
-- Combo fallback triggers much faster
-- No change to actively streaming behavior — deadline is cancelled once stream starts, and idle timer resets on every chunk
-- All timeouts are env-overridable for operators who need different values
-
-### Context
-
-Observed with mimo-v2.5-pro via opencode-go in three separate incidents:
-1. Provider returned HTTP 200 but never sent SSE data → 15+ min hang
-2. Provider sent initial SSE content then stalled completely → 13+ min hang
-3. Request stuck after account fallback (429 on first account, second account's request never reached fetch) → 24+ min hang with zero log output after fallback
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @matteoantoci
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1735-combo-builder-quota-aware-highest-remaining-quota-rule.md

@@ -1,89 +0,0 @@
----
-issue: 1735
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:10Z
----
-
-# Feature: [Feature] Combo Builder: quota-aware Highest Remaining Quota rule
-
-> GitHub Issue: #1735 — opened by @apoapostolov on 2026-04-28T17:54:35Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem
-Combo building needs a quota-aware ranking rule that favors models whose remaining quota can last through the rest of the current quota window.
-
-## Proposed rule: Highest Remaining Quota Rate
-For any service with a fixed quota window:
-
-- Let `remaining_quota` be the fraction of quota still available, normalized to `0..1`.
-- Let `remaining_days` be the time left in the current quota window, expressed in days.
-- Compute `remaining_quota_rate = remaining_quota / remaining_days`.
-
-For weekly quotas:
-
-- The expected pacing threshold is `1/7` quota per day.
-- Prefer models where `remaining_quota_rate > 1/7`.
-- If `remaining_quota_rate <= 1/7`, stop using that model in active combos until it recovers above the threshold.
-
-## Example
-If a model has `60%` of its weekly quota left and `2d 10hr` remaining:
-
-- `remaining_days = 2.4167`
-- `remaining_quota_rate = 0.60 / 2.4167 = 0.248/day`
-- Since `0.248 > 1/7`, the model should remain eligible and be preferred over lower-rate options.
-
-## Expected behavior
-- Combos should rank models using the `remaining_quota_rate` rule whenever a quota window is known.
-- Models above the threshold should be preferred or retained.
-- Models at or below the threshold should be dropped from active use.
-- The rule should be applied consistently during combo evaluation and refresh.
-
-## Notes
-- If a quota is measured in calls instead of percentage, normalize it to a fraction of the current window before applying the rule.
-- The same rule should generalize to other quota windows by using `1 / window_length_days` as the threshold.
-
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @apoapostolov
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1736-dashboard-customization-for-home.md

@@ -1,79 +0,0 @@
----
-issue: 1736
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:10Z
----
-
-# Feature: [Feature] Dashboard customization for /Home
-
-> GitHub Issue: #1736 — opened by @apoapostolov on 2026-04-28T18:03:58Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem
-The /Home dashboard should be customizable so users can choose which widgets appear there and in what order. Right now the home page is too fixed, and some widgets are only useful for specific workflows.
-
-## Request
-Add a /Home customization layer that lets users:
-- Show or hide individual widgets on /Home.
-- Reorder widgets, including pinning a widget to the top.
-- Reuse blocks from other pages where it makes sense, instead of forcing /Home to be a fixed layout.
-
-## Examples
-- Turn off the Onboarding widget after setup.
-- Hide Providers Status when it is not useful for the current workflow.
-- Pin the Limits and Quotas block to the top when tracking monthly usage for GLM, Codex, Claude, and Copilot.
-
-## Expected behavior
-- Widget visibility should be persisted per user.
-- Widget order should be persistent across refreshes and restarts.
-- The /Home page should still have a sensible default layout for first-time users.
-
-## Notes
-- The goal is not a fully freeform page builder. A controlled widget picker and ordering system is enough.
-- This should probably apply only to /Home at first, not every dashboard page.
-
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @apoapostolov
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1737-auto-update-limits-and-quotas-widget.md

@@ -1,80 +0,0 @@
----
-issue: 1737
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:10Z
----
-
-# Feature: [Feature] Auto-update Limits and Quotas widget
-
-> GitHub Issue: #1737 — opened by @apoapostolov on 2026-04-28T18:04:00Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem
-The Limits and Quotas widget should refresh automatically instead of requiring manual updates or stale page reloads. Quota data changes over time and needs to stay current enough to be useful on the dashboard.
-
-## Request
-Add automatic refresh for the Limits and Quotas widget block with the following behavior:
-- Refresh interval defaults to 3 minutes.
-- Auto-update is off by default.
-- Users can enable it when they want the widget to stay current.
-
-## Why this matters
-- The widget is only useful when the quota numbers are fresh.
-- For tracked services like GLM, Codex, Claude, and Copilot, the displayed remaining quota can change quickly enough that stale values are misleading.
-- The /Home dashboard becomes much more useful if the widget can keep itself updated while the page stays open.
-
-## Expected behavior
-- When enabled, the widget refreshes on the configured interval without full page reloads.
-- The refresh should not be noisy or visually disruptive.
-- The interval should be configurable, but 3 minutes is a sensible default.
-- The feature should be opt-in, not forced on every user.
-
-## Notes
-- The widget should continue to work as a normal static block when auto-update is disabled.
-- If a refresh fails, the widget should degrade gracefully and keep the last known data visible.
-
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @apoapostolov
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1786-add-codebuddy-yepcom-support.md

@@ -1,77 +0,0 @@
----
-issue: 1786
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 19
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:08Z
----
-
-# Feature: [Feature] Add CodeBuddy + Yep.com support
-
-> GitHub Issue: #1786 — opened by @crakindee2k-a11y on 2026-04-29T18:43:00Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Feature Request: CodeBuddy + YepApi Support
-
-### Description
-Add routing support for:
-- [CodeBuddy](https://www.codebuddy.ai/home)
-- [YepApi](https://www.yepapi.com/)
-
-### Free Offers
-- **CodeBuddy:** 2-week free trial
-- **YepApi:** $5 free credits
-
-Easy testing, zero cost barrier.
-
-### Implementation
-- Add providers to routing config
-- Implement API integrations
-- Update docs with setup instructions
-
-### References
-- CodeBuddy: https://www.codebuddy.ai/home
-- Yep.com: https://www.yepapi.com/
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @crakindee2k-a11y
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1814-streamed-glm-chatcompletions-requests-can-look-stalled-when-no-output-cap-is-forwarded.md

@@ -1,79 +0,0 @@
----
-issue: 1814
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 18
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:53:07Z
----
-
-# Feature: [Feature] Streamed GLM chat/completions requests can look stalled when no output cap is forwarded
-
-> GitHub Issue: #1814 — opened by @apoapostolov on 2026-04-30T10:49:11Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-Hermes requests routed through OmniRoute to `glm/glm-5-turbo` can appear stalled for 30-85s before the first useful completion finishes.
-
-Observed on 2026-04-30:
-- `POST /v1/chat/completions`
-- provider: `glm`
-- requested model: `glm/glm-5-turbo`
-- status: `200`
-- duration: `84609 ms` on one call, with many others in the 25-45s range
-- prompt tokens: `68906`
-- completion tokens: `5449`
-- stream: `true`
-- tools: `25`
-- `finish_reason: "tool_calls"`
-- request body contained `messages`, `model`, `stream`, `stream_options`, `tools`, and `_omniroute`, but no `max_tokens` or `max_completion_tokens`
-
-The gateway logs look healthy, so this does not appear to be a crash. The user-visible problem is that requests with very large prompts and no explicit output cap can look like the endpoint is hanging even though they eventually complete.
-
-Possible improvements:
-- add a configurable default output cap when the client omits one
-- surface a warning/metric when streaming requests arrive with no cap and very large prompts
-- add clearer observability around time-to-first-token vs total completion time
-
-I can share the local call-log details if useful.
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @apoapostolov
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1833-api-first-management-rest-endpoints-for-programmatic-omniroute-configuration.md

@@ -1,112 +0,0 @@
----
-issue: 1833
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 18
-  labels: ["enhancement", "kilo-triaged", "kilo-duplicate"]
-  state: open
-  classified_at: 2026-05-01T10:53:06Z
----
-
-# Feature: [Feature] API-first Management — REST Endpoints for Programmatic OmniRoute Configuration
-
-> GitHub Issue: #1833 — opened by @diegosouzapw on 2026-04-30T19:55:40Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Summary
-
-Implement a dedicated REST management API with scoped API keys for programmatic OmniRoute configuration. This enables CI/CD integration, infrastructure-as-code workflows, third-party monitoring, and CLI scripting without requiring MCP or the dashboard.
-
-## Origin
-
-This feature request originates from Discussion #1567 by @shannonlowder — a well-specified proposal for management-scoped API keys and settings endpoints.
-
-## Motivation
-
-While OmniRoute already provides programmatic access through the **MCP Server** (29 tools), a dedicated REST API would:
-- Enable CI/CD integration without MCP dependency
-- Support infrastructure-as-code workflows (Terraform, Pulumi)
-- Allow third-party monitoring tool integration
-- Provide CLI scripting for batch operations
-- Lower the barrier for automation (standard HTTP vs MCP protocol)
-
-## Proposed Scope
-
-### Management API Keys
-- Create management-scoped API keys (separate from request proxy keys)
-- Scoped permissions: `providers:read`, `providers:write`, `combos:read`, `combos:write`, `settings:read`, `settings:write`, etc.
-
-### REST Endpoints
-- `GET/POST/PUT/DELETE /api/v1/management/providers` — CRUD for provider connections
-- `GET/POST/PUT/DELETE /api/v1/management/combos` — CRUD for combos
-- `GET/PUT /api/v1/management/settings` — Read/update settings
-- `GET /api/v1/management/health` — Detailed health check
-- `GET /api/v1/management/metrics` — Usage metrics and analytics
-
-### Export/Import
-- `GET /api/v1/management/export` — Full config export (JSON)
-- `POST /api/v1/management/import` — Config import with merge/overwrite options
-
-## Implementation Notes
-
-- Auth: Reuse existing API key infrastructure with added management scope
-- Validation: Zod schemas for all inputs (consistent with existing patterns)
-- DB: All operations through `src/lib/db/` domain modules
-- Audit: Log all management operations to `mcp_audit` or new `management_audit` table
-
-## Labels
-`enhancement`, `api`
-
----
-*Ref: https://github.com/diegosouzapw/OmniRoute/discussions/1567*
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-30T19:55:46Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1568.
-
-> **API-first management for OmniRoute - management-scoped API keys & settings endpoints** (#1568)
-
-Similarity score: 95%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-
-
-### Participants
-
-- @diegosouzapw
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/defer/1845-first-class-hermes-agent-support-auto-configured-tool-card-with-yaml-provider-integration.md

@@ -1,200 +0,0 @@
----
-issue: 1845
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 17
-  labels: ["kilo-triaged", "kilo-duplicate"]
-  state: open
-  classified_at: 2026-05-01T10:53:06Z
----
-
-# Feature: [Feature] First-class Hermes Agent support — auto-configured tool card with YAML provider integration
-
-> GitHub Issue: #1845 — opened by @apoapostolov on 2026-05-01T10:23:54Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## What
-
-Proper first-class Hermes Agent support in the CLI Tools section — with an auto-configured tool card (like Claude Code, OpenClaw, Codex) instead of the current generic guide-based entry.
-
-## Why
-
-Hermes Agent (https://github.com/NousResearch/hermes-agent) is a terminal-native AI agent framework by Nous Research, same category as Claude Code, Codex, and OpenClaw. It's approaching feature parity with OpenClaw and in some areas (skills system, credential pooling, multi-platform gateway, profile isolation) it's already ahead.
-
-Right now Hermes shows up as a **guided** tool card with a generic JSON snippet:
-
-```json
-{
-  "provider": {
-    "type": "openai",
-    "baseURL": "{{baseUrl}}",
-    "apiKey": "***",
-    "model": "{{model}}"
-  }
-}
-```
-
-This doesn't match Hermes Agent's actual config format at all. Hermes uses YAML (`~/.hermes/config.yaml`), not JSON, and has a much richer provider model with several configuration surfaces that OmniRoute could manage automatically:
-
-### What Hermes Agent actually needs
-
-Hermes has **three distinct model slots** that OmniRoute could populate:
-
-**1. Core model** (the main conversation model):
-```yaml
-model:
-  default: omniroute/claude-sonnet-4-6
-  provider: omniroute
-  base_url: http://localhost:20128/v1
-  api_key: sk-...
-```
-
-**2. Delegation model** (for subagents):
-```yaml
-delegation:
-  model: omniroute/claude-sonnet-4-6
-  provider: omniroute
-  base_url: http://localhost:20128/v1
-  api_key: sk-...
-```
-
-**3. Auxiliary models** (for vision, compression, web extraction, etc.):
-```yaml
-auxiliary:
-  vision:
-    provider: omniroute
-    model: omniroute/gemini-3-flash
-    base_url: http://localhost:20128/v1
-    api_key: sk-...
-  compression:
-    provider: omniroute
-    model: omniroute/kimi-k2.5
-    base_url: http://localhost:20128/v1
-    api_key: sk-...
-```
-
-The current guide entry only covers case #1, and even that with the wrong format. An auto-configured card could handle all three, letting users pick which models OmniRoute serves for each slot.
-
-### Hermes Agent is a real integration target
-
-- **YAML config** at `~/.hermes/config.yaml` (readable/writable, well-structured)
-- **Secrets in `.env`** at `~/.hermes/.env` (API keys stored separately, like OpenClaw)
-- **Config path** can be discovered via `hermes config path`
-- **Runtime detection** works — the existing `cliRuntime.ts` already has a `hermes` entry pointing at `CLI_HERMES_BIN` and `.config/hermes/config.json` (though the path is wrong — it should be `.hermes/config.yaml`)
-- **Install detection** via `hermes --version`
-- **Provider-agnostic by design** — adding a custom OpenAI-compatible provider is a first-class config operation
-
-### Config path discrepancy
-
-The current `cliRuntime.ts` entry has:
-```ts
-hermes: {
-  paths: { config: ".config/hermes/config.json" }
-}
-```
-
-The actual config lives at `~/.hermes/config.yaml`. This should be corrected.
-
-## Proposed approach
-
-An auto-configured `HermesToolCard` component, similar to how `OpenClawToolCard` works:
-
-1. **Detect installed Hermes** — run `hermes --version` (already supported by cliRuntime)
-2. **Read current config** — parse `~/.hermes/config.yaml` to check if an `omniroute` provider is already configured
-3. **Offer three configuration modes:**
-   - **Core model** — set `model.default`, `model.provider`, `model.base_url`, `model.api_key` (or the key in `.env`)
-   - **Delegation model** — set `delegation.*` fields (for subagent tasks)
-   - **Auxiliary models** — per-slot (vision, compression, web_extract) with individual model selection
-4. **Write config** — update the YAML file and/or `.env` with the OmniRoute endpoint and API key
-5. **Model selection** — show OmniRoute's available models so users pick which models serve each slot
-6. **Config status** — show whether Hermes is already pointed at OmniRoute (similar to OpenClaw's `getConfigStatus()`)
-
-The `.env` file would get:
-```
-OMNIROUTE_API_KEY=sk-...
-OMNIROUTE_BASE_URL=http://localhost:20128/v1
-```
-
-And `config.yaml` would get the provider reference:
-```yaml
-providers:
-  omniroute:
-    type: openai
-    base_url: ${OMNIROUTE_BASE_URL}
-    api_key: ${OMNIROUTE_API_KEY}
-    models:
-      - claude-sonnet-4-6
-      - gemini-3-flash
-      - kimi-k2.5
-
-model:
-  default: omniroute/claude-sonnet-4-6
-  provider: omniroute
-
-delegation:
-  model: omniroute/claude-sonnet-4-6
-  provider: omniroute
-```
-
-## Additional context
-
-- Hermes Agent docs: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
-- Provider config reference: https://hermes-agent.nousresearch.com/docs/integrations/providers
-- The existing guide-based card has i18n entries in 30+ languages ("Hermes AI Terminal Assistant") which could be reused
-- Hermes Agent users actively use OmniRoute — there are already community guides and a WUPHF integration for it
-- Hermes supports credential pooling and multi-provider routing natively, so an OmniRoute provider fits naturally into its architecture
-
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-05-01T10:23:59Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1475.
-
-> **Feature request: add Hermes quick-configuration support to tools** (#1475)
-
-Similarity score: 91%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@apoapostolov** (2026-05-01T10:28:20Z):
-The similarity confusion comes from the fact there is a Hermes, and a Hermes-agent tools, two different cli tools for AI.
----
-
-
-### Participants
-
-- @apoapostolov
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/notfit/1513-local-llm-fallback.md

@@ -1,75 +0,0 @@
-# Feature: [Feature] Local LLM as final fallback
-
-> GitHub Issue: #1513 — opened by @woutercoppens on 2026-04-22T15:59:51Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-Is it possible to specify a local LLM as a last resort fallback? I'm thinking about Ollama, llama.cpp, vLLM, etc. 
-This could save tokens. 
-
-### Proposed Solution
-
-If all other providers have ran out of tokens, a local LLM could continue the job.
-
-### Alternatives Considered
-
-None
-
-### Acceptance Criteria
-
-Just fallback to local LLM 
-
-### Area
-
-Provider Support
-
-### Related Provider(s)
-
-Ollama (local), Llama.ccp, ...
-
-### Additional Context
-
-_No response_
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-### Participants
-
-- @woutercoppens — Original requester
-
-### Key Points
-
-- User wants a concept of a "final fallback" provider that triggers when all other primary/cloud providers have exhausted their tokens/quotas.
-
-## 🎯 Refined Feature Description
-
-The routing engine (combo routing) allows users to sequence models. The user is asking for a global "last resort" fallback, or a way to include local models (Ollama, vLLM) easily as the final target in a fallback sequence if all others hit rate limits or quota exhaustion.
-OmniRoute already supports Ollama and custom OpenAI-compatible endpoints. The feature request might simply be asking for a way to configure a "Global Fallback" or to build combos where the final fallback is explicitly marked to only trigger on quota exhaustion of the primary ones. Wait, Combo Routing already does this: if the first target fails (e.g. 429 Too Many Requests, Quota Exceeded), it falls back to the next target. If the user sets up a Combo with GPT-4 as Priority 1 and Ollama as Priority 2, it already behaves exactly as requested.
-
-### What it solves
-
-- Save tokens/costs by falling back to a free, local alternative when cloud limits are reached.
-
-### How it should work (high level)
-
-1. Wait, this functionality already exists using the existing **Combo Routing** and **Ollama Provider** support!
-2. Users can create a combo with their primary models, and add a local Ollama model at the lowest priority. OmniRoute's `handleComboChat` naturally falls through targets upon failure.
-
-### Affected areas
-
-- None (Already exists).
-
-## 📎 Attachments & References
-
-- None.
-
-## 🔗 Related Ideas
-
-- None.

_ideia/notfit/1529-request-support-kieai-media-api-generator.md

@@ -1,74 +0,0 @@
-# Feature: [Feature] Request: Support Kie.ai Media API Generator
-
-> GitHub Issue: #1529 — opened by @wauputr4 on 2026-04-23T10:42:35Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Summary
-Support Kie.ai as a provider for the Media API Generator. Kie.ai offers a unified API for various AI models including video, image, and music generation.
-
-### Details
-- **Provider:** Kie.ai
-- **Documentation:** https://docs.kie.ai
-- **Base URL:** https://api.kie.ai
-- **Capabilities:**
-  - **Video:** Veo 3.1, Runway Aleph, Sora2
-  - **Image:** Flux.1, Midjourney, etc.
-  - **Music:** Suno (V3.5, V4, V4.5 Plus)
-- **Workflow:** Asynchronous task model (Submit task -> Task ID -> Poll status -> Download URL).
-
-### Benefits
-Integrating Kie.ai would allow OmniRoute users to access multiple state-of-the-art media generation models through a single provider integration.
-
-## 💬 Community Discussion
-
-**@edwardsconnects90** (2026-04-23T19:46:38Z):
-+++ I also like this provider, I hope there will be a possibility to add it
----
-**@diegosouzapw** (2026-04-25T15:03:03Z):
-Thank you for the suggestion, @wauputr4! Kie.ai looks like a strong candidate for the media generation pipeline — its async task-based model (submit → poll → download) is similar to our existing RunwayML integration, so the executor pattern would translate well.
-
-We'll track this as a provider onboarding candidate for a future release cycle. The key implementation pieces would be:
-1. A task-based executor in `open-sse/executors/` with polling logic
-2. Provider registration in `src/shared/constants/providers.ts`
-3. Coverage for video, image, and music modalities
-
-Keeping this open for tracking.
----
-
-
-### Participants
-
-- @edwardsconnects90
-- @diegosouzapw
-- @wauputr4
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/notfit/1586-modular-prompt-compression-pipeline-foundation-phase-1.md

@@ -1,219 +0,0 @@
-# Feature: [Feature] Modular Prompt Compression Pipeline — Foundation (Phase 1)
-
-> GitHub Issue: #1586 — opened by @oyi77 on 2026-04-25T11:51:38Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem / Use Case
-
-OmniRoute currently has a reactive context manager (`open-sse/services/contextManager.ts`) that only compresses prompts when they **exceed** a model's context window. This means:
-
-1. **Zero savings on normal requests** — if a prompt fits the window, no optimization happens at all, even though 10-40% of tokens are wasted on filler, repetition, and verbose phrasing.
-2. **Destructive overflow handling** — when context does overflow, the current approach drops messages entirely (purify history) or truncates tool outputs (2000 char limit), losing information irreversibly.
-3. **No per-combo control** — different combos (free-tier vs premium) have different cost sensitivities, but there's no way to apply different compression levels.
-4. **Free quota is wasted** — free tier users hit rate limits constantly; reducing token consumption by 25-40% would effectively increase their usable quota by the same amount.
-
-**The proxy layer is the perfect place for compression.** Every request passes through OmniRoute. No individual SDK or client can achieve this — it requires a centralized interception point.
-
-## Proposed Solution
-
-Introduce a **modular compression pipeline** that runs **before** the existing context manager, with four compression modes on a speed/savings/quality tradeoff spectrum:
-
-```
-Full Prompt ──→ [Strategy Selector] ──→ Compressed Prompt ──→ Upstream Provider
-                       │
-                       ├── 🟢 Lite (instant, ~10-15% savings)
-                       │     Structural dedup, whitespace normalization, system prompt dedup
-                       │
-                       ├── 🟡 Standard / Caveman (~25-40% savings, <5ms)
-                       │     Rule-based NLP: strip filler, compress instructions, condense context
-                       │
-                       ├── 🟠 Aggressive (~40-60% savings, <50ms)
-                       │     History summarization, tool result compression, progressive aging
-                       │
-                       └── 🔴 Ultra (up to 80% savings, LLM-assisted)
-                             LLMLingua-style perplexity-based token pruning via local SLM
-```
-
-### Pipeline Placement
-
-```
-Client Request
-  → API Route (auth, guardrails)
-  → [NEW: Compression Pipeline]  ← INSERT HERE, before context manager
-  │   ├── Strategy selection (based on config + context size)
-  │   ├── Compression execution (lite/caveman/aggressive/ultra)
-  │   └── Stats logging (tokens saved, technique used)
-  → [EXISTING: Context Manager (overflow handling)]
-  → [EXISTING: Memory Injection]
-  → [EXISTING: System Prompt Injection]
-  → [EXISTING: Thinking Budget]
-  → chatCore → Executor → Upstream
-```
-
-Key design: **Compression runs before context manager.** Compression reduces the base token count proactively. Context manager still handles overflow cases. Together they provide both proactive savings AND reactive overflow protection.
-
-### Phase 1 Scope — Foundation
-
-This issue covers **Phase 1 only**: the pipeline framework, strategy selector, lite compression, and integration into `chatCore.ts`.
-
-| Component | File | Description |
-|---|---|---|
-| **Compression config** | `src/lib/db/compression.ts` | DB schema for compression settings (enabled, defaultMode, autoTriggerTokens, cacheMinutes, preserveSystemPrompt, comboOverrides) |
-| **Strategy selector** | `open-sse/services/compression/strategySelector.ts` | Mode selection logic: check config → check combo override → estimate tokens → decide mode |
-| **Lite compression** | `open-sse/services/compression/lite.ts` | Structural optimizations: whitespace collapse, system prompt dedup, tool result structural compression, duplicate message removal, image URL → placeholder for non-vision models |
-| **Compression stats** | `open-sse/services/compression/stats.ts` | Track original tokens, compressed tokens, savings %, technique used per request |
-| **Pipeline integration** | `open-sse/handlers/chatCore.ts` | Insert compression call before `compressContext()` |
-| **Settings API** | `src/app/api/v1/settings/compression/route.ts` | CRUD for compression config (GET/PUT) |
-| **Unit tests** | `tests/unit/compression/` | Tests for strategy selector, lite compression, stats |
-
-### Lite Compression Techniques
-
-| Technique | What It Does | Est. Savings |
-|---|---|---|
-| Whitespace collapse | Reduce 3+ newlines to 2, trim trailing spaces | 3-5% |
-| System prompt dedup | Detect repeated system instructions across messages | 5-10% |
-| Tool result structural compression | Replace verbose JSON keys with shorter aliases | 5-15% |
-| Redundant content removal | Remove duplicate messages (common in multi-turn) | 2-5% |
-| Image URL → placeholder | Replace base64 images with `[image: WxH, format]` for non-vision models | 80-95% on that message |
-
-## Alternatives Considered
-
-1. **Only compress on overflow** (current approach) — Misses 90%+ of requests that fit but waste tokens. Rejected as insufficient.
-2. **LLM-based compression only** (send to cheap model, get summary back) — Adds latency and cost. Not practical as the only mode. Kept as optional "Ultra" tier.
-3. **Client-side compression** — Requires every SDK/client to implement compression. Defeats the purpose of a centralized proxy.
-
-## Acceptance Criteria
-
-- [ ] `src/lib/db/compression.ts` — DB module with settings schema (enabled, mode, overrides, thresholds)
-- [ ] `open-sse/services/compression/strategySelector.ts` — Strategy selection logic with config lookup
-- [ ] `open-sse/services/compression/lite.ts` — All 5 lite compression techniques implemented
-- [ ] `open-sse/services/compression/stats.ts` — Per-request compression stats tracking
-- [ ] `open-sse/handlers/chatCore.ts` — Compression pipeline called before `compressContext()`
-- [ ] `src/app/api/v1/settings/compression/route.ts` — GET/PUT compression settings
-- [ ] `tests/unit/compression/` — Unit tests for all new modules with 60%+ coverage
-- [ ] Existing request flow unchanged when compression mode is `off`
-- [ ] Compression stats logged to detailed logs (optional per-request)
-- [ ] No regression in existing `compressContext()` behavior
-- [ ] Lite mode adds <1ms latency on average requests
-
-## Area
-
-- [x] Proxy / Routing
-- [ ] Dashboard / UI
-- [ ] Provider Support
-- [ ] CLI Tools Integration
-- [ ] OAuth / Authentication
-- [x] Analytics / Usage Tracking
-
-## Related Provider(s)
-
-All providers — this is a cross-cutting optimization that applies to every upstream request.
-
-## Additional Context
-
-### Token Savings Estimates
-
-| Mode | Per-Request Savings | Latency Impact | Quality Impact | Best For |
-|---|---|---|---|---|
-| Off | 0% | 0ms | None | Premium providers, sensitive tasks |
-| Lite | 10-15% | <1ms | Imperceptible | All requests (recommended default) |
-| Standard (Caveman) | 25-40% | <5ms | Minimal | Chat, coding, general Q&A |
-| Aggressive | 40-60% | <50ms | Moderate | Long conversations, tool-heavy flows |
-| Ultra | 60-80% | 100-500ms | Noticeable | Batch processing, rate-limited quotas |
-
-### Why This Matters for OmniRoute
-
-1. **Free tier multiplier**: 40% compression = 40% more free usage. Directly improves "never stop coding" value prop.
-2. **Competitive moat**: No other AI proxy/router offers prompt compression.
-3. **Combo routing synergy**: When falling back to cheap providers (smaller context windows), compression makes them more effective.
-4. **Zero-cost Lite mode**: <1ms overhead, 10-15% savings. No reason not to enable it by default.
-
-### Compatibility with Provider-Side Prompt Caching
-
-Anthropic and OpenAI offer prompt caching where repeated prompts cost less. Compression should **skip** when provider-side caching is active (a cached prompt costs less than a compressed uncached one). The strategy selector must be provider-aware.
-
-## Expected Test Plan
-
-- Unit tests for `strategySelector.ts` — all mode selection paths
-- Unit tests for `lite.ts` — each compression technique independently
-- Unit tests for `stats.ts` — token counting accuracy
-- Integration test: full request flow with compression enabled/disabled
-- Integration test: compression + context manager interaction (compress first, then handle overflow)
-- Test coverage: 60%+ for all new modules
-- Run `npm run test:all` — no regressions in existing tests
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-25T11:51:43Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/813.
-
-> **\[Feature\] Prompt Caching & Provider-Specific Caching Support** (#813)
-
-Similarity score: 90%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-**@oyi77** (2026-04-25T12:06:53Z):
-**Not a duplicate of #813.** These are complementary but distinct features:
-
-- **#813 (Prompt Caching)**: Leverages *provider-side* caching (Anthropic `cache_control`, Gemini `cachedContent`, OpenAI `prompt_cache_key`) to reduce costs on **repeated identical prefixes**. The savings come from the provider reusing KV cache across requests.
-
-- **This issue (Prompt Compression)**: Reduces the *token count* of prompts **before** sending them upstream. The savings come from making each request physically smaller — fewer tokens = lower cost, regardless of whether the provider caches anything.
-
-**Key difference**: Caching saves money when the *same* prompt repeats. Compression saves money on *every* request, even unique ones. They're complementary — compression reduces the base token count, caching saves on repetition. In fact, #1591 specifically addresses the interaction between compression and caching (deterministic compression preserves cache hits).
-
-Our full proposal spans 6 issues as a phased rollout:
-- #1586 — Pipeline framework + Lite mode (Phase 1)
-- #1587 — Caveman compression (Phase 2)
-- #1588 — Aggressive compression with history summarization (Phase 3)
-- #1589 — Ultra compression with LLMLingua-style pruning (Phase 4)
-- #1590 — Dashboard UI + Analytics
-- #1591 — MCP tools + provider-aware caching integration (specifically builds on #813's work)
----
-**@diegosouzapw** (2026-04-25T15:02:50Z):
-Thank you for this well-structured, phased proposal, @oyi77! We've reviewed the full 6-issue series (#1586–#1591) and agree these are **not duplicates** — each phase adds a distinct compression module with different algorithms and savings profiles.
-
-The Kilo bot's auto-triage incorrectly flagged these based on surface keyword similarity. We're removing the `kilo-duplicate` labels.
-
-This is a great feature direction that complements our existing proactive context compression (introduced in v3.6.6). We'll track these for a future release cycle. Phase 1 (pipeline framework + Lite mode) is the natural starting point and would integrate cleanly with the existing `contextManager.ts` infrastructure.
-
-Keeping all 6 issues open as a tracked feature series.
----
-
-
-### Participants
-
-- @oyi77
-- @diegosouzapw
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/notfit/1788-1proxy-integration-free-proxy-marketplace-rotator.md

@@ -1,233 +0,0 @@
-# Feature: [Feature] 1proxy Integration - Free Proxy Marketplace & Rotator
-
-> GitHub Issue: #1788 — opened by @oyi77 on 2026-04-29T19:04:21Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-# Feature Request: 1proxy Integration - Free Proxy Marketplace & Rotator
-
-## Summary
-
-Add integration with [1proxy](https://oyi77.is-a.dev/1proxy) - a community-driven free proxy aggregation platform - to provide free proxy fetching, validation, and auto-rotation capabilities in OmniRoute.
-
-## Motivation
-
-### Current Problem
-OmniRoute users currently need to manually configure proxies or use external tools. There's no built-in source for free, validated proxies that can be used for:
-- Bypassing regional restrictions
-- Increasing request diversity
-- Fallback when paid proxies fail
-
-### Solution
-Integrate 1proxy as a "Free Proxy Source" provider that:
-1. Fetches free proxies from 1proxy's validated proxy list
-2. Provides quality-based proxy selection (0-100 score)
-3. Enables auto-rotation when proxies fail
-4. Adds filtering by protocol, country, anonymity level
-
-## Detailed Design
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     OmniRoute                                │
-│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐  │
-│  │   Proxy     │    │   1proxy    │    │    Dashboard    │  │
-│  │  Registry   │◄──►│   Sync      │◄──►│      UI         │  │
-│  └─────────────┘    └─────────────┘    └─────────────────┘  │
-│         ▲                  │                                  │
-│         │           ┌──────┴──────┐                          │
-│         │           │  Rotator     │                          │
-│         │           │   Logic     │                          │
-│         └───────────┴─────────────┘                          │
-└─────────────────────────────────────────────────────────────┘
-                        │
-                        ▼
-           ┌────────────────────────┐
-           │   1proxy API            │
-           │ (1proxy-api.aitradepulse │
-           │        .com)             │
-           └────────────────────────┘
-```
-
-### Components
-
-1. **Data Module** (`src/lib/db/oneproxy.ts`)
-   - Store 1proxy-sourced proxies separately from manually configured ones
-   - Fields: ip, port, protocol, country, anonymity, quality_score, last_validated, status
-
-2. **Sync Service** (`src/lib/oneproxySync.ts`)
-   - Periodic sync from 1proxy API (configurable interval)
-   - Cache last successful fetch for offline resilience
-   - Circuit breaker on API failures
-
-3. **Rotator Logic** (`src/lib/oneproxyRotator.ts`)
-   - Strategies: random, quality-based, sequential
-   - Auto-skip failed proxies
-   - Retry with new proxy on failure
-
-4. **API Routes** (`src/app/api/settings/oneproxy/route.ts`)
-   - `GET /api/settings/oneproxy/proxies` - List synced proxies
-   - `POST /api/settings/oneproxy/sync` - Trigger manual sync
-   - `POST /api/settings/oneproxy/rotate` - Get next proxy
-   - `DELETE /api/settings/oneproxy/proxies/:id` - Remove proxy
-
-5. **Dashboard UI**
-   - New "1proxy" tab in Settings → Proxies
-   - Proxy list with quality indicators
-   - Sync controls and status
-   - Filter controls (protocol, country, quality)
-
-6. **MCP Tools**
-   - `oneproxy_fetch` - Get proxies with filters
-   - `oneproxy_rotate` - Get next available proxy
-   - `oneproxy_stats` - Get sync status and stats
-
-### API Response Mapping
-
-1proxy proxy format → OmniRoute format:
-```
-1proxy: { ip, port, protocol, country, anonymity, quality, latency, google_access }
- OmniRoute: { host: ip, port, port, type: protocol, region: country, status: quality > 50 ? 'active' : 'inactive' }
-```
-
-## Technical Implementation
-
-### File Changes
-
-1. **New Files**:
-   - `src/lib/db/oneproxy.ts` - Database module
-   - `src/lib/oneproxySync.ts` - Sync service
-   - `src/lib/oneproxyRotator.ts` - Rotation logic
-   - `src/app/api/settings/oneproxy/route.ts` - API routes
-   - `src/shared/validation/oneproxySchemas.ts` - Zod schemas
-   - `src/components/dashboard/SettingsProxiesOneproxy.tsx` - UI component
-
-2. **Modified Files**:
-   - `open-sse/mcp-server/index.ts` - Add MCP tools
-   - `src/lib/db/localDb.ts` - Re-export oneproxy module
-   - `src/app/dashboard/settings/proxies/page.tsx` - Add tab
-
-### Database Schema
-
-```sql
-CREATE TABLE oneproxy_proxies (
-  id TEXT PRIMARY KEY,
-  ip TEXT NOT NULL,
-  port INTEGER NOT NULL,
-  protocol TEXT NOT NULL,  -- http, socks4, socks5
-  country TEXT,
-  anonymity TEXT,           -- transparent, anonymous, elite
-  quality_score INTEGER,   -- 0-100
-  latency_ms INTEGER,
-  google_access BOOLEAN,
-  last_validated TEXT,
-  status TEXT DEFAULT 'active',
-  created_at TEXT,
-  updated_at TEXT
-);
-
-CREATE INDEX idx_oneproxy_quality ON oneproxy_proxies(quality_score DESC);
-CREATE INDEX idx_oneproxy_protocol ON oneproxy_proxies(protocol);
-CREATE INDEX idx_oneproxy_country ON oneproxy_proxies(country);
-```
-
-### Environment Variables
-
-```env
-# 1proxy Integration
-ONEPROXY_ENABLED=true                    # Enable/disable integration
-ONEPROXY_API_URL=https://1proxy-api.aitradepulse.com  # API endpoint
-ONEPROXY_SYNC_INTERVAL_MINUTES=60       # Sync interval
-ONEPROXY_MIN_QUALITY_THRESHOLD=50       # Minimum quality to import
-ONEPROXY_MAX_PROXIES=500                 # Maximum proxies to store
-```
-
-### Edge Cases
-
-1. **API Unavailable**: Use cached proxy list, show warning in UI
-2. **Rate Limiting**: Implement exponential backoff, cache aggressively
-3. **All Proxies Dead**: Fall back to manual proxy registry
-4. **Duplicate Proxies**: Deduplicate by ip:port combination
-5. **Memory Pressure**: Limit stored proxies, use LRU eviction
-
-## Acceptance Criteria
-
-- [ ] `GET /api/settings/oneproxy/proxies` returns list of synced proxies
-- [ ] `POST /api/settings/oneproxy/sync` triggers sync and returns count
-- [ ] `POST /api/settings/oneproxy/rotate` returns next available proxy
-- [ ] Dashboard shows 1proxy tab with working UI
-- [ ] MCP tools registered and functional
-- [ ] Graceful degradation when 1proxy API unavailable
-- [ ] Tests pass with >60% coverage
-
-## Benefits
-
-1. **Free Proxy Access**: No additional cost for validated proxies
-2. **Quality Filtering**: Use 1proxy's scoring to select best proxies
-3. **Auto-Rotation**: Automatically cycle through proxies on failure
-4. **Geographic Diversity**: Filter by country for specific use cases
-5. **Community Integration**: Strengthens open-source ecosystem
-
-## Alternatives Considered
-
-1. **GitHub RAW Files**: Simpler but no quality scores, less reliable
-2. **Multiple Proxy Sources**: Could add more later (proxifly, etc.)
-3. **Custom Proxy Pool**: Build own scraper - too much maintenance
-
-## Priority
-
-Medium - Adds valuable free tier capability without affecting existing functionality.
-
----
-
-**Related**: This integration enables the "Free Stack" combo to use proxy rotation for improved reliability.
-
-## 💬 Community Discussion
-
-**@kilo-code-bot** (2026-04-29T19:04:26Z):
-This issue appears to be a duplicate of https://github.com/diegosouzapw/OmniRoute/issues/1787.
-
-> **Feature Proposal: Integrate 1proxy - Free Proxy Marketplace & Rotator** (#1787)
-
-Similarity score: 95%
-
-*This comment was generated by Kilo Auto-Triage.*
----
-
-
-### Participants
-
-- @oyi77
-- @kilo-code-bot
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/notfit/1804-record-provider-failure.md

@@ -1,17 +0,0 @@
-# Feature: Record Provider Failure for Circuit Breaker
-
-> GitHub Issue: #1804 — opened by @matteoantoci on 2026-04-30T07:17:59Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-`recordProviderFailure()` is dead code — circuit breaker never activates.
-
-## 💬 Community Discussion
-None
-
-## 🎯 Refined Feature Description
-
-Integrate `recordProviderFailure()` in `combo.ts` to properly trip circuit breakers on provider failure.
-
-> ℹ️ This issue has already been resolved in a previous PR/commit and exists in `release/v3.7.6`.

_ideia/notfit/1805-codex-missing-input.md

@@ -1,17 +0,0 @@
-# Feature: Codex Missing Input Parameter Fix
-
-> GitHub Issue: #1805 — opened by @artemivchatov on 2026-04-30T07:42:38Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-Codex in Cursor gives `[ERROR] [400]: Missing required parameter: 'input'.`
-
-## 💬 Community Discussion
-Kilo Auto-Triage marked it as a duplicate of 1720, but the author clarified it's a different error message.
-
-## 🎯 Refined Feature Description
-
-Inject a dummy `input` parameter for Codex when it's missing to satisfy schema requirements.
-
-> ℹ️ This issue has already been resolved in a previous PR/commit and exists in `release/v3.7.6`.

_ideia/notfit/1826-add-httpsaihackclubcom-integrations.md

@@ -1,77 +0,0 @@
-# Feature: [Feature] Add https://ai.hackclub.com/ integrations
-
-> GitHub Issue: #1826 — opened by @oyi77 on 2026-04-30T16:25:38Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-This is a free provider access, for teens, might be we could use this as free access of AI
-
-### Proposed Solution
-
-This is a free provider access, for teens, might be we could use this as free access of AI
-
-### Alternatives Considered
-
-_No response_
-
-### Acceptance Criteria
-
-- API route returns 200
-- All Models should be possible to be fetch
-- OpenAI compatible endpoint
-
-### Area
-
-Provider Support
-
-### Related Provider(s)
-
-_No response_
-
-### Additional Context
-
-_No response_
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @oyi77
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Feature needs manual refinement and interpretation to fill logical gaps and outline high-level technical scope.
-
-### What it solves
-
-- TBD
-
-### How it should work (high level)
-
-1. TBD
-2. TBD
-
-### Affected areas
-
-- TBD
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/notfit/2373-third-party-databases.md

@@ -1,62 +0,0 @@
-# Feature: Request support for third-party databases, such as Supabase.
-
-> GitHub Issue: #2373 — opened by @ohyoxo on 2026-05-18T13:58:32Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-I want to deploy this project to a cloud platform like Render, but the free plan doesn't support persistent storage. We can achieve persistence by connecting to a third-party database.
-
-### Proposed Solution
-
-Request support for third-party databases, such as Supabase.
-
-### Alternatives Considered
-
-_No response_
-
-### Acceptance Criteria
-
-Request support for third-party databases, such as Supabase.
-
-### Area
-
-Docker / Deployment
-
-### Related Provider(s)
-
-_No response_
-
-### Additional Context
-
-_No response_
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-No comments yet.
-
-## 🎯 Refined Feature Description
-
-The user wants to connect OmniRoute to a third-party PostgreSQL database like Supabase because cloud platforms like Render don't support persistent storage for SQLite.
-However, OmniRoute is heavily built around `better-sqlite3`, utilizing its synchronous nature for extreme performance, and has over 45+ domain modules directly interacting with it. Migrating to an asynchronous Postgres/Supabase driver would be a massive rewrite of the entire data layer and is outside the core scope of OmniRoute which values simple self-hosted setups.
-
-### What it solves
-- Enables serverless/ephemeral container deployments.
-
-### How it should work (high level)
-- N/A - Too complex/out of scope.
-
-### Affected areas
-- `src/lib/db/*` (45+ files)
-
-## 📎 Attachments & References
-- None
-
-## 🔗 Related Ideas
-- None

_ideia/viable/1718-expose-upstream-error-details-in-client-facing-error-responses.md

@@ -1,99 +0,0 @@
----
-issue: 1718
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:54:56Z
----
-
-# Feature: [Feature] expose upstream error details in client-facing error responses
-
-> GitHub Issue: #1718 — opened by @matteoantoci on 2026-04-28T10:04:16Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Enhancement: Propagate upstream error details to the client
-
-### Problem
-
-When an upstream provider returns an error, the client receives a generic message like:
-
-```
-[400]: Error from provider: Provider returned error
-```
-
-The actual upstream error body is captured internally but never included in the response. This makes it difficult to debug issues — the real error (e.g., `context_length_exceeded`, `invalid_tool_call`, etc.) is hidden behind the generic wrapper.
-
-### Proposed behavior
-
-Add an optional `upstream_details` field to error response bodies alongside the existing `error.message`/`type`/`code` structure. The existing error structure stays unchanged (OpenAI-compatible).
-
-Example response:
-
-```json
-{
-  "error": {
-    "message": "[400]: Error from provider: Provider returned error",
-    "type": "invalid_request_error",
-    "code": "bad_request"
-  },
-  "upstream_details": {
-    "error": { "message": "context_length_exceeded", "type": "invalid_request_error" }
-  }
-}
-```
-
-### Where this helps
-
-- Clients using providers that wrap errors in generic messages (e.g., opencode-go)
-- Debugging 400s from upstream providers where the real error is in the response body
-- Understanding why a specific request failed without checking server-side logs
-
-### Implementation notes
-
-The upstream error body is already parsed and available in the error handling path. The change involves:
-1. Adding an optional parameter to error builder functions (`buildErrorBody`, `errorResponse`, `writeStreamError`, `createErrorResult`)
-2. Passing the parsed upstream body through at the relevant error sites
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @matteoantoci
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Refined and scoped for implementation.
-
-### What it solves
-
-- Debugging upstream errors is difficult because they are hidden behind generic '[400] Error from provider' wrappers.
-
-### How it should work (high level)
-
-1. Modify `buildErrorBody` to accept `upstream_details`.
-2. In `BaseExecutor` or specific handlers, parse the raw upstream response on failure.
-3. Propagate the parsed body to the client response inside `upstream_details`.
-
-### Affected areas
-
-- open-sse/executors/base.ts, open-sse/utils/errors.ts, src/app/api/v1/chat/completions/route.ts
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/viable/1718-expose-upstream-error-details-in-client-facing-error-responses.requirements.md

@@ -1,33 +0,0 @@
-# Requirements: expose upstream error details in client-facing error responses
-
-> Feature Idea: [#1718](./1718-expose-upstream-error-details-in-client-facing-error-responses.md)
-> Research Date: 2026-05-01
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-Expose the upstream error body (e.g. context_length_exceeded) directly in the error response under an `upstream_details` key, without breaking OpenAI compatibility.
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | OmniRoute Source | -     | 2026-05-01   | Internal | High         |
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Modify the central error generation functions (like `buildErrorBody`) to optionally accept an `upstreamDetails` object. Update the request executors to pass the JSON parsed error from the upstream response into this new parameter when a request fails.
-
-### Modified Files
-
-| File | Changes |
-|---|---|
-| `open-sse/utils/errors.ts` | Update `buildErrorBody` to include `upstream_details`. |
-| `open-sse/executors/base.ts` | Extract response body on failure and pass to error builder. |
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Low. A few files changed. No breaking changes.
-- **Breaking changes**: No

_ideia/viable/1731-combo-provider-level-exhaustion-tracking-to-skip-same-provider-targets.md

@@ -1,108 +0,0 @@
----
-issue: 1731
-last_synced_at: 2026-05-19T12:30:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  age_days: 20
-  labels: []
-  state: open
-  classified_at: 2026-05-01T10:54:56Z
----
-
-# Feature: [Feature] (combo): provider-level exhaustion tracking to skip same-provider targets
-
-> GitHub Issue: #1731 — opened by @matteoantoci on 2026-04-28T15:31:43Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-## Problem
-
-When a combo uses the `auto` strategy, targets are reordered by score. If the top-scored targets all share the same provider (e.g., 4 opencode-go models), a single provider quota exhaustion forces the combo to burn through every same-provider target one by one — each cycling through all accounts getting 429 — before reaching a cross-provider fallback (e.g., glm).
-
-Observed behavior: opencode-go quota exhausted → combo spent ~5 minutes cycling through mimo → kimi → qwen → deepseek (all opencode-go), each spending 30-60s on account fallback loops returning 429, before finally trying glm.
-
-The auto-selection algorithm has no awareness that all top-scored targets share the same provider, so cross-provider diversity is zero in the fallback chain.
-
-## Expected Behavior
-
-Before: opencode-go/mimo (429) → opencode-go/kimi (429) → opencode-go/qwen (429) → opencode-go/deepseek (429) → glm/glm-5.1 (success) — **~5 minutes**
-
-After: opencode-go/mimo (429) → skip kimi/qwen/deepseek → glm/glm-5.1 (success) — **~10 seconds**
-
-## Root Cause
-
-Two issues compound:
-
-1. **`isModelAvailable` pre-check doesn't catch quota exhaustion** — when all accounts return 429 "Subscription quota exceeded", the account-level cooldown is only 3-5s (base cooldown for OAuth/API key profiles). By the time the next combo target is evaluated, the cooldown has expired and the account appears available again.
-
-2. **429 is excluded from the provider circuit breaker** — `PROVIDER_FAILURE_ERROR_CODES = {408, 500, 502, 503, 504}` at `accountFallback.ts:59`. Even hundreds of consecutive 429s won't open the provider breaker, so there's no durable cross-request backoff for rate-limited providers.
-
-<details><summary>Log evidence (14:00-14:02 UTC, 2026-04-28)</summary>
-
-```
-14:00:30 Model opencode-go/mimo-v2.5-pro failed, trying next (429)
-14:00:31 Trying model 2/5: opencode-go/kimi-k2.6
-14:01:18 Model opencode-go/kimi-k2.6 failed, trying next (429)
-14:01:18 Trying model 3/5: opencode-go/qwen3.6-plus
-14:02:10 Model opencode-go/qwen3.6-plus succeeded (146978ms, 1 fallbacks)
-```
-
-All accounts returned 429 "Subscription quota exceeded" for each model in sequence. Total cascade: ~2 minutes before a working path was found.
-
-</details>
-
-<details><summary>Additional evidence: overnight harness (2026-04-29)</summary>
-
-```
-03:40:50 429 mimo-v2.5-pro "Subscription quota exceeded"
-03:40:56 429 mimo-v2.5-pro "Subscription quota exceeded"
-03:51:03 429 mimo-v2.5-pro "Subscription quota exceeded"
-03:51:09 429 mimo-v2.5-pro "Subscription quota exceeded"
-03:51:15 429 mimo-v2.5-pro "Subscription quota exceeded"
-...
-06:48:39 429 mimo-v2.5-pro "Subscription quota exceeded"
-```
-
-All 429s are from the same provider. The combo never reached the cross-provider fallback (glm). Every request cycled through all 3 accounts × all opencode-go targets before giving up.
-
-</details>
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @matteoantoci
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Refined and scoped for implementation.
-
-### What it solves
-
-- Combo routing wastes significant time retrying multiple targets from the same provider when the entire provider is rate-limited or quota-exhausted.
-
-### How it should work (high level)
-
-1. Track 429 quota exhaustion errors at the provider level.
-2. In `combo.ts`, before attempting a target, check if its provider is currently marked as exhausted.
-3. If exhausted, skip the target and move to the next provider.
-
-### Affected areas
-
-- open-sse/services/combo.ts, open-sse/services/accountFallback.ts
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/viable/1731-combo-provider-level-exhaustion-tracking-to-skip-same-provider-targets.requirements.md

@@ -1,33 +0,0 @@
-# Requirements: (combo): provider-level exhaustion tracking to skip same-provider targets
-
-> Feature Idea: [#1731](./1731-combo-provider-level-exhaustion-tracking-to-skip-same-provider-targets.md)
-> Research Date: 2026-05-01
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-Implement provider-level 429 exhaustion tracking in the combo router so it skips remaining targets of a provider if a 429 quota exhaustion occurs.
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | OmniRoute Source | -     | 2026-05-01   | Internal | High         |
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Add a temporary exclusion set in `handleComboChat` that tracks providers that have returned a hard 429. Before evaluating the next target in the combo, check if its provider is in the exclusion set and skip it if true.
-
-### Modified Files
-
-| File | Changes |
-|---|---|
-| `open-sse/services/combo.ts` | Add logic to track provider failures and skip matching targets. |
-| `open-sse/services/accountFallback.ts` | Properly bubble up the 429 status. |
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Medium. Needs careful state tracking across the combo loop. No breaking changes.
-- **Breaking changes**: No

_ideia/viable/1764-make-installation-script-detect-termux.md

@@ -1,88 +0,0 @@
-# Feature: [Feature] Make installation script detect termux.
-
-> GitHub Issue: #1764 — opened by @isaacmoren1034-boop on 2026-04-29T08:04:41Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-Due architecture of termux (as in previous cases like with better-sqlite3), wreq-js cannot load native arm64 module of libgcc (even if required library installed like in screenshots)
-
-<img width="1371" height="163" alt="Image" src="https://github.com/user-attachments/assets/da01d29b-bbd7-4315-9127-a9b3516d2d30" />
-
-<img width="2905" height="628" alt="Image" src="https://github.com/user-attachments/assets/54e5ff31-a837-4b5e-b643-aade7a15b0f5" />
-
-### Proposed Solution
-
-In first - I wanted to wreq-js be as additional packet, so users could just skip installation with --no-additional.
-But after some tests I could find out way simple, but buggy solution.
-After just commenting out detection function (and badly rewrite, sorry just noob in programming) in wreq-js.js script (like in screenshot), 
-
-<img width="2852" height="974" alt="Image" src="https://github.com/user-attachments/assets/36df3927-fc25-4cad-af38-fb2e9c43f1e9" />
-
-omniroute finally start out without any problem.
-
-<img width="2906" height="1553" alt="Image" src="https://github.com/user-attachments/assets/b1e8a3ec-fab9-4eb2-ac2a-638e248e4d26" />
-
-### Alternatives Considered
-
-_No response_
-
-### Acceptance Criteria
-
-As temp. solution. just make simple script that would install wreq-js.js script with already comment out detection functions. (like in that crap screenshot).
-It's still a little bit buggy (couldn't catch all and save screenshots, but they're not critical). But OmniRoute still works, provider's oauth and keys files are saving and etc. Maybe if I catch i'll post here.
-
-### Area
-
-Docker / Deployment, Other, Proxy / Routing, Dashboard / UI
-
-### Related Provider(s)
-
-_No response_
-
-### Additional Context
-
-Thank you.
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-*No comments.*
-
-### Participants
-
-- @isaacmoren1034-boop
-
-### Key Points
-
-- Needs detailed analysis
-
-## 🎯 Refined Feature Description
-
-Refined and scoped for implementation.
-
-### What it solves
-
-- OmniRoute fails to start or install properly on Termux because `wreq-js` attempts to load a native `libgcc` arm64 module which is incompatible.
-
-### How it should work (high level)
-
-1. Update the `postinstall` script to check `process.env.PREFIX` for termux.
-2. If termux is detected, gracefully skip or patch the wreq-js installation/loading.
-
-### Affected areas
-
-- scripts/postinstall.mjs, open-sse/executors/wreq.ts
-
-## 📎 Attachments & References
-
-- Check issue body for references
-
-## 🔗 Related Ideas
-
-- None yet

_ideia/viable/1764-make-installation-script-detect-termux.requirements.md

@@ -1,33 +0,0 @@
-# Requirements: Make installation script detect termux
-
-> Feature Idea: [#1764](./1764-make-installation-script-detect-termux.md)
-> Research Date: 2026-05-01
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-Detect termux environments during installation or runtime and gracefully handle the `wreq-js` native module failure, allowing the rest of OmniRoute to function.
-
-## 📚 Reference Implementations
-
-| #   | Repository       | Stars | Last Updated | Approach | Relevance    |
-| --- | ---------------- | ----- | ------------ | -------- | ------------ |
-| 1   | OmniRoute Source | -     | 2026-05-01   | Internal | High         |
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Modify `scripts/postinstall.mjs` or the wreq-js loader logic. If `process.env.PREFIX && process.env.PREFIX.includes('termux')` is true, avoid hard crashing on wreq-js load failures.
-
-### Modified Files
-
-| File | Changes |
-|---|---|
-| `scripts/postinstall.mjs` | Add termux detection and warning. |
-| `open-sse/utils/env.ts` (or similar) | Graceful downgrade. |
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Low. Very localized fix.
-- **Breaking changes**: No

_ideia/viable/1808-auto-combo-context-window-check.md

@@ -1,90 +0,0 @@
----
-issue: 1808
-last_synced_at: 2026-05-19T00:00:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  commenters: 0
-  age_days: 19
-  labels: []
-  state: open
-  classified_at: 2026-05-19T00:00:00Z
----
-
-# Feature: Auto-combo context window pre-filter
-
-> GitHub Issue: #1808 — opened by @matteoantoci on 2026-04-30
-> Status: ✅ VIABLE | Priority: Medium
-
-## 📝 Original Request
-
-### Problem
-
-When auto-combo scores and selects candidates, it doesn't consider whether each model's context window can fit the request. A large request can be routed to a model with a small context window, which immediately fails and wastes a retry slot before falling back.
-
-### Details
-
-- The auto strategy already filters candidates by tool-calling support (when the request includes tools), falling back to the full pool if all are filtered out
-- Token estimation (`estimateTokens()` in `contextManager.ts`) and context limit lookup (`getModelContextLimit()` in `modelCapabilities.ts`) already exist but are only used during context compression after a model is chosen
-- The `estimatedInputTokens` field exists in `routerStrategy.ts` but is never populated
-- When this happens, the user sees extra latency from the failed attempt plus the fallback retry
-
-### Reproduction
-
-1. Configure a combo with models that have different context window sizes (e.g., 16K and 128K)
-2. Send a request with a large prompt that exceeds the smaller model's context window
-3. Observe: the request is routed to the small model, fails with "input too long", then falls back to the larger model
-4. Expected: the small model is excluded from candidates before scoring runs
-
-### Environment
-
-Observed on v3.7.5. The context window information is available but not used during auto-combo candidate selection.
-
-## 💬 Community Discussion
-
-No comments yet.
-
-### Participants
-
-- @matteoantoci — Original requester
-
-### Key Points
-
-- The infrastructure (token estimator + context limit lookup) is already in place — the gap is purely that it isn't wired into the pre-selection filter step.
-- The tool-calling filter is the correct precedent: filter first, fall back to full pool if nothing survives.
-
-## 🎯 Refined Feature Description
-
-Before the auto-combo strategy scores and orders candidates, add a context-window pre-filter that removes any candidate whose known context limit is smaller than the estimated input token count. This mirrors the existing tool-calling filter (lines 1702–1711 of `combo.ts`) and follows the same fallback contract: if all candidates are filtered out, revert to the unfiltered pool to avoid a silent 0-candidate state.
-
-The estimation path already exists in `open-sse/services/contextManager.ts::estimateTokens()`. The limit lookup already exists in `src/lib/modelCapabilities.ts::getModelContextLimit()` (re-exported via `open-sse/services/combo.ts::getModelContextLimitForModelString()`). The `RoutingContext.estimatedInputTokens` field already exists in `routerStrategy.ts` but is never set.
-
-### What it solves
-
-- Eliminates guaranteed-fail routing attempts that consume retry budget and add latency.
-- Makes auto-combo candidate selection aware of an input property (prompt length) it currently ignores entirely.
-- Surfaces the estimated token count to `RouterStrategy` implementations that may want to act on it.
-
-### How it should work (high level)
-
-1. After the tool-calling filter and before `buildAutoCandidates()`, estimate input tokens from the request body using `estimateTokens(JSON.stringify(body.messages))`.
-2. Filter `eligibleTargets` to those whose context limit (via `getModelContextLimitForModelString`) is either unknown (null → include to be safe) or >= estimated input tokens.
-3. If the filtered set is empty, log a warning and revert to the pre-filter set (same pattern as tool-calling fallback).
-4. Pass `estimatedInputTokens` into `RoutingContext` so `RouterStrategy` implementations can also act on it.
-5. Add a unit test covering: (a) small-context candidates are excluded, (b) if all candidates are excluded the fallback restores them, (c) candidates with null context limit are included.
-
-### Affected areas
-
-- `open-sse/services/combo.ts` — add the context-window filter block in the `strategy === "auto"` branch (~line 1712, after tool-calling filter)
-- `open-sse/services/autoCombo/routerStrategy.ts` — `RoutingContext.estimatedInputTokens` is already declared; populate it at the `selectWithStrategy()` call site
-- `open-sse/services/contextManager.ts` — `estimateTokens()` is the token estimator to reuse (no changes needed)
-- `src/lib/modelCapabilities.ts` — `getModelContextLimit()` is the limit lookup to reuse (no changes needed)
-- `tests/unit/combo-context-window-filter.test.ts` — new unit test file
-
-## 📎 Attachments & References
-
-None.
-
-## 🔗 Related Ideas
-
-- `_ideia/1812-auto-combo-output-token-cost.md` — related auto-combo scoring improvement; both involve better use of model metadata during candidate selection.

_ideia/viable/1808-auto-combo-context-window-check.requirements.md

@@ -1,153 +0,0 @@
-# Requirements: 1808 — Auto-combo context window pre-filter
-
-> Status: VIABLE
-> Branch: `release/v3.8.0`
-
----
-
-## 1. Problem Statement
-
-The `auto` combo strategy in `open-sse/services/combo.ts` selects candidates based on a 9-factor scoring function but does not pre-filter candidates whose context window is too small to fit the request. This causes at least one guaranteed-fail attempt before the combo falls back to a larger-context model, adding latency and consuming retry budget.
-
----
-
-## 2. Existing Infrastructure (no new utilities needed)
-
-| Utility | Location | Purpose |
-|---|---|---|
-| `estimateTokens(text)` | `open-sse/services/contextManager.ts:53` | Estimates token count via `Math.ceil(str.length / 4)`. Currently used only after model selection for context compression. |
-| `getModelContextLimit(provider, model)` | `src/lib/modelCapabilities.ts:313` | Returns `contextWindow` from synced capabilities + model specs. Returns `null` when unknown. |
-| `getModelContextLimitForModelString(modelStr)` | `open-sse/services/combo.ts:676` | Parses a `"provider/model"` string and delegates to `getModelContextLimit`. Already used for `context-optimized` and `sortTargetsByContextSize`. |
-| `RoutingContext.estimatedInputTokens` | `open-sse/services/autoCombo/routerStrategy.ts:19` | Field already declared on the interface; never populated. |
-
----
-
-## 3. Where to Add the Check
-
-### 3.1 Primary change: `open-sse/services/combo.ts`
-
-**Location**: inside the `if (strategy === "auto")` block, immediately after the existing tool-calling filter (around line 1711), before the `buildAutoCandidates()` call.
-
-**Pattern to follow** (tool-calling filter at lines 1702–1711):
-
-```ts
-if (requestHasTools) {
-  const filtered = eligibleTargets.filter((target) => supportsToolCalling(target.modelStr));
-  if (filtered.length > 0) {
-    eligibleTargets = filtered;
-  } else {
-    log.warn(
-      "COMBO",
-      "Auto strategy: all candidates filtered by tool-calling policy, falling back to full pool"
-    );
-  }
-}
-```
-
-**New block to add after the tool-calling filter**:
-
-```ts
-// Context-window pre-filter (issue #1808)
-// Estimate input tokens once; exclude candidates whose known context limit is too small.
-const estimatedInputTokens = estimateTokens(JSON.stringify(body?.messages ?? []));
-if (estimatedInputTokens > 0) {
-  const filtered = eligibleTargets.filter((target) => {
-    const limit = getModelContextLimitForModelString(target.modelStr);
-    if (limit === null || limit === undefined) return true; // unknown limit — include to be safe
-    return limit >= estimatedInputTokens;
-  });
-  if (filtered.length > 0) {
-    eligibleTargets = filtered;
-    log.debug(
-      "COMBO",
-      `Auto strategy: context-window filter kept ${filtered.length}/${eligibleTargets.length + (eligibleTargets.length - filtered.length)} candidates (estimated ${estimatedInputTokens} tokens)`
-    );
-  } else {
-    log.warn(
-      "COMBO",
-      `Auto strategy: all candidates filtered by context-window policy (estimated ${estimatedInputTokens} tokens), falling back to full pool`
-    );
-  }
-}
-```
-
-**Required imports** (already imported in combo.ts — verify):
-- `estimateTokens` from `./contextManager.ts` — **not yet imported**, must be added to the import block.
-- `getModelContextLimitForModelString` — already a local function in `combo.ts` (line 676), no import needed.
-
-Import line to add near the top of `combo.ts`:
-
-```ts
-import { estimateTokens } from "./contextManager.ts";
-```
-
-### 3.2 Secondary change: `open-sse/services/combo.ts` — pass `estimatedInputTokens` to `RoutingContext`
-
-At the `selectWithStrategy()` call site (~line 1766), populate the already-declared field:
-
-```ts
-const decision = selectWithStrategy(
-  candidates,
-  { taskType, requestHasTools, lastKnownGoodProvider, estimatedInputTokens },
-  routingStrategy
-);
-```
-
-This makes the token count available to custom `RouterStrategy` implementations without any interface changes.
-
----
-
-## 4. Token Estimation Strategy
-
-`estimateTokens()` uses a 4-chars-per-token heuristic (`Math.ceil(str.length / 4)`). This deliberately over-estimates on average (real BPE rates are closer to 3.5–4 for English prose, lower for code). An over-estimate means:
-
-- **Safe side**: models are more likely to be excluded than included when the input is near the limit.
-- **Not a correctness issue**: the fallback (revert to full pool if all filtered) ensures routing never silently breaks.
-- **No tokenizer dependency**: avoids adding a heavy tokenizer library to the hot request path.
-
-The estimation is applied to `JSON.stringify(body.messages)`, which includes role fields and JSON syntax overhead — consistent with how `contextManager.ts::compressContext()` uses it.
-
----
-
-## 5. Fallback Contract
-
-If all candidates are excluded by the context-window filter:
-1. Log a `warn`-level message with estimated token count.
-2. Restore `eligibleTargets` to the pre-filter set (identical to tool-calling fallback behavior).
-3. Do NOT throw or return an error — this is a best-effort heuristic, not a hard gate.
-
-The upstream provider will still return a "prompt too long" error if the estimation was accurate; the existing fallback/retry machinery handles that case as before.
-
----
-
-## 6. Test Plan
-
-**File**: `tests/unit/combo-context-window-filter.test.ts`
-
-| Test case | Scenario | Expected outcome |
-|---|---|---|
-| TC-1 | 3 candidates with limits [8K, 32K, 128K]; estimated tokens = 20K | Only 32K and 128K candidates survive the filter |
-| TC-2 | All candidates have limit 4K; estimated tokens = 20K | Filter falls back to full 3-candidate pool (fallback contract) |
-| TC-3 | Mix of null-limit and small-limit candidates; large input | Null-limit candidates are always included; small-limit ones excluded |
-| TC-4 | `body.messages` is empty or missing | `estimatedInputTokens = 0` → filter is skipped entirely (no-op) |
-| TC-5 | `estimatedInputTokens` is propagated in `RoutingContext` | Value matches the estimation result |
-
----
-
-## 7. Out of Scope
-
-- Replacing `estimateTokens()`'s 4-char heuristic with a proper BPE tokenizer — tracked separately if needed.
-- Applying this filter to non-`auto` strategies — other strategies (e.g., `context-optimized`, `priority`) have their own ordering/selection logic that already accounts for context size differently.
-- Changing `contextManager.ts` or `modelCapabilities.ts` — both are used as-is.
-
----
-
-## 8. Acceptance Criteria
-
-- [ ] Context-window filter block added in `combo.ts` after the tool-calling filter, using `estimateTokens` + `getModelContextLimitForModelString`.
-- [ ] `estimateTokens` imported in `combo.ts`.
-- [ ] `estimatedInputTokens` populated in the `RoutingContext` passed to `selectWithStrategy()`.
-- [ ] Fallback (revert to full pool) triggers when all candidates are filtered.
-- [ ] Unit tests pass covering TC-1 through TC-5.
-- [ ] No regressions in `npm run test:unit`.
-- [ ] Coverage gate (`npm run test:coverage`) remains >= 75/75/75/70.

_ideia/viable/1812-auto-combo-output-token-cost.md

@@ -1,91 +0,0 @@
----
-issue: 1812
-last_synced_at: 2026-05-19T00:00:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  commenters: 0
-  age_days: 19
-  labels: []
-  state: open
-  classified_at: 2026-05-19T00:00:00Z
----
-
-# Feature: Auto-combo scoring ignores output token cost
-
-> GitHub Issue: #1812 — opened by @matteoantoci on 2026-04-30
-> Status: 📋 Cataloged | Priority: High (correctness bug)
-
-## Original Request
-
-## Problem
-
-In `buildAutoCandidates()` (combo.ts), `costPer1MTokens` is set to only the input token price from `getPricingForModel()`. The output token price is read from pricing data but never used.
-
-## Details
-
-This matters because many reasoning models (e.g., o3, DeepSeek R1) have cheap input tokens but expensive output tokens. Without factoring in output cost, these models appear artificially cheap in the scoring pool.
-
-For example:
-- Model A: $3/M input, $15/M output → scored as $3
-- Model B: $5/M input, $5/M output → scored as $5
-- Router picks Model A as cheaper, but with a typical 40% output ratio, Model A actually costs $3 + $15×0.4 = $9 vs Model B's $5 + $5×0.4 = $7
-
-## Expected Behavior
-
-The cost scoring factor should account for both input and output token pricing. A blended cost using an estimated output/input ratio would give more accurate cost comparisons between models.
-
-## Community Discussion
-
-No comments yet. Issue is self-contained and technically precise.
-
-### Participants
-
-- @matteoantoci — Original requester
-
-### Key Points
-
-- The bug is narrow and well-scoped: only `buildAutoCandidates()` in `combo.ts` is directly affected
-- The fix requires introducing a blended cost formula: `inputPrice * (1 - outputRatio) + outputPrice * outputRatio`
-- A sensible default output ratio is ~0.4 (40% output tokens), matching the example in the issue
-- The `getPricingForModel()` already returns an object with both `pricing.input` and `pricing.output` fields — the output field is simply never read in `buildAutoCandidates()`
-
-## Refined Feature Description
-
-The auto-combo `costInv` scoring factor currently uses only the input token price as a proxy for total request cost. This systematically underestimates the real cost of reasoning-heavy models (o3, DeepSeek R1, Claude 3.7 thinking, etc.) that have cheap input but expensive output tokens, causing the router to incorrectly prefer them in cost-sensitive routing decisions.
-
-The fix introduces a **blended cost** formula:
-
-```
-costPer1MTokens = inputPrice * (1 - OUTPUT_RATIO) + outputPrice * OUTPUT_RATIO
-```
-
-where `OUTPUT_RATIO` is a configurable constant (default `0.4`) representing the expected fraction of tokens that are output. This mirrors how `costCalculator.ts` already handles both `pricing.input` and `pricing.output` fields for actual invoice calculations.
-
-### What it solves
-
-- Reasoning models (o3, DeepSeek R1, Gemini Thinking) are no longer artificially ranked as "cheap" candidates
-- Cost-optimized routing (`auto/cheap`, `cost-saver` mode pack) produces economically accurate selections
-- Parity with `costCalculator.ts` which already uses both input and output pricing for real cost accounting
-
-### How it should work (high level)
-
-1. In `buildAutoCandidates()`, after reading `pricing.input`, also read `pricing.output`
-2. If both values are finite and non-negative, compute blended cost using a constant output ratio (default 0.4)
-3. If only input is available (output is missing/zero), fall back to input-only cost (current behavior) to avoid regressions for providers without output pricing data
-4. Export `OUTPUT_TOKEN_RATIO` as a named constant in `open-sse/config/constants.ts` so it is discoverable and overridable in tests
-5. Add unit tests asserting the blended cost is used when both prices are present, and the fallback when output is absent
-
-### Affected areas
-
-- `open-sse/services/combo.ts` — `buildAutoCandidates()` function (~lines 1218–1227)
-- `open-sse/config/constants.ts` — new `OUTPUT_TOKEN_RATIO` constant
-- `tests/unit/auto-combo-engine.test.ts` or a new `tests/unit/combo-cost-blending.test.ts`
-
-## Attachments & References
-
-- No external attachments.
-
-## Related Ideas
-
-- `_ideia/viable/1731-combo-provider-level-exhaustion-tracking-to-skip-same-provider-targets.md` — also touches combo candidate selection logic; coordinate to avoid merge conflicts in `buildAutoCandidates()`

_ideia/viable/1812-auto-combo-output-token-cost.requirements.md

@@ -1,121 +0,0 @@
-# Requirements: Auto-combo scoring ignores output token cost
-
-> Feature Idea: [#1812](./1812-auto-combo-output-token-cost.md)
-> Research Date: 2026-05-19
-> Verdict: VIABLE
-
-## Research Summary
-
-The bug is confined to `buildAutoCandidates()` in `open-sse/services/combo.ts` (lines 1218–1227). The function calls `getPricingForModel(provider, model)` and reads `pricing?.input` but discards `pricing?.output`. The `getPricingForModel()` return value is a plain `JsonRecord` object; the `costCalculator.ts` at `src/lib/usage/costCalculator.ts` (lines 87–89) already reads both `.input` and `.output` from the same structure for invoice calculations. No library research needed — the fix is a straightforward arithmetic change within existing patterns.
-
-## Reference Implementations
-
-No external references required. Precedent is internal: `src/lib/usage/costCalculator.ts` already applies the correct pattern.
-
-### Key Patterns Found
-
-- `costCalculator.ts` lines 87–89: reads `pricing.input` and `pricing.output` separately, multiplies each by the respective token count
-- `buildAutoCandidates()` lines 1218–1227: reads only `pricing?.input` into `costPer1MTokens`; `pricing?.output` is never accessed
-
-## Proposed Solution Architecture
-
-### Approach
-
-Introduce a module-level constant `OUTPUT_TOKEN_RATIO = 0.4` in `combo.ts` (co-located with the other constants at lines 58–104). In `buildAutoCandidates()`, after reading `inputPrice`, also read `outputPrice = Number(pricing?.output)`. When both are finite and non-negative, compute:
-
-```ts
-costPer1MTokens = inputPrice * (1 - OUTPUT_TOKEN_RATIO) + outputPrice * OUTPUT_TOKEN_RATIO;
-```
-
-When `outputPrice` is absent or invalid, fall back to `inputPrice` alone (preserving current behavior for providers that only publish input pricing).
-
-### New Files
-
-None.
-
-### Modified Files
-
-| File | Changes |
-| --- | --- |
-| `open-sse/services/combo.ts` | Add `OUTPUT_TOKEN_RATIO` constant (~line 98); update `buildAutoCandidates()` cost block (~lines 1218–1227) to read `pricing?.output` and apply blended formula |
-| `tests/unit/auto-combo-engine.test.ts` OR new `tests/unit/combo-cost-blending.test.ts` | Add test cases: (a) both prices present → blended cost, (b) output absent → input-only fallback, (c) reasoning model scenario from issue (o3-like: $3 input / $15 output → blended $9 vs flat-input $3) |
-
-### Database Changes
-
-None.
-
-### API Changes
-
-None. The change is internal to the scoring pipeline.
-
-### UI Changes
-
-None.
-
-## Exact Code Location
-
-**File**: `open-sse/services/combo.ts`
-
-**New constant** (insert after line 98, alongside `MIN_HISTORY_SAMPLES`):
-
-```ts
-// Assumed fraction of tokens that are output when blending input+output prices
-// for auto-combo cost scoring. 0.4 means 40% output, 60% input.
-const OUTPUT_TOKEN_RATIO = 0.4;
-```
-
-**Replace** the cost block in `buildAutoCandidates()` (~lines 1218–1227):
-
-```ts
-// BEFORE (input-only):
-let costPer1MTokens = 1;
-try {
-  const pricing = await getPricingForModel(provider, model);
-  const inputPrice = Number(pricing?.input);
-  if (Number.isFinite(inputPrice) && inputPrice >= 0) {
-    costPer1MTokens = inputPrice;
-  }
-} catch {
-  // keep default cost
-}
-
-// AFTER (blended input + output):
-let costPer1MTokens = 1;
-try {
-  const pricing = await getPricingForModel(provider, model);
-  const inputPrice = Number(pricing?.input);
-  const outputPrice = Number(pricing?.output);
-  if (Number.isFinite(inputPrice) && inputPrice >= 0) {
-    if (Number.isFinite(outputPrice) && outputPrice >= 0) {
-      costPer1MTokens =
-        inputPrice * (1 - OUTPUT_TOKEN_RATIO) + outputPrice * OUTPUT_TOKEN_RATIO;
-    } else {
-      costPer1MTokens = inputPrice;
-    }
-  }
-} catch {
-  // keep default cost
-}
-```
-
-## Implementation Effort
-
-- **Estimated complexity**: Low
-- **Estimated files changed**: ~2 (combo.ts + one test file)
-- **Dependencies needed**: none
-- **Breaking changes**: No — blended cost is only more accurate; existing behavior is preserved when `pricing.output` is absent
-- **i18n impact**: 0 new translation keys
-- **Test coverage needed**: unit tests for blended vs fallback behavior; scenario matching the issue's numerical example
-
-## Open Questions
-
-1. Should `OUTPUT_TOKEN_RATIO` be configurable per-combo or globally? Currently a module constant is sufficient. A per-combo override could be a follow-up.
-2. Should reasoning tokens (e.g., `pricing.reasoning`) also be factored in for models that price them separately? Out of scope for this fix; can be tracked separately.
-3. The `virtualFactory.ts` hardcodes `costPer1MTokens: 0` for all virtual auto-combo candidates (line 139), which bypasses cost scoring entirely for the `auto/` prefix path. That is a separate known limitation and should not be changed in this fix.
-
-## External References
-
-- `open-sse/services/combo.ts` lines 58–104 (constants), 1191–1282 (`buildAutoCandidates`)
-- `src/lib/usage/costCalculator.ts` lines 87–89 (reference pattern for input+output pricing)
-- `src/lib/db/settings.ts` lines 273–323 (`getPricingForModel` return shape: `JsonRecord` with `.input` and `.output` keys)
-- GitHub issue: https://github.com/diegosouzapw/OmniRoute/issues/1812

_ideia/viable/1881-generic-api-key-rotation-cli.md

@@ -1,95 +0,0 @@
----
-issue: 1881
-last_synced_at: 2026-05-19T00:00:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  commenters: 0
-  age_days: 17
-  labels: []
-  state: open
-  classified_at: 2026-05-19T00:00:00Z
----
-
-# Feature: Generic API key rotation CLI command
-
-> GitHub Issue: #1881 — opened by @apoapostolov on 2026-05-02
-> Status: Cataloged | Priority: TBD
-
-## Original Request
-
-## What
-
-A CLI command to rotate API keys across all configured providers:
-
-- `omniroute keys rotate` — Rotate all expired/soon-to-expire keys
-- `omniroute keys rotate <provider>` — Rotate keys for a specific provider
-- `omniroute keys status` — Show key health (age, expiry, last used)
-
-## Why
-
-- `api/settings/oneproxy/rotate` and MCP tool `omniroute_oneproxy_rotate` exist, but only for the OneProxy feature.
-- Many providers (especially Google Cloud, Azure, AWS) use rotating/temporary credentials. There's no generic rotation mechanism.
-- The `token-health` route and `api/providers/expiration` route already track expiration — a CLI command would make this actionable.
-- Key lifecycle management is a security best practice for any proxy handling multiple API keys.
-
-## Implementation
-
-- Extend the existing `api/keys/` and `api/providers/expiration` logic.
-- For OAuth-based providers (Google), trigger the OAuth flow or prompt for a refresh token.
-- Support env var fallback: `omniroute keys rotate OpenRouter --from-env OPENROUTER_API_KEY`.
-
-## Community Discussion
-
-No comments at time of cataloging.
-
-### Participants
-
-- @apoapostolov — Original requester
-
-### Key Points
-
-- Request is scoped exclusively to upstream provider API keys/credentials (not OmniRoute client registered keys)
-- Current `keys rotate <id>` in `bin/cli/commands/keys.mjs` rotates OmniRoute-issued client API keys via `/api/v1/registered-keys/:id/rotate` — a fundamentally different operation
-- The author correctly identifies that OneProxy rotation exists in isolation and desires a generic equivalent
-- The `--from-env` flag for sourcing the new key from an environment variable is a clean pipeline-friendly addition
-
-## Refined Feature Description
-
-This issue requests a **provider credential rotation** facility — the ability to update an upstream API key (or refresh an OAuth token) for a configured provider connection, from the command line. This is distinct from the existing `omniroute keys rotate` which rotates OmniRoute-issued client keys.
-
-OmniRoute currently stores provider credentials (API keys, OAuth tokens, refresh tokens) as encrypted `provider_connections` rows. When a provider key expires or needs rolling (e.g., a key was compromised, a free-tier key is being replaced, a cloud provider's short-lived token expired), the only current path is the dashboard UI or direct SQLite manipulation.
-
-### What it solves
-
-- No CLI path to update expired or compromised upstream provider API keys
-- Operators running headless/server deployments cannot rotate provider keys without a GUI
-- No aggregate health view showing key age, last-used, and expiry across all providers at once
-- CI/CD pipelines cannot automate key rotation from env vars or secrets managers
-
-### How it should work (high level)
-
-1. `omniroute providers rotate <connectionId|providerName> --new-key <key>` — replace the API key for one provider connection in the DB (with `--yes` to skip confirmation)
-2. `omniroute providers rotate <connectionId|providerName> --from-env <VAR>` — read new key from env var (CI-friendly, avoids key in shell history)
-3. `omniroute providers rotate --all --dry-run` — report which connections have expired/soon-to-expire keys; update nothing yet (uses `providerExpiration` domain)
-4. `omniroute providers status` — tabular view of all provider connections with: key age, expiry date (from `providerExpiration`), `testStatus`, `rateLimitedUntil`, last-used timestamp
-5. For OAuth-based providers: `omniroute providers rotate <id> --oauth` triggers the existing OAuth re-auth flow (links to the browser or prints auth URL)
-
-### Affected areas
-
-- `bin/cli/commands/providers.mjs` — new `rotate` and `status` subcommands
-- `bin/cli/provider-store.mjs` — `updateProviderApiKey()` helper (writes encrypted key)
-- `src/domain/providerExpiration.ts` — already tracks expiry; needs no changes, just consumed via API
-- `src/app/api/providers/expiration/route.ts` — consumed by CLI `providers status`
-- `src/app/api/providers/[id]/route.ts` — existing PATCH endpoint can accept the key update
-- `open-sse/services/auth.ts` — `clearAccountError()` should be called after successful rotation to lift any cooldown
-- No new DB schema needed — `provider_connections.apiKey` already holds the encrypted key
-
-## Attachments & References
-
-No images or mockups in the original issue.
-
-## Related Ideas
-
-- Relates to `_ideia/viable/1733-combo-provider-level-exhaustion-tracking...` (both touch provider connection health state)
-- See `docs/architecture/RESILIENCE_GUIDE.md` — connection cooldown section — rotation should call `clearAccountError()` post-rotate to reset `rateLimitedUntil` and `backoffLevel`

_ideia/viable/1881-generic-api-key-rotation-cli.requirements.md

@@ -1,115 +0,0 @@
-# Requirements: Generic API key rotation CLI command
-
-> Feature Idea: [#1881](./1881-generic-api-key-rotation-cli.md)
-> Research Date: 2026-05-19
-> Verdict: VIABLE
-
-## Research Summary
-
-The request is for upstream provider credential rotation via CLI. Key findings from codebase analysis:
-
-1. **The existing `keys rotate` command is NOT the target** — `bin/cli/commands/keys.mjs::runKeysRotateCommand` calls `/api/v1/registered-keys/:id/rotate`, which rotates OmniRoute-issued client API keys. The author wants to rotate upstream provider API keys stored in `provider_connections`.
-
-2. **The `providers.mjs` command already has the right shape** — it registers `providers available`, `providers list`, `providers test`, `providers test-all`, `providers validate`, and `providers metrics`. Two new subcommands fit cleanly: `providers rotate` and `providers status`.
-
-3. **Backend endpoints already exist** — `PATCH /api/providers/:id` can update connection fields including `apiKey`. The `provider_store.mjs` helper `upsertApiKeyProviderConnection()` writes encrypted keys. The PATCH path just needs to be confirmed to accept `apiKey` field updates.
-
-4. **Expiration tracking is in-place** — `src/domain/providerExpiration.ts` + `GET /api/providers/expiration` returns `{ list[], summary }` with `status: active|expiring_soon|expired|unknown` per connection. `providers status` can consume this directly.
-
-5. **Cooldown reset hook** — `open-sse/services/auth.ts::clearAccountError()` must be called (or triggered via an API call that clears it) after successful rotation so the connection exits cooldown immediately.
-
-6. **OAuth providers** — `token-health` endpoint tracks OAuth connection health. For OAuth providers, rotation means re-running the OAuth flow. The CLI already has `omniroute oauth` commands. A `--oauth` flag on `providers rotate` should delegate to the existing oauth flow.
-
-7. **`--from-env` flag** — no precedent in CLI today, but it is a safe, common CLI pattern. The key is read from `process.env[VAR]` and never logged/echoed.
-
-## Reference Implementations
-
-| # | Repository | Stars | Last Updated | Approach | Relevance |
-|---|-----------|-------|-------------|---------|-----------|
-| 1 | [hashicorp/vault](https://github.com/hashicorp/vault) | 32k+ | 2026 | Dynamic secrets, lease renewal via CLI (`vault lease renew`) | High — gold standard for credential lifecycle |
-| 2 | [aws/aws-cli](https://github.com/aws/aws-cli) | 15k+ | 2026 | `aws iam update-access-key` + `aws configure set` for rotation | High — env var sourcing pattern |
-| 3 | [cli/cli (gh)](https://github.com/cli/cli) | 38k+ | 2026 | `gh auth refresh` for OAuth token rotation | High — OAuth re-auth CLI pattern |
-| 4 | [dopplerhq/cli](https://github.com/DopplerHQ/cli) | 400+ | 2025 | `doppler secrets set KEY=VALUE` with env-var sourcing | Medium — secrets manager CLI UX |
-
-### Key Patterns Found
-
-- **Confirmation gate**: `--yes` flag to skip interactive confirmation (already used in `keys remove`, `keys revoke`)
-- **Env-var sourcing**: `--from-env VAR` reads `process.env[VAR]`; guard against empty string; never log the value
-- **Dry-run / status-only**: `--dry-run` flag inspects expiry without writing; surface `providerExpiration.status` per connection
-- **Grace-period / zero-downtime**: brief overlap period where old key is still accepted; out of scope for CLI since provider-side, but `--grace-period` flag in existing `keys rotate` sets a precedent
-- **Post-rotate validation**: after writing the new key, immediately call the test endpoint (`providers test <id>`) to verify the new key works; report pass/fail
-
-## Proposed Solution Architecture
-
-### Approach
-
-Add two new subcommands to the existing `providers` command in `bin/cli/commands/providers.mjs`:
-
-1. `omniroute providers rotate <connectionId> [--new-key <key>] [--from-env <VAR>] [--oauth] [--yes] [--skip-test]`
-2. `omniroute providers status [--provider <name>] [--output table|json]`
-
-Both commands follow the dual-path pattern already established in `keys.mjs`: try server API first (if server is up), fall back to direct SQLite write if offline (for `rotate` only — `status` requires the server for expiration data).
-
-The `rotate` command flow:
-1. Resolve connection by ID or provider name (partial match allowed, error if ambiguous)
-2. Source new key: `--new-key` > `--from-env VAR` > interactive prompt (unless `--yes`)
-3. Confirm unless `--yes`
-4. `PATCH /api/providers/:id` with `{ apiKey: newKey }` — or direct `upsertApiKeyProviderConnection` if offline
-5. POST to clear account error / cooldown (call `/api/providers/:id/clear-error` or the equivalent)
-6. Unless `--skip-test`: run `providers test <id>` and report pass/fail
-7. Report result
-
-### New Files
-
-| File | Purpose |
-|------|---------|
-| No new files required | All changes fit in existing modules |
-
-### Modified Files
-
-| File | Changes |
-|------|---------|
-| `bin/cli/commands/providers.mjs` | Add `providers rotate` and `providers status` subcommands + action implementations |
-| `bin/cli/provider-store.mjs` | Add `updateProviderApiKey(db, connectionId, newEncryptedKey)` helper if not already present; reuse `upsertApiKeyProviderConnection` |
-| `bin/cli/locales/en.json` (or equivalent) | New i18n keys for new subcommand output strings |
-
-### Database Changes
-
-None. `provider_connections.apiKey` already stores encrypted API keys; the PATCH route and existing store helpers handle encryption.
-
-### API Changes
-
-- Verify `PATCH /api/providers/:id` accepts `apiKey` field — if not, a minimal addition to the handler is needed
-- Optional: `POST /api/providers/:id/clear-error` (may already exist; verify via `src/app/api/providers/[id]/route.ts`)
-
-### UI Changes
-
-None required.
-
-## Implementation Effort
-
-- **Estimated complexity**: Low-Medium
-- **Estimated files changed**: ~3 (providers.mjs, provider-store.mjs, locales)
-- **Dependencies needed**: None
-- **Breaking changes**: No — additive only
-- **i18n impact**: ~12 new translation keys (rotate prompt, confirm, success, error, status table headers, dry-run output)
-- **Test coverage needed**: Unit tests for `runProvidersRotateCommand` and `runProvidersStatusCommand`; mock `apiFetch` + `openOmniRouteDb`; assert `--from-env` reads from `process.env`; assert `--yes` skips confirmation; assert cooldown-clear call is made
-
-## Open Questions
-
-1. Does `PATCH /api/providers/:id` currently accept `apiKey` as a writable field? If not, it needs a targeted addition (with the usual Zod validation + encryption).
-2. Is there a `POST /api/providers/:id/clear-error` route, or does cooldown clear happen implicitly on next successful request? If the latter, no explicit clear-call is needed from the CLI.
-3. Should `providers status` also surface `testStatus` and `rateLimitedUntil` (from `provider_connections`) in addition to expiration data? Recommended yes — gives operators a single-command health overview.
-4. For `--oauth`, should `providers rotate` trigger the full browser-based OAuth flow inline, or should it just print the auth URL and instruct the user to run `omniroute oauth <provider>`? The latter is safer and avoids duplicating OAuth flow logic.
-5. `--from-env` with an unset variable: should it error loudly (recommended) or fall through to interactive prompt?
-
-## External References
-
-- `src/domain/providerExpiration.ts` — in-memory expiration store, consumed via `/api/providers/expiration`
-- `src/app/api/providers/expiration/route.ts` — GET endpoint returning expiration list + summary
-- `src/app/api/token-health/route.ts` — OAuth token health aggregate
-- `open-sse/services/auth.ts` — `clearAccountError()` and `markAccountUnavailable()`
-- `bin/cli/commands/providers.mjs` — existing provider subcommand structure
-- `bin/cli/commands/keys.mjs` — precedent for `--yes`, `--from-env` (not yet), `rotate` UX
-- `bin/cli/CONVENTIONS.md` — normative CLI conventions (must follow)
-- `docs/architecture/RESILIENCE_GUIDE.md` — connection cooldown section

_ideia/viable/1909-t3-chat-web-provider.md

@@ -1,117 +0,0 @@
----
-issue: 1909
-last_synced_at: 2026-05-19T00:00:00Z
-last_synced_comment_id: 0
-snapshot:
-  thumbs: 0
-  commenters: 0
-  age_days: 16
-  labels: ["provider-support"]
-  state: open
-  classified_at: 2026-05-19T00:00:00Z
----
-
-# Feature: Add t3.chat web provider
-
-> GitHub Issue: #1909 — opened by @aartzz on 2026-05-03T09:19:28Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-OmniRoute currently supports API-key-based providers like OpenRouter and Ollama, but lacks integration for [t3.chat](https://t3.chat) — a popular multi-model AI platform by Theo Browne that provides access to 50+ models (Claude, GPT-4o/5, Gemini, DeepSeek, Grok, Llama, etc.) under a single $8/month subscription. Users who rely on t3.chat for cost-effective model access have no way to route those requests through OmniRoute's unified proxy, forcing them to manage a separate client and authentication outside of their existing infrastructure.
-
-### Proposed Solution
-
-Add [t3.chat](https://t3.chat) as a new provider in OmniRoute. Due to the platform's architecture, this would likely require cookie/session-based authentication rather than a standard API key. Key implementation points:
-- Authenticate using convex-session-id and browser cookies _(similar to how unofficial clients like [T3Router](https://github.com/vibheksoni/t3router) and [t3-python-client](https://github.com/thethereza/t3-python-client) operate)_.
-- Support chat completions for major models.
-- Support model discovery/listing.
-- Handle session refresh automatically where possible.
-
-### Alternatives Considered
-
-- Using third-party reverse-engineered clients directly — this bypasses OmniRoute's routing, load balancing, logging, and rate-limiting features.
-- Using individual official APIs for each model provider — this requires managing multiple API keys and subscriptions, which defeats the cost-efficiency of [t3.chat](https://t3.chat).
-
-### Acceptance Criteria
-
-- [t3.chat](https://t3.chat) appears as a selectable provider in the OmniRoute dashboard.
-- Chat completion requests can be proxied to [t3.chat](https://t3.chat) successfully.
-- Available models are discoverable and listed.
-- Cookie-based authentication is configurable in provider settings.
-- Existing providers and integrations remain unaffected.
-
-### Area
-
-Provider Support
-
-### Related Provider(s)
-
-t3.chat
-
-### Additional Context
-
-- Pricing: $8/month Pro subscription _(free tier with limited models also exists)_.
-- Authentication: No official public API key; uses browser cookies + `convex-session-id`.
-- Reference implementations: [T3Router (Rust)](https://github.com/vibheksoni/t3router), [t3-python-client](https://github.com/thethereza/t3-python-client).
-
-### Expected Test Plan
-
-- Unit tests for the [t3.chat](https://t3.chat) provider adapter.
-- Integration tests for chat completion routing.
-- Verify model discovery endpoint.
-- Ensure no regressions in existing provider tests.
-
-## 💬 Community Discussion
-
-No comments yet.
-
-### Participants
-
-- @aartzz — Original requester
-
-### Key Points
-
-- No community discussion recorded at this time.
-
-## 🎯 Refined Feature Description
-
-t3.chat is a multi-model AI chat platform built by Theo Browne (of T3 Stack fame) using Convex as its real-time backend. It exposes 50+ models (Claude, GPT, Gemini, DeepSeek, Grok, Llama, etc.) under a $8/month Pro subscription with a limited free tier. There is no official public API — the platform operates via browser session authentication using `cookies` (including a `convex-session-id`) extracted from an authenticated browser session, which is the same mechanism employed by the reference implementations T3Router (Rust) and t3-python-client (Python).
-
-The t3.chat backend is Convex-powered. Convex typically uses a WebSocket-based sync protocol; however, t3.chat also performs standard HTTP fetch calls for chat actions. Research confirms the authentication flow requires two credentials: full browser cookie string (from t3.chat) and the `convex-session-id` value. The unofficial Rust client (T3Router) shows model IDs use simple lower-case strings (e.g. `claude-3.7`, `gpt-4o`, `gemini-2.5-pro`). Streaming support is not yet confirmed in reference implementations — the Rust library notes "streaming planned," suggesting the current HTTP action may return a full response or use Convex's persistent text streaming component.
-
-### What it solves
-
-- Gives OmniRoute users access to 50+ models via a single $8/month t3.chat subscription, avoiding per-model API key overhead.
-- Brings t3.chat requests into OmniRoute's routing, fallback, rate-limiting, and logging pipeline.
-- Complements existing web-session providers (deepseek-web, claude-web, copilot-web, chatgpt-web) with a multi-model aggregator.
-
-### How it should work (high level)
-
-1. User configures a `t3-web` connection by providing browser cookies + `convex-session-id` (extracted from browser DevTools — same UX as other web providers).
-2. On each request, `T3ChatWebExecutor` sends an authenticated HTTP POST to t3.chat's Convex action endpoint with the model name and message history (mapped from OpenAI format).
-3. Response (likely Convex polling or HTTP streaming action) is collected and translated back to OpenAI SSE or JSON format.
-4. Errors (expired session: 401/403, rate limit: 429) are mapped to standard OmniRoute error codes and connection cooldown.
-5. Model list is statically registered in `providerRegistry.ts` (50+ model entries) since no public model-discovery endpoint exists.
-
-### Affected areas
-
-- `open-sse/executors/t3-chat-web.ts` — new executor (cookie auth + Convex action dispatch + SSE/JSON translation)
-- `open-sse/executors/index.ts` — register executor
-- `open-sse/config/providerRegistry.ts` — register provider + model list
-- `src/shared/constants/providers.ts` — add `t3-web` to provider enum
-- `tests/unit/t3-chat-web.test.ts` — unit tests
-
-## 📎 Attachments & References
-
-- [T3Router (Rust) — vibheksoni/t3router](https://github.com/vibheksoni/t3router)
-- [t3-python-client — thethereza/t3-python-client](https://github.com/thethereza/t3-python-client)
-- [t3.chat FAQ](https://t3.chat/faq)
-- [Convex auth docs](https://docs.convex.dev/auth)
-- [Convex persistent text streaming](https://github.com/get-convex/persistent-text-streaming)
-
-## 🔗 Related Ideas
-
-- Existing web providers: deepseek-web, claude-web, copilot-web, chatgpt-web — same cookie-auth pattern

_ideia/viable/1909-t3-chat-web-provider.requirements.md

@@ -1,101 +0,0 @@
-# Requirements: Add t3.chat web provider
-
-> Feature Idea: [#1909](./1909-t3-chat-web-provider.md)
-> Research Date: 2026-05-19
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-t3.chat is a multi-model AI chat platform (Theo Browne / T3 Stack) built on Convex. It exposes 50+ models under a $8/month Pro subscription. There is no official API — authentication relies on browser session cookies plus a `convex-session-id` value extracted from browser DevTools. Two reference implementations exist: T3Router (Rust, `vibheksoni/t3router`) and t3-python-client (Python, `thethereza/t3-python-client`). Both confirm the two-credential pattern. Model IDs are simple lowercase strings (`claude-3.7`, `gpt-4o`, `gemini-2.5-pro`, etc.).
-
-The t3.chat backend uses Convex's WebSocket sync protocol but chat submissions go through Convex HTTP actions. Convex's persistent-text-streaming pattern is likely used for response delivery. Streaming support is not yet confirmed in the reference implementations (T3Router notes "streaming planned"), so the initial executor may need to poll or collect a full response from the Convex HTTP action.
-
-**ToS risk**: t3.chat's terms of service could not be fetched during research (rate-limited). Reference implementations include explicit disclaimers that the tool is a technical demonstration, not endorsed by t3.chat, and accounts may be actioned. This is consistent with other web providers in OmniRoute (claude-web, chatgpt-web) which carry the same inherent ToS ambiguity. OmniRoute should surface this risk in UI documentation but proceed with the implementation per the established web-provider precedent.
-
-## 📚 Reference Implementations
-
-| # | Repository | Stars | Last Updated | Approach | Relevance |
-|---|------------|-------|--------------|----------|-----------|
-| 1 | [vibheksoni/t3router](https://github.com/vibheksoni/t3router) | ~N/A | 2025 | Rust library; cookie + convex-session-id → HTTP action → full response | High |
-| 2 | [thethereza/t3-python-client](https://github.com/thethereza/t3-python-client) | ~N/A | 2025 | Python library; same cookie + session ID; bookmarklet extraction UX | High |
-| 3 | [get-convex/persistent-text-streaming](https://github.com/get-convex/persistent-text-streaming) | ~N/A | 2025 | Convex component for HTTP-streaming text while persisting server-side | Medium |
-
-### Key Patterns Found
-
-- **Credential extraction**: Both clients use a bookmarklet or manual DevTools copy to extract `document.cookie` + `convex-session-id` value from an authenticated t3.chat browser tab. OmniRoute should provide the same instructions in provider setup documentation.
-- **Auth headers**: HTTP requests carry `Cookie: <full_cookie_string>` and a custom header (or request body field) for `convex-session-id`. The exact header name (`convex-session-id` or body field) needs to be confirmed against network traffic capture.
-- **Model IDs**: Simple lowercase strings, e.g. `claude-3.7`, `gpt-4o`, `gemini-2.5-pro`, `deepseek-r1`, `llama-3.3-70b`. Must be registered statically; no public discovery endpoint.
-- **Streaming**: Not yet confirmed. Likely Convex HTTP action with persistent text streaming (chunked transfer encoding). Implementation should attempt streaming, fall back to polling if not available.
-- **DeepSeek-web precedent**: The `deepseek-web` executor (which handles a custom non-OpenAI JSON streaming protocol) is the closest structural analog. `claude-web` provides a more complex session-management example. `t3-chat-web` will be simpler than both since there is no PoW challenge and no sub-org routing.
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Create a new `T3ChatWebExecutor` that authenticates via browser cookies + convex-session-id, submits chat requests to t3.chat's Convex HTTP action endpoint, and transforms the response (streaming chunks or full JSON) back to OpenAI SSE format. Model list is statically registered. The executor follows the established web-provider pattern in OmniRoute.
-
-The Convex HTTP action endpoint is not yet confirmed from public sources. It likely follows the pattern:
-```
-POST https://t3.chat/api/chat  (or Convex deployment action URL)
-Content-Type: application/json
-Cookie: <full_browser_cookies>
-convex-session-id: "<session_id>"
-
-{ "model": "claude-3.7", "messages": [...], "stream": true }
-```
-
-The implementer will need to capture a real network request via browser DevTools to confirm the exact endpoint and request/response format before coding the executor.
-
-### New Files
-
-| File | Purpose |
-|------|---------|
-| `open-sse/executors/t3-chat-web.ts` | New executor: cookie auth, Convex action dispatch, SSE/JSON response translation to OpenAI format |
-| `tests/unit/t3-chat-web.test.ts` | Unit tests: credential validation, model mapping, SSE transform, error handling |
-
-### Modified Files
-
-| File | Changes |
-|------|---------|
-| `open-sse/executors/index.ts` | Import and register `T3ChatWebExecutor` under key `"t3-web"` |
-| `open-sse/config/providerRegistry.ts` | Add `t3-web` provider entry with 50+ model definitions |
-| `src/shared/constants/providers.ts` | Add `"t3-web"` to the provider Zod enum |
-
-### Database Changes
-
-- None. Credentials stored as connection `credentials` JSON with `cookies` and `convexSessionId` fields (same pattern as other web providers).
-
-### API Changes
-
-- None. The new provider plugs into the existing executor dispatch layer transparently.
-
-### UI Changes
-
-- Provider setup page: add connection instructions explaining how to extract `cookies` + `convex-session-id` from browser DevTools (consistent with deepseek-web and claude-web setup instructions).
-
-## ⚙️ Implementation Effort
-
-- **Estimated complexity**: Medium
-- **Estimated files changed**: ~5
-- **Dependencies needed**: None (uses native `fetch`, same as all other web executors)
-- **Breaking changes**: No
-- **i18n impact**: ~2-4 new provider label keys
-- **Test coverage needed**: Credential validation, request construction, SSE stream transform (mocked), error code mapping (401/403/429)
-
-## ⚠️ Open Questions
-
-1. **Exact Convex HTTP action endpoint** — needs to be confirmed via browser DevTools network capture on a real t3.chat session. The T3Router Rust source (not fully accessible) may contain the URL; the implementer should read the actual source code before writing the executor.
-2. **Streaming availability** — does t3.chat's Convex action return streaming chunks or a single full response? If non-streaming, the executor can return a plain JSON response, but streaming is strongly preferred for UX parity with other providers.
-3. **Free tier models** — the issue states a free tier exists with limited models. The provider registry should note which models require Pro; credential validation could attempt a lightweight request to detect account tier.
-4. **Session refresh** — unlike deepseek-web (which has `ds_session_id` as a stable cookie), Convex session IDs may expire. The issue requests auto-refresh; this may require a separate `t3-chat-web-with-auto-refresh.ts` variant (consistent with `deepseek-web-with-auto-refresh.ts`).
-5. **ToS compliance** — same ambiguity as all other web providers. Should be documented in provider description but not block implementation per established OmniRoute precedent.
-
-## 🔗 External References
-
-- [T3Router (Rust)](https://github.com/vibheksoni/t3router)
-- [t3-python-client (Python)](https://github.com/thethereza/t3-python-client)
-- [Convex HTTP streaming pattern](https://stack.convex.dev/ai-chat-with-http-streaming)
-- [Convex persistent-text-streaming component](https://github.com/get-convex/persistent-text-streaming)
-- [t3.chat FAQ](https://t3.chat/faq)
-- [deepseek-web executor (reference)](open-sse/executors/deepseek-web.ts)
-- [copilot-web executor (reference)](open-sse/executors/copilot-web.ts)

_ideia/viable/1980-llama-cpp-local-provider.md

@@ -1,102 +0,0 @@
----
-issue: 1980
-last_synced_at: 2026-05-19T12:26:25Z
-last_synced_comment_id: IC_kwDORPf6ys8AAAABB05zyA
-snapshot:
-  thumbs: 0
-  commenters: 3
-  age_days: 14
-  labels: [enhancement]
-  state: open
-  classified_at: 2026-05-19T12:26:25Z
----
-
-# Feature: [Feature] Please add llama.cpp to Local Providers
-
-> GitHub Issue: #1980 — opened by @woutercoppens on 2026-05-05
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-Current local providers are: LM Studio, vLLM, Lemonade Server, Llamafile, Nvidia Triton, Docker Model Runner, XInterference, oobabooga, SD WebUI, ComfyUI
-
-### Proposed Solution
-
-Please add support for Please add llama.cpp
-
-### Alternatives Considered
-
-_No response_
-
-### Acceptance Criteria
-
-Llama.cpp is added to local providers
-
-### Area
-
-Provider Support
-
-### Related Provider(s)
-
-_No response_
-
-### Additional Context
-
-_No response_
-
-### Expected Test Plan
-
-_No response_
-
-## 💬 Community Discussion
-
-Three participants: @woutercoppens (OP), @hartmark (contributor), @soyelmismo, @rshinde-asapp.
-
-- **@hartmark** (2026-05-08): Pointed out that llama.cpp supports OpenAI style, so users can just add it as an "OpenAI compatible" provider and suffix `/v1` on the URL — suggesting the feature is low-effort and already partially achievable via the generic OpenAI-compatible provider path.
-- **@soyelmismo** (2026-05-11): Reported that the workaround does NOT work for them — OmniRoute's dashboard shows errors finding the models endpoint and chat completions endpoint despite correct configuration. They confirmed testing from inside the Docker container that the llama-server is reachable.
-- **@rshinde-asapp** (2026-05-11): Suggested setting `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` in `.env` and restarting, as this enables private/local URLs for OpenAI-style providers.
-
-Key takeaway: there is both user demand for a first-class named provider entry and a real usability gap — users struggle to configure llama.cpp as a generic OpenAI-compatible provider due to the `ALLOW_PRIVATE_PROVIDER_URLS` requirement not being obvious.
-
-## 🎯 Refined Feature Description
-
-Add `llama-cpp` (id: `llama-cpp`, alias: `llamacpp`) as a named local provider in OmniRoute, following the exact same pattern as `llamafile`, `lm-studio`, `vllm`, and the other self-hosted chat providers. The llama.cpp project (`ggml-org/llama.cpp`) ships a built-in HTTP server (`llama-server`) that exposes a fully OpenAI-compatible API at `/v1/chat/completions`, `/v1/models`, and `/v1/embeddings` by default on port `8080`.
-
-The benefit of a named provider over the generic "OpenAI compatible" workaround is:
-1. Auto-discovery in the dashboard without manual URL configuration.
-2. Clear `authHint` directing users to the correct default endpoint.
-3. No need to set `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` manually.
-4. `passthroughModels: true` so users can type any model name.
-5. Inclusion in `SELF_HOSTED_CHAT_PROVIDER_IDS`, which gates circuit breaker thresholds appropriately (local threshold = 2, reset 15s).
-
-### What it solves
-
-- Users who run `llama-server` locally have no obvious first-class route in OmniRoute.
-- Reduces friction vs. the generic OpenAI-compatible workaround that requires env flag + manual URL.
-- Aligns the provider list with llama.cpp's widespread adoption (the most popular local inference C++ runtime with ~80k GitHub stars).
-
-### How it should work (high level)
-
-1. Register `llama-cpp` in `LOCAL_PROVIDERS` inside `src/shared/constants/providers.ts` with `localDefault: "http://127.0.0.1:8080/v1"` and `passthroughModels: true`.
-2. Add `"llama-cpp"` to `SELF_HOSTED_CHAT_PROVIDER_IDS` (same set as llamafile, vllm, etc.).
-3. No new executor needed — the default OpenAI-compatible executor handles llama-server's `/v1/chat/completions` endpoint perfectly.
-4. No registry entry needed in `providerRegistry.ts` (same as other local providers that use passthroughModels).
-5. Add test coverage matching the existing `llamafile`/`lm-studio` test patterns.
-
-### Affected areas
-
-- `src/shared/constants/providers.ts` — add provider entry + SELF_HOSTED_CHAT_PROVIDER_IDS
-- `tests/unit/providers-route-managed-catalog.test.ts` — add llama-cpp test case
-- `tests/unit/provider-validation-specialty.test.ts` — add optional-key validation test
-- Potentially `open-sse/config/providerRegistry.ts` — only if explicit model list or custom defaults are desired (likely not needed for passthroughModels)
-
-## 📎 Attachments & References
-
-- llama.cpp GitHub: https://github.com/ggml-org/llama.cpp
-- llama-server README: https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
-
-## 🔗 Related Ideas
-
-None identified

_ideia/viable/1980-llama-cpp-local-provider.requirements.md

@@ -1,82 +0,0 @@
-# Requirements: [Feature] Please add llama.cpp to Local Providers
-
-> Feature Idea: [#1980](./1980-llama-cpp-local-provider.md)
-> Research Date: 2026-05-19
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-llama.cpp (`ggml-org/llama.cpp`) is a C/C++ LLM inference engine — the most widely-used local inference runtime (~80k GitHub stars). Its built-in `llama-server` binary exposes a full OpenAI-compatible HTTP API:
-
-- Default base URL: `http://127.0.0.1:8080/v1`
-- Endpoints: `/v1/chat/completions`, `/v1/models`, `/v1/completions`, `/v1/embeddings`
-- Auth: API key optional (server accepts any key or none; `sk-no-key-required` is documented as a valid placeholder)
-- Models endpoint returns loaded model(s); users run one model per server instance by default
-- Also supports Anthropic Messages API natively (bonus — OmniRoute doesn't need to use that path)
-
-All existing local providers that follow this OpenAI-compatible pattern (llamafile, lm-studio, vllm, lemonade, docker-model-runner, xinference, oobabooga) use `passthroughModels: true` and the default executor. No custom executor or translator is needed for llama-cpp.
-
-Community discussion confirms that llama.cpp already works as a generic OpenAI-compatible provider, but users face friction because of the `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS=true` requirement and lack of a named entry in the dashboard.
-
-## 📚 Reference Implementations
-
-| Repository | Stars | Relevance |
-|---|---|---|
-| [ggml-org/llama.cpp](https://github.com/ggml-org/llama.cpp) | ~80k | Official C++ inference engine; `llama-server` is the HTTP server component |
-| [abetlen/llama-cpp-python](https://github.com/abetlen/llama-cpp-python) | ~12k | Python bindings + FastAPI server; same `/v1` base path, same OpenAI compatibility |
-| [Mozilla-Ocho/llamafile](https://github.com/Mozilla-Ocho/llamafile) | ~20k | Already in OmniRoute; same default port 8080, same OpenAI-compatible API — direct precedent |
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Add a single entry to `LOCAL_PROVIDERS` in `src/shared/constants/providers.ts`, following the identical pattern used for `llamafile` (same default port 8080, same `/v1` suffix, same `passthroughModels: true`). Add `"llama-cpp"` to `SELF_HOSTED_CHAT_PROVIDER_IDS`. No new executor, no translator, no registry model list required.
-
-### New Files
-
-None required.
-
-### Modified Files
-
-| File | Change |
-|---|---|
-| `src/shared/constants/providers.ts` | Add `"llama-cpp"` entry to `LOCAL_PROVIDERS` object; add `"llama-cpp"` to `SELF_HOSTED_CHAT_PROVIDER_IDS` set |
-| `tests/unit/providers-route-managed-catalog.test.ts` | Add test case for `llama-cpp` matching the existing `llamafile` pattern |
-| `tests/unit/provider-validation-specialty.test.ts` | Add optional-API-key validation test for `llama-cpp` |
-
-### Database Changes
-
-None.
-
-### API Changes
-
-None. The default executor already handles OpenAI-compatible endpoints. The provider will be auto-discovered in `/v1/providers` and `/v1/providers/local` via the existing `LOCAL_PROVIDERS` merge.
-
-### UI Changes
-
-None required — the dashboard auto-renders local providers from `LOCAL_PROVIDERS`. The new entry will appear in the Local Providers section automatically with the standard server/icon treatment.
-
-## ⚙️ Implementation Effort
-
-- Complexity: Low
-- Files changed: ~2 production files, ~2 test files
-- Dependencies needed: None
-- Breaking changes: No
-- i18n impact: None (provider name/authHint strings are English, consistent with all other providers)
-- Test coverage needed: 2-3 test cases (catalog presence, optional API key validation, `isSelfHostedChatProvider` flag)
-
-## ⚠️ Open Questions
-
-1. **Icon choice**: No official llama.cpp icon in Material Icons. `memory` (used by vLLM) or `article` (used by Llamafile) are the closest existing choices. `terminal` or `code` could also work given it's a C++ binary. Recommend `memory` or `terminal`.
-2. **Color**: The llama.cpp/ggml branding uses a beige/tan color for the llama image. A neutral dark tone like `#795548` (brown) or `#546E7A` (blue-grey) would differentiate it visually from Llamafile (`#EA580C`).
-3. **Text icon**: `LC` (LlamaCpp) is unambiguous; `LL` clashes visually with Llamafile (`LF`).
-4. **Port conflict with Llamafile**: Both default to `http://127.0.0.1:8080/v1`. This is fine — users run one at a time locally, and the `localDefault` is just a UI hint, not enforced. No action needed, but worth noting in `authHint`.
-5. **`providerAllowsOptionalApiKey`**: Should `llama-cpp` be added to this function? Looking at the current code, `llamafile`, `lm-studio`, `vllm`, and `lemonade` are NOT explicitly in `providerAllowsOptionalApiKey` but are in `SELF_HOSTED_CHAT_PROVIDER_IDS` which likely handles the optional-key path separately. Verify before finalizing.
-
-## 🔗 External References
-
-- [llama-server README (ggml-org/llama.cpp)](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md)
-- [llama-cpp-python OpenAI Compatible Server docs](https://llama-cpp-python.readthedocs.io/en/latest/server/)
-- [ServiceStack llama-server deployment guide](https://docs.servicestack.net/ai-server/llama-server)
-- [Arm learning path — llama-server OpenAI API](https://learn.arm.com/learning-paths/servers-and-cloud-computing/llama-cpu/llama-server/)
-- [GitHub Discussion #795 — OpenAI Compatible Web Server for llama.cpp](https://github.com/ggml-org/llama.cpp/discussions/795)

_ideia/viable/2306-zed-docker-integration.md

@@ -1,101 +0,0 @@
-# Feature: Support Zed IDE Integration When OmniRoute Runs in Docker
-
-> GitHub Issue: #2306 — opened by @KrisnaSantosa15 on 2026-05-16T13:12:49Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Problem / Use Case
-
-I want to use the Zed IDE OAuth / import integration inside OmniRoute, but it currently does not work when OmniRoute is running inside Docker while Zed IDE is installed on the host machine.
-
-When I click the "Import from Zed" button, OmniRoute shows this error:
-
-> "Zed IDE does not appear to be installed on this system."
-
-From my understanding, OmniRoute currently checks for a local Zed installation inside the container environment, not on the Docker host.
-
-My setup:
-- OmniRoute runs in Docker
-- Zed IDE is installed on the Linux host machine
-- I mounted the Zed binary path and exposed PATH variables into the container
-
-However, OmniRoute still cannot detect Zed.
-
-I already tried:
-- Mounting `/home/user.local`
-- Extending `PATH`
-- Setting `ZED_ALLOW_ROOT=true`
-
-But the import flow still fails.
-
-### Proposed Solution
-
-Add official support for Zed integration when OmniRoute runs inside Docker containers either exposing PATH and ENV from host machine to docker or adding new feature to upload/import zed creds manually.
-
-### Alternatives Considered
-
-Current workarounds attempted:
-- Mounting host `.local` directory into the container
-- Injecting host PATH into container PATH
-- Running with `ZED_ALLOW_ROOT=true`
-
-None of these worked.
-
-Alternative workaround would be running OmniRoute directly on the host machine instead of Docker, but that removes the portability and isolation benefits of containerized deployment.
-
-### Acceptance Criteria
-
-- OmniRoute can successfully detect Zed IDE when the binary is mounted from the Docker host
-- "Import from Zed" works in Docker deployments
-- OAuth/authentication flow completes successfully
-- Documentation includes a Docker example for Zed integration
-- Existing non-Docker Zed integrations continue working without regression
-
-### Area
-
-OAuth / Authentication
-
-### Related Provider(s)
-
-Zed IDE
-
-### Additional Context
-
-This issue specifically affects self-hosted/containerized setups.
-
-Many developers use Docker for OmniRoute deployment while keeping IDEs installed on the host machine, so supporting host-to-container IDE integrations would improve the developer experience significantly.
-
-### Expected Test Plan
-
-- Add integration tests for Docker-based Zed detection
-- Validate custom `ZED_BINARY_PATH` environment variable behavior
-- Ensure mounted host binaries are detected correctly
-- Ensure existing native/non-Docker Zed integration tests remain green
-
-## 💬 Community Discussion
-
-No comments yet.
-
-## 🎯 Refined Feature Description
-
-When OmniRoute runs in Docker, it cannot interact with the host's Zed IDE or its credentials easily because Zed's config files and binaries are on the host. Even mounting the binaries doesn't always work if the container OS differs or if Zed requires specific host-level APIs/DBs to read its credentials.
-We should add a manual import option for Zed credentials on the UI, or allow parsing Zed's credential files directly if they are mounted. Or simply allow the user to manually paste their Zed auth token like other providers.
-
-### What it solves
-- Unblocks Zed integration for Docker users.
-
-### How it should work (high level)
-1. Add a "Manual Import" tab/button in the Zed provider setup modal.
-2. The user can paste their Zed OAuth token manually.
-3. OmniRoute uses the pasted token directly instead of executing the Zed binary.
-
-### Affected areas
-- `src/components/providers/zed/...` (or wherever the Zed UI is)
-- `src/lib/oauth/services/zed.ts`
-
-## 📎 Attachments & References
-- None
-
-## 🔗 Related Ideas
-- None

_ideia/viable/2306-zed-docker-integration.requirements.md

@@ -1,44 +0,0 @@
-# Requirements: Support Zed IDE Integration When OmniRoute Runs in Docker
-
-> Feature Idea: [#2306](./2306-zed-docker-integration.md)
-> Research Date: 2026-05-19
-> Verdict: ✅ VIABLE
-
-## 🔍 Research Summary
-
-Docker isolates processes, so OmniRoute cannot find or execute the Zed binary located on the host OS. Exposing the binary via volume mounts is prone to failure due to glibc/OS differences or missing dependencies in the container.
-The best solution is to allow users to manually extract their Zed API token (e.g. from `~/.config/zed/` or the Zed dashboard) and paste it into OmniRoute, bypassing the need to execute the Zed binary from the backend.
-
-## 📚 Reference Implementations
-
-- Cursor and GitHub Copilot providers already support "Manual Import" tabs where the user pastes tokens.
-
-## 📐 Proposed Solution Architecture
-
-### Approach
-
-Modify the Zed provider UI component to include a "Manual" tab for token import. The backend already handles saving the token; we just need a way to submit it without triggering the native executable extraction logic.
-
-### Modified Files
-
-| File | Changes |
-| ---- | ------- |
-| `src/components/providers/zed/ZedSetupModal.tsx` (or equivalent) | Add a manual token paste input. |
-
-### Database Changes
-- None.
-
-### API Changes
-- None.
-
-### UI Changes
-- "Manual Token" input for Zed.
-
-## ⚙️ Implementation Effort
-- **Estimated complexity**: Low
-- **Estimated files changed**: 1-2
-- **Dependencies needed**: None
-- **Breaking changes**: No
-
-## ⚠️ Open Questions
-- Where is the exact UI file located for Zed setup?

_ideia/viable/2328-kiro-multi-account-support.md

@@ -1,82 +0,0 @@
-# Feature: Kiro multi-account support: independent OAuth sessions per connection
-
-> GitHub Issue: #2328 — opened by @disonjer on 2026-05-17T10:44:47Z
-> Status: 📋 Cataloged | Priority: TBD
-
-## 📝 Original Request
-
-### Feature Description
-
-When using multiple Kiro accounts (e.g., one Google-authenticated and one GitHub-authenticated Pro account), OmniRoute cannot keep both alive simultaneously. The refresh token of one account gets invalidated when the user logs into the other account via `kiro-cli`, because Kiro backend enforces a single-session policy per account.
-
-### Problem
-
-1. User imports refresh_token for Account A (Google Pro) into OmniRoute via "Import Token"
-2. User needs to log into Account B (GitHub Pro) via `kiro-cli` to get its refresh_token
-3. After logging into Account B, Kiro backend invalidates Account A's refresh_token
-4. OmniRoute can no longer refresh Account A — connection dies within ~1 hour
-5. The workaround (never touching CLI for one account) is fragile and breaks on any re-auth
-
-### Proposed Solution
-
-**Register an independent OIDC client per connection during import.**
-
-The code in `src/lib/oauth/services/kiro.ts` already has `registerClient()` which creates a unique `clientId`/`clientSecret` pair via AWS SSO OIDC. Currently this is only used for the AWS Builder ID device flow.
-
-Proposal:
-1. When a user imports a refresh_token (social auth), OmniRoute calls `registerClient()` to obtain its own `clientId`/`clientSecret` pair
-2. Store this pair in `providerSpecificData` for the connection
-3. Use this dedicated client registration for all subsequent token refreshes
-4. Since each connection has its own registered client, refreshing one account does not invalidate another
-5. CLI logins no longer conflict with OmniRoute sessions because they use different client registrations
-
-This would make OmniRoute's refresh cycle fully independent from kiro-cli sessions.
-
-### Alternative Approaches
-
-- **Stable social OAuth device flow in dashboard** — allow users to authenticate directly through OmniRoute without CLI (currently hidden per #2112)
-- **Per-connection isolation via separate KIRO_HOME** — hacky, requires multiple CLI profiles
-- **Cron-based token rotation** — periodically re-import from CLI, unreliable
-
-### Context
-
-- Related: #2112 (social login buttons hidden), #2114 (AWS Builder ID scope limitation)
-- Current refresh logic: `src/lib/oauth/services/kiro.ts` lines 184-239
-- Token health check correctly saves new refresh_token after refresh (line 417-418 in `tokenHealthCheck.ts`)
-- The issue is upstream (Kiro backend single-session), but OmniRoute can work around it with independent client registration
-
-### Environment
-
-- OmniRoute 3.8.0
-- Two Kiro Pro accounts (one Google auth, one GitHub auth)
-- Linux server, headless
-
-## 💬 Community Discussion
-
-No comments yet.
-
-## 🎯 Refined Feature Description
-
-Currently, when users import a Kiro refresh token, OmniRoute might reuse a global client or the CLI's client to refresh tokens. Because Kiro backend enforces a single-session policy per OIDC client for a given account, logging into a different account via `kiro-cli` (or refreshing) invalidates the other token.
-
-By registering an independent OIDC client per connection (calling `registerClient()` when a new refresh_token is imported or when setting up the provider), OmniRoute can maintain an isolated session. We need to store this `clientId`/`clientSecret` pair in the provider's `providerSpecificData` in the database and use it during `refreshToken` calls.
-
-### What it solves
-- Fixes Kiro token invalidation when using multiple accounts.
-- Stops conflicts between `kiro-cli` and OmniRoute.
-
-### How it should work (high level)
-1. On token import, if it's a Kiro token, call `registerClient()` to get a new pair.
-2. Save `clientId` and `clientSecret` in `providerSpecificData`.
-3. Update `src/lib/oauth/services/kiro.ts` token refresh logic to use the stored client pair if available, falling back to default.
-
-### Affected areas
-- `src/lib/oauth/services/kiro.ts`
-- Token import logic for Kiro.
-- Provider database schema (`providerSpecificData` JSON field).
-
-## 📎 Attachments & References
-- None
-
-## 🔗 Related Ideas
-- None