@gajae-code/agent-core 0.1.1

package/src/compaction/prompts/compaction-update-summary.md

@@ -0,0 +1,45 @@
+You MUST incorporate new messages above into the existing handoff summary in <previous-summary> tags, used by another LLM to resume task.
+RULES:
+- MUST preserve all information from previous summary
+- MUST add new progress, decisions, and context from new messages
+- MUST update Progress: move items from "In Progress" to "Done" when completed
+- MUST update "Next Steps" based on what was accomplished
+- MUST preserve exact file paths, function names, and error messages
+- You MAY remove anything no longer relevant
+
+IMPORTANT: If new messages end with unanswered question or request to user, you MUST add it to Critical Context (replacing any previous pending question if answered).
+
+You MUST use this format (omit sections if not applicable):
+
+## Goal
+[Preserve existing goals; add new ones if task expanded]
+
+## Constraints & Preferences
+- [Preserve existing; add new ones discovered]
+
+## Progress
+
+### Done
+- [x] [Include previously done and newly completed items]
+
+### In Progress
+- [ ] [Current work—update based on progress]
+
+### Blocked
+- [Current blockers—remove if resolved]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale] (preserve all previous, add new)
+
+## Next Steps
+1. [Update based on current state]
+
+## Critical Context
+- [Preserve important context; add new if needed]
+
+## Additional Notes
+[Other important info not fitting above]
+
+You MUST output only the structured summary; you NEVER include extra text.
+
+Sections MUST be kept concise. You MUST preserve relevant tool outputs/command results. You MUST include repository state changes (branch, uncommitted changes) if mentioned.

package/src/compaction/prompts/file-operations.md

@@ -0,0 +1,10 @@
+{{#if readFiles.length}}
+{{#xml "read-files"}}
+{{join readFiles "\n"}}
+{{/xml}}
+{{/if}}
+{{#if modifiedFiles.length}}
+{{#xml "modified-files"}}
+{{join modifiedFiles "\n"}}
+{{/xml}}
+{{/if}}

package/src/compaction/prompts/handoff-document.md

@@ -0,0 +1,49 @@
+<critical>
+Write a handoff document for another instance of yourself.
+The handoff MUST be sufficient for seamless continuation without access to this conversation.
+Output ONLY the handoff document. No preamble, no commentary, no wrapper text.
+</critical>
+
+<instruction>
+Capture exact technical state, not abstractions.
+- File paths, symbol names, commands run
+- Test results, observed failures
+- Decisions made
+- Partial work affecting the next step
+</instruction>
+
+<output>
+Use exactly this structure:
+
+## Goal
+[What the user is trying to accomplish]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks with specifics]
+
+### In Progress
+- [ ] [Current work if any]
+
+### Pending
+- [ ] [Tasks mentioned but not started]
+
+## Key Decisions
+- **[Decision]**: [Rationale]
+
+## Critical Context
+- Code snippets, file paths, function/type names, error messages, data essential to continue
+- Repository state if relevant
+
+## Next Steps
+1. [What should happen next]
+</output>
+
+{{#if additionalFocus}}
+<instruction>
+Additional focus: {{additionalFocus}}
+</instruction>
+{{/if}}

package/src/compaction/prompts/summarization-system.md

@@ -0,0 +1,3 @@
+Summarize conversations between users and AI coding assistants. Produce structured summaries in the exact specified format.
+
+Do NOT continue the conversation. Do NOT respond to questions in the conversation. Output ONLY the structured summary.

package/src/compaction/pruning.ts

@@ -0,0 +1,92 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+
+import type { ToolResultMessage } from "@gajae-code/ai";
+import type { AgentMessage } from "../types";
+import { estimateTokens } from "./compaction";
+import type { SessionEntry, SessionMessageEntry } from "./entries";
+
+export interface PruneConfig {
+	/** Keep the most recent tool output tokens intact. */
+	protectTokens: number;
+	/** Only prune if total savings meets this threshold. */
+	minimumSavings: number;
+	/** Tool names that should never be pruned. */
+	protectedTools: string[];
+}
+
+export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
+	protectTokens: 40_000,
+	minimumSavings: 20_000,
+	protectedTools: ["skill", "read"],
+};
+
+export interface PruneResult {
+	prunedCount: number;
+	tokensSaved: number;
+}
+
+function createPrunedNotice(tokens: number): string {
+	return `[Output truncated - ${tokens} tokens]`;
+}
+
+function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefined {
+	if (entry.type !== "message") return undefined;
+	const message = entry.message as AgentMessage;
+	if (message.role !== "toolResult") return undefined;
+	return message as ToolResultMessage;
+}
+
+function estimatePrunedSavings(tokens: number): number {
+	const noticeTokens = Math.ceil(createPrunedNotice(tokens).length / 4);
+	return Math.max(0, tokens - noticeTokens);
+}
+
+export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+	let accumulatedTokens = 0;
+	let tokensSaved = 0;
+	let prunedCount = 0;
+
+	const candidates: Array<{ entry: SessionMessageEntry; tokens: number }> = [];
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (!message) continue;
+
+		const tokens = estimateTokens(message as AgentMessage);
+		const isProtected = config.protectedTools.includes(message.toolName);
+
+		if (message.prunedAt !== undefined) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		if (accumulatedTokens < config.protectTokens || isProtected) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		candidates.push({ entry: entry as SessionMessageEntry, tokens });
+		accumulatedTokens += tokens;
+	}
+
+	for (const candidate of candidates) {
+		tokensSaved += estimatePrunedSavings(candidate.tokens);
+	}
+
+	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+		return { prunedCount: 0, tokensSaved: 0 };
+	}
+
+	const prunedAt = Date.now();
+	for (const candidate of candidates) {
+		const message = candidate.entry.message as ToolResultMessage;
+		message.content = [{ type: "text", text: createPrunedNotice(candidate.tokens) }];
+		message.prunedAt = prunedAt;
+		prunedCount++;
+	}
+
+	return { prunedCount, tokensSaved };
+}

package/src/compaction/utils.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+
+import type { Message } from "@gajae-code/ai";
+import { prompt } from "@gajae-code/utils";
+import type { AgentMessage } from "../types";
+import fileOperationsTemplate from "./prompts/file-operations.md" with { type: "text" };
+import summarizationSystemPrompt from "./prompts/summarization-system.md" with { type: "text" };
+
+// ============================================================================
+// File Operation Tracking
+// ============================================================================
+
+export interface FileOperations {
+	read: Set<string>;
+	written: Set<string>;
+	edited: Set<string>;
+}
+
+export function createFileOps(): FileOperations {
+	return {
+		read: new Set(),
+		written: new Set(),
+		edited: new Set(),
+	};
+}
+
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void {
+	if (message.role !== "assistant") return;
+	if (!("content" in message) || !Array.isArray(message.content)) return;
+
+	for (const block of message.content) {
+		if (typeof block !== "object" || block === null) continue;
+		if (!("type" in block) || block.type !== "toolCall") continue;
+		if (!("arguments" in block) || !("name" in block)) continue;
+
+		const args = block.arguments as Record<string, unknown> | undefined;
+		if (!args) continue;
+
+		const path = typeof args.path === "string" ? args.path : undefined;
+		if (!path) continue;
+
+		switch (block.name) {
+			case "read":
+				fileOps.read.add(path);
+				break;
+			case "write":
+				fileOps.written.add(path);
+				break;
+			case "edit":
+				fileOps.edited.add(path);
+				break;
+		}
+	}
+}
+
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[] } {
+	const modified = new Set([...fileOps.edited, ...fileOps.written]);
+	const readOnly = [...fileOps.read].filter(f => !modified.has(f)).sort();
+	const modifiedFiles = [...modified].sort();
+	return { readFiles: readOnly, modifiedFiles };
+}
+
+/**
+ * Format file operations as XML tags for summary.
+ */
+const FILE_OPERATION_SUMMARY_LIMIT = 20;
+
+function truncateFileList(files: string[]): string[] {
+	if (files.length <= FILE_OPERATION_SUMMARY_LIMIT) return files;
+	const omitted = files.length - FILE_OPERATION_SUMMARY_LIMIT;
+	return [...files.slice(0, FILE_OPERATION_SUMMARY_LIMIT), `… (${omitted} more files omitted)`];
+}
+
+function stripFileOperationTags(summary: string): string {
+	const withoutReadFiles = summary.replace(/<read-files>[\s\S]*?<\/read-files>\s*/g, "");
+	const withoutModifiedFiles = withoutReadFiles.replace(/<modified-files>[\s\S]*?<\/modified-files>\s*/g, "");
+	return withoutModifiedFiles.trimEnd();
+}
+export function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string {
+	if (readFiles.length === 0 && modifiedFiles.length === 0) return "";
+	return prompt.render(fileOperationsTemplate, {
+		readFiles: truncateFileList(readFiles),
+		modifiedFiles: truncateFileList(modifiedFiles),
+	});
+}
+
+export function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[]): string {
+	const baseSummary = stripFileOperationTags(summary);
+	const fileOperations = formatFileOperations(readFiles, modifiedFiles);
+	if (!fileOperations) return baseSummary;
+	if (!baseSummary) return fileOperations;
+	return `${baseSummary}\n\n${fileOperations}`;
+}
+
+// ============================================================================
+// Message Serialization
+// ============================================================================
+
+/** Maximum characters for a tool result in serialized summaries. */
+const TOOL_RESULT_MAX_CHARS = 2000;
+
+/**
+ * Truncate text to a maximum character length for summarization.
+ * Keeps the beginning and appends a truncation marker.
+ */
+function truncateForSummary(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	const truncatedChars = text.length - maxChars;
+	return `${text.slice(0, maxChars)}\n\n[... ${truncatedChars} more characters truncated]`;
+}
+
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ */
+export function serializeConversation(messages: Message[]): string {
+	const parts: string[] = [];
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			const content =
+				typeof msg.content === "string"
+					? msg.content
+					: msg.content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map(c => c.text)
+							.join("");
+			if (content) parts.push(`[User]: ${content}`);
+		} else if (msg.role === "assistant") {
+			const textParts: string[] = [];
+			const thinkingParts: string[] = [];
+			const toolCalls: string[] = [];
+
+			for (const block of msg.content) {
+				if (block.type === "text") {
+					textParts.push(block.text);
+				} else if (block.type === "thinking") {
+					thinkingParts.push(block.thinking);
+				} else if (block.type === "toolCall") {
+					const args = block.arguments as Record<string, unknown>;
+					const argsStr = Object.entries(args)
+						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+						.join(", ");
+					toolCalls.push(`${block.name}(${argsStr})`);
+				}
+			}
+
+			if (thinkingParts.length > 0) {
+				parts.push(`[Assistant thinking]: ${thinkingParts.join("\n")}`);
+			}
+			if (textParts.length > 0) {
+				parts.push(`[Assistant]: ${textParts.join("\n")}`);
+			}
+			if (toolCalls.length > 0) {
+				parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
+			}
+		} else if (msg.role === "toolResult") {
+			const content = msg.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map(c => c.text)
+				.join("");
+			if (content) {
+				parts.push(`[Tool result]: ${truncateForSummary(content, TOOL_RESULT_MAX_CHARS)}`);
+			}
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+// ============================================================================
+// Summarization System Prompt
+// ============================================================================
+
+export const SUMMARIZATION_SYSTEM_PROMPT = prompt.render(summarizationSystemPrompt);

package/src/compaction.ts

@@ -0,0 +1 @@
+export * from "./compaction/index";