@astrosheep/pi-context 0.9.0 → 0.10.0

package/README.md

@@ -18,10 +18,10 @@ 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.
+- **`new_context` tool** — the model requests a fresh context window. The extension waits for the current run to settle, compacts with a short deterministic reset message (old conversation is excluded from the new provider context but stays in the session), then sends one hidden continuation turn once compaction has fully completed, unless another prompt is already queued or running.
 - **`<context_window>` boot block** — the head of every fresh window. For a reset it IS the summary returned from `session_before_compact` (position 0, persisted, no extra message); for the root window `session_start` persists it once as a visible custom message. It carries the agent name and first/current/previous window IDs, the recent-notes index, and a `<context_window_protocol>` teaching block. The notes index lists up to three most-recent notes, each with its `X lines, Y UTF-8 bytes` metadata plus a local-time ISO 8601 `updated` timestamp (explicit UTC offset, never `Z`) and an inline preview. A note of 200 Unicode characters or fewer is shown whole; a longer one shows its first 120 and last 80 Unicode characters joined by an ellipsis, so the two ends never overlap and no text is repeated. The notes index is a window-open snapshot with the same frozen-at-write semantics as the reminder count. Nothing is injected transiently per request: the boot block is static once-per-window content, so the head of the window stays cache-stable. Codex diverges here — its `<context_window>` block carries only the agent path and window IDs, while the notes index is our own addition.
-- **Low-budget guidance** — when estimated remaining context first drops to the reminder threshold (by default **40,960 tokens**: Pi's default 16,384 `reserveTokens` plus a 24,576 reminder margin; see [Reminder timing](#reminder-timing)), a `<context_window_guidance>` reminder is **persisted once per window** into history (TUI-visible, no extra turn; `sendMessage` safely defers mid-stream). There is deliberately no transient copy: a bridge would make the model meet the same text twice at shifted positions, because history records the persisted copy after the crossing request's assistant reply. The reminder is an early warning, so arriving from the next request on costs nothing and keeps the model's view identical to recorded history. The measured remaining count is frozen into the text at the threshold crossing, so the persisted reminder is a snapshot true at write time; `get_context_remaining` remains the live source for the current figure. The text is appended rather than prepended; existing history is not rewritten.
-- **Two-phase automatic fallback** — while Pi is streaming, the first automatic `threshold`/`overflow` crossing of the reserve line does not reset immediately. `session_before_compact` queues the final note-taking instruction with `pi.sendMessage(..., { triggerTurn: true })` — which Pi routes to `agent.steer()` while streaming, so the message is queued synchronously and reaches the model before any pending user input — and returns `{ cancel: true }`. Pi records that as an aborted compaction, spends no summary, and continues the same run with the borrowed turn; no user text or images are copied, intercepted, or replayed, and no `input` handler is registered. Once the borrowed run has finished, `agent_end` arms the real reset and `agent_settled` requests it through `ctx.compact()` for both `threshold` and `overflow`, unless another compaction has already completed. A threshold crossing does not guarantee another automatic check: the agent loop can end without preparing another assistant response. Overflow recovery also has a one-shot guard. Requesting the reset after the run settles avoids issuing it from `agent_end` while Pi is still finishing the run. A phase flag makes the cancel happen at most once per window — it re-arms only after a completed reset starts a fresh window — and a failed reset keeps retrying the real compaction instead of borrowing another turn. The borrow is skipped when the crossing arrives while Pi is idle (the pre-prompt check in `AgentSession.prompt()`, where `triggerTurn` would start a nested run and make the pending `Agent.prompt()` reject); that crossing resets directly. `manual` `/compact` and `new_context` never take the borrowed-turn path. The reminder asks the model to write notes early; if it misses that opportunity, old history remains searchable.
+- **Low-budget guidance** — when estimated remaining context first drops to the reminder threshold (by default **40,960 tokens**: Pi's default 16,384 `reserveTokens` plus a 24,576 reminder margin; see [Reminder timing](#reminder-timing)), a `<context_window_guidance>` reminder is **persisted once per window** into history (TUI-visible, no extra turn; `sendMessage` safely defers mid-stream). There is deliberately no transient copy: a bridge would make the model meet the same text twice at shifted positions, because history records the persisted copy after the crossing request's assistant reply. The reminder is an early warning, so arriving from the next request on costs nothing and keeps the model's view identical to recorded history. The measured remaining budget excludes `reserveTokens` and is frozen into the text at the threshold crossing, so the persisted reminder is a snapshot true at write time; `get_context_remaining` remains the live source for the current figure. The text is appended rather than prepended; existing history is not rewritten.
+- **Two-phase automatic fallback** — while Pi is streaming, the first automatic `threshold`/`overflow` crossing of the reserve line does not reset immediately. `session_before_compact` queues the final note-taking instruction with `pi.sendMessage(..., { triggerTurn: true })` — which Pi routes to `agent.steer()` while streaming, so the message is queued synchronously and reaches the model before any pending user input — and returns `{ cancel: true }`. Pi records that as an aborted compaction, spends no summary, and continues the same run with the borrowed turn; no user text or images are copied, intercepted, or replayed, and no `input` handler is registered. Once the borrowed run has finished, `agent_end` arms the real reset and `agent_settled` requests it through `ctx.compact()` for both `threshold` and `overflow`, unless another compaction has already completed. Pi can perform another automatic check after a run, and overflow recovery has a one-shot guard. The settled scheduler ensures the borrowed turn has one reset owner even when no native check resets it. Requesting the reset after the run settles avoids issuing it from `agent_end` while Pi is still finishing the run. A phase flag makes the cancel happen at most once per window — it re-arms only after a completed reset starts a fresh window. A failed reset clears the pending request, warns the user, and leaves history intact; another prompt can retry without borrowing another turn. Extension-requested fallback resets send a continuation after the compaction completion callback. The borrow is skipped when the crossing arrives while Pi is idle (the pre-prompt check in `AgentSession.prompt()`, where `triggerTurn` would start a nested run and make the pending `Agent.prompt()` reject); that crossing resets directly. `manual` `/compact` and `new_context` never take the borrowed-turn path. The reminder asks the model to write notes early; if it misses that opportunity, old history remains searchable.
 - **Runtime toggle** — `/pi-context off` disables the boot block, 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.
@@ -75,12 +75,14 @@ Unlike Codex, the history tools do not advertise `agent_name`: Pi has no cross-a
 
 Two extra controls compose Pi public APIs:
 
-- `get_context_remaining` returns `{ "remaining_tokens": number | null }`. `null` means Pi itself cannot make a reliable estimate (notably immediately after compaction). The low-budget guidance uses the same source and stays silent when the estimate is unknown.
-- `new_context` returns terminal tool output, then waits for Pi's `agent_end`, triggers public `ctx.compact()`, installs a short deterministic reset compaction, and sends exactly one hidden continuation turn after compaction succeeds. Call it by itself in a tool batch. Pi only ends a tool turn when every parallel tool result is terminal, so Pi 0.85.1 cannot force an atomic rollover from the middle of a mixed parallel tool batch.
+- `get_context_remaining` returns `{ "remaining_tokens": number | null }`, computed as `max(0, contextWindow - usedTokens - reserveTokens)`: the estimated budget available before Pi's compaction reserve. `null` means Pi itself cannot make a reliable estimate (notably immediately after compaction). The low-budget guidance reports this same reserve-adjusted budget and stays silent when the estimate is unknown. Its trigger still compares physical remaining capacity against `reserveTokens + reminderMarginTokens`, so subtracting reserve from the reported number does not change reminder timing.
+- `new_context` returns terminal tool output, then waits for Pi's `agent_settled`, triggers public `ctx.compact()`, installs a short deterministic reset compaction, and sends exactly one hidden continuation turn after compaction succeeds. Call it by itself in a tool batch. Pi only ends a tool turn when every parallel tool result is terminal, so Pi 0.85.1 cannot force an atomic rollover from the middle of a mixed parallel tool batch.
 
 ## Reset behavior and limits
 
-On `session_before_compact`, the extension appends a persistent custom reset marker through public `pi.appendEntry`, reads that real marker ID from the readonly session manager, and returns it as `firstKeptEntryId`. Pi's `buildContextEntries()` then keeps the compaction envelope plus that custom marker; custom markers are excluded from LLM context. Thus the subsequent provider context contains the boot block summary and the marker, not old conversation messages. The boot summary also carries the extension-minted window id in its `details.windowId`, so the fresh window names itself with an id Pi could not have supplied at bake time. Only an explicit `new_context` adds a hidden continuation; automatic resets and user `/compact` keep Pi's native scheduling. The old entries remain only in the session tree for `history_*`.
+On `session_before_compact`, the extension appends a persistent custom reset marker through public `pi.appendEntry`, reads that real marker ID from the readonly session manager, and returns it as `firstKeptEntryId`. Pi's `buildContextEntries()` then keeps the compaction envelope plus that custom marker; custom markers are excluded from LLM context. Thus the subsequent provider context contains the boot block summary and the marker, not old conversation messages. The boot summary also carries the extension-minted window id in its `details.windowId`, so the fresh window names itself with an id Pi could not have supplied at bake time. Both explicit `new_context` and the reset requested after a borrowed fallback run add a hidden continuation from `ctx.compact`'s `onComplete` callback. Native automatic resets and user `/compact` keep Pi's native scheduling. Explicit and fallback reset requests share the `agent_settled` scheduler: if the model calls `new_context` in a borrowed fallback run, the explicit request consumes that fallback allowance, producing one reset and at most one continuation. Continuation is suppressed if another prompt is queued or already running. The old entries remain only in the session tree for `history_*`.
+
+The scheduler lives in [`src/reset-lifecycle.ts`](src/reset-lifecycle.ts); `src/index.ts` composes the features and builds reset boundaries. History and notes projections, tool adapters, budget policy, and prompt rendering have separate ownership described in [Architecture](docs/architecture.md). See the [lifecycle event table](docs/reset-lifecycle.md) for ownership and cancellation rules. Shutdown, tree navigation, and toggling off invalidate outstanding callbacks. An aborted run clears pending rollover work. Queued steering/follow-up messages may continue before the run settles; the extension does not clear or replay that queue.
 
 Pi's built-in “compacted into the following summary” envelope is left intact. Its content explicitly says: “Context window reset: this is a fresh window. The previous conversation is not included and no summary was generated. Notes and durable session history persist across windows.” No context filtering or TUI override is used to hide that envelope.
 
@@ -95,4 +97,4 @@ npm run typecheck
 npm test
 ```
 
-The integration harness uses the installed Pi `SessionManager` and `SettingsManager` (global and project settings fixtures in temp directories, so the real `~/.pi` is never touched), including an on-disk JSONL reload. It verifies note persistence/Unicode/path rules, the boot block contents and extension-minted window ids on reset and root paths, that the `context` hook never injects, provider context exclusion after the real `firstKeptEntryId` boundary while history remains searchable, completed tool-result boundary placement, settings-derived reminder threshold resolution and margin validation, that the removed `before_agent_start`/`turn_end` fallback is gone, one early reminder per window, one continuation only, the two-phase automatic ordering (one cancel, one steer, one real reset, re-armed per window, `ctx.compact()` for both threshold and overflow, idle crossings and manual/`new_context` resets bypassing the borrow), and cancellation/failure/no-double-retry behavior. It uses no model or network call.
+The integration harness uses the installed Pi `SessionManager` and `SettingsManager` (global and project settings fixtures in temp directories, so the real `~/.pi` is never touched), including an on-disk JSONL reload. It verifies note persistence/Unicode/path rules, the boot block contents and extension-minted window ids on reset and root paths, that the `context` hook never injects, provider context exclusion after the real `firstKeptEntryId` boundary while history remains searchable, completed tool-result boundary placement, settings-derived reminder threshold resolution and margin validation, that the removed `before_agent_start`/`turn_end` fallback is gone, one early reminder per window, one continuation only, the two-phase automatic ordering (one cancel, one steer, one real reset, re-armed per window, `ctx.compact()` for both threshold and overflow, idle crossings and manual/`new_context` resets bypassing the borrow), and cancellation/failure/no-double-retry behavior. Additional lifecycle tests cover duplicate callbacks, stale callback identity, shutdown/tree/toggle changes, user abort, synchronous errors, native retry ownership, and queued prompts. SDK tests run the real Pi agent loop, extension hooks, manual compaction, and continuation with scripted provider responses: explicit and fallback resets each produce one boundary, exclude old provider context, and preserve durable history. A real uncompactable-session case verifies no automatic retry and recovery on the next user prompt. Further SDK cases verify steering/follow-up delivery before reset without replay, consecutive distinct windows, and user cancellation without automatic continuation. Persisted-data tests verify boot/reminder deduplication after JSONL reload and branch navigation, and reject malformed note timestamps without overwriting valid notes. These tests use temporary settings and fake credentials and make no model or network call.

package/docs/architecture.md

@@ -0,0 +1,39 @@
+# Architecture
+
+pi-context uses Pi's session branch as the durable source of truth. It does not maintain a second transcript or a hidden prompt overlay. Runtime state exists only to schedule work and reserve a reminder until Pi persists it.
+
+## Ownership
+
+| Module | Responsibility | Boundary |
+| --- | --- | --- |
+| `index.ts` | Compose features, expose toggle/reset tool, construct reset boundary | Pi extension API |
+| `history.ts` | Project branch entries into windows/items; identify active window | `SessionReader`, read-only branch and session ID |
+| `notes.ts` | Replay note operations, validate paths/timestamps, slice lines | `SessionReader`; no scheduling or writes |
+| `history-tools.ts`, `note-tools.ts` | Public schemas and tool results; append validated note operations | Pi tool API plus read projections |
+| `budget.ts` | Resolve settings, report usable budget, persist guidance once | Pi settings/context hooks |
+| `prompts.ts` | Render static boot block, note index and reminder | Read projections and protocol text |
+| `reset-lifecycle.ts` | Own reset requests, completion and continuation | Pi lifecycle hooks and injected boundary builder |
+| `protocol.ts` | Persisted entry tags, protocol text and defaults | No imports or effects |
+| `tool-schema.ts`, `tool-output.ts` | Shared wire-schema primitives and JSON result encoding | No session state |
+
+Dependencies flow from the composition root and tool adapters to projections and protocol constants. Projections cannot send messages, compact, notify, or mutate the session. A runtime framework or generic event bus would add indirection without strengthening these boundaries.
+
+## State and persistence
+
+Reset requests are a discriminated union: `idle`, `requested`, or `compacting` with an identified attempt. A request cannot simultaneously be pending and in flight. Each attempt records its originating session, whether it was explicit, and whether a matching boundary completed. Callback identity prevents an old attempt from consuming a newer one. See [reset lifecycle](reset-lifecycle.md).
+
+Fallback allowance is a separate per-window state: `available`, `borrowed`, `ready`, `spent`. It answers whether another note-taking turn may be borrowed, independently of whether an explicit request exists. Success re-arms the allowance; failure does not create a retry loop. Runtime shutdown and tree navigation invalidate outstanding requests.
+
+Boot and reminder deduplication inspect messages in the current persisted window. Reloading the extension or the JSONL file therefore does not duplicate either message. Reminder reservation in memory covers Pi's deferred message write; navigation clears that reservation, while persisted branch-local messages remain authoritative. A sibling branch cannot suppress a reminder it never received.
+
+Note replay accepts only supported operations, safe virtual paths, representable timestamps and results within the UTF-8 size limit. Invalid operations are ignored; they cannot replace a valid note. Reads reconstruct the current branch without a cache, so navigating a branch cannot expose notes from a sibling.
+
+Reset IDs are opaque strings tagged with `reset-v2`; newly minted IDs use `pcw:<session>:<8 lowercase hex digits>`. Unsupported details fall back to Pi's compaction-entry identity for history lookup. Minting checks existing branch window IDs, which are independent of Pi entry IDs. A reset adds a marker via the public append API, then uses its real entry ID as `firstKeptEntryId`; old conversation remains searchable in the durable branch.
+
+## Evidence and limits
+
+The integration suite uses real SessionManager and SettingsManager instances, including JSONL restoration, branch navigation, Unicode content, malformed note operations and settings precedence. Lifecycle event tests cover duplicate/stale callbacks, native scheduling, disabled state, abort and failed compaction.
+
+Scripted SDK tests execute the real Pi agent loop with no model network request. They cover explicit and fallback reset, rejected compaction, steering and follow-up delivery before reset without replay, consecutive distinct windows, and cancellation followed by a new user prompt. They inspect actual provider contexts and durable entries. They do not establish reliability of an external provider or every possible interleaving between unrelated extensions.
+
+Pi decides compaction eligibility before the boundary hook. A short uncompactable session therefore cannot be force-reset with the public API. Mixed tool batches and queued messages may finish before `agent_settled`; the extension preserves their delivery rather than clearing the queue. Native compaction owns its subsequent scheduling, while extension-requested compaction resumes from `onComplete` after Pi clears compaction state.

package/docs/reset-lifecycle.md

@@ -0,0 +1,21 @@
+# Reset lifecycle
+
+`src/reset-lifecycle.ts` owns requests, fallback allowance, compaction attempts, and continuation. `src/index.ts` composes the features and constructs reset boundaries; projections, tools, budget policy, and prompt rendering have separate modules described in [Architecture](architecture.md).
+
+| Event | Transition / owner |
+| --- | --- |
+| `new_context` | Mark explicit request; repeated calls report already pending. Tool returns terminal output. |
+| Streaming automatic `session_before_compact` | Available → borrowed; send one note-taking steer and cancel this compaction. |
+| Idle automatic or manual compaction | Build reset directly; no borrowed turn. |
+| `agent_end` | Borrowed → ready. Aborted run clears explicit request and spends borrowed allowance. |
+| `agent_settled` | If idle and explicit/ready, create one identified attempt and request `ctx.compact`. |
+| Matching `session_compact` | Confirm boundary, persist window state, re-arm allowance. Native compaction retains its own scheduling. |
+| Attempt `onComplete` | Consume attempt; send continuation only for a confirmed boundary when idle with no queued messages. |
+| Attempt `onError` or synchronous throw | Clear attempt/request, warn, retain history. No automatic retry loop. |
+| Shutdown / start / tree / toggle off | Invalidate outstanding attempt. Identity checks reject callbacks from older attempts. |
+
+The completion callback is the scheduling boundary: `session_compact` fires before Pi clears manual compaction state. Sending a prompt inside that hook is too early. Both explicit and borrowed-fallback resets use the manual `ctx.compact` route and therefore need the same completion logic. Native compaction/retry already has a caller responsible for subsequent work.
+
+Public APIs cannot guarantee immediate reset inside mixed tool batches or before queued steering/follow-up messages finish. `terminate` ends the tool-followup path; `agent_settled` remains the safe point to request compaction. The scheduler does not manipulate user queues. Pi also determines compaction eligibility before the extension hook; an uncompactable session produces a warning and waits for a new prompt.
+
+Validation is split into persisted-data integration tests, isolated lifecycle event tests, and scripted SDK tests running Pi's actual agent loop. The SDK tests cover explicit success, fallback success, and core compaction rejection followed by a user prompt. Lifecycle tests cover callback races and queue guards without pretending to exercise provider/network behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -20,13 +20,14 @@
   },
   "files": [
     "src",
+    "docs",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test dist/test/integration.test.js",
+    "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck"
   },
   "peerDependencies": {

package/src/budget.ts

@@ -0,0 +1,122 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, SettingsManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, GUIDANCE_TYPE } from "./protocol.js";
+import { currentWindowId, hasWindowMessage } from "./history.js";
+import { tokenBudgetGuidance } from "./prompts.js";
+import { output } from "./tool-output.js";
+
+type ResolvedThresholds = { reminder: number; reserve: number };
+type PiContextMargins = { reminderMarginTokens: unknown };
+
+function isSettingsObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read the raw "pi-context" object from one parsed settings scope. */
+function piContextSettings(settings: unknown): Record<string, unknown> {
+	if (!isSettingsObject(settings)) return {};
+	const value = settings[PI_CONTEXT_SETTINGS_KEY];
+	return isSettingsObject(value) ? value : {};
+}
+
+/** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
+export function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextMargins {
+	const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
+	return { reminderMarginTokens: merged.reminderMarginTokens };
+}
+
+/** A margin is usable only as a positive integer; anything else is ignored. */
+function validMargin(raw: unknown): number | undefined {
+	if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return undefined;
+	return raw;
+}
+
+/**
+ * Pure derivation of the reminder threshold from Pi's reserve plus the pi-context
+ * reminder margin. An invalid margin degrades to the default and reports one warning.
+ * The borrowed fallback turn has no token threshold of its own: it is driven by Pi's
+ * automatic threshold/overflow compaction request (see session_before_compact).
+ */
+export function deriveThresholds(reserveTokens: number, margins: PiContextMargins): { thresholds: ResolvedThresholds; warnings: string[] } {
+	const warnings: string[] = [];
+	const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+	let reminderMargin: number;
+	if (margins.reminderMarginTokens === undefined) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+	else {
+		const parsed = validMargin(margins.reminderMarginTokens);
+		if (parsed === undefined) {
+			warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+			reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+		} else reminderMargin = parsed;
+	}
+	return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens }, warnings };
+}
+
+export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
+	let guidancePersistedInWindow: string | undefined;
+	let thresholds: ResolvedThresholds | undefined;
+
+	/**
+	 * Resolve the thresholds for this session from Pi's compaction reserve plus the
+	 * settings.json "pi-context" margins. The file-backed read is cached until the next
+	 * session_start; invalid configuration degrades per offending key with one warning
+	 * and never throws during session operation.
+	 */
+	const resolveThresholds = (ctx: ExtensionContext): ResolvedThresholds => {
+		if (thresholds) return thresholds;
+		try {
+			const settingsManager = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
+			const derived = deriveThresholds(
+				settingsManager.getCompactionSettings().reserveTokens,
+				mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()),
+			);
+			for (const warning of derived.warnings) ctx.ui.notify(warning, "warning");
+			thresholds = derived.thresholds;
+		} catch (error) {
+			ctx.ui.notify(`pi-context: could not read settings; using defaults (${String(error)}).`, "warning");
+			thresholds = { reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS, reserve: DEFAULT_RESERVE_TOKENS };
+		}
+		return thresholds;
+	};
+
+	pi.on("session_start", (_event, ctx) => { thresholds = undefined; guidancePersistedInWindow = undefined; resolveThresholds(ctx); });
+	pi.on("session_tree", () => { guidancePersistedInWindow = undefined; });
+	pi.on("context", (_event, ctx) => {
+		if (!isEnabled()) return undefined;
+		// This hook does exactly one thing: persist the once-per-window low-budget
+		// reminder the first time remaining context crosses the reminder threshold.
+		// It never injects messages into the request.
+		const usage = ctx.getContextUsage();
+		if (usage && usage.tokens !== null) {
+			const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+			const windowId = currentWindowId(ctx);
+			const { reminder, reserve } = resolveThresholds(ctx);
+			if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+				guidancePersistedInWindow = windowId;
+				// Persist once per window — no transient copy. A transient bridge would
+				// cover the crossing request, but history would record the reminder after
+				// that request's assistant reply, so across the boundary the model would
+				// meet the same text twice at shifted positions. The reminder is an early
+				// warning, not a per-request instruction: arriving from the next request
+				// on (sendMessage defers safely to end of turn while streaming, queueing
+				// instead of splitting a tool call/result pair) costs nothing, and the
+				// model's view stays identical to recorded history, Codex-style.
+				pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(Math.max(0, remaining - reserve)), display: true }, { triggerTurn: false });
+			}
+		}
+		return undefined;
+	});
+
+	pi.registerTool(defineTool({
+		name: "get_context_remaining",
+		label: "Get context remaining",
+		description: "Return estimated context tokens available before the compaction reserve, clamped to zero; null when Pi cannot estimate usage.",
+		parameters: Type.Object({}, { additionalProperties: false }),
+		async execute(_id, _params, _signal, _update, ctx) {
+			const usage = ctx.getContextUsage();
+			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - resolveThresholds(ctx).reserve);
+			return output({ remaining_tokens: remaining });
+		},
+	}));
+
+}

package/src/history-tools.ts

@@ -0,0 +1,59 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { output } from "./tool-output.js";
+import { positiveInteger, recentFirst, nullableString, role } from "./tool-schema.js";
+import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
+
+export function registerHistoryTools(pi: ExtensionAPI) {
+	pi.registerTool(defineTool({
+		name: "history_list_windows",
+		label: "History list windows",
+		description: "List durable Pi session-history windows.",
+		parameters: Type.Object({ limit: positiveInteger(), recent_first: recentFirst() }, { additionalProperties: false }),
+		async execute(_id, params, _signal, _update, ctx) {
+			let windows = historyFromSession(ctx);
+			if (params.recent_first !== false) windows = [...windows].reverse();
+			const limit = params.limit ?? windows.length;
+			return output({ windows: windows.slice(0, limit).map((window) => ({ window_id: window.windowId, item_count: window.items.length })) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		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: recentFirst(), 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);
+			return output({ items: items.slice(0, params.limit ?? items.length).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200)) });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		name: "history_read_item",
+		label: "History read item",
+		description: "Read a bounded character range from one durable session item.",
+		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 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);
+			const offset = params.offset_chars ?? 0;
+			const limit = params.limit_chars ?? chars.length;
+			return output({ window_id: item.windowId, item_id: item.itemId, offset_chars: offset, content: chars.slice(offset, offset + limit).join("") });
+		},
+	}));
+
+	pi.registerTool(defineTool({
+		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: recentFirst(), 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);
+			const matching = items.filter((item) => item.content.includes(params.query));
+			return output({ items: matching.slice(0, params.limit ?? matching.length).map((item) => visibleItem(item)) });
+		},
+	}));
+
+}

package/src/history.ts

@@ -0,0 +1,166 @@
+import type { TextContent } from "@earendil-works/pi-ai";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { SessionReader } from "./session-reader.js";
+import { RESET_V2 } from "./protocol.js";
+
+type HistoryItem = {
+	windowId: string;
+	itemId: string;
+	role: "user" | "assistant" | "tool" | "system" | "developer";
+	content: string;
+	createdAt: string | undefined;
+	toolName?: string;
+	toolNamespace?: string;
+};
+type HistoryWindow = { windowId: string; createdAt?: string; items: HistoryItem[] };
+
+type HistoryFilter = {
+	window_id?: string | null;
+	role?: HistoryItem["role"] | null;
+	tool_namespace?: string | null;
+	tool_name?: string | null;
+	recent_first?: boolean;
+};
+
+function isTextContent(part: unknown): part is TextContent {
+	return typeof part === "object" && part !== null && (part as TextContent).type === "text" && typeof (part as TextContent).text === "string";
+}
+
+function contentText(content: string | unknown[]): string {
+	if (typeof content === "string") return content;
+	return content.filter(isTextContent).map((part) => part.text).join("\n");
+}
+
+function mapRole(role: AgentMessage["role"]): HistoryItem["role"] | undefined {
+	if (role === "user" || role === "assistant") return role;
+	if (role === "toolResult" || role === "bashExecution") return "tool";
+	if (role === "custom") return "user";
+	if (role === "compactionSummary" || role === "branchSummary") return "system";
+	return undefined;
+}
+
+function messageContent(message: AgentMessage): string {
+	switch (message.role) {
+		case "bashExecution":
+			return message.output;
+		case "branchSummary":
+		case "compactionSummary":
+			return message.summary;
+		default:
+			return contentText(message.content);
+	}
+}
+
+function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "toolNamespace"> {
+	if (message.role === "bashExecution") return { toolName: "bash", toolNamespace: undefined };
+	if (message.role !== "toolResult") return {};
+	const underscore = message.toolName.indexOf("_");
+	return { toolName: message.toolName, toolNamespace: underscore > 0 ? message.toolName.slice(0, underscore) : undefined };
+}
+
+/** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
+export function resetV2WindowId(details: unknown): string | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	const candidate = details as { piContext?: unknown; windowId?: unknown };
+	if (candidate.piContext !== RESET_V2 || typeof candidate.windowId !== "string") return undefined;
+	return candidate.windowId;
+}
+
+/** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
+function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
+	return resetV2WindowId(entry.details) ?? `pcw:${sessionId}:${entry.id}`;
+}
+
+/** Build durable, on-demand history directly from every entry on the current session branch. */
+export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
+	const sessionId = ctx.sessionManager.getSessionId();
+	let window: HistoryWindow = { windowId: `pcw:${sessionId}:root`, items: [] };
+	const windows = [window];
+	for (const entry of ctx.sessionManager.getBranch()) {
+		if (entry.type === "compaction") {
+			window = { windowId: windowIdOf(sessionId, entry), createdAt: entry.timestamp, items: [] };
+			windows.push(window);
+			window.items.push({
+				windowId: window.windowId,
+				itemId: entry.id,
+				role: "system",
+				content: entry.summary,
+				createdAt: entry.timestamp,
+			});
+			continue;
+		}
+		if (entry.type === "message") {
+			const role = mapRole(entry.message.role);
+			if (!role) continue;
+			window.items.push({
+				windowId: window.windowId,
+				itemId: entry.id,
+				role,
+				content: messageContent(entry.message),
+				createdAt: entry.timestamp,
+				...toolInfo(entry.message),
+			});
+			continue;
+		}
+		if (entry.type === "custom_message") {
+			window.items.push({
+				windowId: window.windowId,
+				itemId: entry.id,
+				role: "user",
+				content: contentText(entry.content),
+				createdAt: entry.timestamp,
+			});
+		}
+	}
+	return windows;
+}
+
+export function visibleItem(item: HistoryItem, maxChars = 1200) {
+	const characters = Array.from(item.content);
+	return {
+		window_id: item.windowId,
+		item_id: item.itemId,
+		role: item.role,
+		tool_namespace: item.toolNamespace ?? null,
+		tool_name: item.toolName ?? null,
+		truncated_content: characters.length > maxChars ? `${characters.slice(0, maxChars).join("")}…` : item.content,
+	};
+}
+
+export function allItems(ctx: SessionReader) {
+	return historyFromSession(ctx).flatMap((window) => window.items);
+}
+
+export function filteredItems(ctx: SessionReader, 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);
+	if (typeof params.tool_namespace === "string") items = items.filter((item) => item.toolNamespace === params.tool_namespace);
+	if (typeof params.tool_name === "string") items = items.filter((item) => item.toolName === params.tool_name);
+	if (params.recent_first !== false) items.reverse();
+	return items;
+}
+
+
+/** Persisted messages in the active window, excluding earlier windows on this branch. */
+export function hasWindowMessage(ctx: SessionReader, customType: string): boolean {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry.type === "compaction") break;
+		if (entry.type === "custom_message" && entry.customType === customType) return true;
+	}
+	return false;
+}
+
+/** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
+export function currentWindowId(ctx: SessionReader): 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 windowIdOf(sessionId, entry);
+	}
+	return `pcw:${sessionId}:root`;
+}
+