@astrosheep/pi-context 0.4.1 → 0.5.0

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 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.
+- **Low-budget guidance** — when remaining context first drops to 16,000 tokens or below, a `<context_window_guidance>` reminder is **persisted once per window** into history (TUI-visible, no extra turn; `sendMessage` safely defers to end of turn mid-stream). The in-flight request additionally gets one transient tail copy so the model sees it immediately. Text is static and appended, so the provider prefix cache survives. 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.1",
+  "version": "0.5.0",
   "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

@@ -5,6 +5,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 GUIDANCE_TYPE = "pi-context/guidance";
 const RESET_MARKER_TYPE = "pi-context/reset-marker";
 const CONTINUATION_TYPE = "pi-context/continuation";
 const MAX_NOTE_BYTES = 1_000_000;
@@ -236,14 +237,24 @@ export function contextWindowHint(ctx: ExtensionContext): string {
 }
 
 /**
- * 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.
+ * Codex-equivalent low-budget reminder. Static by design: a stale token count in a
+ * persisted message would mislead later turns; 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}`;
 }
 
+/** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
+function currentWindowId(ctx: ExtensionContext): string {
+	const sessionId = ctx.sessionManager.getSessionId();
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry?.type === "compaction") return `pcw:${sessionId}:${entry.id}`;
+	}
+	return `pcw:${sessionId}:root`;
+}
+
 function lineRange(text: string, startValue: unknown, stopValue: unknown) {
 	const lines = text.split("\n");
 	const resolve = (value: unknown, fallback: number) => {
@@ -265,6 +276,7 @@ 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 enabled = true;
+	let guidancePersistedInWindow: string | undefined;
 
 	/** Persist the context_window hint as a visible message (lands in history and the TUI), Codex-style. */
 	const persistHint = (ctx: ExtensionContext) => {
@@ -418,17 +430,23 @@ export default function piContext(pi: ExtensionAPI) {
 
 	pi.on("context", (event, ctx) => {
 		if (!enabled) return undefined;
-		// 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 windowId = currentWindowId(ctx);
+		if (guidancePersistedInWindow === windowId) return undefined;
+		guidancePersistedInWindow = windowId;
+		// Persist once per window, like the hint. sendMessage defers safely to end of
+		// turn while streaming (sendCustomMessage queues instead of splitting a tool
+		// call/result pair), so from the next turn on the guidance lives in history
+		// and the TUI. A transient tail copy covers the in-flight request; it is
+		// appended, static, and one-shot, so the cached prefix survives.
+		const text = tokenBudgetGuidance();
+		pi.sendMessage({ customType: GUIDANCE_TYPE, content: text, display: true }, { triggerTurn: false });
 		const guidance = {
 			role: "user" as const,
-			content: [{ type: "text" as const, text: tokenBudgetGuidance() }],
+			content: [{ type: "text" as const, text }],
 			timestamp: Date.now(),
 		};
 		return { messages: [...event.messages, guidance] };
@@ -498,4 +516,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-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 };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, HINT_TYPE, GUIDANCE_TYPE, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, REMINDER_THRESHOLD_TOKENS, lineRange, assertVirtualPath };