@kiturone/kapibala 0.0.10 → 0.1.0

package/dist/index.d.cts

@@ -787,6 +787,12 @@ declare function indexInteractions(input: readonly CanonicalMessage[], terminals
     protectedMessageIds: string[];
 };
 
+/** 可选单文件读取预算；省略保持旧行为，超限不得被当成 JSON 尾损坏恢复。 */
+interface HistoryReadOptions {
+    /** 编码字节总量上限，必须为正安全整数；不限制已打开事务的追加落盘。 */
+    maxReadBytes?: number;
+}
+
 /**
  * 旧版单文件 JSONL MessageStore：每行一条消息，无版本化状态能力。
  * 写入为同步追加，不做 fsync 或单写者保护；恢复时容错跳过损坏行并闭合悬挂事务。
@@ -831,7 +837,7 @@ declare const SESSION_SCHEMA_VERSION = 2;
 /** 默认主分支标识。 */
 declare const MAIN_BRANCH_ID = "main";
 /** 会话记录类型：header 只出现一次，message 承载正文，其余为分支或全局控制记录。 */
-type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import' | 'branch_created' | 'branch_selected' | 'branch_summary' | 'archive_state';
+type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import' | 'branch_created' | 'branch_selected' | 'branch_summary' | 'archive_state' | 'pin_state';
 /**
  * 判断指定记录类型是否属于全局控制记录。
  *
@@ -936,6 +942,7 @@ declare function assertClosedToolTransaction(records: SessionRecord[], targetRec
  * 调用者须在打开前取得单写者锁；本类不允许静默跳过中部损坏或重复身份。
  */
 declare class SessionStore implements StatefulMessageStore {
+    private readonly readOptions;
     readonly filePath: string;
     private queue;
     private records;
@@ -957,9 +964,9 @@ declare class SessionStore implements StatefulMessageStore {
     /** 注册可重建缓存的写后通知；缓存失败只诊断，不撤销或毒化已 fsync 的正文。 */
     setAppendObserver(observer: (record: SessionRecord) => void, onDiagnostic?: (message: string) => void): void;
     /** 以独占创建方式安装新头部（默认生成 Schema v2 格式），已有文件明确失败，绝不覆盖其它会话。 */
-    static create(filePath: string, header: SessionHeader): Promise<SessionStore>;
+    static create(filePath: string, header: SessionHeader, options?: HistoryReadOptions): Promise<SessionStore>;
     /** 打开并验证已有会话；尾部残片先保存到隔离文件，中部损坏与未知版本拒绝恢复。 */
-    static open(filePath: string): Promise<SessionStore>;
+    static open(filePath: string, options?: HistoryReadOptions): Promise<SessionStore>;
     /** 获取完整记录快照，等候已排队写入后读取；调用者不能借此修改内部记录。 */
     readRecords(): Promise<SessionRecord[]>;
     /** 消息级持久化，补稳定身份并保留所有终态字段，成功后方可进入下一次写入。 */
@@ -1004,6 +1011,16 @@ declare class SessionStore implements StatefulMessageStore {
      * 查询当前会话是否处于已归档状态。
      */
     isArchived(): Promise<boolean>;
+    /**
+     * 追加会话置顶控制记录。
+     *
+     * 约束：
+     * - 置顶状态记录为全局控制记录（parentId 为 null，不推进分支上下文叶子）；
+     * - payload 结构为 { pinned: boolean }，最后一次写入生效；
+     * - 置顶只影响列表排序，不改变正文活动时间，因此不会让会话挤进「最近」；
+     * - v1 历史会话禁止变更置顶状态。
+     */
+    setPinnedState(pinned: boolean): Promise<SessionRecord>;
     /**
      * 获取当前会话中所有已知分支的元数据与状态列表。
      */
@@ -1082,8 +1099,8 @@ interface ProjectIdentity {
 }
 /** Windows 桶和头部使用相同大小写规范，POSIX 保持路径大小写语义。 */
 declare function normalizedProjectRoot(root: string): string;
-/** 解析真实工作树根；同工作树子目录共用桶，非 Git 目录和不同 worktree 独立。不会改变 cwd。 */
-declare function resolveSessionProject(cwd: string): ProjectIdentity;
+/** 选择历史桶身份；exact 不提升显式根，git 保留同工作树子目录共桶的兼容行为。 */
+declare function resolveSessionProject(cwd: string, mode?: 'git' | 'exact'): ProjectIdentity;
 /**
  * 会话 sidecar 缓存元数据；可随时从正文重建，校验失败即丢弃，不是恢复依据。
  * 正文 JSONL 始终是唯一真源。
@@ -1124,6 +1141,10 @@ interface SessionMetadata {
     activeLeafId?: string | null;
     /** 会话是否已归档。 */
     archived?: boolean;
+    /** 会话是否置顶；只在列表排序时前置，不改变活动时间与继续最近会话的判定。 */
+    pinned?: boolean;
+    /** 预算不足时仅提供定位与提示，不把超限文件误判为损坏或写入不完整缓存。 */
+    unavailableReason?: 'HISTORY_READ_LIMIT';
 }
 /** 打开的会话句柄：持有单写者锁与 Store，宿主用毕必须 release。 */
 interface ManagedSession {
@@ -1149,6 +1170,10 @@ interface SessionManagerOptions {
     projectRoot?: string;
     /** 执行或参考目录；若未提供工作区根，以此解析项目工作树。 */
     cwd?: string;
+    /** exact 固定显式根的历史归属；缺省按 Git 工作树分桶，旧调用不迁移历史。 */
+    projectRootMode?: 'git' | 'exact';
+    /** 元数据重建、升级、打开和重载共用的单文件字节预算；省略保持原行为。 */
+    maxReadBytes?: number;
     homeDirectory?: string;
     onDiagnostic?: (message: string) => void;
 }
@@ -1160,16 +1185,19 @@ declare class SessionManager {
     readonly directory: string;
     private readonly handles;
     private readonly diagnostic?;
+    private readonly readOptions;
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
     /**
      * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
-     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；filter 在分页前筛选元数据，调用方须自行处理敏感信息。
+     * 置顶项整体前置、组内仍按活动时间排序；排序只作用于本方法的返回值，不影响 continueRecent。
      */
     list(page?: number, options?: {
         includeArchived?: boolean;
         pageSize?: number;
+        filter?: (metadata: SessionMetadata) => boolean;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -1179,18 +1207,49 @@ declare class SessionManager {
     /** 解析完整 ID 或唯一前缀对应的会话文件与 ID。 */
     private resolveSession;
     /**
-     * 逻辑归档指定会话。
+     * 归档、恢复、重命名与置顶都向正文追加一条全局控制记录，共用同一套前置约束。
      *
      * 约束：
      * - 必须取得会话独占锁；
-     * - 若会话当前正处于活动打开状态，拒绝归档并抛出 SESSION_IN_USE；
-     * - 向会话正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
+     * - 若会话当前正处于活动打开状态，拒绝并抛出 SESSION_IN_USE（调用方先关闭句柄）；
+     * - v1 只读历史不能变更，明确以 LEGACY_SESSION_READ_ONLY 失败而不是静默忽略；
+     * - 写入后按正文重建 sidecar，状态只以正文记录为准。
+     */
+    private appendControlRecord;
+    /**
+     * 逻辑归档指定会话：向正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
      */
     archiveSession(id: string): Promise<void>;
     /**
-     * 恢复已逻辑归档的会话。
+     * 恢复已逻辑归档的会话：追加 archive_state { archived: false }，正文保持不动。
      */
     restoreSession(id: string): Promise<void>;
+    /**
+     * 单独重命名指定会话，不保留句柄：追加 title 记录后立即释放写锁。
+     *
+     * 与 `rename` 的分工：本方法面向「没有打开该会话」的宿主（桌面侧栏、设置页），
+     * 因此不接受活动句柄；已打开的会话由宿主经自己的 Store 追加，避免同进程锁冲突。
+     */
+    renameSession(id: string, title: string): Promise<void>;
+    /**
+     * 切换会话置顶：追加 pin_state { pinned } 控制记录，只在列表排序时前置。
+     *
+     * 置顶不是「最近活动」，因此不写 run_started、也不改 lastActivityAt；
+     * 关闭置顶后会话回到按活动时间排序的原有位置。
+     */
+    pinSession(id: string, pinned: boolean): Promise<void>;
+    /**
+     * 物理删除指定会话的正文与 sidecar 缓存。
+     *
+     * 约束与边界：
+     * - 删除不可逆，本方法不提供回收站或软删除，调用方必须先取得用户确认；
+     * - 本 Manager 已持有句柄的会话拒绝（SESSION_IN_USE），避免删掉正在追加的文件；
+     * - 其它进程持锁时以 SESSION_LOCKED 失败，不抢占他人写入权，也不做「先等一会儿」的重试；
+     * - 只删该会话自己的 `.jsonl` 与 `.meta.json`；桶目录内其它文件（含 `*.tmp-*` 残片）不动；
+     * - 删除前复核首条头部身份与桶归属：文件名匹配但正文身份不符的残留文件删除会放大错误；
+     * - 缓存先删、正文后删：缓存本可重建，若正文删除失败该会话会在下次浏览时自动重建缓存。
+     */
+    deleteSession(id: string): Promise<void>;
     /** 一次扫描建立排序目录，分页和继续最近会话共用；有效缓存不读取正文。 */
     private allMetadata;
     /**
@@ -1206,7 +1265,12 @@ declare class SessionManager {
     continueRecent(options?: {
         autoUpgradeLegacy?: boolean;
     }): Promise<ManagedSession>;
-    /** 标题作为独立耐久记录；标题或浏览不改变正文活动排序。 */
+    /**
+     * 重命名已打开或待打开的会话；标题作为独立耐久记录，标题或浏览都不改变正文活动排序。
+     *
+     * 未持有句柄时临时打开并在追加后释放：只改标题不该把会话一直挂在写锁上，
+     * 否则同进程后续的归档、删除与置顶都会被自己占住的锁挡掉。
+     */
     rename(id: string, title: string): Promise<void>;
     /** 等候所有存储队列后释放句柄；宿主必须先结束 AgentSession 的工具/摘要清理。 */
     close(): Promise<void>;
@@ -1251,6 +1315,8 @@ declare class SessionManager {
     }): Promise<ManagedSession>;
     /** 绑定写后缓存与锁生命周期；正文优先，缓存失败不使保存成功的消息消失。 */
     private attach;
+    /** 超限列表只解析有界头部并核对桶身份，不读取正文、不生成可误用的耐久缓存。 */
+    private readOversizedMetadata;
     /** 缓存通过文件名、身份、统计与正文 stat 校验；失败交由正文重建。 */
     private readMetadata;
     /** 浏览仅解析完整记录；严格打开由 SessionStore 验证，浏览不能改写残片。 */
@@ -2671,7 +2737,6 @@ declare class HookRegistry {
     emit<K extends 'session:start' | 'session:end' | 'model:after' | 'tool:after' | 'error'>(point: K, ctx: HookContext, ...args: any[]): Promise<void>;
 }
 
-/** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
 /** 宿主运行级硬限制；优先于模式、审批及缓存，文案和字段不得携带凭据。 */
 interface ToolHardDenial {
     code: string;
@@ -2679,6 +2744,7 @@ interface ToolHardDenial {
     retryPolicy: ToolResultBlock['retryPolicy'];
     fields?: Record<string, unknown>;
 }
+/** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
 interface ExecutorOptions {
     /** 在最终参数上补充硬拒绝，不能把拒绝转为授权。 */
     hardDenial?: (tool: Tool, input: Record<string, unknown>) => ToolHardDenial | undefined;
@@ -2716,6 +2782,7 @@ interface ExecutorOptions {
     /** 会话内 allow_session / deny_session 审批缓存；缺省使用实例私有缓存。 */
     approvalCache?: SessionApprovalCache;
 }
+
 /**
  * 工具执行器：按「审计 → 钩子裁决 → 权限裁决 → 执行 → 结果闭合」处理单次调用。
  * 所有拒绝与异常都闭合为 isError 的工具结果，不向调用方抛出；
@@ -2783,14 +2850,6 @@ declare class ToolExecutor {
         outputBytes: number;
     }) => void, forcedDeny?: boolean): Promise<ToolResultBlock>;
     private executeResolved;
-    /**
-     * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
-     * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
-     *
-     * 局限：同步 CPU 密集型实现会阻塞事件循环，timer 同样无法触发；
-     * 因此内置工具仍需避免执行用户可控的同步高复杂度计算。
-     */
-    private withTimeout;
     /**
      * 构建当前会话在派生时刻的父权限策略快照。
      */
@@ -3237,6 +3296,7 @@ interface AgentLoopOptions {
     getMode?: () => SessionMode;
     permissionRules?: readonly PermissionRule[];
 }
+
 /**
  * 主执行循环：按 turn 推进「模型请求 → 整批校验 → 工具调度 → 历史闭合」。
  * run 会就地追加传入的 history，assistant 与全部 tool_result 在同一同步临界段落入，
@@ -3829,7 +3889,6 @@ interface PreparedTaskResult {
     /** 可选技能名称；存在时按显式技能流程处理。 */
     skillName?: string;
 }
-
 /** 会话的非根选项；扩展配置时与 SessionConfig 的显式根联合组合，不能隐式推导工作区。 */
 interface SessionOptions {
     /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
@@ -3904,6 +3963,7 @@ interface SessionStats {
     /** 最近一次内部模型请求的窗口占用；无实测时仅提供窗口上限。 */
     contextUsage: ContextUsage;
 }
+
 /**
  * 宿主无关的 Agent 会话门面：统一模型路由、工具执行、权限与上下文压缩。
  * 每次用户输入产生一个 run；历史与状态经 MessageStore 持久化，恢复后语义连续。
@@ -4118,4 +4178,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, 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, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryReadOptions, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, 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, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };

package/dist/index.d.ts

@@ -787,6 +787,12 @@ declare function indexInteractions(input: readonly CanonicalMessage[], terminals
     protectedMessageIds: string[];
 };
 
+/** 可选单文件读取预算；省略保持旧行为，超限不得被当成 JSON 尾损坏恢复。 */
+interface HistoryReadOptions {
+    /** 编码字节总量上限，必须为正安全整数；不限制已打开事务的追加落盘。 */
+    maxReadBytes?: number;
+}
+
 /**
  * 旧版单文件 JSONL MessageStore：每行一条消息，无版本化状态能力。
  * 写入为同步追加，不做 fsync 或单写者保护；恢复时容错跳过损坏行并闭合悬挂事务。
@@ -831,7 +837,7 @@ declare const SESSION_SCHEMA_VERSION = 2;
 /** 默认主分支标识。 */
 declare const MAIN_BRANCH_ID = "main";
 /** 会话记录类型：header 只出现一次，message 承载正文，其余为分支或全局控制记录。 */
-type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import' | 'branch_created' | 'branch_selected' | 'branch_summary' | 'archive_state';
+type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import' | 'branch_created' | 'branch_selected' | 'branch_summary' | 'archive_state' | 'pin_state';
 /**
  * 判断指定记录类型是否属于全局控制记录。
  *
@@ -936,6 +942,7 @@ declare function assertClosedToolTransaction(records: SessionRecord[], targetRec
  * 调用者须在打开前取得单写者锁；本类不允许静默跳过中部损坏或重复身份。
  */
 declare class SessionStore implements StatefulMessageStore {
+    private readonly readOptions;
     readonly filePath: string;
     private queue;
     private records;
@@ -957,9 +964,9 @@ declare class SessionStore implements StatefulMessageStore {
     /** 注册可重建缓存的写后通知；缓存失败只诊断，不撤销或毒化已 fsync 的正文。 */
     setAppendObserver(observer: (record: SessionRecord) => void, onDiagnostic?: (message: string) => void): void;
     /** 以独占创建方式安装新头部（默认生成 Schema v2 格式），已有文件明确失败，绝不覆盖其它会话。 */
-    static create(filePath: string, header: SessionHeader): Promise<SessionStore>;
+    static create(filePath: string, header: SessionHeader, options?: HistoryReadOptions): Promise<SessionStore>;
     /** 打开并验证已有会话；尾部残片先保存到隔离文件，中部损坏与未知版本拒绝恢复。 */
-    static open(filePath: string): Promise<SessionStore>;
+    static open(filePath: string, options?: HistoryReadOptions): Promise<SessionStore>;
     /** 获取完整记录快照，等候已排队写入后读取；调用者不能借此修改内部记录。 */
     readRecords(): Promise<SessionRecord[]>;
     /** 消息级持久化，补稳定身份并保留所有终态字段，成功后方可进入下一次写入。 */
@@ -1004,6 +1011,16 @@ declare class SessionStore implements StatefulMessageStore {
      * 查询当前会话是否处于已归档状态。
      */
     isArchived(): Promise<boolean>;
+    /**
+     * 追加会话置顶控制记录。
+     *
+     * 约束：
+     * - 置顶状态记录为全局控制记录（parentId 为 null，不推进分支上下文叶子）；
+     * - payload 结构为 { pinned: boolean }，最后一次写入生效；
+     * - 置顶只影响列表排序，不改变正文活动时间，因此不会让会话挤进「最近」；
+     * - v1 历史会话禁止变更置顶状态。
+     */
+    setPinnedState(pinned: boolean): Promise<SessionRecord>;
     /**
      * 获取当前会话中所有已知分支的元数据与状态列表。
      */
@@ -1082,8 +1099,8 @@ interface ProjectIdentity {
 }
 /** Windows 桶和头部使用相同大小写规范，POSIX 保持路径大小写语义。 */
 declare function normalizedProjectRoot(root: string): string;
-/** 解析真实工作树根；同工作树子目录共用桶，非 Git 目录和不同 worktree 独立。不会改变 cwd。 */
-declare function resolveSessionProject(cwd: string): ProjectIdentity;
+/** 选择历史桶身份；exact 不提升显式根，git 保留同工作树子目录共桶的兼容行为。 */
+declare function resolveSessionProject(cwd: string, mode?: 'git' | 'exact'): ProjectIdentity;
 /**
  * 会话 sidecar 缓存元数据；可随时从正文重建，校验失败即丢弃，不是恢复依据。
  * 正文 JSONL 始终是唯一真源。
@@ -1124,6 +1141,10 @@ interface SessionMetadata {
     activeLeafId?: string | null;
     /** 会话是否已归档。 */
     archived?: boolean;
+    /** 会话是否置顶；只在列表排序时前置，不改变活动时间与继续最近会话的判定。 */
+    pinned?: boolean;
+    /** 预算不足时仅提供定位与提示，不把超限文件误判为损坏或写入不完整缓存。 */
+    unavailableReason?: 'HISTORY_READ_LIMIT';
 }
 /** 打开的会话句柄：持有单写者锁与 Store，宿主用毕必须 release。 */
 interface ManagedSession {
@@ -1149,6 +1170,10 @@ interface SessionManagerOptions {
     projectRoot?: string;
     /** 执行或参考目录；若未提供工作区根，以此解析项目工作树。 */
     cwd?: string;
+    /** exact 固定显式根的历史归属；缺省按 Git 工作树分桶，旧调用不迁移历史。 */
+    projectRootMode?: 'git' | 'exact';
+    /** 元数据重建、升级、打开和重载共用的单文件字节预算；省略保持原行为。 */
+    maxReadBytes?: number;
     homeDirectory?: string;
     onDiagnostic?: (message: string) => void;
 }
@@ -1160,16 +1185,19 @@ declare class SessionManager {
     readonly directory: string;
     private readonly handles;
     private readonly diagnostic?;
+    private readonly readOptions;
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
     /**
      * 按正文活动排序分页；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。
-     * pageSize 由调用方显式给出时必须在 1–100 之间；非法页参数直接失败，不静默修正。
+     * pageSize 由调用方显式给出时必须在 1–100 之间；filter 在分页前筛选元数据，调用方须自行处理敏感信息。
+     * 置顶项整体前置、组内仍按活动时间排序；排序只作用于本方法的返回值，不影响 continueRecent。
      */
     list(page?: number, options?: {
         includeArchived?: boolean;
         pageSize?: number;
+        filter?: (metadata: SessionMetadata) => boolean;
     }): Promise<{
         items: SessionMetadata[];
         total: number;
@@ -1179,18 +1207,49 @@ declare class SessionManager {
     /** 解析完整 ID 或唯一前缀对应的会话文件与 ID。 */
     private resolveSession;
     /**
-     * 逻辑归档指定会话。
+     * 归档、恢复、重命名与置顶都向正文追加一条全局控制记录，共用同一套前置约束。
      *
      * 约束：
      * - 必须取得会话独占锁；
-     * - 若会话当前正处于活动打开状态，拒绝归档并抛出 SESSION_IN_USE；
-     * - 向会话正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
+     * - 若会话当前正处于活动打开状态，拒绝并抛出 SESSION_IN_USE（调用方先关闭句柄）；
+     * - v1 只读历史不能变更，明确以 LEGACY_SESSION_READ_ONLY 失败而不是静默忽略；
+     * - 写入后按正文重建 sidecar，状态只以正文记录为准。
+     */
+    private appendControlRecord;
+    /**
+     * 逻辑归档指定会话：向正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
      */
     archiveSession(id: string): Promise<void>;
     /**
-     * 恢复已逻辑归档的会话。
+     * 恢复已逻辑归档的会话：追加 archive_state { archived: false }，正文保持不动。
      */
     restoreSession(id: string): Promise<void>;
+    /**
+     * 单独重命名指定会话，不保留句柄：追加 title 记录后立即释放写锁。
+     *
+     * 与 `rename` 的分工：本方法面向「没有打开该会话」的宿主（桌面侧栏、设置页），
+     * 因此不接受活动句柄；已打开的会话由宿主经自己的 Store 追加，避免同进程锁冲突。
+     */
+    renameSession(id: string, title: string): Promise<void>;
+    /**
+     * 切换会话置顶：追加 pin_state { pinned } 控制记录，只在列表排序时前置。
+     *
+     * 置顶不是「最近活动」，因此不写 run_started、也不改 lastActivityAt；
+     * 关闭置顶后会话回到按活动时间排序的原有位置。
+     */
+    pinSession(id: string, pinned: boolean): Promise<void>;
+    /**
+     * 物理删除指定会话的正文与 sidecar 缓存。
+     *
+     * 约束与边界：
+     * - 删除不可逆，本方法不提供回收站或软删除，调用方必须先取得用户确认；
+     * - 本 Manager 已持有句柄的会话拒绝（SESSION_IN_USE），避免删掉正在追加的文件；
+     * - 其它进程持锁时以 SESSION_LOCKED 失败，不抢占他人写入权，也不做「先等一会儿」的重试；
+     * - 只删该会话自己的 `.jsonl` 与 `.meta.json`；桶目录内其它文件（含 `*.tmp-*` 残片）不动；
+     * - 删除前复核首条头部身份与桶归属：文件名匹配但正文身份不符的残留文件删除会放大错误；
+     * - 缓存先删、正文后删：缓存本可重建，若正文删除失败该会话会在下次浏览时自动重建缓存。
+     */
+    deleteSession(id: string): Promise<void>;
     /** 一次扫描建立排序目录，分页和继续最近会话共用；有效缓存不读取正文。 */
     private allMetadata;
     /**
@@ -1206,7 +1265,12 @@ declare class SessionManager {
     continueRecent(options?: {
         autoUpgradeLegacy?: boolean;
     }): Promise<ManagedSession>;
-    /** 标题作为独立耐久记录；标题或浏览不改变正文活动排序。 */
+    /**
+     * 重命名已打开或待打开的会话；标题作为独立耐久记录，标题或浏览都不改变正文活动排序。
+     *
+     * 未持有句柄时临时打开并在追加后释放：只改标题不该把会话一直挂在写锁上，
+     * 否则同进程后续的归档、删除与置顶都会被自己占住的锁挡掉。
+     */
     rename(id: string, title: string): Promise<void>;
     /** 等候所有存储队列后释放句柄；宿主必须先结束 AgentSession 的工具/摘要清理。 */
     close(): Promise<void>;
@@ -1251,6 +1315,8 @@ declare class SessionManager {
     }): Promise<ManagedSession>;
     /** 绑定写后缓存与锁生命周期；正文优先，缓存失败不使保存成功的消息消失。 */
     private attach;
+    /** 超限列表只解析有界头部并核对桶身份，不读取正文、不生成可误用的耐久缓存。 */
+    private readOversizedMetadata;
     /** 缓存通过文件名、身份、统计与正文 stat 校验；失败交由正文重建。 */
     private readMetadata;
     /** 浏览仅解析完整记录；严格打开由 SessionStore 验证，浏览不能改写残片。 */
@@ -2671,7 +2737,6 @@ declare class HookRegistry {
     emit<K extends 'session:start' | 'session:end' | 'model:after' | 'tool:after' | 'error'>(point: K, ctx: HookContext, ...args: any[]): Promise<void>;
 }
 
-/** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
 /** 宿主运行级硬限制；优先于模式、审批及缓存，文案和字段不得携带凭据。 */
 interface ToolHardDenial {
     code: string;
@@ -2679,6 +2744,7 @@ interface ToolHardDenial {
     retryPolicy: ToolResultBlock['retryPolicy'];
     fields?: Record<string, unknown>;
 }
+/** ToolExecutor 的构造项；审计写入需要 eventLogger 与 sessionId 同时提供，否则不产生审计。 */
 interface ExecutorOptions {
     /** 在最终参数上补充硬拒绝，不能把拒绝转为授权。 */
     hardDenial?: (tool: Tool, input: Record<string, unknown>) => ToolHardDenial | undefined;
@@ -2716,6 +2782,7 @@ interface ExecutorOptions {
     /** 会话内 allow_session / deny_session 审批缓存；缺省使用实例私有缓存。 */
     approvalCache?: SessionApprovalCache;
 }
+
 /**
  * 工具执行器：按「审计 → 钩子裁决 → 权限裁决 → 执行 → 结果闭合」处理单次调用。
  * 所有拒绝与异常都闭合为 isError 的工具结果，不向调用方抛出；
@@ -2783,14 +2850,6 @@ declare class ToolExecutor {
         outputBytes: number;
     }) => void, forcedDeny?: boolean): Promise<ToolResultBlock>;
     private executeResolved;
-    /**
-     * 给工具执行加超时护栏：Promise.race 在超时后reject，循环拿到 isError 结果继续运转，
-     * 不会因某个异步工具(如未来接入的网络/exec 工具)挂起而永久卡死。
-     *
-     * 局限：同步 CPU 密集型实现会阻塞事件循环，timer 同样无法触发；
-     * 因此内置工具仍需避免执行用户可控的同步高复杂度计算。
-     */
-    private withTimeout;
     /**
      * 构建当前会话在派生时刻的父权限策略快照。
      */
@@ -3237,6 +3296,7 @@ interface AgentLoopOptions {
     getMode?: () => SessionMode;
     permissionRules?: readonly PermissionRule[];
 }
+
 /**
  * 主执行循环：按 turn 推进「模型请求 → 整批校验 → 工具调度 → 历史闭合」。
  * run 会就地追加传入的 history，assistant 与全部 tool_result 在同一同步临界段落入，
@@ -3829,7 +3889,6 @@ interface PreparedTaskResult {
     /** 可选技能名称；存在时按显式技能流程处理。 */
     skillName?: string;
 }
-
 /** 会话的非根选项；扩展配置时与 SessionConfig 的显式根联合组合，不能隐式推导工作区。 */
 interface SessionOptions {
     /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
@@ -3904,6 +3963,7 @@ interface SessionStats {
     /** 最近一次内部模型请求的窗口占用；无实测时仅提供窗口上限。 */
     contextUsage: ContextUsage;
 }
+
 /**
  * 宿主无关的 Agent 会话门面：统一模型路由、工具执行、权限与上下文压缩。
  * 每次用户输入产生一个 run；历史与状态经 MessageStore 持久化，恢复后语义连续。
@@ -4118,4 +4178,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, 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, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryReadOptions, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, 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, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionErrorCode, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionOptions, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentRunnerContext, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSessionError, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };