@kiturone/kapibala 0.0.3 → 0.0.4

package/dist/index.d.cts

@@ -1,7 +1,106 @@
+/** 内置适配器的实际请求目标；用于拒绝模型、协议或端点错配的绑定。 */
+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;
@@ -22,6 +121,8 @@ interface ModelErrorInfo {
     transportCode?: string;
     stage?: ModelErrorOptions['stage'];
     operation?: 'primary' | 'summary';
+    /** type-only 引用协议层角色类型；运行时无循环依赖。 */
+    modelRole?: PrimaryModelRole;
     modelId?: string;
     provider?: string;
     retryPolicy: KapibalaError['retryPolicy'];
@@ -30,7 +131,8 @@ interface ModelErrorInfo {
 /** 清理服务端报错中的终端控制符、常见凭据及带凭据的 URL，限制长度；不展示完整响应或请求头。 */
 declare function sanitizeModelErrorMessage(value: string): string;
 /** 生成统一脱敏说明；上下文补充调用场景，不携带原始异常、请求正文或密钥。 */
-declare function describeModelError(error: ModelError, context?: Pick<ModelErrorInfo, 'modelId' | 'provider' | 'operation'>): ModelErrorInfo;
+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';
@@ -41,8 +143,10 @@ declare class KapibalaError extends Error {
         safeMessage?: string;
     });
 }
+/** 模型调用失败；message 已脱敏，对外诊断统一经 describeModelError 产出，retryPolicy 仅为处理建议。 */
 declare class ModelError extends KapibalaError {
     readonly status?: number;
+    /** 属于可退避重试的瞬态类别（限流/服务/超时/网络）；不等于自动重试授权。 */
     readonly retryable: boolean;
     /** 可选的受控底层连接错误码，不包含原始传输异常文本。 */
     readonly transportCode?: string;
@@ -60,24 +164,30 @@ declare class ContextOverflowError extends ModelError {
         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);
 }
@@ -96,10 +206,47 @@ declare class ContextStorageError extends KapibalaError {
  * 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 {
     /** 工具执行语义来源；新运行记录，旧历史可缺省。未知插件不按内置只读工具剪裁。 */
@@ -110,6 +257,8 @@ interface ToolUseBlock {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    /** 源 wire Item 元数据；内容被改写后由调用方清除，不作为业务身份。 */
+    protocolMeta?: ProtocolItemMetadata;
 }
 interface ToolResultBlock {
     type: 'tool_result';
@@ -126,12 +275,17 @@ 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;
@@ -139,7 +293,12 @@ interface Usage {
     /** Provider 明确提供的缓存命中输入量；缺失表示未知，不能按零推断。 */
     cachedPromptTokens?: number;
 }
+/** canonical 消息角色；'tool' 仅用于工具结果消息，wire 角色转换只发生在请求投影阶段。 */
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/**
+ * 协议无关的历史真源；wire 格式只在请求投影时出现。
+ * 不变量：assistant 消息中的 tool_use 进入历史后，对应 tool_result 消息必须紧跟其后。
+ */
 interface CanonicalMessage {
     /** 派生背景锚点独立于真实用户输入，避免合并后丢失受保护原消息的来源身份。 */
     contextSummary?: {
@@ -155,10 +314,15 @@ interface CanonicalMessage {
     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;
@@ -172,6 +336,7 @@ interface TurnMetrics {
     totalTokens: number;
     toolCallsCount: number;
 }
+/** 一次完整 run 的累计指标；token 数为各轮请求之和，上下文占用单独见 contextUsage。 */
 interface RunMetrics {
     startTime: number;
     endTime: number;
@@ -190,6 +355,7 @@ interface RunMetrics {
     /** 最近一次内部模型请求占用的上下文；不使用 run 累计 promptTokens。 */
     contextUsage?: ContextUsage;
 }
+/** 供宿主展示的上下文占用快照；估算值不能用于计费或精确预算。 */
 interface ContextUsage {
     usedTokens?: number;
     /** true 表示未收到当前请求 usage，输入占用使用预算估算，不能用于计费。 */
@@ -198,7 +364,9 @@ interface ContextUsage {
     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;
@@ -273,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;
@@ -325,9 +500,16 @@ type SessionEvent = {
 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;
@@ -349,19 +531,30 @@ type ModelEvent = {
     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>;
@@ -371,16 +564,23 @@ 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[];
 }
 /**
@@ -388,11 +588,15 @@ interface NormalizedHistory {
  * 合并仅适用于纯文本的同角色消息，失败正文不重放，所有来源均可追踪。
  */
 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'];
@@ -406,11 +610,18 @@ declare function indexInteractions(input: readonly CanonicalMessage[], terminals
     protectedMessageIds: string[];
 };
 
+/**
+ * 旧版单文件 JSONL MessageStore：每行一条消息，无版本化状态能力。
+ * 写入为同步追加，不做 fsync 或单写者保护；恢复时容错跳过损坏行并闭合悬挂事务。
+ */
 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，
@@ -423,22 +634,32 @@ declare class JSONLMessageStore implements MessageStore {
     private healDanglingToolCalls;
 }
 
+/**
+ * 消息级持久化最小契约：user、assistant、tool 三类消息逐条经 append 落盘，
+ * load 恢复原始正文（而非模型请求投影），clear 实现 SDK 清空语义。
+ * 需要持久压缩、交互终态等能力的宿主另实现 StatefulMessageStore。
+ */
 interface MessageStore {
     append(message: CanonicalMessage): Promise<void>;
     load(): Promise<CanonicalMessage[]>;
     clear(): Promise<void>;
 }
 
+/** 会话正文 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;
@@ -447,6 +668,7 @@ interface SessionRecord {
     parentId: string | null;
     payload: Record<string, unknown>;
 }
+/** loadState 返回的版本化状态视图；记录自最近 reset 起有效。 */
 interface SessionState {
     header: SessionHeader;
     /** 最近 reset 之后的记录；包含正文及状态，不包含头部。 */
@@ -527,33 +749,48 @@ declare class SessionLock {
     private static isDead;
 }
 
+/** 会话桶的项目身份：会话按工作树根隔离存储在项目桶目录下。 */
 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;
@@ -566,8 +803,10 @@ interface ManagedSession {
         createdBranch?: string;
         currentBranch?: string;
     };
+    /** 释放单写者锁并移除句柄；宿主须先结束 AgentSession 的工具/摘要清理。 */
     release(): Promise<void>;
 }
+/** SessionManager 配置；cwd 决定项目桶，homeDirectory 便于测试隔离。 */
 interface SessionManagerOptions {
     cwd?: string;
     homeDirectory?: string;
@@ -623,57 +862,19 @@ declare class SessionManager {
     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;
-}
+/** 对对象 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;
@@ -684,12 +885,14 @@ interface ContextBudget {
      */
     target: number;
 }
+/** 单次请求的 token 占用分解；total 与各部分独立取整，不保证严格相加。 */
 interface TokenEstimate {
     total: number;
     system: number;
     tools: number;
     history: number;
     overhead: number;
+    /** calibrated 表示该请求指纹已有实测校准；估算结果仍非计费依据。 */
     source: 'estimated' | 'calibrated';
 }
 /** 可替换估算器；不得执行 Provider、Hook 或改写传入请求。 */
@@ -697,10 +900,16 @@ 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;
+/**
+ * 计算一次有效输出预留及输入预算；输出上限须为正安全整数，缺省沿用 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;
 /**
@@ -716,36 +925,58 @@ declare class UnicodeTokenEstimator implements TokenEstimator {
 }
 
 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 或任何终端操作。 */
@@ -767,15 +998,21 @@ declare class ContextManager {
     /** 添加本次交互终态，使下一次准备的保护范围与恢复后的边界一致。 */
     finishInteraction(terminal: InteractionTerminal): void;
     /**
-     * 最终 Hook 之后统一预算；输出 reserve 同时约束实际 maxTokens，超限零 Provider 调用。
+     * 最终 Hook 之后统一预算；Profile 与请求的更低覆盖同时约束输出预留和实际 maxTokens。
+     * 非法输出配置或输入超限在 Provider 调用前失败；不使用固定 4096 覆盖原生模型上限。
+     * 签名或加密续答可禁止压缩；此时仍估算并拒绝超预算请求，不剪裁历史或调用摘要网络。
+     * @param allowCompaction 是否允许当前请求剪裁/摘要；冻结私有续答前缀时传 false。
      * @returns 语义事件及准备完成的请求，不改变持久历史。
      */
-    prepare(history: readonly CanonicalMessage[], request: ModelRequest, profile: ModelProfile, runId?: string, reason?: CompactionReason): AsyncGenerator<SessionEvent, ModelRequest>;
+    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 或更新状态；恢复后即可查看检查点。 */
+    /**
+     * 从当前静态投影估算，不执行 Hook/Provider 或更新状态；恢复后即可查看检查点。
+     * 输出预留与准备请求使用同一 Profile/请求覆盖规则；非法覆盖也在只读检查时失败。
+     */
     inspect(history: readonly CanonicalMessage[], request: ModelRequest, profile: ModelProfile): ContextSnapshot;
     /** 模型或指令发生变化后使已有预算快照过期，直到下一最终请求准备成功。 */
     invalidate(): void;
@@ -805,6 +1042,7 @@ declare class ContextManager {
     private report;
 }
 
+/** 摘要模型的 JSON 输出契约；只有通过 validateSummary 的实例可进入检查点。 */
 interface ContextSummary {
     schemaVersion: 1;
     goal: string;
@@ -814,8 +1052,10 @@ interface ContextSummary {
     pendingWork: string[];
     /** 原消息身份，不接受模型虚构来源或把旧摘要当成授权。 */
     references: string[];
+    /** 结果未知的副作用记录；保留不确定性，不冒充成功或失败。 */
     unknownEffects: string[];
 }
+/** 一次文件操作的历史观察；只描述曾经发生，不描述文件当前状态。 */
 interface FileObservation {
     /** 有执行目录证据时为绝对路径；旧记录缺少依据时为原相对路径，基目录未知。 */
     path: string;
@@ -823,11 +1063,14 @@ interface FileObservation {
     toolCallId: string;
     operation: string;
 }
+/** 检查点携带的文件事实：按结果分类的观察列表，每类上限 500 条。 */
 interface FileDetails {
     readFiles: FileObservation[];
     modifiedFiles: FileObservation[];
     failedFileOperations: FileObservation[];
+    /** 工具结果缺失或 OUTCOME_UNKNOWN 时的操作记录。 */
     unknownFileOperations: FileObservation[];
+    /** 超出 500 上限被丢弃的观察总数；渲染时与列表截断数合并展示。 */
     omitted: number;
 }
 /** 对超长结果保留总计 2000 code point 首尾正文，省略说明不冒充原始结果。 */
@@ -846,21 +1089,27 @@ declare function extractFileDetails(history: readonly CanonicalMessage[], _proje
 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;
 }
 /** 摘要单次流式输出文本最大防御倍数；防止模型无限输出耗尽内存。 */
@@ -873,12 +1122,16 @@ declare class SummaryService {
     /**
      * 按完整用户交互分批，以旧摘要和新增原始前缀取材；中间结果只是局部候选，不激活。
      * 单个不可拆分输入超预算、无终态、截断或非法来源均失败，取消先关闭 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 {
@@ -898,6 +1151,7 @@ interface LogEvent {
 interface LogSink {
     write(event: LogEvent): Promise<void>;
 }
+/** 调用方提供的宽松输入；fields 仅白名单字段经脱敏校验后进入 LogEvent。 */
 interface LogInput {
     level: LogLevel;
     event: string;
@@ -954,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 事件完整追加到本地文件，并按日期及文件大小轮转。 */
@@ -972,7 +1232,9 @@ declare class FileLogSink implements LogSink {
     write(event: LogEvent): Promise<void>;
     /** 返回该通道已占用的字节数，供宿主提示长期保留的审计用量。 */
     getUsageBytes(): number;
+    /** 优先写入当天未满的最后一个序号文件，超限或无同名文件时开下一个序号。 */
     private chooseFile;
+    /** 按文件名中的日期删除早于保留期的自有文件；删除依据文件名而非文件 mtime。 */
     private cleanupExpired;
     private isOwnedFile;
 }
@@ -984,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;
@@ -1010,8 +1285,11 @@ interface ShellEnvironment {
     cwd: string;
 }
 interface ShellDetectOptions {
+    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
     preference?: ShellPreference;
+    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
     cwd: string;
+    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
     platform?: NodeJS.Platform;
     pathEnv?: string;
 }
@@ -1029,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;
@@ -1090,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'];
 }
@@ -1121,6 +1435,7 @@ declare function cleanupCommandResults(rootDir: string, now?: number): void;
 /** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
 declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
 
+/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
 interface SandboxConfig {
     rootDir: string;
     /**
@@ -1129,6 +1444,10 @@ interface SandboxConfig {
      */
     allowSymlinks?: boolean;
 }
+/**
+ * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
+ * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
+ */
 declare class PathSandbox {
     readonly rootDir: string;
     readonly allowSymlinks: boolean;
@@ -1158,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 {
@@ -1166,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>;
 }
@@ -1181,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;
@@ -1195,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[];
@@ -1222,6 +1554,7 @@ declare const grepTool: Tool<{
     pattern: string;
     path?: string;
 }, string>;
+/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
 declare const builtinTools: (Tool<{
     path: string;
     startLine?: number;
@@ -1241,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';
 } | {
@@ -1256,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>;
@@ -1279,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 结果，避免永久卡死会话循环 */
@@ -1310,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;
@@ -1335,6 +1703,7 @@ declare class ToolExecutor {
     constructor(options: ExecutorOptions);
     /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
     cancel(): void;
+    /** 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。 */
     runAll(calls: ToolUseBlock[], onProgress?: (event: {
         id: string;
         name: string;
@@ -1362,6 +1731,7 @@ declare class ToolExecutor {
     private withTimeout;
 }
 
+/** Chat 端点配置；能力覆盖只改变请求字段和完成边界，不改变协议身份。 */
 interface OpenAIProviderOptions {
     baseURL: string;
     apiKey: string;
@@ -1369,34 +1739,150 @@ interface OpenAIProviderOptions {
     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;
 }
 
+/** 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[];
+    /**
+     * 发送 Messages 流并按索引组装完整内容；增量仅供展示，终态提供有序落盘来源。
+     * maxTokens 包含思考消耗，缺省为 4096；缺终态、坏参数与服务端流错误均抛错。
+     * pause_turn 表示服务端工具暂停；当前不支持其续答，明确失败而非报告完成或调度客户端工具。
+     * 同 run/模型/端点的来源校验允许私有续答；来源不匹配的可见思考降为普通文字。
+     * 取消或消费者提前结束会等待 reader 清理并解除 HTTP 取消监听，不自动重发请求。
+     */
+    create(req: ModelRequest): AsyncIterable<ModelEvent>;
+    /**
+     * 投影 system、普通内容与工具结果；连续结果合并为下一 user 内容并置于文字之前。
+     * 私有块由共享来源规则筛选，原始消息和工具 ID 不被改写；不发送能力标签推测的思考参数。
+     */
+    private createPayload;
+}
+
+/** 原生 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;
@@ -1405,6 +1891,7 @@ declare class PromptAssembler {
     private readonly instructionSources;
     private readonly visibleTools?;
     constructor(options: PromptAssemblerOptions);
+    /** 按固定层级拼装系统提示词；同一选项集总是产出相同文本，便于审计与缓存。 */
     assemble(): string;
     private getL1Behavior;
     private getL2Tools;
@@ -1414,27 +1901,41 @@ 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?;
@@ -1452,48 +1953,74 @@ 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?;
@@ -1537,12 +2064,32 @@ declare class AgentSession {
     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;
@@ -1564,6 +2111,7 @@ declare class AgentSession {
     getLastMetrics(): TurnMetrics | undefined;
     /** 返回最近用户任务指标的独立副本；恢复的 usage 不伪造实时任务指标。 */
     getLastRunMetrics(): RunMetrics | undefined;
+    /** 空闲时清空存储与全部内存状态；conversationId 不变，恢复语义等同全新会话。 */
     reset(): Promise<void>;
     /**
      * 执行一次用户输入，并以宿主无关的语义事件流返回全过程。
@@ -1572,15 +2120,18 @@ 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;
     /**
@@ -1600,15 +2151,17 @@ declare class AgentSession {
     compact(options?: {
         signal?: AbortSignal;
     }): AsyncGenerator<SessionEvent>;
-    /** 手动压缩执行主体，接收由消费者生命周期拥有的中止信号。 */
+    /** 手动压缩按主任务协议投影旧历史，不复用旧 run 私有状态；原始历史与落盘内容保持不变。 */
     private compactOperation;
-    /** 以模型 attempt 身份幂等累加真实消耗；非法或缺失 usage 保持未知。 */
+    /** 压缩与预算超限事件写入操作日志并携带 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 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 };
+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 };