literouter v0.5.1

Linux packaging correction (2026-10-26)

The initial Linux desktop archive mixed the runner system loader with the private
libc. The Linux assets and SHA-256 files have been replaced after deriving the
loader from ELF PT_INTERP and executing the staged tray. Core/application source
and the v0.5.1 tag are unchanged; Windows/macOS assets are unchanged. Re-download
the Linux archive and its checksum if downloaded before this correction.
The repaired archive passed clean Debian execution, private D-Bus gateway
ownership/autostart tests and 48 isolated CLI/integration checks.

中文：最初 Linux 桌面包的加载器与 libc 不匹配，现已修正并更新校验和；版本 tag、
核心源码、Windows/macOS 资产未变。此前下载的 Linux 包请重新下载并校验。

v0.5.1 — Safer routing and reliable desktop packaging

This patch repairs credential boundaries, configuration/state consistency and
desktop distribution. It remains a single-user local gateway: one
server.api_key protects model and management interfaces. There are no client
accounts, permission groups or quota distribution.

Security and reliability

• Buffered, streamed and probe requests refuse automatic upstream redirects,
  including same-origin redirects. Credentials and prompts are never replayed
  to a Location target; configure the final Base URL. Streaming authentication
  failures stop the attempt instead of sending an unsigned request.
• Invalid client authorities return errors instead of dereferencing an empty
  HTTP client. Configured port 0 discovers and verifies a matching instance
  through its state record; stale/ambiguous destinations fail, and a record
  cannot downgrade an HTTPS management credential to plaintext.
• Real first startup creates a missing template. serve --check and
  --print-config remain read-only; corrupt files are not overwritten. Invalid
  manual or automatic reloads leave the active configuration intact.
• Management status includes cache, model usage, cost and bucket fields. Costs
  survive telemetry restoration. Inline probes use the requested protocol, and
  pooled connections distinguish proxy ports. Telemetry lock boundaries and
  socket test shutdown races are corrected.
• Windows socket cancellation is tracked explicitly across bounded poll slices:
  local shutdown otherwise leaves a reader blocked for the original timeout.
  The header deadline now returns 504 promptly without imposing that deadline
  on an already committed stream.
• TLS reads PEM via native filesystem paths rather than lossy narrow filenames,
  while retaining chain and hostname checks and rejecting malformed chains.

Routing change: explicit model fallback

providers[].models is an advertised directory, not a replacement-model
chain. A failing request will not silently select an unrelated model from that
directory. If a replacement is acceptable, author it explicitly:

{
  "model": "my-model",
  "targets": [
    { "provider": "primary", "model": "preferred-model" },
    { "provider": "primary", "model": "accepted-replacement" },
    { "provider": "backup", "model": "preferred-model" }
  ]
}

The configuration schema is unchanged, but this behavior change is intentional.

Desktop and distribution

• Desktop console URLs use the actual port and TLS scheme. A tray owns only the
  gateway it starts; exiting a tray attached to an existing gateway leaves that
  gateway alone. Linux without a StatusNotifierWatcher fails clearly rather
  than leaving an invisible resident process.
• Linux archives ship a launcher and a matching private loader/libc plus shared
  runtime closure under lib/tray/. Keep the entire extracted directory.
  Runtime provenance, full license manifests and corresponding GNU/GLib source
  accompany distribution; shared components keep their own license terms.
• Windows installers include the tray executable and icons. PATH edits follow
  the selected per-user/system installation and uninstall removes only entries
  it added. It does not kill arbitrary same-name programs, guess a shutdown port,
  or recursively erase untracked files in the application directory. Autostart
  initializes the COM apartment before creating shortcuts.
• macOS bundles have numeric versions, assets/notices and a 14.0+ deployment
  minimum. Autostart addresses the bundle correctly and escapes XML paths.
  Ad-hoc or Developer ID signing alone is not notarization.
• CI selects exact CLI targets, bounds smoke tests, and checks the web console.
  Release builds require passing core/CLI tests and desktop builds; a missing
  tray is no longer silently omitted. Vite/Vitest build-tool patches are updated.

Downloads and upgrade

Platform	Desktop package
Linux x86-64	literouter-v0.5.1-linux-x86_64.tar.gz
macOS Apple Silicon, 14+	literouter-v0.5.1-macos-arm64-app.zip
Windows x86-64	literouter-v0.5.1-windows-x86_64-setup.exe

Standalone CLI files and per-file SHA-256 checksums remain available. Linux CLI
requires glibc 2.38+; Linux tray requires a StatusNotifierWatcher (for example
KDE or a compatible GNOME extension/panel). macOS Intel is not distributed.
The container image is built from the exact published Linux CLI.

Back up configuration, inspect any intentional redirect/model-fallback usage,
then switch versions in a maintenance window. This release does not update
or restart an already running installation. v0.5.0 assets remain historical.

Validation scope and limits

Local Linux checks cover the 15 core suites, CLI tests, 103 frontend tests,
isolated simulated requests, 21 real-browser console checks, clean-container
package execution, private D-Bus lifecycle tests, and selected sanitizer suites.
They are not live-provider benchmarks or a guarantee for every client extension.
The pre-release CI matrix
passed on Linux, macOS and Windows, including core/CLI tests, packaging helpers
and CLI first-run/dynamic-port/CRLF checks.
Platform CI exercises builds/tests and native packaging; visible desktop UI,
all installation scopes, and Gatekeeper approval still depend on the target
environment. See the packaging guide.

Matching-wire forwarding avoids protocol conversion, but routing/validation
still parses requests and streaming uses bounded queues. Costs are estimates
from configured prices and reported usage, not synchronized billing. Secret
references remain preserved on save; arbitrary text/custom headers and logs
are not covered by an absolute "zero-leak" promise.

中文升级摘要

• 修复重定向凭据边界、端口 0 管理崩溃、坏配置重载、首次配置创建和费用/缓存状态恢复。
• 模型目录不再隐式换模型；可接受的替代模型必须显式写入路由候选。依赖重定向的上游需改用最终地址。
• 修复 Linux tray 运行库分发、Windows 安装器桌面产物与自启 COM、macOS 包版本/系统要求及自启路径。
• Linux CLI 要求 glibc 2.38+，tray 保留整包并需要托盘面板；macOS Apple Silicon 要求 14+，签名不等于公证。
• 原有配置 schema 不变，本版不会自动重启或升级正在运行的网关。升级前备份配置，并在维护窗口中切换。

literouter v0.5.0

v0.5.0 — The Desktop App

Highlights

• literouter is now an application you install and double-click. It starts the gateway, opens the web console in your browser, and lives in the system tray. No window of its own — the console is the interface. Tray menu: Show opens the console, Exit stops the gateway.
• The gateway runs inside the app's process. literouter.core is a library, so the app links it and calls start() / stop() directly instead of spawning literouter serve as a child. That is what makes one implementation instead of three: a supervised child would need posix_spawn/CreateProcessW, kill/GenerateConsoleCtrlEvent, waitpid/WaitForSingleObject and a pipe on every platform.
• A gateway that is already running is adopted, not fought over. If you have literouter serve going, the app opens its console, keeps the icon, and leaves that gateway alone on exit — it did not start it. Detection asks the instance (GET /__literouter/status), so port: 0 works: only the instance knows what the kernel gave it.
• A macOS .app bundle. Unzip, drag to Applications, double-click. Gets its own Dock icon and a Gatekeeper identity that can be granted per app. ditto -c -k --sequesterRsrc packs it, because a plain zip -r of a .app is a known way to ship a bundle that will not launch.
• A Windows installer. Installs to Program Files, adds Start-menu entries, uninstalls from Apps & features. It does not edit PATH unless asked, does not add firewall rules, and does not register a service.
• Autostart is opt-in and user-scoped. Nothing is written on first launch. literouter-tray --autostart adds a login entry in a location you can delete by hand without elevation — XDG autostart, ~/Library/LaunchAgents, or the Windows Startup folder. Never a system service.

Fixed

• Streamed answers were paced by Nagle. Neither the server socket nor the upstream socket set TCP_NODELAY, which is httplib's default. Measured on loopback against a relay answering in 0.1 ms: a buffered request took 42 ms instead of 0.7 ms, and a streamed answer 42.15 ms instead of 0.90 ms. Both legs now set it. Group 4c guards the upstream leg against the burst-write relay that actually reproduces it — the existing Stream stub pauses 5 ms per chunk, which is longer than the delayed-ACK timer, so it passed even with the bug present.
• TLS certificate paths were passed to OpenSSL as UTF-8 bytes. The config stores UTF-8; OpenSSL's PEM loaders decode through the ANSI code page on Windows, so a certificate under a directory named in Chinese failed at bind time with a message that named neither the path nor the reason. pathFromUtf8 and pathForCApi make the two conversions explicit — and they are not interchangeable, because pathToUtf8 produces exactly the bytes those APIs cannot read.
• stdout was left in the CRT's text mode on Windows, turning every \n in --json output into \r\n. A CR inside a JSON string value is either invalid JSON or a silently different value, and the consumers are jq, CI, and the Docker healthcheck.

Changed

• The raw-socket test groups run on Windows. Groups 12 (hanging relay), 23 (request deadline) and 20 (connection reuse) were wrapped in #ifndef _WIN32 because their stubs speak raw sockets. Those are the failover and pooling paths — the parts with the most to go wrong — so the platform with the least coverage was the one where a failover bug would be hardest to find. core/tests/lr_test_socket.h provides the same vocabulary with Winsock behind it.
• tray is a workspace member. It has to be: core pins its dependencies with workspace = true, which mcpp only resolves inside the workspace that declares them. The cost is that a full workspace build now pulls eui-neo's graphics closure; mcpp build -p core -p cli still builds only the headless pair.

Upgrade Notes

• The configuration schema is unchanged and needs no migration. Existing config.json files load and behave exactly as before.
• If you use the command-line gateway, nothing about it changed. The install scripts still install literouter and still take --service / -Service for a headless service.
• The desktop app and the CLI are independent: installing one does not touch the other, and both read the same config.
• New artifacts this release adds: literouter-<version>-macos-arm64-app.zip, literouter-<version>-windows-x86_64-setup.exe, and literouter-tray inside the Linux tarball.
• macOS Intel is still not published; install.sh refuses it with a pointer to Rosetta or building from source.

Known Limits

• The tray menu has two entries. EUI-NEO hard-codes Show / separator / Exit in all three of its backends and exposes only two booleans. Starting and stopping follow the process lifetime instead, and autostart is a command-line flag rather than a menu item.
• Show cannot report failure. EUI-NEO's openUrl runs xdg-open … & through std::system(), so it returns success as soon as the fork happens, whether or not a browser appears. The app calls it and does not pretend the result means anything.
• The Windows and macOS packaging steps have not run on this machine. ISCC is Windows-only and ditto/codesign are macOS-only; they were verified structurally (the plist parses, the .iss has every required section and its staged path rewriting resolves) and execute for the first time in this release workflow.

Installation

Desktop app — download from the GitHub Release:

Platform	File
macOS (Apple Silicon)	literouter-0.5.0-macos-arm64-app.zip
Windows (x86_64)	literouter-0.5.0-windows-x86_64-setup.exe
Linux (x86_64)	literouter-0.5.0-linux-x86_64.tar.gz (run the literouter-tray inside)

Command-line gateway — unchanged:

curl -fsSL https://raw.githubusercontent.com/YangQi0408/literouter/main/scripts/install.sh | bash

Then open http://127.0.0.1:8787/ui/.

literouter v0.4.0

v0.4.0 — Stateless Responses Requests

Highlights

• A relay can be told to forget: the new per-relay option strip_responses_state removes the Responses API's server-side state from a forwarded /v1/responses request — every input item's id, any encrypted* field on an item (the encrypted reasoning chain), and the top-level previous_response_id. Message text, call_id and tool arguments are forwarded untouched.
• Built for multi-resource Azure relays: Azure OpenAI stores items and encrypts reasoning content per resource. A relay that balances across several resources without session stickiness answers the next turn of a conversation with HTTP 400 (The requested item was created under a different Azure OpenAI resource / The encrypted content for item rs_… could not be verified). Stripping makes every request a shape any resource in the pool accepts.
• Visible when it fires: the request log records how many fields were removed (… · stripped 8 Responses state fields), on both the buffered and the streamed path. A workaround nobody can see is one that gets debugged by guessing.
• Said out loud when it cannot work: enabling it on a relay whose wire shape is not Responses — openai, azure, anthropic, … — produces a config validate warning instead of a switch that quietly does nothing.
• In both front ends: literouter providers add … --strip-responses-state (and providers list --json), plus a "Stateless Responses requests" switch in the console's relay editor, shown only for openai_responses relays, with Chinese and English copy.

Upgrade Notes

• The option is off by default and is written to config.json only when on, so existing files load and behave exactly as before.
• The configuration schema is unchanged; no migration is needed.
• A request with nothing to strip is still forwarded as the client's original bytes, so the same-protocol fast path keeps its zero-parse, zero-copy properties.
• With it on, the model no longer continues a hidden reasoning chain across turns and reasons again each turn. The visible conversation and the tool-call chain are unaffected. Turn it off again as soon as the relay routes consistently or strips on its side.
• This port is derived from codex-strip-proxy by AnnaofArendelle; the attribution is recorded in NOTICE.

Installation

Download the archive for Linux x86_64, macOS arm64, or Windows x86_64 from the GitHub Release, verify its .sha256 file, and run literouter serve. Linux users can also install the latest binary with:

curl -fsSL https://raw.githubusercontent.com/YangQi0408/literouter/main/scripts/install.sh | bash

Then open http://127.0.0.1:8787/ui/ to use the built-in Web Console.

literouter v0.3.1

v0.3.1 — Richer Request Activity

Highlights

• Request-level context: Every activity entry now records the ingress method and path, ingress and upstream protocols, client IP, User-Agent, and the exact request and response sizes.
• Usage and cost: Input tokens, output tokens, and the estimated cost are carried from the relay that actually answered into both the activity table and the detail view.
• Operational filters: The console can filter the stream by cache hits, failovers, or errors, with live totals for the visible requests, tokens, cost, and cache hits.
• Cache visibility: A local response-cache hit or miss is recorded on the request itself, so a fast answer no longer looks like an unexplained relay response.
• Routing clarity: The detail view keeps the logical model beside the renamed upstream model and names both sides' protocols, while preserving the existing timing, streaming, failover, and body-logging views.

Upgrade Notes

• The configuration schema is unchanged. Existing config.json files continue to load without edits.
• Existing persisted logs remain readable. Entries written before this release simply omit the new request-context fields, and the console renders them as unavailable rather than failing.
• The new fields describe only values the proxy already observed; no prompt, credential, or additional request content is logged.

Installation

Download the archive for Linux x86_64, macOS arm64, or Windows x86_64 from the GitHub Release, verify its .sha256 file, and run literouter serve. Linux users can also install the latest binary with:

curl -fsSL https://raw.githubusercontent.com/YangQi0408/literouter/main/scripts/install.sh | bash

Then open http://127.0.0.1:8787/ui/ to use the built-in Web Console.

literouter v0.3.0

v0.3.0 — Relay Round-Robin Balancing

Highlights

• Round-robin relay balancing: Set server.routing_policy to round_robin to rotate the first relay between requests while keeping each relay's model fallback chain together. Equal relays converge on an even traffic split as requests accumulate.
• Health and affinity remain authoritative: Open circuit breakers are still skipped before healthy relays, and session affinity still moves the relay that already served a conversation to the front.
• Safer model fallback: A relay's advertised models now stay grouped during routing, including the single-relay case, so model fallback order is not interleaved across relays.
• Console and documentation: The built-in Web Console exposes the new policy in multiple languages, with configuration and routing documentation updated in both Chinese and English.

Upgrade Notes

• The configuration schema is unchanged. Existing configurations continue to load with routing_policy: "priority" and the same behavior as v0.2.0.

• To enable balanced routing, edit the server configuration:

  {
    "server": {
      "routing_policy": "round_robin"
    }
  }

• round_robin is equal-weight rotation. It is not weighted traffic splitting; provider weight remains a tie-breaker in priority ordering.

Installation

Download the archive for Linux x86_64, macOS arm64, or Windows x86_64 from the GitHub Release, verify its .sha256 file, and run literouter serve. Linux users can also install the latest binary with:

curl -fsSL https://raw.githubusercontent.com/YangQi0408/literouter/main/scripts/install.sh | bash

Then open http://127.0.0.1:8787/ui/ to use the built-in Web Console.

literouter v0.2.0

更新日志 (Changelog)

所有重要的版本更新将在此处和 docs/release-notes/ 专题文档中记录。
本项目遵循 Semantic Versioning 语义化版本规范。

---

[0.2.0] - 2026-09-25

详细说明见 docs/release-notes/v0.2.0.md。

Added

• 完整的个人本地聚合网关：Provider 路由、模型别名、故障转移、熔断、限流与本地响应缓存。
• 内置 Web 控制台继续随服务提供，支持遥测、Provider/路由管理、探测、日志和配置编辑。
• 支持 OpenAI、Anthropic、Gemini、Responses、Azure、Vertex、Bedrock 与 Ollama 协议组合。
• 提供跨平台 GitHub Release、Linux 安装脚本、Docker、Compose 与 systemd 部署方式。

Changed

• 项目定位为每个人独立运行的单用户本地聚合器，仅使用一个 server.api_key。
• 移除桌面 GUI、客户端账户、按账户密钥、权限组、配额账本和每日预算等 API 分发功能。

[0.1.0] - 2026-09-13

详细说明见 docs/release-notes/v0.1.0.md。

Added

• 初版发布：支持 OpenAI、Anthropic Claude、Google Gemini 多协议双向转换网关。
• 响应头闸门 (Header Gate) 流式无感故障转移机制与熔断自愈保护。
• 基于 React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui 的内置 Web 控制台，支持概览看板、中转站健康探测、路由候选链调序、实时日志流与配置在线安全保存。
• 原生跨平台 CLI 命令行工具（支持前台 serve、实时看板 status、日志流跟踪 logs、配置工具 config 与环境体检 doctor）。
• 原生跨平台桌面 GUI 控制台（基于 EUI-NEO 与 OpenGL 硬件加速）。
• 环境变量占位符解析与密钥防泄漏持久化保障。
• 跨平台二进制分发：支持 Linux (x86_64)、macOS (Apple Silicon)、Windows (x86_64)，Linux 产物自动适配系统标准动态链接器与 GUI 运行时动态依赖库。

literouter v0.1.0

更新日志 (Changelog)

所有重要的版本更新将在此处和 docs/release-notes/ 专题文档中记录。
本项目遵循 Semantic Versioning 语义化版本规范。

---

[0.1.0] - 2026-09-13

详细说明见 docs/release-notes/v0.1.0.md。

Added

• 初版发布：支持 OpenAI、Anthropic Claude、Google Gemini 多协议双向转换网关。
• 响应头闸门 (Header Gate) 流式无感故障转移机制与熔断自愈保护。
• 基于 React 19 + TypeScript + Vite + Tailwind CSS v4 + shadcn/ui 的内置 Web 控制台，支持概览看板、中转站健康探测、路由候选链调序、实时日志流与配置在线安全保存。
• 原生跨平台 CLI 命令行工具（支持前台 serve、实时看板 status、日志流跟踪 logs、配置工具 config 与环境体检 doctor）。
• 原生跨平台桌面 GUI 控制台（基于 EUI-NEO 与 OpenGL 硬件加速）。
• 环境变量占位符解析与密钥防泄漏持久化保障。
• 跨平台二进制分发：支持 Linux (x86_64)、macOS (Apple Silicon)、Windows (x86_64)，Linux 产物自动适配系统标准动态链接器与 GUI 运行时动态依赖库。