@kodax-ai/kodax 0.7.43 → 0.7.44

package/dist/types-chunks/{file-tracker.d-zaLZeNBK.d.ts → types.d-DM8zEJgF.d.ts}

@@ -1,43 +1,173 @@
-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';
+import { X as KodaXToolDefinition, m as KodaXMessage, D as KodaXReasoningMode, Z as KodaXToolResultContentItem, T as KodaXThinkingBlock, G as KodaXRedactedThinkingBlock } from './types.d-B1uGoVTE.js';
+import { a as KodaXCompactMemorySeed, k as KodaXSessionArtifactLedgerEntry } from './types.d-HBbWT-iA.js';
 
 /**
- * @kodax-ai/agent Constants
+ * Layer A Primitive: Agent / Handoff / Guardrail / AgentReasoningProfile
  *
- * 通用 Agent 常量配置
+ * FEATURE_080 (v0.7.23): Agent-as-data types. Declarative dataclass shape.
+ * The runtime counterpart is `Runner` in `./runner.ts`.
+ *
+ * History: extracted to `@kodax-ai/core` in FEATURE_082 (v0.7.24); merged back
+ * into `@kodax-ai/agent` in v0.7.35.1 FEATURE_142 (single-consumer rule —
+ * @kodax-ai/core had only @kodax-ai/coding as consumer). `@kodax-ai/coding` retains
+ * a barrel re-export for batteries-included consumers.
+ *
+ * Status: @experimental — API shape may be refined during v0.7.x. Used by
+ * the task-engine rewrite in FEATURE_084 (v0.7.26).
+ *
+ * Guardrail and AgentReasoningProfile are declared here but their runtime
+ * behavior is deferred:
+ *   - Guardrail runtime → FEATURE_085 (v0.7.26)
+ *   - AgentReasoningProfile behavior → FEATURE_078 (v0.7.29)
  */
-declare const KODAX_MAX_TOKENS = 32768;
-declare const KODAX_DEFAULT_TIMEOUT = 60;
-declare const KODAX_HARD_TIMEOUT = 300;
-declare const KODAX_MAX_RETRIES = 3;
-declare const KODAX_RETRY_BASE_DELAY = 2;
-declare const KODAX_MAX_INCOMPLETE_RETRIES = 2;
-declare const KODAX_MAX_MAXTOKENS_RETRIES = 3;
-declare const KODAX_STAGGER_DELAY = 1;
-declare const KODAX_API_MIN_INTERVAL = 0.5;
-declare const PROMISE_PATTERN: RegExp;
 
 /**
- * @kodax-ai/agent Tokenizer
+ * Reasoning depth / mode selector. Alias for `KodaXReasoningMode` to keep the
+ * Layer A surface independent of the `KodaX*` brand; unified during the prefix
+ * cleanup in FEATURE_086 (v0.7.27).
+ */
+type ReasoningDepth = KodaXReasoningMode;
+/**
+ * Tool binding accepted by an `Agent`. Layer A treats tools as opaque
+ * definitions; the executor lives in `@kodax-ai/coding` and is wired up by the
+ * Runner when it dispatches through `runKodaX`.
+ */
+type AgentTool = KodaXToolDefinition;
+/**
+ * Transport-level message reused from the AI layer. Kept as an alias so
+ * consumers of the Layer A primitives do not need to import from `@kodax-ai/llm`
+ * directly.
+ */
+type AgentMessage = KodaXMessage;
+/**
+ * Declarative reasoning profile attached to an Agent.
  *
- * Token 估算 - 使用 tiktoken 进行精确计算
+ * In v0.7.23 this is a placeholder shape — only the `default` depth is read
+ * when the Runner dispatches to `runKodaX`. Escalation on revise/replan and
+ * max clamping are implemented in FEATURE_078 (v0.7.29).
  */
-
+interface AgentReasoningProfile {
+    readonly default: ReasoningDepth;
+    readonly max?: ReasoningDepth;
+    readonly escalateOnRevise?: boolean;
+}
+/**
+ * Declarative middleware reference attached to an Agent.
+ *
+ * FEATURE_100 (v0.7.29) introduces this field so the coding preset
+ * can declare the four substrate middlewares (auto-reroute,
+ * mutation-reflection, pre-answer-judge, post-tool-judge) on the
+ * Agent declaration itself. Today these middlewares fire inside
+ * the substrate body; the declaration field serves as the
+ * machine-readable contract that the substrate honours, and lets
+ * SDK consumers introspect / override middleware policy without
+ * touching `runKodaX` internals.
+ *
+ * `enabled` is the only knob today; future versions add config
+ * payload as additional fields (kept declarative — no fn callbacks).
+ */
+interface AgentMiddlewareDeclaration {
+    readonly name: string;
+    readonly enabled: boolean;
+}
 /**
- * 估算消息的 token 数量
+ * Guardrail placeholder. Layer A declares the slot; the actual
+ * input/output/tool-call gating runtime lives in FEATURE_085 (v0.7.26).
  *
- * 精确计算包括：
- * - 消息结构开销（每条约 4 tokens）
- * - 角色标识
- * - 内容文本
- * - 工具调用和结果
+ * A guardrail targets one of three hook points:
+ *   - `input`: inspect / veto prompts before they enter the agent loop.
+ *   - `output`: inspect / rewrite assistant messages before they leave.
+ *   - `tool`: inspect / veto tool invocations during the loop.
  */
-declare function estimateTokens(messages: KodaXMessage[]): number;
+interface Guardrail {
+    readonly kind: 'input' | 'output' | 'tool';
+    readonly name: string;
+}
 /**
- * 计算单个文本的 token 数量（便捷函数）
+ * Handoff between Agents.
+ *
+ *   - `continuation`: ownership of the conversation transfers to `target` and
+ *     the caller exits. Mirrors the Scout → Generator upgrade path.
+ *   - `as-tool`: `target` is invoked like a tool from within the caller loop;
+ *     only the generated input is passed, and control returns on completion.
+ *     Mirrors FEATURE_067 `dispatch_child_task`.
+ *
+ * `inputFilter` is applied to the visible history before the target runs;
+ * default is no filtering.
+ */
+interface Handoff<TTo = unknown> {
+    readonly target: Agent<TTo>;
+    readonly kind: 'continuation' | 'as-tool';
+    readonly description?: string;
+    readonly inputFilter?: (history: readonly AgentMessage[]) => readonly AgentMessage[];
+}
+/**
+ * Agent-as-data. A declarative specification of "who is running, with which
+ * instructions, tools, handoffs, and reasoning profile."
+ *
+ * Runtime note: in v0.7.23 the only Agent that is fully executed is the
+ * built-in coding preset (`createDefaultCodingAgent()`), which dispatches
+ * through `runKodaX`. Custom Agents defined by SDK consumers run through a
+ * generic Runner loop with limited capabilities (LLM call + Agent-declared
+ * tools only — no extensions, no managed-task harness). The full runtime
+ * arrives with FEATURE_084 (v0.7.26).
  */
-declare function countTokens(text: string): number;
+interface Agent<TContext = unknown> {
+    readonly name: string;
+    readonly instructions: string | ((ctx: TContext) => string);
+    readonly tools?: readonly AgentTool[];
+    readonly handoffs?: readonly Handoff[];
+    readonly reasoning?: AgentReasoningProfile;
+    readonly guardrails?: readonly Guardrail[];
+    /**
+     * FEATURE_191 — one-sentence human-readable summary surfaced to
+     * other agents that may dispatch this one (e.g., via the
+     * `dispatch_child_task(subagent_type=<name>)` Worker SP block). The
+     * field propagates from `AgentContent.description` when the agent is
+     * built via the construction substrate; built-in / SDK-created
+     * agents may set it directly. Optional for backward compatibility
+     * with the FEATURE_089 minimal-agent shape and pre-FEATURE_191
+     * built-ins.
+     */
+    readonly description?: string;
+    /** Reserved for structured-output agents; not consumed in v0.7.23. */
+    readonly outputSchema?: unknown;
+    readonly model?: string;
+    readonly provider?: string;
+    /**
+     * FEATURE_100 (v0.7.29) substrate executor: when set, `Runner.run`
+     * delegates execution to this function instead of consulting the
+     * preset-dispatcher registry or running the generic LLM loop. The
+     * coding preset attaches `runKodaX`'s full execution pipeline here so
+     * the SDK surface `Runner.run(createDefaultCodingAgent(), prompt, opts)`
+     * directly drives substrate without a `registerPresetDispatcher`
+     * indirection (the v0.7.23 "Option Y" facade).
+     *
+     * Type is intentionally `unknown` to avoid a `core/agent.ts` ↔
+     * `core/runner.ts` module cycle. `Runner.run` casts to the
+     * `PresetDispatcher` shape declared in `runner.ts` at the call site.
+     */
+    readonly substrateExecutor?: unknown;
+    /**
+     * FEATURE_100 (v0.7.29) declarative middleware list. The coding
+     * preset declares the four substrate middlewares it ships with
+     * (auto-reroute, mutation-reflection, pre-answer-judge,
+     * post-tool-judge). Substrate consults this list on entry and
+     * skips the corresponding step when `enabled === false`. SDK
+     * consumers can introspect or override declared middleware
+     * without touching the substrate body.
+     */
+    readonly middleware?: readonly AgentMiddlewareDeclaration[];
+}
+/**
+ * Ergonomic factory. Equivalent to a plain object literal but freezes the
+ * shape so tests cannot mutate a shared Agent by accident.
+ */
+declare function createAgent<TContext = unknown>(spec: Agent<TContext>): Agent<TContext>;
+/**
+ * Ergonomic factory for Handoff.
+ */
+declare function createHandoff<TTo = unknown>(spec: Handoff<TTo>): Handoff<TTo>;
 
 /**
  * Layer A Primitive: Session / SessionEntry / MessageEntry / SessionExtension
@@ -147,129 +277,200 @@ interface InMemorySessionOptions {
 declare function createInMemorySession(opts?: InMemorySessionOptions): Session;
 
 /**
- * Layer A Primitive: CompactionPolicy + DefaultSummaryCompaction
- *
- * FEATURE_081 (v0.7.23): Pluggable compaction for generic agent loops.
- *
- * Two layers:
- *   - Layer A (here): `CompactionPolicy` interface + `DefaultSummaryCompaction`
- *     — a minimal "token threshold → LLM summary of old messages" policy that
- *     any external Agent can pick up with zero KodaX runtime dependency.
- *   - Layer B (`../session-lineage/index.js/src/lineage.ts`): `LineageCompaction`
- *     wraps the full FEATURE_072 lineage-native compaction for the coding
- *     preset.
- *
- * The `compaction` entry shape written by `DefaultSummaryCompaction` is the
- * same type used by `LineageExtension`, so the two layers interoperate on
- * the same Session log.
- *
- * History: extracted to `@kodax-ai/core` in FEATURE_082 (v0.7.24); merged back
- * into `@kodax-ai/agent` in v0.7.35.1 FEATURE_142.
- */
-
-/**
- * Runtime context for a compaction pass. Abstracts the LLM/tokenizer
- * dependencies so policies stay independent of any specific provider.
- */
-interface CompactionContext {
+ * SpanData variants — payload shapes carried by each `Span`.
+ *
+ * FEATURE_083 (v0.7.24): the Agent-era tracing model uses a discriminated
+ * union so consumers (OpenTelemetry adapter, Langfuse adapter, KodaX
+ * built-in file processor) can render each span kind with type safety.
+ *
+ * Variants mirror the semantic events KodaX emits today:
+ *   - AgentSpanData     : one `Runner.run(agent, ...)` round
+ *   - GenerationSpanData: one provider LLM call
+ *   - ToolCallSpanData  : one tool invocation (including MCP tool)
+ *   - HandoffSpanData   : continuation or as-tool handoff between agents
+ *   - CompactionSpanData: one compaction pass (token-threshold or lineage)
+ *   - GuardrailSpanData : one guardrail check at input/output/tool
+ *   - EvidenceSpanData  : repo-intelligence / evidence acquisition
+ *   - FanoutSpanData    : parallel fanout bracket (winner-cancel capable)
+ *
+ * API surface is `@experimental` until v0.8.0 — shape may be refined as
+ * FEATURE_084 (v0.7.26) starts emitting these.
+ */
+interface AgentSpanData {
+    readonly kind: 'agent';
+    readonly agentName: string;
+    readonly model?: string;
+    readonly provider?: string;
+    readonly tools?: readonly string[];
+    readonly handoffs?: readonly string[];
+    readonly outputMessages?: number;
+    readonly error?: string;
+}
+interface GenerationSpanData {
+    readonly kind: 'generation';
+    readonly agentName: string;
+    readonly provider: string;
+    readonly model: string;
+    readonly inputMessages?: number;
+    readonly outputTokens?: number;
+    readonly inputTokens?: number;
+    readonly reasoningTokens?: number;
+    readonly cachedTokens?: number;
+    readonly usage?: {
+        readonly inputTokens?: number;
+        readonly outputTokens?: number;
+        readonly totalTokens?: number;
+        readonly reasoningTokens?: number;
+        readonly cachedTokens?: number;
+        readonly costUsd?: number;
+    };
+    readonly finishReason?: string;
+    readonly error?: string;
+}
+interface ToolCallSpanData {
+    readonly kind: 'tool_call';
+    readonly toolName: string;
+    readonly providerId?: string;
+    readonly capabilityId?: string;
+    readonly inputPreview?: string;
+    readonly outputPreview?: string;
+    readonly status: 'ok' | 'error';
+    readonly error?: string;
+}
+interface HandoffSpanData {
+    readonly kind: 'handoff';
+    readonly fromAgent: string;
+    readonly toAgent: string;
+    readonly handoffKind: 'continuation' | 'as-tool';
+    readonly description?: string;
+}
+interface CompactionSpanData {
+    readonly kind: 'compaction';
+    readonly policyName: string;
     readonly tokensUsed: number;
     readonly budget: number;
-    /**
-     * Summarizer implementation. Callers inject a function that maps a list of
-     * messages to a short summary string. In coding-preset mode this is wired
-     * to `runKodaX` internally; for external consumers it can call any LLM.
-     */
-    readonly summarize: (messages: readonly AgentMessage[]) => Promise<string>;
+    readonly replacedMessageCount: number;
+    readonly summaryLength: number;
+    readonly error?: string;
+}
+interface GuardrailSpanData {
+    readonly kind: 'guardrail';
+    readonly guardrailName: string;
+    readonly hookPoint: 'input' | 'output' | 'tool';
+    readonly decision: 'pass' | 'veto' | 'rewrite' | 'error';
+    readonly reason?: string;
+    readonly error?: string;
+}
+interface EvidenceSpanData {
+    readonly kind: 'evidence';
+    readonly source: string;
+    readonly queryPreview?: string;
+    readonly resultCount?: number;
+    readonly cacheHit?: boolean;
+    readonly error?: string;
+}
+interface FanoutSpanData {
+    readonly kind: 'fanout';
+    readonly agentName: string;
+    readonly childCount: number;
+    readonly winnerChildId?: string;
+    readonly cancelledChildIds?: readonly string[];
 }
 /**
- * Payload written to the `compaction` entry appended by `compact()`.
+ * FEATURE_184 (v0.7.45) — Stop hook observability.
+ *
+ * Emitted when the Runner's `RunOptions.stopHook` is invoked or fails.
+ * `outcome` records what the hook returned (or `'error'` for thrown
+ * exceptions — fail-open path), `reanimateCount` is the running count
+ * after this invocation. `reason` carries the abort/reanimate text
+ * when relevant, truncated by consumers as needed.
  */
-interface CompactionEntryPayload {
-    readonly summary: string;
-    readonly replacedMessageEntryIds: readonly string[];
+interface StopHookSpanData {
+    readonly kind: 'stop-hook';
+    readonly outcome: 'accept' | 'reanimate' | 'abort' | 'budget-exhausted' | 'error';
+    readonly reanimateCount: number;
+    readonly reanimateBudget: number;
+    readonly reason?: string;
+    readonly error?: string;
 }
 /**
- * Typed compaction entry. `type` is `'compaction'`; extensions (LineageExtension)
- * may claim this same type.
+ * Discriminated union of all span payload shapes. Additional variants may
+ * be added in future features — consumers should check `kind` before
+ * reading specific fields.
  */
-interface CompactionEntry extends SessionEntry {
-    readonly type: 'compaction';
-    readonly payload: CompactionEntryPayload;
-}
+type SpanData = AgentSpanData | GenerationSpanData | ToolCallSpanData | HandoffSpanData | CompactionSpanData | GuardrailSpanData | EvidenceSpanData | FanoutSpanData | StopHookSpanData;
+
 /**
- * Outcome of a single CompactionPolicy.compact() pass. Renamed from
- * `CompactionResult` to `PolicyCompactionResult` in v0.7.35.1 FEATURE_142
- * because the Layer A primitive collided with @kodax-ai/agent's pre-existing
- * `CompactionResult` (compaction/types.ts) used by the coding orchestration
- * post-compact pipeline. The two types model different things:
- *   - `PolicyCompactionResult` (here): "summary + replaced entry ids", the
- *     payload of one CompactionPolicy step.
- *   - `CompactionResult` (compaction/types.ts): the rich result of the
- *     coding-side multi-pass compaction (artifactLedger / memorySeed /
- *     tokensBefore / tokensAfter / etc).
+ * Span — a single timed unit of work inside a Trace.
+ *
+ * FEATURE_083 (v0.7.24): minimal Span implementation modeled after the
+ * openai-agents-python Trace/Span pattern.
+ *
+ * Design constraints:
+ *   - Span creation must be cheap (no await, no serialisation). Processors
+ *     do their own batching / flushing.
+ *   - `addChild()` is synchronous and immediately visible in the Trace tree.
+ *   - `end()` is idempotent; calling it twice is a no-op.
+ *   - `error` is an optional field that sets a flag on the span without
+ *     throwing. The consumer decides how to surface errors.
  */
-interface PolicyCompactionResult {
-    readonly summary: string;
-    readonly replacedMessageEntryIds: readonly string[];
+
+interface SpanError {
+    readonly message: string;
+    readonly stack?: string;
+    readonly data?: unknown;
 }
 /**
- * Pluggable compaction policy. Any multi-turn Agent loop can check
- * `shouldCompact()` at round boundaries and call `compact()` when it returns
- * true.
+ * Public Span interface. Concrete implementation is `SpanImpl`.
  */
-interface CompactionPolicy {
+interface Span {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
     readonly name: string;
-    shouldCompact(session: Session, tokensUsed: number, budget: number): boolean;
-    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
-    /** Optional: rehydrate compacted content when a restore hint is available. */
-    restore?(session: Session, hint: unknown): Promise<void>;
+    readonly data: SpanData;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+    readonly error?: SpanError;
+    readonly children: readonly Span[];
+    addChild(name: string, data: SpanData): Span;
+    setError(err: SpanError | Error): void;
+    end(): void;
 }
-/**
- * Configuration for `DefaultSummaryCompaction`.
- */
-interface DefaultSummaryCompactionOptions {
-    /**
-     * Fraction of `budget` at which compaction triggers. Default 0.8 (i.e.
-     * 80% of the token budget). Must be in (0, 1].
-     */
-    readonly thresholdRatio?: number;
-    /**
-     * Number of most-recent message entries to preserve verbatim. Default 10.
-     * Must be non-negative.
-     */
-    readonly keepRecent?: number;
-    /**
-     * Optional clock override (ms epoch). Useful for deterministic tests.
-     */
+interface SpanImplOptions {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
+    readonly name: string;
+    readonly data: SpanData;
+    readonly startedAt?: number;
     readonly now?: () => number;
-    /**
-     * Optional random-string override. Useful for deterministic tests.
-     */
-    readonly randomSuffix?: () => string;
+    readonly nextSpanId?: () => string;
+    readonly onChildCreated?: (span: Span) => void;
+    readonly onSpanEnd?: (span: Span) => void;
 }
-/**
- * Minimal "token threshold + LLM summary" compaction policy. Works on any
- * Session that stores `message` entries.
- *
- * Behavior:
- *   - `shouldCompact` returns true when `tokensUsed >= budget *
- *     thresholdRatio`.
- *   - `compact` reads all `message` entries, keeps the last `keepRecent`
- *     untouched, summarizes the rest via `ctx.summarize`, and appends a
- *     single `compaction` entry to the session.
- *
- * Caller is responsible for invoking `shouldCompact` and for interpreting the
- * appended entry when building the next turn's prompt.
- */
-declare class DefaultSummaryCompaction implements CompactionPolicy {
-    readonly name = "default-summary";
-    private readonly thresholdRatio;
-    private readonly keepRecent;
+declare class SpanImpl implements Span {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
+    readonly name: string;
+    readonly data: SpanData;
+    readonly startedAt: number;
+    private _endedAt?;
+    private _error?;
+    private readonly _children;
     private readonly now;
-    private readonly randomSuffix;
-    constructor(opts?: DefaultSummaryCompactionOptions);
-    shouldCompact(_session: Session, tokensUsed: number, budget: number): boolean;
-    compact(session: Session, ctx: CompactionContext): Promise<PolicyCompactionResult>;
+    private readonly nextSpanId;
+    private readonly onChildCreated?;
+    private readonly onSpanEnd?;
+    private _ended;
+    constructor(opts: SpanImplOptions);
+    get endedAt(): number | undefined;
+    get error(): SpanError | undefined;
+    get children(): readonly Span[];
+    addChild(name: string, data: SpanData): Span;
+    setError(err: SpanError | Error): void;
+    end(): void;
 }
 
 /**
@@ -894,6 +1095,155 @@ declare class InvariantSession {
  */
 declare function createInvariantSessionForAgent(agent: Agent): InvariantSession | undefined;
 
+/**
+ * Runner Tool Loop — FEATURE_084 Shard 1 (v0.7.26).
+ *
+ * Extends the Layer A Runner generic-dispatch path with tool-call support.
+ * Before Shard 1 the Runner could only do a single `system+user → assistant`
+ * turn. Now the injected LLM callback may return a structured result that
+ * declares tool calls; the Runner executes them, appends tool_use +
+ * tool_result content blocks, and loops until the LLM stops emitting tool
+ * calls (or MAX_TOOL_LOOP_ITERATIONS is reached).
+ *
+ * This Shard only lands the capability. No built-in Agent consumes it yet —
+ * the coding preset (SA path) continues to dispatch through
+ * `registerPresetDispatcher` unchanged.
+ *
+ * @experimental Shape may be refined during the v0.7.26 shard rollout.
+ */
+
+/**
+ * Hard ceiling on tool-loop iterations. A single run may invoke at most this
+ * many LLM turns (counting the initial turn); if the model keeps returning
+ * tool calls past this limit we abort to prevent runaway behaviour.
+ */
+declare const MAX_TOOL_LOOP_ITERATIONS = 20;
+/**
+ * One tool invocation requested by the LLM.
+ */
+interface RunnerToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly input: Record<string, unknown>;
+}
+/**
+ * Structured LLM result. Returning this instead of a plain string lets the
+ * Runner drive a tool loop. If `toolCalls` is empty or omitted the loop
+ * terminates and `text` becomes the final output.
+ */
+interface RunnerLlmResult {
+    readonly text: string;
+    readonly toolCalls?: readonly RunnerToolCall[];
+    readonly stopReason?: string;
+    /**
+     * v0.7.26 parity: extended-thinking blocks from the provider stream.
+     * Must be preserved on the assistant message so (a) session resume can
+     * re-render them and (b) Anthropic's extended-thinking API contract is
+     * honoured — provider rejects the next turn with a 400 when a tool_use
+     * turn's `thinking` block is missing from prior assistant history.
+     */
+    readonly thinkingBlocks?: readonly (KodaXThinkingBlock | KodaXRedactedThinkingBlock)[];
+}
+/**
+ * LLM callback return type. `string` preserves the v0.7.23 single-turn
+ * behaviour; `RunnerLlmResult` opts into the tool loop.
+ */
+type RunnerLlmReturn = string | RunnerLlmResult;
+/**
+ * Observer callbacks fired around every tool invocation. Preset
+ * dispatchers (e.g. the coding Runner-driven path) pass these through
+ * `RunOptions.toolObserver` so REPL / CLI consumers see live
+ * `onToolCall` / `onToolResult` events, matching the legacy task-engine
+ * event surface (v0.7.22 agent.ts fired `events.onToolResult` at three
+ * sites per invocation).
+ */
+interface RunnerToolObserver {
+    /**
+     * Permission / policy gate fired BEFORE each tool invocation. Return
+     * `true` (or `undefined`) to allow, `false` to block with a generic
+     * message, or a `string` to block with that message as the tool result.
+     * Used to hook plan-mode / accept-edits / extension `tool:before`
+     * policies onto the Runner-driven path (v0.7.22 parity — legacy
+     * `events.beforeToolExecute` surface).
+     */
+    readonly beforeTool?: (call: RunnerToolCall) => Promise<boolean | string | undefined>;
+    readonly onToolCall?: (call: RunnerToolCall) => void;
+    readonly onToolResult?: (call: RunnerToolCall, result: RunnerToolResult) => void;
+}
+/**
+ * Context passed to a RunnableTool's `execute` function.
+ */
+interface RunnerToolContext {
+    readonly agent: Agent;
+    readonly abortSignal?: AbortSignal;
+    /** The agent's Span, so tool implementations can nest custom spans if needed. */
+    readonly agentSpan?: Span | null;
+    /**
+     * Current tool_use call id. Passed through so tool wrappers can correlate
+     * progress events (`onToolProgress`) and other per-call side-effects with
+     * the REPL's tool-block in the transcript. Populated by `executeRunnerToolCall`.
+     */
+    readonly toolCallId?: string;
+}
+/**
+ * Value returned by `RunnableTool.execute`. The `content` is what the LLM
+ * sees in the next turn as `tool_result`:
+ *
+ *   - `string` — plain text (the default for most tools).
+ *   - `readonly KodaXToolResultContentItem[]` — an array of typed items
+ *     (text + image), used by multimodal tools like `read` on an image
+ *     path. Provider serializers lower each item to the wire format
+ *     (Anthropic accepts inline; OpenAI-compat downgrades image to text
+ *     placeholder).
+ */
+interface RunnerToolResult {
+    readonly content: string | readonly KodaXToolResultContentItem[];
+    readonly isError?: boolean;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * A tool bundled with its executor. Extends `AgentTool` (the wire-format
+ * `KodaXToolDefinition`) so it can be passed through to the provider
+ * unchanged while also carrying a function the Runner can invoke.
+ */
+interface RunnableTool extends AgentTool {
+    readonly execute: (input: Record<string, unknown>, ctx: RunnerToolContext) => Promise<RunnerToolResult>;
+}
+/**
+ * Narrowing helper — distinguishes a `RunnableTool` from a plain
+ * `AgentTool`. An agent may declare both: the Runner only executes the
+ * tools that carry an `execute` function.
+ */
+declare function isRunnableTool(tool: AgentTool): tool is RunnableTool;
+/**
+ * Narrowing helper for the LLM callback return shape.
+ */
+declare function isRunnerLlmResult(value: unknown): value is RunnerLlmResult;
+/**
+ * Execute one tool call against the agent's declared tools. Emits a
+ * ToolCallSpan under `ctx.agentSpan` when tracing is active. Returns a
+ * `RunnerToolResult` — tool errors do not throw, they are surfaced with
+ * `isError: true` so the LLM can see them in the next turn and react.
+ */
+declare function executeRunnerToolCall(call: RunnerToolCall, agent: Agent, ctx: RunnerToolContext): Promise<RunnerToolResult>;
+/**
+ * Build the assistant message that captures one LLM turn. Preserves
+ * thinking blocks (extended-thinking contract), text blocks, and tool_use
+ * blocks in the order Anthropic's wire format expects: thinking → text →
+ * tool_use. This mirrors v0.7.22 `agent.ts:2230`
+ * (`[...thinkingBlocks, ...textBlocks, ...visibleToolBlocks]`) which the
+ * Runner-driven path must preserve — without it Anthropic returns 400 on
+ * the next turn when extended thinking is active, and session resume
+ * loses the reasoning trace.
+ */
+declare function buildAssistantMessageFromLlmResult(result: RunnerLlmResult): AgentMessage;
+/**
+ * Build the user message that carries tool_result blocks back to the LLM.
+ * Provider serializers (Anthropic, OpenAI) both accept tool_result on the
+ * user turn.
+ */
+declare function buildToolResultMessage(calls: readonly RunnerToolCall[], results: readonly RunnerToolResult[]): AgentMessage;
+
 /**
  * Layer A Primitive: Runner
  *
@@ -1316,468 +1666,612 @@ declare class Runner {
 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
+ * Guardrail Runtime — FEATURE_085 (v0.7.26).
  *
- * Capability inventory: docs/features/v0.7.29-capability-inventory.md#cap-002
+ * Three-tier runtime for Agent guardrails:
  *
- * Two pure functions that maintain the assistant↔user `tool_use`/`tool_result`
- * pairing invariant the provider expects. Both functions take a message array
- * and return a new array (immutable — never mutate the input).
+ *   - `InputGuardrail`: runs once before the first LLM turn, inspects the
+ *     full input transcript, may allow / rewrite / block / escalate.
+ *   - `OutputGuardrail`: runs once before returning, inspects the final
+ *     assistant message, may allow / rewrite / block / escalate.
+ *   - `ToolGuardrail`: runs before and/or after each tool invocation,
+ *     inspects the call / result, may allow / rewrite / block / escalate.
  *
- *   - `cleanupIncompleteToolCalls`: when a stream is interrupted mid-flight,
- *     the last assistant message may carry orphan `tool_use` blocks with no
- *     matching `tool_result`. The next provider call would 400 with
- *     "tool_call_id not found". This function strips those orphans before
- *     the next request.
+ * The four verdict actions:
  *
- *   - `validateAndFixToolHistory`: deeper pass that walks the full message
- *     history and fixes mis-pairings on both sides — orphan `tool_use` in
- *     assistant messages, orphan `tool_result` in user messages, and ensures
- *     no message becomes empty after stripping (Kimi specifically rejects
- *     empty assistant messages with 400, so we inject a `'...'` placeholder
- *     when stripping would empty an assistant message).
+ *   - `allow`: continue with the current value.
+ *   - `rewrite`: replace the current value with `payload`.
+ *   - `block`: throw `GuardrailBlockedError` (for input/output) or surface
+ *     an error tool_result (for tool-before); the LLM / caller sees a
+ *     rejection and must adapt.
+ *   - `escalate`: throw `GuardrailEscalateError`; the SDK consumer catches
+ *     and decides whether to prompt the user, retry under different
+ *     constraints, etc.
  *
- * Migration history: extracted from `agent.ts` (originally lines 517–758)
- * during FEATURE_100 P2. Both `agent.ts` and `task-engine/runner-driven.ts`
- * already consume these via the package re-export (`@kodax-ai/coding`).
+ * Every guardrail invocation emits a `GuardrailSpan` under the agent's
+ * span when tracing is active.
  *
- * Type guards are inlined here rather than imported from agent.ts because
- * the migration's whole point is to remove dependencies on agent.ts. If
- * additional agent-runtime modules need the same guards in the future,
- * extract them to `agent-runtime/content-blocks.ts`.
+ * @experimental API shape may adjust during v0.7.x rollout.
  */
 
 /**
- * Walk the message history and remove mis-paired `tool_use` / `tool_result`
- * blocks. Preserves message order and structure; never mutates input.
+ * Shared execution context passed to every guardrail.
  *
- * Rules enforced:
- *   - assistant `tool_use` with no matching `tool_result` in the next user
- *     message → removed
- *   - assistant `tool_use` with empty / missing id → removed
- *   - user `tool_result` with no matching assistant `tool_use` in the previous
- *     message → removed
- *   - user `tool_result` with empty / missing tool_use_id → removed
- *   - assistant message that becomes content-empty after stripping → inject
- *     a `'...'` placeholder text block (preserves message-alternation invariant
- *     downstream providers like Kimi require)
- */
-declare function validateAndFixToolHistory(messages: KodaXMessage[]): KodaXMessage[];
-/**
- * Strip orphan `tool_use` blocks from the LAST assistant message only.
+ * `messages` is the live conversation transcript at the moment this
+ * guardrail fires. For tool-side guardrails this is the transcript at
+ * call-site time — it does NOT yet include the assistant turn that
+ * emitted the current tool_use, since that turn is appended only after
+ * the full tool batch settles. Optional so existing guardrails that
+ * don't read context still type-check; populated by the Runner for all
+ * production hook points.
  *
- * Used as a quick pre-stream guard when a previous turn was interrupted
- * (Issue 072): the last assistant message has unanswered tool_use blocks,
- * and the next provider request would 400 with "tool_call_id not found".
- *
- * Cheaper than `validateAndFixToolHistory` because it only touches the tail.
+ * Added in FEATURE_092 (v0.7.33) so the auto-mode classifier guardrail
+ * can extract intent context (user prompt + prior tool_use / tool_result
+ * blocks) without reaching into Runner internals.
  */
-declare function cleanupIncompleteToolCalls(messages: KodaXMessage[]): KodaXMessage[];
-
+interface GuardrailContext {
+    readonly agent: Agent;
+    readonly abortSignal?: AbortSignal;
+    readonly messages?: readonly AgentMessage[];
+}
 /**
- * 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.
+ * Outcome of a single guardrail check. `payload` shape depends on the hook
+ * point — see the specific guardrail interface for the expected type.
  */
-
+type GuardrailVerdict = {
+    readonly action: 'allow';
+} | {
+    readonly action: 'rewrite';
+    readonly payload: unknown;
+    readonly reason?: string;
+} | {
+    readonly action: 'block';
+    readonly reason: string;
+} | {
+    readonly action: 'escalate';
+    readonly reason: string;
+};
 /**
- * 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).
+ * Input-side guardrail. Expected `rewrite` payload shape:
+ * `readonly AgentMessage[]` — the replacement transcript.
  */
-declare const LINEAGE_ENTRY_TYPES: readonly ["message", "label", "compaction", "branch_summary", "archive_marker", "rewind_marker", "artifact_ledger"];
-type LineageEntryType = (typeof LINEAGE_ENTRY_TYPES)[number];
+interface InputGuardrail extends Guardrail {
+    readonly kind: 'input';
+    check(input: readonly AgentMessage[], ctx: GuardrailContext): Promise<GuardrailVerdict>;
+}
 /**
- * Payload shape for a `label` entry. Mirrors
- * `KodaXSessionLabelEntry.targetId`/`label` fields on the legacy lineage.
+ * Output-side guardrail. Expected `rewrite` payload shape:
+ * `AgentMessage` — the replacement final assistant message.
  */
-interface LineageLabelPayload {
-    readonly targetId: string;
-    readonly label?: string;
+interface OutputGuardrail extends Guardrail {
+    readonly kind: 'output';
+    check(output: AgentMessage, ctx: GuardrailContext): Promise<GuardrailVerdict>;
 }
 /**
- * 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.
+ * Tool-side guardrail. `beforeTool` rewrite payload shape: `RunnerToolCall`
+ * (replacement call). `afterTool` rewrite payload shape: `RunnerToolResult`
+ * (replacement result). Either hook is optional.
  */
-interface LineageArtifactLedgerPayload {
-    readonly ref: string;
-    readonly kind?: string;
-    readonly summary?: string;
+interface ToolGuardrail extends Guardrail {
+    readonly kind: 'tool';
+    beforeTool?(call: RunnerToolCall, ctx: GuardrailContext): Promise<GuardrailVerdict>;
+    afterTool?(call: RunnerToolCall, result: RunnerToolResult, ctx: GuardrailContext): Promise<GuardrailVerdict>;
 }
 /**
- * Projected tree node. Mirrors the navigation shape of
- * `KodaXSessionTreeNode` from `../index.js/types.ts`, restricted to the
- * fields the base Session can supply.
+ * Thrown when any guardrail returns `{ action: 'block' }`. The Runner
+ * propagates this up to the caller — the run is aborted at that point.
  */
-interface LineageTreeNode {
-    readonly entry: SessionEntry;
-    readonly children: LineageTreeNode[];
-    readonly label?: string;
+declare class GuardrailBlockedError extends Error {
+    readonly guardrailName: string;
+    readonly hookPoint: 'input' | 'output' | 'tool';
+    constructor(guardrailName: string, hookPoint: 'input' | 'output' | 'tool', reason: 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.
+ * Thrown when any guardrail returns `{ action: 'escalate' }`. Callers can
+ * catch and prompt the user or apply a stricter policy before retrying.
  */
-declare const LineageExtension: SessionExtension;
-
+declare class GuardrailEscalateError extends Error {
+    readonly guardrailName: string;
+    readonly hookPoint: 'input' | 'output' | 'tool';
+    constructor(guardrailName: string, hookPoint: 'input' | 'output' | 'tool', reason: string);
+}
+/** Filter a guardrail list by hook-point. */
+declare function collectGuardrails(guardrails: readonly Guardrail[] | undefined): {
+    input: readonly InputGuardrail[];
+    output: readonly OutputGuardrail[];
+    tool: readonly ToolGuardrail[];
+};
 /**
- * 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`.
+ * Run all input guardrails in declaration order. Returns the (possibly
+ * rewritten) transcript. Throws on block / escalate.
  */
-
+declare function runInputGuardrails(transcript: readonly AgentMessage[], guardrails: readonly InputGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<readonly AgentMessage[]>;
 /**
- * Delegates required to implement `LineageCompaction`. The coding preset
- * supplies implementations that bridge to the existing FEATURE_072 code
- * paths.
+ * Run all output guardrails in declaration order. Returns the (possibly
+ * rewritten) final assistant message. Throws on block / escalate.
  */
-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>;
-}
+declare function runOutputGuardrails(output: AgentMessage, guardrails: readonly OutputGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<AgentMessage>;
 /**
- * `CompactionPolicy` implementation that preserves FEATURE_072 lineage-native
- * compaction semantics by delegating to injected coding-preset functions.
+ * Outcome of the before-tool guardrail stage.
+ *   - `{ kind: 'allow', call }`: continue to executeRunnerToolCall with `call`
+ *   - `{ kind: 'block', result }`: skip execution; return `result` as the
+ *     tool_result to the LLM (so it sees the rejection and can adapt)
  */
-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>;
-}
-
+type ToolBeforeOutcome = {
+    readonly kind: 'allow';
+    readonly call: RunnerToolCall;
+} | {
+    readonly kind: 'block';
+    readonly result: RunnerToolResult;
+};
 /**
- * ../index.js Session
- *
- * 会话管理 - Session ID 生成和消息处理
+ * Run before-tool guardrails in declaration order. Rewrite replaces the
+ * tool call. Block surfaces an error tool_result to the LLM instead of
+ * throwing — the LLM sees the rejection and adapts. Escalate still throws.
  */
-
+declare function runToolBeforeGuardrails(call: RunnerToolCall, guardrails: readonly ToolGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<ToolBeforeOutcome>;
 /**
- * 生成会话 ID
- * 格式: YYYYMMDD_HHMMSS
+ * Run after-tool guardrails in declaration order. Rewrite replaces the
+ * result content. Block replaces with an error result. Escalate throws.
  */
-declare function generateSessionId(): Promise<string>;
+declare function runToolAfterGuardrails(call: RunnerToolCall, result: RunnerToolResult, guardrails: readonly ToolGuardrail[], ctx: GuardrailContext, agentSpan: Span | null): Promise<RunnerToolResult>;
+
 /**
- * 从消息中提取标题
- * 取第一条用户消息的前50个字符
- */
-declare function extractTitleFromMessages(messages: KodaXMessage[]): string;
+ * Child task registry primitive — generic fan-out tracking.
+ *
+ * FEATURE_120 v0.7.39 Step 0 (package-attribution migration, ADR-021).
+ * Lifted from `@kodax-ai/coding`'s `KodaXToolExecutionContext.childTaskRegistry`
+ * field + inline cleanup chain in `tools/dispatch-child-tasks.ts`. The
+ * coding side now consumes this primitive specialized to its
+ * `KodaXChildExecutionResult` type; any other agent-flavor downstream
+ * can specialize on its own child-result type without re-implementing
+ * the cleanup contract.
+ *
+ * The shape is intentionally minimal: a Map plus a `register` helper
+ * that bundles the v0.7.38 FEATURE_155 Bug A hotfix (`c1bdaf4e`)
+ * cleanup chain into a single call site. The helper exists because
+ * the cleanup is **not optional** — without it, every settled promise
+ * stays in the registry forever, gets re-wrapped by the next
+ * idle-yield `waitForWakeEvent` call, and fires spurious
+ * `child-completed` wakes (production symptom: Evaluator gets
+ * bombarded by duplicate `<task-completed>` notifications, consuming
+ * an LLM turn each up to `IDLE_YIELD_MAX_ITERATIONS=64`).
+ */
+/**
+ * Map of `task_id` → in-flight child-execution promise. Generic over
+ * the child-result type so the agent layer doesn't depend on any
+ * specific agent flavor's result shape.
+ *
+ * Mutation contract:
+ *   - Owned by the runner's per-turn execution context. The dispatch
+ *     tool writes via `registerChildTask`; the idle-yield outer loop
+ *     reads via `Map.prototype.entries()` / `.size`.
+ *   - **Never delete entries manually** — call `registerChildTask`
+ *     and the cleanup chain it installs will run on settle.
+ */
+type ChildTaskRegistry<T> = Map<string, Promise<T>>;
+/**
+ * Register an in-flight child-execution promise in the registry and
+ * install the cleanup chain that removes the entry once the promise
+ * settles (success or failure).
+ *
+ * The cleanup chain is two stages:
+ *   1. `.finally(() => registry.delete(childId))` — runs on settle
+ *      regardless of outcome, removing the entry before the next
+ *      idle-yield outer-loop iteration observes the registry.
+ *   2. `.catch(() => {})` — swallows the rejection on the cleanup
+ *      chain so a child that crashes before any consumer awaits it
+ *      doesn't surface as `unhandledRejection` on Node. Must come
+ *      AFTER `.finally` because `.finally` returns a NEW promise
+ *      that rejects with the same reason.
+ *
+ * The original `promise` argument is **not** returned — the helper's
+ * value-add is the cleanup side-effect, not promise transformation.
+ * Callers that need to await the result read from `registry.get(id)`
+ * or hold their own reference.
+ *
+ * @throws Error when `childId` already exists in the registry. Caller
+ *   should report this to the LLM as a tool-error (duplicate task_id);
+ *   the helper does NOT swallow the conflict because that would
+ *   silently overwrite an in-flight child's tracking entry.
+ */
+declare function registerChildTask<T>(registry: ChildTaskRegistry<T>, childId: string, promise: Promise<T>): void;
 
-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;
+ * Generic per-task abort primitive — `requestTaskStop`.
+ *
+ * FEATURE_120 v0.7.39 Phase 3a (ADR-021). Coordinator-style agents need
+ * to request that a specific in-flight child task exit gracefully. The
+ * @kodax-ai/agent layer owns the abort-controller registry shape and
+ * the abort-dispatch decision; agent-flavor wrappers (e.g. the coding
+ * `task_stop` tool, Phase 3b) layer in domain framing such as the
+ * `<coordinator-stop-request>` message tag.
+ *
+ * What this primitive owns:
+ *   - A `TaskAbortRegistry` type alias = `Map<string, AbortController>`.
+ *     The map is owned + mutated by the caller; the primitive only
+ *     reads it. Callers use `registry.set(id, controller)` /
+ *     `registry.delete(id)` directly — the standard `Map` mutators
+ *     are simple enough that wrapping them adds no value.
+ *   - `requestTaskStop({taskId, registry, reason?})` — looks up the
+ *     controller, decides whether to abort, calls `controller.abort`,
+ *     returns a structured outcome.
+ *
+ * Abort semantics (matches the existing FEATURE_115 soft-pause
+ * principle): aborting fires the signal but does NOT interrupt any
+ * synchronous tool that's already executing. The child's next abort
+ * check (`signal.throwIfAborted()` or an `signal.aborted` poll)
+ * surfaces the abort. This matches Node's AbortController contract.
+ *
+ * What this primitive does NOT do (deliberate):
+ *   - Enqueue a coordinator-stop-request message — that's a
+ *     coding-flavor convenience and uses the existing
+ *     `routeMessage` primitive at the tool layer.
+ *   - Track abort lifecycle / auto-cleanup the registry — the
+ *     controller's lifetime is tied to its owning task's Promise;
+ *     the caller removes the registry entry when the task settles
+ *     (typically in a `.finally` chain alongside the child-task
+ *     registry cleanup).
+ *   - Time-out enforcement / retry — orthogonal concerns owned at
+ *     higher layers if needed.
+ */
+/**
+ * Registry mapping task ids to their owning AbortController.
+ * Lifetime: created per parent-run, populated at child dispatch,
+ * cleared when the child Promise settles.
+ */
+type TaskAbortRegistry = Map<string, AbortController>;
+interface RequestTaskStopOptions {
+    /** Target task id. Must exist as a key in `registry`. */
+    readonly taskId: string;
+    /** Registry of in-flight task abort controllers. */
+    readonly registry: ReadonlyMap<string, AbortController>;
+    /**
+     * Optional cause forwarded to `AbortController.abort(reason)`.
+     *   - Error → passed through verbatim (preserves stack / custom
+     *     subclasses).
+     *   - string → wrapped in `new Error(reason)`.
+     *   - undefined → a default Error mentioning the taskId is
+     *     fabricated so the child receives a non-empty signal.reason.
+     */
+    readonly reason?: string | Error;
+}
+type RequestTaskStopResult = {
+    readonly ok: true;
+    readonly taskId: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'unknown-target';
+    readonly taskId: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'already-aborted';
+    readonly taskId: string;
+};
 /**
- * Walk the lineage from a target entry back to the root.
+ * Look up `taskId` in `registry`. If found and not yet aborted, abort
+ * the controller with the supplied reason. Returns a discriminated
+ * outcome so callers can render success / error UX without string
+ * matching.
  *
- * 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.
+ * `already-aborted` is reported separately from success because the
+ * first-abort `signal.reason` is preserved verbatim — debugging
+ * chains depend on the original cause not being overwritten by
+ * subsequent stop requests.
  *
- * 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.
+ * Synchronous: `AbortController.abort` is synchronous; no async work
+ * is performed by this primitive.
  */
-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;
+declare function requestTaskStop(opts: RequestTaskStopOptions): RequestTaskStopResult;
+
 /**
- * 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_125 (v0.7.41) — Team Mode Layer 1: per-instance state broadcast.
+ *
+ * Each running KodaX session registers a directory under
+ * `<agentConfigHome>/instances/<pid>/` containing three files:
+ *
+ *   meta.json   — written once at registration; cwd / startedAt /
+ *                  optional git branch + remote. Static for the session.
+ *   state.json  — re-written whenever the session's `currentIntent`,
+ *                  `agentPhase`, or active/recently-modified file set
+ *                  changes. Read by sibling sessions for context.
+ *   heartbeat   — empty file whose mtime is touched on every refresh.
+ *                  Sibling sessions use the mtime to declare an instance
+ *                  stale (default 30s of no heartbeat → cleanup).
+ *
+ * Atomic write strategy:
+ *   - state.json is written via `<path>.tmp` + `rename()`. On POSIX the
+ *     rename is atomic; on Windows it is atomic when source + target sit
+ *     on the same filesystem (always true for `<agentConfigHome>/...`).
+ *   - heartbeat is touched via `utimesSync()`. Cheap, no rename needed.
+ *
+ * Lifecycle:
+ *   - `createStateWriter` writes meta.json + state.json + heartbeat once,
+ *     then starts an interval timer (default 1000ms) that refreshes
+ *     state.json and touches heartbeat.
+ *   - `update(patch)` shallow-merges the patch into the in-memory state
+ *     and flushes immediately so peer sessions see the change at the
+ *     next tool boundary, not at the next heartbeat tick.
+ *   - `shutdown()` clears the timer, removes the instance directory,
+ *     and resolves. Idempotent — safe to call multiple times.
+ *
+ * Crash recovery:
+ *   - If a process is killed mid-run, the directory is left on disk.
+ *     The next session's discovery scan (S2, `instance-discovery.ts`)
+ *     detects the stale heartbeat and removes the directory.
+ *
+ * DI-clean: every fs / clock dependency is injectable for hermetic tests.
+ */
+/**
+ * Live session state surfaced to sibling KodaX sessions. Mirrors the
+ * shape documented in `docs/features/v0.7.41.md#feature_125-step-1`.
+ */
+interface SessionStateSnapshot {
+    readonly agentPhase: 'idle' | 'awaiting_llm' | 'running_tool';
+    /** Single-line description of what the agent is currently doing. */
+    readonly currentIntent?: string;
+    /** Files the session is actively editing right now. */
+    readonly activeFiles?: readonly string[];
+    /** Files modified in the recent past (sibling sessions read this to detect "their content may be stale"). */
+    readonly recentlyModifiedFiles?: readonly RecentlyModifiedFile[];
+    /**
+     * FEATURE_170 (v0.7.41) — optional one-line summary of the active
+     * todo list. Lets sibling sessions display "they're currently
+     * working on: <X>" without owning the todo store.
+     */
+    readonly currentTodoSummary?: CurrentTodoSummary;
+    /**
+     * v0.7.43 (FEATURE_173 Part B follow-up) — REPL session id
+     * (e.g. `YYYYMMDD_HHMMSS`). Lets `listRunningSessions()` correlate
+     * a sibling instance with its `.jsonl` file. Mutable: starts
+     * undefined during bootstrap, set after `createInteractiveContext`,
+     * re-published on `/new`. Older writers omit this; readers MUST
+     * treat as optional.
+     */
+    readonly sessionId?: string;
+}
+interface RecentlyModifiedFile {
+    readonly path: string;
+    readonly modifiedAt: number;
+}
+interface CurrentTodoSummary {
+    readonly inProgress?: string;
+    readonly pendingCount: number;
+    readonly completedCount: number;
+}
+interface SessionMeta {
+    readonly cwd: string;
+    readonly startedAt: number;
+    readonly gitBranch?: string;
+    readonly gitRemote?: string;
+}
 /**
- * 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.
+ * Stored shape of `state.json` on disk — additive over SessionStateSnapshot.
  *
- * 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.
+ * Reader contract (S2 `instance-discovery.ts`): parse the JSON, verify
+ * `version === '1'` before reading any other field. On an unknown
+ * version, log + skip the instance — this lets a newer writer coexist
+ * with an older reader during an in-place upgrade.
  *
- * @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
+ * Fields are camelCase + a nested `meta` object (cwd / startedAt /
+ * gitBranch / gitRemote). Do NOT assume the snake_case / flat shape
+ * shown in early design-doc drafts — the typed interface here is the
+ * ground truth; the doc has been updated to match.
  */
+interface PersistedSessionState extends SessionStateSnapshot {
+    readonly version: '1';
+    readonly pid: number;
+    readonly updatedAt: number;
+    readonly meta: SessionMeta;
+}
+/** Minimal injectable fs surface — lets tests drive the writer without disk I/O. */
+interface StateWriterFs {
+    mkdirSync(dirPath: string, options: {
+        recursive: true;
+    }): void;
+    writeFileSync(filePath: string, data: string): void;
+    /** Atomic write helper: writes to `${filePath}.tmp` then renames. */
+    atomicWriteSync(filePath: string, data: string): void;
+    utimesSync(filePath: string, atime: number, mtime: number): void;
+    rmSync(dirPath: string, options: {
+        recursive: true;
+        force: true;
+    }): void;
+    existsSync(targetPath: string): boolean;
+}
+interface StateWriterOptions {
+    /** Defaults to `process.pid`. Tests / multi-instance fixtures override. */
+    readonly pid?: number;
+    readonly meta: SessionMeta;
+    readonly initialState: SessionStateSnapshot;
+    /** Defaults to 1000ms. Tests pass a faster tick. */
+    readonly heartbeatIntervalMs?: number;
+    /** Defaults to `Date.now`. Tests inject a controllable clock. */
+    readonly clock?: () => number;
+    /** Defaults to {@link REAL_FS}. Tests inject an in-memory fs. */
+    readonly fs?: StateWriterFs;
+    /**
+     * Root directory under which `<pid>/` is created. Defaults to
+     * `getAgentConfigPath('instances')`. Tests can point at a temp dir.
+     */
+    readonly instancesRoot?: string;
+}
+interface StateWriter {
+    readonly pid: number;
+    readonly instanceDir: string;
+    /** Apply a partial update to the in-memory state and flush to disk. */
+    update(patch: Partial<SessionStateSnapshot>): void;
+    /** Touch the heartbeat and re-write state.json without changing state. */
+    refresh(): void;
+    /** Stop the interval, remove the instance directory, resolve when done. */
+    shutdown(): Promise<void>;
+    /** Read-only snapshot of the current state. Useful for tests. */
+    getState(): SessionStateSnapshot;
+}
 /**
- * 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.
+ * Construct a writer, register the instance directory, and start the
+ * heartbeat interval. Returns synchronously so the caller can rely on
+ * `instanceDir` being live the moment the function returns.
  */
-declare function countActiveLineageMessages(lineage: KodaXSessionLineage): number;
+declare function createStateWriter(options: StateWriterOptions): StateWriter;
+
 /**
- * Archive message entries from old "islands" (disconnected subtrees).
+ * FEATURE_125 (v0.7.41) — Team Mode Layer 2a: sibling instance discovery.
  *
- * 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.
+ * Scans `<agentConfigHome>/instances/`, filters out the caller's own
+ * pid, drops any directory whose `heartbeat` file is stale (>30s of no
+ * touch), parses `state.json`, validates `version === '1'`, and returns
+ * a typed list of live sibling instances. Stale directories are
+ * optionally reaped (`reapStale: true`) — the next session entering
+ * Team Mode does the cleanup so crashed processes don't accumulate
+ * forever.
  *
- * 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)
+ * Per-instance failures (corrupt JSON, vanished file mid-read, permission
+ * error) are isolated: the bad directory is logged + skipped, the rest
+ * of the scan completes. Discovery NEVER throws to its caller — a
+ * Team-Mode-disabled return is `[]`, not an exception. This keeps the
+ * worker LLM call path resilient to one peer session's bad state.
  *
- * Only entries outside the preserve closure are archived.
+ * DI-clean: every fs / clock / logger dependency is injectable so
+ * hermetic tests can simulate stale / corrupt / mid-scan-deletion
+ * scenarios without real disk.
  */
-declare function archiveOldIslands(lineage: KodaXSessionLineage): {
-    slimmedLineage: KodaXSessionLineage;
-    archivedEntries: KodaXSessionEntry[];
-    archivedCount: number;
-    archiveBatchId: string;
-};
 
+/** A sibling KodaX session that passed stale + version-guard checks. */
+interface DiscoveredInstance {
+    readonly pid: number;
+    readonly state: PersistedSessionState;
+    /** Heartbeat mtime in ms (epoch). Useful for ordering "freshest first". */
+    readonly heartbeatMtimeMs: number;
+}
+/** Minimal injectable fs surface used by `discoverInstances`. */
+interface InstanceDiscoveryFs {
+    existsSync(targetPath: string): boolean;
+    readdirSync(dirPath: string): string[];
+    /** Returns the mtime of the path in ms, or `null` if missing / unreadable. */
+    statMtimeMs(filePath: string): number | null;
+    readFileSync(filePath: string, encoding: 'utf8'): string;
+    rmSync(dirPath: string, options: {
+        recursive: true;
+        force: true;
+    }): void;
+}
+interface DiscoveryOptions {
+    /**
+     * pid to exclude from the result. Defaults to `process.pid` — the
+     * caller's own state.json should not appear in its own sibling list.
+     */
+    readonly excludePid?: number;
+    /**
+     * Heartbeat mtime older than `now - staleThresholdMs` → directory is
+     * stale. Default 30_000 (matches v0.7.41 spec).
+     */
+    readonly staleThresholdMs?: number;
+    /**
+     * When true, stale directories are removed during the scan (best-
+     * effort `rmSync(force:true)`; failure is swallowed). When false,
+     * stale directories are skipped but left on disk. Defaults to false
+     * — wire from the session-startup path with `true` so crashed-process
+     * dirs don't accumulate.
+     */
+    readonly reapStale?: boolean;
+    readonly clock?: () => number;
+    readonly fs?: InstanceDiscoveryFs;
+    readonly instancesRoot?: string;
+    /** Per-instance failure log; defaults to a no-op. Pass `console.warn` in dev. */
+    readonly logger?: (message: string) => void;
+}
 /**
- * ../../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: ...]`
+ * Synchronous discovery scan. Returns a freshness-sorted array
+ * (newest heartbeat first) so callers that want only the N most-recent
+ * siblings can slice without re-sorting.
  *
- *   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.
+ * Never throws. A missing `<instancesRoot>` directory means the user
+ * is the first session ever on this machine → `[]`. A scan failure on
+ * one entry is logged + skipped, not propagated.
+ */
+declare function discoverInstances(options?: DiscoveryOptions): DiscoveredInstance[];
+
+/**
+ * ../../index.js Compaction Types
  */
 
-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[];
+interface CompactionConfig {
+    /** Whether automatic compaction is enabled. */
+    enabled: boolean;
+    /** Trigger compaction when context usage exceeds this percentage of the window. */
+    triggerPercent: number;
+    /**
+     * @deprecated V2 compaction no longer uses this option.
+     *
+     * The system now combines protected recent context, lightweight pruning, and
+     * rolling summaries automatically.
+     */
+    keepRecentPercent?: number;
+    /** Percentage of the most recent context that is never compacted or pruned. Defaults to 20. */
+    protectionPercent?: number;
+    /**
+     * Percentage of the context window used as the chunk size for each rolling
+     * summary pass. Defaults to 10.
+     */
+    rollingSummaryPercent?: number;
+    /** Prune oversized tool results when they exceed roughly this many tokens. Defaults to 500. */
+    pruningThresholdTokens?: number;
+    /**
+     * Gap ratio for prune fast-return. After pruning, if remaining tokens still exceed
+     * triggerTokens * pruningGapRatio, the system continues to the summarization path
+     * instead of returning early. Defaults to 0.8.
+     */
+    pruningGapRatio?: number;
+    /** Optional override for the provider context window. */
+    contextWindow?: number;
+}
+interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+interface CompactionAnchor {
+    summary: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    entriesRemoved: number;
+    reason: string;
+    artifactLedgerId?: string;
+    details?: CompactionDetails;
+    memorySeed?: KodaXCompactMemorySeed;
+}
+interface CompactionUpdate {
+    anchor?: CompactionAnchor;
+    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
+    memorySeed?: KodaXCompactMemorySeed;
+    /**
+     * FEATURE_072: ledger-summary + file-content messages produced by
+     * `buildPostCompactAttachments` + `buildFileContentMessages`. Agent.ts
+     * passes these separately from the kept-tail messages so REPL-side
+     * `applySessionCompaction` can store them natively on the CompactionEntry
+     * rather than inlining them as loose `[Post-compact: ...]` system messages
+     * in lineage. Agent.ts keeps inlining them into its local flat `messages`
+     * via `injectPostCompactAttachments` (P4 belt-and-suspenders); the lineage
+     * is the persistence source of truth.
+     */
+    postCompactAttachments?: readonly KodaXMessage[];
+}
+interface CompactionResult {
+    compacted: boolean;
+    messages: KodaXMessage[];
+    summary?: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    entriesRemoved: number;
+    details?: CompactionDetails;
+    artifactLedger?: KodaXSessionArtifactLedgerEntry[];
+    anchor?: CompactionAnchor;
+    memorySeed?: KodaXCompactMemorySeed;
+}
+interface FileOperations {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
 
-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 };
+export { DEFAULT_SYSTEM_CAP as D, InvariantSession as O, MAX_TOOL_LOOP_ITERATIONS as P, getAdmittedAgentBindings as a$, Runner as a6, Tracer as aI, _resetAdmittedAgentBindings as aK, _resetPresetDispatchers as aL, buildAssistantMessageFromLlmResult as aM, buildSystemPrompt as aN, buildToolResultMessage as aO, collectGuardrails as aP, createAgent as aQ, createHandoff as aR, createInMemorySession as aS, createInvariantSessionForAgent as aT, createStateWriter as aU, createTrace as aV, defaultTracer as aW, detectInstructionsInjection as aX, discoverInstances as aY, executeRunnerToolCall as aZ, extractAssistantTextFromMessage as a_, SpanImpl as ao, isRunnableTool as b0, isRunnerLlmResult as b1, registerChildTask as b2, registerPresetDispatcher as b3, requestTaskStop as b4, runAdmissionAudit as b5, runInputGuardrails as b6, runOutputGuardrails as b7, runToolAfterGuardrails as b8, runToolBeforeGuardrails as b9, setAdmittedAgentBindings as ba, GuardrailBlockedError as w, GuardrailEscalateError as y };
+export type { RecentlyModifiedFile as $, AdmissionAuditOptions as A, GuardrailVerdict as B, ChildTaskRegistry as C, EvidenceSpanData as E, FanoutSpanData as F, GenerationSpanData as G, Handoff as H, HandoffSpanData as I, InMemorySessionOptions as J, InputGuardrail as K, InstanceDiscoveryFs as L, InvariantId as M, InvariantResult as N, ManifestPatch as Q, MessageEntry as R, ObserveCtx as S, OutputGuardrail as T, PersistedSessionState as U, PresetDispatcher as V, PresetTracingContext as W, QualityInvariant as X, ReadonlyMutationTracker as Y, ReadonlyRecorder as Z, ReasoningDepth as _, AdmissionCtx as a, RequestTaskStopOptions as a0, RequestTaskStopResult as a1, RunEvent as a2, RunOptions as a3, RunResult as a4, RunnableTool as a5, RunnerEvent as a7, RunnerLlmResult as a8, RunnerLlmReturn as a9, TerminalCtx as aA, ToolBeforeOutcome as aB, ToolCallSpanData as aC, ToolCapability as aD, ToolGuardrail as aE, ToolPermission as aF, Trace as aG, TraceOptions as aH, TracerOptions as aJ, RunnerToolCall as aa, RunnerToolContext as ab, RunnerToolObserver as ac, RunnerToolResult as ad, Session as ae, SessionDispatchResult as af, SessionEntry as ag, SessionExtension as ah, SessionForkOptions as ai, SessionMeta as aj, SessionStateSnapshot as ak, Span as al, SpanData as am, SpanError as an, SpanImplOptions as ap, StartTraceOptions as aq, StateWriter as ar, StateWriterFs as as, StateWriterOptions as at, StopHookContext as au, StopHookFn as av, StopHookResult as aw, StopHookSpanData as ax, SystemCap as ay, TaskAbortRegistry as az, AdmissionVerdict as b, AdmittedHandle as c, Agent as d, AgentManifest as e, AgentMessage as f, AgentMiddlewareDeclaration as g, AgentReasoningProfile as h, AgentSpanData as i, AgentTool as j, CompactionAnchor as k, CompactionConfig as l, CompactionDetails as m, CompactionResult as n, CompactionSpanData as o, CompactionUpdate as p, CurrentTodoSummary as q, Deliverable as r, DiscoveredInstance as s, DiscoveryOptions as t, FileOperations as u, Guardrail as v, GuardrailContext as x, GuardrailSpanData as z };