pi-blackhole 0.5.9 → 0.5.10

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ---
 
+## [0.5.10] - 2026-09-29
+
+### Fixed
+
+- **`/blackhole` on a branch Pi considers ineligible now reports nothing-to-compact instead of failing.** Pi's `AgentSession.compact()` runs `prepareCompaction()` _before_ it emits `session_before_compact`, so a branch whose entries after the last boundary fit inside `keepRecentTokens` is refused by the host before any blackhole hook can run. The refusal surfaced twice — as Pi's error card (`reason: "manual"` always renders `Compaction failed: …`) and again as `Compaction failed: Nothing to compact (session too small)` from the command's `onError`, whose benign set covered only `Compaction cancelled` and `Already compacted`. The 0.5.4 eligibility fix gated the auto-compaction trigger but not this call site. The command now asks the host's own question via the new `getCompactionIneligibility()` before it mutates anything: an ineligible branch reports `blackhole: nothing to compact yet — Pi's keep-recent budget still covers this branch` (or `already compacted — …`) as information and returns, and the check sits above the pending-observational-memory flush so a refusal no longer appends entries, clears the pending buffer, and announces a flush that never compacted. `onError` keeps the same messages as a backstop for the case where our probe and the host still disagree.
+- **The eligibility probe now resolves compaction settings with the session model.** `isCompactionEligible` called `settingsManager.getCompactionSettings()` with no argument, while Pi calls `getCompactionSettings(model)`; Pi resolves `compaction.modelOverrides["<provider>/<id>"]` for `keepRecentTokens` and `reserveTokens` only when handed the model, so the probe was asking a different question than the host — with a per-model override configured it could report a branch eligible that `compact()` then refuses (or the reverse). All four call sites now pass `ctx.model`.
+- **A cancelled `/blackhole` no longer adds a second, vaguer toast.** The own-cut guard already names the specific reason (`blackhole: Nothing to compact (no live messages)`, or the `tailBehavior` hint) before returning `{ cancel: true }`, and Pi renders `Compaction cancelled` itself for manual aborts; the command's `onError` was adding a third message on top of those.
+- **`/blackhole` loads the config before reading it.** The handler read `runtime.config.compaction` to decide whether to flush pending observational memory, but never called `runtime.ensureConfig`, which only `agent_start` did. When `/blackhole` was the first command of a session, a configured `compaction: "manual"` install read `DEFAULTS` (`"auto"`) and silently skipped the flush, so memory accumulated in the pending file and the summary missed it.
+- **An observer stream error no longer counts as a completed chunk.** A provider failure after a recorded batch used to return partial work as success, advancing `coversUpToId` past content that was never observed. `runObserver` now throws a `WorkerStreamError` (message unchanged); the stage keeps the cursor and retries through the fallback chain, logging `discardedCount`. A valid `complete: true` close from a run that recorded something is still kept when a later turn fails: the failure is warned with the error class only (per [#80](https://github.com/k0valik/pi-blackhole/issues/80)), logged as `observer.error_after_close`, and cools the model when deterministic. A run the turn cap cuts off before it closes is treated the same way when it recorded something; a cap firing before anything was recorded is still an empty success. ([#137](https://github.com/k0valik/pi-blackhole/pull/137))
+- **A failed reflector or dropper run no longer counts as finished work.** Both stages advance their cursor on success, so a partial result marked that work covered: unreflected observations were never crystallized again, and half-evaluated drop candidates were written under an `OM_OBSERVATIONS_DROPPED` marker. `runReflector` now throws a `WorkerStreamError` unless a valid `complete: true` batch that recorded reflections closed the review (a kept close returns `errorAfterClose`, which the stage cools and warns about exactly like the observer's); `runDropper` always throws, since `drop_observations` has no complete flag to prove the evaluation finished. The turn cap cuts a run that recorded something the same way an error does (a cap before anything was recorded is still an empty success), both stages log `discardedCount`, and neither spends another `agentMaxTurns` budget retrying a session model the cap already exhausted. The cap only reports exhaustion for a turn that did tool work, so a run that stopped naturally on exactly its last allowed turn keeps its result. ([#137](https://github.com/k0valik/pi-blackhole/pull/137))
+- **A stream failure that never reaches `agent_end` still reports what it discarded.** When the stream itself breaks, or `result()` rejects, the observer, reflector and dropper rethrow that error with the count of records already written attached, so the stage error logs no longer show `discardedCount: undefined` for the most common way a run dies. The error keeps its own identity — wrapping it would break the stage's stale-context and timeout checks — and a thrown value that cannot carry a property simply loses the count rather than the failure. A run cut off by the hard `workerAttemptTimeoutMs` deadline is the deliberate exception: the deadline rejects immediately with its own error instead of waiting to learn what the worker had recorded, so that path still logs `discardedCount: undefined`. ([#137](https://github.com/k0valik/pi-blackhole/pull/137))
+
+- **A provider body no longer cools a model because the worker framed it as an error.** `isDeterministicError` only accepts a bare 4xx code alongside an error signal word, but the `<worker> API error: ` framing supplied that word on every message the observer, reflector and dropper emit — so a status-shaped token anywhere in a provider body (`processed 401 rows`) counted as a real status and cooled the session model for the default hour. The framing is stripped before the signal-word check, the three workers build their messages from one prefix shared by the throw path and the kept-close path so the two cannot drift, and the reflector's kept-close debug entry now classifies the same framed message it would throw. ([#137](https://github.com/k0valik/pi-blackhole/pull/137))
+- **The kept-close toast no longer claims a cooldown that was not recorded.** A session model whose resolved config carries no provider/id never reaches the cooldown file (`recordDeterministicError` keys it on both), yet the warning still said `model cooled down; details in cooldown log`. It now reports only what was written (`deterministic error; no cooldown recorded`), alongside the existing `cooldownHours: 0` branch, which the observer and reflector stages share through one helper. ([#137](https://github.com/k0valik/pi-blackhole/pull/137))
+- **Token counts no longer read as retryable provider statuses.** The numeric alternatives in `RETRYABLE_ERROR_RE` matched as substrings, so `1500 tokens`, `5000 rows`, or `14290` classified retryable on the `retryable:`/`cooldownWorthy:` debug axis. The codes (`429`, `500`, `502`–`504`) are now word-boundary anchored; standalone codes and real phrasing (`429 Too Many Requests`, `HTTP 503`) still match. Nothing branches on this axis today (candidate cooldowns are recorded unconditionally), so the change is log-precision only.
+
+---
+
 ## [0.5.9] - 2026-09-26
 
 ### Added

package/README.md

@@ -2,7 +2,19 @@
 
 **Deterministic compaction + session-aware observational memory for [Pi](https://github.com/earendil-works/pi) — in one unified extension.**
 
-`/blackhole` replaces Pi's LLM-based `/compact` with an algorithmic structural summary — fast, zero-cost. Three background workers (Observer, Reflector, Dropper) capture durable facts and decisions that survive across compactions. Per-worker model fallback chains with persisted cooldowns. Manual flush mode. One JSON file to configure it all.
+`/blackhole` replaces Pi's LLM-based `/compact` with an algorithmic structural summary — fast, and the compaction step itself is zero-cost. Three background workers (Observer, Reflector, Dropper) run as separate billed model calls to capture durable facts and decisions that survive across compactions. Per-worker model fallback chains with persisted cooldowns. Manual flush mode. One JSON file to configure it all.
+
+> **A note from the maintainer: this is experimental.**
+>
+> It won't save you tokens by itself. Compacting is free — no model call, just structure. Remembering is not: the background workers wake up as your session grows, read what happened, and write down what seems worth keeping. Those are real billed calls. Untuned, on your main coding model, this costs more than doing nothing. It only earns its keep with the workers on something cheap or free.
+>
+> It also doesn't solve compaction — nobody has, as far as I know. It takes a different approach ([observational memory](https://mastra.ai/blog/observational-memory), via [pi-observational-memory](https://github.com/elpapi42/pi-observational-memory)) and merges it with [pi-vcc](https://github.com/sting8k/pi-vcc), because the two conflicted when installed together. I merged them and vibeslopped a lot on top: robustness work, new behavior, and bugfixes ported from both upstreams. The recap is pattern-matching, not understanding: it guesses at goals and preferences from their shape. The memory is model-written, so it has the opposite weakness: it can keep what sounds right but isn't. Assume both need the search tool as a backstop.
+>
+> Want only one half? Use the project that does just that half. No hard feelings.
+>
+> Scope stays tight on purpose: forks welcome, bug fixes welcome and reviewed, new features only if they serve conversation compaction itself — not the week's AI fad bolted on. Almost everything is a toggle, which I'll admit is tiring; I use a small slice myself. Memory on most days, off some days. Workers on free models, waking rarely, size-based auto-compaction as a backstop. Most days I don't compact at all — fresh sessions beat resumed ones.
+>
+> Best fit is someone who doesn't count every token: code locally and push the workers to free hosted models, or code on a top model and run the workers on a local card — knowing each worker's different instructions wipe the local prompt cache for the next one. No measurements, no comparisons against other methods. Fast and nearly free the way I run it, good enough for what I need.
 
 ---
 
@@ -34,14 +46,12 @@ Then `/reload` or restart Pi. The config file at `~/.pi/agent/pi-blackhole/pi-bl
 
 ## ✨ What's new
 
-> **Latest release: [0.5.9](CHANGELOG.md)**
+> **Latest release: [0.5.10](CHANGELOG.md)**
 >
-> - **Recall drill-downs can no longer flood your context** — every `#N:path` / `#N:text` expansion is capped by `recallResponseMaxChars`, and the cap names where to pick up (`continue at #42:src/auth.ts:412:30`), so a minified bundle or a huge write no longer dumps itself into the prompt.
-> - **Quiet sessions** — `showWorkerNotifications: false` silences routine observer/reflector/dropper progress toasts; warnings, errors, and `/blackhole*` command output stay visible.
-> - **Worker prompt caching is tunable per install** — `cacheRetention: none | short | long` is forwarded to all three worker streams, and unset inherits Pi's effective setting.
-> - **A hung worker model fails on a clock, not a hope** — new `workerAttemptTimeoutMs` bounds the whole agent loop (header waits, heartbeats, tool turns) per attempt; configured candidates then enter their normal cooldown and fallback chain.
-> - **Finished worker runs stop early** — `record_observations` / `record_reflections` accept a `complete` flag, so a fully-processed run ends instead of spending its `agentMaxTurns` budget.
-> - **Dropper pool pressure now works end to end** — gated on `observationsPoolMaxTokens` (the same pool the footer P gauge shows), it bypasses new-data gates and `1.0` disables it.
+> - **Memory workers that fail now fall back instead of silently skipping** — observer/reflector/dropper stream errors and turn-cap cutoffs throw into the model fallback chain, so a failed run no longer advances the cursor over work it never finished.
+> - **The turn cap only ends runs that did tool work** — a run that stops naturally on exactly its last allowed turn keeps its result instead of failing as cap-cut, and a capped session model is not retried on an identical budget.
+> - **`/blackhole` on an ineligible branch reports nothing-to-compact** — instead of Pi's error card plus a second failure toast when the branch already fits inside the keep-recent budget.
+> - **A cancelled `/blackhole` stays quiet, and the command loads the config first** — no second vaguer toast on cancel, and a `manual`-mode session flushes pending memory instead of reading defaults.
 >
 > See [`CHANGELOG.md`](CHANGELOG.md) for the full history.