@astrosheep/pi-context 0.15.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.15.1",
+  "version": "0.16.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));
 		},
@@ -73,9 +77,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,16 @@ 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;
 };
 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 +43,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 +54,35 @@ 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"> {
+	if (message.role === "bashExecution") return { toolName: "bash" };
 	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 };
+}
+
+/**
+ * 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 +128,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,7 +152,6 @@ 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,
 		truncated,
 		total_chars: characters.length,
@@ -141,11 +165,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/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 })]);