Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ pi install /path/to/pi-subscription-usage
Sign in through `/login` as described above, then select a model from that provider. From then on:

- The footer status bar shows the active quota windows and refreshes after each turn and every 5 minutes (using a 5-minute cache).
- Running `/usage` always fetches fresh data for the active provider and shows progress bars, reset times (`MM/DD HH:mm`), and account details.
- Running `/usage` always fetches fresh data for the active provider and shows progress bars, reset times (`MM/DD HH:mm`), and account details. With [`showAllProviders`](#configuration) it also lists the other signed-in providers.
- Claude is the exception: its quota is never fetched, only read from Claude Code's responses (see [Claude (Claude Code)](#claude-claude-code)).

### Reset Credits (OpenAI and Codex)
Expand All @@ -121,23 +121,31 @@ When your OpenAI or Codex account has redeemable rate-limit reset tickets, `/usa
- Before redeeming, the extension checks that the active model and account have not changed and that the runtime token matches Pi's stored OAuth login.
- In OpenAI mode, a ticket resets server-defined account windows rather than specifically clearing the current app's limits.
- Redeeming a reset ticket is the only write operation in this extension.
- Set [`offerResetCredits`](#configuration) to `false` to skip the offer; the account still lists how many tickets it has.

## Configuration

Percentages show remaining quota by default. To show used quota instead, create `~/.pi/agent/subscription-usage.json` (global) or `.pi/subscription-usage.json` (trusted project override):
Create `~/.pi/agent/subscription-usage.json` (global) or `.pi/subscription-usage.json` (trusted project override). Run `/reload` after changing it.

| Key | Value | Description |
| --- | --- | --- |
| `displayMode` | `"remaining"` (default) or `"used"` | Whether percentages show remaining or used quota, in the footer, `/usage` progress bars and status events |
| `showAllProviders` | `true` or `false` (default) | `/usage` lists every signed-in provider instead of the active one |
| `offerResetCredits` | `true` (default) or `false` | Whether `/usage` offers to redeem a reset credit when the active OpenAI or Codex account has one |
| `showAllProvidersCacheMinutes` | `5` (default) | How long `/usage` reuses a provider's report in the all-providers list; `0` fetches every time |

```json
{
"displayMode": "used"
"displayMode": "used",
"showAllProviders": true,
"offerResetCredits": false,
"showAllProvidersCacheMinutes": 10
}
```

| Value | Description |
| --- | --- |
| `"remaining"` | Show remaining quota percentage (default) |
| `"used"` | Show used quota percentage |
With `showAllProviders`, the active provider stays first and is always fetched fresh; the others reuse a report for `showAllProvidersCacheMinutes` minutes and are left out when Pi holds no credential for them. Claude appears as `Waiting` until Claude Code reports usage in the session. The footer keeps tracking the active provider on its own five-minute refresh.

Run `/reload` after changing the config file. `displayMode` applies to the footer status bar, `/usage` progress bars, and status events.
With `offerResetCredits` set to `false`, `/usage` still shows how many reset credits the account has, but never asks whether to redeem one; redeeming then needs the setting turned back on.

## Privacy and Safety

Expand Down
24 changes: 16 additions & 8 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ pi install /path/to/pi-subscription-usage
按上面的方法登录,再选一个该提供商的模型,之后:

- 底部状态栏会自动显示当前额度窗口,在每轮对话结束后及每 5 分钟刷新一次(带 5 分钟缓存)。
- 执行 `/usage` 会跳过缓存直接拉取最新数据,显示进度条、重置时间(`MM/DD HH:mm`)及账号信息。
- 执行 `/usage` 会跳过缓存直接拉取最新数据,显示进度条、重置时间(`MM/DD HH:mm`)及账号信息。开启 [`showAllProviders`](#配置) 后,还会一并列出其他已登录的提供商。
- Claude 例外:不会主动查询额度,只读取 Claude Code 回复中附带的数据(见 [Claude (Claude Code)](#claude-claude-code))。

### 使用重置券(OpenAI 与 Codex)
Expand All @@ -121,23 +121,31 @@ OpenAI 或 Codex 账号里有可用的限额重置券时,`/usage` 会提供使
- 提交兑换前,扩展会检查当前模型和账号是否发生变动,并核对运行时令牌是否与 Pi 保存的 OAuth 登录信息一致。
- 在 OpenAI 模式下,重置券作用于服务端定义的账户级窗口,不一定单独清空当前应用的限额。
- 兑换重置券是本扩展唯一的写操作。
- 把 [`offerResetCredits`](#配置) 设为 `false` 可以关掉这个询问;账号上的重置券数量仍会显示。

## 配置

百分比默认显示剩余额度。如需改为显示已用额度,可在 `~/.pi/agent/subscription-usage.json`(全局)或 `.pi/subscription-usage.json`(受信任项目的局部覆盖)中配置:
配置文件为 `~/.pi/agent/subscription-usage.json`(全局)或 `.pi/subscription-usage.json`(受信任项目的局部覆盖),修改后执行 `/reload` 生效。

| 配置项 | 取值 | 说明 |
| --- | --- | --- |
| `displayMode` | `"remaining"`(默认)或 `"used"` | 百分比显示剩余额度还是已用额度,作用于底部状态栏、`/usage` 进度条和状态事件 |
| `showAllProviders` | `true` 或 `false`(默认) | `/usage` 列出所有已登录的提供商,而不只是当前提供商 |
| `offerResetCredits` | `true`(默认)或 `false` | 当前 OpenAI 或 Codex 账号有重置券时,`/usage` 是否询问是否使用一张 |
| `showAllProvidersCacheMinutes` | 默认 `5` | `/usage` 列表里其他提供商的报告复用多久;`0` 表示每次都重新查询 |

```json
{
"displayMode": "used"
"displayMode": "used",
"showAllProviders": true,
"offerResetCredits": false,
"showAllProvidersCacheMinutes": 10
}
```

| 配置值 | 说明 |
| --- | --- |
| `"remaining"` | 显示剩余额度百分比(默认) |
| `"used"` | 显示已用额度百分比 |
开启 `showAllProviders` 后,当前提供商排在最前并总是重新查询;其余提供商的报告按 `showAllProvidersCacheMinutes` 分钟复用,Pi 没有其凭据的提供商会直接略过。底部状态栏仍按自己的五分钟节奏刷新。Claude 在 Claude Code 于本次会话中上报用量之前显示为 `Waiting`。底部状态栏仍然只跟踪当前提供商。

修改配置文件后执行 `/reload` 生效。`displayMode` 同时作用于底部状态栏、`/usage` 进度条和状态事件。
`offerResetCredits` 设为 `false` 时,`/usage` 仍会显示账号上有几张重置券,但不再询问是否使用;需要使用重置券时把该配置改回 `true`。

## 隐私与安全

Expand Down
59 changes: 55 additions & 4 deletions src/config-core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,27 @@ import {

export interface UsageConfig {
displayMode: UsageDisplayMode;
/** `/usage` lists every signed-in provider instead of the active one. */
showAllProviders: boolean;
/** `/usage` offers to redeem a reset credit when the account has one. */
offerResetCredits: boolean;
/** Minutes a report is reused for the providers after the active one; 0 fetches each time. */
showAllProvidersCacheMinutes: number;
}

export interface ParsedUsageConfig {
displayMode?: UsageDisplayMode;
showAllProviders?: boolean;
offerResetCredits?: boolean;
showAllProvidersCacheMinutes?: number;
warning?: string;
}

export const DEFAULT_USAGE_CONFIG: UsageConfig = {
displayMode: DEFAULT_USAGE_DISPLAY_MODE,
showAllProviders: false,
offerResetCredits: true,
showAllProvidersCacheMinutes: 5,
};

export function resolveUsageConfig(
Expand All @@ -25,19 +37,58 @@ export function resolveUsageConfig(
projectConfig?.displayMode ??
globalConfig?.displayMode ??
DEFAULT_USAGE_CONFIG.displayMode,
showAllProviders:
projectConfig?.showAllProviders ??
globalConfig?.showAllProviders ??
DEFAULT_USAGE_CONFIG.showAllProviders,
offerResetCredits:
projectConfig?.offerResetCredits ??
globalConfig?.offerResetCredits ??
DEFAULT_USAGE_CONFIG.offerResetCredits,
showAllProvidersCacheMinutes:
projectConfig?.showAllProvidersCacheMinutes ??
globalConfig?.showAllProvidersCacheMinutes ??
DEFAULT_USAGE_CONFIG.showAllProvidersCacheMinutes,
};
}

export function parseUsageConfig(value: unknown): ParsedUsageConfig {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return { warning: "configuration must be a JSON object" };
}
const displayMode = (value as Record<string, unknown>).displayMode;
if (displayMode === undefined) return {};
if (displayMode !== "remaining" && displayMode !== "used") {
const record = value as Record<string, unknown>;
const displayMode = record.displayMode;
const showAllProviders = record.showAllProviders;
const offerResetCredits = record.offerResetCredits;
const showAllProvidersCacheMinutes = record.showAllProvidersCacheMinutes;
if (displayMode !== undefined && displayMode !== "remaining" && displayMode !== "used") {
return {
warning: 'displayMode must be either "remaining" or "used"',
};
}
return { displayMode };
if (showAllProviders !== undefined && typeof showAllProviders !== "boolean") {
return { warning: "showAllProviders must be true or false" };
}
if (offerResetCredits !== undefined && typeof offerResetCredits !== "boolean") {
return { warning: "offerResetCredits must be true or false" };
}
if (
showAllProvidersCacheMinutes !== undefined &&
(typeof showAllProvidersCacheMinutes !== "number" ||
!Number.isFinite(showAllProvidersCacheMinutes) ||
showAllProvidersCacheMinutes < 0)
) {
return {
warning:
"showAllProvidersCacheMinutes must be 0 or more",
};
}
return {
...(displayMode === undefined ? {} : { displayMode }),
...(showAllProviders === undefined ? {} : { showAllProviders }),
...(offerResetCredits === undefined ? {} : { offerResetCredits }),
...(showAllProvidersCacheMinutes === undefined
? {}
: { showAllProvidersCacheMinutes }),
};
}
15 changes: 13 additions & 2 deletions src/core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ export class UsageCache {
string,
{ createdAt: number; report: UsageReport }
>();
private readonly ttlMs: number;
private ttlMs: number;
private readonly maxEntries: number;

constructor(ttlMs: number, maxEntries = 32) {
Expand All @@ -21,13 +21,24 @@ export class UsageCache {
this.maxEntries = maxEntries;
}

/** `maxAgeMs` lets one caller accept a staler report than the default window. */
get(
providerId: string,
fingerprint: string,
now = Date.now(),
maxAgeMs = this.ttlMs,
): UsageReport | undefined {
this.sweepExpired(now);
return this.entries.get(cacheKey(providerId, fingerprint))?.report;
// A zero window means "fetch every time", not "accept a same-millisecond hit".
if (maxAgeMs <= 0) return undefined;
const entry = this.entries.get(cacheKey(providerId, fingerprint));
if (!entry) return undefined;
return now - entry.createdAt <= maxAgeMs ? entry.report : undefined;
}

/** A caller that accepts staler reports keeps entries that long before sweeping. */
raiseTtl(ttlMs: number): void {
if (Number.isFinite(ttlMs) && ttlMs > this.ttlMs) this.ttlMs = ttlMs;
}

set(
Expand Down
Loading