@astrosheep/pi-context 0.16.0 → 0.18.0

package/package.json

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

@@ -66,6 +66,12 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		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 totalChars = Array.from(item.content).length;
+			// A positive offset past the end is an addressing error, not an empty page: say so,
+			// and name the largest legal offset (offset == total stays the legal empty end-read).
+			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
+				return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
+			}
 			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;

package/src/history.ts

@@ -10,6 +10,11 @@ type HistoryItem = {
 	content: string;
 	createdAt: string | undefined;
 	toolName?: string;
+	// bashExecution only: the persisted output was truncated and the full text lives on disk.
+	outputTruncated?: boolean;
+	fullOutputPath?: string;
+	// toolResult only: the run reported an error.
+	toolError?: boolean;
 };
 type HistoryWindow = { windowId: string; createdAt?: string; items: HistoryItem[] };
 
@@ -54,10 +59,13 @@ function messageContent(message: AgentMessage): string {
 	}
 }
 
-function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName"> {
-	if (message.role === "bashExecution") return { toolName: "bash" };
+function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "outputTruncated" | "fullOutputPath" | "toolError"> {
+	if (message.role === "bashExecution") {
+		// A truncated bash run is only half the record without the on-disk path: surface both.
+		return { toolName: "bash", outputTruncated: message.truncated || undefined, fullOutputPath: message.truncated ? message.fullOutputPath : undefined };
+	}
 	if (message.role !== "toolResult") return {};
-	return { toolName: message.toolName };
+	return { toolName: message.toolName, toolError: message.isError === true ? true : undefined };
 }
 
 /**
@@ -153,6 +161,10 @@ export function visibleItem(item: HistoryItem, maxChars = 1200) {
 		item_id: item.itemId,
 		role: item.role,
 		tool_name: item.toolName ?? null,
+		// Surfaced only when set: a truncated bash run names its full-output path, and an
+		// errored tool run says so. Absent keys mean nothing special happened.
+		...(item.outputTruncated ? { output_truncated: true, full_output_path: item.fullOutputPath ?? null } : {}),
+		...(item.toolError ? { tool_error: true } : {}),
 		truncated,
 		total_chars: characters.length,
 		// A truncated payload is a plain prefix: no synthetic marker is appended, and

package/src/note-tools.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 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 { notesFromSession, assertVirtualPath, 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) {
@@ -54,6 +54,12 @@ export function registerNoteTools(pi: ExtensionAPI) {
 			const path = assertVirtualPath(params.path);
 			const file = notesFromSession(ctx).get(path);
 			if (!file) return output({ error: "note file not found", path });
+			const totalChars = Array.from(file.text).length;
+			// A positive offset past the end is an addressing error, not an empty page: say so,
+			// and name the largest legal offset (offset == total stays the legal empty end-read).
+			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
+				return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, path, offset_chars: params.offset_chars, total_chars: totalChars });
+			}
 			const created_at = localIso(file.createdAt);
 			const updated_at = localIso(file.updatedAt);
 			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
@@ -67,12 +73,13 @@ export function registerNoteTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "notes_search_contents",
 		label: "Notes search",
-		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 }),
+		description: "Case-sensitive literal substring search over note lines; query is one string or several (OR), each matched line appears once. No semantic search. Optionally filtered by a glob pattern (* within a path segment, ** across segments). 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(), pattern: 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));
+			const pattern = assertGlobPattern(params.pattern);
+			const matcher = pattern ? globToRegExp(pattern) : undefined;
+			let files = [...notesFromSession(ctx)].filter(([path]) => !matcher || matcher.test(path));
 			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: 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
@@ -146,6 +153,9 @@ export function registerNoteTools(pi: ExtensionAPI) {
 				if (!hasText && !hasStale) return output({ error: "provide text, mark_stale, or both", path });
 				const old = notesFromSession(ctx).get(path);
 				if (!hasText && !old) return output({ error: "note file not found", path });
+				// Appending is not creating: an append to a path that does not exist almost always
+				// means a typo'd path, so it dies loudly instead of silently minting a new note.
+				if (op === "append" && hasText && !old) return output({ error: "note file not found (use notes_write_file to create)", path });
 				const next = hasText ? (op === "append" ? `${old?.text ?? ""}${params.text}` : params.text as string) : old!.text;
 				const bytes = Buffer.byteLength(next, "utf8");
 				if (hasText && bytes > MAX_NOTE_BYTES) return output({ error: `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes`, path, size_bytes: bytes });

package/src/notes.ts

@@ -20,11 +20,6 @@ export function assertVirtualPath(value: unknown): string {
 	return value;
 }
 
-export function assertVirtualPrefix(value: unknown): string | undefined {
-	if (value === undefined || value === null || value === "") return 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
@@ -112,4 +107,3 @@ export function localIso(epochMs: number): string {
 	const wallClock = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
 	return `${wallClock}${offset}`;
 }
-

package/src/tool-schema.ts

@@ -12,13 +12,15 @@ export const searchQuery = () => Type.Union([Type.String(), Type.Array(Type.Stri
 /**
  * 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.
+ * An empty list, a non-string element, or an empty string is refused rather than silently
+ * searching for nothing: those are argument errors, not empty result sets. An empty string
+ * matches every line and every item, so it can never be what the caller meant.
  */
 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[];
+	const candidates = typeof query === "string" ? [query] : query;
+	if (!Array.isArray(candidates) || candidates.length === 0) throw new Error("query must be a string or a non-empty array of strings");
+	if (!candidates.every((candidate) => typeof candidate === "string")) throw new Error("query array elements must be strings");
+	if (candidates.some((candidate) => candidate === "")) throw new Error("query strings must be non-empty: an empty query matches everything");
+	return candidates as string[];
 }