@cad0p/pi-tree-navigator 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.3] - 2026-09-14
+
+<!-- USER-EDITABLE SECTION START -->
+Last version before adopting the branch summarization cache hit mechanism to save everyone money -> https://github.com/earendil-works/pi/issues/9411
+<!-- USER-EDITABLE SECTION END -->
+
+### 🚀 Features
+
+- *(ci)* Daily pi-upstream reflection probe (closes #17)
+- *(guidelines)* Steer agents to anchor early at context-gathered (closes #29)
+- Mandate anchoring via before_agent_start system prompt (closes #31)
+
+### 🐛 Bug Fixes
+
+- *(rewind)* Reject degenerate rewinds below a min-savings floor (closes #21, closes #20)
+- *(rewind)* Inject opencode session headers for summarization (closes #26)
+
+### ⚙️ Miscellaneous Tasks
+
+- *(tooldef)* Trim navigate_tree tool definition (~848 → ~470 tok/request) (closes #22)
+
+
 ## [0.1.2] - 2026-08-20
 
 <!-- USER-EDITABLE SECTION START -->

package/README.md

@@ -53,6 +53,8 @@ A single agent-callable tool, `navigate_tree`, with three actions:
 
 `name` (written by `anchor`) and `labelEnd` (written by `rewind`) both share the reserved `anchor:` label prefix; `labelStart` resolves against that same namespace. Every label written by `anchor` and every `labelEnd` written by `rewind` is referenceable by any subsequent `rewind`'s `labelStart`, and `list` shows all of them.
 
+**Anchoring is mandated, not suggested.** On every agent start the extension appends a one-line mandate to the end of the system prompt (`before_agent_start`), gated on the tool being active: `navigate_tree: gather all context, then anchor \`context-gathered\`; list anchors and rewind after every milestone or rabbit hole / dead end.` The append lands after project context and skills, is re-applied on every prompt, and survives compaction — unlike the `promptGuidelines` bullet it replaced. ~35 tokens, constant for prompt caching.
+
 ## How it works
 
 A typical autonomous-loop pattern:
@@ -99,6 +101,8 @@ The synthetic assistant we inject after each rewind carries the **post-rewind ch
 
 - **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.
 
+- **Tiny rewinds are rejected by a minimum-savings floor.** A `rewind` whose measured savings falls below an internal floor (~4k tokens of apparent context freed) is refused with guidance listing the active anchors instead of executing — collapsing a near-empty segment burns a summarizer LLM call and can even grow live context once the summary and its synthetic assistant land on the kept chain. This pairs with anchoring early: anchor at the start of a stage, then rewind only once real work has accumulated above the anchor.
+
 - **Abandoned branches grow the JSONL forever.** Each rewind preserves the abandoned subtree on disk. Session files get bigger over time even as live context shrinks. For very long autonomous runs (days), session files can hit hundreds of MB.
 
 - **Tested against Anthropic and Kiro providers.** The synthetic-tool_use trick is specifically for Anthropic's strict tool_use/tool_result pairing; the synthetic's `stopReason: "toolUse"` survives Kiro's `normalizeMessages` filter. Other providers may have different validation rules — untested.

package/extensions/navigate-tree/index.ts

@@ -36,6 +36,7 @@
  * `buildContextMessages`), not `agent.prepareNextTurn*` reflection.
  */
 
+import { randomUUID } from "node:crypto";
 import {
   estimateContextTokens,
   type StreamFn,
@@ -64,10 +65,22 @@ import {
 } from "./helpers.ts";
 
 const LABEL_PREFIX = "anchor:";
+const TOOL_NAME = "navigate_tree";
+
+/**
+ * Always-on anchor mandate appended to the system prompt on every agent
+ * start (gated on the tool being active). Same lever as pi-napkin's vault
+ * mandate: `promptGuidelines` bullets land mid-prompt; this append lands
+ * at the very end of the system prompt, after <project_context> and
+ * skills, and is re-applied on every prompt (never compacted). Byte-stable
+ * (module constant, no per-session interpolation) for provider caching.
+ */
+export const ANCHOR_MANDATE = `${TOOL_NAME}: gather all context, then anchor \`context-gathered\`; list anchors and rewind after every milestone or rabbit hole / dead end.`;
 
 // ---------------------------------------------------------------------------
 // Exported boundary constants below (MAX_SESSION_REFS, MAX_HINT_WALK_DEPTH,
-// MIN_SUMMARY_FOCUS_LENGTH, MAX_SYNTHETIC_FOCUS_LENGTH).
+// MIN_SUMMARY_FOCUS_LENGTH, MIN_REWIND_SAVINGS_TOKENS,
+// MAX_SYNTHETIC_FOCUS_LENGTH).
 //
 // Stability: these are internal tunables. Exported only so the test suite
 // can pin boundary cases by constant rather than literal. Re-tuning is
@@ -95,6 +108,19 @@ export const MAX_HINT_WALK_DEPTH = 50;
 // reliably loses continuity — raising it forces more useful focus text
 // without inviting verbosity.
 export const MIN_SUMMARY_FOCUS_LENGTH = 20;
+// Floor on the *apparent* token savings (`beforeTokens − tokensAtTarget`) a
+// `rewind` must clear to execute. Absolute threshold, deliberately NOT
+// window-relative: % semantics drift with window size, so a fixed token bar
+// is the only stable shape. Every rewind carries ≈350–900 tokens of fixed
+// overhead (the branch_summary adds ~300–800 permanent tokens on the kept
+// chain; the synthetic assistant re-emits ~50 on every subsequent turn), so
+// apparent savings OVERSTATES true freed context. Empirically the degenerate
+// anchor→immediate-rewind case measures ~100 apparent tokens while a healthy
+// stage measures ~20k — 4k separates them cleanly (~200×) and roughly equals
+// one 300-line source-file read (~5.9k tokens measured). Below the floor a
+// rewind burns a summarizer LLM call, forks a junk branch_summary, consumes
+// a milestone label, and GROWS live context.
+export const MIN_REWIND_SAVINGS_TOKENS = 4000;
 // Cap on the `summaryFocus` length stored in the synthetic assistant's
 // arguments. The full focus is passed live to `generateBranchSummary`, so
 // the summarizer always sees the original; we only need a trimmed copy in
@@ -248,6 +274,53 @@ function stripNullHeaders(
     : undefined;
 }
 
+/**
+ * Session-routing headers for the summarization request.
+ *
+ * Pi's live turns merge these in `sdk.ts` via `mergeProviderAttributionHeaders`
+ * (session headers + install-telemetry attribution). Out-of-loop summarization
+ * callers — pi's own `agent-session.navigateTree` and this extension — pass only
+ * auth headers, so providers that REQUIRE the session header 400 the request
+ * (`MissingSessionID`; observed on opencode-go 2026-09-07: every rewind and every
+ * native `/tree` summary fails deterministically).
+ *
+ * The tool-execute ctx exposes neither `settingsManager` (telemetry attribution)
+ * nor the live routing `sessionId`, so this replicates only the session half of
+ * pi's merge (`getSessionHeaders` in `provider-attribution.ts`): for
+ * opencode-family providers, inject `x-opencode-session` + `x-opencode-client`.
+ * The value is a fresh UUID per rewind — upstream does the same for routing
+ * (`completeSummarization` falls back to `uuidv7()` when the caller passes no
+ * session id), and one-off summaries have no continuation to route. Proven by
+ * the branch-summary eval harness, whose identical injection succeeds on
+ * opencode-go where the bare call 400s. Never overrides a header the auth layer
+ * already set.
+ */
+function withSessionHeaders(
+  model: { provider?: string; baseUrl?: string } | undefined,
+  headers: Record<string, string> | undefined,
+): Record<string, string> | undefined {
+  const provider = model?.provider ?? "";
+  let host = "";
+  try {
+    host = model?.baseUrl ? new URL(model.baseUrl).hostname : "";
+  } catch {
+    host = "";
+  }
+  const needsSession =
+    provider === "opencode" ||
+    provider === "opencode-go" ||
+    host === "opencode.ai";
+  if (!needsSession) return headers;
+  const merged = { ...(headers ?? {}) };
+  if (!merged["x-opencode-session"]) {
+    merged["x-opencode-session"] = randomUUID();
+  }
+  if (!merged["x-opencode-client"]) {
+    merged["x-opencode-client"] = "pi";
+  }
+  return merged;
+}
+
 /**
  * Project the session tree's active branch into the messages the next LLM
  * call should see — the public-API replacement for the deleted
@@ -327,6 +400,49 @@ function estimateAtEntry(
   ).tokens;
 }
 
+/**
+ * Rejection copy for the rewind min-savings floor (#21). Reports the
+ * apparent savings plus every active anchor — chronological root→leaf,
+ * same walk order as `list`, including labelStart itself — with its
+ * cumulative context percentage, so the agent can pick a genuinely earlier
+ * anchor or keep working. Move-on-collision means the tool itself never
+ * creates duplicate anchor names; a manual `/label anchor:x` CAN put the
+ * same name on two entries — duplicates print twice here, exactly as
+ * `list` prints them today.
+ *
+ * Deliberately does NOT print the floor value anywhere: an agent-visible
+ * numeric bar invites grinding up to it instead of doing real work.
+ */
+function buildMinSavingsRejection(
+  labelStart: string,
+  labelEnd: string,
+  apparentSavings: number,
+  sm: SessionManager,
+  cw: number,
+  allEntries: SessionEntry[],
+  byId: Map<string, SessionEntry>,
+): string {
+  const anchors: string[] = [];
+  let oldestAnchorName: string | null = null;
+  for (const e of sm.getBranch()) {
+    const lbl = sm.getLabel(e.id);
+    if (!lbl?.startsWith(LABEL_PREFIX)) continue;
+    const name = lbl.slice(LABEL_PREFIX.length);
+    if (!oldestAnchorName) oldestAnchorName = name;
+    anchors.push(
+      `'${name}' ${formatPct1(estimateAtEntry(allEntries, e.id, byId), cw)}`,
+    );
+  }
+  // cw=0 → percents fall back to formatPct1's k-format and the window
+  // suffix is omitted, mirroring `list`'s header behavior.
+  const suffix = cw > 0 ? ` of ${formatWindow(cw)}` : "";
+  const guidance =
+    oldestAnchorName === labelStart
+      ? "No earlier anchors — keep working and rewind later once more has accumulated above it."
+      : "Rewind further back to actually free context, or keep working.";
+  return `Rewinding '${labelStart}' → '${labelEnd}' would free only ~${formatPct1(apparentSavings, 0)} tokens. ${guidance} Active anchors: ${anchors.join(" · ")}${suffix}`;
+}
+
 /**
  * Walk parentId chain back from `fromId` and return a one-line preview of
  * the first entry that has meaningful text content. Branch summaries are
@@ -452,22 +568,35 @@ export default function (
     messages: buildContextMessages(ctx.sessionManager),
   }));
 
+  // Anchor mandate (#31): a before_agent_start append lands at the END of
+  // the system prompt — stronger than the mid-prompt Guidelines block, and
+  // re-applied on every prompt instead of living in the conversation. Skip
+  // only when the tool is verifiably absent from the active set; fail-open
+  // when `selectedTools` is undefined (this extension always registers it).
+  pi.on("before_agent_start", async (event) => {
+    const selected = event.systemPromptOptions?.selectedTools;
+    if (Array.isArray(selected) && !selected.includes(TOOL_NAME)) return {};
+    return { systemPrompt: `${event.systemPrompt}\n\n${ANCHOR_MANDATE}` };
+  });
+
   pi.registerTool({
-    name: "navigate_tree",
+    name: TOOL_NAME,
     label: "Navigate Tree",
     // Stateful: every action mutates SessionManager; concurrent calls would
     // race on `leafId` / `labelsById` and produce an undefined tree.
     executionMode: "sequential",
-    description: `Long-session context management via the pi session tree. Anchor named milestones, then collapse work between them into a model-generated summary while preserving the full history on a sibling branch. Despite the verb, \`rewind\` does not restore prior state — it forks a sibling branch from the anchor and continues forward from a model-generated summary; the abandoned subtree is preserved on disk but no longer on the active path.
-
-Operations (set the \`action\` parameter):
-  • action='anchor', name='<milestone-name>': label the current point so a later rewind can target it. Use at the start of a stage you'll summarize (e.g. 'design-start', 'impl-start'). If the same name already exists on the active branch, the prior label is moved to the new leaf (no duplicates).
-  • action='rewind', labelStart='<existing>', labelEnd='<new>': collapse work between labelStart and the current leaf into a branch_summary. The new summary entry is itself labeled with labelEnd, so you can chain rewinds.
-  • action='list': show all named anchors on the active branch in chronological order, with cumulative context % at each anchor.
+    promptGuidelines: [
+      `${TOOL_NAME}: the further back you rewind, the more you free but the more collapses into the summary; pick the earliest anchor that still preserves what you need next.`,
+    ],
+    description: `Long-session context management via the pi session tree. Anchor named milestones, then collapse work between them into a model-generated summary to free context.
+\`rewind\` does not restore prior state: it forks a sibling branch from the anchor and continues forward from a model-generated summary.
 
-Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor namespace — either becomes addressable as a future \`labelStart\`. \`list\` shows every anchor under the \`anchor:\` prefix, regardless of which action wrote it. Pi labels written via \`/label anchor:foo\` (manually or by other extensions) are also addressable here. Avoid the \`anchor:\` prefix in manually-set labels.
+Operations (set \`action\`):
+  • 'anchor', name='<milestone-name>': label the current point. Anchor at the start of a stage you'll summarize (e.g. 'impl-start').
+  • 'rewind', labelStart='<existing>', labelEnd='<new>': collapse work between labelStart and the current leaf into a branch_summary labeled labelEnd, so rewinds can chain.
+  • 'list': show all anchors on the active branch, oldest first, with cumulative context % at each.
 
-\`summaryFocus\` is required when \`action='rewind'\` (≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim). Calls without it are rejected. It's passed to pi's \`generateBranchSummary\` as \`customInstructions\`, biasing the summarizer LLM toward the agent's specified focus while it rewrites the collapsed work into pi's structured summary format. To preserve continuity, instruct the summarizer to keep: (1) the user's most recent message verbatim, (2) what's done in the collapsed segment, (3) what's left to do as a next action.`,
+\`name\` (anchor) and \`labelEnd\` (rewind) write into one shared anchor namespace: re-using an existing label moves it to the new entry, and everything written there is addressable as a future \`labelStart\`. Avoid the reserved \`anchor:\` prefix.`,
     promptSnippet:
       "Use to anchor named milestones and rewind the conversation tree to a prior point with a model-generated summary, for token-efficient long autonomous sessions.",
     // The schema is intentionally a flat `Type.Object` with everything-but-
@@ -481,28 +610,27 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
       action: Type.Union(
         [Type.Literal("anchor"), Type.Literal("rewind"), Type.Literal("list")],
         {
-          description:
-            "Which operation to perform. 'anchor' labels the current point, 'rewind' collapses work between an anchor and the current leaf into a branch_summary, 'list' shows every anchor on the active branch.",
+          description: "Which operation to perform.",
         },
       ),
       name: Type.Optional(
         Type.String({
-          description: `Required when action='anchor'. Kebab-case label (max ${MAX_NAME_LENGTH} chars) for the milestone. If a label with this name already exists on the active branch, it is moved to the new leaf.`,
+          description: `Required when action='anchor'. Kebab-case milestone label, max ${MAX_NAME_LENGTH} chars.`,
         }),
       ),
       labelStart: Type.Optional(
         Type.String({
-          description: `Required when action='rewind'. Kebab-case name (max ${MAX_NAME_LENGTH} chars) of an existing anchor on the active branch — work between this anchor and the current leaf is summarized.`,
+          description: `Required when action='rewind'. Kebab-case name of an existing anchor on the active branch to rewind to.`,
         }),
       ),
       labelEnd: Type.Optional(
         Type.String({
-          description: `Required when action='rewind'. Kebab-case name (max ${MAX_NAME_LENGTH} chars) for the resulting branch_summary entry. If a label with this name already exists on the active branch, it is moved to the new entry (mirrors anchor's move-on-collision). Becomes addressable as a future labelStart.`,
+          description: `Required when action='rewind'. Kebab-case label for the resulting branch_summary entry; reusable as a future labelStart.`,
         }),
       ),
       summaryFocus: Type.Optional(
         Type.String({
-          description: `Required when action='rewind'. ≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim. Should encode (1) the user's most recent instruction verbatim, (2) what was done in the collapsed segment, (3) what's left to do as a next action.`,
+          description: `Required when action='rewind'; ≥${MIN_SUMMARY_FOCUS_LENGTH} chars after trim. Encode: (1) the user's most recent instruction verbatim, (2) what's done in the collapsed segment, (3) what's left to do as a next action.`,
         }),
       ),
     }),
@@ -595,7 +723,7 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
               type: "text",
               text:
                 `[anchor '${p.name}'] set at ${positionLine}${hintLine}\n\n` +
-                `When you finish this stage, call: navigate_tree(action='rewind', labelStart='${p.name}', labelEnd='<milestone-name>', summaryFocus='<≥${MIN_SUMMARY_FOCUS_LENGTH}-char focus: latest user instruction + done + remaining>').`,
+                `Once real work has accumulated after this anchor, collapse it into a summary with: ${TOOL_NAME}(action='rewind', labelStart='${p.name}', labelEnd='<milestone-name>', summaryFocus='<≥${MIN_SUMMARY_FOCUS_LENGTH}-char focus: latest user instruction + done + remaining>').`,
             },
           ],
           details: {
@@ -647,15 +775,13 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         );
       }
 
-      if (!ctx.model) {
-        return toolError("No model configured for summarization.");
-      }
-
-      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
-      if (!auth.ok) {
-        return toolError(`Auth resolution failed: ${auth.error}`);
-      }
-
+      // Token math hoisted ABOVE the model check / auth await (#21): these
+      // are pure SessionManager reads, and the min-savings floor below must
+      // be evaluable — and able to reject — before any auth resolution.
+      // `allEntries`/`byId` are hoisted out of the parented-assistant branch
+      // because the floor rejection copy reports per-anchor percentages from
+      // the same maps.
+      //
       // The leaf at execute time is the assistant that just streamed the
       // rewind tool call. Its `usage.input` is the *minimum* of recent API
       // calls in this turn, so estimating from it understates what the
@@ -663,6 +789,9 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
       // assistant's usage as baseline) so beforeTokens matches the value
       // `list` would have reported on the previous turn.
       const oldLeafEntry = sm.getEntry(oldLeaf);
+      const allEntries = sm.getEntries();
+      const byId = new Map<string, SessionEntry>();
+      for (const e of allEntries) byId.set(e.id, e);
       let beforeTokens: number;
       if (
         oldLeafEntry &&
@@ -670,14 +799,12 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         oldLeafEntry.message.role === "assistant" &&
         oldLeafEntry.parentId
       ) {
-        const allEntries = sm.getEntries();
-        const byId = new Map<string, SessionEntry>();
-        for (const e of allEntries) byId.set(e.id, e);
         beforeTokens = estimateAtEntry(allEntries, oldLeafEntry.parentId, byId);
       } else {
         beforeTokens = estimateActiveBranchTokens(sm);
       }
-      const contextWindow = ctx.model.contextWindow ?? 0;
+      const tokensAtTarget = estimateAtEntry(allEntries, target, byId);
+      const contextWindow = ctx.model?.contextWindow ?? 0;
 
       const { entries } = collectEntriesForBranchSummary(sm, oldLeaf, target);
       if (entries.length === 0) {
@@ -710,7 +837,7 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
           if (
             block &&
             block.type === "toolCall" &&
-            block.name === "navigate_tree" &&
+            block.name === TOOL_NAME &&
             isSyntheticShape
           ) {
             return toolError(
@@ -720,6 +847,38 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
         }
       }
 
+      // Minimum-savings floor (#21): refuse rewinds whose apparent savings
+      // is below MIN_REWIND_SAVINGS_TOKENS — collapsing a near-empty segment
+      // burns a summarizer LLM call, forks a junk branch_summary, consumes
+      // a milestone label, and grows live context. Placed AFTER the
+      // synthetic-boundary guard so the chained rewind-with-no-turns case
+      // keeps its specific diagnostic, and BEFORE the model/auth checks so
+      // the rejection fires without touching provider config.
+      const apparentSavings = beforeTokens - tokensAtTarget;
+      if (apparentSavings < MIN_REWIND_SAVINGS_TOKENS) {
+        return toolError(
+          buildMinSavingsRejection(
+            p.labelStart,
+            p.labelEnd,
+            apparentSavings,
+            sm,
+            contextWindow,
+            allEntries,
+            byId,
+          ),
+          { rejected: "min-savings", apparentSavings },
+        );
+      }
+
+      if (!ctx.model) {
+        return toolError("No model configured for summarization.");
+      }
+
+      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+      if (!auth.ok) {
+        return toolError(`Auth resolution failed: ${auth.error}`);
+      }
+
       const result = await summarize(entries, {
         // `auth.baseUrl` (OAuth/credential-derived endpoint, e.g.
         // githubCopilotOAuth) must be applied to the model, mirroring pi's
@@ -729,7 +888,7 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
           ? { ...ctx.model, baseUrl: auth.baseUrl }
           : ctx.model,
         apiKey: auth.apiKey ?? "",
-        headers: stripNullHeaders(auth.headers),
+        headers: withSessionHeaders(ctx.model, stripNullHeaders(auth.headers)),
         ...(auth.env ? { env: auth.env } : {}),
         signal: signal ?? new AbortController().signal,
         customInstructions: p.summaryFocus,
@@ -848,7 +1007,7 @@ Both \`name\` (anchor) and \`labelEnd\` (rewind) write into the same anchor name
       }
       const syntheticMsg = buildSyntheticAssistant(
         toolCallId,
-        "navigate_tree",
+        TOOL_NAME,
         syntheticArgs,
         ctx.model as
           | { api?: string; provider?: string; id?: string }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cad0p/pi-tree-navigator",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",