@astrosheep/pi-context 0.5.0 → 0.6.1

package/README.md

@@ -21,7 +21,8 @@ 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** — 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.
+- **Auto-compact fallback** — Codex `auto_compact_fallback_prompt` parity, adapted to Pi's trigger points. On the first proactive `threshold` compaction in a window (post-run, agent still streaming), the extension cancels compaction once and steers in a note-taking turn ("write durable state with `notes_write_file` now"); the next threshold trigger performs the real reset and auto-continues, like Codex's mid-turn rollover. The pre-prompt threshold path (idle — cancelling would race the user prompt) and `overflow` recovery (cancelling would abandon Pi's one-shot retry) reset immediately without a fallback turn.
+- **Runtime toggle** — `/pi-context off` disables hint injection, guidance, fallback turns, 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.
 
@@ -45,7 +46,7 @@ The nine Codex History/Notes actions are flattened because Pi tools have one glo
 
 `notes_*` stores operation entries in the same append-only Pi session under `pi-context/note`. They are session-scoped, survive JSONL reload, never enter provider context, and use safe relative virtual paths only (no absolute paths, `..`, `.`, empty components, or backslashes). Searches are literal and case-sensitive. `notes_read_file` accepts inclusive 1-based line ranges; negative line numbers count from the last line. Writes are capped at 1,000,000 UTF-8 bytes.
 
-Pi has no public cross-agent session router. Passing `agent_name` to a history tool returns an explicit unsupported error; it is never silently redirected to the current session.
+Unlike Codex, the history tools do not advertise `agent_name`: Pi has no cross-agent session routing, so the parameter is omitted from the schemas entirely (strict `additionalProperties: false` still rejects it) instead of costing schema tokens on every request.
 
 Two extra controls compose Pi public APIs:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.5.0",
+  "version": "0.6.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

@@ -6,6 +6,7 @@ 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 FALLBACK_TYPE = "pi-context/fallback";
 const RESET_MARKER_TYPE = "pi-context/reset-marker";
 const CONTINUATION_TYPE = "pi-context/continuation";
 const MAX_NOTE_BYTES = 1_000_000;
@@ -17,6 +18,10 @@ const REMINDER_THRESHOLD_TOKENS = 16_000;
 const RESET_SUMMARY = "Context window reset. Prior session entries remain available only through the pi-context history tools.";
 const CONTINUATION = "This is a fresh context window. Recover only the details needed to continue with history_* and notes_*; then continue the task.";
 
+/** Codex auto_compact_fallback_prompt parity: one note-taking chance before an automatic reset. */
+const FALLBACK_PROMPT =
+	"Context limit reached. This window is about to be reset. Write durable state with notes_write_file now: task state, decisions, open issues, next steps. Do not start new work. After this turn the window resets automatically; old conversation stays searchable through the history_* tools.";
+
 type NoteFile = { text: string; createdAt: number; updatedAt: number };
 type NoteOperation = {
 	op: "write" | "append";
@@ -37,7 +42,6 @@ type HistoryItem = {
 type HistoryWindow = { windowId: string; createdAt?: string; items: HistoryItem[] };
 
 type HistoryFilter = {
-	agent_name?: string | null;
 	window_id?: string | null;
 	role?: HistoryItem["role"] | null;
 	tool_namespace?: string | null;
@@ -53,12 +57,6 @@ function output(value: unknown, details: unknown = value, terminate = false) {
 	return { content: [{ type: "text" as const, text: json(value) }], details, terminate };
 }
 
-function unsupportedAgent(agentName: string | null | undefined) {
-	return agentName !== undefined && agentName !== null
-		? { error: "Pi 0.85.1 exposes no cross-agent session routing; agent_name is unsupported and was not aliased to this session." }
-		: undefined;
-}
-
 function isTextContent(part: unknown): part is TextContent {
 	return typeof part === "object" && part !== null && (part as TextContent).type === "text" && typeof (part as TextContent).text === "string";
 }
@@ -155,9 +153,7 @@ function allItems(ctx: ExtensionContext) {
 	return historyFromSession(ctx).flatMap((window) => window.items);
 }
 
-function filteredItems(ctx: ExtensionContext, params: HistoryFilter): HistoryItem[] | { error: string } {
-	const agentError = unsupportedAgent(params.agent_name);
-	if (agentError) return agentError;
+function filteredItems(ctx: ExtensionContext, params: HistoryFilter): HistoryItem[] {
 	let items = allItems(ctx);
 	if (typeof params.window_id === "string") items = items.filter((item) => item.windowId === params.window_id);
 	if (typeof params.role === "string") items = items.filter((item) => item.role === params.role);
@@ -277,6 +273,8 @@ export default function piContext(pi: ExtensionAPI) {
 	let rollover: "idle" | "requested" | "compacting" | "continued" = "idle";
 	let enabled = true;
 	let guidancePersistedInWindow: string | undefined;
+	let fallbackSentInWindow: string | undefined;
+	let continueAfterFallback = false;
 
 	/** Persist the context_window hint as a visible message (lands in history and the TUI), Codex-style. */
 	const persistHint = (ctx: ExtensionContext) => {
@@ -312,11 +310,9 @@ export default function piContext(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_list_windows",
 		label: "History list windows",
-		description: "List durable Pi session-history windows. agent_name is explicitly unsupported because Pi has no cross-agent session routing.",
-		parameters: Type.Object({ limit: positiveInteger(), agent_name: nullableString(), recent_first: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+		description: "List durable Pi session-history windows.",
+		parameters: Type.Object({ limit: positiveInteger(), recent_first: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const agentError = unsupportedAgent(params.agent_name);
-			if (agentError) return output(agentError);
 			let windows = historyFromSession(ctx);
 			if (params.recent_first) windows = [...windows].reverse();
 			const limit = params.limit ?? windows.length;
@@ -328,10 +324,9 @@ export default function piContext(pi: ExtensionAPI) {
 		name: "history_list_items",
 		label: "History list items",
 		description: "List durable session items, including items before compaction, using opaque item and window IDs.",
-		parameters: Type.Object({ limit: positiveInteger(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), agent_name: nullableString(), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+		parameters: Type.Object({ limit: positiveInteger(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const items = filteredItems(ctx, params);
-			if ("error" in items) return output(items);
 			return output({ items: items.slice(0, params.limit ?? items.length).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200)) });
 		},
 	}));
@@ -340,10 +335,8 @@ export default function piContext(pi: ExtensionAPI) {
 		name: "history_read_item",
 		label: "History read item",
 		description: "Read a bounded character range from one durable session item.",
-		parameters: Type.Object({ agent_name: nullableString(), item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ minimum: 0 })), limit_chars: positiveInteger(), window_id: Type.String() }, { additionalProperties: false }),
+		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ minimum: 0 })), limit_chars: positiveInteger(), window_id: Type.String() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const agentError = unsupportedAgent(params.agent_name);
-			if (agentError) return output(agentError);
 			const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
 			if (!item) return output({ error: "unknown item_id or window_id" });
 			const chars = Array.from(item.content);
@@ -357,10 +350,9 @@ export default function piContext(pi: ExtensionAPI) {
 		name: "history_search_contents",
 		label: "History search",
 		description: "Case-sensitive literal substring search over durable Pi session history; no semantic search.",
-		parameters: Type.Object({ limit: positiveInteger(), query: Type.String(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), agent_name: nullableString(), tool_name: nullableString(), window_id: nullableString() }, { additionalProperties: false }),
+		parameters: Type.Object({ limit: positiveInteger(), query: Type.String(), recent_first: Type.Optional(Type.Boolean()), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const items = filteredItems(ctx, params);
-			if ("error" in items) return output(items);
 			const matching = items.filter((item) => item.content.includes(params.query));
 			return output({ items: matching.slice(0, params.limit ?? matching.length).map((item) => visibleItem(item)) });
 		},
@@ -490,6 +482,22 @@ export default function piContext(pi: ExtensionAPI) {
 		if (!enabled) return undefined; // Default Pi compaction applies; keepRecentTokens is honored again.
 		// Never let an aborted or failed custom reset fall through to Pi's default summary.
 		if (event.signal.aborted) return { cancel: true };
+		// Codex auto_compact_fallback_prompt parity, adapted to Pi's trigger points:
+		// - threshold, post-run (agent still streaming): cancel once per window and steer a
+		//   note-taking turn in; _runAutoCompaction then returns hasQueuedMessages() and the
+		//   post-run loop delivers it via agent.continue(). Safe, intended path.
+		// - threshold, pre-prompt (idle): cancelling still sends the user prompt with an
+		//   over-threshold context, and sendMessage would race _runAgentPrompt. Reset instead.
+		// - overflow: never cancel; that would abandon Pi's one-shot compact-and-retry recovery.
+		if (event.reason === "threshold" && !ctx.isIdle()) {
+			const windowId = currentWindowId(ctx);
+			if (fallbackSentInWindow !== windowId) {
+				fallbackSentInWindow = windowId;
+				continueAfterFallback = true;
+				pi.sendMessage({ customType: FALLBACK_TYPE, content: FALLBACK_PROMPT, display: true }, { triggerTurn: true });
+				return { cancel: true };
+			}
+		}
 		try {
 			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: rollover === "compacting" });
 			const markerId = ctx.sessionManager.getLeafId();
@@ -501,11 +509,18 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_compact", (event, ctx) => {
-		if (!enabled) return;
+		if (!enabled) {
+			continueAfterFallback = false;
+			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";
+		// Continue after our own rollover, and after a fallback reset (Codex rolls over
+		// mid-turn and keeps going). A user's manual /compact gets no continuation.
+		const shouldContinue = rollover === "compacting" || continueAfterFallback;
+		continueAfterFallback = false;
+		if (rollover === "compacting") rollover = "continued";
+		if (!shouldContinue) return;
 		pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: event.compactionEntry.id });
 		persistHint(ctx);
 		pi.sendMessage({ customType: CONTINUATION_TYPE, content: CONTINUATION, display: false }, { triggerTurn: true });
@@ -516,4 +531,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-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 };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, HINT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, FALLBACK_PROMPT, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, GUIDANCE_OPEN_TAG, REMINDER_THRESHOLD_TOKENS, lineRange, assertVirtualPath };