@cad0p/pi-tree-navigator 0.1.0 → 0.1.1-20260809.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.1] - 2026-07-31
+
+<!-- USER-EDITABLE SECTION START -->
+Patch release: restores the mid-loop context refresh on pi ≥0.80.3. No behavior change on pi ≤0.80.2.
+
+**The bug (pi ≥0.80.3):** pi 0.80.3 added `AgentSession._installAgentNextTurnRefresh()`, which installs pi's own `agent.prepareNextTurnWithContext` in the constructor, and pi-agent-core's `Agent.createLoopConfig` now prefers that field over `agent.prepareNextTurn`. Since this extension only wrapped `prepareNextTurn`, its mid-loop context replacement was dead code: after a `rewind`, the branch summary landed correctly, but every remaining turn of the same loop still sent the full pre-rewind context to the API, and the footer's context-% re-anchored on that stale usage (jumping back up right after the rewind). Rewinds only actually saved context on the *next* user prompt.
+
+**The fix:** `installPrepareNextTurn` now wraps both hook fields with the same marker/`__prior` chaining discipline. On pi ≥0.80.3 the `prepareNextTurnWithContext` wrapper chains pi's own (keeping its per-turn `systemPrompt`/`tools`/`model`/`thinkingLevel` refreshes) and overrides only `messages`; on pi ≤0.80.2 the new field is never read and `prepareNextTurn` does the work as before.
+
+Verified live on pi 0.83.0 (persisted session): after a rewind at 31.5% context, the footer stays at ~1.6% for the rest of the loop (previously bounced back to ~33.5%), and the post-rewind API call goes out with ~3.7k tokens instead of ~80.5k.
+<!-- USER-EDITABLE SECTION END -->
+
+### 🚀 Features
+
+- Discriminated-union schema makes summaryFocus required at the wire level ([#1](https://github.com/cad0p/pi-tree-navigator/pull/1))
+
+### 🐛 Bug Fixes
+
+- Revert discriminated-union parameters — Kiro rejects non-object root schemas ([#2](https://github.com/cad0p/pi-tree-navigator/pull/2))
+- Wrap prepareNextTurnWithContext — in-loop context refresh dead since pi 0.80.3 ([#8](https://github.com/cad0p/pi-tree-navigator/pull/8))
+
+### 🚜 Refactor
+
+- Nest extension under extensions/navigate-tree/ per pi-napkin convention
+
+### 📚 Documentation
+
+- Promote npm install and publishing ([#4](https://github.com/cad0p/pi-tree-navigator/pull/4))
+
+### ⚙️ Miscellaneous Tasks
+
+- Release-grade cleanup for v0.1.0 ([#3](https://github.com/cad0p/pi-tree-navigator/pull/3))
+- Switch from bun to node + pnpm for local dev and CI ([#6](https://github.com/cad0p/pi-tree-navigator/pull/6))
+
+
 ## [0.1.0] - 2026-05-25
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -6,28 +6,31 @@ Lets a pi agent anchor named milestones in its own conversation, then collapse w
 
 ## Install
 
+Stable npm release:
+
 ```bash
-pi install git:github.com/cad0p/pi-tree-navigator
+pi install npm:@cad0p/pi-tree-navigator
 ```
 
-> **Status:** v0.1.0 is not yet on the npm registry (pending OIDC trusted-publisher setup). Install from the git source for now.
+Pre-release npm snapshots from `main` are published with the `next` dist-tag:
 
-<details>
-<summary>Once published / pre-release installs</summary>
+```bash
+pi install npm:@cad0p/pi-tree-navigator@next
+```
 
-- Stable (once published to npm):
+You can also install directly from the git source when testing unreleased branches:
 
-  ```bash
-  pi install npm:@cad0p/pi-tree-navigator
-  ```
+```bash
+pi install git:github.com/cad0p/pi-tree-navigator
+```
 
-- Pre-release (calver snapshots from `main`, published to npm `@next` on every push):
+## Publishing
 
-  ```bash
-  pi install npm:@cad0p/pi-tree-navigator@next
-  ```
+This repo uses [`cad0p/semver-calver-release`](https://github.com/cad0p/semver-calver-release)'s npm-package workflow:
 
-</details>
+- Pushes to `main` compute the next hybrid SemVer + CalVer version, tag a GitHub prerelease, and publish to npm with the `next` dist-tag.
+- Curated release PRs from `release/from-v*` branches bump the base `package.json` version and publish stable npm releases.
+- npm publishing uses GitHub OIDC / npm trusted publishing via `.github/workflows/release.yml` (`id-token: write`) and `publishConfig.access: public`.
 
 ### Requirements
 
@@ -36,7 +39,7 @@ pi install git:github.com/cad0p/pi-tree-navigator
   - `@earendil-works/pi-coding-agent >=0.74.0`
   - `@earendil-works/pi-agent-core >=0.74.0`
   - `typebox ^1.0.0` (used to declare the tool's parameter schema; bundled with pi but listed explicitly so a standalone install resolves correctly).
-- The reflection bootstrap depends on five plain (not `#`-private) internal pi/agent fields: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, and `agent.prepareNextTurn`. Verified against pi 0.75.x.
+- The reflection bootstrap depends on six plain (not `#`-private) internal pi/agent fields: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, `agent.prepareNextTurn` (pi ≤0.80.2), and `agent.prepareNextTurnWithContext` (preferred by pi ≥0.80.3). Verified against pi 0.75.5 and pi 0.83.0.
 
 ## What you get
 
@@ -90,7 +93,7 @@ The synthetic assistant we inject after each rewind carries the **post-rewind ch
 
 ## Limitations
 
-- **Brittle to pi version bumps.** The fix uses five independent reflection points on internals that aren't part of pi's public API: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, and `agent.prepareNextTurn`. If a future pi release renames any of these, switches them to private (`#`) fields, or restructures the class hierarchy, this breaks. The extension fails loudly: `anchor` still works, `rewind` reports `⚠ reflection bootstrap missing — the rewind landed on disk but the next assistant turn may still see the pre-rewind context. Run \`/reload\` (or restart pi) to recover.`, and you'd see context corruption return on the next prompt.
+- **Brittle to pi version bumps.** The fix uses six independent reflection points on internals that aren't part of pi's public API: `AgentSession.prototype.prompt`, `agent.state.messages`, `agent.state.systemPrompt`, `agent.state.tools`, `agent.prepareNextTurn`, and `agent.prepareNextTurnWithContext`. This is not hypothetical: pi 0.80.3 added `prepareNextTurnWithContext` and made the loop prefer it, silently dead-ending the `prepareNextTurn`-only hook until v0.1.1. If a future pi release renames any of these, switches them to private (`#`) fields, or restructures the class hierarchy, this breaks. The extension fails loudly: `anchor` still works, `rewind` reports `⚠ reflection bootstrap missing — the rewind landed on disk but the next assistant turn may still see the pre-rewind context. Run \`/reload\` (or restart pi) to recover.`, and you'd see context corruption return on the next prompt.
 
 - **Anchor early in the turn.** Whatever's in `agent.state.messages` *before* the `anchor` tool call stays in the kept chain. Everything after gets summarized. Anchor at the *start* of a stage for maximum context savings.
 
@@ -107,13 +110,13 @@ The synthetic assistant we inject after each rewind carries the **post-rewind ch
 ## Development
 
 ```bash
-bun install
-bun test          # helpers + dispatch / reflection bootstrap / salvage path
-bunx biome check extensions/
-bunx tsc --noEmit
+pnpm install
+pnpm test          # helpers + dispatch / reflection bootstrap / salvage path
+pnpm run lint      # biome check extensions/
+pnpm run typecheck # tsc --noEmit
 ```
 
-Tests cover `extensions/navigate-tree/helpers.ts` (pure helpers in `helpers.test.ts`) and `extensions/navigate-tree/index.ts` (action dispatch, schema shape, synthetic-assistant injection, reflection bootstrap, salvage path — in `index.test.ts`). The `summarize` factory option injects a stub for `generateBranchSummary` so no real LLM call fires during rewind tests. Additional manual e2e validation against pi 0.75.x is recommended for any pi version bump (the reflection bootstrap depends on internal field shapes).
+Tests cover `extensions/navigate-tree/helpers.ts` (pure helpers in `helpers.test.ts`) and `extensions/navigate-tree/index.ts` (action dispatch, schema shape, synthetic-assistant injection, reflection bootstrap, salvage path — in `index.test.ts`). The `summarize` factory option injects a stub for `generateBranchSummary` so no real LLM call fires during rewind tests. Additional manual e2e validation against the current pi release (0.83.x at time of writing) is recommended for any pi version bump (the reflection bootstrap depends on internal field shapes).
 
 ## License
 

package/extensions/navigate-tree/index.ts

@@ -22,18 +22,20 @@
  *   this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
  *
  * Risks of the reflection approach:
- *   • If pi switches any of the five fields this extension reads —
+ *   • If pi switches any of the six fields this extension reads —
  *     `AgentSession.prototype.prompt`, `agent.state.messages`,
- *     `agent.state.systemPrompt`, `agent.state.tools`, or
- *     `agent.prepareNextTurn` — to ES `#` private fields, this breaks
- *     fundamentally.
+ *     `agent.state.systemPrompt`, `agent.state.tools`,
+ *     `agent.prepareNextTurn`, or `agent.prepareNextTurnWithContext` —
+ *     to ES `#` private fields, this breaks fundamentally.
  *   • If pi renames or restructures any of these fields, this breaks.
  *   • Patches `AgentSession.prototype.prompt` globally on import; not
  *     reversible without a process restart; affects every session in
  *     the pi process, including sessions that never call
  *     `navigate_tree`.
  *
- * Verified against pi 0.75.5.
+ * Verified against pi 0.75.5 (`prepareNextTurn` path) and pi 0.83.0
+ * (`prepareNextTurnWithContext` path — required since pi 0.80.3, see
+ * `installPrepareNextTurn`).
  */
 
 import { estimateContextTokens } from "@earendil-works/pi-agent-core";
@@ -116,6 +118,7 @@ const LIST_PCT_COL_WIDTH = 5;
 // hint column visible without truncating common names.
 const LIST_LABEL_COL_WIDTH = 28;
 const PNT_MARKER = Symbol.for("navigate-tree.pnt-installed");
+const PNTWC_MARKER = Symbol.for("navigate-tree.pntwc-installed");
 const ORIG_PROMPT_KEY = Symbol.for("navigate-tree.orig-prompt");
 
 // Two warnings: list-site (read-only path; warns about the next turn's
@@ -144,6 +147,10 @@ interface PiInternals {
       tools: unknown[];
     };
     prepareNextTurn?: unknown;
+    // Preferred over `prepareNextTurn` by `Agent.createLoopConfig`
+    // when set; pi's own AgentSession always sets it (via
+    // `_installAgentNextTurnRefresh`) since pi-coding-agent 0.80.3.
+    prepareNextTurnWithContext?: unknown;
   };
   sessionManager: SessionManager;
 }
@@ -163,14 +170,22 @@ type PntResult = {
   thinkingLevel?: unknown;
 };
 // pi 0.75.5 invokes `agent.prepareNextTurn(signal)` from
-// `Agent.createLoopConfig` — a single AbortSignal argument. This differs
-// from the documented `AgentLoopConfig.prepareNextTurn(context: PrepareNextTurnContext)`
-// shape, which `Agent` is bridging. We accept whatever pi passes and forward
-// it verbatim to the prior wrapper so we don't fight a future signature
-// alignment. Verified against pi-coding-agent 0.75.5; revisit if the call
-// site changes.
+// `Agent.createLoopConfig` — a single AbortSignal argument. Since pi
+// 0.80.3 the loop instead invokes
+// `agent.prepareNextTurnWithContext(nextTurnContext, signal)` (and only
+// falls back to `prepareNextTurn` when the WithContext field is unset).
+// Both differ from the documented
+// `AgentLoopConfig.prepareNextTurn(context: PrepareNextTurnContext)`
+// shape, which `Agent` is bridging. We accept whatever pi passes and
+// forward it verbatim to the prior wrapper so we don't fight a future
+// signature alignment. Verified against pi-coding-agent 0.75.5 and
+// 0.83.0; revisit if the call site changes.
 type PntFn = (...args: unknown[]) => Promise<PntResult> | PntResult;
-type MarkedPntFn = PntFn & { [PNT_MARKER]?: boolean; __prior?: PntFn };
+type MarkedPntFn = PntFn & {
+  [PNT_MARKER]?: boolean;
+  [PNTWC_MARKER]?: boolean;
+  __prior?: PntFn;
+};
 
 // =============================================================================
 // Reflection bootstrap & in-loop refresh
@@ -218,17 +233,32 @@ function patchAgentSessionPrototype(): void {
 }
 
 /**
- * Wire `agent.prepareNextTurn` so the in-flight agent loop refreshes its
- * context from sessionManager between turns within the same prompt() call.
- * Without this, the loop snapshots agent.state.messages once at prompt start
- * and pushes new messages onto its own array — a rewind issued mid-loop
- * doesn't reduce the next API call's size until the user sends a new prompt.
+ * Wire the in-flight agent loop to refresh its context from sessionManager
+ * between turns within the same prompt() call. Without this, the loop
+ * snapshots agent.state.messages once at prompt start and pushes new
+ * messages onto its own array — a rewind issued mid-loop doesn't reduce
+ * the next API call's size until the user sends a new prompt.
+ *
+ * Two hook fields, by pi version:
+ *   • pi ≤0.80.2: `Agent.createLoopConfig` reads `agent.prepareNextTurn`.
+ *   • pi ≥0.80.3: AgentSession's constructor installs its own
+ *     `agent.prepareNextTurnWithContext` (`_installAgentNextTurnRefresh`),
+ *     and `createLoopConfig` prefers that field over `prepareNextTurn`.
+ *     Pi's wrapper refreshes systemPrompt/tools/model/thinkingLevel per
+ *     turn but leaves `messages` stale — so wrapping only
+ *     `prepareNextTurn` silently dead-ends (footer % and the wire context
+ *     stay pre-rewind for the rest of the loop).
+ *
+ * We install on BOTH fields, each with the same marker/__prior chaining
+ * discipline: on new pi the WithContext wrapper chains pi's own (keeping
+ * its per-turn refreshes) and overrides only `messages`; on old pi the
+ * WithContext field is never read and `prepareNextTurn` does the work.
  *
- * The Agent class's `createLoopConfig` dereferences `this.prepareNextTurn`
- * at the closure call site, so the value here is read at every turn boundary.
- * But it gates the closure on `this.prepareNextTurn` being truthy at config
- * creation — so we have to set this BEFORE prompt() runs, hence wiring it
- * from inside the prompt patch.
+ * The Agent class's `createLoopConfig` dereferences both fields at the
+ * closure call site, so the values here are read at every turn boundary.
+ * But it gates the closure on either field being truthy at config
+ * creation — so we have to set this BEFORE prompt() runs, hence wiring
+ * it from inside the prompt patch.
  */
 function installPrepareNextTurn(session: AgentSession): void {
   const internals = asInternals(session);
@@ -237,15 +267,22 @@ function installPrepareNextTurn(session: AgentSession): void {
 
   const sm = internals.sessionManager;
 
-  // If the existing prepareNextTurn was installed by a previous load of THIS
-  // extension, recover the chain it captured (its `__prior`) so we don't
-  // strand other extensions' closures across /reload. Preserve any other
-  // extension's prepareNextTurn so we compose with them.
+  // If the existing hooks were installed by a previous load of THIS
+  // extension, recover the chains they captured (their `__prior`) so we
+  // don't strand other extensions' closures across /reload. Preserve any
+  // other extension's (or pi's own) hooks so we compose with them.
   const existing = agent.prepareNextTurn as MarkedPntFn | undefined;
   const prior: PntFn | undefined =
     typeof existing === "function" && existing[PNT_MARKER]
       ? existing.__prior
       : (existing as PntFn | undefined);
+  const existingWc = agent.prepareNextTurnWithContext as
+    | MarkedPntFn
+    | undefined;
+  const priorWc: PntFn | undefined =
+    typeof existingWc === "function" && existingWc[PNTWC_MARKER]
+      ? existingWc.__prior
+      : (existingWc as PntFn | undefined);
 
   const next: MarkedPntFn = async (...args: unknown[]) => {
     let priorResult: PntResult | undefined;
@@ -273,6 +310,40 @@ function installPrepareNextTurn(session: AgentSession): void {
   next[PNT_MARKER] = true;
   next.__prior = prior;
   agent.prepareNextTurn = next;
+
+  const nextWc: MarkedPntFn = async (...args: unknown[]) => {
+    // On pi ≥0.80.3 the loop calls this as (nextTurnContext, signal),
+    // where nextTurnContext = { message, toolResults, context,
+    // newMessages }. Forward args verbatim to the prior (pi's own
+    // wrapper expects exactly this shape).
+    const turn = args[0] as { context?: PntResult["context"] } | undefined;
+    let priorResult: PntResult | undefined;
+    if (typeof priorWc === "function") {
+      priorResult = await priorWc(...args);
+    }
+    // Same wholesale-replacement rationale as the prepareNextTurn
+    // wrapper above. When no prior result exists, fall back to the
+    // turn's live context (mirrors pi's own wrapper, which does
+    // `previousSnapshot?.context ?? turn.context`) so systemPrompt and
+    // tools are never dropped. `messages` is owned by this wrapper —
+    // this override is the entire point of the hook on pi ≥0.80.3, whose
+    // own wrapper refreshes every other field but leaves messages stale.
+    const priorContext = priorResult?.context ?? turn?.context;
+    return {
+      ...priorResult,
+      context: {
+        ...priorContext,
+        systemPrompt: priorContext?.systemPrompt ?? agent.state.systemPrompt,
+        tools: priorContext?.tools ?? agent.state.tools,
+        messages: sm.buildSessionContext().messages,
+      },
+      model: priorResult?.model,
+      thinkingLevel: priorResult?.thinkingLevel,
+    };
+  };
+  nextWc[PNTWC_MARKER] = true;
+  nextWc.__prior = priorWc;
+  agent.prepareNextTurnWithContext = nextWc;
 }
 
 function findOwningSession(sm: SessionManager): AgentSession | null {
@@ -934,8 +1005,11 @@ export const __testHooks = {
   installPrepareNextTurn,
   refreshAgentMessages,
   captureSession,
-  /** Symbol used to mark the wrapper installed by `installPrepareNextTurn`. */
+  /** Symbols used to mark the wrappers installed by `installPrepareNextTurn`
+   * (`PNT_MARKER` on `agent.prepareNextTurn`, `PNTWC_MARKER` on
+   * `agent.prepareNextTurnWithContext` — the field pi ≥0.80.3 prefers). */
   PNT_MARKER,
+  PNTWC_MARKER,
   /** Read-only view of captured-session ref count for reaping assertions. */
   sessionRefCount(): number {
     return sessionInstances.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cad0p/pi-tree-navigator",
-  "version": "0.1.0",
+  "version": "0.1.1-20260809.0",
   "description": "agent-callable session tree navigation for pi: anchor named milestones, rewind work into a branch summary, free up context for long autonomous sessions",
   "publishConfig": {
     "access": "public",
@@ -36,14 +36,14 @@
     ]
   },
   "scripts": {
-    "lint": "bunx biome check extensions/",
-    "lint:fix": "bunx biome check --write extensions/",
-    "typecheck": "bunx tsc --noEmit",
-    "test": "bun test"
+    "lint": "biome check extensions/",
+    "lint:fix": "biome check --write extensions/",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test extensions/**/*.test.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
-    "@types/bun": "^1.3.0",
+    "@types/node": "^22.0.0",
     "typescript": "^5.8.0"
   },
   "peerDependencies": {