@prometheus-ai/agent-core 0.5.0

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,99 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+
+import type { ToolResultMessage } from "@prometheus-ai/ai";
+import type { AgentMessage } from "../types";
+import { estimateTokens } from "./compaction";
+import type { SessionEntry, SessionMessageEntry } from "./entries";
+import {
+	collectToolCallsById,
+	isProtectedToolResult,
+	isSkillReadToolResult,
+	type ProtectedToolMatcher,
+} from "./tool-protection";
+
+export interface PruneConfig {
+	/** Keep the most recent tool output tokens intact. */
+	protectTokens: number;
+	/** Only prune if total savings meets this threshold. */
+	minimumSavings: number;
+	/** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+	protectedTools: ProtectedToolMatcher[];
+}
+
+export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
+	protectTokens: 40_000,
+	minimumSavings: 20_000,
+	protectedTools: ["skill", isSkillReadToolResult],
+};
+
+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 }> = [];
+	const toolCallsById = collectToolCallsById(entries);
+
+	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 = isProtectedToolResult(message, toolCallsById.get(message.toolCallId), config.protectedTools);
+
+		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/shake.ts

@@ -0,0 +1,406 @@
+/**
+ * Context-reducing surgical compaction ("shake").
+ *
+ * `shake` drops heavy content out of the live context mechanically: whole
+ * tool-call results and large fenced/XML blocks are replaced with short
+ * placeholders. This module is the pure layer — region detection and in-place
+ * mutation only. Artifact offload, persistence, and provider-session teardown
+ * are orchestrated by the caller (`AgentSession.shake`).
+ *
+ * Layering mirrors `pruning.ts`: no I/O here.
+ */
+
+import type { TextContent, ToolResultMessage } from "@prometheus-ai/ai";
+import { countTokens } from "@prometheus-ai/natives";
+import type { AgentMessage } from "../types";
+import { estimateTokens } from "./compaction";
+import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries";
+import {
+	collectToolCallsById,
+	isProtectedToolResult,
+	isSkillReadToolResult,
+	type ProtectedToolMatcher,
+} from "./tool-protection";
+
+export interface ShakeConfig {
+	/** Keep the most recent context tokens (across all entries) intact. */
+	protectTokens: number;
+	/** Only shake when total estimated savings meets this threshold. */
+	minSavings: number;
+	/** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+	protectedTools: ProtectedToolMatcher[];
+	/** Minimum token size for a fenced/XML block to be eligible. */
+	fenceMinTokens: number;
+}
+
+/** Auto-shake config: protects the live tail, conservative thresholds. */
+export const DEFAULT_SHAKE_CONFIG: ShakeConfig = {
+	protectTokens: 16_000,
+	minSavings: 4_000,
+	protectedTools: ["skill", isSkillReadToolResult],
+	fenceMinTokens: 400,
+};
+
+/** Manual `/shake`: aggressive — drops every eligible region across history. */
+export const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig = {
+	protectTokens: 0,
+	minSavings: 0,
+	protectedTools: ["skill", isSkillReadToolResult],
+	fenceMinTokens: 400,
+};
+
+/** Rough token cost of a placeholder line; used only for the savings gate. */
+const PLACEHOLDER_TOKEN_ESTIMATE = 16;
+
+/** A located eligible region. */
+export interface ToolResultShakeRegion {
+	kind: "toolResult";
+	entry: SessionMessageEntry;
+	tokens: number;
+	originalText: string;
+	/** Human label for the offload doc (tool name). */
+	label: string;
+}
+
+export interface BlockShakeRegion {
+	kind: "block";
+	entry: SessionMessageEntry | CustomMessageEntry;
+	/** Index into the content array, or -1 for string-form content. */
+	blockIndex: number;
+	/** Character offsets into the target text (start inclusive, end exclusive). */
+	start: number;
+	end: number;
+	tokens: number;
+	originalText: string;
+	/** Human label for the offload doc (role / customType). */
+	label: string;
+}
+
+export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
+
+// Mirror prompt.ts top-level XML detection. Lowercase tag names only —
+// conservative by design (uppercase / mixed-case tags are ignored).
+const OPENING_XML = /^<([a-z_-]+)(?:\s+[^>]*)?>$/;
+const CLOSING_XML = /^<\/([a-z_-]+)>$/;
+
+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 toolResultText(message: ToolResultMessage): string {
+	return message.content
+		.filter((block): block is TextContent => block.type === "text")
+		.map(block => block.text)
+		.join("\n");
+}
+
+/** Estimate the token contribution of an entry for the protect-recent window. */
+function entryTokens(entry: SessionEntry): number {
+	if (entry.type === "message") {
+		return estimateTokens(entry.message);
+	}
+	if (entry.type === "custom_message") {
+		const content = entry.content;
+		if (typeof content === "string") return content.length === 0 ? 0 : countTokens(content);
+		const fragments = content.filter((block): block is TextContent => block.type === "text").map(block => block.text);
+		return fragments.length === 0 ? 0 : countTokens(fragments);
+	}
+	return 0;
+}
+
+/**
+ * Locate fenced code blocks and top-level XML element spans inside `text`.
+ * Returns character ranges `[start, end)` covering the full block (including the
+ * opening and closing fence/tag lines, excluding the trailing newline).
+ *
+ * Conservative: unterminated fences/tags yield no range, and XML detection is
+ * suppressed inside fences. Mirrors the toggling logic in
+ * `@prometheus-ai/utils` `format()` so behavior stays aligned with prompt rendering.
+ */
+function scanTextForBlockRanges(text: string): Array<{ start: number; end: number }> {
+	const ranges: Array<{ start: number; end: number }> = [];
+	let inFence = false;
+	let fenceStart = -1;
+	const tagStack: string[] = [];
+	let xmlStart = -1;
+
+	let lineStart = 0;
+	for (let i = 0; i <= text.length; i++) {
+		if (i !== text.length && text[i] !== "\n") continue;
+		const line = text.slice(lineStart, i);
+		const lineEnd = i; // offset of the newline (or end of text); excludes the "\n"
+		const trimmedStart = line.trimStart();
+
+		const isFenceLine = trimmedStart.startsWith("```") || trimmedStart.startsWith("~~~");
+		if (isFenceLine) {
+			if (!inFence) {
+				inFence = true;
+				fenceStart = lineStart;
+			} else {
+				inFence = false;
+				ranges.push({ start: fenceStart, end: lineEnd });
+				fenceStart = -1;
+			}
+			lineStart = i + 1;
+			continue;
+		}
+
+		if (!inFence) {
+			const isOpeningXml = line.length === trimmedStart.length && OPENING_XML.test(trimmedStart);
+			if (isOpeningXml) {
+				const match = OPENING_XML.exec(trimmedStart);
+				if (match) {
+					if (tagStack.length === 0) xmlStart = lineStart;
+					tagStack.push(match[1]);
+				}
+			} else {
+				const closingMatch = CLOSING_XML.exec(trimmedStart);
+				if (closingMatch && tagStack.length > 0 && tagStack[tagStack.length - 1] === closingMatch[1]) {
+					tagStack.pop();
+					if (tagStack.length === 0 && xmlStart >= 0) {
+						ranges.push({ start: xmlStart, end: lineEnd });
+						xmlStart = -1;
+					}
+				}
+			}
+		}
+
+		lineStart = i + 1;
+	}
+
+	return mergeRanges(ranges);
+}
+
+/**
+ * Sort ascending by start and drop any range that overlaps an already-kept
+ * range. Because fence/XML spans are always properly nested (XML detection is
+ * suppressed inside fences), overlap means containment — keeping the
+ * earlier-starting range keeps the outermost span.
+ */
+function mergeRanges(ranges: Array<{ start: number; end: number }>): Array<{ start: number; end: number }> {
+	if (ranges.length <= 1) return ranges;
+	const sorted = [...ranges].sort((a, b) => a.start - b.start);
+	const kept: Array<{ start: number; end: number }> = [];
+	let lastEnd = -1;
+	for (const range of sorted) {
+		if (range.start < lastEnd) continue;
+		kept.push(range);
+		lastEnd = range.end;
+	}
+	return kept;
+}
+
+function pushBlockRegions(
+	entry: SessionMessageEntry | CustomMessageEntry,
+	blockIndex: number,
+	text: string,
+	config: ShakeConfig,
+	label: string,
+	out: ShakeRegion[],
+): void {
+	for (const range of scanTextForBlockRanges(text)) {
+		const slice = text.slice(range.start, range.end);
+		if (slice.length === 0) continue;
+		const tokens = countTokens(slice);
+		if (tokens < config.fenceMinTokens) continue;
+		out.push({
+			kind: "block",
+			entry,
+			blockIndex,
+			start: range.start,
+			end: range.end,
+			tokens,
+			originalText: slice,
+			label,
+		});
+	}
+}
+
+function collectBlockRegions(
+	entry: SessionMessageEntry | CustomMessageEntry,
+	config: ShakeConfig,
+	out: ShakeRegion[],
+): void {
+	if (entry.type === "message") {
+		const message = entry.message;
+		if (message.role === "assistant") {
+			for (let bi = 0; bi < message.content.length; bi++) {
+				const block = message.content[bi];
+				if (block.type === "text") pushBlockRegions(entry, bi, block.text, config, "assistant", out);
+			}
+			return;
+		}
+		if (message.role === "user" || message.role === "developer") {
+			scanContentBlocks(entry, message.content, config, message.role, out);
+		}
+		return;
+	}
+	// custom_message
+	scanContentBlocks(entry, entry.content, config, entry.customType, out);
+}
+
+function scanContentBlocks(
+	entry: SessionMessageEntry | CustomMessageEntry,
+	content: string | Array<{ type: string; text?: string }>,
+	config: ShakeConfig,
+	label: string,
+	out: ShakeRegion[],
+): void {
+	if (typeof content === "string") {
+		pushBlockRegions(entry, -1, content, config, label, out);
+		return;
+	}
+	for (let bi = 0; bi < content.length; bi++) {
+		const block = content[bi];
+		if (block.type === "text" && typeof block.text === "string") {
+			pushBlockRegions(entry, bi, block.text, config, label, out);
+		}
+	}
+}
+
+/**
+ * Pure detection: locate every eligible shake region on a branch.
+ *
+ * Walks the protect-recent window (most recent `protectTokens` of context is
+ * kept intact), collects whole tool-result messages (honoring `protectedTools`
+ * and skipping already-pruned results) and large fenced/XML blocks inside
+ * user/developer/assistant/custom messages. Returns regions in document order.
+ *
+ * `toolCall` blocks are never touched (tool-call/result pairing is preserved)
+ * and regions never span a message boundary. When the combined estimated
+ * savings is below `minSavings`, returns `[]` (no-op).
+ */
+export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[] {
+	const n = entries.length;
+	if (n === 0) return [];
+
+	// Tokens of all entries strictly more recent than index i.
+	const accumulatedAfter = new Array<number>(n);
+	let acc = 0;
+	for (let i = n - 1; i >= 0; i--) {
+		accumulatedAfter[i] = acc;
+		acc += entryTokens(entries[i]);
+	}
+
+	const toolCallsById = collectToolCallsById(entries);
+
+	const regions: ShakeRegion[] = [];
+	for (let i = 0; i < n; i++) {
+		if (accumulatedAfter[i] < config.protectTokens) continue;
+		const entry = entries[i];
+
+		const toolResult = getToolResultMessage(entry);
+		if (toolResult) {
+			if (toolResult.prunedAt !== undefined) continue;
+			if (isProtectedToolResult(toolResult, toolCallsById.get(toolResult.toolCallId), config.protectedTools))
+				continue;
+			const text = toolResultText(toolResult);
+			if (text.length === 0) continue;
+			regions.push({
+				kind: "toolResult",
+				entry: entry as SessionMessageEntry,
+				tokens: estimateTokens(toolResult as AgentMessage),
+				originalText: text,
+				label: toolResult.toolName,
+			});
+			continue;
+		}
+
+		if (entry.type === "message" || entry.type === "custom_message") {
+			collectBlockRegions(entry as SessionMessageEntry | CustomMessageEntry, config, regions);
+		}
+	}
+
+	let savings = 0;
+	for (const region of regions) savings += Math.max(0, region.tokens - PLACEHOLDER_TOKEN_ESTIMATE);
+	if (savings < config.minSavings) return [];
+
+	return regions;
+}
+
+interface TextSlot {
+	read(): string;
+	write(value: string): void;
+}
+
+function getBlockTextSlot(entry: SessionMessageEntry | CustomMessageEntry, blockIndex: number): TextSlot | undefined {
+	if (entry.type === "message") {
+		const message = entry.message as { content: unknown };
+		if (blockIndex === -1) {
+			if (typeof message.content !== "string") return undefined;
+			return {
+				read: () => message.content as string,
+				write: value => {
+					message.content = value;
+				},
+			};
+		}
+		if (!Array.isArray(message.content)) return undefined;
+		const block = message.content[blockIndex] as TextContent | undefined;
+		if (block?.type !== "text") return undefined;
+		return {
+			read: () => block.text,
+			write: value => {
+				block.text = value;
+			},
+		};
+	}
+	// custom_message
+	if (blockIndex === -1) {
+		if (typeof entry.content !== "string") return undefined;
+		return {
+			read: () => entry.content as string,
+			write: value => {
+				entry.content = value;
+			},
+		};
+	}
+	if (!Array.isArray(entry.content)) return undefined;
+	const block = entry.content[blockIndex] as TextContent | undefined;
+	if (block?.type !== "text") return undefined;
+	return {
+		read: () => block.text,
+		write: value => {
+			block.text = value;
+		},
+	};
+}
+
+/**
+ * Pure mutation: replace a single region's content in place.
+ *
+ * Tool-result: replaces the message content with the placeholder text and
+ * stamps `prunedAt`. Block: splices `replacement` over `[start, end)` of the
+ * target text block. When several block regions share one text block they MUST
+ * be applied highest-start-first so earlier offsets stay valid — use
+ * {@link applyShakeRegions}, which orders them correctly.
+ */
+export function applyShakeRegion(region: ShakeRegion, replacement: string): void {
+	if (region.kind === "toolResult") {
+		const message = region.entry.message as ToolResultMessage;
+		message.content = [{ type: "text", text: replacement }];
+		message.prunedAt = Date.now();
+		return;
+	}
+	const slot = getBlockTextSlot(region.entry, region.blockIndex);
+	if (!slot) return;
+	const text = slot.read();
+	slot.write(text.slice(0, region.start) + replacement + text.slice(region.end));
+}
+
+/**
+ * Apply many regions at once. Block regions are applied highest-start-first so
+ * that splicing one region never shifts the offsets of another in the same text
+ * block; tool-result regions are independent.
+ */
+export function applyShakeRegions(items: Array<{ region: ShakeRegion; replacement: string }>): void {
+	const ordered = [...items].sort((a, b) => {
+		const aStart = a.region.kind === "block" ? a.region.start : -1;
+		const bStart = b.region.kind === "block" ? b.region.start : -1;
+		return bStart - aStart;
+	});
+	for (const { region, replacement } of ordered) applyShakeRegion(region, replacement);
+}

package/src/compaction/tool-protection.ts

@@ -0,0 +1,55 @@
+import type { ToolResultMessage } from "@prometheus-ai/ai";
+import type { AgentToolCall } from "../types";
+import type { SessionEntry } from "./entries";
+
+export interface ProtectedToolContext {
+	readonly toolResult: ToolResultMessage;
+	readonly toolCall: AgentToolCall | undefined;
+}
+
+export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) => boolean);
+
+const SKILL_INTERNAL_URL_PREFIX = "skill://";
+
+export function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall> {
+	const toolCalls = new Map<string, AgentToolCall>();
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (message.role !== "assistant") continue;
+		for (const block of message.content) {
+			if (block.type === "toolCall") toolCalls.set(block.id, block);
+		}
+	}
+	return toolCalls;
+}
+
+/**
+ * Extract the `path` argument from a paired `read` tool call, when the result
+ * is a `read` result carrying a string path. Returns `undefined` otherwise.
+ * Shared primitive for read-targeted protection matchers (skills, plans, …).
+ */
+export function getReadToolPath({ toolResult, toolCall }: ProtectedToolContext): string | undefined {
+	if (toolResult.toolName !== "read" || toolCall?.name !== "read") return undefined;
+	const path = (toolCall.arguments as Record<string, unknown>).path;
+	return typeof path === "string" ? path : undefined;
+}
+
+export function isSkillReadToolResult(context: ProtectedToolContext): boolean {
+	return getReadToolPath(context)?.startsWith(SKILL_INTERNAL_URL_PREFIX) ?? false;
+}
+
+export function isProtectedToolResult(
+	toolResult: ToolResultMessage,
+	toolCall: AgentToolCall | undefined,
+	matchers: readonly ProtectedToolMatcher[],
+): boolean {
+	for (const matcher of matchers) {
+		if (typeof matcher === "string") {
+			if (toolResult.toolName === matcher) return true;
+			continue;
+		}
+		if (matcher({ toolResult, toolCall })) return true;
+	}
+	return false;
+}