@linxiraos/pi-agent-core 1.0.0

package/src/compaction/entries.ts

@@ -0,0 +1,141 @@
+import type { ImageContent, MessageAttribution, ServiceTierByFamily, TextContent } from "@linxiraos/pi-ai";
+import type { AgentMessage } from "../types";
+
+export interface SessionEntryBase {
+	type: string;
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+}
+
+export interface SessionMessageEntry extends SessionEntryBase {
+	type: "message";
+	message: AgentMessage;
+}
+
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+	type: "thinking_level_change";
+	thinkingLevel?: string | null;
+}
+
+export interface ModelChangeEntry extends SessionEntryBase {
+	type: "model_change";
+	/** Model in "provider/modelId" format */
+	model: string;
+	/** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+	role?: string;
+}
+
+export interface ServiceTierChangeEntry extends SessionEntryBase {
+	type: "service_tier_change";
+	serviceTier: ServiceTierByFamily | null;
+}
+
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+	type: "compaction";
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+	details?: T;
+	/** Hook-provided data to persist across compaction */
+	preserveData?: Record<string, unknown>;
+	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+	fromExtension?: boolean;
+	/**
+	 * Dead-end warning from the post-pass progress guard: the pass completed
+	 * but freed too little for maintenance to continue. Rendered on the
+	 * compaction divider.
+	 */
+	warning?: string;
+}
+
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+	type: "branch_summary";
+	fromId: string;
+	summary: string;
+	/** Extension-specific data (not sent to LLM) */
+	details?: T;
+	/** True if generated by an extension, false if pi-generated */
+	fromExtension?: boolean;
+}
+
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+	type: "custom_message";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	details?: T;
+	display: boolean;
+	/** Who initiated this message for billing/attribution semantics. */
+	attribution?: MessageAttribution;
+}
+
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+	type: "custom";
+	customType: string;
+	data?: T;
+}
+
+export interface LabelEntry extends SessionEntryBase {
+	type: "label";
+	targetId: string;
+	label: string | undefined;
+}
+
+export interface TitleChangeEntry extends SessionEntryBase {
+	type: "title_change";
+	title: string;
+	previousTitle?: string;
+	source: "auto" | "user";
+	trigger?: string;
+}
+
+export interface TtsrInjectionEntry extends SessionEntryBase {
+	type: "ttsr_injection";
+	/** Names of rules that were injected */
+	injectedRules: string[];
+}
+
+export interface SessionInitEntry extends SessionEntryBase {
+	type: "session_init";
+	/** Full system prompt sent to the model */
+	systemPrompt: string;
+	/** Initial task/user message */
+	task: string;
+	/** Tools available to the agent */
+	tools: string[];
+	/** Output schema if structured output was requested */
+	outputSchema?: unknown;
+}
+
+export interface ModeChangeEntry extends SessionEntryBase {
+	type: "mode_change";
+	/** Current mode name, or "none" when exiting a mode */
+	mode: string;
+	/** Optional mode-specific data (e.g. plan file path) */
+	data?: Record<string, unknown>;
+}
+
+export interface CustomCompactionSessionEntries {}
+
+export type SessionEntry =
+	| SessionMessageEntry
+	| ThinkingLevelChangeEntry
+	| ModelChangeEntry
+	| ServiceTierChangeEntry
+	| CompactionEntry
+	| BranchSummaryEntry
+	| CustomEntry
+	| CustomMessageEntry
+	| LabelEntry
+	| TitleChangeEntry
+	| TtsrInjectionEntry
+	| SessionInitEntry
+	| ModeChangeEntry
+	| CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
+
+export interface ReadonlySessionManager {
+	getBranch(leafId?: string | null): SessionEntry[];
+	getEntry(id: string): SessionEntry | undefined;
+}

package/src/compaction/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * Compaction error types.
+ *
+ * `CompactionCancelledError` is the canonical signal raised when a compaction
+ * is explicitly aborted — operator Esc, extension hook returning `cancel`,
+ * programmatic `session.abortCompaction()` call, or any other deliberate
+ * abort source. Downstream callers (e.g. `executeCompaction`) discriminate
+ * cancellation from other failures via `instanceof CompactionCancelledError`
+ * rather than introspecting error messages or `name` fields — the typed
+ * sentinel makes classification source-agnostic and refactor-stable.
+ */
+
+export class CompactionCancelledError extends Error {
+	override readonly name = "CompactionCancelledError" as const;
+
+	constructor(message = "Compaction cancelled") {
+		super(message);
+	}
+}
+
+/**
+ * A provider-native compaction request failed after every native protocol
+ * available for the selected model was exhausted.
+ *
+ * The cause stays attached so AI error classification can still recognize
+ * authentication failures. Non-auth failures remain distinguishable from
+ * ordinary summarization errors and must not fall through to another provider.
+ */
+export class NativeCompactionError extends Error {
+	override readonly name = "NativeCompactionError" as const;
+
+	constructor(cause: unknown) {
+		super(cause instanceof Error ? cause.message : String(cause), { cause });
+	}
+}
+
+/**
+ * Outcome of a compaction attempt, surfaced by `CommandController.executeCompaction`
+ * so callers (e.g. the plan-mode approval flow) can distinguish a deliberate abort
+ * from an unrelated failure.
+ *
+ *   "ok"        — compaction completed; transcript was summarized.
+ *   "cancelled" — `CompactionCancelledError` was raised. Operator Esc, extension
+ *                 hook, programmatic abort — all source-agnostic.
+ *   "failed"    — any other rejection from `session.compact()`.
+ */
+export type CompactionOutcome = "ok" | "cancelled" | "failed";

package/src/compaction/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Compaction and summarization utilities.
+ */
+
+export * from "./branch-summarization";
+export * from "./compaction";
+export * from "./entries";
+export * from "./errors";
+export * from "./message-cache";
+export * from "./messages";
+export * from "./openai";
+export * from "./pruning";
+export * from "./shake";
+export * from "./utils";

package/src/compaction/message-cache.ts

@@ -0,0 +1,92 @@
+/**
+ * Per-message memoization for the two hot history walks: token estimation
+ * ({@link estimateTokens}) and LLM conversion (the coding-agent's `convertToLlm`).
+ *
+ * Long sessions re-walk a settled `AgentMessage[]` every turn, re-tokenizing and
+ * re-converting historical objects that only the newest suffix can change. These
+ * caches key on message *identity* so a settled message is counted/converted once
+ * and reused until an owner rewrites it.
+ *
+ * Correctness rests on two invariants:
+ *
+ * 1. **Settle gate.** A streaming assistant is mutated under one identity while
+ *    its `usage`/`stopReason` are provisional (the seed carries zeroed usage and
+ *    a placeholder `stopReason`). Caching it would freeze a mid-stream count, so
+ *    estimation only caches assistants that are settled — real `usage`
+ *    (`totalTokens > 0`) with a terminal `stopReason` that is not `"aborted"` /
+ *    `"error"`. Unsettled assistants never read or insert. Non-assistant roles
+ *    are immutable once appended and cache by identity.
+ * 2. **Owner invalidation.** `pruneToolOutputs` / `pruneSupersededToolResults`,
+ *    `applyShakeRegion`, and `stripImagesFromMessage` rewrite message content in
+ *    place under a stable identity. Each MUST call {@link invalidateMessageCache}
+ *    on the mutated message before the next convert/estimate pass so both caches
+ *    drop the stale entry. The convert cache lives in another package, so it
+ *    subscribes via {@link registerMessageCacheInvalidator}.
+ */
+import type { AssistantMessage } from "@linxiraos/pi-ai";
+import type { AgentMessage } from "../types";
+
+/** External cache invalidators (e.g. the coding-agent `convertToLlm` memo). */
+const externalInvalidators = new Set<(message: AgentMessage) => void>();
+
+/**
+ * Register a cache tied to message identity so owner mutations in this package
+ * (prune/shake) can invalidate it across the package boundary. Returns an
+ * unregister function. The coding-agent `convertToLlm` memo registers here.
+ */
+export function registerMessageCacheInvalidator(invalidate: (message: AgentMessage) => void): () => void {
+	externalInvalidators.add(invalidate);
+	return () => {
+		externalInvalidators.delete(invalidate);
+	};
+}
+
+// Dual option-split estimate caches: the compaction floor passes
+// `excludeEncryptedReasoning` (dropping opaque provider reasoning), so a message
+// has two distinct estimates that must not collide in one map.
+//
+// These are WeakMaps, not symbol-tagged properties, deliberately: callers spread
+// messages to derive throwaway variants for counting — `estimateBranchSummaryTokens`
+// does `estimateTokens({ ...message, content: truncated })`. A symbol-keyed cache
+// value rides along an object spread, so the truncated clone would inherit (and
+// return) the full-content estimate. Keying strictly on identity keeps the cache
+// off spread copies, which get their own fresh count.
+const estimateCacheDefault = new WeakMap<AgentMessage, number>();
+const estimateCacheFloored = new WeakMap<AgentMessage, number>();
+
+/**
+ * True when this message's estimate is safe to cache by identity. Non-assistants
+ * are immutable once appended; assistants are cached only once settled (see the
+ * settle-gate invariant above).
+ */
+export function isEstimateCacheable(message: AgentMessage): boolean {
+	if (message.role !== "assistant") return true;
+	const assistant = message as AssistantMessage;
+	return (
+		assistant.stopReason !== "aborted" &&
+		assistant.stopReason !== "error" &&
+		assistant.usage != null &&
+		assistant.usage.totalTokens > 0
+	);
+}
+
+/** Read a cached estimate for the given option split, or `undefined` on miss. */
+export function readEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean): number | undefined {
+	return (excludeEncryptedReasoning ? estimateCacheFloored : estimateCacheDefault).get(message);
+}
+
+/** Store an estimate for the given option split. */
+export function writeEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean, value: number): void {
+	(excludeEncryptedReasoning ? estimateCacheFloored : estimateCacheDefault).set(message, value);
+}
+
+/**
+ * Drop every cached derivation of `message` after an in-place rewrite. Owners of
+ * mutation (prune, shake, strip-images) call this at the mutation seam so the
+ * next convert/estimate pass recomputes from the new content.
+ */
+export function invalidateMessageCache(message: AgentMessage): void {
+	estimateCacheDefault.delete(message);
+	estimateCacheFloored.delete(message);
+	for (const invalidate of externalInvalidators) invalidate(message);
+}

package/src/compaction/messages.ts

@@ -0,0 +1,241 @@
+import type {
+	ImageContent,
+	Message,
+	MessageAttribution,
+	ProviderPayload,
+	TextContent,
+	ToolResultMessage,
+} from "@linxiraos/pi-ai";
+import { prompt } from "@linxiraos/pi-utils";
+import type { AgentMessage } from "../types";
+import branchSummaryContextPrompt from "./prompts/branch-summary-context.md" with { type: "text" };
+import compactionSummaryContextPrompt from "./prompts/compaction-summary-context.md" with { type: "text" };
+
+const COMPACTION_SUMMARY_TEMPLATE = compactionSummaryContextPrompt;
+const BRANCH_SUMMARY_TEMPLATE = branchSummaryContextPrompt;
+
+export interface CustomMessage<T = unknown> {
+	role: "custom";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	display: boolean;
+	details?: T;
+	/** Who initiated this message for billing/attribution semantics. */
+	attribution?: MessageAttribution;
+	timestamp: number;
+}
+
+/** Legacy hook message type (pre-extensions). Kept for session migration. */
+export interface HookMessage<T = unknown> {
+	role: "hookMessage";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	display: boolean;
+	details?: T;
+	/** Who initiated this message for billing/attribution semantics. */
+	attribution?: MessageAttribution;
+	timestamp: number;
+}
+
+export interface BranchSummaryMessage {
+	role: "branchSummary";
+	summary: string;
+	fromId: string;
+	timestamp: number;
+}
+
+export interface CompactionSummaryMessage {
+	role: "compactionSummary";
+	summary: string;
+	shortSummary?: string;
+	tokensBefore: number;
+	providerPayload?: ProviderPayload;
+	/** Runtime-only ordered archive blocks for snapcompact: old text region,
+	 *  imaged middle, then new text region. When present, `summary` is already
+	 *  the final lead-in text (no legacy wrapper applied). */
+	blocks?: (TextContent | ImageContent)[];
+	/** Snapcompact image blocks, kept for display counts / legacy consumers. */
+	images?: ImageContent[];
+	/** Post-pass dead-end warning attached to this compaction (progress guard). */
+	warning?: string;
+	timestamp: number;
+}
+
+export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
+
+declare module "../types" {
+	interface CustomAgentMessages {
+		custom: CustomMessage;
+		hookMessage: HookMessage;
+		branchSummary: BranchSummaryMessage;
+		compactionSummary: CompactionSummaryMessage;
+	}
+}
+export type ConvertToLlm = (messages: AgentMessage[]) => Message[];
+
+function getPrunedToolResultContent(message: ToolResultMessage): (TextContent | ImageContent)[] {
+	if (message.prunedAt === undefined) {
+		return message.content;
+	}
+	const textBlocks = message.content.filter((content): content is TextContent => content.type === "text");
+	const text = textBlocks.map(block => block.text).join("") || "[Output truncated]";
+	return [{ type: "text", text }];
+}
+
+export function renderBranchSummaryContext(summary: string): string {
+	return prompt.render(BRANCH_SUMMARY_TEMPLATE, { summary });
+}
+
+export function renderCompactionSummaryContext(summary: string): string {
+	return prompt.render(COMPACTION_SUMMARY_TEMPLATE, { summary });
+}
+
+export function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage {
+	return {
+		role: "branchSummary",
+		summary,
+		fromId,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+export function createCompactionSummaryMessage(
+	summary: string,
+	tokensBefore: number,
+	timestamp: string,
+	shortSummary?: string,
+	providerPayload?: ProviderPayload,
+	images?: ImageContent[],
+	blocks?: (TextContent | ImageContent)[],
+	warning?: string,
+): CompactionSummaryMessage {
+	const imageBlocks =
+		blocks?.filter((block): block is ImageContent => block.type === "image") ??
+		(images && images.length > 0 ? images : undefined);
+	return {
+		role: "compactionSummary",
+		summary,
+		shortSummary,
+		tokensBefore,
+		providerPayload,
+		blocks: blocks && blocks.length > 0 ? blocks : undefined,
+		images: imageBlocks && imageBlocks.length > 0 ? imageBlocks : undefined,
+		warning,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+export function createCustomMessage(
+	customType: string,
+	content: string | (TextContent | ImageContent)[],
+	display: boolean,
+	details: unknown | undefined,
+	timestamp: string,
+	attribution?: MessageAttribution,
+): CustomMessage {
+	return {
+		role: "custom",
+		customType,
+		content,
+		display,
+		details,
+		attribution,
+		timestamp: new Date(timestamp).getTime(),
+	};
+}
+
+function isCoreCompactionMessage(message: AgentMessage): message is AgentMessage & CoreCompactionMessage {
+	return (
+		message.role === "custom" ||
+		message.role === "hookMessage" ||
+		message.role === "branchSummary" ||
+		message.role === "compactionSummary"
+	);
+}
+
+/**
+ * Transform a single core-domain agent message to its LLM form; `undefined`
+ * drops it from the provider request.
+ *
+ * Single source of truth for the core roles (user/developer/assistant/
+ * toolResult) and the compaction messages owned by this package. Embedders
+ * with their own app messages (e.g. the coding agent) handle their custom
+ * roles and delegate every core role here — duplicating these cases is how
+ * snapcompact frames once silently fell off the provider request.
+ */
+export function convertMessageToLlm(message: AgentMessage): Message | undefined {
+	if (isCoreCompactionMessage(message)) {
+		switch (message.role) {
+			case "custom":
+			case "hookMessage": {
+				const content =
+					typeof message.content === "string"
+						? [{ type: "text" as const, text: message.content }]
+						: message.content;
+				return {
+					role: "developer",
+					content,
+					attribution: message.attribution,
+					timestamp: message.timestamp,
+				};
+			}
+			case "branchSummary":
+				return {
+					role: "user",
+					content: [
+						{
+							type: "text" as const,
+							text: renderBranchSummaryContext(message.summary),
+						},
+					],
+					attribution: "agent",
+					timestamp: message.timestamp,
+				};
+			case "compactionSummary":
+				return {
+					role: "user",
+					content:
+						message.blocks !== undefined
+							? [{ type: "text" as const, text: message.summary }, ...message.blocks]
+							: [
+									{
+										type: "text" as const,
+										text: renderCompactionSummaryContext(message.summary),
+									},
+									...(message.images ?? []),
+								],
+					attribution: "agent",
+					providerPayload: message.providerPayload,
+					timestamp: message.timestamp,
+				};
+		}
+	}
+
+	switch (message.role) {
+		case "user":
+			return { ...message, attribution: message.attribution ?? "user" };
+		case "developer":
+			return { ...message, attribution: message.attribution ?? "agent" };
+		case "assistant":
+			return message;
+		case "toolResult":
+			return {
+				...message,
+				content: getPrunedToolResultContent(message as ToolResultMessage),
+				attribution: message.attribution ?? "agent",
+			};
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Default compaction-domain transformer.
+ *
+ * Embedders with their own app messages should pass a richer transformer through
+ * `SummaryOptions.convertToLlm`; this default intentionally preserves only the
+ * core LLM roles and the compaction messages owned by this package.
+ */
+export function defaultConvertToLlm(messages: AgentMessage[]): Message[] {
+	return messages.map(convertMessageToLlm).filter(message => message !== undefined);
+}