@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/{extensions/check/README.md → docs/extensions/check.md}

@@ -1,27 +1,65 @@
 # check — cross-stack verification runs
 
 Run the project's test, lint, or typecheck command from Pi, watch it live, and
-turn its output into a navigable `file:line` list. The same run is available to
-the model as `run_check`, with structured failures instead of a wall of log
-text.
+turn its output into a navigable `file:line` list. The model gets the same run
+as `run_check`, with structured failures instead of a wall of log text. Detection
+is manifest-driven and deliberately generic: `check` assumes no language, test
+framework, or CI system.
 
-`check` is deliberately generic: it detects the project's command from its
-manifest or takes `check.command`, and it does not assume Node, Bun, a test
-framework, or a particular CI system.
+## Capabilities
 
-```
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Plan-mode refusal | `/check`, the read-only policy | Plan mode refuses a check because tests still write caches, snapshots, or generated files; approve the plan first. | Shipped |
+| Single active run | `run_check`, `/check` | A second run is refused with the corrective action while one process is active, instead of starting a parallel check. | Shipped |
+| Supervised run | `/check`, `run_check` | One process per command, with a wall-clock timeout, a bounded log, and `Esc` to cancel the process tree. | Shipped |
+| Command detection | a project manifest, `check.command` | The project's test, lint, and typecheck commands are found without configuration, with a shell command override. | Shipped |
+| Target selection | `/check` with a target, `run_check.target` | Run `test`, `lint`, `typecheck`, or `all`; `all` is the default. | Shipped |
+| Structured failures | `run_check` | The model gets `path`, `line`, `column`, `test`, `message`, and `command` instead of a wall of log text. | Shipped |
+| Failure list | `/check` | A navigable list with a detail view for the focused failure, drawn from a source excerpt or the bounded tail. | Shipped |
+| Rerun from the list | `r` in the failure list | Rerun the same check after reading a failure; `Enter` opens its detail and `Esc` closes. | Shipped |
+| Live run screen | `/check` | A scrolling tail that repaints while the command runs, so a silent compiler still shows progress. | Shipped |
+| Capped transcript | `run_check` | One status summary and at most five failure rows, expanded with `ctrl+o` to the model's 20-failure cap. | Shipped |
+| Headless report | `/check`, `run_check` | RPC, JSON, and print sessions post the summary plus the failure list, with no screen. | Shipped |
+| Honest fallback | `/check`, `run_check` | An unparsed failure names the exit status and the last output lines, never an invented location. | Shipped |
+
+## Quickstart
+
+```bash
 pi --extension ./extensions/check   # load just this extension
 pi -e .                             # load the whole @gavin-hu/my-pi-agent package
 pi install ./                       # install the package
 ```
 
-## Screens
+```text
+/check                              # run every detected command
+/check test                         # run the detected test command
+```
 
-<img src="../../assets/check.png" alt="The /check screen: a failed run with failure rows and the focused failure's message" width="100%">
+The model calls `run_check` with the same four targets.
 
-<img src="../../assets/check-detail.png" alt="The /check failure detail: the location and message over a source excerpt with the failing line marked by >" width="100%">
+## Tool
 
-## Tool rendering
+<img src="../../assets/tools/run_check.png" alt="The run_check transcript block: a status summary and two failure rows under a rail" width="100%">
+
+`run_check` — direct exposure (the default), `executionMode: "sequential"`,
+annotations `readOnlyHint: false`, `destructiveHint: false`,
+`openWorldHint: false`. It takes one optional parameter:
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `target` | `test` \| `lint` \| `typecheck` \| `all` | Which command to run; defaults to `all`. |
+
+Result (`details` / `structuredContent`): `{ target, status, commands, exitCode,
+durationMs, truncated, failures[] }`. `details` also carries the bounded `tail`,
+which the transcript block reads and the structured mirror deliberately omits.
+
+`content` is a short summary plus up to 20 failures. A failing check is a normal
+result (`isError: false`) so the model can fix it; a check that cannot run — no
+detected command, a spawn failure, or another run already active — is an error
+with the corrective action.
 
 The call line is `run_check <target>`. While the command runs, the result is one
 line — `Running bun run check… · 12s` — and it repaints once a second, so a
@@ -30,47 +68,19 @@ a capped view of the run: a status summary, at most five failure rows, and the
 bounded tail when nothing parsed. `ctrl+o` expands it to the model's 20-failure
 cap; `/check` remains the full navigable list.
 
-<img src="../../assets/tools/run_check.png" alt="The run_check transcript block: a status summary and two failure rows under a rail" width="100%">
-
 A failed command whose output parsed no location names the exit status in the
 summary, prints `no parsed failure; last output:`, and shows the last five tail
 lines instead of an exit-status row. The transcript never prints the model
 report; the full failure list and the tail stay in `details`.
 
-## What it does
-
-- **Detects a command** from `package.json`, `Cargo.toml`, `go.mod`, a pytest
-  configuration, a `justfile`, or a `Makefile`, or uses `check.command`.
-- **Runs it in a supervised process** with a wall-clock timeout and a bounded
-  log; `Esc` cancels the process tree.
-- **Shows a live tail** while the command runs, then a failure list with a
-  detail view for the focused failure: a source excerpt around `path:line` when
-  the file is readable, otherwise the bounded tail.
-- **Returns structured failures** to the model with `path`, `line`, `column`,
-  `test`, `message`, and `command`.
-- **Falls back honestly**: a failed command with no recognizable failure becomes
-  one “Command exited with status N” entry, with the bounded tail in its detail.
-- **One line on success**: `Check passed: bun run check · 12.4s`.
-
-## Tool
+## Commands
 
-`run_check` takes optional `target`:
-
-| Field | Value |
-|---|---|
-| `target` | `test`, `lint`, `typecheck`, or `all`; defaults to `all`. |
-| `exposure` | `direct`, active by default. |
-| `executionMode` | `sequential` — one run owns the process and the live buffer. |
-| `annotations` | `readOnlyHint: false`, `destructiveHint: false`, `openWorldHint: false`. |
-| `outputSchema` | `{ target, status, commands, exitCode, durationMs, truncated, failures[] }`, mirrored by `structuredContent`. |
+`/check [target]` runs one target, or every detected command, with the same
+timeout, bounded log, and failure list as `run_check`.
 
-`content` is a short summary plus up to 20 failures. `details` carries the full
-bounded failure list and the tail, which the transcript block reads. A failing
-check is a normal result (`isError: false`) so the model can fix it; a check
-that cannot run — no detected command, a spawn failure, or another run already
-active — is an error with the corrective action.
+<img src="../../assets/screens/check.png" alt="The /check screen: a failed run with failure rows and the focused failure's message" width="100%">
 
-## Command
+<img src="../../assets/screens/check-detail.png" alt="The /check failure detail: the location and message over a source excerpt with the failing line marked by >" width="100%">
 
 | Command | What it does |
 |---|---|
@@ -80,23 +90,27 @@ active — is an error with the corrective action.
 | `/check typecheck` | Run the detected typecheck command. |
 | `/check all` | Same as `/check`. |
 
-`getArgumentCompletions` offers the four targets. The command refuses while plan
-mode is on: relying on tests is still writing to the project (caches, snapshots,
-generated files), so the plan must be approved first.
+`getArgumentCompletions` offers the four targets. In the TUI the run screen
+shows a scrolling tail and `Esc cancel`; a failed run then opens the failure
+list, where `Enter` opens the focused failure's detail, `r` reruns, and `Esc`
+closes. The command refuses while plan mode is on: relying on tests is still
+writing to the project (caches, snapshots, generated files), so the plan must be
+approved first.
 
 ## Behaviour by mode
 
 | Mode | Behaviour |
 |---|---|
-| Interactive TUI | A live run screen with a scrolling tail and `Esc cancel`; then a failure list with `Enter` detail, `r` rerun, and `Esc` close. A pass posts one notice. |
-| RPC (`hasUI`) | Runs headless and posts the summary plus the failure list; no custom screen. |
+| Interactive TUI | The run screen, then the failure list; a pass posts one notice. |
+| RPC | Runs headless and posts the summary plus the failure list; no custom screen. |
 | `print` / `json` | Runs headless and posts the same report. |
 | `run_check` | No UI of its own. Returns the summary in `content`, the structured result, and a capped transcript block drawn from `details`. |
 
 ## Configuration
 
-The `check` section of the shared `bytefly.json` (global then project, project
-wins). All keys are JSON-only; none has a `/bytefly settings` row.
+The `check` section of the shared `bytefly.json`; resolution rules are in
+[`../configuration.md`](../configuration.md#check--verification-runs). All keys
+are JSON-only; none has a `/bytefly settings` row.
 
 | Key | Default | Bounds | Meaning |
 |---|---|---|---|
@@ -107,6 +121,19 @@ wins). All keys are JSON-only; none has a `/bytefly settings` row.
 `command` is the escape hatch for any stack without a detector. It is a shell
 command and runs with the project root as its working directory.
 
+## Security
+
+`check` executes project scripts. That is the same trust boundary as running the
+command yourself or letting the agent call `bash`: a project with a hostile
+`test` script can do anything your user can do. The extension does not add a
+sandbox. `/check` is user-invoked and refuses in plan mode; `run_check` declares
+`readOnlyHint: false`, so a permission policy can gate it, and plan mode blocks
+it.
+
+The extension adds no network calls of its own. The command's environment is
+made non-interactive (`CI=1`, `NO_COLOR=1`, `FORCE_COLOR=0`, `TERM=dumb`,
+`GIT_PAGER=cat`, `PAGER=cat`).
+
 ## Detection
 
 Detection order stops at the first family that declares a command:
@@ -141,25 +168,12 @@ the fallback for everything else:
 | `File "path", line N, in test` | Python tracebacks |
 | `FAILED path::test - message` | pytest |
 | `--- FAIL: Test` and `path:line:` | Go |
-| `panicked at path:line` / `thread 'test'` | Cargo |
+| `thread 'test' panicked at path:line` | Cargo |
 | anything else on a non-zero exit | one fallback entry with the bounded tail |
 
 Failures are deduped and capped at 200; the model report shows 20. A miss is
 never turned into an invented location.
 
-## Security
-
-`check` executes project scripts. That is the same trust boundary as running the
-command yourself or letting the agent call `bash`: a project with a hostile
-`test` script can do anything your user can do. The extension does not add a
-sandbox. `/check` is user-invoked and refuses in plan mode; `run_check` declares
-`readOnlyHint: false`, so a permission policy can gate it, and plan mode blocks
-it.
-
-The extension adds no network calls of its own. The command's environment is
-made non-interactive (`CI=1`, `NO_COLOR=1`, `FORCE_COLOR=0`, `TERM=dumb`,
-`GIT_PAGER=cat`, `PAGER=cat`).
-
 ## Limitations
 
 - Detection covers the families above. Other stacks need `check.command`.
@@ -188,7 +202,7 @@ made non-interactive (`CI=1`, `NO_COLOR=1`, `FORCE_COLOR=0`, `TERM=dumb`,
 
 | Aspect | Contract |
 |---|---|
-| Registration | `check(pi)` guards on `isExtensionEnabled("check")` and calls `registerCheck(pi)`, which registers `run_check`, `/check`, and one `session_shutdown` hook. The factory only registers. |
+| Registration | `checkExtension(pi)` guards on `isExtensionEnabled("check")` and calls `registerCheck(pi)`, which registers `run_check`, `/check`, and one `session_shutdown` hook. The factory only registers. |
 | Tool | `run_check`, `exposure: "direct"`, `executionMode: "sequential"`, annotations `{ readOnlyHint: false, destructiveHint: false, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, `structuredContent` mirror. |
 | Command | `/check [target]` with `getArgumentCompletions` for the four targets; reports through `ctx.ui.notify`. |
 | State | None persisted. The runtime closure owns the single active child, its controller, and the live line buffer; `session_shutdown` aborts it. |
@@ -249,5 +263,6 @@ Co-located tests cover config clamps, every detector family, the runner's
 streaming/timeout/cancel/log cap, the parsers, command planning, aggregation,
 the tool's output contract and transcript block, the command's guards and
 headless path, and both screens' keys and width bounds.
-`extensions/check/check.test.ts` runs a real Node script through the extension,
-so the process path is exercised without depending on Bun or a test framework.
+`extensions/check/extension.test.ts` runs a real Node script through the
+extension, so the process path is exercised without depending on Bun or a test
+framework.

package/{extensions/context/README.md → docs/extensions/context.md}

@@ -5,37 +5,41 @@ the conversation is too full, the report is where you decide to compact. It is
 command-only on purpose — no tool is declared, so the model's prompt budget is
 untouched.
 
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Window headline | `/context` | Pi's own estimate: tokens, window, percentage, free space, and the auto-compaction threshold with the headroom left before it. | Shipped |
+| Composition breakdown | `/context` | Where the window went — system prompt, active tool definitions, the conversation by role, injected pack context, summaries, and shell output. | Shipped |
+| Guarded compaction | `/context compact [instructions]`, `c` on the screen | Compact from the report without interrupting a streaming turn or a running compaction. | Shipped |
+| Compact result | `/context compact` result | The before and after token counts are reported, so the effect of the compaction is visible. | Shipped |
+| Honest drift | `/context` | The difference between Pi's total and the composition estimate, named instead of hidden by forcing the parts to add up. | Shipped |
+| Compaction history | `/context` | How many compactions the branch has, what the newest one cut from and to, and what its summary costs. | Shipped |
+| Largest messages | `/context` | The five largest single messages, so a report that is mostly one tool result says so. | Shipped |
+| Gauge rendering | the `/context` screen | The window and composition bars show ten or eight cells, colored by role, instead of leaving the reader to infer the shape. | Shipped |
+| Pending total | `/context` after a compaction | The report shows a pending total instead of a fabricated estimate while Pi recalculates the window. | Shipped |
+| Mode coverage | `/context` | A scrollable screen in the TUI, the same facts as plain text in `rpc`, `json`, and `print`. | Shipped |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/context    # load just this extension
 pi -e .                                # load the whole @gavin-hu/my-pi-agent package
 pi install ./                          # install the package
 ```
 
-## What it does
-
-- Registers one command, `/context`. In the TUI it opens a docked screen; in
-  `rpc`, `json`, and `print` it notifies the same facts as plain text.
-- Reports Pi's own estimate first — tokens, window, percentage, free space, the
-  auto-compaction threshold, and the headroom left before it while compaction is
-  on — then the composition under a header that names the composition's own
-  estimate: the system prompt, the active tool definitions, the conversation by
-  role, injected pack context grouped by type, summaries, and shell output.
-- Names the difference between Pi's total and the composition estimate instead
-  of forcing the parts to add up: one line with both figures, `unattributed` when
-  the host's total is the larger one, and `host counts messages only` before the
-  first reply, when Pi's fallback leaves the prompt and the tools out.
-- Rounds each bar to the nearest cell, so a bar sits within half a cell of the
-  percentage printed beside it; the percentage itself is exact.
-- Reads the branch's compaction history: how many compactions there have been,
-  what the newest one cut from and to, and how much its summary costs.
-- Lists the five largest single messages, so a report that is mostly one tool
-  result says so.
-- Compacts from the report: `c` on the screen asks first, `/context compact
-  [instructions]` runs directly. Both refuse while the agent is busy — a
-  streaming turn or a running compaction.
+```text
+/context                               # the report
+/context compact focus on the parser   # compact from it, with instructions
+```
 
 ## Commands
 
+One command, two forms: `/context` reports, `/context compact` acts on the
+report.
+
 | Command | What it does |
 |---|---|
 | `/context` | The report: a screen in the TUI, a notification elsewhere |
@@ -67,6 +71,18 @@ largest messages. `/context compact` is the same in every mode and reports throu
 
 ## How the numbers are computed
 
+The report gives Pi's own estimate first — tokens, window, percentage, free
+space, the auto-compaction threshold, and the headroom left before it while
+compaction is on — then the composition under a header that names the
+composition's own estimate.
+
+It names the difference between Pi's total and the composition estimate instead
+of forcing the parts to add up: one line with both figures, `unattributed` when
+the host's total is the larger one, and `host counts messages only` before the
+first reply, when Pi's fallback leaves the prompt and the tools out. Each bar
+rounds to the nearest cell, so a bar sits within half a cell of the percentage
+printed beside it; the percentage itself is exact.
+
 | Row | Source |
 |---|---|
 | Headline (`tokens`, `percent`) | `ctx.getContextUsage()`: the last valid provider usage plus Pi's estimate of the messages after it. `tokens` is `null` between a compaction and the next successful reply, because the last usage describes the pre-compaction context. |
@@ -76,6 +92,7 @@ largest messages. `/context compact` is the same in every mode and reports throu
 | Tool definitions | `pi.getAllTools()` filtered to `pi.getActiveTools()`, over each active tool's name, description, and parameter schema at characters/4. `promptGuidelines` are counted in the system prompt instead, because Pi renders them into its rules section. |
 | Conversation rows | `sessionManager.buildSessionProjection().messages`, each counted with Pi's own `estimateTokens` (characters/4; an image is 4800 characters; a tool call is its name plus its JSON arguments). |
 | Injected context | `custom` messages grouped by `customType`, biggest first; the five largest types are named and the rest fold into one row. |
+| Largest messages | The five highest `estimateTokens` values in the projection, each with its role and a bounded descriptor: a tool name, a custom type, a command, or the first line of text. |
 | Threshold | `compaction.modelOverrides["provider/id"]`, then `compaction`, then `DEFAULT_COMPACTION_SETTINGS` — the same three-step fallback Pi uses. |
 | Compaction history | `getLatestCompactionEntry(branch)` and the branch's `compaction` count. The summary's cost is the summary text at characters/4. |
 | Drift | `tokens - estimate`, printed with both figures. A positive value appends `+… unattributed` — usage the rows do not explain; a negative one appends `host counts messages only` while the projection holds no assistant message, because Pi's message-only fallback omits the system prompt and the tool definitions. |
@@ -119,7 +136,7 @@ largest messages. `/context compact` is the same in every mode and reports throu
 
 | Contract | Detail |
 |---|---|
-| Registration | The default export registers the `/context` command and nothing else. No tool, no flag, no shortcut, no session hook. |
+| Registration | The default export registers the `/context` command and nothing else, behind the `PI_DISABLED_EXTENSIONS` gate. No tool, no flag, no shortcut, no session hook. |
 | Tool surface | None. Command-only, so there is no `promptSnippet`, `annotations`, `executionMode`, or `outputSchema`. |
 | Host reads | `ctx.getContextUsage()`, `ctx.getSystemPrompt()`, `ctx.model`, `ctx.isIdle()`, `ctx.sessionManager.buildSessionProjection()` / `getBranch()`, `pi.getActiveTools()` / `getAllTools()` / `getSettings()`. All in `collect.ts`. |
 | Action | `ctx.compact({ customInstructions, onComplete, onError })`. It is fire-and-forget; the callbacks repaint the screen or notify the command's caller. |