@kiturone/kapibala 0.0.4 → 0.0.5

package/dist/index.d.cts

@@ -1,3 +1,97 @@
+/** 技能知识来源；层级决定覆盖顺序，不授予文件或执行权限。 */
+type SkillScope = 'builtin' | 'global' | 'project';
+/** 结构化技能诊断；路径及文案需由宿主安全展示，不包含正文或凭据。 */
+interface SkillDiagnostic {
+    code: string;
+    level: 'warn' | 'error';
+    path: string;
+    message: string;
+    winnerPath?: string;
+    loserPath?: string;
+}
+/** 已校验的文件内容；available=false 的执行扩展仅供诊断，不得激活。 */
+interface SkillDocument {
+    name: string;
+    description: string;
+    body: string;
+    when?: string;
+    license?: string;
+    compatibility?: string;
+    argumentHint?: string;
+    metadata?: Readonly<Record<string, string>>;
+    frontmatter: Readonly<Record<string, unknown>>;
+    allowedTools?: readonly string[];
+    modelInvocable: boolean;
+    userInvocable: boolean;
+    available: boolean;
+    unavailableReason?: string;
+    diagnostics: readonly SkillDiagnostic[];
+}
+/** 宿主显式提供的扫描根；项目缺省不可信，boundary 必须是授权物理边界。 */
+interface SkillRoot {
+    path: string;
+    scope: SkillScope;
+    kind?: 'native' | 'agents';
+    trusted?: boolean;
+    boundary?: string;
+}
+/** 可查询元数据；文件指纹来自发现快照，加载前必须重新核验。 */
+interface SkillMetadata extends Omit<SkillDocument, 'body' | 'frontmatter' | 'diagnostics'> {
+    scope: SkillScope;
+    sourceRoot: string;
+    filePath: string;
+    baseDir: string;
+    contentDigest: string;
+    /** 原词法发现身份；加载重核根链接，不以旧物理文件继续授权。 */
+    discoveryRoot: string;
+    discoveryPath: string;
+    priority: number;
+    disabled: boolean;
+}
+/** 完整快照实体；正文仅在校验通过后按需进入模型历史。 */
+interface SkillDefinition extends SkillMetadata {
+    body: string;
+}
+/** 会话技能选项；无根即不扫描 home，disabled 名称不能由项目配置重新启用。 */
+interface SkillOptions {
+    roots: readonly SkillRoot[];
+    enabled?: boolean;
+    disabled?: readonly string[];
+}
+/** 技能正文持久来源；只追踪事实，历史来源不恢复授权。 */
+interface SkillContentSource {
+    version: 1;
+    name: string;
+    scope: SkillScope;
+    filePath: string;
+    baseDir: string;
+    contentDigest: string;
+    renderedDigest: string;
+    caller: 'user' | 'model';
+    runId: string;
+    invocationId: string;
+}
+/** 本轮活动记录；pending 只收紧，committed 后才可受控读取资源。 */
+interface SkillActivation {
+    definition: SkillDefinition;
+    source: SkillContentSource;
+    state: 'pending' | 'committed';
+    allowedTools?: ReadonlySet<string>;
+}
+/** 统一默认限额；宿主不得另算一套目录、文件或响应预算。 */
+declare const SKILL_LIMITS: Readonly<{
+    fileBytes: number;
+    frontmatterBytes: number;
+    depth: 6;
+    directories: 2000;
+    entries: 20000;
+    descriptionChars: 250;
+    catalogTokens: 2000;
+    queryTokens: 1000;
+    resourceBytes: number;
+    resourceFiles: 20;
+}>;
+
 /** 内置适配器的实际请求目标；用于拒绝模型、协议或端点错配的绑定。 */
 interface ModelProviderBinding {
     protocol: ModelProtocol;
@@ -245,6 +339,8 @@ type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ThinkingBlock |
 interface TextBlock {
     type: 'text';
     text: string;
+    /** 宿主注入技能的可选来源；只追踪正文，缺失或恢复不授予权限。 */
+    skillSource?: SkillContentSource;
     /** 源 wire Item 元数据；正文被改写后由调用方清除，不作为业务身份。 */
     protocolMeta?: ProtocolItemMetadata;
 }
@@ -262,6 +358,8 @@ interface ToolUseBlock {
 }
 interface ToolResultBlock {
     type: 'tool_result';
+    /** 完整技能正文的宿主来源；不发送到Provider wire，不从历史恢复授权。 */
+    skillSource?: SkillContentSource;
     toolUseId: string;
     content: string;
     isError?: boolean;
@@ -383,6 +481,11 @@ interface StepLogEntry {
  * 不应直接把本类型当作长期兼容的网络协议。
  */
 type SessionEvent = {
+    type: 'skill_loaded';
+    source: SkillContentSource;
+    messageId: string;
+    persistence: 'memory' | 'disk';
+} | {
     type: 'session_resumed';
     conversationId: string;
     runtimeSessionId: string;
@@ -1022,7 +1125,7 @@ declare class ContextManager {
     private publishSnapshot;
     /** 最终请求与只读估算共用来源和状态计数。 */
     private buildSnapshot;
-    /** 摘要以用户历史背景注入，不升级为系统指令或恢复旧授权。 */
+    /** 摘要与技能重载事实由已验证原历史生成，不升级为系统指令或恢复旧授权；旧检查点同样适用。 */
     private summaryMessage;
     /**
      * 旧轮次仅在工具事务闭合时可摘要；成功可由旧记录推断，失败或中断必须有运行终态来源。
@@ -1273,37 +1376,89 @@ interface InstructionLoadOptions {
  */
 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;
-    executableDigest: string;
-    cwd: string;
+/** 安全名称语法；不接受厂商命名空间、路径或连续连字符。 */
+declare function isSkillName(value: string): boolean;
+/** 解析常用 Frontmatter 子集；格式错误抛出，未知执行扩展返回不可执行诊断，正文不截断。 */
+declare function parseSkillDocument(content: string, filePath: string): SkillDocument;
+
+/** 技能错误仅返回受控文案；retryPolicy 不触发工具内部重试。 */
+declare function skillFailure(code: string, message: string): KapibalaError;
+/** 以路径段判断物理边界，允许边界自身但不接受越界或其他盘符。 */
+declare function isWithinSkillRoot(root: string, target: string): boolean;
+/** Windows 物理身份忽略盘符/路径大小写，其他平台维持文件系统原义。 */
+declare function skillPathKey(value: string): string;
+/** 按 code point 排序，不使用受语言区域影响的比较器。 */
+declare function compareSkillPaths(left: string, right: string): number;
+/** 有界 UTF-8 读取；先检查文件类型/大小，增长中的文件也不能突破上限。 */
+declare function readBoundedSkillText(filePath: string, maximum: number, signal?: AbortSignal): Promise<string>;
+/** 原文件字节摘要；有效 UTF-8 的重新编码保留 BOM 与换行，不使用规范化正文替代。 */
+declare function skillDigest(content: string): string;
+/** 单根发现结果；诊断可包含无效候选，扫描结束后只保留元数据，不常驻正文。 */
+interface SkillScanResult {
+    skills: SkillMetadata[];
+    diagnostics: SkillDiagnostic[];
+}
+/** 扫描单根的技能边界；有界异步遍历，项目未声明信任时实体只供宿主诊断。 */
+declare function scanSkillRoot(root: SkillRoot, signal?: AbortSignal): Promise<SkillScanResult>;
+
+/** 使用现有 Unicode 估算器计完整文本，非 ASCII 不按四字符折算。 */
+declare function estimateSkillTokens(text: string): number;
+/** 技能元数据的 XML 转义；不把未转义的描述或路径当作目录结构。 */
+declare function escapeSkillXml(text: string): string;
+/** 完整目录投影及遗漏统计；text 为空表示最小目录也无法容纳。 */
+interface SkillCatalog {
+    text: string;
+    included: number;
+    omitted: number;
+    estimatedTokens: number;
+}
+/** 生成确定性 L2.5；预算含标题、XML、转义及遗漏提示，只删完整条目。 */
+declare function formatSkillCatalog(skills: readonly SkillMetadata[], contextWindow?: number, remainingTokens?: number): SkillCatalog;
+/** 模型目录分页输入；游标只定位快照，不提供信任或正文访问授权。 */
+interface SkillQuery {
+    query?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** 有界模型元数据页；不包含正文，游标按实际返回条目推进。 */
+interface SkillQueryPage {
+    skills: {
+        name: string;
+        description: string;
+        scope: string;
+        argumentHint?: string;
+    }[];
+    total: number;
+    nextCursor?: string;
 }
-interface ShellDetectOptions {
-    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
-    preference?: ShellPreference;
-    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
-    cwd: string;
-    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
-    platform?: NodeJS.Platform;
-    pathEnv?: string;
+
+/** 确定性技能注册表；刷新原子替换快照，运行中加载必须与发现指纹一致。 */
+declare class SkillRegistry {
+    private readonly options;
+    private definitions;
+    private warnings;
+    private revisionValue;
+    /** 固定宿主配置副本，外部对象变更不能静默改变本轮发现或信任。 */
+    constructor(options: SkillOptions);
+    /** 获取独立诊断副本，调用方不能修改生效候选或权限。 */
+    get diagnostics(): SkillDiagnostic[];
+    /** 快照游标身份随正文、来源、可用性变化而失效。 */
+    get revision(): string;
+    /** 是否由宿主启用；关闭只影响本次能力，不删除历史或文件。 */
+    get enabled(): boolean;
+    /** 每轮开始重新发现；取消不发布半个快照，非法单文件只产生诊断。 */
+    refresh(signal?: AbortSignal): Promise<void>;
+    /** 按名称查询胜出元数据副本；未知名称返回 undefined，正文仅由 load 校验后懒读取。 */
+    get(name: string): SkillMetadata | undefined;
+    /** 宿主可检查不可用条目；模型/用户视图分别施加调用控制，均不读取正文。 */
+    list(caller?: 'host' | 'model' | 'user', query?: string): SkillMetadata[];
+    /** 按当前快照校验调用控制与物理身份，不接受模型提供的信任或 caller 升级。 */
+    load(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<SkillDefinition>;
+    /** 查询可信模型集合；过期游标可修正，预算不足不返回不前进的分页。 */
+    queryModel(input?: SkillQuery, remainingTokens?: number): SkillQueryPage;
+    /** 复核配置根、词法发现路径和原文件字节，返回本次有界读取文本；漂移要求新运行，不能热替换。 */
+    verify(skill: SkillMetadata, signal?: AbortSignal): Promise<string>;
 }
-/**
- * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
- * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
- */
-declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
-/**
- * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
- * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
- * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
- */
-declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
 
 /** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
 type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
@@ -1407,75 +1562,32 @@ declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>
 /** 投影为模型可见的工具描述；刻意丢弃 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'];
-}
-/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
-declare function cleanupCommandResults(rootDir: string, now?: number): void;
-/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
-declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
+/** 归一化技能白名单；参数模式/未知名称不得退化成宽泛命令授权。 */
+declare function normalizeSkillTools(skill: SkillDefinition, tools: readonly Tool[]): ReadonlySet<string> | undefined;
+/** 多活动技能白名单取交集；未声明不参与，空集合不等于无限制。 */
+declare function intersectSkillTools(activations: Iterable<Pick<SkillActivation, 'allowedTools'>>): ReadonlySet<string> | undefined;
 
-/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
-interface SandboxConfig {
-    rootDir: string;
-    /**
-     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
-     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
-     */
-    allowSymlinks?: boolean;
-}
-/**
- * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
- * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
- */
-declare class PathSandbox {
-    readonly rootDir: string;
-    readonly allowSymlinks: boolean;
-    private cachedRealRootDir?;
-    constructor(config: SandboxConfig);
-    /**
-     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
-     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
-     */
-    private get realRootDir();
-    /**
-     * 检查并解析安全路径
-     * 1. 解析相对路径为相对于 rootDir 的绝对路径
-     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
-     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
-     */
-    resolveSafePath(targetPath: string): string;
-    /**
-     * 把词法路径映射为物理路径。
-     *
-     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
-     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
-     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
-     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
-     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
-     */
-    private toPhysicalPath;
+/** 受控文本范围；offset 用于 UTF-8 大行续读，不能与行范围混用。 */
+interface SkillResourceInput {
+    name: string;
+    path: string;
+    startLine?: number;
+    endLine?: number;
+    offset?: number;
 }
+/** 只读资源页；nextOffset 是完整 UTF-8 字符边界，不代表文件执行授权。 */
+interface SkillResourcePage {
+    text: string;
+    truncated: boolean;
+    nextOffset?: number;
+}
+/** 读取技能根内文本；复核物理边界，有界返回并关闭文件，不扩大普通文件沙箱。 */
+declare function readSkillResource(skill: SkillDefinition, input: SkillResourceInput, signal?: AbortSignal): Promise<SkillResourcePage>;
+/** 限量列出包内资源名而不读取正文；外部链接、默认忽略目录及深层资源不展开。 */
+declare function listSkillResources(skill: SkillDefinition, signal?: AbortSignal): Promise<{
+    files: string[];
+    truncated: boolean;
+}>;
 
 /**
  * 人工审批的五选一结果。allow_once / deny_once 只作用于本次执行；
@@ -1526,54 +1638,14 @@ declare class ToolRegistry {
     registerSource(source: string, tools: Tool[]): void;
     unregisterSource(source: string): void;
     get(name: string): Tool | undefined;
+    /** 注销指定名称及来源记录；调用方须核对实例身份，不能移除同名替代工具。 */
+    unregister(name: string): void;
     /** 未命中时抛 ToolNotFound，并携带当前全部可用名称辅助模型自纠。 */
     resolve(name: string): Tool;
     list(): Tool[];
     definitions(): ToolDefinition[];
 }
 
-declare const readFileTool: Tool<{
-    path: string;
-    startLine?: number;
-    endLine?: number;
-}, string>;
-declare const writeFileTool: Tool<{
-    path: string;
-    content: string;
-}, string>;
-declare const editFileTool: Tool<{
-    path: string;
-    targetContent: string;
-    replacementContent: string;
-}, string>;
-declare const globTool: Tool<{
-    pattern: string;
-    subDirectory?: string;
-}, string>;
-declare const grepTool: Tool<{
-    pattern: string;
-    path?: string;
-}, string>;
-/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
-declare const builtinTools: (Tool<{
-    path: string;
-    startLine?: number;
-    endLine?: number;
-}, string> | Tool<{
-    path: string;
-    content: string;
-}, string> | Tool<{
-    path: string;
-    targetContent: string;
-    replacementContent: string;
-}, string> | Tool<{
-    pattern: string;
-    subDirectory?: string;
-}, string> | Tool<{
-    pattern: string;
-    path?: string;
-}, string>)[];
-
 /**
  * 运行时钩子契约：宿主与插件在固定切点观察或调整流程。
  * 通知型切点由 HookRegistry.emit 串行触发；需要返回值的 model:before / tool:before
@@ -1639,25 +1711,19 @@ declare class HookRegistry {
     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 ToolHardDenial {
+    code: string;
+    message: string;
+    retryPolicy: ToolResultBlock['retryPolicy'];
+    fields?: Record<string, unknown>;
+}
 interface ExecutorOptions {
+    /** 在最终参数上补充硬拒绝，不能把拒绝转为授权。 */
+    hardDenial?: (tool: Tool, input: Record<string, unknown>) => ToolHardDenial | undefined;
+    /** 结果钩子和执行审计完成后调用；用于在同批次下一调用前安装宿主收紧状态。 */
+    onToolResult?: (tool: Tool, input: Record<string, unknown>, result: ToolResultBlock) => void | Promise<void>;
     tools: ToolRegistry;
     hooks: HookRegistry;
     /** 工具执行的绝对根目录；路径解析与审批均以此为基准。 */
@@ -1684,6 +1750,8 @@ interface ExecutorOptions {
  * 同一 run 内参数完全相同的 never 失败会被拒绝重复执行。
  */
 declare class ToolExecutor {
+    private readonly hardDenial?;
+    private readonly onToolResult?;
     private readonly tools;
     private readonly hooks;
     private readonly rootDir;
@@ -1703,13 +1771,16 @@ declare class ToolExecutor {
     constructor(options: ExecutorOptions);
     /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
     cancel(): void;
-    /** 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。 */
+    /**
+     * 串行执行全部调用并返回与入参顺序一致的结果；某个结果要求用户介入后，其余调用直接拒绝。
+     * onResult 在每个最终结果（含拒绝/失败）产生后提供独立快照，供在途预算估算，不代表历史已提交；回调不得抛错。
+     */
     runAll(calls: ToolUseBlock[], onProgress?: (event: {
         id: string;
         name: string;
         elapsedMs: number;
         outputBytes: number;
-    }) => void): Promise<ToolResultBlock[]>;
+    }) => void, onResult?: (result: ToolResultBlock) => void): Promise<ToolResultBlock[]>;
     /**
      * 在最终参数上裁决并审计一次调用，所有拒绝和异常均闭合为工具结果。
      * 为调用记录本次绝对工具根目录，供跨目录恢复后的文件事实解析；不使用历史目录授权。
@@ -1731,6 +1802,237 @@ declare class ToolExecutor {
     private withTimeout;
 }
 
+/** 加载预检结果；只有最终成功工具结果或真实用户消息提交后才形成活动资格。 */
+interface PreparedSkill {
+    /** 本轮完整正文仍可见时只引用，引用结果不附完整正文来源。 */
+    alreadyPresent?: boolean;
+    definition: SkillDefinition;
+    source: SkillContentSource;
+    text: string;
+    allowedTools?: ReadonlySet<string>;
+}
+/** 会话内技能运行状态；控制工具按实例身份识别，pending 只收紧而不授予资源。 */
+declare class SkillRuntime {
+    readonly registry: SkillRegistry;
+    private readonly tools;
+    private readonly onResourceRead?;
+    readonly loaderTool: Tool;
+    readonly queryTool: Tool;
+    readonly resourceTool: Tool;
+    private readonly controls;
+    private readonly prepared;
+    private readonly active;
+    private runId;
+    private history;
+    private projection;
+    private reservedTokens;
+    private remaining;
+    /** 注册表和工具集合属于一个Session；不跨会话共享授权或隐式目录。 */
+    constructor(registry: SkillRegistry, tools: ToolRegistry, onResourceRead?: ((source: SkillContentSource, input: SkillResourceInput, page: SkillResourcePage) => Promise<void>) | undefined);
+    /**
+     * 开始新运行；历史正文只作事实，必须由本轮加载重新激活。
+     * remaining 必须扣除在途 assistant 和普通工具结果；尚未提交的成功技能正文由本类独立预留，不重复扣除。
+     */
+    begin(runId: string, history: () => readonly CanonicalMessage[], remaining: () => number, projection?: () => readonly CanonicalMessage[]): void;
+    /** 按实际集合安装实例工具；同名插件不覆盖为受信任工具，也不能制造目录引导。 */
+    syncTools(): void;
+    /** 清空本轮状态；调用方必须先等待工具和历史事务清理，不能提前释放会话锁。 */
+    clear(): void;
+    /** 查询本轮活动状态副本，避免宿主修改限制。 */
+    get activations(): SkillActivation[];
+    /** 预检正文、限制和输入空间；调用方由宿主固定，不读取模型伪造caller。 */
+    prepare(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<PreparedSkill>;
+    /** 真实用户入口安装pending；正文需进入用户消息，提交前不提供资源。 */
+    acceptUser(prepared: PreparedSkill): void;
+    /** 最终工具结果通过执行器钩子/审计后安装收紧；同名或仿造结果不激活。 */
+    acceptResult(tool: Tool, result: ToolResultBlock): void;
+    /** 业务调用的动态硬拒绝；控制工具仅按实例豁免，仍须宿主权限裁决。 */
+    denial(tool: Tool): ToolHardDenial | undefined;
+    /** 完整消息提交后记录审计再发布事件；失败不回滚历史，但不提交资源资格。 */
+    commit(audit: (source: SkillContentSource, messageId: string) => Promise<void>, persistence: 'memory' | 'disk'): Promise<SessionEvent[]>;
+    /** 检查最终模型投影的完整活动指导；钩子或压缩不能移走后继续执行。 */
+    assertProjection(messages: readonly CanonicalMessage[]): void;
+    /** 只读本轮已提交技能资源；文件/来源漂移要求重新开始，不重放脚本。 */
+    readResource(input: SkillResourceInput, signal?: AbortSignal): Promise<SkillResourcePage>;
+}
+
+/** 技能正文在实际投影中的状态；来源只关联事实，present 不代表当前运行获得授权。 */
+interface SkillContextState {
+    source: SkillContentSource;
+    messageId: string;
+    state: 'present' | 'requires_reload';
+}
+/** 查找真实投影中的完整正文来源；字段缺失、未知版本或文本摘要不匹配不用于去重。 */
+declare function findSkillContent(history: readonly CanonicalMessage[], source: SkillContentSource): {
+    messageId: string;
+    source: SkillContentSource;
+} | undefined;
+/** 比较原始来源与真实投影，以最后一次相同文件/版本正文为准；不恢复旧授权或执行动作。 */
+declare function inspectSkillContent(raw: readonly CanonicalMessage[], projected: readonly CanonicalMessage[]): SkillContextState[];
+/** 将离开投影的旧正文表示为有界重载事实；最多50条，遗漏数明确，不把历史包装成当前指令。 */
+declare function renderSkillReloads(covered: readonly CanonicalMessage[]): string;
+
+/** 受支持的解释器家族；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;
+    executableDigest: string;
+    cwd: string;
+}
+interface ShellDetectOptions {
+    /** 'auto'、具名解释器，或解释器可执行文件全路径；含路径分隔符或 .exe 后缀按显式路径处理。 */
+    preference?: ShellPreference;
+    /** 探测与后续执行的基准目录；探测前先取 realpath，符号链接会被展开。 */
+    cwd: string;
+    /** 以下两项供测试注入平台与 PATH；缺省取当前进程的值。 */
+    platform?: NodeJS.Platform;
+    pathEnv?: string;
+}
+/**
+ * 按 uname 输出分类 bash 家族：Git Bash/MSYS2/Cygwin 归 native bash，
+ * Windows 上报告 Linux 的是 WSL launcher（独立 kind，路径语义不同）。
+ */
+declare function classifyBashOutput(unameOutput: string, platform: NodeJS.Platform): ShellKind | undefined;
+/**
+ * 发现并固定实际解释器：只用 PATH 与用户显式给出的路径，不写死任何安装目录。
+ * auto 在 Windows 上按 native Bash → WSL → pwsh → powershell 依次兜底，
+ * bash 家族用运行时 uname 探针区分 Git Bash 与 WSL launcher。
+ */
+declare function detectShell(options: ShellDetectOptions): ShellEnvironment;
+
+/** 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'];
+}
+/** 仅清理受管 UUID 文件，避免删除用户在同目录保存的结果。 */
+declare function cleanupCommandResults(rootDir: string, now?: number): void;
+/** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
+declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
+
+/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
+interface SandboxConfig {
+    rootDir: string;
+    /**
+     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
+     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
+     */
+    allowSymlinks?: boolean;
+}
+/**
+ * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
+ * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
+ */
+declare class PathSandbox {
+    readonly rootDir: string;
+    readonly allowSymlinks: boolean;
+    private cachedRealRootDir?;
+    constructor(config: SandboxConfig);
+    /**
+     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
+     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
+     */
+    private get realRootDir();
+    /**
+     * 检查并解析安全路径
+     * 1. 解析相对路径为相对于 rootDir 的绝对路径
+     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
+     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
+     */
+    resolveSafePath(targetPath: string): string;
+    /**
+     * 把词法路径映射为物理路径。
+     *
+     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
+     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
+     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
+     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
+     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
+     */
+    private toPhysicalPath;
+}
+
+declare const readFileTool: Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string>;
+declare const writeFileTool: Tool<{
+    path: string;
+    content: string;
+}, string>;
+declare const editFileTool: Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string>;
+declare const globTool: Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string>;
+declare const grepTool: Tool<{
+    pattern: string;
+    path?: string;
+}, string>;
+/** 五个内置文件工具的聚合；全部经 PathSandbox 校验，路径越界或符号链接穿透一律拒绝。 */
+declare const builtinTools: (Tool<{
+    path: string;
+    startLine?: number;
+    endLine?: number;
+}, string> | Tool<{
+    path: string;
+    content: string;
+}, string> | Tool<{
+    path: string;
+    targetContent: string;
+    replacementContent: string;
+}, string> | Tool<{
+    pattern: string;
+    subDirectory?: string;
+}, string> | Tool<{
+    pattern: string;
+    path?: string;
+}, string>)[];
+
+/** 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>;
+}
+
 /** Chat 端点配置；能力覆盖只改变请求字段和完成边界，不改变协议身份。 */
 interface OpenAIProviderOptions {
     baseURL: string;
@@ -1866,7 +2168,13 @@ declare class OpenAIResponsesProvider implements ModelProvider {
     private toUsage;
 }
 
+/** 分层提示选项；目录受实际工具定义和请求剩余空间约束，不能用同名工具冒充加载能力。 */
 interface PromptAssemblerOptions {
+    /** 可信技能快照；仅匹配加载工具实例实际可见时注入L2.5。 */
+    skills?: SkillRegistry;
+    skillLoader?: Tool;
+    contextWindow?: number;
+    skillBudgetTokens?: number;
     /** 提供时才生成 L2 工具清单段；缺省表示本次运行不向模型展示任何工具。 */
     tools?: ToolRegistry;
     /** L3 环境段展示的工作区根目录；文件工具的沙箱边界与其保持一致。 */
@@ -1884,6 +2192,7 @@ interface PromptAssemblerOptions {
  * 各段之间以 `\n\n---\n\n` 分隔；不提供的内容整段跳过，不做占位填充。
  */
 declare class PromptAssembler {
+    private readonly options;
     private readonly tools?;
     private readonly rootDir;
     private readonly agentName;
@@ -1893,11 +2202,14 @@ declare class PromptAssembler {
     constructor(options: PromptAssemblerOptions);
     /** 按固定层级拼装系统提示词；同一选项集总是产出相同文本，便于审计与缓存。 */
     assemble(): string;
+    /** 返回与 assemble 相同的目录统计；加载器被隐藏、替换或禁用时省略执行目录。 */
+    getSkillCatalog(): SkillCatalog;
     private getL1Behavior;
     private getL2Tools;
     private getL3Environment;
 }
 
+/** 循环宿主配置；请求投影与在途预算只操作临时视图，历史仍按完整工具事务追加。 */
 interface AgentLoopOptions {
     /** 本次交互身份，内部步骤仍独立编号。 */
     interactionId?: string;
@@ -1910,6 +2222,8 @@ interface AgentLoopOptions {
     prepareRequest?: RequestPreparation;
     /** 每次收到 usage 后回调；attemptId 标识 run:step:attempt，便于按尝试归因。 */
     onUsage?: (request: ModelRequest, usage: Usage, attemptId: string) => Promise<void>;
+    /** 在途批次预算视图；含当前 assistant 和已完成结果，不能作为落盘或授权依据，闭合后清空；回调不得抛错。 */
+    onToolBatchUpdate?: (messages: readonly CanonicalMessage[]) => void;
     provider: ModelProvider;
     executor: ToolExecutor;
     tools: ToolRegistry;
@@ -1939,6 +2253,7 @@ declare class AgentLoop {
     private readonly projectHistory?;
     private readonly prepareRequest?;
     private readonly onUsage?;
+    private readonly onToolBatchUpdate?;
     private readonly provider;
     private readonly executor;
     private readonly tools;
@@ -1966,6 +2281,8 @@ declare class AgentLoop {
 
 /** AgentSession 的构造配置；除主任务绑定外均可缺省，缺省行为见各字段。 */
 interface SessionConfig {
+    /** 宿主显式技能配置；缺省不扫描home，项目根需独立信任。 */
+    skills?: SkillOptions;
     /** 持久会话身份；有版本化 Store 时须与头部一致，日志实例身份保持独立。 */
     conversationId?: string;
     tokenEstimator?: TokenEstimator;
@@ -2022,6 +2339,8 @@ interface SessionStats {
  * 运行或清理进行中，改变状态的公开方法一律被拒绝；Core 不承担任何界面职责。
  */
 declare class AgentSession {
+    private readonly skillRegistry?;
+    private readonly skillRuntime?;
     private persistentId;
     private readonly configuredConversationId?;
     private readonly estimator?;
@@ -2101,6 +2420,17 @@ declare class AgentSession {
     getHistory(): CanonicalMessage[];
     /** 返回当前投影视图，区别于原始历史；不执行模型或 Hook。 */
     getContextHistory(): CanonicalMessage[];
+    /** 查询技能元数据、诊断与本轮活动状态；只读，不加载正文或改变权限。 */
+    getSkills(query?: string): {
+        skills: SkillMetadata[];
+        diagnostics: SkillDiagnostic[];
+        activations: SkillActivation[];
+        content: SkillContextState[];
+        catalog: {
+            included: number;
+            omitted: number;
+        };
+    };
     /** 查询最近最终请求的预算快照，尚未准备请求时返回 undefined。 */
     getContextSnapshot(): ContextSnapshot | undefined;
     /** 执行中止后的工具/摘要与存储收口期间仍返回 true。 */
@@ -2129,11 +2459,22 @@ declare class AgentSession {
         signal?: AbortSignal;
         role?: PrimaryModelRole;
     }): AsyncIterable<SessionEvent>;
+    /** 显式用户技能入口；任务原文单条提交，与普通run共享互斥、取消及清理，不恢复历史授权。 */
+    runSkill(name: string, task: string, options?: {
+        signal?: AbortSignal;
+        role?: PrimaryModelRole;
+    }): AsyncIterable<SessionEvent>;
     /** 单次任务执行主体；调用方 return 的中止与 finally 清理由外层统一协调。 */
     private runOperation;
     /** 幂等销毁：卸载插件后发出 session:end；运行中拒绝，teardown 失败聚合抛出且不完成销毁。 */
     destroy(): Promise<void>;
     private assertIdle;
+    /** 实际请求、静态统计和手动压缩共用目录空间推导；先计正文、工具和非目录提示，再预算整段目录。 */
+    private createPromptAssembler;
+    /** 完整消息提交后完成技能审计；审计失败保留真实历史，停止本轮且不发布成功事件。 */
+    private commitSkills;
+    /** 显式加载仍按同一读取策略、精确缓存与宿主审批裁决；拒绝/取消/审计失败时不追加用户任务。 */
+    private authorizeSkill;
     /**
      * 计算最近一次内部模型请求的上下文占用；无 usage 时显式标注预算估算。
      * run 累计 promptTokens 会重复计算每一步都重发的历史，不能用于窗口占用率。
@@ -2164,4 +2505,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-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 };
+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 PreparedSkill, 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, SKILL_LIMITS, 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 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 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 ToolHardDenial, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolResultBlock, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, assembleCanonicalToolResults, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, createContextBudget, createDefaultLogSinks, createLogId, createMessageId, createRunCommandTool, defineTool, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatSkillCatalog, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isSkillName, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, listSkillResources, loadInstructions, normalizeHistory, normalizeSkillTools, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };