@astrosheep/pi-context 0.15.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
 
@@ -57,12 +57,16 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_read_item",
 		label: "History read item",
-		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).",
+		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: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
 		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" });
-			return output(readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => ({ window_id: item.windowId, item_id: item.itemId, ...window })));
+			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...cursor } = window;
+				return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
+			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));
 

package/src/note-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } 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";
@@ -48,7 +48,7 @@ export function registerNoteTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "notes_read_file",
 		label: "Notes read file",
-		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.",
+		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 limit_chars caps the window (default 12000, max 50000). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw note text behind a one-line [bracketed] header naming the file, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or 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);
@@ -56,7 +56,11 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			if (!file) return output({ error: "note file not found", path });
 			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 })));
+			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			return readCharacterWindow(file.text, params.offset_chars, params.limit_chars, (window) => {
+				const { content, ...cursor } = window;
+				return outputRaw(characterWindowHeader(path, window, ` · created ${created_at} · updated ${updated_at}`), content, { path, ...cursor, limit_chars, created_at, updated_at });
+			}, (result) => withinTextBudget(result.content[0].text));
 		},
 	}));
 

package/src/protocol.ts

@@ -52,5 +52,5 @@ Notes are session-scoped virtual files. Treat notes and history as internal book
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 
 export const WARNING_PROMPT =
-	"Memory wipe incoming — this turn is all you get. Do not continue any task. Get that checkpoint down NOW — one note, write it or append to it: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Then call new_context immediately and go out clean — anything not in the note is gone.";
+	"Your memory is about to be erased. Write the note. NOW. If it already exists, append instead: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";
 

package/src/tool-output.ts

@@ -9,6 +9,11 @@ export function withinBudget(value: unknown, budget = TOOL_OUTPUT_MAX_BYTES): bo
 	return Buffer.byteLength(json(value), "utf8") <= budget;
 }
 
+/** True when `text` fits the wire budget verbatim, for raw payloads with no JSON encoding. */
+export function withinTextBudget(text: string, budget = TOOL_OUTPUT_MAX_BYTES): boolean {
+	return Buffer.byteLength(text, "utf8") <= budget;
+}
+
 /** Marker standing in for characters elided from the middle of an oversized single unit. */
 export function truncationMarker(removedChars: number): string {
 	return `…[truncated ${removedChars} chars]…`;
@@ -89,9 +94,11 @@ export type CharacterWindow = {
  * `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.
+ * a candidate window, and `measure` decides whether that response fits the wire budget (JSON
+ * serialization by default; raw-text renders pass a verbatim byte measure), so the budget is
+ * always 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 {
+export function readCharacterWindow<T>(text: string, offsetChars: number | undefined, limitChars: number | undefined, render: (window: CharacterWindow) => T, measure: (rendered: T) => boolean = withinBudget): T {
 	const chars = Array.from(text);
 	const requested = offsetChars ?? 0;
 	const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
@@ -100,10 +107,23 @@ export function readCharacterWindow<T>(text: string, offsetChars: number | undef
 		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))));
+	const content = prefixFit(windowChars.join(""), (candidate) => measure(render(build(candidate))));
 	return render(build(content));
 }
 
+/**
+ * One-line bracketed header preceding a raw character-window payload: the identity, the
+ * delivered char range, and either the resume cursor or `end`. `tail` appends extra
+ * metadata (notes add their timestamps) inside the same brackets.
+ */
+export function characterWindowHeader(identity: string, window: CharacterWindow, tail = ""): string {
+	// The range end is offset + delivered count, never `total_chars`: a read resolved past the
+	// end delivers zero characters there, and the header must not render an inverted range.
+	const end = window.offset_chars + Array.from(window.content).length;
+	const resume = window.next_offset_chars === null ? "end" : `continue at offset_chars=${window.next_offset_chars}`;
+	return `[${identity} · chars ${window.offset_chars}-${end} of ${window.total_chars} · ${resume}${tail}]`;
+}
+
 /**
  * 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.
@@ -150,7 +170,20 @@ export function page<T>(items: T[], cursor: number, key: string, limit?: number,
 	return { [key]: selected, next_cursor: next };
 }
 
-/** Encode a result through the common tool result boundary. */
-export function output(value: unknown, details: unknown = value, terminate = false) {
+/**
+ * Encode a structured result through the common tool result boundary. `details` is slim
+ * metadata for logs/UI (pi convention: never a second copy of the payload) and stays
+ * undefined unless the tool has metadata worth persisting.
+ */
+export function output(value: unknown, details?: unknown, terminate = false) {
 	return { content: [{ type: "text" as const, text: json(value) }], details, terminate };
 }
+
+/**
+ * Encode a prose payload as raw text: a one-line bracketed metadata header, then the payload
+ * verbatim. The model reads the note or history item itself instead of a JSON envelope;
+ * `details` carries the slim metadata object and never duplicates the payload.
+ */
+export function outputRaw(header: string, content: string, details: unknown, terminate = false) {
+	return { content: [{ type: "text" as const, text: `${header}\n${content}` }], details, terminate };
+}