|
| 1 | +import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; |
| 2 | + |
| 3 | +// Mid-run context watchdog (issue #59). |
| 4 | +// |
| 5 | +// pi only evaluates auto-compaction at a *user-turn boundary* — its |
| 6 | +// `_checkCompaction` runs inside `_handlePostAgentRun`, which fires only after |
| 7 | +// `agent.prompt()` has fully returned (i.e. once the model stops requesting |
| 8 | +// tools and goes idle). During one long autonomous run this boundary is never |
| 9 | +// reached: little-coder's small models routinely chain dozens of tool-call |
| 10 | +// turns before yielding, so context grows unchecked and can blow straight past |
| 11 | +// the window — pi then only reacts to the *overflow error* after the fact. |
| 12 | +// charly1r reproduced exactly this: context climbing 34k → 40k → … → 64k across |
| 13 | +// many `slot release` turns with no compaction until the request overflowed. |
| 14 | +// |
| 15 | +// pi does expose the levers to fix this from an extension: `ctx.getContextUsage()` |
| 16 | +// reports live token usage against the active model's window, and `ctx.compact()` |
| 17 | +// triggers pi's own compaction without awaiting it. This extension watches usage |
| 18 | +// at every turn boundary and, once it crosses a threshold, proactively kicks off |
| 19 | +// compaction — so a long single run compacts *before* it overflows, at roughly |
| 20 | +// the same point pi would have if the model had yielded. |
| 21 | +// |
| 22 | +// Tuning / opt-out: |
| 23 | +// LITTLE_CODER_COMPACT_AT_PERCENT trigger threshold, percent of the context |
| 24 | +// window (default 80). <=0 or >=100 disables. |
| 25 | +// LITTLE_CODER_NO_COMPACT_WATCHDOG=1 hard off. |
| 26 | +// |
| 27 | +// This is complementary to pi's end-of-run compaction, not a replacement — the |
| 28 | +// `compacting` guard below keeps us from re-firing while a compaction is already |
| 29 | +// in flight, and pi's own threshold/overflow paths still run at run boundaries. |
| 30 | + |
| 31 | +export interface ContextUsageLike { |
| 32 | + tokens: number | null; |
| 33 | + contextWindow: number; |
| 34 | + percent: number | null; |
| 35 | +} |
| 36 | + |
| 37 | +const DEFAULT_PERCENT = 80; |
| 38 | + |
| 39 | +// Resolve the trigger threshold (percent of context window). Non-numeric or |
| 40 | +// missing → default. Returns 0 to mean "disabled" for out-of-band values |
| 41 | +// (<=0 disables outright; >=100 leaves it to pi's own overflow recovery). |
| 42 | +export function thresholdPercent(env: NodeJS.ProcessEnv = process.env): number { |
| 43 | + if (env.LITTLE_CODER_NO_COMPACT_WATCHDOG === "1") return 0; |
| 44 | + const raw = env.LITTLE_CODER_COMPACT_AT_PERCENT; |
| 45 | + if (raw === undefined || raw.trim() === "") return DEFAULT_PERCENT; |
| 46 | + const n = Number(raw); |
| 47 | + if (!Number.isFinite(n)) return DEFAULT_PERCENT; |
| 48 | + if (n <= 0 || n >= 100) return 0; |
| 49 | + return n; |
| 50 | +} |
| 51 | + |
| 52 | +// Pure decision: should we kick off compaction on this turn? True only when the |
| 53 | +// watchdog is enabled, no compaction is already in flight, and we have a real |
| 54 | +// usage reading at or above the threshold. `tokens == null` (e.g. right after a |
| 55 | +// compaction, before the next LLM response) is treated as "unknown" → no-op. |
| 56 | +export function shouldCompactNow( |
| 57 | + usage: ContextUsageLike | undefined, |
| 58 | + pct: number, |
| 59 | + compacting: boolean, |
| 60 | +): boolean { |
| 61 | + if (pct <= 0) return false; |
| 62 | + if (compacting) return false; |
| 63 | + if (!usage) return false; |
| 64 | + if (usage.contextWindow <= 0) return false; |
| 65 | + if (usage.tokens === null || usage.percent === null) return false; |
| 66 | + return usage.percent >= pct; |
| 67 | +} |
| 68 | + |
| 69 | +export default function (pi: ExtensionAPI) { |
| 70 | + const pct = thresholdPercent(); |
| 71 | + if (pct <= 0) return; // disabled — register nothing |
| 72 | + |
| 73 | + // In flight until the matching `session_compact` (or the next user prompt) |
| 74 | + // clears it, so a burst of turn_start events can't stack compaction calls. |
| 75 | + let compacting = false; |
| 76 | + |
| 77 | + pi.on("before_agent_start", async () => { |
| 78 | + // A fresh user prompt is a clean boundary; drop any stale in-flight flag so |
| 79 | + // a cancelled/failed compaction can't wedge the watchdog off permanently. |
| 80 | + compacting = false; |
| 81 | + }); |
| 82 | + |
| 83 | + pi.on("turn_start", async (_event, ctx) => { |
| 84 | + const usage = ctx.getContextUsage?.(); |
| 85 | + if (!shouldCompactNow(usage, pct, compacting)) return; |
| 86 | + compacting = true; |
| 87 | + const windowK = Math.round((usage!.contextWindow / 1000) * 10) / 10; |
| 88 | + ctx.ui.notify( |
| 89 | + `context at ${Math.round(usage!.percent!)}% of ${windowK}k — compacting mid-run to stay under the window`, |
| 90 | + "info", |
| 91 | + ); |
| 92 | + // Fire-and-forget: pi runs compaction and the run continues on the compacted |
| 93 | + // transcript. We do NOT await (the API is explicitly non-awaiting). |
| 94 | + ctx.compact(); |
| 95 | + }); |
| 96 | + |
| 97 | + pi.on("session_compact", async () => { |
| 98 | + compacting = false; |
| 99 | + }); |
| 100 | +} |
0 commit comments