pi-blackhole 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -2,8 +2,50 @@
 
 ---
 
+## [0.5.8] - 2026-09-22
+
+### Changed
+
+- **Observation-pool measurement is centralized.** The dropper trigger, `/blackhole-memory` pool lines, and footer P gauge each summed the active pool with their own inline copy; they now share `observationPoolTokens()` (`ledger/progress.ts`), which sums the live active pool plus — always explicitly — manual-mode pending observation batches. `/blackhole-memory` now includes those pending batches in its `Obs pool` / `Dropper:` percentages (so a manual-only user sees the same pool the trigger gates on) and labels the split (`· branch 0 + pending 1,400`); the footer P gauge deliberately stays branch-only. No trigger, threshold, or dropper-candidate behavior changes ([#120](https://github.com/k0valik/pi-blackhole/issues/120)).
+
+- **Pi loads the prebuilt `dist/index.js`.** `pi.extensions` now points at the tsup bundle instead of `./index.ts`, removing jiti transpilation of the whole module graph on startup (measured import 500 to 570 ms down to 350 to 530 ms, factory time unchanged). Registry installs ship `dist/` in the tarball. Git installs need `npmCommand` set so devDependencies install and `prepare` builds `dist/`; when they don't, `scripts/prepare.mjs` now warns that the extension will not load instead of failing silently, documented next to the GitHub install command in `README.md`.
+
+### Fixed
+
+- **`agentMaxTurns` is enforced on Pi 0.87.** The observer, reflector, and dropper capped their loops with `shouldStopAfterTurn`, which 0.87 removed in favour of `finishTurn` (whose `{ action: "end" }` ends the run), so the configured turn budget was silently ignored and a worker could keep running until it stopped naturally, errored, or was aborted. Both hooks are now emitted through `createTurnCap` with independent counters, so the loaded generation picks the one it knows and a host calling both still ends at `maxTurns`; a turn that already hard-exited (`error`/`aborted`) neither decides the run nor spends budget ([upstream OM `#83`](https://github.com/elpapi42/pi-observational-memory/pull/83)).
+- **Extension registration survives class-based `ExtensionAPI` hosts.** `registerCompactFailedHook` widened and then invoked `pi.on` detached, so a host whose `on` reads instance state (e.g. oh-my-pi's `ConcreteExtensionAPI`) threw `TypeError: undefined is not an object (evaluating 'this.extension')` during registration and took the rest of the extension's hooks down with it; the handler is now bound to `pi` before the widening cast, a no-op on pi's closure-based API ([#124](https://github.com/k0valik/pi-blackhole/pull/124)).
+- **Custom-provider streams keep their receiver when the bridge dispatches them.** Each `streamSimple` handler was stored in the global capture map detached from its provider config, and the api-only fallback for host-aliased provider ids extracted it the same way. A class-based config that reads instance state therefore threw `Cannot read properties of undefined`: the capture-map path crashed the worker stream, while the aliased path swallowed the error and silently degraded to the compat dispatcher. Captured handlers are now bound to their config, and the api-only match is invoked on it ([upstream OM `#80`](https://github.com/elpapi42/pi-observational-memory/pull/80)).
+
+---
+
+## [0.5.7] - 2026-09-21
+
+### Added
+
+- **Footer status bar.** pi-blackhole now shows live state in the pi footer (config key `statusBar`, default on; env `PI_BLACKHOLE_STATUSBAR`): three token gauges — O (transcript since the last observer run), P (observation pool fill), X (context since the last compaction) — plus worker spinners, `✓ +N` completion events, and compaction notes with their trigger reason. Gauges color by fill: dim under 80%, theme warning color from 80%, theme error color at 100%. The bar reads in-process state (`runtime.config`, `model-budget.ts`, `ledger/progress.ts`, `runtime.consolidationPhase`), so its numbers match `/blackhole-memory` status; it adds no file polling and no threshold guessing, only a 1-second in-process poll of the runtime state. If you ran the standalone `blackhole-status.ts` footer extension before, remove it: two writers on the same `setStatus` key race.
+
+### Changed
+
+- **Pi 0.87 is supported.** The `@earendil-works/*` devDependencies move to `0.87.0` in lockstep and the dependabot `>=0.87.0` hold is removed ([#118](https://github.com/k0valik/pi-blackhole/issues/118)). `peerDependencies` (`>=0.85.1 <1.0.0`) is unchanged: the observational-memory system-prompt carrier is probed at runtime, so consolidation keeps its prompt on 0.85/0.86 (legacy `AgentContext.systemPrompt`) and 0.87+ (leading transcript system message) — see Fixed.
+- **CI runs on pull requests targeting `dev` too.** `ci.yml` previously triggered only for `pull_request → main`, so PRs merged into the working branch were gated by bot reviews alone. The full gate (build → typecheck → lint → test → format:check) now covers both branches.
+- **Installs work under pnpm's built-in minimum-release-age policy.** pnpm 11 enforces a 24-hour minimum release age by default, which rejected the brand-new `@earendil-works/*@0.87.0` set. The toolchain pin moves to `pnpm@11.27.1` and those versions are listed in `minimumReleaseAgeExclude` (the previous pin, `11.2.2`, ignored that list), so `pnpm install --frozen-lockfile`, CI, and git-based extension installs no longer wait out the window.
+
+### Fixed
+
+- **The compact-shape guard follows Pi 0.87's `_refreshFinalizedContext()` indirection.** 0.87 moved the `agent.state.messages` repoint out of `AgentSession.compact()` into a helper, so the guard that requires the write _inside_ `compact()` rejected the class and mid-run inline compaction failed closed on 0.87 ([#117](https://github.com/k0valik/pi-blackhole/issues/117)). The guard now accepts an assignment found one call level deep in one of the class's own prototype methods, and still rejects inherited helpers, deeper indirection, and a helper that only reads the property.
+- **Observational-memory consolidation keeps its system prompt on Pi 0.87.** 0.87 removed `AgentContext.systemPrompt` and now carries the prompt as a leading transcript `system` message, so the observer, reflector, and dropper would have silently run without their prompts. They now build whichever carrier the loaded host reads — probed by the presence of Pi 0.87's `createInitialSystemMessage` helper, not a version allowlist — so 0.85/0.86 keep the legacy field and 0.87+ gets the transcript message ([#118](https://github.com/k0valik/pi-blackhole/issues/118)).
+- **Discover Pi 0.86's bundled host behind its `createRequire` launcher.** Follow the same-package bootstrap file without executing it before locating the runtime chunk, so inline compaction captures the active `AgentSession` instead of patching the unused modular class and falling back to settled compaction. A bootstrap target that is missing, unreadable, or outside the Pi package now leaves the launcher's own source in place, so the direct-import scan still runs instead of being skipped.
+- **Observer preamble cap now applies in auto/off compaction modes.** `observerPreambleMaxTokens` was previously only enforced in manual mode, so auto-mode observer prompts could grow without bound even though the main session prompt stayed capped by `observationsPoolMaxTokens`; the observer now applies the same relevance-ranked selection budget in all modes, defaulting to 30% of `observerChunkMaxTokens` when unset.
+- **Observer preamble cap now covers reflections, and the context guard prices the full prompt.** Reflections were never trimmed (no drop entry type exists for them), leaving a permanently growing floor on the observer preamble; each preamble section is now capped at `observerPreambleMaxTokens` (reflections newest-first). The pre-flight `observer.context_window_exceeded` guard previously measured only `chunkTokens + 8000`, so oversized prompts sailed through and failed every attempt with a provider 400; it now accounts for the rendered preamble and the observer system prompt, skipping the model cleanly instead.
+
+---
+
 ## [0.5.6] - 2026-09-19
 
+### Added
+
+- **Pre-compaction output stays visible after compaction** ([#103](https://github.com/k0valik/pi-blackhole/pull/103), thanks @sonSunnoi). After a successful Blackhole compaction, the newest assistant text removed from view is re-rendered as a display-only **Previous output — display only** block, so recent work stays readable without opening `/tree`. Bounded and opt-out: 16 KiB UTF-8 cap with a truncation marker, text only (no tool output, thinking, or images), idempotent per compaction, skipped when the newest dropped text is retained; disabled via `showPreCompactionMessage` (default `true`, env `PI_BLACKHOLE_SHOW_PRE_COMPACTION_MESSAGE`).
+
 ### Changed
 
 - **Minimum supported Pi raised to 0.85.1; compat-floor CI retired.** The `compat-min-supported` job re-pinned the `@earendil-works/*` peers to the `peerDependencies` floor and typechecked against them, going red every time. The extension now builds against the pinned devDependencies (0.85.1) and the peer floor is set to match; `peerDependencies` remains the single source of truth for the declared minimum.

package/README.md

@@ -12,7 +12,10 @@
 # From npm (recommended)
 pi install npm:pi-blackhole
 
-# Or directly from GitHub
+# Or directly from GitHub.
+# Requires npmCommand to be set in settings.json, otherwise pi runs
+# `npm install --omit=dev`, devDependencies are skipped, and dist/ is not built.
+# Example: "npmCommand": ["npm"] in ~/.pi/agent/settings.json
 pi install git:github.com/k0valik/pi-blackhole
 ```
 
@@ -31,14 +34,15 @@ Then `/reload` or restart Pi. The config file at `~/.pi/agent/pi-blackhole/pi-bl
 
 ## ✨ What's new
 
-> **Latest release: [0.5.6](CHANGELOG.md)**
+> **Latest release: [0.5.8](CHANGELOG.md)**
 >
-> - **Non-English (CJK) sessions are now fully script-aware** — token accounting counts CJK as ~1 token/char (no more ~3× silent overage), text clipping and `recall` queries respect CJK punctuation and word boundaries, and the extractors accept CJK correction anchors and failure stems. ([#105](https://github.com/k0valik/pi-blackhole/issues/105), [#106](https://github.com/k0valik/pi-blackhole/issues/106))
-> - **`[Files And Changes]` and `[Commits]` extract what actually happened** — file attribution correlates tool calls with results instead of guessing from a hardcoded tool list, and commit capture understands real-world flag orders and heredocs. ([#105](https://github.com/k0valik/pi-blackhole/issues/105))
-> - **Observer chunks always respect `maxTokens`** — `custom_message` entries (previously zero-counted) are now sized like every other entry. ([#110](https://github.com/k0valik/pi-blackhole/issues/110))
-> - **`[Files And Changes]` display and cross-compaction merge overhauled** — cwd-relative paths, capped lists that never shrink, and `(#N)` drill-down refs.
-
-See [`CHANGELOG.md`](CHANGELOG.md) for the full history.
+> - **Pi loads a prebuilt bundle** — `pi.extensions` points at the tsup `dist/index.js` instead of TypeScript source, cutting startup import time (500–570 ms → 350–530 ms). Registry installs ship `dist/`; git installs need `npmCommand` set, and a missing `dist/` now warns instead of failing silently.
+> - **Every observation-pool readout agrees** — the dropper trigger, `/blackhole-memory` pool lines, and the footer P gauge each summed the pool inline; they now share one helper, and `/blackhole-memory` includes (and labels) manual-mode pending batches so the display matches what the trigger gates on. No threshold or candidate behavior changes. ([#120](https://github.com/k0valik/pi-blackhole/issues/120))
+> - **`agentMaxTurns` is enforced on Pi 0.87** — the worker loops emitted only the removed `shouldStopAfterTurn`, so the turn budget was silently ignored; `createTurnCap` now emits both that hook and 0.87's `finishTurn`, with independent counters. ([upstream OM `#83`](https://github.com/elpapi42/pi-observational-memory/pull/83))
+> - **Extension registration survives class-based hosts** — hooks were invoked detached from their API object, which threw on hosts like oh-my-pi; handlers are now bound before registration. ([#124](https://github.com/k0valik/pi-blackhole/pull/124))
+> - **Custom-provider streams keep their receiver** — captured `streamSimple` handlers are bound to their config, so class-based providers no longer crash or silently fall back to the compat dispatcher. ([upstream OM `#80`](https://github.com/elpapi42/pi-observational-memory/pull/80))
+>
+> See [`CHANGELOG.md`](CHANGELOG.md) for the full history.
 
 ---
 
@@ -73,7 +77,8 @@ Both halves share a single hook and a single output. Together they keep the agen
 
 All commands work regardless of `compaction` mode — only _when_ auto-compaction fires changes. See [Compaction modes](#compaction-modes) below.
 
-### The `recall` tool (agent-facing)
+<details>
+<summary>The `recall` tool (agent-facing)</summary>
 
 The agent gets one unified `recall` tool that handles every form of historical lookup. Searches read the raw session file directly, bypassing compaction.
 
@@ -95,6 +100,8 @@ Every recall response is capped at `recallResponseMaxChars` (default 48,000 ≈
 
 The `/blackhole-recall` command exposes the same engine to the user. Results are shown as a collapsible message and auto-fed to the agent as context.
 
+</details>
+
 ---
 
 ## Compaction modes
@@ -195,7 +202,8 @@ If any stage fails (model error, rate limit, timeout), remaining stages are skip
 
 ---
 
-## What the agent sees after compaction
+<details>
+<summary>What the agent sees after compaction</summary>
 
 After compaction, the agent sees something like this (sections appear only when relevant — a session with no git commits won't show `[Commits]`):
 
@@ -248,9 +256,12 @@ Use `recall` with an id to retrieve original context.
 
 > **Note:** The OM injection format uses `## Reflections` and `## Observations` Markdown headers followed by a brief footer. Each observation and reflection has a 12-char hex identifier the agent (and you, via `/blackhole-recall`) can use to recover source evidence. When no observations or reflections exist, only the short recall-guidance footer is appended.
 
+</details>
+
 ---
 
-## Feature comparison
+<details>
+<summary>Feature comparison</summary>
 
 |                                             | pi-blackhole | pi-vcc | pi-obs-memory | Pi default |
 | ------------------------------------------- | ------------ | ------ | ------------- | ---------- |
@@ -268,6 +279,8 @@ Use `recall` with an id to retrieve original context.
 | Unified single-file config                  | ✓            | —      | —             | —          |
 | Per-session pending state                   | ✓            | —      | —             | —          |
 
+</details>
+
 ---
 
 ## Uninstall
@@ -285,6 +298,7 @@ rm -rf ~/.pi/agent/pi-blackhole
 | ------------------------------------------------------------ | ----------------- | ----------------------------------------------------------------------------------------- |
 | **[`README.md`](README.md)**                                 | You, now          | Install, commands, the pitch, the value, the demo.                                        |
 | **[`CHANGELOG.md`](CHANGELOG.md)**                           | You               | Every release, what changed, who contributed.                                             |
+| **[`CONTRIBUTING.md`](CONTRIBUTING.md)**                     | You, if helping   | Branch model, dev setup, PR description format, docs/changelog gates.                     |
 | **[`docs/CONFIG.md`](docs/CONFIG.md)**                       | You, when tuning  | Every config key with type, default, behavior, and env-var overrides.                     |
 | **[`llms.txt`](llms.txt)**                                   | Your agent        | Step-by-step guided setup interview, anti-patterns, exact file paths, internal constants. |
 | **[`docs/MIGRATION-GUIDE.md`](docs/MIGRATION-GUIDE.md)**     | You, if upgrading | Old → new config key mapping, semantic changes, automatic migration behavior.             |
@@ -296,16 +310,6 @@ rm -rf ~/.pi/agent/pi-blackhole
 
 ---
 
-## Migration from an older version
-
-If you're upgrading from a pre-0.4.0 config (the old `pi-vcc` / `pi-observational-memory` keys, or an early `pi-blackhole` config with `overrideDefaultCompaction` / `noAutoCompact` / `passive`): see **[`docs/MIGRATION-GUIDE.md`](docs/MIGRATION-GUIDE.md)** for the key mapping, semantic changes, and notes on automatic migration.
-
-The short version: old keys are auto-migrated in memory at load time and the on-disk file is never mutated. Set the new keys explicitly via `/blackhole settings` (alias `/blackhole configure`) to silence the migration notification.
-
-The legacy config surface is documented at **[`docs/OLD_CONFIG.md`](docs/OLD_CONFIG.md)** for reference only — no new keys are added there.
-
----
-
 ## Credits
 
 `pi-blackhole` started as a merge of two upstream projects but has since diverged significantly. The codebase still carries DNA from both: