@kodax-ai/kodax 0.7.41 → 0.7.43

package/dist/sdk-agent.d.ts

@@ -1,10 +1,130 @@
-import { A as Agent, H as Handoff, $ as RunnerToolCall, a2 as RunnerToolResult, a6 as Span, a as AgentMessage, C as ChildTaskRegistry, D as DiscoveredInstance, a4 as SessionMeta, a5 as SessionStateSnapshot, aa as StateWriterFs, k as InstanceDiscoveryFs, a9 as StateWriter } from './types-chunks/instance-discovery.d-DZhp77vb.js';
-export { b as AgentMiddlewareDeclaration, c as AgentReasoningProfile, d as AgentTool, e as CurrentTodoSummary, f as DiscoveryOptions, G as Guardrail, g as GuardrailBlockedError, h as GuardrailContext, i as GuardrailEscalateError, j as GuardrailVerdict, I as InputGuardrail, K as KodaXCompactMemoryProgress, l as KodaXCompactMemorySeed, m as KodaXExtensionSessionRecord, n as KodaXExtensionSessionState, o as KodaXExtensionStore, p as KodaXExtensionStoreEntry, q as KodaXJsonValue, r as KodaXSessionArchiveMarkerEntry, s as KodaXSessionArtifactLedgerEntry, t as KodaXSessionBranchSummaryEntry, u as KodaXSessionCompactionEntry, v as KodaXSessionData, w as KodaXSessionEntry, x as KodaXSessionEntryBase, y as KodaXSessionLabelEntry, z as KodaXSessionLineage, B as KodaXSessionMessageEntry, E as KodaXSessionMeta, F as KodaXSessionNavigationOptions, J as KodaXSessionRuntimeInfo, L as KodaXSessionScope, M as KodaXSessionStorage, N as KodaXSessionTreeNode, O as KodaXSessionUiHistoryItem, P as KodaXSessionUiHistoryItemType, Q as KodaXSessionWorkspaceKind, R as MAX_TOOL_LOOP_ITERATIONS, S as OutputGuardrail, T as PersistedSessionState, U as ReasoningDepth, V as RecentlyModifiedFile, W as RequestTaskStopOptions, X as RequestTaskStopResult, Y as RunnableTool, Z as RunnerLlmResult, _ as RunnerLlmReturn, a0 as RunnerToolContext, a1 as RunnerToolObserver, a3 as SessionErrorMetadata, ab as StateWriterOptions, ac as TaskAbortRegistry, ad as ToolBeforeOutcome, ae as ToolGuardrail, af as buildAssistantMessageFromLlmResult, ag as buildToolResultMessage, ah as collectGuardrails, ai as createAgent, aj as createHandoff, ak as createStateWriter, al as discoverInstances, am as executeRunnerToolCall, an as isRunnableTool, ao as isRunnerLlmResult, ap as registerChildTask, aq as requestTaskStop, ar as runInputGuardrails, as as runOutputGuardrails, at as runToolAfterGuardrails, au as runToolBeforeGuardrails } from './types-chunks/instance-discovery.d-DZhp77vb.js';
-import { d as AgentManifest, M as ManifestPatch, k as InvariantId, Q as QualityInvariant } from './types-chunks/history-cleanup.d-q1vAvCss.js';
-export { A as AdmissionAuditOptions, a as AdmissionCtx, b as AdmissionVerdict, c as AdmittedHandle, C as CompactionContext, e as CompactionEntry, f as CompactionEntryPayload, g as CompactionPolicy, D as DEFAULT_SYSTEM_CAP, h as DefaultSummaryCompaction, i as DefaultSummaryCompactionOptions, j as Deliverable, I as InMemorySessionOptions, l as InvariantResult, m as InvariantSession, K as KODAX_API_MIN_INTERVAL, n as KODAX_DEFAULT_TIMEOUT, o as KODAX_HARD_TIMEOUT, p as KODAX_MAX_INCOMPLETE_RETRIES, q as KODAX_MAX_MAXTOKENS_RETRIES, r as KODAX_MAX_RETRIES, s as KODAX_MAX_TOKENS, t as KODAX_RETRY_BASE_DELAY, u as KODAX_STAGGER_DELAY, v as MessageEntry, O as ObserveCtx, P as PROMISE_PATTERN, w as PolicyCompactionResult, x as PresetDispatcher, y as PresetTracingContext, R as ReadonlyMutationTracker, z as ReadonlyRecorder, B as RunEvent, E as RunOptions, F as RunResult, G as Runner, H as RunnerEvent, S as Session, J as SessionDispatchResult, L as SessionEntry, N as SessionExtension, T as SessionForkOptions, U as SystemCap, V as TerminalCtx, W as ToolCapability, X as ToolPermission, _ as _resetAdmittedAgentBindings, Y as _resetPresetDispatchers, Z as buildSystemPrompt, $ as cleanupIncompleteToolCalls, a0 as countTokens, a1 as createInMemorySession, a2 as createInvariantSessionForAgent, a3 as detectInstructionsInjection, a4 as estimateTokens, a5 as extractAssistantTextFromMessage, a6 as getAdmittedAgentBindings, a7 as registerPresetDispatcher, a8 as runAdmissionAudit, a9 as setAdmittedAgentBindings, aa as validateAndFixToolHistory } from './types-chunks/history-cleanup.d-q1vAvCss.js';
-import { o as KodaXMessage } from './types-chunks/capability.d-BxNgd1-c.js';
-export { C as CapabilityKind, a as CapabilityProvider, b as CapabilityResult, g as KodaXAssuranceIntent, i as KodaXContentBlock, k as KodaXExecutionMode, l as KodaXExecutionPattern, n as KodaXImageBlock, q as KodaXMutationSurface, t as KodaXProviderConfig, B as KodaXProviderStreamOptions, F as KodaXReasoningCapability, G as KodaXReasoningMode, I as KodaXReasoningRequest, J as KodaXRedactedThinkingBlock, M as KodaXRiskLevel, N as KodaXStreamResult, O as KodaXTaskActionability, P as KodaXTaskBudgetOverrides, Q as KodaXTaskComplexity, R as KodaXTaskFamily, S as KodaXTaskRoutingDecision, T as KodaXTaskType, U as KodaXTaskWorkIntent, V as KodaXTextBlock, W as KodaXThinkingBlock, X as KodaXThinkingBudgetMap, Y as KodaXThinkingDepth, Z as KodaXTokenUsage, _ as KodaXToolDefinition, $ as KodaXToolResultBlock, a0 as KodaXToolUseBlock } from './types-chunks/capability.d-BxNgd1-c.js';
+import { h as KodaXSessionArtifactLedgerEntry, d as KodaXExtensionStore, e as KodaXExtensionStoreEntry, f as KodaXJsonValue } from './types-chunks/types.d-mM8vqvhT.js';
+export { K as KodaXCompactMemoryProgress, a as KodaXCompactMemorySeed, b as KodaXExtensionSessionRecord, c as KodaXExtensionSessionState, g as KodaXSessionArchiveMarkerEntry, i as KodaXSessionBranchSummaryEntry, j as KodaXSessionCompactionEntry, k as KodaXSessionData, l as KodaXSessionEntry, m as KodaXSessionEntryBase, n as KodaXSessionLabelEntry, o as KodaXSessionLineage, p as KodaXSessionMessageEntry, q as KodaXSessionMeta, r as KodaXSessionNavigationOptions, s as KodaXSessionRuntimeInfo, t as KodaXSessionScope, u as KodaXSessionStorage, v as KodaXSessionTreeNode, w as KodaXSessionUiHistoryItem, x as KodaXSessionUiHistoryItemType, y as KodaXSessionWorkspaceKind, S as SessionErrorMetadata } from './types-chunks/types.d-mM8vqvhT.js';
+import { a8 as Trace, d as AgentManifest, M as ManifestPatch, k as InvariantId, Q as QualityInvariant } from './types-chunks/file-tracker.d-zaLZeNBK.js';
+export { A as AdmissionAuditOptions, a as AdmissionCtx, b as AdmissionVerdict, c as AdmittedHandle, C as CompactionContext, e as CompactionEntry, f as CompactionEntryPayload, g as CompactionPolicy, D as DEFAULT_SYSTEM_CAP, h as DefaultSummaryCompaction, i as DefaultSummaryCompactionOptions, j as Deliverable, I as InMemorySessionOptions, l as InvariantResult, m as InvariantSession, K as KODAX_API_MIN_INTERVAL, n as KODAX_DEFAULT_TIMEOUT, o as KODAX_HARD_TIMEOUT, p as KODAX_MAX_INCOMPLETE_RETRIES, q as KODAX_MAX_MAXTOKENS_RETRIES, r as KODAX_MAX_RETRIES, s as KODAX_MAX_TOKENS, t as KODAX_RETRY_BASE_DELAY, u as KODAX_STAGGER_DELAY, L as LINEAGE_ENTRY_TYPES, v as LineageArtifactLedgerPayload, w as LineageCompaction, x as LineageCompactionDelegates, y as LineageEntryType, z as LineageExtension, B as LineageLabelPayload, E as LineageTreeNode, F as MessageEntry, O as ObserveCtx, P as PROMISE_PATTERN, G as PolicyCompactionResult, H as PresetDispatcher, J as PresetTracingContext, R as ReadonlyMutationTracker, N as ReadonlyRecorder, S as RunEvent, T as RunOptions, U as RunResult, V as Runner, W as RunnerEvent, X as Session, Y as SessionDispatchResult, Z as SessionEntry, _ as SessionExtension, $ as SessionForkOptions, a0 as StartTraceOptions, a1 as StopHookContext, a2 as StopHookFn, a3 as StopHookResult, a4 as SystemCap, a5 as TerminalCtx, a6 as ToolCapability, a7 as ToolPermission, a9 as TraceOptions, aa as Tracer, ab as TracerOptions, ac as _resetAdmittedAgentBindings, ad as _resetPresetDispatchers, ae as appendSessionLineageLabel, af as applyLineageTruncation, ag as applySessionCompaction, ah as archiveOldIslands, ai as buildSessionTree, aj as buildSystemPrompt, ak as cleanupIncompleteToolCalls, al as countActiveLineageMessages, am as countTokens, an as createInMemorySession, ao as createInvariantSessionForAgent, ap as createSessionLineage, aq as createTrace, ar as defaultTracer, as as detectInstructionsInjection, at as estimateTokens, au as extractArtifactLedger, av as extractAssistantTextFromMessage, aw as extractFileOps, ax as extractTitleFromMessages, ay as findPreviousUserEntryId, az as forkSessionLineage, aA as generateSessionId, aB as getAdmittedAgentBindings, aC as getAgentConfigHome, aD as getAgentConfigPath, aE as getAppDataDir, aF as getSessionLineagePath, aG as getSessionMessagesFromLineage, aH as mergeArtifactLedger, aI as mergeFileOps, aJ as registerPresetDispatcher, aK as resolveSessionLineageTarget, aL as rewindSessionLineage, aM as runAdmissionAudit, aN as setAdmittedAgentBindings, aO as setAgentConfigHome, aP as setSessionLineageActiveEntry, aQ as validateAndFixToolHistory } from './types-chunks/file-tracker.d-zaLZeNBK.js';
+import { U as Span, A as Agent, H as Handoff, K as RunnerToolCall, Q as RunnerToolResult, a as AgentMessage, C as ChildTaskRegistry, D as DiscoveredInstance, S as SessionMeta, T as SessionStateSnapshot, _ as StateWriterFs, v as InstanceDiscoveryFs, Z as StateWriter, h as CompactionDetails, g as CompactionConfig, i as CompactionResult } from './types-chunks/types.d-CKJtjo-6.js';
+export { b as AgentMiddlewareDeclaration, c as AgentReasoningProfile, d as AgentSpanData, e as AgentTool, f as CompactionAnchor, j as CompactionSpanData, k as CompactionUpdate, l as CurrentTodoSummary, m as DiscoveryOptions, E as EvidenceSpanData, F as FanoutSpanData, n as FileOperations, G as GenerationSpanData, o as Guardrail, p as GuardrailBlockedError, q as GuardrailContext, r as GuardrailEscalateError, s as GuardrailSpanData, t as GuardrailVerdict, u as HandoffSpanData, I as InputGuardrail, M as MAX_TOOL_LOOP_ITERATIONS, O as OutputGuardrail, P as PersistedSessionState, R as ReasoningDepth, w as RecentlyModifiedFile, x as RequestTaskStopOptions, y as RequestTaskStopResult, z as RunnableTool, B as RunnerLlmResult, J as RunnerLlmReturn, L as RunnerToolContext, N as RunnerToolObserver, V as SpanData, W as SpanError, X as SpanImpl, Y as SpanImplOptions, $ as StateWriterOptions, a0 as StopHookSpanData, a1 as TaskAbortRegistry, a2 as ToolBeforeOutcome, a3 as ToolCallSpanData, a4 as ToolGuardrail, a5 as buildAssistantMessageFromLlmResult, a6 as buildToolResultMessage, a7 as collectGuardrails, a8 as createAgent, a9 as createHandoff, aa as createStateWriter, ab as discoverInstances, ac as executeRunnerToolCall, ad as isRunnableTool, ae as isRunnerLlmResult, af as registerChildTask, ag as requestTaskStop, ah as runInputGuardrails, ai as runOutputGuardrails, aj as runToolAfterGuardrails, ak as runToolBeforeGuardrails } from './types-chunks/types.d-CKJtjo-6.js';
+import { m as KodaXMessage } from './types-chunks/types.d-B1uGoVTE.js';
+export { e as KodaXAssuranceIntent, g as KodaXContentBlock, i as KodaXExecutionMode, j as KodaXExecutionPattern, l as KodaXImageBlock, o as KodaXMutationSurface, r as KodaXProviderConfig, z as KodaXProviderStreamOptions, C as KodaXReasoningCapability, D as KodaXReasoningMode, F as KodaXReasoningRequest, G as KodaXRedactedThinkingBlock, I as KodaXRiskLevel, J as KodaXStreamResult, L as KodaXTaskActionability, M as KodaXTaskBudgetOverrides, N as KodaXTaskComplexity, O as KodaXTaskFamily, P as KodaXTaskRoutingDecision, Q as KodaXTaskType, R as KodaXTaskWorkIntent, S as KodaXTextBlock, T as KodaXThinkingBlock, U as KodaXThinkingBudgetMap, V as KodaXThinkingDepth, W as KodaXTokenUsage, X as KodaXToolDefinition, Y as KodaXToolResultBlock, a0 as KodaXToolUseBlock } from './types-chunks/types.d-B1uGoVTE.js';
+export { C as CapabilityKind, a as CapabilityProvider, b as CapabilityResult } from './types-chunks/capability.d-3C62G8Eq.js';
 import { Q as QueueEventListener, b as QueuedMessage, E as EnqueueInput, D as DequeueFilter, a as MessagePriority, M as MessageMode } from './types-chunks/types.d-C5mHR87z.js';
+export { M as McpConnectMode, a as McpServerConfig, b as McpServersConfig, c as McpTransportKind } from './types-chunks/config.d-BfJUXxC0.js';
+export { M as McpCapabilityDescriptor, a as McpCapabilityKind, b as McpCapabilityProvider, c as McpCapabilityRisk, d as McpCatalogItem, e as McpManager, f as McpProviderOptions, g as McpServerCatalog, h as McpServerCatalogSnapshot, i as McpServerLogs, j as McpServerRuntime, k as McpServerRuntimeDiagnostics, l as McpServerStatus, m as McpServerToolList, n as McpTransport, o as McpTransportEvents, p as createMcpCapabilityId, q as createMcpManager, r as createMcpTransport, s as defaultMcpCacheDir, t as getMcpCachePaths, u as parseMcpCapabilityId, v as searchMcpCatalog } from './types-chunks/manager.d-87belpiS.js';
+export { createMcpTestServerFixture } from './sdk-mcp.js';
+export { DiscoveryResult, ExecutionMode, ExecutionOptions, ISkillRegistry, IVariableResolver, Skill, SkillArtifact, SkillContext, SkillDynamicContextExecutor, SkillExecutor, SkillExpansionResult, SkillFile, SkillFrontmatter, SkillHook, SkillHooks, SkillMetadata, SkillPathsConfig, SkillRegistry, SkillResult, SkillSource, VariableResolver, clearPluginSkillPaths, createExecutor, createResolver, discoverSkills, discoverSkillsWithMonorepo, executeSkill, expandSkillForLLM, formatSkillActivationMessage, getDefaultSkillPaths, getNestedSkillPaths, getSkillPathsFlat, getSkillRegistry, initializeSkillRegistry, listPluginSkillPaths, loadFullSkill, loadSkillFileContent, loadSkillMetadata, parseArguments, parseSkillMarkdown, registerPluginSkillPath, resetSkillRegistry, resolveSkillContent, unregisterPluginSkillPath } from './sdk-skills.js';
+import { K as KodaXBaseProvider } from './types-chunks/base.d-FUJahC0i.js';
+
+/**
+ * TracingProcessor — sink for span/trace lifecycle events.
+ *
+ * FEATURE_083 (v0.7.24): minimal processor contract modeled after
+ * openai-agents-python. External adapters (OpenTelemetry, Langfuse, custom
+ * telemetry) implement this interface and register via
+ * `addTracingProcessor` / `setTracingProcessors`.
+ *
+ * Lifecycle:
+ *   - `onSpanStart(span)` fires when a span is created and attached to its
+ *     parent. Called synchronously; implementations should defer I/O.
+ *   - `onSpanEnd(span)` fires on `span.end()`. The span's `endedAt`,
+ *     `error`, and final children list are authoritative at this point.
+ *   - `onTraceEnd(trace)` fires on `trace.end()` after the root span ends.
+ *   - `shutdown()` is optional; called when the host wants processors to
+ *     flush pending work (e.g. batch buffers).
+ */
+
+interface TracingProcessor {
+    onSpanStart(span: Span): void;
+    onSpanEnd(span: Span): void;
+    onTraceEnd(trace: Trace): void;
+    shutdown?(): Promise<void>;
+}
+/**
+ * Register a tracing processor. Returns an unregister function.
+ *
+ * Consumers typically call this at app startup:
+ *
+ *     addTracingProcessor(new ConsoleTracingProcessor());
+ */
+declare function addTracingProcessor(p: TracingProcessor): () => void;
+/**
+ * Replace the current processor list. Useful in tests where you want a
+ * deterministic set of sinks.
+ */
+declare function setTracingProcessors(ps: TracingProcessor[]): void;
+/** @internal */
+declare function _getRegisteredProcessors(): readonly TracingProcessor[];
+/** @internal */
+declare function _emitSpanStart(span: Span): void;
+/** @internal */
+declare function _emitSpanEnd(span: Span): void;
+/** @internal */
+declare function _emitTraceEnd(trace: Trace): void;
+/**
+ * Flush-and-shutdown all registered processors. Callers can await this on
+ * process shutdown.
+ */
+declare function shutdownTracing(): Promise<void>;
+
+/**
+ * ConsoleTracingProcessor — writes span lifecycle lines to stdout.
+ *
+ * FEATURE_083 (v0.7.24): handy for local development. Not intended for
+ * production traffic.
+ *
+ * Output format (one line per event):
+ *
+ *     [span:start] traceId=... spanId=... name=... kind=...
+ *     [span:end]   traceId=... spanId=... name=... kind=... durationMs=...
+ *     [trace:end]  traceId=... rootName=... durationMs=...
+ */
+
+type WriteFn = (line: string) => void;
+interface ConsoleTracingProcessorOptions {
+    /**
+     * Writer override. Defaults to `process.stdout.write`. Useful in tests so
+     * output goes to a capture buffer instead of the real stdout.
+     */
+    readonly write?: WriteFn;
+}
+declare class ConsoleTracingProcessor implements TracingProcessor {
+    private readonly write;
+    constructor(opts?: ConsoleTracingProcessorOptions);
+    onSpanStart(span: Span): void;
+    onSpanEnd(span: Span): void;
+    onTraceEnd(trace: Trace): void;
+}
+
+/**
+ * FileTracingProcessor — writes JSONL records to `.kodax/.traces/{traceId}.jsonl`.
+ *
+ * FEATURE_083 (v0.7.24): simple append-only log for offline analysis. Each
+ * span start / end / trace end becomes a separate JSON line.
+ *
+ * The processor buffers per-trace writes to the file system; call
+ * `shutdown()` on process exit to flush pending writes.
+ */
+
+interface FileTracingProcessorOptions {
+    /**
+     * Directory for trace files. Defaults to `./.kodax/.traces`. Must be an
+     * absolute path or resolvable relative to `process.cwd()`.
+     */
+    readonly traceDir?: string;
+}
+declare class FileTracingProcessor implements TracingProcessor {
+    private readonly traceDir;
+    private readonly queues;
+    private writeChain;
+    private ensuredDir;
+    constructor(opts?: FileTracingProcessorOptions);
+    onSpanStart(span: Span): void;
+    onSpanEnd(span: Span): void;
+    onTraceEnd(trace: Trace): void;
+    shutdown(): Promise<void>;
+    private scheduleFlush;
+    private enqueue;
+    private flushTrace;
+}
 
 /**
  * Runner Handoff Helpers — FEATURE_084 Shard 4 (v0.7.26).
@@ -332,92 +452,6 @@ declare const CORE_INVARIANTS: readonly QualityInvariant[];
  */
 declare function registerCoreInvariants(): void;
 
-/**
- * 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;
-
 /**
  * @kodax-ai/agent/messaging/queue — 2-tier agentId-scoped FIFO message queue.
  *
@@ -689,9 +723,22 @@ interface IdleYieldSnapshot {
     /**
      * True if the run's managed-protocol payload has been populated
      * with a handoff (typically `emit_handoff` for the worker→evaluator
-     * boundary). False = the run ended without a handoff. Idle-yield
-     * REQUIRES this to be false; otherwise the handoff target already
-     * owns the next step.
+     * boundary in legacy V1 / V2 chains). False = the run ended without
+     * a handoff. Idle-yield REQUIRES this to be false; otherwise the
+     * handoff target already owns the next step.
+     *
+     * **FEATURE_184 (v0.7.45) + FEATURE_190 (v0.7.43)**: the Evaluator
+     * role was retired and Worker/Generator are now terminal. Under the
+     * Sidecar Verifier architecture, the CANONICAL post-F184 terminal
+     * signal is text-only termination — Worker produces a final text
+     * message with no `tool_use` block, Runner.run exits via the no-
+     * tool-calls branch, and this snapshot reads `hasEmittedHandoff:
+     * false` + `lastAssistantToolCallCount: 0`. `detectIdleYield`
+     * correctly returns false in that state (no pending child, no
+     * pending banner) → the outer loop breaks. So text-only termination
+     * is a first-class exit path; `hasEmittedHandoff` retained only for
+     * the pre-FEATURE_190 Phase 3 legacy `emit_handoff` tool that
+     * remains in scope through the cleanup window.
      */
     readonly hasEmittedHandoff: boolean;
     /**
@@ -744,44 +791,6 @@ interface IdleYieldSnapshot {
  * resume gate (fast-child race recovery; see field docs).
  */
 declare function detectIdleYield(snapshot: IdleYieldSnapshot): boolean;
-/**
- * FEATURE_167 (v0.7.41) — terminal-verdict-missing predicate.
- *
- * Companion to `detectIdleYield`, gating the OPPOSITE half of the
- * outer-loop exit decision: when the inner Runner.run loop exits
- * with no tool calls AFTER a handoff has fired but BEFORE the
- * Evaluator has emitted a terminal verdict, the run is structurally
- * INCOMPLETE — the audit step is missing. `detectIdleYield` correctly
- * returns false in this state (the gate at line 174 short-circuits on
- * `hasEmittedHandoff`), so the outer loop currently terminates with
- * `recorder.verdict === undefined`. Downstream `deriveFinalStatus`
- * then falls back to `signal:'COMPLETE'`, falsely reporting success
- * for a failed audit (production session 20260515_185354).
- *
- * This predicate identifies that exact missing-verdict state so the
- * outer loop can branch into a retry path (inject a "call emit_verdict"
- * prompt and re-invoke the Evaluator) before falling through to a
- * synthesized fallback verdict.
- *
- * **Disjoint from `detectIdleYield`** by construction:
- *
- *   - `detectIdleYield` requires `!hasEmittedHandoff`
- *   - `detectMissingTerminalVerdict` requires `hasEmittedHandoff`
- *
- * Both also require `lastAssistantToolCallCount === 0`. Both gate on
- * `!hasEmittedTerminalVerdict`. The two predicates partition the
- * "Evaluator turn just exited text-only" space cleanly — no run can
- * satisfy both.
- *
- * **Pending children take precedence over verdict retry.** Predicate
- * is intentionally `pendingChildTaskCount <= 0 && !hasPendingBackgroundMessages`
- * so that if Evaluator dispatched audit children and is correctly
- * idle-yielding for them (FEATURE_155 Bug C discipline), the
- * verdict-missing retry does NOT fire — `detectIdleYield` handles
- * that path instead. Only when there's nothing left to wait on does
- * the verdict-missing branch take over.
- */
-declare function detectMissingTerminalVerdict(snapshot: IdleYieldSnapshot): boolean;
 /**
  * Discriminated union surfacing the reason a wake completed.
  *
@@ -1460,5 +1469,714 @@ declare function getActiveTeamModeWriter(): StateWriter | null;
  */
 declare function updateActiveTeamMode(patch: Partial<SessionStateSnapshot>): void;
 
-export { Agent, AgentManifest, AgentMessage, CORE_INVARIANTS, ChildTaskRegistry, DEFAULT_IDLE_YIELD_MAX_ITERATIONS, DequeueFilter, DiscoveredInstance, EnqueueInput, Handoff, InstanceDiscoveryFs, InvariantId, KodaXMessage, ManifestPatch, MessageMode, MessagePriority, MessageQueue, QualityInvariant, QueuedMessage, RunnerToolCall, RunnerToolResult, SessionMeta, SessionStateSnapshot, StateWriter, StateWriterFs, YIELD_TOOL_NAMES, _resetAdmissionMetrics, _resetInvariantRegistry, _resetMessageQueueForTests, applyManifestPatch, bootstrapTeamMode, buildOtherInstancesPromptBlock, composeIdleYieldUserMessage, composePatches, countLastAssistantToolCalls, detectHandoffSignal, detectIdleYield, detectMissingTerminalVerdict, emitHandoffSpan, enqueueChildTaskNotification, evidenceTrail, finalOwner, getActiveTeamModeWriter, getAdmissionMetricsSnapshot, getAgentConfigHome, getAgentConfigPath, getInvariant, getMessageQueue, handoffLegality, isAdmissionDebugEnabled, isIdleYieldEnabled, listRegisteredInvariants, maybeDrainMidTurn, midTurnDrainPriority, registerCoreInvariants, registerInvariant, replaceSystemMessage, resolveEffectiveInvariants, resolveRequiredInvariants, routeMessage, runFanOut, runWithIdleYield, setActiveTeamModeWriter, setAgentConfigHome, updateActiveTeamMode, waitForWakeEvent };
-export type { AdmissionMetricsSnapshot, EnqueueChildTaskNotificationInput, EnvelopeAggregateEnforcer, FanOutOutcome, FanOutProgressEvent, HandoffSignal, IdleYieldSnapshot, MaybeDrainMidTurnInput, RenderOptions, RouteMessageOptions, RouteMessageResult, RunFanOutOptions, RunFanOutResult, RunWithIdleYieldOptions, RunWithIdleYieldRunResult, TeamModeBootstrapOptions, TeamModeHandle, WaitForWakeEventOptions, WakeEvent };
+/**
+ * FEATURE_124 (v0.7.43) — Memory System Alignment: path resolver.
+ *
+ * Per-project isolated memory directory under
+ * `<agentConfigHome>/projects/<sanitized-project-key>/memory/`. Mirrors
+ * claudecode `src/memdir/paths.ts` per-project layout so the same repo
+ * gets the same memory directory across worktrees / machines.
+ *
+ * Resolution order:
+ *   1. `git config --get remote.origin.url` (when present) — stable across
+ *      worktrees + clones, matches claudecode's `findCanonicalGitRoot`
+ *      semantic without re-implementing git plumbing.
+ *   2. `local-<sha256(cwd)>` fallback — for repos without a remote, or
+ *      when git is unavailable. Stable within a single clone path.
+ *
+ * Reuses `getAgentConfigPath('projects', key, 'memory')` from
+ * `runtime/agent-home.ts` (v0.7.35.1 FEATURE_145) so substrate consumers
+ * who override `setAgentConfigHome()` automatically get a fresh memory
+ * directory tree under their override root.
+ */
+/**
+ * Sanitize a git remote URL to a filesystem-safe project key.
+ *
+ * Strips protocol / SSH user prefix, lowercases host, replaces `:`, `@`,
+ * `/` with `-`, drops trailing `.git`. The result is deterministic and
+ * collision-free for distinct repos (different host or path → different
+ * key) and stable across clones of the same repo (same remote → same key).
+ *
+ * Examples:
+ *   `https://github.com/user/repo.git`         → `github.com-user-repo`
+ *   `git@github.com:user/repo.git`             → `github.com-user-repo`
+ *   `ssh://git@gitlab.example.com/team/repo`   → `gitlab.example.com-team-repo`
+ *
+ * Note: hosts `github.com` over HTTPS and `git@github.com:` over SSH
+ * intentionally produce the same key — they identify the same repo,
+ * just different access protocols.
+ */
+declare function sanitizeProjectKey(remoteUrl: string): string;
+/**
+ * SHA-256 hash of an absolute cwd, truncated to 16 hex chars. Used as
+ * the project key fallback when `git config --get remote.origin.url`
+ * returns nothing.
+ *
+ * Path is normalized + lowercased before hashing so case-insensitive
+ * filesystems (macOS default, Windows) produce the same key for
+ * `/Users/X/repo` and `/users/x/repo`.
+ */
+declare function hashCwd(cwd: string): string;
+/**
+ * Read `git config --get remote.origin.url` from the given cwd. Returns
+ * `undefined` on any failure (no git installed / not a repo / no remote
+ * configured / git timed out). NEVER throws.
+ *
+ * 1000ms timeout — guards against pathological git hangs on broken
+ * .git/config without blocking session startup.
+ */
+declare function tryGitRemote(cwd: string): string | undefined;
+/**
+ * Resolve the memory directory for the given cwd.
+ *
+ * `<agentConfigHome>/projects/<key>/memory/` where key is:
+ *   - sanitized git remote URL when available
+ *   - `local-<sha256(cwd)[:16]>` fallback otherwise
+ */
+declare function resolveMemoryRoot(cwd: string): string;
+/**
+ * Path of the MEMORY.md index file inside a resolved memory root.
+ */
+declare function resolveMemoryEntrypoint(cwd: string): string;
+/**
+ * Check whether a given absolute path is inside ANY memory directory
+ * (under `<agentConfigHome>/projects/*​/memory/`). Used by the REPL
+ * transcript renderer to badge memory writes / reads, and by future
+ * tool-permission carve-outs.
+ *
+ * Returns true only for `.md` files inside a `memory/` directory whose
+ * parent is the agent config home's `projects/<key>/` tree. Path
+ * traversal (`..`) is normalized before the check.
+ *
+ * The check is path-prefix only — it does NOT verify the file exists
+ * on disk. A planned write to `<memoryRoot>/feedback_X.md` returns true
+ * even before the file is created.
+ */
+declare function isAutoManagedMemoryFile(filePath: string): boolean;
+/**
+ * Best-effort filename-based type guess for badge rendering. Mirrors the
+ * 4-type taxonomy: `feedback_*.md` → `feedback`, etc. Returns `undefined`
+ * for filenames that don't follow the convention — UI should fall back
+ * to reading frontmatter or showing a generic `[memory]` badge.
+ *
+ * This is a HEURISTIC for cheap UI display. Authoritative type lives in
+ * the file's YAML frontmatter (see `frontmatter.ts`).
+ */
+declare function parseMemoryTypeFromFilename(filePath: string): 'user' | 'feedback' | 'project' | 'reference' | undefined;
+
+/**
+ * FEATURE_124 (v0.7.43) — Memory frontmatter parser.
+ *
+ * Minimal YAML frontmatter subset for memory files:
+ *
+ *   ---
+ *   name: User role
+ *   description: Senior backend engineer, Go/PostgreSQL focus
+ *   type: user
+ *   ---
+ *
+ *   <body markdown>
+ *
+ * Why a hand-rolled parser instead of `yaml` dep:
+ *   - `@kodax-ai/agent` is the substrate package; adding a runtime YAML
+ *     dependency would propagate to every consumer (kodax CLI, downstream
+ *     `@kodax-ai/data-analysis-agent`, etc.). Frontmatter has only 3
+ *     scalar string fields — a 40-line regex parser is the appropriate
+ *     scope.
+ *   - Degraded-tolerant: corrupt YAML / unknown type / missing
+ *     frontmatter MUST NOT throw — the file remains readable as
+ *     `{ raw: <full content>, type: undefined }`. Memory directories
+ *     accumulate files over months; one bad file cannot break session
+ *     startup.
+ *
+ * Contract guarantees (verified by frontmatter.test.ts):
+ *   - Parser NEVER throws.
+ *   - Unknown / mistyped `type:` → `type: undefined` (still readable).
+ *   - Missing frontmatter → `{ name: undefined, description: undefined,
+ *     type: undefined, body: <full content> }`.
+ *   - Body extraction strips the frontmatter block + leading newlines.
+ */
+type MemoryType = 'user' | 'feedback' | 'project' | 'reference';
+interface MemoryFrontmatter {
+    /** Human-readable short title. May be undefined when frontmatter is malformed or missing. */
+    readonly name: string | undefined;
+    /** One-line search hint. May be undefined when frontmatter is malformed or missing. */
+    readonly description: string | undefined;
+    /** 4-type taxonomy; undefined for unknown / missing types (degraded tolerant). */
+    readonly type: MemoryType | undefined;
+}
+interface ParsedMemoryFile {
+    readonly frontmatter: MemoryFrontmatter;
+    /** Body content WITHOUT the frontmatter block. May be empty. */
+    readonly body: string;
+}
+/**
+ * Coerce a raw frontmatter value to the closed 4-type taxonomy.
+ * Returns `undefined` for unknown types — degraded tolerance lets the
+ * file remain in the directory without breaking the index or session
+ * startup.
+ */
+declare function parseMemoryType(raw: unknown): MemoryType | undefined;
+/**
+ * Parse a memory file's raw text into frontmatter + body. NEVER throws.
+ *
+ * Behavior:
+ *   - No frontmatter block → all fields undefined, body = full input.
+ *   - Frontmatter present + parseable → fields populated where possible,
+ *     unknown / mistyped fields → undefined. Body = content after the
+ *     closing `---` line.
+ *   - Frontmatter block syntactically present but no parseable
+ *     `key: value` lines → all fields undefined, body = content after
+ *     closing `---`. (Garbage frontmatter is not an error.)
+ */
+declare function parseMemoryFile(raw: string): ParsedMemoryFile;
+/**
+ * Parse `key: value` scalar lines from a YAML block. Supports:
+ *   - bare strings: `name: Hello world`
+ *   - single-quoted strings: `name: 'Hello: world'`
+ *   - double-quoted strings: `name: "Hello: world"`
+ *
+ * Does NOT support: nested objects, sequences (lists), multiline scalars,
+ * YAML anchors / aliases / tags. Lines that don't match the simple
+ * scalar shape are silently skipped (degraded tolerance).
+ *
+ * Visibility: exported only for testing; consumers use `parseMemoryFile`.
+ */
+declare function parseScalarFields(yamlBlock: string): Record<string, string>;
+
+/**
+ * FEATURE_124 (v0.7.43) — MEMORY.md entrypoint truncation.
+ *
+ * Mirrors claudecode `src/memdir/memdir.ts` `truncateEntrypointContent`
+ * (caps + warning text) byte-for-byte semantically — verified by
+ * truncate.test.ts text-mirror assertion against the claudecode-shape
+ * warning string. Mirroring the caps + warning is intentional: it pins
+ * the same context-budget invariant (≤25KB SP overhead from MEMORY.md)
+ * across both agents and inherits claudecode's empirical line/byte
+ * tuning without re-deriving thresholds.
+ *
+ * Two-stage truncation:
+ *   1. If `lineCount > MAX_ENTRYPOINT_LINES`, slice the array to that
+ *      many lines and re-join.
+ *   2. If the resulting (or original, when no line truncation) string is
+ *      still > MAX_ENTRYPOINT_BYTES, find the last newline at or before
+ *      the byte cap and slice there. Falls back to a hard byte slice if
+ *      no newline is found within the cap (one giant line worse-case).
+ *
+ * Warning is appended only when at least one cap fired. Warning text
+ * mirrors claudecode line 87-97; the test asserts the literal string.
+ */
+declare const MAX_ENTRYPOINT_LINES = 200;
+declare const MAX_ENTRYPOINT_BYTES = 25000;
+interface EntrypointTruncation {
+    /** Truncated content with claudecode-shape WARNING line appended (if any cap fired). */
+    readonly content: string;
+    /** Original line count BEFORE truncation. */
+    readonly lineCount: number;
+    /** Original byte count BEFORE truncation. */
+    readonly byteCount: number;
+    readonly wasLineTruncated: boolean;
+    readonly wasByteTruncated: boolean;
+}
+/**
+ * Truncate MEMORY.md content to the line AND byte caps, appending a
+ * claudecode-shape WARNING when truncated. Pass-through when within caps.
+ *
+ * Input MAY be trimmed of leading/trailing whitespace before measurement
+ * (matches claudecode). Returns a `content` string ready for direct SP
+ * injection.
+ */
+declare function truncateEntrypointContent(raw: string): EntrypointTruncation;
+
+/**
+ * ../../index.js Compaction Utils
+ *
+ * 消息序列化工具 - 将消息转换为结构化文本格式
+ */
+
+/**
+ * 序列化对话为文本
+ *
+ * 将消息转换为结构化文本格式，保留完整内容不截断
+ * 参考 pi-mono 的实现：让 LLM 决定重点，不通过截断丢失信息
+ *
+ * 输出格式:
+ * ```
+ * [User]: 用户说的内容
+ * [Assistant thinking]: 内部推理
+ * [Assistant]: 响应文本
+ * [Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
+ * [Tool result]: 工具输出
+ * ```
+ *
+ * @param messages - 消息列表
+ * @returns 序列化后的文本
+ */
+declare function serializeConversation(messages: KodaXMessage[]): string;
+
+/**
+ * ../../index.js Compaction Summary Generator
+ *
+ * Generates continuation-oriented summaries for compacted conversations.
+ */
+
+/**
+ * Default neutral compaction summary prompts (v0.7.35.1 FEATURE_142 B-R1).
+ *
+ * These are the *generic* defaults shipped with @kodax-ai/session-lineage.
+ * They are the "candidate-a-conservative" winner from the prompt eval
+ * (`tests/compaction-prompt.eval.ts`, 150 cells over 5 aliases × 10
+ * fixtures × 3 candidates) — schema-stable and high-recall on both
+ * coding and non-coding fixtures, with domain-neutral wording.
+ *
+ * The prior coding-flavored prompts (referencing "coding agent",
+ * "file paths, function names", "HTTP status codes", "## Files & Changes")
+ * have moved to `@kodax-ai/coding` as `CODING_SUMMARY_PROMPT` /
+ * `CODING_UPDATE_SUMMARY_PROMPT`. Coding callers pass them via the
+ * `summaryPrompt` / `updateSummaryPrompt` parameters of
+ * `buildCompactionPromptSnapshot()` and `generateSummary()` / `compact()`
+ * to preserve the v0.7.35 behavior byte-equivalent on the coding path.
+ *
+ * Why this split (per ADR-021): @kodax-ai/session-lineage is the generic
+ * compaction primitive package. Its public surface must not assume the
+ * caller is a coding agent — domain-specific prompt language belongs
+ * one layer up.
+ */
+declare const DEFAULT_SUMMARY_PROMPT = "Create a structured summary for the conversation below.\n\nThis summary will be handed to another agent so it can continue the same task with minimal context.\nKeep only information that is still useful for continuing the work.\n\nYou may drop:\n- completed low-value micro-steps\n- repetitive thinking\n- stale intermediate plans\n- verbose tool output details\n\nYou must keep:\n- the current goal\n- user constraints and preferences\n- current progress and unfinished work\n- blockers or unresolved questions\n- the most important next steps\n- EXACT identifiers, references, and concrete locations the agent operated on or referenced\n- EXACT error messages, status codes, and exception types\n- EXACT configuration values, parameter values, and external resource names mentioned\n- key decisions WITH reasoning (not just the choice)\n\nCRITICAL: Every user REQUEST and DECISION must be preserved verbatim or near-verbatim.\nNever reduce \"user asked to upgrade dependency X to v3.4 to resolve incompatibility with system Y\"\nto \"user asked to fix an issue\".\n\nKeep the summary concise and high-signal. Do not mechanically preserve every historical detail.\n\nFirst, wrap your analysis in <analysis> tags:\n- Walk through messages chronologically\n- Note exact identifiers, references, error codes, configuration values\n- Identify user's explicit requests vs inferred intent\n- Flag technical details that MUST survive compression\n\nThen output the structured summary in <summary> tags.\n\nOutput format (strict markdown, inside <summary> tags):\n\n## Goal\n[1-2 sentences describing the active goal]\n\n## Constraints & Preferences\n- [One item per line]\n- [Write \"None\" if there are no explicit constraints]\n\n## Progress\n### Completed\n- [x] [Completed work that still matters for context]\n\n### In Progress\n- [ ] [Current work that is actively underway]\n\n### Blockers\n- [Current blockers, or \"None\"]\n\n## Key Decisions\n- **[Decision]**: [Short reason]\n\n## Next Steps\n1. [Highest-priority next action]\n\n## Key Context\n- [Critical context needed to continue]\n\n---\n\n<read-files>\n[One reference per line \u2014 file paths, URLs, IDs, or other locations the agent read; leave empty if none]\n</read-files>\n\n<modified-files>\n[One reference per line \u2014 locations the agent modified; leave empty if none]\n</modified-files>\n\nConversation:\n";
+declare const DEFAULT_UPDATE_SUMMARY_PROMPT = "Merge the new conversation content above into <previous-summary>.\n\nUpdate the structured summary so another agent can continue the task immediately.\nKeep only the information needed to continue the work.\n\nYou may remove:\n- repetitive or superseded plans\n- completed low-value steps\n- outdated blockers\n- noisy tool output details\n\nYou must preserve or update:\n- the current goal\n- user constraints and preferences\n- current progress and unfinished work\n- blockers that still matter\n- next steps based on the latest state\n- EXACT identifiers, references, and concrete locations\n- EXACT error messages, status codes, and exception types\n- EXACT configuration values, parameter values, and external resource names\n- key decisions WITH reasoning\n\nCRITICAL: Every user REQUEST and DECISION must be preserved verbatim or near-verbatim.\n\nDo not accumulate every past detail. Compress aggressively while keeping continuation-critical context.\n\nFirst, wrap your analysis in <analysis> tags, then output the summary in <summary> tags.\n\nOutput format (strict markdown, inside <summary> tags):\n\n## Goal\n[Updated goal]\n\n## Constraints & Preferences\n- [Relevant constraints only]\n\n## Progress\n### Completed\n- [x] [Completed work that still matters]\n\n### In Progress\n- [ ] [Active work in the latest state]\n\n### Blockers\n- [Current blockers, or \"None\"]\n\n## Key Decisions\n- **[Decision]**: [Short reason]\n\n## Next Steps\n1. [Most relevant next action]\n\n## Key Context\n- [Critical context needed to continue]\n\n---\n\n<read-files>\n[One reference per line \u2014 file paths, URLs, IDs, or other locations the agent read; leave empty if none]\n</read-files>\n\n<modified-files>\n[One reference per line \u2014 locations the agent modified; leave empty if none]\n</modified-files>\n\nKeep every section concise.";
+type KodaXCompactionPromptVariant = 'initial-summary' | 'update-summary';
+interface KodaXCompactionPromptSection {
+    id: string;
+    title: string;
+    owner: 'compaction';
+    /**
+     * Provenance label — opaque string identifying which feature ticket
+     * authored this section, used by debug tooling and prompt-eval
+     * provenance traces. v0.7.35.1 FEATURE_142: widened from coding-side
+     * `'FEATURE_044' | 'FEATURE_050'` literal union per ADR-021 — the
+     * session-lineage package is generic and must not enumerate coding
+     * feature IDs in its public type surface.
+     */
+    feature: string;
+    slot: 'conversation' | 'history' | 'instructions' | 'tracking';
+    order: number;
+    stability: 'stable' | 'dynamic' | 'specialist';
+    inclusionReason: string;
+    content: string;
+}
+interface KodaXCompactionPromptSnapshot {
+    kind: 'specialist';
+    specialist: 'compaction-summary';
+    variant: KodaXCompactionPromptVariant;
+    systemPrompt: string;
+    userPrompt: string;
+    sections: KodaXCompactionPromptSection[];
+    hash: string;
+}
+declare function buildCompactionPromptSnapshot(args: {
+    messages: KodaXMessage[];
+    details: CompactionDetails;
+    customInstructions?: string;
+    systemPrompt?: string;
+    previousSummary?: string;
+    /**
+     * Override the initial-summary instructions. When omitted, falls back
+     * to {@link DEFAULT_SUMMARY_PROMPT}. Coding callers pass
+     * `CODING_SUMMARY_PROMPT` (from @kodax-ai/coding) here to preserve the
+     * v0.7.35 byte-equivalent prompt on the coding path.
+     */
+    summaryPrompt?: string;
+    /**
+     * Override the update-summary instructions. When omitted, falls back
+     * to {@link DEFAULT_UPDATE_SUMMARY_PROMPT}. Coding callers pass
+     * `CODING_UPDATE_SUMMARY_PROMPT` (from @kodax-ai/coding) here.
+     */
+    updateSummaryPrompt?: string;
+}): KodaXCompactionPromptSnapshot;
+declare function generateSummary(messages: KodaXMessage[], provider: KodaXBaseProvider, details: CompactionDetails, customInstructions?: string, systemPrompt?: string, previousSummary?: string, summaryPrompt?: string, updateSummaryPrompt?: string): Promise<string>;
+
+/**
+ * ../../index.js Compaction Core
+ *
+ * Progressive compaction with lightweight tool-result pruning and rolling
+ * summarization to an internal low-water mark.
+ */
+
+/**
+ * Exported as the canonical PROTECTED set so peer modules
+ * (microcompaction.ts default config, registry-parity test, future
+ * Stage 3 ledger work) can pull a single source-of-truth.
+ */
+declare const PROTECTED_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Marker prefix on the synthesized summary system message. Other packages
+ * use this literal as the discriminator to tell CompactionSummary system
+ * messages apart from role-prompt system messages \u2014 exported so callers
+ * (notably `@kodax-ai/coding`'s `preserveTranscriptForRoundExit`) cannot
+ * drift from the producer side.
+ */
+declare const COMPACTION_SUMMARY_PREFIX = "[\u5BF9\u8BDD\u5386\u53F2\u6458\u8981]\n\n";
+/**
+ * FEATURE_181 (v0.7.42): detect LLM "I have no content to summarize" output.
+ *
+ * Empty-like markers observed across 788 sessions (7.8% of compactions):
+ *   - "No active goal" / "no active goal"
+ *   - "conversation is empty" / "The conversation is empty"
+ *   - "no prior context"
+ *   - "nothing to summarize" / "no content to summarize"
+ *
+ * Also catches very short outputs (< 80 chars) — a meaningful goal summary
+ * is empirically ≥150 chars even for simple tasks. Conservative threshold:
+ * false positives only cause us to KEEP the previous summary, never lose
+ * information.
+ *
+ * Exported for unit testing.
+ */
+declare function isEmptyLikeSummary(summary: string): boolean;
+declare function needsCompaction(messages: KodaXMessage[], config: CompactionConfig, contextWindow?: number, tokenCountOverride?: number): boolean;
+declare function compact(messages: KodaXMessage[], config: CompactionConfig, provider: KodaXBaseProvider, contextWindow?: number, customInstructions?: string, systemPrompt?: string, tokenCountOverride?: number, summaryPrompt?: string, updateSummaryPrompt?: string): Promise<CompactionResult>;
+
+/**
+ * KodaX Microcompaction - Time-driven context cleanup
+ *
+ * Clears old tool result content from messages to slow context growth.
+ * Pure function, no LLM calls, runs after each agent turn.
+ *
+ * Design:
+ * - Tracks "turns" (role switches from assistant to user)
+ * - Clears tool_result blocks older than maxAge turns
+ * - Preserves thinking blocks (token cost is marginal; Kimi requires non-empty
+ *   reasoning_content on every tool-call assistant message)
+ * - Preserves image blocks (replacing them invalidates Anthropic prompt-cache
+ *   prefixes and discards multimodal context; all reference agents — claudecode,
+ *   pi-mono, opencode — also preserve images at this layer. Token cost is handled
+ *   by the LLM compaction layer that produces a summary when budget pressure hits.)
+ * - Preserves protected tools (e.g., ask_user_question)
+ * - Placeholder format matches compaction pruning: `[Cleared: grep src/auth.ts "pattern"]`
+ * - Immutable: returns new array, never mutates input
+ */
+
+interface MicrocompactionConfig {
+    readonly enabled: boolean;
+    readonly maxAge: number;
+    readonly protectedTools: readonly string[];
+}
+/**
+ * FEATURE_183 (v0.7.42): align `protectedTools` with the canonical
+ * PROTECTED_TOOL_NAMES from compaction.ts so microcompact and the
+ * slow-path pruneToolResults agree on which tools are off-limits. Pre-F183
+ * the two sets had drifted (microcompact = `['ask_user_question']`, prune
+ * = `['skill']`), meaning a tool could be cleared by one path and
+ * protected by the other depending on whether maxAge or pruning ran
+ * first — semantically incoherent.
+ */
+declare const DEFAULT_MICROCOMPACTION_CONFIG: MicrocompactionConfig;
+/**
+ * Microcompact messages by clearing old tool result content.
+ * Returns a new array - does NOT mutate the input.
+ *
+ * Placeholder format reuses the same rich preview as compaction pruning:
+ * - bash:  `[Cleared: git status]`
+ * - grep:  `[Cleared: grep src/auth.ts "pattern"]`
+ * - read:  `[Cleared: read auth.ts]`
+ * - edit:  `[Cleared: edit auth.ts]`
+ *
+ * @param messages - The input messages to microcompact
+ * @param config - Configuration (defaults to DEFAULT_MICROCOMPACTION_CONFIG)
+ * @returns A new message array with old tool results cleared, or original if unchanged
+ */
+declare function microcompact(messages: readonly KodaXMessage[], config?: MicrocompactionConfig): readonly KodaXMessage[];
+
+/**
+ * Post-Compact Reconstruction
+ *
+ * After compaction, injects artifact ledger summary and recently modified
+ * file content back into the context so the agent remembers what it
+ * operated on without re-reading files.
+ *
+ * Budget rule: total post-compact attachments are capped by the smaller of
+ * (freed tokens × budgetRatio) and POST_COMPACT_TOKEN_BUDGET (absolute cap).
+ * The absolute cap mirrors Claude Code's `POST_COMPACT_TOKEN_BUDGET = 50_000`
+ * and prevents re-inflation when a single compaction frees a huge chunk.
+ * Within the budget: ledger gets ≤15%, rest goes to file content
+ * (per-file cap = min(perFileShare × total, POST_COMPACT_MAX_TOKENS_PER_FILE),
+ * max 5 files).
+ *
+ * Idempotence: `injectPostCompactAttachments` strips any prior
+ * `[Post-compact: ...]` system messages before inserting new ones, so a flat
+ * messages array that survives across compaction rounds does not accumulate
+ * multiple generations of post-compact attachments.
+ */
+
+/**
+ * Absolute cap on total post-compact attachment tokens.
+ * Mirrors Claude Code's POST_COMPACT_TOKEN_BUDGET (services/compact/compact.ts).
+ */
+declare const POST_COMPACT_TOKEN_BUDGET = 50000;
+/**
+ * Per-file hard cap on content tokens.
+ * Mirrors Claude Code's POST_COMPACT_MAX_TOKENS_PER_FILE.
+ */
+declare const POST_COMPACT_MAX_TOKENS_PER_FILE = 5000;
+interface PostCompactConfig {
+    /** Ratio of freed tokens to use for post-compact attachments. Default 0.5. */
+    readonly budgetRatio: number;
+    /** Maximum files to inject. Default 5. */
+    readonly maxFiles: number;
+    /** Ledger share as fraction of total budget. Default 0.15. */
+    readonly ledgerShare: number;
+    /** Per-file share as fraction of total budget. Default 0.20. */
+    readonly perFileShare: number;
+}
+declare const DEFAULT_POST_COMPACT_CONFIG: PostCompactConfig;
+interface PostCompactAttachments {
+    readonly ledgerMessage: KodaXMessage | null;
+    readonly fileMessages: readonly KodaXMessage[];
+    readonly totalTokens: number;
+}
+/**
+ * Build post-compact system messages from the artifact ledger.
+ * Does NOT read files from disk — that is the caller's responsibility.
+ *
+ * @param ledger - The artifact ledger from compaction
+ * @param freedTokens - Tokens freed by compaction (tokensBefore - tokensAfter)
+ * @param config - Budget configuration
+ * @returns Attachments to inject after the compacted messages
+ */
+declare function buildPostCompactAttachments(ledger: readonly KodaXSessionArtifactLedgerEntry[], freedTokens: number, config?: PostCompactConfig): PostCompactAttachments;
+/**
+ * Inject post-compact attachments into the compacted message array.
+ *
+ * Inserts after the compaction summary (first system message with the
+ * summary prefix) and before the protected tail. Any existing post-compact
+ * attachment messages in the input are stripped first to keep the injection
+ * idempotent — without this, compaction repeated across iterations would
+ * stack N generations of attachments, causing monotonic context growth.
+ */
+declare function injectPostCompactAttachments(messages: KodaXMessage[], attachments: PostCompactAttachments): KodaXMessage[];
+/**
+ * Read recently modified files from disk and build system messages for
+ * post-compact context restoration.
+ *
+ * @param ledger - Artifact ledger from compaction
+ * @param budgetTokens - Remaining token budget after ledger injection
+ * @param config - Budget configuration
+ * @returns File content messages to merge into PostCompactAttachments.fileMessages
+ */
+declare function buildFileContentMessages(ledger: readonly KodaXSessionArtifactLedgerEntry[], budgetTokens: number, config?: PostCompactConfig): Promise<readonly KodaXMessage[]>;
+
+/**
+ * ../index.js Extension Persistence Store
+ *
+ * JSONL-backed key-value store scoped to a single extension identity.
+ * Each store instance owns one `.jsonl` file inside the extension store
+ * directory.  All I/O is async and safe for single-writer use.
+ *
+ * File format (one JSON object per line):
+ *
+ *   {"_type":"entry","key":"...","value":...,"version":"...","updatedAt":...}
+ */
+
+/**
+ * JSONL-backed implementation of {@link KodaXExtensionStore}.
+ *
+ * All data for a single extension namespace lives in one JSONL file under
+ * `~/.kodax/extension-store/<namespace>/store.jsonl`.  The file is rewritten
+ * atomically on every mutation (replace-then-rename).
+ */
+declare class FileExtensionStore implements KodaXExtensionStore {
+    private readonly filePath;
+    constructor(namespaceId: string);
+    get(key: string): Promise<KodaXExtensionStoreEntry | undefined>;
+    put(key: string, value: KodaXJsonValue, options?: {
+        expectedVersion?: string;
+    }): Promise<KodaXExtensionStoreEntry | false>;
+    delete(key: string): Promise<boolean>;
+    list(options?: {
+        prefix?: string;
+    }): Promise<string[]>;
+    clear(options?: {
+        prefix?: string;
+    }): Promise<number>;
+    private readAllEntries;
+    private writeAllEntries;
+}
+/**
+ * Create a {@link FileExtensionStore} for the given extension namespace.
+ *
+ * The namespace is typically the `extensionId` (e.g. `cli:extension:/path/to/ext.mjs`).
+ */
+declare function createExtensionStore(namespaceId: string): KodaXExtensionStore;
+
+/**
+ * Compaction trigger decision — CAP-059
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-059-compaction-trigger-decision
+ *
+ * Class 1 (substrate). Per-turn predicate read BEFORE the provider
+ * stream call to decide whether the compaction lifecycle (CAP-060)
+ * should run this turn. Time-ordering: AFTER microcompact (CAP-014);
+ * BEFORE intelligentCompact orchestration (CAP-060).
+ *
+ * The wrapper preserves the historical short-circuit `compactionConfig.enabled`
+ * gate from `agent.ts` even though the underlying `needsCompaction`
+ * helper already returns `false` when the config is disabled. The
+ * double-gate matches the pre-FEATURE_100 baseline byte-for-byte —
+ * removing the redundancy is a P3.6 cleanup concern, not a P3.4
+ * extraction concern.
+ *
+ * Migration history:
+ *   - extracted from `agent.ts:598-600` — pre-FEATURE_100 baseline —
+ *     during FEATURE_100 P3.4a.
+ *   - moved from `../../index.js/src/runtime-middleware/` to
+ *     `@kodax-ai/session-lineage/src/runtime-middleware/` in v0.7.36 to
+ *     break the build cycle introduced by FEATURE_142 Batch D
+ *     (agent → session-lineage → agent). session-lineage already
+ *     depends on agent, so this direction is acyclic. Semantically
+ *     this also reflects that compaction trigger is part of the
+ *     compaction lifecycle, which is session-lineage's domain.
+ */
+
+interface ShouldCompactInput {
+    readonly messages: KodaXMessage[];
+    readonly compactionConfig: CompactionConfig;
+    readonly contextWindow: number;
+    readonly currentTokens: number;
+}
+/**
+ * Returns `true` iff the compaction lifecycle should run this turn.
+ * Combines the config-enabled gate with the underlying trigger
+ * threshold check from `@kodax-ai/session-lineage`'s `needsCompaction`.
+ */
+declare function shouldCompact(input: ShouldCompactInput): boolean;
+
+/**
+ * Graceful compaction degradation — CAP-028
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-028-graceful-compaction-degradation
+ *
+ * Class 1 (substrate middleware). Truncation-based fallback that fires
+ * when the primary FEATURE_072 lineage compaction fails (LLM error,
+ * token overflow during summarization, etc.) so the run can continue
+ * instead of hard-failing.
+ *
+ * Strategy: drop the oldest atomic blocks (tool_use + tool_result
+ * pairs) one at a time from the front until token estimate is below
+ * the target threshold (`triggerPercent * 80%` of context window).
+ * Three invariants are load-bearing:
+ *
+ *   1. **Summary preservation** — if the very first message is a
+ *      `system` message OR a `user` message containing `'[对话历史摘要]'`
+ *      (the FEATURE_072 lineage marker), `startIdx = 1` so the
+ *      summary itself is never dropped.
+ *
+ *   2. **Tool pairing** — `tool_use` blocks (assistant) and
+ *      `tool_result` blocks (user) MUST stay paired. If we encounter
+ *      a `tool_use` without a following `tool_result` (or a
+ *      `tool_result` without a preceding `tool_use`), we skip past
+ *      it rather than orphaning its partner. This is critical because
+ *      providers reject unpaired tool blocks with `400` errors.
+ *
+ *   3. **Recent-context preservation** — the loop terminates as soon
+ *      as the running token estimate dips below the target, so the
+ *      tail of the conversation (most-recent messages) is preserved.
+ *
+ * The function is INTENTIONALLY destructive — it returns a NEW array
+ * with the dropped messages removed. Callers do not mutate the input
+ * array directly (the `messages = [...messages.slice(...)]` pattern
+ * inside the loop ensures each iteration starts from a fresh copy).
+ *
+ * The two content-block predicates (`isTypedContentBlock`,
+ * `isToolResultContentBlock`) are private helpers carried over with
+ * this function — by the time this batch ran, prior batches had
+ * already migrated `validateAndFixToolHistory` (the only other
+ * consumer of these predicates in HEAD `agent.ts`) into
+ * `agent-runtime/history-cleanup.ts` along with its own local copies
+ * of the predicates (CAP-002). So at the point of extraction, the
+ * predicates' only remaining `agent.ts` consumer was
+ * `gracefulCompactDegradation` itself. Co-locating them here keeps
+ * the module self-contained.
+ *
+ * (The original `agent.ts` also defined `isToolUseContentBlock` next
+ * to these. In HEAD it had 2 callers inside
+ * `validateAndFixToolHistory`; those callers moved with the function
+ * to `history-cleanup.ts` (CAP-002) and the agent.ts copy of
+ * `isToolUseContentBlock` was left without callers. It is therefore
+ * intentionally NOT carried over to this module. The dispatcher's
+ * tool-use checks elsewhere in `agent.ts` use the inline pattern
+ * `isTypedContentBlock(b) && b.type === 'tool_use'` instead.)
+ *
+ * Migration history:
+ *   - extracted from `agent.ts:185-187` + `195-199` (the two carried
+ *     predicates) + `agent.ts:201-266` (`gracefulCompactDegradation`
+ *     with its docstring) — pre-FEATURE_100 baseline — during
+ *     FEATURE_100 P2.
+ *   - moved from `../../index.js/src/runtime-middleware/` to
+ *     `@kodax-ai/session-lineage/src/runtime-middleware/` in v0.7.36 to
+ *     break the build cycle introduced by FEATURE_142 Batch D
+ *     (agent → session-lineage → agent). Semantically this also
+ *     reflects that compaction degradation is part of the compaction
+ *     lifecycle, which is session-lineage's domain.
+ */
+
+/**
+ * Graceful compact degradation: drop oldest atomic blocks (tool_use + tool_result pairs)
+ * one at a time from the front until tokens are below the target threshold.
+ * Preserves summary messages, message structure integrity, and recent context.
+ */
+declare function gracefulCompactDegradation(messages: KodaXMessage[], contextWindow: number, config: CompactionConfig): KodaXMessage[];
+
+/**
+ * Effective context-window resolver — CAP-056
+ *
+ * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-056-effective-context-window-resolution-cascade
+ *
+ * Class 1 (substrate middleware). Pure four-step cascade evaluated at
+ * the start of every turn (after per-turn provider re-resolution,
+ * before the compaction trigger decision). The cascade order is
+ * load-bearing — earlier sources override later ones:
+ *
+ *   1. **`compactionConfig.contextWindow`** (user-supplied) — wins
+ *      unconditionally so an operator can pin a smaller window for
+ *      cost / latency reasons even if the provider would advertise a
+ *      larger one.
+ *   2. **`provider.getEffectiveContextWindow?.(model)`** — model-
+ *      specific window when the provider exposes it (e.g.
+ *      `claude-3-5-sonnet-20241022` advertises 200000, while a
+ *      provider with multiple models returns a per-model value).
+ *   3. **`provider.getContextWindow?.()`** — provider-level default
+ *      (used when the provider only exposes a single window).
+ *   4. **`200000`** — hard fallback. Mirrors Anthropic's standard
+ *      Claude window; safe default for providers that don't implement
+ *      either capability check.
+ *
+ * The optional-chained calls are load-bearing — providers that don't
+ * implement `getEffectiveContextWindow` / `getContextWindow` simply
+ * skip to the next step in the cascade rather than throwing.
+ *
+ * P3 note: per inventory's stated migration target this module is
+ * "shared with CAP-055" (per-turn provider re-resolution). CAP-055
+ * lives inline in `runKodaX`'s for-loop today; once P3 substrate
+ * adoption lands and the per-turn block lives inside the Runner
+ * frame, both helpers will likely co-locate in
+ * `per-turn-provider-resolution.ts`. For P2 this single-cascade
+ * helper is the only piece tractable as a discrete extraction.
+ *
+ * Migration history:
+ *   - extracted from `agent.ts:1700-1703` — pre-FEATURE_100 baseline
+ *     — during FEATURE_100 P2.
+ *   - moved from `../../index.js/src/runtime-middleware/` to
+ *     `@kodax-ai/session-lineage/src/runtime-middleware/` in v0.7.36 to
+ *     break the build cycle introduced by FEATURE_142 Batch D
+ *     (agent → session-lineage → agent). Semantically this also
+ *     reflects that the resolver consumes session-lineage's
+ *     `CompactionConfig`, so its canonical home is alongside
+ *     compaction policy types.
+ */
+
+/** Hard fallback. Mirrors Anthropic standard Claude window. */
+declare const DEFAULT_CONTEXT_WINDOW = 200000;
+declare function resolveContextWindow(compactionConfig: CompactionConfig, provider: KodaXBaseProvider, modelOverride: string | undefined): number;
+
+export { Agent, AgentManifest, AgentMessage, COMPACTION_SUMMARY_PREFIX, CORE_INVARIANTS, ChildTaskRegistry, CompactionConfig, CompactionDetails, CompactionResult, ConsoleTracingProcessor, DEFAULT_CONTEXT_WINDOW, DEFAULT_IDLE_YIELD_MAX_ITERATIONS, DEFAULT_MICROCOMPACTION_CONFIG, DEFAULT_POST_COMPACT_CONFIG, DEFAULT_SUMMARY_PROMPT, DEFAULT_UPDATE_SUMMARY_PROMPT, DequeueFilter, DiscoveredInstance, EnqueueInput, FileExtensionStore, FileTracingProcessor, Handoff, InstanceDiscoveryFs, InvariantId, KodaXExtensionStore, KodaXExtensionStoreEntry, KodaXJsonValue, KodaXMessage, KodaXSessionArtifactLedgerEntry, MAX_ENTRYPOINT_BYTES, MAX_ENTRYPOINT_LINES, ManifestPatch, MessageMode, MessagePriority, MessageQueue, POST_COMPACT_MAX_TOKENS_PER_FILE, POST_COMPACT_TOKEN_BUDGET, PROTECTED_TOOL_NAMES, QualityInvariant, QueuedMessage, RunnerToolCall, RunnerToolResult, SessionMeta, SessionStateSnapshot, Span, StateWriter, StateWriterFs, Trace, YIELD_TOOL_NAMES, _emitSpanEnd, _emitSpanStart, _emitTraceEnd, _getRegisteredProcessors, _resetAdmissionMetrics, _resetInvariantRegistry, _resetMessageQueueForTests, addTracingProcessor, applyManifestPatch, bootstrapTeamMode, buildCompactionPromptSnapshot, buildFileContentMessages, buildOtherInstancesPromptBlock, buildPostCompactAttachments, compact, composeIdleYieldUserMessage, composePatches, countLastAssistantToolCalls, createExtensionStore, detectHandoffSignal, detectIdleYield, emitHandoffSpan, enqueueChildTaskNotification, evidenceTrail, finalOwner, generateSummary, getActiveTeamModeWriter, getAdmissionMetricsSnapshot, getInvariant, getMessageQueue, gracefulCompactDegradation, handoffLegality, hashCwd, injectPostCompactAttachments, isAdmissionDebugEnabled, isAutoManagedMemoryFile, isEmptyLikeSummary, isIdleYieldEnabled, listRegisteredInvariants, maybeDrainMidTurn, microcompact, midTurnDrainPriority, needsCompaction, parseMemoryFile, parseMemoryType, parseMemoryTypeFromFilename, parseScalarFields, registerCoreInvariants, registerInvariant, replaceSystemMessage, resolveContextWindow, resolveEffectiveInvariants, resolveMemoryEntrypoint, resolveMemoryRoot, resolveRequiredInvariants, routeMessage, runFanOut, runWithIdleYield, sanitizeProjectKey, serializeConversation, setActiveTeamModeWriter, setTracingProcessors, shouldCompact, shutdownTracing, truncateEntrypointContent, tryGitRemote, updateActiveTeamMode, waitForWakeEvent };
+export type { AdmissionMetricsSnapshot, ConsoleTracingProcessorOptions, EnqueueChildTaskNotificationInput, EntrypointTruncation, EnvelopeAggregateEnforcer, FanOutOutcome, FanOutProgressEvent, FileTracingProcessorOptions, HandoffSignal, IdleYieldSnapshot, KodaXCompactionPromptSection, KodaXCompactionPromptSnapshot, KodaXCompactionPromptVariant, MaybeDrainMidTurnInput, MemoryFrontmatter, MemoryType, MicrocompactionConfig, ParsedMemoryFile, PostCompactAttachments, PostCompactConfig, RenderOptions, RouteMessageOptions, RouteMessageResult, RunFanOutOptions, RunFanOutResult, RunWithIdleYieldOptions, RunWithIdleYieldRunResult, ShouldCompactInput, TeamModeBootstrapOptions, TeamModeHandle, TracingProcessor, WaitForWakeEventOptions, WakeEvent };