jeopi-agent-core 16.2.13

package/src/compaction/entries.ts

@@ -0,0 +1,142 @@
+import type { ImageContent, MessageAttribution, ServiceTierByFamily, TextContent } from "jeopi-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;
+}
+
+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 MCPToolSelectionEntry extends SessionEntryBase {
+	type: "mcp_tool_selection";
+	/** MCP tool names selected for visibility in discovery mode. */
+	selectedToolNames: 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
+	| MCPToolSelectionEntry
+	| 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,31 @@
+/**
+ * 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 {
+	readonly name = "CompactionCancelledError" as const;
+
+	constructor(message = "Compaction cancelled") {
+		super(message);
+	}
+}
+
+/**
+ * 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,13 @@
+/**
+ * Compaction and summarization utilities.
+ */
+
+export * from "./branch-summarization";
+export * from "./compaction";
+export * from "./entries";
+export * from "./errors";
+export * from "./messages";
+export * from "./openai";
+export * from "./pruning";
+export * from "./shake";
+export * from "./utils";

package/src/compaction/messages.ts

@@ -0,0 +1,237 @@
+import type {
+	ImageContent,
+	Message,
+	MessageAttribution,
+	ProviderPayload,
+	TextContent,
+	ToolResultMessage,
+} from "jeopi-ai";
+import { prompt } from "jeopi-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[];
+	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)[],
+): 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,
+		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);
+}