@sayknow-cli/agent-core 0.4.1 → 0.4.3

package/dist/types/append-only-context.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+import type { Context, Message, Tool } from "@sayknow-cli/ai";
+import type { AgentContext } from "./types";
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+    systemPrompt: string[];
+    tools: Tool[];
+    fingerprint: string;
+}
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+    /** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+    intentTracing: boolean;
+}
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export declare class StablePrefix {
+    #private;
+    get fingerprint(): string;
+    get version(): number;
+    get built(): boolean;
+    exportSnapshot(): StablePrefixSnapshot | null;
+    importSnapshot(snapshot: StablePrefixSnapshot, options: BuildOptions): void;
+    /**
+     * Build or rebuild from live context.
+     * Returns `true` if the prefix actually changed (cache miss imminent).
+     */
+    build(context: AgentContext, options: BuildOptions): boolean;
+    /** Force rebuild on the next `build()` call. */
+    invalidate(): void;
+    /**
+     * Returns the cached prefix.
+     * @throws if `build()` was never called.
+     */
+    toContext(): {
+        systemPrompt: string[];
+        tools: Tool[];
+    };
+}
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export declare class AppendOnlyLog {
+    #private;
+    get length(): number;
+    append(message: any): void;
+    extend(messages: any[]): void;
+    /** Replace the last entry — only legal for compaction. */
+    replaceTail(replacement: any): void;
+    /** Returns a shallow copy of all entries. */
+    toMessages(): Message[];
+    /** Direct readonly access for in-place inspection. */
+    entries(): readonly Message[];
+    clear(): void;
+}
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export interface AppendOnlyContextManagerOptions {
+    /**
+     * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+     * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+     * not throw. `from` is `<unbuilt>` on the first build.
+     */
+    readonly onPrefixChange?: (info: {
+        from: string;
+        to: string;
+        version: number;
+    }) => void;
+}
+export declare class AppendOnlyContextManager {
+    #private;
+    readonly prefix: StablePrefix;
+    readonly log: AppendOnlyLog;
+    constructor(options?: AppendOnlyContextManagerOptions);
+    static forkFromSeed(args: {
+        prefixSnapshot?: StablePrefixSnapshot;
+        messages?: readonly Message[];
+        options: BuildOptions;
+    }): AppendOnlyContextManager;
+    build(context: AgentContext, options: BuildOptions): Context;
+    /**
+     * Sync normalized (provider-level) messages into the append-only log.
+     *
+     * Detects both compaction (shorter array) and in-place rewrites
+     * (same length, changed content via a rolling digest).
+     */
+    syncMessages(normalizedMessages: any[]): void;
+    seedNormalizedMessages(messages: readonly Message[], options?: {
+        reset?: boolean;
+    }): void;
+    /** Reset prefix + log for a model/provider switch while mode stays active. */
+    invalidateForModelChange(): void;
+    /** Reset the sync cursor AND clear the log. */
+    resetSyncCursor(): void;
+    appendMessage(message: any): void;
+    replaceTailMessage(message: any): void;
+    invalidate(): void;
+    reset(context: AgentContext, options: BuildOptions): void;
+}
+export declare function cloneJson<T>(value: T): T;

package/dist/types/compaction/branch-summarization.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Branch summarization for tree navigation.
+ *
+ * When navigating to a different point in the session tree, this generates
+ * a summary of the branch being left so context isn't lost.
+ */
+import type { Model, ProviderSessionState } from "@sayknow-cli/ai";
+import { type AgentTelemetry } from "../telemetry";
+import type { AgentMessage } from "../types";
+import type { ReadonlySessionManager, SessionEntry } from "./entries";
+import { type ConvertToLlm } from "./messages";
+import { type FileOperations } from "./utils";
+export interface BranchSummaryResult {
+    summary?: string;
+    readFiles?: string[];
+    modifiedFiles?: string[];
+    aborted?: boolean;
+    error?: string;
+}
+/** Details stored in BranchSummaryEntry.details for file tracking */
+export interface BranchSummaryDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export type { FileOperations } from "./utils";
+export interface BranchPreparation {
+    /** Messages extracted for summarization, in chronological order */
+    messages: AgentMessage[];
+    /** File operations extracted from tool calls */
+    fileOps: FileOperations;
+    /** Total estimated tokens in messages */
+    totalTokens: number;
+}
+export interface CollectEntriesResult {
+    /** Entries to summarize, in chronological order */
+    entries: SessionEntry[];
+    /** Common ancestor between old and new position, if any */
+    commonAncestorId: string | null;
+}
+export interface GenerateBranchSummaryOptions {
+    /** Model to use for summarization */
+    model: Model;
+    /** API key for the model */
+    apiKey: string;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Optional custom instructions for summarization */
+    customInstructions?: string;
+    /** Tokens reserved for prompt + LLM response (default 16384) */
+    reserveTokens?: number;
+    /** Optional metadata forwarded to the underlying API request (e.g. user_id for session attribution). */
+    metadata?: Record<string, unknown>;
+    /** Convert app-specific messages before serializing the branch summary prompt. */
+    convertToLlm?: ConvertToLlm;
+    /**
+     * Optional telemetry handle. When provided, the branch summary LLM call is
+     * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "branch_summary"`.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Provider session affinity id forwarded to the branch summary LLM call so it
+     * reuses the live turn's provider/WebSocket session.
+     */
+    sessionId?: string;
+    /** Shared provider state map so the branch summary call reuses session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+}
+/**
+ * Collect entries that should be summarized when navigating from one position to another.
+ *
+ * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
+ * along the way. Does NOT stop at compaction boundaries - those are included and their
+ * summaries become context.
+ *
+ * @param session - Session manager (read-only access)
+ * @param oldLeafId - Current position (where we're navigating from)
+ * @param targetId - Target position (where we're navigating to)
+ * @returns Entries to summarize and the common ancestor
+ */
+export declare function collectEntriesForBranchSummary(session: ReadonlySessionManager, oldLeafId: string | null, targetId: string): CollectEntriesResult;
+/**
+ * Prepare entries for summarization with token budget.
+ *
+ * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
+ * This ensures we keep the most recent context when the branch is too long.
+ *
+ * Also collects file operations from:
+ * - Tool calls in assistant messages
+ * - Existing branch_summary entries' details (for cumulative tracking)
+ *
+ * @param entries - Entries in chronological order
+ * @param tokenBudget - Maximum tokens to include (0 = no limit)
+ */
+export declare function prepareBranchEntries(entries: SessionEntry[], tokenBudget?: number): BranchPreparation;
+/**
+ * Generate a summary of abandoned branch entries.
+ *
+ * @param entries - Session entries to summarize (chronological order)
+ * @param options - Generation options
+ */
+export declare function generateBranchSummary(entries: SessionEntry[], options: GenerateBranchSummaryOptions): Promise<BranchSummaryResult>;

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

@@ -0,0 +1,323 @@
+/**
+ * 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 ProviderSessionState, type Usage } from "@sayknow-cli/ai";
+import { type AgentTelemetry } from "../telemetry";
+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" | "off";
+    thresholdPercent?: number;
+    thresholdTokens?: number;
+    reserveTokens: number;
+    keepRecentTokens: number;
+    autoContinue?: boolean;
+    remoteEnabled?: boolean;
+    remoteEndpoint?: string;
+}
+export type RemoteCompactionFallbackHealthEvent = {
+    kind: "success";
+    model: string;
+    provider: string;
+} | {
+    kind: "fallback";
+    model: string;
+    provider: string;
+    error: string;
+};
+export interface RemoteCompactionFallbackHealthHooks {
+    recordRemoteCompactionFallback(event: RemoteCompactionFallbackHealthEvent): void;
+}
+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: the largest of 15% of the context window, the configured floor,
+ * and the model's reserved completion budget (`maxOutputTokens`).
+ *
+ * Reserving `maxOutputTokens` keeps the safe input/prompt-packing budget below the
+ * *total* context window for models whose completion reservation exceeds the 15%
+ * floor (e.g. a 400K-context model with 128K max output reserves 128K, not 60K, so
+ * input is capped near 272K instead of 340K).
+ */
+export declare function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
+/**
+ * Check if compaction should trigger based on context usage.
+ *
+ * `maxOutputTokens` is the model's reserved completion budget; it is excluded from
+ * the safe input budget so prompt + reserved output cannot exceed the total window.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): boolean;
+/** Reason a compaction was triggered. `token` is the normal user-configurable path; the rest are emergency floors. */
+export type CompactionTriggerReason = "token" | "heap" | "retainedMemory" | "providerBytes" | "messageCount" | "imageBytes";
+/** A point-in-time resource sample. Supplied by an injectable sampler so tests never read real RSS. */
+export interface EmergencyCompactionSample {
+    /** Resident heap bytes (e.g. process.memoryUsage().heapUsed). */
+    heapUsedBytes: number;
+    /** Approximate serialized provider-context bytes. */
+    providerBytes: number;
+    /** Provider-visible message count. */
+    messageCount: number;
+    /** Approximate inline image bytes in the provider context. */
+    imageBytes: number;
+    /** Bytes retained by session resident image sentinels; separate from provider-visible bytes. */
+    sessionResidentImageBytes?: number;
+    /** Bytes retained by non-provider materialized/session-local caches. */
+    materializedResidentBytes?: number;
+    /** Number of live TUI chat-container children. */
+    tuiChatChildren?: number;
+    /** Bytes retained by TUI render caches. */
+    tuiCachedRenderBytes?: number;
+}
+export interface EmergencyCompactionLimits {
+    heapUsedBytes: number;
+    providerBytes: number;
+    messageCount: number;
+    imageBytes: number;
+    retainedMemoryBytes?: number;
+    retainedMemoryDiagnosticBytes?: number;
+    tuiChatChildren?: number;
+    tuiChatChildrenDiagnostic?: number;
+}
+export declare function resetEmergencyRetainedMemoryDiagnosticsForTests(): void;
+export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: number): EmergencyCompactionLimits;
+/**
+ * Non-disableable emergency floors. These sit well above normal usage and exist so a
+ * long session on weak hardware compacts before OOM even when token-based compaction is
+ * disabled or its threshold is set too high. They are NOT user-tunable down to zero.
+ */
+export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits;
+/**
+ * Returns the first emergency limit exceeded (heap > retainedMemory > providerBytes > imageBytes > messageCount),
+ * or null when none is. Pure apart from retained-memory diagnostics; the caller routes the result through the
+ * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
+ */
+export declare function emergencyCompactionReason(sample: EmergencyCompactionSample, limits?: EmergencyCompactionLimits): CompactionTriggerReason | null;
+export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
+/**
+ * Image content has no tokenizer representation; charge a fixed estimate
+ * matching what providers typically bill for inline images.
+ */
+export declare const IMAGE_TOKEN_ESTIMATE = 1200;
+/**
+ * Native-free token estimate for a message. This is the only message
+ * token estimator: provider usage (see {@link calculatePromptTokens}) anchors
+ * the already-sent context, and this covers unsent/trailing deltas, per-entry
+ * budgeting, and display surfaces. Callers add a conservative inflation factor
+ * where compaction-threshold safety requires it.
+ */
+export declare function estimateMessageTokensHeuristic(message: AgentMessage): number;
+/**
+ * Script-aware native-free token estimate for plain string fragments.
+ * Fragment-level counterpart of {@link estimateMessageTokensHeuristic}.
+ */
+export declare function estimateTextTokensHeuristic(fragments: string | readonly string[]): number;
+export declare function estimateEntryTokens(entry: SessionEntry): number;
+export declare function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): 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
+     * `pi.gen_ai.oneshot.kind` (`compaction_summary` or `compaction_turn_prefix`).
+     */
+    telemetry?: AgentTelemetry;
+    authCredentialType?: "api_key" | "oauth";
+    /**
+     * Provider session affinity id forwarded to the maintenance LLM call so it
+     * reuses the live turn's provider/WebSocket session (matches the
+     * `providerSessionId ?? sessionId` the agent loop sends for normal turns).
+     */
+    sessionId?: string;
+    /** Shared provider state map so maintenance calls reuse session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /** Session-owned health sink for remote-compaction fallback transition logging. */
+    remoteCompactionFallbackHealth?: RemoteCompactionFallbackHealthHooks;
+}
+/**
+ * Cap the serialized conversation fed to a summarization request so the request
+ * itself fits inside the model's context window.
+ *
+ * Without this, summarizing a near-full context serializes (nearly) the entire
+ * history back into a single summary request; on strict backends (e.g.
+ * OpenAI-code/Codex `context_length_exceeded`) that request itself overflows and
+ * throws, so context-overflow recovery cannot produce a summary and the agent
+ * fails to compact-and-continue — a non-interactive `skc -p` run then terminates
+ * on the very overflow the recovery was meant to absorb.
+ *
+ * The budget reserves the summary's own output tokens plus prompt/system/template
+ * overhead, and applies a conservative safety factor for estimator error on
+ * dense text (the reason the original overflow was missed).
+ * Truncation keeps the head (origin/goals) and the tail (most recent state) and
+ * elides the middle; it is a last resort that only triggers when the input would
+ * otherwise not fit.
+ */
+export declare function boundConversationTextForSummary(conversationText: string, model: Model, outputMaxTokens: number): string;
+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;
+    /**
+     * Optional user-configured extension appended to the base handoff prompt.
+     * It SUPPLEMENTS the immutable base (safety/continuity structure); it never
+     * replaces `HANDOFF_DOCUMENT_PROMPT`.
+     */
+    promptExtension?: 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 `pi.gen_ai.oneshot.kind = "handoff"`.
+     */
+    telemetry?: AgentTelemetry;
+    authCredentialType?: "api_key" | "oauth";
+    /**
+     * Provider session affinity id forwarded to the handoff LLM call so it
+     * reuses the live turn's provider/WebSocket session.
+     */
+    sessionId?: string;
+    /** Shared provider state map so the handoff call reuses session-scoped transport/session caches. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+}
+export declare function renderHandoffPrompt(customInstructions?: string, promptExtension?: 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;
+    /**
+     * Diagnostics for the keep-window token correction (Finding 7). `ratio` is the
+     * clamped heuristic→actual correction that was applied (1 when none supplied);
+     * `keepRecentTokensCorrected` is the heuristic budget findCutPoint actually used.
+     */
+    tokenCorrection: {
+        ratio: number;
+        keepRecentTokensCorrected: number;
+    };
+}
+/** Bounds for the keep-window token correction (Finding 7): never trust a ratio
+ * beyond 2x in either direction so a bad estimate cannot balloon or collapse the
+ * kept window. */
+export declare const TOKEN_CORRECTION_MIN_RATIO = 0.5;
+export declare const TOKEN_CORRECTION_MAX_RATIO = 2;
+export interface PrepareCompactionOptions {
+    /**
+     * Observed heuristic→actual token correction for the post-boundary keep window
+     * (actualTokens / chars-4-heuristicTokens), supplied by the caller from per-turn
+     * Usage deltas or a stable-prefix-subtracted comparison. Clamped to
+     * [0.5, 2] and applied bidirectionally. When omitted, no correction is applied
+     * (the confounded raw promptTokens/estimatedTokens quotient is never used).
+     */
+    tokenCorrectionRatio?: number;
+    /**
+     * Model context-window size. Windows below 66k retain the legacy fixed
+     * keepRecentTokens behavior; larger windows scale the keep window to 30%.
+     */
+    contextWindow?: number;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, options?: PrepareCompactionOptions): 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,124 @@
+import type { ImageContent, MessageAttribution, ServiceTier, TextContent } from "@sayknow-cli/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;
+    /** Requested model before a runtime substitution/fallback, in "provider/modelId" format. */
+    previousModel?: string;
+    /** Machine-readable reason for runtime model substitution/fallback. */
+    reason?: string;
+    /** Effective thinking level when the change was recorded. */
+    thinkingLevel?: string | null;
+}
+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 DiscoveredBuiltinToolSelectionEntry extends SessionEntryBase {
+    type: "discovered_builtin_tool_selection";
+    /** Discoverable built-in 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 ConfiguredModelChainEntry extends SessionEntryBase {
+    type: "configured_model_chain";
+    role: string;
+    entries: readonly string[];
+    origin: string;
+    identity?: string;
+    explicitHead: boolean;
+    /** Whether this entry removes the configured chain for its role. */
+    cleared?: boolean;
+}
+export interface CustomCompactionSessionEntries {
+}
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TtsrInjectionEntry | MCPToolSelectionEntry | DiscoveredBuiltinToolSelectionEntry | SessionInitEntry | ModeChangeEntry | ConfiguredModelChainEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
+export interface ReadonlySessionManager {
+    getBranch(leafId?: string | null): SessionEntry[];
+    getEntry(id: string): SessionEntry | undefined;
+}