@vib-rato/agent-core 0.16.0

package/dist/types/attempt-scope.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Per-attempt scope identity for request-scoped execution attribution.
+ *
+ * An AttemptScope is an immutable, frozen value allocated before every
+ * observable lifecycle emission for a single provider/agent attempt.
+ * It carries a stable `attemptId`, a monotonic `generation` (per-lineage),
+ * and a `lineage` discriminator that distinguishes the main attempt from
+ * concurrent side attempts (IRC background, ephemeral/btw turns).
+ *
+ * The `attemptId` + `generation` + `lineage` form the comparable identity.
+ * AttemptScope is structurally assignable to AttemptScopeRef in
+ * `packages/ai` so it can be carried through `SimpleStreamOptions` and
+ * provider hook signatures without a reverse dependency.
+ */
+export type AttemptLineage = "main" | `side:${string}`;
+export interface AttemptScope {
+    readonly attemptId: string;
+    readonly generation: number;
+    readonly lineage: AttemptLineage;
+}
+export declare function attemptScopesEqual(a: AttemptScope, b: AttemptScope): boolean;
+/**
+ * Per-lineage currentness authority. Main and side attempts have separate
+ * instances so a side attempt never invalidates the main scope, and
+ * `forceAbort` advances only the main lineage.
+ */
+export interface LineageCurrentness {
+    readonly lineage: AttemptLineage;
+    /** True iff no successor scope with a greater generation was allocated in this lineage. */
+    isCurrent(scope: AttemptScope): boolean;
+    /** Allocate the next generation for the given attempt identity in this lineage. */
+    advance(attemptId: string): number;
+    /** Allocate the next generation in this lineage. */
+    /** Current generation value for this lineage. */
+    readonly current: number;
+}
+export declare function createLineageCurrentness(lineage: AttemptLineage): LineageCurrentness;
+/**
+ * Agent-owned authority over all attempt lineages. Owns the main lineage;
+ * side lineages are registered/removed with bounded lifecycle.
+ *
+ * This is the SINGLE source of currentness truth injected into
+ * AttemptRecordStore (packages/coding-agent). Every store operation
+ * calls `authority.isCurrent(scope)` and fails closed when the authority
+ * is missing or the scope is superseded.
+ */
+export interface AttemptScopeAuthority {
+    /** Register a side-lineage authority. Returns an unregister function. */
+    registerSide(lineage: AttemptLineage, auth: LineageCurrentness): () => void;
+    /** True iff the scope's lineage is known and its generation is current. */
+    isCurrent(scope: AttemptScope): boolean;
+    /** Advance the main lineage (called by forceAbort). Returns the new generation. */
+    advanceMain(): number;
+    /** Mint the next main-lineage scope. */
+    mintMain(): AttemptScope;
+    /**
+     * Atomically register a fresh side lineage, mint a side scope, and return
+     * both the scope and a dispose function. The authority knows the lineage
+     * BEFORE the scope is returned, so `isCurrent` succeeds immediately.
+     */
+    mintSide(): {
+        scope: AttemptScope;
+        dispose: () => void;
+    };
+}
+export interface AttemptMinter {
+    mint(lineage: AttemptLineage): AttemptScope;
+}
+export declare function createAttemptMinter(): AttemptMinter;
+/**
+ * Create the Agent-owned authority. Owns the main lineage and a bounded
+ * (LRU-capped) map of side lineages. Only RETIRED side authorities are
+ * eligible for LRU eviction; a live side attempt is never silently
+ * invalidated by a newer side registration.
+ */
+export declare function createAttemptScopeAuthority(): AttemptScopeAuthority;
+/**
+ * Immutable per-run attempt handle, carried through terminal/finalizer paths.
+ * Keyed by logicalRunId in the Agent's `#runHandles` map.
+ */
+export interface AttemptRunHandle {
+    readonly logicalRunId: number | import("./types.js").ManagedLogicalRunId;
+    readonly scope: AttemptScope;
+}

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

@@ -0,0 +1,31 @@
+export interface AdaptiveCompactionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    windowStart: number;
+    lastContextTokens: number;
+    lastCompactContextTokens: number | null;
+    lastCompactTs: number | null;
+}
+export interface AdaptiveCompactionDecisionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    lastContextTokens?: number;
+}
+export interface AdaptiveCompactionOptions {
+    enabled: boolean;
+    turnWindow: number;
+    baseThresholdPercent: number;
+    aggression: number;
+    minThresholdPercent?: number;
+}
+export declare class AdaptiveCompactionTracker {
+    #private;
+    windowMs: number;
+    constructor(windowMs?: number, now?: number);
+    setWindowMs(windowMs: number, now?: number): void;
+    reset(now?: number): void;
+    recordCall(contextTokens: number, now?: number): void;
+    recordCompact(contextTokens: number, now?: number): void;
+    snapshot(): AdaptiveCompactionState;
+    decisionState(): AdaptiveCompactionDecisionState;
+}

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 "@vib-rato/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,330 @@
+/**
+ * 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 "@vib-rato/ai";
+import { type AgentTelemetry } from "../telemetry";
+import type { AgentMessage, AgentTool } from "../types";
+import type { AdaptiveCompactionDecisionState, AdaptiveCompactionOptions } from "./adaptive";
+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;
+    adaptive?: AdaptiveCompactionOptions;
+    adaptiveState?: AdaptiveCompactionDecisionState;
+    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;
+export declare function computeAdaptiveThresholdPercent(basePercent: number, contextTokens: number, contextWindow: number, state: AdaptiveCompactionDecisionState | undefined, options: AdaptiveCompactionOptions | undefined): number;
+/**
+ * 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" | "transcriptFile" | "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;
+    /** On-disk JSONL transcript file size in bytes; 0/undefined when unknown. */
+    transcriptFileBytes?: number;
+}
+export interface EmergencyCompactionLimits {
+    heapUsedBytes: number;
+    providerBytes: number;
+    messageCount: number;
+    imageBytes: number;
+    retainedMemoryBytes?: number;
+    retainedMemoryDiagnosticBytes?: number;
+    tuiChatChildren?: number;
+    tuiChatChildrenDiagnostic?: number;
+    transcriptFileBytes?: 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 > transcriptFile > 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, contextTokens?: 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 `vib -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 "@vib-rato/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;
+}