pi-context 1.1.4 → 2.0.0-beta.0

package/skills/context-management/references/development-and-troubleshooting.md

@@ -0,0 +1,75 @@
+# Development and Troubleshooting
+
+Use this reference for long-running:
+- implementation
+- debugging
+- troubleshooting
+- refactoring
+- migration
+- review or audit work
+
+These tasks often stay cleaner when treated as stages with anchors, instead of one uninterrupted thread. If multiple alternative approaches, failed branches, or route comparisons become central, also read `retry-branch-and-pivot.md`.
+
+## Working pattern
+
+1. Create a checkpoint before starting serious work.
+2. Add checkpoints before risky edits, new approaches, or major phase changes.
+3. Review the timeline when you need to understand the current shape of the work.
+4. Rewind after a stable implementation milestone, a failed approach, or a completed troubleshooting phase.
+
+## Typical checkpoint moments
+
+Checkpoint:
+- before starting implementation
+- before a risky refactor
+- before trying an alternative fix
+- after a milestone like "root cause confirmed" or "first pass implemented"
+- before switching to a side task
+
+Example checkpoint names:
+- `parser-fix-start`
+- `cache-refactor-attempt-2`
+- `migration-plan-ready`
+- `incident-root-cause-confirmed`
+
+## Timeline review moments
+
+Run `context_timeline` when:
+- multiple attempts now exist
+- the task moved from diagnosis to implementation
+- you are about to abandon one approach and restart from another anchor
+- you are unsure which checkpoint best represents the clean continuation point
+
+## Rewind patterns
+
+### After a failed attempt
+
+Use rewind when an attempt clearly failed and you have a crisp summary of why.
+
+```javascript
+context_rewind({
+  target: "memory-leak-fix-start",
+  message: "WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Reason: abandoning this attempt and returning to a clean anchor. Next step: try object pooling instead.",
+  backupCheckpoint: "memory-leak-weakref-raw-history"
+});
+```
+
+### After a completed phase
+
+Use rewind when a phase is done and you want to continue from a cleaner thread.
+
+```javascript
+context_rewind({
+  target: "parser-fix-start",
+  message: "Parser fix is implemented and the debugging phase is complete. Reason: compacting implementation history before focused validation. Next step: run targeted validation and summarize remaining edge cases.",
+  backupCheckpoint: "parser-fix-debug-history"
+});
+```
+
+## Warning signs
+
+Switch into stronger context-management behavior when:
+- you are accumulating many partial theories
+- the thread contains multiple fix attempts
+- you keep revisiting earlier reasoning
+- the next step is clear but the path behind it is getting noisy

package/skills/context-management/references/planning-and-execution.md

@@ -0,0 +1,79 @@
+# Planning and Execution
+
+Use this reference when the work is organized around an explicit execution frame, such as:
+- a formal implementation or migration plan
+- a roadmap with multiple milestones
+- a lightweight todo list or checklist
+- staged execution that will be revisited, updated, or reordered across many turns
+
+The defining feature here is not just that the work has phases. It is that execution repeatedly returns to an explicit plan, roadmap, or todo baseline.
+
+## Two common variants
+
+### Formal plan
+Examples:
+- a plan produced by a planning step or planning agent
+- a migration plan with several services or phases
+- a rollout plan with checkpoints and validation steps
+
+### Lightweight todo / checklist
+Examples:
+- a short task list for a refactor
+- a checklist for a release or audit
+- a small execution outline that will be worked through item by item
+
+Both variants use the same context-management rhythm.
+
+## Working pattern
+
+1. Create or confirm the plan / todo list.
+2. Create a checkpoint for the clean plan-ready state.
+3. Execute one subtask or phase.
+4. If that subtask becomes noisy, let it get noisy locally.
+5. Once the subtask produces a stable takeaway, rewind back to the plan-ready or phase-start anchor.
+6. Continue with the next subtask from the clean anchor.
+7. If the plan changes materially, checkpoint the updated plan state again.
+
+## Useful anchors
+
+Example checkpoint names:
+- `auth-migration-plan-ready`
+- `release-rollout-plan-ready`
+- `parser-refactor-todo-baseline`
+- `cleanup-phase-2-start`
+- `vendor-audit-milestone-1`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- several subtasks have already been executed
+- the plan has changed more than once
+- multiple branches now exist under the same plan
+- you are unsure whether to rewind to the overall plan anchor or the current phase-start anchor
+
+## When to rewind
+
+Rewind when:
+- a subtask is complete and its raw execution path is no longer worth keeping active
+- a phase finished and the next phase should start from a cleaner state
+- the plan remains valid but the current execution segment has become noisy
+
+Do not rewind just because a todo list exists. Rewind when a specific execution segment has already served its purpose and can be compacted.
+
+## Replan
+
+If the plan itself changes materially:
+1. finish or abandon the current noisy segment
+2. summarize the change in direction
+3. checkpoint the new plan-ready state
+4. continue from the updated plan anchor
+
+If the plan change is driven by failed branches or strategy shifts, also read `retry-branch-and-pivot.md`.
+
+## Common mistakes
+
+Avoid:
+- keeping every finished subtask's raw reasoning active
+- rewinding too far back when the current plan-ready anchor is still valid
+- failing to checkpoint the updated plan after a major replan
+- confusing repeated-item work with plan-driven work when the subtasks are actually different in nature

package/skills/context-management/references/repeated-items-and-batch-work.md

@@ -0,0 +1,68 @@
+# Repeated Items and Batch Work
+
+Use this reference when the work involves many similar items handled over many turns, such as:
+- repeated cases
+- repeated tickets
+- repeated reviews
+- repeated checks
+- repeated fix attempts on similar inputs
+
+Use this reference when the items are similar enough that the same method should be reused across them. If the subtasks are heterogeneous and anchored to a roadmap or todo baseline, use `planning-and-execution.md` instead.
+
+## Working pattern
+
+1. Create a checkpoint at the start of the overall repeated-item task.
+2. If item 1 teaches you a reusable approach, checkpoint again after that approach becomes clear.
+3. Work item by item.
+4. Rewind after each completed item or completed mini-phase when the raw path is no longer worth carrying forward.
+5. Use timeline occasionally to verify that the history still has a clean structure.
+
+For repeated-item work, the default completion move is not "keep carrying the last item's raw reasoning". Once an item is done and its takeaway is stable, rewind back to the repeated-work anchor.
+
+## Useful anchors
+
+Example checkpoint names:
+- `vendor-review-start`
+- `vendor-review-method-clear`
+- `ticket-triage-batch-start`
+- `ticket-triage-pattern-1-confirmed`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- several items have already been processed
+- item-level work has created multiple branches or rewinds
+- you want to confirm that the overall pattern still looks clean
+- you are about to choose which anchor repeated work should keep returning to
+
+## When to rewind
+
+Rewind after:
+- a representative item produced a reusable method
+- a single item is complete and the raw path should be compacted
+- an item-specific dead end is understood and should not remain active in full
+
+## Example rhythm
+
+```javascript
+context_checkpoint({ name: "vendor-review-start" });
+
+// ... work through first representative item ...
+
+context_checkpoint({ name: "vendor-review-method-clear" });
+
+// ... process another item ...
+
+context_rewind({
+  target: "vendor-review-method-clear",
+  message: "One more vendor review completed. Reason: compacting finished item work and returning to the clean repeated-item anchor. Next step: process the next vendor using the same method.",
+  backupCheckpoint: "vendor-review-item-7-history"
+});
+```
+
+## Warning signs
+
+Use stronger checkpoint/timeline/rewind discipline when:
+- each item creates lots of local reasoning
+- you are starting to confuse one item's path with another's
+- the repeated work is stretching across many turns

package/skills/context-management/references/retry-branch-and-pivot.md

@@ -0,0 +1,71 @@
+# Retry, Branch, and Pivot
+
+Use this reference when multiple approaches are being tried and abandoned cleanly, such as:
+- trying A / B / C approaches
+- failed branches that should not pollute the main line
+- compare-and-choose work
+- strategy pivots or goal shifts
+- restarting from a cleaner anchor after a dead end
+
+This is a **cross-cutting pattern reference**. Read it alongside a primary reference such as search/research, development/troubleshooting, or planning/execution when branch behavior becomes central.
+
+## Working pattern
+
+1. Checkpoint before opening a risky branch or alternative path.
+2. Explore or implement that branch.
+3. If anchor choice becomes unclear, inspect timeline.
+4. Once the branch produces a stable lesson, decision, or dead-end, rewind back to the best clean pre-branch anchor.
+5. Continue with the next branch or the chosen direction from that clean state.
+
+## When to review timeline
+
+Run `context_timeline` when:
+- multiple branches now exist
+- you are unsure which branch actually stayed useful
+- you need to choose the cleanest pre-branch anchor
+- the next direction is clear but the old branch still clutters active context
+
+## When to rewind
+
+Rewind when:
+- a branch clearly failed
+- a comparison is complete and one option won
+- the direction changed enough that the old path is now baggage
+- the next attempt should start from a cleaner base
+
+## Strategy pivot
+
+Use this pattern when the old direction no longer makes sense even though the task is still continuing.
+
+Examples:
+- the original approach is no longer viable
+- the user's priority changed
+- the scope narrowed or widened enough that old execution noise is now baggage
+
+In these cases:
+- summarize what still matters
+- rewind back to the best clean anchor before the stale branch
+- continue under the new direction
+
+## Example rhythm
+
+```javascript
+context_checkpoint({ name: "oauth-fix-start" });
+
+// ... try cookie-based approach ...
+
+context_rewind({
+  target: "oauth-fix-start",
+  message: "Cookie-based approach is not viable because the callback flow loses session continuity. Reason: retrying from a clean anchor after a failed branch. Important decision: switch to signed state tokens. Next step: implement the signed-state approach.",
+  backupCheckpoint: "oauth-cookie-approach-history"
+});
+context_checkpoint({ name: "oauth-signed-state-start" });
+```
+
+## Common mistakes
+
+Avoid:
+- opening alternative branches without a clean checkpoint first
+- dragging failed branches forward after their lesson is already clear
+- rewinding to a point that still includes the branch you meant to abandon
+- treating every branch as equally worth preserving

package/skills/context-management/references/search-research-and-reading.md

@@ -0,0 +1,82 @@
+# Search, Research, and Reading
+
+Use this reference when the work is mainly driven by large amounts of input material, such as:
+- searching
+- research
+- web search
+- browser-driven information gathering
+- reading many files, logs, docs, webpages, or web results
+- review-heavy reading
+- comparison-heavy reading
+- audit or inspection across many sources
+
+This reference is for **input-heavy work where the process is much larger than the final conclusion**. It is especially relevant for web search and browser/page reading, where the information density is often low and the raw trail becomes stale quickly. If the main anchor is an explicit plan or todo list, use `planning-and-execution.md` instead.
+
+## Working pattern
+
+1. Create a checkpoint before a large search or reading loop.
+2. Search, browse, read, inspect, and follow leads normally.
+3. If you lose orientation, review the timeline.
+4. Once the investigation yields a stable finding, rewind to a cleaner anchor.
+5. Continue with the conclusion, recommendation, or next action instead of carrying the entire raw exploration forward.
+
+Do not stop at "I already made a checkpoint" if the investigation phase is actually complete. The cleanup move for completed research is usually a rewind back to the best earlier anchor.
+
+## When to checkpoint
+
+Checkpoint:
+- before the first big search pass
+- before opening a browser-heavy or webpage-heavy reading pass
+- before diving into a new evidence branch
+- after a stable intermediate conclusion
+- before changing investigation direction
+
+Example checkpoint names:
+- `incident-search-start`
+- `vendor-review-evidence-branch`
+- `api-timeout-investigation-midpoint`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- you have followed several leads
+- you are no longer sure what the main anchor is
+- the investigation has already produced multiple checkpoints
+- you are deciding which path should be compacted
+
+## When to rewind
+
+Rewind after the investigation produces one of these:
+- a stable root cause
+- a stable comparison result
+- a dead-end conclusion
+- a shortlist of viable next actions
+
+If you already have one of these, the investigation phase is usually complete enough to compact.
+
+Do not rewind in the middle of a still-open search loop just because the thread feels busy.
+
+## Typical rhythm
+
+```javascript
+context_checkpoint({ name: "timeout-investigation-start" });
+
+// ... search logs, read code, compare docs, inspect outputs ...
+
+context_timeline();
+
+context_rewind({
+  target: "timeout-investigation-start",
+  message: "Found DB connection pool exhaustion as the likely root cause. Reason: investigation phase is complete and ready to compact. Next step: report findings and propose mitigation."
+});
+```
+
+## Good rewind outcomes
+
+After rewinding, you should be able to continue with:
+- the finding
+- the recommendation
+- the next verification step
+- the next narrower investigation
+
+You should not still need the whole raw trail in active context unless the investigation is still ongoing.

package/skills/context-management/references/task-switching-and-cleanup.md

@@ -0,0 +1,63 @@
+# Task Switching and Cleanup
+
+Use this reference when the main problem is not the task domain itself, but a change in thread state, such as:
+- the user inserts a temporary side task
+- you need to pause one line of work and resume it later
+- several active fronts now exist
+- the thread is already messy and needs cleanup before continuing
+- a finished noisy phase should be summarized and left behind
+
+This reference is for **pause/resume, cleanup, and clean continuation**. It is not for repeated similar items or plan-driven execution.
+
+## Two common variants
+
+### Interruption / task switch
+Use when you are actively switching away from one line of work and intend to come back.
+
+### Cleanup and continue
+Use when the thread is already stale or messy and you want to compress it now, even though context management is being adopted late.
+
+## Working pattern
+
+1. Inspect timeline if anchor choice is unclear.
+2. Before switching away or compacting a noisy path, preserve the best clean anchor.
+3. If needed, create a backup checkpoint for the current noisy branch.
+4. Handle the side task or cleanup move.
+5. Rewind away the stale path when the baton pass is clear.
+6. Resume from the paused anchor or continue from the compacted state.
+
+## Useful anchors
+
+Example checkpoint names:
+- `primary-task-paused`
+- `migration-mainline-paused`
+- `release-investigation-paused`
+- `cleanup-pre-noise-anchor`
+
+## When to review timeline
+
+Run `context_timeline` when:
+- multiple interruptions happened
+- the pause lasted many turns
+- several side-task branches now exist
+- you are unsure which clean anchor should be resumed
+- the thread is already messy and you need to find the right pre-noise checkpoint
+
+## When to rewind
+
+Rewind when:
+- the interruption created lots of noise
+- the side task is done and should not stay active in full
+- a stale path is making current reasoning worse
+- the useful state is now much smaller than the accumulated process
+- you can express the baton pass clearly in a summary
+
+If the interruption was tiny and clean, a rewind may be unnecessary. A checkpoint before switching away is still the key move.
+
+## Common mistakes
+
+Avoid:
+- switching away without a pause checkpoint
+- returning to the main line while still carrying the side task's full raw path
+- trying to clean up without first checking timeline when anchor choice is unclear
+- over-resetting and losing still-valid near-term context

package/src/context.ts

@@ -2,8 +2,8 @@ import {
   type ExtensionAPI,
   type SessionManager,
   DynamicBorder,
-} from "@mariozechner/pi-coding-agent";
-import { Container, Text, Spacer } from "@mariozechner/pi-tui";
+} from "@earendil-works/pi-coding-agent";
+import { Container, Text, Spacer } from "@earendil-works/pi-tui";
 import { formatTokens } from "./utils.js";
 
 export default function (pi: ExtensionAPI) {
@@ -61,8 +61,9 @@ export default function (pi: ExtensionAPI) {
       const toolDefTokensRaw = estimateTokens(JSON.stringify(activeToolDefs));
       const totalActual = usage.tokens;
       const limit = usage.contextWindow;
+      const usagePercent = usage.percent;
 
-      if (totalActual == null || limit == null || usage.percent == null) {
+      if (totalActual == null || limit == null || usagePercent == null) {
         ctx.ui.notify("Context usage info not available.", "warning");
         return;
       }
@@ -123,7 +124,7 @@ export default function (pi: ExtensionAPI) {
           gridLines.push(rowStr.trimEnd());
         }
 
-        const totalUsageTitle = `${theme.fg("text", theme.bold("Total Usage".padEnd(16)))} ${theme.fg("text", theme.bold(formatTokens(totalActual).padStart(7)))} ${theme.fg("text", theme.bold(`(${usage.percent.toFixed(1).padStart(5)}%)`))}`;
+        const totalUsageTitle = `${theme.fg("text", theme.bold("Total Usage".padEnd(16)))} ${theme.fg("text", theme.bold(formatTokens(totalActual).padStart(7)))} ${theme.fg("text", theme.bold(`(${usagePercent.toFixed(1).padStart(5)}%)`))}`;
 
         const catDetailLines = categories.map(cat => {
           const labelStr = cat.label.padEnd(14);