@ychris12138/dsh-usage-stats 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,6 @@
 # dsh-usage-stats
 
-<!-- stable-version: 0.3.0 -->
+<!-- stable-version: 0.3.2 -->
 
 [![GitHub Release](https://img.shields.io/github/v/release/Ychris12138/dsh-usage-stats?display_name=tag&sort=semver&color=1f6feb)](https://github.com/Ychris12138/dsh-usage-stats/releases/latest)
 [![CI](https://github.com/Ychris12138/dsh-usage-stats/actions/workflows/ci.yml/badge.svg)](https://github.com/Ychris12138/dsh-usage-stats/actions/workflows/ci.yml)
@@ -14,17 +14,21 @@ Provider balances, subscription quotas, and token-usage analytics for the DeepSe
 
 > 展示图使用脱敏演示数据；插件不会把 API Key、Cookie、管理 PAT 或上游原始响应发送到浏览器。
 
+[![Powered by OrcaRouter](https://img.shields.io/badge/Powered_by-OrcaRouter-2563eb)](https://www.orcarouter.ai/ref/ref_13c34663d1527ac16963)
+
+> 🐋 OrcaRouter sponsors this project and is available as an optional OpenAI-compatible provider. [Learn more](https://www.orcarouter.ai/ref/ref_13c34663d1527ac16963) · Referral link.
+
 ## 一眼看懂 / At a glance
 
 | | 能力 | 说明 |
 | --- | --- | --- |
 | 💳 | 统一账户卡片 | API 供应商显示余额，Token Plan 显示分窗口额度；面板一次只呈现当前供应商 |
 | 📊 | Token 用量分析 | 今日、本月、累计、缓存命中率、月历热图，以及按日期/供应商/模型下钻 |
-| 💰 | 估算费用与预算 | 按事件时间匹配历史价格，提供当前会话、日/月与 session 维度费用；可选日/月预算预警 |
+| 💰 | 估算费用与预算 | 按事件时间匹配历史价格，提供日/月费用、session 级聚合及可选预算预警 |
 | 🔄 | 后台监测 | 账户按 active/detail/background 自适应刷新；间隔可配置或完全关闭，本地 Token 聚合保持独立运行 |
 | 🧩 | 可扩展适配器 | 支持 New API、Sub2API、通用余额模板，以及声明式 JSON Pointer 自定义查询 |
 | 📦 | 安全导出 | 提供 daily/session CSV 与版本化 JSON；Unicode、CSV 公式前缀和不完整费用均安全处理 |
-| 🔒 | 本机安全边界 | 九个端点仅接受回环 GET；凭据只在服务端解析并发往校验后的供应商地址 |
+| 🔒 | 本机安全边界 | 数据端点仅接受回环 GET；OrcaRouter preset 仅由带防跨站请求头的显式回环 POST 写入；凭据只在服务端解析 |
 
 界面支持中文和英文。浏览器只请求当前选择的 provider；账户自动刷新由服务端统一调度。手动刷新会更新用量、供应商列表，并强制刷新当前账户，不会批量强制请求其他供应商。
 
@@ -35,7 +39,7 @@ Provider balances, subscription quotas, and token-usage analytics for the DeepSe
 稳定版优先安装 npm 上的精确版本；这也是 DSH Desktop Market 使用的同一个包：
 
 ```bash
-dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.0"
+dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.2"
 ```
 
 只有测试尚未发布的 source/RC 时才使用 `dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"`。GitHub `main` 可能领先 npm stable，不应把 source 安装当作市场安装验收。
@@ -49,7 +53,7 @@ dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.0"
 - `catalog/catalog-source.json` — 来源 manifest（`catalog-source.schema.json` v1.0.0）
 - `catalog/v1/plugins.json` — 标准 provider page（`catalog-provider-page.schema.json` v1.0.0）
 
-**使用前提（重要）**：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。`dsh-usage-stats` 这个 npm 名已被其他项目占用，因此目录条目身份使用 `@ychris12138/dsh-usage-stats`。当前 stable/catalog 版本是 `0.3.0`；每个新版本都按以下顺序发布：
+**使用前提（重要）**：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。`dsh-usage-stats` 这个 npm 名已被其他项目占用，因此目录条目身份使用 `@ychris12138/dsh-usage-stats`。当前 stable/catalog 版本是 `0.3.2`；每个新版本都按以下顺序发布：
 
 1. 运行 `npm run release:sync -- <version>` 同步 `package.json` / `package-lock.json` / `catalog/v1/plugins.json`，再由 `npm run check:release` 阻止身份或版本漂移。
 2. 发布 scoped 公共包：`npm publish --access public`。
@@ -101,6 +105,7 @@ npx --yes github:Ychris12138/dsh-usage-stats --no-enable
 | --- | --- | --- | --- |
 | DeepSeek | 余额 | provider `apiKeyEnv` | `/user/balance` |
 | OpenRouter | 余额 | `OPENROUTER_MANAGEMENT_KEY` | `/api/v1/credits` |
+| OrcaRouter | 余额 | `ORCAROUTER_API_KEY` | `/v1/balance`（旧部署回退到账单摘要接口） |
 | Moonshot / Kimi API | 余额 | provider `apiKeyEnv` | `/v1/users/me/balance` |
 | OpenCode Go | 订阅 | `OPENCODE_GO_API_KEY` 或本地 `auth.json` | `/zen/go/v1/usage` |
 | Z.ai / 智谱 | 订阅 | `ZAI_API_KEY` | Coding Plan quota/subscription |
@@ -157,19 +162,6 @@ npx --yes github:Ychris12138/dsh-usage-stats --no-enable
 
 预算使用本机日历日/月边界：低于 80% 为正常，达到 80% 为 warning，达到 100% 为 critical。`daily` / `monthly` 必须是正数或 `null`；当前版本不做 FX 换算，因此预算货币与可靠价格货币不兼容时状态保持 unknown。
 
-### 界面设置 / Display settings
-
-Current Session Pill 默认开启。只隐藏 composer 附近的 Pill、保留侧边栏账户面板时：
-
-```yaml
-- insert:
-    - id: usage-stats
-      name: "@ychris12138/dsh-usage-stats"
-      config:
-        display:
-          currentSessionPill: false
-```
-
 面板的当前 provider 会保存在浏览器的命名空间 localStorage 中；刷新页面或重启 DSH 后恢复。若该 provider 已被删除，插件会清除旧值并使用原有的 DeepSeek/已配置 provider fallback。该选择不会写入 DSH 设置、服务端缓存或新 API。
 
 ### 余额型供应商
@@ -190,6 +182,8 @@ OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key
 
 插件按 `total_credits - total_usage` 显示 OpenRouter 余额，并同时展示累计已用和总 credits。普通 Key 的 `/api/v1/key` 只描述单个 Key 的 spending limit，不会被当作账户余额。自定义引用可在 `monitors.openrouter` 中设置 `adapter: openrouter-balance` 与 `credentialRef`。
 
+OrcaRouter 优先读取其余额接口 `/v1/balance`，将 paid、free 和 promo credits 汇总为当前可用余额；旧部署没有该接口时，回退到官方文档提供的 OpenAI-compatible 账单摘要接口（订阅端点总额度 + usage 端点累计用量，按美分换算）。任一可用路径返回无法识别的数据时会显示明确的错误状态，不会把未知结果当作 0；无限额度哨兵值会显示为 `∞`，OrcaRouter 路由仍不参与本插件的模型价格估算。
+
 ### Token Plan 供应商
 
 ```yaml
@@ -355,7 +349,7 @@ Constraints:
 
 Procedure:
 1. Confirm node, npx, and dsh are available.
-2. Prefer the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.0"` (or update the existing scoped package).
+2. Prefer the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.2"` (or update the existing scoped package).
 3. Use `github:Ychris12138/dsh-usage-stats` only when I explicitly ask to test unreleased source/RC code.
 4. If dsh plugin is unavailable, use the compatible source installer only with my approval: `npx --yes github:Ychris12138/dsh-usage-stats`.
 5. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
@@ -395,7 +389,7 @@ npx --yes github:Ychris12138/dsh-usage-stats --check
 - 自定义 monitor 默认要求 HTTPS、同源相对路径、手动 redirect 和 JSON 响应，body 上限为 1 MiB。
 - 发凭据前会筛选域名的 IPv4/IPv6 解析结果并固定一个允许的连接地址，优先使用公网地址；HTTPS 域名解析到 `198.18.0.0/15` 时可作为 Clash/Mihomo 等代理的 synthetic fake-IP 使用。字面量 `198.18/15`、其他私网/特殊地址仍默认拒绝，防止 DNS rebinding 绕过私网限制。
 - `usageBaseURL` 禁止内嵌 username/password；`Authorization`、`X-API-Key`、`API-Key` 等 header 必须由 credential ref 注入。
-- 九个端点仅接受 GET，并同时校验 peer socket 与 Host；支持 IPv4、IPv4-mapped IPv6 和 `[::1]:port`。
+- 九个数据端点仅接受 GET；OrcaRouter 集成路由的 GET 只返回布尔状态，POST 仅在用户点击后执行局部 settings mutation，并要求非简单自定义 action header。所有路由同时校验 peer socket 与 Host，支持 IPv4、IPv4-mapped IPv6 和 `[::1]:port`。
 - 用量缓存 `~/.dsh/storages/usage-stats-cache.json` 只保存聚合 Token、会话 id、不透明 revision 与折叠游标，不保存提示词、回复或文件路径。
 
 本机反向代理会让插件看到代理自身的回环地址。请勿把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。
@@ -404,7 +398,7 @@ npx --yes github:Ychris12138/dsh-usage-stats --check
 
 Token 统计值来自 `assistant/chunk` 或 `assistant/message` 中 provider-reported `usage`，不是本地估算。相同 turn/step 的后续样本会替换旧样本，并按 `provider/model` 归集。
 
-费用是明确标注的估算派生值：每个 usage 样本使用自己的事件时间、原始 provider/model 与四类 token bucket 匹配 `lib/pricing.js`；替换样本会先减去旧费用，再加入新费用。绝不会用“当前价格 × 历史累计 Token”。Current Session Pill 使用 DSH 原生 `tokenUsage` projection 触发重读，并只在 projection 与服务端 session buckets 完全一致时显示服务端事件级估算。
+费用是明确标注的估算派生值：每个 usage 样本使用自己的事件时间、原始 provider/model 与四类 token bucket 匹配 `lib/pricing.js`；替换样本会先减去旧费用，再加入新费用。绝不会用“当前价格 × 历史累计 Token”。每个 session 的派生费用继续进入 `usage.sessions`、session CSV、JSON export 与整体 billing aggregation；插件不会向 DSH composer 注入 session UI。
 
 - 活跃会话只处理新追加事件。
 - 持久化会话使用不透明 revision；未变化时不重复读取日志。
@@ -425,8 +419,10 @@ Token 统计值来自 `assistant/chunk` 或 `assistant/message` 中 provider-rep
 | `GET` | `/api/usage-stats/export/daily.csv` | secret-free daily provider/model CSV |
 | `GET` | `/api/usage-stats/export/sessions.csv` | secret-free session CSV |
 | `GET` | `/api/usage-stats/export.json` | versioned usage、budget、pricing provenance 与 account-safe JSON |
+| `GET` | `/api/usage-stats/integrations/orcarouter` | 仅返回 OrcaRouter preset 是否可写/已存在的 secret-free 布尔状态 |
+| `POST` | `/api/usage-stats/integrations/orcarouter` | 用户明确请求后，以 revision-guarded path mutation 幂等加入 preset；要求 `application/json` 与 `X-DSH-Usage-Stats-Action: add-orcarouter` |
 
-非 GET 返回 `405`，非回环请求返回 `403`。API JSON 使用 `Cache-Control: no-cache`；下载响应使用 `Cache-Control: no-store` 与固定文件名。
+除上述 OrcaRouter POST 外，非 GET 返回 `405`；非回环请求返回 `403`。API JSON 使用 `Cache-Control: no-cache`；下载响应使用 `Cache-Control: no-store` 与固定文件名。
 
 ## 开发与验证 / Development
 
@@ -448,7 +444,9 @@ node scripts/check-balance.mjs
 
 ## 兼容性与致谢 / Compatibility & credits
 
-当前 npm stable 为 `0.3.0`；`v0.3.0` 的完整发布门禁见 [`docs/release-checklist.md`](docs/release-checklist.md)，变更摘要见 [`docs/release-notes-v0.3.0.md`](docs/release-notes-v0.3.0.md)。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。
+当前 npm stable 为 `0.3.2`；`v0.3.2` 的完整发布门禁见 [`docs/release-checklist.md`](docs/release-checklist.md)，变更摘要见 [`docs/release-notes-v0.3.2.md`](docs/release-notes-v0.3.2.md)。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。
+
+`display.currentSessionPill` 作为 v0.3.0 legacy boolean 配置键继续被接受，避免旧配置导致启动失败；当前客户端不再注册任何 composer UI，因此该键不再产生可见效果。`session-context` 服务端 API 暂时保留原有响应语义，供 v0.3.0 API compatibility 与后续集成使用。
 
 - [Javis603/token-monitor](https://github.com/Javis603/token-monitor)：参考多 provider 配额归一化与 Z.ai 限额解析。
 - [xiaoqi20/dsh-opencode-go-usage](https://github.com/xiaoqi20/dsh-opencode-go-usage)：参考 DSH 凭据接入、OpenCode `auth.json` 回退与 Bearer usage endpoint。

package/SECURITY.md

@@ -12,7 +12,7 @@ Never include DeepSeek API keys, credentials files, session contents, raw logs,
 
 ## Scope
 
-Security fixes target the latest version on the default branch. The nine HTTP endpoints are designed for direct loopback use only; exposing them through a reverse proxy is outside the supported security model unless the proxy adds authentication and access control.
+Security fixes target the latest version on the default branch. The nine read-only data endpoints and the optional OrcaRouter integration route are designed for direct loopback use only; exposing them through a reverse proxy is outside the supported security model unless the proxy adds authentication and access control. The integration route's `GET` response contains only availability booleans. Its `POST` performs the user's explicit, revision-guarded `llm-pi-ai.providers.orcarouter` path mutation and additionally requires JSON plus the non-simple `X-DSH-Usage-Stats-Action: add-orcarouter` header; plugin startup never performs this write.
 
 CSV and JSON exports are fixed, versioned projections of normalized usage and account-safe metadata. They do not serialize plugin/provider configuration, credential references or values, raw upstream responses, prompts, replies, or file paths. CSV text fields are quoted and guarded against spreadsheet-formula execution; incomplete monetary derivations remain blank/null.
 

package/docs/release-checklist.md

@@ -30,8 +30,11 @@ npm pack --json
 - [ ] Confirm a valid old cache is migrated/refolded and retains exact token totals.
 - [ ] Replace the cache with malformed JSON; confirm the plugin rebuilds from authoritative session events without blocking DSH startup.
 - [ ] Confirm existing account monitors remain compatible and no new provider/monitor is inserted into user configuration.
-- [ ] Confirm `display.currentSessionPill` defaults on and `false` removes the Pill without affecting the sidebar panel.
+- [ ] Confirm legacy `display.currentSessionPill: true` and `false` configurations both start successfully and neither registers composer UI.
 - [ ] Confirm a persisted provider selection survives browser refresh and DSH restart; removing that provider clears the saved id and uses the existing fallback.
+- [ ] Confirm OrcaRouter is added only through the explicit fresh-user synthetic Add action; startup performs no settings mutation and existing provider configuration is not overwritten.
+- [ ] Confirm OrcaRouter balance succeeds through `/v1/balance` or the compatible billing fallback, pricing stays unknown/null, and no credential value reaches the browser or export payloads.
+- [ ] Confirm unchanged persisted fallback logs read only from the folded cursor, appended events remain incremental, and truncation/rewrite still refolds from sequence 0 (#58/#57).
 
 ## 4. Export and security
 
@@ -43,10 +46,19 @@ npm pack --json
 
 ## 5. Real DSH release-candidate regression
 
+### v0.3.2-specific gates
+
+- [ ] Current DSH sessions use the public `seq` / `snapshotEvents()` API; no current-session path accesses the removed `session.events` property.
+- [ ] Legacy sessions exposing `seq` plus an `events` array, but no `snapshotEvents()`, remain supported.
+- [ ] UI steady state performs zero persisted `listSnapshots`, zero persisted `readFrom`, zero unchanged aggregate rebuilds, and zero unchanged cache writes.
+- [ ] Background refresh skips `readFrom` and cache writes for unchanged revisions, uses incremental reads for changed revisions, and full-refolds truncation or rewrite cases.
+
 - [ ] Test the latest supported `@deepseek-ai/dsh` Desktop/Web release candidate with an isolated profile.
 - [ ] Confirm DSH starts without `Failed to load plugins` or loader identity errors.
-- [ ] Confirm client bundle load, sidebar entry, panel open/close, provider switching, Current Session Pill, cost/budget states, and manual Retry.
-- [ ] Test light and dark themes; confirm a missing composer mount point degrades silently.
+- [ ] Confirm client bundle load and that `sidebar.footer.action` is the only extension point registered by dsh-usage-stats; verify panel open/close, provider switching, cost/budget states, and manual Retry.
+- [ ] At 700 / 500 / 400 / 320 px, confirm dsh-usage-stats registers no `conversation.input.*` component or composer DOM and leaves native Permission / Model / Context / Submit layout untouched. Record any remaining sub-400 px overlap as DSH host behavior rather than changing host controls from this plugin.
+- [ ] Test the sidebar action and panel in light and dark themes.
+- [ ] Confirm Last 14 days token values retain an 84 px minimum width, right alignment, and tabular numerals while the date column shrinks/ellipsizes without adding narrow-panel overflow (#75).
 - [ ] With `refresh.enabled: false`, confirm one first account fetch, no expiry-driven upstream requests, manual Retry, and a fresh fetch after provider configuration changes.
 - [ ] Recheck #53 only in an available enterprise proxy environment; record evidence, but do not infer a fix without reproduction.
 - [ ] Recheck #14 with a real MiniMax Coding Plan account: both current and weekly windows plus reset information. Record the sanitized response shape if it fails.
@@ -56,8 +68,8 @@ npm pack --json
 Do not run this section until every release-candidate gate above passes and the maintainer approves preparing the release commit.
 
 - [ ] Create a release branch from the reviewed `main` at `RC_BASE_SHA`.
-- [ ] Run `npm run release:sync -- 0.3.0` once to update `package.json`, `package-lock.json`, the Community Market catalog, and documented stable-version references together.
-- [ ] Remove release-candidate wording/status from the v0.3.0 release notes.
+- [ ] Run `npm run release:sync -- 0.3.2` once to update `package.json`, `package-lock.json`, the Community Market catalog, and documented stable-version references together.
+- [ ] Confirm the v0.3.2 release notes use final stable wording, preserve the historical v0.3.0/v0.3.1 notes, and do not claim #84 fixed or include #88 behavior.
 - [ ] Run the release gates again against the synchronized version:
 
 ```bash
@@ -66,20 +78,20 @@ npm test
 npm pack --json
 ```
 
-- [ ] Inspect the final pack manifest, then commit all version/release metadata changes with `chore: prepare v0.3.0 release`.
+- [ ] Inspect the final pack manifest, then commit all version/release metadata changes with `chore: prepare v0.3.2 release`.
 - [ ] Record that commit as `RELEASE_SHA`; this replaces `RC_BASE_SHA` as the only publish/tag identity.
 - [ ] Confirm the working tree is clean and `HEAD` equals `RELEASE_SHA`.
 - [ ] Confirm the committed package version, not merely the working-tree version:
 
 ```bash
-test "$(git show "$RELEASE_SHA:package.json" | jq -r .version)" = "0.3.0"
+test "$(git show "$RELEASE_SHA:package.json" | jq -r .version)" = "0.3.2"
 ```
 
 The release invariant is:
 
 ```text
 npm published source commit
-== v0.3.0 tag commit
+== v0.3.2 tag commit
 == GitHub Release commit
 == package/catalog version commit
 == RELEASE_SHA
@@ -93,14 +105,14 @@ Do not run this section until the immutable release commit exists and the mainta
 - [ ] From a clean checkout/worktree at exactly `RELEASE_SHA`, run `npm publish --access public --registry=https://registry.npmjs.org/`.
 - [ ] `npm view "@ychris12138/dsh-usage-stats" version --registry=https://registry.npmjs.org/` equals the target version.
 - [ ] Merge or push the release commit to `main` according to the chosen branch workflow; verify `main` contains the exact `RELEASE_SHA` without recreating the release changes.
-- [ ] Only after npm and `main` verification: create the signed/annotated `v0.3.0` tag pointing explicitly to `RELEASE_SHA`.
+- [ ] Only after npm and `main` verification: create the signed/annotated `v0.3.2` tag pointing explicitly to `RELEASE_SHA`.
 - [ ] Verify the tag resolves to the published source commit:
 
 ```bash
-test "$(git rev-parse v0.3.0^{commit})" = "$RELEASE_SHA"
+test "$(git rev-parse v0.3.2^{commit})" = "$RELEASE_SHA"
 ```
 
-- [ ] Create the GitHub Release from `v0.3.0`; verify it resolves to `RELEASE_SHA`.
+- [ ] Create the GitHub Release from `v0.3.2`; verify it resolves to `RELEASE_SHA`.
 - [ ] Verify the public Pages `catalog-source.json` and `/v1/plugins` response content type, package name, and exact version.
 - [ ] Install the exact npm version through DSH Desktop Community Market and restart the host.
 - [ ] Close the npm/market release issue only after the Desktop Market installation succeeds.

package/docs/release-notes-v0.3.1.md

@@ -0,0 +1,40 @@
+# v0.3.1 release notes
+
+`v0.3.1` is a small maintenance release focused on an optional OrcaRouter integration, lower UI intrusion, and two focused correctness and usability fixes.
+
+## Highlights
+
+### OrcaRouter optional integration
+
+- Adds an optional, explicit OrcaRouter provider preset with `orcarouter/auto`.
+- Never mutates settings at startup and never embeds or stores an API key value.
+- Fresh installations expose a user-triggered Add flow; existing OrcaRouter provider settings remain untouched.
+- Reads current wallet data from `/v1/balance`, with the compatible billing-summary fallback retained for older deployments.
+- Includes paid, free, and promotional credit only when the upstream response provides valid values.
+- Keeps OrcaRouter pricing unknown (`null`): an OrcaRouter route never inherits DeepSeek, OpenAI, or another upstream provider's prices.
+- Keeps the sponsored-integration disclosure compact in the README and provider selector.
+
+### Sidebar-only UI
+
+- Removes all dsh-usage-stats components from `conversation.input.*` and the composer toolbar. Permission, Model, Context, and Submit remain entirely host-owned.
+- Keeps Usage Stats available through `sidebar.footer.action` and the existing sidebar panel.
+- Continues to accept legacy `display.currentSessionPill: true` and `false` configuration for compatibility; the setting is now a no-op and renders no composer UI.
+
+### Persisted-session fallback performance
+
+- Fixes #57 through #58: unchanged persisted fallback logs no longer refold from sequence 0.
+- Keeps appended events incremental.
+- Still detects truncation or rewrite and performs the required full refold.
+
+### Recent usage list polish
+
+- Fixes #75 by right-aligning Last 14 days token values.
+- Lets the date column shrink and ellipsize in narrow panels instead of forcing a fixed width.
+
+## Compatibility and non-features
+
+- No OrcaRouter automatic pricing and no second pricing engine.
+- No new client polling loop and no composer UI.
+- No #84 quota-precision behavior change is claimed in this release; #84 remains open for clarification and retesting.
+- No client price table, fallback unknown-model pricing, Beijing-tariff recomputation, independent account polling, or blended-price sidebar logic from #88 is included.
+- No changes to historical pricing semantics and no credential migration.

package/docs/release-notes-v0.3.2.md

@@ -0,0 +1,36 @@
+# v0.3.2 release notes
+
+`v0.3.2` is a focused maintenance release for current DSH session compatibility and lower steady-state usage aggregation overhead.
+
+## Highlights
+
+### Current DSH Session API compatibility
+
+- Fixes #95 for DSH builds where the public `Session.events` array has been replaced by `seq` and `snapshotEvents()`.
+- Current DSH sessions now use the formal `seq` / `snapshotEvents(fromSeq)` API and continue folding only the live event tail.
+- Older DSH session objects without `snapshotEvents()` retain the legacy `events` fallback.
+- Compatibility is capability-based rather than tied to a DSH version string.
+- Preserves live-log shrink recovery and conservative live/persisted refolding semantics.
+
+### Lower usage polling overhead
+
+- Fixes #94 by separating high-frequency UI usage reads from persisted archive refreshes.
+- Ordinary `/usage` requests fold live-session tails and reuse cached persisted aggregates instead of enumerating every archived session.
+- Persisted archive scanning remains on the existing background refresh path and explicit export paths.
+- Unchanged collections no longer rebuild global aggregates or rewrite `usage-stats-cache.json`.
+- Persisted sessions with unchanged revision tokens perform no event reads.
+- A changed persisted revision still uses the existing incremental cursor logic, with full refolding retained for truncation or rewrite recovery.
+- Scan-mode single-flight guarantees that a required full persisted refresh cannot be satisfied accidentally by an in-flight live-only request.
+
+## Compatibility and non-features
+
+- No frontend polling interval change and no additional timer or polling loop.
+- No pricing-rule or billing-semantics changes.
+- Pricing/provider fingerprint changes still invalidate and persist derived billing state safely.
+- No private JSONL/zstd reader or plugin-owned persistence index.
+- No attempt to optimize live-to-persisted transitions by trusting the previous live fold.
+- No DSH `sessionProjectionCache` migration or modification.
+- No cold-session eviction or bounded-cache redesign.
+- No provider or composer UI changes.
+- No #84 quota-precision change and no #93 feature work is included in this release.
+- JSONL suffix reads remain an upstream DSH concern; a changed large archive may still require the host persistence backend to decode more data than the logical suffix.

package/lib/accounts.js

@@ -42,6 +42,7 @@ const OFFICIAL_ADAPTERS = new Set([
 	"openrouter-balance",
 	"moonshot-balance",
 	"zai-balance",
+	"orcarouter-balance",
 	"opencode-go",
 	"zai-token-plan",
 	"kimi-token-plan",
@@ -92,6 +93,7 @@ const ADAPTERS = new Set([
 	"openrouter-balance",
 	"moonshot-balance",
 	"zai-balance",
+	"orcarouter-balance",
 	"general",
 	"new-api",
 	"sub2api",
@@ -733,7 +735,7 @@ async function queryBuiltInBalance(spec, credential, deps, now) {
 		...(used === null ? {} : { used }),
 		...(total === null ? {} : { total }),
 		currency: nonEmptyString(raw.currency) ?? "USD",
-		unlimited: false,
+		unlimited: raw.unlimited === true,
 		expiresAt: null,
 		available: raw.isAvailable !== false,
 		breakdown: {

package/lib/balance.js

@@ -47,6 +47,28 @@ const SCHEMES = {
 			};
 		}
 	},
+	/** OrcaRouter: wallet balance with an OpenAI-compatible billing fallback. */
+	orcarouter: {
+		// OrcaRouter exposes these endpoints under the public /v1 prefix. Keep the
+		// configured origin/path so the normal pinned-network policy still applies
+		// and a provider profile never causes a cross-origin request.
+		balanceURL: (baseURL) => orcaBillingURL(baseURL, "/balance"),
+		subscriptionURL: (baseURL) => orcaBillingURL(baseURL, "/dashboard/billing/subscription"),
+		usageURL: (baseURL) => orcaBillingURL(baseURL, "/dashboard/billing/usage"),
+		query: async (baseURL, apiKey, timeoutMs, fetchImpl) => {
+			// Current deployments expose the wallet's paid/free/promo balance. Older
+			// deployments may not have it, so retain the documented OpenAI-shaped
+			// subscription + usage fallback for compatibility.
+			try {
+				return parseOrcaRouterWallet(await requestJSON(orcaBillingURL(baseURL, "/balance"), apiKey, timeoutMs, fetchImpl));
+			} catch (error) {
+				if (error?.providerStatus !== "unsupported") throw error;
+			}
+			const subscription = await requestJSON(orcaBillingURL(baseURL, "/dashboard/billing/subscription"), apiKey, timeoutMs, fetchImpl);
+			const usage = await requestJSON(orcaBillingURL(baseURL, "/dashboard/billing/usage"), apiKey, timeoutMs, fetchImpl);
+			return parseOrcaRouter(subscription, usage);
+		}
+	},
 	/** Moonshot / Kimi: GET {origin}/v1/users/me/balance — available/cash/voucher. */
 	moonshot: {
 		url: (baseURL) => new URL("/v1/users/me/balance", baseURL).href,
@@ -82,6 +104,74 @@ const SCHEMES = {
 	}
 };
 
+function orcaBillingURL(baseURL, path) {
+	const base = new URL(baseURL);
+	const pathname = base.pathname.replace(/\/+$/, "");
+	const prefix = pathname === "" ? "/v1" : pathname.endsWith("/v1") ? pathname : `${pathname}/v1`;
+	return new URL(`${prefix}${path}`, base.origin).href;
+}
+
+function parseOrcaRouter(subscription, usage) {
+	const total = numberOrNull(subscription?.hard_limit_usd ?? subscription?.soft_limit_usd);
+	// OpenAI-compatible dashboard usage is reported in cents. Keep the unit
+	// conversion in this adapter so `remaining`, `used`, and `limit` share one
+	// consistent currency basis.
+	const usageCents = numberOrNull(usage?.total_usage);
+	if (total === null || usageCents === null || total < 0 || usageCents < 0) {
+		throw providerError("invalid-response", "OrcaRouter billing response is missing numeric quota data");
+	}
+	const used = usageCents / 100;
+	const unlimited = total === 100000000
+		&& numberOrNull(subscription?.soft_limit_usd) === total
+		&& numberOrNull(subscription?.system_hard_limit_usd) === total;
+	return {
+		isAvailable: unlimited || total - used > 0,
+		currency: "USD",
+		total: unlimited ? total : total - used,
+		used,
+		limit: unlimited ? void 0 : total,
+		unlimited,
+		granted: void 0,
+		toppedUp: void 0
+	};
+}
+
+function creditArrayTotal(value, currency, label) {
+	if (value === void 0 || value === null) return 0;
+	if (!Array.isArray(value)) throw providerError("invalid-response", `OrcaRouter ${label} credits are invalid`);
+	let total = 0;
+	for (const entry of value) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw providerError("invalid-response", `OrcaRouter ${label} credits are invalid`);
+		const entryCurrency = typeof entry.unit === "string" && entry.unit.trim() !== "" ? entry.unit.trim().toUpperCase() : currency;
+		if (entryCurrency !== currency) throw providerError("invalid-response", `OrcaRouter ${label} credits use a different currency`);
+		const amount = numberOrNull(entry.balance_usd ?? entry.balance);
+		if (amount === null || amount < 0) throw providerError("invalid-response", `OrcaRouter ${label} credits are missing a numeric balance`);
+		total += amount;
+	}
+	return total;
+}
+
+function parseOrcaRouterWallet(body) {
+	if (body === null || typeof body !== "object" || Array.isArray(body)) throw providerError("invalid-response", "OrcaRouter wallet response is invalid");
+	const currency = typeof body.unit === "string" && body.unit.trim() !== "" ? body.unit.trim().toUpperCase() : null;
+	if (currency === null) throw providerError("invalid-response", "OrcaRouter wallet response is missing currency");
+	const paid = numberOrNull(body.paid_balance);
+	if (paid === null || paid < 0) throw providerError("invalid-response", "OrcaRouter wallet response is missing paid balance");
+	const remaining = paid
+		+ creditArrayTotal(body.free_credit, currency, "free")
+		+ creditArrayTotal(body.promo_credits, currency, "promo");
+	return {
+		isAvailable: remaining > 0,
+		currency,
+		total: remaining,
+		used: void 0,
+		limit: void 0,
+		unlimited: false,
+		granted: void 0,
+		toppedUp: void 0
+	};
+}
+
 function providerError(status, message, httpStatus) {
 	const error = new Error(message);
 	error.providerStatus = status;
@@ -92,30 +182,43 @@ function providerError(status, message, httpStatus) {
 function responseStatus(status) {
 	if (status === 401 || status === 403) return "unauthorized";
 	if (status === 429) return "rate-limited";
+	if (status === 404 || status === 405) return "unsupported";
 	return status >= 500 ? "unavailable" : "invalid-response";
 }
 
-/** Map a provider id (dsh adapter id or pi-ai route) to a balance scheme id. */
-export function balanceSchemeOf(providerId) {
-	return balanceSchemeForProviderId(providerId);
+function numberOrNull(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return null;
 }
 
-/** Query one provider's balance. Throws on transport/HTTP errors. */
-export async function queryBalance(scheme, baseURL, apiKey, timeoutMs = 15000, fetchImpl = fetch) {
-	const spec = SCHEMES[scheme];
-	if (spec === void 0) throw new Error(`no balance scheme "${scheme}"`);
-	const response = await fetchImpl(spec.url(baseURL), {
-		headers: { authorization: `Bearer ${apiKey}` },
+async function requestJSON(url, apiKey, timeoutMs, fetchImpl) {
+	const response = await fetchImpl(url, {
+		headers: { authorization: `Bearer ${apiKey}`, accept: "application/json" },
 		signal: AbortSignal.timeout(timeoutMs)
 	});
 	if (!response.ok) throw providerError(responseStatus(response.status), `balance API returned HTTP ${response.status}`, response.status);
-	let body;
 	try {
-		body = await response.json();
+		return await response.json();
 	} catch {
 		throw providerError("invalid-response", "balance API returned invalid JSON");
 	}
-	return spec.parse(body);
+}
+
+/** Map a provider id (dsh adapter id or pi-ai route) to a balance scheme id. */
+export function balanceSchemeOf(providerId) {
+	return balanceSchemeForProviderId(providerId);
+}
+
+/** Query one provider's balance. Throws on transport/HTTP errors. */
+export async function queryBalance(scheme, baseURL, apiKey, timeoutMs = 15000, fetchImpl = fetch) {
+	const spec = SCHEMES[scheme];
+	if (spec === void 0) throw new Error(`no balance scheme "${scheme}"`);
+	if (typeof spec.query === "function") return spec.query(baseURL, apiKey, timeoutMs, fetchImpl);
+	return spec.parse(await requestJSON(spec.url(baseURL), apiKey, timeoutMs, fetchImpl));
 }
 
 /** Scheme ids with built-in support (for docs/tests). */