@kiturone/kapibala 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -1,16 +1,264 @@
+/** 内置适配器的实际请求目标；用于拒绝模型、协议或端点错配的绑定。 */
+interface ModelProviderBinding {
+    protocol: ModelProtocol;
+    modelName: string;
+    baseURL: string;
+    workspaceId?: string;
+}
+/** 协议适配器：把 canonical 请求翻译为 wire 协议并流式返回事件。 */
+interface ModelProvider {
+    /** 用于诊断与脱敏说明的稳定名称。 */
+    readonly name: string;
+    readonly binding?: ModelProviderBinding;
+    /** 内置 Provider 凭据是否可用；自定义无需鉴权的 Provider 可省略。 */
+    readonly credentialsReady?: boolean;
+    /** 发起一次模型调用；signal 取消时立即停止，实现负责协议翻译、私有状态校验与流清理。 */
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /** 返回统一 canonical tool 消息；wire 角色转换仅发生在请求翻译阶段。 */
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+}
+/** 按消息级事务装配工具结果；任何协议都不得把 wire user/Item 写为历史角色。 */
+declare function assembleCanonicalToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+
+/** 逻辑模型角色：default 为回退绑定，planning / execution / fast 是主任务可选场景，summary 仅用于独立的上下文压缩。 */
+type ModelRole = 'default' | 'planning' | 'execution' | 'summary' | 'fast';
+/** 主任务可显式选择的场景；summary 只用于独立的上下文压缩。 */
+type PrimaryModelRole = Exclude<ModelRole, 'summary'>;
+/** wire 协议族；决定适配器实现、私有状态格式与错误解析方式。 */
+type ModelProtocol = 'openai-compatible' | 'anthropic' | 'openai-responses';
+/** 兼容 Chat 端点的显式参数/完成能力；缺省保持既有参数并要求完整 DONE。 */
+interface ChatCapabilities {
+    maxTokensField?: 'max_tokens' | 'max_completion_tokens';
+    supportsStreamingUsage?: boolean;
+    supportsTemperature?: boolean;
+    requiresDone?: boolean;
+    replayReasoningContent?: boolean;
+}
+/** 配置侧窗口值：正整数 Token 数，或十进制 K / M 简写（如 '200K'）；解析规则见 resolveContextWindow。 */
+type ContextWindowValue = number | `${number}${'K' | 'k' | 'M' | 'm'}`;
+/** 解析后的窗口；estimated 为 true 时数值来自默认估算，不能当作模型的精确保证。 */
+interface ResolvedContextWindow {
+    tokens: number;
+    /** true 表示模型未声明窗口，当前值来自 Kapibala 的默认估算。 */
+    estimated: boolean;
+}
+/** 模型未声明 contextWindow 时的默认窗口估算值。 */
+declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 1000000;
+/**
+ * 将模型上下文窗口统一解析为整数 Token 数。
+ *
+ * 配置允许直接填写整数，或使用十进制 K/M 简写；未填写时返回默认 1M，并标记为估算值。
+ */
+declare function resolveContextWindow(value?: ContextWindowValue): ResolvedContextWindow;
+/** 模型配置档案；provider 是 wire 协议族而非厂商名，绑定必须与适配器声明一致（见 validateModelBinding）。 */
+interface ModelProfile {
+    id: string;
+    name: string;
+    provider: ModelProtocol;
+    baseURL: string;
+    /** 承载密钥的环境变量名；core 不直接读取，由宿主解析后注入 Provider。 */
+    apiKeyEnv: string;
+    apiKey?: string;
+    modelName: string;
+    /** 未声明时按 DEFAULT_CONTEXT_WINDOW_TOKENS 估算；解析规则见 resolveContextWindow。 */
+    contextWindow?: ContextWindowValue;
+    supportsThinking?: boolean;
+    /** 单次输出上限；参与上下文预算推导，缺省按 4096 预留。 */
+    maxOutputTokens?: number;
+    chatCapabilities?: ChatCapabilities;
+    /** Anthropic 请求携带的 workspace；参与绑定一致性校验。 */
+    anthropicWorkspaceId?: string;
+}
+/** 角色到 Profile / Provider 配对的解析接口；实现必须保证配对一致且 profile 以副本返回。 */
+interface ModelRouter {
+    resolve(role?: ModelRole): ModelProvider;
+    getProfile(role?: ModelRole): ModelProfile;
+}
+/** 校验内置适配器的实际请求目标；旧自定义 Provider 由宿主显式提供绑定。 */
+declare function validateModelBinding(profile: ModelProfile, provider: ModelProvider): void;
+/** 保存原子 Profile/Provider 配对；普通与摘要查询可回退 default，显式任务严格解析。 */
+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;
+    /** 显式场景要求存在绑定；只有普通查询和摘要允许既有默认回退。 */
+    getBinding(role?: ModelRole, strict?: boolean): {
+        profile: ModelProfile;
+        provider: ModelProvider;
+    };
+    resolve(role?: ModelRole): ModelProvider;
+    /** 返回指定角色或默认模型的独立副本，调用方不能改写在途绑定。 */
+    getProfile(role?: ModelRole): ModelProfile;
+}
+
+/**
+ * Error Taxonomy for Kapibala Agent Harness
+ */
+
+/** 模型失败的安全分类；由明确状态码与受控错误码推导，不基于自然语言猜测根因。 */
+type ModelErrorCategory = 'authentication' | 'quota' | 'rate_limit' | 'context' | 'service' | 'network' | 'timeout' | 'invalid_request' | 'invalid_response' | 'unknown';
+/** ModelError 的受控输入；仅这些字段会进入错误对象，原始响应体与密钥不得携带。 */
+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';
+    /** type-only 引用协议层角色类型；运行时无循环依赖。 */
+    modelRole?: PrimaryModelRole;
+    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' | 'modelRole'>): ModelErrorInfo;
+/** 错误体系基类：code 供机器判定，retryPolicy 是处理建议而非重试授权，safeMessage 是可对外展示的固定文案。 */
+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;
+    });
+}
+/** 模型调用失败；message 已脱敏，对外诊断统一经 describeModelError 产出，retryPolicy 仅为处理建议。 */
+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;
+    });
+}
+/** 模型 API 语义之外的传输失败；retryable 表示属于可立即重试的网络类错误。 */
+declare class TransportError extends KapibalaError {
+    readonly retryable: boolean;
+    constructor(message: string, retryable?: boolean);
+}
+/** 工具执行失败的通用错误；retryPolicy 固定 never，后续处理由调用方决定。 */
+declare class ToolError extends KapibalaError {
+    constructor(message: string);
+}
+/** 请求的工具在注册表中不存在；message 回显工具名与可用列表，对外展示用 safeMessage。 */
+declare class ToolNotFound extends KapibalaError {
+    readonly toolName: string;
+    readonly availableTools: string[];
+    constructor(toolName: string, availableTools?: string[]);
+}
+/** 用户主动中止；不属于失败，恢复需要用户重新发起操作。 */
+declare class AbortError extends KapibalaError {
+    constructor(message?: string);
+}
+/** 无受控分类的致命错误（code 固定 INTERNAL_ERROR、不可重试）；终止策略由宿主决定。 */
+declare class FatalError extends KapibalaError {
+    constructor(message: string);
+}
+/** 会话正在执行任务时拒绝新的排他操作（切换模型、挂载插件等），operation 描述被拒绝的动作。 */
+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 ProtocolOrigin {
+    version: 1;
+    protocol: 'anthropic' | 'openai-responses';
+    modelName: string;
+    modelId?: string;
+    runId: string;
+    endpointScope: string;
+}
+/** Responses Item 与 canonical 块的对应关系；调用 Item 身份独立于业务 call_id。 */
+interface ProtocolItemMetadata {
+    origin: ProtocolOrigin;
+    itemIndex: number;
+    itemId?: string;
+    contentIndex?: number;
+    phase?: 'commentary' | 'final_answer';
+    contentType?: 'output_text' | 'refusal';
+    arguments?: string;
+}
+/** 只保存受控 reasoning Item；密文不进入展示或摘要源。 */
+interface ProviderStateBlock {
+    type: 'provider_state';
+    origin: ProtocolOrigin;
+    item: {
+        type: 'reasoning';
+        id: string;
+        encrypted_content?: string;
+        summary: {
+            type: 'summary_text';
+            text: string;
+        }[];
+        status?: 'in_progress' | 'completed' | 'incomplete';
+    };
+}
+/** canonical 历史的内容块联合；provider_state 等私有块只在同 run、同模型与端点续答回传。 */
+type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock | RedactedThinkingBlock | ProviderStateBlock;
 interface TextBlock {
     type: 'text';
     text: string;
+    /** 源 wire Item 元数据；正文被改写后由调用方清除，不作为业务身份。 */
+    protocolMeta?: ProtocolItemMetadata;
 }
 interface ToolUseBlock {
+    /** 工具执行语义来源；新运行记录，旧历史可缺省。未知插件不按内置只读工具剪裁。 */
+    source?: string;
+    /** 执行器记录的绝对工具根目录；仅作历史路径依据，不改变参数或恢复旧授权。旧历史可缺省。 */
+    executionRoot?: string;
     type: 'tool_use';
     id: string;
     name: string;
     input: Record<string, unknown>;
+    /** 源 wire Item 元数据；内容被改写后由调用方清除，不作为业务身份。 */
+    protocolMeta?: ProtocolItemMetadata;
 }
 interface ToolResultBlock {
     type: 'tool_result';
@@ -27,27 +275,54 @@ interface ToolResultBlock {
 interface ThinkingBlock {
     type: 'thinking';
     thinking: string;
+    /** 存在签名或来源时属于私有输出，改写内容会被整批拒绝。 */
     signature?: string;
+    origin?: ProtocolOrigin;
 }
+/** Provider 提供的密文占位；仅按原样回传用于续答，不进入展示或摘要源。 */
 interface RedactedThinkingBlock {
     type: 'redacted_thinking';
     data: string;
+    origin?: ProtocolOrigin;
 }
+/** 单次模型请求的 token 用量；由 Provider 上报，缺失的字段不能按零推断。 */
 interface Usage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Provider 明确提供的缓存命中输入量；缺失表示未知，不能按零推断。 */
+    cachedPromptTokens?: number;
 }
+/** canonical 消息角色；'tool' 仅用于工具结果消息，wire 角色转换只发生在请求投影阶段。 */
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * 协议无关的历史真源；wire 格式只在请求投影时出现。
+ * 不变量：assistant 消息中的 tool_use 进入历史后，对应 tool_result 消息必须紧跟其后。
+ */
 interface CanonicalMessage {
+    /** 派生背景锚点独立于真实用户输入，避免合并后丢失受保护原消息的来源身份。 */
+    contextSummary?: {
+        checkpointId: string;
+    };
+    /** 稳定消息身份；旧 SDK 消息可省略，在进入受管历史时补齐。 */
+    id?: string;
+    /** 用户交互身份，与内部模型步骤及进程运行实例分别记录。 */
+    interactionId?: string;
+    /** 未完成正文不会进入模型请求视图。省略表示旧版已落盘正文。 */
+    state?: 'completed' | 'draft' | 'failed' | 'interrupted';
     role: MessageRole;
     content: ContentBlock[];
     timestamp?: number;
 }
+/** 判别并收窄为文本块。 */
 declare function isTextBlock(block: ContentBlock): block is TextBlock;
+/** 判别并收窄为工具调用块。 */
 declare function isToolUseBlock(block: ContentBlock): block is ToolUseBlock;
+/** 判别并收窄为工具结果块。 */
 declare function isToolResultBlock(block: ContentBlock): block is ToolResultBlock;
+/** 判别并收窄为思考块。 */
 declare function isThinkingBlock(block: ContentBlock): block is ThinkingBlock;
+/** 单个 turn 的指标快照；错误与熔断路径也以统一构造产出（工具字段为零），保证结构一致。 */
 interface TurnMetrics {
     turn: number;
     startTime: number;
@@ -61,6 +336,7 @@ interface TurnMetrics {
     totalTokens: number;
     toolCallsCount: number;
 }
+/** 一次完整 run 的累计指标；token 数为各轮请求之和，上下文占用单独见 contextUsage。 */
 interface RunMetrics {
     startTime: number;
     endTime: number;
@@ -74,16 +350,23 @@ 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;
 }
+/** 单 turn 内关键阶段的进度标记；顺序与 AgentLoop 的实际派发时序一致，供展示与诊断。 */
 type StepLogStage = 'model_request_start' | 'first_token' | 'model_stream_finish' | 'tool_execution_start' | 'tool_execution_finish' | 'turn_finish';
+/** 面向宿主的步骤日志；message 可直接展示，结构化数值放在 metadata 中。 */
 interface StepLogEntry {
     timestamp: number;
     turn: number;
@@ -100,6 +383,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;
 } | {
@@ -108,9 +441,16 @@ type SessionEvent = {
 } | {
     type: 'text_delta';
     text: string;
+} | {
+    type: 'thinking_block_start';
+    blockId: string;
 } | {
     type: 'thinking_delta';
     thinking: string;
+    blockId?: string;
+} | {
+    type: 'thinking_block_stop';
+    blockId: string;
 } | {
     type: 'tool_start';
     id: string;
@@ -155,13 +495,21 @@ type SessionEvent = {
 } | {
     type: 'error';
     error: Error;
+    modelError?: ModelErrorInfo;
 };
 type ModelEvent = {
     type: 'text_delta';
     text: string;
+} | {
+    type: 'thinking_block_start';
+    blockId: string;
 } | {
     type: 'thinking_delta';
     thinking: string;
+    blockId?: string;
+} | {
+    type: 'thinking_block_stop';
+    blockId: string;
 } | {
     type: 'tool_call_start';
     id: string;
@@ -182,66 +530,608 @@ type ModelEvent = {
     usage?: Usage;
     ttftMs?: number;
     durationMs?: number;
+    finishReason?: string;
+    /** 完整且有序的最终内容；有此字段时增量只供展示，不重复装配或执行工具。 */
+    finalContent?: ContentBlock[];
+    refusal?: boolean;
 };
+/** 投影给模型的工具描述；由注册表条目转换而来，仅暴露名称、描述与参数 Schema。 */
 interface ToolDefinition {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
 }
+/** 协议无关的模型请求；messages 是 canonical 真源的克隆，wire 翻译只发生在 Provider 内。 */
 interface ModelRequest {
     systemPrompt?: string;
     messages: CanonicalMessage[];
     tools?: ToolDefinition[];
     signal?: AbortSignal;
+    /** 以下两项可选覆盖采样温度与单次输出上限；未设置时由适配器按协议与能力决定。 */
     temperature?: number;
     maxTokens?: number;
+    /** 宿主提供的本次运行来源；缺省时原生适配器不回传来源未知的私有状态。 */
+    context?: {
+        runId: string;
+        modelId?: string;
+    };
+}
+/** 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[];
+/**
+ * 一次缺失工具结果的补齐：result 为 OUTCOME_UNKNOWN 占位，只用于闭合历史事务。
+ * 持久化为 history_repair 记录后，恢复时叠加到原工具事务；不重放工具。
+ */
+interface HistoryRepair {
+    assistantId: string;
+    toolCallId: string;
+    result: ToolResultBlock;
 }
+/** normalizeHistory 的产物：合法请求视图、来源追踪与修复/丢弃审计。 */
+interface NormalizedHistory {
+    messages: CanonicalMessage[];
+    /** 与 messages 同序的原始消息 ID 集合；修复结果关联原始 assistant。 */
+    sources: string[][];
+    /** 已注入 messages 的缺失结果占位；结构与 history_repair 持久记录一致。 */
+    repairs: HistoryRepair[];
+    /** 被忽略的孤儿、迟到或重复工具结果提示；只诊断，不回写调用方输入。 */
+    diagnostics: string[];
+}
+/**
+ * 构造合法且独立的请求视图：只接受紧邻事务的结果，缺失结果标为未知；重复调用身份明确失败。
+ * 合并仅适用于纯文本的同角色消息，失败正文不重放，所有来源均可追踪。
+ */
+declare function normalizeHistory(input: readonly CanonicalMessage[]): NormalizedHistory;
+/** 以用户输入为界划分的一次交互及其终态；保护范围与摘要资格都以它为单位。 */
+interface InteractionBoundary {
+    interactionId: string;
+    /** completed 需显式终态或推断成功；failed 只来自显式终态，缺省 interrupted。 */
+    status: 'completed' | 'failed' | 'interrupted';
+    /** 该交互按历史顺序覆盖的原始消息 ID。 */
+    messageIds: string[];
+}
+/** 运行收尾时记录的交互终态；有 start 无 finish 的运行恢复后保持 interrupted。 */
+interface InteractionTerminal {
+    interactionId: string;
+    status: InteractionBoundary['status'];
+}
+/**
+ * 以显式终态为准恢复用户交互；旧历史仅在完整工具事务之后存在非空最终答复时推断成功。
+ * 保护最近成功交互及其后的所有交互，没有成功证据时保护全部历史。
+ */
+declare function indexInteractions(input: readonly CanonicalMessage[], terminals?: readonly InteractionTerminal[]): {
+    interactions: InteractionBoundary[];
+    protectedMessageIds: string[];
+};
 
 /**
- * Error Taxonomy for Kapibala Agent Harness
+ * 旧版单文件 JSONL MessageStore：每行一条消息，无版本化状态能力。
+ * 写入为同步追加，不做 fsync 或单写者保护；恢复时容错跳过损坏行并闭合悬挂事务。
  */
-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 JSONLMessageStore implements MessageStore {
+    readonly filePath: string;
+    constructor(filePath: string);
+    /** 校验协议内容后追加一行 JSON；不补身份、不查重、不 fsync。 */
+    append(message: CanonicalMessage): Promise<void>;
+    /** 读取全部消息；半截损坏行忽略，悬挂 tool_use 就地补 OUTCOME_UNKNOWN 结果。 */
+    load(): Promise<CanonicalMessage[]>;
+    /** 删除整个文件；文件不存在时静默成功。 */
+    clear(): Promise<void>;
+    /**
+     * 历史自愈(设计文档 §4.4)：逐条扫描 assistant 的 tool_use，
+     * 若其后的 tool 消息未完整覆盖这些 tool_use，就地补一条 is_error 的 tool_result。
+     *
+     * 之所以做**全历史扫描**而非只看末条：崩溃可能发生在任意一轮工具执行中途，
+     * 悬挂的 tool_use 未必位于历史末尾(例如中断后用户又继续提了问)。
+     * 只看末条会漏掉夹在中间的悬挂，下一次请求仍会因上下文非法而 400。
+     */
+    private healDanglingToolCalls;
 }
-declare class ModelError extends KapibalaError {
-    readonly status?: number;
-    readonly retryable: boolean;
-    constructor(message: string, options?: {
-        status?: number;
-        retryable?: boolean;
-    });
+
+/**
+ * 消息级持久化最小契约：user、assistant、tool 三类消息逐条经 append 落盘，
+ * load 恢复原始正文（而非模型请求投影），clear 实现 SDK 清空语义。
+ * 需要持久压缩、交互终态等能力的宿主另实现 StatefulMessageStore。
+ */
+interface MessageStore {
+    append(message: CanonicalMessage): Promise<void>;
+    load(): Promise<CanonicalMessage[]>;
+    clear(): Promise<void>;
 }
-declare class TransportError extends KapibalaError {
-    readonly retryable: boolean;
-    constructor(message: string, retryable?: boolean);
+
+/** 会话正文 schema 版本；读取时不匹配即拒绝恢复，不做跨版本猜测。 */
+declare const SESSION_SCHEMA_VERSION = 1;
+/** 会话记录类型：header 只出现一次，message 承载正文，其余为状态记录。 */
+type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import';
+/** 会话文件首条记录：身份与创建环境快照；conversationId 与文件名强绑定。 */
+interface SessionHeader {
+    conversationId: string;
+    projectRoot: string;
+    initialCwd: string;
+    createdAt?: number;
+    gitBranch?: string;
+    /** 旧历史导入的幂等身份；存在时同一来源只导入一次。 */
+    importIdentity?: string;
+}
+/** 单条 JSONL 记录封装；parentId 链接前驱，恢复时校验追加次序。 */
+interface SessionRecord {
+    schemaVersion: number;
+    type: SessionRecordType;
+    recordId: string;
+    timestamp: number;
+    parentId: string | null;
+    payload: Record<string, unknown>;
+}
+/** loadState 返回的版本化状态视图；记录自最近 reset 起有效。 */
+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 ToolError extends KapibalaError {
-    constructor(message: string);
+
+/** 基于目录独占创建的单写者锁；只有能确认死亡的进程才允许保守回收，不按年龄抢占。 */
+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;
 }
-declare class ToolNotFound extends KapibalaError {
-    readonly toolName: string;
-    readonly availableTools: string[];
-    constructor(toolName: string, availableTools?: string[]);
+
+/** 会话桶的项目身份：会话按工作树根隔离存储在项目桶目录下。 */
+interface ProjectIdentity {
+    /** 真实工作树根（非 Git 目录时为真实 cwd），作为会话归属与来源基准。 */
+    projectRoot: string;
+    /** 解析符号链接后的真实 cwd。 */
+    cwd: string;
+    /** 规范化根目录的 SHA-256，决定 ~/.kapibala/sessions 下的桶目录。 */
+    projectKey: string;
+    /** detached HEAD 或非 Git 目录时缺省。 */
+    gitBranch?: string;
+    /** true 表示 cwd 位于 Git 工作树内；同工作树子目录共用同一桶。 */
+    gitWorktree?: boolean;
+}
+/** 解析真实工作树根；同工作树子目录共用桶，非 Git 目录和不同 worktree 独立。不会改变 cwd。 */
+declare function resolveSessionProject(cwd: string): ProjectIdentity;
+/**
+ * 会话 sidecar 缓存元数据；可随时从正文重建，校验失败即丢弃，不是恢复依据。
+ * 正文 JSONL 始终是唯一真源。
+ */
+interface SessionMetadata {
+    schemaVersion: 1;
+    conversationId: string;
+    fileName: string;
+    projectRoot: string;
+    createdAt: number;
+    /** 最后一次正文、用户 run 或 reset 的时间；usage 与标题不影响排序。 */
+    lastActivityAt: number;
+    messageCount: number;
+    title: string;
+    /** 用户显式重命名的标题；存在时 reset 不再回退为默认标题。 */
+    customTitle?: string;
+    gitBranch?: string;
+    lastActivityGitBranch?: string;
+    lastModelId?: string;
+    /** 旧历史导入的幂等身份（来源路径 + 内容哈希）；重复导入据此跳过。 */
+    importIdentity?: string;
+    size: number;
+    mtimeMs: number;
+    /** 最后计入的记录 ID；与正文 stat 一同用于增量校验。 */
+    revision: string;
+}
+/** 打开的会话句柄：持有单写者锁与 Store，宿主用毕必须 release。 */
+interface ManagedSession {
+    conversationId: string;
+    store: SessionStore;
+    metadataPath: string;
+    /** 可丢弃缓存的只读快照；缺失时为 undefined，不代表正文丢失。 */
+    readonly metadata?: SessionMetadata;
+    header: SessionHeader;
+    /** 环境提示，不执行 checkout，也不把旧授权或模型配置带入当前运行。 */
+    branchDrift?: {
+        createdBranch?: string;
+        currentBranch?: string;
+    };
+    /** 释放单写者锁并移除句柄；宿主须先结束 AgentSession 的工具/摘要清理。 */
+    release(): Promise<void>;
+}
+/** SessionManager 配置；cwd 决定项目桶，homeDirectory 便于测试隔离。 */
+interface SessionManagerOptions {
+    cwd?: string;
+    homeDirectory?: string;
+    onDiagnostic?: (message: string) => void;
 }
-declare class AbortError extends KapibalaError {
-    constructor(message?: string);
+/** 将终端控制字符转成可见转义，并按 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;
 }
-declare class FatalError extends KapibalaError {
-    constructor(message: string);
+
+/** 对对象 key 确定性排序，保证摘要、工具 schema 与 fingerprint 不受插入顺序影响。 */
+declare function stableSerialize(value: unknown): string;
+
+/** 由生效窗口推导的请求预算；实际请求与只读展示必须共用同一份推导。 */
+interface ContextBudget {
+    contextWindow: number;
+    /** 窗口来自保守估算（未知按 32K 推导）时为 true。 */
+    estimatedWindow: boolean;
+    /** 输出预留（含私有推理消耗），同时作为实际请求的 maxTokens。 */
+    outputReserve: number;
+    /** 至少 128 的窗口安全余量，防止输入预算顶满窗口。 */
+    safetyReserve: number;
+    /** 输入预算 = 窗口 − 输出预留 − 安全余量；超限请求在 Provider 调用前失败。 */
+    inputBudget: number;
+    /** 触发阈值 0.85B：超过才启动一级剪裁/二级摘要（迁移文档：剪裁后低于触发阈值则不调用摘要模型）。 */
+    trigger: number;
+    /**
+     * 目标 0.65B：压缩后期望达到的占用水平，随 ContextSnapshot 暴露给 /context 展示。
+     * 当前算法的启停条件是 trigger；设计文档未定义向该目标迭代收敛的机制，
+     * 故不作为候选接受条件或强制收敛线使用。
+     */
+    target: number;
+}
+/** 单次请求的 token 占用分解；total 与各部分独立取整，不保证严格相加。 */
+interface TokenEstimate {
+    total: number;
+    system: number;
+    tools: number;
+    history: number;
+    overhead: number;
+    /** calibrated 表示该请求指纹已有实测校准；估算结果仍非计费依据。 */
+    source: 'estimated' | 'calibrated';
+}
+/** 可替换估算器；不得执行 Provider、Hook 或改写传入请求。 */
+interface TokenEstimator {
+    estimate(request: ModelRequest, modelFingerprint?: string): TokenEstimate;
+    observe?(request: ModelRequest, actualPromptTokens: number, modelFingerprint?: string): void;
 }
-declare class SessionBusyError extends KapibalaError {
-    constructor(operation: string);
+/**
+ * 计算一次有效输出预留及输入预算；输出上限须为正安全整数，缺省沿用 4096。
+ * 未知窗口以 32K 控制，输出最多占窗口 12.5%，另留至少 128 的 5% 安全余量。
+ * 输出预留包含思考/推理；不能把 Profile 的较低覆盖重新放大为默认值。
+ * @param window 模型声明的上下文窗口；缺省采用保守估算。
+ * @param maxOutputTokens 当前目的的输出上限，包含可见文字及私有推理消耗。
+ * @returns 实际请求与上下文展示共用的预算。
+ * @throws {ModelError} 输出上限不是正安全整数或窗口过小；错误纳入统一脱敏诊断通道。
+ */
+declare function createContextBudget(window?: ContextWindowValue, maxOutputTokens?: number): ContextBudget;
+/** 请求 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;
+    /** 最终请求指纹；observe 只对匹配指纹的请求回填实测 usage。 */
+    fingerprint: string;
+    budget: ContextBudget;
+    estimate: TokenEstimate;
+    /** 最近成功交互及其后全部交互的原始消息 ID；剪裁与摘要不得越过。 */
+    protectedMessageIds: string[];
+    /** 原始历史条数；与 projectedMessageCount 的差值来自摘要覆盖与压缩投影。 */
+    rawMessageCount: number;
+    projectedMessageCount: number;
+    /** 模型或请求配置变化后为 true，直到下一次准备成功。 */
+    stale: boolean;
+    /** 匹配指纹请求的实测 usage；缺失表示尚未观测，不按零推断。 */
+    actualPromptTokens?: number;
+    actualCachedPromptTokens?: number;
+    /** false 表示只读静态估算，尚未执行下一请求的动态 Hook。 */
+    dynamicKnown: boolean;
+    /** 当前检查点摘要消息的估算占用；无检查点为 0。 */
+    summaryTokens: number;
+    checkpointId?: string;
+    /** 累计被替换为占位描述的成功工具结果数。 */
+    prunedResults: number;
+    /** 已提交（含恢复自持久状态）的摘要检查点次数。 */
+    summaryCount: number;
+    /** 当前配置纪元内连续摘要失败次数；达到 3 次暂停自动摘要。 */
+    consecutiveFailures: number;
+    /** 熔断生效标志；阈值触发的压缩被暂停，手动压缩仍可重试。 */
+    automaticSummaryPaused: boolean;
+    /** disk 有版本化 Store 支撑；memory 只在内存，unsupported 禁用剪裁与摘要。 */
+    persistence: 'disk' | 'memory' | 'unsupported';
+}
+/** ContextManager 的宿主注入；除 conversationId 外均可缺省，缺省时按保守方式降级。 */
+interface ContextManagerOptions {
+    /** 提供状态能力时启用持久剪裁与摘要；旧 Store 降级为仅内存并给出诊断。 */
+    store?: MessageStore;
+    estimator?: TokenEstimator;
+    conversationId: string;
+    /** 存储降级、无效状态记录等非致命事件的脱敏诊断通道。 */
+    onDiagnostic?: (message: string) => void;
+    /** 摘要角色绑定来源；缺省时跳过二级摘要，仅保留一级剪裁。 */
+    router?: ModelRouter;
+    /** 转发给文件观察提取；项目根不作为历史工具相对路径的推断依据。 */
+    projectRoot?: string;
+    /** 当前已注册的内置工具名集合；剪裁白名单只认可其中的内置只读工具。 */
+    builtInToolNames?: () => ReadonlySet<string>;
+    /** 每个摘要 attempt 的使用量回调；在候选校验前触发，失败摘要仍计消耗。 */
+    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 之后统一预算；Profile 与请求的更低覆盖同时约束输出预留和实际 maxTokens。
+     * 非法输出配置或输入超限在 Provider 调用前失败；不使用固定 4096 覆盖原生模型上限。
+     * 签名或加密续答可禁止压缩；此时仍估算并拒绝超预算请求，不剪裁历史或调用摘要网络。
+     * @param allowCompaction 是否允许当前请求剪裁/摘要；冻结私有续答前缀时传 false。
+     * @returns 语义事件及准备完成的请求，不改变持久历史。
+     */
+    prepare(history: readonly CanonicalMessage[], request: ModelRequest, profile: ModelProfile, runId?: string, reason?: CompactionReason, allowCompaction?: boolean): AsyncGenerator<SessionEvent, ModelRequest>;
+    /** 观测真实使用量只作用于对应最终请求，不把累计 usage 当成当前窗口占用。 */
+    observe(request: ModelRequest, usage: Usage, profile: ModelProfile): void;
+    /** 查询已发布快照，不运行 Hook/Provider；配置变化后明确标记 stale。 */
+    getSnapshot(): ContextSnapshot | undefined;
+    /**
+     * 从当前静态投影估算，不执行 Hook/Provider 或更新状态；恢复后即可查看检查点。
+     * 输出预留与准备请求使用同一 Profile/请求覆盖规则；非法覆盖也在只读检查时失败。
+     */
+    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;
+}
+
+/** 摘要模型的 JSON 输出契约；只有通过 validateSummary 的实例可进入检查点。 */
+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;
+}
+/** 检查点携带的文件事实：按结果分类的观察列表，每类上限 500 条。 */
+interface FileDetails {
+    readFiles: FileObservation[];
+    modifiedFiles: FileObservation[];
+    failedFileOperations: FileObservation[];
+    /** 工具结果缺失或 OUTCOME_UNKNOWN 时的操作记录。 */
+    unknownFileOperations: FileObservation[];
+    /** 超出 500 上限被丢弃的观察总数；渲染时与列表截断数合并展示。 */
+    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;
+/** 摘要服务配置；router 提供摘要角色绑定，全部 attempt 共享总时限。 */
+interface SummaryServiceOptions {
+    router: ModelRouter;
+    /** 保留旧 API 形参；项目根不作为历史工具相对路径的推断依据。 */
+    projectRoot: string;
+    estimator?: TokenEstimator;
+    /** 真实使用量在候选校验前记账，失败摘要仍保留消耗；不得包含主任务 TTFT。 */
+    onUsage?: (attemptId: string, usage: Usage | undefined, modelId: string) => Promise<void>;
+    /** 单次 generate 的总时限，生效值不超过 120 秒；超时按摘要失败处理。 */
+    timeoutMs?: number;
+}
+/** 一次成功摘要的产出与计量；usage 为本次 generate 全部 attempt 的累计值。 */
+interface SummaryCandidate {
+    summary: ContextSummary;
+    details: FileDetails;
+    /** 实际发起的摘要模型调用次数；上限 4。 */
+    calls: number;
+    modelId: string;
+    durationMs: number;
+    usage: Usage;
+    /** 任一 attempt 缺失 usage 时为 false，不将缺失消耗伪装为零。 */
+    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 迭代。
+     * 摘要输出独立限制为 4096，并受 Profile 更低覆盖及窗口约束；非法 Profile 预算先失败。
+     */
+    generate(history: readonly CanonicalMessage[], previous?: Pick<SummaryCandidate, 'summary' | 'details'>, signal?: AbortSignal): Promise<SummaryCandidate>;
+}
+
+/** 事件严重度；debug / trace 仅在 StructuredLogger 显式开启 debug 时写入。 */
 type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/** 事件通道：operation 为运行日志，audit 为审批与操作审计；两者持久化保证与保留策略不同。 */
 type LogChannel = 'operation' | 'audit';
+/** 允许落盘的字段值类型；复杂结构必须先降维为标量或受控摘要。 */
 type LogField = string | number | boolean | null;
 /** 单条可持久化的脱敏运行或审计事件。 */
 interface LogEvent {
@@ -251,6 +1141,7 @@ interface LogEvent {
     channel: LogChannel;
     event: string;
     sessionId: string;
+    conversationId?: string;
     runId?: string;
     operationId?: string;
     toolUseId?: string;
@@ -260,10 +1151,12 @@ interface LogEvent {
 interface LogSink {
     write(event: LogEvent): Promise<void>;
 }
+/** 调用方提供的宽松输入；fields 仅白名单字段经脱敏校验后进入 LogEvent。 */
 interface LogInput {
     level: LogLevel;
     event: string;
     sessionId: string;
+    conversationId?: string;
     runId?: string;
     operationId?: string;
     toolUseId?: string;
@@ -315,11 +1208,17 @@ declare class StructuredLogger implements EventLogger {
     private format;
 }
 
+/** FileLogSink 的构造项；保留与落盘策略按通道强制，调用方传值不能放宽。 */
 interface FileLogSinkOptions {
+    /** 日志目录；不存在时按 0o700 创建。 */
     directory: string;
+    /** 通道前缀，同时决定文件名与保留、同步策略。 */
     prefix: 'operation' | 'audit';
+    /** 单文件字节上限，超出后换下一个序号文件；缺省 10MB。 */
     maxBytes?: number;
+    /** 按天保留的天数；仅 operation 通道生效，audit 恒为长期保留。 */
     retentionDays?: number;
+    /** 每条写入后强制 fsync；audit 通道强制开启。 */
     sync?: boolean;
 }
 /** 将每条 JSONL 事件完整追加到本地文件，并按日期及文件大小轮转。 */
@@ -333,7 +1232,9 @@ declare class FileLogSink implements LogSink {
     write(event: LogEvent): Promise<void>;
     /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
     getUsageBytes(): number;
+    /** 优先写入当天未满的最后一个序号文件，超限或无同名文件时开下一个序号。 */
     private chooseFile;
+    /** 按文件名中的日期删除早于保留期的自有文件；删除依据文件名而非文件 mtime。 */
     private cleanupExpired;
     private isOwnedFile;
 }
@@ -345,25 +1246,38 @@ declare function createDefaultLogSinks(baseDirectory?: string): {
 /** 启动时保守关闭上次进程未完成的审计事务，绝不将其当作未执行或自动重试。 */
 declare function recoverIncompleteAudit(directory: string): Promise<number>;
 
+/** 单个通过全部校验的指令文件；path 为去重后的候选路径，content 是严格 UTF-8 解码的全文。 */
 interface InstructionSource {
     path: string;
     content: string;
 }
+/** 一次成功加载的完整结果；sources 按「用户层 → 项目根 → 逐级子目录」顺序排列。 */
 interface InstructionSnapshot {
     sources: readonly InstructionSource[];
+    /** 全部来源实际字节数之和（以读取结果为准），供调用方审计体积预算。 */
     totalBytes: number;
 }
 interface InstructionLoadOptions {
+    /** 目录链上界；cwd 必须位于其内，越界直接失败而不是静默截断链。 */
     projectRoot: string;
+    /** 指令收集的终点目录；相对 projectRoot 的每一层都会尝试读取 AGENTS.md。 */
     cwd: string;
+    /** 用户层指令文件；缺省为 ~/.kapibala/AGENTS.md，与项目层同路径时去重。 */
     userFile?: string;
 }
-/** 按用户层和项目根至 cwd 的目录链读取指令，全部成功后才返回快照。 */
+/**
+ * 按用户层和项目根至 cwd 的目录链读取指令，全部成功后才返回快照。
+ * 所有路径统一用 native 语义解析（与 resolveSessionProject 的 projectRoot 对齐）：JS realpath
+ * 不展开 Windows 8.3 短名（CI 临时目录形如 RUNNER~1），混用会让包含性检查把同一目录误判越界、
+ * 让去重错过同一文件；返回的 source 路径因此是 canonical 形式，调用方按 canonical 比较。
+ */
 declare function loadInstructions(options: InstructionLoadOptions): InstructionSnapshot;
 
+/** 受支持的解释器家族；wsl 是 Windows 上的 WSL bash launcher，路径与输出语义与 native bash 不同。 */
 type ShellKind = 'bash' | 'wsl' | 'pwsh' | 'powershell';
 /** auto / 具名解释器，或用户显式提供的解释器可执行文件全路径。 */
 type ShellPreference = 'auto' | ShellKind | (string & {});
+/** 探测成功后固定的解释器身份；executableDigest 参与命令审批指纹，解释器被替换即失配。 */
 interface ShellEnvironment {
     kind: ShellKind;
     executable: string;
@@ -371,8 +1285,11 @@ interface ShellEnvironment {
     cwd: string;
 }
 interface ShellDetectOptions {
+    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
     preference?: ShellPreference;
+    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
     cwd: string;
+    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
     platform?: NodeJS.Platform;
     pathEnv?: string;
 }
@@ -390,57 +1307,81 @@ declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
 
 /** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
 type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
+/** 规则动作与裁决结果共用同一词表；ask 表示交人工审批，不是放行。 */
 type PermissionAction = 'allow' | 'ask' | 'deny';
+/** 一次 Shell 执行的精确目标；字段组合构成审批与缓存命中的身份，任何维度都不允许通配。 */
 interface ShellScope {
     command: string;
     interpreter: string;
     executablePath?: string;
     cwd: string;
+    /** 解释器身份摘要（路径、大小、mtime 推导）；解释器被替换后规则与缓存即失配。 */
     executableDigest?: string;
+    /** 命令直接引用的工作目录内脚本的内容摘要；仅单脚本命令可计算，组合命令缺省。 */
     scriptDigest?: string;
+    /** 执行前复核用指纹；审批后重新推导不一致时按目标漂移拒绝执行。 */
     executionFingerprint?: string;
 }
+/** 宿主提供的显式规则；tool / capability / shell 三种范围必须恰好声明一个。 */
 interface PermissionRule {
     action: PermissionAction;
     tool?: string;
     capability?: Capability;
     shell?: ShellScope;
 }
+/** 权限裁决的全部输入；硬限制与缓存命中由宿主查询后以标志位传入，策略本身不持有状态。 */
 interface PermissionRequest {
     mode: SessionMode;
     toolName: string;
     capabilities: readonly Capability[];
+    /** 危险性来自工具元数据；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask。 */
     dangerous?: boolean;
+    /** 宿主硬限制；命中即拒绝，优先级高于一切规则与缓存。 */
     hardDenied?: boolean;
     shell?: ShellScope;
+    /** 规则表须先经 validatePermissionRules 校验；同动作规则按声明顺序取首个命中。 */
     rules?: readonly PermissionRule[];
+    /** 会话缓存命中标志（来自 SessionApprovalCache）；仅在 deny / ask 规则都未命中时生效。 */
     cachedApproval?: boolean;
+    /** 会话缓存拒绝标志；在 deny 规则之后、ask 规则之前生效。 */
     cachedDenial?: boolean;
 }
+/** 裁决结果及其来源；source 供审计区分硬限制、Plan、规则、缓存与模式默认。 */
 interface PermissionDecision {
     decision: PermissionAction;
     source: 'hard_limit' | 'plan' | 'explicit_rule' | 'session_cache' | 'mode_default';
+    /** 命中规则在 rules 中的下标；仅 source 为 explicit_rule 时存在。 */
     ruleIndex?: number;
 }
 /** 拒绝含糊的 Shell 前缀/通配符和结构不完整的规则。 */
 declare function validatePermissionRules(rules: readonly PermissionRule[]): void;
 /** 纯策略裁决；宿主硬限制和 Plan 始终先于任何规则或会话缓存。 */
 declare class PermissionPolicy {
+    /**
+     * 裁决顺序固定：硬限制 → Plan 收窄 → deny 规则 → 会话缓存拒绝 → ask 规则 →
+     * 会话缓存允许 → allow 规则（run_command 必须带 shell 范围，工具级 allow 不能放行命令）
+     * → 模式默认。同一输入总是得到同一裁决，不读取任何外部状态。
+     */
     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 {
+    /** 注册来源标记（如 'builtin'）；注册表据此执行冲突策略并支持按源注销。 */
     source?: string;
+    /** 标记危险工具；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask 而非按模式默认放行。 */
     dangerous?: boolean;
     /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
     permissions?: Capability[];
     /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
     managesTimeout?: boolean;
 }
+/** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
 interface ToolContext {
+    /** 本次执行的沙箱根目录；文件类工具以此为界解析相对路径并拒绝越界。 */
     rootDir: string;
     signal?: AbortSignal;
     logger?: (message: string) => void;
@@ -451,29 +1392,41 @@ interface ToolContext {
         outputBytes: number;
     }) => void;
 }
+/** 工具契约；parameters 是 JSON Schema，模型只能看到经 toToolDefinition 投影后的三个字段。 */
 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>;
+/** 投影为模型可见的工具描述；刻意丢弃 metadata 与 approvalScope，执行侧信息不进入协议。 */
 declare function toToolDefinition(tool: Tool): ToolDefinition;
 
+/** run_command 的输入；cwd 相对工作区根解析，timeout_ms 合法区间 1..600000，越界在执行前失败。 */
 interface RunCommandInput {
     [key: string]: unknown;
     command: string;
     cwd?: string;
     timeout_ms?: number;
 }
+/** 命令执行结果；output 只是内联前缀，完整输出超过内联上限的部分落盘为受管结果文件。 */
 interface CommandResult {
+    /** 进程正常退出时的退出码；被信号终止时为 null。 */
     exitCode: number | null;
+    /** stdout 与 stderr 交错合并的文本，最多前 64 KiB（按 UTF-8 字符边界截断）。 */
     output: string;
+    /** output 并非全部输出的标志；超出内联上限的完整内容写入 outputFile。 */
     outputTruncated: boolean;
+    /** 受管结果文件路径（工作区内 .kapibala/tool-results/），仅输出超过内联上限时存在。 */
     outputFile?: string;
+    /** 结果文件触及 16 MiB 上限后被截断的标志。 */
     outputFileTruncated: boolean;
+    /** 两个流产生的原始字节总数（不受截断影响），供进度与审计使用。 */
     outputBytes: number;
     shell: ShellEnvironment['kind'];
 }
@@ -482,6 +1435,7 @@ declare function cleanupCommandResults(rootDir: string, now?: number): void;
 /** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
 declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
 
+/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
 interface SandboxConfig {
     rootDir: string;
     /**
@@ -490,6 +1444,10 @@ interface SandboxConfig {
      */
     allowSymlinks?: boolean;
 }
+/**
+ * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
+ * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
+ */
 declare class PathSandbox {
     readonly rootDir: string;
     readonly allowSymlinks: boolean;
@@ -519,6 +1477,11 @@ declare class PathSandbox {
     private toPhysicalPath;
 }
 
+/**
+ * 人工审批的五选一结果。allow_once / deny_once 只作用于本次执行；
+ * allow_session / deny_session 由执行器按精确调用范围写入会话缓存（allow_session 还要求请求允许会话级缓存）；
+ * cancel 表示放弃审批，一律拒绝且绝不进入缓存。
+ */
 type ApprovalChoice = 'allow_once' | 'allow_session' | 'deny_once' | 'deny_session' | 'cancel';
 /** 宿主展示实际执行目标并取得人工选择；无通道视为非交互拒绝。 */
 interface ApprovalRequest {
@@ -527,8 +1490,10 @@ interface ApprovalRequest {
     input: Record<string, unknown>;
     rootDir: string;
     shell?: ShellScope;
+    /** 宿主是否允许本次请求写入会话级允许缓存；deny_session 的缓存不受此限制。 */
     sessionAllowed: boolean;
 }
+/** 宿主实现的审批入口；未提供通道时执行器按非交互直接拒绝，通道抛错视同 cancel。 */
 interface ApprovalChannel {
     requestApproval(request: ApprovalRequest, signal?: AbortSignal): Promise<ApprovalChoice>;
 }
@@ -542,7 +1507,12 @@ declare class SessionApprovalCache {
     set(request: ApprovalRequest, choice: 'allow' | 'deny'): void;
 }
 
+/** 同名工具冲突策略：error 直接抛错；prefer-builtin 保留既有内置注册；prefer-last 后到者覆盖。 */
 type ConflictPolicy = 'error' | 'prefer-builtin' | 'prefer-last';
+/**
+ * 按名称索引的工具注册表。冲突按构造时给定的策略处理，胜出条目的来源标签保持不变；
+ * 来源标签支持按源批量注册与注销，注销只移除以该标签注册的工具，不回收冲突中保留的内置实现。
+ */
 declare class ToolRegistry {
     private readonly tools;
     private readonly toolSources;
@@ -556,6 +1526,7 @@ declare class ToolRegistry {
     registerSource(source: string, tools: Tool[]): void;
     unregisterSource(source: string): void;
     get(name: string): Tool | undefined;
+    /** 未命中时抛 ToolNotFound，并携带当前全部可用名称辅助模型自纠。 */
     resolve(name: string): Tool;
     list(): Tool[];
     definitions(): ToolDefinition[];
@@ -583,6 +1554,7 @@ declare const grepTool: Tool<{
     pattern: string;
     path?: string;
 }, string>;
+/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
 declare const builtinTools: (Tool<{
     path: string;
     startLine?: number;
@@ -602,11 +1574,22 @@ declare const builtinTools: (Tool<{
     path?: string;
 }, string>)[];
 
+/**
+ * 运行时钩子契约：宿主与插件在固定切点观察或调整流程。
+ * 通知型切点由 HookRegistry.emit 串行触发；需要返回值的 model:before / tool:before
+ * 由执行方（AgentLoop / ToolExecutor）自行遍历并消费返回值。
+ */
+/** 钩子切点；session:start / session:end 由会话初始化与销毁触发，其余在单次交互流程内触发。 */
 type HookPoint = 'session:start' | 'session:end' | 'model:before' | 'model:after' | 'tool:before' | 'tool:after' | 'error';
+/** 传给每个钩子的运行上下文；signal 与当前执行的取消联动，未提供表示该切点不可取消。 */
 interface HookContext {
     readonly signal?: AbortSignal;
     readonly logger?: (msg: string) => void;
 }
+/**
+ * tool:before 的裁决结果：continue 放行；skip 不执行工具，以 result 作为工具结果落盘；
+ * modify 用替换后的入参继续（仍会经过后续权限裁决，不构成绕过审批的通道）。
+ */
 type ToolDecision = {
     action: 'continue';
 } | {
@@ -617,10 +1600,12 @@ type ToolDecision = {
     action: 'modify';
     input: Record<string, unknown>;
 };
+/** 各切点的处理器签名；未注册的切点直接跳过，处理器抛出的异常向上传播。 */
 interface HookHandlers {
     'session:start'?: (ctx: HookContext) => void | Promise<void>;
     'session:end'?: (ctx: HookContext) => void | Promise<void>;
     'model:before'?: (ctx: HookContext, req: ModelRequest) => ModelRequest | Promise<ModelRequest>;
+    /** 收到的是即将进入历史的完整 assistant 消息；执行方会校验钩子未改动身份与受保护内容。 */
     'model:after'?: (ctx: HookContext, res: {
         message: CanonicalMessage;
     }) => void | Promise<void>;
@@ -640,30 +1625,44 @@ interface HookHandlers {
     error?: (ctx: HookContext, err: Error) => void | Promise<void>;
 }
 
+/** 按切点收集钩子的有序注册表；同一处理器可注册多次，触发时按注册顺序执行。 */
 declare class HookRegistry {
     private readonly hooks;
+    /** 注册到指定切点；不查重，触发顺序即注册顺序。 */
     on<K extends HookPoint>(point: K, handler: NonNullable<HookHandlers[K]>): void;
+    /** 返回该切点的处理器列表（无注册时为空数组）；数组为内部引用，调用方不应修改。 */
     get<K extends HookPoint>(point: K): Array<NonNullable<HookHandlers[K]>>;
+    /**
+     * 串行 await 通知型切点的全部处理器；任一抛错立即中断并向调用方传播。
+     * 需要返回值的 model:before / tool:before 不经 emit，由执行方自行遍历。
+     */
     emit<K extends 'session:start' | 'session:end' | 'model:after' | 'tool:after' | 'error'>(point: K, ctx: HookContext, ...args: any[]): Promise<void>;
 }
 
+/** setup 收到的能力入口；tools / hooks 是会话共享的注册表，注册的条目影响后续所有执行。 */
 interface PluginContext {
     readonly tools: ToolRegistry;
     readonly hooks: HookRegistry;
+    /** 本次会话的绝对工具根目录；工具的路径解析与审批都以此为基准。 */
     readonly rootDir: string;
     readonly logger?: (msg: string) => void;
 }
+/** 插件生命周期：setup 在会话空闲时挂载执行一次，teardown 在会话销毁时逐个调用以回收资源。 */
 interface AgentPlugin {
+    /** 用于挂载失败与 teardown 的诊断信息。 */
     readonly name: string;
     readonly version?: string;
     setup(ctx: PluginContext): void | Promise<void>;
     teardown?(): void | Promise<void>;
 }
 
+/** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
 interface ExecutorOptions {
     tools: ToolRegistry;
     hooks: HookRegistry;
+    /** 工具执行的绝对根目录；路径解析与审批均以此为基准。 */
     rootDir: string;
+    /** 会话级取消信号；与 cancel() 的内部信号合并生效。 */
     signal?: AbortSignal;
     logger?: (msg: string) => void;
     /** 单次工具执行超时(毫秒)。异步挂起的工具超时后返回 isError 结果，避免永久卡死会话循环 */
@@ -671,11 +1670,19 @@ interface ExecutorOptions {
     eventLogger?: EventLogger;
     sessionId?: string;
     runId?: string;
+    /** 固定模式或每次裁决时读取的取值函数；宿主可中途切换。 */
     mode?: SessionMode | (() => SessionMode);
     permissionRules?: readonly PermissionRule[];
+    /** 审批入口；缺省视为非交互环境，需要询问的调用一律拒绝。 */
     approvalChannel?: ApprovalChannel;
+    /** 会话内 allow_session / deny_session 审批缓存；缺省使用实例私有缓存。 */
     approvalCache?: SessionApprovalCache;
 }
+/**
+ * 工具执行器：按「审计 → 钩子裁决 → 权限裁决 → 执行 → 结果闭合」处理单次调用。
+ * 所有拒绝与异常都闭合为 isError 的工具结果，不向调用方抛出；
+ * 同一 run 内参数完全相同的 never 失败会被拒绝重复执行。
+ */
 declare class ToolExecutor {
     private readonly tools;
     private readonly hooks;
@@ -696,13 +1703,17 @@ declare class ToolExecutor {
     constructor(options: ExecutorOptions);
     /** 中止本轮正在等待或执行的工具；调用方仍须等待 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;
@@ -720,104 +1731,158 @@ 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[];
-}
-
+/** Chat 端点配置；能力覆盖只改变请求字段和完成边界，不改变协议身份。 */
 interface OpenAIProviderOptions {
     baseURL: string;
     apiKey: string;
     modelName: string;
     supportsThinking?: boolean;
+    /** 回传 assistant 思考历史；默认仅为 DeepSeek 官方端点启用，自建兼容网关可显式开启。 */
+    replayReasoningContent?: boolean;
+    /** 显式端点能力；缺省保留 max_tokens、usage 和 temperature 请求基线，要求 DONE。 */
+    chatCapabilities?: ChatCapabilities;
     /** 建立 HTTP 连接(收到响应头)的超时毫秒数；仅约束建连阶段，不限制流式读取总时长 */
     connectTimeoutMs?: number;
 }
+/** 将 canonical 历史投影为 Chat 请求，在完整终态和全部工具验证后交付可执行结果。 */
 declare class OpenAICompatibleProvider implements ModelProvider {
     readonly name = "openai-compatible";
     readonly baseURL: string;
     readonly apiKey: string;
+    /** 未提供凭据时由 Session 在记录用户消息前拒绝请求。 */
+    get credentialsReady(): boolean;
     readonly modelName: string;
     readonly supportsThinking: boolean;
+    readonly replayReasoningContent: boolean;
     readonly connectTimeoutMs: number;
+    readonly chatCapabilities: Readonly<ChatCapabilities>;
+    /** 暴露实际请求目标供原子绑定校验，不包含凭据。 */
+    get binding(): {
+        protocol: "openai-compatible";
+        baseURL: string;
+        modelName: string;
+    };
+    /**
+     * 初始化 Chat 协议适配；显式端点能力优先，思考回传独立于模型 supportsThinking 标签。
+     * @param options 请求目标、凭据和能力配置；缺省只有 DeepSeek 官方端点回传可见思考。
+     */
     constructor(options: OpenAIProviderOptions);
+    /**
+     * 发送 Chat 流式请求；默认同时要求合法 finish_reason 和 DONE，只有显式例外允许完整 EOF。
+     * 全部工具的 ID、名称和对象参数在任何完成事件之前校验；截断、过滤或中断不交付工具。
+     * @param req canonical 历史、工具、预算与取消信号；能力覆盖来自端点配置。
+     * @returns 文本、可见思考和工具增量，完整响应最后产生 message_stop。
+     * @throws ModelError 响应缺少合法终态、工具身份或完整对象参数时失败，不自动重放请求。
+     */
     create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /**
+     * 将工具结果装配为 canonical tool 消息，wire 角色仅在下一请求投影时转换。
+     * @param results 已完成的工具结果，保持调用 ID 与内容，不重放工具。
+     * @returns 逐条克隆的 canonical tool 消息，允许消息级落盘。
+     */
     assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+    /**
+     * 将历史投影为 Chat 消息；合并连续 user，剔除空 assistant，保持工具调用与结果身份。
+     * 仅显式允许的端点回传可见思考；签名、脱敏思考和原生私有 Item 不适用于 Chat。
+     * @param messages canonical 历史；只投影文本、可选可见思考和工具语义。
+     * @param systemPrompt 可选全局提示词，去除首尾空白后作为首条 system。
+     * @returns 与输入历史独立的 Chat wire 消息数组。
+     */
     private translateMessagesToWire;
 }
 
-declare class JSONLMessageStore implements MessageStore {
-    readonly filePath: string;
-    constructor(filePath: string);
-    append(message: CanonicalMessage): Promise<void>;
-    load(): Promise<CanonicalMessage[]>;
-    clear(): Promise<void>;
+/** Messages 原生连接配置；baseURL 包含版本前缀，workspaceId 仅选择请求工作区。 */
+interface AnthropicProviderOptions {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    connectTimeoutMs?: number;
+    workspaceId?: string;
+}
+/** 独立 Messages 适配器；复用 canonical 工具事务及来源校验，不拥有工具执行权限。 */
+declare class AnthropicProvider implements ModelProvider {
+    readonly name = "anthropic";
+    readonly baseURL: string;
+    readonly modelName: string;
+    readonly workspaceId?: string;
+    readonly connectTimeoutMs: number;
+    private readonly apiKey;
+    /** 表明该适配器已装载非空凭据，不暴露凭据内容。 */
+    get credentialsReady(): boolean;
+    /** 暴露不含凭据的请求目标；用于宿主校验 Profile 与 Provider 的原子绑定。 */
+    get binding(): {
+        protocol: "anthropic";
+        baseURL: string;
+        modelName: string;
+        workspaceId: string | undefined;
+    };
+    /** 初始化连接；无效 URL/凭据/超时在请求前失败，错误不回显配置值。 */
+    constructor(options: AnthropicProviderOptions);
+    /** 装配统一 tool 历史；Messages 的 user/tool_result 转换只作用于请求视图。 */
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
     /**
-     * 历史自愈(设计文档 §4.4)：逐条扫描 assistant 的 tool_use，
-     * 若其后的 tool 消息未完整覆盖这些 tool_use，就地补一条 is_error 的 tool_result。
-     *
-     * 之所以做**全历史扫描**而非只看末条：崩溃可能发生在任意一轮工具执行中途，
-     * 悬挂的 tool_use 未必位于历史末尾(例如中断后用户又继续提了问)。
-     * 只看末条会漏掉夹在中间的悬挂，下一次请求仍会因上下文非法而 400。
+     * 发送 Messages 流并按索引组装完整内容；增量仅供展示，终态提供有序落盘来源。
+     * maxTokens 包含思考消耗，缺省为 4096；缺终态、坏参数与服务端流错误均抛错。
+     * pause_turn 表示服务端工具暂停；当前不支持其续答，明确失败而非报告完成或调度客户端工具。
+     * 同 run/模型/端点的来源校验允许私有续答；来源不匹配的可见思考降为普通文字。
+     * 取消或消费者提前结束会等待 reader 清理并解除 HTTP 取消监听，不自动重发请求。
      */
-    private healDanglingToolCalls;
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /**
+     * 投影 system、普通内容与工具结果；连续结果合并为下一 user 内容并置于文字之前。
+     * 私有块由共享来源规则筛选，原始消息和工具 ID 不被改写；不发送能力标签推测的思考参数。
+     */
+    private createPayload;
 }
 
-interface MessageStore {
-    append(message: CanonicalMessage): Promise<void>;
-    load(): Promise<CanonicalMessage[]>;
-    clear(): Promise<void>;
+/** 原生 Responses 的端点、模型及建连配置；输出预算由每次请求指定。 */
+interface OpenAIResponsesProviderOptions {
+    baseURL: string;
+    apiKey: string;
+    modelName: string;
+    supportsThinking?: boolean;
+    connectTimeoutMs?: number;
+}
+/** 原生 Responses 适配器拥有手动无状态历史，完成边界与 Agent 的 canonical 工具事务一致。 */
+declare class OpenAIResponsesProvider implements ModelProvider {
+    readonly name = "openai-responses";
+    readonly binding: {
+        protocol: 'openai-responses';
+        modelName: string;
+        baseURL: string;
+    };
+    private readonly options;
+    /** 表明该适配器已装载非空凭据，不暴露凭据内容。 */
+    get credentialsReady(): boolean;
+    /** 绑定明确模型与端点；不从模型名推断协议，也不在失败后自动切换协议。非法配置在请求前失败。 */
+    constructor(options: OpenAIResponsesProviderOptions);
+    /** 消费完整 Responses 流，增量仅用于展示；终态与全部 Item 合法后才交付工具完成和最终内容。 */
+    create(request: ModelRequest): AsyncIterable<ModelEvent>;
+    /** 保持消息级 canonical tool 落盘，Responses function_call_output 仅存在于请求投影。 */
+    assembleToolResults(results: ToolResultBlock[]): CanonicalMessage[];
+    /** 服务端错误仅保留明确标识，不回显请求、输出正文、签名或加密 reasoning。 */
+    private throwWireError;
+    /** 只接受真实且合法的计数；缺失 usage 保持未知，推理 token 已包含在 output_tokens 中。 */
+    private toUsage;
 }
 
 interface PromptAssemblerOptions {
+    /** 提供时才生成 L2 工具清单段；缺省表示本次运行不向模型展示任何工具。 */
     tools?: ToolRegistry;
+    /** L3 环境段展示的工作区根目录；文件工具的沙箱边界与其保持一致。 */
     rootDir: string;
     agentName?: string;
+    /** 宿主自定义提示词，插在环境段与 L4 指令之间；纯空白视为未提供。 */
     customInstructions?: string;
+    /** L4 项目指令段的内容，来自 loadInstructions 快照；为空时整段省略。 */
     instructionSources?: readonly InstructionSource[];
+    /** 覆盖 tools.list() 作为 L2 清单来源；通常传入按权限过滤后的可见工具。 */
     visibleTools?: readonly Tool[];
 }
+/**
+ * 把行为规则（L1）、工具清单（L2）、环境（L3）与项目指令（L4）拼装为系统提示词。
+ * 各段之间以 `\n\n---\n\n` 分隔；不提供的内容整段跳过，不做占位填充。
+ */
 declare class PromptAssembler {
     private readonly tools?;
     private readonly rootDir;
@@ -826,6 +1891,7 @@ declare class PromptAssembler {
     private readonly instructionSources;
     private readonly visibleTools?;
     constructor(options: PromptAssemblerOptions);
+    /** 按固定层级拼装系统提示词；同一选项集总是产出相同文本，便于审计与缓存。 */
     assemble(): string;
     private getL1Behavior;
     private getL2Tools;
@@ -833,21 +1899,46 @@ declare class PromptAssembler {
 }
 
 interface AgentLoopOptions {
+    /** 本次交互身份，内部步骤仍独立编号。 */
+    interactionId?: string;
+    /** 仅用于诊断、用量归因与脱敏说明，不参与请求构造。 */
+    modelId?: string;
+    modelRole?: PrimaryModelRole;
+    /** 请求视图投影：只允许变换克隆出的请求消息，不得改动真实历史。 */
+    projectHistory?: (history: readonly CanonicalMessage[]) => CanonicalMessage[];
+    /** 请求准备契约；可在请求前产出事件，并在上下文溢出时参与一次预算重试。 */
+    prepareRequest?: RequestPreparation;
+    /** 每次收到 usage 后回调；attemptId 标识 run:step:attempt，便于按尝试归因。 */
+    onUsage?: (request: ModelRequest, usage: Usage, attemptId: string) => Promise<void>;
     provider: ModelProvider;
     executor: ToolExecutor;
     tools: ToolRegistry;
     hooks: HookRegistry;
     systemPrompt?: string;
+    /** 单次 run 的最大 turn 数，耗尽时以 error 事件收尾；缺省 20。 */
     maxSteps?: number;
+    /** 连续工具失败达到该阈值即熔断终止本轮 run；缺省 3。 */
     maxConsecutiveErrors?: number;
     signal?: AbortSignal;
     eventLogger?: EventLogger;
     sessionId?: string;
     runId?: string;
+    /** 每轮开始时读取；工具可见性与权限模式可随宿主状态变化。 */
     getMode?: () => SessionMode;
     permissionRules?: readonly PermissionRule[];
 }
+/**
+ * 主执行循环：按 turn 推进「模型请求 → 整批校验 → 工具调度 → 历史闭合」。
+ * run 会就地追加传入的 history，assistant 与全部 tool_result 在同一同步临界段落入，
+ * 消费方在任何对外事件后停止迭代都不会看到半闭合历史（设计文档 §4.3 / §4.4）。
+ */
 declare class AgentLoop {
+    private readonly interactionId?;
+    private readonly modelId?;
+    private readonly modelRole?;
+    private readonly projectHistory?;
+    private readonly prepareRequest?;
+    private readonly onUsage?;
     private readonly provider;
     private readonly executor;
     private readonly tools;
@@ -862,39 +1953,86 @@ declare class AgentLoop {
     private readonly getMode;
     private readonly permissionRules;
     constructor(options: AgentLoopOptions);
+    /**
+     * 执行一次交互并流式产出事件。
+     *
+     * 语义要点：
+     * - message_stop 携带完整 canonical 消息，是唯一落盘来源；text / thinking 增量仅供展示。
+     * - 模型失败以 error + turn_finish 事件收尾并结束 run（不抛出）；用户中止抛 AbortError。
+     * - turn_start / turn_finish 严格配对，错误、熔断与步数耗尽路径均保证收口。
+     */
     run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
 }
 
+/** AgentSession 的构造配置；除主任务绑定外均可缺省，缺省行为见各字段。 */
 interface SessionConfig {
+    /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
+    conversationId?: string;
+    tokenEstimator?: TokenEstimator;
+    /** 无 Git 工作树时随 run_started 记录的分支回退值。 */
+    gitBranch?: string;
+    /** 主任务默认模型绑定；恢复历史及未显式选择角色时使用。 */
     defaultProfile: ModelProfile;
+    /** 与 defaultProfile 匹配的协议适配器。 */
     defaultProvider: ModelProvider;
+    /** 消息级落盘通道；支持状态能力的 Store 额外启用持久压缩与交互终态。 */
     store?: MessageStore;
+    /** 工具执行与会话基目录；projectRoot/cwd 缺省沿用此值。 */
     rootDir?: string;
     systemPrompt?: string;
     maxSteps?: number;
     logger?: (msg: string) => void;
     eventLogger?: EventLogger;
     loggingDirectory?: string;
+    /** 初始权限模式，缺省 Approval；仅空闲时可切换。 */
     mode?: SessionMode;
     permissionRules?: readonly PermissionRule[];
     approvalChannel?: ApprovalChannel;
     projectRoot?: string;
     cwd?: string;
     userInstructionsPath?: string;
+    /** 未提供时使用默认日志 sink 的审计目录；init 时恢复不完整审计。 */
     auditRecoveryDirectory?: string;
     /** 接收普通运行日志失败的脱敏诊断；诊断失败也不得中断问答或替代审计。 */
     onDiagnostic?: (message: string) => void;
 }
+/** getStats 返回的统计快照；全部字段为独立副本，宿主修改不影响会话内部状态。 */
 interface SessionStats {
+    conversationId?: string;
+    /** 历史存在无 usage 的模型步骤时为 false，不将旧消耗伪装为精确零。 */
+    usageKnown?: boolean;
+    /** 摘要 attempt 的累计消耗；独立于主任务指标。 */
+    summaryUsage?: Usage;
+    summaryUsageKnown?: boolean;
+    contextSnapshot?: ContextSnapshot;
+    /** 累计用户任务次数，含恢复自持久状态的 run_started 记录。 */
     totalTurns: number;
+    /** 主任务累计消耗；摘要消耗在 summaryUsage 单独统计。 */
     totalTokens: Usage;
     activeModel: string;
     loadedToolsCount: number;
     lastMetrics?: TurnMetrics;
     lastRunMetrics?: RunMetrics;
+    /** 最近一次内部模型请求的窗口占用；无实测时仅提供窗口上限。 */
     contextUsage: ContextUsage;
 }
+/**
+ * 宿主无关的 Agent 会话门面：统一模型路由、工具执行、权限与上下文压缩。
+ * 每次用户输入产生一个 run；历史与状态经 MessageStore 持久化，恢复后语义连续。
+ * 运行或清理进行中，改变状态的公开方法一律被拒绝；Core 不承担任何界面职责。
+ */
 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;
@@ -920,23 +2058,60 @@ declare class AgentSession {
     private lastMetrics?;
     private lastRunMetrics?;
     private initialized;
+    private pendingResume;
     private destroyed;
+    private cleanupStarted;
+    private cleanupPromise?;
+    private sessionEndFinished;
     private activeRun;
+    private primaryRole;
+    private lastPrimaryProfile?;
+    private lastPrimaryProvider?;
     private readonly plugins;
     constructor(config: SessionConfig);
+    /** 幂等初始化：恢复审计残留、指令快照与持久历史，校验会话身份并回放 usage。 */
     init(): Promise<void>;
+    /** 挂载插件并执行 setup；销毁后或运行中拒绝，setup 失败的插件不进入已装列表。 */
     use(plugin: AgentPlugin): Promise<void>;
+    /**
+     * 空闲时原子替换角色的模型绑定；本方法不改变当前角色或工具权限。
+     * @param profile 模型协议、请求目标和输出预算。
+     * @param role 被配置的主任务或摘要角色。
+     * @param provider 与目标匹配的适配器；省略时只允许复用相同目标。
+     * @throws {ModelError} 协议、模型、端点或 workspace 与适配器错配，旧绑定保留。
+     * @throws {SessionBusyError} 正在执行或清理当前任务。
+     */
     switchModel(profile: ModelProfile, role?: ModelRole, provider?: ModelProvider): void;
+    /** 查询指定绑定或当前明确选择的主任务模型，返回独立配置副本。 */
     getActiveProfile(role?: ModelRole): ModelProfile;
+    /** 空闲时显式选择场景；缺少映射或凭据时拒绝，不回退默认模型、不修改权限。 */
+    selectModelRole(role: PrimaryModelRole): void;
+    /** 返回本进程明确选择的场景，历史恢复不改变此状态。 */
+    getModelRole(): PrimaryModelRole;
+    /** 严格解析主任务快照，在输入落盘与网络调用之前检查角色、凭据与预算。 */
+    private resolvePrimaryBinding;
     /** 只在空闲时切换本次会话模式；宿主负责 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;
+    /** 空闲时清空存储与全部内存状态；conversationId 不变，恢复语义等同全新会话。 */
     reset(): Promise<void>;
     /**
      * 执行一次用户输入，并以宿主无关的语义事件流返回全过程。
@@ -945,24 +2120,48 @@ declare class AgentSession {
      * {@link SessionEvent}，分别完成展示、交互和中止控制。
      *
      * @param userInput 用户本轮输入。
-     * @param options 可选的中止信号。
+     * @param options 可选中止信号与显式主任务角色；角色在整个工具任务内固定。
      * @returns 文本、思考、工具、指标和错误等结构化事件的异步流。
      * @throws {SessionBusyError} 当前会话已有正在执行的 run 时抛出。
+     * @throws {ModelError} 显式角色缺少绑定或凭据时，在输入落盘和网络调用前抛出。
      */
     run(userInput: string, options?: {
         signal?: AbortSignal;
+        role?: PrimaryModelRole;
     }): AsyncIterable<SessionEvent>;
+    /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
+    private runOperation;
+    /** 幂等销毁：卸载插件后发出 session:end；运行中拒绝，teardown 失败聚合抛出且不完成销毁。 */
     destroy(): Promise<void>;
     private assertIdle;
     /**
-     * 计算最近一次内部模型请求的上下文占用。
+     * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
      * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
      */
     private createContextUsage;
     private persistAssistant;
+    /** 创建上下文协调器并注入当前路由；摘要不经过主任务 Loop，插件结果不默认为可剪裁。 */
+    private createContextManager;
+    /** 摘要实际消耗按 attempt 身份独立累加；缺失消耗保留未知，不计入主任务指标。 */
+    private accountSummaryUsage;
+    /**
+     * 空闲时手动摘要旧完整前缀，不创建用户任务、不执行工具，不突破当前与最近成功交互。
+     * 迭代结束或取消后等候摘要与提交收口，再释放执行状态；已提交检查点保持有效。
+     */
+    compact(options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SessionEvent>;
+    /** 手动压缩按主任务协议投影旧历史，不复用旧 run 私有状态；原始历史与落盘内容保持不变。 */
+    private compactOperation;
+    /** 压缩与预算超限事件写入操作日志并携带 runId；其他事件不落日志。 */
+    private logContextEvent;
+    /** 以模型 attempt 身份幂等累加真实消耗；非法或缺失 usage 保持未知。 */
+    private accountUsage;
     private persistToolMessages;
+    /** 中止时为缓冲 assistant 的每个 tool_use 生成 OUTCOME_UNKNOWN 结果并入历史，保持事务闭合。 */
     private closeInterruptedToolCalls;
+    /** 收集历史中紧跟该 assistant 的连续 tool 消息；仅当覆盖全部 tool_use 时视为已闭合。 */
     private findClosedToolMessages;
 }
 
-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 ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, FileLogSink, type FileLogSinkOptions, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type MessageRole, type MessageStore, ModelError, type ModelEvent, type ModelProfile, type ModelProvider, type ModelRequest, type ModelRole, type ModelRouter, OpenAICompatibleProvider, type OpenAIProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginContext, PromptAssembler, type PromptAssemblerOptions, type RedactedThinkingBlock, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionMode, type SessionStats, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type StepLogEntry, type StepLogStage, StructuredLogger, 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, classifyBashOutput, cleanupCommandResults, commandAuditSummary, createDefaultLogSinks, createLogId, createRunCommandTool, defineTool, detectShell, editFileTool, executionFingerprint, globTool, grepTool, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, loadInstructions, projectSafeFields, readFileTool, recoverIncompleteAudit, resolveContextWindow, stableJsonStringify, toToolDefinition, validatePermissionRules, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type ChatCapabilities, 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 ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginContext, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, 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, assembleCanonicalToolResults, 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, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };