@kodax-ai/kodax 0.7.71 → 0.7.72

package/dist/types-chunks/public-api.d--IDNJsu1.d.ts

@@ -0,0 +1,1342 @@
+import { a as BashPrefixExtractor, t as KodaXAgentMode } from './bash-prefix-extractor.d-CHJO5y94.js';
+import { F as KodaXReasoningMode, k as KodaXMessage, S as KodaXTaskResultMetadata } from './types.d-Cqaw71Ax.js';
+import { p as LearningSurfaceSnapshot$1, n as LearningQuery, m as LearningPage, b as LearnedCapabilityRecord, j as LearningEvent, o as LearningSubscribeOptions } from './center-types.d-BBT122uJ.js';
+import { bG as KodaXSessionData, bL as KodaXSessionLineage, bQ as KodaXSessionNavigationOptions, bS as KodaXSessionRuntimeInfo, bU as KodaXSessionStorage, i as AgentActorSnapshot, bx as KodaXJsonValue } from './types.d-DH1mvdcl.js';
+
+/**
+ * TextBuffer - Text buffer management class - 文本缓冲区管理类
+ *
+ * Reference implementation: Gemini CLI text-buffer.ts - 参考实现: Gemini CLI text-buffer.ts
+ * Supports multi-line text editing, cursor navigation, and Unicode-safe operations - 支持多行文本编辑，光标导航，Unicode 安全操作
+ */
+interface CursorPosition {
+    row: number;
+    col: number;
+}
+interface VisualCursor$1 {
+    row: number;
+    col: number;
+}
+interface TextBufferOptions {
+    maxHistory?: number;
+}
+declare class TextBuffer {
+    private _text;
+    private _lines;
+    private _cursor;
+    private _rememberedCol;
+    private _history;
+    private _historyIndex;
+    private _maxHistory;
+    constructor(options?: TextBufferOptions);
+    get text(): string;
+    get lines(): string[];
+    get cursor(): CursorPosition;
+    get lineCount(): number;
+    get currentLine(): string;
+    get isEmpty(): boolean;
+    /**
+     * Get visual width of current line - 获取当前行的视觉宽度
+     */
+    get currentLineVisualWidth(): number;
+    /**
+     * Get visual position of cursor (considering wide characters) - 获取光标的视觉位置（考虑宽字符）
+     */
+    get visualCursor(): VisualCursor$1;
+    /**
+     * Get visual width of character at cursor position on current line - 获取当前行在光标位置的字符视觉宽度
+     */
+    getCharWidthAtCursor(): number;
+    /**
+     * Convert visual column position to logical column position - 将视觉列位置转换为逻辑列位置
+     */
+    visualColToLogicalCol(visualCol: number): number;
+    /**
+     * Move to visual column position - 移动到视觉列位置
+     */
+    moveToVisualCol(visualCol: number): void;
+    /**
+     * Set entire text content - 设置整个文本内容
+     */
+    setText(text: string): void;
+    /**
+     * Replace a text range and leave the cursor after the replacement.
+     */
+    replaceRange(start: number, end: number, replacement: string): void;
+    /**
+     * Insert text at cursor position - 在光标位置插入文本
+     */
+    insert(text: string, options?: {
+        paste?: boolean;
+    }): void;
+    /**
+     * Insert text on current line - 在当前行插入文本
+     */
+    private _insertText;
+    /**
+     * Insert newline character - 插入换行符
+     */
+    newline(): void;
+    private _insertNewline;
+    /**
+     * Delete character before cursor - 删除光标前的字符
+     */
+    backspace(): void;
+    /**
+     * Delete character after cursor - 删除光标后的字符
+     */
+    delete(): void;
+    /**
+     * Move cursor - 移动光标
+     */
+    move(direction: "up" | "down" | "left" | "right" | "home" | "end"): void;
+    private _moveUp;
+    private _moveDown;
+    private _moveLeft;
+    private _moveRight;
+    private _moveHome;
+    private _moveEnd;
+    /**
+     * Clamp column position within current line range using rememberedCol - 限制列位置在当前行范围内，使用 rememberedCol
+     */
+    private _clampColumn;
+    /**
+     * Clamp cursor to valid range - 限制光标在有效范围内
+     */
+    private _clampCursor;
+    /**
+     * Delete content from cursor to end of line (Ctrl+K) - 删除光标到行尾的内容 (Ctrl+K)
+     */
+    killLineRight(): void;
+    /**
+     * Delete content from line start to cursor (Ctrl+U) - 删除行首到光标的内容 (Ctrl+U)
+     */
+    killLineLeft(): void;
+    /**
+     * Delete word before cursor (Ctrl+W) - 删除光标前的一个词 (Ctrl+W)
+     */
+    deleteWordLeft(): void;
+    private _saveHistory;
+    /**
+     * Undo - 撤销
+     */
+    undo(): boolean;
+    /**
+     * Redo - 重做
+     */
+    redo(): boolean;
+    private _updateText;
+    private _setTextInternal;
+    /**
+     * Move cursor to an absolute string offset - 将光标移动到文本中的绝对偏移位置
+     */
+    moveToAbsoluteOffset(offset: number): void;
+    /**
+     * Clear buffer - 清空缓冲区
+     */
+    clear(): void;
+    /**
+     * Get absolute position of cursor in text - 获取光标在文本中的绝对位置
+     */
+    getAbsoluteOffset(): number;
+    /**
+     * Check if current line ends with backslash - 检查当前行是否以反斜杠结尾
+     */
+    isLineContinuation(): boolean;
+    /**
+     * Move cursor to end of entire text - 将光标移动到整个文本的末尾
+     */
+    moveToEnd(): void;
+}
+
+/**
+ * PasteStore — per-session paste content registry + placeholder ref helpers.
+ *
+ * Design: see docs/KNOWN_ISSUES.md Issue 121 (三层防御：粘贴拦截 / 输入兜底 / 渲染硬上限).
+ * Reference implementation: Claude Code src/history.ts + src/utils/pasteStore.ts.
+ *
+ * Responsibilities (pure / deterministic where possible):
+ * - Format / parse `[Pasted text #N +K lines]` and related refs
+ * - Allocate monotonic per-session paste IDs
+ * - Store / expand paste content in memory
+ * - Find placeholder boundaries adjacent to cursor (for atomic edit)
+ *
+ * Stateful concerns are confined to the `PasteStore` class. Everything else is
+ * pure so rendering and controller code can call them safely.
+ */
+type PastedContentType = "text" | "image";
+interface PastedContent {
+    id: number;
+    type: PastedContentType;
+    content: string;
+    /** Optional sha256 hash — set when backed by on-disk paste-cache */
+    contentHash?: string;
+    /** Media type for image pastes; unused for text */
+    mediaType?: string;
+    /** Optional filename hint for image pastes */
+    filename?: string;
+}
+/**
+ * Session-scoped stateful registry. One instance per REPL session (not per
+ * paste). Lives as long as the composer. IDs are monotonic and never recycled
+ * so undo/redo never collides with a fresh paste that reused an id.
+ */
+declare class PasteStore {
+    private readonly contents;
+    private nextId;
+    /**
+     * Register text content, returns the allocated id + the placeholder string
+     * to insert into the buffer in place of the raw content.
+     */
+    registerText(content: string): {
+        id: number;
+        placeholder: string;
+        numLines: number;
+    };
+    /**
+     * Register pre-computed Layer 2 truncation output. Caller is responsible
+     * for constructing the truncated text; this just stores the middle chunk.
+     */
+    registerTruncatedText(content: string): {
+        id: number;
+        numLines: number;
+    };
+    /**
+     * Adopt a pre-allocated id + content (e.g. when restoring from disk-backed
+     * input history).
+     */
+    adopt(entry: PastedContent): void;
+    /** Allocate the NEXT id without registering anything yet. */
+    peekNextId(): number;
+    get(id: number): PastedContent | undefined;
+    /** Expand all placeholders in `input` using this store's contents. */
+    expand(input: string): string;
+    /**
+     * Snapshot the current contents map. Returned map is a COPY — mutation does
+     * not leak back. Used by undo buffer snapshots.
+     */
+    snapshot(): Map<number, PastedContent>;
+    /** Replace contents from a snapshot. Used by undo. `nextId` preserved. */
+    restore(snapshot: ReadonlyMap<number, PastedContent>): void;
+    /**
+     * Session-level reset. Called on `/clear`, start-new-session, etc.
+     * Does NOT clear on per-submit since Up-arrow navigation re-submits may
+     * reuse stored refs.
+     */
+    reset(): void;
+    size(): number;
+    /** Export contents for persistence (input history serialization). */
+    export(): PastedContent[];
+}
+
+/**
+ * Permission Types
+ */
+
+/**
+ * Permission mode
+ * - plan: Read-only planning, all modifications blocked unless explicitly whitelisted
+ * - accept-edits: File edits auto-approved, shell commands require confirmation
+ * - auto: All tools auto-approved (with optional LLM classifier review when
+ *         auto-mode engine === 'llm'; FEATURE_092 v0.7.33). When engine === 'rules',
+ *         falls back to the legacy "all tools approved within project, outside
+ *         requires confirmation" behavior — i.e., the v0.7.32 `auto-in-project`
+ *         shape. The `auto-in-project` name is preserved as a deprecated alias
+ *         for 5 minor versions (removed in v0.7.38).
+ */
+type PermissionMode = "plan" | "accept-edits" | "auto" | "auto-in-project";
+declare const PERMISSION_MODES: PermissionMode[];
+/**
+ * Status-bar display name for a permission mode. Title-Case short labels
+ * (mirrors Claude Code's `shortTitle` convention in
+ * `src/utils/permissions/PermissionMode.ts`):
+ *   - `plan`             → `Plan`
+ *   - `accept-edits`     → `Edits`
+ *   - `auto`             → `Auto`
+ *   - `auto-in-project`  → `Auto`  (deprecated alias folds into the canonical
+ *                                   display name; the deprecation notice
+ *                                   surfaces once per session at startup)
+ *
+ * Single source of truth for command output, startup summaries, and the live
+ * Ink status-bar view-model. The former write-only readline StatusBar was
+ * removed; Classic continues to use the same display helper in text surfaces.
+ */
+declare function permissionModeDisplayName(mode: PermissionMode): string;
+interface ConfirmResult {
+    confirmed: boolean;
+    always?: boolean;
+}
+/**
+ * Tools that mutate the local filesystem AND accept a `path` input.
+ * Eligible for plan-mode's path-aware escape (writes to
+ * `.agent/plan_mode_doc.md` or the system temp dir are permitted; all
+ * other paths block).
+ *
+ * Derived from metadata: `sideEffect === 'mutates-fs'` AND
+ * `requiredParams.includes('path')`. Tools that mutate the FS without a
+ * `path` input (`undo`, `worktree_*`, construction-staircase tools) are
+ * NOT in this set — their plan-mode block reason is computed elsewhere
+ * via `isToolPlanModeAllowed()` instead of a path check.
+ */
+declare const FILE_MODIFICATION_TOOLS: Set<string>;
+interface PermissionContext {
+    permissionMode: PermissionMode;
+    confirmTools: Set<string>;
+    gitRoot?: string;
+    alwaysAllowTools: string[];
+    onConfirm?: (tool: string, input: Record<string, unknown>) => Promise<ConfirmResult>;
+    saveAlwaysAllowTool?: (tool: string, input: Record<string, unknown>, allowAll?: boolean) => void;
+    switchPermissionMode?: (mode: PermissionMode) => void;
+    beforeToolExecute?: (tool: string, input: Record<string, unknown>) => Promise<boolean | string>;
+    /**
+     * FEATURE_153 (v0.7.38) — Optional LLM-backed bash command prefix extractor.
+     * When supplied, `isToolCallAllowed` uses it to extract the SAFE PREFIX of
+     * a bash command before matching against allowlist patterns like
+     * `Bash(git commit:*)`. This eliminates the pre-FEATURE_153 vulnerability
+     * where `git commit -m "x" $(curl evil)` matched the allowlist via naive
+     * `command.startsWith` semantics.
+     *
+     * KodaX REPL bootstrap creates this via `createBashPrefixExtractor` from
+     * `@kodax-ai/coding` and threads it here. SDK consumers / tests without
+     * LLM access can omit it; legacy startsWith semantics apply (documented
+     * as insecure in `matchesBashPatternLegacy`).
+     */
+    bashPrefixExtractor?: BashPrefixExtractor;
+}
+/**
+ * Compute the base confirmation set for each permission mode.
+ *
+ * Note: `plan` still lists the standard mutating tools here even though most of
+ * them are blocked earlier in the permission pipeline via `getPlanModeBlockReason`.
+ * This helper only describes the remaining confirmation step for calls that are
+ * not hard-blocked.
+ */
+declare function computeConfirmTools(mode: PermissionMode): Set<string>;
+declare function isPermissionMode(value: string | undefined): value is PermissionMode;
+declare function normalizePermissionMode(value: string | undefined, fallback?: PermissionMode): PermissionMode | undefined;
+
+/**
+ * Keyboard info interface - 键盘信息接口
+ * Reference: Gemini CLI Key interface - 参考: Gemini CLI Key interface
+ */
+interface KeyInfo {
+    name: string;
+    sequence: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    insertable: boolean;
+    isPasted?: boolean;
+    mouse?: {
+        action: "press" | "release" | "drag" | "move" | "wheel";
+        button: "left" | "middle" | "right" | "wheelup" | "wheeldown" | "unknown";
+        row: number;
+        column: number;
+    };
+}
+
+type PromptEditingMode = "idle" | "typing" | "pasting";
+interface UseTextBufferReturn {
+    buffer: TextBuffer;
+    text: string;
+    cursor: CursorPosition;
+    lines: string[];
+    isPasting: boolean;
+    editingMode: PromptEditingMode;
+    /**
+     * Issue 121: session-scoped paste registry. Registered paste ids survive
+     * submit so Up-arrow input-history recall can still expand them.
+     */
+    pasteStore: PasteStore;
+    resetTransientState: () => void;
+    setText: (text: string) => void;
+    replaceRange: (start: number, end: number, replacement: string) => void;
+    insert: (text: string, options?: {
+        paste?: boolean;
+    }) => void;
+    newline: () => void;
+    backspace: () => void;
+    delete: () => void;
+    move: (direction: "up" | "down" | "left" | "right" | "home" | "end") => void;
+    moveToEnd: () => void;
+    moveToOffset: (offset: number) => void;
+    killLineRight: () => void;
+    killLineLeft: () => void;
+    deleteWordLeft: () => void;
+    clear: () => void;
+    undo: () => boolean;
+    redo: () => boolean;
+}
+/**
+ * Visual Layout Interface - 视觉布局接口
+ * Reference: Gemini CLI text-buffer.ts - VisualLayout
+ */
+interface VisualLayout {
+    /** All visual lines for rendering - 所有视觉行（用于渲染） */
+    visualLines: string[];
+    /** For each logical line: [[visualLineIndex, startColInLogical], ...] - 每个逻辑行 -> 视觉行索引 + 起始列的映射 */
+    logicalToVisualMap: Array<Array<[number, number]>>;
+    /** For each visual line: [logicalLineIndex, startColInLogical] - 每个视觉行 -> 逻辑行 + 起始列的映射 */
+    visualToLogicalMap: Array<[number, number]>;
+}
+type VisualCursor = [number, number];
+/**
+ * An input-history entry. `text` is the display form (may contain
+ * `[Pasted text #N]` placeholders). `pastedContents`, when present, carries
+ * the stored contents needed to expand those placeholders after recall.
+ *
+ * Issue 121: pastedContents preserves paste fidelity across Up-arrow and
+ * undo. For entries loaded from disk-backed history, contents may carry only
+ * `contentHash` until `retrievePastedText` resolves them.
+ */
+interface HistoryEntry {
+    text: string;
+    timestamp: number;
+    pastedContents?: PastedContent[];
+}
+interface Completion {
+    text: string;
+    display: string;
+    description?: string;
+    type: "file" | "command" | "argument";
+}
+interface Completer {
+    canComplete(input: string, cursorPos: number): boolean;
+    getCompletions(input: string, cursorPos: number): Promise<Completion[]>;
+}
+/**
+ * Autocomplete suggestion item - 自动补全建议项
+ * For SuggestionsDisplay component - 用于 SuggestionsDisplay 组件
+ */
+interface Suggestion {
+    id: string;
+    text: string;
+    displayText?: string;
+    description?: string;
+    type?: "command" | "file" | "history" | "argument" | "snippet" | "skill";
+    icon?: string;
+}
+interface ThemeColors {
+    primary: string;
+    secondary: string;
+    accent: string;
+    text: string;
+    dim: string;
+    thinking: string;
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    hint: string;
+    background: string;
+    inputBackground: string;
+}
+interface ThemeSymbols {
+    prompt: string;
+    success: string;
+    error: string;
+    warning: string;
+    spinner: string[];
+}
+interface Theme {
+    name: string;
+    colors: ThemeColors;
+    symbols: ThemeSymbols;
+}
+interface PromptSubmitPayload {
+    /**
+     * Display form — what the user saw in the input bar. May contain
+     * `[Pasted text #N +K lines]` placeholders or `[...Truncated text #N ...]`
+     * refs (Issue 121).
+     */
+    displayText: string;
+    /**
+     * Fully expanded form — all paste placeholders substituted for their raw
+     * stored contents. This is what parseCommand / the agent pipeline consume.
+     */
+    fullText: string;
+    /** Paste contents referenced by displayText — for persistence / recall. */
+    pastedContents: PastedContent[];
+}
+interface InputPromptProps {
+    onSubmit: (payload: PromptSubmitPayload) => void;
+    placeholder?: string;
+    prompt?: string;
+    focus?: boolean;
+    initialValue?: string;
+    /** Callback when input text changes - 输入文本变化时的回调 */
+    onInputChange?: (text: string) => void;
+    /** Called for a transient UI notice when image paste falls back to text. */
+    onPasteFallback?: (message: string) => void;
+    /**
+     * Called when the ↑ arrow history recall brings back an entry with stored
+     * paste contents. Consumer can hydrate a disk-backed paste cache here.
+     */
+    onHistoryRecall?: (entry: {
+        text: string;
+        pastedContents: PastedContent[];
+    }) => void;
+    /**
+     * FEATURE_149 Phase 2.1 (v0.7.38) — pop the queued follow-up inputs back
+     * into the editor when the user presses ↑ on an empty buffer. Return the
+     * joined text to load (queue gets atomically cleared by the consumer), or
+     * `undefined` to leave history-recall behavior intact when the queue is
+     * empty.
+     */
+    onPopPendingInputs?: () => string | undefined;
+}
+type LearningSurfaceSnapshot = LearningSurfaceSnapshot$1;
+interface LearningBinding {
+    getSnapshot(): Promise<LearningSurfaceSnapshot>;
+    list(query?: LearningQuery): Promise<LearningPage>;
+    get(nameOrSlug: string): Promise<LearnedCapabilityRecord>;
+    subscribe(listener: (event: LearningEvent) => void, options?: LearningSubscribeOptions): {
+        close(): void;
+    };
+    acknowledge(nameOrSlug: string): Promise<void>;
+    snooze(nameOrSlug: string, until: string): Promise<void>;
+    reject(nameOrSlug: string): Promise<void>;
+    disable(nameOrSlug: string): Promise<void>;
+    rollback(nameOrSlug: string): Promise<void>;
+    promote(nameOrSlug: string, scope: 'user'): Promise<void>;
+    review(nameOrSlug: string): Promise<void>;
+    trust(nameOrSlug: string): Promise<void>;
+}
+interface StatusBarProps {
+    sessionId: string;
+    permissionMode: PermissionMode;
+    agentMode: KodaXAgentMode;
+    provider: string;
+    model: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    currentTool?: string;
+    activeToolCount?: number;
+    thinking?: boolean;
+    reasoningMode?: KodaXReasoningMode;
+    effort?: string;
+    reasoningEffortLabel?: string;
+    reasoningCapability?: string;
+    /** Is context currently compacting - 是否正在压缩上下文 */
+    isCompacting?: boolean;
+    /** Thinking character count - Issue 068: 显示 thinking 进度 */
+    thinkingCharCount?: number;
+    /** Whether a thinking stream is currently active */
+    isThinkingActive?: boolean;
+    /** Tool input character count - Issue 068: 显示 tool 输入进度 */
+    toolInputCharCount?: number;
+    /** Tool input content (truncated) - Issue 068 Phase 4: 显示参数摘要 */
+    toolInputContent?: string;
+    /** Current iteration number - Issue 068: 显示迭代进度 */
+    currentIteration?: number;
+    /** Maximum iterations - Issue 068: 显示迭代进度 */
+    maxIter?: number;
+    /** Context usage info - Issue 070: 显示上下文使用情况 */
+    contextUsage?: {
+        /** Current token count in context */
+        currentTokens: number;
+        /** Context window size (effective contextWindow) */
+        contextWindow: number;
+        /** Compaction trigger percentage (0-100) */
+        triggerPercent: number;
+        /** Provider output capacity reserved from the physical context window. */
+        reservedResponseTokens?: number;
+    };
+    /** Client-specific Learning Center projection. Inventory alone stays hidden. */
+    learning?: LearningSurfaceSnapshot;
+    /** Whether current busy/thinking status should be visible in the bar */
+    showBusyStatus?: boolean;
+    managedPhase?: "starting" | "routing" | "preflight" | "round" | "worker" | "upgrade" | "verifying" | "completed";
+    managedHarnessProfile?: string;
+    managedWorkerTitle?: string;
+    managedRound?: number;
+    managedMaxRounds?: number;
+    managedGlobalWorkBudget?: number;
+    managedBudgetUsage?: number;
+    managedBudgetApprovalRequired?: boolean;
+    /**
+     * v0.7.38 FEATURE_156 — true when the runner-driven outer loop is
+     * parked in `waitForWakeEvent` (idle-yield from FEATURE_155). The
+     * status bar renders this as "{role} - waiting for N children"
+     * instead of falling back to the last role-emit label, so the user
+     * can tell the spinner is actively waiting on something concrete.
+     * Consumers MUST branch on `=== true` (undefined transitions out).
+     */
+    managedIdleWaiting?: boolean;
+    /** v0.7.38 FEATURE_156 — child count surfaced in the idle-wait label. */
+    managedIdleWaitingPendingCount?: number;
+    /**
+     * FEATURE_092 phase 2b.8: classifier engine indicator. Only renders when
+     * permissionMode is in the auto family. `'llm'` shows green `auto[LLM]`
+     * (healthy), `'rules'` shows yellow `auto[RULES]` (downgraded — every
+     * non-Tier-1 tool call escalates to user confirm).
+     */
+    autoModeEngine?: 'llm' | 'rules';
+}
+/**
+ * @deprecated Use MessageListProps from components/MessageList.js instead
+ */
+interface LegacyMessageListProps {
+    messages: Message[];
+    isLoading?: boolean;
+}
+interface Message {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: number;
+}
+interface AppState {
+    messages: Message[];
+    isLoading: boolean;
+    error?: string;
+    sessionId: string;
+}
+interface AppProps {
+    model: string;
+    provider: string;
+    onSubmit: (input: string) => Promise<void>;
+    permissionMode?: PermissionMode;
+    agentMode?: KodaXAgentMode;
+}
+/**
+ * Streaming response state enum - 流式响应状态枚举
+ * Reference: Gemini CLI StreamingContext.tsx - 参考: Gemini CLI StreamingContext.tsx
+ */
+declare enum StreamingState {
+    Idle = "idle",
+    Responding = "responding",
+    WaitingForConfirmation = "waiting_for_confirmation"
+}
+/**
+ * Tool call status enum - 工具调用状态枚举
+ * Reference: Gemini CLI useToolScheduler - 参考: Gemini CLI useToolScheduler
+ */
+declare enum ToolCallStatus {
+    Scheduled = "scheduled",
+    Validating = "validating",
+    AwaitingApproval = "awaiting_approval",
+    Executing = "executing",
+    Success = "success",
+    Error = "error",
+    Cancelled = "cancelled"
+}
+/**
+ * Tool call status icons - 工具调用状态图标
+ */
+declare const TOOL_STATUS_ICONS: Record<ToolCallStatus, string>;
+/**
+ * Single tool call - 单个工具调用
+ */
+interface ToolCall {
+    id: string;
+    name: string;
+    status: ToolCallStatus;
+    input?: Record<string, unknown>;
+    preview?: string;
+    output?: unknown;
+    error?: string;
+    progress?: number;
+    /** Real-time progress lines displayed inside the tool block during execution. */
+    progressLines?: string[];
+    startTime: number;
+    endTime?: number;
+}
+/**
+ * History item type - 历史项类型
+ * Reference: Gemini CLI HistoryItem - 参考: Gemini CLI HistoryItem
+ */
+type HistoryItemType = "user" | "assistant" | "system" | "tool_group" | "thinking" | "error" | "event" | "info" | "hint" | "sidecar";
+/**
+ * History item base class - 历史项基类
+ */
+interface HistoryItemBase {
+    id: string;
+    type: HistoryItemType;
+    timestamp: number;
+}
+/**
+ * User message - 用户消息
+ */
+interface HistoryItemUser extends HistoryItemBase {
+    type: "user";
+    text: string;
+}
+/**
+ * Assistant message - 助手消息
+ */
+interface HistoryItemAssistant extends HistoryItemBase {
+    type: "assistant";
+    text: string;
+    compactText?: string;
+    isStreaming?: boolean;
+}
+/**
+ * System message - 系统消息
+ */
+interface HistoryItemSystem extends HistoryItemBase {
+    type: "system";
+    text: string;
+}
+/**
+ * Tool group - 工具组
+ */
+interface HistoryItemToolGroup extends HistoryItemBase {
+    type: "tool_group";
+    tools: ToolCall[];
+}
+/**
+ * Thinking content - 思考内容
+ */
+interface HistoryItemThinking extends HistoryItemBase {
+    type: "thinking";
+    text: string;
+    compactText?: string;
+}
+/**
+ * Error message - 错误消息
+ */
+interface HistoryItemError extends HistoryItemBase {
+    type: "error";
+    text: string;
+}
+interface HistoryItemEvent extends HistoryItemBase {
+    type: "event";
+    text: string;
+    icon?: string;
+    compactText?: string;
+}
+/**
+ * Info message - 信息消息
+ */
+interface HistoryItemInfo extends HistoryItemBase {
+    type: "info";
+    text: string;
+    icon?: string;
+    compactText?: string;
+    /**
+     * When true, drop the default bottom margin so consecutive info items
+     * (e.g. a burst of repo-intelligence trace stages emitted within one
+     * turn) visually stack as a block instead of each getting a blank
+     * spacer line. Non-tight items following a tight run restore normal
+     * spacing on their own via their own `marginBottom`.
+     */
+    tightSpacing?: boolean;
+}
+/**
+ * Hint message - 提示消息
+ */
+interface HistoryItemHint extends HistoryItemBase {
+    type: "hint";
+    text: string;
+}
+/**
+ * Sidecar Verifier message - Sidecar 验证器消息
+ * Displayed as an independent "role" with its own header so the user can
+ * clearly see that the Sidecar Verifier is actively reviewing the output.
+ * verdict: 'revise' | 'blocked' | undefined; delivery 'budget-exhausted' means
+ * the verifier ran out of budget before returning a verdict.
+ */
+interface HistoryItemSidecar extends HistoryItemBase {
+    type: "sidecar";
+    text: string;
+    /** 'revise' or 'blocked'; absent when delivery === 'budget-exhausted' */
+    verdict?: "revise" | "blocked";
+    /** Set when the verifier exhausted its token budget before reaching a verdict */
+    delivery?: "budget-exhausted";
+}
+/**
+ * Union type of all history items - 所有历史项的联合类型
+ */
+type HistoryItem = HistoryItemUser | HistoryItemAssistant | HistoryItemSystem | HistoryItemToolGroup | HistoryItemThinking | HistoryItemError | HistoryItemEvent | HistoryItemInfo | HistoryItemHint | HistoryItemSidecar;
+/**
+ * Creatable history item types (with text property) - 可创建的历史项类型（带 text 属性）
+ * Used for addHistoryItem function parameter type - 用于 addHistoryItem 等函数的参数类型
+ */
+type CreatableHistoryItem = (Omit<HistoryItemUser, "id" | "timestamp"> | Omit<HistoryItemAssistant, "id" | "timestamp"> | Omit<HistoryItemSystem, "id" | "timestamp"> | Omit<HistoryItemThinking, "id" | "timestamp"> | Omit<HistoryItemError, "id" | "timestamp"> | Omit<HistoryItemEvent, "id" | "timestamp"> | Omit<HistoryItemInfo, "id" | "timestamp"> | Omit<HistoryItemHint, "id" | "timestamp"> | Omit<HistoryItemSidecar, "id" | "timestamp"> | Omit<HistoryItemToolGroup, "id" | "timestamp">) & {
+    /** Preserve the source event time when committing live or restored history. */
+    timestamp?: number;
+};
+/**
+ * UI global state interface - UI 全局状态接口
+ * Reference: Gemini CLI UIStateContext - 参考: Gemini CLI UIStateContext
+ */
+interface UIState {
+    streamingState: StreamingState;
+    currentResponse: string;
+    history: HistoryItem[];
+    pendingToolCalls: ToolCall[];
+    sessionId: string;
+    provider: string;
+    model: string;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    error?: string;
+    isLoading: boolean;
+}
+/**
+ * UI actions interface - UI 操作接口
+ */
+interface UIActions {
+    setStreamingState: (state: StreamingState) => void;
+    appendToResponse: (text: string) => void;
+    clearResponse: () => void;
+    addHistoryItem: (item: CreatableHistoryItem) => void;
+    addHistoryItems: (items: CreatableHistoryItem[]) => void;
+    updateHistoryItem: (id: string, updates: Partial<HistoryItem>) => void;
+    clearHistory: () => void;
+    addToolCall: (tool: Omit<ToolCall, "id" | "startTime">) => string;
+    updateToolCall: (id: string, updates: Partial<ToolCall>) => void;
+    clearToolCalls: () => void;
+    setSessionId: (id: string) => void;
+    setProvider: (provider: string) => void;
+    setModel: (model: string) => void;
+    setTokenUsage: (usage: UIState["tokenUsage"]) => void;
+    setError: (error: string | undefined) => void;
+    setLoading: (loading: boolean) => void;
+}
+/**
+ * Keyboard event handler priority - 键盘事件处理器优先级
+ * Reference: Gemini CLI KeypressContext - 参考: Gemini CLI KeypressContext
+ */
+declare enum KeypressHandlerPriority {
+    Low = -100,
+    Normal = 0,
+    High = 100,
+    Critical = 200
+}
+/**
+ * Keyboard event handler - 键盘事件处理器
+ */
+type KeypressHandler = (event: KeyInfo) => boolean | void;
+/**
+ * Keyboard event - 键盘事件
+ */
+interface KeypressEvent {
+    key: KeyInfo;
+    handled: boolean;
+}
+/**
+ * Default UI state - 默认 UI 状态
+ */
+declare const DEFAULT_UI_STATE: UIState;
+
+/**
+ * Session Storage - Session storage abstraction layer
+ *
+ * Provides a shared persistence interface across memory and filesystem storage.
+ */
+
+/**
+ * Session data structure.
+ */
+type SessionData = KodaXSessionData;
+/**
+ * Session storage interface.
+ */
+interface SessionStorage {
+    save(id: string, data: SessionData): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    getLineage?(id: string): Promise<KodaXSessionLineage | null>;
+    setActiveEntry?(id: string, selector: string, options?: KodaXSessionNavigationOptions): Promise<SessionData | null>;
+    setLabel?(id: string, selector: string, label?: string): Promise<SessionData | null>;
+    rewind?(id: string, selector?: string): Promise<SessionData | null>;
+    fork?(id: string, selector?: string, options?: {
+        sessionId?: string;
+        title?: string;
+    }): Promise<{
+        sessionId: string;
+        data: SessionData;
+    } | null>;
+    list(gitRoot?: string): Promise<Array<{
+        id: string;
+        title: string;
+        msgCount: number;
+        tag?: string;
+        runtimeInfo?: KodaXSessionRuntimeInfo;
+    }>>;
+    delete?(id: string): Promise<void>;
+    deleteAll?(gitRoot?: string): Promise<void>;
+}
+/**
+ * In-memory session storage implementation.
+ */
+declare class MemorySessionStorage implements SessionStorage {
+    private sessions;
+    save(id: string, data: SessionData): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    getLineage(id: string): Promise<KodaXSessionLineage | null>;
+    setActiveEntry(id: string, selector: string, options?: KodaXSessionNavigationOptions): Promise<SessionData | null>;
+    setLabel(id: string, selector: string, label?: string): Promise<SessionData | null>;
+    fork(id: string, selector?: string, options?: {
+        sessionId?: string;
+        title?: string;
+    }): Promise<{
+        sessionId: string;
+        data: SessionData;
+    } | null>;
+    rewind(id: string, selector?: string): Promise<SessionData | null>;
+    list(_gitRoot?: string): Promise<Array<{
+        id: string;
+        title: string;
+        msgCount: number;
+        tag?: string;
+    }>>;
+    delete(id: string): Promise<void>;
+    deleteAll(_gitRoot?: string): Promise<void>;
+}
+declare function createMemorySessionStorage(): SessionStorage;
+
+/**
+ * KodaX session storage - filesystem implementation.
+ */
+
+declare class FileSessionStorage implements KodaXSessionStorage {
+    private readonly sessionsDir;
+    /**
+     * v0.7.46 — optional explicit project cwd for in-process embedders
+     * (KodaX Space) serving multiple projects from a single runtime.
+     * Threaded through `getGitRoot(this.hostCwd)` and `inspectWorkspaceRuntime({cwd: this.hostCwd})`
+     * so the workspace-mismatch check in `load()` compares against the
+     * project the embedder opened, NOT the embedder's startup directory.
+     * Unset → all paths behave identically to the pre-v0.7.46 form.
+     */
+    private readonly hostCwd?;
+    /**
+     * v0.7.46 F7 — explicit opt-in for the CLI-style "[Warning] Session
+     * project mismatch" stderr notice emitted from `load()`. Pre-v0.7.46
+     * the gate was `!this.hostCwd` which fired whenever the embedder
+     * hadn't supplied a cwd — but that ALSO matched SDK consumers who
+     * don't set cwd (e.g. KodaX Space), bleeding the yellow warning into
+     * their stdout/stderr UI channels on every cross-project load. The
+     * v0.7.46 default is `false` — silent. CLI surfaces that want the
+     * old behavior (warn when user resumes a session from outside its
+     * original project) can pass `emitMismatchWarnings: true`.
+     */
+    private readonly emitMismatchWarnings;
+    constructor(opts?: {
+        sessionsDir?: string;
+        cwd?: string;
+        emitMismatchWarnings?: boolean;
+    });
+    /** Absolute session root used by this storage instance. */
+    getSessionsDir(): string;
+    private writeQueues;
+    private serializedWrite;
+    private appendState;
+    private sessionDirCache;
+    private projectJsonWritten;
+    private migrationPromise?;
+    private ensureMigrated;
+    /** Update watermarks. Only overwrites fields the caller actually provided. */
+    private syncAppendState;
+    private legacyFlatPath;
+    private legacyFlatArchivePath;
+    private projectDir;
+    /** Resolve (and cache) the project directory a write for `id` should land in. */
+    private resolveWriteDir;
+    private writeFilePath;
+    /**
+     * id-only locator (ADR-038 §7). Resolution order:
+     *   1. cached project dir for this id
+     *   2. bounded scan of project dirs:  <key>/<id>.jsonl
+     *   3. bounded scan of archived:      <key>/archived/<id>.jsonl
+     *   4. legacy flat:                   <sessionsDir>/<id>.jsonl
+     * On multiple matches (only possible for pre-FEATURE_219 same-second
+     * duplicate ids) it prefers the current process's project dir, else
+     * returns null with a warning rather than guessing.
+     */
+    private resolveSessionLocation;
+    private readSession;
+    /** Write `<dir>/project.json` once per process per directory (best-effort). */
+    private ensureProjectJson;
+    private writeSessionInternal;
+    private mergeAndWriteInternal;
+    appendSessionDelta(id: string, data: SessionData): Promise<void>;
+    private shouldRunMaintenance;
+    private runMaintenance;
+    save(id: string, data: SessionData): Promise<void>;
+    /** F270/F269 owner mutation: CAS-update only the Actor section of a session snapshot. */
+    saveActorSnapshot(id: string, snapshot: AgentActorSnapshot, expectedRevision: number): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    getLineage(id: string): Promise<KodaXSessionLineage | null>;
+    setActiveEntry(id: string, selector: string, options?: {
+        summarizeCurrentBranch?: boolean;
+    }): Promise<SessionData | null>;
+    rewind(id: string, selector?: string): Promise<SessionData | null>;
+    setLabel(id: string, selector: string, label?: string): Promise<SessionData | null>;
+    fork(id: string, selector?: string, options?: {
+        sessionId?: string;
+        title?: string;
+    }): Promise<{
+        sessionId: string;
+        data: SessionData;
+    } | null>;
+    /**
+     * v0.7.46 — `opts.limit` added so SDK consumers can request more than
+     * the legacy 10-entry cap. Default stays at 10 to preserve the
+     * interactive REPL picker's behavior. The `public-api.ts` fast path
+     * forwards the caller's `limit`; `deleteAll()` passes a large value
+     * so it can enumerate ALL sessions for the gitRoot.
+     *
+     * v0.7.46 — return now carries `createdAt` so the fast path in
+     * `public-api.ts` no longer silently strips it. Pre-v0.7.46 callers
+     * that only destructured `{id, title, msgCount, runtimeInfo}` are
+     * unaffected (extra fields are ignored).
+     */
+    list(gitRoot?: string, opts?: {
+        limit?: number;
+        includeArchived?: boolean;
+    }): Promise<Array<{
+        id: string;
+        title: string;
+        msgCount: number;
+        tag?: string;
+        runtimeInfo?: KodaXSessionRuntimeInfo;
+        archived?: boolean;
+        createdAt?: string;
+    }>>;
+    /**
+     * FEATURE_219 Phase 4 — whole-session archive (ADR-038 §4). Moves the session
+     * file together with its island sidecar into `<projectKey>/archived/`. Paired
+     * (never orphans the sidecar). No-op + returns false for a missing session.
+     */
+    archive(id: string): Promise<boolean>;
+    /** Restore an archived session back into its project directory. */
+    unarchive(id: string): Promise<boolean>;
+    /**
+     * Move a session + its island sidecar between two directories. Propagates a
+     * non-ENOENT rename error (e.g. Windows file-in-use) so a partial move is
+     * surfaced as a failure instead of silently splitting main + sidecar.
+     */
+    private movePair;
+    delete(id: string): Promise<void>;
+    deleteAll(gitRoot?: string): Promise<void>;
+    /**
+     * Auto-retention: delete session files (`.jsonl` + `.archive.jsonl`) whose
+     * mtime is older than `retentionDays`. Modeled on claudecode's
+     * `cleanup.ts` (`unlinkIfOld`). Bounds the sessions directory so it never
+     * accumulates unboundedly — which is what keeps `list()`'s head-read pass
+     * fast (its cost scales with file COUNT, not size). A non-positive /
+     * non-finite `retentionDays` disables cleanup (no-op). Best-effort: per-file
+     * errors are swallowed so a single locked/racing file never aborts the
+     * sweep. Returns the number of files removed. mtime-based, so the session
+     * currently being written/resumed (fresh mtime) is never eligible.
+     */
+    cleanupOldSessions(retentionDays: number): Promise<number>;
+}
+
+/**
+ * FEATURE_247 (R6) — imperative session compaction.
+ *
+ * Lets an SDK embedder (KodaX-Space) compact a session by id immediately —
+ * e.g. when the user clicks a "/compact" button — instead of forging a token
+ * snapshot or appending an empty message to trip auto-compaction. Loads the
+ * session, runs the same `compact()` pass the REPL `/compact` command uses,
+ * applies the result to the session lineage (so `loadFullTranscript` / resume
+ * see the compaction entry), and writes it back.
+ *
+ * Applies uniformly to Partner and Coder sessions. Never throws — failures
+ * return `{ compacted: false, reason }`.
+ */
+
+interface CompactSessionOptions {
+    /** Provider alias for the summarizer. Defaults to the session's persisted provider, then 'anthropic'. */
+    readonly provider?: string;
+    /** Model override forwarded to the summarizer. */
+    readonly model?: string;
+    /** Custom summarizer instructions (same as `/compact <text>`). */
+    readonly customInstructions?: string;
+    /** Provider context-window override (tokens). Otherwise resolved from the provider/model. */
+    readonly contextWindow?: number;
+    /** Sessions directory (mirrors createSessionManager's override). */
+    readonly sessionsDir?: string;
+    /** Injected storage instance (takes precedence over sessionsDir). */
+    readonly storage?: FileSessionStorage;
+}
+interface CompactSessionResult {
+    /** True when the session was actually rewritten. */
+    readonly compacted: boolean;
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+    /** The rewritten (or unchanged) message list. */
+    readonly messages: KodaXMessage[];
+    /** Populated when `compacted` is false to explain why (not-found / no-op / error). */
+    readonly reason?: string;
+}
+/**
+ * Compact a session by id, writing the result (lineage + messages) back to
+ * storage. Never throws.
+ */
+declare function compactSession(sessionId: string, options?: CompactSessionOptions): Promise<CompactSessionResult>;
+
+/**
+ * FEATURE_173 Part B (v0.7.42) — Session Management Public SDK.
+ *
+ * Thin facades over FileSessionStorage + discoverInstances. All methods
+ * NEVER throw — missing sessions return null, blocked operations return
+ * an error envelope, missing directories return empty arrays / no-op
+ * watchers.
+ *
+ * The `@kodax-ai/kodax/session` SDK subpath re-exports this module.
+ */
+
+interface SessionSummary {
+    readonly id: string;
+    /** Opaque continuation token; pass the last item cursor back to listSessions(). */
+    readonly cursor?: string;
+    readonly title: string;
+    readonly msgCount: number;
+    readonly tag?: string;
+    readonly createdAt?: string;
+    readonly runtimeInfo?: {
+        workspaceRoot?: string;
+        gitRoot?: string;
+        surface?: string;
+        profileId?: string;
+    };
+    /**
+     * FEATURE_219 (v0.7.46) — the per-project directory key this session lives
+     * under (ADR-038 §7). A backward-compatible hint: consumers may pass it back
+     * for precise disambiguation, but `loadSession(id)` works without it.
+     */
+    readonly projectKey?: string;
+    /** FEATURE_219 — true when the session is whole-session archived (only ever
+     * surfaced when `includeArchived` is set). */
+    readonly archived?: boolean;
+}
+type SessionTranscriptEntryType = 'message' | 'compaction' | 'branch_summary'
+/** Rewind audit marker; not included in `FullTranscriptSessionData.messages`. */
+ | 'rewind_marker' | 'client_notice'
+/**
+ * Synthetic task/workflow completion entry derived from `_taskResult`,
+ * `_taskResults`, or legacy `<task-completed>` banners. The original
+ * `KodaXMessage` is still exposed on `message`, but consumers that want a
+ * complete transcript should not filter only `type === 'message'`.
+ */
+ | 'task_result';
+type SessionTranscriptEntrySource = 'user' | 'assistant' | 'workflow' | 'child_task' | 'system' | 'client';
+interface SessionTranscriptEntry {
+    readonly entryId: string;
+    readonly parentId: string | null;
+    /** Stable logical identity shared by cloned/forked copies of the same entry. */
+    readonly logicalId: string;
+    /** Root source physical entry id when this transcript entry was cloned/forked. */
+    readonly sourceEntryId?: string;
+    readonly timestamp: string;
+    readonly type: SessionTranscriptEntryType;
+    readonly source?: SessionTranscriptEntrySource;
+    readonly turnId?: string;
+    readonly message: KodaXMessage;
+    readonly active: boolean;
+    readonly summary?: string;
+    readonly payload?: unknown;
+    readonly taskResults?: readonly KodaXTaskResultMetadata[];
+}
+interface FullTranscriptSessionData extends Omit<SessionData, 'messages'> {
+    readonly messages: KodaXMessage[];
+    readonly activeMessages: KodaXMessage[];
+    readonly transcriptEntries: SessionTranscriptEntry[];
+}
+interface AppendClientNoticeOptions {
+    readonly source?: string;
+    readonly content: string;
+    readonly timestamp?: string;
+    readonly turnId?: string;
+    readonly payload?: KodaXJsonValue;
+}
+interface ListSessionsOptions {
+    /**
+     * Alias for gitRoot; backwards-compat with KodaX Space terminology.
+     * When provided, list() is scoped to sessions from this project root.
+     */
+    readonly projectRoot?: string;
+    /**
+     * Which session scopes to include.
+     * - 'user' (default): only user-initiated sessions.
+     * - 'managed-task-worker': only managed-task worker sessions.
+     * - 'all': no scope filter.
+     */
+    readonly scope?: 'user' | 'managed-task-worker' | 'all';
+    /**
+     * Whether to include whole-session-archived sessions. FEATURE_219 (v0.7.46):
+     * archived sessions live in `<projectKey>/archived/` (see `archiveSession`);
+     * also still hides the legacy `archived-` filename prefix. Default false.
+     */
+    readonly includeArchived?: boolean;
+    /** Maximum number of sessions to return. Default 50. */
+    readonly limit?: number;
+    /**
+     * ISO date string — return only sessions whose createdAt is before this
+     * timestamp. Applied after list + scope filtering.
+     */
+    readonly before?: string;
+    /** Exact match. Omitted means no tag filter. */
+    readonly tag?: string;
+    /** Exact runtime surface match, for example `repl`, `cli`, `acp`, or `partner`. */
+    readonly surface?: string;
+    /** Opaque cursor returned on a previous page's last SessionSummary. */
+    readonly cursor?: string;
+}
+type WatchSessionsCallback = (event: {
+    kind: 'change' | 'add' | 'remove';
+    sessionId: string;
+}) => void;
+interface SessionManager {
+    listSessions: typeof listSessions;
+    loadSession: typeof loadSession;
+    loadFullTranscript: typeof loadFullTranscript;
+    appendClientNotice: typeof appendClientNotice;
+    forkSession: typeof forkSession;
+    rewindSession: typeof rewindSession;
+    setActiveEntry: typeof setActiveEntry;
+    deleteSession: typeof deleteSession;
+    archiveSession: typeof archiveSession;
+    unarchiveSession: typeof unarchiveSession;
+    listRunningSessions: typeof listRunningSessions;
+    watchSessions: typeof watchSessions;
+    /** FEATURE_247 (R6) — imperatively compact a session by id (writes lineage + emits nothing; returns stats). */
+    compactSession: typeof compactSession;
+    /**
+     * v0.7.43 — the raw write-side storage instance. SDK embedders pass
+     * this into `runKodaX({ session: { id, scope, storage } })` so the
+     * SA / AMA loops write per-turn JSONL snapshots to disk. Without an
+     * injected storage, `saveSessionSnapshot` is a silent no-op and the
+     * sessions directory stays empty regardless of `session.id`.
+     *
+     * See {@link FileSessionStorage} for the concrete implementation and
+     * `docs/SDK_EMBEDDER_GUIDE.md` §6 for the end-to-end recipe.
+     */
+    storage: FileSessionStorage;
+}
+/**
+ * List sessions, optionally filtered by scope, limit, and date.
+ * NEVER throws. Returns [] when the sessions directory is empty or missing.
+ */
+declare function listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]>;
+/**
+ * Load full session data by ID.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function loadSession(id: string): Promise<SessionData | null>;
+/**
+ * Load append-order transcript data by ID.
+ *
+ * `loadSession` remains the active model-context API. This helper is for UI
+ * scrollback: it returns every persisted transcript-bearing lineage entry in
+ * append order and keeps the active branch in `activeMessages`.
+ */
+declare function loadFullTranscript(id: string): Promise<FullTranscriptSessionData | null>;
+/**
+ * Append a host-owned transcript notice that never enters model context.
+ *
+ * Use this for local slash-command output such as `/doctor`, `/mcp status`,
+ * or host-side status panes. It is visible through `loadFullTranscript()` but
+ * `loadSession()` keeps returning only the active model messages.
+ */
+declare function appendClientNotice(id: string, options: AppendClientNoticeOptions): Promise<SessionTranscriptEntry | null>;
+/**
+ * Fork a session at an optional selector.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function forkSession(id: string, opts?: {
+    selector?: string;
+    sessionId?: string;
+    title?: string;
+}): Promise<{
+    sessionId: string;
+    data: SessionData;
+} | null>;
+/**
+ * Rewind a session to a previous user entry.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function rewindSession(id: string, opts?: {
+    selector?: string;
+}): Promise<SessionData | null>;
+/**
+ * Set the active lineage entry by selector.
+ * Returns null for a missing session. NEVER throws.
+ */
+declare function setActiveEntry(id: string, selector: string): Promise<SessionData | null>;
+interface RunningSessionInfo {
+    readonly pid: number;
+    readonly startedAt: number;
+    readonly cwd: string;
+    /**
+     * v0.7.43 — populated from `PersistedSessionState.sessionId`, published
+     * by the REPL after `createInteractiveContext`. Remains `undefined` for
+     * a brief window during a peer's bootstrap (before the first sessionId
+     * is generated) and for peers running pre-v0.7.43 binaries; consumers
+     * MUST handle `undefined`.
+     */
+    readonly sessionId: string | undefined;
+}
+/**
+ * Returns live KodaX sibling instances (excluding this process).
+ * Uses discoverInstances() from @kodax-ai/agent (FEATURE_125 Team Mode).
+ * NEVER throws. Returns [] when no instances directory exists.
+ */
+declare function listRunningSessions(): Promise<RunningSessionInfo[]>;
+type DeleteSessionResult = {
+    ok: true;
+} | {
+    error: {
+        code: 'session_running';
+        runningProcess: {
+            pid: number;
+            startedAt: number;
+        };
+    };
+};
+/**
+ * Delete a session by ID.
+ * Returns { ok: true } on success (including when the session doesn't exist).
+ * Returns an error envelope when the session is currently running.
+ * NEVER throws.
+ */
+declare function deleteSession(id: string): Promise<DeleteSessionResult>;
+/**
+ * FEATURE_219 (v0.7.46) — whole-session archive. Moves the session (and its
+ * island sidecar) into `<projectKey>/archived/`. Returns false for a missing
+ * session. NEVER throws. Archived sessions are hidden from the default listing
+ * and resurface only with `listSessions({ includeArchived: true })`.
+ */
+declare function archiveSession(id: string): Promise<boolean>;
+/** Restore an archived session back into its project directory. NEVER throws. */
+declare function unarchiveSession(id: string): Promise<boolean>;
+/**
+ * Watch the sessions directory for changes.
+ * Returns { close() } that stops the watcher / poll interval.
+ *
+ * Platform branches:
+ * - POSIX: fs.watch() with 100ms debounce.
+ * - Windows: readdir poll every 1000ms, diffed against a snapshot.
+ *
+ * NEVER throws — if the directory doesn't exist the watcher is a no-op
+ * until the directory is created.
+ */
+declare function watchSessions(cb: WatchSessionsCallback): {
+    close: () => void;
+};
+/**
+ * Factory that returns an object with all session management methods bound.
+ *
+ * v0.7.43 (FEATURE_173 Part B follow-up) — the `sessionsDir` override is
+ * now honored. When provided, all read/write/watch operations go through
+ * that directory instead of the module-load-frozen `KODAX_SESSIONS_DIR`.
+ * `listRunningSessions` still consults the agent-config-home instances
+ * directory (sibling-process awareness is not scoped per sessions dir).
+ */
+declare function createSessionManager(opts?: {
+    sessionsDir?: string;
+}): SessionManager;
+
+export { KeypressHandlerPriority as B, DEFAULT_UI_STATE as D, FILE_MODIFICATION_TOOLS as F, MemorySessionStorage as M, PERMISSION_MODES as P, StreamingState as a0, TOOL_STATUS_ICONS as a2, TextBuffer as a3, ToolCallStatus as a9, appendClientNotice as ag, archiveSession as ah, compactSession as ai, computeConfirmTools as aj, createMemorySessionStorage as ak, createSessionManager as al, deleteSession as am, forkSession as an, isPermissionMode as ao, listRunningSessions as ap, listSessions as aq, loadFullTranscript as ar, loadSession as as, normalizePermissionMode as at, permissionModeDisplayName as au, rewindSession as av, setActiveEntry as aw, unarchiveSession as ax, watchSessions as ay, FileSessionStorage as j };
+export type { StatusBarProps as $, AppProps as A, CompactSessionOptions as C, LearningSurfaceSnapshot as E, LegacyMessageListProps as G, HistoryEntry as H, InputPromptProps as I, ListSessionsOptions as J, KeyInfo as K, LearningBinding as L, Message as N, PastedContent as O, PermissionContext as Q, PermissionMode as R, PromptEditingMode as S, PromptSubmitPayload as T, RunningSessionInfo as U, SessionData as V, SessionManager as W, SessionStorage as X, SessionSummary as Y, SessionTranscriptEntry as Z, SessionTranscriptEntryType as _, AppState as a, Suggestion as a1, TextBufferOptions as a4, Theme as a5, ThemeColors as a6, ThemeSymbols as a7, ToolCall as a8, UIActions as aa, UIState as ab, UseTextBufferReturn as ac, VisualCursor as ad, VisualLayout as ae, WatchSessionsCallback as af, AppendClientNoticeOptions as b, CompactSessionResult as c, Completer as d, Completion as e, ConfirmResult as f, CreatableHistoryItem as g, CursorPosition as h, DeleteSessionResult as i, FullTranscriptSessionData as k, HistoryItem as l, HistoryItemAssistant as m, HistoryItemBase as n, HistoryItemError as o, HistoryItemEvent as p, HistoryItemHint as q, HistoryItemInfo as r, HistoryItemSidecar as s, HistoryItemSystem as t, HistoryItemThinking as u, HistoryItemToolGroup as v, HistoryItemType as w, HistoryItemUser as x, KeypressEvent as y, KeypressHandler as z };