@howaboua/pi-notes-compaction 0.0.0-stage → 0.0.1

package/src/bridge.ts

@@ -0,0 +1,156 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type {
+	AgentToolResult,
+	ExtensionAPI,
+	ExtensionContext,
+	SessionEntry,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+export const BRIDGE_CHANNEL = "pi-notes-compaction:bridge:v1";
+export const OWNER_CHANNEL = "pi-notes-compaction:owner:v1";
+export const TOOL_NAMES = [
+	"notes",
+	"history",
+	"new_context",
+	"get_context_remaining",
+] as const;
+
+export interface LookupQuery {
+	namespace: "notes" | "history";
+	params: Record<string, unknown>;
+}
+
+/** Raw backend response, not a reconstructed ciphertext or an old delivery receipt. */
+export interface CachedResponse {
+	query: LookupQuery;
+	bytes: Uint8Array;
+	source: string;
+	encoding: string;
+	fetchedAt: number;
+	coverage: "complete" | "partial" | "unknown";
+}
+
+export interface WindowIdentity {
+	firstWindowId: string;
+	currentWindowId: string;
+	previousWindowId?: string;
+	windowNumber: number;
+}
+
+export interface NoteSnapshotData {
+	protocol: 1;
+	timestamp: number;
+	files: Array<{
+		path: string;
+		text: string;
+		createdAt: number;
+		updatedAt: number;
+		operation: "local_append_overlay" | "local_replacement";
+	}>;
+}
+
+/** JSON-safe raw provenance. Projection belongs to the requesting runtime. */
+export interface SerializedCachedResponse
+	extends Omit<CachedResponse, "bytes"> {
+	bytesBase64: string;
+}
+
+export interface SharedNotesDetails {
+	codexHistoryNotes: Record<string, unknown>;
+	externalNotesResponses?: SerializedCachedResponse[];
+	notesCompactionRouted?: true;
+}
+
+export interface NotesOwner {
+	protocol: 1;
+	owner: "pi-notes-compaction";
+	identity(ctx: ExtensionContext): WindowIdentity | undefined;
+	projectMessages(messages: readonly AgentMessage[]): AgentMessage[];
+	projectBranch(entries: readonly SessionEntry[]): SessionEntry[];
+	canBind?(ctx: ExtensionContext): boolean;
+	snapshotNotes?(
+		entries: readonly SessionEntry[],
+		agentName: string,
+	): NoteSnapshotData;
+	executeShared?(
+		query: LookupQuery,
+		callId: string,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<SharedNotesDetails>>;
+}
+
+export interface NotesBridge {
+	protocol: 1;
+	/** Synchronous atomic handoff. No legacy registrations or lifecycle owners remain active. */
+	claim(owner: NotesOwner):
+		| {
+				claimed: true;
+				registerTools(
+					tools: readonly ToolDefinition[],
+					ctx: ExtensionContext,
+				): void;
+		  }
+		| { claimed: false; reason: string };
+	/** Configures PCC nested registrations, visibility and opaque-result capture. Never nests new_context. */
+	configureTools?(
+		tools: readonly ToolDefinition[],
+		ctx: ExtensionContext,
+		contracts: Readonly<Record<"notes" | "history", string>>,
+	): void;
+	beforeWindow?(ctx: ExtensionContext, signal?: AbortSignal): Promise<void>;
+	lookup?(
+		query: LookupQuery,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+	): Promise<readonly CachedResponse[]>;
+	canProject?(ctx: ExtensionContext): boolean;
+	/** Fresh current-call delivery, including original exec ancestry when nested. */
+	projectResult?(
+		result: AgentToolResult<unknown>,
+		responses: readonly CachedResponse[],
+		callId: string,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<unknown>>;
+	agentName?(ctx: ExtensionContext): string;
+	/** Optional family routing. undefined means this agent owns the requested path. */
+	route?(
+		query: LookupQuery,
+		callId: string,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<unknown> | undefined>;
+}
+
+export interface BridgeRequest {
+	protocol: 1;
+	reply(bridge: NotesBridge): void;
+}
+export interface OwnerRequest {
+	protocol: 1;
+	reply(owner: NotesOwner): void;
+}
+
+export function discoverBridge(pi: ExtensionAPI): NotesBridge | undefined {
+	let found: NotesBridge | undefined;
+	pi.events.emit(BRIDGE_CHANNEL, {
+		protocol: 1,
+		reply(bridge: NotesBridge) {
+			if (bridge?.protocol !== 1 || typeof bridge.claim !== "function")
+				throw new Error("Unsupported notes bridge");
+			if (found && found !== bridge)
+				throw new Error("Multiple notes bridges responded");
+			found = bridge;
+		},
+	} satisfies BridgeRequest);
+	return found;
+}
+
+export function queryKey(query: LookupQuery): string {
+	return JSON.stringify([
+		query.namespace,
+		Object.entries(query.params).sort(([a], [b]) => a.localeCompare(b)),
+	]);
+}

package/src/fresh-notes.ts

@@ -0,0 +1,132 @@
+import {
+	buildSessionProjection,
+	type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { NOTE_RECEIPT, noteReceipt } from "./notes.js";
+
+/** A receipt proves persistence. Current-run tool outcomes prove the checkpoint actually completed. */
+export function hasFreshNotes(
+	branch: readonly SessionEntry[],
+	windowId: string | undefined,
+	runId?: string,
+): boolean {
+	if (!windowId) return false;
+	const lastUser = branch.findLastIndex(
+		(entry) => entry.type === "message" && entry.message.role === "user",
+	);
+	const run = branch.slice(lastUser + 1);
+	const receipts = run
+		.filter(
+			(entry) => entry.type === "custom" && entry.customType === NOTE_RECEIPT,
+		)
+		.flatMap((entry) =>
+			entry.type === "custom" ? [noteReceipt(entry.data)] : [],
+		)
+		.filter(
+			(receipt) =>
+				receipt &&
+				receipt.origin !== "routed" &&
+				receipt.windowId === windowId &&
+				(!runId || receipt.runId === runId),
+		);
+	if (!receipts.length) return false;
+	const messages = buildSessionProjection(run).messages;
+	const final = messages.findLast((message) => message.role === "assistant");
+	if (
+		final?.role !== "assistant" ||
+		final.stopReason !== "stop" ||
+		final.content.some((block) => block.type === "toolCall")
+	)
+		return false;
+	const calls = messages.flatMap((message) =>
+		message.role === "assistant"
+			? message.content.filter((block) => block.type === "toolCall")
+			: [],
+	);
+	const results = messages.flatMap((message) =>
+		message.role === "toolResult" ? [message] : [],
+	);
+	const writes = calls.filter(
+		(call) =>
+			call.name === "notes" &&
+			(call.arguments["action"] === "write_file" ||
+				call.arguments["action"] === "append_to_file"),
+	);
+	let completedWrite = false;
+	for (const call of writes) {
+		const result = results.find(
+			(result) =>
+				result.toolCallId === call.id && result.toolName === call.name,
+		);
+		if (
+			result?.details &&
+			typeof result.details === "object" &&
+			"notesCompactionRouted" in result.details &&
+			result.details["notesCompactionRouted"] === true
+		)
+			continue;
+		if (
+			!result ||
+			result.isError ||
+			!result.details ||
+			typeof result.details !== "object" ||
+			!("notesCompaction" in result.details)
+		)
+			return false;
+		const details = result.details["notesCompaction"];
+		if (
+			!details ||
+			typeof details !== "object" ||
+			!("protocol" in details) ||
+			details["protocol"] !== 1 ||
+			!("saved" in details) ||
+			details["saved"] !== true ||
+			!("runId" in details) ||
+			!receipts.some((receipt) => receipt?.runId === details["runId"])
+		)
+			return false;
+		completedWrite = true;
+	}
+	for (const result of results) {
+		const details = result.details;
+		const saved =
+			details && typeof details === "object" && "contextNotesSaved" in details
+				? details["contextNotesSaved"]
+				: undefined;
+		// PCC's protected exec/wait host records cover nested calls outside Pi's executeTool path.
+		if (saved === false || (saved === true && result.isError)) return false;
+		if (
+			saved === true &&
+			(result.toolName === "exec" || result.toolName === "wait")
+		)
+			completedWrite = true;
+		const nested = result.nestedCalls;
+		const noteCalls =
+			nested?.calls.filter((call) => call.name === "notes") ?? [];
+		if (
+			noteCalls.some(
+				(call) =>
+					call.status !== "ok" &&
+					(!call.arguments ||
+						call.arguments["action"] === "write_file" ||
+						call.arguments["action"] === "append_to_file"),
+			) ||
+			(noteCalls.length && !nested?.complete)
+		)
+			return false;
+		const nestedWrites =
+			nested?.calls.filter(
+				(call) =>
+					call.name === "notes" &&
+					(call.arguments?.["action"] === "write_file" ||
+						call.arguments?.["action"] === "append_to_file"),
+			) ?? [];
+		if (
+			nestedWrites.some((call) => call.status !== "ok") ||
+			(nestedWrites.length && (result.isError || !nested?.complete))
+		)
+			return false;
+		if (nestedWrites.length) completedWrite = true;
+	}
+	return completedWrite;
+}

package/src/history.ts

@@ -0,0 +1,198 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { windowDetails } from "./windows.js";
+
+interface HistoryItem {
+	window_id: string;
+	item_id: string;
+	role: string;
+	tool_name?: string;
+	tool_namespace?: string;
+	content: string;
+}
+
+function customHistoryRole(
+	entry: Extract<SessionEntry, { type: "custom_message" }>,
+): string {
+	// Persisted developer metadata is a wire contract, not a package dependency.
+	const details = entry.details;
+	const metadata =
+		details &&
+		typeof details === "object" &&
+		"@howaboua/pi-codex-conversion/developer-message" in details
+			? details["@howaboua/pi-codex-conversion/developer-message"]
+			: [
+						"codex-developer-message",
+						"codex-context-window",
+						"codex-current-time-reminder",
+						"codex-toolkit-update",
+						"codex-notebook-status",
+						"codex-context-briefing",
+					].includes(entry.customType)
+				? details
+				: undefined;
+	return metadata &&
+		typeof metadata === "object" &&
+		"protocol" in metadata &&
+		metadata.protocol === 1 &&
+		"id" in metadata &&
+		typeof metadata.id === "string" &&
+		metadata.id.trim() !== ""
+		? "developer"
+		: "user";
+}
+
+/** Pi's selected JSONL branch is the archive. No transcript database or Tree backend. */
+export function useHistory(
+	entries: readonly SessionEntry[],
+	params: Record<string, unknown>,
+	sessionId: string,
+): Record<string, unknown> {
+	let windowId = `session:${sessionId}`;
+	const windows = new Map<string, HistoryItem[]>();
+	windows.set(windowId, []);
+	for (const entry of entries) {
+		const boundary = windowDetails(entry);
+		if (boundary?.kind === "window") {
+			windowId = boundary.identity.currentWindowId;
+			if (!windows.has(windowId)) windows.set(windowId, []);
+			continue;
+		}
+		if (entry.type === "message") {
+			const message = entry.message;
+			const call =
+				message.role === "assistant"
+					? message.content.find((block) => block.type === "toolCall")
+					: undefined;
+			const toolName =
+				message.role === "toolResult"
+					? message.toolName
+					: call?.type === "toolCall"
+						? call.name
+						: undefined;
+			const content = !("content" in message)
+				? JSON.stringify(message)
+				: typeof message.content === "string"
+					? message.content
+					: message.content
+							.map((block) => {
+								if (block.type === "text") return block.text;
+								if (block.type === "thinking") return block.thinking;
+								if (block.type === "toolCall")
+									return JSON.stringify({
+										tool: block.name,
+										arguments: block.arguments,
+									});
+								if (block.type === "image") return `[image ${block.mimeType}]`;
+								return JSON.stringify(block);
+							})
+							.join("\n");
+			windows.get(windowId)!.push({
+				window_id: windowId,
+				item_id: entry.id,
+				role: message.role === "toolResult" ? "tool" : message.role,
+				...(toolName
+					? {
+							tool_name: toolName,
+							...(["notes", "history"].includes(toolName)
+								? { tool_namespace: toolName }
+								: {}),
+						}
+					: {}),
+				content,
+			});
+		} else if (entry.type === "custom_message" && !boundary) {
+			windows.get(windowId)!.push({
+				window_id: windowId,
+				item_id: entry.id,
+				role: customHistoryRole(entry),
+				content:
+					typeof entry.content === "string"
+						? entry.content
+						: entry.content
+								.map((block) =>
+									block.type === "text" ? block.text : "[image]",
+								)
+								.join("\n"),
+			});
+		}
+	}
+	const action = params["action"];
+	if (action === "list_windows") {
+		let values = [...windows].filter(([, items]) => items.length);
+		if (params["recent_first"] === true) values = values.reverse();
+		const limit = integer(params["limit"], 20, 100);
+		return {
+			windows: values
+				.slice(0, limit)
+				.map(([id, items]) => ({ window_id: id, item_count: items.length })),
+			truncated: values.length > limit,
+		};
+	}
+	if (action === "read_item") {
+		if (
+			typeof params["window_id"] !== "string" ||
+			typeof params["item_id"] !== "string"
+		)
+			throw new Error("Supply window_id and item_id unchanged from history");
+		const item = windows
+			.get(params["window_id"])
+			?.find((item) => item.item_id === params["item_id"]);
+		if (!item) return { item: null };
+		const offset = integer(params["offset_chars"], 0, item.content.length);
+		const limit = integer(params["limit_chars"], 8000, 8000);
+		const content = item.content.slice(offset, offset + limit);
+		return {
+			item: {
+				...item,
+				content,
+				total_chars: item.content.length,
+				...(offset + content.length < item.content.length
+					? { next_offset_chars: offset + content.length }
+					: {}),
+			},
+		};
+	}
+	if (action !== "list_items" && action !== "search_contents")
+		throw new Error("Unknown history action");
+	if (
+		action === "search_contents" &&
+		(typeof params["query"] !== "string" || !params["query"])
+	)
+		throw new Error("Supply a nonempty search query");
+	let items = [...windows.values()]
+		.flat()
+		.filter(
+			(item) =>
+				(!params["window_id"] || item.window_id === params["window_id"]) &&
+				(!params["role"] || item.role === params["role"]) &&
+				(!params["tool_name"] || item.tool_name === params["tool_name"]) &&
+				(!params["tool_namespace"] ||
+					item.tool_namespace === params["tool_namespace"]) &&
+				(action !== "search_contents" ||
+					item.content.includes(params["query"] as string)),
+		);
+	if (params["recent_first"] === true) items = items.reverse();
+	const limit = integer(params["limit"], 10, 25);
+	const previewChars = integer(params["max_chars_per_item"], 1000, 1000);
+	const previews = [];
+	let size = 0;
+	for (const item of items) {
+		const { content, ...metadata } = item;
+		const preview = {
+			...metadata,
+			truncated_content: content.slice(0, previewChars),
+			content_chars: content.length,
+		};
+		const chars = JSON.stringify(preview).length;
+		if (previews.length >= limit || size + chars > 8000) break;
+		previews.push(preview);
+		size += chars;
+	}
+	return { items: previews, truncated: previews.length < items.length };
+}
+
+function integer(value: unknown, fallback: number, max: number): number {
+	return typeof value === "number" && Number.isInteger(value)
+		? Math.max(0, Math.min(value, max))
+		: fallback;
+}