@kodax-ai/kodax 0.7.42 → 0.7.43

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

@@ -1,5 +1,6 @@
 import { m as KodaXMessage } from './types.d-B1uGoVTE.js';
-import { a as AgentMessage, x as SpanData, w as Span, y as SpanError, A as Agent, q as RunnerLlmReturn, G as Guardrail, t as RunnerToolObserver } from './instance-discovery.d-BsKnIwpg.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.
@@ -1471,5 +1480,304 @@ declare function validateAndFixToolHistory(messages: KodaXMessage[]): KodaXMessa
  */
 declare function cleanupIncompleteToolCalls(messages: KodaXMessage[]): KodaXMessage[];
 
-export { _resetAdmittedAgentBindings as $, DEFAULT_SYSTEM_CAP as D, Runner as G, KODAX_API_MIN_INTERVAL as K, PROMISE_PATTERN as P, _resetPresetDispatchers as a0, buildSystemPrompt as a1, cleanupIncompleteToolCalls as a2, countTokens as a3, createInMemorySession as a4, createInvariantSessionForAgent as a5, detectInstructionsInjection as a6, estimateTokens as a7, extractAssistantTextFromMessage as a8, getAdmittedAgentBindings as a9, getAgentConfigHome as aa, getAgentConfigPath as ab, getAppDataDir as ac, registerPresetDispatcher as ad, runAdmissionAudit as ae, setAdmittedAgentBindings as af, setAgentConfigHome as ag, validateAndFixToolHistory as ah, 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, StopHookContext as U, StopHookFn as V, StopHookResult as W, SystemCap as X, TerminalCtx as Y, ToolCapability as Z, ToolPermission as _, 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 };