@astrosheep/pi-context 0.3.0 → 0.4.1

package/README.md

@@ -19,8 +19,8 @@ pi -e npm:@astrosheep/pi-context
 The extension composes Pi's public `session_before_compact` / `session_compact` hooks, custom session entries, and the `context` hook to approximate Codex's experimental context management:
 
 - **`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** — every model request carries a Codex-equivalent fragment with the agent name, first/current/previous window IDs, and the 5 most recently updated notes. The model gets recovery entry points, not a bare "go search" message.
-- **Low-budget guidance** — when remaining context drops to 16,000 tokens or below, a `<context_window_guidance>` reminder is injected exactly once per window (re-armed after each reset), matching Codex's `token_budget` reminder semantics: 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.
+- **`<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 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.3.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

@@ -4,6 +4,7 @@ import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-
 
 const STATE_TYPE = "pi-context/state";
 const NOTE_TYPE = "pi-context/note";
+const HINT_TYPE = "pi-context/hint";
 const RESET_MARKER_TYPE = "pi-context/reset-marker";
 const CONTINUATION_TYPE = "pi-context/continuation";
 const MAX_NOTE_BYTES = 1_000_000;
@@ -234,14 +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}`;
-}
-
-function currentWindowId(ctx: ExtensionContext): string | undefined {
-	const windows = historyFromSession(ctx);
-	return windows[windows.length - 1]?.windowId;
+/**
+ * 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) {
@@ -264,8 +264,17 @@ const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.L
 
 export default function piContext(pi: ExtensionAPI) {
 	let rollover: "idle" | "requested" | "compacting" | "continued" = "idle";
-	let reminderClaimedInWindow: string | undefined;
 	let enabled = true;
+
+	/** Persist the context_window hint as a visible message (lands in history and the TUI), Codex-style. */
+	const persistHint = (ctx: ExtensionContext) => {
+		pi.sendMessage({ customType: HINT_TYPE, content: contextWindowHint(ctx), display: true }, { triggerTurn: false });
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		if (!enabled) return;
+		persistHint(ctx);
+	});
 	const saveNote = (op: NoteOperation) => {
 		// pi.appendEntry writes a custom SessionManager entry. Custom entries are persistent but excluded from LLM context.
 		// ExtensionContext deliberately exposes only a readonly SessionManager, so this is the public extension write path.
@@ -409,27 +418,20 @@ export default function piContext(pi: ExtensionAPI) {
 
 	pi.on("context", (event, ctx) => {
 		if (!enabled) return undefined;
-		// Rebuilt per request, so no state diffing is needed; identical to Codex's
-		// context_window developer fragment rendered into each model call.
-		const userText = (text: string) => ({
+		// 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 }],
+			content: [{ type: "text" as const, text: tokenBudgetGuidance() }],
 			timestamp: Date.now(),
-		});
-		const injected = [userText(contextWindowHint(ctx))];
-
-		// Codex token_budget.maybe_record parity: below the threshold, claim the
-		// reminder once per context window; a new window makes it eligible again.
-		const usage = ctx.getContextUsage();
-		if (usage && usage.tokens !== null) {
-			const remaining = Math.max(0, usage.contextWindow - usage.tokens);
-			const windowId = currentWindowId(ctx);
-			if (remaining <= REMINDER_THRESHOLD_TOKENS && reminderClaimedInWindow !== windowId) {
-				reminderClaimedInWindow = windowId;
-				injected.push(userText(tokenBudgetGuidance(remaining)));
-			}
-		}
-		return { messages: [...injected, ...event.messages] };
+		};
+		return { messages: [...event.messages, guidance] };
 	});
 
 	pi.registerTool(defineTool({
@@ -480,13 +482,14 @@ export default function piContext(pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("session_compact", (event) => {
+	pi.on("session_compact", (event, ctx) => {
 		if (!enabled) return;
 		// Overflow retry is already continued once by Pi core. Sending another turn would duplicate it.
 		if (event.willRetry) return;
 		if (rollover !== "compacting") return;
 		rollover = "continued";
 		pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: event.compactionEntry.id });
+		persistHint(ctx);
 		pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: true });
 	});
 
@@ -495,4 +498,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, REMINDER_THRESHOLD_TOKENS, lineRange, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, HINT_TYPE, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, REMINDER_THRESHOLD_TOKENS, lineRange, assertVirtualPath };