@leo000001/opencode-quota-sidebar 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+## Unreleased
+
+### Features
+
+- Refactor quota provider handling to an adapter registry (`src/providers/*`), so adding a new provider no longer requires editing core dispatch code.
+- Add RightCode provider support (`https://www.right.codes/account/summary`) with baseURL-based matching.
+- RightCode subscription display now uses daily quota logic and ignores tiny plans (`total_quota < 10`); when not matched, falls back to account balance.
+
+### UX
+
+- Merge Reasoning tokens into Output across sidebar, toast, and markdown report.
+- Sidebar quota windows now support indented multiline layout with compact reset time (`Rst HH:MM` / `Rst MM-DD`).
+- Toast now includes a dedicated `Cost as API` section with per-provider equivalent API cost.
+- Quota rendering now de-duplicates provider snapshots before output (prevents duplicate RightCode lines).
+- Remove `sidebar.maxQuotaProviders` config (unused in current design).
+
+### Bug Fixes
+
+- Invalidate stale RightCode cache entries that still use old non-daily window formats (auto-refetch on next render).
+
+### Bug Fixes (Critical)
+
+- H1: Fix `saveState` empty dirty keys triggering full writeAll on every save.
+- H2: Fix `persistState` dirty-key race condition — delete captured keys instead of clearing the whole set.
+- H3: Fix `pendingAppliedTitle` TTL corruption — detect decorated titles to prevent double-decoration; increase TTL to 15s.
+- H4: Fix `updateAuth` silently dropping token persistence — log and return error snapshot on failure.
+- H5: Add per-session concurrency lock for `applyTitle` to prevent conflicting concurrent updates.
+
+### Bug Fixes (Medium)
+
+- M1: `refreshTimer` entries are now cleaned up when timers fire.
+- M2: Sessions older than `retentionDays` (default 730 days) are evicted from memory on startup.
+- M3: v1→v2 migration now recovers `createdAt` from v1 data when available.
+- M4: State and chunk file writes are now atomic (write to temp + rename).
+- M5: `flushSave` now flushes current dirty keys even when no timer is pending.
+- M6: `shortNumber` now handles negative, NaN, and Infinity values gracefully.
+- M7: `dateKeysInRange` is capped at 400 iterations to prevent runaway loops.
+- M8: Deduplicated `isRecord`/`asNumber`/`asBoolean` into shared `helpers.ts`.
+- M9: `scanSessionsByCreatedRange` now prefers in-memory state over disk reads.
+- M10: `summarizeRangeUsage` now fetches session messages in parallel (concurrency 5).
+- M11: `saveState` now only iterates sessions belonging to dirty date keys.
+- M12: Removed double timestamp normalization in `dateKeyFromTimestamp`.
+
+### Performance
+
+- P1: Incremental usage aggregation — tracks last processed message cursor per session.
+- P2: LRU chunk cache (64 entries) for loaded day chunks.
+- P3: `restoreAllVisibleTitles` limited to concurrency 5.
+- P4: `sessionDateMap` dirty tracking integrated with chunk-level dirty keys.
+
+### Security
+
+- S1: Replaced 15+ silent `.catch(() => undefined)` with debug-mode logging via `swallow()`.
+- S2: Added screen-sharing privacy warning to README.
+- S3: State file writes now refuse to follow symlinks.
+- S4: Renamed `OPENCODE_TEST_HOME` env var to `OPENCODE_QUOTA_DATA_HOME`.
+
+### Open-Source Prep
+
+- O1: Added `repository`, `homepage`, `bugs`, `author` to package.json; moved SDK deps to `peerDependencies`.
+- O2: Added `*.tsbuildinfo`, `.DS_Store`, `coverage/`, `.env` to `.gitignore`.
+- O3: README config example now includes `sidebar.enabled` and `retentionDays`.
+- O4: Added unit tests for helpers, storage, and usage modules.
+- O5: Main entry now exports consumer types (`QuotaSidebarConfig`, `QuotaSnapshot`, etc.).
+
+## 0.1.0
+
+- Initial release.

package/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing
+
+Thanks for contributing to opencode-quota-sidebar.
+
+The plugin now uses a provider adapter registry, so adding a new provider does not require editing core dispatch logic.
+
+## Architecture overview
+
+- Provider adapters live in `src/providers/`
+- Built-in adapters live in `src/providers/core/`
+- Third-party/community adapters live in `src/providers/third_party/`
+- `src/providers/registry.ts` resolves which adapter handles a provider
+- `src/quota.ts` provides `createQuotaRuntime()`; runtime methods delegate to resolved adapter and manage auth/cache glue
+- `src/format.ts` renders generic sidebar/report output from `QuotaSnapshot`
+
+## Add a new provider
+
+### 1) Create an adapter file
+
+Add `src/providers/third_party/<your-provider>.ts` and implement `QuotaProviderAdapter`.
+
+Minimal shape:
+
+```ts
+import type { QuotaProviderAdapter } from './types.js'
+
+export const myProviderAdapter: QuotaProviderAdapter = {
+  id: 'my-provider',
+  label: 'My Provider',
+  shortLabel: 'MyProv',
+  sortOrder: 40,
+  matchScore: ({ providerID, providerOptions }) => {
+    if (providerID === 'my-provider') return 80
+    if (providerOptions?.baseURL === 'https://api.example.com') return 100
+    return 0
+  },
+  isEnabled: (config) =>
+    config.quota.providers?.['my-provider']?.enabled ?? true,
+  fetch: async ({ providerID, auth, config }) => {
+    const checkedAt = Date.now()
+    // ... call endpoint, parse payload, return QuotaSnapshot
+    return {
+      providerID,
+      adapterID: 'my-provider',
+      label: 'My Provider',
+      shortLabel: 'MyProv',
+      sortOrder: 40,
+      status: 'ok',
+      checkedAt,
+      remainingPercent: 80,
+    }
+  },
+}
+```
+
+### 2) Register the adapter
+
+Edit `src/providers/index.ts` and add `registry.register(myProviderAdapter)`.
+
+If your provider has ID variants, implement `normalizeID` in the adapter.
+
+### 3) Optional config toggle
+
+Add to user config:
+
+```json
+{
+  "quota": {
+    "providers": {
+      "my-provider": { "enabled": true }
+    }
+  }
+}
+```
+
+### 4) Add tests
+
+At minimum:
+
+- adapter selection (`matchScore`)
+- successful response parsing
+- error/unavailable paths
+- format output if using special fields (e.g. `balance`)
+
+## QuotaSnapshot rules
+
+- Always fill `status` (`ok`, `error`, `unavailable`, `unsupported`)
+- Keep `providerID` as runtime provider identity
+- Set `adapterID`, `label`, `shortLabel`, `sortOrder`
+- Use `windows` for percent-based quota windows
+- Use `balance` for balance-based providers
+- Never throw in adapter `fetch`; return an error snapshot instead
+
+## Development workflow
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Both build and tests must pass before submitting a PR.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The opencode-quota-sidebar 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.

package/README.md

@@ -0,0 +1,216 @@
+# opencode-quota-sidebar
+
+OpenCode plugin: show token usage and subscription quota in the session sidebar title.
+
+## Install
+
+Add the package name to `plugin` in your `opencode.json`. OpenCode uses Bun to install it automatically on startup:
+
+```json
+{
+  "plugin": ["@leo000001/opencode-quota-sidebar"]
+}
+```
+
+## Development (build from source)
+
+```bash
+npm install
+npm run build
+```
+
+Add the built file to your `opencode.json`:
+
+```json
+{
+  "plugin": ["file:///ABSOLUTE/PATH/opencode-quota-sidebar/dist/index.js"]
+}
+```
+
+## Supported quota providers
+
+| Provider       | Endpoint                               | Auth            | Status                                 |
+| -------------- | -------------------------------------- | --------------- | -------------------------------------- |
+| OpenAI Codex   | `chatgpt.com/backend-api/wham/usage`   | OAuth (ChatGPT) | Multi-window (short-term + weekly)     |
+| GitHub Copilot | `api.github.com/copilot_internal/user` | OAuth           | Monthly quota                          |
+| RightCode      | `www.right.codes/account/summary`      | API key         | Subscription or balance (by prefix)    |
+| Anthropic      | —                                      | —               | Unsupported (no public quota endpoint) |
+
+Want to add support for another provider (Google Antigravity, Zhipu AI, Firmware AI, etc.)? See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Features
+
+- Session title becomes multiline in sidebar:
+  - line 1: original session title
+  - line 2: Input/Output tokens
+  - line 3: Cache Read tokens (only if non-zero)
+  - line 4: Cache Write tokens (only if non-zero)
+  - line 5: `$X.XX as API cost` (equivalent API billing for subscription-auth providers)
+  - quota lines: quota text like `OpenAI 5h 80% Rst 16:20`, with multi-window continuation lines indented (e.g. `       Weekly 70% Rst 03-01`)
+  - RightCode daily quota shows `$remaining/$dailyTotal` + expiry (e.g. `RC Daily $105/$60 Exp 02-27`, without trailing percent) and also shows balance on the next indented line when available
+- Toast message includes three sections: `Token Usage`, `Cost as API` (per provider), and `Quota`
+- Quota snapshots are de-duplicated before rendering to avoid repeated provider lines
+- Custom tools:
+  - `quota_summary` — generate usage report for session/day/week/month (markdown + toast)
+  - `quota_show` — toggle sidebar title display on/off (state persists across sessions)
+- Quota connectors:
+  - OpenAI Codex OAuth (`/backend-api/wham/usage`)
+  - GitHub Copilot OAuth (`/copilot_internal/user`)
+  - RightCode API key (`/account/summary`)
+  - Anthropic: currently marked unsupported (no public quota endpoint)
+- OpenAI OAuth quota checks auto-refresh expired access token (using refresh token)
+- API key providers still show usage aggregation (quota only applies to subscription providers)
+- Incremental usage aggregation — only processes new messages since last cursor
+- Sidebar token units are adaptive (`k`/`m` with one decimal where applicable)
+
+## Storage layout (v2)
+
+The plugin stores lightweight global state and date-partitioned session chunks.
+
+- Global metadata: `<opencode-data>/quota-sidebar.state.json`
+  - `titleEnabled`
+  - `sessionDateMap` (sessionID -> `YYYY-MM-DD`)
+  - `quotaCache`
+- Session chunks: `<opencode-data>/quota-sidebar-sessions/YYYY/MM/DD.json`
+  - per-session title state (`baseTitle`, `lastAppliedTitle`)
+  - `createdAt`
+  - cached usage summary used by `quota_summary`
+  - incremental aggregation cursor
+
+Example tree:
+
+```text
+~/.local/share/opencode/
+  quota-sidebar.state.json
+  quota-sidebar-sessions/
+    2026/
+      02/
+        23.json
+        24.json
+```
+
+This replaces the old fixed-entry cap approach. `quota_summary` now scans date chunks
+for day/week/month ranges by session creation date.
+
+Sessions older than `retentionDays` (default 730 days / 2 years) are evicted from
+memory on startup. Chunk files remain on disk for historical range scans.
+
+## Migration from v1
+
+If an old `quota-sidebar.state.json` exists (`version: 1`), the plugin migrates it
+to `version: 2` automatically on load and then persists data in the new chunked layout.
+
+On Windows, use forward slashes: `"file:///D:/Lab/opencode-quota-sidebar/dist/index.js"`
+
+## Compatibility
+
+- Node.js: >= 18 (for `fetch` + `AbortController`)
+- OpenCode: plugin SDK `@opencode-ai/plugin` ^1.2.10
+
+## Optional commands
+
+You can add these command templates in `opencode.json` so you can run `/qday`, `/qweek`, `/qmonth`, `/qtoggle`:
+
+```json
+{
+  "command": {
+    "qday": {
+      "description": "Show today's usage and quota",
+      "template": "Call tool quota_summary with period=day and toast=true."
+    },
+    "qweek": {
+      "description": "Show this week's usage and quota",
+      "template": "Call tool quota_summary with period=week and toast=true."
+    },
+    "qmonth": {
+      "description": "Show this month's usage and quota",
+      "template": "Call tool quota_summary with period=month and toast=true."
+    },
+    "qtoggle": {
+      "description": "Toggle sidebar usage display on/off",
+      "template": "Call tool quota_show (no arguments, it toggles)."
+    }
+  }
+}
+```
+
+## Optional project config
+
+Create `quota-sidebar.config.json` under your project root:
+
+```json
+{
+  "sidebar": {
+    "enabled": true,
+    "width": 36,
+    "showCost": true,
+    "showQuota": true
+  },
+  "quota": {
+    "refreshMs": 300000,
+    "includeOpenAI": true,
+    "includeCopilot": true,
+    "includeAnthropic": true,
+    "providers": {
+      "rightcode": {
+        "enabled": true
+      }
+    },
+    "refreshAccessToken": false,
+    "requestTimeoutMs": 8000
+  },
+  "toast": {
+    "durationMs": 12000
+  },
+  "retentionDays": 730
+}
+```
+
+Notes:
+
+- `sidebar.showCost` controls API-cost visibility in sidebar title, `quota_summary` markdown report, and toast message.
+- `output` now includes reasoning tokens. Reasoning is no longer rendered as a separate line.
+- API cost excludes reasoning tokens from output billing (uses `tokens.output` only for output-price multiplication).
+- `quota.providers` is the extensible per-adapter switch map.
+- If API Cost is `$0.00`, it usually means the model/provider has no pricing mapping in OpenCode at the moment, so equivalent API cost cannot be estimated.
+
+## Debug logging
+
+Set `OPENCODE_QUOTA_DEBUG=1` to enable debug logging to stderr. This logs:
+
+- Chunk I/O operations
+- Auth refresh attempts and failures
+- Session eviction counts
+- Symlink write refusals
+
+## Independent repository
+
+This folder is initialized as its own git repository.
+
+## Security & privacy notes
+
+- The plugin reads OpenCode credentials from `<opencode-data>/auth.json`.
+- If enabled, quota checks call external endpoints:
+  - OpenAI Codex: `https://chatgpt.com/backend-api/wham/usage`
+  - GitHub Copilot: `https://api.github.com/copilot_internal/user`
+  - RightCode: `https://www.right.codes/account/summary`
+- **Screen-sharing warning**: Session titles and toasts surface usage/quota
+  information. If you are screen-sharing or recording, consider toggling the
+  sidebar display off (`/qtoggle` or `quota_show` tool) to avoid leaking
+  subscription details.
+- State is persisted under `<opencode-data>/quota-sidebar.state.json` and
+  `<opencode-data>/quota-sidebar-sessions/` (see Storage layout).
+- OpenAI OAuth token refresh is disabled by default; set
+  `quota.refreshAccessToken=true` if you want the plugin to refresh access
+  tokens when expired.
+- State file writes refuse to follow symlinks to prevent symlink attacks.
+- The `OPENCODE_QUOTA_DATA_HOME` env var can override the home directory for
+  testing; do not set this in production.
+
+## Contributing
+
+Contributions are welcome — especially new quota provider connectors. See [CONTRIBUTING.md](CONTRIBUTING.md) for a step-by-step guide on adding support for a new provider.
+
+## License
+
+MIT. See `LICENSE`.

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security issue in this project, please do not open a public issue first.
+
+Use one of these channels:
+
+1. GitHub Security Advisory (preferred)
+2. Open a private report to repository maintainers
+
+Please include:
+
+- affected version
+- impact and attack scenario
+- minimal reproduction steps
+- suggested fix (if available)
+
+We will acknowledge reports as quickly as possible and provide a remediation timeline.
+
+## Security Notes for Contributors
+
+- Never commit real tokens, API keys, or auth snapshots.
+- This plugin reads credentials from OpenCode local auth storage; treat all auth data as sensitive.
+- Keep debug logs free of secrets.
+- Prefer fail-closed behavior for writes (already enforced via symlink checks and atomic writes).

package/dist/cache.d.ts

@@ -0,0 +1,6 @@
+export declare class TtlValueCache<T> {
+    private entry;
+    get(now?: number): T | undefined;
+    set(value: T, ttlMs: number, now?: number): T;
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,22 @@
+export class TtlValueCache {
+    entry;
+    get(now = Date.now()) {
+        if (!this.entry)
+            return undefined;
+        if (this.entry.expiresAt <= now) {
+            this.entry = undefined;
+            return undefined;
+        }
+        return this.entry.value;
+    }
+    set(value, ttlMs, now = Date.now()) {
+        this.entry = {
+            value,
+            expiresAt: now + Math.max(0, ttlMs),
+        };
+        return value;
+    }
+    clear() {
+        this.entry = undefined;
+    }
+}

package/dist/cost.d.ts

@@ -0,0 +1,13 @@
+import type { AssistantMessage } from '@opencode-ai/sdk';
+export declare const SUBSCRIPTION_API_COST_PROVIDERS: Set<string>;
+export declare function canonicalApiCostProviderID(providerID: string): string;
+export type ModelCostRates = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
+export declare function modelCostKey(providerID: string, modelID: string): string;
+export declare function parseModelCostRates(value: unknown): ModelCostRates | undefined;
+export declare function guessModelCostDivisor(rates: ModelCostRates): 1 | 1000000;
+export declare function calcEquivalentApiCostForMessage(message: AssistantMessage, rates: ModelCostRates): number;

package/dist/cost.js

@@ -0,0 +1,76 @@
+import { asNumber, isRecord } from './helpers.js';
+export const SUBSCRIPTION_API_COST_PROVIDERS = new Set(['openai', 'anthropic']);
+function normalizeKnownProviderID(providerID) {
+    if (providerID.startsWith('github-copilot'))
+        return 'github-copilot';
+    return providerID;
+}
+export function canonicalApiCostProviderID(providerID) {
+    const normalized = normalizeKnownProviderID(providerID);
+    if (SUBSCRIPTION_API_COST_PROVIDERS.has(normalized))
+        return normalized;
+    const lowered = providerID.toLowerCase();
+    if (lowered.includes('copilot'))
+        return 'github-copilot';
+    if (lowered.includes('openai') || lowered.endsWith('-oai'))
+        return 'openai';
+    if (lowered.includes('anthropic') || lowered.includes('claude')) {
+        return 'anthropic';
+    }
+    return normalized;
+}
+export function modelCostKey(providerID, modelID) {
+    return `${providerID}:${modelID}`;
+}
+export function parseModelCostRates(value) {
+    if (!isRecord(value))
+        return undefined;
+    const readRate = (input) => {
+        if (typeof input === 'number')
+            return input;
+        if (typeof input === 'string') {
+            const parsed = Number(input);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }
+        if (isRecord(input)) {
+            return asNumber(input.usd, asNumber(input.value, asNumber(input.per_1m, asNumber(input.per1m, asNumber(input.per_token, asNumber(input.perToken, 0))))));
+        }
+        return 0;
+    };
+    const cache = isRecord(value.cache) ? value.cache : undefined;
+    const input = readRate(value.input ?? value.prompt);
+    const output = readRate(value.output ?? value.completion);
+    const cacheRead = readRate(value.cache_read ?? cache?.read);
+    const cacheWrite = readRate(value.cache_write ?? cache?.write);
+    if (input <= 0 && output <= 0 && cacheRead <= 0 && cacheWrite <= 0) {
+        return undefined;
+    }
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+    };
+}
+const MODEL_COST_DIVISOR_PER_TOKEN = 1;
+const MODEL_COST_DIVISOR_PER_MILLION = 1_000_000;
+export function guessModelCostDivisor(rates) {
+    // OpenCode provider pricing units can differ:
+    // - some providers expose USD per token (e.g. 0.0000025)
+    // - others expose USD per 1M tokens (e.g. 2.5)
+    // Heuristic: treat values > 0.001 as "per 1M".
+    const maxRate = Math.max(rates.input, rates.output, rates.cacheRead, rates.cacheWrite);
+    return maxRate > 0.001
+        ? MODEL_COST_DIVISOR_PER_MILLION
+        : MODEL_COST_DIVISOR_PER_TOKEN;
+}
+export function calcEquivalentApiCostForMessage(message, rates) {
+    const rawCost = message.tokens.input * rates.input +
+        // API cost intentionally excludes reasoning tokens.
+        message.tokens.output * rates.output +
+        message.tokens.cache.read * rates.cacheRead +
+        message.tokens.cache.write * rates.cacheWrite;
+    const divisor = guessModelCostDivisor(rates);
+    const normalized = rawCost / divisor;
+    return Number.isFinite(normalized) && normalized > 0 ? normalized : 0;
+}

package/dist/format.d.ts

@@ -0,0 +1,21 @@
+import type { QuotaSidebarConfig, QuotaSnapshot } from './types.js';
+import type { UsageSummary } from './usage.js';
+/**
+ * Render sidebar title with multi-line token breakdown.
+ *
+ * Layout:
+ *   Session title
+ *   Input 18.9k  Output 53
+ *   Cache Read 1.5k           (only if read > 0)
+ *   Cache Write 200           (only if write > 0)
+ *   $3.81 as API cost         (only if showCost=true)
+ *   OpenAI Remaining 78%      (only if quota available)
+ */
+export declare function renderSidebarTitle(baseTitle: string, usage: UsageSummary, quotas: QuotaSnapshot[], config: QuotaSidebarConfig): string;
+export declare function renderMarkdownReport(period: string, usage: UsageSummary, quotas: QuotaSnapshot[], options?: {
+    showCost?: boolean;
+}): string;
+export declare function renderToastMessage(period: string, usage: UsageSummary, quotas: QuotaSnapshot[], options?: {
+    showCost?: boolean;
+    width?: number;
+}): string;