@prometheus-ai/agent-core 0.5.0

package/dist/types/compaction/compaction.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+import { type MessageAttribution, type Model, type Usage } from "@prometheus-ai/ai";
+import { type AgentTelemetry } from "../telemetry";
+import { ThinkingLevel } from "../thinking";
+import type { AgentMessage, AgentTool } from "../types";
+import type { SessionEntry } from "./entries";
+import { type ConvertToLlm } from "./messages";
+import { type FileOperations } from "./utils";
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+    summary: string;
+    /** Short PR-style summary for display purposes. */
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Hook-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** Hook-provided data to persist alongside compaction entry. */
+    preserveData?: Record<string, unknown>;
+}
+export interface CompactionSettings {
+    enabled: boolean;
+    strategy?: "context-full" | "handoff" | "shake" | "off";
+    thresholdPercent?: number;
+    thresholdTokens?: number;
+    reserveTokens: number;
+    keepRecentTokens: number;
+    autoContinue?: boolean;
+    remoteEnabled?: boolean;
+    remoteEndpoint?: string;
+}
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/**
+ * Calculate total context tokens from usage.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export declare function calculateContextTokens(usage: Usage): number;
+export declare function calculatePromptTokens(usage: Usage): number;
+/**
+ * Find the last non-aborted assistant message usage from session entries.
+ */
+export declare function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined;
+/**
+ * Effective reserve: at least 15% of context window or the configured floor, whichever is larger.
+ */
+export declare function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Estimate token count for a message using cl100k_base via the native
+ * tokenizer. This is not Claude's first-party tokenizer (Anthropic doesn't
+ * publish one) but is within ~5–10% across English/code text.
+ */
+export declare function estimateTokens(message: AgentMessage): number;
+/**
+ * Find the user message (or bashExecution) that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ * BashExecutionMessage is treated like a user message for turn boundaries.
+ */
+export declare function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number;
+export interface CutPointResult {
+    /** Index of first entry to keep */
+    firstKeptEntryIndex: number;
+    /** Index of user message that starts the turn being split, or -1 if not splitting */
+    turnStartIndex: number;
+    /** Whether this cut splits a turn (cut point is not a user message) */
+    isSplitTurn: boolean;
+}
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+export declare const AUTO_HANDOFF_THRESHOLD_FOCUS: string;
+/**
+ * Generate a summary of the conversation using the LLM.
+ * If previousSummary is provided, uses the update prompt to merge.
+ */
+export interface SummaryOptions {
+    promptOverride?: string;
+    extraContext?: string[];
+    remoteEndpoint?: string;
+    remoteInstructions?: string;
+    initiatorOverride?: MessageAttribution;
+    metadata?: Record<string, unknown>;
+    convertToLlm?: ConvertToLlm;
+    /**
+     * Optional telemetry handle. When provided, every LLM call emitted during
+     * compaction is wrapped in an OTEL chat span tagged with
+     * `prometheus.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
+     * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Active session thinking level. Threaded from `agent-session.ts` so
+     * compaction honors the user's `/model` thinking selection instead of
+     * silently overriding it with `Effort.High` (the historical default).
+     * `undefined` / `ThinkingLevel.Inherit` falls back to that historical
+     * default; `ThinkingLevel.Off` omits reasoning entirely. See
+     * `resolveCompactionEffort` for the conversion contract.
+     */
+    thinkingLevel?: ThinkingLevel;
+}
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
+export interface HandoffOptions {
+    /** Live agent system prompt — passed verbatim so providers hit the cached prefix. */
+    systemPrompt: string[];
+    /** Live agent tool list — same purpose. Forced to `toolChoice: "none"`. */
+    tools?: AgentTool<any>[];
+    customInstructions?: string;
+    convertToLlm?: ConvertToLlm;
+    initiatorOverride?: MessageAttribution;
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional telemetry handle. When provided, the handoff LLM call is
+     * wrapped in an OTEL chat span tagged with `prometheus.gen_ai.oneshot.kind = "handoff"`.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Active session thinking level. Threaded from `agent-session.ts` so
+     * handoff generation honors the user's `/model` thinking selection
+     * instead of silently overriding it with `Effort.High`. See
+     * `resolveCompactionEffort` for the conversion contract.
+     */
+    thinkingLevel?: ThinkingLevel;
+}
+export declare function renderHandoffPrompt(customInstructions?: string): string;
+export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: string, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
+export interface CompactionPreparation {
+    /** UUID of first entry to keep */
+    firstKeptEntryId: string;
+    /** Messages that will be summarized and discarded */
+    messagesToSummarize: AgentMessage[];
+    /** Messages that will be turned into turn prefix summary (if splitting) */
+    turnPrefixMessages: AgentMessage[];
+    /** Messages kept in full after compaction (recent history) */
+    recentMessages: AgentMessage[];
+    /** Whether this is a split turn (cut point in middle of turn) */
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    /** Summary from previous compaction, for iterative update */
+    previousSummary?: string;
+    /** Preserved opaque compaction payload from the previous compaction, if any. */
+    previousPreserveData?: Record<string, unknown>;
+    /** File operations extracted from messagesToSummarize */
+    fileOps: FileOperations;
+    /** Compaction settions from settings.jsonl	*/
+    settings: CompactionSettings;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds id/parentId when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ */
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;

package/dist/types/compaction/entries.d.ts

@@ -0,0 +1,103 @@
+import type { ImageContent, MessageAttribution, ServiceTier, TextContent } from "@prometheus-ai/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/dist/types/compaction/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 declare class CompactionCancelledError extends Error {
+    readonly name: "CompactionCancelledError";
+    constructor(message?: string);
+}
+/**
+ * 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/dist/types/compaction/index.d.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 "./shake";
+export * from "./utils";

package/dist/types/compaction/messages.d.ts

@@ -0,0 +1,61 @@
+import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@prometheus-ai/ai";
+import type { AgentMessage } from "../types";
+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[];
+export declare function renderBranchSummaryContext(summary: string): string;
+export declare function renderCompactionSummaryContext(summary: string): string;
+export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload): CompactionSummaryMessage;
+export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
+/**
+ * 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 declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];
+export declare const convertToLlm: typeof defaultConvertToLlm;

package/dist/types/compaction/openai.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Remote compaction utilities.
+ *
+ * Provider-side conversation summarization endpoints. Two flavors:
+ *
+ * - **OpenAI remote compaction** (`/responses/compact`): preserves encrypted
+ *   reasoning across compactions by submitting the full responses-API native
+ *   history and storing the returned `compaction` / `compaction_summary`
+ *   item in `preserveData` so future turns can replay the encrypted state.
+ * - **Generic remote compaction**: a thin POST helper for self-hosted
+ *   summarization endpoints that accept `{ systemPrompt, prompt }` and reply
+ *   with `{ summary, shortSummary? }`.
+ */
+import type { Message, Model } from "@prometheus-ai/ai/types";
+export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+export type OpenAiRemoteCompactionItem = {
+    type: "compaction" | "compaction_summary";
+    encrypted_content?: string;
+    summary?: string;
+};
+export interface OpenAiRemoteCompactionPreserveData {
+    provider?: string;
+    replacementHistory: Array<Record<string, unknown>>;
+    compactionItem: OpenAiRemoteCompactionItem;
+}
+export interface OpenAiRemoteCompactionRequest {
+    model: string;
+    input: Array<Record<string, unknown>>;
+    instructions: string;
+}
+export interface OpenAiRemoteCompactionResponse extends OpenAiRemoteCompactionPreserveData {
+}
+export interface RemoteCompactionRequest {
+    systemPrompt: string;
+    prompt: string;
+}
+export interface RemoteCompactionResponse {
+    summary: string;
+    shortSummary?: string;
+}
+export declare function shouldUseOpenAiRemoteCompaction(model: Model): boolean;
+export declare function getPreservedOpenAiRemoteCompactionData(preserveData: Record<string, unknown> | undefined): OpenAiRemoteCompactionPreserveData | undefined;
+export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Record<string, unknown> | undefined, remoteCompaction: OpenAiRemoteCompactionPreserveData | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the OpenAI Responses-API native history array from LLM messages.
+ *
+ * Caller is responsible for converting any custom message types to
+ * `Message[]` first (e.g. via the agent's `convertToLlm`); this function
+ * operates purely on the LLM-domain shape.
+ *
+ * @param messages - LLM messages to encode.
+ * @param model - Target model (used for provider gating + tool-call id rules).
+ * @param previousReplacementHistory - History from a prior compaction whose
+ *   encrypted reasoning we want to preserve.
+ */
+export declare function buildOpenAiNativeHistory(messages: Message[], model: Model, previousReplacementHistory?: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: string, compactInput: Array<Record<string, unknown>>, instructions: string, signal?: AbortSignal): Promise<OpenAiRemoteCompactionResponse>;
+export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal): Promise<RemoteCompactionResponse>;

package/dist/types/compaction/pruning.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+import type { SessionEntry } from "./entries";
+import { 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 declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PruneResult {
+    prunedCount: number;
+    tokensSaved: number;
+}
+export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/dist/types/compaction/shake.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries";
+import { 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 declare const DEFAULT_SHAKE_CONFIG: ShakeConfig;
+/** Manual `/shake`: aggressive — drops every eligible region across history. */
+export declare const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig;
+/** 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;
+/**
+ * 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 declare function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[];
+/**
+ * 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 declare function applyShakeRegion(region: ShakeRegion, replacement: string): void;
+/**
+ * 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 declare function applyShakeRegions(items: Array<{
+    region: ShakeRegion;
+    replacement: string;
+}>): void;

package/dist/types/compaction/tool-protection.d.ts

@@ -0,0 +1,17 @@
+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);
+export declare function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall>;
+/**
+ * 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 declare function getReadToolPath({ toolResult, toolCall }: ProtectedToolContext): string | undefined;
+export declare function isSkillReadToolResult(context: ProtectedToolContext): boolean;
+export declare function isProtectedToolResult(toolResult: ToolResultMessage, toolCall: AgentToolCall | undefined, matchers: readonly ProtectedToolMatcher[]): boolean;

package/dist/types/compaction/utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { Message } from "@prometheus-ai/ai";
+import type { AgentMessage } from "../types";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * 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 declare function serializeConversation(messages: Message[]): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/compaction.d.ts

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