From 7906519eeb88bba69d3d77d9384e7394d9437be1 Mon Sep 17 00:00:00 2001 From: Evan Reichard Date: Sun, 3 May 2026 21:22:26 -0400 Subject: [PATCH] docs: update AGENTS.md with accurate file layout and current conventions --- AGENTS.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1b25a2f..7dcbc72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,14 +6,17 @@ ## Layout -- `index.ts` — Extension entrypoint, footer registration, refresh timers, slash command, auth lookup. +- `index.ts` — Extension entrypoint, footer registration, refresh timers, debounced rendering, slash command, auth lookup. - `config.ts` — User-facing layout/config. Prefer changing this for layout tweaks. - `types.ts` — Shared config/module/state types. - `render.ts` — Width allocation, ANSI-aware truncation, dim text rendering. +- `utils.ts` — Shared utility helpers (`isRecord`, `toNumber`). +- `usage.ts` — Provider-agnostic usage type definitions (report, limit, credential, etc.). - `modules/basic.ts` — Directory, context, model, thinking, and cost modules. - `modules/usage.ts` — Usage bars/text modules and color gradient rendering. - `usage/` — Provider usage fetchers adapted from `oh-my-pi`: https://github.com/can1357/oh-my-pi/tree/main/packages/ai/src/usage -- `providers/openai-codex/constants.ts`, `usage.ts`, `utils.ts` — Local shims/support for copied usage code. +- `usage/shared.ts` — Shared helpers for usage fetchers. +- `providers/openai-codex/constants.ts` — OpenAI Codex base URL constant. ## Conventions @@ -26,14 +29,15 @@ { type: "usage", window: "week", style: "text", parts: ["percent", "time"], separator: " | " } ``` -- Usage fallback behavior should be stable/no-pop-in: - - unknown/loading line bars render like 0% usage - - unknown/loading percent renders `0%` - - unknown/loading time renders `∞` +- Usage data is preserved during refresh (no clearing before fetch) to prevent pop-in: + - Old data stays visible until new data arrives. + - When no data exists yet: line bars render like 0% usage, percent renders `0%`, time renders `∞`. - Usage bar colors are a continuous green → yellow → red gradient derived from usage percentage, not hard thresholds. - Rendering must remain ANSI-aware. If adding colors, update `visibleWidth`/`truncate` behavior as needed. - Text modules and separators should remain dim; filled usage bars may use gradient color. - Thinking level comes from `pi.getThinkingLevel()` and `thinking_level_select`, not `ctx.thinkingLevel`. +- `rerender()` is debounced via `queueMicrotask` — multiple rapid calls coalesce into a single render pass. +- All providers use the same refresh interval (`REFRESH_MS`). ## Testing