mirror of
https://github.com/AgentSeal/codeburn.git
synced 2026-05-17 03:56:45 +00:00
6746ecc22f
Document the contributor onboarding path: - CONTRIBUTING.md: setup, npm scripts, coding conventions, PR process, the block-claude-coauthor enforcement, and the five providers without test coverage today (claude, gemini, goose, qwen, antigravity). - docs/architecture.md: 12-command CLI surface, parser pipeline, three cache layers, 14 optimize detectors, and the mac / gnome / build layouts with cited line numbers. - docs/providers/: one file per provider (17 providers plus the shared vscode-cline-parser helper). Each covers data path, storage format, caching, dedup key, quirks, and a "when fixing a bug here" checklist. Also fix two pre-existing documentation issues surfaced while writing the new docs: - RELEASING.md claimed GitHub Actions auto-publishes the CLI when a v* tag is pushed. There is no such workflow; CLI publishing is manual via npm publish. Updated the CLI section to reflect reality and kept the menubar (mac-v* tag) automation accurate. - .gitignore had CLAUDE.md unanchored, which on case-insensitive filesystems also matched docs/providers/claude.md. Anchored to /CLAUDE.md so the root-level memory file stays ignored without affecting subdirectory docs. All cited file paths, line numbers, function names, and test counts were verified against current code (41 test files, 558 tests passing).
35 lines
1.2 KiB
Markdown
35 lines
1.2 KiB
Markdown
# Pi
|
|
|
|
Pi agent CLI.
|
|
|
|
- **Source:** `src/providers/pi.ts`
|
|
- **Loading:** eager (`src/providers/index.ts:9`)
|
|
- **Test:** `tests/providers/pi.test.ts` (336 lines)
|
|
|
|
## Where it reads from
|
|
|
|
`~/.pi/agent/sessions/` (`pi.ts:55-57`).
|
|
|
|
## Storage format
|
|
|
|
JSONL (`pi.ts:98`).
|
|
|
|
## Caching
|
|
|
|
None.
|
|
|
|
## Deduplication
|
|
|
|
Per `<provider>:<path>:<responseId>` when a response ID is present, falling back to the entry timestamp, and finally to a line index (`pi.ts:164`).
|
|
|
|
## Quirks
|
|
|
|
- Undefined token fields in `message.usage` are coerced to `0` (`pi.ts:156-159`); never `undefined`.
|
|
- The provider name is taken from `source.provider` (`pi.ts:182`), not hard-coded. This matters because `pi.ts` is the parser for **both** Pi and OMP; see [`omp.md`](omp.md).
|
|
- Tool-call content type is extracted from the message envelope (`pi.ts:169-176`).
|
|
|
|
## When fixing a bug here
|
|
|
|
1. If you change parsing logic, also run `tests/providers/omp.test.ts` because OMP shares this code.
|
|
2. If the bug is "tokens are NaN", look at the coercion at `pi.ts:156-159`. A regression on this is silent and easy to miss.
|
|
3. If the bug is specific to the dedup behavior, decide which of the three fallback keys was used by adding a temporary log; the keys collide differently for old vs. new Pi versions.
|