pi-spark 0.18.1 → 0.19.0

package/README.md

@@ -41,6 +41,12 @@ pi-spark shows the active provider's credit balance or rate-limit usage in the s
 
 ![Credits](./assets/screenshot-credits.png)
 
+#### OpenAI Codex banked resets
+
+Banked rate-limit resets are saved benefits that can reset eligible Codex usage windows when redeemed. When available, their count appears after the usage windows. Run `/codex-reset` to inspect each reset and its expiration date, then select one to redeem. See [OpenAI Codex Banked Rate-Limit Resets](./docs/openai-codex-banked-rate-limit-resets.md) for the underlying behavior and internal APIs.
+
+![Codex resets](./assets/screenshot-codex-resets.png)
+
 ### Presets
 
 pi-spark lets you define named model presets in `spark.json` (see [Configuration](#configuration)), so you can switch between models and thinking levels without retyping provider details. The active preset is shown on the editor's top border.

package/docs/background-model-calls-and-openai-codex-sessions.md

@@ -0,0 +1,75 @@
+# Background Model Calls and OpenAI Codex Sessions
+
+> This document was generated with the [Pi](https://pi.dev/) coding agent.
+
+In pi-spark, the title and recap features call the model outside Pi's main agent loop. They send a small, independent conversation through `completeSimple()` and persist only the resulting text and usage.
+
+On July 10, 2026, the day GPT-5.6 became available, I configured `openai-codex/gpt-5.6-luna` for title and recap generation while the main thread also used the `openai-codex` provider.
+
+## Problem
+
+Two failures appeared.
+
+Without a session ID, GPT-5.6 Luna returned no text:
+
+```text
+Codex error: Model not found gpt-5.6-luna-free-1p-codexswic-ev3
+```
+
+Passing the main thread's session ID to `completeSimple()` fixed routing, but made the background call reuse the main Codex WebSocket. Its response changed the socket's server-side continuation state. The next main turn then failed:
+
+```text
+Codex error: Previous response with id 'resp_...' not found.
+```
+
+Using a non-cached WebSocket was not enough: it stopped the background call from writing a client-side continuation, but the physical socket was still shared by session ID.
+
+## Root cause
+
+For `openai-codex-responses`, the session ID serves two roles:
+
+- Request-routing identity through `session-id` and `x-client-request-id` headers
+- Client-side WebSocket cache key and response-chain identity
+
+A background call therefore needs a valid Codex session ID, but it must not reuse the main thread's ID.
+
+In our tests, Codex accepted independent session IDs generated by Pi's `uuidv7()`. UUIDv4 values from `crypto.randomUUID()` and IDs modified with prefixes or suffixes were instead routed to an unavailable internal model.
+
+## Solution
+
+`completeBackground()` applies special handling only to `openai-codex-responses`. Every call gets an independent Pi UUIDv7 session ID:
+
+```ts
+completeSimple(model, context, { ...options, sessionId: uuidv7() });
+```
+
+The background session resource is closed in `finally`. Non-Codex providers use an ordinary one-shot `completeSimple()` call without a shared session ID or transport override.
+
+For OpenAI Codex, title, recap, and the main thread consequently have separate:
+
+- WebSocket connections
+- Response chains
+- Session routing identities
+- Prompt-cache identities
+
+The main socket is never closed or modified by background work. Every background call uses a fresh ID, so overlapping title, recap, or retry calls cannot affect each other's response chains.
+
+## Error handling
+
+Provider failures from `completeSimple()` may arrive as assistant messages rather than thrown exceptions. Title and recap therefore check:
+
+```ts
+if (response.stopReason === "error") {
+  throw new Error(response.errorMessage ?? "Background generation failed");
+}
+```
+
+This prevents a provider error with empty content from being mistaken for an empty model response.
+
+## Cache and performance
+
+The independent-session design preserves the main thread's WebSocket reuse, `previous_response_id` continuation, and prompt-cache identity. Background generation pays for its own WebSocket handshake, but that work does not invalidate or reconnect the main thread.
+
+Cache admission remains provider-controlled and noisy. In repeated GPT-5.6 Luna title A/B probes, isolated background calls caused no continuation errors and showed no negative main-thread cache trend. Main second-turn latency remained around the normal control range instead of paying the reconnect penalty seen when the shared main socket was closed.
+
+Use the [`measuring-model-cache`](../.agents/skills/measuring-model-cache/SKILL.md) skill to repeat the comparison after changes to Pi, providers, session handling, title, recap, or other background model features.

package/docs/openai-codex-banked-rate-limit-resets.md

@@ -0,0 +1,255 @@
+# OpenAI Codex Banked Rate-Limit Resets
+
+> This document was generated with the [Pi](https://pi.dev/) coding agent.
+
+OpenAI Codex allows eligible users to save a rate-limit reset and redeem it later. OpenAI calls this a **banked rate-limit reset**, usually shortened to **banked reset** or **reset**. Internal APIs and source code instead use **rate-limit reset credit** and `RateLimitResetCredit`.
+
+A reset is not money, an OpenAI API credit, or a transferable benefit. User-facing interfaces should therefore say `reset`, while code may retain the API's `credit` terminology.
+
+## How resets work
+
+A banked reset restores eligible Codex subscription rate-limit windows when redeemed. It is separate from the normal five-hour and weekly windows shown in Codex usage data.
+
+Resets are promotional benefits, not recurring subscription allowances. Confirmed grants have included the June 2026 launch grant and referral promotions. OpenAI may offer different rewards in the future, with eligibility determined dynamically by plan, region, workspace, account state, prior Codex use, and promotion-specific limits. The offer shown in the product is authoritative.
+
+Banked resets usually expire 30 days after they are granted unless an offer states otherwise. The API's `available_count` is the number already granted and currently available; it does not represent how many more resets a user may earn.
+
+## Integration surfaces
+
+The feature has two integration surfaces:
+
+- **Codex App Server JSON-RPC** is the documented, supported integration boundary
+- **ChatGPT WHAM REST** is used by the official open-source Codex client and covered by its contract tests, but it is not a public REST API with a compatibility guarantee
+
+The REST interface is convenient for a Pi extension because Pi already stores and refreshes the required ChatGPT OAuth credentials. It should nevertheless be isolated behind a small adapter so endpoint or schema changes do not spread through the feature.
+
+## WHAM REST endpoints
+
+The confirmed production base URL is:
+
+```text
+https://chatgpt.com/backend-api
+```
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/wham/usage` | Read rate-limit windows and the available-reset summary |
+| `GET` | `/wham/rate-limit-reset-credits` | Read individual reset details |
+| `POST` | `/wham/rate-limit-reset-credits/consume` | Redeem one reset |
+
+The official client also supports paths under `<codex-backend-base>/api/codex/...`, but OpenAI has not documented a public production host for that form. In particular, do not assume that `https://api.openai.com/api/codex/...` is valid.
+
+## Authentication
+
+These endpoints require ChatGPT subscription OAuth, not a normal OpenAI API key:
+
+```http
+Authorization: Bearer <access_token>
+ChatGPT-Account-ID: <account_id>
+```
+
+A Pi extension should ask Pi's model registry to resolve the credential so expired OAuth tokens are refreshed. It should not read or parse `~/.pi/agent/auth.json` directly. Tokens and complete request headers must never be logged or included in model context.
+
+## Reading usage and the reset summary
+
+Request:
+
+```http
+GET /backend-api/wham/usage HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer <access_token>
+ChatGPT-Account-ID: <account_id>
+Accept: application/json
+```
+
+Relevant response fields:
+
+```json
+{
+  "plan_type": "plus",
+  "rate_limit": {
+    "primary_window": {
+      "used_percent": 27,
+      "limit_window_seconds": 18000,
+      "reset_after_seconds": 13140,
+      "reset_at": 1782770922
+    },
+    "secondary_window": {
+      "used_percent": 4,
+      "limit_window_seconds": 604800,
+      "reset_after_seconds": 566340,
+      "reset_at": 1783357722
+    }
+  },
+  "rate_limit_reset_credits": {
+    "available_count": 2
+  }
+}
+```
+
+`primary_window` is normally the five-hour window and `secondary_window` the weekly window. `reset_at` is a Unix timestamp; `reset_after_seconds` is the corresponding relative duration observed in live responses. Read the reset count defensively:
+
+```ts
+const available = response.rate_limit_reset_credits?.available_count ?? 0;
+```
+
+This endpoint provides only a summary. Use the details endpoint to show expiration times or select a particular reset.
+
+## Reading reset details
+
+Request:
+
+```http
+GET /backend-api/wham/rate-limit-reset-credits HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer <access_token>
+ChatGPT-Account-ID: <account_id>
+Accept: application/json
+```
+
+Response:
+
+```json
+{
+  "credits": [
+    {
+      "id": "RateLimitResetCredit_...",
+      "reset_type": "codex_rate_limits",
+      "status": "available",
+      "granted_at": "2026-06-17T00:00:00Z",
+      "expires_at": "2026-07-17T00:00:00Z",
+      "title": "Full reset (Weekly + 5 hr)",
+      "description": "Ready to redeem"
+    }
+  ],
+  "available_count": 2
+}
+```
+
+The official Codex client consumes these fields:
+
+- `id`
+- `reset_type`
+- `status`
+- `granted_at`
+- `expires_at`
+- `title`
+- `description`
+- `available_count`
+
+The backend may return additional fields, but the official client deliberately ignores them. A live response contained `total_earned_count: 0` alongside four available credits, so `total_earned_count` must not be used as an earned or available balance. Nullable fields such as `redeem_started_at` and `redeemed_at` were also present but are unnecessary when listing available resets.
+
+Treat `available_count` as authoritative. The backend may limit the number of entries in `credits`, so `credits.length` is not a reliable substitute. Only entries whose status is `available` should be offered for redemption.
+
+## Consuming a reset
+
+Redeeming a reset is irreversible. The UI should show the selected reset, its expiration time, and the current rate-limit windows, then require explicit confirmation with a safe default of cancel.
+
+Request:
+
+```http
+POST /backend-api/wham/rate-limit-reset-credits/consume HTTP/1.1
+Host: chatgpt.com
+Authorization: Bearer <access_token>
+ChatGPT-Account-ID: <account_id>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "redeem_request_id": "55cbe0c1-71ab-4c52-b855-80746f73ff52",
+  "credit_id": "RateLimitResetCredit_..."
+}
+```
+
+- `redeem_request_id` is a required idempotency key; a UUID is appropriate (UUIDv7 is suitable and is already available from `@earendil-works/pi-agent-core`)
+- `credit_id` is optional; when omitted, the server chooses a reset
+- Retries of the same logical redemption must reuse the original `redeem_request_id`
+
+Successful response:
+
+```json
+{
+  "code": "reset",
+  "credit": {
+    "id": "RateLimitResetCredit_...",
+    "reset_type": "codex_rate_limits",
+    "status": "redeemed",
+    "redeemed_at": "2026-07-10T12:30:00Z"
+  },
+  "windows_reset": 2
+}
+```
+
+The REST response uses one of four snake-case result codes:
+
+| Code | Meaning |
+| --- | --- |
+| `reset` | The reset was redeemed and eligible windows were reset |
+| `nothing_to_reset` | No rate-limit window was currently eligible |
+| `no_credit` | No banked reset was available |
+| `already_redeemed` | This idempotent request had already completed; treat it as success |
+
+After `reset` or `already_redeemed`, refresh usage rather than deriving the new count or window state from stale client data. Reset details can be fetched again the next time the selection panel opens.
+
+## Error handling and compatibility
+
+The REST API can change independently of pi-spark. An adapter should handle:
+
+- Missing or newly added fields
+- `401` for missing or expired authorization
+- `403` for an ineligible account, workspace, region, or endpoint
+- Non-JSON responses, including proxy or Cloudflare HTML
+- Request cancellation and timeouts
+- Ambiguous network failures during redemption
+
+Do not include response bodies in user-facing errors unless they have been validated and sanitized. If the details endpoint fails, `/wham/usage` can still provide `available_count` for a degraded summary.
+
+## pi-spark behavior
+
+When `/wham/usage` reports one or more available resets, the credits status appends a summary after the normal windows:
+
+```text
+Codex 5h 42% 7d 7% (4 resets available)
+```
+
+The suffix is omitted when no reset is available. `/codex-reset` opens an interactive panel that loads current usage and reset details, lists available resets by title, grant time, and expiration time, and sorts the earliest expiration first. Selecting a reset opens a separate confirmation prompt before any POST request is made.
+
+Each confirmed redemption uses a new UUIDv7 idempotency key and makes one consume request without automatic retries. Successful and idempotently completed redemptions refresh the credits status.
+
+## Public App Server equivalent
+
+The documented Codex App Server exposes equivalent operations over JSON-RPC.
+
+Read limits and resets:
+
+```json
+{ "method": "account/rateLimits/read", "id": 1 }
+```
+
+The response includes camel-case `rateLimitResetCredits`, `availableCount`, and individual credits.
+
+Consume a reset:
+
+```json
+{
+  "method": "account/rateLimitResetCredit/consume",
+  "id": 2,
+  "params": {
+    "idempotencyKey": "55cbe0c1-71ab-4c52-b855-80746f73ff52",
+    "creditId": "RateLimitResetCredit_..."
+  }
+}
+```
+
+The App Server is the safer boundary for long-lived external integrations. Direct WHAM access is simpler inside pi-spark today, but should remain replaceable.
+
+## References
+
+- [Codex App Server](https://developers.openai.com/codex/app-server)
+- [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan)
+- [Codex Referral Promotions](https://help.openai.com/en/articles/20001271-codex-referral-promotions)
+- [Codex pricing and invitations](https://developers.openai.com/codex/pricing)
+- [Official REST implementation](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client/rate_limit_resets.rs)
+- [Official REST contract tests](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/client/rate_limit_resets_tests.rs)
+- [Official backend response types](https://github.com/openai/codex/blob/main/codex-rs/backend-client/src/types.rs)
+- [App Server reset processing](https://github.com/openai/codex/blob/main/codex-rs/app-server/src/request_processors/account_processor/rate_limit_resets.rs)

package/docs/reverse-engineering-fireworks-credits.md

@@ -0,0 +1,99 @@
+# Reverse-Engineering Fireworks Credits
+
+> This document was generated with the [Pi](https://pi.dev/) coding agent.
+
+Most providers in the credits feature expose a documented HTTP endpoint that returns a balance. [Fireworks](https://fireworks.ai/) does not. Its dashboard shows account credit, but there is no public REST route for it. This note records how the balance API was found by reverse-engineering the official `firectl` CLI, and how the provider is implemented on top of it.
+
+## Where the binary came from
+
+Fireworks ships a command-line tool, [`firectl`](https://docs.fireworks.ai/tools-sdks/firectl/). The [Homebrew tap formula](https://github.com/fw-ai/homebrew-firectl/blob/main/Formula/firectl.rb) points at per-platform binaries; the `darwin-amd64` build was used here.
+
+It is a Go binary, and crucially an **unstripped** one, which keeps the symbol table, the `pclntab` (function/line metadata), and the full module dependency list. None of that yields original source, but it exposes the program's structure in detail.
+
+```sh
+go version -m firectl        # build info: firectl 1.7.22, Go 1.25.0, module path
+go tool nm firectl           # 81k symbols, including package-qualified names
+go tool objdump -s SYM firectl   # disassembly annotated with file:line
+go run github.com/goretk/redress@latest source firectl   # folder/file/function tree
+```
+
+## Locating the credit feature
+
+The CLI is a Cobra app that is a thin client over a gRPC service named `gateway.Gateway`. Listing the RPC method paths embedded in the binary surfaced the relevant calls:
+
+```sh
+strings firectl | grep -oE '/gateway\.Gateway/[A-Za-z]+' | sort -u
+# ... /gateway.Gateway/GetBalance
+# ... /gateway.Gateway/GetLedger
+# ... /gateway.Gateway/ListCreditRedemptions
+# ... /gateway.Gateway/ListAccounts
+```
+
+`GetBalance` is exactly what the dashboard shows, but checking the symbol table revealed that **no CLI command is wired to it** — it exists in the gateway client yet is not reachable through any `firectl` subcommand. So the goal became calling it directly.
+
+## Working out authentication
+
+Two facts had to be recovered: the host and the credential format.
+
+The binary contains several Fireworks hostnames. The inference API (`api.fireworks.ai`) is the well-known one, but the control plane uses a separate host:
+
+```sh
+strings firectl | grep -oE '[a-z0-9.-]+\.fireworks\.ai' | sort -u
+# api.fireworks.ai          (inference)
+# gateway.fireworks.ai      (control-plane gRPC)  <- this one
+# app.fireworks.ai, device-auth.fireworks.ai
+```
+
+For the credential, the disassembly of the client's auth interceptor showed it sets gRPC metadata and references both `authorization` (Bearer) and `x-api-key`. The Bearer slot expects an OIDC ID token, which is what interactive `firectl signin` produces. API-key auth uses the `x-api-key` header instead.
+
+This matched what happened on the wire while probing the endpoint with a saved API key:
+
+- `api.fireworks.ai:443` returned HTTP 404 — wrong host for this service.
+- `gateway.fireworks.ai:443` with `authorization: Bearer <key>` returned `UNAUTHENTICATED: invalid id token` — the key is not a JWT.
+- `gateway.fireworks.ai:443` with `x-api-key: <key>` authenticated, then returned `INVALID_ARGUMENT` — auth worked; the request body was incomplete.
+
+## Reconstructing the messages
+
+The Go protobuf structs carry their field tags as string literals, so the message shapes can be read straight out of the binary:
+
+```sh
+strings firectl | grep -oE 'protobuf:"[^"]*name=(name|money|currency_code|units|nanos)[^"]*"'
+```
+
+That, plus the generated getter names (`(*Balance).GetMoney`, `(*GetBalanceRequest).GetName`), gives:
+
+```proto
+message GetBalanceRequest { string name = 1; }     // "accounts/<account_id>"
+message Balance           { Money money = 1; }
+message Money { string currency_code = 1; int64 units = 2; int32 nanos = 3; }  // google.type.Money
+```
+
+`GetBalance` needs a `name` like `accounts/<account_id>`. Rather than ask the user for their account id, `ListAccounts` (which the same API key can call) returns it:
+
+```proto
+message Account              { string name = 1; string display_name = 2; }
+message ListAccountsResponse { repeated Account accounts = 1; }
+```
+
+## Confirming end to end
+
+A minimal Node.js client using `@grpc/grpc-js` and `@grpc/proto-loader` confirmed the full flow against the live service:
+
+1. `ListAccounts` with `x-api-key` → `accounts/<id>`.
+2. `GetBalance { name }` → `Balance { money: { currency_code, units, nanos } }`.
+
+The amount is `units + nanos / 1e9` (the standard `google.type.Money` encoding), e.g., `units=9, nanos=694293840` → `$9.69`.
+
+## How the provider is implemented in the credits feature
+
+The provider lives in [`src/features/credits/providers/fireworks.ts`](../src/features/credits/providers/fireworks.ts) and follows the same `CreditsProvider` contract as the HTTP-based providers; only the transport differs.
+
+- **Transport.** A single, reused `@grpc/grpc-js` client dials `gateway.fireworks.ai:443` over TLS. The service is declared in [`fireworks.proto`](../src/features/credits/providers/fireworks.proto) — the minimal slice needed, loaded at runtime with `@grpc/proto-loader`. The `.proto` is resolved relative to the module via `import.meta.url`, so it ships and loads from the package directory.
+- **Auth.** Each call sends `x-api-key: <key>` in gRPC metadata. The key comes from Pi's `modelRegistry.getApiKeyForProvider("fireworks")` (env `FIREWORKS_API_KEY`), handled by the manager.
+- **Account resolution.** `ListAccounts` is called once and the resolved `accounts/<id>` is cached per API key, so steady-state refreshes are a single `GetBalance` round trip.
+- **Cancellation.** The shared `AbortSignal` cancels the in-flight gRPC call, and a defensive deadline bounds each request.
+- **Result.** `Money` is converted to a dollar amount and returned as `{ type: "balance", remaining }`, which the status line renders like any other balance provider.
+
+## Caveats
+
+`GetBalance` is an internal API: it is intentionally absent from `firectl`, undocumented, and not part of any public contract. Its host, request shape, and behavior can change at any time without notice, which would break this provider. The narrow `.proto` keeps the blast radius small if that happens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Pi package that polishes your daily experience.",
   "keywords": [
     "pi-coding-agent",
@@ -16,6 +16,7 @@
     "index.ts",
     "src",
     "assets",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -36,19 +37,19 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": ">=0.80.6",
+    "@earendil-works/pi-ai": ">=0.80.6",
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-agent-core": ">=0.80.6",
+    "@earendil-works/pi-ai": ">=0.80.6",
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6",
     "@types/node": "*",
     "typebox": "*",
-    "typescript": "^6.0.3"
+    "typescript": "^7.0.2"
   }
 }

package/src/components/loader.ts

@@ -0,0 +1,17 @@
+import { Loader as BaseLoader } from "@earendil-works/pi-tui";
+
+/** The built-in loader hardcodes 1 column of horizontal padding, which is private. */
+const PADDING_X = 1;
+
+export class Loader extends BaseLoader {
+  override render(width: number): string[] {
+    // Inflate the width so the base loader keeps full content width, then strip its padding.
+    return super.render(width + PADDING_X * 2).map((line) => {
+      if (line.length === 0) {
+        return line;
+      }
+
+      return line.slice(PADDING_X, line.length - PADDING_X);
+    });
+  }
+}

package/src/features/credits/index.ts

@@ -1,4 +1,5 @@
 import { CreditsManager } from "./manager";
+import { registerProviderExtensions } from "./providers";
 import { loadConfig } from "../../config";
 import { isUsage } from "../../utils/usage";
 
@@ -20,6 +21,8 @@ export function registerCredits(pi: ExtensionAPI): void {
     if (!ctx.hasUI || !config) return;
 
     creditsManager = new CreditsManager();
+    registerProviderExtensions(pi, ctx, async (ctx) => await creditsManager?.refresh(ctx));
+
     creditsManager.refresh(ctx);
   });
 

package/src/features/credits/providers/index.ts

@@ -6,7 +6,8 @@ import { openaiCodexProvider } from "./openai-codex";
 import { openrouterProvider } from "./openrouter";
 import { vercelAiGatewayProvider } from "./vercel-ai-gateway";
 
-import type { CreditsProvider } from "../types";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CreditsProvider, RefreshCredits } from "../types";
 
 const PROVIDERS: CreditsProvider[] = [
   deepseekProvider,
@@ -22,3 +23,7 @@ const PROVIDERS: CreditsProvider[] = [
 export function findProvider(provider?: string): CreditsProvider | undefined {
   return PROVIDERS.find((entry) => entry.id === provider);
 }
+
+export function registerProviderExtensions(pi: ExtensionAPI, ctx: ExtensionContext, refresh: RefreshCredits): void {
+  for (const provider of PROVIDERS) provider.register?.(pi, ctx, refresh);
+}

package/src/features/credits/providers/openai-codex-panel.ts

@@ -0,0 +1,229 @@
+import { DynamicBorder, keyHint, rawKeyHint } from "@earendil-works/pi-coding-agent";
+import { Box, Container, matchesKey, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+
+import { Loader } from "../../../components/loader";
+import { renderCredits } from "../status";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SelectItem } from "@earendil-works/pi-tui";
+import type { BankedRateLimitReset, RateLimitResetCreditsResponse } from "./openai-codex";
+import type { Credits } from "../types";
+
+const DATE_COLUMN_WIDTH = 14;
+
+export interface CodexResetPanelData extends RateLimitResetCreditsResponse {
+  usage: Credits;
+}
+
+export async function showCodexResetSelector(ctx: ExtensionContext, load: (signal: AbortSignal) => Promise<CodexResetPanelData>): Promise<BankedRateLimitReset | undefined> {
+  const selected = await ctx.ui.custom<BankedRateLimitReset | null>((tui, theme, _keybindings, done) => {
+    const controller = new AbortController();
+
+    const container = new Container();
+    const box = new Box(1, 1);
+    const loader = new Loader(tui, (text) => theme.fg("accent", text), (text) => theme.fg("muted", text), "Loading...");
+
+    let settled = false;
+    let selectList: SelectList | undefined;
+
+    const finish = (value: BankedRateLimitReset | null) => {
+      if (settled) return;
+
+      settled = true;
+      controller.abort();
+      loader.stop();
+
+      done(value);
+    };
+
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    box.addChild(new Text(theme.bold(theme.fg("accent", "OpenAI Codex banked rate-limit resets")), 0, 0));
+    box.addChild(loader);
+    box.addChild(new Spacer(1));
+    box.addChild(new Text(keyHint("tui.select.cancel", "cancel"), 0, 0));
+
+    container.addChild(box);
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    loader.start();
+
+    load(controller.signal).then((data) => {
+      if (settled) return;
+
+      loader.stop();
+
+      const credits = data.credits.filter((credit) => credit.status === "available").toSorted((a, b) => getExpirationTime(a) - getExpirationTime(b));
+      if (data.available_count === 0) {
+        ctx.ui.notify("No Codex resets available", "info");
+        finish(null);
+        return;
+      }
+      if (credits.length === 0) {
+        ctx.ui.notify(`${formatAvailableResets(data.available_count)}, but no reset details were returned`, "warning");
+        finish(null);
+        return;
+      }
+
+      box.clear();
+      box.addChild(new Text(theme.bold(theme.fg("accent", "OpenAI Codex banked rate-limit resets")), 0, 0));
+      box.addChild(new Text(renderCredits(theme, "", data.usage), 0, 0));
+      box.addChild(new Spacer(1));
+
+      const creditsById = new Map(credits.map((credit) => [credit.id, credit]));
+      const items: SelectItem[] = credits.map((credit) => ({
+        value: credit.id,
+        label: formatCreditTitle(credit),
+        description: formatCreditDescription(credit),
+      }));
+
+      selectList = new SelectList(items, Math.min(items.length, 10), {
+        selectedPrefix: (text) => theme.fg("accent", text),
+        selectedText: (text) => theme.fg("accent", text),
+        description: (text) => theme.fg("muted", text),
+        scrollInfo: (text) => theme.fg("dim", text),
+        noMatch: (text) => theme.fg("warning", text),
+      });
+      selectList.onSelect = (item) => finish(creditsById.get(item.value) ?? null);
+      selectList.onCancel = () => finish(null);
+
+      box.addChild(selectList);
+      box.addChild(new Spacer(1));
+
+      const keyHints = [rawKeyHint("↑↓", "navigate"), keyHint("tui.select.confirm", "redeem"), keyHint("tui.select.cancel", "cancel")];
+      box.addChild(new Text(keyHints.join("  "), 0, 0));
+
+      tui.requestRender();
+    }).catch((error) => {
+      if (settled || controller.signal.aborted) return;
+
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      finish(null);
+    });
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (selectList) {
+          selectList.handleInput(data);
+          tui.requestRender();
+        } else if (matchesKey(data, "escape")) {
+          finish(null);
+        }
+      },
+    };
+  });
+
+  return selected ?? undefined;
+}
+
+export async function confirmCodexReset(ctx: ExtensionContext, credit: BankedRateLimitReset): Promise<boolean> {
+  const confirmed = await ctx.ui.custom<boolean>((tui, theme, _keybindings, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    const box = new Box(1, 1);
+    box.addChild(new Text(theme.bold(theme.fg("accent", "Redeem reset?")), 0, 0));
+    box.addChild(new Spacer(1));
+
+    const details = [
+      formatCreditTitle(credit),
+      formatCreditDescription(credit, false),
+      credit.description?.trim(),
+    ].filter(Boolean).join("\n");
+
+    box.addChild(new Text(theme.fg("muted", details), 0, 0));
+    box.addChild(new Spacer(1));
+    box.addChild(new Text(theme.fg("warning", "This permanently consumes one banked reset and resets all eligible windows."), 0, 0));
+    box.addChild(new Spacer(1));
+
+    const items: SelectItem[] = [
+      { value: "yes", label: "Yes" },
+      { value: "no", label: "No" },
+    ];
+
+    const selectList = new SelectList(items, 2, {
+      selectedPrefix: (text) => theme.fg("accent", text),
+      selectedText: (text) => theme.fg("accent", text),
+      description: (text) => theme.fg("muted", text),
+      scrollInfo: (text) => theme.fg("dim", text),
+      noMatch: (text) => theme.fg("warning", text),
+    });
+    selectList.onSelect = (item) => done(item.value === "yes");
+    selectList.onCancel = () => done(false);
+
+    box.addChild(selectList);
+    box.addChild(new Spacer(1));
+
+    const keyHints = [rawKeyHint("↑↓", "navigate"), keyHint("tui.select.confirm", "confirm"), keyHint("tui.select.cancel", "cancel")];
+    box.addChild(new Text(keyHints.join("  "), 0, 0));
+
+    container.addChild(box);
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  return confirmed ?? false;
+}
+
+export async function showCodexResetLoader(ctx: ExtensionContext, run: () => Promise<void>): Promise<void> {
+  await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+    const container = new Container();
+    const loader = new Loader(tui, (text) => theme.fg("accent", text), (text) => theme.fg("muted", text), "Redeeming...");
+
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    const box = new Box(1, 1);
+    box.addChild(new Text(theme.bold(theme.fg("accent", "OpenAI Codex banked rate-limit resets")), 0, 0));
+    box.addChild(loader);
+
+    container.addChild(box);
+    container.addChild(new DynamicBorder((text: string) => theme.fg("border", text)));
+
+    loader.start();
+
+    run()
+      .catch((error: unknown) => ctx.ui.notify(error instanceof Error ? error.message : String(error), "error"))
+      .finally(() => {
+        loader.stop();
+        done();
+      });
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+    };
+  });
+}
+
+export function formatAvailableResets(count: number): string {
+  return `${count} ${count === 1 ? "reset" : "resets"} available`;
+}
+
+function formatCreditTitle(credit: BankedRateLimitReset): string {
+  return credit.title?.trim() || "Banked rate-limit reset";
+}
+
+function formatCreditDescription(credit: BankedRateLimitReset, padEnd: boolean = true): string {
+  const formatDate = (value: string) => new Intl.DateTimeFormat("en-US", { month: "short", day: "numeric" }).format(new Date(value));
+
+  const granted = padEnd ? `Granted ${formatDate(credit.granted_at)}`.padEnd(DATE_COLUMN_WIDTH) : `Granted ${formatDate(credit.granted_at)}`;
+  const expires = padEnd ? (credit.expires_at ? `Expires ${formatDate(credit.expires_at)}` : "No expiration").padEnd(DATE_COLUMN_WIDTH) : (credit.expires_at ? `Expires ${formatDate(credit.expires_at)}` : "No expiration");
+  return `${granted} · ${expires}`;
+}
+
+function getExpirationTime(credit: BankedRateLimitReset): number {
+  if (!credit.expires_at) return Number.POSITIVE_INFINITY;
+
+  const timestamp = Date.parse(credit.expires_at);
+  return Number.isNaN(timestamp) ? Number.POSITIVE_INFINITY : timestamp;
+}

package/src/features/credits/providers/openai-codex.ts

@@ -1,16 +1,25 @@
+import { uuidv7 } from "@earendil-works/pi-agent-core";
+
+import { confirmCodexReset, formatAvailableResets, showCodexResetLoader, showCodexResetSelector } from "./openai-codex-panel";
 import { toNumber } from "../../../utils/format";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { Credits, CreditsProvider } from "../types";
+import type { CodexResetPanelData } from "./openai-codex-panel";
+import type { Credits, CreditsProvider, RefreshCredits } from "../types";
 
 const PROVIDER = "openai-codex";
-const URL = "https://chatgpt.com/backend-api/wham/usage";
+const BASE_URL = "https://chatgpt.com/backend-api";
+const USAGE_PATH = "/wham/usage";
+const RESET_CREDITS_PATH = "/wham/rate-limit-reset-credits";
+const CONSUME_RESET_PATH = "/wham/rate-limit-reset-credits/consume";
+const REQUEST_TIMEOUT_MS = 30_000;
 
 interface CodexUsageResponse {
   rate_limit?: {
     primary_window?: CodexRateWindow | null;
     secondary_window?: CodexRateWindow | null;
   } | null;
+  rate_limit_reset_credits?: { available_count: number } | null;
   credits?: { unlimited?: boolean } | null;
 }
 
@@ -18,16 +27,116 @@ interface CodexRateWindow {
   used_percent?: number | string;
 }
 
-function getAccountId(ctx: ExtensionContext): string | undefined {
-  const credential = ctx.modelRegistry.authStorage.get(PROVIDER) as { accountId?: string } | undefined;
-  const accountId = credential?.accountId;
+export interface BankedRateLimitReset {
+  id: string;
+  status: string;
+  granted_at: string;
+  expires_at: string | null;
+  title?: string | null;
+  description?: string | null;
+}
+
+export interface RateLimitResetCreditsResponse {
+  credits: BankedRateLimitReset[];
+  available_count: number;
+}
+
+interface ConsumeResetResponse {
+  code: "reset" | "nothing_to_reset" | "no_credit" | "already_redeemed";
+  windows_reset: number;
+}
+
+async function runCodexReset(ctx: ExtensionContext, refresh: RefreshCredits): Promise<void> {
+  const apiKey = await ctx.modelRegistry.getApiKeyForProvider(PROVIDER);
+  if (!apiKey) return;
+
+  const headers = buildHeaders(ctx, apiKey);
+
+  const credit = await showCodexResetSelector(ctx, async (signal) => {
+    const requestSignal = AbortSignal.any([signal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)]);
+    const [usage, details] = await Promise.all([fetchUsage(headers, requestSignal), fetchResetCredits(headers, requestSignal)]);
+
+    return {
+      ...details,
+      usage: toCredits(usage, `· ${formatAvailableResets(details.available_count)}`),
+    } satisfies CodexResetPanelData;
+  });
+  if (!credit || !(await confirmCodexReset(ctx, credit))) return;
+
+  await redeemReset(ctx, headers, credit, refresh);
+}
+
+async function redeemReset(ctx: ExtensionContext, headers: Record<string, string>, credit: BankedRateLimitReset, refresh: RefreshCredits): Promise<void> {
+  await showCodexResetLoader(ctx, async () => {
+    const response = await consumeReset(headers, uuidv7(), credit.id);
+    if (response.code === "nothing_to_reset") throw new Error("No Codex rate-limit window currently needs a reset");
+    if (response.code === "no_credit") throw new Error("No Codex resets are available");
+  }).finally(() => refresh(ctx));
+}
+
+function buildHeaders(ctx: ExtensionContext, apiKey: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    Authorization: `Bearer ${apiKey}`,
+  };
 
-  return typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
+  const credential = ctx.modelRegistry.authStorage.get(PROVIDER);
+  const accountId = credential?.type === "oauth" ? (credential.accountId as string | undefined) : undefined;
+  if (accountId) headers["ChatGPT-Account-ID"] = accountId;
+
+  return headers;
+}
+
+async function requestJson<T>(path: string, headers: Record<string, string>, signal: AbortSignal, init: RequestInit = {}): Promise<T> {
+  const requestHeaders = new Headers(headers);
+  new Headers(init.headers).forEach((value, key) => requestHeaders.set(key, value));
+
+  const response = await fetch(`${BASE_URL}${path}`, {
+    ...init,
+    headers: requestHeaders,
+    signal,
+  });
+  if (!response.ok) throw new Error(`Codex backend returned ${response.status}`);
+
+  return (await response.json()) as T;
+}
+
+async function fetchUsage(headers: Record<string, string>, signal: AbortSignal): Promise<CodexUsageResponse> {
+  return requestJson<CodexUsageResponse>(USAGE_PATH, headers, signal);
+}
+
+async function fetchResetCredits(headers: Record<string, string>, signal: AbortSignal): Promise<RateLimitResetCreditsResponse> {
+  return requestJson<RateLimitResetCreditsResponse>(RESET_CREDITS_PATH, headers, signal);
+}
+
+async function consumeReset(headers: Record<string, string>, redeemRequestId: string, creditId: string): Promise<ConsumeResetResponse> {
+  return requestJson<ConsumeResetResponse>(
+    CONSUME_RESET_PATH,
+    headers,
+    AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ redeem_request_id: redeemRequestId, credit_id: creditId }),
+    },
+  );
+}
+
+function toCredits(usage: CodexUsageResponse, suffix?: string): Credits {
+  return {
+    type: "windows",
+    unlimited: usage.credits?.unlimited === true,
+    lanes: [
+      { label: "5h", percent: parseUsedPercent(usage.rate_limit?.primary_window) },
+      { label: "7d", percent: parseUsedPercent(usage.rate_limit?.secondary_window) },
+    ],
+    suffix,
+  };
 }
 
 function parseUsedPercent(window?: CodexRateWindow | null): number | undefined {
   const value = toNumber(window?.used_percent);
-  return typeof value === "number" ? Math.min(100, Math.max(0, value)) : undefined;
+  return value === undefined ? undefined : Math.min(100, Math.max(0, value));
 }
 
 export const openaiCodexProvider: CreditsProvider = {
@@ -35,26 +144,21 @@ export const openaiCodexProvider: CreditsProvider = {
   label: "Codex",
 
   async fetch(ctx, apiKey, signal): Promise<Credits> {
-    const headers: Record<string, string> = {
-      Accept: "application/json",
-      Authorization: `Bearer ${apiKey}`,
-    };
-
-    const accountId = getAccountId(ctx);
-    if (accountId) headers["ChatGPT-Account-Id"] = accountId;
+    const headers = buildHeaders(ctx, apiKey);
+    const usage = await fetchUsage(headers, signal);
+    const availableCount = usage.rate_limit_reset_credits?.available_count ?? 0;
+    const suffix = availableCount > 0 ? `(${formatAvailableResets(availableCount)})` : undefined;
 
-    const response = await fetch(URL, { headers, signal });
-    if (!response.ok) throw new Error("request failed");
+    return toCredits(usage, suffix);
+  },
 
-    const payload = (await response.json()) as CodexUsageResponse;
+  register(pi, ctx, refresh): void {
+    const credential = ctx.modelRegistry.authStorage.get(PROVIDER);
+    if (credential?.type !== "oauth") return;
 
-    return {
-      type: "windows",
-      unlimited: payload.credits?.unlimited === true,
-      lanes: [
-        { label: "5h", percent: parseUsedPercent(payload.rate_limit?.primary_window) },
-        { label: "7d", percent: parseUsedPercent(payload.rate_limit?.secondary_window) },
-      ],
-    };
+    pi.registerCommand("codex-reset", {
+      description: "Select and redeem a banked OpenAI Codex rate-limit reset",
+      handler: async (_args, ctx) => await runCodexReset(ctx, refresh),
+    });
   },
 };

package/src/features/credits/status.ts

@@ -7,10 +7,11 @@ const BALANCE_WARNING = 10;
 const BALANCE_ERROR = 5;
 
 export function renderCredits(theme: Theme, label: string, credits: Credits): string {
-  const styledLabel = theme.fg("dim", label);
+  const styledLabel = theme.fg("dim", label ? `${label} ` : "");
+  const value = credits.type === "windows" ? renderWindows(theme, credits) : renderBalance(theme, credits);
+  const suffix = credits.suffix ? ` ${theme.fg("dim", credits.suffix)}` : "";
 
-  if (credits.type === "windows") return `${styledLabel} ${renderWindows(theme, credits)}`;
-  return `${styledLabel} ${renderBalance(theme, credits)}`;
+  return `${styledLabel}${value}${suffix}`;
 }
 
 export function renderError(theme: Theme, label: string, message: string): string {

package/src/features/credits/types.ts

@@ -1,5 +1,5 @@
 import type { ProviderId } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 /**
  * Normalized credits/usage for a provider.
@@ -7,18 +7,22 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
  * - `balance` providers (e.g., OpenRouter, Vercel AI Gateway) report a remaining dollar balance.
  * - `windows` providers (e.g., OpenAI Codex) report rate-limit windows as used percentages.
  */
-export type Credits =
+export type Credits = (
   | { type: "balance"; remaining?: number | undefined }
-  | { type: "windows"; lanes: CreditsLane[]; unlimited?: boolean | undefined };
+  | { type: "windows"; lanes: CreditsLane[]; unlimited?: boolean | undefined }
+) & { suffix?: string | undefined };
 
 export interface CreditsLane {
   label: string;
   percent: number | undefined;
 }
 
+export type RefreshCredits = (ctx: ExtensionContext) => Promise<void>;
+
 /** A credits source for a Pi provider, shown in the status line while that provider is active. */
 export interface CreditsProvider {
   readonly id: ProviderId;
   readonly label: string;
   fetch(ctx: ExtensionContext, apiKey: string, signal: AbortSignal): Promise<Credits>;
+  register?(pi: ExtensionAPI, ctx: ExtensionContext, refresh: RefreshCredits): void;
 }

package/src/features/editor/index.ts

@@ -155,6 +155,11 @@ export function registerEditor(pi: ExtensionAPI, events: EventCollector): void {
   pi.on("agent_end", () => {
     runningToolCallIds.clear();
     editor?.setWorkingMessage();
+  });
+
+  pi.on("agent_settled", () => {
+    runningToolCallIds.clear();
+    editor?.setWorkingMessage();
     spinner?.stop();
   });
 

package/src/features/presets/selector.ts

@@ -38,11 +38,7 @@ export async function showPresetSelector(ctx: ExtensionContext, presetManager: P
     box.addChild(selectList);
     box.addChild(new Spacer(1));
 
-    const keyHints = [
-      rawKeyHint("↑↓", "navigate"),
-      keyHint("tui.select.confirm", "select"),
-      keyHint("tui.select.cancel", "cancel"),
-    ];
+    const keyHints = [rawKeyHint("↑↓", "navigate"), keyHint("tui.select.confirm", "select"), keyHint("tui.select.cancel", "cancel")];
     box.addChild(new Text(keyHints.join("  "), 0, 0));
 
     container.addChild(box);

package/src/features/recap/index.ts

@@ -48,7 +48,7 @@ export function registerRecap(pi: ExtensionAPI): void {
     idleListener?.wake(ctx);
   });
 
-  pi.on("agent_end", (_event, ctx) => {
+  pi.on("agent_settled", (_event, ctx) => {
     idleListener?.watch(ctx);
   });
 

package/src/features/title/index.ts

@@ -15,8 +15,8 @@ export function registerTitle(pi: ExtensionAPI): void {
 
   // Generate the title after the first exchange, once the session has context to summarize.
   // The manager runs at most once and skips sessions that already have a name.
-  pi.on("agent_end", (_event, ctx) => {
-    titleManager?.run(ctx);
+  pi.on("agent_settled", (_event, ctx) => {
+    void titleManager?.run(ctx);
   });
 
   pi.on("session_shutdown", () => {

package/src/features/title/manager.ts

@@ -12,6 +12,7 @@ const SYSTEM_PROMPT = [
   "Base the title only on the transcript; do not invent topics, files, or intent.",
   "Capture the user's main goal or the session's central task.",
   "Respond in the conversation's primary language.",
+  "For English, use sentence case, never title case. Add spaces between English and CJK text.",
   "Output a single title of 3-8 words. No trailing punctuation, quotes, markdown, or prefix like 'Title:'.",
 ].join(" ");