jeopi-agent-core 16.2.13

package/src/compaction/prompts/compaction-turn-prefix.md

@@ -0,0 +1,17 @@
+This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
+
+You MUST summarize the prefix to provide context for the retained suffix:
+
+## Original Request
+
+[What did the user ask for in this turn?]
+
+## Early Progress
+- [Key decisions and work done in the prefix]
+
+## Context for Suffix
+- [Information needed to understand the retained recent work]
+
+You MUST output only the structured summary. You NEVER include extra text.
+
+You MUST be concise. You MUST preserve exact file paths, function names, error messages, and relevant tool outputs or command results if they appear. You MUST focus on what's needed to understand the kept suffix.

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

@@ -0,0 +1,45 @@
+You MUST incorporate the new messages above into the existing handoff summary in <previous-summary> tags, used by another LLM to resume the task.
+RULES:
+- MUST preserve all information from the 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 the new messages end with an unanswered question or request to the 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,5 @@
+{{#if files}}
+{{#xml "files"}}
+{{files}}
+{{/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/snapcompact-archive-context.md

@@ -0,0 +1,3 @@
+Previous snapcompact archive source text:
+
+{{archiveText}}

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.
+
+NEVER continue the conversation. NEVER respond to questions in it. Output ONLY the structured summary.

package/src/compaction/pruning.ts

@@ -0,0 +1,424 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+
+import type { ToolResultMessage } from "jeopi-ai";
+import type { AgentMessage, AgentToolCall } from "../types";
+import { estimateTokens } from "./compaction";
+import type { SessionEntry, SessionMessageEntry } from "./entries";
+import {
+	collectToolCallsById,
+	isProtectedToolResult,
+	isSkillReadToolResult,
+	type ProtectedToolMatcher,
+} from "./tool-protection";
+import { splitReadSelector } from "./utils";
+
+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[];
+	/**
+	 * Optional supersede key function (see {@link SupersedePruneConfig.supersedeKey}).
+	 * When provided, superseded tool results are pruned first — even inside the
+	 * `protectTokens` window — before age-based victims. Absent, behavior is
+	 * unchanged.
+	 */
+	supersedeKey?: SupersedeKeyFn;
+	/** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
+	pruneUseless?: boolean;
+	/**
+	 * Compaction boundary: the `firstKeptEntryId` of the latest compaction on
+	 * the branch. Entries at indices BEFORE this id are summarized away and never
+	 * sent to the model, so mutating them only churns persisted history without
+	 * shrinking the prompt — they are skipped. Undefined = no compaction (the
+	 * whole branch is sent).
+	 */
+	keepBoundaryId?: string;
+	/**
+	 * Prompt-cache guard. When set, a tool result whose all-message suffix
+	 * (tokens of every message after it) EXCEEDS this is part of the warm,
+	 * already-sent cache prefix: mutating it forces the provider to re-write the
+	 * whole suffix (cacheWrite premium). Such results — including superseded and
+	 * useless ones, which otherwise bypass {@link protectTokens} — are left for
+	 * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+	 * no cache guard (legacy: superseded/useless prune at any depth).
+	 */
+	cacheWarmSuffixTokens?: number;
+}
+
+export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
+	protectTokens: 40_000,
+	minimumSavings: 20_000,
+	protectedTools: ["skill", isSkillReadToolResult],
+	pruneUseless: true,
+};
+
+export interface PruneResult {
+	prunedCount: number;
+	tokensSaved: number;
+}
+
+/** Exact placeholder written over a superseded tool result. */
+export const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
+
+/** Exact placeholder written over an elided useless tool result. */
+export const USELESS_NOTICE = "[Uneventful result elided]";
+
+/**
+ * Maps a tool call to a supersede key. Results sharing a key form a group in
+ * which every result except the newest is a supersede candidate. A key `K`
+ * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
+ * supersedes selector-carrying reads of the same base path). Return
+ * `undefined` to exempt a call from supersede grouping.
+ */
+export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
+
+export interface SupersedePruneConfig {
+	/** Supersede key function; results sharing a key supersede older ones. */
+	supersedeKey?: SupersedeKeyFn;
+	/** Also prune results flagged useless by their tool. Default false. */
+	pruneUseless?: boolean;
+	/** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+	suffixTokenLimit?: number;
+	/**
+	 * Prune all candidates when the last message is at least this old: the
+	 * provider prompt cache is then cold, so re-writing it is free. MUST exceed
+	 * the cache retention (Anthropic "long" = 1h) or a still-warm prefix is busted
+	 * by the flush. Default 30 min — callers on long retention override it.
+	 */
+	idleFlushMs?: number;
+	/** Clock override for tests. */
+	now?: number;
+	/**
+	 * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+	 * before it are summarized away and never sent, so they are skipped in every
+	 * path — including the idle flush — to avoid pointless history churn.
+	 * Undefined = no compaction (the whole branch is sent).
+	 */
+	keepBoundaryId?: string;
+	/** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
+	protectedTools: ProtectedToolMatcher[];
+}
+
+const DEFAULT_SUFFIX_TOKEN_LIMIT = 8_000;
+const DEFAULT_IDLE_FLUSH_MS = 30 * 60_000;
+
+function createPrunedNotice(tokens: number): string {
+	return `[Output truncated - ${tokens} tokens]`;
+}
+
+/**
+ * Generic age-based pruning floor. Below this, blanking a result to
+ * `[Output truncated - N tokens]` recovers nothing — the placeholder itself
+ * costs ~8 tokens, so a sub-floor result grows the context (and churns the
+ * prompt cache) instead of shrinking it. Superseded/useless results keep their
+ * own rules: useless already drops no-savings candidates, superseded prunes for
+ * correctness regardless of size.
+ */
+const MIN_PRUNE_TOKENS = 50;
+
+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, notice: string): number {
+	const noticeTokens = Math.ceil(notice.length / 4);
+	return Math.max(0, tokens - noticeTokens);
+}
+
+/**
+ * For each entry index, the estimated token total of all *message* entries
+ * strictly after it — how much prompt-cache content the provider must re-write
+ * (cacheWrite premium) if that entry is mutated in place. Used to keep prune
+ * mutations inside the cheap-to-recache tail.
+ */
+function computeMessageSuffixTokens(entries: readonly SessionEntry[]): number[] {
+	const suffix = new Array<number>(entries.length);
+	let accumulated = 0;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		suffix[i] = accumulated;
+		const entry = entries[i];
+		if (entry.type === "message") accumulated += estimateTokens(entry.message as AgentMessage);
+	}
+	return suffix;
+}
+
+/**
+ * Resolve the array index of the compaction boundary (`keepBoundaryId`). Entries
+ * before this index are summarized away by the latest compaction and never sent,
+ * so prune passes must not mutate them. Returns 0 when there is no boundary (no
+ * compaction → whole branch is sent) or the id is absent from `entries`.
+ */
+function resolveBoundaryIndex(entries: readonly SessionEntry[], keepBoundaryId: string | undefined): number {
+	if (keepBoundaryId === undefined) return 0;
+	const index = entries.findIndex(entry => entry.id === keepBoundaryId);
+	return index < 0 ? 0 : index;
+}
+
+interface SupersedeCandidate {
+	entry: SessionMessageEntry;
+	message: ToolResultMessage;
+	/** Index of the entry within the `entries` array. */
+	index: number;
+	tokens: number;
+	/** Placeholder text written over the blanked result. */
+	notice: string;
+}
+
+/**
+ * Collect superseded tool results: for every unpruned, unprotected tool result
+ * whose paired call resolves a supersede key, a LATER result with the same key
+ * — or with a key that is the `"\u0000"`-prefix parent of this one — marks it
+ * superseded. Returned in message order.
+ */
+function collectSupersededResults(
+	entries: readonly SessionEntry[],
+	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	supersedeKey: SupersedeKeyFn,
+	protectedTools: readonly ProtectedToolMatcher[],
+): SupersedeCandidate[] {
+	const candidates: SupersedeCandidate[] = [];
+	const seenKeys = new Set<string>();
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (!message || message.prunedAt !== undefined) continue;
+		const toolCall = toolCallsById.get(message.toolCallId);
+		if (!toolCall) continue;
+		if (isProtectedToolResult(message, toolCall, protectedTools)) continue;
+		const key = supersedeKey(toolCall.name, toolCall.arguments as Record<string, unknown>);
+		if (key === undefined) continue;
+		const separator = key.indexOf("\u0000");
+		const superseded = seenKeys.has(key) || (separator >= 0 && seenKeys.has(key.slice(0, separator)));
+		seenKeys.add(key);
+		if (!superseded) continue;
+		candidates.push({
+			entry: entry as SessionMessageEntry,
+			message,
+			index: i,
+			tokens: estimateTokens(message as AgentMessage),
+			notice: SUPERSEDED_NOTICE,
+		});
+	}
+	return candidates.reverse();
+}
+
+/**
+ * Collect tool results their tool flagged contextually useless (zero matches,
+ * elapsed wait): unpruned, non-error, unprotected, not in `exclude`, and large
+ * enough that blanking to {@link USELESS_NOTICE} actually saves tokens.
+ * Returned in message order.
+ */
+function collectUselessResults(
+	entries: readonly SessionEntry[],
+	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	protectedTools: readonly ProtectedToolMatcher[],
+	exclude: ReadonlySet<ToolResultMessage>,
+): SupersedeCandidate[] {
+	const candidates: SupersedeCandidate[] = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (message?.useless !== true || message.prunedAt !== undefined || message.isError === true) continue;
+		if (exclude.has(message)) continue;
+		if (isProtectedToolResult(message, toolCallsById.get(message.toolCallId), protectedTools)) continue;
+		const tokens = estimateTokens(message as AgentMessage);
+		if (estimatePrunedSavings(tokens, USELESS_NOTICE) <= 0) continue;
+		candidates.push({ entry: entry as SessionMessageEntry, message, index: i, tokens, notice: USELESS_NOTICE });
+	}
+	return candidates;
+}
+
+/**
+ * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
+ * read of the same file) and, when `pruneUseless` is set, results their tool
+ * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
+ * candidate is pruned now only when the suffix after it is small (tail case —
+ * the read→edit→read loop) or when the context has been idle long enough that
+ * the provider cache is cold anyway (then all still-sent candidates flush).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ */
+export function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult {
+	const toolCallsById = collectToolCallsById(entries);
+	const candidates = config.supersedeKey
+		? collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools)
+		: [];
+	if (config.pruneUseless) {
+		const exclude = new Set(candidates.map(candidate => candidate.message));
+		candidates.push(...collectUselessResults(entries, toolCallsById, config.protectedTools, exclude));
+		candidates.sort((a, b) => a.index - b.index);
+	}
+	if (candidates.length === 0) return { prunedCount: 0, tokensSaved: 0 };
+
+	const now = config.now ?? Date.now();
+	let lastMessageTimestamp: number | undefined;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type !== "message") continue;
+		const timestamp = (entry.message as AgentMessage).timestamp;
+		if (typeof timestamp === "number") lastMessageTimestamp = timestamp;
+		break;
+	}
+	const idle =
+		lastMessageTimestamp !== undefined && now - lastMessageTimestamp >= (config.idleFlushMs ?? DEFAULT_IDLE_FLUSH_MS);
+
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+
+	let toPrune: SupersedeCandidate[];
+	if (idle) {
+		// Provider cache is cold (idle exceeds the retention TTL), so re-writing
+		// the sent region costs nothing. Entries before the compaction boundary
+		// are summarized away and never sent — skip them to avoid pointless churn.
+		toPrune = candidates.filter(candidate => candidate.index >= boundaryIndex);
+	} else {
+		const suffixTokenLimit = config.suffixTokenLimit ?? DEFAULT_SUFFIX_TOKEN_LIMIT;
+		// suffixTokens[i] = estimated tokens of all messages strictly after entry i.
+		// Mutating a candidate re-writes its suffix in the warm cache, so prune only
+		// when that suffix is small (cheap-to-recache tail) and the candidate sits
+		// at/after the compaction boundary.
+		const suffixTokens = computeMessageSuffixTokens(entries);
+		toPrune = candidates.filter(
+			candidate => candidate.index >= boundaryIndex && suffixTokens[candidate.index] <= suffixTokenLimit,
+		);
+	}
+	if (toPrune.length === 0) return { prunedCount: 0, tokensSaved: 0 };
+
+	const prunedAt = Date.now();
+	let tokensSaved = 0;
+	for (const candidate of toPrune) {
+		candidate.message.content = [{ type: "text", text: candidate.notice }];
+		candidate.message.prunedAt = prunedAt;
+		tokensSaved += estimatePrunedSavings(candidate.tokens, candidate.notice);
+	}
+	return { prunedCount: toPrune.length, tokensSaved };
+}
+
+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; superseded: boolean; useless: boolean }> = [];
+	const toolCallsById = collectToolCallsById(entries);
+	const supersededMessages = config.supersedeKey
+		? new Set(
+				collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools).map(
+					candidate => candidate.message,
+				),
+			)
+		: undefined;
+	const uselessMessages =
+		config.pruneUseless !== false
+			? new Set(
+					collectUselessResults(
+						entries,
+						toolCallsById,
+						config.protectedTools,
+						supersededMessages ?? new Set(),
+					).map(candidate => candidate.message),
+				)
+			: undefined;
+
+	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
+	const cacheWarmSuffixTokens = config.cacheWarmSuffixTokens;
+	// All-message suffix per index, only when the cache guard is armed.
+	const messageSuffix = cacheWarmSuffixTokens === undefined ? undefined : computeMessageSuffixTokens(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;
+		}
+
+		// Prompt-cache guard: a result whose all-message suffix exceeds the
+		// warm-cache window sits in the already-sent cached prefix — mutating it
+		// re-writes the whole suffix (cacheWrite premium). Entries before the
+		// compaction boundary are summarized away (never sent). Both are skipped
+		// before any prune decision, so superseded/useless cannot reach a deep,
+		// still-cached copy; compaction/shake reclaim those when they rebuild.
+		const inWarmPrefix =
+			messageSuffix !== undefined && cacheWarmSuffixTokens !== undefined && messageSuffix[i] > cacheWarmSuffixTokens;
+		if (inWarmPrefix || i < boundaryIndex) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		// Superseded and useless results bypass the age-based protect window
+		// (a stale re-read copy, or a result the tool flagged as uninformative,
+		// is dead weight at any age) — but only within the cache-warm tail: the
+		// guard above already excluded deeper, still-cached copies.
+		const superseded = supersededMessages?.has(message) ?? false;
+		const useless = uselessMessages?.has(message) ?? false;
+		const tooSmall = tokens < MIN_PRUNE_TOKENS;
+		if (!superseded && !useless && (accumulatedTokens < config.protectTokens || isProtected || tooSmall)) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		candidates.push({ entry: entry as SessionMessageEntry, tokens, superseded, useless });
+		accumulatedTokens += tokens;
+	}
+
+	for (const candidate of candidates) {
+		tokensSaved += estimatePrunedSavings(
+			candidate.tokens,
+			candidate.superseded
+				? SUPERSEDED_NOTICE
+				: candidate.useless
+					? USELESS_NOTICE
+					: createPrunedNotice(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;
+		const notice = candidate.superseded
+			? SUPERSEDED_NOTICE
+			: candidate.useless
+				? USELESS_NOTICE
+				: createPrunedNotice(candidate.tokens);
+		message.content = [{ type: "text", text: notice }];
+		message.prunedAt = prunedAt;
+		prunedCount++;
+	}
+
+	return { prunedCount, tokensSaved };
+}
+
+/**
+ * Supersede key for the `read` tool: the file path with the trailing line/raw
+ * selector stripped (the read tool's own splitter grammar via
+ * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
+ * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
+ * Selector-free reads key on the bare path; selector-carrying reads key on
+ * `path + "\u0000" + selector`, so two reads collide only when the newer is
+ * selector-free or the selectors are identical (the pass's prefix rule lets a
+ * bare-path read supersede selector-carrying reads of the same file).
+ */
+export function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined {
+	if (toolName !== "read") return undefined;
+	const path = args.path;
+	if (typeof path !== "string" || path.length === 0) return undefined;
+	if (path.includes("://")) return undefined;
+	const { path: base, sel } = splitReadSelector(path);
+	return sel === undefined ? base : `${base}\u0000${sel}`;
+}