156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# Usage Command Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Add a built-in `/usage` command with a generic agent usage-reporting interface, and implement the first provider-backed version for Codex using ChatGPT OAuth quota data.
|
|
|
|
**Architecture:** The engine gains a new built-in command that depends only on an optional `UsageReporter` interface. Agents that implement the interface return a generic `UsageReport`; the engine formats that into text. The Codex agent reads ChatGPT OAuth credentials from `~/.codex/auth.json`, calls the `wham/usage` endpoint, and maps the response into the generic structure.
|
|
|
|
**Tech Stack:** Go, built-in command dispatch in `core/engine.go`, optional agent interfaces in `core/interfaces.go`, HTTP/JSON via Go standard library, table-driven tests.
|
|
|
|
---
|
|
|
|
### Task 1: Add generic usage-reporting types
|
|
|
|
**Files:**
|
|
- Modify: `core/interfaces.go`
|
|
|
|
**Step 1: Add the failing interface usage surface**
|
|
|
|
Define:
|
|
|
|
- `UsageReporter`
|
|
- `UsageReport`
|
|
- `UsageBucket`
|
|
- `UsageWindow`
|
|
- `UsageCredits`
|
|
|
|
The structure should cover provider identity, plan/tier, generic allowed/limit-reached flags, one or more windows, and credits metadata.
|
|
|
|
**Step 2: Run targeted compile check**
|
|
|
|
Run: `go test ./core/...`
|
|
Expected: compile failures in engine/tests until the command layer is wired.
|
|
|
|
**Step 3: Keep the types minimal**
|
|
|
|
Do not add provider-specific fields unless they are broadly useful.
|
|
|
|
**Step 4: Re-run compile check**
|
|
|
|
Run: `go test ./core/...`
|
|
Expected: still failing only because `/usage` command is not yet fully integrated.
|
|
|
|
### Task 2: Add `/usage` built-in command and output formatter
|
|
|
|
**Files:**
|
|
- Modify: `core/engine.go`
|
|
- Modify: `core/i18n.go`
|
|
- Test: `core/engine_test.go`
|
|
|
|
**Step 1: Write/extend failing tests**
|
|
|
|
Add tests for:
|
|
|
|
- `/usage` dispatch to a supporting agent
|
|
- unsupported-agent message
|
|
- successful output formatting with representative report data
|
|
|
|
**Step 2: Run the targeted tests**
|
|
|
|
Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
|
|
Expected: FAIL because the command is not registered yet.
|
|
|
|
**Step 3: Implement command plumbing**
|
|
|
|
Update:
|
|
|
|
- built-in command registration
|
|
- command dispatch switch
|
|
- bot command listing
|
|
- help/i18n text
|
|
|
|
Add a `cmdUsage` implementation that:
|
|
|
|
- type-asserts `UsageReporter`
|
|
- fetches usage with timeout
|
|
- formats a concise text response
|
|
|
|
**Step 4: Run the targeted tests again**
|
|
|
|
Run: `go test ./core/... -run 'Test.*Usage|TestHandleCommand'`
|
|
Expected: PASS
|
|
|
|
### Task 3: Implement Codex usage retrieval against ChatGPT OAuth
|
|
|
|
**Files:**
|
|
- Modify: `agent/codex/codex.go`
|
|
- Add or Modify: `agent/codex/usage.go`
|
|
- Test: `agent/codex/usage_test.go`
|
|
|
|
**Step 1: Write failing tests for the mapper/fetcher**
|
|
|
|
Cover:
|
|
|
|
- successful parsing of a representative `wham/usage` payload
|
|
- missing `auth.json`
|
|
- missing token/account fields
|
|
- HTTP error response
|
|
|
|
**Step 2: Run the targeted tests**
|
|
|
|
Run: `go test ./agent/codex -run 'Test.*Usage'`
|
|
Expected: FAIL because the implementation does not exist yet.
|
|
|
|
**Step 3: Implement minimal production code**
|
|
|
|
Add:
|
|
|
|
- auth file path resolver
|
|
- auth JSON loader
|
|
- HTTP request builder
|
|
- response DTOs
|
|
- mapping into `core.UsageReport`
|
|
|
|
Prefer dependency injection for:
|
|
|
|
- auth file path / reader
|
|
- HTTP client / transport
|
|
|
|
So tests avoid live network and real user files.
|
|
|
|
**Step 4: Run the targeted tests again**
|
|
|
|
Run: `go test ./agent/codex -run 'Test.*Usage'`
|
|
Expected: PASS
|
|
|
|
### Task 4: End-to-end verification and cleanup
|
|
|
|
**Files:**
|
|
- Modify: `README.md`
|
|
- Modify: `README.zh-CN.md`
|
|
- Modify: `CHANGELOG.md`
|
|
|
|
**Step 1: Document the new command**
|
|
|
|
Add `/usage` to command lists and a short explanation that support depends on the current agent.
|
|
|
|
**Step 2: Run focused test suites**
|
|
|
|
Run: `go test ./core/... ./agent/codex`
|
|
Expected: PASS
|
|
|
|
**Step 3: Run broader verification**
|
|
|
|
Run: `go test ./...`
|
|
Expected: PASS, or identify unrelated pre-existing failures clearly.
|
|
|
|
**Step 4: Commit**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git add core/interfaces.go core/engine.go core/i18n.go core/engine_test.go agent/codex/codex.go agent/codex/usage.go agent/codex/usage_test.go README.md README.zh-CN.md CHANGELOG.md docs/plans/2026-03-12-usage-design.md docs/plans/2026-03-12-usage.md
|
|
git commit -m "feat: add usage command for codex oauth"
|
|
```
|