@kodax-ai/kodax 0.7.43 → 0.7.44

package/dist/types-chunks/file-tracker.d-DOfaoCbJ.d.ts

@@ -0,0 +1,633 @@
+import { m as KodaXMessage } from './types.d-B1uGoVTE.js';
+import { f as AgentMessage, ag as SessionEntry, ae as Session, ah as SessionExtension, m as CompactionDetails, u as FileOperations } from './types.d-DM8zEJgF.js';
+import { s as KodaXSessionLineage, i as KodaXJsonValue, a as KodaXCompactMemorySeed, o as KodaXSessionEntry, z as KodaXSessionTreeNode, r as KodaXSessionLabelEntry, q as KodaXSessionGoalEntry, v as KodaXSessionNavigationOptions, k as KodaXSessionArtifactLedgerEntry } from './types.d-HBbWT-iA.js';
+
+/**
+ * @kodax-ai/agent Constants
+ *
+ * 通用 Agent 常量配置
+ */
+declare const KODAX_MAX_TOKENS = 32768;
+declare const KODAX_DEFAULT_TIMEOUT = 60;
+declare const KODAX_HARD_TIMEOUT = 300;
+declare const KODAX_MAX_RETRIES = 3;
+declare const KODAX_RETRY_BASE_DELAY = 2;
+declare const KODAX_MAX_INCOMPLETE_RETRIES = 2;
+declare const KODAX_MAX_MAXTOKENS_RETRIES = 3;
+declare const KODAX_STAGGER_DELAY = 1;
+declare const KODAX_API_MIN_INTERVAL = 0.5;
+declare const PROMISE_PATTERN: RegExp;
+
+/**
+ * @kodax-ai/agent Tokenizer
+ *
+ * Token 估算 - 使用 tiktoken 进行精确计算
+ */
+
+/**
+ * 估算消息的 token 数量
+ *
+ * 精确计算包括：
+ * - 消息结构开销（每条约 4 tokens）
+ * - 角色标识
+ * - 内容文本
+ * - 工具调用和结果
+ */
+declare function estimateTokens(messages: KodaXMessage[]): number;
+/**
+ * 计算单个文本的 token 数量（便捷函数）
+ */
+declare function countTokens(text: string): number;
+
+/**
+ * Layer A Primitive: CompactionPolicy + DefaultSummaryCompaction
+ *
+ * FEATURE_081 (v0.7.23): Pluggable compaction for generic agent loops.
+ *
+ * Two layers:
+ *   - Layer A (here): `CompactionPolicy` interface + `DefaultSummaryCompaction`
+ *     — a minimal "token threshold → LLM summary of old messages" policy that
+ *     any external Agent can pick up with zero KodaX runtime dependency.
+ *   - Layer B (`../session-lineage/index.js/src/lineage.ts`): `LineageCompaction`
+ *     wraps the full FEATURE_072 lineage-native compaction for the coding
+ *     preset.
+ *
+ * The `compaction` entry shape written by `DefaultSummaryCompaction` is the
+ * same type used by `LineageExtension`, so the two layers interoperate on
+ * the same Session log.
+ *
+ * History: extracted to `@kodax-ai/core` in FEATURE_082 (v0.7.24); merged back
+ * into `@kodax-ai/agent` in v0.7.35.1 FEATURE_142.
+ */
+
+/**
+ * Runtime context for a compaction pass. Abstracts the LLM/tokenizer
+ * dependencies so policies stay independent of any specific provider.
+ */
+interface CompactionContext {
+    readonly tokensUsed: number;
+    readonly budget: number;
+    /**
+     * Summarizer implementation. Callers inject a function that maps a list of
+     * messages to a short summary string. In coding-preset mode this is wired
+     * to `runKodaX` internally; for external consumers it can call any LLM.
+     */
+    readonly summarize: (messages: readonly AgentMessage[]) => Promise<string>;
+}
+/**
+ * Payload written to the `compaction` entry appended by `compact()`.
+ */
+interface CompactionEntryPayload {
+    readonly summary: string;
+    readonly replacedMessageEntryIds: readonly string[];
+}
+/**
+ * Typed compaction entry. `type` is `'compaction'`; extensions (LineageExtension)
+ * may claim this same type.
+ */
+interface CompactionEntry extends SessionEntry {
+    readonly type: 'compaction';
+    readonly payload: CompactionEntryPayload;
+}
+/**
+ * Outcome of a single CompactionPolicy.compact() pass. Renamed from
+ * `CompactionResult` to `PolicyCompactionResult` in v0.7.35.1 FEATURE_142
+ * because the Layer A primitive collided with @kodax-ai/agent's pre-existing
+ * `CompactionResult` (compaction/types.ts) used by the coding orchestration
+ * post-compact pipeline. The two types model different things:
+ *   - `PolicyCompactionResult` (here): "summary + replaced entry ids", the
+ *     payload of one CompactionPolicy step.
+ *   - `CompactionResult` (compaction/types.ts): the rich result of the
+ *     coding-side multi-pass compaction (artifactLedger / memorySeed /
+ *     tokensBefore / tokensAfter / etc).
+ */
+interface PolicyCompactionResult {
+    readonly summary: string;
+    readonly replacedMessageEntryIds: readonly string[];
+}
+/**
+ * Pluggable compaction policy. Any multi-turn Agent loop can check
+ * `shouldCompact()` at round boundaries and call `compact()` when it returns
+ * true.
+ */
+interface CompactionPolicy {
+    readonly name: string;
+    shouldCompact(session: Session, tokensUsed: number, budget: number): boolean;
+    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
+    /** Optional: rehydrate compacted content when a restore hint is available. */
+    restore?(session: Session, hint: unknown): Promise<void>;
+}
+/**
+ * Configuration for `DefaultSummaryCompaction`.
+ */
+interface DefaultSummaryCompactionOptions {
+    /**
+     * Fraction of `budget` at which compaction triggers. Default 0.8 (i.e.
+     * 80% of the token budget). Must be in (0, 1].
+     */
+    readonly thresholdRatio?: number;
+    /**
+     * Number of most-recent message entries to preserve verbatim. Default 10.
+     * Must be non-negative.
+     */
+    readonly keepRecent?: number;
+    /**
+     * Optional clock override (ms epoch). Useful for deterministic tests.
+     */
+    readonly now?: () => number;
+    /**
+     * Optional random-string override. Useful for deterministic tests.
+     */
+    readonly randomSuffix?: () => string;
+}
+/**
+ * Minimal "token threshold + LLM summary" compaction policy. Works on any
+ * Session that stores `message` entries.
+ *
+ * Behavior:
+ *   - `shouldCompact` returns true when `tokensUsed >= budget *
+ *     thresholdRatio`.
+ *   - `compact` reads all `message` entries, keeps the last `keepRecent`
+ *     untouched, summarizes the rest via `ctx.summarize`, and appends a
+ *     single `compaction` entry to the session.
+ *
+ * Caller is responsible for invoking `shouldCompact` and for interpreting the
+ * appended entry when building the next turn's prompt.
+ */
+declare class DefaultSummaryCompaction implements CompactionPolicy {
+    readonly name = "default-summary";
+    private readonly thresholdRatio;
+    private readonly keepRecent;
+    private readonly now;
+    private readonly randomSuffix;
+    constructor(opts?: DefaultSummaryCompactionOptions);
+    shouldCompact(_session: Session, tokensUsed: number, budget: number): boolean;
+    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
+}
+
+/**
+ * v0.7.35.1 FEATURE_145 — Agent config home, 3-tier resolution.
+ *
+ * Centralizes the user-config directory used to be hardcoded across
+ * ~30 sites in 6 packages as `path.join(os.homedir(), '.kodax', ...)`.
+ * That pattern had two problems:
+ *
+ *   1. **Drift**: each new caller in a future feature was a fresh
+ *      hardcode site; nothing stopped a caller from using the wrong
+ *      string (`'kodax'` instead of `'.kodax'`, etc.).
+ *   2. **Substrate consumer coupling**: when `@kodax-ai/agent` is reused
+ *      by a downstream agent (e.g. `@kodax-ai/ops-agent`,
+ *      `@kodax-ai/data-analysis-agent`), there was no way to redirect the
+ *      runtime config dir — every derivative agent was forced to
+ *      share the `~/.kodax/` namespace.
+ *
+ * The helper exposes a 3-tier priority chain:
+ *
+ *   1. **Programmatic override** via {@link setAgentConfigHome} —
+ *      highest priority. Substrate consumers call this once at boot,
+ *      before any subsystem reads the path.
+ *   2. **`KODAX_HOME` env var** — middle priority. Used by shell / CI /
+ *      test isolation / multi-tenant shared machines. (Already honored
+ *      historically by `@kodax-ai/llm/src/reasoning-overrides.ts`; this
+ *      helper makes it the canonical path for all packages.)
+ *   3. **`~/.kodax/`** — lowest priority. Default for the standalone
+ *      kodax CLI. With DI not set + env not set, the resolver returns
+ *      the same byte sequence as the prior hardcoded
+ *      `path.join(os.homedir(), '.kodax')` calls — so the migration
+ *      from hardcoded sites to this helper is byte-equivalent for the
+ *      existing user base.
+ *
+ * Why a process-level singleton (and not per-call DI):
+ * the ~30 fs callsites are buried in library helpers (construction /
+ * mcp catalog / oauth tokens / paste-cache etc.). Threading a
+ * `configHome` parameter through every helper would change ~50
+ * function signatures, and every caller would have to remember to
+ * thread it — a single forgotten thread silently falls back to
+ * default. Singleton matches the `process.env.NODE_ENV` pattern: a
+ * process really has a single config home (no legitimate use case
+ * for a process to interleave reads/writes against `~/.kodax/` AND
+ * `~/.opsagent/` simultaneously).
+ *
+ * NOT migrated:
+ *   - `@kodax-ai/llm/src/reasoning-overrides.ts:49` keeps its inline
+ *     `process.env.KODAX_HOME ?? path.join(os.homedir(), '.kodax')`
+ *     fallback because moving it to this helper would create an
+ *     `@kodax-ai/llm → @kodax-ai/agent` dependency cycle (agent already
+ *     imports ai). The two implementations have identical observable
+ *     behavior at the env / default tiers; the programmatic override
+ *     tier doesn't apply to ai-layer code.
+ *   - **Project-relative** `.kodax/` paths (e.g. `path.join(projectRoot,
+ *     '.kodax', 'AGENTS.md')`) are NOT migrated — those name a
+ *     different concept (per-project config) and use a different root.
+ *   - **CWD-relative** subpath constants like `path.join('.kodax',
+ *     'constructed', '_audit.jsonl')` (joined with a project root by
+ *     the caller) are likewise project-scoped and stay as-is.
+ */
+/**
+ * Set the agent config home programmatically. Highest priority in
+ * {@link getAgentConfigHome}'s 3-tier chain.
+ *
+ * Substrate consumers (e.g. an agent built on top of `@kodax-ai/agent`)
+ * should call this once at process boot, before any subsystem reads
+ * the path. Pass `undefined` to reset (used in tests).
+ */
+declare function setAgentConfigHome(path: string | undefined): void;
+/**
+ * Resolve the agent runtime config home directory.
+ *
+ * Priority (high → low):
+ *   1. Programmatic override via {@link setAgentConfigHome}
+ *   2. `KODAX_HOME` env var
+ *   3. `~/.kodax` (hardcoded default)
+ */
+declare function getAgentConfigHome(): string;
+/**
+ * Resolve a sub-path under the agent config home.
+ *
+ * Equivalent to `path.join(getAgentConfigHome(), ...segments)` but
+ * shorter at every callsite (which is the entire point of the helper —
+ * 30 callsites of `path.join(os.homedir(), '.kodax', x, y)` collapse to
+ * 30 callsites of `getAgentConfigPath(x, y)`).
+ */
+declare function getAgentConfigPath(...segments: string[]): string;
+/**
+ * v0.7.42 — Namespaced data directory for third-party apps embedding the
+ * KodaX SDK (e.g. `KodaX Space` desktop client, IDE extensions).
+ *
+ * Returns `${getAgentConfigHome()}/apps/<appId>/` and creates the directory
+ * if missing. Provides a coordination point so multiple SDK consumers can
+ * share `~/.kodax/` without colliding on path conventions.
+ *
+ * Constraints:
+ *   - `appId` must match `^[a-z][a-z0-9-]{1,31}$` (lowercase kebab, 2–32 chars,
+ *     no dots, no slashes, no underscores) — keeps the directory name safe
+ *     across all filesystems and prevents `../` traversal.
+ *   - Reserved prefixes (`kodax`, `kodax-*`) are rejected to leave room
+ *     for first-party feature directories that may collide later.
+ *
+ * The convention is intentionally light — no central registry, no manifest.
+ * Apps owning their data dir means SDK upgrades cannot trample on third-party
+ * state. Apps are responsible for migration/cleanup within their own subtree.
+ */
+declare function getAppDataDir(appId: string): string;
+
+/**
+ * History cleanup middleware — CAP-002
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-002
+ *
+ * Two pure functions that maintain the assistant↔user `tool_use`/`tool_result`
+ * pairing invariant the provider expects. Both functions take a message array
+ * and return a new array (immutable — never mutate the input).
+ *
+ *   - `cleanupIncompleteToolCalls`: when a stream is interrupted mid-flight,
+ *     the last assistant message may carry orphan `tool_use` blocks with no
+ *     matching `tool_result`. The next provider call would 400 with
+ *     "tool_call_id not found". This function strips those orphans before
+ *     the next request.
+ *
+ *   - `validateAndFixToolHistory`: deeper pass that walks the full message
+ *     history and fixes mis-pairings on both sides — orphan `tool_use` in
+ *     assistant messages, orphan `tool_result` in user messages, and ensures
+ *     no message becomes empty after stripping (Kimi specifically rejects
+ *     empty assistant messages with 400, so we inject a `'...'` placeholder
+ *     when stripping would empty an assistant message).
+ *
+ * Migration history: extracted from `agent.ts` (originally lines 517–758)
+ * during FEATURE_100 P2. Both `agent.ts` and `task-engine/runner-driven.ts`
+ * already consume these via the package re-export (`@kodax-ai/coding`).
+ *
+ * Type guards are inlined here rather than imported from agent.ts because
+ * the migration's whole point is to remove dependencies on agent.ts. If
+ * additional agent-runtime modules need the same guards in the future,
+ * extract them to `agent-runtime/content-blocks.ts`.
+ */
+
+/**
+ * Walk the message history and remove mis-paired `tool_use` / `tool_result`
+ * blocks. Preserves message order and structure; never mutates input.
+ *
+ * Rules enforced:
+ *   - assistant `tool_use` with no matching `tool_result` in the next user
+ *     message → removed
+ *   - assistant `tool_use` with empty / missing id → removed
+ *   - user `tool_result` with no matching assistant `tool_use` in the previous
+ *     message → removed
+ *   - user `tool_result` with empty / missing tool_use_id → removed
+ *   - assistant message that becomes content-empty after stripping → inject
+ *     a `'...'` placeholder text block (preserves message-alternation invariant
+ *     downstream providers like Kimi require)
+ */
+declare function validateAndFixToolHistory(messages: KodaXMessage[]): KodaXMessage[];
+/**
+ * Strip orphan `tool_use` blocks from the LAST assistant message only.
+ *
+ * Used as a quick pre-stream guard when a previous turn was interrupted
+ * (Issue 072): the last assistant message has unanswered tool_use blocks,
+ * and the next provider request would 400 with "tool_call_id not found".
+ *
+ * Cheaper than `validateAndFixToolHistory` because it only touches the tail.
+ */
+declare function cleanupIncompleteToolCalls(messages: KodaXMessage[]): KodaXMessage[];
+
+/**
+ * LineageExtension — SessionExtension façade over lineage semantics.
+ *
+ * FEATURE_081 (v0.7.23): expresses today's `KodaXSessionLineage` operations
+ * (label, rewind, compaction ledger, branch summary) as a
+ * `SessionExtension` over the base `Session` primitive.
+ *
+ * FEATURE_082 (v0.7.24): moved from `@kodax-ai/coding/src/extensions/lineage.ts`
+ * to this package. Depends on `../index.js` for `Session` / `SessionEntry` /
+ * `SessionExtension` (Layer A primitives — extracted to `@kodax-ai/core` in
+ * FEATURE_082, merged back into `../index.js` in v0.7.35.1 FEATURE_142).
+ * `@kodax-ai/coding` keeps a barrel re-export.
+ *
+ * Scope:
+ *   - Declare the extension object.
+ *   - Implement `label` and `attachArtifact` operators that append standard
+ *     entries to a Session.
+ *   - Implement a `buildLineageTree` reducer that projects an entry stream
+ *     back to a navigable tree.
+ *   - NOT re-implemented here: `branch`, `rewind`, full compaction. Those
+ *     stay in `../index.js/session-lineage.ts` for coding-preset use; the
+ *     `LineageCompaction` policy in this package is the thin wrapper that
+ *     adapts them to the Layer A `CompactionPolicy` contract.
+ */
+
+/**
+ * Entry types claimed by `LineageExtension`. Mirrors the legacy
+ * `KodaXSessionEntry` tagged union plus a `rewind_marker` placeholder (the
+ * legacy lineage records rewinds via `activeEntryId` mutation; Session is
+ * linear, so a marker entry is the equivalent).
+ */
+declare const LINEAGE_ENTRY_TYPES: readonly ["message", "label", "compaction", "branch_summary", "archive_marker", "rewind_marker", "artifact_ledger"];
+type LineageEntryType = (typeof LINEAGE_ENTRY_TYPES)[number];
+/**
+ * Payload shape for a `label` entry. Mirrors
+ * `KodaXSessionLabelEntry.targetId`/`label` fields on the legacy lineage.
+ */
+interface LineageLabelPayload {
+    readonly targetId: string;
+    readonly label?: string;
+}
+/**
+ * Payload shape for an `artifact_ledger` entry. Mirrors a minimal subset of
+ * `KodaXSessionArtifactLedgerEntry`; full semantic fidelity is kept on the
+ * legacy side for now and normalised in FEATURE_082.
+ */
+interface LineageArtifactLedgerPayload {
+    readonly ref: string;
+    readonly kind?: string;
+    readonly summary?: string;
+}
+/**
+ * Projected tree node. Mirrors the navigation shape of
+ * `KodaXSessionTreeNode` from `../index.js/types.ts`, restricted to the
+ * fields the base Session can supply.
+ */
+interface LineageTreeNode {
+    readonly entry: SessionEntry;
+    readonly children: LineageTreeNode[];
+    readonly label?: string;
+}
+/**
+ * The exported extension. Operators write standard-shaped entries; the
+ * reducer projects an entry stream back to a navigable tree.
+ *
+ * Immutability: top-level object, `operators`, and `reducers` are all
+ * frozen. Freezes are shallow — the functions stored inside `operators`
+ * and `reducers` are immutable by nature (closures reference only
+ * module-private state). External code must not mutate the extension;
+ * doing so is a programmer error that the type-level `readonly` already
+ * disallows without a cast.
+ */
+declare const LineageExtension: SessionExtension;
+
+/**
+ * LineageCompaction — `CompactionPolicy` adapter for the coding preset's
+ * FEATURE_072 lineage-native compaction runtime.
+ *
+ * FEATURE_082 (v0.7.24): introduced alongside the lineage extraction so the
+ * coding preset can implement `CompactionPolicy` without re-implementing the
+ * compaction loop. The actual compaction runtime (microcompaction, post-
+ * compact reconstruction, summary generation) stays in
+ * `../index.js/src/compaction/` until FEATURE_084 (v0.7.26) consolidates it.
+ *
+ * Usage (inside @kodax-ai/coding):
+ *
+ *   const policy = new LineageCompaction({
+ *     shouldCompact: (session, used, budget) => runFeature072Heuristic(used, budget),
+ *     compact: async (session, ctx) => runFeature072Compaction(session, ctx),
+ *   });
+ *
+ * The injected delegates keep this package free of coding-specific imports,
+ * preserving the dependency direction
+ * `@kodax-ai/coding -> @kodax-ai/session-lineage -> ../index.js`.
+ */
+
+/**
+ * Delegates required to implement `LineageCompaction`. The coding preset
+ * supplies implementations that bridge to the existing FEATURE_072 code
+ * paths.
+ */
+interface LineageCompactionDelegates {
+    readonly shouldCompact: (session: Session, tokensUsed: number, budget: number) => boolean;
+    readonly compact: (session: Session, ctx: CompactionContext) => Promise<PolicyCompactionResult>;
+    readonly restore?: (session: Session, hint: unknown) => Promise<void>;
+}
+/**
+ * `CompactionPolicy` implementation that preserves FEATURE_072 lineage-native
+ * compaction semantics by delegating to injected coding-preset functions.
+ */
+declare class LineageCompaction implements CompactionPolicy {
+    readonly name = "lineage-compaction";
+    private readonly delegates;
+    constructor(delegates: LineageCompactionDelegates);
+    shouldCompact(session: Session, tokensUsed: number, budget: number): boolean;
+    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
+    restore(session: Session, hint: unknown): Promise<void>;
+}
+
+/**
+ * ../index.js Session
+ *
+ * 会话管理 - Session ID 生成和消息处理
+ */
+
+/**
+ * 生成会话 ID
+ * 格式: YYYYMMDD_HHMMSS
+ */
+declare function generateSessionId(): Promise<string>;
+/**
+ * 从消息中提取标题
+ * 取第一条用户消息的前50个字符
+ */
+declare function extractTitleFromMessages(messages: KodaXMessage[]): string;
+
+type NavigableSessionEntry = Exclude<KodaXSessionEntry, KodaXSessionLabelEntry | KodaXSessionGoalEntry>;
+/**
+ * Reconcile a linear message list against an existing lineage tree.
+ *
+ * Existing matching entries are reused when possible, and only the missing
+ * tail is appended as new message entries.
+ */
+declare function createSessionLineage(messages: KodaXMessage[], previous?: KodaXSessionLineage): KodaXSessionLineage;
+/**
+ * Walk the lineage from a target entry back to the root.
+ *
+ * Traversal stops safely if malformed data introduces a parent cycle.
+ */
+declare function getSessionLineagePath(lineage: KodaXSessionLineage, targetId?: string | null): NavigableSessionEntry[];
+/**
+ * Build the effective LLM-visible message context for the active lineage path.
+ *
+ * FEATURE_072: for non-rewind compaction entries that carry
+ * `postCompactAttachments`, the slicer inlines attachments immediately after
+ * the summary. `getContextMessagesForEntry` stays 1-to-1 — attachments are a
+ * slicer-layer concern, which preserves the contract
+ * `entryMatchesContextMessage` and FEATURE_073's future firstKeptEntryId-based
+ * slicing both depend on.
+ */
+declare function getSessionMessagesFromLineage(lineage: KodaXSessionLineage, targetId?: string | null): KodaXMessage[];
+/**
+ * Resolve an entry selector using either a direct entry id or the latest label.
+ */
+declare function resolveSessionLineageTarget(lineage: KodaXSessionLineage, selector: string): NavigableSessionEntry | undefined;
+/**
+ * Move the active leaf to a selected target, optionally appending a
+ * branch-summary node that captures the abandoned path.
+ */
+declare function setSessionLineageActiveEntry(lineage: KodaXSessionLineage, selector: string, options?: KodaXSessionNavigationOptions): KodaXSessionLineage | null;
+/**
+ * Append a label change entry that bookmarks a lineage node.
+ */
+declare function appendSessionLineageLabel(lineage: KodaXSessionLineage, selector: string, label?: string): KodaXSessionLineage | null;
+/**
+ * Apply a compaction event to the lineage.
+ *
+ * FEATURE_072 signature change: `keptMessages` (the post-summary tail that
+ * will become lineage entries) and `postCompactAttachments` (ledger +
+ * file-content messages that live on the CompactionEntry itself) are now
+ * separate parameters. The kept tail MUST NOT include attachments — otherwise
+ * they would be double-stored (once as message entries in lineage, once on
+ * the compaction entry). Phase A keeps `postCompactAttachments` optional so
+ * current callers that pass `[]` (or omit it) behave identically to today.
+ * Phase B migrates callers to supply real attachments.
+ */
+declare function applySessionCompaction(lineage: KodaXSessionLineage | undefined, compactedMessages: KodaXMessage[], anchor: {
+    summary: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    artifactLedgerId?: string;
+    reason?: string;
+    details?: KodaXJsonValue | CompactionDetails;
+    memorySeed?: KodaXCompactMemorySeed;
+}, postCompactAttachments?: readonly KodaXMessage[]): KodaXSessionLineage;
+/**
+ * FEATURE_072 §7a: reconcile lineage after graceful-degradation trimming.
+ *
+ * Unlike `applySessionCompaction` (which creates a new island with a summary
+ * CompactionEntry), graceful degradation is atomic-block trimming — no LLM
+ * summary, no ledger re-injection. Routing it through `applySessionCompaction`
+ * would produce a degenerate CompactionEntry with `summary: ''` that pollutes
+ * the lineage view and session-tree UI.
+ *
+ * Instead, `applyLineageTruncation` reconciles the lineage against the trimmed
+ * flat messages via `createSessionLineage`, which will:
+ *   - Match surviving messages to existing entries (reference or fingerprint)
+ *   - Drop unmatched entries from the active path
+ * Fingerprint lookup handles the "trimmed tool_result content changed" case:
+ * the trimmed message gets a new entry id under the same parent chain.
+ *
+ * This is distinct from `applySessionCompaction`: no new CompactionEntry is
+ * appended, no summary is written, no island root is created. The lineage
+ * stays on the same island; only the tail shape changes.
+ *
+ * Reserved for a future caller (v0.7.20 Phase C / v0.7.25 FEATURE_073). Phase B
+ * defines the helper; no production caller yet.
+ */
+declare function applyLineageTruncation(lineage: KodaXSessionLineage | undefined, trimmedMessages: KodaXMessage[]): KodaXSessionLineage;
+/**
+ * Rewind the current session lineage to a target entry, truncating all entries after it.
+ * Records a rewind event in the lineage for auditability.
+ * Returns null if targetEntryId is not found.
+ *
+ * @param lineage - The session lineage to rewind
+ * @param targetEntryId - The entry ID to rewind to (inclusive)
+ * @returns A new lineage with entries truncated after the target, or null if target not found
+ */
+/**
+ * Find the entry ID of the second-to-last user message in the lineage.
+ * Used by `/rewind` (no argument) to go back one conversational turn.
+ * Returns null if fewer than 2 user messages exist.
+ */
+declare function findPreviousUserEntryId(lineage: KodaXSessionLineage): string | null;
+declare function rewindSessionLineage(lineage: KodaXSessionLineage, targetEntryId: string): KodaXSessionLineage | null;
+declare function forkSessionLineage(lineage: KodaXSessionLineage, selector?: string): KodaXSessionLineage | null;
+/**
+ * Convert a lineage into a nested tree structure for UI presentation.
+ */
+declare function buildSessionTree(lineage: KodaXSessionLineage): KodaXSessionTreeNode[];
+/**
+ * Count the effective context messages on the active lineage path.
+ */
+declare function countActiveLineageMessages(lineage: KodaXSessionLineage): number;
+/**
+ * Archive message entries from old "islands" (disconnected subtrees).
+ *
+ * Each compaction entry has parentId: null, creating an independent island.
+ * The active leaf lives in one island (the "current" island). All other
+ * islands are considered "old" and eligible for archival.
+ *
+ * A "preserve closure" is computed first:
+ *  - All entries in the current island (active path + recent branches)
+ *  - Label targets and their ancestor chains
+ *  - Non-message entries and their ancestor chains (prevents tree drift)
+ *
+ * Only entries outside the preserve closure are archived.
+ */
+declare function archiveOldIslands(lineage: KodaXSessionLineage): {
+    slimmedLineage: KodaXSessionLineage;
+    archivedEntries: KodaXSessionEntry[];
+    archivedCount: number;
+    archiveBatchId: string;
+};
+
+/**
+ * ../../index.js File Tracking — artifactLedger extraction.
+ *
+ * FEATURE_185 (v0.7.42) extends the previous input-only extractor to also
+ * read each tool_use's matching tool_result, enriching `metadata` with parsed
+ * hits / matchedPaths / exitCode / tail. Pipeline:
+ *
+ *   Round end (REPL: repl.ts:1279/1371)
+ *     → extractArtifactLedger(result.messages)
+ *     → tool_result still raw (top-of-loop microcompact hasn't run on these)
+ *     → buildArtifactEntry parses result content into metadata
+ *     → mergeArtifactLedger commits enrichment to context.artifactLedger
+ *     → storage.save persists the enriched ledger
+ *
+ *   Top-of-loop microcompact (run-substrate.ts:621, iteration N+1)
+ *     → clears tool_result.content older than maxAge to `[Cleared: ...]`
+ *
+ *   Compaction time (compaction.ts:257)
+ *     → extractArtifactLedger(toProcess) re-runs on cleared messages
+ *     → buildArtifactEntry's parsers refuse `[Cleared: ...]` → no fresh hits
+ *     → mergeArtifactLedger preserves the round-end enrichment via
+ *       per-key non-empty preference (see `mergeLedgerMetadata`).
+ *
+ * The metadata-aware merge is the keystone — without it, every compaction
+ * would silently downgrade ledger entries to input-only. End-to-end
+ * preservation is exercised by the "end-to-end enrichment survives
+ * microcompact" tests in file-tracker.test.ts.
+ */
+
+declare function extractFileOps(messages: KodaXMessage[]): FileOperations;
+declare function mergeFileOps(ops1: FileOperations, ops2: FileOperations): FileOperations;
+declare function extractArtifactLedger(messages: KodaXMessage[]): KodaXSessionArtifactLedgerEntry[];
+declare function mergeArtifactLedger(existing: KodaXSessionArtifactLedgerEntry[], next: KodaXSessionArtifactLedgerEntry[]): KodaXSessionArtifactLedgerEntry[];
+
+export { countActiveLineageMessages as A, countTokens as B, DefaultSummaryCompaction as D, createSessionLineage as E, estimateTokens as F, extractArtifactLedger as G, extractFileOps as H, extractTitleFromMessages as I, findPreviousUserEntryId as J, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, forkSessionLineage as M, generateSessionId as N, getAgentConfigHome as O, PROMISE_PATTERN as P, getAgentConfigPath as Q, getAppDataDir as R, getSessionLineagePath as S, getSessionMessagesFromLineage as T, mergeArtifactLedger as U, mergeFileOps as V, resolveSessionLineageTarget as W, rewindSessionLineage as X, setAgentConfigHome as Y, setSessionLineageActiveEntry as Z, validateAndFixToolHistory as _, KODAX_DEFAULT_TIMEOUT as e, KODAX_HARD_TIMEOUT as f, KODAX_MAX_INCOMPLETE_RETRIES as g, KODAX_MAX_MAXTOKENS_RETRIES as h, KODAX_MAX_RETRIES as i, KODAX_MAX_TOKENS as j, KODAX_RETRY_BASE_DELAY as k, KODAX_STAGGER_DELAY as l, LineageCompaction as n, LineageExtension as q, appendSessionLineageLabel as u, applyLineageTruncation as v, applySessionCompaction as w, archiveOldIslands as x, buildSessionTree as y, cleanupIncompleteToolCalls as z };
+export type { CompactionContext as C, CompactionEntry as a, CompactionEntryPayload as b, CompactionPolicy as c, DefaultSummaryCompactionOptions as d, LineageArtifactLedgerPayload as m, LineageCompactionDelegates as o, LineageEntryType as p, LineageLabelPayload as r, LineageTreeNode as s, PolicyCompactionResult as t };