@astrosheep/pi-context 0.15.1 → 0.17.0

package/package.json

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

@@ -2,14 +2,14 @@ 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 { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
-import { historyFromSession, filteredItems, visibleItem, allItems } from "./history.js";
+import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } 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.
+ * payload, and keeps its visible middle-truncation marker. `item_id`, `window_id`, and `role`
+ * 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;
@@ -46,9 +46,13 @@ 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. 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 }),
+		description: "List durable session items, including items before compaction, using opaque item and window IDs; the role parameter's description enumerates the six roles. 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(), 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 invalid = vacuousRoleToolCombo(params);
+			if (invalid) return output({ error: invalid, role: params.role, tool_name: params.tool_name });
+			const badWindow = unknownWindowId(ctx, params);
+			if (badWindow) return output({ error: badWindow.message, window_id: params.window_id, known_windows: badWindow.known });
 			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));
 		},
@@ -62,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;
@@ -73,9 +83,13 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 	pi.registerTool(defineTool({
 		name: "history_search_contents",
 		label: "History search",
-		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 }),
+		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. Invocations and outputs are separate items (roles \"tool_call\" and \"tool\"), so both are searchable; the role parameter's description enumerates all six. 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(), 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 invalid = vacuousRoleToolCombo(params);
+			if (invalid) return output({ error: invalid, role: params.role, tool_name: params.tool_name });
+			const badWindow = unknownWindowId(ctx, params);
+			if (badWindow) return output({ error: badWindow.message, window_id: params.window_id, known_windows: badWindow.known });
 			const queries = searchQueries(params.query);
 			const matching = filteredItems(ctx, params)
 				.filter((item) => queries.some((query) => item.content.includes(query)))

package/src/history.ts

@@ -1,4 +1,4 @@
-import type { TextContent } from "@earendil-works/pi-ai";
+import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { SessionReader } from "./session-reader.js";
 import { RESET_V2 } from "./protocol.js";
@@ -6,18 +6,21 @@ import { RESET_V2 } from "./protocol.js";
 type HistoryItem = {
 	windowId: string;
 	itemId: string;
-	role: "user" | "assistant" | "tool" | "system" | "developer";
+	role: "user" | "assistant" | "tool_call" | "tool" | "system" | "developer";
 	content: string;
 	createdAt: string | undefined;
 	toolName?: string;
-	toolNamespace?: 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[] };
 
 type HistoryFilter = {
 	window_id?: string | null;
 	role?: HistoryItem["role"] | null;
-	tool_namespace?: string | null;
 	tool_name?: string | null;
 	recent_first?: boolean;
 };
@@ -45,7 +48,9 @@ const PI_CONTEXT_ENTRY_PREFIX = "pi-context/";
 function messageContent(message: AgentMessage): string {
 	switch (message.role) {
 		case "bashExecution":
-			return message.output;
+			// The command is as much the record as its output: without it the typed line is
+			// unsearchable. Mirrors the tool-call projection below.
+			return message.output ? `${message.command}\n${message.output}` : message.command;
 		case "branchSummary":
 		case "compactionSummary":
 			return message.summary;
@@ -54,11 +59,38 @@ function messageContent(message: AgentMessage): string {
 	}
 }
 
-function toolInfo(message: AgentMessage): Pick<HistoryItem, "toolName" | "toolNamespace"> {
-	if (message.role === "bashExecution") return { toolName: "bash", toolNamespace: undefined };
+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 {};
-	const underscore = message.toolName.indexOf("_");
-	return { toolName: message.toolName, toolNamespace: underscore > 0 ? message.toolName.slice(0, underscore) : undefined };
+	return { toolName: message.toolName, toolError: message.isError === true ? true : undefined };
+}
+
+/**
+ * An assistant turn's tool calls, projected as their own items: calls wear their own role so the
+ * authoring turn's visible text (role "assistant") stays pure; what was invoked stays as
+ * searchable as what came back (role "tool"). Ids derive from the turn's entry id and stay
+ * opaque; history_read_item resolves them like any other item.
+ */
+function toolCallItems(windowId: string, entry: { id: string; timestamp?: string }, message: AgentMessage): HistoryItem[] {
+	if (message.role !== "assistant" || !Array.isArray(message.content)) return [];
+	const items: HistoryItem[] = [];
+	let callIndex = 0;
+	for (const part of message.content) {
+		if (typeof part !== "object" || part === null || (part as { type?: unknown }).type !== "toolCall") continue;
+		const call = part as ToolCall;
+		items.push({
+			windowId,
+			itemId: `${entry.id}#${callIndex++}`,
+			role: "tool_call",
+			content: JSON.stringify(call.arguments),
+			createdAt: entry.timestamp,
+			toolName: call.name,
+		});
+	}
+	return items;
 }
 
 /** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
@@ -104,6 +136,7 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 				createdAt: entry.timestamp,
 				...toolInfo(entry.message),
 			});
+			window.items.push(...toolCallItems(window.windowId, entry, entry.message));
 			continue;
 		}
 		if (entry.type === "custom_message") {
@@ -127,8 +160,11 @@ export function visibleItem(item: HistoryItem, maxChars = 1200) {
 		window_id: item.windowId,
 		item_id: item.itemId,
 		role: item.role,
-		tool_namespace: item.toolNamespace ?? null,
 		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
@@ -141,11 +177,34 @@ export function allItems(ctx: SessionReader) {
 	return historyFromSession(ctx).flatMap((window) => window.items);
 }
 
-	export function filteredItems(ctx: SessionReader, params: HistoryFilter): HistoryItem[] {
+/**
+ * window_id must name a real window; anything else is a named error, not a silent empty page
+ * (a window that exists but has no matching items after the other filters stays a legal empty
+ * page). Returns the teaching message plus the known window ids so the error is self-healing.
+ */
+export function unknownWindowId(ctx: SessionReader, params: HistoryFilter): { message: string; known: string[] } | undefined {
+	if (typeof params.window_id !== "string") return undefined;
+	const known = historyFromSession(ctx).map((window) => window.windowId);
+	return known.includes(params.window_id) ? undefined : { message: `unknown window_id "${params.window_id}"`, known };
+}
+
+/**
+ * A role×tool_name combination is vacuous — provably empty from the taxonomy alone, before
+ * any data is read — when tool_name is given alongside a role that never carries one. Only
+ * "tool_call" and "tool" items have a tool name. Returns the teaching error message, or
+ * undefined when the combination can match.
+ */
+export function vacuousRoleToolCombo(params: HistoryFilter): string | undefined {
+	if (typeof params.tool_name === "string" && typeof params.role === "string" && params.role !== "tool_call" && params.role !== "tool") {
+		return `tool_name is only set on "tool_call" and "tool" items; role "${params.role}" never carries one`;
+	}
+	return undefined;
+}
+
+export function filteredItems(ctx: SessionReader, params: HistoryFilter): HistoryItem[] {
 	let items = allItems(ctx);
 	if (typeof params.window_id === "string") items = items.filter((item) => item.windowId === params.window_id);
 	if (typeof params.role === "string") items = items.filter((item) => item.role === params.role);
-	if (typeof params.tool_namespace === "string") items = items.filter((item) => item.toolNamespace === params.tool_namespace);
 	if (typeof params.tool_name === "string") items = items.filter((item) => item.toolName === params.tool_name);
 	if (params.recent_first !== false) items.reverse();
 	return items;

package/src/note-tools.ts

@@ -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);
@@ -146,6 +152,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/tool-schema.ts

@@ -4,7 +4,7 @@ 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." }));
 /** 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, warning, and continuation messages, its reset-window compaction summaries, and any other pi-context/* entry)." });
+export const role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool_call"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: "Filter by the item's role. Exactly six: \"user\" and \"assistant\" are a message's visible text (assistant text never contains tool calls); \"tool_call\" is one tool invocation (tool_name set, content = the call's JSON arguments); \"tool\" is one tool run's output (tool_name set); \"system\" is a native Pi compaction summary; \"developer\" is an entry this extension authored (boot, guidance, warning, continuation messages, reset-window compaction summaries, any 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 })]);
@@ -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[];
 }