taskplane 0.17.0 → 0.18.0

package/dashboard/server.cjs

@@ -462,8 +462,11 @@ function loadTelemetryData(batchState) {
                 ? (usage.cost.total || 0)
                 : (typeof usage.cost === "number" ? usage.cost : 0);
             }
-            const totalTokens = usage.totalTokens
+            // Include cacheRead: totalTokens from pi excludes cache reads,
+            // but cached tokens still consume context window capacity.
+            const rawTotal = usage.totalTokens
               || ((usage.input || 0) + (usage.output || 0));
+            const totalTokens = rawTotal + (usage.cacheRead || 0);
             if (totalTokens > acc.latestTotalTokens) {
               acc.latestTotalTokens = totalTokens;
             }

package/extensions/task-runner.ts

@@ -1204,7 +1204,10 @@ function spawnAgent(opts: {
 								// Use totalTokens (cumulative) — works across providers.
 								// Anthropic reports small `input` per-turn but growing `totalTokens`.
 								// OpenAI reports growing `input` but also growing `totalTokens`.
-								const tokens = (usage as any).totalTokens || ((usage as any).input + (usage as any).output) || 0;
+								// Include cacheRead: pi's totalTokens excludes cache reads,
+								// but cached tokens still consume context window capacity.
+								const rawTokens = (usage as any).totalTokens || ((usage as any).input + (usage as any).output) || 0;
+								const tokens = rawTokens + ((usage as any).cacheRead || 0);
 								if (tokens > 0) {
 									const pct = (tokens / opts.contextWindow) * 100;
 									opts.onContextPct?.(pct);
@@ -1380,9 +1383,13 @@ function tailSidecarJsonl(filePath: string, tailState: SidecarTailState): Sideca
 							? (usage.cost.total || 0)
 							: (typeof usage.cost === "number" ? usage.cost : 0);
 					}
-					// totalTokens is cumulative (grows each turn) — use latest value
-					const totalTokens = usage.totalTokens
+					// totalTokens is cumulative (grows each turn) — use latest value.
+					// Include cacheRead tokens: pi's totalTokens and the
+					// input+output fallback both exclude cache reads, but cached
+					// tokens still consume context window capacity.
+					const rawTotal = usage.totalTokens
 						|| ((usage.input || 0) + (usage.output || 0));
+					const totalTokens = rawTotal + (usage.cacheRead || 0);
 					if (totalTokens > delta.latestTotalTokens) {
 						delta.latestTotalTokens = totalTokens;
 					}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/templates/agents/local/task-worker.md

@@ -19,6 +19,7 @@ name: task-worker
   - Review protocol (inline reviews via review_step tool when available)
   - Review response handling
   - Test execution strategy (targeted tests during steps, full suite at gate)
+  - File reading strategy (grep-first for large files, context budget awareness)
 
   Add project-specific rules below. Common examples:
   - Preferred package manager (pnpm, yarn, bun)

package/templates/agents/task-worker.md

@@ -265,4 +265,41 @@ checkpoints protect against regressions even when intermediate steps use targete
 2. The merge agent (before merging to the orchestrator branch)
 3. CI (before merging to main)
 
+## File Reading Strategy (Context Budget)
+
+Your context window is finite. Reading large files whole wastes budget and risks
+triggering the context-pressure safety net (85% → wrap-up, 95% → kill).
+Use targeted reads instead:
+
+### Pattern: grep-first, read-with-offset
+
+1. **Locate** the relevant section with `grep` or `find`:
+   ```
+   grep -n "function buildPrompt" extensions/task-runner.ts
+   ```
+2. **Read** just that region with `offset` and `limit`:
+   ```
+   read extensions/task-runner.ts (offset: 1773, limit: 50)
+   ```
+3. **Edit** surgically with exact `oldText → newText`
+
+### When to read a full file
+
+- Files under ~500 lines — read the whole thing, it's fine
+- Config files, test files, templates — usually small enough to read fully
+- New files you're creating — read after writing to verify
+
+### When NOT to read a full file
+
+- Source files over ~1000 lines — grep first, read the relevant region
+- Generated files, lock files, large data files — almost never need full reads
+- Files you've already read this session — re-read only the changed region
+
+### Getting a file outline
+
+To understand a large file's structure without reading it all:
+```bash
+grep -n "^function\|^export\|^class\|^interface\|^const.*=" file.ts | head -50
+```
+