@gajae-code/agent-core 0.1.1

package/src/compaction/entries.ts

@@ -0,0 +1,133 @@
+import type { ImageContent, MessageAttribution, ServiceTier, TextContent } from "@gajae-code/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: ServiceTier | 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 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
+	| 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,12 @@
+/**
+ * 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 "./utils";

package/src/compaction/messages.ts

@@ -0,0 +1,212 @@
+import type {
+	AssistantMessage,
+	ImageContent,
+	Message,
+	MessageAttribution,
+	ProviderPayload,
+	TextContent,
+	ToolResultMessage,
+} from "@gajae-code/ai";
+import { prompt } from "@gajae-code/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;
+	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,
+): CompactionSummaryMessage {
+	return {
+		role: "compactionSummary",
+		summary,
+		shortSummary,
+		tokensBefore,
+		providerPayload,
+		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"
+	);
+}
+
+/**
+ * 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((message): 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: "user",
+							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: [
+								{
+									type: "text" as const,
+									text: renderCompactionSummaryContext(message.summary),
+								},
+							],
+							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 as AssistantMessage;
+				case "toolResult":
+					return {
+						...message,
+						content: getPrunedToolResultContent(message as ToolResultMessage),
+						attribution: message.attribution ?? "agent",
+					};
+				default:
+					return undefined;
+			}
+		})
+		.filter(message => message !== undefined);
+}
+export const convertToLlm = defaultConvertToLlm;