@kiturone/kapibala 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -1,12 +1,111 @@
+/**
+ * Error Taxonomy for Kapibala Agent Harness
+ */
+type ModelErrorCategory = 'authentication' | 'quota' | 'rate_limit' | 'context' | 'service' | 'network' | 'timeout' | 'invalid_request' | 'invalid_response' | 'unknown';
+interface ModelErrorOptions {
+    status?: number;
+    retryable?: boolean;
+    code?: string;
+    transportCode?: string;
+    providerCode?: string;
+    providerType?: string;
+    stage?: 'connect' | 'response' | 'stream' | 'request';
+}
+/** 跨协议模型失败的脱敏说明；适用于主任务和摘要，不代表自动重试授权。 */
+interface ModelErrorInfo {
+    category: ModelErrorCategory;
+    code: string;
+    message: string;
+    status?: number;
+    providerCode?: string;
+    providerType?: string;
+    transportCode?: string;
+    stage?: ModelErrorOptions['stage'];
+    operation?: 'primary' | 'summary';
+    modelId?: string;
+    provider?: string;
+    retryPolicy: KapibalaError['retryPolicy'];
+    suggestion: string;
+}
+/** 清理服务端报错中的终端控制符、常见凭据及带凭据的 URL，限制长度；不展示完整响应或请求头。 */
+declare function sanitizeModelErrorMessage(value: string): string;
+/** 生成统一脱敏说明；上下文补充调用场景，不携带原始异常、请求正文或密钥。 */
+declare function describeModelError(error: ModelError, context?: Pick<ModelErrorInfo, 'modelId' | 'provider' | 'operation'>): ModelErrorInfo;
+declare class KapibalaError extends Error {
+    readonly code: string;
+    readonly retryPolicy: 'never' | 'immediate' | 'backoff' | 'after_user_action';
+    readonly safeMessage: string;
+    constructor(message: string, options?: {
+        code?: string;
+        retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
+        safeMessage?: string;
+    });
+}
+declare class ModelError extends KapibalaError {
+    readonly status?: number;
+    readonly retryable: boolean;
+    /** 可选的受控底层连接错误码，不包含原始传输异常文本。 */
+    readonly transportCode?: string;
+    readonly providerCode?: string;
+    readonly providerType?: string;
+    readonly stage?: ModelErrorOptions['stage'];
+    readonly category: ModelErrorCategory;
+    /** 构建模型错误，清理服务端原因并按明确状态/错误码分类；重试策略仅为建议，不授权重放。 */
+    constructor(message: string, options?: ModelErrorOptions);
+}
+/** Provider 明确拒绝上下文长度；仅无输出请求允许预算处理后重发一次。 */
+declare class ContextOverflowError extends ModelError {
+    /** 保留明确上下文错误的脱敏服务端原因；只允许尚无输出的请求进入一次预算处理。 */
+    constructor(status?: number, details?: Pick<ModelErrorOptions, 'providerCode' | 'providerType' | 'stage'> & {
+        message?: string;
+    });
+}
+declare class TransportError extends KapibalaError {
+    readonly retryable: boolean;
+    constructor(message: string, retryable?: boolean);
+}
+declare class ToolError extends KapibalaError {
+    constructor(message: string);
+}
+declare class ToolNotFound extends KapibalaError {
+    readonly toolName: string;
+    readonly availableTools: string[];
+    constructor(toolName: string, availableTools?: string[]);
+}
+declare class AbortError extends KapibalaError {
+    constructor(message?: string);
+}
+declare class FatalError extends KapibalaError {
+    constructor(message: string);
+}
+declare class SessionBusyError extends KapibalaError {
+    constructor(operation: string);
+}
+/** 请求硬预算不足；需用户缩小任务或选择更大窗口，不允许切掉当前任务继续。 */
+declare class ContextBudgetError extends KapibalaError {
+    readonly usedTokens: number;
+    readonly inputBudget: number;
+    constructor(usedTokens: number, inputBudget: number);
+}
+/** 压缩状态持久提交失败，与模型预算或生成失败分别处理，不允许未落盘候选生效。 */
+declare class ContextStorageError extends KapibalaError {
+    constructor(message: string);
+}
+
 /**
  * Canonical Message & Event Types for Kapibala
  */
+
 type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | RedactedThinkingBlock;
 interface TextBlock {
     type: 'text';
     text: string;
 }
 interface ToolUseBlock {
+    /** 工具执行语义来源；新运行记录，旧历史可缺省。未知插件不按内置只读工具剪裁。 */
+    source?: string;
+    /** 执行器记录的绝对工具根目录；仅作历史路径依据，不改变参数或恢复旧授权。旧历史可缺省。 */
+    executionRoot?: string;
     type: 'tool_use';
     id: string;
     name: string;
@@ -19,6 +118,10 @@ interface ToolResultBlock {
     isError?: boolean;
     /** 单次工具调用总耗时，包含 tool hooks 与实际执行。 */
     durationMs?: number;
+    /** 稳定错误类别；旧历史中的该字段可缺省。 */
+    errorCode?: string;
+    /** 不代表自动重试，只描述调用方应如何处理该错误。 */
+    retryPolicy?: 'never' | 'immediate' | 'backoff' | 'after_user_action';
 }
 interface ThinkingBlock {
     type: 'thinking';
@@ -33,9 +136,21 @@ interface Usage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Provider 明确提供的缓存命中输入量；缺失表示未知，不能按零推断。 */
+    cachedPromptTokens?: number;
 }
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 interface CanonicalMessage {
+    /** 派生背景锚点独立于真实用户输入，避免合并后丢失受保护原消息的来源身份。 */
+    contextSummary?: {
+        checkpointId: string;
+    };
+    /** 稳定消息身份；旧 SDK 消息可省略，在进入受管历史时补齐。 */
+    id?: string;
+    /** 用户交互身份，与内部模型步骤及进程运行实例分别记录。 */
+    interactionId?: string;
+    /** 未完成正文不会进入模型请求视图。省略表示旧版已落盘正文。 */
+    state?: 'completed' | 'draft' | 'failed' | 'interrupted';
     role: MessageRole;
     content: ContentBlock[];
     timestamp?: number;
@@ -70,11 +185,15 @@ interface RunMetrics {
     turns: number;
     toolCalls: number;
     status: 'completed' | 'failed' | 'aborted';
+    /** 模型失败的脱敏汇总；保留具体阶段与原因，不携带请求或响应正文。 */
+    failure?: ModelErrorInfo;
     /** 最近一次内部模型请求占用的上下文；不使用 run 累计 promptTokens。 */
     contextUsage?: ContextUsage;
 }
 interface ContextUsage {
     usedTokens?: number;
+    /** true 表示未收到当前请求 usage，输入占用使用预算估算，不能用于计费。 */
+    estimatedUsage?: boolean;
     limitTokens: number;
     percent?: number;
     estimatedLimit: boolean;
@@ -96,6 +215,56 @@ interface StepLogEntry {
  * 不应直接把本类型当作长期兼容的网络协议。
  */
 type SessionEvent = {
+    type: 'session_resumed';
+    conversationId: string;
+    runtimeSessionId: string;
+    messageCount: number;
+} | {
+    type: 'session_switched';
+    conversationId: string;
+    previousConversationId: string;
+} | {
+    type: 'compaction_start';
+    conversationId: string;
+    runId?: string;
+    kind: 'prune' | 'summary';
+    reason: 'threshold' | 'manual' | 'overflow';
+    persistence: 'disk' | 'memory';
+    beforeTokens: number;
+} | {
+    type: 'compaction_finish';
+    conversationId: string;
+    runId?: string;
+    kind: 'prune' | 'summary';
+    reason: 'threshold' | 'manual' | 'overflow';
+    persistence: 'disk' | 'memory';
+    beforeTokens: number;
+    afterTokens: number;
+    checkpointId?: string;
+    coveredEndMessageId?: string;
+    prunedResults?: number;
+    modelId?: string;
+    durationMs: number;
+} | {
+    type: 'compaction_failed';
+    conversationId: string;
+    runId?: string;
+    kind: 'prune' | 'summary';
+    reason: 'threshold' | 'manual' | 'overflow';
+    persistence: 'disk' | 'memory';
+    error: string;
+    /** 脱敏失败分类，不包含 Provider 响应正文或历史内容。 */
+    errorCode?: string;
+    /** 摘要模型失败采用与主任务相同的脱敏说明；验证失败不回显摘要正文。 */
+    modelError?: ModelErrorInfo;
+    consecutiveFailures: number;
+} | {
+    type: 'context_budget_exceeded';
+    conversationId: string;
+    runId?: string;
+    usedTokens: number;
+    inputBudget: number;
+} | {
     type: 'turn_start';
     turn: number;
 } | {
@@ -112,6 +281,12 @@ type SessionEvent = {
     id: string;
     name: string;
     input: Record<string, unknown>;
+} | {
+    type: 'tool_progress';
+    id: string;
+    name: string;
+    elapsedMs: number;
+    outputBytes: number;
 } | {
     type: 'tool_finish';
     id: string;
@@ -145,6 +320,7 @@ type SessionEvent = {
 } | {
     type: 'error';
     error: Error;
+    modelError?: ModelErrorInfo;
 };
 type ModelEvent = {
     type: 'text_delta';
@@ -172,6 +348,7 @@ type ModelEvent = {
     usage?: Usage;
     ttftMs?: number;
     durationMs?: number;
+    finishReason?: string;
 };
 interface ToolDefinition {
     name: string;
@@ -186,42 +363,763 @@ interface ModelRequest {
     temperature?: number;
     maxTokens?: number;
 }
+/** runtime 通用请求准备契约；实现可以预算或投影，Loop 不依赖具体上下文管理器。 */
+type RequestPreparation = (request: ModelRequest, history: readonly CanonicalMessage[], reason?: 'threshold' | 'overflow') => AsyncGenerator<SessionEvent, ModelRequest>;
+
+/** 生成进程内单调递增的 UUIDv7；时钟回拨时沿用逻辑时间，序列耗尽才推进时间。 */
+declare function createMessageId(): string;
 
+/** 按来源及原始位置生成旧消息身份；复制输入，不改变调用者持有的正文或已有身份。 */
+declare function identifyHistory(messages: readonly CanonicalMessage[], source: string): CanonicalMessage[];
+interface HistoryRepair {
+    assistantId: string;
+    toolCallId: string;
+    result: ToolResultBlock;
+}
+interface NormalizedHistory {
+    messages: CanonicalMessage[];
+    /** 与 messages 同序的原始消息 ID 集合；修复结果关联原始 assistant。 */
+    sources: string[][];
+    repairs: HistoryRepair[];
+    diagnostics: string[];
+}
 /**
- * Error Taxonomy for Kapibala Agent Harness
+ * 构造合法且独立的请求视图：只接受紧邻事务的结果，缺失结果标为未知；重复调用身份明确失败。
+ * 合并仅适用于纯文本的同角色消息，失败正文不重放，所有来源均可追踪。
  */
-declare class KapibalaError extends Error {
-    constructor(message: string);
+declare function normalizeHistory(input: readonly CanonicalMessage[]): NormalizedHistory;
+interface InteractionBoundary {
+    interactionId: string;
+    status: 'completed' | 'failed' | 'interrupted';
+    messageIds: string[];
 }
-declare class ModelError extends KapibalaError {
-    readonly status?: number;
-    readonly retryable: boolean;
-    constructor(message: string, options?: {
-        status?: number;
-        retryable?: boolean;
+interface InteractionTerminal {
+    interactionId: string;
+    status: InteractionBoundary['status'];
+}
+/**
+ * 以显式终态为准恢复用户交互；旧历史仅在完整工具事务之后存在非空最终答复时推断成功。
+ * 保护最近成功交互及其后的所有交互，没有成功证据时保护全部历史。
+ */
+declare function indexInteractions(input: readonly CanonicalMessage[], terminals?: readonly InteractionTerminal[]): {
+    interactions: InteractionBoundary[];
+    protectedMessageIds: string[];
+};
+
+declare class JSONLMessageStore implements MessageStore {
+    readonly filePath: string;
+    constructor(filePath: string);
+    append(message: CanonicalMessage): Promise<void>;
+    load(): Promise<CanonicalMessage[]>;
+    clear(): Promise<void>;
+    /**
+     * 历史自愈(设计文档 §4.4)：逐条扫描 assistant 的 tool_use，
+     * 若其后的 tool 消息未完整覆盖这些 tool_use，就地补一条 is_error 的 tool_result。
+     *
+     * 之所以做**全历史扫描**而非只看末条：崩溃可能发生在任意一轮工具执行中途，
+     * 悬挂的 tool_use 未必位于历史末尾(例如中断后用户又继续提了问)。
+     * 只看末条会漏掉夹在中间的悬挂，下一次请求仍会因上下文非法而 400。
+     */
+    private healDanglingToolCalls;
+}
+
+interface MessageStore {
+    append(message: CanonicalMessage): Promise<void>;
+    load(): Promise<CanonicalMessage[]>;
+    clear(): Promise<void>;
+}
+
+declare const SESSION_SCHEMA_VERSION = 1;
+type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import';
+interface SessionHeader {
+    conversationId: string;
+    projectRoot: string;
+    initialCwd: string;
+    createdAt?: number;
+    gitBranch?: string;
+    importIdentity?: string;
+}
+interface SessionRecord {
+    schemaVersion: number;
+    type: SessionRecordType;
+    recordId: string;
+    timestamp: number;
+    parentId: string | null;
+    payload: Record<string, unknown>;
+}
+interface SessionState {
+    header: SessionHeader;
+    /** 最近 reset 之后的记录；包含正文及状态，不包含头部。 */
+    records: SessionRecord[];
+    /** 只随正文、修复与 reset 改变，不因 usage 或缓存写入失效。 */
+    contentRevision: string;
+}
+/** MessageStore 的可选状态能力；旧 SDK Store 不需要实现，宿主据此降级持久压缩。 */
+interface StatefulMessageStore extends MessageStore {
+    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>): Promise<SessionRecord>;
+    loadState(): Promise<SessionState>;
+}
+/** 判断 Store 是否支持版本化状态；不读取数据或改变旧 Store。 */
+declare function supportsSessionState(store: MessageStore): store is StatefulMessageStore;
+/**
+ * 版本化消息与上下文状态的单文件存储。所有写入串行并 fsync，失败后拒绝继续写入。
+ * 调用者须在打开前取得单写者锁；本类不允许静默跳过中部损坏或重复身份。
+ */
+declare class SessionStore implements StatefulMessageStore {
+    readonly filePath: string;
+    private queue;
+    private records;
+    private observer?;
+    private onDiagnostic?;
+    private stamp?;
+    private constructor();
+    /** 注册可重建缓存的写后通知；缓存失败只诊断，不撤销或毒化已 fsync 的正文。 */
+    setAppendObserver(observer: (record: SessionRecord) => void, onDiagnostic?: (message: string) => void): void;
+    /** 以独占创建方式安装新头部，已有文件明确失败，绝不覆盖其它会话。 */
+    static create(filePath: string, header: SessionHeader): Promise<SessionStore>;
+    /** 打开并验证已有会话；尾部残片先保存到隔离文件，中部损坏与未知版本拒绝恢复。 */
+    static open(filePath: string): Promise<SessionStore>;
+    /** 获取完整记录快照，等候已排队写入后读取；调用者不能借此修改内部记录。 */
+    readRecords(): Promise<SessionRecord[]>;
+    /** 消息级持久化，补稳定身份并保留所有终态字段，成功后方可进入下一次写入。 */
+    append(message: CanonicalMessage): Promise<void>;
+    /** 持久化状态记录，fsync 成功才返回；失败会毒化当前写者，要求重新验证后恢复。 */
+    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>): Promise<SessionRecord>;
+    /** 重建 reset 后的状态；统计记录和检查点不会推进正文 revision。 */
+    loadState(): Promise<SessionState>;
+    /**
+     * 恢复原始正文，并将幂等修复叠加到原工具事务；不合并连续消息，也不执行工具。
+     * 缺失结果用 history_repair 落盘，独立于实际工具结果和正文，不伪造成功。
+     */
+    load(): Promise<CanonicalMessage[]>;
+    /** SDK 清空语义通过持久边界实现；此前摘要、剪裁及失败状态不再参与恢复。 */
+    clear(): Promise<void>;
+    /** 生成前驱关联的 Envelope，前驱仅表达追加次序，未来 DAG 不改变当前恢复规则。 */
+    private makeRecord;
+    /** 单写者队列不吞异常；后续写入依赖同一失败 Promise，防止继续污染正文。 */
+    private enqueue;
+    /** 保存当前写者的正文版本，拒绝未经锁保护的第二写者继续追加。 */
+    private refreshStamp;
+    /** 校验每个完整记录，只有最后非空行的 JSON 残片可隔离，语义损坏绝不作为残片吞掉。 */
+    private readFile;
+}
+
+/** 基于目录独占创建的单写者锁；只有能确认死亡的进程才允许保守回收，不按年龄抢占。 */
+declare class SessionLock {
+    readonly lockPath: string;
+    private readonly owner;
+    private released;
+    private constructor();
+    /** 获取写入权，存活、无权限探测、损坏 owner 或正在回收均明确失败。 */
+    static acquire(lockPath: string): Promise<SessionLock>;
+    /** 仅释放本 nonce 的锁；调用者必须先等待在途工具、摘要及存储结束。 */
+    release(): Promise<void>;
+    /** 只认格式完整的 owner，缺失与损坏时保持锁而非猜测安全。 */
+    private static readOwner;
+    /**
+     * 清除上次回收崩溃的残留：无身份标记或标记进程已死亡的 recovery 目录可安全移除；
+     * 身份确认存活的回收进行中则保留。清不掉时视为回收进行中，由后续获取者再试。
+     */
+    private static clearAbandonedRecovery;
+    /** 无残留或残留进程已死亡时放行；确认存活的回收进行中则明确失败。 */
+    private static ensureNoLiveRecovery;
+    /** 仅 ESRCH 表示确定死亡；PID 复用或 EPERM 均保持原锁。 */
+    private static isDead;
+}
+
+interface ProjectIdentity {
+    projectRoot: string;
+    cwd: string;
+    projectKey: string;
+    gitBranch?: string;
+    gitWorktree?: boolean;
+}
+/** 解析真实工作树根；同工作树子目录共用桶，非 Git 目录和不同 worktree 独立。不会改变 cwd。 */
+declare function resolveSessionProject(cwd: string): ProjectIdentity;
+interface SessionMetadata {
+    schemaVersion: 1;
+    conversationId: string;
+    fileName: string;
+    projectRoot: string;
+    createdAt: number;
+    lastActivityAt: number;
+    messageCount: number;
+    title: string;
+    customTitle?: string;
+    gitBranch?: string;
+    lastActivityGitBranch?: string;
+    lastModelId?: string;
+    importIdentity?: string;
+    size: number;
+    mtimeMs: number;
+    revision: string;
+}
+interface ManagedSession {
+    conversationId: string;
+    store: SessionStore;
+    metadataPath: string;
+    /** 可丢弃缓存的只读快照；缺失时为 undefined，不代表正文丢失。 */
+    readonly metadata?: SessionMetadata;
+    header: SessionHeader;
+    /** 环境提示，不执行 checkout，也不把旧授权或模型配置带入当前运行。 */
+    branchDrift?: {
+        createdBranch?: string;
+        currentBranch?: string;
+    };
+    release(): Promise<void>;
+}
+interface SessionManagerOptions {
+    cwd?: string;
+    homeDirectory?: string;
+    onDiagnostic?: (message: string) => void;
+}
+/** 将终端控制字符转成可见转义，并按 Unicode code point 限长。 */
+declare function sanitizeSessionTitle(title: string, maximum?: number): string;
+/** 按项目发现、创建和打开独立会话；缓存可丢弃，JSONL 是唯一恢复依据。 */
+declare class SessionManager {
+    readonly project: ProjectIdentity;
+    readonly directory: string;
+    private readonly handles;
+    private readonly diagnostic?;
+    constructor(options?: SessionManagerOptions);
+    /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
+    create(): Promise<ManagedSession>;
+    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。 */
+    list(page?: number): Promise<{
+        items: SessionMetadata[];
+        total: number;
+        page: number;
+        pages: number;
+    }>;
+    /** 一次扫描建立排序目录，分页和继续最近会话共用；有效缓存不读取正文。 */
+    private allMetadata;
+    /** 打开完整 ID 或唯一前缀；跨桶、缺失与歧义均失败，同一 Manager 已持有的目标直接返回。 */
+    open(id: string): Promise<ManagedSession>;
+    /** 继续最近有正文的会话；没有历史才新建，显式打开失败绝不回退为空会话。 */
+    continueRecent(): Promise<ManagedSession>;
+    /** 标题作为独立耐久记录；标题或浏览不改变正文活动排序。 */
+    rename(id: string, title: string): Promise<void>;
+    /** 等候所有存储队列后释放句柄；宿主必须先结束 AgentSession 的工具/摘要清理。 */
+    close(): Promise<void>;
+    /**
+     * 只发现 cwd 和工作树根的旧文件；来源快照 hash 幂等，完整临时文件 fsync 后独占安装。
+     * 保留源文件，安装身份写入头部，缓存丢失或进程退出后仍不会重复导入。
+     */
+    importLegacy(): Promise<string[]>;
+    /** 绑定写后缓存与锁生命周期；正文优先，缓存失败不使保存成功的消息消失。 */
+    private attach;
+    /** 缓存通过文件名、身份、统计与正文 stat 校验；失败交由正文重建。 */
+    private readMetadata;
+    /** 浏览仅解析完整记录；严格打开由 SessionStore 验证，浏览不能改写残片。 */
+    private readDiscoveryRecords;
+    /** 从正文重建元数据，标题和上下文事件不改变内容活动时间。 */
+    private buildMetadata;
+    /** 只由正文、用户 run 与 reset 更新活动；usage、标题、摘要均不能把浏览对象置顶。 */
+    private applyRecord;
+    /** 临时 sidecar 完整写入后替换，可重建缓存不承担正文提交职责。 */
+    private writeMetadata;
+    private metadataPath;
+    private lockPath;
+    private report;
+}
+
+interface ModelProvider {
+    readonly name: string;
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /** 把一批工具结果装配成符合本协议的 canonical 消息序列 */
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+}
+
+type ModelRole = 'default' | 'planning' | 'execution' | 'summary' | 'fast';
+type ContextWindowValue = number | `${number}${'K' | 'k' | 'M' | 'm'}`;
+interface ResolvedContextWindow {
+    tokens: number;
+    /** true 表示模型未声明窗口，当前值来自 Kapibala 的默认估算。 */
+    estimated: boolean;
+}
+declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 1000000;
+/**
+ * 将模型上下文窗口统一解析为整数 Token 数。
+ *
+ * 配置允许直接填写整数，或使用十进制 K/M 简写；未填写时返回默认 1M，并标记为估算值。
+ */
+declare function resolveContextWindow(value?: ContextWindowValue): ResolvedContextWindow;
+interface ModelProfile {
+    id: string;
+    name: string;
+    provider: 'openai-compatible';
+    baseURL: string;
+    apiKeyEnv: string;
+    apiKey?: string;
+    modelName: string;
+    contextWindow?: ContextWindowValue;
+    supportsThinking?: boolean;
+}
+interface ModelRouter {
+    resolve(role?: ModelRole): ModelProvider;
+    getProfile(role?: ModelRole): ModelProfile;
+}
+declare class SimpleModelRouter implements ModelRouter {
+    private readonly providers;
+    private readonly profiles;
+    private defaultRole;
+    constructor(defaultProfile: ModelProfile, defaultProvider: ModelProvider);
+    setRole(role: ModelRole, profile: ModelProfile, provider: ModelProvider): void;
+    resolve(role?: ModelRole): ModelProvider;
+    getProfile(role?: ModelRole): ModelProfile;
+}
+
+interface ContextBudget {
+    contextWindow: number;
+    estimatedWindow: boolean;
+    outputReserve: number;
+    safetyReserve: number;
+    inputBudget: number;
+    /** 触发阈值 0.85B：超过才启动一级剪裁/二级摘要（迁移文档：剪裁后低于触发阈值则不调用摘要模型）。 */
+    trigger: number;
+    /**
+     * 目标 0.65B：压缩后期望达到的占用水平，随 ContextSnapshot 暴露给 /context 展示。
+     * 当前算法的启停条件是 trigger；设计文档未定义向该目标迭代收敛的机制，
+     * 故不作为候选接受条件或强制收敛线使用。
+     */
+    target: number;
+}
+interface TokenEstimate {
+    total: number;
+    system: number;
+    tools: number;
+    history: number;
+    overhead: number;
+    source: 'estimated' | 'calibrated';
+}
+/** 可替换估算器；不得执行 Provider、Hook 或改写传入请求。 */
+interface TokenEstimator {
+    estimate(request: ModelRequest, modelFingerprint?: string): TokenEstimate;
+    observe?(request: ModelRequest, actualPromptTokens: number, modelFingerprint?: string): void;
+}
+/** 未知窗口以 32K 控制，保留 12.5%（最多 4096）输出与至少 128 的 5% 安全余量。 */
+declare function createContextBudget(window?: ContextWindowValue): ContextBudget;
+/** 对对象 key 确定性排序，保证摘要、工具 schema 与 fingerprint 不受插入顺序影响。 */
+declare function stableSerialize(value: unknown): string;
+/** 请求 fingerprint 不包含 AbortSignal 等宿主对象，包含实际指令、schema、正文和输出配置。 */
+declare function requestFingerprint(request: ModelRequest, modelFingerprint?: string): string;
+/**
+ * 无依赖 Unicode 分类估算器；非 ASCII 按 code point 保守计数，ASCII 按四字符估算。
+ * 观测 usage 仅校准相同最终请求与模型，改变指令或工具会自然失效；未知值不伪造为实测。
+ */
+declare class UnicodeTokenEstimator implements TokenEstimator {
+    private readonly calibration;
+    /** 计算系统、工具、历史和协议开销，返回估算/校准来源，保持请求不变。 */
+    estimate(request: ModelRequest, modelFingerprint?: string): TokenEstimate;
+    /** 仅接受真实正整数 prompt usage，校准不会降低原保守估算；缓存最多 64 个最终请求。 */
+    observe(request: ModelRequest, actualPromptTokens: number, modelFingerprint?: string): void;
+}
+
+type CompactionReason = 'threshold' | 'manual' | 'overflow';
+interface ContextSnapshot {
+    conversationId: string;
+    modelId: string;
+    fingerprint: string;
+    budget: ContextBudget;
+    estimate: TokenEstimate;
+    protectedMessageIds: string[];
+    rawMessageCount: number;
+    projectedMessageCount: number;
+    stale: boolean;
+    actualPromptTokens?: number;
+    actualCachedPromptTokens?: number;
+    /** false 表示只读静态估算，尚未执行下一请求的动态 Hook。 */
+    dynamicKnown: boolean;
+    summaryTokens: number;
+    checkpointId?: string;
+    prunedResults: number;
+    summaryCount: number;
+    consecutiveFailures: number;
+    automaticSummaryPaused: boolean;
+    persistence: 'disk' | 'memory' | 'unsupported';
+}
+interface ContextManagerOptions {
+    store?: MessageStore;
+    estimator?: TokenEstimator;
+    conversationId: string;
+    onDiagnostic?: (message: string) => void;
+    router?: ModelRouter;
+    projectRoot?: string;
+    builtInToolNames?: () => ReadonlySet<string>;
+    onSummaryUsage?: (attemptId: string, usage: Usage | undefined, modelId: string) => Promise<void>;
+}
+/** 原始历史与请求视图之间的协调器；不执行工具、Hook 或任何终端操作。 */
+declare class ContextManager {
+    private readonly options;
+    private readonly estimator;
+    private snapshot?;
+    private terminals;
+    private checkpoint?;
+    private pruning;
+    private failure;
+    private summaryCount;
+    private readonly persistence;
+    constructor(options: ContextManagerOptions);
+    /** 恢复交互终态；有 start 无 finish 的运行保持 interrupted，不根据部分输出伪造成功。 */
+    restore(history?: readonly CanonicalMessage[]): Promise<void>;
+    /** 输出合法独立视图；原始消息和工具结果绝不被 Hook 共享引用修改。 */
+    project(history: readonly CanonicalMessage[]): CanonicalMessage[];
+    /** 添加本次交互终态，使下一次准备的保护范围与恢复后的边界一致。 */
+    finishInteraction(terminal: InteractionTerminal): void;
+    /**
+     * 最终 Hook 之后统一预算；输出 reserve 同时约束实际 maxTokens，超限零 Provider 调用。
+     * @returns 语义事件及准备完成的请求，不改变持久历史。
+     */
+    prepare(history: readonly CanonicalMessage[], request: ModelRequest, profile: ModelProfile, runId?: string, reason?: CompactionReason): AsyncGenerator<SessionEvent, ModelRequest>;
+    /** 观测真实使用量只作用于对应最终请求，不把累计 usage 当成当前窗口占用。 */
+    observe(request: ModelRequest, usage: Usage, profile: ModelProfile): void;
+    /** 查询已发布快照，不运行 Hook/Provider；配置变化后明确标记 stale。 */
+    getSnapshot(): ContextSnapshot | undefined;
+    /** 从当前静态投影估算，不执行 Hook/Provider 或更新状态；恢复后即可查看检查点。 */
+    inspect(history: readonly CanonicalMessage[], request: ModelRequest, profile: ModelProfile): ContextSnapshot;
+    /** 模型或指令发生变化后使已有预算快照过期，直到下一最终请求准备成功。 */
+    invalidate(): void;
+    /** reset 同时废弃投影与交互终态。 */
+    reset(): void;
+    /** 发布实际准备请求的独立快照，查询不会触发重新压缩。 */
+    private publishSnapshot;
+    /** 最终请求与只读估算共用来源和状态计数。 */
+    private buildSnapshot;
+    /** 摘要以用户历史背景注入，不升级为系统指令或恢复旧授权。 */
+    private summaryMessage;
+    /**
+     * 旧轮次仅在工具事务闭合时可摘要；成功可由旧记录推断，失败或中断必须有运行终态来源。
+     * 该判断不代表执行成功，也不解除最近成功轮次及其后失败尾部的保护。
+     */
+    private isClosedInteraction;
+    /** 严格检查覆盖来源、前驱链、完整终态轮次及保护集合；未知工具结果不能被冒充为成功。 */
+    private validCheckpoint;
+    /** 仅成功完成旧轮次中的白名单内置成功结果可剪裁；失败或中断轮次只参与二级摘要。 */
+    private pruningTargets;
+    /** 用候选描述替换对应结果正文，工具事务、失败标记及全部其它动态内容不变。 */
+    private applyPruningRequest;
+    /** 恢复剪裁必须满足当前来源、策略、前驱与保护范围，摘要覆盖的旧剪裁不会再次使用。 */
+    private validPruning;
+    /** 状态提交失败独立于摘要熔断；内存模式只更新内存，旧 Store 不假称可恢复。 */
+    private commit;
+    private report;
+}
+
+interface ContextSummary {
+    schemaVersion: 1;
+    goal: string;
+    constraints: string[];
+    decisions: string[];
+    completedWork: string[];
+    pendingWork: string[];
+    /** 原消息身份，不接受模型虚构来源或把旧摘要当成授权。 */
+    references: string[];
+    unknownEffects: string[];
+}
+interface FileObservation {
+    /** 有执行目录证据时为绝对路径；旧记录缺少依据时为原相对路径，基目录未知。 */
+    path: string;
+    sourceMessageId: string;
+    toolCallId: string;
+    operation: string;
+}
+interface FileDetails {
+    readFiles: FileObservation[];
+    modifiedFiles: FileObservation[];
+    failedFileOperations: FileObservation[];
+    unknownFileOperations: FileObservation[];
+    omitted: number;
+}
+/** 对超长结果保留总计 2000 code point 首尾正文，省略说明不冒充原始结果。 */
+declare function truncateToolOutput(text: string, maximum?: number): string;
+/**
+ * 从紧邻工具结果确定性提取文件事实；只认内置文件读写，不猜测命令/插件的磁盘变化。
+ * 原始成功、失败和结果未知分别记录，列表表示历史观察，不表示当前文件状态。
+ * 相对路径只按调用记录的执行根目录解析；旧历史缺少目录时保留原相对路径，位置未知。
+ * @param history 原始工具调用及紧邻结果，不执行工具或修改历史。
+ * @param _projectRoot 保留旧 API 参数；项目根不作为历史工具相对路径的推断依据。
+ * @param previous 先前检查点中的文件观察，独立复制后增量合并。
+ * @returns 有界的成功、失败和结果未知文件观察。
+ */
+declare function extractFileDetails(history: readonly CanonicalMessage[], _projectRoot: string, previous?: FileDetails): FileDetails;
+/** 有界渲染唯一文件详情，不将模型生成的文本文件列表当作成功写入证据。 */
+declare function renderFileDetails(details: FileDetails): string;
+/** 校验结构与来源；空、超长、未知字段及虚构消息引用不能进入检查点。 */
+declare function validateSummary(value: unknown, sourceIds: ReadonlySet<string>): ContextSummary;
+interface SummaryServiceOptions {
+    router: ModelRouter;
+    projectRoot: string;
+    estimator?: TokenEstimator;
+    /** 真实使用量在候选校验前记账，失败摘要仍保留消耗；不得包含主任务 TTFT。 */
+    onUsage?: (attemptId: string, usage: Usage | undefined, modelId: string) => Promise<void>;
+    timeoutMs?: number;
+}
+interface SummaryCandidate {
+    summary: ContextSummary;
+    details: FileDetails;
+    calls: number;
+    modelId: string;
+    durationMs: number;
+    usage: Usage;
+    usageKnown: boolean;
+}
+/** 摘要单次流式输出文本最大防御倍数；防止模型无限输出耗尽内存。 */
+declare const SUMMARY_OUTPUT_BUFFER_MULTIPLIER = 16;
+/** Pi 式滚动摘要服务；无主 Loop/Hook/工具，整次操作最多四调用且总时限 120 秒。 */
+declare class SummaryService {
+    private readonly options;
+    private readonly estimator;
+    constructor(options: SummaryServiceOptions);
+    /**
+     * 按完整用户交互分批，以旧摘要和新增原始前缀取材；中间结果只是局部候选，不激活。
+     * 单个不可拆分输入超预算、无终态、截断或非法来源均失败，取消先关闭 Provider 迭代。
+     */
+    generate(history: readonly CanonicalMessage[], previous?: Pick<SummaryCandidate, 'summary' | 'details'>, signal?: AbortSignal): Promise<SummaryCandidate>;
+}
+
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+type LogChannel = 'operation' | 'audit';
+type LogField = string | number | boolean | null;
+/** 单条可持久化的脱敏运行或审计事件。 */
+interface LogEvent {
+    schemaVersion: 1;
+    timestamp: string;
+    level: LogLevel;
+    channel: LogChannel;
+    event: string;
+    sessionId: string;
+    conversationId?: string;
+    runId?: string;
+    operationId?: string;
+    toolUseId?: string;
+    fields: Record<string, LogField>;
+}
+/** 宿主提供的事件存储入口；审计 Sink 的写入完成代表已持久化。 */
+interface LogSink {
+    write(event: LogEvent): Promise<void>;
+}
+interface LogInput {
+    level: LogLevel;
+    event: string;
+    sessionId: string;
+    conversationId?: string;
+    runId?: string;
+    operationId?: string;
+    toolUseId?: string;
+    fields?: Record<string, unknown>;
+}
+/** Core 与宿主共同使用的运行日志和审批审计入口。 */
+interface EventLogger {
+    record(event: LogInput): Promise<void>;
+    recordAudit(event: LogInput): Promise<void>;
+}
+/** 将任意来源的字段缩减为可写入日志的固定集合。 */
+declare function projectSafeFields(fields: Record<string, unknown>): Record<string, LogField>;
+/** 生成不依赖模型工具调用 ID 的内部关联标识。 */
+declare function createLogId(): string;
+/** 只暴露固定命令类别与参数数目，避免把自由文本写入审计。 */
+declare function commandAuditSummary(command: string): {
+    commandDigest: string;
+    commandPreview: string;
+    commandLength: number;
+    argumentCount: number;
+};
+/** 将批准范围绑定到最终命令、解释器、目录与执行选项。 */
+declare function executionFingerprint(input: {
+    command: string;
+    shell: string;
+    executable: string;
+    cwd: string;
+    environmentDigest: string;
+    timeoutMs: number;
+    outputLimitBytes: number;
+    targetDigest?: string;
+}): string;
+/** 统一筛选和脱敏日志；运行日志失败只报告安全诊断，审计失败仍向调用方传播。 */
+declare class StructuredLogger implements EventLogger {
+    private readonly operationSink;
+    private readonly auditSink;
+    private readonly debug;
+    private readonly onDiagnostic?;
+    constructor(options: {
+        operationSink: LogSink;
+        auditSink: LogSink;
+        debug?: boolean;
+        onDiagnostic?: (message: string) => void;
     });
+    /** 普通日志写入失败不阻断业务，也不声称持久化成功；诊断不携带原始异常内容。 */
+    record(event: LogInput): Promise<void>;
+    /** 审计必须成功持久化；异常交由执行器拒绝启动工具或报告已执行操作的结果未知。 */
+    recordAudit(event: LogInput): Promise<void>;
+    private format;
 }
-declare class TransportError extends KapibalaError {
-    readonly retryable: boolean;
-    constructor(message: string, retryable?: boolean);
+
+interface FileLogSinkOptions {
+    directory: string;
+    prefix: 'operation' | 'audit';
+    maxBytes?: number;
+    retentionDays?: number;
+    sync?: boolean;
 }
-declare class ToolError extends KapibalaError {
-    constructor(message: string);
+/** 将每条 JSONL 事件完整追加到本地文件，并按日期及文件大小轮转。 */
+declare class FileLogSink implements LogSink {
+    readonly directory: string;
+    readonly prefix: 'operation' | 'audit';
+    private readonly maxBytes;
+    private readonly retentionDays?;
+    private readonly sync;
+    constructor(options: FileLogSinkOptions);
+    write(event: LogEvent): Promise<void>;
+    /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
+    getUsageBytes(): number;
+    private chooseFile;
+    private cleanupExpired;
+    private isOwnedFile;
 }
-declare class ToolNotFound extends KapibalaError {
-    readonly toolName: string;
-    readonly availableTools: string[];
-    constructor(toolName: string, availableTools?: string[]);
+/** 构造 CLI 与默认 SDK 使用的用户级运行及审计 Sink。 */
+declare function createDefaultLogSinks(baseDirectory?: string): {
+    operationSink: FileLogSink;
+    auditSink: FileLogSink;
+};
+/** 启动时保守关闭上次进程未完成的审计事务，绝不将其当作未执行或自动重试。 */
+declare function recoverIncompleteAudit(directory: string): Promise<number>;
+
+interface InstructionSource {
+    path: string;
+    content: string;
 }
-declare class AbortError extends KapibalaError {
-    constructor(message?: string);
+interface InstructionSnapshot {
+    sources: readonly InstructionSource[];
+    totalBytes: number;
 }
-declare class FatalError extends KapibalaError {
-    constructor(message: string);
+interface InstructionLoadOptions {
+    projectRoot: string;
+    cwd: string;
+    userFile?: string;
 }
-declare class SessionBusyError extends KapibalaError {
-    constructor(operation: string);
+/** 按用户层和项目根至 cwd 的目录链读取指令，全部成功后才返回快照。 */
+declare function loadInstructions(options: InstructionLoadOptions): InstructionSnapshot;
+
+type ShellKind = 'bash' | 'wsl' | 'pwsh' | 'powershell';
+/** auto / 具名解释器，或用户显式提供的解释器可执行文件全路径。 */
+type ShellPreference = 'auto' | ShellKind | (string & {});
+interface ShellEnvironment {
+    kind: ShellKind;
+    executable: string;
+    executableDigest: string;
+    cwd: string;
+}
+interface ShellDetectOptions {
+    preference?: ShellPreference;
+    cwd: string;
+    platform?: NodeJS.Platform;
+    pathEnv?: string;
 }
+/**
+ * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
+ * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
+ */
+declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
+/**
+ * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
+ * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
+ * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
+ */
+declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
+
+/** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
+type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
+type PermissionAction = 'allow' | 'ask' | 'deny';
+interface ShellScope {
+    command: string;
+    interpreter: string;
+    executablePath?: string;
+    cwd: string;
+    executableDigest?: string;
+    scriptDigest?: string;
+    executionFingerprint?: string;
+}
+interface PermissionRule {
+    action: PermissionAction;
+    tool?: string;
+    capability?: Capability;
+    shell?: ShellScope;
+}
+interface PermissionRequest {
+    mode: SessionMode;
+    toolName: string;
+    capabilities: readonly Capability[];
+    dangerous?: boolean;
+    hardDenied?: boolean;
+    shell?: ShellScope;
+    rules?: readonly PermissionRule[];
+    cachedApproval?: boolean;
+    cachedDenial?: boolean;
+}
+interface PermissionDecision {
+    decision: PermissionAction;
+    source: 'hard_limit' | 'plan' | 'explicit_rule' | 'session_cache' | 'mode_default';
+    ruleIndex?: number;
+}
+/** 拒绝含糊的 Shell 前缀/通配符和结构不完整的规则。 */
+declare function validatePermissionRules(rules: readonly PermissionRule[]): void;
+/** 纯策略裁决；宿主硬限制和 Plan 始终先于任何规则或会话缓存。 */
+declare class PermissionPolicy {
+    decide(request: PermissionRequest): PermissionDecision;
+}
+/** 只向模型展示当前模式与整项拒绝规则允许请求的工具。 */
+declare function visibleTools(tools: readonly Tool[], mode: SessionMode, rules?: readonly PermissionRule[]): Tool[];
+
+type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn';
+interface ToolMetadata {
+    source?: string;
+    dangerous?: boolean;
+    /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
+    permissions?: Capability[];
+    /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
+    managesTimeout?: boolean;
+}
+interface ToolContext {
+    rootDir: string;
+    signal?: AbortSignal;
+    logger?: (message: string) => void;
+    /** 命令工具在真实进程创建后调用；审计失败时须先回收进程再报告结果未知。 */
+    onProcessSpawned?: () => Promise<void>;
+    onProgress?: (progress: {
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void;
+}
+interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly metadata?: ToolMetadata;
+    approvalScope?(input: TInput, rootDir: string): ShellScope;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>(tool: Tool<TInput, TOutput>): Tool<TInput, TOutput>;
+declare function toToolDefinition(tool: Tool): ToolDefinition;
+
+interface RunCommandInput {
+    [key: string]: unknown;
+    command: string;
+    cwd?: string;
+    timeout_ms?: number;
+}
+interface CommandResult {
+    exitCode: number | null;
+    output: string;
+    outputTruncated: boolean;
+    outputFile?: string;
+    outputFileTruncated: boolean;
+    outputBytes: number;
+    shell: ShellEnvironment['kind'];
+}
+/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
+declare function cleanupCommandResults(rootDir: string, now?: number): void;
+/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
+declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
 
 interface SandboxConfig {
     rootDir: string;
@@ -260,27 +1158,28 @@ declare class PathSandbox {
     private toPhysicalPath;
 }
 
-type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn';
-interface ToolMetadata {
-    source?: string;
-    dangerous?: boolean;
-    /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
-    permissions?: Capability[];
-}
-interface ToolContext {
+type ApprovalChoice = 'allow_once' | 'allow_session' | 'deny_once' | 'deny_session' | 'cancel';
+/** 宿主展示实际执行目标并取得人工选择；无通道视为非交互拒绝。 */
+interface ApprovalRequest {
+    toolName: string;
+    capabilities: readonly Capability[];
+    input: Record<string, unknown>;
     rootDir: string;
-    signal?: AbortSignal;
-    logger?: (message: string) => void;
+    shell?: ShellScope;
+    sessionAllowed: boolean;
 }
-interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: Record<string, unknown>;
-    readonly metadata?: ToolMetadata;
-    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+interface ApprovalChannel {
+    requestApproval(request: ApprovalRequest, signal?: AbortSignal): Promise<ApprovalChoice>;
+}
+/** 规范化 JSON 序列化：递归对对象键按字典序排序，保证相同的输入结构产生一致的字符串和 Hash。 */
+declare function stableJsonStringify(value: unknown): string;
+/** 只在当前 Session 内复用精确调用范围，不存储原始工具参数。 */
+declare class SessionApprovalCache {
+    private readonly choices;
+    key(request: ApprovalRequest): string;
+    get(request: ApprovalRequest): 'allow' | 'deny' | undefined;
+    set(request: ApprovalRequest, choice: 'allow' | 'deny'): void;
 }
-declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>(tool: Tool<TInput, TOutput>): Tool<TInput, TOutput>;
-declare function toToolDefinition(tool: Tool): ToolDefinition;
 
 type ConflictPolicy = 'error' | 'prefer-builtin' | 'prefer-last';
 declare class ToolRegistry {
@@ -408,6 +1307,13 @@ interface ExecutorOptions {
     logger?: (msg: string) => void;
     /** 单次工具执行超时(毫秒)。异步挂起的工具超时后返回 isError 结果，避免永久卡死会话循环 */
     toolTimeoutMs?: number;
+    eventLogger?: EventLogger;
+    sessionId?: string;
+    runId?: string;
+    mode?: SessionMode | (() => SessionMode);
+    permissionRules?: readonly PermissionRule[];
+    approvalChannel?: ApprovalChannel;
+    approvalCache?: SessionApprovalCache;
 }
 declare class ToolExecutor {
     private readonly tools;
@@ -416,9 +1322,36 @@ declare class ToolExecutor {
     private readonly signal?;
     private readonly logger?;
     private readonly toolTimeoutMs;
+    private readonly eventLogger?;
+    private readonly sessionId?;
+    private readonly runId?;
+    private readonly mode;
+    private readonly permissionRules;
+    private readonly approvalChannel?;
+    private readonly approvalCache;
+    private readonly policy;
+    private readonly neverFailures;
+    private readonly cancellation;
     constructor(options: ExecutorOptions);
-    runAll(calls: ToolUseBlock[]): Promise<ToolResultBlock[]>;
-    executeOne(call: ToolUseBlock): Promise<ToolResultBlock>;
+    /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
+    cancel(): void;
+    runAll(calls: ToolUseBlock[], onProgress?: (event: {
+        id: string;
+        name: string;
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void): Promise<ToolResultBlock[]>;
+    /**
+     * 在最终参数上裁决并审计一次调用，所有拒绝和异常均闭合为工具结果。
+     * 为调用记录本次绝对工具根目录，供跨目录恢复后的文件事实解析；不使用历史目录授权。
+     */
+    executeOne(call: ToolUseBlock, onProgress?: (event: {
+        id: string;
+        name: string;
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void, forcedDeny?: boolean): Promise<ToolResultBlock>;
+    private executeResolved;
     /**
      * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
      * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
@@ -429,57 +1362,13 @@ declare class ToolExecutor {
     private withTimeout;
 }
 
-type ModelRole = 'default' | 'planning' | 'execution' | 'summary' | 'fast';
-type ContextWindowValue = number | `${number}${'K' | 'k' | 'M' | 'm'}`;
-interface ResolvedContextWindow {
-    tokens: number;
-    /** true 表示模型未声明窗口，当前值来自 Kapibala 的默认估算。 */
-    estimated: boolean;
-}
-declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 1000000;
-/**
- * 将模型上下文窗口统一解析为整数 Token 数。
- *
- * 配置允许直接填写整数，或使用十进制 K/M 简写；未填写时返回默认 1M，并标记为估算值。
- */
-declare function resolveContextWindow(value?: ContextWindowValue): ResolvedContextWindow;
-interface ModelProfile {
-    id: string;
-    name: string;
-    provider: 'openai-compatible';
-    baseURL: string;
-    apiKeyEnv: string;
-    apiKey?: string;
-    modelName: string;
-    contextWindow?: ContextWindowValue;
-    supportsThinking?: boolean;
-}
-interface ModelRouter {
-    resolve(role?: ModelRole): ModelProvider;
-    getProfile(role?: ModelRole): ModelProfile;
-}
-declare class SimpleModelRouter implements ModelRouter {
-    private readonly providers;
-    private readonly profiles;
-    private defaultRole;
-    constructor(defaultProfile: ModelProfile, defaultProvider: ModelProvider);
-    setRole(role: ModelRole, profile: ModelProfile, provider: ModelProvider): void;
-    resolve(role?: ModelRole): ModelProvider;
-    getProfile(role?: ModelRole): ModelProfile;
-}
-
-interface ModelProvider {
-    readonly name: string;
-    create(req: ModelRequest): AsyncIterable<ModelEvent>;
-    /** 把一批工具结果装配成符合本协议的 canonical 消息序列 */
-    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
-}
-
 interface OpenAIProviderOptions {
     baseURL: string;
     apiKey: string;
     modelName: string;
     supportsThinking?: boolean;
+    /** 回传 assistant 思考历史；默认仅为 DeepSeek 官方端点启用，自建兼容网关可显式开启。 */
+    replayReasoningContent?: boolean;
     /** 建立 HTTP 连接(收到响应头)的超时毫秒数；仅约束建连阶段，不限制流式读取总时长 */
     connectTimeoutMs?: number;
 }
@@ -489,47 +1378,32 @@ declare class OpenAICompatibleProvider implements ModelProvider {
     readonly apiKey: string;
     readonly modelName: string;
     readonly supportsThinking: boolean;
+    readonly replayReasoningContent: boolean;
     readonly connectTimeoutMs: number;
+    /** 初始化协议适配；思考历史回传独立于模型能力标签，仅对兼容端点启用。 */
     constructor(options: OpenAIProviderOptions);
+    /** 发送流式请求，兼容端点原样回传思考历史；中断仅报告错误，不自动重放工具或请求。 */
     create(req: ModelRequest): AsyncIterable<ModelEvent>;
     assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+    /** 将历史投影为协议消息；兼容端点完整回传思考片段，普通端点不发送该扩展字段。 */
     private translateMessagesToWire;
 }
 
-declare class JSONLMessageStore implements MessageStore {
-    readonly filePath: string;
-    constructor(filePath: string);
-    append(message: CanonicalMessage): Promise<void>;
-    load(): Promise<CanonicalMessage[]>;
-    clear(): Promise<void>;
-    /**
-     * 历史自愈(设计文档 §4.4)：逐条扫描 assistant 的 tool_use，
-     * 若其后的 tool 消息未完整覆盖这些 tool_use，就地补一条 is_error 的 tool_result。
-     *
-     * 之所以做**全历史扫描**而非只看末条：崩溃可能发生在任意一轮工具执行中途，
-     * 悬挂的 tool_use 未必位于历史末尾(例如中断后用户又继续提了问)。
-     * 只看末条会漏掉夹在中间的悬挂，下一次请求仍会因上下文非法而 400。
-     */
-    private healDanglingToolCalls;
-}
-
-interface MessageStore {
-    append(message: CanonicalMessage): Promise<void>;
-    load(): Promise<CanonicalMessage[]>;
-    clear(): Promise<void>;
-}
-
 interface PromptAssemblerOptions {
     tools?: ToolRegistry;
     rootDir: string;
     agentName?: string;
     customInstructions?: string;
+    instructionSources?: readonly InstructionSource[];
+    visibleTools?: readonly Tool[];
 }
 declare class PromptAssembler {
     private readonly tools?;
     private readonly rootDir;
     private readonly agentName;
     private readonly customInstructions?;
+    private readonly instructionSources;
+    private readonly visibleTools?;
     constructor(options: PromptAssemblerOptions);
     assemble(): string;
     private getL1Behavior;
@@ -538,6 +1412,12 @@ declare class PromptAssembler {
 }
 
 interface AgentLoopOptions {
+    /** 本次交互身份，内部步骤仍独立编号。 */
+    interactionId?: string;
+    modelId?: string;
+    projectHistory?: (history: readonly CanonicalMessage[]) => CanonicalMessage[];
+    prepareRequest?: RequestPreparation;
+    onUsage?: (request: ModelRequest, usage: Usage, attemptId: string) => Promise<void>;
     provider: ModelProvider;
     executor: ToolExecutor;
     tools: ToolRegistry;
@@ -546,8 +1426,18 @@ interface AgentLoopOptions {
     maxSteps?: number;
     maxConsecutiveErrors?: number;
     signal?: AbortSignal;
+    eventLogger?: EventLogger;
+    sessionId?: string;
+    runId?: string;
+    getMode?: () => SessionMode;
+    permissionRules?: readonly PermissionRule[];
 }
 declare class AgentLoop {
+    private readonly interactionId?;
+    private readonly modelId?;
+    private readonly projectHistory?;
+    private readonly prepareRequest?;
+    private readonly onUsage?;
     private readonly provider;
     private readonly executor;
     private readonly tools;
@@ -556,11 +1446,20 @@ declare class AgentLoop {
     private readonly maxSteps;
     private readonly maxConsecutiveErrors;
     private readonly signal?;
+    private readonly eventLogger?;
+    private readonly sessionId?;
+    private readonly runId?;
+    private readonly getMode;
+    private readonly permissionRules;
     constructor(options: AgentLoopOptions);
     run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
 }
 
 interface SessionConfig {
+    /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
+    conversationId?: string;
+    tokenEstimator?: TokenEstimator;
+    gitBranch?: string;
     defaultProfile: ModelProfile;
     defaultProvider: ModelProvider;
     store?: MessageStore;
@@ -568,8 +1467,25 @@ interface SessionConfig {
     systemPrompt?: string;
     maxSteps?: number;
     logger?: (msg: string) => void;
+    eventLogger?: EventLogger;
+    loggingDirectory?: string;
+    mode?: SessionMode;
+    permissionRules?: readonly PermissionRule[];
+    approvalChannel?: ApprovalChannel;
+    projectRoot?: string;
+    cwd?: string;
+    userInstructionsPath?: string;
+    auditRecoveryDirectory?: string;
+    /** 接收普通运行日志失败的脱敏诊断；诊断失败也不得中断问答或替代审计。 */
+    onDiagnostic?: (message: string) => void;
 }
 interface SessionStats {
+    conversationId?: string;
+    /** 历史存在无 usage 的模型步骤时为 false，不将旧消耗伪装为精确零。 */
+    usageKnown?: boolean;
+    summaryUsage?: Usage;
+    summaryUsageKnown?: boolean;
+    contextSnapshot?: ContextSnapshot;
     totalTurns: number;
     totalTokens: Usage;
     activeModel: string;
@@ -579,6 +1495,17 @@ interface SessionStats {
     contextUsage: ContextUsage;
 }
 declare class AgentSession {
+    private persistentId;
+    private readonly configuredConversationId?;
+    private readonly estimator?;
+    private readonly onDiagnostic?;
+    private readonly gitBranch?;
+    private context;
+    private usageKnown;
+    private summaryUsageKnown;
+    private summaryUsage;
+    private readonly summaryAttempts;
+    private readonly accountedAttempts;
     readonly rootDir: string;
     readonly tools: ToolRegistry;
     readonly hooks: HookRegistry;
@@ -587,13 +1514,28 @@ declare class AgentSession {
     private readonly customSystemPrompt?;
     private readonly maxSteps;
     private readonly logger?;
+    private readonly eventLogger;
+    private readonly sessionId;
+    private mode;
+    private readonly permissionRules;
+    private readonly approvalChannel?;
+    private readonly approvalCache;
+    private readonly projectRoot;
+    private readonly cwd;
+    private readonly userInstructionsPath?;
+    private instructionSnapshot?;
+    private readonly auditRecoveryDirectory?;
     private history;
     private totalTurns;
     private usageStats;
     private lastMetrics?;
     private lastRunMetrics?;
     private initialized;
+    private pendingResume;
     private destroyed;
+    private cleanupStarted;
+    private cleanupPromise?;
+    private sessionEndFinished;
     private activeRun;
     private readonly plugins;
     constructor(config: SessionConfig);
@@ -601,9 +1543,26 @@ declare class AgentSession {
     use(plugin: AgentPlugin): Promise<void>;
     switchModel(profile: ModelProfile, role?: ModelRole, provider?: ModelProvider): void;
     getActiveProfile(role?: ModelRole): ModelProfile;
+    /** 只在空闲时切换本次会话模式；宿主负责 FullAccess 的显式选择交互。 */
+    switchMode(mode: SessionMode): void;
+    getMode(): SessionMode;
+    /** 返回最近一次成功装载的来源路径，不暴露指令正文。 */
+    getInstructionSources(): string[];
+    /** 稳定会话身份，独立于当前进程日志实例和每次用户交互。 */
+    get conversationId(): string;
+    /** 返回原始历史独立快照，外部修改不会改变落盘事实或当前工具事务。 */
     getHistory(): CanonicalMessage[];
+    /** 返回当前投影视图，区别于原始历史；不执行模型或 Hook。 */
+    getContextHistory(): CanonicalMessage[];
+    /** 查询最近最终请求的预算快照，尚未准备请求时返回 undefined。 */
+    getContextSnapshot(): ContextSnapshot | undefined;
+    /** 执行中止后的工具/摘要与存储收口期间仍返回 true。 */
+    isBusy(): boolean;
+    /** 返回独立统计快照，宿主修改嵌套指标不会改变会话状态或预算展示。 */
     getStats(): SessionStats;
+    /** 返回最近请求指标的独立副本；尚无完成请求时返回 undefined。 */
     getLastMetrics(): TurnMetrics | undefined;
+    /** 返回最近用户任务指标的独立副本；恢复的 usage 不伪造实时任务指标。 */
     getLastRunMetrics(): RunMetrics | undefined;
     reset(): Promise<void>;
     /**
@@ -620,17 +1579,36 @@ declare class AgentSession {
     run(userInput: string, options?: {
         signal?: AbortSignal;
     }): AsyncIterable<SessionEvent>;
+    /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
+    private runOperation;
     destroy(): Promise<void>;
     private assertIdle;
     /**
-     * 计算最近一次内部模型请求的上下文占用。
+     * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
      * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
      */
     private createContextUsage;
     private persistAssistant;
+    /** 创建上下文协调器并注入当前路由；摘要不经过主任务 Loop，插件结果不默认为可剪裁。 */
+    private createContextManager;
+    /** 摘要实际消耗按 attempt 身份独立累加；缺失消耗保留未知，不计入主任务指标。 */
+    private accountSummaryUsage;
+    /**
+     * 空闲时手动摘要旧完整前缀，不创建用户任务、不执行工具，不突破当前与最近成功交互。
+     * 迭代结束或取消后等候摘要与提交收口，再释放执行状态；已提交检查点保持有效。
+     */
+    compact(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SessionEvent>;
+    /** 手动压缩执行主体，接收由消费者生命周期拥有的中止信号。 */
+    private compactOperation;
+    /** 以模型 attempt 身份幂等累加真实消耗；非法或缺失 usage 保持未知。 */
+    private logContextEvent;
+    /** 以模型 attempt 身份幂等累加真实消耗；非法或缺失 usage 保持未知。 */
+    private accountUsage;
     private persistToolMessages;
     private closeInterruptedToolCalls;
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, type CanonicalMessage, type Capability, type ConflictPolicy, type ContentBlock, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type ExecutorOptions, FatalError, type HookContext, type HookHandlers, type HookPoint, HookRegistry, JSONLMessageStore, KapibalaError, type MessageRole, type MessageStore, ModelError, type ModelEvent, type ModelProfile, type ModelProvider, type ModelRequest, type ModelRole, type ModelRouter, OpenAICompatibleProvider, type OpenAIProviderOptions, PathSandbox, type PluginContext, PromptAssembler, type PromptAssemblerOptions, type RedactedThinkingBlock, type ResolvedContextWindow, type RunMetrics, type SandboxConfig, SessionBusyError, type SessionConfig, type SessionEvent, type SessionStats, SimpleModelRouter, type StepLogEntry, type StepLogStage, type TextBlock, type ThinkingBlock, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, ToolExecutor, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolResultBlock, type ToolUseBlock, TransportError, type TurnMetrics, type Usage, builtinTools, defineTool, editFileTool, globTool, grepTool, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, readFileTool, resolveContextWindow, toToolDefinition, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProvider, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginContext, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionHeader, SessionLock, SessionManager, type SessionManagerOptions, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, ToolExecutor, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolResultBlock, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, createContextBudget, createDefaultLogSinks, createLogId, createMessageId, createRunCommandTool, defineTool, describeModelError, detectShell, editFileTool, executionFingerprint, extractFileDetails, globTool, grepTool, identifyHistory, indexInteractions, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, loadInstructions, normalizeHistory, projectSafeFields, readFileTool, recoverIncompleteAudit, renderFileDetails, requestFingerprint, resolveContextWindow, resolveSessionProject, sanitizeModelErrorMessage, sanitizeSessionTitle, stableJsonStringify, stableSerialize, supportsSessionState, toToolDefinition, truncateToolOutput, validatePermissionRules, validateSummary, visibleTools, writeFileTool };