@astrosheep/pi-context 0.4.0 → 0.4.1

package/README.md

@@ -20,7 +20,7 @@ The extension composes Pi's public `session_before_compact` / `session_compact`
 
 - **`new_context` tool** — the model requests a fresh context window. The extension waits for the current tool turn to end, compacts with a short deterministic reset message (old conversation is excluded from the new provider context but stays in the session), then sends exactly one hidden continuation turn.
 - **`<context_window>` hint** — persisted as a visible custom message at session start and after each window reset (Codex-style: written once into history instead of re-injected per request). It carries the agent name, first/current/previous window IDs, and the 5 most recently updated notes. Within a window the note list goes stale, exactly like Codex's steady-state world-state diffing.
-- **Low-budget guidance** — while remaining context is at or below 16,000 tokens, a `<context_window_guidance>` reminder is injected transiently on every request (transient single-shot would vanish from the next request; Codex's persisted reminder stays visible, so continuous low-budget injection is the effective parity). It tells the model to persist state with `notes_write_file` and call `new_context` before the window closes. Note: Pi's built-in auto-compaction fires when remaining context falls below `reserveTokens` (default 16,384), so raise the reminder threshold above your `reserveTokens` or the reminder never precedes compaction.
+- **Low-budget guidance** — while remaining context is at or below 16,000 tokens, a `<context_window_guidance>` reminder is appended after the request messages on every call (transient single-shot would vanish from the next request; Codex's persisted reminder stays visible, so continuous low-budget injection is the effective parity). The text is static and appended (not prepended), so the provider's prefix cache survives: crossing the threshold adds one stable suffix segment instead of rewriting the prefix. The exact remaining figure is one `get_context_remaining` call away. Note: Pi's built-in auto-compaction fires when remaining context falls below `reserveTokens` (default 16,384), so raise the reminder threshold above your `reserveTokens` or the reminder never precedes compaction.
 - **Runtime toggle** — `/pi-context off` disables hint injection, guidance, and reset-style compaction (Pi's default compaction, including `keepRecentTokens`, applies again). `/pi-context on` re-enables; a bare `/pi-context` reports the current state.
 - **History tools** — the model searches pre-reset conversation with case-sensitive literal substring search, exactly like Codex's `history.*` namespace.
 - **Notes tools** — persistent, session-scoped virtual files that survive window resets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/index.ts

@@ -235,9 +235,13 @@ export function contextWindowHint(ctx: ExtensionContext): string {
 	return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
 }
 
-/** Codex-equivalent low-budget reminder: threshold-gated, claimed once per context window. */
-function tokenBudgetGuidance(remaining: number): string {
-	return `${GUIDANCE_OPEN_TAG}\nYou have ${remaining} tokens left in this context window. Write durable state with notes_write_file and call new_context before the window closes.\n${GUIDANCE_CLOSE_TAG}`;
+/**
+ * Codex-equivalent low-budget reminder. Static by design: this text is injected on
+ * every request while below the threshold, so a varying token count would invalidate
+ * the provider's prefix cache on each call. The exact figure is one tool call away.
+ */
+function tokenBudgetGuidance(): string {
+	return `${GUIDANCE_OPEN_TAG}\nContext budget is at or below ${REMINDER_THRESHOLD_TOKENS} tokens remaining. Persist durable state with notes_write_file, then call new_context before the window closes. get_context_remaining reports the exact figure.\n${GUIDANCE_CLOSE_TAG}`;
 }
 
 function lineRange(text: string, startValue: unknown, stopValue: unknown) {
@@ -414,18 +418,20 @@ export default function piContext(pi: ExtensionAPI) {
 
 	pi.on("context", (event, ctx) => {
 		if (!enabled) return undefined;
-		// Transient per-request while below the threshold. Codex's reminder persists in
-		// history and therefore stays visible; re-injecting while low is the effective parity.
+		// Transient while below the threshold: Codex's reminder persists in history and
+		// stays visible, so continuous low-budget visibility is the effective parity.
+		// Appended (not prepended) with static text: the cached prefix stays untouched,
+		// crossing the threshold only adds one stable suffix segment.
 		const usage = ctx.getContextUsage();
 		if (!usage || usage.tokens === null) return undefined;
 		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
 		if (remaining > REMINDER_THRESHOLD_TOKENS) return undefined;
 		const guidance = {
 			role: "user" as const,
-			content: [{ type: "text" as const, text: tokenBudgetGuidance(remaining) }],
+			content: [{ type: "text" as const, text: tokenBudgetGuidance() }],
 			timestamp: Date.now(),
 		};
-		return { messages: [guidance, ...event.messages] };
+		return { messages: [...event.messages, guidance] };
 	});
 
 	pi.registerTool(defineTool({