@kodax-ai/kodax 0.7.41 → 0.7.43

package/dist/types-chunks/{history-cleanup.d-q1vAvCss.d.ts → file-tracker.d-zaLZeNBK.d.ts}

@@ -1,5 +1,6 @@
-import { o as KodaXMessage } from './capability.d-BxNgd1-c.js';
-import { a as AgentMessage, a7 as SpanData, a6 as Span, a8 as SpanError, A as Agent, _ as RunnerLlmReturn, G as Guardrail, a1 as RunnerToolObserver } from './instance-discovery.d-DZhp77vb.js';
+import { m as KodaXMessage } from './types.d-B1uGoVTE.js';
+import { a as AgentMessage, V as SpanData, U as Span, W as SpanError, A as Agent, J as RunnerLlmReturn, o as Guardrail, N as RunnerToolObserver, h as CompactionDetails, n as FileOperations } from './types.d-CKJtjo-6.js';
+import { o as KodaXSessionLineage, f as KodaXJsonValue, a as KodaXCompactMemorySeed, l as KodaXSessionEntry, v as KodaXSessionTreeNode, n as KodaXSessionLabelEntry, r as KodaXSessionNavigationOptions, h as KodaXSessionArtifactLedgerEntry } from './types.d-mM8vqvhT.js';
 
 /**
  * @kodax-ai/agent Constants
@@ -42,7 +43,7 @@ declare function countTokens(text: string): number;
  * Layer A Primitive: Session / SessionEntry / MessageEntry / SessionExtension
  *
  * FEATURE_081 (v0.7.23): Base Session shape. The thick
- * `KodaXSessionLineage` lives in `@kodax-ai/session-lineage` and is re-expressed
+ * `KodaXSessionLineage` lives in `../session-lineage/index.js` and is re-expressed
  * as a `LineageExtension` over this base.
  *
  * History: extracted to `@kodax-ai/core` in FEATURE_082 (v0.7.24); merged back
@@ -141,7 +142,7 @@ interface InMemorySessionOptions {
 /**
  * In-memory Session suitable for tests, examples, and embedded SDK use. Not
  * durable across process restarts — persistence is provided by coding-specific
- * adapters in `@kodax-ai/session-lineage` and `@kodax-ai/agent`.
+ * adapters in `../session-lineage/index.js` and `@kodax-ai/agent`.
  */
 declare function createInMemorySession(opts?: InMemorySessionOptions): Session;
 
@@ -154,7 +155,7 @@ declare function createInMemorySession(opts?: InMemorySessionOptions): Session;
  *   - 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 (`@kodax-ai/session-lineage/src/lineage.ts`): `LineageCompaction`
+ *   - Layer B (`../session-lineage/index.js/src/lineage.ts`): `LineageCompaction`
  *     wraps the full FEATURE_072 lineage-native compaction for the coding
  *     preset.
  *
@@ -300,6 +301,12 @@ interface TraceOptions {
     readonly onSpanEnd?: (span: Span) => void;
     readonly onTraceEnd?: (trace: Trace) => void;
 }
+/**
+ * In-memory Trace implementation. External consumers can replace this with
+ * an adapter (OpenTelemetry Trace, Langfuse trace) by registering their own
+ * `TracingProcessor`.
+ */
+declare function createTrace(opts?: TraceOptions): Trace;
 
 /**
  * Tracer — convenience façade that creates Traces wired to the registered
@@ -333,6 +340,8 @@ declare class Tracer {
     constructor(options?: TracerOptions);
     startTrace(opts?: StartTraceOptions): Trace;
 }
+/** Default tracer shared by the KodaX runtime. External callers can create their own. */
+declare const defaultTracer: Tracer;
 
 /**
  * Layer A Primitive: Quality Invariant + Admission Contract types.
@@ -977,14 +986,34 @@ interface RunOptions {
      */
     readonly toolObserver?: RunnerToolObserver;
     /**
-     * v0.7.26 parity: compaction hook. Called AFTER each iteration's
-     * tool_result has been appended to the transcript (or after the
-     * assistant message when there are no tool calls), before the next
-     * LLM turn. Return the replacement transcript to trigger compaction;
-     * return the same array (or undefined) to skip. Legacy agent.ts ran
-     * `intelligentCompact` on the same boundary, so Runner-driven parity
-     * requires this hook point. The Runner owns the transcript mutably,
-     * so this is the only point consumers can insert a compacted view.
+     * Compaction hook. Fires at the TOP of every tool-loop iteration,
+     * BEFORE the LLM call. Return the replacement transcript to trigger
+     * compaction; return the same array (or undefined) to skip. The Runner
+     * owns the transcript mutably, so this is the only point consumers can
+     * insert a compacted view before the next provider.stream invocation.
+     *
+     * **Trigger frequency**: every iteration of every Runner.run() call.
+     * - Iteration 0 fires BEFORE the first LLM call (covers idle-yield
+     *   resume / new user activation where the transcript already exceeds
+     *   threshold from accumulated prior turns).
+     * - Iteration N (N≥1) fires after the previous iteration's tool_result
+     *   was appended, same "before next LLM call" timing as the legacy
+     *   post-tool-result firing point.
+     * - Text-only iterations are covered: the next Runner.run() invocation
+     *   (when the user/parent re-engages) runs iter 0 → hook fires before
+     *   the new LLM call.
+     *
+     * **Why not after tool_result append (legacy v0.7.26 location)**: that
+     * boundary skipped text-only termination — Runner exits at line ~611
+     * without firing the hook, so idle-yield + text-only end-of-turn
+     * sessions grew unbounded between checks. claudecode (`query.ts:307-454`),
+     * pi-mono (`agent-session.ts:949`), opencode (`processor.ts:609-613`),
+     * and KodaX SA (`run-substrate.ts:621-627`) all check at the per-LLM-
+     * call boundary. FEATURE_179 (v0.7.42) brought the AMA Runner path
+     * into line — the failure scenario was a Worker session that grew
+     * 165K → 180K through text-only end-of-turn + idle-yield, then
+     * triggered at 181K (61K over the 120K threshold) only after the next
+     * tool call landed.
      */
     readonly compactionHook?: (transcript: readonly AgentMessage[]) => Promise<readonly AgentMessage[] | undefined>;
     /**
@@ -1090,7 +1119,84 @@ interface RunOptions {
         readonly to: Agent;
         readonly iteration: number;
     }) => void | Promise<void>;
+    /**
+     * FEATURE_184 (v0.7.45) — Stop Hook primitive.
+     *
+     * Fires when the model terminates a turn with no `tool_use` blocks
+     * (text-only response). The hook receives the post-output-guardrail
+     * transcript and the final assistant text, and returns one of:
+     *
+     * - `undefined` → accept the termination, fall through to the normal
+     *   terminal path (assertTerminal + return). This is the no-op default.
+     * - `string` → "blockingErrors" / reanimate. Runner synthesizes a
+     *   `{role: 'user', content: <string>}` message, appends it to the
+     *   transcript + session, and continues the loop. Bounded by
+     *   `stopHookReanimateBudget` (default 2); exceeded budget converts
+     *   the string return to a forced abort.
+     * - `{abort: true, reason}` → preventContinuation / halt-and-surface.
+     *   Run returns immediately with `output = reason` and
+     *   `stoppedByHook = true`. assertTerminal still fires before the
+     *   return so invariant violations on the halted state surface
+     *   normally.
+     *
+     * Errors thrown by the hook are caught and treated as `undefined`
+     * (fail-open). A span is emitted for observability. Matches the
+     * `compactionHook` failure semantics — a buggy hook must never
+     * abort the run.
+     *
+     * Design reference: claudecode `query.ts:1282-1305` blockingErrors +
+     * `query.ts:1278` preventContinuation. Generalizes the deterministic
+     * shell-script Stop hook surface to an LLM-driven Sidecar Verifier
+     * (the v0.7.45 first consumer; see FEATURE_184 Phase D).
+     */
+    readonly stopHook?: StopHookFn;
+    /**
+     * FEATURE_184 (v0.7.45) — Reanimate budget for `stopHook`. Default 2.
+     *
+     * When `stopHook` returns a string AND `reanimateCount` has already
+     * reached this budget, the string return is forcibly converted to an
+     * abort with reason `"reanimate budget exhausted: <string>"`. Prevents
+     * unbounded reanimate loops when the hook + model disagree on
+     * completion forever.
+     */
+    readonly stopHookReanimateBudget?: number;
 }
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook context handed to the caller's
+ * `stopHook` when the model terminates a turn text-only.
+ */
+interface StopHookContext {
+    /** Transcript snapshot at the moment the hook fires. Includes the
+     *  just-pushed final assistant message. Readonly — the hook must not
+     *  mutate; to influence the run return a `string` (reanimate) or
+     *  `{abort, reason}` instead. */
+    readonly transcript: readonly AgentMessage[];
+    /** Convenience field: the final assistant message's text content. */
+    readonly lastAssistantText: string;
+    /** Why the turn ended. For Phase A this is always `'natural-end'`
+     *  (model emitted no `tool_use`). Future signal sources (explicit
+     *  COMPLETE protocol emission, harness-injected stop) can extend
+     *  the union without breaking existing hooks. */
+    readonly signal: 'natural-end';
+    /** How many times the hook has already reanimated this run. Starts
+     *  at 0; incremented after each `string` return. Hooks can use this
+     *  for telemetry but enforcement is Runner-side. */
+    readonly reanimateCount: number;
+    /** Total reanimate budget for this run (`stopHookReanimateBudget`
+     *  or default 2). Exposed for transparency. */
+    readonly reanimateBudget: number;
+}
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook return surface.
+ */
+type StopHookResult = undefined | string | {
+    readonly abort: true;
+    readonly reason: string;
+};
+/**
+ * FEATURE_184 (v0.7.45) — Stop hook signature.
+ */
+type StopHookFn = (ctx: StopHookContext) => StopHookResult | Promise<StopHookResult>;
 /**
  * Result returned by `Runner.run`.
  */
@@ -1099,6 +1205,12 @@ interface RunResult<TData = unknown> {
     readonly messages: readonly AgentMessage[];
     readonly sessionId?: string;
     readonly data?: TData;
+    /** FEATURE_184 (v0.7.45): `true` when the run terminated because
+     *  the caller's `stopHook` returned `{abort: true}` OR because the
+     *  hook's `string` return exceeded `stopHookReanimateBudget`. The
+     *  abort reason is in `output`. Sidecar Verifier sets this when it
+     *  outputs a `blocked` verdict (halt + surface to user). */
+    readonly stoppedByHook?: boolean;
 }
 /**
  * Stream events emitted by `Runner.runStream`. The event surface is
@@ -1203,6 +1315,112 @@ declare class Runner {
 /** @internal Exposed so preset dispatchers can extract the assistant text from a KodaXResult. */
 declare function extractAssistantTextFromMessage(message: AgentMessage): string;
 
+/**
+ * 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
  *
@@ -1262,5 +1480,304 @@ declare function validateAndFixToolHistory(messages: KodaXMessage[]): KodaXMessa
  */
 declare function cleanupIncompleteToolCalls(messages: KodaXMessage[]): KodaXMessage[];
 
-export { cleanupIncompleteToolCalls as $, DEFAULT_SYSTEM_CAP as D, Runner as G, KODAX_API_MIN_INTERVAL as K, PROMISE_PATTERN as P, _resetPresetDispatchers as Y, buildSystemPrompt as Z, _resetAdmittedAgentBindings as _, countTokens as a0, createInMemorySession as a1, createInvariantSessionForAgent as a2, detectInstructionsInjection as a3, estimateTokens as a4, extractAssistantTextFromMessage as a5, getAdmittedAgentBindings as a6, registerPresetDispatcher as a7, runAdmissionAudit as a8, setAdmittedAgentBindings as a9, validateAndFixToolHistory as aa, DefaultSummaryCompaction as h, InvariantSession as m, KODAX_DEFAULT_TIMEOUT as n, KODAX_HARD_TIMEOUT as o, KODAX_MAX_INCOMPLETE_RETRIES as p, KODAX_MAX_MAXTOKENS_RETRIES as q, KODAX_MAX_RETRIES as r, KODAX_MAX_TOKENS as s, KODAX_RETRY_BASE_DELAY as t, KODAX_STAGGER_DELAY as u };
-export type { AdmissionAuditOptions as A, RunEvent as B, CompactionContext as C, RunOptions as E, RunResult as F, RunnerEvent as H, InMemorySessionOptions as I, SessionDispatchResult as J, SessionEntry as L, ManifestPatch as M, SessionExtension as N, ObserveCtx as O, QualityInvariant as Q, ReadonlyMutationTracker as R, Session as S, SessionForkOptions as T, SystemCap as U, TerminalCtx as V, ToolCapability as W, ToolPermission as X, AdmissionCtx as a, AdmissionVerdict as b, AdmittedHandle as c, AgentManifest as d, CompactionEntry as e, CompactionEntryPayload as f, CompactionPolicy as g, DefaultSummaryCompactionOptions as i, Deliverable as j, InvariantId as k, InvariantResult as l, MessageEntry as v, PolicyCompactionResult as w, PresetDispatcher as x, PresetTracingContext as y, ReadonlyRecorder as z };
+/**
+ * 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>;
+/**
+ * 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 { DEFAULT_SYSTEM_CAP as D, KODAX_API_MIN_INTERVAL as K, LINEAGE_ENTRY_TYPES as L, PROMISE_PATTERN as P, Runner as V, generateSessionId as aA, getAdmittedAgentBindings as aB, getAgentConfigHome as aC, getAgentConfigPath as aD, getAppDataDir as aE, getSessionLineagePath as aF, getSessionMessagesFromLineage as aG, mergeArtifactLedger as aH, mergeFileOps as aI, registerPresetDispatcher as aJ, resolveSessionLineageTarget as aK, rewindSessionLineage as aL, runAdmissionAudit as aM, setAdmittedAgentBindings as aN, setAgentConfigHome as aO, setSessionLineageActiveEntry as aP, validateAndFixToolHistory as aQ, Tracer as aa, _resetAdmittedAgentBindings as ac, _resetPresetDispatchers as ad, appendSessionLineageLabel as ae, applyLineageTruncation as af, applySessionCompaction as ag, archiveOldIslands as ah, buildSessionTree as ai, buildSystemPrompt as aj, cleanupIncompleteToolCalls as ak, countActiveLineageMessages as al, countTokens as am, createInMemorySession as an, createInvariantSessionForAgent as ao, createSessionLineage as ap, createTrace as aq, defaultTracer as ar, detectInstructionsInjection as as, estimateTokens as at, extractArtifactLedger as au, extractAssistantTextFromMessage as av, extractFileOps as aw, extractTitleFromMessages as ax, findPreviousUserEntryId as ay, forkSessionLineage as az, DefaultSummaryCompaction as h, InvariantSession as m, KODAX_DEFAULT_TIMEOUT as n, KODAX_HARD_TIMEOUT as o, KODAX_MAX_INCOMPLETE_RETRIES as p, KODAX_MAX_MAXTOKENS_RETRIES as q, KODAX_MAX_RETRIES as r, KODAX_MAX_TOKENS as s, KODAX_RETRY_BASE_DELAY as t, KODAX_STAGGER_DELAY as u, LineageCompaction as w, LineageExtension as z };
+export type { SessionForkOptions as $, AdmissionAuditOptions as A, LineageLabelPayload as B, CompactionContext as C, LineageTreeNode as E, MessageEntry as F, PolicyCompactionResult as G, PresetDispatcher as H, InMemorySessionOptions as I, PresetTracingContext as J, ManifestPatch as M, ReadonlyRecorder as N, ObserveCtx as O, QualityInvariant as Q, ReadonlyMutationTracker as R, RunEvent as S, RunOptions as T, RunResult as U, RunnerEvent as W, Session as X, SessionDispatchResult as Y, SessionEntry as Z, SessionExtension as _, AdmissionCtx as a, StartTraceOptions as a0, StopHookContext as a1, StopHookFn as a2, StopHookResult as a3, SystemCap as a4, TerminalCtx as a5, ToolCapability as a6, ToolPermission as a7, Trace as a8, TraceOptions as a9, TracerOptions as ab, AdmissionVerdict as b, AdmittedHandle as c, AgentManifest as d, CompactionEntry as e, CompactionEntryPayload as f, CompactionPolicy as g, DefaultSummaryCompactionOptions as i, Deliverable as j, InvariantId as k, InvariantResult as l, LineageArtifactLedgerPayload as v, LineageCompactionDelegates as x, LineageEntryType as y };