@sema-ai/core 1.275.1

package/dist/engine/compaction/compaction.d.ts

@@ -0,0 +1,139 @@
+import type { Model, StreamFn, Usage } from "../llm/index.js";
+import { type AgentCoreCompletionRuntimeDeps } from "../loop/runtime-deps.js";
+import type { AgentMessage, ThinkingLevel } from "../loop/types.js";
+import { CompactionError, type Result, type SessionTreeEntry } from "../harness/types.js";
+import { type FileOperations } from "./utils.js";
+/** File-operation details stored on generated compaction entries. */
+export interface CompactionDetails {
+    /** Files read in the compacted history. */
+    readFiles: string[];
+    /** Files modified in the compacted history (sorted, for stable display). */
+    modifiedFiles: string[];
+    /**
+     * The same modified set ordered most-recently-touched FIRST. Top-N consumers (working-file
+     * attachments) pick from here so an alphabetical sort cannot push the file the model actually
+     * needs out of the window (the LONGRUN-2b miss). Optional: absent on details persisted before
+     * this field existed.
+     */
+    modifiedFilesByRecency?: string[];
+}
+/** Generated compaction data ready to be persisted as a compaction entry. */
+export interface CompactionResult<T = unknown> {
+    /** Summary text that replaces compacted history in future context. */
+    summary: string;
+    /** Entry id where retained history starts. */
+    firstKeptEntryId: string;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+    /** Optional implementation-specific details stored with the compaction entry. */
+    details?: T;
+}
+/** Compaction thresholds and retention settings. */
+export interface CompactionSettings {
+    /** Enable automatic compaction decisions. */
+    enabled: boolean;
+    /** Tokens reserved for summary prompt and output. */
+    reserveTokens: number;
+    /** Approximate recent-context tokens to keep after compaction. */
+    keepRecentTokens: number;
+}
+/** Default compaction settings used by the harness. */
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/**
+ * design/123 D2 — default structural coefficient (chars per token) for every structural token
+ * estimate. 4 = the historical chars/4 heuristic (CC 198's legacy-family value); per-model override
+ * via `Model.charsPerToken` (newer families → 3, CJK-heavy → 2–3). Threaded as an explicit parameter
+ * through the estimate chain so caller-side coordinates never split (estimate vs cut-point vs defense).
+ */
+export declare const DEFAULT_CHARS_PER_TOKEN = 4;
+/** Calculate total context tokens from provider usage. */
+export declare function calculateContextTokens(usage: Usage): number;
+/**
+ * Return usage from the last successful assistant message in session entries.
+ *
+ * design/123 D1 stale-anchor note (fable-m2, same-family point): this scans RAW session entries, so
+ * unlike `buildSessionContext` (which shallow-strips the usage of kept-tail assistants replayed
+ * across a compaction boundary — the anchor "naturally disappears", CC 198 parity) it CAN still see
+ * a pre-compaction anchor. Any consumer using this across a compaction boundary must treat such an
+ * anchor as STALE: it reflects the pre-compaction request and overestimates the post-compaction
+ * context. (Currently exported with no in-repo production consumer.)
+ */
+export declare function getLastAssistantUsage(entries: SessionTreeEntry[]): Usage | undefined;
+/** Estimated context-token usage for a message list. */
+export interface ContextUsageEstimate {
+    /** Estimated total context tokens. */
+    tokens: number;
+    /** Tokens reported by the most recent assistant usage block. */
+    usageTokens: number;
+    /** Estimated tokens after the most recent assistant usage block. */
+    trailingTokens: number;
+    /** Index of the message that provided usage, or null when none exists. */
+    lastUsageIndex: number | null;
+}
+/** Estimate context tokens for messages using provider usage when available.
+ *  `charsPerToken` (design/123 D2): structural coefficient for the anchor-less fallback and the
+ *  trailing (post-anchor) increment — pass `Model.charsPerToken` so the estimate matches the model. */
+export declare function estimateContextTokens(messages: AgentMessage[], charsPerToken?: number): ContextUsageEstimate;
+/** Return whether context usage exceeds the configured compaction threshold. */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/** Estimate token count for one message using a conservative character heuristic.
+ *  `charsPerToken` (design/123 D2): per-model structural coefficient (default 4 = byte-compatible
+ *  legacy heuristic). Images contribute a FIXED token weight independent of the coefficient. */
+export declare function estimateTokens(message: AgentMessage, charsPerToken?: number): number;
+/** Find the user-visible message that starts the turn containing an entry. */
+export declare function findTurnStartIndex(entries: SessionTreeEntry[], entryIndex: number, startIndex: number): number;
+/** Cut point selected for compaction. */
+export interface CutPointResult {
+    /** Index of the first entry retained after compaction. */
+    firstKeptEntryIndex: number;
+    /** Index of the turn-start entry when the cut splits a turn, otherwise -1. */
+    turnStartIndex: number;
+    /** Whether the selected cut point splits an in-progress turn. */
+    isSplitTurn: boolean;
+}
+/** Find the compaction cut point that keeps approximately the requested recent-token budget.
+ *  `charsPerToken` (design/123 D2): the keep-recent accumulation must live in the SAME structural
+ *  coordinate as the trigger estimate, or the kept tail is systematically over/under-sized. */
+export declare function findCutPoint(entries: SessionTreeEntry[], startIndex: number, endIndex: number, keepRecentTokens: number, charsPerToken?: number): CutPointResult;
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI coding assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
+/** Fidelity-disclosure payload for a truncated summarization input (bridged by the caller to the
+ *  `compaction.input_truncated` trace frame). `keptChars` = surviving conversation chars (marker excluded). */
+export interface SummarizationInputTruncation {
+    label: "history" | "turn_prefix";
+    droppedChars: number;
+    keptChars: number;
+}
+/** CC 198 jNl — verbatim marker inserted where the oldest conversation groups were dropped. */
+export declare const COMPACTION_PTL_RETRY_MARKER = "[earlier conversation truncated for compaction retry]";
+/** Generate or update a conversation summary for compaction. */
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, runtime?: AgentCoreCompletionRuntimeDeps, charsPerToken?: number, onInputTruncated?: (info: SummarizationInputTruncation) => void): Promise<Result<string, CompactionError>>;
+/** Prepared inputs for a compaction run. */
+export interface CompactionPreparation {
+    /** Entry id where retained history starts. */
+    firstKeptEntryId: string;
+    /** Messages summarized into the history summary. */
+    messagesToSummarize: AgentMessage[];
+    /** Prefix messages summarized separately when compaction splits a turn. */
+    turnPrefixMessages: AgentMessage[];
+    /** Whether compaction splits a turn. */
+    isSplitTurn: boolean;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+    /** Previous compaction summary used for iterative updates. */
+    previousSummary?: string;
+    /** File operations extracted from summarized history. */
+    fileOps: FileOperations;
+    /** Settings used to prepare compaction. */
+    settings: CompactionSettings;
+}
+/** Prepare session entries for compaction, or return undefined when compaction is not applicable.
+ *  `charsPerToken` (design/123 D2, signature threading): keeps `tokensBefore` and the cut-point
+ *  accounting in the same per-model structural coordinate as the caller's trigger estimate. */
+export declare function prepareCompaction(pathEntries: SessionTreeEntry[], settings: CompactionSettings, charsPerToken?: number): Result<CompactionPreparation | undefined, CompactionError>;
+export { computeFileLists, serializeConversation } from "./utils.js";
+/** Generate compaction summary data from prepared session history.
+ *  `charsPerToken` (design/123 D2, signature threading): coefficient for the summarization-input
+ *  window guard. Defaults to the SUMMARY model's own `charsPerToken` (the estimated input is sent to
+ *  THAT model), then 4. */
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, runtime?: AgentCoreCompletionRuntimeDeps, charsPerToken?: number, onInputTruncated?: (info: SummarizationInputTruncation) => void): Promise<Result<CompactionResult, CompactionError>>;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/engine/compaction/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../../src/engine/compaction/compaction.ts"],"names":[],"mappings":"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"}