mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-18 21:22:28 +03:00
beb6ec857b
* feat(responses): virtualize previous_response_id continuation regardless of upstream support OmniRoute now exposes OpenAI-compatible previous_response_id/store continuation to clients unconditionally, even when the selected upstream provider has no native Responses-API state support. Reconstruction happens server-side in handleChatImplementation, before any downstream validation or provider translation: OmniRoute resolves the response id back to the full input/output it previously produced, prepends it to the client's delta, and forwards the full reconstructed history upstream exactly as it does today. Client<->OmniRoute traffic shrinks to the new delta only; OmniRoute<->provider traffic is unchanged. Storage reuses the existing call-log pipeline artifact (already gated by call_log_pipeline_enabled, already retained/cleaned up by the existing call-log lifecycle) instead of duplicating conversation content into a second store -- only a lightweight call_logs.response_id index is new. Every lookup is scoped by api_key_id so one client can never resolve another client's stored conversation, and any unresolvable/missing/ size-limit-omitted state fails closed with OpenAI's own previous_response_not_found contract. Stacked on feat/openai-responses-store-toggle (#10121). * feat(dashboard): agentic conversation tracking with live transcript view Every agentic chat request now gets a conversation id (X-ConversationId response header). OmniRoute detects when a follow-up request continues the same conversation via fingerprint + bounded prefix-hash matching, with a strict-growth invariant to prevent false merges between independent single-shot requests that happen to share identical opening content. Continuation detection excludes the system message from the identity anchor, since real coding-agent CLIs commonly regenerate it every request with live context (timestamp, cwd, git status) — without this, that volatility alone broke every continuation check against real traffic. - `/dashboard/logs`: new toggleable Conversation column. - `/dashboard/logs/timeline`: requests sharing a conversation id share a timeline lane, connected by an arrow, with a configurable lane-reuse window. - Request detail panel: new Full Conversation transcript above the raw SSE event stream — Markdown rendering, per-turn timestamps, turn-relative view, click-any-turn navigation, live auto-refresh building the transcript in real time from the in-flight SSE chunk buffer while a request is still streaming, auto-scroll-to-bottom as the live turn grows. - New `/dashboard/conversations` page listing conversations with 2+ turns, no-forking model (an edited/duplicated mid-history turn mints its own independent conversation instead of merging), pagination, duplicate- anchor fix. - Configurable auto-refresh intervals on both the timeline and conversations list pages. - Responses API tool-call gap fix: turnsFromOpenAiMessages only handled role-based Chat Completions messages, so bare {type:"function_call"} / {type:"function_call_output"} / {type:"reasoning"} items (real Responses API traffic) silently vanished from the Conversation Context panel. - truncateForLog now counts input[] (Responses API), not just messages[] (Chat Completions), so a truncated /v1/responses request still shows a placeholder instead of nothing. - RequestTimeline.tsx now reads the same debugEnabled/emailsVisible settings RequestLoggerV2.tsx already used, instead of hardcoding both false — the timeline view never showed SSE/stream-chunk events or respected email-masking, regardless of the actual setting. Migrations 147/148 (agentic_conversations, conversation_turn_nodes) — 135 and 136 are now taken upstream; 143-145 are documented KNOWN_GAPS, so this uses the next free slot past upstream's current highest. Test plan: - npm run typecheck:core — clean - npm run lint — clean - node --import tsx/esm scripts/check/check-migration-numbering.mjs — OK, 0 collisions - 109 unit tests across the conversation-tracking, migration-renumber, and dashboard-wiring surface — 0 failures * refactor(dashboard): reuse call-log artifacts for conversation transcript content conversation_turn_nodes no longer stores turn text/tool-call content (text_preview/block_kind/tool_name) -- it's identity-only now (id/parent/ content_hash), matching agentic_conversations' existing lightweight-index shape. Every node's originating request is already fully captured by the call-log pipeline artifact its last_correlation_id points at, so the /dashboard/conversations tree view resolves each node's actual display content on demand from there (open-sse/services/conversationTurnContent.ts), re-running the same extractCanonicalTurns/hashTurnContent the write path used and matching by content_hash, instead of duplicating conversation content into a second store under a separate retention/gating policy. This also drops the old 8000-char text_preview truncation entirely -- resolved content is always full and untruncated. The frontend contract is unchanged (tree API still returns {textPreview, blockKind, toolName} per node), so the dashboard UI itself (page.tsx, RequestLoggerDetail/RequestTimeline, sidebar, i18n) needed no changes. Renumbered the cherry-picked 147/148 migrations to 153/154 -- 147 now collides with 147_api_keys_model_access_mode.sql, which landed on release/v3.8.50 after this work was originally built. Also includes a standalone, unrelated fix carried along from this rebase: close isProviderModelHidden's missing function-body brace in modelSelectModalHelpers.ts (separately landed as #10206). Stacked on feat/responses-previous-response-id-virtualization (#3), which is itself stacked on feat/openai-responses-store-toggle (#10121). * fix(dashboard): resync conversation list on open so the live-text poll starts immediately openConversation() seeded activeConversation (and therefore activeCallLogId, which gates the live-partial-text poll effect) from whatever row snapshot the list's own fixed-interval poll last produced. A conversation opened right after a reply started streaming -- after that tick, before the next -- had activeCallLogId still null, so the live-text poll never started; only a subsequent background list-poll resync (already existed) picked it up, which is why closing and reopening the same conversation "just worked". loadConversations() is now a shared callback so openConversation can force one immediately on open instead of waiting on pollSeconds. Live-verified against omniroute-dev: opening a conversation mid-stream now shows live reasoning on the first open. * style: prettier formatting for conversationTurnContent.test.ts * fix(db): close migration numbering gap left by decoupling from #3/#10262 153/154 (originally 154/155) were chosen back when this branch stacked on top of the previous_response_id migration (153_call_logs_response_id.sql). Decoupling removed that migration from this branch's history, leaving an unused 153 slot that check-migration-numbering.test.ts correctly flags as a gap. * refactor(dashboard): split RequestTimeline/RequestLoggerDetail under the 1000-line file-size cap Both files exceeded check-file-size's new-file cap after this PR's own additions (RequestTimeline 1048, RequestLoggerDetail 1163). Extracted pure non-component logic (types, constants, allocateLanes and its helpers) out of RequestTimeline.tsx into RequestTimeline.utils.ts, and the two self-contained presentational sub-components (PayloadSection, ConversationContextSection + its private helper) out of RequestLoggerDetail.tsx into RequestLoggerDetail.sections.tsx. No behavior change; existing external imports (default exports, allocateLanes, TimelineLog, CONVERSATION_LANE_REUSE_STORAGE_KEY) still resolve from the original file paths. * fix(db): renumber agentic-conversation migrations to clear 153 collision + sync migration-count docs The refresh-merge of release/v3.8.50 exposed that the feature's three migrations collided at slot 153 with the base's radar_local_model_state (153) and its own call_logs_response_id. Migration runner enforces unique numeric prefixes -> every DB init threw, red-ing Vitest, all Unit shards and the DB-backed quality gates. Renumber the feature's pair to 155_agentic_conversations / 156_conversation_turn_nodes and move call_logs_response_id to 154 (keeps 153_radar base-owned, preserves agentic-before-turn_nodes ordering). Update SQL headers and the 154/156 references in feature code + tests. Migration count is now 151 (was 148 stale in README/AGENTS/llm.txt) — sync the doc counts to clear the docs-accuracy gate. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(ui): drop unused CONVERSATION_LANE_REUSE_STORAGE_KEY re-export from RequestTimeline Knip 6.32 (baseline 415) flags the public re-export of CONVERSATION_LANE_REUSE_STORAGE_KEY from RequestTimeline.tsx as dead: no external consumer imports it through that re-export (it is imported and used directly from RequestTimeline.utils.ts inside the component). Removed the unused re-export; the internal import stays. DEAD_TOTAL 416 -> 415, back to the frozen baseline. Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> * fix(agentic-conversations): guard resolveConversationId, drop dead whole-chain export - Wrap resolveConversationId() in try/catch in chat.ts, matching the defensive pattern used by every other best-effort side call nearby, so a DB hiccup in conversation tracking can't turn a working chat request into a hard failure. - Remove getConversationTurnTree: knip's project scope excludes tests/**, so an export used only by tests can never register as used there. Swap its 8 test call sites to the paginated getConversationTurnPage (already the dashboard's canonical query) with a generous limit, collapsing to one query path instead of keeping a second whole-chain export alive solely for test convenience. - Regenerate i18n llm.txt mirrors from root (pre-existing drift on this branch, unrelated to the above, caught by the docs-sync pre-commit gate). Addresses PR review feedback. * fix(i18n): close requestLogger conversation-column gap, fix domain-modules count drift - fr.json, vi.json were missing requestLogger.columns.conversation (added in the conversation-tracking feature), failing i18n-vi-completeness.test.ts. - docs/i18n/*/llm.txt mirrors still said 117 domain-specific files after an earlier rebase fixed the migration count but missed this companion number, failing check-docs-sync.mjs across all 42 locales. Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com> * fix(docs): restore PROXY_LOG_INCLUDE_IPS env/doc entries (env-doc-sync red) .env.example and docs/reference/ENVIRONMENT.md were both missing the PROXY_LOG_INCLUDE_IPS entry that src/lib/proxyLogger.ts already reads (confirmed present at this branch's merge-base too, so this predates the conversation-tracking work and is unrelated to it) -- the entry was added on release/v3.8.50 after this branch's last sync and this branch never picked it up. That gap red-lines tests/unit/check-env-doc-sync.test.ts and tests/unit/issue-7793-env-doc-sync-repro.test.ts (Unit Tests fast-path 2/4 in CI). Restore both entries verbatim from the current release/v3.8.50 tip -- no feature-code change. Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com> --------- Co-authored-by: hartmark <hartmark@users.noreply.github.com> Co-authored-by: diegosouzapw <diegosouza.pw@gmail.com> Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>
title, version, lastUpdated
| title | version | lastUpdated |
|---|---|---|
| OmniRoute Documentation | 3.8.40 | 2026-06-28 |
OmniRoute Documentation
Navigable index of the OmniRoute documentation set. Topics are grouped by intent so you can find what you need quickly.
Looking for the project overview, install steps, or release notes? See the root README.md, ROADMAP.md, CHANGELOG.md, and CONTRIBUTING.md.
For Non-Tech Users
Simple guides for using OmniRoute — no technical background needed.
getting-started/
- QUICK-START.md — install and run OmniRoute in 3 minutes.
- AUTO-COMBO-GUIDE.md — let OmniRoute pick the best AI for you.
- PROVIDERS-GUIDE.md — how to connect AI providers.
- FREE-TIERS-GUIDE.md — get free AI with no credit card.
- WEB-COOKIE-GUIDE.md — web cookie providers (session-credential setup).
guides/
- SETUP_GUIDE.md — first-time setup of OmniRoute.
- USER_GUIDE.md — daily usage of the dashboard and API.
- THINKING_BUDGET.md — thinking/reasoning budget modes (passthrough vs auto-strip).
- FEATURES.md — dashboard feature gallery.
- TIERS.md — OmniRoute tiers explained (user guide).
- USAGE_QUOTA_GUIDE.md — usage, quota & spend tracking.
- COST_TRACKING.md — cost and spend tracking.
- FREE_PROVIDER_RANKINGS.md — free provider rankings (Arena ELO).
- DOCKER_GUIDE.md — running OmniRoute under Docker.
- ELECTRON_GUIDE.md — desktop (Electron) builds.
- TERMUX_GUIDE.md — running on Android via Termux.
- PWA_GUIDE.md — installing the dashboard as a PWA.
- REMOTE-MODE.md — exposing OmniRoute remotely + scoped tokens.
- CLI-INTEGRATIONS.md — master table of
setup-*CLI integrations. - CLAUDE-CODE-CONFIGURATION.md — Claude Code CLI with OmniRoute.
- CODEX-CLI-CONFIGURATION.md — Codex CLI with OmniRoute.
- KIRO_SETUP.md — Kiro setup.
- ANTIGRAVITY-ONBOARDING.md — Antigravity (Google One AI) onboarding.
- MANAGEMENT-AUTH.md — management authentication.
- I18N.md — translation and locale workflow.
- TROUBLESHOOTING.md — detailed troubleshooting reference.
- UNINSTALL.md — clean removal steps.
For Tech Users
Technical documentation for developers and contributors.
architecture/
How the system is put together — read these to understand the runtime, code layout, and resilience model.
- ARCHITECTURE.md — high-level system architecture (request pipeline, layers, modules).
- CODEBASE_DOCUMENTATION.md — engineering reference for the codebase.
- REPOSITORY_MAP.md — directory-by-directory navigation guide.
- AUTHZ_GUIDE.md — authorization pipeline (route classifier + policy engine).
- RESILIENCE_GUIDE.md — provider circuit breaker, connection cooldown, and model lockout.
- QUALITY_GATES.md — quality-gate scripts and CI jobs inventory.
- MONITORING_SECTIONS.md — monitoring/costs dashboard navigation.
- cluster-decisions.md — optional sidecar/cluster profile decisions.
- DESIGN_SYSTEM.md — design system & visual identity.
- ROUTER_BACKENDS.md — router backends & embedded services architecture contract (ADR).
- admission-lanes.md — the two admission-lane systems and what gates each.
- persistence-backend-boundary.md — pluggable persistence boundary (ADR).
reference/
Lookup material — API surface, environment variables, CLI flags, provider catalog.
- API_REFERENCE.md — REST API endpoints and shapes.
- PROVIDER_REFERENCE.md — auto-generated provider catalog (do not edit by hand).
- PROVIDER_PLUGIN_MANIFEST.md — sidecar-safe provider plugin contract for Bifrost and CLIProxyAPI migration.
- openapi.yaml — OpenAPI spec for the public API.
- ENVIRONMENT.md — environment variables reference.
- FEATURE_FLAGS.md — feature flags and their defaults.
- CLI-TOOLS.md — bundled CLI commands.
- FREE_TIERS.md — free-tier LLM provider directory.
- FREE_PROXIES_API.md — free proxies API.
- RELAY_BACKEND_STRATEGY.md — relay backend strategy.
- RELAY_TROUBLESHOOTING.md — relay troubleshooting.
frameworks/
Pluggable subsystems exposed to clients, agents, and operators.
- MCP-SERVER.md — Model Context Protocol server.
- A2A-SERVER.md — Agent-to-Agent (A2A) JSON-RPC server.
- ACP.md — Agent Client Protocol.
- AGENT_PROTOCOLS_GUIDE.md — A2A / ACP / Cloud agent overview.
- AGENTBRIDGE.md — IDE agent bridge.
- AGENT-SKILLS.md — agent skills catalog.
- CLOUD_AGENT.md — cloud agent runtime and providers.
- SKILLS.md — Skills framework (sandboxed extension).
- MEMORY.md — persistent memory (FTS5 + Qdrant).
- WEBHOOKS.md — webhook events and dispatch.
- EVALS.md — eval suites.
- GAMIFICATION.md — gamification & leaderboard system.
- EMBEDDED-SERVICES.md — embedded sidecar services (9Router, CLIProxyAPI).
- NOTION_CONTEXT.md — Notion context source.
- OBSIDIAN_CONTEXT.md — Obsidian context source.
- LOCAL_CORPUS_CONTEXT.md — local corpus context source (approved directory exposed to MCP).
- OPENCODE.md — OpenCode integration.
- OPEN_SSE_ARCHITECTURE.md — open-sse streaming engine internals.
- PLAYGROUND_STUDIO.md — Playground Studio UI.
- SEARCH_TOOLS_STUDIO.md — Search Tools Studio UI.
- TRAFFIC_INSPECTOR.md — traffic inspector (MITM).
- PLUGINS.md — CLI plugin system overview.
- PLUGIN_SDK.md — plugin SDK reference.
- PLUGIN_MARKETPLACE.md — plugin marketplace.
- RADAR.md — Radar free-model catalog overlay (optional, off by default).
routing/
Combo routing, scoring, and replay.
- AUTO-COMBO.md — Auto-Combo (multi-factor scoring, 19 strategies).
- QUOTA_SHARE.md — quota sharing engine.
- REASONING_REPLAY.md — reasoning replay cache.
- REASONING_ROUTING.md — reasoning routing rules (effort/budget rule engine).
security/
Guardrails, compliance, stealth, and the mandatory patterns for handling public credentials and error messages.
- GUARDRAILS.md — PII, prompt injection, vision guardrails.
- COMPLIANCE.md — audit trails and compliance.
- STEALTH_GUIDE.md — TLS / fingerprint stealth.
- PUBLIC_CREDS.md — mandatory pattern for embedding public upstream OAuth client_id/secret + Firebase Web keys without tripping secret scanners.
- ERROR_SANITIZATION.md — mandatory pattern for routing every error response through
sanitizeErrorMessageto prevent stack-trace exposure. - ROUTE_GUARD_TIERS.md — route-guard classification tiers.
- CLI_TOKEN.md — CLI machine-ID token (HMAC + legacy SHA-256) auth.
- EGRESS_POLICY.md — egress IP family (IPv4/IPv6) policy.
- BAN_DETECTION.md — account-ban / banned-keyword detection.
- AGENTROUTER_WAF.md — agentrouter.org WAF.
- CORS.md — CORS configuration & security.
- MITM-TPROXY-DECRYPT.md — transparent MITM decrypt.
- SUPPLY_CHAIN.md — supply-chain gates (SLSA, SBOM, Trivy, osv-scanner, Scorecard).
- SOCKET_DEV_FINDINGS.md — supply-chain finding attestations.
compression/
Prompt compression engines, rules, and language packs.
- COMPRESSION_GUIDE.md — top-level compression overview.
- COMPRESSION_ENGINES.md — available compression engines.
- COMPRESSION_RULES_FORMAT.md — rule file format.
- COMPRESSION_LANGUAGE_PACKS.md — language packs.
- RTK_COMPRESSION.md — RTK engine deep dive.
- CONTEXT_EDITING.md — delegated context editing (Anthropic).
- EXTENDING_COMPRESSION.md — adding a custom compression engine.
providers/
Provider-specific integration guides.
- CLAUDE_WEB.md — Claude Web (cookie-auth) provider.
- CHATGPT_WEB.md — ChatGPT Web (Plus/Pro + Codex) providers.
- ALIBABA-QWEN-PROVIDER-FAMILIES.md — Alibaba and Qwen provider families.
- AGENTROUTER.md — AgentRouter setup.
- ZED-DOCKER.md — Zed IDE integration under Docker.
- CURSOR-DOCKER.md — Cursor model listing under Docker.
comparison/
- OMNIROUTE_VS_ALTERNATIVES.md — how OmniRoute compares to alternatives.
ops/
Release, deployment, proxies, tunnels, coverage, database, monitoring.
- RELEASE_CHECKLIST.md — release flow checklist.
- RELEASE_GREEN.md — keeping the PR queue and release branch green.
- BRANCHING_MODEL.md — branching & release model.
- MERGE_TRAIN.md — merge queue & manual merge-train runbook.
- HOMOLOGATION.md — homologation suite (
npm run homolog). - QUALITY_GATE_PLAYBOOK.md — quality-gate playbook.
- RUNNER_BOX.md — self-hosted runner box operations.
- BRANCH_PROTECTION_MAIN.md —
mainbranch protection. - CONTRIBUTION_GOLDEN_PATH.md — contribution golden path (focused checks per change type).
- COVERAGE_PLAN.md — test coverage plan.
- DATABASE_GUIDE.md — DB schema and operations.
- SQLITE_RUNTIME.md — SQLite driver resolution chain.
- REDIS_PRODUCTION_CONFIG.md — Redis production configuration.
- MONITORING_GUIDE.md — monitoring & observability.
- FLY_IO_DEPLOYMENT_GUIDE.md — Fly.io deployment.
- VM_DEPLOYMENT_GUIDE.md — generic VM deployment.
- PROXY_GUIDE.md — upstream proxy configuration.
- TUNNELS_GUIDE.md — Cloudflare tunnel and friends.
diagrams/
Mermaid sources and exported SVG/PNG diagrams referenced from the docs above. See diagrams/README.md.
i18n/
Translated mirrors of the documentation in 43 locales. See i18n/README.md for the supported language list.
screenshots/
Static screenshots used by the dashboard and the README. Not part of the doc body.
Auto-generated artifacts
- reference/PROVIDER_REFERENCE.md is generated by
scripts/docs/gen-provider-reference.tsfromsrc/shared/constants/providers.ts. Do not edit by hand. - The
/docsUI is backed by Fumadocs MDX source generation from the subfolders above.