agentdev 0.1.9 → 0.2.1

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { E as EnrichedMessage, M as MessageTag, a as Message, L as LLMResponse, T as ToolCall, b as Tool, A as AgentConfig, I as InlineRenderTemplate, c as LogContextRef, d as ToolRenderConfig, H as HookInspectorSnapshot, e as AgentOverviewSnapshot, f as AgentInfo, N as Notification, U as UserInputRequest, g as UserInputResponse, h as UsageStatsSnapshot, i as TemplateSource, j as TemplateLoader, k as UsageStats, P as PlaceholderContext, l as UsageInfo, m as UserInputAction, n as LLMClient, o as MessageRole, p as AgentSession } from './types-CF5UsxD9.js';
-export { C as CacheStats, q as ContextMiddleware, D as DebugHubIPCMessage, r as TemplateComposer, s as TemplateError, t as TemplateLoaderOptions, u as TemplateResult, v as ToolMetadata, w as getDefaultUDSPath } from './types-CF5UsxD9.js';
+import { E as EnrichedMessage, M as MessageTag, a as Message, L as LLMResponse, T as ToolCall, b as Tool, A as AgentConfig, I as InlineRenderTemplate, c as LogContextRef, d as ToolRenderConfig, H as HookInspectorSnapshot, e as AgentOverviewSnapshot, f as AgentInfo, N as Notification, U as UserInputRequest, g as UserInputResponse, h as UsageStatsSnapshot, i as TemplateSource, j as TemplateLoader, k as UsageStats, P as PlaceholderContext, l as UsageInfo, m as UserInputAction, n as UserInputQuestion, o as UserInputChoiceAnswer, p as LLMClient, q as MessageRole, r as AgentSession } from './types-NVwNUVFR.js';
+export { C as CacheStats, s as ContextMiddleware, D as DebugHubIPCMessage, t as MessageUsage, u as TemplateComposer, v as TemplateError, w as TemplateLoaderOptions, x as TemplateResult, y as ToolMetadata, z as getDefaultUDSPath } from './types-NVwNUVFR.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { EventEmitter } from 'events';
+import { Diagnostic } from 'vscode-languageserver-types';
 import { IncomingMessage, ServerResponse } from 'http';
 
 /**
@@ -272,6 +274,54 @@ interface PackageInfo {
     /** 包根目录绝对路径 */
     root: string;
 }
+/**
+ * Feature Manifest 配置项
+ *
+ * 用于声明 Feature 在 Agent Project 级别可配置的静态参数。
+ * Claw 等消费端可根据该契约自动渲染表单。
+ */
+interface FeatureManifestSettingProperty {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'file' | 'directory' | 'group';
+    title: string;
+    description?: string;
+    default?: unknown;
+    options?: Array<{
+        label: string;
+        value: string | number | boolean;
+    }>;
+    placeholder?: string;
+    /** number 类型下的最小值 */
+    min?: number;
+    /** number 类型下的最大值 */
+    max?: number;
+    /** number 类型下的步进值 */
+    step?: number;
+    /** file 类型下的可接受文件类型，如 '.mp3,.wav' 或 'audio/*' */
+    accept?: string | string[];
+    /** directory 类型下的最大条目数 */
+    maxItems?: number;
+    /** type: 'group' 时的嵌套子属性 */
+    properties?: Record<string, FeatureManifestSettingProperty>;
+    /** 条件可见性：仅当同级指定属性值在 values 中时渲染此字段 */
+    showWhen?: {
+        property: string;
+        values: (string | number | boolean)[];
+    };
+}
+interface FeatureManifestDefinition {
+    schemaVersion: 1;
+    settings?: {
+        properties: Record<string, FeatureManifestSettingProperty>;
+        /** 有序分区，用于 UI 分组渲染。省略则平铺全部属性 */
+        sections?: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            /** 分区内属性 key 的显示顺序 */
+            properties: string[];
+        }>;
+    };
+}
 /**
  * Feature 初始化上下文
  */
@@ -383,6 +433,13 @@ interface AgentFeature {
      * ```
      */
     getRenderTemplates?(): Record<string, InlineRenderTemplate>;
+    /**
+     * 声明 Feature 的项目级静态配置契约（Manifest）
+     *
+     * 该契约回答“这个 Feature 平时怎么工作”，
+     * 与 Flow 节点中的 Mode（什么时候、以什么状态工作）是正交的。
+     */
+    getFeatureManifest?(): FeatureManifestDefinition | null;
     /**
      * 声明上下文注入器
      */
@@ -489,6 +546,13 @@ interface CallStartContext {
     /** Agent 实例（用于访问 setUserInput/getUserInput 等 API） */
     agent?: any;
 }
+/**
+ * Call 结束原因
+ *
+ * 让 @CallFinish 钩子能结构化地判断 call 为什么结束，
+ * 不再需要解析 response 字符串前缀。
+ */
+type CallFinishReason = 'completed' | 'interrupted' | 'api_error' | 'error' | 'max_steps' | 'continuation' | 'exception';
 /**
  * Call 结束上下文
  */
@@ -503,6 +567,8 @@ interface CallFinishContext {
     steps: number;
     /** 是否成功完成 */
     completed: boolean;
+    /** 结束原因 */
+    finishReason: CallFinishReason;
 }
 /**
  * Step 开始上下文
@@ -518,6 +584,8 @@ interface StepStartContext {
     context: Context;
     /** 原始用户输入 */
     input: string;
+    /** Agent 实例（用于访问当前会话中的 Feature、工具和输入状态） */
+    agent?: any;
 }
 /**
  * Step 结束上下文
@@ -719,6 +787,8 @@ declare function createTool(config: {
     parameters?: Record<string, any>;
     execute: (args: any, context?: any) => Promise<any>;
     render?: ToolRenderInput;
+    executionMode?: 'normal' | 'exclusive';
+    parallelizable?: boolean;
 }, sourceFile?: string): Tool;
 /**
  * 工具注册表 - 管理多个工具
@@ -726,24 +796,51 @@ declare function createTool(config: {
 declare class ToolRegistry {
     private tools;
     private enabled;
+    private disabled;
     private pendingDisabled;
+    private pendingRemoved;
     private sources;
+    private superseded;
     /**
      * 注册工具（默认启用，记录来源）
      */
     register(tool: Tool, source?: string): this;
     /**
-     * 禁用工具
+     * 禁用工具（LLM 可见，但执行时会被拦截）
      */
     disable(name: string): boolean;
     /**
      * 启用工具
      */
     enable(name: string): boolean;
+    /**
+     * 移除工具（LLM 不可见，承接旧 disable 行为）
+     */
+    remove(name: string): boolean;
+    /**
+     * 取消移除工具，恢复为启用状态
+     */
+    unremove(name: string): boolean;
     /**
      * 检查工具是否启用
      */
     isEnabled(name: string): boolean;
+    /**
+     * 检查工具是否禁用（屏蔽）
+     */
+    isDisabled(name: string): boolean;
+    /**
+     * 检查工具是否移除
+     */
+    isRemoved(name: string): boolean;
+    /**
+     * 检查工具是否为 exclusive 模式
+     */
+    isExclusive(name: string): boolean;
+    /**
+     * 检查工具是否可并行执行
+     */
+    isParallelizable(name: string): boolean;
     /**
      * 获取工具来源（调试用）
      */
@@ -753,6 +850,7 @@ declare class ToolRegistry {
      */
     getEntries(): Array<{
         tool: Tool;
+        state: 'enabled' | 'disabled' | 'removed' | 'superseded';
         enabled: boolean;
         source?: string;
     }>;
@@ -761,7 +859,7 @@ declare class ToolRegistry {
      */
     get(name: string): Tool | undefined;
     /**
-     * 获取所有工具（只返回启用的）
+     * 获取所有 LLM 可见工具（启用 + 禁用）
      */
     getAll(): Tool[];
     /**
@@ -811,11 +909,14 @@ declare class DebugHub {
     private nextId;
     private readonly processId;
     private pendingInputRequests;
+    private queuedInputHandler?;
+    private interruptHandler?;
     private activeInputRequests;
     private udsClient?;
     private udsPath;
     private workerPort;
     private clientReady;
+    private stopped;
     private registrationLock;
     private messageQueue;
     private reconnectTimer?;
@@ -889,6 +990,13 @@ declare class DebugHub {
     getCurrentAgentId(): string | null;
     getTransportMode(): 'viewer-worker' | 'claw';
     getCapabilities(): DebugCapabilities;
+    setQueuedInputHandler(handler?: (agentId: string, input: {
+        id: string;
+        text: string;
+        timestamp: number;
+    }) => void | Promise<void>): void;
+    setInterruptHandler(handler?: (agentId: string, clearQueue: boolean) => void | Promise<void>): void;
+    consumeQueuedInput(agentId: string, inputId: string): void;
     /**
      * 根据 Agent 实例获取其 ID
      */
@@ -943,6 +1051,45 @@ declare class DebugHub {
     private sendToWorker;
 }
 
+/**
+ * Continuation Request 类型定义
+ *
+ * 控制工具（如 checkpoint、rollback）通过 registerContinuationRequest()
+ * 登记一个 continuation request，使当前 onCall 在合法边界停止。
+ * 宿主（如 CallArbiter）通过 consumeContinuationRequest() 消费该请求，
+ * 决定是否在同一个逻辑 envelope 内启动下一个 onCall segment。
+ */
+/**
+ * Checkpoint continuation request
+ *
+ * Agent 建立了一个命名检查点，希望继续执行。
+ * 宿主应捕获当前 runtime snapshot 并将其与 checkpointId 关联，
+ * 然后启动 continuation segment。
+ */
+interface CheckpointContinuationRequest {
+    kind: 'checkpoint';
+    checkpointId: string;
+    /** 可选附加元数据（如 Agent 的自由备注） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Rollback continuation request
+ *
+ * Agent 希望回退到指定 checkpoint，并携带一个失败分支的摘要。
+ * 宿主应恢复到 checkpoint 的 runtime snapshot，
+ * 然后以摘要作为 continuation segment 的输入启动新的 onCall。
+ */
+interface RollbackContinuationRequest {
+    kind: 'rollback';
+    checkpointId: string;
+    /** Agent 生成的失败分支摘要 */
+    summary: string;
+}
+/**
+ * 受类型约束的 continuation request
+ */
+type CallContinuationRequest = CheckpointContinuationRequest | RollbackContinuationRequest;
+
 interface FeatureCheckpoint {
     featureName: string;
     snapshot: FeatureStateSnapshot;
@@ -960,6 +1107,26 @@ interface CallRollbackSnapshot {
     draftInput: string;
     runtime: AgentRuntimeSnapshot;
 }
+/**
+ * 命名检查点 — 由 Agent 自主建立的可恢复快照
+ *
+ * 与 CallRollbackSnapshot 的区别：
+ * - CallRollbackSnapshot 面向"回到某个用户 call 之前"，是 onCall 的副产品
+ * - NamedCheckpoint 面向"Agent 主动建立的恢复点"，有稳定 ID，可跨 segment 引用
+ *
+ * checkpoint 表示控制工具执行完成、tool result 已写入、
+ * 当前 segment 已完全结束之后的 runtime 状态（协议完整）。
+ */
+interface NamedCheckpoint {
+    /** 全局唯一的 checkpoint ID（由 Agent 提供） */
+    id: string;
+    /** 创建时间戳 */
+    createdAt: number;
+    /** 创建时的 callIndex */
+    sourceCallIndex: number;
+    /** 完整的 runtime snapshot */
+    runtime: AgentRuntimeSnapshot;
+}
 interface AgentSessionSnapshot {
     version: number;
     sessionId: string;
@@ -967,6 +1134,8 @@ interface AgentSessionSnapshot {
     agentType: string;
     runtime: AgentRuntimeSnapshot;
     rollbackHistory: CallRollbackSnapshot[];
+    /** 命名检查点列表（可选，用于 checkpoint/rollback 能力） */
+    namedCheckpoints?: NamedCheckpoint[];
 }
 interface SessionStore {
     save(sessionId: string, snapshot: AgentSessionSnapshot): Promise<string>;
@@ -1023,8 +1192,12 @@ declare class AgentBase {
     protected _callIndex: number;
     protected _callStartTimes: Map<number, number>;
     protected _callCheckpoints: CallRollbackCheckpoint[];
+    protected _namedCheckpoints: NamedCheckpoint[];
     protected usageStats: UsageStats;
+    private _continuationRequest;
     private _pendingInput;
+    private _abortController;
+    private _stepAutoSave?;
     private templateResolver?;
     private toolExecutor?;
     private reactRunner?;
@@ -1051,6 +1224,27 @@ declare class AgentBase {
      * @returns 当前输入缓存，如果未设置则返回空字符串
      */
     getUserInput(): string;
+    /**
+     * 登记一个 continuation request
+     *
+     * 控制工具（如 checkpoint、rollback）在正常完成执行后调用此方法，
+     * 使当前 onCall 在工具结果闭合后停止，并将请求传递给宿主。
+     *
+     * 该方法仅在 onCall 执行期间有效。onCall 开始时会清理上一次的遗留请求。
+     */
+    registerContinuationRequest(request: CallContinuationRequest): void;
+    /**
+     * 消费当前 continuation request（一次性）
+     *
+     * 宿主（如 CallArbiter）在 onCall 返回后调用此方法，
+     * 判断是否需要在同一逻辑 envelope 内启动下一个 segment。
+     *
+     * - 请求只能消费一次，消费后自动清除。
+     * - onCall 开始时也会清理上次未消费的请求。
+     *
+     * @returns 当前 continuation request，如果没有则返回 null
+     */
+    consumeContinuationRequest(): CallContinuationRequest | null;
     /**
      * 唯一的公开入口 - 执行 Agent
      */
@@ -1081,13 +1275,64 @@ declare class AgentBase {
      * 从会话快照恢复
      */
     restoreSessionSnapshot(snapshot: AgentSessionSnapshot): Promise<this>;
+    /**
+     * 中断正在运行的 onCall
+     * 会触发 AbortController，在下一个检查点（step 间或 tool 执行中）优雅停止
+     * 返回 true 表示成功触发中断，false 表示当前没有正在运行的 call
+     */
+    interrupt(): boolean;
+    /**
+     * 当前是否正在执行 onCall
+     */
+    isRunning(): boolean;
     rollbackToCall(callIndex: number): Promise<{
         draftInput: string;
     }>;
+    /**
+     * 创建一个命名检查点
+     *
+     * 捕获当前完整 runtime snapshot 并将其与 checkpointId 关联。
+     * 应在 onCall 完全退出后、由宿主（CallArbiter）的 checkpoint barrier 调用。
+     *
+     * @param id 全局唯一的 checkpoint ID
+     * @returns 创建的 NamedCheckpoint
+     */
+    createNamedCheckpoint(id: string): Promise<NamedCheckpoint>;
+    /**
+     * 回退到命名检查点
+     *
+     * 恢复到指定 checkpoint 的 runtime snapshot，
+     * 并剪除该 checkpoint 之后创建的所有命名检查点。
+     * 应在 onCall 完全退出后、由宿主（CallArbiter）的 rollback barrier 调用。
+     *
+     * @param id 目标 checkpoint ID
+     * @throws 如果 checkpoint 不存在
+     */
+    rollbackToNamedCheckpoint(id: string): Promise<void>;
+    /**
+     * 获取所有命名检查点（只读视图）
+     */
+    getNamedCheckpoints(): readonly NamedCheckpoint[];
+    /**
+     * 清除所有命名检查点
+     *
+     * 用于单 checkpoint 模式：创建新 checkpoint 前清除旧的。
+     */
+    clearNamedCheckpoints(): void;
     /**
      * 保存会话到持久化存储
      */
     saveSession(sessionId: string, store?: SessionStore): Promise<string>;
+    /**
+     * 启用 Step 级自动保存：每个 ReAct step 完成后自动将 session 快照写入磁盘。
+     * 不会替换 CallFinish 后的 saveSession 调用——后者仍作为兜底全量保存。
+     */
+    enableStepAutoSave(sessionId: string, store: SessionStore): void;
+    /**
+     * 禁用 Step 级自动保存
+     */
+    disableStepAutoSave(): void;
+    private _createStepSaveFn;
     /**
      * 从持久化存储加载会话
      */
@@ -1158,6 +1403,13 @@ declare class AgentBase {
      * 使用 Feature（链式调用）
      */
     use(feature: AgentFeature): this;
+    /**
+     * 彻底移除一个 Feature：移除其工具并从 features Map 中删除
+     *
+     * @example
+     * agent.removeFeature('subagent')  // 移除 SubAgentFeature
+     */
+    removeFeature(featureName: string): this;
     /**
      * 启用 Feature 的所有工具
      *
@@ -1172,6 +1424,13 @@ declare class AgentBase {
      * agent.disable('mcp')  // 禁用 MCP 工具
      */
     disable(featureName: string): this;
+    /**
+     * 移除 Feature 的所有工具（从 LLM 工具列表物理移除）
+     *
+     * @example
+     * agent.remove('mcp')  // 移除 MCP 工具
+     */
+    remove(featureName: string): this;
     /**
      * 检查 Feature 是否启用
      *
@@ -1187,6 +1446,35 @@ declare class AgentBase {
      * 确保 Feature 工具已注册
      */
     private ensureFeatureTools;
+    /**
+     * 为单个 Feature 执行工具注册、onInitiate 和 hooks 收集。
+     *
+     * 被 ensureFeatureTools() 和 mountFeature() 共用。
+     */
+    private initSingleFeature;
+    /**
+     * 动态挂载 Feature（运行时）
+     *
+     * 与 use() 不同，mountFeature 会在 agent 已初始化的情况下
+     * 立即对新 feature 执行工具注册、onInitiate 和 hooks 收集。
+     *
+     * 如果 agent 尚未初始化（未发生首次 onCall），feature 会被加入 Map，
+     * 后续由 ensureFeatureTools() 统一处理。
+     *
+     * @example
+     * await agent.mountFeature(new SomeFeature());
+     */
+    mountFeature(feature: AgentFeature): Promise<this>;
+    /**
+     * 在所有 Feature 工具注册完毕后、inspector snapshot 推送之前调用。
+     * 子类可重写此方法注册额外工具（如统一代理工具覆盖同名 feature 工具）。
+     */
+    protected onFeatureToolsReady(): Promise<void>;
+    /**
+     * 收集所有 Feature 自带的 skills
+     * 约定：Feature 目录下存在 skills/ 目录则自动发现
+     */
+    private collectFeatureSkills;
     /**
      * 解析相对路径（处理 ./ 和 ../）
      * @param baseDir 基础目录
@@ -1480,6 +1768,7 @@ declare class MCPConnectionManager {
     private sendDirectRequest;
     private normalizeToolCallResponse;
     private rejectAllPendingRequests;
+    private stopProcess;
     dispose(): Promise<void>;
 }
 
@@ -1521,6 +1810,8 @@ declare class MCPFeature implements AgentFeature {
     readonly description = "\u8FDE\u63A5 MCP \u670D\u52A1\u5668\u5E76\u628A\u53D1\u73B0\u5230\u7684\u8FDC\u7A0B\u80FD\u529B\u6302\u8F7D\u6210\u6807\u51C6\u5DE5\u5177\u3002";
     private readonly manager;
     private clients;
+    private readonly input?;
+    private readonly options;
     private config?;
     private mcpContext?;
     /**
@@ -1536,6 +1827,9 @@ declare class MCPFeature implements AgentFeature {
      */
     getTemplateNames(): string[];
     constructor(input?: MCPFeatureInput, options?: MCPFeatureOptions);
+    getFeatureManifest(): FeatureManifestDefinition;
+    private resolveFeatureConfig;
+    private resolveRuntimeConfig;
     /**
      * 获取同步工具（无）
      */
@@ -1543,7 +1837,7 @@ declare class MCPFeature implements AgentFeature {
     /**
      * 获取异步工具（需要连接 MCP 服务器）
      */
-    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    getAsyncTools(ctx: FeatureInitContext): Promise<Tool[]>;
     /**
      * 声明上下文注入器
      * 为所有 MCP 工具注入 _mcpContext
@@ -1592,6 +1886,8 @@ interface AuditFeatureConfig {
     dbPath?: string;
     /** 缓存有效期（天数，0 表示永久，默认 0） */
     cacheTtlDays?: number;
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
 }
 /**
  * AuditFeature 实现
@@ -1665,6 +1961,8 @@ declare class AuditFeature implements AgentFeature {
 interface AudioFeedbackConfig {
     /** 音频文件路径（相对于 feature 目录或绝对路径） */
     audioPath?: string;
+    /** 失败时的音频文件路径（留空时使用内置 error.mp3） */
+    errorAudioPath?: string;
     /** 是否启用音频反馈（默认：true） */
     enabled?: boolean;
     /** 音量（0-1，默认：0.5） */
@@ -1685,6 +1983,27 @@ declare class AudioFeedbackFeature implements AgentFeature {
     private readonly runtime;
     private logger?;
     constructor(config?: AudioFeedbackConfig);
+    getFeatureManifest(): FeatureManifestDefinition;
+    getFlowModes(): {
+        id: string;
+        title: string;
+        description: string;
+    }[];
+    getFlowVariables(): ({
+        key: string;
+        type: "boolean";
+        title: string;
+        description: string;
+        resolver: () => boolean;
+    } | {
+        key: string;
+        type: "number";
+        title: string;
+        description: string;
+        resolver: () => number;
+    })[];
+    applyFlowMode(modeId: string): void;
+    resetFlowModes(): void;
     /**
      * 公开 API：启用或禁用音频反馈
      */
@@ -1701,8 +2020,26 @@ declare class AudioFeedbackFeature implements AgentFeature {
     restoreState(snapshot: FeatureStateSnapshot): void;
     /**
      * 核心功能：在 call 完成时播放音频
+     *
+     * 根据 finishReason 区分成功 / 失败，播放不同音效：
+     * - completed → 成功音
+     * - interrupted / api_error / error / exception / max_steps → 失败音
+     * - continuation → 不播放（call 暂停续接，非真正结束）
      */
     playAudioOnCallFinish(ctx: CallFinishContext): Promise<void>;
+    /**
+     * 稳健的跨平台音频播放
+     *
+     * 替代第三方 sound-play 库。sound-play 在 Windows 上使用
+     * `Start-Sleep -s $player.NaturalDuration.TimeSpan.TotalSeconds` 来
+     * 等待播放结束，但 NaturalDuration 在 MediaPlayer.Open() 的异步加载
+     * 完成前会抛出 InvalidOperationException，导致 PowerShell 进程提前
+     * 退出、声音被截断——表现为"有时有声音有时没有"。
+     *
+     * 本方法在 Windows 上使用 Dispatcher.PushFrame 消息循环正确等待
+     * MediaOpened 事件，确保媒体加载完毕后再读取时长。
+     */
+    private _playSound;
 }
 
 interface MemoryFeatureConfig {
@@ -1712,6 +2049,8 @@ interface MemoryFeatureConfig {
     forceInject?: boolean;
     /** 读取 CLAUDE.md 的工作目录 */
     workspaceDir?: string;
+    /** 宿主资源目录；如果提供，优先从这里读取 CLAUDE.md */
+    resourceRoot?: string;
 }
 declare class MemoryFeature implements AgentFeature {
     readonly name = "memory";
@@ -1719,7 +2058,7 @@ declare class MemoryFeature implements AgentFeature {
     readonly source: string;
     readonly description = "\u81EA\u52A8\u8BFB\u53D6\u5E76\u6CE8\u5165\u9879\u76EE CLAUDE.md \u6587\u4EF6\u4F5C\u4E3A\u7CFB\u7EDF\u63D0\u793A\u8BCD\u3002";
     private filename;
-    private workspaceDir;
+    private sourceRoot;
     private _packageInfo;
     constructor(config?: MemoryFeatureConfig);
     /**
@@ -1761,6 +2100,12 @@ interface SkillMetadata {
 interface SkillsOptions {
     /** skills 目录，默认 cwd/.agentdev/skills */
     dir?: string;
+    /** 是否扫描 cwd/.agentdev/skills，默认 true */
+    scanAgentdevDir?: boolean;
+    /** 是否扫描 cwd/.claude/skills，默认 false */
+    scanClaudeDir?: boolean;
+    /** 额外 skills 目录列表，至多 5 个 */
+    extraDirs?: string[];
 }
 
 /**
@@ -1785,6 +2130,12 @@ interface SkillsOptions {
 interface SkillFeatureConfig extends SkillsOptions {
     /** Skills 目录路径 */
     dir?: string;
+    /** 是否扫描 .agentdev/skills，默认 true */
+    scanAgentdevDir?: boolean;
+    /** 是否扫描 .claude/skills，默认 false */
+    scanClaudeDir?: boolean;
+    /** 额外 skills 目录列表 */
+    extraDirs?: string[];
 }
 /**
  * Skill Feature 输入类型
@@ -1800,6 +2151,10 @@ declare class SkillFeature implements AgentFeature {
     readonly description = "\u53D1\u73B0\u672C\u5730 skills\uFF0C\u5E76\u63D0\u4F9B invoke_skill \u5DE5\u5177\u4E0E\u6280\u80FD\u6570\u636E\u6E90\u3002";
     private skillsDir?;
     private skills;
+    private featureSkills;
+    private scanAgentdevDir;
+    private scanClaudeDir;
+    private extraDirs;
     /**
      * 缓存包信息
      */
@@ -1817,6 +2172,35 @@ declare class SkillFeature implements AgentFeature {
      * 获取同步工具（invoke_skill）
      */
     getTools(): Tool[];
+    /**
+     * 向 Flow 暴露 Skills 相关变量
+     */
+    getFlowVariables(): ({
+        key: string;
+        type: string;
+        title: string;
+        description: string;
+        resolver: () => string[];
+    } | {
+        key: string;
+        type: string;
+        title: string;
+        description: string;
+        resolver: () => string;
+    })[];
+    /**
+     * 向 Flow 暴露可直接复用的节点 Prompt 模板
+     */
+    getFlowNodeTemplates(): {
+        id: string;
+        name: string;
+        description: string;
+        prompt: string;
+        tools: {
+            enable: string[];
+        };
+    }[];
+    getFeatureManifest(): FeatureManifestDefinition;
     /**
      * 声明上下文注入器
      * 为 invoke_skill 工具注入 _context.skills
@@ -1827,6 +2211,11 @@ declare class SkillFeature implements AgentFeature {
      * 执行 Skills 发现并注册数据源
      */
     onInitiate(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 注入来自其他 Feature 的 skills
+     * 由 Agent 在 onInitiate 之前调用
+     */
+    addFeatureSkills(skills: SkillMetadata[]): void;
     /**
      * 获取已加载的 Skills
      */
@@ -2218,6 +2607,10 @@ interface QQBotFeatureConfig {
     systemPrompt?: string;
     /** 附加配置（传递给 Gateway） */
     cfg?: Record<string, unknown>;
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
+    /** 宿主资源目录；默认从这里查找 .agentdev/qqbot.config.json */
+    resourceRoot?: string;
 }
 /**
  * QQBotFeature - QQ 机器人 Feature
@@ -2273,7 +2666,15 @@ declare class QQBotFeature implements AgentFeature {
 /**
  * Shell Feature 工具定义
  *
- * 提供 run_shell_command 工具，通过 Git Bash 执行 Shell 命令
+ * 提供 bash 工具，通过 Git Bash 执行 Shell 命令，支持 AbortSignal 中断。
+ *
+ * 改进点（照搬 Claude Code 的优秀实践）：
+ * 1. 命令引用：eval + 单引号包裹，彻底解决 syntax error near unexpected token '('
+ * 2. 非 -i 模式：去掉 interactive flag，消除 job control 警告
+ * 3. stdin redirect：自动添加 < /dev/null 防止命令挂起
+ * 4. Windows null rewrite：>nul → >/dev/null
+ * 5. 动态 Git Bash 路径检测
+ * 6. 输出截断：防止大输出撑爆 LLM 上下文
  */
 
 interface ShellExecutionResult {
@@ -2283,10 +2684,10 @@ interface ShellExecutionResult {
 }
 
 /**
- * Shell Feature - Git Bash 命令执行工具 + 安全删除/恢复工具
+ * Shell Feature - 双 Shell 命令执行工具 + 安全删除/恢复工具
  *
- * 通过 Git Bash 执行 Shell 命令，description 从内部配置加载
- * 提供安全删除、列表和恢复功能
+ * 支持 Git Bash 和 PowerShell 两种 Shell 环境。
+ * 根据用户配置和运行时探测结果，条件注册 Bash 和/或 PowerShell 工具。
  *
  * @example
  * ```typescript
@@ -2297,6 +2698,7 @@ interface ShellExecutionResult {
 
 interface ShellFeatureConfig {
     workspaceDir?: string;
+    workdir?: string;
     resourceRoot?: string;
 }
 /**
@@ -2306,13 +2708,20 @@ declare class ShellFeature implements AgentFeature {
     readonly name = "shell";
     readonly dependencies: string[];
     readonly source: string;
-    readonly description = "\u63D0\u4F9B bash \u6267\u884C\u80FD\u529B\uFF0C\u4EE5\u53CA\u5B89\u5168\u5220\u9664\u3001\u6062\u590D\u548C\u67E5\u770B\u5783\u573E\u6876\u5DE5\u5177\u3002";
+    readonly description = "\u63D0\u4F9B Bash/PowerShell \u547D\u4EE4\u6267\u884C\u80FD\u529B\uFF0C\u4EE5\u53CA\u5B89\u5168\u5220\u9664\u3001\u6062\u590D\u548C\u67E5\u770B\u5783\u573E\u6876\u5DE5\u5177\u3002";
     private bashDescription?;
+    private powershellDescription?;
     private _packageInfo;
     private readonly workspaceDir;
+    private readonly workdir;
     private readonly resourceRoot;
     constructor(config?: ShellFeatureConfig);
     run(command: string): Promise<ShellExecutionResult>;
+    getFeatureManifest(): FeatureManifestDefinition;
+    /**
+     * 解析 featureConfig 为结构化配置
+     */
+    private resolveShellConfig;
     /**
      * 获取包信息（统一打包方案）
      */
@@ -2326,9 +2735,9 @@ declare class ShellFeature implements AgentFeature {
      */
     getTools(): Tool[];
     /**
-     * 获取异步工具（bash 工具，加载 description）
+     * 获取异步工具（bash/powershell 工具，条件注册）
      */
-    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    getAsyncTools(ctx: FeatureInitContext): Promise<Tool[]>;
 }
 
 /**
@@ -2697,6 +3106,8 @@ declare class TodoFeature implements AgentFeature {
  * TTS Feature 配置选项
  */
 interface TTSFeatureConfig {
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
     /**
      * Python 可执行文件路径
      * 默认：项目 .venv 中的 Python 或系统 PATH 中的 python
@@ -2945,6 +3356,8 @@ declare class UserInputFeature implements AgentFeature {
      */
     getUserInput(prompt?: string, timeout?: number): Promise<string>;
     getUserInputEvent(prompt?: string, timeout?: number, actions?: UserInputAction[]): Promise<UserInputResponse>;
+    requestUserChoices(prompt: string, questions: UserInputQuestion[], timeout?: number): Promise<UserInputChoiceAnswer[]>;
+    private normalizeChoiceQuestions;
     getTools(): Tool[];
     onInitiate(_ctx: FeatureInitContext): Promise<void>;
     onDestroy(_ctx: FeatureContext): Promise<void>;
@@ -3024,6 +3437,8 @@ interface VisualUnderstandingResult {
  * VisualFeature 配置
  */
 interface VisualFeatureConfig {
+    /** 工作目录（默认 process.cwd()） */
+    workspaceDir?: string;
     /** LLM 服务地址（默认 localhost:7575） */
     baseUrl?: string;
     /** 视觉理解模型名称（默认 Qwen3.5-4B-Q5_K_M） */
@@ -3474,6 +3889,117 @@ declare class WebSearchFeature implements AgentFeature {
     getTemplateNames(): string[];
 }
 
+interface DiffStats {
+    filesChanged: string[];
+    insertions: number;
+    deletions: number;
+}
+
+/**
+ * FileHistoryFeature - 文件修改历史追踪与回退
+ *
+ * 独立 Feature，无侵入地接入 AgentDev 的 checkpoint/rollback 体系：
+ *
+ * - @ToolUse 反向钩子：在 write/edit 执行前自动备份文件
+ * - @CallStart 反向钩子：在每轮用户输入时创建快照
+ * - captureState/restoreState：与 Agent 的 CallRollback 集成（仅恢复内存状态）
+ * - rewindToSnapshot / rewindToLastSnapshot：用户显式触发的文件回退
+ *
+ * 文件回退是独立于对话回退的操作（与 Claude Code 的设计一致），
+ * 用户可以选择"仅回退代码"/"仅回退对话"/"两者都回退"。
+ *
+ * 使用方式（消费端，如 Claw）：
+ *   const fh = agent.features?.get('file-history');
+ *   if (fh) {
+ *     const snapshots = fh.getSnapshotList();
+ *     await fh.rewindToSnapshot(selectedId);
+ *   }
+ */
+
+interface FileHistoryFeatureConfig {
+    /** 覆盖工作区目录，默认 process.cwd() */
+    workspaceDir?: string;
+}
+type SnapshotInfo = {
+    id: number;
+    timestamp: number;
+    trackedFileCount: number;
+};
+declare class FileHistoryFeature implements AgentFeature {
+    readonly name = "file-history";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u8FFD\u8E2A\u6587\u4EF6\u4FEE\u6539\u5386\u53F2\uFF0C\u652F\u6301\u4EE3\u7801\u56DE\u9000\u5230\u4EFB\u610F\u8F6E\u6B21\u7684\u72B6\u6001\u3002";
+    private _packageInfo;
+    private logger;
+    private state;
+    private readonly workspaceDir;
+    constructor(config?: FileHistoryFeatureConfig);
+    getPackageInfo(): PackageInfo | null;
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    /**
+     * @ToolUse 反向钩子：在 write/edit 工具执行前备份文件
+     *
+     * 在所有 Feature 的 @ToolUse 钩子中，本钩子只关注 write/edit 两个工具，
+     * 其余一律放行 (Decision.Continue)。
+     */
+    trackFileEdits(ctx: ToolContext): Promise<DecisionResult>;
+    /**
+     * @CallStart 反向钩子：每轮用户输入时创建文件快照
+     *
+     * 第一次 CallStart 创建空快照，后续 CallStart 检测已追踪文件是否有变化，
+     * 有变化的创建新版本备份。
+     */
+    onCallStart(_ctx: any): Promise<void>;
+    /**
+     * 捕获当前文件历史状态（纯内存，不碰磁盘）
+     *
+     * 由 Agent 的 commitCallCheckpoint 调用。
+     * 保存快照元数据，使得 rollbackToCall 时能恢复到对应的文件历史状态。
+     */
+    captureState(): FeatureStateSnapshot;
+    /**
+     * 恢复文件历史状态（仅恢复内存，不恢复磁盘文件）
+     *
+     * 在三种场景下被调用：step rollback、call rollback、session load。
+     * 这里只恢复内存中的快照索引，不做文件回退。
+     * 文件回退由用户显式调用 rewindToSnapshot / rewindToLastSnapshot 触发。
+     */
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    /**
+     * 获取快照列表（供 UI 展示）
+     */
+    getSnapshotList(): SnapshotInfo[];
+    /**
+     * 获取当前追踪的文件数量
+     */
+    getTrackedFileCount(): number;
+    /**
+     * 获取快照数量
+     */
+    getSnapshotCount(): number;
+    /**
+     * 回退文件到指定快照
+     *
+     * @returns 被修改的文件路径列表
+     */
+    rewindToSnapshot(snapshotId: number): Promise<string[]>;
+    /**
+     * 回退文件到当前内存状态的最后一个快照
+     *
+     * 典型用法：先 rollbackToCall 恢复对话 + 内存状态，再调此方法恢复文件。
+     *   await agent.rollbackToCall(targetCallIndex)
+     *   const fh = agent.features?.get('file-history')
+     *   await fh?.rewindToLastSnapshot()
+     */
+    rewindToLastSnapshot(): Promise<string[]>;
+    /**
+     * 计算回退到指定快照的 diff 统计（预览用，不修改文件）
+     */
+    getDiffStats(snapshotId: number): Promise<DiffStats>;
+}
+
 interface OpencodeBasicFeatureConfig {
     workspaceDir?: string;
 }
@@ -3588,6 +4114,130 @@ declare class ExampleFeature implements AgentFeature {
     handleStepFinish(ctx: StepFinishDecisionContext): Promise<typeof Decision.Continue>;
 }
 
+/**
+ * LSP Feature 类型定义
+ */
+/**
+ * LSP Server handle returned by spawn functions
+ */
+interface LspServerHandle {
+    process: any;
+    initialization?: Record<string, any>;
+}
+/**
+ * Configuration for a single LSP server
+ */
+interface LspServerConfig {
+    disabled?: boolean;
+    binary?: string;
+    /** Launch mode override */
+    mode?: 'exec' | 'runtime';
+    /** Runtime type, only meaningful when mode='runtime' */
+    runtime?: 'nodejs' | 'uv';
+    /** npm package name for nodejs runtime (npx <package>) */
+    package?: string;
+    /** Package name for uv runtime (uv tool run <package>), if different */
+    uvPackage?: string;
+    /** Additional arguments passed to the server */
+    args?: string[];
+    command?: string[];
+    extensions?: string[];
+    env?: Record<string, string>;
+    initialization?: Record<string, any>;
+}
+/**
+ * LSP Feature configuration
+ */
+interface LspFeatureConfig {
+    workdir?: string;
+    binDir?: string;
+    disableDownload?: boolean;
+    /** Shared runtime binary paths */
+    runtimes?: {
+        nodejs?: string;
+        uv?: string;
+    };
+    servers?: Record<string, LspServerConfig>;
+}
+
+/**
+ * LSP Client - 通过 JSON-RPC 与 LSP 服务器通信
+ */
+
+/**
+ * LSP Client - 处理与 LSP 服务器的 JSON-RPC 通信
+ */
+declare class LspClient extends EventEmitter {
+    private serverID;
+    private handle;
+    private root;
+    private logger;
+    private connection;
+    private diagnostics;
+    private files;
+    constructor(serverID: string, handle: LspServerHandle, root: string, logger: {
+        info: (msg: string, data?: any) => void;
+        error: (msg: string, data?: any) => void;
+    });
+    private setupHandlers;
+    initialize(): Promise<void>;
+    get serverId(): string;
+    get clientRoot(): string;
+    getDiagnostics(): Map<string, Diagnostic[]>;
+    notifyOpen(filePath: string): Promise<void>;
+    waitForDiagnostics(filePath: string): Promise<void>;
+    definition(filePath: string, line: number, character: number): Promise<unknown>;
+    references(filePath: string, line: number, character: number): Promise<unknown>;
+    hover(filePath: string, line: number, character: number): Promise<unknown>;
+    documentSymbol(uri: string): Promise<unknown>;
+    workspaceSymbol(query: string): Promise<unknown>;
+    implementation(filePath: string, line: number, character: number): Promise<unknown>;
+    prepareCallHierarchy(filePath: string, line: number, character: number): Promise<unknown>;
+    incomingCalls(filePath: string, line: number, character: number): Promise<unknown>;
+    outgoingCalls(filePath: string, line: number, character: number): Promise<unknown>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * LSP Feature - Language Server Protocol 代码智能
+ *
+ * 为 AI agent 提供代码智能能力：跳转定义、查找引用、悬停提示等
+ * 支持 14 种语言的 LSP 服务器，每个支持 exec / runtime 两种启动模式
+ */
+
+declare class LspFeature implements AgentFeature {
+    readonly name = "lsp";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "LSP (Language Server Protocol) - \u63D0\u4F9B\u4EE3\u7801\u667A\u80FD\u80FD\u529B\uFF1A\u8DF3\u8F6C\u5B9A\u4E49\u3001\u67E5\u627E\u5F15\u7528\u3001\u60AC\u505C\u63D0\u793A\u7B49";
+    private config;
+    private _packageInfo;
+    private logger;
+    private clients;
+    private spawning;
+    private broken;
+    constructor(config?: LspFeatureConfig);
+    getPackageInfo(): PackageInfo | null;
+    getTemplateNames(): string[];
+    getTools(): Tool[];
+    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    onDestroy(): Promise<void>;
+    getFeatureManifest(): FeatureManifestDefinition;
+    captureState(): {
+        activeServerIds: string[];
+    };
+    restoreState(_state: any): void;
+    getWorkdir(): string;
+    hasServer(file: string): Promise<boolean>;
+    touchFile(file: string): Promise<void>;
+    executeOnFile<T>(file: string, fn: (client: LspClient) => Promise<T>): Promise<T[]>;
+    executeAll<T>(fn: (client: LspClient) => Promise<T>): Promise<T[]>;
+    private getClientsForFile;
+    private spawnServer;
+    private shutdownAll;
+}
+
 /**
  * 配置加载
  * 从 config 目录读取 JSON 配置文件
@@ -3596,6 +4246,17 @@ declare class ExampleFeature implements AgentFeature {
  * - loadConfig() - 异步加载（用于特殊场景）
  * - loadConfigSync() - 同步加载（推荐，用于 Agent 构造）
  */
+/**
+ * 自定义请求头条目
+ * - valueMode 'static': 使用 value 原样
+ * - valueMode 'uuid':    每次请求生成新的 UUID v4
+ * - valueMode 'random':  每次请求生成新的随机数
+ */
+interface CustomHeaderEntry {
+    key: string;
+    value: string;
+    valueMode?: 'static' | 'uuid' | 'random';
+}
 /**
  * 统一配置类型
  * 字段允许冗余，各 LLM 实现只取自己需要的
@@ -3609,6 +4270,10 @@ interface ModelConfig {
     thinkingBudgetTokens?: number;
     thinkingKeepTurns?: number;
     providerOptions?: Record<string, unknown>;
+    /** 追加到每次 LLM API 请求的自定义请求头 */
+    customHeaders?: CustomHeaderEntry[];
+    /** OpenAI 专用接口面：chat / responses */
+    apiSurface?: 'chat' | 'responses';
     region?: string;
     projectId?: string;
 }
@@ -3684,6 +4349,10 @@ interface BasicAgentConfig {
     tools?: Tool[];
     /** Skills 目录（可选，默认使用 .agentdev/skills） */
     skillsDir?: string;
+    /** SkillFeature 完整配置（可选，覆盖 skillsDir） */
+    skillConfig?: SkillFeatureConfig;
+    /** Feature 特定配置（可选） */
+    features?: AgentConfig['features'];
     /** 调试器和模板解析使用的项目根目录 */
     projectRoot?: string;
     /** 工具默认操作的工作目录 */
@@ -3863,13 +4532,19 @@ interface CompiledAnthropicRequest {
 }
 declare class AnthropicLLM implements LLMClient {
     private readonly apiKey;
-    private readonly modelName;
+    private readonly _modelName;
     private readonly baseUrl;
     private readonly maxTokens;
     private readonly thinkingBudgetTokens?;
     private readonly thinkingKeepTurns;
-    constructor(apiKey: string, modelName?: string, baseUrl?: string, maxTokens?: number, thinkingBudgetTokens?: number | undefined, thinkingKeepTurns?: number);
-    chat(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
+    private readonly customHeaders?;
+    private initPromise;
+    /** 返回当前 LLM 实例使用的模型名 */
+    get modelName(): string;
+    constructor(apiKey: string, _modelName?: string, baseUrl?: string, maxTokens?: number, thinkingBudgetTokens?: number | undefined, thinkingKeepTurns?: number, customHeaders?: CustomHeaderEntry[] | undefined);
+    chat(messages: Message[], tools: Tool[], options?: {
+        signal?: AbortSignal;
+    }): Promise<LLMResponse>;
 }
 declare function compileContextForAnthropic(messages: Message[], tools: Tool[]): CompiledAnthropicRequest;
 declare function createAnthropicLLM(config: AgentConfigFile): AnthropicLLM;
@@ -3883,14 +4558,20 @@ declare function createAnthropicLLM(apiKey: string, modelName: string, baseUrl?:
 
 declare class OpenAILLM implements LLMClient {
     private client;
-    private modelName;
+    private _modelName;
     private maxTokens?;
     private providerOptions?;
-    constructor(apiKey: string, modelName?: string, baseUrl?: string, maxTokens?: number, providerOptions?: Record<string, unknown>);
+    private customHeaders?;
+    private initPromise;
+    /** 返回当前 LLM 实例使用的模型名 */
+    get modelName(): string;
+    constructor(apiKey: string, modelName?: string, baseUrl?: string, maxTokens?: number, providerOptions?: Record<string, unknown>, customHeaders?: CustomHeaderEntry[]);
     /**
-     * 聊天 - 核心方法（内部使用流式处理）
+     * 聊天 - 核心方法（内部使用流式处理，带重试）
      */
-    chat(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
+    chat(messages: Message[], tools: Tool[], options?: {
+        signal?: AbortSignal;
+    }): Promise<LLMResponse>;
 }
 
 /**
@@ -3916,6 +4597,53 @@ declare function createOpenAILLM(config: AgentConfigFile): OpenAILLM;
 declare function createOpenAILLM(modelConfig: ModelConfig): OpenAILLM;
 declare function createOpenAILLM(apiKey: string, modelName: string, baseUrl?: string): OpenAILLM;
 
+/**
+ * OpenAI Responses LLM 适配器
+ *
+ * 只负责把框架的 Message / Tool 编译为 Responses 输入，
+ * 再把 Responses 输出收敛回 LLMResponse。
+ */
+
+type ResponsesRequest = {
+    model: string;
+    input: any[];
+    tools?: Array<Record<string, unknown>>;
+    max_output_tokens?: number;
+    parallel_tool_calls?: boolean;
+    reasoning?: Record<string, unknown>;
+    previous_response_id?: string;
+    store?: boolean;
+    text?: Record<string, unknown>;
+    include?: Array<string>;
+    [key: string]: unknown;
+};
+declare class OpenAIResponsesLLM implements LLMClient {
+    private client;
+    private _modelName;
+    private maxTokens?;
+    private thinkingBudgetTokens?;
+    private providerOptions?;
+    private customHeaders?;
+    private initPromise;
+    /** 返回当前 LLM 实例使用的模型名 */
+    get modelName(): string;
+    constructor(apiKey: string, modelName?: string, baseUrl?: string, maxTokens?: number, thinkingBudgetTokens?: number, providerOptions?: Record<string, unknown>, customHeaders?: CustomHeaderEntry[]);
+    chat(messages: Message[], tools: Tool[], options?: {
+        signal?: AbortSignal;
+    }): Promise<LLMResponse>;
+    private createResponsesCompletion;
+}
+interface CompileOpenAIResponsesOptions {
+    modelName?: string;
+    maxTokens?: number;
+    thinkingBudgetTokens?: number;
+    providerOptions?: Record<string, unknown>;
+}
+declare function compileContextForOpenAIResponses(messages: Message[], tools: Tool[], options?: CompileOpenAIResponsesOptions): ResponsesRequest;
+declare function createOpenAIResponsesLLM(config: AgentConfigFile): OpenAIResponsesLLM;
+declare function createOpenAIResponsesLLM(modelConfig: ModelConfig): OpenAIResponsesLLM;
+declare function createOpenAIResponsesLLM(apiKey: string, modelName: string, baseUrl?: string): OpenAIResponsesLLM;
+
 declare function createLLM(config: AgentConfigFile): LLMClient;
 declare function createLLM(modelConfig: ModelConfig): LLMClient;
 declare function createLLM(apiKey: string, modelName: string, provider?: string, baseUrl?: string): LLMClient;
@@ -4029,6 +4757,27 @@ declare class ViewerWorker {
      * 提交用户输入
      */
     private handlePostInput;
+    /**
+     * 排队用户输入（运行期间提交的消息）
+     */
+    private handleQueueInput;
+    /**
+     * 获取排队中的用户输入
+     */
+    private handleGetQueuedInputs;
+    /**
+     * 消费第一条排队消息
+     */
+    private handleDequeueInput;
+    private handleConsumeQueuedInput;
+    /**
+     * 中断正在运行的 Agent
+     */
+    private handleInterrupt;
+    /**
+     * 查询 Agent 是否正在运行
+     */
+    private handleGetRunning;
     /**
      * 获取或创建会话
      */
@@ -4062,6 +4811,12 @@ declare class ViewerWorker {
      */
     handlePushMessages(msg: any): void;
     private createEmptyOverview;
+    private createEmptyRuntimeState;
+    private cloneRuntimeState;
+    private getRuntimeStageFromLLMPhase;
+    private updateRuntimeStage;
+    private getSessionRuntimeState;
+    private getMergedOverview;
     /**
      * 检查消息是否发生变化
      */
@@ -4330,6 +5085,8 @@ declare function createListRenderer<T = any>(config: Omit<DataSourceRenderer<T>,
 declare function discover(options?: SkillsOptions): Promise<SkillMetadata[]>;
 
 interface LoadAllMCPConfigsOptions {
+    loadDefaultDir?: boolean;
+    extraConfigFiles?: string[];
     excludeServers?: string[];
 }
 declare function getDefaultMCPConfigDir(rootDir?: string): string;
@@ -4373,4 +5130,4 @@ declare function renderMCPToolCall(serverName: string, toolName: string, args: R
  */
 declare function renderMCPToolResult(result: any, success?: boolean): string;
 
-export { AgentBase as Agent, AgentConfig, type AgentConfigFile, type AgentFeature, AgentInfo, type AgentInitiateContext, AgentPool, AgentSession, type AgentSessionSnapshot, AnthropicLLM, AudioFeedbackFeature, AuditFeature, type AuditFeatureConfig, BasicAgent, type BasicAgentConfig, CallFinish, type CallFinishContext, CallStart, type CallStartContext, type CaptureResult, Context, type ContextInjector, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, Decision, type DecisionResult, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureContext, type FeatureInitContext, type FeatureStateSnapshot, FileSessionStore, type HookResult, InlineRenderTemplate, type KnownUser, LLMClient, LLMResponse, type LoadAllMCPConfigsOptions, type Logger, type LoggerBindings, MCPClient, type MCPClientConfig, type MCPConfig, type MCPConfigMountOptions, type MCPConnectionInfo, MCPConnectionManager, MCPConnectionState, type MCPDiscoveredTool, type MCPDiscoveredToolSet, MCPFeature, type MCPFeatureOptions, type MCPHTTPConfig, type MCPMountedConfigResult, type MCPMountedToolSet, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPStatistics, MCPToolAdapter, type MCPToolAdapterConfig, type MCPToolCreationOptions, type MCPToolDiscoveryOptions, type MCPToolManagementOptions, type MCPToolPatch, type MCPToolResult, MCP_RENDER_TEMPLATES, MemoryFeature, type MemoryFeatureConfig, Message, MessageRole, type ModelConfig, OpenAILLM, OpencodeBasicFeature, type PackageInfo, PlaceholderContext, PlaceholderResolver, PluginCompatFeature, QQBotFeature, type QQBotFeatureConfig, type QQBotSendOptions, type QQBotSendResult, type SessionStore, ShellFeature, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, StepFinish, type StepFinishedContext, StepStart, type StepStartContext, SubAgentFeature, type SystemContext$1 as SystemContext, TTSFeature, type TTSFeatureConfig, type TTSResult, type TTSState, type TaskStatus, TemplateLoader, TemplateSource, TodoFeature, type TodoFeatureConfig, type TodoTask, type TodoTaskSummary, Tool, ToolCall, type ToolContext, type ToolContextValue, ToolFinished, ToolRegistry, ToolRenderConfig, type ToolResult, ToolUse, UserInputFeature, type UserInputFeatureConfig, ViewerWorker, VisualFeature, type VisualFeatureConfig, type VisualUnderstandingResult, WebSearchFeature, type WebSearchFeatureConfig, type WindowInfo, assistant, compileContextForAnthropic, createAnthropicLLM, createDefaultMCPToolName, createLLM, createListRenderer, createLogger, createMCPTool, createMCPToolAdapters, createMCPToolsFromClient, createManagedMCPToolsFromClient, createMessage, createOpenAILLM, createTool, discover, discoverMCPTools, discoverManagedMCPTools, getClawRuntimeUrl, getDebugCapabilities, getDefaultMCPConfigDir, getDefaultSessionStore, getMCPRenderTemplate, getPackageInfoFromSource, installConsoleBridge, listConfigs, loadAllMCPConfigs, loadConfig, loadConfigSync, loadMCPConfigFromInput, mountMCPToolsFromConfig, renderMCPToolCall, renderMCPToolResult, resolveDebugTransportMode, runWithLogScope, system, toolResult, user };
+export { AgentBase as Agent, AgentConfig, type AgentConfigFile, type AgentFeature, AgentInfo, type AgentInitiateContext, AgentPool, AgentSession, type AgentSessionSnapshot, AnthropicLLM, AudioFeedbackFeature, AuditFeature, type AuditFeatureConfig, BasicAgent, type BasicAgentConfig, type CallContinuationRequest, CallFinish, type CallFinishContext, type CallFinishReason, CallStart, type CallStartContext, type CaptureResult, type CheckpointContinuationRequest, Context, type ContextInjector, type ContextSnapshot, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, Decision, type DecisionResult, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureContext, type FeatureInitContext, type FeatureManifestDefinition, type FeatureManifestSettingProperty, type FeatureStateSnapshot, FileHistoryFeature, type FileHistoryFeatureConfig, FileSessionStore, type HookResult, InlineRenderTemplate, type KnownUser, LLMClient, LLMResponse, type LoadAllMCPConfigsOptions, type Logger, type LoggerBindings, LspFeature, type LspFeatureConfig, MCPClient, type MCPClientConfig, type MCPConfig, type MCPConfigMountOptions, type MCPConnectionInfo, MCPConnectionManager, MCPConnectionState, type MCPDiscoveredTool, type MCPDiscoveredToolSet, MCPFeature, type MCPFeatureOptions, type MCPHTTPConfig, type MCPMountedConfigResult, type MCPMountedToolSet, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPStatistics, MCPToolAdapter, type MCPToolAdapterConfig, type MCPToolCreationOptions, type MCPToolDiscoveryOptions, type MCPToolManagementOptions, type MCPToolPatch, type MCPToolResult, MCP_RENDER_TEMPLATES, MemoryFeature, type MemoryFeatureConfig, Message, MessageRole, type ModelConfig, type NamedCheckpoint, OpenAILLM, OpenAIResponsesLLM, OpencodeBasicFeature, type PackageInfo, PlaceholderContext, PlaceholderResolver, PluginCompatFeature, QQBotFeature, type QQBotFeatureConfig, type QQBotSendOptions, type QQBotSendResult, type RollbackContinuationRequest, type SessionStore, ShellFeature, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, type SnapshotInfo, StepFinish, type StepFinishedContext, StepStart, type StepStartContext, SubAgentFeature, type SystemContext$1 as SystemContext, TTSFeature, type TTSFeatureConfig, type TTSResult, type TTSState, type TaskStatus, TemplateLoader, TemplateSource, TodoFeature, type TodoFeatureConfig, type TodoTask, type TodoTaskSummary, Tool, ToolCall, type ToolContext, type ToolContextValue, ToolFinished, ToolRegistry, ToolRenderConfig, type ToolResult, ToolUse, UserInputFeature, type UserInputFeatureConfig, ViewerWorker, VisualFeature, type VisualFeatureConfig, type VisualUnderstandingResult, WebSearchFeature, type WebSearchFeatureConfig, type WindowInfo, assistant, compileContextForAnthropic, compileContextForOpenAIResponses, createAnthropicLLM, createDefaultMCPToolName, createLLM, createListRenderer, createLogger, createMCPTool, createMCPToolAdapters, createMCPToolsFromClient, createManagedMCPToolsFromClient, createMessage, createOpenAILLM, createOpenAIResponsesLLM, createTool, discover, discoverMCPTools, discoverManagedMCPTools, getClawRuntimeUrl, getDebugCapabilities, getDefaultMCPConfigDir, getDefaultSessionStore, getMCPRenderTemplate, getPackageInfoFromSource, installConsoleBridge, listConfigs, loadAllMCPConfigs, loadConfig, loadConfigSync, loadMCPConfigFromInput, mountMCPToolsFromConfig, renderMCPToolCall, renderMCPToolResult, resolveDebugTransportMode, runWithLogScope, system, toolResult, user };