agentdev 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3836 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * 上下文查询构建器
+ *
+ * 提供链式 API 用于过滤和聚合消息
+ * 从 ContextFeature 移植到内核，作为 Context 的原生能力
+ */
+
+/**
+ * 上下文查询构建器
+ *
+ * 提供链式 API 用于过滤和聚合消息
+ */
+declare class ContextQuery {
+    private messages;
+    private indexes;
+    constructor(messages: EnrichedMessage[], indexes: Map<string, Set<string>>);
+    private result;
+    /**
+     * 按角色过滤
+     */
+    byRole(...roles: string[]): this;
+    /**
+     * 按标签过滤（可组合）
+     */
+    byTag(...tags: MessageTag[]): this;
+    /**
+     * 按工具名过滤（使用索引加速）
+     */
+    byTool(name: string): this;
+    /**
+     * 按任务 ID 过滤（使用索引加速）
+     */
+    byTask(taskId: string): this;
+    /**
+     * 按子代理 ID 过滤
+     */
+    byAgentId(agentId: string): this;
+    /**
+     * 按时间起点过滤
+     */
+    since(timestamp: number): this;
+    /**
+     * 按轮次范围过滤
+     */
+    inTurns(from: number, to?: number): this;
+    /**
+     * content 包含指定文本
+     */
+    containing(text: string): this;
+    /**
+     * 最近 N 条
+     */
+    recent(n: number): this;
+    /**
+     * 执行查询，返回结果数组
+     */
+    exec(): EnrichedMessage[];
+    /**
+     * 获取第一条
+     */
+    first(): EnrichedMessage | undefined;
+    /**
+     * 获取最后一条
+     */
+    last(): EnrichedMessage | undefined;
+    /**
+     * 计数
+     */
+    count(): number;
+    /**
+     * 时间跨度统计
+     */
+    timeSpan(): {
+        start: number;
+        end: number;
+        duration: number;
+    };
+    /**
+     * 按工具分组统计
+     */
+    groupByTool(): Record<string, number>;
+}
+
+/**
+ * 上下文管理器
+ * 管理消息数组，提供简单的操作方法
+ *
+ * 内核化能力：
+ * - 消息元数据包装（EnrichedMessage）
+ * - 内容解析和索引
+ * - 查询接口
+ */
+
+/**
+ * 工具执行结果（用于 addToolMessage）
+ */
+interface ToolExecResult {
+    success: boolean;
+    result: string | Record<string, any>;
+    error?: string;
+}
+/**
+ * 上下文快照类型 - 用于序列化
+ */
+interface ContextSnapshot {
+    version: number;
+    messages: Message[];
+    enrichedMessages?: EnrichedMessage[];
+    sequence?: number;
+}
+declare class Context {
+    private messages;
+    private enrichedMessages;
+    private indexes;
+    private sequence;
+    /**
+     * 添加一条消息
+     */
+    add(message: Message): this;
+    /**
+     * 添加多条消息
+     */
+    addAll(messages: Message[]): this;
+    /**
+     * 获取所有消息的副本
+     */
+    getAll(): Message[];
+    /**
+     * 获取消息数量
+     */
+    get length(): number;
+    /**
+     * 获取最后一条消息
+     */
+    getLast(): Message | undefined;
+    /**
+     * 清空消息
+     */
+    clear(): void;
+    /**
+     * 应用中间件处理消息
+     */
+    apply(middleware: (messages: Message[]) => Message[]): this;
+    /**
+     * 过滤消息
+     */
+    filter(predicate: (msg: Message) => boolean): Message[];
+    /**
+     * 切片
+     */
+    slice(start?: number, end?: number): Message[];
+    /**
+     * 序列化为快照
+     */
+    toJSON(): ContextSnapshot;
+    /**
+     * 从快照恢复
+     */
+    static fromJSON(snapshot: ContextSnapshot): Context;
+    /**
+     * 用快照原地恢复当前 Context
+     */
+    restore(snapshot: ContextSnapshot): this;
+    /**
+     * 序列化为 JSON 字符串
+     */
+    serialize(): string;
+    /**
+     * 从 JSON 字符串反序列化
+     */
+    static deserialize(json: string): Context;
+    /**
+     * 统一消息入口（内部方法）
+     */
+    private addMessage;
+    /**
+     * 添加用户消息
+     */
+    addUserMessage(content: string, turn: number): void;
+    /**
+     * 添加助手响应
+     */
+    addAssistantMessage(response: LLMResponse, turn: number): void;
+    /**
+     * 添加工具结果
+     */
+    addToolMessage(call: ToolCall, result: ToolExecResult, turn: number): void;
+    /**
+     * 添加系统消息
+     */
+    addSystemMessage(content: string, turn: number, source?: string): void;
+    /**
+     * 查询构建器
+     */
+    query(): ContextQuery;
+    /**
+     * 按轮次获取消息
+     */
+    getByTurn(turn: number): EnrichedMessage[];
+    /**
+     * 获取最近 N 条消息
+     */
+    getRecent(n: number): EnrichedMessage[];
+    /**
+     * 获取所有丰富化消息（内部使用）
+     */
+    getAllEnriched(): EnrichedMessage[];
+    /**
+     * 丰富化消息：添加元数据
+     */
+    private enrich;
+    /**
+     * 推断消息标签
+     */
+    private inferTags;
+    /**
+     * 解析 content 提取结构化信息
+     */
+    private parseContent;
+    /**
+     * 更新索引
+     */
+    private updateIndexes;
+    /**
+     * 从 enrichedMessages 重建索引
+     */
+    private rebuildIndexes;
+    /**
+     * 生成唯一 ID
+     */
+    private generateId;
+}
+
+/**
+ * 生命周期类型定义
+ * 定义 Agent 生命周期钩子相关的类型
+ */
+
+/**
+ * 决策状态（反向钩子返回值）
+ *
+ * 用于控制执行流程的三个状态
+ */
+declare enum Decision {
+    /** 批准：确认执行，跳过后续决策 */
+    Approve = "approve",
+    /** 拒绝：阻止执行，跳过后续决策 */
+    Deny = "deny",
+    /** 继续：交给下一个决策节点，使用默认行为 */
+    Continue = "continue"
+}
+/**
+ * 决策结果类型
+ */
+type DecisionResult = Decision | {
+    /** 决策动作 */
+    action: Decision;
+    /** 拒绝原因（用于日志/调试） */
+    reason?: string;
+    /** 附加元数据 */
+    metadata?: Record<string, any>;
+};
+/**
+ * Agent 初始化上下文
+ */
+interface AgentInitiateContext {
+    /** 消息上下文 */
+    context: Context;
+}
+/**
+ * Agent 销毁上下文
+ */
+interface AgentDestroyContext {
+    /** 消息上下文 */
+    context: Context;
+}
+/**
+ * Call 开始上下文
+ */
+interface CallStartContext {
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+    /** 是否首次调用 */
+    isFirstCall: boolean;
+    /** Agent 实例（用于访问 setUserInput/getUserInput 等 API） */
+    agent?: any;
+}
+/**
+ * Call 结束上下文
+ */
+interface CallFinishContext {
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+    /** 最终响应 */
+    response: string;
+    /** 执行的步骤数 */
+    steps: number;
+    /** 是否成功完成 */
+    completed: boolean;
+}
+/**
+ * Step 开始上下文
+ *
+ * Step 是 ReAct 循环中的单次迭代
+ */
+interface StepStartContext {
+    /** 当前步骤序号（从 0 开始） */
+    step: number;
+    /** 当前调用序号（用户交互次数，从 0 开始） */
+    callIndex: number;
+    /** 消息上下文 */
+    context: Context;
+    /** 原始用户输入 */
+    input: string;
+}
+/**
+ * Step 结束上下文
+ */
+interface StepFinishedContext extends StepStartContext {
+    /** LLM 响应 */
+    llmResponse: LLMResponse;
+    /** 执行的工具调用数量 */
+    toolCallsCount: number;
+}
+/**
+ * 工具上下文 - onToolUse 钩子的参数
+ *
+ * 提供工具调用时的完整上下文信息
+ */
+interface ToolContext {
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具定义 */
+    tool: Tool;
+    /** 当前步骤序号 */
+    step: number;
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文（可读写） */
+    context: Context;
+}
+/**
+ * 工具结果 - onToolFinished 钩子的参数
+ *
+ * 提供工具执行后的完整结果信息
+ */
+interface ToolResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 返回数据 */
+    data: unknown;
+    /** 错误信息（如果失败） */
+    error?: string;
+    /** 执行耗时(ms) */
+    duration: number;
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具定义 */
+    tool: Tool;
+    /** 当前步骤序号 */
+    step: number;
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+}
+/**
+ * 钩子返回值类型（扩展版）
+ *
+ * 统一的生命周期钩子控制流指令
+ *
+ * - { action: 'block' }: 阻止工具执行（工具级）
+ * - { action: 'allow' }: 允许工具执行（工具级）
+ * - undefined: 默认行为
+ */
+type HookResult = {
+    action: 'block';
+    reason?: string;
+} | {
+    action: 'allow';
+} | undefined;
+/**
+ * 子代理状态
+ */
+type SubAgentStatus = 'idle' | 'busy' | 'completed' | 'failed' | 'terminated';
+/**
+ * 子代理创建上下文
+ */
+interface SubAgentSpawnContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 初始指令 */
+    instruction: string;
+    /** 子代理实例 */
+    agent: AgentBase;
+}
+/**
+ * 子代理状态更新上下文
+ */
+interface SubAgentUpdateContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 旧状态 */
+    oldStatus: SubAgentStatus;
+    /** 新状态 */
+    newStatus: SubAgentStatus;
+    /** 执行结果（完成时） */
+    result?: string;
+    /** 错误信息（失败时） */
+    error?: string;
+}
+/**
+ * 子代理销毁上下文
+ */
+interface SubAgentDestroyContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 销毁原因 */
+    reason: 'manual' | 'parent_dispose' | 'error';
+}
+/**
+ * Agent 中断上下文
+ */
+interface AgentInterruptContext {
+    /** 中断原因 */
+    reason: 'max_steps_reached' | 'error' | 'cancelled';
+    /** 当前步骤序号 */
+    step: number;
+    /** 当前消息上下文 */
+    context: Context;
+}
+/**
+ * 子代理中断上下文
+ */
+interface SubAgentInterruptContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 中断原因 */
+    reason: 'max_steps_reached' | 'error' | 'cancelled';
+    /** 中断时的结果 */
+    result: string;
+}
+/**
+ * Step 结束决策上下文（反向钩子）
+ *
+ * 用于在 Step 结束后进行流程控制决策
+ */
+interface StepFinishDecisionContext extends StepFinishedContext {
+    /** 是否有活跃的子代理（busy 状态） */
+    hasActiveSubAgents?: boolean;
+    /** 是否有待处理的子代理消息 */
+    hasPendingMessages?: boolean;
+    /** 是否调用了 wait 工具 */
+    waitCalled?: boolean;
+}
+/**
+ * 工具完成决策上下文（反向钩子）
+ *
+ * 用于在工具执行完成后进行流程控制决策
+ */
+interface ToolFinishedDecisionContext extends ToolResult {
+    /** 刚才执行的工具名称 */
+    toolName: string;
+}
+
+/**
+ * 模板加载器
+ * 从文件系统读取和缓存模板文件
+ */
+
+/**
+ * 模板加载器
+ */
+declare class TemplateLoader {
+    private cache;
+    private searchDirs;
+    private enabled;
+    private stats;
+    constructor(options?: TemplateLoaderOptions);
+    /**
+     * 加载模板（异步）
+     */
+    load(templatePath: string): Promise<string>;
+    /**
+     * 加载模板（同步）
+     */
+    loadSync(templatePath: string): string;
+    /**
+     * 解析路径为绝对路径
+     * @param templatePath 模板路径
+     * @returns 解析后的绝对路径
+     * @throws TemplateError 如果文件格式不支持
+     */
+    resolvePath(templatePath: string): string;
+    /**
+     * 清除缓存
+     */
+    clearCache(pattern?: string): void;
+    /**
+     * 批量加载
+     */
+    loadMultiple(paths: string[]): Promise<Map<string, string>>;
+    /**
+     * 获取缓存统计
+     */
+    getStats(): CacheStats;
+    /**
+     * 检查是否是绝对路径
+     */
+    private isAbsolute;
+    /**
+     * 简单检查文件是否存在（同步，不进行实际IO）
+     */
+    private fileExists;
+}
+
+/**
+ * 模板组合器
+ * 支持流式 API 和灵活拼接
+ */
+
+/**
+ * 模板组合器
+ */
+declare class TemplateComposer {
+    private parts;
+    private separator;
+    private loader;
+    constructor(loader?: TemplateLoader);
+    /**
+     * 添加模板源
+     */
+    add(source: TemplateSource | TemplateComposer): this;
+    /**
+     * 添加模板源（别名）
+     */
+    append(source: TemplateSource | TemplateComposer): this;
+    /**
+     * 在头部插入
+     */
+    prepend(source: TemplateSource | TemplateComposer): this;
+    /**
+     * 添加多个模板源
+     */
+    addAll(...sources: (TemplateSource | TemplateComposer)[]): this;
+    /**
+     * 设置分隔符
+     */
+    joinWith(sep: string): this;
+    /**
+     * 条件添加
+     */
+    when(condition: boolean | ((ctx: PlaceholderContext) => boolean), source: TemplateSource | TemplateComposer): this;
+    /**
+     * 条件分支（三目运算语法糖）
+     */
+    either(condition: boolean | ((ctx: PlaceholderContext) => boolean), trueSource: TemplateSource | TemplateComposer, falseSource?: TemplateSource | TemplateComposer): this;
+    /**
+     * 嵌套子组合器
+     */
+    nest(composer: TemplateComposer): this;
+    /**
+     * 条件嵌套
+     */
+    nestIf(condition: boolean | ((ctx: PlaceholderContext) => boolean), composer: TemplateComposer): this;
+    /**
+     * 清空所有模板
+     */
+    clear(): this;
+    /**
+     * 获取当前模板数量
+     */
+    get size(): number;
+    /**
+     * 获取所有模板源
+     */
+    getSources(): TemplateSource[];
+    /**
+     * 渲染最终模板
+     */
+    render(context?: PlaceholderContext): Promise<TemplateResult>;
+    /**
+     * 渲染单个片段
+     */
+    private renderPart;
+    /**
+     * 转换为 TemplatePart
+     */
+    private toPart;
+}
+
+/**
+ * 提示词模板系统 - 核心类型定义
+ */
+/**
+ * 模板源
+ * - string: 硬编码字符串
+ * - { file: string }: 文件路径
+ * - [dataSourceName: string]: 数据源名称（如 skills, tasks 等）
+ * - TemplateComposer: 组合模板
+ *
+ * @example
+ * ```typescript
+ * // 静态字符串
+ * 'Hello {{name}}'
+ *
+ * // 文件
+ * { file: 'prompts/system.md' }
+ *
+ * // 数据源（列表渲染）
+ * { skills: '- **{{name}}**: {{description}}' }
+ * { tasks: '- [{{title}}](#{{id}}) ({{priority}})' }
+ *
+ * // 条件渲染
+ * { conditional: { part: { file: 'advanced.md' }, condition: (ctx) => ctx.advanced } }
+ * ```
+ */
+type TemplateSource = string | {
+    file: string;
+} | {
+    conditional: ConditionalSource;
+} | {
+    [dataSourceName: string]: string;
+} | TemplateComposer;
+/**
+ * 条件源配置
+ */
+interface ConditionalSource {
+    /** 条件模板源 */
+    part: TemplateSource;
+    /** 条件函数（true 时渲染） */
+    condition: (context: PlaceholderContext) => boolean;
+}
+/**
+ * 占位符上下文 - 变量替换的键值对
+ * 支持原始类型和复杂对象（用于数据源渲染）
+ */
+type PlaceholderContext = Record<string, string | number | boolean | undefined | object>;
+/**
+ * 模板渲染结果
+ */
+interface TemplateResult {
+    /** 渲染后的内容 */
+    content: string;
+    /** 使用的源文件列表（用于调试） */
+    sources: string[];
+}
+/**
+ * 模板加载器配置
+ */
+interface TemplateLoaderOptions {
+    /** 缓存启用状态，默认 true */
+    cacheEnabled?: boolean;
+    /** 模板搜索目录（相对于项目根目录） */
+    searchDirs?: string[];
+    /** 项目根目录（自动检测） */
+    projectRoot?: string;
+}
+/**
+ * 缓存统计
+ */
+interface CacheStats {
+    size: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+}
+/**
+ * 模板相关错误
+ */
+declare class TemplateError extends Error {
+    code: 'FILE_NOT_FOUND' | 'INVALID_PATH' | 'READ_ERROR' | 'UNSUPPORTED_FORMAT';
+    path?: string | undefined;
+    constructor(message: string, code: 'FILE_NOT_FOUND' | 'INVALID_PATH' | 'READ_ERROR' | 'UNSUPPORTED_FORMAT', path?: string | undefined);
+}
+
+/**
+ * UsageStats - 用量统计系统
+ *
+ * 职责：
+ * - 记录 LLM 调用的 token 用量
+ * - 聚合 session/call/step 三级统计
+ * - 提供快照序列化和恢复
+ * - 格式化用量报告
+ *
+ * 设计原则：
+ * - 框架内置，不是 Feature
+ * - 自动收集，不需要手动干预
+ * - 快照包含 session 级数据，用于会话恢复
+ */
+/**
+ * 统一用量格式（兼容 Anthropic 和 OpenAI）
+ */
+interface UsageInfo$1 {
+    /** 输入 token 数 */
+    inputTokens: number;
+    /** 输出 token 数 */
+    outputTokens: number;
+    /** 总 token 数 */
+    totalTokens: number;
+    /** 创建缓存消耗的 token 数 */
+    cacheCreationTokens?: number;
+    /** 从缓存读取的 token 数 */
+    cacheReadTokens?: number;
+    /** 推理 token 数（prompt_tokens_details 或 completion_tokens_details） */
+    reasoningTokens?: number;
+    /** 音频 token 数 */
+    audioTokens?: number;
+}
+/**
+ * 单次 Call 用量汇总
+ */
+interface CallUsageSummary {
+    callIndex: number;
+    totalUsage: UsageInfo$1;
+    stepCount: number;
+    cacheHitRequests: number;
+    startTime: number;
+    endTime?: number;
+}
+/**
+ * Session 用量快照（用于序列化）
+ */
+interface UsageStatsSnapshot {
+    /** Session 级累计用量 */
+    totalUsage: UsageInfo$1;
+    /** 各 Call 的用量汇总 */
+    calls: CallUsageSummary[];
+    /** 总请求数（LLM 调用次数） */
+    totalRequests: number;
+    /** 命中缓存的请求数（request-level） */
+    totalCacheHitRequests: number;
+}
+/**
+ * 用量统计类
+ */
+declare class UsageStats {
+    /** Session 级累计用量 */
+    private totalUsage;
+    /** 当前活跃 Call 的用量记录 */
+    private currentCallUsage;
+    /** 总 LLM 调用次数 */
+    private totalRequests;
+    /** 命中缓存的总请求数 */
+    private totalCacheHitRequests;
+    /** 当前 Call 的 Step 记录（临时，用于聚合） */
+    private currentStepRecords;
+    /**
+     * 记录一次 LLM 调用的用量
+     * @param callIndex Call 序号
+     * @param step Step 序号
+     * @param usage 用量数据
+     */
+    record(callIndex: number, step: number, usage: UsageInfo$1): void;
+    /**
+     * 标记 Call 结束
+     * @param callIndex Call 序号
+     */
+    endCall(callIndex: number): void;
+    /**
+     * 获取 Session 级累计用量
+     */
+    getTotalUsage(): UsageInfo$1;
+    /**
+     * 获取指定 Call 的用量汇总
+     * @param callIndex Call 序号
+     */
+    getCallUsage(callIndex: number): CallUsageSummary | undefined;
+    /**
+     * 获取所有 Call 的用量汇总
+     */
+    getAllCallUsage(): CallUsageSummary[];
+    /**
+     * 获取总请求次数
+     */
+    getTotalRequests(): number;
+    getTotalCacheHitRequests(): number;
+    /**
+     * 获取格式化的用量报告
+     */
+    getReport(): string;
+    /**
+     * 创建快照（用于序列化）
+     */
+    toSnapshot(): UsageStatsSnapshot;
+    /**
+     * 从快照恢复
+     */
+    fromSnapshot(snapshot: UsageStatsSnapshot): void;
+    /**
+     * 重置统计（谨慎使用）
+     */
+    reset(): void;
+}
+
+/**
+ * 基础类型定义
+ * 所有类型集中在这里，简单直观
+ */
+/**
+ * 通知分类
+ * - state: 覆盖式更新（如 LLM 字符计数）
+ * - event: 追加式记录（如工具开始/完成）
+ */
+type NotificationCategory = 'state' | 'event';
+/**
+ * 通知基础接口
+ */
+interface Notification {
+    type: string;
+    category: NotificationCategory;
+    timestamp: number;
+    data: unknown;
+}
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+type DebugLogDeliveryReason = 'hub' | 'hub-unavailable' | 'no-agent-context';
+interface DebugLogDelivery {
+    hub: boolean;
+    console: boolean;
+    reason: DebugLogDeliveryReason;
+}
+interface LogContextRef {
+    agentId?: string;
+    agentName?: string;
+    parentAgentId?: string;
+    callIndex?: number;
+    step?: number;
+    toolName?: string;
+    toolCallId?: string;
+    feature?: string;
+    lifecycle?: string;
+    hookMethod?: string;
+    hookKind?: 'forward' | 'reverse';
+    sourceFile?: string;
+    sourceLine?: number;
+    tags?: string[];
+    [key: string]: unknown;
+}
+interface DebugLogEntry {
+    id: string;
+    timestamp: number;
+    level: LogLevel;
+    message: string;
+    namespace: string;
+    context: LogContextRef;
+    data?: unknown;
+    delivery: DebugLogDelivery;
+}
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool' | string;
+interface Message {
+    role: MessageRole;
+    content: string;
+    turn?: number;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    reasoning?: string;
+    thinkingBlocks?: ThinkingBlock[];
+}
+interface ThinkingBlock {
+    signature: string;
+    thinking: string;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+}
+/**
+ * 统一用量格式（兼容 Anthropic 和 OpenAI）
+ */
+interface UsageInfo {
+    /** 输入 token 数 */
+    inputTokens: number;
+    /** 输出 token 数 */
+    outputTokens: number;
+    /** 总 token 数 */
+    totalTokens: number;
+    /** 创建缓存消耗的 token 数 */
+    cacheCreationTokens?: number;
+    /** 从缓存读取的 token 数 */
+    cacheReadTokens?: number;
+    /** 推理 token 数 */
+    reasoningTokens?: number;
+    /** 音频 token 数 */
+    audioTokens?: number;
+}
+interface LLMResponse {
+    content: string;
+    toolCalls?: ToolCall[];
+    reasoning?: string;
+    thinkingBlocks?: ThinkingBlock[];
+    /** 用量统计（可选） */
+    usage?: UsageInfo;
+}
+/**
+ * 渲染模板项
+ * 可以是字符串模板或函数模板
+ */
+type RenderTemplateItem = string | RenderTemplateFn;
+/**
+ * 渲染模板函数类型
+ */
+type RenderTemplateFn = (data: Record<string, any>, success?: boolean) => string;
+/**
+ * 内联渲染模板
+ * 直接定义在工具中的渲染模板（无需引用预设模板）
+ */
+interface InlineRenderTemplate {
+    call: RenderTemplateItem;
+    result: RenderTemplateItem;
+}
+interface ToolRenderConfig {
+    /** 调用时的渲染模板（字符串引用或内联模板） */
+    call?: string | InlineRenderTemplate;
+    /** 结果时的渲染模板（字符串引用或内联模板） */
+    result?: string | InlineRenderTemplate;
+}
+interface Tool {
+    name: string;
+    description: string;
+    parameters?: Record<string, any>;
+    execute: (args: any, context?: any) => Promise<any>;
+    /** 可选：渲染配置 */
+    render?: ToolRenderConfig;
+}
+interface LLMClient {
+    chat(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
+}
+
+interface AgentConfig {
+    llm: LLMClient;
+    tools?: Tool[];
+    maxTurns?: number;
+    systemMessage?: string | TemplateSource;
+    name?: string;
+    /**
+     * Feature 配置
+     *
+     * 新的声明式 Feature 注册方式
+     */
+    features?: {
+        /** 启用的 Feature 列表 */
+        enabled?: string[];
+        /** Feature 特定配置 */
+        [key: string]: unknown;
+    };
+}
+type ContextMiddleware = (messages: Message[]) => Message[];
+/**
+ * Agent 注册信息（Hub 端）
+ */
+interface AgentInfo {
+    id: string;
+    name: string;
+    registeredAt: number;
+}
+/**
+ * 工具元数据（用于前端渲染）
+ */
+interface ToolMetadata {
+    name: string;
+    description: string;
+    render: {
+        call: string | InlineRenderTemplate;
+        result: string | InlineRenderTemplate;
+        inlineCall?: InlineRenderTemplate;
+        inlineResult?: InlineRenderTemplate;
+    };
+}
+interface HookSourceLocation {
+    file?: string;
+    line?: number;
+    column?: number;
+    display: string;
+}
+interface HookEntryMetadata {
+    order: number;
+    featureName: string;
+    methodName: string;
+    lifecycle: string;
+    kind: 'decision' | 'notify';
+    source?: HookSourceLocation;
+    description?: string;
+}
+interface HookLifecycleSnapshot {
+    lifecycle: string;
+    kind: 'decision' | 'notify';
+    entries: HookEntryMetadata[];
+}
+interface FeatureInspectorSnapshot {
+    name: string;
+    enabled: boolean;
+    status: 'enabled' | 'disabled' | 'partial';
+    hookCount: number;
+    toolCount: number;
+    enabledToolCount: number;
+    source?: string;
+    description?: string;
+    tools: Array<{
+        name: string;
+        description: string;
+        enabled: boolean;
+        renderCall?: string;
+        renderResult?: string;
+    }>;
+}
+interface HookInspectorSnapshot {
+    lifecycleOrder: string[];
+    features: FeatureInspectorSnapshot[];
+    hooks: HookLifecycleSnapshot[];
+}
+interface AgentContextMetrics {
+    messageCount: number;
+    charCount: number;
+    toolCallCount: number;
+    turnCount: number;
+}
+interface AgentOverviewSnapshot {
+    updatedAt: number;
+    context: AgentContextMetrics;
+    usageStats: UsageStatsSnapshot;
+}
+/**
+ * Agent 会话数据（Worker 端）
+ */
+interface AgentSession {
+    id: string;
+    name: string;
+    messages: Message[];
+    tools: ToolMetadata[];
+    createdAt: number;
+    lastActive: number;
+    projectRoot?: string;
+    currentState: Notification | null;
+    events: Notification[];
+    lastEventCount: number;
+    logs: DebugLogEntry[];
+    clientId?: string;
+    _lastMessageSig?: string;
+    hookInspector?: HookInspectorSnapshot;
+    overview?: AgentOverviewSnapshot;
+}
+/**
+ * DebugHub IPC 消息类型（主进程 → Worker）
+ * 使用 discriminated union 确保类型安全
+ */
+type DebugHubIPCMessage = RegisterAgentMsg | UpdateAgentInspectorMsg | UpdateAgentOverviewMsg | PushMessagesMsg | RegisterToolsMsg | SetCurrentAgentMsg | UnregisterAgentMsg | PushNotificationMsg | RequestInputMsg | StopMsg;
+/**
+ * 注册新 Agent
+ */
+interface RegisterAgentMsg {
+    type: 'register-agent';
+    agentId: string;
+    name: string;
+    createdAt: number;
+    projectRoot?: string;
+    featureTemplates?: Record<string, string>;
+    hookInspector?: HookInspectorSnapshot;
+    overview?: AgentOverviewSnapshot;
+    activeInputRequest?: ActiveInputRequest;
+}
+interface UpdateAgentInspectorMsg {
+    type: 'update-agent-inspector';
+    agentId: string;
+    hookInspector: HookInspectorSnapshot;
+}
+interface UpdateAgentOverviewMsg {
+    type: 'update-agent-overview';
+    agentId: string;
+    overview: AgentOverviewSnapshot;
+}
+/**
+ * 推送 Agent 消息
+ */
+interface PushMessagesMsg {
+    type: 'push-messages';
+    agentId: string;
+    messages: Message[];
+}
+/**
+ * 注册 Agent 工具
+ */
+interface RegisterToolsMsg {
+    type: 'register-tools';
+    agentId: string;
+    tools: Tool[];
+}
+/**
+ * 切换当前选中的 Agent
+ */
+interface SetCurrentAgentMsg {
+    type: 'set-current-agent';
+    agentId: string;
+}
+/**
+ * 活跃的输入请求（用于重连后恢复）
+ */
+interface ActiveInputRequest {
+    requestId: string;
+    prompt: string;
+    placeholder?: string;
+    initialValue?: string;
+    actions?: UserInputAction[];
+    timestamp: number;
+}
+/**
+ * 注销 Agent
+ */
+interface UnregisterAgentMsg {
+    type: 'unregister-agent';
+    agentId: string;
+}
+/**
+ * 停止 Worker
+ */
+interface StopMsg {
+    type: 'stop';
+}
+/**
+ * 推送通知
+ */
+interface PushNotificationMsg {
+    type: 'push-notification';
+    agentId: string;
+    notification: Notification;
+}
+/**
+ * 请求用户输入
+ */
+interface RequestInputMsg {
+    type: 'request-input';
+    agentId: string;
+    requestId: string;
+    prompt: string;
+    timeout?: number;
+    placeholder?: string;
+    initialValue?: string;
+    actions?: UserInputAction[];
+}
+interface UserInputAction {
+    id: string;
+    label: string;
+    kind?: 'rollback' | 'custom';
+    variant?: 'primary' | 'secondary' | 'danger';
+    payload?: Record<string, unknown>;
+}
+interface UserInputRequest {
+    prompt: string;
+    placeholder?: string;
+    initialValue?: string;
+    actions?: UserInputAction[];
+}
+interface UserInputResponse {
+    kind: 'text' | 'action';
+    text?: string;
+    actionId?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * 消息标签枚举
+ *
+ * 用于快速分类和过滤消息，一条消息可能有多个标签
+ */
+type MessageTag = 'user' | 'system' | 'assistant' | 'tool-call' | 'tool-result' | 'sub-agent' | 'reminder';
+/**
+ * 解析结果结构
+ *
+ * 从消息 content 中提取的结构化信息
+ */
+interface ParsedContent {
+    /** 从 content 提取的任务 ID（正则匹配 "taskId":"xxx"） */
+    taskIds: string[];
+    /** 从 content 提取的工具调用名称（从 toolCalls 或 content 解析） */
+    toolCalls: string[];
+    /** @ 提及的内容 */
+    mentions: string[];
+    /** 用户可继承扩展更多字段 */
+    [key: string]: any;
+}
+/**
+ * 扩展的消息结构
+ *
+ * 在原始 Message 基础上添加元数据
+ * 不破坏现有 Message 类型，保证 LLM 调用兼容性
+ */
+interface EnrichedMessage extends Message {
+    /** 唯一标识（用于索引关联） */
+    id: string;
+    /** 消息产生时间戳（毫秒） */
+    timestamp: number;
+    /** 所属 ReAct 循环轮次（从 0 开始） */
+    turn: number;
+    /** 全局消息序号（从 0 开始递增） */
+    sequence: number;
+    /** 来源 Agent ID（子代理消息） */
+    agentId?: string;
+    /** 来源 Feature（如 'todo-feature'，仅 reminder 等） */
+    source?: string;
+    /** 消息分类标签（用于快速查询） */
+    tags: MessageTag[];
+    /** 从 content 中提取的结构化信息 */
+    parsed: ParsedContent;
+}
+
+/**
+ * 平台检测后的 UDS 路径
+ */
+declare function getDefaultUDSPath(): string;
+
+interface LoggerBindings extends LogContextRef {
+    tags?: string[];
+}
+interface Logger {
+    trace(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    child(options?: LoggerBindings & {
+        namespace?: string;
+    }): Logger;
+}
+
+/**
+ * Feature 上下文值类型
+ */
+type ToolContextValue = Record<string, unknown>;
+/**
+ * Feature 上下文注入器
+ * 返回要注入到 tool.execute() 的额外参数
+ */
+type ContextInjector = (call: ToolCall) => ToolContextValue;
+/**
+ * Feature 运行时上下文
+ */
+interface FeatureContext {
+    agentId: string;
+    config: AgentConfig;
+}
+/**
+ * Feature 快照状态
+ *
+ * 第一阶段只支持显式白名单状态：
+ * - Feature 自己决定要保存什么
+ * - 未声明的状态一律不保证恢复
+ */
+type FeatureStateSnapshot = unknown;
+/**
+ * 包信息
+ */
+interface PackageInfo {
+    /** 包名，如 '@agentdev/shell-feature' 或 'agentdev' */
+    name: string;
+    /** 版本号（可选） */
+    version?: string;
+    /** 包根目录绝对路径 */
+    root: string;
+}
+/**
+ * Feature 初始化上下文
+ */
+interface FeatureInitContext {
+    /** Agent ID */
+    agentId: string;
+    /** Agent 配置 */
+    config: AgentConfig;
+    /** Feature 级结构化日志 */
+    logger: Logger;
+    /** Feature 特定配置 */
+    featureConfig?: unknown;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+    /** 注册工具 */
+    registerTool(tool: Tool): void;
+}
+/**
+ * Feature 初始化上下文
+ */
+interface FeatureInitContext {
+    /** Agent ID */
+    agentId: string;
+    /** Agent 配置 */
+    config: AgentConfig;
+    /** Feature 级结构化日志 */
+    logger: Logger;
+    /** Feature 特定配置 */
+    featureConfig?: unknown;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+    /** 注册工具 */
+    registerTool(tool: Tool): void;
+}
+/**
+ * Agent Feature 接口
+ *
+ * 可外挂的功能模块，提供工具和上下文注入
+ */
+interface AgentFeature {
+    /** Feature 名称 */
+    readonly name: string;
+    /** 依赖的其他 Feature */
+    readonly dependencies?: string[];
+    /** 可选：用于调试器展示的源码位置 */
+    readonly source?: string;
+    /** 可选：用于调试器展示的 Feature 描述 */
+    readonly description?: string;
+    /**
+     * 获取同步工具（已知工具列表）
+     */
+    getTools?(): Tool[];
+    /**
+     * 获取异步工具（需要连接、发现等）
+     */
+    getAsyncTools?(ctx: FeatureInitContext): Promise<Tool[]>;
+    /**
+     * 获取包信息
+     *
+     * 返回 Feature 所在的包信息（包名、版本、根目录）
+     * 用于统一模板路径解析和包管理
+     *
+     * @returns 包信息，如果 Feature 不属于任何包则返回 null
+     *
+     * @example
+     * ```typescript
+     * getPackageInfo(): PackageInfo | null {
+     *   return {
+     *     name: '@agentdev/shell-feature',
+     *     version: '1.0.0',
+     *     root: '/path/to/package/root'
+     *   };
+     * }
+     * ```
+     */
+    getPackageInfo?(): PackageInfo | null;
+    /**
+     * 获取模板名称列表
+     *
+     * 返回 Feature 提供的模板名称列表（不含扩展名）
+     * 模板文件必须位于 {packageRoot}/dist/templates/{templateName}.render.js
+     *
+     * @returns 模板名称数组
+     *
+     * @example
+     * ```typescript
+     * getTemplateNames(): string[] {
+     *   return ['bash', 'trash-delete', 'trash-list'];
+     * }
+     * ```
+     */
+    getTemplateNames?(): string[];
+    /**
+     * 声明渲染模板（推荐方式）
+     * 直接返回模板对象，无需文件路径
+     *
+     * @example
+     * ```typescript
+     * getRenderTemplates(): Record<string, InlineRenderTemplate> {
+     *   return {
+     *     'bash': {
+     *       call: (args) => `<div class="bash-command">> ${escapeHtml(args.command)}</div>`,
+     *       result: (data, success) => success
+     *         ? `<pre class="bash-output">${escapeHtml(data)}</pre>`
+     *         : `<div class="tool-error">${escapeHtml(data)}</div>`
+     *     }
+     *   };
+     * }
+     * ```
+     */
+    getRenderTemplates?(): Record<string, InlineRenderTemplate>;
+    /**
+     * 声明上下文注入器
+     */
+    getContextInjectors?(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 初始化钩子
+     */
+    onInitiate?(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 清理钩子
+     */
+    onDestroy?(ctx: FeatureContext): Promise<void>;
+    /**
+     * 捕获可回滚的 Feature 状态
+     *
+     * 仅返回显式声明、可序列化的状态。
+     * 未返回的字段不会参与 rollback。
+     */
+    captureState?(): FeatureStateSnapshot;
+    /**
+     * 从快照恢复 Feature 状态
+     */
+    restoreState?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * rollback 前钩子
+     */
+    beforeRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * rollback 后钩子
+     */
+    afterRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    /**
+     * 可选：为调试器提供 hook 的人类可读说明
+     */
+    getHookDescription?(lifecycle: string, methodName: string): string | undefined;
+}
+/**
+ * 从 Feature 的 source 属性获取包信息
+ *
+ * 通过向上查找 package.json 文件来确定包信息
+ * 支持三种场景：
+ * 1. 框架内置 Feature：找到 AgentDev 的 package.json
+ * 2. 外部 npm 包：找到包的 package.json
+ * 3. 用户本地 Feature：找到用户项目的 package.json
+ *
+ * @param source Feature 的源文件路径（import.meta.url）
+ * @returns 包信息，如果找不到 package.json 则返回 null
+ */
+declare function getPackageInfoFromSource(source: string | undefined): PackageInfo | null;
+
+/**
+ * 工具定义
+ * 简单的工具创建函数
+ */
+
+/**
+ * 渲染配置扩展类型
+ * 支持字符串（模板名称）或配置对象
+ */
+type ToolRenderInput = ToolRenderConfig | string;
+/**
+ * 创建一个工具
+ * @param config 工具配置
+ * @param sourceFile 可选：调用此函数的源文件路径（用于自动查找渲染文件）
+ */
+declare function createTool(config: {
+    name: string;
+    description: string;
+    parameters?: Record<string, any>;
+    execute: (args: any, context?: any) => Promise<any>;
+    render?: ToolRenderInput;
+}, sourceFile?: string): Tool;
+/**
+ * 工具注册表 - 管理多个工具
+ */
+declare class ToolRegistry {
+    private tools;
+    private enabled;
+    private pendingDisabled;
+    private sources;
+    /**
+     * 注册工具（默认启用，记录来源）
+     */
+    register(tool: Tool, source?: string): this;
+    /**
+     * 禁用工具
+     */
+    disable(name: string): boolean;
+    /**
+     * 启用工具
+     */
+    enable(name: string): boolean;
+    /**
+     * 检查工具是否启用
+     */
+    isEnabled(name: string): boolean;
+    /**
+     * 获取工具来源（调试用）
+     */
+    getSource(name: string): string | undefined;
+    /**
+     * 获取工具条目（调试快照用）
+     */
+    getEntries(): Array<{
+        tool: Tool;
+        enabled: boolean;
+        source?: string;
+    }>;
+    /**
+     * 获取工具
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * 获取所有工具（只返回启用的）
+     */
+    getAll(): Tool[];
+    /**
+     * 检查工具是否存在
+     */
+    has(name: string): boolean;
+    /**
+     * 获取工具的渲染配置
+     */
+    getRenderConfig(name: string): ToolRenderConfig | undefined;
+}
+
+type DebugTransportMode = 'viewer-worker' | 'claw';
+declare function resolveDebugTransportMode(): DebugTransportMode;
+declare function getClawRuntimeUrl(): string;
+
+interface DebugCapabilities {
+    transportMode: DebugTransportMode;
+    interactiveInput: boolean;
+    runtimeUrl: string | null;
+    viewerCompatibleApi: boolean;
+    debuggerMcpMetadata: boolean;
+}
+declare function getDebugCapabilities(): DebugCapabilities;
+
+/**
+ * DebugHub - 全局多 Agent 调试中心
+ *
+ * 职责：
+ * - 管理所有 Agent 的注册和注销
+ * - 连接到独立的 Viewer Worker UDS 服务器
+ * - 路由 Agent 消息到 Worker
+ *
+ * 设计原则：
+ * - 单例模式，全局唯一
+ * - 轻量：只做路由，不存储消息
+ * - 直观：API 简单明了
+ */
+
+type Agent = any;
+declare class DebugHub {
+    private static instance;
+    private readonly transportMode;
+    private readonly clawClient?;
+    private agents;
+    private currentAgentId;
+    private nextId;
+    private readonly processId;
+    private pendingInputRequests;
+    private activeInputRequests;
+    private udsClient?;
+    private udsPath;
+    private workerPort;
+    private clientReady;
+    private registrationLock;
+    private messageQueue;
+    private reconnectTimer?;
+    private reconnectAttempts;
+    private readonly MAX_RECONNECT_ATTEMPTS;
+    private readonly RECONNECT_DELAY;
+    private agentFeatureTemplates;
+    private constructor();
+    static getInstance(): DebugHub;
+    /**
+     * 启动调试服务器
+     * @param port HTTP 端口（默认 2026，仅用于显示）
+     * @param openBrowser 是否自动打开浏览器（默认 true，已废弃参数）
+     */
+    start(port?: number, openBrowser?: boolean): Promise<void>;
+    /**
+     * 自动启动 ViewerWorker 进程
+     */
+    private openBrowser;
+    private viewerWorkerProcess?;
+    private spawnViewerWorker;
+    /**
+     * 停止调试服务器
+     */
+    stop(): void;
+    /**
+     * 手动重连（可选）
+     * 如果已经连接，则不执行任何操作
+     */
+    reconnect(): Promise<void>;
+    /**
+     * 注册 Agent
+     * @param agent Agent 实例
+     * @param name 显示名称（可选，默认使用类名）
+     * @param featureTemplates Feature 模板路径映射（可选）
+     * @returns 分配的 agentId
+     */
+    registerAgent(agent: Agent, name?: string, featureTemplates?: Record<string, string>, hookInspector?: HookInspectorSnapshot, overview?: AgentOverviewSnapshot): string;
+    /**
+     * 注销 Agent
+     * @param agentId Agent ID
+     */
+    unregisterAgent(agentId: string): void;
+    /**
+     * 切换当前选中的 Agent
+     * @param agentId Agent ID
+     * @returns 是否成功
+     */
+    selectAgent(agentId: string): boolean;
+    /**
+     * 推送 Agent 消息
+     * @param agentId Agent ID
+     * @param messages 消息数组
+     */
+    pushMessages(agentId: string, messages: Message[]): void;
+    /**
+     * 注册 Agent 工具
+     * @param agentId Agent ID
+     * @param tools 工具数组
+     */
+    registerAgentTools(agentId: string, tools: Tool[]): void;
+    updateAgentInspector(agentId: string, hookInspector: HookInspectorSnapshot): void;
+    updateAgentOverview(agentId: string, overview: AgentOverviewSnapshot): void;
+    /**
+     * 获取所有已注册的 Agent 信息
+     */
+    getAgentList(): AgentInfo[];
+    /**
+     * 获取当前选中的 Agent ID
+     */
+    getCurrentAgentId(): string | null;
+    getTransportMode(): 'viewer-worker' | 'claw';
+    getCapabilities(): DebugCapabilities;
+    /**
+     * 根据 Agent 实例获取其 ID
+     */
+    getAgentId(agent: Agent): string | undefined;
+    /**
+     * 获取 Worker 端口
+     */
+    getPort(): number | null;
+    /**
+     * 检查是否已连接到 ViewerWorker
+     */
+    isConnected(): boolean;
+    /**
+     * 推送通知
+     * @param agentId Agent ID
+     * @param notification 通知对象
+     */
+    pushNotification(agentId: string, notification: Notification): void;
+    /**
+     * 请求用户输入
+     * @param agentId Agent ID
+     * @param prompt 提示信息
+     * @param timeout 超时时间（毫秒），默认 Infinity（无限等待）
+     * @returns Promise<string> 用户输入内容
+     */
+    requestUserInput(agentId: string, prompt: string, timeout?: number): Promise<string>;
+    requestUserInputEvent(agentId: string, request: UserInputRequest, timeout?: number): Promise<UserInputResponse>;
+    /**
+     * 连接到 UDS 服务器
+     */
+    private connectToWorker;
+    /**
+     * 处理来自 Worker 的消息
+     */
+    private handleWorkerMessage;
+    /**
+     * 重新注册所有 Agent（重连后调用）
+     * 确保 ViewerWorker 能够恢复所有 Agent 的注册信息
+     */
+    private reregisterAllAgents;
+    /**
+     * 安排重连（指数退避）
+     */
+    private scheduleReconnect;
+    /**
+     * 通过 UDS 发送消息
+     */
+    private sendViaUDS;
+    /**
+     * 发送消息到 Worker
+     */
+    private sendToWorker;
+}
+
+interface FeatureCheckpoint {
+    featureName: string;
+    snapshot: FeatureStateSnapshot;
+}
+
+interface AgentRuntimeSnapshot {
+    initialized: boolean;
+    callIndex: number;
+    context?: ContextSnapshot;
+    featureStates: FeatureCheckpoint[];
+    usageStats?: UsageStatsSnapshot;
+}
+interface CallRollbackSnapshot {
+    callIndex: number;
+    draftInput: string;
+    runtime: AgentRuntimeSnapshot;
+}
+interface AgentSessionSnapshot {
+    version: number;
+    sessionId: string;
+    savedAt: number;
+    agentType: string;
+    runtime: AgentRuntimeSnapshot;
+    rollbackHistory: CallRollbackSnapshot[];
+}
+interface SessionStore {
+    save(sessionId: string, snapshot: AgentSessionSnapshot): Promise<string>;
+    load(sessionId: string): Promise<AgentSessionSnapshot>;
+    list(): Promise<string[]>;
+    delete(sessionId: string): Promise<void>;
+}
+declare class FileSessionStore implements SessionStore {
+    private readonly baseDir;
+    constructor(baseDir?: string);
+    save(sessionId: string, snapshot: AgentSessionSnapshot): Promise<string>;
+    load(sessionId: string): Promise<AgentSessionSnapshot>;
+    list(): Promise<string[]>;
+    delete(sessionId: string): Promise<void>;
+    private resolvePath;
+}
+declare function getDefaultSessionStore(): SessionStore;
+
+/**
+ * 钩子错误处理策略
+ */
+declare enum HookErrorHandling {
+    /** 静默失败：记录警告，不中断主流程 */
+    Silent = "silent",
+    /** 传播异常：中断整个 onCall 流程 */
+    Propagate = "propagate",
+    /** 记录后传播：先记录日志再抛出 */
+    Logged = "logged"
+}
+
+type CallRollbackCheckpoint = CallRollbackSnapshot;
+declare class AgentBase {
+    protected readonly logger: Logger;
+    protected llm: AgentConfig['llm'];
+    protected tools: ToolRegistry;
+    protected maxTurns: number;
+    protected systemMessage?: string | TemplateSource;
+    protected config: AgentConfig;
+    protected templateLoader: TemplateLoader;
+    protected persistentContext?: Context;
+    protected debugHub?: DebugHub;
+    protected agentId?: string;
+    protected debugEnabled: boolean;
+    protected _agentId?: string;
+    protected _parentPool?: any;
+    private features;
+    private contextInjectors;
+    private featureToolsReady;
+    private hooksRegistry;
+    protected _initialized: boolean;
+    protected _currentCallInput?: string;
+    protected _currentStep: number;
+    protected _callIndex: number;
+    protected _callStartTimes: Map<number, number>;
+    protected _callCheckpoints: CallRollbackCheckpoint[];
+    protected usageStats: UsageStats;
+    private _pendingInput;
+    private templateResolver?;
+    private toolExecutor?;
+    private reactRunner?;
+    constructor(config: AgentConfig);
+    /**
+     * 获取钩子的错误处理策略（可被子类覆盖）
+     */
+    getHookErrorHandling(hookName: string): HookErrorHandling;
+    /**
+     * 设置待注入的用户输入
+     *
+     * Feature 可以在 CallStart 钩子中调用此方法来修改即将注入到上下文的输入内容
+     * 典型用法：处理斜杠命令，去除命令前缀后更新输入
+     *
+     * @param input 新的输入内容
+     */
+    setUserInput(input: string): void;
+    /**
+     * 获取当前待注入的用户输入
+     *
+     * Feature 可以在 CallStart 钩子中调用此方法来获取当前输入缓存
+     * 用于链式处理或条件判断
+     *
+     * @returns 当前输入缓存，如果未设置则返回空字符串
+     */
+    getUserInput(): string;
+    /**
+     * 唯一的公开入口 - 执行 Agent
+     */
+    onCall(input: string): Promise<string>;
+    /**
+     * 启用可视化查看器
+     */
+    withViewer(name?: string, port?: number, openBrowser?: boolean): Promise<this>;
+    /**
+     * 设置上下文
+     */
+    withContext(context: Context): this;
+    /**
+     * 从快照加载上下文
+     */
+    load(snapshot: ContextSnapshot): this;
+    /**
+     * 保存上下文为快照
+     */
+    save(): ContextSnapshot | undefined;
+    /**
+     * 生成当前会话快照
+     */
+    createSessionSnapshot(sessionId: string): Promise<AgentSessionSnapshot>;
+    /**
+     * 从会话快照恢复
+     */
+    restoreSessionSnapshot(snapshot: AgentSessionSnapshot): Promise<this>;
+    rollbackToCall(callIndex: number): Promise<{
+        draftInput: string;
+    }>;
+    /**
+     * 保存会话到持久化存储
+     */
+    saveSession(sessionId: string, store?: SessionStore): Promise<string>;
+    /**
+     * 从持久化存储加载会话
+     */
+    loadSession(sessionId: string, store?: SessionStore): Promise<this>;
+    /**
+     * 重置上下文
+     */
+    reset(): this;
+    /**
+     * 设置系统提示词模板
+     */
+    setSystemPrompt(prompt: string | TemplateSource): this;
+    /**
+     * 设置占位符上下文变量
+     */
+    setSystemContext(context: PlaceholderContext): this;
+    /**
+     * 获取上下文（用于调试，向后兼容）
+     */
+    getContext(): Context;
+    /**
+     * 获取工具列表（向后兼容）
+     */
+    getTools(): ToolRegistry;
+    /**
+     * 获取用量统计
+     */
+    getUsage(): UsageStats;
+    /**
+     * 记录一次 LLM 调用的用量
+     * @param callIndex Call 序号
+     * @param step Step 序号
+     * @param usage 用量数据
+     */
+    recordUsage(callIndex: number, step: number, usage: UsageInfo): void;
+    /**
+     * 标记 Call 结束
+     * @param callIndex Call 序号
+     */
+    endCallUsage(callIndex: number): void;
+    /**
+     * 子代理向父代理回传消息
+     */
+    protected reportToParent(message: string): Promise<void>;
+    /**
+     * 创建 Agent 实例（子类可覆盖）
+     */
+    createAgentByType(type: string): Promise<AgentBase>;
+    /**
+     * 清理资源
+     */
+    dispose(): Promise<void>;
+    /**
+     * 使用 Feature（链式调用）
+     */
+    use(feature: AgentFeature): this;
+    /**
+     * 启用 Feature 的所有工具
+     *
+     * @example
+     * agent.enable('mcp')  // 启用 MCP 工具
+     */
+    enable(featureName: string): this;
+    /**
+     * 禁用 Feature 的所有工具
+     *
+     * @example
+     * agent.disable('mcp')  // 禁用 MCP 工具
+     */
+    disable(featureName: string): this;
+    /**
+     * 检查 Feature 是否启用
+     *
+     * @example
+     * if (agent.isEnabled('mcp')) { ... }
+     */
+    isEnabled(featureName: string): boolean;
+    /**
+     * 确保 Feature 工具已注册
+     */
+    private ensureFeatureTools;
+    /**
+     * 解析相对路径（处理 ./ 和 ../）
+     * @param baseDir 基础目录
+     * @param relativePath 相对路径
+     * @returns 绝对路径
+     */
+    private resolveRelativePath;
+    /**
+     * 确保执行器已初始化（延迟初始化）
+     */
+    private ensureExecutorsInitialized;
+    /**
+     * 推送到 DebugHub
+     */
+    private pushToDebug;
+    private pushOverviewSnapshot;
+    private captureRuntimeSnapshot;
+    private restoreRuntimeSnapshot;
+    private commitCallCheckpoint;
+    private normalizeSessionSnapshot;
+    private syncRegisteredToolsToDebug;
+    private pushInspectorSnapshot;
+    private buildOverviewSnapshot;
+    private buildHookInspectorSnapshot;
+    protected onInitiate(_ctx: AgentInitiateContext): Promise<void>;
+    protected onDestroy(_ctx: AgentDestroyContext): Promise<void>;
+    protected onCallStart(_ctx: CallStartContext): Promise<void>;
+    protected onCallFinish(_ctx: CallFinishContext): Promise<void>;
+    protected onStepStart(_ctx: StepStartContext): Promise<void>;
+    /**
+     * Step 结束钩子（扩展支持流控制）
+     *
+     * @returns
+     * - undefined: 默认行为
+     * - { action: 'continue' }: 继续下一步
+     * - { action: 'end' }: 强制结束循环
+     */
+    protected onStepFinished(_ctx: StepFinishedContext): Promise<HookResult | undefined>;
+    protected onToolUse(_ctx: ToolContext): Promise<HookResult | undefined>;
+    /**
+     * 工具执行完成钩子
+     */
+    protected onToolFinished(_result: ToolResult): Promise<void>;
+    onSubAgentSpawn(_ctx: SubAgentSpawnContext): Promise<void>;
+    onSubAgentUpdate(_ctx: SubAgentUpdateContext): Promise<void>;
+    onSubAgentDestroy(_ctx: SubAgentDestroyContext): Promise<void>;
+    onSubAgentInterrupt(_ctx: SubAgentInterruptContext): Promise<void>;
+    protected onInterrupt(ctx: AgentInterruptContext): Promise<string>;
+}
+
+/**
+ * MCP stdio 传输配置
+ */
+interface MCPSstdioConfig {
+    /** 传输类型 */
+    transport: 'stdio';
+    /** 启动命令 */
+    command: string;
+    /** 命令参数 */
+    args: string[];
+    /** 环境变量 (可选) */
+    env?: Record<string, string>;
+    /** 工作目录 (可选) */
+    cwd?: string;
+}
+/**
+ * MCP HTTP 传输配置
+ */
+interface MCPHTTPConfig {
+    /** 传输类型 */
+    transport: 'http';
+    /** 服务器 URL */
+    url: string;
+    /** HTTP 请求头 (可选) */
+    headers?: Record<string, string>;
+    /** 超时时间 (毫秒，默认 30000) */
+    timeout?: number;
+    /** 重连次数 (默认 3) */
+    retryCount?: number;
+}
+/**
+ * MCP SSE 传输配置
+ */
+interface MCPSSEConfig {
+    /** 传输类型 */
+    transport: 'sse';
+    /** 服务器 URL */
+    url: string;
+    /** HTTP 请求头 (可选) */
+    headers?: Record<string, string>;
+    /** 重连次数 (默认 3) */
+    retryCount?: number;
+}
+/**
+ * MCP 服务器配置
+ */
+type MCPServerConfig = MCPSstdioConfig | MCPHTTPConfig | MCPSSEConfig;
+/**
+ * MCP 工具映射配置
+ */
+interface MCPToolMappingConfig {
+    /** 渲染模板覆盖 */
+    render?: {
+        call?: string;
+        result?: string;
+    };
+    /** 工具注解覆盖 */
+    annotations?: {
+        /** 是否需要用户批准 */
+        requiresApproval?: boolean;
+        /** 是否为只读工具 */
+        readOnly?: boolean;
+        /** 是否为破坏性操作 */
+        destructive?: boolean;
+    };
+    /** 是否禁用该工具 */
+    disabled?: boolean;
+}
+/**
+ * MCP 主配置
+ */
+interface MCPConfig {
+    /** 是否启用 MCP (默认 true) */
+    enabled?: boolean;
+    /** MCP 服务器配置 */
+    servers: Record<string, MCPServerConfig>;
+    /** 旧格式兼容 */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /** 工具级别配置映射 */
+    toolMapping?: Record<string, MCPToolMappingConfig>;
+    /** 全局超时 (毫秒) */
+    timeout?: number;
+    /** 是否启用工具缓存 */
+    enableCache?: boolean;
+}
+/**
+ * MCP 连接状态
+ */
+declare const enum MCPConnectionState {
+    /** 未连接 */
+    Disconnected = "disconnected",
+    /** 连接中 */
+    Connecting = "connecting",
+    /** 已连接 */
+    Connected = "connected",
+    /** 连接错误 */
+    Error = "error"
+}
+/**
+ * MCP 连接信息
+ */
+interface MCPConnectionInfo {
+    /** 服务器名称 */
+    name: string;
+    /** 连接状态 */
+    state: MCPConnectionState;
+    /** 连接时间 */
+    connectedAt?: number;
+    /** 最后错误 */
+    lastError?: string;
+    /** 工具数量 */
+    toolCount: number;
+}
+/**
+ * MCP 工具调用结果
+ */
+interface MCPToolResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 结果内容 */
+    content?: string;
+    /** 结构化数据 (如果可用) */
+    structuredContent?: any;
+    /** 错误信息 */
+    error?: string;
+    /** MCP 服务器名称 */
+    server: string;
+    /** 调用耗时 (毫秒) */
+    duration: number;
+    /** 图像数据 (如果有) */
+    images?: Array<{
+        data: string;
+        mimeType: string;
+    }>;
+    /** 资源数据 (如果有) */
+    resources?: Array<{
+        uri: string;
+        mimeType: string;
+        text?: string;
+    }>;
+}
+/**
+ * MCP 统计信息
+ */
+interface MCPStatistics {
+    /** 总调用次数 */
+    totalCalls: number;
+    /** 成功调用次数 */
+    successfulCalls: number;
+    /** 失败调用次数 */
+    failedCalls: number;
+    /** 平均耗时 (毫秒) */
+    averageDuration: number;
+    /** 按服务器统计 */
+    byServer: Record<string, {
+        totalCalls: number;
+        successfulCalls: number;
+        failedCalls: number;
+        averageDuration: number;
+    }>;
+}
+/**
+ * MCP 客户端配置
+ */
+interface MCPClientConfig {
+    /** 配置文件路径 */
+    configPath?: string;
+    /** 是否自动重连 */
+    autoReconnect?: boolean;
+    /** 重连间隔 (毫秒) */
+    reconnectInterval?: number;
+    /** 最大重连次数 */
+    maxReconnectAttempts?: number;
+    /** 日志级别 */
+    logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
+}
+
+declare class MCPConnectionManager {
+    private connections;
+    private reconnectTimers;
+    private readonly logger;
+    /**
+     * 连接到 MCP 服务器
+     */
+    connectServer(name: string, config: MCPServerConfig): Promise<Client | any>;
+    /**
+     * 连接到 stdio MCP 服务器
+     */
+    private connectStdio;
+    /**
+     * 连接到 HTTP MCP 服务器
+     */
+    private connectSSE;
+    /**
+     * 连接到 HTTP MCP 服务器
+     */
+    private connectHTTP;
+    /**
+     * 断开服务器连接
+     */
+    disconnectServer(name: string): Promise<void>;
+    /**
+     * 断开所有连接
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * 列出服务器的所有工具
+     */
+    listTools(name: string): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema?: any;
+    }>>;
+    callTool(name: string, serverName: string, args: Record<string, unknown>): Promise<{
+        content: any[];
+        isError?: boolean;
+    }>;
+    getConnectionInfo(name: string): MCPConnectionInfo | undefined;
+    /**
+     * 获取所有连接信息
+     */
+    getAllConnections(): MCPConnectionInfo[];
+    /**
+     * 检查连接状态
+     */
+    isConnected(name: string): boolean;
+    /**
+     * 获取服务器实例
+     */
+    getServer(name: string): Client | any | undefined;
+    /**
+     * 安排重连
+     */
+    private scheduleReconnect;
+    /**
+     * 日志输出
+     */
+    private log;
+    private handleProcessOutput;
+    private handleDirectResponse;
+    private sendDirectRequest;
+    private normalizeToolCallResponse;
+    private rejectAllPendingRequests;
+    dispose(): Promise<void>;
+}
+
+/**
+ * MCP Feature - MCP 服务器连接和工具注册
+ *
+ * 将 MCP 集成从 Agent 核心中解耦，实现可外挂功能
+ *
+ * @example
+ * ```typescript
+ * // 自动扫描 .agentdev/mcps/*.json
+ * agent.use(new MCPFeature());
+ *
+ * // 从配置文件加载（默认路径 .agentdev/mcps）
+ * agent.use(new MCPFeature('github'));
+ *
+ * // 从指定路径加载配置
+ * agent.use(new MCPFeature('./path/to/mcps/github'));
+ *
+ * // 直接传入配置对象
+ * agent.use(new MCPFeature({ servers: { ... } }));
+ * ```
+ */
+
+/**
+ * MCP Feature 配置类型
+ */
+type MCPFeatureInput = MCPConfig | string;
+interface MCPFeatureOptions {
+    excludeServers?: string[];
+}
+/**
+ * MCP Feature 实现
+ */
+declare class MCPFeature implements AgentFeature {
+    readonly name = "mcp";
+    readonly dependencies: string[];
+    readonly source: string;
+    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 config?;
+    private mcpContext?;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    constructor(input?: MCPFeatureInput, options?: MCPFeatureOptions);
+    /**
+     * 获取同步工具（无）
+     */
+    getTools(): Tool[];
+    /**
+     * 获取异步工具（需要连接 MCP 服务器）
+     */
+    getAsyncTools(_ctx: FeatureInitContext): Promise<Tool[]>;
+    /**
+     * 声明上下文注入器
+     * 为所有 MCP 工具注入 _mcpContext
+     */
+    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 清理钩子
+     */
+    onDestroy(): Promise<void>;
+    /**
+     * 设置 MCP 上下文（运行时注入）
+     */
+    setMCPContext(context: Record<string, unknown>): void;
+    /**
+     * 获取连接管理器（供外部使用）
+     */
+    getConnectionManager(): MCPConnectionManager | undefined;
+}
+
+/**
+ * Agent Skills 类型定义
+ */
+/**
+ * Skill 元数据
+ */
+interface SkillMetadata {
+    /** Skill 名称 */
+    name: string;
+    /** Skill 描述 */
+    description: string;
+    /** SKILL.md 完整路径 */
+    path: string;
+}
+/**
+ * Skills 加载器配置
+ */
+interface SkillsOptions {
+    /** skills 目录，默认 cwd/.agentdev/skills */
+    dir?: string;
+}
+
+/**
+ * Skill Feature - Skills 发现和 invoke_skill 工具
+ *
+ * 将 Skills 集成从 Agent 核心中解耦，实现可外挂功能
+ *
+ * @example
+ * ```typescript
+ * // 使用默认路径 .agentdev/skills
+ * agent.use(new SkillFeature());
+ *
+ * // 使用自定义路径
+ * agent.use(new SkillFeature('./custom/skills'));
+ * agent.use(new SkillFeature({ dir: './custom/skills' }));
+ * ```
+ */
+
+/**
+ * Skill Feature 配置类型
+ */
+interface SkillFeatureConfig extends SkillsOptions {
+    /** Skills 目录路径 */
+    dir?: string;
+}
+/**
+ * Skill Feature 输入类型
+ */
+type SkillFeatureInput = SkillFeatureConfig | string | undefined;
+/**
+ * Skill Feature 实现
+ */
+declare class SkillFeature implements AgentFeature {
+    readonly name = "skill";
+    readonly dependencies: string[];
+    readonly source: string;
+    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 _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    constructor(input?: SkillFeatureInput);
+    /**
+     * 获取同步工具（invoke_skill）
+     */
+    getTools(): Tool[];
+    /**
+     * 声明上下文注入器
+     * 为 invoke_skill 工具注入 _context.skills
+     */
+    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 初始化钩子
+     * 执行 Skills 发现并注册数据源
+     */
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 获取已加载的 Skills
+     */
+    getSkills(): SkillMetadata[];
+    /**
+     * 设置 Skills 目录
+     */
+    setSkillsDir(dir: string): void;
+}
+
+/**
+ * 反向钩子装饰器
+ *
+ * 使用装饰器标记反向钩子方法，提供编译时和运行时类型检查
+ */
+
+/**
+ * Call 开始装饰器
+ *
+ * 标记在 Call 开始时执行的方法
+ * 返回 void（仅做处理，不控制流程）
+ */
+declare const CallStart: (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+
+/**
+ * AgentPool - 子代理管理核心
+ * 管理父代理创建的所有子代理实例
+ */
+
+/**
+ * 子代理实例信息
+ */
+interface SubAgentInstance {
+    id: string;
+    type: string;
+    agent: AgentBase;
+    status: SubAgentStatus;
+    initialInstruction: string;
+    createdAt: number;
+    completedAt?: number;
+    result?: string;
+    error?: string;
+}
+/**
+ * Agent 创建函数类型（异步）
+ */
+type AgentFactory = (type: string) => AgentBase | Promise<AgentBase>;
+/**
+ * AgentPool - 子代理管理核心
+ * 管理父代理创建的所有子代理实例
+ */
+declare class AgentPool {
+    private _instances;
+    private _counters;
+    private _parent;
+    /** 待回传消息队列：agentId -> messages[] */
+    private _pendingMessages;
+    /** 消息就绪解析器：key -> resolver function */
+    private _messageResolvers;
+    constructor(parent: AgentBase);
+    /**
+     * 创建子代理（不自动执行，等待 sendTo 激活）
+     */
+    spawn(type: string, createAgentFn: AgentFactory): Promise<string>;
+    /**
+     * 获取实例信息
+     */
+    get(id: string): SubAgentInstance | undefined;
+    /**
+     * 列出所有实例
+     */
+    list(filter?: SubAgentStatus): SubAgentInstance[];
+    /**
+     * 向子代理发送消息（非阻塞）
+     */
+    sendTo(id: string, message: string): Promise<void>;
+    /**
+     * 关闭子代理
+     */
+    close(id: string, reason?: string): Promise<void>;
+    /**
+     * 子代理回传消息到父代理
+     * @param agentId 子代理 ID
+     * @param message 消息内容
+     */
+    report(agentId: string, message: string): Promise<void>;
+    /**
+     * 等待任意子代理的消息
+     * @returns { agentId, message }
+     */
+    waitForMessage(): Promise<{
+        agentId: string;
+        message: string;
+    }>;
+    /**
+     * 检查是否有活跃的子代理或待处理的消息
+     *
+     * 注意：先检查消息队列，避免竞态条件
+     */
+    hasActiveAgents(): boolean;
+    /**
+     * 检查是否有待处理的子代理消息
+     */
+    hasPendingMessages(): boolean;
+    /**
+     * 处理子代理中断
+     * @param agentId 子代理 ID
+     * @param reason 中断原因
+     * @param result 中断时的结果
+     */
+    handleInterrupt(agentId: string, reason: 'max_steps_reached' | 'error' | 'cancelled', result: string): Promise<void>;
+    /**
+     * 关闭所有子代理
+     */
+    shutdown(): Promise<void>;
+    getRuntimeSnapshot(): {
+        counters: Array<[string, number]>;
+        instances: Array<{
+            id: string;
+            type: string;
+            status: SubAgentStatus;
+        }>;
+        pendingMessages: Array<[string, string[]]>;
+    };
+    restoreRuntimeSnapshot(snapshot: {
+        counters?: Array<[string, number]>;
+    }): Promise<void>;
+    private _onComplete;
+    private _onError;
+}
+
+/**
+ * 子代理 Feature
+ *
+ * 提供子代理创建、管理、消息回传等完整能力
+ *
+ * 重构说明：
+ * - 使用装饰器实现反向钩子
+ * - @ToolFinished: 处理 wait 工具完成后的等待逻辑
+ * - @StepFinish: 处理无工具调用时的子代理等待逻辑
+ */
+declare class SubAgentFeature implements AgentFeature {
+    readonly name = "subagent";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B\u5B50\u4EE3\u7406\u521B\u5EFA\u3001\u7B49\u5F85\u4E0E\u6D88\u606F\u56DE\u4F20\u80FD\u529B\uFF0C\u8BA9\u4E3B\u5FAA\u73AF\u53EF\u4EE5\u534F\u540C\u591A\u4E2A\u4EE3\u7406\u5DE5\u4F5C\u3002";
+    private agentPool?;
+    private parentAgent?;
+    private toolFactory?;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    constructor();
+    /**
+     * 获取 AgentPool（供外部访问）
+     */
+    get pool(): AgentPool | undefined;
+    /**
+     * 初始化钩子
+     */
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 设置父代理引用（由 Agent 在 use() 时调用）
+     */
+    _setParentAgent(agent: AgentBase): void;
+    /**
+     * 获取同步工具
+     */
+    getTools(): Tool[];
+    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+    /**
+     * 处理 wait 工具
+     *
+     * 触发时机：wait 工具执行完成后
+     * 处理逻辑：
+     * 1. 检测刚才执行的工具是否是 wait
+     * 2. 如果不是，直接返回（不处理）
+     * 3. 如果是，检查是否有 busy 状态的子代理
+     * 4. 如果有，调用 agentPool.waitForMessage() 阻塞等待（await 阻塞主循环）
+     * 5. 消息插入到主代理 context
+     *
+     * 注意：这是纯通知钩子（void），流程控制通过 await 阻塞实现
+     */
+    handleWaitTool(ctx: ToolFinishedDecisionContext): Promise<void>;
+    /**
+     * 处理无工具调用时的子代理等待
+     *
+     * 触发时机：Step 结束时
+     * 处理逻辑：
+     * 1. 检查是否有 busy 状态的子代理
+     * 2. 如果没有，返回 Continue（正常结束）
+     * 3. 如果有，调用 agentPool.waitForMessage() 阻塞等待
+     * 4. 消息插入到主代理 context
+     * 5. 返回 Approve（重启 ReAct 循环）
+     */
+    handleNoToolCalls(ctx: StepFinishDecisionContext): Promise<DecisionResult>;
+    onDestroy(): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): Promise<void>;
+}
+
+/**
+ * Todo Feature 类型定义
+ */
+/**
+ * 任务状态
+ */
+type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'deleted';
+/**
+ * 任务数据结构
+ */
+interface TodoTask {
+    /** 任务 ID */
+    id: string;
+    /** 任务标题（祈使句） */
+    subject: string;
+    /** 详细描述 */
+    description: string;
+    /** 进行时形式（用于进度显示） */
+    activeForm: string;
+    /** 任务状态 */
+    status: TaskStatus;
+    /** 负责人（Agent ID） */
+    owner?: string;
+    /** 此任务阻塞的其他任务 ID */
+    blocks: string[];
+    /** 阻塞此任务的其他任务 ID */
+    blockedBy: string[];
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+    /** 创建时间 */
+    createdAt: number;
+    /** 更新时间 */
+    updatedAt: number;
+}
+/**
+ * 任务更新参数
+ */
+interface TodoTaskUpdate {
+    status?: TaskStatus;
+    subject?: string;
+    description?: string;
+    activeForm?: string;
+    owner?: string;
+    metadata?: Record<string, unknown>;
+    addBlocks?: string[];
+    addBlockedBy?: string[];
+}
+/**
+ * 任务列表摘要
+ */
+interface TodoTaskSummary {
+    id: string;
+    subject: string;
+    status: TaskStatus;
+    owner?: string;
+    blockedBy: string[];
+}
+/**
+ * TodoFeature 配置
+ */
+interface TodoFeatureConfig {
+    /** Reminder 模板文件路径 */
+    reminderTemplate?: string;
+    /** 有待执行任务时的提醒间隔（默认：3 轮） */
+    reminderThresholdWithTasks?: number;
+    /** 无待执行任务时的提醒间隔（默认：6 轮） */
+    reminderThresholdWithoutTasks?: number;
+}
+
+/**
+ * Todo Feature - 任务列表管理功能模块
+ *
+ * 提供任务创建、查询、更新等能力，用于跟踪复杂任务的进度
+ * 内置智能提醒功能，自动跟踪工具使用并在合适时机注入提醒
+ *
+ * 重构说明：
+ * - 使用反向钩子装饰器实现提醒逻辑
+ * - 不再需要在 Agent 中重写 onStepStart/onStepFinished
+ */
+
+/**
+ * TodoFeature 实现
+ *
+ * 提供任务管理和智能提醒功能
+ * 使用反向钩子自动处理提醒逻辑，无需在 Agent 中重写钩子方法
+ */
+declare class TodoFeature implements AgentFeature {
+    readonly name = "todo";
+    readonly source: string;
+    readonly description = "\u7EF4\u62A4\u4EFB\u52A1\u6E05\u5355\uFF0C\u5E76\u5728\u5408\u9002\u7684\u5FAA\u73AF\u65F6\u673A\u81EA\u52A8\u63D0\u9192\u6A21\u578B\u66F4\u65B0 todo \u72B6\u6001\u3002";
+    private tasks;
+    private counter;
+    private config;
+    private reminderContent;
+    private consecutiveNoTodoTurns;
+    private reminderInjected;
+    private toolFactory?;
+    private _packageInfo;
+    constructor(config?: TodoFeatureConfig);
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    getTools(): Tool[];
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    getHookDescription(lifecycle: string, methodName: string): string | undefined;
+    /**
+     * Step 开始时检查是否需要注入 reminder
+     *
+     * 触发时机：每轮 ReAct 迭代开始时
+     * 处理逻辑：
+     * 1. 检查连续未使用 todo 工具的轮次
+     * 2. 达到阈值时注入 reminder 系统消息
+     * 3. 防止重复注入
+     */
+    checkAndInjectReminder(ctx: StepStartContext): Promise<void>;
+    /**
+     * Step 结束时记录是否使用了 todo 工具
+     *
+     * 触发时机：每轮 ReAct 迭代结束时
+     * 处理逻辑：
+     * 1. 检查本轮是否使用了 todo 工具
+     * 2. 使用了则重置计数器，未使用则计数器+1
+     * 3. 返回 Continue 使用默认行为
+     */
+    recordToolUsage(ctx: StepFinishDecisionContext): Promise<DecisionResult>;
+    /**
+     * 设置 reminder 内容
+     */
+    setReminderContent(content: string): void;
+    /**
+     * 获取当前的提醒阈值（根据任务状态动态调整）
+     */
+    private getCurrentThreshold;
+    /**
+     * 创建任务
+     */
+    createTask(subject: string, description: string, activeForm: string, options?: {
+        owner?: string;
+        metadata?: Record<string, unknown>;
+    }): TodoTask;
+    /**
+     * 获取任务详情
+     */
+    getTask(taskId: string): TodoTask | undefined;
+    /**
+     * 列出所有任务摘要
+     */
+    listTasks(filter?: {
+        status?: TaskStatus;
+    }): TodoTaskSummary[];
+    /**
+     * 更新任务
+     */
+    updateTask(taskId: string, updates: TodoTaskUpdate): TodoTask | undefined;
+    /**
+     * 清空所有任务
+     */
+    clearTasks(): void;
+    /** 判断是否是 todo 工具 */
+    private isTodoTool;
+    /** 获取默认 reminder 内容 */
+    private getDefaultReminder;
+}
+
+/**
+ * UserInputFeature - 通过调试界面获取用户输入
+ *
+ * 功能：
+ * - 提供 get_user_input 工具，允许 LLM 请求用户输入
+ * - 通过 DebugHub 的 UDS 通道与 ViewerWorker 通信
+ * - 前端显示输入框，用户提交后返回给 Agent
+ */
+
+interface UserInputFeatureConfig {
+    /** 默认超时时间（毫秒），默认无限等待 */
+    timeout?: number;
+}
+declare class UserInputFeature implements AgentFeature {
+    readonly name = "user-input";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u5141\u8BB8 Agent \u901A\u8FC7\u8C03\u8BD5\u754C\u9762\u5411\u7528\u6237\u53D1\u8D77\u8F93\u5165\u8BF7\u6C42\u5E76\u7B49\u5F85\u56DE\u590D\u3002";
+    private defaultTimeout;
+    private nextDraftInput;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     * 注意：UserInputFeature 没有渲染模板
+     */
+    getTemplateNames(): string[];
+    constructor(config?: UserInputFeatureConfig);
+    setNextDraftInput(input: string): void;
+    /**
+     * 请求用户输入（核心方法）
+     */
+    requestUserInput(prompt: string, timeout?: number): Promise<string>;
+    requestUserInputEvent(request: UserInputRequest, timeout?: number): Promise<UserInputResponse>;
+    /**
+     * 获取用户输入（公开接口，供主循环直接调用）
+     * @param prompt 提示信息
+     * @param timeout 超时时间（毫秒）
+     * @returns 用户输入内容
+     */
+    getUserInput(prompt?: string, timeout?: number): Promise<string>;
+    getUserInputEvent(prompt?: string, timeout?: number, actions?: UserInputAction[]): Promise<UserInputResponse>;
+    getTools(): Tool[];
+    onInitiate(_ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+}
+
+/**
+ * OpencodeBasic Feature - 基础文件操作工具集
+ */
+declare class OpencodeBasicFeature implements AgentFeature {
+    readonly name = "opencode-basic";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u63D0\u4F9B\u8BFB\u5199\u6587\u4EF6\u3001\u7F16\u8F91\u3001\u5217\u76EE\u5F55\u3001glob \u548C grep \u7B49\u57FA\u7840\u5DE5\u7A0B\u5316\u5DE5\u5177\u3002\u5305\u542B\"\u5148\u8BFB\u540E\u5199\"\u5B89\u5168\u4FDD\u62A4\u673A\u5236\u3002";
+    /**
+     * 存储已读取文件的路径（绝对路径）
+     * 在整个 Session 生命周期中保持，用于验证 write 操作
+     */
+    private readFiles;
+    /**
+     * 缓存包信息
+     */
+    private _packageInfo;
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    /**
+     * Logger 实例，用于记录结构化日志
+     */
+    private logger;
+    /**
+     * Feature 初始化时清空读取历史
+     */
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    /**
+     * 工具使用前拦截器
+     * - 记录 read 操作的文件路径
+     * - 验证 write 操作是否已先读取
+     */
+    validateWriteOperation(ctx: ToolContext): Promise<DecisionResult>;
+    /**
+     * 获取所有工具
+     */
+    getTools(): Tool[];
+}
+
+interface ExampleFeatureConfig {
+    enabledByDefault?: boolean;
+    notePrefix?: string;
+}
+interface ExampleFeatureRuntimeState {
+    enabled: boolean;
+    counter: number;
+    lastInput: string;
+    notes: string[];
+}
+interface ExampleFeatureSnapshot {
+    enabled: boolean;
+    counter: number;
+    lastInput: string;
+    notes: string[];
+}
+
+declare class ExampleFeature implements AgentFeature {
+    readonly name = "example-feature";
+    readonly dependencies: string[];
+    readonly source: string;
+    readonly description = "\u793A\u8303\u7528 Feature \u9AA8\u67B6\uFF1A\u5C55\u793A\u5DE5\u5177\u3001\u6A21\u677F\u3001\u4E0A\u4E0B\u6587\u6CE8\u5165\u3001\u56DE\u6EDA\u5FEB\u7167\u548C\u53CD\u5411\u94A9\u5B50\u7684\u6807\u51C6\u5199\u6CD5\u3002";
+    private readonly config;
+    private readonly runtime;
+    private logger?;
+    private _packageInfo;
+    constructor(config?: ExampleFeatureConfig);
+    /**
+     * 公开 API 只保留“其他 Feature 真会读取的东西”。
+     * 不要把整个 runtime 对象直接暴露出去。
+     */
+    isEnabled(): boolean;
+    getCounter(): number;
+    listNotes(): string[];
+    /**
+     * 内部 helper 比直接在装饰器和工具里散改字段更容易维护。
+     * 如果 Feature 很简单，也可以不抽这些方法。
+     */
+    private appendNote;
+    private setEnabled;
+    private buildReminder;
+    getTools(): Tool[];
+    /**
+     * 获取包信息（统一打包方案）
+     */
+    getPackageInfo(): PackageInfo | null;
+    /**
+     * 获取模板名称列表（统一打包方案）
+     */
+    getTemplateNames(): string[];
+    getContextInjectors(): Map<string | RegExp, ContextInjector>;
+    onInitiate(ctx: FeatureInitContext): Promise<void>;
+    onDestroy(_ctx: FeatureContext): Promise<void>;
+    captureState(): FeatureStateSnapshot;
+    restoreState(snapshot: FeatureStateSnapshot): void;
+    beforeRollback(snapshot: FeatureStateSnapshot): Promise<void>;
+    afterRollback(snapshot: FeatureStateSnapshot): Promise<void>;
+    handleCallStart(ctx: CallStartContext): Promise<void>;
+    validateExampleTool(ctx: ToolContext): Promise<typeof Decision.Continue | typeof Decision.Deny>;
+    handleStepFinish(ctx: StepFinishDecisionContext): Promise<typeof Decision.Continue>;
+}
+
+/**
+ * 配置加载
+ * 从 config 目录读取 JSON 配置文件
+ *
+ * 提供两种方式：
+ * - loadConfig() - 异步加载（用于特殊场景）
+ * - loadConfigSync() - 同步加载（推荐，用于 Agent 构造）
+ */
+/**
+ * 统一配置类型
+ * 字段允许冗余，各 LLM 实现只取自己需要的
+ */
+interface ModelConfig {
+    provider: 'openai' | 'anthropic' | string;
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    maxTokens?: number;
+    thinkingBudgetTokens?: number;
+    thinkingKeepTurns?: number;
+    providerOptions?: Record<string, unknown>;
+    region?: string;
+    projectId?: string;
+}
+interface AgentConfigFile {
+    defaultModel: ModelConfig;
+    agent: {
+        maxTurns: number;
+        temperature: number;
+    };
+}
+/**
+ * 读取配置文件（异步版本）
+ * @param name 配置文件名（不含路径和扩展名），默认 'default'
+ */
+declare function loadConfig(name?: string): Promise<AgentConfigFile>;
+/**
+ * 读取配置文件（同步版本，推荐用于 Agent 构造）
+ * @param name 配置文件名（不含路径和扩展名），默认 'default'
+ */
+declare function loadConfigSync(name?: string): AgentConfigFile;
+/**
+ * 列出所有可用的配置文件
+ */
+declare function listConfigs(): Promise<string[]>;
+
+/**
+ * BasicAgent - 基础 Agent 类
+ *
+ * 集成了常用 Feature 和系统环境信息
+ * 适用于大多数 Agent 场景
+ *
+ * 默认自动加载配置文件，开箱即用
+ */
+
+/**
+ * 系统环境信息上下文
+ */
+interface SystemContext$1 {
+    /** 当前工作目录 */
+    SYSTEM_WORKING_DIR: string;
+    /** 是否是 Git 仓库 */
+    SYSTEM_IS_GIT_REPOSITORY: boolean;
+    /** 操作系统平台 */
+    SYSTEM_PLATFORM: NodeJS.Platform;
+    /** 当前日期 (YYYY-MM-DD) */
+    SYSTEM_DATE: string;
+    /** 当前使用的模型名称 */
+    SYSTEM_CURRENT_MODEL: string;
+    /** 索引签名，允许作为 PlaceholderContext 使用 */
+    [key: string]: any;
+}
+/**
+ * BasicAgent 配置选项
+ *
+ * 所有参数都是可选的，默认会自动同步加载配置文件
+ */
+interface BasicAgentConfig {
+    /** LLM 客户端（可选，不传则自动同步加载配置创建） */
+    llm?: LLMClient;
+    /** 配置文件名（可选，默认 'default'） */
+    configName?: string;
+    /** Agent 显示名称（可选） */
+    name?: string;
+    /** 系统提示词（可选，后续可通过 setPrompt() 设置） */
+    systemMessage?: string;
+    /** MCP 配置：传字符串时加载指定配置；传 false 时禁用自动加载；不传时若 .agentdev/mcps 存在则自动加载全部 */
+    mcpServer?: string | false;
+    /** MCP 运行时上下文（可选，如 GitHub Token） */
+    mcpContext?: Record<string, unknown>;
+    /** 自动扫描 MCP 时排除的 serverId 列表 */
+    excludeMcpServers?: string[];
+    /** 自定义工具集（可选，默认使用 Feature 提供的工具） */
+    tools?: Tool[];
+    /** Skills 目录（可选，默认使用 .agentdev/skills） */
+    skillsDir?: string;
+}
+/**
+ * 基础 Agent 类
+ *
+ * 集成常用 Feature 和系统环境信息，开箱即用
+ * 构造函数不传任何参数时，会自动同步加载配置文件创建 LLM
+ */
+declare class BasicAgent extends AgentBase {
+    protected _systemContext: SystemContext$1;
+    protected _mcpServer?: string | false;
+    protected _mcpContext?: Record<string, unknown>;
+    protected _config?: AgentConfigFile;
+    protected _skillsDir?: string;
+    protected _mcpFeature?: MCPFeature;
+    /**
+     * 构造函数
+     *
+     * @param config 基础配置（全部可选，不传则使用默认配置）
+     */
+    constructor(config?: BasicAgentConfig);
+    /**
+     * 获取系统环境信息
+     */
+    getSystemContext(): SystemContext$1;
+    /**
+     * 获取 MCP 服务器配置
+     */
+    getMcpServer(): string | false | undefined;
+    /**
+     * 获取 MCP 上下文
+     */
+    getMcpContext(): Record<string, unknown> | undefined;
+}
+
+/**
+ * ExplorerAgent - 代码探索者 Agent
+ *
+ * 专注于代码库探索和理解的轻量级 Agent
+ * 仅配备 read、list、bash 三个核心工具
+ * 适用于代码审查、结构分析、文档生成等场景
+ */
+
+/**
+ * 系统环境信息上下文
+ */
+interface SystemContext {
+    /** 当前工作目录 */
+    SYSTEM_WORKING_DIR: string;
+    /** 是否是 Git 仓库 */
+    SYSTEM_IS_GIT_REPOSITORY: boolean;
+    /** 操作系统平台 */
+    SYSTEM_PLATFORM: NodeJS.Platform;
+    /** 当前日期 (YYYY-MM-DD) */
+    SYSTEM_DATE: string;
+    /** 当前使用的模型名称 */
+    SYSTEM_CURRENT_MODEL: string;
+    /** 索引签名，允许作为 PlaceholderContext 使用 */
+    [key: string]: any;
+}
+/**
+ * ExplorerAgent 配置选项
+ *
+ * 所有参数都是可选的，默认会自动同步加载配置文件
+ */
+interface ExplorerAgentConfig {
+    /** LLM 客户端（可选，不传则自动同步加载配置创建） */
+    llm?: LLMClient;
+    /** 配置文件名（可选，默认 'default'） */
+    configName?: string;
+    /** Agent 显示名称（可选） */
+    name?: string;
+    /** 系统提示词（可选，默认使用 explorer.md） */
+    systemMessage?: string;
+    /** Skills 目录（可选，默认使用 .agentdev/skills） */
+    skillsDir?: string;
+}
+/**
+ * 代码探索者 Agent
+ *
+ * 轻量级代码探索 Agent，专注于：
+ * - 代码库结构分析
+ * - 代码审查和理解
+ * - 文档生成
+ * - 依赖关系梳理
+ *
+ * 构造函数不传任何参数时，会自动同步加载配置文件创建 LLM
+ */
+declare class ExplorerAgent extends AgentBase {
+    protected _systemContext: SystemContext;
+    protected _config?: AgentConfigFile;
+    protected _skillsDir?: string;
+    /**
+     * 构造函数
+     *
+     * @param config 探索者配置（全部可选，不传则使用默认配置）
+     */
+    constructor(config?: ExplorerAgentConfig);
+    /**
+     * Agent 初始化钩子
+     * 配置系统提示词，禁用写入和编辑工具（只读模式）
+     */
+    protected onInitiate(): Promise<void>;
+    /**
+     * 获取系统环境信息
+     */
+    getSystemContext(): SystemContext;
+}
+
+/**
+ * 消息创建工具
+ * 简单的工厂函数，直观易懂
+ */
+
+/**
+ * 创建消息
+ */
+declare function createMessage(role: MessageRole, content: string, toolCalls?: ToolCall[], reasoning?: string): Message;
+/**
+ * 创建系统消息
+ */
+declare function system(content: string): Message;
+/**
+ * 创建用户消息
+ */
+declare function user(content: string): Message;
+/**
+ * 创建助手消息
+ */
+declare function assistant(content: string, toolCalls?: ToolCall[], reasoning?: string): Message;
+/**
+ * 创建工具返回消息
+ */
+declare function toolResult(toolCallId: string, content: string): Message;
+
+type AnthropicTextBlock = {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+};
+type AnthropicThinkingBlock = {
+    type: 'thinking';
+    thinking: string;
+    signature: string;
+};
+type AnthropicToolResultBlock = {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+};
+type AnthropicToolUseBlock = {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input?: unknown;
+};
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicThinkingBlock | AnthropicToolResultBlock | AnthropicToolUseBlock;
+interface AnthropicRequestMessage {
+    role: 'user' | 'assistant';
+    content: string | AnthropicContentBlock[];
+}
+interface AnthropicToolDef {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface CompiledAnthropicRequest {
+    system?: AnthropicTextBlock[];
+    messages: AnthropicRequestMessage[];
+    tools?: AnthropicToolDef[];
+}
+declare class AnthropicLLM implements LLMClient {
+    private readonly apiKey;
+    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>;
+}
+declare function compileContextForAnthropic(messages: Message[], tools: Tool[]): CompiledAnthropicRequest;
+declare function createAnthropicLLM(config: AgentConfigFile): AnthropicLLM;
+declare function createAnthropicLLM(modelConfig: ModelConfig): AnthropicLLM;
+declare function createAnthropicLLM(apiKey: string, modelName: string, baseUrl?: string): AnthropicLLM;
+
+/**
+ * OpenAI LLM 适配器
+ * 实现 LLMClient 接口
+ */
+
+declare class OpenAILLM implements LLMClient {
+    private client;
+    private modelName;
+    private maxTokens?;
+    private providerOptions?;
+    constructor(apiKey: string, modelName?: string, baseUrl?: string, maxTokens?: number, providerOptions?: Record<string, unknown>);
+    /**
+     * 聊天 - 核心方法（内部使用流式处理）
+     */
+    chat(messages: Message[], tools: Tool[]): Promise<LLMResponse>;
+}
+
+/**
+ * 从配置创建 OpenAI LLM 实例
+ *
+ * @example
+ *   // 方式1：传入配置文件对象（推荐）
+ *   const llm = createOpenAILLM(config);
+ *
+ * @example
+ *   // 方式2：传入模型配置
+ *   const llm = createOpenAILLM(config.defaultModel);
+ *
+ * @example
+ *   // 方式3：单独传参
+ *   const llm = createOpenAILLM(apiKey, 'gpt-4o', baseUrl);
+ *
+ * @example
+ *   // 方式4：自定义配置
+ *   const llm = createOpenAILLM({ apiKey: 'xxx', model: 'gpt-4o' });
+ */
+declare function createOpenAILLM(config: AgentConfigFile): OpenAILLM;
+declare function createOpenAILLM(modelConfig: ModelConfig): OpenAILLM;
+declare function createOpenAILLM(apiKey: string, modelName: string, baseUrl?: string): OpenAILLM;
+
+declare function createLLM(config: AgentConfigFile): LLMClient;
+declare function createLLM(modelConfig: ModelConfig): LLMClient;
+declare function createLLM(apiKey: string, modelName: string, provider?: string, baseUrl?: string): LLMClient;
+
+/**
+ * Viewer Worker - 在独立进程中运行 HTTP 服务器
+ * 支持多 Agent 调试，共享单端口
+ * 支持通过 UDS（Unix Domain Socket）或 Windows Named Pipe 接收来自多进程的连接
+ */
+
+declare class ViewerWorker {
+    private port;
+    private openBrowser;
+    private server;
+    private udsPath;
+    private udsServer?;
+    private udsClients;
+    private agentSessions;
+    private currentAgentId;
+    private featureTemplateMap;
+    private readonly debuggerMcp;
+    private readonly MAX_MESSAGES;
+    private readonly MAX_BYTES;
+    private readonly MAX_LOGS;
+    constructor(port: number, openBrowser?: boolean, udsPath?: string);
+    start(): Promise<void>;
+    /**
+     * 停止服务器
+     */
+    stop(): Promise<void>;
+    /**
+     * 启动 UDS 服务器
+     */
+    private startUDSServer;
+    /**
+     * 处理 UDS 消息（复用现有处理方法）
+     */
+    private handleUDSMessage;
+    private handleRequest;
+    /**
+     * 主页 - 带多 Agent 切换器
+     */
+    private handleIndex;
+    /**
+     * API 端点路由
+     */
+    private handleAPI;
+    /**
+     * GET /api/agents - 获取所有 Agent
+     */
+    private handleGetAgents;
+    /**
+     * GET /api/agents/current - 获取当前 Agent
+     */
+    private handleGetCurrentAgent;
+    /**
+     * PUT /api/agents/current - 切换当前 Agent
+     */
+    handleSetCurrentAgentHttp(req: IncomingMessage, res: ServerResponse): void;
+    /**
+     * GET /api/templates/feature - 获取 Feature 模板映射
+     */
+    handleGetFeatureTemplates(req: IncomingMessage, res: ServerResponse): void;
+    /**
+     * 将模板文件路径转换为 HTTP URL
+     * 支持多种来源：
+     * 1. 独立 npm 包 node_modules/@scope/package/dist/templates/xxx.render.js
+     * 2. npm 包 node_modules/agentdev/dist/features/xxx/templates/xxx.render.js
+     * 3. npm workspace 符号链接（路径是真实物理路径，但需要转换为 node_modules 路径）
+     * 4. 项目内 dist/features/xxx/templates/xxx.render.js
+     * 5. 项目内 src/features/xxx/templates/xxx.render.ts
+     * 6. 用户自定义路径
+     */
+    private templatePathToUrl;
+    /**
+     * 解析 npm workspace 符号链接
+     * 当 Feature 来自 npm workspace 时，import.meta.url 返回的是符号链接的真实物理路径
+     * 需要检查 node_modules 目录中的符号链接来确定包名
+     */
+    private npmWorkspaceCache;
+    private resolveNpmWorkspacePackage;
+    /**
+     * GET /api/agents/:id/messages - 获取指定 Agent 的消息
+     */
+    private handleGetAgentMessages;
+    /**
+     * GET /api/agents/:id/tools - 获取指定 Agent 的工具
+     */
+    private handleGetAgentTools;
+    private handleGetAgentHooks;
+    private handleGetAgentOverview;
+    /**
+     * GET /api/agents/:id/notification - 获取指定 Agent 的通知状态
+     */
+    private handleGetAgentNotification;
+    private handleGetLogs;
+    private handleGetMCPInfo;
+    /**
+     * GET /api/agents/:id/connection - 获取指定 Agent 的真实连接状态
+     */
+    private handleGetAgentConnection;
+    /**
+     * DELETE /api/agents/:id - 删除已断开的 Agent 会话
+     */
+    private handleDeleteAgent;
+    /**
+     * 获取输入请求列表
+     */
+    private handleGetInputRequests;
+    /**
+     * 提交用户输入
+     */
+    private handlePostInput;
+    /**
+     * 获取或创建会话
+     */
+    getOrCreateSession(agentId: string, name: string): AgentSession;
+    /**
+     * 更新会话活跃时间
+     */
+    updateSessionActivity(agentId: string): void;
+    private isSessionConnected;
+    /**
+     * 应用内存限制
+     */
+    enforceMemoryLimits(session: AgentSession): void;
+    /**
+     * 处理注册 Agent
+     */
+    handleRegisterAgent(msg: any, clientId?: string): void;
+    handleUpdateAgentInspector(msg: any): void;
+    handleUpdateAgentOverview(msg: {
+        agentId: string;
+        overview: AgentOverviewSnapshot;
+    }): void;
+    /**
+     * 清空 Feature 模板映射（当 Agent 断开连接时调用）
+     */
+    private clearFeatureTemplates;
+    /**
+     * 处理推送消息（带去重优化）
+     *
+     * 只有在消息真正变化时才更新会话并触发前端更新
+     */
+    handlePushMessages(msg: any): void;
+    private createEmptyOverview;
+    /**
+     * 检查消息是否发生变化
+     */
+    private hasMessagesChanged;
+    /**
+     * 获取最后一条消息的签名（用于变化检测）
+     *
+     * 使用消息的 role、content 和 toolCalls 生成签名
+     */
+    private getLastMessageSignature;
+    /**
+     * 处理注册工具
+     */
+    handleRegisterTools(msg: any): void;
+    /**
+     * 处理切换当前 Agent（IPC 消息）
+     */
+    handleSetCurrentAgent(msg: any): void;
+    /**
+     * 处理注销 Agent
+     */
+    handleUnregisterAgent(msg: any): void;
+    /**
+     * 处理停止
+     */
+    handleStop(): void;
+    /**
+     * 处理推送通知
+     */
+    handlePushNotification(msg: any): void;
+    private normalizeLogEntry;
+    private withSessionLogContext;
+    private parseNumberParam;
+    private listAgentSummaries;
+    private getAgentDetails;
+    private queryLogs;
+    private handleMCP;
+    /**
+     * 处理用户输入请求
+     */
+    handleRequestInput(msg: any): void;
+    /**
+     * 处理静态工具渲染文件
+     * 直接返回已编译的 .js 文件内容
+     * 路径规则：/tools/{category}/{filename}.js → dist/tools/{category}/{filename}.render.js
+     *
+     * 支持从多个位置查找：
+     * 1. 项目根目录 dist/tools/
+     * 2. npm 包 node_modules/agentdev/dist/tools/
+     */
+    handleStaticToolFile(req: IncomingMessage, res: ServerResponse, url: string): void;
+    /**
+     * 尝试从多个路径读取文件
+     */
+    private tryReadFile;
+    /**
+     * 处理统一的 Feature 模板路由（新格式）
+     * URL 格式: /template/{packageName}/{templateName}.render.js
+     *
+     * 统一支持三种来源：
+     * 1. 框架内置 Feature：/template/agentdev/visual/capture.render.js
+     *    映射到: node_modules/agentdev/dist/features/visual/templates/capture.render.js
+     *    或: dist/features/visual/templates/capture.render.js（开发模式）
+     *
+     * 2. 外部 npm 包：/template/@agentdev/shell-feature/bash.render.js
+     *    映射到: node_modules/@agentdev/shell-feature/dist/templates/bash.render.js
+     *
+     * 3. 用户本地 Feature：/template/my-project/visual/capture.render.js
+     *    映射到: dist/templates/capture.render.js
+     *    或: dist/features/visual/templates/capture.render.js
+     */
+    handleUnifiedTemplate(req: IncomingMessage, res: ServerResponse, url: string): void;
+    /**
+     * 处理 Feature 渲染模板文件
+     * 解析路径: /features/shell/trash-delete.render.js
+     *
+     * 支持从多个位置查找：
+     * 1. 项目根目录 dist/features/{feature}/templates/
+     * 2. 项目根目录 src/features/{feature}/templates/
+     * 3. npm 包 node_modules/agentdev/dist/features/{feature}/templates/
+     *
+     * 支持扩展名映射：
+     * - .js → 同时尝试 .js 和 .ts
+     */
+    handleFeatureTemplate(req: IncomingMessage, res: ServerResponse, url: string): void;
+    /**
+     * 处理 npm 包中的 Feature 模板
+     * 支持两种路径格式：
+     * 1. 独立包: /npm/@agentdev/shell-feature/templates/bash.render.js
+     *    映射到: node_modules/@agentdev/shell-feature/dist/templates/bash.render.js
+     * 2. 框架包: /npm/agentdev/features/shell/bash.render.js
+     *    映射到: node_modules/agentdev/dist/features/shell/templates/bash.render.js
+     */
+    handleNpmFeatureTemplate(req: IncomingMessage, res: ServerResponse, url: string): void;
+    private getHtml;
+}
+
+/**
+ * 占位符解析器
+ * 使用正则表达式实现占位符替换
+ */
+
+/**
+ * 占位符解析器
+ */
+declare class PlaceholderResolver {
+    private static PATTERNS;
+    /**
+     * 解析模板中的占位符
+     * @param template 模板内容
+     * @param context 变量上下文
+     * @returns 解析后的内容
+     */
+    static resolve(template: string, context?: PlaceholderContext): string;
+    /**
+     * 处理循环渲染 {{#each}}...{{/each}}
+     * 格式：{{#each}}arrayName
+     *   ...template...
+     * {{/each}}
+     * 在循环内可使用数组元素的字段（如 {{name}}, {{description}}）或 {{this}} 引用整个对象
+     */
+    private static processEach;
+    /**
+     * 处理条件渲染 {{#if}}...{{/if}}
+     * 条件格式：{{#if}}varName{{/if}} - 只有当 varName 为真时才显示内容
+     */
+    private static processConditionals;
+    /**
+     * 获取嵌套对象的值
+     * 支持点号分隔的路径，如 "user.name"
+     */
+    private static getNestedValue;
+    /**
+     * 获取模板中使用的变量列表
+     */
+    static extractVariables(template: string): string[];
+    /**
+     * 验证上下文是否包含所需变量
+     * @returns 缺失的变量数组
+     */
+    static validate(template: string, context: PlaceholderContext): string[];
+}
+
+/**
+ * 数据源注册系统
+ *
+ * 提供通用的列表数据渲染能力，Feature 可以注册自定义数据源
+ * 然后在 TemplateComposer 中使用 `{ dataSourceName: 'template' }` 语法
+ *
+ * @example
+ * ```typescript
+ * // 注册数据源
+ * DataSourceRegistry.register({
+ *   name: 'tasks',
+ *   getData: async () => [{ id: 1, title: 'Task 1', priority: 'high' }],
+ *   renderItem: (item, template, ctx) => {
+ *     return PlaceholderResolver.resolve(template, { ...ctx, ...item });
+ *   },
+ * });
+ *
+ * // 在模板中使用
+ * composer.add({ tasks: '- {{title}} ({{priority}})' });
+ * ```
+ */
+
+/**
+ * 数据源渲染器接口
+ */
+interface DataSourceRenderer<T = any> {
+    /** 数据源唯一标识 */
+    name: string;
+    /**
+     * 获取数据列表
+     * @param context 渲染上下文
+     * @returns 数据数组（可以是异步的）
+     */
+    getData(context: PlaceholderContext): Promise<T[]> | T[];
+    /**
+     * 渲染单个数据项
+     * @param item 数据项
+     * @param template 模板字符串
+     * @param context 渲染上下文
+     * @returns 渲染后的字符串
+     */
+    renderItem(item: T, template: string, context: PlaceholderContext): string;
+    /**
+     * 可选：判断是否启用该数据源
+     * @param context 渲染上下文
+     * @returns 是否启用（默认 true）
+     */
+    isEnabled?(context: PlaceholderContext): boolean;
+}
+/**
+ * 数据源注册中心
+ */
+declare class DataSourceRegistry {
+    private static sources;
+    /**
+     * 注册数据源
+     */
+    static register(renderer: DataSourceRenderer): void;
+    /**
+     * 注销数据源
+     */
+    static unregister(name: string): boolean;
+    /**
+     * 获取数据源
+     */
+    static get(name: string): DataSourceRenderer | undefined;
+    /**
+     * 检查数据源是否存在
+     */
+    static has(name: string): boolean;
+    /**
+     * 获取所有已注册的数据源名称
+     */
+    static names(): string[];
+    /**
+     * 渲染数据源
+     * @param name 数据源名称
+     * @param template 模板字符串
+     * @param context 渲染上下文
+     * @returns 渲染后的字符串
+     */
+    static render(name: string, template: string, context?: PlaceholderContext): Promise<string>;
+    /**
+     * 清空所有数据源（主要用于测试）
+     */
+    static clear(): void;
+}
+/**
+ * 创建列表渲染器的工厂函数
+ * 简化常见数据源的注册
+ *
+ * @example
+ * ```typescript
+ * DataSourceRegistry.register(createListRenderer({
+ *   name: 'tasks',
+ *   getData: (ctx) => ctx.tasks as Task[],
+ *   // 默认 renderItem 会将 item 合并到 context 中
+ * }));
+ * ```
+ */
+declare function createListRenderer<T = any>(config: Omit<DataSourceRenderer<T>, 'renderItem'> & {
+    /** 自定义渲染函数（可选） */
+    renderItem?: DataSourceRenderer<T>['renderItem'];
+    /** 是否合并 item 到 context（默认 true） */
+    mergeItem?: boolean;
+}): DataSourceRenderer<T>;
+
+/**
+ * Agent Skills 加载器
+ * 扫描目录，解析 SKILL.md 文件
+ */
+
+/**
+ * 发现并加载指定目录下的所有 skills
+ * @param options Skills 配置选项
+ * @returns Skill 元数据列表
+ */
+declare function discover(options?: SkillsOptions): Promise<SkillMetadata[]>;
+
+/**
+ * MCP Tool Adapter - 适配器模式实现
+ *
+ * 将 MCP 工具适配为现有 Tool 接口，保持架构一致性
+ */
+
+/**
+ * 注册工具的简化接口
+ * 用于适配器包装
+ */
+interface RegisteredToolLike {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+    outputSchema?: any;
+    annotations?: any;
+    handler?: (args: any, context?: any) => Promise<any> | any;
+    enabled?: boolean;
+}
+/**
+ * MCP 工具适配器配置
+ */
+interface MCPToolAdapterConfig {
+    /** MCP 服务器名称 */
+    serverName: string;
+    /** 是否为只读工具 */
+    readOnly?: boolean;
+    /** 渲染模板覆盖 */
+    render?: {
+        call?: string;
+        result?: string;
+    };
+}
+/**
+ * MCP 工具适配器
+ *
+ * 将 MCP RegisteredTool 适配为 Agent 的 Tool 接口
+ * 负责格式转换和生命周期管理
+ */
+declare class MCPToolAdapter implements Tool {
+    private registeredTool;
+    private config;
+    readonly name: string;
+    readonly description: string;
+    readonly parameters?: Record<string, any>;
+    readonly render?: {
+        call?: string;
+        result?: string;
+    };
+    constructor(registeredTool: RegisteredToolLike, config: MCPToolAdapterConfig);
+    /**
+     * 执行 MCP 工具
+     */
+    execute(args: any, context?: any): Promise<any>;
+    /**
+     * 格式化 MCP 工具结果
+     */
+    private formatResult;
+    /**
+     * 格式化错误
+     */
+    private formatError;
+    /**
+     * 从 RegisteredToolLike 提取参数定义
+     *
+     * MCP 工具的 inputSchema 已经是 JSON Schema 格式
+     * 直接返回，不需要转换
+     */
+    private extractParameters;
+}
+/**
+ * 批量创建 MCP 工具适配器
+ */
+declare function createMCPToolAdapters(registeredTools: RegisteredToolLike[], serverName: string, config?: Omit<MCPToolAdapterConfig, 'serverName'>): Tool[];
+
+interface MCPDiscoveredTool {
+    name: string;
+    description?: string;
+    inputSchema?: any;
+}
+interface MCPToolCreationOptions {
+    name?: string;
+    description?: string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: (args: Record<string, unknown>, context?: any) => Record<string, unknown>;
+}
+interface MCPToolDiscoveryOptions {
+    filter?: (tool: MCPDiscoveredTool) => boolean;
+    mapName?: (tool: MCPDiscoveredTool) => string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+}
+interface MCPDiscoveredToolSet {
+    client: MCPClient;
+    tools: Tool[];
+}
+declare function createDefaultMCPToolName(serverId: string, toolName: string): string;
+declare class MCPClient {
+    readonly serverId: string;
+    private readonly config;
+    private readonly manager;
+    private connected;
+    constructor(serverId: string, config: MCPServerConfig, manager?: MCPConnectionManager);
+    connect(): Promise<void>;
+    listTools(): Promise<MCPDiscoveredTool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    getConnectionManager(): MCPConnectionManager;
+    dispose(): Promise<void>;
+}
+declare function createMCPTool(client: MCPClient, tool: MCPDiscoveredTool, options?: MCPToolCreationOptions): Tool;
+declare function createMCPToolsFromClient(client: MCPClient, options?: MCPToolDiscoveryOptions): Promise<Tool[]>;
+declare function discoverMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolDiscoveryOptions, manager?: MCPConnectionManager): Promise<MCPDiscoveredToolSet>;
+
+interface LoadAllMCPConfigsOptions {
+    excludeServers?: string[];
+}
+declare function getDefaultMCPConfigDir(rootDir?: string): string;
+declare function loadMCPConfigFromInput(input: string, rootDir?: string): MCPConfig | undefined;
+declare function loadAllMCPConfigs(rootDir?: string, options?: LoadAllMCPConfigsOptions): MCPConfig | undefined;
+
+interface MCPToolPatch {
+    enabled?: boolean;
+    name?: string;
+    description?: string;
+    render?: MCPToolAdapterConfig['render'];
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+}
+interface MCPToolManagementOptions {
+    include?: string[];
+    exclude?: string[];
+    disable?: string[];
+    rename?: Record<string, string>;
+    describe?: Record<string, string>;
+    render?: MCPToolAdapterConfig['render'];
+    toolRender?: Record<string, MCPToolAdapterConfig['render']>;
+    mapName?: (tool: MCPDiscoveredTool, client: MCPClient) => string;
+    transformArgs?: MCPToolCreationOptions['transformArgs'];
+    transform?: (tool: MCPDiscoveredTool, client: MCPClient) => MCPToolPatch | false | null | undefined;
+}
+interface MCPConfigMountOptions {
+    manager?: MCPConnectionManager;
+    clients?: Map<string, MCPClient>;
+    getServerOptions?: (serverId: string, serverConfig: MCPServerConfig) => MCPToolManagementOptions | undefined;
+    onError?: (serverId: string, error: unknown) => void;
+}
+interface MCPMountedToolSet {
+    client: MCPClient;
+    tools: Tool[];
+}
+interface MCPMountedConfigResult {
+    tools: Tool[];
+    clients: Map<string, MCPClient>;
+}
+declare function createManagedMCPToolsFromClient(client: MCPClient, options?: MCPToolManagementOptions): Promise<Tool[]>;
+declare function discoverManagedMCPTools(serverId: string, config: MCPServerConfig, options?: MCPToolManagementOptions, manager?: MCPConnectionManager): Promise<MCPMountedToolSet>;
+declare function mountMCPToolsFromConfig(config: MCPConfig, options?: MCPConfigMountOptions): Promise<MCPMountedConfigResult>;
+
+/**
+ * MCP 工具渲染模板
+ *
+ * 定义 MCP 工具在 DebugHub 中的显示样式
+ */
+/**
+ * MCP 工具渲染模板
+ */
+declare const MCP_RENDER_TEMPLATES: {
+    /**
+     * MCP 工具调用显示
+     */
+    readonly 'mcp-tool': {
+        readonly call: (args: any) => string;
+        readonly result: (data: any, success?: boolean) => string;
+    };
+    /**
+     * MCP 结果 (简化版)
+     */
+    readonly 'mcp-result': {
+        readonly call: () => string;
+        readonly result: (data: any, success?: boolean) => string;
+    };
+};
+/**
+ * 获取 MCP 渲染模板
+ */
+declare function getMCPRenderTemplate(toolName: string): string;
+/**
+ * 渲染 MCP 工具调用
+ */
+declare function renderMCPToolCall(serverName: string, toolName: string, args: Record<string, any>): string;
+/**
+ * 渲染 MCP 工具结果
+ */
+declare function renderMCPToolResult(result: any, success?: boolean): string;
+
+export { AgentBase as Agent, type AgentConfig, type AgentConfigFile, type AgentFeature, type AgentInfo, type AgentInitiateContext, AgentPool, type AgentSession, type AgentSessionSnapshot, AnthropicLLM, BasicAgent, type BasicAgentConfig, type CacheStats, CallStart, type CallStartContext, Context, type ContextInjector, type ContextMiddleware, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, type DebugHubIPCMessage, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureContext, type FeatureInitContext, type FeatureStateSnapshot, FileSessionStore, type HookResult, type InlineRenderTemplate, type LLMClient, type LLMResponse, type LoadAllMCPConfigsOptions, 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, type Message, type MessageRole, type ModelConfig, OpenAILLM, OpencodeBasicFeature, type PackageInfo, type PlaceholderContext, PlaceholderResolver, type SessionStore, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, SubAgentFeature, type SystemContext$1 as SystemContext, type TaskStatus, TemplateComposer, TemplateError, TemplateLoader, type TemplateLoaderOptions, type TemplateResult, type TemplateSource, TodoFeature, type TodoFeatureConfig, type TodoTask, type TodoTaskSummary, type Tool, type ToolCall, type ToolContext, type ToolContextValue, type ToolMetadata, ToolRegistry, type ToolRenderConfig, type ToolResult, UserInputFeature, type UserInputFeatureConfig, ViewerWorker, assistant, compileContextForAnthropic, createAnthropicLLM, createDefaultMCPToolName, createLLM, createListRenderer, createMCPTool, createMCPToolAdapters, createMCPToolsFromClient, createManagedMCPToolsFromClient, createMessage, createOpenAILLM, createTool, discover, discoverMCPTools, discoverManagedMCPTools, getClawRuntimeUrl, getDebugCapabilities, getDefaultMCPConfigDir, getDefaultSessionStore, getDefaultUDSPath, getMCPRenderTemplate, getPackageInfoFromSource, listConfigs, loadAllMCPConfigs, loadConfig, loadConfigSync, loadMCPConfigFromInput, mountMCPToolsFromConfig, renderMCPToolCall, renderMCPToolResult, resolveDebugTransportMode, system, toolResult, user };