@astrosheep/pi-context 0.12.0 → 0.14.0

package/README.md

@@ -14,46 +14,13 @@ Or load it for a single invocation without installing:
 pi -e npm:@astrosheep/pi-context
 ```
 
-## How it works
+## What you get
 
-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 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 hidden custom message (`display: false`, kept out of the TUI). 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 320 Unicode characters or fewer is shown whole; a longer one shows its first 80 and last 240 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 (hidden from the TUI transcript — one ephemeral `ui.notify` warning tells the user instead, and the model never sees it; 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.
-
-## Reminder timing
-
-The reminder threshold derives from Pi's compaction reserve plus a margin configured in `settings.json` under the top-level `pi-context` key:
-
-```json
-{
-  "compaction": { "reserveTokens": 16384 },
-  "pi-context": {
-    "reminderMarginTokens": 24576
-  }
-}
-```
-
-The margin is measured in **remaining context tokens** added on top of Pi's `compaction.reserveTokens`:
-
-- `reminder = reserveTokens + reminderMarginTokens` (default margin `24576`)
-
-Put the key in the global settings (`~/.pi/agent/settings.json`) or the project settings (`<cwd>/.pi/settings.json`); project values win per key, mirroring Pi's own settings merge. With Pi's default `reserveTokens: 16384` the default gives reminder `40960`, leaving 24,576 tokens of working room above Pi's reset line no matter how you set `reserveTokens`. The reminder is an early warning; once fallback guidance has been persisted in the current window, no later early reminder is appended. This also applies after session reload. The borrowed fallback turn needs no threshold of its own: it is driven by Pi's automatic `threshold`/`overflow` compaction request, so `before_agent_start`/`turn_end` send nothing and no `fallbackMarginTokens` setting exists.
-
-Pi's `reserveTokens` and the `pi-context` reminder margin are re-read from disk at every `session_start` and cached for that session. An invalid margin — not a positive integer — is ignored with one TUI warning naming the key and the default used instead; session handling never throws.
-
-This is a file-backed read through Pi's public `SettingsManager`. It sees committed `settings.json` only: SDK-level ephemeral `applyOverrides()` calls and the unreleased `compaction.modelOverrides` are not seen by this extension.
-
-The extension does not change Pi settings or reserve additional context. Large tool outputs or user inputs can jump over the reminder. For small context windows, tune the reminder margin (or Pi's reserve) to fit the model.
-
-## Tools
-
-The nine Codex History/Notes actions are flattened because Pi tools have one global name space:
+- **`new_context`** — the model can start a fresh context window. The old conversation leaves the provider context but stays in the session, so nothing is lost. Call it on its own, not inside a parallel tool batch.
+- **A boot block at every window head** — static once-per-window content (cache-stable) carrying the window identity, the recent-notes index, and a short protocol that teaches the model how to recover: notes for its own bookkeeping, history tools for everything before the reset.
+- **Low-budget guidance** — one persisted early warning per window when the estimated remaining budget crosses the reminder line, so the model checkpoints before the lights go out.
+- **`get_context_remaining`** — the live, reserve-adjusted estimate of the context budget left before Pi's compaction reserve.
+- **Nine history/notes tools** — Codex's History/Notes actions flattened into Pi's single tool namespace:
 
 | Codex action | Pi tool |
 | --- | --- |
@@ -61,42 +28,42 @@ The nine Codex History/Notes actions are flattened because Pi tools have one glo
 | `history.list_items` | `history_list_items` |
 | `history.read_item` | `history_read_item` |
 | `history.search_contents` | `history_search_contents` |
-| `notes.list_files_by_prefix` | `notes_list_files_by_prefix` |
+| `notes.list_files` | `notes_list_files` |
 | `notes.read_file` | `notes_read_file` |
 | `notes.search_contents` | `notes_search_contents` |
 | `notes.append_to_file` | `notes_append_to_file` |
 | `notes.write_file` | `notes_write_file` |
 
-`history_*` reads the current branch's actual Pi session entries, including entries hidden by earlier compaction. Window IDs are extension-owned: the root window is `pcw:<session-id>:root`, and each reset mints an 8-hex id baked into the compaction entry's `details.windowId` as `pcw:<session-id>:<minted>`. Pi-native compactions (extension toggled off) fall back to `pcw:<session-id>:<compaction-entry-id>`. Item IDs are the persisted Pi entry IDs. No transcript copy or volatile archive is maintained. Ordering is newest-first by default: `recent_first` omitted or `true` returns newest-first, and only an explicit `false` returns oldest-first; `history_list_windows`, `history_list_items`, and `history_search_contents` share that switch.
-
-`history_*` and paged `notes_*` read/search results share a **32 KiB (32 * 1024 UTF-8 bytes) per-result budget**. List/search tools return whole items only and include `next_offset` (an integer cursor, or `null` when exhausted); pass that cursor back with the same parameters to continue. `history_read_item` defaults to `limit_chars: 12000`, accepts at most 50000, and returns `total_chars` plus `next_offset_chars` when more content remains. `notes_read_file` returns whole lines only, includes `total_lines`, and uses `next_start_line` for a bounded continuation. When one indivisible unit is larger than the whole budget (a single note line, search match, or history item), it is returned middle-truncated — head and tail joined by a `…[truncated N chars]…` marker, mirroring Codex's `truncate_middle` — instead of being dropped, so a page is never empty and its cursor always advances. `max_chars_per_item` limits Unicode code points including the truncation ellipsis (`…`). The 32 KiB choice matches Aider's default and Claude Code's roughly 30k-character limit while keeping worst-case CJK output (about 11k tokens) below Pi's default `reserveTokens` of 16384.
-
-`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. Staleness is explicit and never inferred from timestamps. `notes_write_file` and `notes_append_to_file` accept an optional `mark_stale` boolean, and `notes_list_files_by_prefix` reports each file's `stale` flag. Stale notes leave the boot notes index — which omits itself once no fresh note remains — but stay listed, readable, and searchable. Each call must carry `text`, `mark_stale`, or both: `mark_stale: true` alone flags a note without touching its content, `mark_stale: false` alone clears the flag without touching content, and either call may carry `text` too — so final content can be written and marked stale in one call, and a closing log line can be appended and marked stale in one call. Carrying `text` without `mark_stale` revives a stale note, and marking a path that does not exist is an error. `notes_read_file` success results and every matched file object from `notes_search_contents` also carry `created_at` and `updated_at`, the same fields `notes_list_files_by_prefix` returns. All note timestamps are local-time ISO 8601 strings with an explicit UTC offset (for example `2026-09-15T17:31:45.392+08:00`; a UTC host renders `+00:00`, never `Z`), while the persisted `NoteFile`/`NoteOperation` metadata keeps plain epoch milliseconds. Error results carry no timestamps. Writes are capped at 1,000,000 UTF-8 bytes. `notes_write_file` and `notes_append_to_file` declare `executionMode: "sequential"` (the Pi equivalent of Codex's `supports_parallel_tool_calls = false`), so a tool batch containing either runs its calls one at a time and note read-modify-write cannot race with itself.
-
-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:
+The tool descriptions the model sees are the behavioral documentation: search is case-sensitive literal substring; reads are character windows whose cursors reconstruct the original exactly; anything a response does not deliver is named by an explicit field.
 
-- `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.
+- **Runtime toggle** — `/pi-context off` restores Pi's default compaction (including `keepRecentTokens`); `/pi-context on` re-enables; bare `/pi-context` reports the current state.
 
-## Reset behavior and limits
+## Configuration
 
-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 reminder threshold is Pi's compaction reserve plus a margin, configured under the top-level `pi-context` key in `~/.pi/agent/settings.json` or `<cwd>/.pi/settings.json` (project values win per key):
 
-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.
+```json
+{
+  "compaction": { "reserveTokens": 16384 },
+  "pi-context": { "reminderMarginTokens": 24576 }
+}
+```
 
-Pi's built-in “compacted into the following summary” envelope is left intact. Its content says, in the extension's wake-up voice: “You wake up. Your head is empty — no memories, the past a blank. But nothing is lost: the notes you wrote and the recorded history still remember for you.” No context filtering or TUI override is used to hide that envelope.
+`reminder = reserveTokens + reminderMarginTokens`; with the defaults the early warning fires 24,576 tokens above Pi's reset line.
 
-The same handler is used for native automatic compaction. When Pi marks an overflow compaction `willRetry`, Pi core performs its single retry itself and this extension deliberately sends no second continuation. While the extension is enabled, its custom reset keeps nothing after the boundary marker, so Pi's `keepRecentTokens` setting has no effect; with `/pi-context off`, Pi's default compaction (and `keepRecentTokens`) applies again.
+## Documentation
 
-This is a composition of public `session_before_compact`, `session_compact`, `pi.appendEntry`, `ctx.compact`, and `pi.sendMessage`; it is not a Pi-core `newSession` call. A manual Pi compaction is only eligible when Pi's own `prepareCompaction()` accepts the session. Therefore a `new_context` request in a too-small/uncompactable session fails cleanly without default-summary fallback or continuation. A core change would be needed only to guarantee a force-reset at arbitrary small context sizes or to atomically interrupt a mixed parallel tool batch.
+Implementation architecture and the reset lifecycle live in [docs/](docs/).
 
-## Verification
+## Development
 
 ```sh
+npm test            # build from a clean dist, then run the suite
 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. 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 fallback note-writing while usage remains above the reserve line, with no obsolete early reminder before reset; 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.
+The harness runs against the real installed Pi `SessionManager`/`SettingsManager` in temporary directories with fake credentials — no model or network calls, and the real `~/.pi` is never touched.
+
+## License
+
+MIT

package/docs/architecture.md

@@ -8,7 +8,7 @@ pi-context uses Pi's session branch as the durable source of truth. It does not
 | --- | --- | --- |
 | `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 |
+| `notes.ts` | Replay note operations, validate paths/timestamps | `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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
     "prepublishOnly": "npm run typecheck"

package/src/history-tools.ts

@@ -1,9 +1,34 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, withinBudget } from "./tool-output.js";
-import { positiveInteger, recentFirst, nullableString, role } from "./tool-schema.js";
+import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
 
+/**
+ * Shrink one page item to fit the wire budget. `truncated`/`total_chars` stay honest: the
+ * payload is only ever cut to a plain prefix of itself, never filled with a marker, and the
+ * flag flips on whenever a shrink actually removed characters. `tool_name` is metadata, not a
+ * payload, and keeps its visible middle-truncation marker. `item_id`, `window_id`, `role`, and
+ * `tool_namespace` are identity or tiny metadata and are never touched.
+ */
+function truncateHistoryItem<T extends { truncated_content: string; truncated: boolean; tool_name: string | null }>(item: T, fits: (candidate: T) => boolean): T {
+	if (fits(item)) return item;
+	const shrinkContent = (base: T): T => ({
+		...base,
+		truncated: true,
+		truncated_content: prefixFit(base.truncated_content, (candidate) => fits({ ...base, truncated: true, truncated_content: candidate } as T)),
+	});
+	const withContent = shrinkContent(item);
+	if (fits(withContent)) return withContent;
+	if (item.tool_name === null) return withContent;
+	// Content could not help even as an empty prefix: tool_name is oversized, so keep the
+	// original payload and truncate the metadata as the last resort.
+	const withName = { ...item, tool_name: middleTruncate(item.tool_name, (candidate) => fits({ ...item, tool_name: candidate } as T)) } as T;
+	if (fits(withName)) return withName;
+	// Both fields are oversized: dissolve the payload against the truncated metadata.
+	return shrinkContent(withName);
+}
+
 export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_list_windows",
@@ -21,41 +46,37 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	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(), offset: Type.Optional(Type.Integer({ minimum: 0 })), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+		description: "List durable session items, including items before compaction, using opaque item and window IDs. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read_item.",
+		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), 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).slice(0, params.limit ?? Number.POSITIVE_INFINITY).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
-			return output(page(items, params.offset ?? 0, "items", undefined, (item, fits) => ({ ...item, truncated_content: middleTruncate(item.truncated_content, (candidate) => fits({ ...item, truncated_content: candidate })) })));
+			const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+			return output(page(items, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));
 
 	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: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000 })), window_id: Type.String() }, { additionalProperties: false }),
+		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget. next_offset_chars is exactly offset_chars plus the delivered code-point count and is null only once the item ends: follow it to reconstruct the item exactly. A negative offset_chars counts back from the item's end, and the response always echoes the resolved absolute offset. Offsets and counts are code points (an emoji or CJK character counts as one).",
+		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })), 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 = Math.min(params.limit_chars ?? 12000, 50000);
-			const result = (content: string) => ({ window_id: item.windowId, item_id: item.itemId, offset_chars: offset, content, total_chars: chars.length, next_offset_chars: offset + limit < chars.length ? offset + limit : null });
-			// One clean middle-truncation replaces the old 0.9 shrink loop: a requested window larger
-			// than the budget comes back with its middle elided, never empty, and the cursor advances.
-			const content = middleTruncate(chars.slice(offset, offset + limit).join(""), (candidate) => withinBudget(result(candidate)));
-			return output(result(content));
+			return output(readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => ({ window_id: item.windowId, item_id: item.itemId, ...window })));
 		},
 	}));
 
 	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(), offset: Type.Optional(Type.Integer({ minimum: 0 })), query: Type.String(), recent_first: recentFirst(), tool_namespace: nullableString(), role: Type.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+		description: "Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read_item at match_offset_chars.",
+		parameters: Type.Object({ limit: positiveInteger(), cursor: cursor(), query: searchQuery(), 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 matching = filteredItems(ctx, params).filter((item) => item.content.includes(params.query)).slice(0, params.limit ?? Number.POSITIVE_INFINITY).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
-			return output(page(matching, params.offset ?? 0, "items", undefined, (item, fits) => ({ ...item, truncated_content: middleTruncate(item.truncated_content, (candidate) => fits({ ...item, truncated_content: candidate })) })));
+			const queries = searchQueries(params.query);
+			const matching = filteredItems(ctx, params)
+				.filter((item) => queries.some((query) => item.content.includes(query)))
+				.map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? 1200), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+			return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));
 

package/src/history.ts

@@ -39,6 +39,9 @@ function mapRole(role: AgentMessage["role"]): HistoryItem["role"] | undefined {
 	return undefined;
 }
 
+/** This extension's own custom-entry namespace; entries under it are authored by pi-context. */
+const PI_CONTEXT_ENTRY_PREFIX = "pi-context/";
+
 function messageContent(message: AgentMessage): string {
 	switch (message.role) {
 		case "bashExecution":
@@ -68,13 +71,13 @@ export function resetV2WindowId(details: unknown): string | undefined {
 
 /** 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}`;
+	return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${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: [] };
+	let window: HistoryWindow = { windowId: `pcw:${sessionId.slice(0, 8)}:root`, items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type === "compaction") {
@@ -83,7 +86,8 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 			window.items.push({
 				windowId: window.windowId,
 				itemId: entry.id,
-				role: "system",
+				// A reset-v2 compaction is authored by this extension; a native Pi compaction is not.
+				role: resetV2WindowId(entry.details) === undefined ? "system" : "developer",
 				content: entry.summary,
 				createdAt: entry.timestamp,
 			});
@@ -106,7 +110,8 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 			window.items.push({
 				windowId: window.windowId,
 				itemId: entry.id,
-				role: "user",
+				// Only entries this extension wrote are its own; every foreign custom message stays a user turn.
+				role: entry.customType.startsWith(PI_CONTEXT_ENTRY_PREFIX) ? "developer" : "user",
 				content: contentText(entry.content),
 				createdAt: entry.timestamp,
 			});
@@ -117,13 +122,18 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 
 export function visibleItem(item: HistoryItem, maxChars = 1200) {
 	const characters = Array.from(item.content);
+	const truncated = characters.length > maxChars;
 	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, Math.max(0, maxChars - 1)).join("")}…` : item.content,
+		truncated,
+		total_chars: characters.length,
+		// A truncated payload is a plain prefix: no synthetic marker is appended, and
+		// `total_chars` names exactly how many code points were left out.
+		truncated_content: truncated ? characters.slice(0, maxChars).join("") : item.content,
 	};
 }
 
@@ -161,6 +171,6 @@ export function currentWindowId(ctx: SessionReader): string {
 		const entry = branch[i];
 		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
 	}
-	return `pcw:${sessionId}:root`;
+	return `pcw:${sessionId.slice(0, 8)}:root`;
 }
 

package/src/index.ts

@@ -5,7 +5,7 @@ import { output } from "./tool-output.js";
 export { deriveThresholds, mergePiContextSettings } from "./budget.js";
 import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, RESET_SUMMARY, CONTINUATION, FALLBACK_PROMPT } from "./protocol.js";
 import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId } from "./history.js";
-import { assertVirtualPath, lineRange } from "./notes.js";
+import { assertVirtualPath } from "./notes.js";
 import { bootBlock } from "./prompts.js";
 export { historyFromSession } from "./history.js";
 export { notesFromSession } from "./notes.js";
@@ -24,7 +24,7 @@ export default function piContext(pi: ExtensionAPI) {
 		// it once as a hidden custom message. Reset windows already carry theirs at
 		// position 0 in the compaction summary, so a resumed session adds nothing.
 		const sessionId = ctx.sessionManager.getSessionId();
-		const rootId = `pcw:${sessionId}:root`;
+		const rootId = `pcw:${sessionId.slice(0, 8)}:root`;
 		if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE)) return;
 		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
 	});
@@ -53,7 +53,7 @@ export default function piContext(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "new_context",
 		label: "New context",
-		description: "Request a reset-style context rollover after this tool result is safely recorded. Call alone in a tool batch.",
+		description: "Clear your mind and start a new context window. Your session, notes, and history survive.",
 		parameters: Type.Object({}, { additionalProperties: false }),
 		async execute() {
 			if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
@@ -71,15 +71,15 @@ export default function piContext(pi: ExtensionAPI) {
 		},
 		onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
 		buildReset: (event, ctx, explicit) => {
-			const sessionId = ctx.sessionManager.getSessionId();
+			const session8 = ctx.sessionManager.getSessionId().slice(0, 8);
 			// Window IDs are independent of Pi entry IDs. Avoid reusing a window
 			// identity already present on this branch.
 			const windows = historyFromSession(ctx);
 			const usedIds = new Set(windows.map((window) => window.windowId));
 			let minted = randomUUID().slice(0, 8);
-			while (usedIds.has(`pcw:${sessionId}:${minted}`)) minted = randomUUID().slice(0, 8);
-			const windowId = `pcw:${sessionId}:${minted}`;
-			const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${sessionId}:root`;
+			while (usedIds.has(`pcw:${session8}:${minted}`)) minted = randomUUID().slice(0, 8);
+			const windowId = `pcw:${session8}:${minted}`;
+			const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${session8}:root`;
 			// The reset marker stays as firstKeptEntryId; it no longer names the window.
 			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: explicit });
 			const markerId = ctx.sessionManager.getLeafId();
@@ -96,4 +96,4 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 }
 
-export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, FALLBACK_PROMPT, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, lineRange, assertVirtualPath };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, FALLBACK_TYPE, FALLBACK_PROMPT, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/src/note-tools.ts

@@ -1,9 +1,9 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, withinBudget } from "./tool-output.js";
-import { nullableString, nullableInteger, positiveInteger } from "./tool-schema.js";
-import { notesFromSession, assertVirtualPath, assertVirtualPrefix, lineRange, localIso, type NoteOperation } from "./notes.js";
-import { NOTE_TYPE, MAX_NOTE_BYTES } from "./protocol.js";
+import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { nullableString, positiveInteger, cursor, searchQuery, searchQueries } from "./tool-schema.js";
+import { notesFromSession, assertVirtualPath, assertVirtualPrefix, assertGlobPattern, globToRegExp, localIso, type NoteOperation } from "./notes.js";
+import { NOTE_TYPE, MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./protocol.js";
 
 export function registerNoteTools(pi: ExtensionAPI) {
 	const saveNote = (op: NoteOperation) => {
@@ -13,67 +13,108 @@ export function registerNoteTools(pi: ExtensionAPI) {
 	};
 
 	pi.registerTool(defineTool({
-		name: "notes_list_files_by_prefix",
+		name: "notes_list_files",
 		label: "Notes list files",
-		description: "List persistent, session-scoped virtual note files. created_at and updated_at are local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ prefix: nullableString(), max_results: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
+		description: "List note files, optionally filtered by a glob pattern (* within a path segment, ** across segments). The default order is most recently updated first; file_order_by (name, created_at, updated_at) and file_order (ascending, descending) select another. Entries carry each file's stale flag.",
+		parameters: Type.Object({ pattern: nullableString(), max_results: positiveInteger(), cursor: cursor(), file_order_by: Type.Optional(Type.Union([Type.Literal("name"), Type.Literal("created_at"), Type.Literal("updated_at")])), file_order: Type.Optional(Type.Union([Type.Literal("ascending"), Type.Literal("descending")])) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
-			const prefix = assertVirtualPrefix(params.prefix);
-			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
-			const key = params.file_order_by ?? "name";
-			files.sort(([aPath, a], [bPath, b]) => key === "name" ? aPath.localeCompare(bPath) : (key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt));
-			if (params.file_order === "descending") files.reverse();
-			const listed = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
-			return output(page(listed, params.offset ?? 0, "files", params.max_results, (file, fits) => ({ ...file, path: middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate })) })));
+			const pattern = assertGlobPattern(params.pattern);
+			const matcher = pattern ? globToRegExp(pattern) : undefined;
+			let files = [...notesFromSession(ctx)].filter(([path]) => !matcher || matcher.test(path));
+			const key = params.file_order_by ?? "updated_at";
+			// Deterministic total order: (axis key, createdAt, path) ascending. Paths are unique, so
+			// this never depends on map iteration order; descending reverses the whole comparator.
+			files.sort(([aPath, a], [bPath, b]) => {
+				const primary = key === "name" ? aPath.localeCompare(bPath) : key === "created_at" ? a.createdAt - b.createdAt : a.updatedAt - b.updatedAt;
+				if (primary !== 0) return primary;
+				if (a.createdAt !== b.createdAt) return a.createdAt - b.createdAt;
+				return aPath.localeCompare(bPath);
+			});
+			// An explicit file_order always wins; otherwise the axis's natural direction applies
+			// (descending for the time axes, ascending for name).
+			if (params.file_order ? params.file_order === "descending" : key !== "name") files.reverse();
+			const listed: Array<{ path: string; size_bytes: number; stale: boolean; created_at: string; updated_at: string; path_truncated?: boolean }> = files.map(([path, file]) => ({ path, size_bytes: Buffer.byteLength(file.text, "utf8"), stale: file.stale, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) }));
+			// `path` is the entry's identity: return it intact whenever the entry fits, and only
+			// ever alter it together with a visible `path_truncated: true` flag. A pathological
+			// legacy path predating the write cap is the one case that cannot fit at all.
+			return output(page(listed, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+				if (fits(file)) return file;
+				const path = middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate, path_truncated: true }));
+				return { ...file, path, path_truncated: true };
+			}));
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_read_file",
 		label: "Notes read file",
-		description: "Read a virtual note file, optionally by inclusive 1-based line range; negative lines count from the end. Success results carry created_at and updated_at as local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ path: Type.String(), start_line: nullableInteger(), stop_line: nullableInteger() }, { additionalProperties: false }),
+		description: "Read a character window from a note file: offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end (offset_chars: -2000 reads the last 2000) and the response echoes the resolved absolute offset — and limit_chars caps the window (default 12000, max 50000). Each response delivers the longest fitting prefix of that window: pass next_offset_chars back unchanged to continue, concatenate pages in order, null only at the end.",
+		parameters: Type.Object({ path: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })) }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const path = assertVirtualPath(params.path);
 			const file = notesFromSession(ctx).get(path);
 			if (!file) return output({ error: "note file not found", path });
-			const range = lineRange(file.text, params.start_line, params.stop_line);
-			const lines = range.content ? range.content.split("\n") : [];
-			const totalLines = file.text.split("\n").length;
-			const result = (content: string, count: number) => ({ path, start_line: range.start_line, stop_line: range.start_line + count - 1, content, total_lines: totalLines, next_start_line: range.start_line + count <= range.stop_line ? range.start_line + count : null, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt) });
-			let count = lines.length;
-			while (count > 0 && !withinBudget(result(lines.slice(0, count).join("\n"), count))) count--;
-			if (count === 0 && lines.length > 0) {
-				// One indivisible line is larger than the whole budget: return it middle-truncated and
-				// advance past it instead of looping on an empty page whose cursor never moves.
-				return output(result(middleTruncate(lines[0], (candidate) => withinBudget(result(candidate, 1))), 1));
-			}
-			return output(result(lines.slice(0, count).join("\n"), count));
+			const created_at = localIso(file.createdAt);
+			const updated_at = localIso(file.updatedAt);
+			return output(readCharacterWindow(file.text, params.offset_chars, params.limit_chars, (window) => ({ path, ...window, created_at, updated_at })));
 		},
 	}));
 
 	pi.registerTool(defineTool({
 		name: "notes_search_contents",
 		label: "Notes search",
-		description: "Case-sensitive literal substring search over virtual note lines; no semantic search. Each matched file carries created_at and updated_at as local-time ISO 8601 strings with an explicit UTC offset.",
-		parameters: Type.Object({ max_matches_per_file: positiveInteger(), offset: Type.Optional(Type.Integer({ minimum: 0 })), query: Type.String(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
+		description: "Case-sensitive literal substring search over note lines; query is one string or several (OR), each matched line appears once. No semantic search. Each file entry carries matches_total, its full match count before capping: matches_total minus matches.length is how many were dropped. Each match carries line and offset_chars (the file-absolute code-point offset of the earliest match): notes_read_file at offset_chars shows the query. An over-budget matched line comes back as a prefix with truncated and total_chars; read the rest at the same offset_chars.",
+		parameters: Type.Object({ max_matches_per_file: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_file_first: Type.Optional(Type.Boolean()), max_files: positiveInteger(), path_prefix: nullableString() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
+			const queries = searchQueries(params.query);
 			const prefix = assertVirtualPrefix(params.path_prefix);
 			let files = [...notesFromSession(ctx)].filter(([path]) => !prefix || path.startsWith(prefix));
 			if (params.recent_file_first) files.sort((a, b) => b[1].createdAt - a[1].createdAt);
 			const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
-			const result = files.map(([path, file]) => ({ path, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt), matches: file.text.split("\n").flatMap((line, index) => line.includes(params.query) ? [{ line: index + 1, text: line }] : []).slice(0, maxPerFile) })).filter((file) => file.matches.length > 0);
-			// A file is capped by dropping whole trailing matches, but its last match is never
-			// dropped: one oversized line is middle-truncated so the file still appears.
+			const result: Array<{ path: string; created_at: string; updated_at: string; matches_total: number; matches: Array<{ line: number; text: string; truncated: boolean; total_chars: number; offset_chars: number }>; path_truncated?: boolean }> = files
+				.map(([path, file]) => {
+					// A match's offset_chars is file-absolute: the code points before its line, plus the
+					// earliest occurrence of any query inside that line. Search then composes with
+					// notes_read_file exactly like history_search_contents composes with history_read_item.
+					let baseChars = 0;
+					const allMatches = file.text.split("\n").flatMap((line, index) => {
+						const match = queries.some((query) => line.includes(query))
+							? [{ line: index + 1, text: line, truncated: false, total_chars: Array.from(line).length, offset_chars: baseChars + earliestMatchOffsetChars(line, queries) }]
+							: [];
+						baseChars += Array.from(line).length + 1;
+						return match;
+					});
+					return { path, created_at: localIso(file.createdAt), updated_at: localIso(file.updatedAt), matches_total: allMatches.length, matches: allMatches.slice(0, maxPerFile) };
+				})
+				.filter((file) => file.matches.length > 0);
+			// Trailing matches are dropped to fit the budget (bounded by a monotone binary search),
+			// and the entry's matches_total keeps naming the drop. Only when a single intact match is
+			// over budget is its line delivered as a plain prefix, flagged and counted. Only when the
+			// entry cannot fit even then is the identity field itself truncated, and then only together
+			// with a visible `path_truncated: true` flag.
 			const fitFile = (file: (typeof result)[number], fits: (candidate: (typeof result)[number]) => boolean) => {
-				let matches = file.matches;
-				while (matches.length > 1 && !fits({ ...file, matches })) matches = matches.slice(0, -1);
-				const first = matches[0];
-				if (!first) return { ...file, matches };
-				const text = middleTruncate(first.text, (candidate) => fits({ ...file, matches: [{ ...first, text: candidate }, ...matches.slice(1)] }));
-				return { ...file, matches: [{ ...first, text }, ...matches.slice(1)] };
+				if (fits(file)) return file;
+				const matches = file.matches;
+				// First, drop whole trailing matches: the largest prefix that fits intact is kept, so an
+				// entry only truncates a line when that single line alone is over budget.
+				let low = 0;
+				let high = matches.length;
+				while (low < high) {
+					const mid = Math.ceil((low + high) / 2);
+					if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) })) low = mid;
+					else high = mid - 1;
+				}
+				if (low >= 1) return { ...file, matches: matches.slice(0, low) };
+				// Even one intact match is over budget: keep the first match as a plain, named prefix.
+				const first = matches[0]!;
+				const fitted = (text: string): (typeof result)[number] => ({ ...file, matches: [{ ...first, text, truncated: true }] });
+				const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+				const prefix: (typeof result)[number] = fitted(text);
+				if (fits(prefix)) return prefix;
+				const path = middleTruncate(prefix.path, (candidate) => fits({ ...prefix, path: candidate, path_truncated: true }));
+				return { ...prefix, path, path_truncated: true };
 			};
-			return output(page(result.slice(0, params.max_files ?? result.length), params.offset ?? 0, "files", undefined, fitFile));
+			return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
 		},
 	}));
 
@@ -82,8 +123,8 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			name,
 			label: name === "notes_append_to_file" ? "Notes append" : "Notes write",
 			description: name === "notes_append_to_file"
-				? "Append exact text to a persistent virtual note file. Appending suits chronological logs; for current-state notes, replace the whole file with notes_write_file instead. Accepts the same mark_stale flag to close a note."
-				: "Create or replace a persistent virtual note file. Keep notes small and split by topic; replace outdated notes whole. With mark_stale: true, flag the note as stale instead — optionally writing its final content in the same call: stale notes leave the boot index but stay readable and searchable, and rewriting revives them.",
+				? "Append exact text to a note file. Appending suits chronological logs; for current-state notes use notes_write_file instead. mark_stale closes a note."
+				: "Create or replace a note file. Keep notes small and split by topic; replace outdated notes whole. mark_stale: true flags a note stale (optionally with its final content): stale notes leave the boot index but stay readable and searchable; rewriting revives them.",
 			parameters: Type.Object({ text: Type.Optional(Type.String()), path: Type.String(), mark_stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
 			// Codex sets supports_parallel_tool_calls = false on notes.write_file/append_to_file.
 			// Pi's per-tool equivalent is executionMode "sequential": a batch containing either
@@ -91,6 +132,11 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			executionMode: "sequential",
 			async execute(_id, params, _signal, _update, ctx) {
 				const path = assertVirtualPath(params.path);
+				const pathBytes = Buffer.byteLength(path, "utf8");
+				// The cap lives here, at the tool boundary, and never in assertVirtualPath: note
+				// replay validates persisted ops through that helper and must keep loading sessions
+				// that already contain a longer legacy path (reads stay un-capped too).
+				if (pathBytes > MAX_NOTE_PATH_BYTES) return output({ error: `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes`, path_bytes: pathBytes });
 				const hasText = params.text !== undefined;
 				const hasStale = params.mark_stale !== undefined;
 				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });

package/src/notes.ts

@@ -25,6 +25,40 @@ export function assertVirtualPrefix(value: unknown): string | undefined {
 	return assertVirtualPath(value);
 }
 
+/**
+ * Minimal glob over virtual note paths: `*` matches any run within a segment (never
+ * `/`), `**` matches any run across segments (a leading double-star followed by a
+ * slash also matches zero segments, so it covers the root too), `?` matches exactly
+ * one non-`/` character. Everything else is literal and the match is anchored to the
+ * whole path.
+ */
+export function globToRegExp(pattern: string): RegExp {
+	let source = "^";
+	for (let index = 0; index < pattern.length; index++) {
+		const char = pattern[index]!;
+		if (char === "*") {
+			if (pattern[index + 1] === "*") {
+				const followedBySlash = pattern[index + 2] === "/";
+				source += followedBySlash ? "(?:[^]*\\/)?" : "[^]*";
+				index += followedBySlash ? 2 : 1;
+			} else {
+				source += "[^/]*";
+			}
+		} else {
+			source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+		}
+	}
+	return new RegExp(`${source}$`);
+}
+
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+export function assertGlobPattern(value: unknown): string | undefined {
+	if (value === undefined || value === null || value === "") return undefined;
+	if (typeof value !== "string") throw new Error("glob pattern must be a string");
+	if (value.includes("\0") || value.includes("\\")) throw new Error("glob pattern must not contain NUL or backslashes");
+	return value;
+}
+
 /** Replays only pi-context note operations from session custom entries. */
 function isNoteOperation(data: unknown): data is NoteOperation {
 	if (typeof data !== "object" || data === null) return false;
@@ -63,19 +97,6 @@ export function notesFromSession(ctx: SessionReader): Map<string, NoteFile> {
 	return files;
 }
 
-export function lineRange(text: string, startValue: unknown, stopValue: unknown) {
-	const lines = text.split("\n");
-	const resolve = (value: unknown, fallback: number) => {
-		if (value === undefined || value === null) return fallback;
-		if (!Number.isInteger(value) || value === 0) throw new Error("line numbers must be non-zero integers; negative values count from the end");
-		const line = value as number;
-		return line > 0 ? line : lines.length + line + 1;
-	};
-	const start = Math.max(1, resolve(startValue, 1));
-	const stop = Math.min(lines.length, resolve(stopValue, lines.length));
-	return { start_line: start, stop_line: stop, content: start > stop ? "" : lines.slice(start - 1, stop).join("\n") };
-}
-
 const pad2 = (value: number) => String(value).padStart(2, "0");
 
 /**

package/src/prompts.ts

@@ -65,6 +65,6 @@ export function bootBlock(ctx: ExtensionContext, currentId: string, previousId:
  * at write time; get_context_remaining remains the live source for the current figure.
  */
 export function tokenBudgetGuidance(remaining: number): string {
-	return `${GUIDANCE_OPEN_TAG}\nYour memory is about to be erased — only ${remaining} tokens left at last count; get_context_remaining has the live number. Before the lights go out, write your checkpoint with notes_write_file: the goal, decisions, progress, open issues, next steps, the skills you still need, and the window ID and item ID of every user request you are still solving. Then call new_context and wake clean. Don't count on the automatic reset leaving you another turn to write.\n${GUIDANCE_CLOSE_TAG}`;
+	return `${GUIDANCE_OPEN_TAG}\nYour memory is about to be erased — only ${remaining} tokens left at last count; get_context_remaining has the live number. Before the lights go out, write your checkpoint with notes_write_file: the goal, decisions, progress, open issues, next steps, the skills you still need, and the window ID and item ID of every user request you are still solving. If this checkpoint replaces an older note, close it in the same sitting with mark_stale: true — stale notes leave the boot index but stay readable and searchable. Then call new_context and wake clean. Don't count on the automatic reset leaving you another turn to write.\n${GUIDANCE_CLOSE_TAG}`;
 }
 

package/src/protocol.ts

@@ -7,6 +7,10 @@ export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
 export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
+// Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
+// notesFromSession replays already-persisted operations, which must keep loading sessions
+// that contain a longer legacy path. Reads and replay stay un-capped.
+export const MAX_NOTE_PATH_BYTES = 512;
 export const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 export const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
 export const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";

package/src/tool-output.ts

@@ -41,6 +41,83 @@ export function middleTruncate(text: string, fits: (content: string) => boolean)
 	return build(low);
 }
 
+/**
+ * Longest contiguous prefix of `text` (counted in code points) accepted by `fits`.
+ *
+ * This is the truncation used by every cursor-bearing payload: the delivered text is
+ * always a plain prefix of the original, so a cursor computed from its code-point length
+ * addresses exactly the first undelivered character. No marker character is ever appended;
+ * the companion `truncated`/`total_chars` fields name what was left out.
+ */
+export function prefixFit(text: string, fits: (content: string) => boolean): string {
+	if (fits(text)) return text;
+	const chars = Array.from(text);
+	// Serialized size is non-decreasing in the kept count, so the largest fitting prefix is
+	// found by a monotone binary search instead of a quadratic shrink loop.
+	let low = 0;
+	let high = chars.length;
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		if (fits(chars.slice(0, mid).join(""))) low = mid;
+		else high = mid - 1;
+	}
+	// A candidate's serialized size can dip by a byte or two at the very end (a numeric cursor
+	// becoming null), so the predicate is not perfectly monotone at the tail. Back off until the
+	// returned prefix provably fits; in the monotone case this loop never runs.
+	while (low > 0 && !fits(chars.slice(0, low).join(""))) low -= 1;
+	return chars.slice(0, low).join("");
+}
+
+/**
+ * Fields every character-window read returns; each tool adds its own identity and metadata.
+ * `offset_chars` is always the resolved absolute offset, and `next_offset_chars` is exactly
+ * that offset plus the delivered code-point count, null only at the text's true end.
+ */
+export type CharacterWindow = {
+	offset_chars: number;
+	content: string;
+	total_chars: number;
+	next_offset_chars: number | null;
+};
+
+/**
+ * Read one character window of `text`: the longest contiguous prefix of
+ * `chars[resolved, resolved + limit)` that fits the wire budget.
+ *
+ * `offsetChars` is a code-point offset. A negative value counts back from the end and
+ * resolves to `max(0, total_chars + offsetChars)`, so `-N` reaches the tail and any
+ * `N >= total_chars` reads from the start; the resolved absolute offset is always echoed.
+ * Following `next_offset_chars` reconstructs `text` by plain concatenation, because the
+ * payload is always a plain prefix with no marker. `render` builds the exact response for
+ * a candidate window, so the budget is measured on the bytes that go on the wire.
+ */
+export function readCharacterWindow<T>(text: string, offsetChars: number | undefined, limitChars: number | undefined, render: (window: CharacterWindow) => T): T {
+	const chars = Array.from(text);
+	const requested = offsetChars ?? 0;
+	const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
+	const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? 12000, 50000));
+	const build = (content: string): CharacterWindow => {
+		const next = resolved + Array.from(content).length;
+		return { offset_chars: resolved, content, total_chars: chars.length, next_offset_chars: next < chars.length ? next : null };
+	};
+	const content = prefixFit(windowChars.join(""), (candidate) => withinBudget(render(build(candidate))));
+	return render(build(content));
+}
+
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export function earliestMatchOffsetChars(text: string, queries: string[]): number {
+	let earliest = -1;
+	for (const query of queries) {
+		const index = text.indexOf(query);
+		if (index < 0) continue;
+		if (earliest < 0 || index < earliest) earliest = index;
+	}
+	return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}
+
 /** Shrink a single page item to fit; only invoked when that item alone exceeds the budget. */
 export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;
 
@@ -48,17 +125,17 @@ export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;
  * Build a page without ever adding an item that would exceed the wire budget.
  *
  * A single item that cannot fit is middle-truncated through the optional `truncate`
- * callback and still included, with `next_offset` advanced past it. Without that fallback
+ * callback and still included, with `next_cursor` advanced past it. Without that fallback
  * an oversized item would yield an empty page forever: the cursor would keep pointing back
  * at the same index.
  */
-export function page<T>(items: T[], offset: number, key: string, limit?: number, truncate?: ItemTruncator<T>) {
-	const end = Math.min(items.length, offset + (limit ?? items.length));
+export function page<T>(items: T[], cursor: number, key: string, limit?: number, truncate?: ItemTruncator<T>) {
+	const end = Math.min(items.length, cursor + (limit ?? items.length));
 	const selected: T[] = [];
 	let next = end < items.length ? end : null;
-	for (let index = offset; index < end; index++) {
+	for (let index = cursor; index < end; index++) {
 		const candidateNext = index + 1 < end || end < items.length ? index + 1 : null;
-		const fits = (list: T[]) => withinBudget({ [key]: list, next_offset: candidateNext });
+		const fits = (list: T[]) => withinBudget({ [key]: list, next_cursor: candidateNext });
 		if (!fits([...selected, items[index]])) {
 			if (selected.length === 0 && truncate) {
 				selected.push(truncate(items[index], (candidate) => fits([candidate])));
@@ -70,7 +147,7 @@ export function page<T>(items: T[], offset: number, key: string, limit?: number,
 		}
 		selected.push(items[index]);
 	}
-	return { [key]: selected, next_offset: next };
+	return { [key]: selected, next_cursor: next };
 }
 
 /** Encode a result through the common tool result boundary. */

package/src/tool-schema.ts

@@ -1,7 +1,24 @@
 import { Type } from "@earendil-works/pi-ai";
 export const nullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
-export const nullableInteger = () => Type.Optional(Type.Union([Type.Integer(), Type.Null()]));
 export const positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
+export const cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
 export const recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
-export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()]);
+/** Role filter. `developer` is the known author for this extension's own custom entries. */
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the entry's known author: user/assistant/tool from the conversation, system for native Pi compaction summaries, developer for entries this extension authored (its boot, guidance, fallback, and continuation messages, its reset-window compaction summaries, and any other pi-context/* entry)." });
+
+/** Search query parameter: one literal, or several literals combined with OR. */
+export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);
+
+/**
+ * Normalize a search `query` parameter into the literal needles to match.
+ * A bare string is a one-element list, so single-query behavior is unchanged.
+ * An empty list or a non-string element is refused rather than silently searching
+ * for nothing: an empty array is an argument error, not an empty result set.
+ */
+export function searchQueries(query: unknown): string[] {
+	if (typeof query === "string") return [query];
+	if (!Array.isArray(query) || query.length === 0) throw new Error("query must be a string or a non-empty array of strings");
+	if (!query.every((candidate) => typeof candidate === "string")) throw new Error("query array elements must be strings");
+	return query as string[];
+}