@sayknow-cli/agent-core 0.2.2

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,431 @@
+/**
+ * Tool output pruning utilities for compaction.
+ *
+ * Candidate selection is staleness-aware: tool results that have been
+ * superseded by a later result for the same target (same file read again,
+ * same search re-run) or invalidated by a later successful edit/write to a
+ * covered file are pruned in preference to merely-old results. Protect-window
+ * and minimum-savings hysteresis semantics are unchanged.
+ */
+
+import type { ToolCall, ToolResultMessage } from "@sayknow-cli/ai";
+import type { AgentMessage } from "../types";
+import { estimateEntryTokens } 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[];
+	/**
+	 * Tools in `protectedTools` whose protection is waived once the result is
+	 * superseded (a later result for the same target, or a later successful
+	 * edit/write to the covered file). The most recent result per target is
+	 * never considered superseded. Optional; defaults to none.
+	 */
+	staleOverridableTools?: string[];
+}
+
+export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
+	protectTokens: 40_000,
+	minimumSavings: 20_000,
+	protectedTools: ["skill", "read"],
+	staleOverridableTools: ["read"],
+};
+
+export interface PruneResult {
+	prunedCount: number;
+	tokensSaved: number;
+	/**
+	 * The mutated message entries. Callers whose entry source returns
+	 * materialized copies (not live references) must write these back into
+	 * their canonical store by id.
+	 */
+	prunedEntries: SessionMessageEntry[];
+}
+
+const DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER = 1.25;
+
+function createGenericPrunedNotice(tokens: number): string {
+	return `[Output truncated - ${tokens} tokens]`;
+}
+
+function firstTextContent(message: ToolResultMessage): string {
+	if (typeof message.content === "string") return message.content;
+	const block = message.content.find(part => part.type === "text");
+	return block?.type === "text" ? block.text : "";
+}
+
+function firstErrorLine(text: string): string | undefined {
+	return text
+		.split(/\r?\n/)
+		.find(line => /error|failed|exception|panic/i.test(line))
+		?.trim();
+}
+
+function truncateField(value: string, maxLength: number): string {
+	if (value.length <= maxLength) return value;
+	if (maxLength <= 1) return "…";
+	return `${value.slice(0, maxLength - 1)}…`;
+}
+
+function resultDigest(message: ToolResultMessage): string | undefined {
+	const toolName = message.toolName.toLowerCase();
+	const text = firstTextContent(message);
+	if (toolName === "bash") {
+		const details = message as { details?: { exitCode?: unknown } };
+		const exitCode =
+			typeof details.details?.exitCode === "number" ? details.details.exitCode : message.isError ? 1 : 0;
+		const tail = text.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? "";
+		const error = firstErrorLine(text);
+		return [`exit=${exitCode}`, tail ? `tail=${tail}` : undefined, error ? `error=${error}` : undefined]
+			.filter((part): part is string => part !== undefined)
+			.join("; ");
+	}
+	if (toolName === "search" || toolName === "grep") {
+		const match = text.match(/(\d+)\s+matches?/i) ?? text.match(/totalMatches["']?:\s*(\d+)/i);
+		const files = text.match(/(\d+)\s+files?/i) ?? text.match(/filesWithMatches["']?:\s*(\d+)/i);
+		const error = firstErrorLine(text);
+		return (
+			[
+				match ? `matches=${match[1]}` : undefined,
+				files ? `files=${files[1]}` : undefined,
+				error ? `error=${error}` : undefined,
+			]
+				.filter((part): part is string => part !== undefined)
+				.join("; ") || "search digest unavailable"
+		);
+	}
+	return undefined;
+}
+
+function createPrunedNotice(tokens: number, message?: ToolResultMessage): string {
+	const generic = createGenericPrunedNotice(tokens);
+	const digest = message ? resultDigest(message) : undefined;
+	if (!digest) return generic;
+	const genericTokens = Math.ceil(generic.length / 4);
+	const maxTokens = Math.max(genericTokens, Math.floor(genericTokens * DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER));
+	const prefix = `[Output truncated - ${tokens} tokens; `;
+	const suffix = "]";
+	const maxChars = Math.max(0, maxTokens * 4 - prefix.length - suffix.length);
+	return `${prefix}${truncateField(digest, maxChars)}${suffix}`;
+}
+
+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);
+}
+
+const EDIT_TOOL_NAMES = new Set(["edit", "write", "apply_patch", "ast_edit"]);
+
+/** Extract the file-path argument from a tool call, when the tool has one. */
+function toolCallPath(call: ToolCall): string | undefined {
+	const args = call.arguments;
+	const path = args.path ?? args.file_path ?? args.filePath;
+	return typeof path === "string" && path.length > 0 ? path : undefined;
+}
+
+/**
+ * `*** Add|Update|Delete File: <path>` headers open a hunk; `*** Move to:
+ * <path>` attaches a rename destination to the current hunk. Move
+ * destinations count as touched paths: a rename onto a file invalidates
+ * earlier reads of that destination.
+ */
+const APPLY_PATCH_HEADER = /^\*\*\* (?:((?:Add|Update|Delete) File)|(Move to)): (.+)$/gm;
+
+/**
+ * Paths touched by an edit-class tool call, grouped per hunk so a failed
+ * hunk can be excluded wholesale (its rename destination included). Most
+ * edit tools carry a single path argument; apply_patch envelopes carry an
+ * `input` string with per-file headers instead. The envelope shape can
+ * arrive under the custom `apply_patch` tool OR the regular `edit` tool
+ * (providers without custom-tool support fall back to the JSON function), so
+ * any edit-class call with a string `input` is parsed for headers.
+ */
+function editToolPathGroups(call: ToolCall): string[][] {
+	const path = toolCallPath(call);
+	if (path !== undefined) return [[path]];
+	const input = call.arguments.input;
+	if (typeof input !== "string") return [];
+	const groups: string[][] = [];
+	for (const match of input.matchAll(APPLY_PATCH_HEADER)) {
+		const headerPath = match[3]?.trim();
+		if (!headerPath) continue;
+		const isMoveTo = match[2] !== undefined;
+		if (isMoveTo && groups.length > 0) {
+			groups[groups.length - 1].push(headerPath);
+		} else {
+			groups.push([headerPath]);
+		}
+	}
+	return groups;
+}
+
+/**
+ * Trailing read selectors (`:50`, `:50-200`, `:50+150`, `:5-16,960-973`,
+ * `:raw`, `:conflicts`), possibly stacked (`:2-4:raw`). Stripped to resolve
+ * the underlying file for edit invalidation.
+ */
+const READ_SELECTOR_SUFFIX = /:(?:raw|conflicts|\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/;
+
+/** Base file path of a read target with any line/mode selectors stripped. */
+function readBasePath(path: string): string {
+	let base = path;
+	while (READ_SELECTOR_SUFFIX.test(base)) {
+		base = base.replace(READ_SELECTOR_SUFFIX, "");
+	}
+	return base;
+}
+
+/**
+ * Stable identity for "the same logical lookup": same tool re-targeting the
+ * same subject. A later result with the same key supersedes earlier ones.
+ * Keys are canonical JSON tuples so user-controlled text (patterns, paths)
+ * can never collide via delimiter ambiguity. Search keys include pagination
+ * (`skip`) and result-shaping flags (`i`, `gitignore`): a later page or a
+ * differently-shaped search complements earlier output, it does not replace it.
+ */
+function toolTargetKey(call: ToolCall): string | undefined {
+	const path = toolCallPath(call);
+	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
+	const pattern = call.arguments.pattern;
+	if (typeof pattern === "string" && pattern.length > 0) {
+		const paths = call.arguments.paths;
+		const pathList = Array.isArray(paths) ? paths.filter((p): p is string => typeof p === "string") : [];
+		const skip = typeof call.arguments.skip === "number" ? call.arguments.skip : 0;
+		const caseInsensitive = call.arguments.i === true;
+		const gitignore = call.arguments.gitignore !== false;
+		return JSON.stringify([call.name, "pattern", pattern, pathList, skip, caseInsensitive, gitignore]);
+	}
+	return undefined;
+}
+
+/**
+ * Files actually mutated according to a tool result's details. Used for
+ * AST-edit-shaped results (`ast_edit` direct-apply and the hidden `resolve`
+ * apply step), which report `{ applied: true, files: [...] }` — the resolve
+ * tool nests that payload under `details.sourceResultDetails`. Conservative:
+ * returns nothing unless the details explicitly mark the change as applied.
+ * Checked even on `isError` results: a stale-preview apply reports an error
+ * while still having mutated the listed files.
+ */
+function resultDetailFiles(message: ToolResultMessage): string[] {
+	const raw = message.details as { applied?: unknown; files?: unknown; sourceResultDetails?: unknown } | undefined;
+	const candidates = [raw, raw?.sourceResultDetails as { applied?: unknown; files?: unknown } | undefined];
+	for (const details of candidates) {
+		if (details?.applied === true && Array.isArray(details.files)) {
+			return details.files.filter((file): file is string => typeof file === "string" && file.length > 0);
+		}
+	}
+	return [];
+}
+
+/**
+ * Paths that FAILED in a per-file edit result (`details.perFileResults`) and
+ * were NOT mutated by any same-path entry. Multi-file apply_patch catches
+ * per-file failures and still returns a non-error result; a purely-failed
+ * path was not mutated and must not stale reads. But apply_patch can emit
+ * multiple entries for the same path (e.g. several hunks): if any same-path
+ * entry succeeded the file still mutated, so it must NOT be suppressed.
+ * Conservative: only an entry explicitly marked `isError === true` counts as
+ * a failure; anything else (including ambiguous/malformed entries) counts as
+ * a success and keeps the path out of the suppression set.
+ */
+function failedEditPaths(message: ToolResultMessage): Set<string> {
+	const details = message.details as { perFileResults?: unknown } | undefined;
+	const perFile = details?.perFileResults;
+	if (!Array.isArray(perFile)) return new Set();
+	const failed = new Set<string>();
+	const succeeded = new Set<string>();
+	for (const item of perFile) {
+		const entry = item as { path?: unknown; isError?: unknown };
+		if (typeof entry?.path !== "string") continue;
+		if (entry.isError === true) failed.add(entry.path);
+		else succeeded.add(entry.path);
+	}
+	// A path mutated if any same-path entry succeeded, even when another
+	// same-path entry failed; drop those from the suppression set.
+	for (const path of succeeded) failed.delete(path);
+	return failed;
+}
+
+/**
+ * Concrete file path a `read` result actually came from, when the tool
+ * reported one (`details.resolvedPath`). Suffix resolution can map a bare
+ * filename argument onto a different concrete path.
+ */
+function readResolvedPath(message: ToolResultMessage): string | undefined {
+	const details = message.details as { resolvedPath?: unknown } | undefined;
+	const resolved = details?.resolvedPath;
+	return typeof resolved === "string" && resolved.length > 0 ? resolved : undefined;
+}
+
+interface StalenessIndex {
+	/** Entry indices of toolResults superseded by a later same-target result or a later edit. */
+	staleResultIndices: Set<number>;
+}
+
+/**
+ * Build a staleness index over session entries (oldest -> newest):
+ * - a toolResult is stale when a later non-error toolResult shares its target key;
+ * - a `read` result is stale when a later non-error edit/write touches its file.
+ * The most recent result per target is never stale.
+ */
+function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
+	const callsById = new Map<string, ToolCall>();
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message as AgentMessage;
+		if (message.role !== "assistant") continue;
+		for (const content of message.content) {
+			if (content.type === "toolCall") callsById.set(content.id, content);
+		}
+	}
+
+	const lastResultIndexByKey = new Map<string, number>();
+	const resultMeta = new Map<number, { key?: string; call: ToolCall; message: ToolResultMessage }>();
+	const lastEditIndexByPath = new Map<string, number>();
+
+	for (let i = 0; i < entries.length; i++) {
+		const message = getToolResultMessage(entries[i]);
+		if (!message) continue;
+		const call = callsById.get(message.toolCallId);
+		if (!call) continue;
+
+		// AST edits mutate files when previews are applied via the hidden
+		// `resolve` tool; the call args carry globs, not concrete paths. Both
+		// tools report actually-touched files in result details. Collected
+		// BEFORE the error gate: a stale-preview apply reports an error while
+		// still having mutated the listed files.
+		if (call.name === "resolve" || call.name === "ast_edit") {
+			for (const editPath of resultDetailFiles(message)) {
+				lastEditIndexByPath.set(editPath, i);
+			}
+		}
+		if (message.isError) continue;
+
+		const key = toolTargetKey(call);
+		resultMeta.set(i, { key, call, message });
+		if (key !== undefined) lastResultIndexByKey.set(key, i);
+		if (EDIT_TOOL_NAMES.has(call.name)) {
+			// Per-file edit results record failures in details.perFileResults;
+			// a failed hunk mutated nothing, so exclude its whole path group
+			// (rename destination included) from touched paths.
+			const failed = failedEditPaths(message);
+			for (const group of editToolPathGroups(call)) {
+				if (group.some(groupPath => failed.has(groupPath))) continue;
+				for (const editPath of group) {
+					lastEditIndexByPath.set(editPath, i);
+				}
+			}
+		}
+	}
+
+	const staleResultIndices = new Set<number>();
+	for (const [index, meta] of resultMeta) {
+		if (meta.key !== undefined) {
+			const lastIndex = lastResultIndexByKey.get(meta.key);
+			if (lastIndex !== undefined && lastIndex > index) {
+				staleResultIndices.add(index);
+				continue;
+			}
+		}
+		if (meta.call.name === "read") {
+			// Check both the call argument (selectors stripped) and the resolved
+			// path from result details: suffix resolution can map a bare filename
+			// onto a different concrete path, and edits may use either form.
+			const lookupPaths = new Set<string>();
+			const argPath = toolCallPath(meta.call);
+			if (argPath !== undefined) lookupPaths.add(readBasePath(argPath));
+			const resolved = readResolvedPath(meta.message);
+			if (resolved !== undefined) lookupPaths.add(resolved);
+			for (const lookupPath of lookupPaths) {
+				const editIndex = lastEditIndexByPath.get(lookupPath);
+				if (editIndex !== undefined && editIndex > index) {
+					staleResultIndices.add(index);
+					break;
+				}
+			}
+		}
+	}
+
+	return { staleResultIndices };
+}
+
+export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+	let accumulatedTokens = 0;
+	let tokensSaved = 0;
+	let prunedCount = 0;
+
+	const { staleResultIndices } = buildStalenessIndex(entries);
+	const staleOverridable = new Set(config.staleOverridableTools ?? []);
+	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; notice: string; savings: number }> = [];
+
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (!message) continue;
+
+		const tokens = estimateEntryTokens(entry);
+		const isStale = staleResultIndices.has(i);
+		// Staleness waives protected-tool immunity for overridable tools
+		// (e.g. a superseded `read`); the most recent result per target is
+		// never stale, so the latest read of each file stays protected.
+		const isProtected =
+			config.protectedTools.includes(message.toolName) && !(isStale && staleOverridable.has(message.toolName));
+
+		if (message.prunedAt !== undefined) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		// Stale results are prunable even inside the recency protect window —
+		// they are superseded, so recency no longer implies relevance. They
+		// still count toward window accounting so non-stale protection is
+		// unchanged.
+		const insideProtectWindow = accumulatedTokens < config.protectTokens;
+		if ((insideProtectWindow && !isStale) || isProtected) {
+			accumulatedTokens += tokens;
+			continue;
+		}
+
+		const notice = createPrunedNotice(tokens, message);
+		candidates.push({
+			entry: entry as SessionMessageEntry,
+			tokens,
+			notice,
+			savings: estimatePrunedSavings(tokens, notice),
+		});
+		accumulatedTokens += tokens;
+	}
+
+	for (const candidate of candidates) {
+		tokensSaved += candidate.savings;
+	}
+
+	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
+	}
+
+	const prunedAt = Date.now();
+	const prunedEntries: SessionMessageEntry[] = [];
+	for (const candidate of candidates) {
+		const message = candidate.entry.message as ToolResultMessage;
+		message.content = [{ type: "text", text: candidate.notice }];
+		message.prunedAt = prunedAt;
+		prunedEntries.push(candidate.entry);
+		prunedCount++;
+	}
+
+	return { prunedCount, tokensSaved, prunedEntries };
+}