@agentdevjs/core 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,171 +1,44 @@
 import { EventEmitter } from 'events';
 import { Diagnostic } from 'vscode-languageserver-types';
 
-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;
-}
-declare function installConsoleBridge(): void;
-declare function runWithLogScope<T>(scope: LogContextRef, fn: () => T): T;
-declare function emitLog(level: LogLevel, message: string, data?: unknown, options?: {
-    namespace?: string;
-    context?: LogContextRef;
-}): DebugLogEntry;
-declare function createLogger(namespace: string, bindings?: LoggerBindings): Logger;
-
-/**
- * Capability System - 统一能力控制面（P1：command）
- *
- * Feature 通过 getCapabilities() 声明可被显式调用的命令，注册表提供
- * 平面寻址（`featureName.commandName`）与三动词中的 invoke 语义。
- *
- * 设计裁决（详见 AgentDevClaw docs/adr capability-registry-as-control-plane）：
- * - 命令式优先：只有 invoke / query / emit，不存在 bind / reactive / watch。
- *   共享权威状态与跨 feature 事务是负面清单，不做。
- * - entryPoints 是契约约束而非安全边界：声明不含请求入口的 command 被
- *   invoke 时返回 entry_point_denied（结构化错误，非静默失败）。绕过
- *   路径（getFeature 直引）依旧存在，这是已知边界而非漏洞。
- * - 进程内语义：args 是普通 JS 值，不为序列化设计。跨进程投递是宿主层
- *   职责，注册表不为其建模。
- * - 注册表是哑的：不做参数校验（schema 服务于消费端渲染表单）、不含
- *   派发策略、不管依赖管理。
- * - 命令超时即失败：超时返回 timeout，但执行体可能仍在进行（Promise
- *   无法取消），不保证中断，只保证调用方不挂死。
- */
-
 /**
- * 能力入口类型
+ * Continuation Request 类型定义
  *
- * - 'slash'：出现在用户命令菜单（宿主下发清单时过滤）
- * - 'feature'：可被其他 feature（或经宿主转发的等价调用）invoke
+ * 控制工具（如 checkpoint、rollback）通过 registerContinuationRequest()
+ * 登记一个 continuation request，使当前 onCall 在合法边界停止。
+ * 宿主（如 CallArbiter）通过 consumeContinuationRequest() 消费该请求，
+ * 决定是否在同一个逻辑 envelope 内启动下一个 onCall segment。
  */
-type CapabilityEntryPoint = 'slash' | 'feature';
 /**
- * 命令类型。框架层仅定义形状并透传——两种 kind 在框架眼里同质
- * （收到 invoke 一律执行 execute）；行为差异（表单/pill/toast/触发
- * 时机）由应用层（宿主前端）按 kind 消费。
+ * Checkpoint continuation request
  *
- * - invoke（缺省）：选中即执行的触发型命令（配置开关等）
- * - prompt：调用指令以文本形式嵌入输入的命令（skill 等），
- *   应用层负责其呈现与发送时机，feature 在自身生命周期内消费
- */
-type CapabilityKind = 'invoke' | 'prompt';
-/**
- * Feature 声明的可调用命令
- */
-interface CapabilityDefinition {
-    /** 命令名（标识符），注册表内以 `featureName.commandName` 寻址 */
-    name: string;
-    /** 命令类型，缺省 'invoke'。框架透传不解释，语义由应用层消费 */
-    kind?: CapabilityKind;
-    /** 菜单显示标题，缺省用 name */
-    title?: string;
-    /** 菜单描述 */
-    description?: string;
-    /**
-     * 参数 schema，复用 FeatureManifestSettingProperty 词汇表，
-     * 与 feature-setup 配置表单、flow 交互选项共用一套渲染基底。
-     */
-    parameters?: Record<string, FeatureManifestSettingProperty>;
-    /**
-     * 可见入口，缺省 ['feature']（最小暴露）。
-     * 进 slash 菜单必须是显式主动行为。
-     */
-    entryPoints?: CapabilityEntryPoint[];
-    /**
-     * 参数当前生效值（配置回显）：参数表单打开时优先于 parameters 的
-     * default 显示。返回普通对象，键与 parameters 对齐；缺省或抛错
-     * 时表单回退 default。读取必须无副作用。
-     */
-    readCurrentValues?: () => Record<string, unknown>;
-    /** 执行体。抛出的任何错误归一为 execute_failed */
-    execute(args: Record<string, unknown>, ctx: CapabilityContext): Promise<unknown>;
-}
-/**
- * 命令执行上下文（进程内）
+ * Agent 建立了一个命名检查点，希望继续执行。
+ * 宿主应捕获当前 runtime snapshot 并将其与 checkpointId 关联，
+ * 然后启动 continuation segment。
  */
-interface CapabilityContext {
-    agentId: string;
-    getFeature<T extends AgentFeature>(name: string): T | undefined;
-    logger: Logger;
+interface CheckpointContinuationRequest {
+    kind: 'checkpoint';
+    checkpointId: string;
+    /** 可选附加元数据（如 Agent 的自由备注） */
+    metadata?: Record<string, unknown>;
 }
 /**
- * invoke 的结构化结果。错误码是稳定契约：
- * - not_found：ref 未注册
- * - entry_point_denied：该入口不在 entryPoints 中
- * - execute_failed：执行体抛错
- * - timeout：超过时限（执行体不保证被取消）
- */
-type CapabilityInvokeResult = {
-    ok: true;
-    result: unknown;
-} | {
-    ok: false;
-    code: 'not_found' | 'entry_point_denied' | 'execute_failed' | 'timeout';
-    message: string;
-};
-/**
- * 清单快照条目（下发宿主 / 前端菜单消费的数据形态，纯数据）
+ * Rollback continuation request
+ *
+ * Agent 希望回退到指定 checkpoint，并携带一个失败分支的摘要。
+ * 宿主应恢复到 checkpoint 的 runtime snapshot，
+ * 然后以摘要作为 continuation segment 的输入启动新的 onCall。
  */
-interface CapabilitySnapshot {
-    feature: string;
-    name: string;
-    ref: string;
-    /** 命令类型（缺省 'invoke'），透传给应用层消费 */
-    kind: CapabilityKind;
-    title: string;
-    description?: string;
-    parameters?: Record<string, FeatureManifestSettingProperty>;
-    entryPoints: CapabilityEntryPoint[];
-    /** 参数当前生效值（readCurrentValues 收集；读取失败时缺省） */
-    currentValues?: Record<string, unknown>;
+interface RollbackContinuationRequest {
+    kind: 'rollback';
+    checkpointId: string;
+    /** Agent 生成的失败分支摘要 */
+    summary: string;
 }
 /**
- * 能力注册表（per-Agent 实例）
+ * 受类型约束的 continuation request
  */
-declare class CapabilityRegistry {
-    private defs;
-    /**
-     * 注册 feature 的命令。ref（`feature.name`）重复视为装配错误，直接抛出，
-     * 对齐 feature-graph 的报错哲学。
-     */
-    register(featureName: string, def: CapabilityDefinition): void;
-    has(ref: string): boolean;
-    /** ref → 所属 feature 名（dispatchTurnActivations 按 owner 分组派发用） */
-    ownerOf(ref: string): string | null;
-    /** ref → 命令类型（缺省 'invoke'）；未注册返回 null */
-    kindOf(ref: string): CapabilityKind | null;
-    /**
-     * 移除指定 feature 的全部命令（幂等）。
-     * initSingleFeature 重挂路径先调它，避免热载时误报 duplicate ref。
-     */
-    unregisterFeature(featureName: string): void;
-    /**
-     * 清单快照。传入 entryPoint 时过滤出该入口可见的命令
-     * （宿主下发 slash 菜单清单时用 { entryPoint: 'slash' }）。
-     */
-    list(filter?: {
-        entryPoint?: CapabilityEntryPoint;
-    }): CapabilitySnapshot[];
-    /**
-     * 调用命令。entryPoint 必填——调用方声明自己以哪个入口进来，
-     * 注册表据此执行 entryPoints 契约检查。
-     */
-    invoke(ref: string, opts: {
-        args?: Record<string, unknown>;
-        entryPoint: CapabilityEntryPoint;
-        timeoutMs?: number;
-    }, ctx: CapabilityContext): Promise<CapabilityInvokeResult>;
-}
+type CallContinuationRequest = CheckpointContinuationRequest | RollbackContinuationRequest;
 
 /**
  * 模板加载器
@@ -188,7 +61,7 @@ declare class TemplateLoader {
     /**
      * 加载模板（同步）
      */
-    loadSync(templatePath: string): string;
+    loadSync(_templatePath: string): string;
     /**
      * 解析路径为绝对路径
      * @param templatePath 模板路径
@@ -219,46 +92,157 @@ declare class TemplateLoader {
 }
 
 /**
- * 模板组合器
- * 支持流式 API 和灵活拼接
+ * 数据源注册系统
+ *
+ * 提供通用的列表数据渲染能力，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}})' });
+ * ```
  */
 
 /**
- * 模板组合器
+ * 数据源渲染器接口
  */
-declare class TemplateComposer {
-    private parts;
-    private separator;
-    private loader;
-    private _dataSourceRegistry?;
-    constructor(loader?: TemplateLoader);
+interface DataSourceRenderer<T = any> {
+    /** 数据源唯一标识 */
+    name: string;
     /**
-     * 设置 Agent 级数据源注册表实例
-     * 由 TemplateResolver 在渲染前调用，嵌套 composer 会自动继承。
+     * 获取数据列表
+     * @param context 渲染上下文
+     * @returns 数据数组（可以是异步的）
      */
-    setDataSourceRegistry(registry?: DataSourceRegistry): this;
+    getData(context: PlaceholderContext): Promise<T[]> | T[];
     /**
-     * 添加模板源
+     * 渲染单个数据项
+     * @param item 数据项
+     * @param template 模板字符串
+     * @param context 渲染上下文
+     * @returns 渲染后的字符串
      */
-    add(source: TemplateSource | TemplateComposer): this;
+    renderItem(item: T, template: string, context: PlaceholderContext): string;
     /**
-     * 添加模板源（别名）
+     * 可选：判断是否启用该数据源
+     * @param context 渲染上下文
+     * @returns 是否启用（默认 true）
      */
-    append(source: TemplateSource | TemplateComposer): this;
+    isEnabled?(context: PlaceholderContext): boolean;
+}
+/**
+ * 数据源注册中心（per-Agent 实例）
+ *
+ * 历史上此类是 static（进程全局），在共享进程模式下多个 Agent 实例
+ * 会互相覆盖数据源。现已改为实例化：每个 Agent 持有独立的注册表，
+ * 由 FeatureInitContext.dataSourceRegistry 传递给各 Feature。
+ */
+declare class DataSourceRegistry {
+    private sources;
     /**
-     * 在头部插入
+     * 注册数据源
      */
-    prepend(source: TemplateSource | TemplateComposer): this;
+    register(renderer: DataSourceRenderer): void;
     /**
-     * 添加多个模板源
+     * 注销数据源
      */
-    addAll(...sources: (TemplateSource | TemplateComposer)[]): this;
+    unregister(name: string): boolean;
     /**
-     * 设置分隔符
+     * 获取数据源
      */
-    joinWith(sep: string): this;
+    get(name: string): DataSourceRenderer | undefined;
     /**
-     * 条件添加
+     * 检查数据源是否存在
+     */
+    has(name: string): boolean;
+    /**
+     * 获取所有已注册的数据源名称
+     */
+    names(): string[];
+    /**
+     * 渲染数据源
+     * @param name 数据源名称
+     * @param template 模板字符串
+     * @param context 渲染上下文
+     * @returns 渲染后的字符串
+     */
+    render(name: string, template: string, context?: PlaceholderContext): Promise<string>;
+    /**
+     * 清空所有数据源（主要用于测试）
+     */
+    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>;
+
+/**
+ * 模板组合器
+ * 支持流式 API 和灵活拼接
+ */
+
+/**
+ * 模板组合器
+ */
+declare class TemplateComposer {
+    private parts;
+    private separator;
+    private loader;
+    private _dataSourceRegistry?;
+    constructor(loader?: TemplateLoader);
+    /**
+     * 设置 Agent 级数据源注册表实例
+     * 由 TemplateResolver 在渲染前调用，嵌套 composer 会自动继承。
+     */
+    setDataSourceRegistry(registry?: DataSourceRegistry): this;
+    /**
+     * 添加模板源
+     */
+    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;
     /**
@@ -302,6 +286,7 @@ declare class TemplateComposer {
 /**
  * 提示词模板系统 - 核心类型定义
  */
+
 /**
  * 模板源
  * - string: 硬编码字符串
@@ -385,2136 +370,2234 @@ declare class TemplateError extends Error {
 }
 
 /**
- * 数据源注册系统
+ * UsageStats - 用量统计系统
  *
- * 提供通用的列表数据渲染能力，Feature 可以注册自定义数据源
- * 然后在 TemplateComposer 中使用 `{ dataSourceName: 'template' }` 语法
+ * 职责：
+ * - 记录 LLM 调用的 token 用量
+ * - 聚合 session/call/step 三级统计
+ * - 提供快照序列化和恢复
+ * - 格式化用量报告
  *
- * @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 });
- *   },
- * });
+ * 设计原则：
+ * - 框架内置，不是 Feature
+ * - 自动收集，不需要手动干预
+ * - 快照包含 session 级数据，用于会话恢复
+ */
+/**
+ * 统一用量格式（兼容 Anthropic 和 OpenAI）
+ */
+interface UsageInfo {
+    /** 输入 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;
+}
+/**
+ * 单次 LLM 调用的模型归因（轮换 / mid-turn 热切换场景下每次请求可能不同）
+ */
+interface ModelUsageKey {
+    /** 模型名（getLLMMeta().modelName） */
+    modelName?: string;
+    /** preset 名（getLLMMeta().presetName） */
+    presetName?: string;
+}
+/**
+ * Call 内按模型分段的用量汇总。
  *
- * // 在模板中使用
- * composer.add({ tasks: '- {{title}} ({{priority}})' });
- * ```
+ * 一次 call 内发生模型切换时，用量归因以每次 LLM 请求发出时刻的模型为准；
+ * totalUsage 仍是整 call 聚合，分段是它的模型维度拆分。
  */
-
+interface ModelUsageSegment {
+    modelName: string;
+    presetName: string;
+    usage: UsageInfo;
+    /** 该模型承担的 LLM 请求数 */
+    requests: number;
+    /** 该模型命中缓存的请求数 */
+    cacheHitRequests: number;
+}
 /**
- * 数据源渲染器接口
+ * 单次 Call 用量汇总
  */
-interface DataSourceRenderer<T = any> {
-    /** 数据源唯一标识 */
-    name: string;
+interface CallUsageSummary {
+    callIndex: number;
+    totalUsage: UsageInfo;
+    stepCount: number;
+    cacheHitRequests: number;
+    startTime: number;
+    endTime?: number;
+    /** 按模型分段的用量（record 未携带模型归因时为空） */
+    modelSegments?: ModelUsageSegment[];
+}
+/**
+ * Session 用量快照（用于序列化）
+ */
+interface UsageStatsSnapshot {
+    /** Session 级累计用量 */
+    totalUsage: UsageInfo;
+    /** 各 Call 的用量汇总 */
+    calls: CallUsageSummary[];
+    /** 总请求数（LLM 调用次数） */
+    totalRequests: number;
+    /** 命中缓存的请求数（request-level） */
+    totalCacheHitRequests: number;
+    /** 最后一次请求的用量（用于显示当前上下文占用） */
+    lastRequestUsage?: UsageInfo;
+}
+/**
+ * 用量统计类
+ */
+declare class UsageStats {
+    /** Session 级累计用量 */
+    private totalUsage;
+    /** 当前活跃 Call 的用量记录 */
+    private currentCallUsage;
+    /** 总 LLM 调用次数 */
+    private totalRequests;
+    /** 命中缓存的总请求数 */
+    private totalCacheHitRequests;
+    /** 当前 Call 的 Step 记录（临时，用于聚合） */
+    private currentStepRecords;
+    /** 最后一次 LLM 调用的用量（用于显示当前上下文占用） */
+    private lastRequestUsage;
     /**
-     * 获取数据列表
-     * @param context 渲染上下文
-     * @returns 数据数组（可以是异步的）
+     * 记录一次 LLM 调用的用量
+     * @param callIndex Call 序号
+     * @param step Step 序号
+     * @param usage 用量数据
+     * @param model 该次请求的模型归因；缺省时不产生分段
      */
-    getData(context: PlaceholderContext): Promise<T[]> | T[];
+    record(callIndex: number, step: number, usage: UsageInfo, model?: ModelUsageKey): void;
     /**
-     * 渲染单个数据项
-     * @param item 数据项
-     * @param template 模板字符串
-     * @param context 渲染上下文
-     * @returns 渲染后的字符串
+     * 标记 Call 结束
+     * @param callIndex Call 序号
      */
-    renderItem(item: T, template: string, context: PlaceholderContext): string;
+    endCall(callIndex: number): void;
     /**
-     * 可选：判断是否启用该数据源
-     * @param context 渲染上下文
-     * @returns 是否启用（默认 true）
+     * 获取 Session 级累计用量
      */
-    isEnabled?(context: PlaceholderContext): boolean;
-}
-/**
- * 数据源注册中心（per-Agent 实例）
- *
- * 历史上此类是 static（进程全局），在共享进程模式下多个 Agent 实例
- * 会互相覆盖数据源。现已改为实例化：每个 Agent 持有独立的注册表，
- * 由 FeatureInitContext.dataSourceRegistry 传递给各 Feature。
- */
-declare class DataSourceRegistry {
-    private sources;
+    getTotalUsage(): UsageInfo;
+    /** Call 汇总的深拷贝（totalUsage 与 modelSegments 均独立副本） */
+    private cloneCallSummary;
     /**
-     * 注册数据源
+     * 获取指定 Call 的用量汇总
+     * @param callIndex Call 序号
      */
-    register(renderer: DataSourceRenderer): void;
+    getCallUsage(callIndex: number): CallUsageSummary | undefined;
     /**
-     * 注销数据源
+     * 获取所有 Call 的用量汇总
      */
-    unregister(name: string): boolean;
+    getAllCallUsage(): CallUsageSummary[];
     /**
-     * 获取数据源
+     * 获取总请求次数
      */
-    get(name: string): DataSourceRenderer | undefined;
+    getTotalRequests(): number;
+    getTotalCacheHitRequests(): number;
     /**
-     * 检查数据源是否存在
+     * 获取最后一次请求的用量（用于显示当前上下文占用）
      */
-    has(name: string): boolean;
+    getLastRequestUsage(): UsageInfo | null;
     /**
-     * 获取所有已注册的数据源名称
+     * 获取格式化的用量报告
      */
-    names(): string[];
+    getReport(): string;
     /**
-     * 渲染数据源
-     * @param name 数据源名称
-     * @param template 模板字符串
-     * @param context 渲染上下文
-     * @returns 渲染后的字符串
+     * 创建快照（用于序列化）
      */
-    render(name: string, template: string, context?: PlaceholderContext): Promise<string>;
+    toSnapshot(): UsageStatsSnapshot;
     /**
-     * 清空所有数据源（主要用于测试）
+     * 从快照恢复
      */
-    clear(): void;
+    fromSnapshot(snapshot: UsageStatsSnapshot): void;
+    /**
+     * 重置统计（谨慎使用）
+     */
+    reset(): void;
 }
+
 /**
- * 创建列表渲染器的工厂函数
- * 简化常见数据源的注册
+ * 上下文查询构建器
  *
- * @example
- * ```typescript
- * DataSourceRegistry.register(createListRenderer({
- *   name: 'tasks',
- *   getData: (ctx) => ctx.tasks as Task[],
- *   // 默认 renderItem 会将 item 合并到 context 中
- * }));
- * ```
+ * 提供链式 API 用于过滤和聚合消息
+ * 从 ContextFeature 移植到内核，作为 Context 的原生能力
  */
-declare function createListRenderer<T = any>(config: Omit<DataSourceRenderer<T>, 'renderItem'> & {
-    /** 自定义渲染函数（可选） */
-    renderItem?: DataSourceRenderer<T>['renderItem'];
-    /** 是否合并 item 到 context（默认 true） */
-    mergeItem?: boolean;
-}): DataSourceRenderer<T>;
 
 /**
- * Feature 上下文值类型
- */
-type ToolContextValue = Record<string, unknown>;
-/**
- * Feature 上下文注入器
- * 返回要注入到 tool.execute() 的额外参数
- */
-type ContextInjector = (call: ToolCall) => ToolContextValue;
-/**
- * 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 级数据源注册表（per-Agent 实例，非进程全局） */
-    dataSourceRegistry: DataSourceRegistry;
-}
-/**
- * Feature 运行时上下文
- */
-interface FeatureContext {
-    agentId: string;
-    config: AgentConfig;
-    getFeature<T extends AgentFeature>(name: string): T | undefined;
-}
-/**
- * Feature 快照状态
- *
- * 第一阶段只支持显式白名单状态：
- * - Feature 自己决定要保存什么
- * - 未声明的状态一律不保证恢复
- */
-type FeatureStateSnapshot = unknown;
-/**
- * 包信息
- */
-interface PackageInfo {
-    /** 包名，如 '@agentdevjs/shell-feature' 或 'agentdev' */
-    name: string;
-    /** 版本号（可选） */
-    version?: string;
-    /** 包根目录绝对路径 */
-    root: string;
-}
-/**
- * Feature Manifest 配置项
- *
- * 用于声明 Feature 在 Agent Project 级别可配置的静态参数。
- * Claw 等消费端可根据该契约自动渲染表单。
- */
-interface FeatureManifestSettingProperty {
-    type: 'string' | 'number' | 'boolean' | 'select' | 'file' | 'directory' | 'group';
-    title: string;
-    description?: string;
-    default?: unknown;
-    options?: Array<{
-        label: string;
-        value: string | number | boolean;
-    }>;
-    placeholder?: string;
-    /** number 类型下的最小值 */
-    min?: number;
-    /** number 类型下的最大值 */
-    max?: number;
-    /** number 类型下的步进值 */
-    step?: number;
-    /** file 类型下的可接受文件类型，如 '.mp3,.wav' 或 'audio/*' */
-    accept?: string | string[];
-    /** directory 类型下的最大条目数 */
-    maxItems?: number;
-    /** type: 'group' 时的嵌套子属性 */
-    properties?: Record<string, FeatureManifestSettingProperty>;
-    /** 条件可见性：仅当同级指定属性值在 values 中时渲染此字段 */
-    showWhen?: {
-        property: string;
-        values: (string | number | boolean)[];
-    };
-}
-interface FeatureManifestDefinition {
-    schemaVersion: 1;
-    settings?: {
-        properties: Record<string, FeatureManifestSettingProperty>;
-        /** 有序分区，用于 UI 分组渲染。省略则平铺全部属性 */
-        sections?: Array<{
-            id: string;
-            title: string;
-            description?: string;
-            /** 分区内属性 key 的显示顺序 */
-            properties: string[];
-        }>;
-    };
-}
-/**
- * Agent Feature 接口
+ * 上下文查询构建器
  *
- * 可外挂的功能模块，提供工具和上下文注入
+ * 提供链式 API 用于过滤和聚合消息
  */
-interface AgentFeature {
-    /** Feature 名称 */
-    readonly name: string;
+declare class ContextQuery {
+    private messages;
+    private indexes;
+    constructor(messages: EnrichedMessage[], indexes: Map<string, Set<string>>);
+    private result;
     /**
-     * 依赖的其他 Feature（装配时拓扑排序，工作项 A3）。
-     *
-     * 声明位置在类的静态属性上（实例字段无法装配时静态读取）：
-     * ```typescript
-     * class MyFeature implements AgentFeature {
-     *   name = 'my-feature';
-     *   static inject = ['storage'];
-     * }
-     * ```
-     * 读取与校验见 feature-graph.ts（readInjectDeclarations / resolveFeatureOrder）。
+     * 按角色过滤
      */
+    byRole(...roles: string[]): this;
     /**
-     * Feature 源文件路径（import.meta.url）。
-     *
-     * 既是调试器展示的源码位置，也是框架自动发现 Feature 自带资源的唯一锚点。
-     *
-     * 约定：Feature 的所有静态资源放在 source 文件的同级目录下。
-     * 框架会自动扫描 `dirname(source)/skills/` 发现内置 skill 并注入系统提示词。
-     * 其他资源（图片、模板等）由 Feature 代码通过 import.meta.url 自行解析。
-     *
-     * 标准写法（由 create-feature 脚手架自动生成）：
-     * ```typescript
-     * readonly source = fileURLToPath(import.meta.url).replace(/\\/g, '/');
-     * ```
+     * 按标签过滤（可组合）
      */
-    readonly source?: string;
-    /** 可选：用于调试器展示的 Feature 描述 */
-    readonly description?: string;
+    byTag(...tags: MessageTag[]): this;
     /**
-     * 获取同步工具（已知工具列表）
+     * 按工具名过滤（使用索引加速）
      */
-    getTools?(): Tool[];
+    byTool(name: string): this;
     /**
-     * 获取异步工具（需要连接、发现等）
+     * 按任务 ID 过滤（使用索引加速）
      */
-    getAsyncTools?(ctx: FeatureInitContext): Promise<Tool[]>;
+    byTask(taskId: string): this;
     /**
-     * 获取包信息
-     *
-     * 返回 Feature 所在的包信息（包名、版本、根目录）
-     * 用于统一模板路径解析和包管理
-     *
-     * @returns 包信息，如果 Feature 不属于任何包则返回 null
-     *
-     * @example
-     * ```typescript
-     * getPackageInfo(): PackageInfo | null {
-     *   return {
-     *     name: '@agentdevjs/shell-feature',
-     *     version: '1.0.0',
-     *     root: '/path/to/package/root'
-     *   };
-     * }
-     * ```
+     * 按子代理 ID 过滤
      */
-    getPackageInfo?(): PackageInfo | null;
+    byAgentId(agentId: string): this;
     /**
-     * 获取模板名称列表
-     *
-     * 返回 Feature 提供的模板名称列表（不含扩展名）
-     * 模板文件必须位于 {packageRoot}/dist/templates/{templateName}.render.js
-     *
-     * @returns 模板名称数组
-     *
-     * @example
-     * ```typescript
-     * getTemplateNames(): string[] {
-     *   return ['bash', 'trash-delete', 'trash-list'];
-     * }
-     * ```
+     * 按时间起点过滤
      */
-    getTemplateNames?(): string[];
+    since(timestamp: number): this;
     /**
-     * 声明渲染模板（推荐方式）
-     * 直接返回模板对象，无需文件路径
-     *
-     * @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>;
+    inTurns(from: number, to?: number): this;
     /**
-     * 声明 Feature 的项目级静态配置契约（Manifest）
-     *
-     * 该契约回答“这个 Feature 平时怎么工作”，
-     * 与 Flow 节点中的 Mode（什么时候、以什么状态工作）是正交的。
+     * content 包含指定文本
      */
-    getFeatureManifest?(): FeatureManifestDefinition | null;
+    containing(text: string): this;
     /**
-     * 声明可调用命令（Capability）
-     *
-     * 命令以 `featureName.commandName` 在注册表内平面寻址，两类消费入口：
-     * - 用户命令菜单：宿主下发清单时按 entryPoints 含 'slash' 过滤
-     * - 其他 Feature：进程内 invokeCapability，entryPoint 为 'feature'；
-     *   宿主前端转发的用户触发同样经注册表，entryPoint 为 'slash'。
-     * entryPoints 是契约约束（不匹配返回 entry_point_denied），不是安全边界。
+     * 最近 N 条
      */
-    getCapabilities?(): CapabilityDefinition[];
+    recent(n: number): this;
     /**
-     * 消费"随消息到达的能力激活通知"（可选）。
-     *
-     * 激活通知（capability refs 数组）作为用户输入的结构化元数据随消息
-     * 本体流动：新 call 开始时（onCall 第三参）与 busy 排队消息的步边界
-     * 注入时（react-loop drain）两个消息落地点，Agent 会按 ref 归属分组
-     * 调用对应 feature 的本方法。refs 是完整引用（`featureName.commandName`），
-     * feature 只需处理自己前缀的条目。
-     *
-     * 这是 prompt 型命令（skill 等）的唯一消费口——不解析输入文本，
-     * 不维护跨消息的 pending 状态。
+     * 执行查询，返回结果数组
      */
-    onCapabilityActivations?(refs: string[], ctx: {
-        context: Context;
-    }): Promise<void>;
+    exec(): EnrichedMessage[];
     /**
-     * 声明上下文注入器
+     * 获取第一条
      */
-    getContextInjectors?(): Map<string | RegExp, ContextInjector>;
-    /**
-     * 初始化钩子
-     */
-    onInitiate?(ctx: FeatureInitContext): Promise<void>;
-    /**
-     * 清理钩子
-     */
-    onDestroy?(ctx: FeatureContext): Promise<void>;
-    /**
-     * LLM 变更时调用（可选）
-     *
-     * Feature 可在此重新绑定对 LLM 的引用、更新阈值等。
-     * 该钩子在 Agent.setLLM() 中被同步调用，且仅在 onCall 间隙执行。
-     */
-    onLLMSwap?(newLLM: LLMClient, oldLLM: LLMClient): void;
-    /**
-     * 捕获可回滚的 Feature 状态
-     *
-     * 仅返回显式声明、可序列化的状态。
-     * 未返回的字段不会参与 rollback。
-     */
-    captureState?(): FeatureStateSnapshot;
+    first(): EnrichedMessage | undefined;
     /**
-     * 从快照恢复 Feature 状态
+     * 获取最后一条
      */
-    restoreState?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    last(): EnrichedMessage | undefined;
     /**
-     * rollback 前钩子
+     * 计数
      */
-    beforeRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    count(): number;
     /**
-     * rollback 后钩子
+     * 时间跨度统计
      */
-    afterRollback?(snapshot: FeatureStateSnapshot): void | Promise<void>;
+    timeSpan(): {
+        start: number;
+        end: number;
+        duration: number;
+    };
     /**
-     * 可选：为调试器提供 hook 的人类可读说明
+     * 按工具分组统计
      */
-    getHookDescription?(lifecycle: string, methodName: string): string | undefined;
+    groupByTool(): Record<string, number>;
 }
-/**
- * 从 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;
-
-/**
- * 生命周期类型定义
- * 定义 Agent 生命周期钩子相关的类型
- */
 
 /**
- * Call（调用）: 用户一次完整的输入-输出交互
- * - 用户输入 → Agent 处理（可能包含多个 ReAct 步骤） → 返回最终输出
- * - 一个 Call 可能包含多个 Step
- *
- * Step（步骤）: ReAct 循环中的单次迭代
- * - 一次 LLM 调用 + 工具执行（如果有）
- * - Step 是 Call 内部的执行单元
- *
- * Turn（轮）: 从无工具调用开始，到下一次无工具调用结束的完整对话周期
- * - 可能包含多个 Step
- * - 用于反向钩子决策点
- */
-/**
- * 核心生命周期枚举
+ * 上下文管理器
+ * 管理消息数组，提供简单的操作方法
  *
- * 三级结构：Agent 级 > Call 级 > Step 级 > Tool 级
- * 每个生命周期都有配套的正向钩子（通知）和反向钩子（决策/处理）
+ * 内核化能力：
+ * - 消息元数据包装（EnrichedMessage）
+ * - 内容解析和索引
+ * - 查询接口
  */
-declare enum CoreLifecycle {
-    /** Agent 初始化 */
-    AgentInitiate = "AgentInitiate",
-    /** Agent 销毁 */
-    AgentDestroy = "AgentDestroy",
-    /** Call 开始 */
-    CallStart = "CallStart",
-    /** Call 结束 */
-    CallFinish = "CallFinish",
-    /** Step 开始 */
-    StepStart = "StepStart",
-    /** Step 结束 */
-    StepFinish = "StepFinish",
-    /** 工具使用前 */
-    ToolUse = "ToolUse",
-    /** 工具使用后 */
-    ToolFinished = "ToolFinished",
-    /** 工具结果变换（结果写入 context 前，可修改结果） */
-    ToolResultTransform = "ToolResultTransform"
-}
+
 /**
- * 决策状态（反向钩子返回值）
- *
- * 用于控制执行流程的三个状态
+ * 工具执行结果（用于 addToolMessage）
  */
-declare enum Decision {
-    /** 批准：确认执行，跳过后续决策 */
-    Approve = "approve",
-    /** 拒绝：阻止执行，跳过后续决策 */
-    Deny = "deny",
-    /** 继续：交给下一个决策节点，使用默认行为 */
-    Continue = "continue"
+interface ToolExecResult {
+    success: boolean;
+    result: string | Record<string, any>;
+    error?: string;
+    /**
+     * 终止标注（ticket 023 / ADR-0005）：工具被超时/用户打断终止但仍在 settle
+     * 窗口内收尾时，结果以 success: true 返回并携带此字段。
+     * reason: 'timeout'（框架统一超时）| 'user'（外部用户中断）。
+     */
+    interrupted?: {
+        reason: ToolTerminationReason;
+    };
+    /** 工具返回的图片（注入到 tool 消息，视觉模式下传给 LLM） */
+    images?: ImageInput[];
+    /** 前端展示数据（不注入 LLM，仅 tool 消息） */
+    display?: unknown;
 }
 /**
- * 决策结果类型
- */
-type DecisionResult = Decision | {
-    /** 决策动作 */
-    action: Decision;
-    /** 拒绝原因（用于日志/调试） */
-    reason?: string;
-    /** 附加元数据 */
-    metadata?: Record<string, any>;
-};
-/**
- * 将 DecisionResult 转换为标准 Decision
- */
-declare function normalizeDecision(result: DecisionResult): Decision;
-/**
- * Agent 初始化上下文
+ * 上下文快照类型 - 用于序列化
  */
-interface AgentInitiateContext {
-    /** 消息上下文 */
-    context: Context;
+interface ContextSnapshot {
+    version: number;
+    messages: Message[];
+    enrichedMessages?: EnrichedMessage[];
+    sequence?: number;
+    generation?: number;
+    /** 截断归档（tombstone）。旧快照可能没有该字段，加载时视为空归档。 */
+    tombstones?: ContextTombstoneEntry[];
 }
 /**
- * Agent 销毁上下文
+ * Context 边界快照 — 用于增量 rollback。
+ *
+ * 记录某个时间点两个数组的长度、sequence 和 generation，
+ * 截断时只需按长度切片即可恢复到该边界。
+ *
+ * generation 用于防止 ABA 问题：如果 Context 经历了
+ * clear/apply/restore 等非追加 mutation，generation 会递增，
+ * 旧 boundary 会被拒绝。
  */
-interface AgentDestroyContext {
-    /** 消息上下文 */
-    context: Context;
+interface ContextBoundaryV2 {
+    messagesLength: number;
+    enrichedMessagesLength: number;
+    sequence: number;
+    generation: number;
 }
 /**
- * Call 开始上下文
+ * Tombstone 摘要 — 轻量元数据，不含消息内容。
  */
-interface CallStartContext {
-    /** 用户输入 */
-    input: string;
-    /** 消息上下文 */
-    context: Context;
-    /** 是否首次调用 */
-    isFirstCall: boolean;
-    /** Agent 实例（用于访问 setUserInput/getUserInput 等 API） */
-    agent?: any;
+interface ContextTombstoneSummary {
+    /** 单调递增的 tombstone ID（同一 Context 实例内唯一） */
+    id: number;
+    /** 截断恢复到的边界 */
+    boundary: ContextBoundaryV2;
+    /** 被截断的消息条数 */
+    removedMessageCount: number;
+    /** 截断发生时间（ISO 字符串） */
+    truncatedAt: string;
 }
 /**
- * 执行单元的终态。它只表达执行是否完成、失败、取消或移交给后续单元；
- * 不复用模型厂商的 stop reason，也不推断宿主任务的业务状态。
- */
-type ExecutionStatus = 'completed' | 'failed' | 'cancelled' | 'continued';
-/**
- * 执行终止的框架级原因。
+ * Tombstone 完整条目 — 含被截断的消息内容。
  *
- * `reason` 描述生命周期语义，错误来源由 `error.category` 表达，避免一个字段
- * 同时承担供应商协议、框架控制流和宿主业务状态三种含义。
- */
-type ExecutionReason = 'completed' | 'cancelled' | 'limit_reached' | 'continued' | 'error';
-/** 可序列化的错误事实。category 是稳定的机器分类，message 只供展示。 */
-interface ExecutionError {
-    category: string;
-    message: string;
-    code?: string;
-    statusCode?: number;
-    retryable?: boolean;
-}
-/** 单次模型请求的来源信息；不决定 Call 的终态。 */
-interface ModelRequestOutcome {
-    providerStopReason?: string | null;
-}
-/**
- * 一次 Agent Call（而非宿主任务）的结构化终态。
- * 该对象可安全持久化、跨进程传输和用于 JSONL/CLI 消费。
+ * rollback 截断不再物理丢失内容：被截尾部进入 tombstone 归档，
+ * 可查询（listTombstones / getTombstone），在 Context 仍处于该边界时
+ * 可完整恢复（restoreTombstone）。
  */
-interface CallOutcome {
-    status: ExecutionStatus;
-    reason: ExecutionReason;
-    response: string;
-    steps: number;
-    startedAt: number;
-    finishedAt: number;
-    error?: ExecutionError;
-    model?: ModelRequestOutcome;
+interface ContextTombstoneEntry extends ContextTombstoneSummary {
+    removedMessages: Message[];
+    removedEnrichedMessages: EnrichedMessage[];
 }
-/** @deprecated 使用 CallOutcome.reason。保留旧 hook/API 的类型兼容。 */
-type CallFinishReason = ExecutionReason;
-/**
- * Call 结束上下文
- */
-interface CallFinishContext {
-    /** 用户输入 */
-    input: string;
-    /** 消息上下文 */
-    context: Context;
-    /** 最终响应 */
-    response: string;
-    /** 执行的步骤数 */
-    steps: number;
-    /** 是否成功完成 */
-    completed: boolean;
-    /** 结束原因 */
-    finishReason: CallFinishReason;
-    /** 完整的结构化终态 */
-    outcome: CallOutcome;
+declare class Context {
+    private messages;
+    private enrichedMessages;
+    private indexes;
+    private sequence;
+    /**
+     * Lineage generation，用于检测非追加 mutation。
+     *
+     * - 纯追加 typed message（addUserMessage 等）：不变
+     * - rollback 的合法截断（truncateToBoundary）：不变
+     * - clear / apply：递增
+     * - restore：使用 snapshot 携带的 generation，否则递增
+     */
+    private generation;
+    /**
+     * 截断归档（tombstone）。append-only：clear/apply/restore 不清空，
+     * 只有 restore(snapshot) 采用快照携带的归档。
+     */
+    private tombstones;
+    private tombstoneSeq;
+    /**
+     * 添加一条消息
+     */
+    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, images?: ImageInput[]): void;
+    /**
+     * 添加助手响应
+     *
+     * 框架合成消息（错误/截断说明）可通过 execution 字段附带执行终态元数据。
+     */
+    addAssistantMessage(response: LLMResponse & {
+        execution?: MessageExecutionMeta;
+    }, turn: number): void;
+    /**
+     * 添加工具结果
+     */
+    addToolMessage(call: ToolCall, result: ToolExecResult, turn: number): void;
+    /**
+     * 添加已经序列化的工具消息。
+     *
+     * 用于 session/handoff 恢复等边界：原始 tool content 已经是 provider 可重放的
+     * 序列化字符串，不应先解析成 ToolExecResult 再重新编码。该入口同时维护
+     * messages[] 与 enrichedMessages[]，并保留工具返回的图片附件。
+     */
+    addSerializedToolMessage(toolCallId: string, content: string, turn: number, images?: ImageInput[], display?: unknown): void;
+    /**
+     * 添加系统消息
+     */
+    addSystemMessage(content: string, turn: number, source?: string, tag?: 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;
+    /**
+     * 捕获当前 Context 的前缀边界。
+     *
+     * 返回一个轻量快照，记录两个数组的长度、sequence 和 generation。
+     * 后续可传给 truncateToBoundary() 恢复到此边界。
+     *
+     * generation 不变：纯读取操作。
+     */
+    captureBoundary(): ContextBoundaryV2;
+    /**
+     * 校验 boundary 是否与当前 Context 兼容。
+     *
+     * @throws 如果 generation 不匹配、长度非法或超出当前数组。
+     */
+    private assertBoundaryCompatible;
+    /**
+     * 将两个数组截断到指定边界。
+     *
+     * 这是合法的 rollback 操作：generation 保持不变，
+     * 截断后同一 lineage 的旧 boundary 仍然可以继续使用。
+     *
+     * 被截尾部进入 tombstone 归档（不物理丢失）：
+     * 通过 listTombstones() / getTombstone() 查询，
+     * Context 仍处于该边界时可通过 restoreTombstone() 完整恢复。
+     *
+     * @throws 如果 boundary 与当前 Context 不兼容（generation 不匹配或长度越界）。
+     */
+    truncateToBoundary(boundary: ContextBoundaryV2): void;
+    /**
+     * 列出 tombstone 摘要（不含消息内容）。
+     */
+    listTombstones(): ContextTombstoneSummary[];
+    /**
+     * 按 ID 取回 tombstone 完整内容（深拷贝，修改返回值不影响归档）。
+     */
+    getTombstone(id: number): ContextTombstoneEntry | undefined;
+    /**
+     * 从 tombstone 恢复被截尾部。
+     *
+     * 仅当 Context 仍精确处于该 tombstone 的边界时允许
+     * （generation、两个数组长度、sequence 全部匹配）——此时恢复是
+     * 截断的精确逆操作，不破坏 lineage。
+     *
+     * 恢复后 sequence 续接被截尾部的最大序号，generation 不变。
+     *
+     * @throws 如果 Context 已离开该边界（例如截断后追加了新消息）。
+     *         此时内容仍可通过 getTombstone() 提取，由调用方决定如何重组。
+     */
+    restoreTombstone(id: number): void;
 }
+
 /**
- * Step 开始上下文
+ * Capability System - 统一能力控制面（P1：command）
  *
- * Step 是 ReAct 循环中的单次迭代
+ * Feature 通过 getCapabilities() 声明可被显式调用的命令，注册表提供
+ * 平面寻址（`featureName.commandName`）与三动词中的 invoke 语义。
+ *
+ * 设计裁决（详见 AgentDevClaw docs/adr capability-registry-as-control-plane）：
+ * - 命令式优先：只有 invoke / query / emit，不存在 bind / reactive / watch。
+ *   共享权威状态与跨 feature 事务是负面清单，不做。
+ * - entryPoints 是契约约束而非安全边界：声明不含请求入口的 command 被
+ *   invoke 时返回 entry_point_denied（结构化错误，非静默失败）。绕过
+ *   路径（getFeature 直引）依旧存在，这是已知边界而非漏洞。
+ * - 进程内语义：args 是普通 JS 值，不为序列化设计。跨进程投递是宿主层
+ *   职责，注册表不为其建模。
+ * - 注册表是哑的：不做参数校验（schema 服务于消费端渲染表单）、不含
+ *   派发策略、不管依赖管理。
+ * - 命令超时即失败：超时返回 timeout，但执行体可能仍在进行（Promise
+ *   无法取消），不保证中断，只保证调用方不挂死。
  */
-interface StepStartContext {
-    /** 当前步骤序号（从 0 开始） */
-    step: number;
-    /** 当前调用序号（用户交互次数，从 0 开始） */
-    callIndex: number;
-    /** 消息上下文 */
-    context: Context;
-    /** 原始用户输入 */
-    input: string;
-    /** Agent 实例（用于访问当前会话中的 Feature、工具和输入状态） */
-    agent?: any;
-}
+
 /**
- * Step 结束上下文
+ * 能力入口类型
+ *
+ * - 'slash'：出现在用户命令菜单（宿主下发清单时过滤）
+ * - 'feature'：可被其他 feature（或经宿主转发的等价调用）invoke
  */
-interface StepFinishedContext extends StepStartContext {
-    /** LLM 响应 */
-    llmResponse: LLMResponse;
-    /** 执行的工具调用数量 */
-    toolCallsCount: number;
-}
+type CapabilityEntryPoint = 'slash' | 'feature';
 /**
- * 工具上下文 - onToolUse 钩子的参数
+ * 命令类型。框架层仅定义形状并透传——两种 kind 在框架眼里同质
+ * （收到 invoke 一律执行 execute）；行为差异（表单/pill/toast/触发
+ * 时机）由应用层（宿主前端）按 kind 消费。
  *
- * 提供工具调用时的完整上下文信息
+ * - invoke（缺省）：选中即执行的触发型命令（配置开关等）
+ * - prompt：调用指令以文本形式嵌入输入的命令（skill 等），
+ *   应用层负责其呈现与发送时机，feature 在自身生命周期内消费
  */
-interface ToolContext {
-    /** 工具调用 */
-    call: ToolCall;
-    /** 工具定义 */
-    tool: Tool;
-    /** 当前步骤序号 */
-    step: number;
-    /** 用户输入 */
-    input: string;
-    /** 消息上下文（可读写） */
-    context: Context;
-    /** 获取其他 Feature */
-    getFeature<T extends AgentFeature>(name: string): T | undefined;
+type CapabilityKind = 'invoke' | 'prompt';
+/**
+ * Feature 声明的可调用命令
+ */
+interface CapabilityDefinition {
+    /** 命令名（标识符），注册表内以 `featureName.commandName` 寻址 */
+    name: string;
+    /** 命令类型，缺省 'invoke'。框架透传不解释，语义由应用层消费 */
+    kind?: CapabilityKind;
+    /** 菜单显示标题，缺省用 name */
+    title?: string;
+    /** 菜单描述 */
+    description?: string;
+    /**
+     * 参数 schema，复用 FeatureManifestSettingProperty 词汇表，
+     * 与 feature-setup 配置表单、flow 交互选项共用一套渲染基底。
+     */
+    parameters?: Record<string, FeatureManifestSettingProperty>;
+    /**
+     * 可见入口，缺省 ['feature']（最小暴露）。
+     * 进 slash 菜单必须是显式主动行为。
+     */
+    entryPoints?: CapabilityEntryPoint[];
+    /**
+     * 参数当前生效值（配置回显）：参数表单打开时优先于 parameters 的
+     * default 显示。返回普通对象，键与 parameters 对齐；缺省或抛错
+     * 时表单回退 default。读取必须无副作用。
+     */
+    readCurrentValues?: () => Record<string, unknown>;
+    /** 执行体。抛出的任何错误归一为 execute_failed */
+    execute(args: Record<string, unknown>, ctx: CapabilityContext): Promise<unknown>;
 }
 /**
- * 工具结果 - onToolFinished 钩子的参数
- *
- * 提供工具执行后的完整结果信息
+ * 命令执行上下文（进程内）
  */
-interface ToolResult {
-    /** 是否成功 */
-    success: boolean;
-    /** 经过 ToolResultTransform 后、实际写入模型上下文的最终结果。 */
-    delivered?: ToolExecResult;
-    /** 返回数据 */
-    data: unknown;
-    /** 错误信息（如果失败） */
-    error?: string;
-    /** 执行耗时(ms) */
-    duration: number;
-    /** 工具调用 */
-    call: ToolCall;
-    /** 工具定义 */
-    tool: Tool;
-    /** 当前步骤序号 */
-    step: number;
-    /** 用户输入 */
-    input: string;
-    /** 消息上下文 */
-    context: Context;
-    /** 获取其他 Feature */
+interface CapabilityContext {
+    agentId: string;
     getFeature<T extends AgentFeature>(name: string): T | undefined;
+    logger: Logger;
 }
 /**
- * 钩子返回值类型（扩展版）
- *
- * 统一的生命周期钩子控制流指令
- *
- * - { action: 'block' }: 阻止工具执行（工具级）
- * - { action: 'allow' }: 允许工具执行（工具级）
- * - undefined: 默认行为
+ * invoke 的结构化结果。错误码是稳定契约：
+ * - not_found：ref 未注册
+ * - entry_point_denied：该入口不在 entryPoints 中
+ * - execute_failed：执行体抛错
+ * - timeout：超过时限（执行体不保证被取消）
  */
-type HookResult = {
-    action: 'block';
-    reason?: string;
+type CapabilityInvokeResult = {
+    ok: true;
+    result: unknown;
 } | {
-    action: 'allow';
-} | undefined;
+    ok: false;
+    code: 'not_found' | 'entry_point_denied' | 'execute_failed' | 'timeout';
+    message: string;
+};
 /**
- * 子代理状态
+ * 清单快照条目（下发宿主 / 前端菜单消费的数据形态，纯数据）
  */
-type SubAgentStatus = 'idle' | 'busy' | 'completed' | 'failed' | 'terminated';
+interface CapabilitySnapshot {
+    feature: string;
+    name: string;
+    ref: string;
+    /** 命令类型（缺省 'invoke'），透传给应用层消费 */
+    kind: CapabilityKind;
+    title: string;
+    description?: string;
+    parameters?: Record<string, FeatureManifestSettingProperty>;
+    entryPoints: CapabilityEntryPoint[];
+    /** 参数当前生效值（readCurrentValues 收集；读取失败时缺省） */
+    currentValues?: Record<string, unknown>;
+}
 /**
- * 子代理创建上下文
+ * 能力注册表（per-Agent 实例）
  */
-interface SubAgentSpawnContext {
-    /** 子代理 ID */
-    agentId: string;
-    /** 子代理类型 */
-    type: string;
-    /** 初始指令 */
-    instruction: string;
-    /** 子代理实例 */
-    agent: AgentBase;
+declare class CapabilityRegistry {
+    private defs;
+    /**
+     * 注册 feature 的命令。ref（`feature.name`）重复视为装配错误，直接抛出，
+     * 对齐 feature-graph 的报错哲学。
+     */
+    register(featureName: string, def: CapabilityDefinition): void;
+    has(ref: string): boolean;
+    /** ref → 所属 feature 名（dispatchTurnActivations 按 owner 分组派发用） */
+    ownerOf(ref: string): string | null;
+    /** ref → 命令类型（缺省 'invoke'）；未注册返回 null */
+    kindOf(ref: string): CapabilityKind | null;
+    /**
+     * 移除指定 feature 的全部命令（幂等）。
+     * initSingleFeature 重挂路径先调它，避免热载时误报 duplicate ref。
+     */
+    unregisterFeature(featureName: string): void;
+    /**
+     * 清单快照。传入 entryPoint 时过滤出该入口可见的命令
+     * （宿主下发 slash 菜单清单时用 { entryPoint: 'slash' }）。
+     */
+    list(filter?: {
+        entryPoint?: CapabilityEntryPoint;
+    }): CapabilitySnapshot[];
+    /**
+     * 调用命令。entryPoint 必填——调用方声明自己以哪个入口进来，
+     * 注册表据此执行 entryPoints 契约检查。
+     */
+    invoke(ref: string, opts: {
+        args?: Record<string, unknown>;
+        entryPoint: CapabilityEntryPoint;
+        timeoutMs?: number;
+    }, ctx: CapabilityContext): Promise<CapabilityInvokeResult>;
 }
+
 /**
- * 子代理状态更新上下文
+ * Feature System - 可外挂功能模块接口
+ *
+ * Feature 系统允许将功能（MCP、Skills、子代理等）从 Agent 核心中解耦，
+ * 实现新功能的声明式注册和统一的生命周期管理。
  */
-interface SubAgentUpdateContext {
-    /** 子代理 ID */
-    agentId: string;
-    /** 子代理类型 */
-    type: string;
-    /** 旧状态 */
-    oldStatus: SubAgentStatus;
-    /** 新状态 */
-    newStatus: SubAgentStatus;
-    /** 执行结果（完成时） */
-    result?: string;
-    /** 错误信息（失败时） */
-    error?: string;
-}
+
 /**
- * 子代理销毁上下文
+ * Feature 上下文值类型
  */
-interface SubAgentDestroyContext {
-    /** 子代理 ID */
-    agentId: string;
-    /** 子代理类型 */
-    type: string;
-    /** 销毁原因 */
-    reason: 'manual' | 'parent_dispose' | 'error';
-}
+type ToolContextValue = Record<string, unknown>;
 /**
- * Agent 中断上下文
+ * Feature 上下文注入器
+ * 返回要注入到 tool.execute() 的额外参数
  */
-interface AgentInterruptContext {
-    /** 中断原因 */
-    reason: 'limit_reached' | 'error' | 'cancelled';
-    /** 当前步骤序号 */
-    step: number;
-    /** 当前消息上下文 */
-    context: Context;
-}
+type ContextInjector = (call: ToolCall) => ToolContextValue;
 /**
- * 子代理中断上下文
+ * Feature 初始化上下文
  */
-interface SubAgentInterruptContext {
-    /** 子代理 ID */
+interface FeatureInitContext {
+    /** Agent ID */
     agentId: string;
-    /** 子代理类型 */
-    type: string;
-    /** 中断原因 */
-    reason: 'limit_reached' | 'error' | 'cancelled';
-    /** 中断时的结果 */
-    result: string;
+    /** Agent 配置 */
+    config: AgentConfig;
+    /** Feature 级结构化日志 */
+    logger: Logger;
+    /** Feature 特定配置 */
+    featureConfig?: unknown;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
+    /** 注册工具 */
+    registerTool(tool: Tool): void;
+    /** Agent 级数据源注册表（per-Agent 实例，非进程全局） */
+    dataSourceRegistry: DataSourceRegistry;
 }
 /**
- * Step 结束决策上下文（反向钩子）
- *
- * 用于在 Step 结束后进行流程控制决策
+ * Feature 运行时上下文
  */
-interface StepFinishDecisionContext extends StepFinishedContext {
-    /** 是否有活跃的子代理（busy 状态） */
-    hasActiveSubAgents?: boolean;
-    /** 是否有待处理的子代理消息 */
-    hasPendingMessages?: boolean;
-    /** 是否调用了 wait 工具 */
-    waitCalled?: boolean;
+interface FeatureContext {
+    agentId: string;
+    config: AgentConfig;
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
 }
 /**
- * 工具完成决策上下文（反向钩子）
+ * Feature 快照状态
  *
- * 用于在工具执行完成后进行流程控制决策
+ * 第一阶段只支持显式白名单状态：
+ * - Feature 自己决定要保存什么
+ * - 未声明的状态一律不保证恢复
  */
-interface ToolFinishedDecisionContext extends ToolResult {
-    /** 刚才执行的工具名称 */
-    toolName: string;
+type FeatureStateSnapshot = unknown;
+/**
+ * 包信息
+ */
+interface PackageInfo {
+    /** 包名，如 '@agentdevjs/shell-feature' 或 'agentdev' */
+    name: string;
+    /** 版本号（可选） */
+    version?: string;
+    /** 包根目录绝对路径 */
+    root: string;
 }
 /**
- * 工具结果变换上下文（反向钩子）
+ * Feature Manifest 配置项
  *
- * 在工具执行完成、结果写入 context 之前，允许 Feature 对结果进行变换。
- * 典型用途：输出截断（OutputGuard）、脱敏、格式清理等。
- *
- * 钩子返回 undefined 表示不修改；返回 ToolExecResult 表示用新结果替换。
- * 多个钩子按注册顺序链式执行，前一个钩子的输出作为后一个钩子的输入。
- */
-interface ToolResultTransformContext {
-    /** 工具名称 */
-    toolName: string;
-    /** 工具调用 */
-    call: ToolCall;
-    /** 当前结果（可能已被前一个变换钩子修改） */
-    result: ToolExecResult;
-    /** 当前步骤序号 */
-    step: number;
-}
-
-/**
- * Continuation Request 类型定义
- *
- * 控制工具（如 checkpoint、rollback）通过 registerContinuationRequest()
- * 登记一个 continuation request，使当前 onCall 在合法边界停止。
- * 宿主（如 CallArbiter）通过 consumeContinuationRequest() 消费该请求，
- * 决定是否在同一个逻辑 envelope 内启动下一个 onCall segment。
- */
-/**
- * Checkpoint continuation request
- *
- * Agent 建立了一个命名检查点，希望继续执行。
- * 宿主应捕获当前 runtime snapshot 并将其与 checkpointId 关联，
- * 然后启动 continuation segment。
+ * 用于声明 Feature 在 Agent Project 级别可配置的静态参数。
+ * Claw 等消费端可根据该契约自动渲染表单。
  */
-interface CheckpointContinuationRequest {
-    kind: 'checkpoint';
-    checkpointId: string;
-    /** 可选附加元数据（如 Agent 的自由备注） */
-    metadata?: Record<string, unknown>;
+interface FeatureManifestSettingProperty {
+    type: 'string' | 'number' | 'boolean' | 'select' | 'file' | 'directory' | 'group';
+    title: string;
+    description?: string;
+    default?: unknown;
+    options?: Array<{
+        label: string;
+        value: string | number | boolean;
+    }>;
+    placeholder?: string;
+    /** number 类型下的最小值 */
+    min?: number;
+    /** number 类型下的最大值 */
+    max?: number;
+    /** number 类型下的步进值 */
+    step?: number;
+    /** file 类型下的可接受文件类型，如 '.mp3,.wav' 或 'audio/*' */
+    accept?: string | string[];
+    /** directory 类型下的最大条目数 */
+    maxItems?: number;
+    /** type: 'group' 时的嵌套子属性 */
+    properties?: Record<string, FeatureManifestSettingProperty>;
+    /** 条件可见性：仅当同级指定属性值在 values 中时渲染此字段 */
+    showWhen?: {
+        property: string;
+        values: (string | number | boolean)[];
+    };
+    /**
+     * select 类型下的动态选项来源：options 由宿主在渲染时提供（活数据，
+     * 无法静态枚举），options 字段省略。当前定义 'model-presets' =
+     * 宿主模型 preset 清单。静态 options 存在时本字段被忽略。
+     */
+    dynamicOptions?: 'model-presets';
 }
-/**
- * Rollback continuation request
- *
- * Agent 希望回退到指定 checkpoint，并携带一个失败分支的摘要。
- * 宿主应恢复到 checkpoint 的 runtime snapshot，
- * 然后以摘要作为 continuation segment 的输入启动新的 onCall。
- */
-interface RollbackContinuationRequest {
-    kind: 'rollback';
-    checkpointId: string;
-    /** Agent 生成的失败分支摘要 */
-    summary: string;
+interface FeatureManifestDefinition {
+    schemaVersion: 1;
+    settings?: {
+        properties: Record<string, FeatureManifestSettingProperty>;
+        /** 有序分区，用于 UI 分组渲染。省略则平铺全部属性 */
+        sections?: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            /** 分区内属性 key 的显示顺序 */
+            properties: string[];
+        }>;
+    };
 }
 /**
- * 受类型约束的 continuation request
- */
-type CallContinuationRequest = CheckpointContinuationRequest | RollbackContinuationRequest;
-
-/**
- * UsageStats - 用量统计系统
- *
- * 职责：
- * - 记录 LLM 调用的 token 用量
- * - 聚合 session/call/step 三级统计
- * - 提供快照序列化和恢复
- * - 格式化用量报告
+ * Agent Feature 接口
  *
- * 设计原则：
- * - 框架内置，不是 Feature
- * - 自动收集，不需要手动干预
- * - 快照包含 session 级数据，用于会话恢复
- */
-/**
- * 统一用量格式（兼容 Anthropic 和 OpenAI）
- */
-interface UsageInfo {
-    /** 输入 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;
-    stepCount: number;
-    cacheHitRequests: number;
-    startTime: number;
-    endTime?: number;
-}
-/**
- * Session 用量快照（用于序列化）
- */
-interface UsageStatsSnapshot {
-    /** Session 级累计用量 */
-    totalUsage: UsageInfo;
-    /** 各 Call 的用量汇总 */
-    calls: CallUsageSummary[];
-    /** 总请求数（LLM 调用次数） */
-    totalRequests: number;
-    /** 命中缓存的请求数（request-level） */
-    totalCacheHitRequests: number;
-    /** 最后一次请求的用量（用于显示当前上下文占用） */
-    lastRequestUsage?: UsageInfo;
-}
-/**
- * 用量统计类
+ * 可外挂的功能模块，提供工具和上下文注入
  */
-declare class UsageStats {
-    /** Session 级累计用量 */
-    private totalUsage;
-    /** 当前活跃 Call 的用量记录 */
-    private currentCallUsage;
-    /** 总 LLM 调用次数 */
-    private totalRequests;
-    /** 命中缓存的总请求数 */
-    private totalCacheHitRequests;
-    /** 当前 Call 的 Step 记录（临时，用于聚合） */
-    private currentStepRecords;
-    /** 最后一次 LLM 调用的用量（用于显示当前上下文占用） */
-    private lastRequestUsage;
-    /**
-     * 记录一次 LLM 调用的用量
-     * @param callIndex Call 序号
-     * @param step Step 序号
-     * @param usage 用量数据
-     */
-    record(callIndex: number, step: number, usage: UsageInfo): void;
+interface AgentFeature {
+    /** Feature 名称 */
+    readonly name: string;
     /**
-     * 标记 Call 结束
-     * @param callIndex Call 序号
+     * 依赖的其他 Feature（装配时拓扑排序，工作项 A3）。
+     *
+     * 声明位置在类的静态属性上（实例字段无法装配时静态读取）：
+     * ```typescript
+     * class MyFeature implements AgentFeature {
+     *   name = 'my-feature';
+     *   static inject = ['storage'];
+     * }
+     * ```
+     * 读取与校验见 feature-graph.ts（readInjectDeclarations / resolveFeatureOrder）。
      */
-    endCall(callIndex: number): void;
     /**
-     * 获取 Session 级累计用量
+     * Feature 源文件路径（import.meta.url）。
+     *
+     * 既是调试器展示的源码位置，也是框架自动发现 Feature 自带资源的唯一锚点。
+     *
+     * 约定：Feature 的所有静态资源放在 source 文件的同级目录下。
+     * 框架会自动扫描 `dirname(source)/skills/` 发现内置 skill 并注入系统提示词。
+     * 其他资源（图片、模板等）由 Feature 代码通过 import.meta.url 自行解析。
+     *
+     * 标准写法（由 create-feature 脚手架自动生成）：
+     * ```typescript
+     * readonly source = fileURLToPath(import.meta.url).replace(/\\/g, '/');
+     * ```
      */
-    getTotalUsage(): UsageInfo;
+    readonly source?: string;
+    /** 可选：用于调试器展示的 Feature 描述 */
+    readonly description?: string;
     /**
-     * 获取指定 Call 的用量汇总
-     * @param callIndex Call 序号
+     * 获取同步工具（已知工具列表）
      */
-    getCallUsage(callIndex: number): CallUsageSummary | undefined;
+    getTools?(): Tool[];
     /**
-     * 获取所有 Call 的用量汇总
+     * 获取异步工具（需要连接、发现等）
      */
-    getAllCallUsage(): CallUsageSummary[];
+    getAsyncTools?(ctx: FeatureInitContext): Promise<Tool[]>;
     /**
-     * 获取总请求次数
+     * 获取包信息
+     *
+     * 返回 Feature 所在的包信息（包名、版本、根目录）
+     * 用于统一模板路径解析和包管理
+     *
+     * @returns 包信息，如果 Feature 不属于任何包则返回 null
+     *
+     * @example
+     * ```typescript
+     * getPackageInfo(): PackageInfo | null {
+     *   return {
+     *     name: '@agentdevjs/shell-feature',
+     *     version: '1.0.0',
+     *     root: '/path/to/package/root'
+     *   };
+     * }
+     * ```
      */
-    getTotalRequests(): number;
-    getTotalCacheHitRequests(): number;
+    getPackageInfo?(): PackageInfo | null;
     /**
-     * 获取最后一次请求的用量（用于显示当前上下文占用）
+     * 获取模板名称列表
+     *
+     * 返回 Feature 提供的模板名称列表（不含扩展名）
+     * 模板文件必须位于 {packageRoot}/dist/templates/{templateName}.render.js
+     *
+     * @returns 模板名称数组
+     *
+     * @example
+     * ```typescript
+     * getTemplateNames(): string[] {
+     *   return ['bash', 'trash-delete', 'trash-list'];
+     * }
+     * ```
      */
-    getLastRequestUsage(): UsageInfo | null;
+    getTemplateNames?(): string[];
     /**
-     * 获取格式化的用量报告
-     */
-    getReport(): 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>;
     /**
-     * 创建快照（用于序列化）
+     * 声明 Feature 的项目级静态配置契约（Manifest）
+     *
+     * 该契约回答“这个 Feature 平时怎么工作”，
+     * 与 Flow 节点中的 Mode（什么时候、以什么状态工作）是正交的。
      */
-    toSnapshot(): UsageStatsSnapshot;
+    getFeatureManifest?(): FeatureManifestDefinition | null;
     /**
-     * 从快照恢复
+     * 声明可调用命令（Capability）
+     *
+     * 命令以 `featureName.commandName` 在注册表内平面寻址，两类消费入口：
+     * - 用户命令菜单：宿主下发清单时按 entryPoints 含 'slash' 过滤
+     * - 其他 Feature：进程内 invokeCapability，entryPoint 为 'feature'；
+     *   宿主前端转发的用户触发同样经注册表，entryPoint 为 'slash'。
+     * entryPoints 是契约约束（不匹配返回 entry_point_denied），不是安全边界。
      */
-    fromSnapshot(snapshot: UsageStatsSnapshot): void;
+    getCapabilities?(): CapabilityDefinition[];
     /**
-     * 重置统计（谨慎使用）
+     * 消费"随消息到达的能力激活通知"（可选）。
+     *
+     * 激活通知（capability refs 数组）作为用户输入的结构化元数据随消息
+     * 本体流动：新 call 开始时（onCall 第三参）与 busy 排队消息的步边界
+     * 注入时（react-loop drain）两个消息落地点，Agent 会按 ref 归属分组
+     * 调用对应 feature 的本方法。refs 是完整引用（`featureName.commandName`），
+     * feature 只需处理自己前缀的条目。
+     *
+     * 这是 prompt 型命令（skill 等）的唯一消费口——不解析输入文本，
+     * 不维护跨消息的 pending 状态。
      */
-    reset(): void;
+    onCapabilityActivations?(refs: string[], ctx: {
+        context: Context;
+    }): Promise<void>;
+    /**
+     * 声明上下文注入器
+     */
+    getContextInjectors?(): Map<string | RegExp, ContextInjector>;
+    /**
+     * 初始化钩子
+     */
+    onInitiate?(ctx: FeatureInitContext): Promise<void>;
+    /**
+     * 清理钩子
+     */
+    onDestroy?(ctx: FeatureContext): Promise<void>;
+    /**
+     * LLM 变更时调用（可选）
+     *
+     * Feature 可在此重新绑定对 LLM 的引用、更新阈值等。
+     * 该钩子在 Agent.setLLM() 中被同步调用，且仅在 onCall 间隙执行。
+     */
+    onLLMSwap?(newLLM: LLMClient, oldLLM: LLMClient): 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;
 }
-
-/**
- * 通知分类
- * - state: 覆盖式更新（如 LLM 字符计数）
- * - event: 追加式记录（如工具开始/完成）
- */
-type NotificationCategory = 'state' | 'event';
 /**
- * LLM 生成阶段
+ * 从 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
  */
-type LLMPhase = 'thinking' | 'content' | 'tool_calling';
+declare function getPackageInfoFromSource(source: string | undefined): PackageInfo | null;
+
 /**
- * 通知基础接口
+ * 生命周期类型定义
+ * 定义 Agent 生命周期钩子相关的类型
  */
-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' | 'observe' | 'guard' | 'transform';
-    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 RuntimeStage = 'idle' | 'llm_thinking' | 'llm_content' | 'llm_tool_call_building' | 'awaiting_runtime' | 'tool_executing' | 'retry_waiting' | 'retry_requesting' | 'completed' | 'failed' | 'cancelled';
+
 /**
- * 工具终止原因（ticket 023 / ADR-0005）
+ * Call（调用）: 用户一次完整的输入-输出交互
+ * - 用户输入 → Agent 处理（可能包含多个 ReAct 步骤） → 返回最终输出
+ * - 一个 Call 可能包含多个 Step
  *
- * - 'timeout'：框架统一超时计时触发（Tool 声明 timeout 后生效）
- * - 'user'：外部用户中断（Agent.interrupt() 触发的 abort signal）
+ * Step（步骤）: ReAct 循环中的单次迭代
+ * - 一次 LLM 调用 + 工具执行（如果有）
+ * - Step 是 Call 内部的执行单元
+ *
+ * Turn（轮）: 从无工具调用开始，到下一次无工具调用结束的完整对话周期
+ * - 可能包含多个 Step
+ * - 用于反向钩子决策点
  */
-type ToolTerminationReason = 'timeout' | 'user';
-interface AgentRuntimeStateSnapshot {
-    stage: RuntimeStage;
-    callActive: boolean;
-    charCount: number;
-    thinkingChars: number;
-    contentChars: number;
-    toolCallCount: number;
-    activeToolNames: string[];
-    activeToolCount: number;
-    /** LLM 流式期间检测到的工具名称（仅 llm_tool_call_building 阶段有值） */
-    streamToolNames?: string[];
-    callStartedAt?: number;
-    stageStartedAt?: number;
-    retryAttempt?: number;
-    maxRetries?: number;
-    nextRetryDelayMs?: number;
-    lastErrorType?: string | null;
-    lastErrorMessage?: string | null;
-    /** 最近一次已结束 Call 的结构化终态。 */
-    lastOutcome?: CallOutcome | null;
-    updatedAt: number;
-}
 /**
- * 工具执行上下文
+ * 核心生命周期枚举
  *
- * 由框架在执行工具时注入。Feature 通过 {@link AgentFeature.getContextInjectors}
- * 可以扩展额外字段。
+ * 三级结构：Agent 级 > Call 级 > Step 级 > Tool 级
+ * 每个生命周期都有配套的正向钩子（通知）和反向钩子（决策/处理）
  */
-interface ToolExecutionContext {
-    /** 中断信号，用于取消工具执行（外部用户中断与框架超时合并后的 signal） */
-    signal?: AbortSignal;
-    /** 当前工具调用的 LLM 生成 call.id（tool.progress 等进度信号配对用） */
-    callId?: string;
-    /**
-     * 查询当前工具执行是否已被终止及终止原因（ticket 023）。
-     *
-     * 返回 null 表示尚未终止；工具可据此在结果中填写模型可读的终止元数据。
-     * reason 不挂在 AbortSignal 上（signal 保持标准形状），统一经此函数查询。
-     */
-    termination?: () => ToolTerminationReason | null;
-    /** 当前终止 settle 的绝对截止时间（epoch ms）；工具用于把内部 drain 纳入同一预算。 */
-    terminationDeadline?: () => number | null;
-    /** 本次调用生效的超时（毫秒，含 args 覆盖后的 clamp 结果）；仅声明 timeout 的工具注入（ticket 025 进度显示用） */
-    timeoutMs?: number;
-    /** 注册 continuation request（供 checkpoint/rollback 等控制流工具使用） */
-    registerContinuationRequest?: (request: CallContinuationRequest) => void;
-    /** Feature 通过 contextInjectors 注入的自定义属性 */
-    [key: string]: unknown;
+declare enum CoreLifecycle {
+    /** Agent 初始化 */
+    AgentInitiate = "AgentInitiate",
+    /** Agent 销毁 */
+    AgentDestroy = "AgentDestroy",
+    /** Call 开始 */
+    CallStart = "CallStart",
+    /** Call 结束 */
+    CallFinish = "CallFinish",
+    /** Step 开始 */
+    StepStart = "StepStart",
+    /** Step 结束 */
+    StepFinish = "StepFinish",
+    /** 工具使用前 */
+    ToolUse = "ToolUse",
+    /** 工具使用后 */
+    ToolFinished = "ToolFinished",
+    /** 工具结果变换（结果写入 context 前，可修改结果） */
+    ToolResultTransform = "ToolResultTransform"
 }
 /**
- * 工具执行返回值类型
+ * 决策状态（反向钩子返回值）
  *
- * 工具可以返回纯文本或结构化对象。框架会自动序列化非 string 返回值。
+ * 用于控制执行流程的三个状态
  */
-type ToolResultValue = string | Record<string, unknown>;
+declare enum Decision {
+    /** 批准：确认执行，跳过后续决策 */
+    Approve = "approve",
+    /** 拒绝：阻止执行，跳过后续决策 */
+    Deny = "deny",
+    /** 继续：交给下一个决策节点，使用默认行为 */
+    Continue = "continue"
+}
 /**
- * 工具定义
+ * 决策结果类型
  */
-interface Tool {
-    name: string;
-    description: string;
-    parameters?: Record<string, unknown>;
-    /**
-     * 执行工具
-     *
-     * @param args 工具参数（来自 LLM 的 JSON 解析结果）
-     * @param context 执行上下文，包含框架注入的 signal、registerContinuationRequest，
-     *   以及各 Feature 通过 contextInjectors 注入的自定义属性
-     */
-    execute: (args: Record<string, unknown>, context?: ToolExecutionContext) => Promise<ToolResultValue>;
-    /** 可选：渲染配置 */
-    render?: ToolRenderConfig;
-    /**
-     * 工具执行模式
-     * - 'normal'（默认）：普通工具，可与其他工具在同一次 assistant turn 中并行调用
-     * - 'exclusive'：独占工具，必须是 assistant turn 中唯一的工具调用
-     *
-     * exclusive 工具适用于控制流工具（如 checkpoint、rollback），
-     * 它们不应与其他工具产生副作用交织。
-     */
-    executionMode?: 'normal' | 'exclusive';
-    /**
-     * 工具是否可并行执行。
-     *
-     * - true: 该工具可以与同批次中其他 parallelizable 工具并发执行
-     * - false/undefined: 串行执行（默认，向后兼容）
-     *
-     * 约束：
-     * - exclusive 工具忽略此属性（exclusive 总是独占批次）
-     * - 标记为 parallelizable 的工具应是无副作用的只读操作，
-     *   或其副作用不会与同批次其他工具冲突
-     */
-    parallelizable?: boolean;
-    /**
-     * 超时契约声明（ticket 023 / ADR-0005）。
-     *
-     * 声明后由框架执行器统一计时：超时触发合并 AbortSignal（reason=timeout），
-     * 并给工具一个 settle 窗口优雅收尾；未声明的工具不受框架超时管辖，行为不变。
-     *
-     * - defaultMs: 默认超时（模型未通过 fromArg 参数覆盖时生效）
-     * - maxMs: 生效超时的硬上限，任何来源的超时值都会被 clamp 到 [1, maxMs]
-     * - fromArg: 可选参数名；声明后生效超时取 args[fromArg]（数字），再 clamp
-     */
-    timeout?: {
-        defaultMs: number;
-        maxMs: number;
-        fromArg?: string;
-    };
-}
-interface AgentLogsResponse {
-    scope: 'current' | 'all';
-    selectedAgentId: string | null;
-    total: number;
-    logs: DebugLogEntry[];
-    truncation?: {
-        truncated: boolean;
-        appliedLimit?: number;
-        returnedCount: number;
-        availableCount: number;
-        nextOffset?: number;
-        reason?: string;
-        guidance?: string;
-    };
-    collectionPolicy: {
-        hubConnected: boolean;
-        includesOnlyHubDeliveredLogs: boolean;
-        fallbackBehavior: string;
-    };
-}
-type MessageRole = 'system' | 'user' | 'assistant' | 'tool' | string;
+type DecisionResult = Decision | {
+    /** 决策动作 */
+    action: Decision;
+    /** 拒绝原因（用于日志/调试） */
+    reason?: string;
+    /** 附加元数据 */
+    metadata?: Record<string, any>;
+};
 /**
- * 图片输入（多模态支持）
- *
- * 支持两种数据来源：
- * - `path`：图片已落盘到本地文件，编译 LLM 请求时按需读取为 base64（推荐）
- * - `base64`：内联 base64 数据（向后兼容旧会话）
- *
- * 优先使用 `path`；`base64` 仅作为旧会话兼容或无法落盘时的回退。
- * - 视觉模式（vision: true）：从 path 或 base64 读取图片数据传给 LLM API
- * - 非视觉模式（vision: false）：source 用于生成文字占位符
+ * 将 DecisionResult 转换为标准 Decision
  */
-interface ImageInput {
-    /** 本地文件绝对路径（推荐方式，避免 session 膨胀） */
-    path?: string;
-    /** Base64 编码的图片数据（不含 data URI 前缀），向后兼容 */
-    base64?: string;
-    /** MIME 类型，如 'image/png'、'image/jpeg' */
-    mediaType?: string;
-    /** 来源描述或原始文件名（用于非视觉模式的文字占位符显示） */
-    source?: string;
-}
-interface Message {
-    role: MessageRole;
-    content: string;
-    turn?: number;
-    toolCallId?: string;
-    toolCalls?: ToolCall[];
-    reasoning?: string;
-    thinkingBlocks?: ThinkingBlock[];
-    /** 图片附件（user 消息：用户输入的图片；tool 消息：工具返回的图片），多模态输入 */
-    images?: ImageInput[];
-    /**
-     * 前端展示数据（仅 tool 消息）。
-     *
-     * 当工具使用 withDisplay() 分离返回时，display 携带富数据（如 diff），
-     * 仅供前端渲染，不注入 LLM 上下文。LLM 只看到 content 中的精简文本。
-     */
-    display?: unknown;
-    /**
-     * 消息来源标记（仅 system 消息使用）。
-     *
-     * - undefined：agent 自身的系统提示词（由 templateResolver 生成），
-     *   Anthropic provider 将其放入顶层 system 参数。
-     * - 有值（如 'handoff-seed'、'partial-compact'）：Feature 注入的 system 消息，
-     *   Anthropic provider 将其包裹为 <reminder> 嵌入最近的 user turn，
-     *   而非混入顶层 system 参数。
-     */
-    source?: string;
-    /**
-     * 消息语义标签（所有 role 通用）。
-     *
-     * 与 source 的区别：
-     * - source 控制 LLM 编译层行为（顶层 system vs reminder）
-     * - tag 控制上下文管理层行为（trim/compact 时的保留策略）
-     *
-     * undefined = 无标签，向后兼容，行为与当前完全一致。
-     */
-    tag?: string;
-    /**
-     * LLM 用量信息（仅 assistant 消息有值）。
-     *
-     * 由 LLM provider 在生成响应时返回，表示生成此消息时的上下文 token 开销。
-     * inputTokens 是发送给 LLM 的完整上下文大小（包含所有历史消息），
-     * 不是单条消息的 token 数。
-     */
-    usage?: MessageUsage;
-    /**
-     * 执行终态元数据（仅 assistant 消息有值）。
-     *
-     * 框架在写入错误/截断等执行结果消息时盖戳。展示端（Web UI / 查看器）
-     * 应依据此字段渲染终态样式，而不是解析 content 文本前缀；该字段随
-     * 会话快照持久化，重渲染后保持稳定。
-     */
-    execution?: MessageExecutionMeta;
-}
+declare function normalizeDecision(result: DecisionResult): Decision;
 /**
- * 消息级执行终态摘要（Message.execution）
- *
- * CallOutcome 的可序列化子集；不重复 response/steps 等会话级信息。
+ * Agent 初始化上下文
  */
-interface MessageExecutionMeta {
-    status: ExecutionStatus;
-    reason: ExecutionReason;
-    error?: ExecutionError;
+interface AgentInitiateContext {
+    /** 消息上下文 */
+    context: Context;
 }
 /**
- * 消息级用量记录（盖戳在 assistant 消息上）
+ * Agent 销毁上下文
  */
-interface MessageUsage {
-    /** 生成此消息时，发送给 LLM 的总输入 token（即当时的完整上下文大小） */
-    inputTokens: number;
-    /** LLM 生成的输出 token */
-    outputTokens: number;
-}
-interface ThinkingBlock {
-    signature: string;
-    thinking: string;
-}
-interface ToolCall {
-    id: string;
-    name: string;
-    arguments: Record<string, any>;
-}
-interface LLMResponse {
-    content: string;
-    toolCalls?: ToolCall[];
-    reasoning?: string;
-    thinkingBlocks?: ThinkingBlock[];
-    /** 用量统计（可选） */
-    usage?: UsageInfo;
-    /** 停止原因，由 LLM API 返回（如 end_turn, tool_use, stop 等） */
-    stopReason?: string | null;
+interface AgentDestroyContext {
+    /** 消息上下文 */
+    context: Context;
 }
 /**
- * 渲染模板项
- * 可以是字符串模板或函数模板
+ * Call 开始上下文
  */
-type RenderTemplateItem = string | RenderTemplateFn;
+interface CallStartContext {
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+    /** 是否首次调用 */
+    isFirstCall: boolean;
+    /** Agent 实例（用于访问 setUserInput/getUserInput 等 API） */
+    agent?: any;
+}
 /**
- * 渲染模板函数类型
+ * 执行单元的终态。它只表达执行是否完成、失败、取消或移交给后续单元；
+ * 不复用模型厂商的 stop reason，也不推断宿主任务的业务状态。
  */
-type RenderTemplateFn = (data: Record<string, any>, success?: boolean) => string;
+type ExecutionStatus = 'completed' | 'failed' | 'cancelled' | 'continued';
 /**
- * 内联渲染模板
- * 直接定义在工具中的渲染模板（无需引用预设模板）
+ * 执行终止的框架级原因。
+ *
+ * `reason` 描述生命周期语义，错误来源由 `error.category` 表达，避免一个字段
+ * 同时承担供应商协议、框架控制流和宿主业务状态三种含义。
  */
-interface InlineRenderTemplate {
-    call: RenderTemplateItem;
-    result: RenderTemplateItem;
-}
-interface ToolRenderConfig {
-    /** 调用时的渲染模板（字符串引用或内联模板） */
-    call?: string | InlineRenderTemplate;
-    /** 结果时的渲染模板（字符串引用或内联模板） */
-    result?: string | InlineRenderTemplate;
-}
-interface LLMClient {
-    chat(messages: Message[], tools: Tool[], options?: LLMChatOptions): Promise<LLMResponse>;
-    /** 可选：返回当前 LLM 实例使用的模型名（用于调试显示） */
-    readonly modelName?: string;
+type ExecutionReason = 'completed' | 'cancelled' | 'limit_reached' | 'continued' | 'error';
+/** 可序列化的错误事实。category 是稳定的机器分类，message 只供展示。 */
+interface ExecutionError {
+    category: string;
+    message: string;
+    code?: string;
+    statusCode?: number;
+    retryable?: boolean;
 }
-interface LLMChatOptions {
-    /** 允许中断正在进行的 LLM 调用 */
-    signal?: AbortSignal;
-    /** 请求非流式响应（适用于一次性摘要、标题生成等场景） */
-    noStream?: boolean;
+/** 单次模型请求的来源信息；不决定 Call 的终态。 */
+interface ModelRequestOutcome {
+    providerStopReason?: string | null;
 }
 /**
- * 可热更新的模型元数据（与 LLMClient 实例解耦）
- *
- * 用于 Agent.setLLM() 时传递模型上下文信息，
- * 供 Feature（如 ContextGuard）根据新模型的 contextLength 调整行为。
+ * 一次 Agent Call（而非宿主任务）的结构化终态。
+ * 该对象可安全持久化、跨进程传输和用于 JSONL/CLI 消费。
  */
-interface LLMMeta {
-    modelName?: string;
-    contextLength?: number | null;
-    compressRatio?: number;
-    presetName?: string;
-    thinkingEffort?: string | null;
-}
-
-interface AgentConfig {
-    llm: LLMClient;
-    tools?: Tool[];
-    maxTurns?: number;
-    systemMessage?: string | TemplateSource;
-    name?: string;
-    projectRoot?: string;
-    workspaceDir?: string;
-    /**
-     * Feature 配置
-     *
-     * 新的声明式 Feature 注册方式
-     */
-    features?: {
-        /** 启用的 Feature 列表 */
-        enabled?: string[];
-        /** Feature 特定配置 */
-        [key: string]: unknown;
-    };
+interface CallOutcome {
+    status: ExecutionStatus;
+    reason: ExecutionReason;
+    response: string;
+    steps: number;
+    startedAt: number;
+    finishedAt: number;
+    error?: ExecutionError;
+    model?: ModelRequestOutcome;
 }
-type ContextMiddleware = (messages: Message[]) => Message[];
+/** @deprecated 使用 CallOutcome.reason。保留旧 hook/API 的类型兼容。 */
+type CallFinishReason = ExecutionReason;
 /**
- * Agent 注册信息（Hub 端）
+ * Call 结束上下文
  */
-interface AgentInfo {
-    id: string;
-    name: string;
-    registeredAt: number;
-    projectRoot?: string;
+interface CallFinishContext {
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+    /** 最终响应 */
+    response: string;
+    /** 执行的步骤数 */
+    steps: number;
+    /** 是否成功完成 */
+    completed: boolean;
+    /** 结束原因 */
+    finishReason: CallFinishReason;
+    /** 完整的结构化终态 */
+    outcome: CallOutcome;
 }
 /**
- * 工具元数据（用于前端渲染）
+ * Step 开始上下文
+ *
+ * Step 是 ReAct 循环中的单次迭代
  */
-interface ToolMetadata {
-    name: string;
-    description: string;
-    render: {
-        call: string | InlineRenderTemplate;
-        result: string | InlineRenderTemplate;
-        inlineCall?: InlineRenderTemplate;
-        inlineResult?: InlineRenderTemplate;
-    };
+interface StepStartContext {
+    /** 当前步骤序号（从 0 开始） */
+    step: number;
+    /** 当前调用序号（用户交互次数，从 0 开始） */
+    callIndex: number;
+    /** 消息上下文 */
+    context: Context;
+    /** 原始用户输入 */
+    input: string;
+    /** Agent 实例（用于访问当前会话中的 Feature、工具和输入状态） */
+    agent?: any;
 }
-interface HookSourceLocation {
-    file?: string;
-    line?: number;
-    column?: number;
-    display: string;
+/**
+ * Step 结束上下文
+ */
+interface StepFinishedContext extends StepStartContext {
+    /** LLM 响应 */
+    llmResponse: LLMResponse;
+    /** 执行的工具调用数量 */
+    toolCallsCount: number;
 }
-interface HookEntryMetadata {
-    order: number;
-    featureName: string;
-    methodName: string;
-    lifecycle: string;
-    /** 三原语（observe / guard / transform），由静态声明或装饰器路径推导 */
-    kind: 'observe' | 'guard' | 'transform';
-    /** guard 角色（policy 先于 advisor 执行）。仅 kind='guard' 条目存在。 */
-    role?: 'policy' | 'advisor';
-    source?: HookSourceLocation;
-    description?: string;
-    /** 是否启用。false 表示被运行时禁用。缺省视为 true（向后兼容）。 */
-    enabled?: boolean;
+/**
+ * 工具上下文 - onToolUse 钩子的参数
+ *
+ * 提供工具调用时的完整上下文信息
+ */
+interface ToolContext {
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具定义 */
+    tool: Tool;
+    /** 当前步骤序号 */
+    step: number;
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文（可读写） */
+    context: Context;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
 }
-interface HookLifecycleSnapshot {
-    lifecycle: string;
-    /** 生命周期级三原语汇总：桶内有 guard → guard，有 transform → transform，否则 observe */
-    kind: 'observe' | 'guard' | 'transform';
-    entries: HookEntryMetadata[];
+/**
+ * 工具结果 - onToolFinished 钩子的参数
+ *
+ * 提供工具执行后的完整结果信息
+ */
+interface ToolResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 经过 ToolResultTransform 后、实际写入模型上下文的最终结果。 */
+    delivered?: ToolExecResult;
+    /** 返回数据 */
+    data: unknown;
+    /** 错误信息（如果失败） */
+    error?: string;
+    /** 执行耗时(ms) */
+    duration: number;
+    /** 工具调用 */
+    call: ToolCall;
+    /** 工具定义 */
+    tool: Tool;
+    /** 当前步骤序号 */
+    step: number;
+    /** 用户输入 */
+    input: string;
+    /** 消息上下文 */
+    context: Context;
+    /** 获取其他 Feature */
+    getFeature<T extends AgentFeature>(name: string): T | undefined;
 }
-interface FeatureInspectorSnapshot {
-    name: string;
-    enabled: boolean;
-    status: 'enabled' | 'disabled' | 'removed' | 'partial';
-    hookCount: number;
-    toolCount: number;
-    enabledToolCount: number;
-    source?: string;
-    description?: string;
-    tools: Array<{
-        name: string;
-        description: string;
-        state: 'enabled' | 'disabled' | 'removed' | 'superseded';
-        enabled?: boolean;
-        renderCall?: string;
-        renderResult?: string;
-        parameters?: Record<string, unknown>;
-    }>;
+/**
+ * 钩子返回值类型（扩展版）
+ *
+ * 统一的生命周期钩子控制流指令
+ *
+ * - { 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 HookInspectorSnapshot {
-    lifecycleOrder: string[];
-    features: FeatureInspectorSnapshot[];
-    hooks: HookLifecycleSnapshot[];
-    standaloneTools?: Array<{
-        name: string;
-        description: string;
-        state: 'enabled' | 'disabled' | 'removed' | 'superseded';
-        enabled?: boolean;
-        source?: string;
-        renderCall?: string;
-        renderResult?: string;
-        parameters?: Record<string, unknown>;
-    }>;
+/**
+ * 子代理状态更新上下文
+ */
+interface SubAgentUpdateContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 旧状态 */
+    oldStatus: SubAgentStatus;
+    /** 新状态 */
+    newStatus: SubAgentStatus;
+    /** 执行结果（完成时） */
+    result?: string;
+    /** 错误信息（失败时） */
+    error?: string;
 }
-interface AgentContextMetrics {
-    messageCount: number;
-    charCount: number;
-    toolCallCount: number;
-    turnCount: number;
-}
-interface AgentOverviewSnapshot {
-    updatedAt: number;
-    context: AgentContextMetrics;
-    usageStats: UsageStatsSnapshot;
-    runtime?: AgentRuntimeStateSnapshot;
-    /** 可选：当前使用的模型名（由 agent 实例注入） */
-    modelName?: string;
-    /** 可选：当前使用的预设名（由 agent 实例注入，用于 UI dropdown 高亮） */
-    presetName?: string;
-    /** 可选：当前 LLM 实例的思考强度（由 agent 实例注入，用于 UI 状态同步） */
-    thinkingEffort?: string | null;
-    /** 可选：当前模型的上下文窗口长度（由 agent 实例注入，用于 UI 用量条实时同步） */
-    contextLength?: number;
-    /** 可选：当前模型的压缩阈值百分比（由 agent 实例注入，用于 UI 用量条实时同步） */
-    compressRatio?: number;
-}
-interface TodoTaskSnapshot {
-    id: string;
-    subject: string;
-    description: string;
-    status: 'pending' | 'in_progress' | 'completed' | 'deleted';
-    metadata?: Record<string, unknown>;
-    createdAt: number;
-    updatedAt: number;
-}
-interface TodoPlanSummary {
-    total: number;
-    pending: number;
-    inProgress: number;
-    completed: number;
-    cancelled: number;
-}
-interface TodoPlanSnapshot {
-    feature: 'todo';
-    updatedAt: number;
-    counter: number;
-    tasks: TodoTaskSnapshot[];
-    summary: TodoPlanSummary;
-    /** 中断目标 task ID（由 ControlledTodoFeature 扩展，null = 无中断目标） */
-    interruptTargetId?: string | null;
-    /** 任务未完强制继续开关状态（由 ControlledTodoFeature 扩展，null = 未上报） */
-    forceContinue?: {
-        enabled: boolean;
-        consecutive: number;
-        max: number;
-    } | null;
+/**
+ * 子代理销毁上下文
+ */
+interface SubAgentDestroyContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 销毁原因 */
+    reason: 'manual' | 'parent_dispose' | 'error';
 }
 /**
- * Agent 会话数据（Worker 端）
+ * Agent 中断上下文
  */
-interface AgentSession {
-    id: string;
-    name: string;
-    messages: Message[];
-    tools: ToolMetadata[];
-    createdAt: number;
-    lastActive: number;
-    projectRoot?: string;
-    currentState: Notification | null;
-    callActive?: boolean;
-    runtimeState?: AgentRuntimeStateSnapshot;
-    events: Notification[];
-    lastEventCount: number;
-    logs: DebugLogEntry[];
-    clientId?: string;
-    _lastMessageSig?: string;
-    hookInspector?: HookInspectorSnapshot;
-    overview?: AgentOverviewSnapshot;
-    todoPlan?: TodoPlanSnapshot;
-    /**
-     * 唯一的活动输入租约。一个 Agent 实例在任意时刻只能由一个输入请求
-     * 消费用户回复；这是跨 reconnect / 多进程路由的归属锚点。
-     */
-    inputLease?: InputLease;
-    queuedInputs: QueuedInput[];
-    /**
-     * 外部用户回合的接受策略，注册时声明。
-     * 'standard'（默认）：接受聊天邮箱排队与输入租约。
-     * 'none'：拒绝排队注入；测试沙盒等由宿主进程驱动输入的运行时使用。
-     * 输入租约（interactive input request）不受此策略限制，仍由 feature 控制。
-     */
-    inputPolicy?: 'standard' | 'none';
-}
-interface InputLease {
-    requestId: string;
-    prompt: string;
-    placeholder?: string;
-    initialValue?: string;
-    actions?: UserInputAction[];
-    mode?: UserInputRequestMode;
-    questions?: UserInputQuestion[];
-    timestamp: number;
+interface AgentInterruptContext {
+    /** 中断原因 */
+    reason: 'limit_reached' | 'error' | 'cancelled';
+    /** 当前步骤序号 */
+    step: number;
+    /** 当前消息上下文 */
+    context: Context;
 }
 /**
- * 排队的用户输入
+ * 子代理中断上下文
  */
-interface QueuedInput {
-    id: string;
-    text: string;
-    timestamp: number;
-    /** 图片附件（多模态输入） */
-    images?: ImageInput[];
-    /** 稳定的输入来源标识，供宿主诊断和后续路由扩展使用 */
-    source?: string;
-    /** 来源侧事件/请求标识，不承担全局幂等语义 */
-    sourceRef?: string;
-    /** 随消息流动的能力激活通知（capability refs，如 skill.grill-me） */
-    capabilityActivations?: string[];
+interface SubAgentInterruptContext {
+    /** 子代理 ID */
+    agentId: string;
+    /** 子代理类型 */
+    type: string;
+    /** 中断原因 */
+    reason: 'limit_reached' | 'error' | 'cancelled';
+    /** 中断时的结果 */
+    result: string;
 }
 /**
- * 一个不绑定具体 input request 的新用户回合。
+ * Step 结束决策上下文（反向钩子）
  *
- * ViewerWorker 会原子决定：若存在兼容的文本 input request，则直接响应；
- * 否则进入该已连接 runtime 的会话邮箱，等待下一次兼容的文本输入租约。
- * 这覆盖新建/恢复会话在输入循环尚未打开的启动窗口，不依赖 callActive。
+ * 用于在 Step 结束后进行流程控制决策
  */
-interface UserTurnInput {
-    text: string;
-    images?: ImageInput[];
-    source?: string;
-    sourceRef?: string;
-    /** 随消息流动的能力激活通知（capability refs）；经 lease 响应 payload 与排队项原样随行 */
-    capabilityActivations?: string[];
+interface StepFinishDecisionContext extends StepFinishedContext {
+    /** 是否有活跃的子代理（busy 状态） */
+    hasActiveSubAgents?: boolean;
+    /** 是否有待处理的子代理消息 */
+    hasPendingMessages?: boolean;
+    /** 是否调用了 wait 工具 */
+    waitCalled?: boolean;
 }
-type UserTurnSubmissionResult = {
-    success: true;
-    delivery: 'input';
-    requestId: string;
-    source?: string;
-    sourceRef?: string;
-} | {
-    success: true;
-    delivery: 'queued';
-    id: string;
-    queueLength: number;
-    source?: string;
-    sourceRef?: string;
-} | {
-    success: false;
-    code: 'agent_not_found' | 'invalid_input' | 'input_mode_conflict' | 'runtime_not_accepting_input';
-    error: string;
-    pendingMode?: UserInputRequestMode;
-};
-/**
- * DebugHub IPC 消息类型（主进程 → Worker）
- * 使用 discriminated union 确保类型安全
- */
-type DebugHubIPCMessage = RegisterAgentMsg | UpdateAgentInspectorMsg | UpdateAgentOverviewMsg | UpdateTodoPlanMsg | PushMessagesMsg | RegisterToolsMsg | UnregisterAgentMsg | PushNotificationMsg | RequestInputMsg | InputRequestCancelledMsg | InterruptAgentMsg | StopMsg;
 /**
- * 注册新 Agent
+ * 工具完成决策上下文（反向钩子）
+ *
+ * 用于在工具执行完成后进行流程控制决策
  */
-interface RegisterAgentMsg {
-    type: 'register-agent';
-    agentId: string;
-    name: string;
-    createdAt: number;
-    projectRoot?: string;
-    /**
-     * 模板装载点：Feature 所属包的真实目录根（junction 已解析）。
-     * Agent 侧是唯一知道权威 mount root 的一层（来自 feature.getPackageInfo()），
-     * 注册只传事实，不做 URL 推导；URL 由 viewer-worker 分配。
-     */
-    templateMounts?: string[];
-    /**
-     * 模板名 → 装载条目。mount 为 templateMounts 数组下标，
-     * rel 为该 mount root 下的相对路径（POSIX 分隔符）。
-     */
-    templateEntries?: Record<string, {
-        mount: number;
-        rel: string;
-    }>;
-    hookInspector?: HookInspectorSnapshot;
-    overview?: AgentOverviewSnapshot;
-    activeInputRequest?: ActiveInputRequest;
-    inputPolicy?: 'standard' | 'none';
-}
-interface UpdateAgentInspectorMsg {
-    type: 'update-agent-inspector';
-    agentId: string;
-    hookInspector: HookInspectorSnapshot;
-}
-interface UpdateAgentOverviewMsg {
-    type: 'update-agent-overview';
-    agentId: string;
-    overview: AgentOverviewSnapshot;
-}
-interface UpdateTodoPlanMsg {
-    type: 'update-todo-plan';
-    agentId: string;
-    plan: TodoPlanSnapshot;
+interface ToolFinishedDecisionContext extends ToolResult {
+    /** 刚才执行的工具名称 */
+    toolName: string;
 }
 /**
- * 推送 Agent 消息
+ * 工具结果变换上下文（反向钩子）
+ *
+ * 在工具执行完成、结果写入 context 之前，允许 Feature 对结果进行变换。
+ * 典型用途：输出截断（OutputGuard）、脱敏、格式清理等。
+ *
+ * 钩子返回 undefined 表示不修改；返回 ToolExecResult 表示用新结果替换。
+ * 多个钩子按注册顺序链式执行，前一个钩子的输出作为后一个钩子的输入。
  */
-interface PushMessagesMsg {
-    type: 'push-messages';
-    agentId: string;
-    messages: Message[];
+interface ToolResultTransformContext {
+    /** 工具名称 */
+    toolName: string;
+    /** 工具调用 */
+    call: ToolCall;
+    /** 当前结果（可能已被前一个变换钩子修改） */
+    result: ToolExecResult;
+    /** 当前步骤序号 */
+    step: number;
 }
+
 /**
-  * 注册 Agent 工具
-  */
-interface RegisterToolsMsg {
-    type: 'register-tools';
-    agentId: string;
-    tools: Tool[];
-}
+ * 基础类型定义
+ * 所有类型集中在这里，简单直观
+ */
+
 /**
- * 活跃的输入请求（用于重连后恢复）
+ * 通知分类
+ * - state: 覆盖式更新（如 LLM 字符计数）
+ * - event: 追加式记录（如工具开始/完成）
  */
-interface ActiveInputRequest {
-    requestId: string;
-    prompt: string;
-    placeholder?: string;
-    initialValue?: string;
-    actions?: UserInputAction[];
-    timestamp: number;
-}
+type NotificationCategory = 'state' | 'event';
 /**
- * 注销 Agent
+ * LLM 生成阶段
  */
-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[];
-    mode?: UserInputRequestMode;
-    questions?: UserInputQuestion[];
-}
-/**
- * 通知 Worker 一个输入请求已被运行时结算/取消（中断、销毁等）。
- * Worker 持有同名 inputLease 作为 HTTP 投递面；收到后应清除对应租约，
- * 否则陈旧租约会永久阻塞后续 user-turn（input_mode_conflict）。
- */
-interface InputRequestCancelledMsg {
-    type: 'input-request-cancelled';
-    agentId: string;
-    requestId: string;
-}
+type LLMPhase = 'thinking' | 'content' | 'tool_calling';
 /**
- * 中断正在运行的 Agent
+ * 通知基础接口
  */
-interface InterruptAgentMsg {
-    type: 'interrupt-agent';
-    agentId: string;
-    clearQueue?: boolean;
+interface Notification {
+    type: string;
+    category: NotificationCategory;
+    timestamp: number;
+    data: unknown;
 }
-interface UserInputAction {
-    id: string;
-    label: string;
-    kind?: 'rollback' | 'custom';
-    variant?: 'primary' | 'secondary' | 'danger';
-    payload?: Record<string, unknown>;
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+type DebugLogDeliveryReason = 'hub' | 'hub-unavailable' | 'no-agent-context';
+interface DebugLogDelivery {
+    hub: boolean;
+    console: boolean;
+    reason: DebugLogDeliveryReason;
 }
-type UserInputRequestMode = 'text' | 'choices';
-interface UserInputOption {
-    id: string;
-    label: string;
-    description?: string;
-    /** Whether this option allows supplementary free-text input */
-    allowSupplement?: boolean;
-    /** Whether the supplement text is required (only meaningful when allowSupplement is true) */
-    supplementRequired?: boolean;
-    /** Label shown above the supplement textarea */
-    supplementLabel?: string;
-    /** Placeholder for the supplement textarea */
-    supplementPlaceholder?: string;
+interface LogContextRef {
+    agentId?: string;
+    agentName?: string;
+    parentAgentId?: string;
+    callIndex?: number;
+    step?: number;
+    toolName?: string;
+    toolCallId?: string;
+    feature?: string;
+    lifecycle?: string;
+    hookMethod?: string;
+    hookKind?: 'forward' | 'observe' | 'guard' | 'transform';
+    sourceFile?: string;
+    sourceLine?: number;
+    tags?: string[];
+    [key: string]: unknown;
 }
-interface UserInputQuestion {
+interface DebugLogEntry {
     id: string;
-    question: string;
-    options: UserInputOption[];
-    allowCustom?: boolean;
-    customLabel?: string;
-    customPlaceholder?: string;
-}
-interface UserInputRequest {
-    prompt: string;
-    placeholder?: string;
-    initialValue?: string;
-    actions?: UserInputAction[];
-    mode?: UserInputRequestMode;
-    questions?: UserInputQuestion[];
-}
-interface UserInputChoiceAnswer {
-    questionId: string;
-    optionId?: string;
-    customText?: string;
-    /** Supplementary free-text provided alongside the selected option */
-    supplementText?: string;
-}
-interface UserInputResponse {
-    kind: 'text' | 'action' | 'choices';
-    text?: string;
-    actionId?: string;
-    choices?: UserInputChoiceAnswer[];
-    payload?: Record<string, unknown>;
+    timestamp: number;
+    level: LogLevel;
+    message: string;
+    namespace: string;
+    context: LogContextRef;
+    data?: unknown;
+    delivery: DebugLogDelivery;
 }
+type RuntimeStage = 'idle' | 'llm_thinking' | 'llm_content' | 'llm_tool_call_building' | 'awaiting_runtime' | 'tool_executing' | 'retry_waiting' | 'retry_requesting' | 'completed' | 'failed' | 'cancelled';
 /**
- * 消息标签枚举
- *
- * 用于快速分类和过滤消息，一条消息可能有多个标签
- */
-type MessageTag = 'user' | 'system' | 'assistant' | 'tool-call' | 'tool-result' | 'sub-agent' | 'reminder';
-/**
- * 解析结果结构
+ * 工具终止原因（ticket 023 / ADR-0005）
  *
- * 从消息 content 中提取的结构化信息
+ * - 'timeout'：框架统一超时计时触发（Tool 声明 timeout 后生效）
+ * - 'user'：外部用户中断（Agent.interrupt() 触发的 abort signal）
  */
-interface ParsedContent {
-    /** 从 content 提取的任务 ID（正则匹配 "taskId":"xxx"） */
-    taskIds: string[];
-    /** 从 content 提取的工具调用名称（从 toolCalls 或 content 解析） */
-    toolCalls: string[];
-    /** @ 提及的内容 */
-    mentions: string[];
-    /** 用户可继承扩展更多字段 */
-    [key: string]: any;
+type ToolTerminationReason = 'timeout' | 'user';
+interface AgentRuntimeStateSnapshot {
+    stage: RuntimeStage;
+    callActive: boolean;
+    charCount: number;
+    thinkingChars: number;
+    contentChars: number;
+    toolCallCount: number;
+    activeToolNames: string[];
+    activeToolCount: number;
+    /** LLM 流式期间检测到的工具名称（仅 llm_tool_call_building 阶段有值） */
+    streamToolNames?: string[];
+    callStartedAt?: number;
+    stageStartedAt?: number;
+    retryAttempt?: number;
+    maxRetries?: number;
+    nextRetryDelayMs?: number;
+    lastErrorType?: string | null;
+    lastErrorMessage?: string | null;
+    /** 最近一次已结束 Call 的结构化终态。 */
+    /** 最近一次已结束 Call 的结构化终态。 */
+    lastOutcome?: CallOutcome | null;
+    updatedAt: number;
 }
 /**
- * 扩展的消息结构
+ * 工具执行上下文
  *
- * 在原始 Message 基础上添加元数据
- * 不破坏现有 Message 类型，保证 LLM 调用兼容性
+ * 由框架在执行工具时注入。Feature 通过 {@link AgentFeature.getContextInjectors}
+ * 可以扩展额外字段。
  */
-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;
+interface ToolExecutionContext {
+    /** 中断信号，用于取消工具执行（外部用户中断与框架超时合并后的 signal） */
+    signal?: AbortSignal;
+    /** 当前工具调用的 LLM 生成 call.id（tool.progress 等进度信号配对用） */
+    callId?: string;
+    /**
+     * 查询当前工具执行是否已被终止及终止原因（ticket 023）。
+     *
+     * 返回 null 表示尚未终止；工具可据此在结果中填写模型可读的终止元数据。
+     * reason 不挂在 AbortSignal 上（signal 保持标准形状），统一经此函数查询。
+     */
+    termination?: () => ToolTerminationReason | null;
+    /** 当前终止 settle 的绝对截止时间（epoch ms）；工具用于把内部 drain 纳入同一预算。 */
+    terminationDeadline?: () => number | null;
+    /** 本次调用生效的超时（毫秒，含 args 覆盖后的 clamp 结果）；仅声明 timeout 的工具注入（ticket 025 进度显示用） */
+    timeoutMs?: number;
+    /** 注册 continuation request（供 checkpoint/rollback 等控制流工具使用） */
+    registerContinuationRequest?: (request: CallContinuationRequest) => void;
+    /** Feature 通过 contextInjectors 注入的自定义属性 */
+    [key: string]: unknown;
 }
-
-/**
- * 决策上下文（反向钩子参数）
- *
- * 所有决策上下文的联合类型
- */
-type DecisionContext = AgentInitiateContext | AgentDestroyContext | CallStartContext | CallFinishContext | StepStartContext | StepFinishedContext | ToolContext | ToolResult | StepFinishDecisionContext | ToolFinishedDecisionContext | ToolResultTransformContext;
-/**
- * 平台检测后的 UDS 路径
- */
-declare function getDefaultUDSPath(): string;
-
 /**
- * 上下文查询构建器
+ * 工具执行返回值类型
  *
- * 提供链式 API 用于过滤和聚合消息
- * 从 ContextFeature 移植到内核，作为 Context 的原生能力
+ * 工具可以返回纯文本或结构化对象。框架会自动序列化非 string 返回值。
  */
-
+type ToolResultValue = string | Record<string, unknown>;
 /**
- * 上下文查询构建器
- *
- * 提供链式 API 用于过滤和聚合消息
+ * 工具定义
  */
-declare class ContextQuery {
-    private messages;
-    private indexes;
-    constructor(messages: EnrichedMessage[], indexes: Map<string, Set<string>>);
-    private result;
-    /**
-     * 按角色过滤
-     */
-    byRole(...roles: string[]): this;
+interface Tool {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
     /**
-     * 按标签过滤（可组合）
-     */
-    byTag(...tags: MessageTag[]): this;
-    /**
-     * 按工具名过滤（使用索引加速）
-     */
-    byTool(name: string): this;
-    /**
-     * 按任务 ID 过滤（使用索引加速）
-     */
-    byTask(taskId: string): this;
-    /**
-     * 按子代理 ID 过滤
-     */
-    byAgentId(agentId: string): this;
-    /**
-     * 按时间起点过滤
-     */
-    since(timestamp: number): this;
-    /**
-     * 按轮次范围过滤
+     * 执行工具
+     *
+     * @param args 工具参数（来自 LLM 的 JSON 解析结果）
+     * @param context 执行上下文，包含框架注入的 signal、registerContinuationRequest，
+     *   以及各 Feature 通过 contextInjectors 注入的自定义属性
      */
-    inTurns(from: number, to?: number): this;
+    execute: (args: Record<string, unknown>, context?: ToolExecutionContext) => Promise<ToolResultValue>;
+    /** 可选：渲染配置 */
+    render?: ToolRenderConfig;
     /**
-     * content 包含指定文本
+     * 工具执行模式
+     * - 'normal'（默认）：普通工具，可与其他工具在同一次 assistant turn 中并行调用
+     * - 'exclusive'：独占工具，必须是 assistant turn 中唯一的工具调用
+     *
+     * exclusive 工具适用于控制流工具（如 checkpoint、rollback），
+     * 它们不应与其他工具产生副作用交织。
      */
-    containing(text: string): this;
+    executionMode?: 'normal' | 'exclusive';
     /**
-     * 最近 N 条
+     * 工具是否可并行执行。
+     *
+     * - true: 该工具可以与同批次中其他 parallelizable 工具并发执行
+     * - false/undefined: 串行执行（默认，向后兼容）
+     *
+     * 约束：
+     * - exclusive 工具忽略此属性（exclusive 总是独占批次）
+     * - 标记为 parallelizable 的工具应是无副作用的只读操作，
+     *   或其副作用不会与同批次其他工具冲突
      */
-    recent(n: number): this;
+    parallelizable?: boolean;
     /**
-     * 执行查询，返回结果数组
+     * 超时契约声明（ticket 023 / ADR-0005）。
+     *
+     * 声明后由框架执行器统一计时：超时触发合并 AbortSignal（reason=timeout），
+     * 并给工具一个 settle 窗口优雅收尾；未声明的工具不受框架超时管辖，行为不变。
+     *
+     * - defaultMs: 默认超时（模型未通过 fromArg 参数覆盖时生效）
+     * - maxMs: 生效超时的硬上限，任何来源的超时值都会被 clamp 到 [1, maxMs]
+     * - fromArg: 可选参数名；声明后生效超时取 args[fromArg]（数字），再 clamp
      */
-    exec(): EnrichedMessage[];
+    timeout?: {
+        defaultMs: number;
+        maxMs: number;
+        fromArg?: string;
+    };
+}
+interface AgentLogsResponse {
+    scope: 'current' | 'all';
+    selectedAgentId: string | null;
+    total: number;
+    logs: DebugLogEntry[];
+    truncation?: {
+        truncated: boolean;
+        appliedLimit?: number;
+        returnedCount: number;
+        availableCount: number;
+        nextOffset?: number;
+        reason?: string;
+        guidance?: string;
+    };
+    collectionPolicy: {
+        hubConnected: boolean;
+        includesOnlyHubDeliveredLogs: boolean;
+        fallbackBehavior: string;
+    };
+}
+type MessageRole = 'system' | 'user' | 'assistant' | 'tool' | string;
+/**
+ * 图片输入（多模态支持）
+ *
+ * 支持两种数据来源：
+ * - `path`：图片已落盘到本地文件，编译 LLM 请求时按需读取为 base64（推荐）
+ * - `base64`：内联 base64 数据（向后兼容旧会话）
+ *
+ * 优先使用 `path`；`base64` 仅作为旧会话兼容或无法落盘时的回退。
+ * - 视觉模式（vision: true）：从 path 或 base64 读取图片数据传给 LLM API
+ * - 非视觉模式（vision: false）：source 用于生成文字占位符
+ */
+interface ImageInput {
+    /** 本地文件绝对路径（推荐方式，避免 session 膨胀） */
+    path?: string;
+    /** Base64 编码的图片数据（不含 data URI 前缀），向后兼容 */
+    base64?: string;
+    /** MIME 类型，如 'image/png'、'image/jpeg' */
+    mediaType?: string;
+    /** 来源描述或原始文件名（用于非视觉模式的文字占位符显示） */
+    source?: string;
+}
+interface Message {
+    role: MessageRole;
+    content: string;
+    turn?: number;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+    reasoning?: string;
+    thinkingBlocks?: ThinkingBlock[];
+    /** 图片附件（user 消息：用户输入的图片；tool 消息：工具返回的图片），多模态输入 */
+    images?: ImageInput[];
     /**
-     * 获取第一条
+     * 前端展示数据（仅 tool 消息）。
+     *
+     * 当工具使用 withDisplay() 分离返回时，display 携带富数据（如 diff），
+     * 仅供前端渲染，不注入 LLM 上下文。LLM 只看到 content 中的精简文本。
      */
-    first(): EnrichedMessage | undefined;
+    display?: unknown;
     /**
-     * 获取最后一条
+     * 消息来源标记（仅 system 消息使用）。
+     *
+     * - undefined：agent 自身的系统提示词（由 templateResolver 生成），
+     *   Anthropic provider 将其放入顶层 system 参数。
+     * - 有值（如 'handoff-seed'、'partial-compact'）：Feature 注入的 system 消息，
+     *   Anthropic provider 将其包裹为 <reminder> 嵌入最近的 user turn，
+     *   而非混入顶层 system 参数。
      */
-    last(): EnrichedMessage | undefined;
+    source?: string;
     /**
-     * 计数
+     * 消息语义标签（所有 role 通用）。
+     *
+     * 与 source 的区别：
+     * - source 控制 LLM 编译层行为（顶层 system vs reminder）
+     * - tag 控制上下文管理层行为（trim/compact 时的保留策略）
+     *
+     * undefined = 无标签，向后兼容，行为与当前完全一致。
      */
-    count(): number;
+    tag?: string;
     /**
-     * 时间跨度统计
+     * LLM 用量信息（仅 assistant 消息有值）。
+     *
+     * 由 LLM provider 在生成响应时返回，表示生成此消息时的上下文 token 开销。
+     * inputTokens 是发送给 LLM 的完整上下文大小（包含所有历史消息），
+     * 不是单条消息的 token 数。
      */
-    timeSpan(): {
-        start: number;
-        end: number;
-        duration: number;
-    };
+    usage?: MessageUsage;
     /**
-     * 按工具分组统计
+     * 执行终态元数据（仅 assistant 消息有值）。
+     *
+     * 框架在写入错误/截断等执行结果消息时盖戳。展示端（Web UI / 查看器）
+     * 应依据此字段渲染终态样式，而不是解析 content 文本前缀；该字段随
+     * 会话快照持久化，重渲染后保持稳定。
      */
-    groupByTool(): Record<string, number>;
+    execution?: MessageExecutionMeta;
 }
-
 /**
- * 上下文管理器
- * 管理消息数组，提供简单的操作方法
+ * 消息级执行终态摘要（Message.execution）
  *
- * 内核化能力：
- * - 消息元数据包装（EnrichedMessage）
- * - 内容解析和索引
- * - 查询接口
+ * CallOutcome 的可序列化子集；不重复 response/steps 等会话级信息。
  */
-
+interface MessageExecutionMeta {
+    status: ExecutionStatus;
+    reason: ExecutionReason;
+    error?: ExecutionError;
+}
 /**
- * 工具执行结果（用于 addToolMessage）
+ * 消息级用量记录（盖戳在 assistant 消息上）
  */
-interface ToolExecResult {
-    success: boolean;
-    result: string | Record<string, any>;
-    error?: string;
-    /**
-     * 终止标注（ticket 023 / ADR-0005）：工具被超时/用户打断终止但仍在 settle
-     * 窗口内收尾时，结果以 success: true 返回并携带此字段。
-     * reason: 'timeout'（框架统一超时）| 'user'（外部用户中断）。
-     */
-    interrupted?: {
-        reason: ToolTerminationReason;
-    };
-    /** 工具返回的图片（注入到 tool 消息，视觉模式下传给 LLM） */
-    images?: ImageInput[];
-    /** 前端展示数据（不注入 LLM，仅 tool 消息） */
-    display?: unknown;
+interface MessageUsage {
+    /** 生成此消息时，发送给 LLM 的总输入 token（即当时的完整上下文大小） */
+    inputTokens: number;
+    /** LLM 生成的输出 token */
+    outputTokens: number;
+}
+interface ThinkingBlock {
+    signature: string;
+    thinking: string;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+}
+interface LLMResponse {
+    content: string;
+    toolCalls?: ToolCall[];
+    reasoning?: string;
+    thinkingBlocks?: ThinkingBlock[];
+    /** 用量统计（可选） */
+    usage?: UsageInfo;
+    /** 停止原因，由 LLM API 返回（如 end_turn, tool_use, stop 等） */
+    stopReason?: string | null;
 }
 /**
- * 上下文快照类型 - 用于序列化
+ * 渲染模板项
+ * 可以是字符串模板或函数模板
  */
-interface ContextSnapshot {
-    version: number;
-    messages: Message[];
-    enrichedMessages?: EnrichedMessage[];
-    sequence?: number;
-    generation?: number;
-    /** 截断归档（tombstone）。旧快照可能没有该字段，加载时视为空归档。 */
-    tombstones?: ContextTombstoneEntry[];
-}
+type RenderTemplateItem = string | RenderTemplateFn;
 /**
- * Context 边界快照 — 用于增量 rollback。
- *
- * 记录某个时间点两个数组的长度、sequence 和 generation，
- * 截断时只需按长度切片即可恢复到该边界。
- *
- * generation 用于防止 ABA 问题：如果 Context 经历了
- * clear/apply/restore 等非追加 mutation，generation 会递增，
- * 旧 boundary 会被拒绝。
+ * 渲染模板函数类型
  */
-interface ContextBoundaryV2 {
-    messagesLength: number;
-    enrichedMessagesLength: number;
-    sequence: number;
-    generation: number;
-}
+type RenderTemplateFn = (data: Record<string, any>, success?: boolean) => string;
 /**
- * Tombstone 摘要 — 轻量元数据，不含消息内容。
+ * 内联渲染模板
+ * 直接定义在工具中的渲染模板（无需引用预设模板）
  */
-interface ContextTombstoneSummary {
-    /** 单调递增的 tombstone ID（同一 Context 实例内唯一） */
-    id: number;
-    /** 截断恢复到的边界 */
-    boundary: ContextBoundaryV2;
-    /** 被截断的消息条数 */
-    removedMessageCount: number;
-    /** 截断发生时间（ISO 字符串） */
-    truncatedAt: string;
+interface InlineRenderTemplate {
+    call: RenderTemplateItem;
+    result: RenderTemplateItem;
+}
+interface ToolRenderConfig {
+    /** 调用时的渲染模板（字符串引用或内联模板） */
+    call?: string | InlineRenderTemplate;
+    /** 结果时的渲染模板（字符串引用或内联模板） */
+    result?: string | InlineRenderTemplate;
+}
+interface LLMClient {
+    chat(messages: Message[], tools: Tool[], options?: LLMChatOptions): Promise<LLMResponse>;
+    /** 可选：返回当前 LLM 实例使用的模型名（用于调试显示） */
+    readonly modelName?: string;
+}
+interface LLMChatOptions {
+    /** 允许中断正在进行的 LLM 调用 */
+    signal?: AbortSignal;
+    /** 请求非流式响应（适用于一次性摘要、标题生成等场景） */
+    noStream?: boolean;
 }
 /**
- * Tombstone 完整条目 — 含被截断的消息内容。
+ * 可热更新的模型元数据（与 LLMClient 实例解耦）
  *
- * rollback 截断不再物理丢失内容：被截尾部进入 tombstone 归档，
- * 可查询（listTombstones / getTombstone），在 Context 仍处于该边界时
- * 可完整恢复（restoreTombstone）。
+ * 用于 Agent.setLLM() 时传递模型上下文信息，
+ * 供 Feature（如 ContextGuard）根据新模型的 contextLength 调整行为。
  */
-interface ContextTombstoneEntry extends ContextTombstoneSummary {
-    removedMessages: Message[];
-    removedEnrichedMessages: EnrichedMessage[];
+interface LLMMeta {
+    modelName?: string;
+    contextLength?: number | null;
+    compressRatio?: number;
+    presetName?: string;
+    thinkingEffort?: string | null;
+    /** 模型协议（'anthropic' | 'openai' 等），由 resolver 提供时携带，供档位切换等消费方推断协议 */
+    provider?: string;
+    /** 本次切换的发起方标记：'boot' | 'user' | 'feature:<name>' 等，供让位策略区分用户手动切换与 Feature 切换 */
+    source?: string;
 }
-declare class Context {
-    private messages;
-    private enrichedMessages;
-    private indexes;
-    private sequence;
-    /**
-     * Lineage generation，用于检测非追加 mutation。
-     *
-     * - 纯追加 typed message（addUserMessage 等）：不变
-     * - rollback 的合法截断（truncateToBoundary）：不变
-     * - clear / apply：递增
-     * - restore：使用 snapshot 携带的 generation，否则递增
-     */
-    private generation;
+/**
+ * resolver 解析产物：成品 LLM 客户端 + 对齐 LLMMeta 的元数据。
+ * 资产（apiKey / OAuth token / 配置文件）由注入方持有，永不进入本结构。
+ */
+interface ResolvedModelPreset {
+    llm: AgentConfig['llm'];
+    meta: LLMMeta;
+}
+/**
+ * 模型 preset 解析服务契约（应用层注入，core 不提供实现）。
+ *
+ * 框架只编排"怎么换"（resolve → setLLM → 贴标 → 通知）；
+ * "有哪些 preset、凭证在哪、客户端怎么造"归应用层。每次调用都应现读
+ * 配置源（不缓存快照），调用方可安全地以任意频率重复调用。
+ */
+interface ModelPresetResolver {
     /**
-     * 截断归档（tombstone）。append-only：clear/apply/restore 不清空，
-     * 只有 restore(snapshot) 采用快照携带的归档。
+     * @param presetName preset 名（应用层命名空间，如 Claw 的 presets.json 条目名）
+     * @param overrides 运行时覆盖；thinkingEffort 为 null 表示清除为厂商默认。
+     * @returns 解析失败（名字不存在 / 凭证缺失）返回 null，不抛错
      */
-    private tombstones;
-    private tombstoneSeq;
+    resolve(presetName: string, overrides?: {
+        thinkingEffort?: string | null;
+    }): ResolvedModelPreset | null;
+}
+
+interface AgentConfig {
+    llm: LLMClient;
+    tools?: Tool[];
+    maxTurns?: number;
+    systemMessage?: string | TemplateSource;
+    name?: string;
+    projectRoot?: string;
+    workspaceDir?: string;
     /**
-     * 添加一条消息
+     * 模型 preset 解析服务（可选注入）。
+     * 注入后 setModel / setThinkingEffort 可用；资产留在注入方，agent 只拿成品客户端。
      */
-    add(message: Message): this;
+    modelResolver?: ModelPresetResolver;
     /**
-     * 添加多条消息
+     * Feature 配置
+     *
+     * 新的声明式 Feature 注册方式
      */
-    addAll(messages: Message[]): this;
+    features?: {
+        /** 启用的 Feature 列表 */
+        enabled?: string[];
+        /** Feature 特定配置 */
+        [key: string]: unknown;
+    };
+}
+type ContextMiddleware = (messages: Message[]) => Message[];
+/**
+ * Agent 注册信息（Hub 端）
+ */
+interface AgentInfo {
+    id: string;
+    name: string;
+    registeredAt: number;
+    projectRoot?: string;
+}
+/**
+ * 工具元数据（用于前端渲染）
+ */
+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;
+    /** 三原语（observe / guard / transform），由静态声明或装饰器路径推导 */
+    kind: 'observe' | 'guard' | 'transform';
+    /** guard 角色（policy 先于 advisor 执行）。仅 kind='guard' 条目存在。 */
+    role?: 'policy' | 'advisor';
+    source?: HookSourceLocation;
+    description?: string;
+    /** 是否启用。false 表示被运行时禁用。缺省视为 true（向后兼容）。 */
+    enabled?: boolean;
+}
+interface HookLifecycleSnapshot {
+    lifecycle: string;
+    /** 生命周期级三原语汇总：桶内有 guard → guard，有 transform → transform，否则 observe */
+    kind: 'observe' | 'guard' | 'transform';
+    entries: HookEntryMetadata[];
+}
+interface FeatureInspectorSnapshot {
+    name: string;
+    enabled: boolean;
+    status: 'enabled' | 'disabled' | 'removed' | 'partial';
+    hookCount: number;
+    toolCount: number;
+    enabledToolCount: number;
+    source?: string;
+    description?: string;
+    tools: Array<{
+        name: string;
+        description: string;
+        state: 'enabled' | 'disabled' | 'removed' | 'superseded';
+        enabled?: boolean;
+        renderCall?: string;
+        renderResult?: string;
+        parameters?: Record<string, unknown>;
+    }>;
+}
+interface HookInspectorSnapshot {
+    lifecycleOrder: string[];
+    features: FeatureInspectorSnapshot[];
+    hooks: HookLifecycleSnapshot[];
+    standaloneTools?: Array<{
+        name: string;
+        description: string;
+        state: 'enabled' | 'disabled' | 'removed' | 'superseded';
+        enabled?: boolean;
+        source?: string;
+        renderCall?: string;
+        renderResult?: string;
+        parameters?: Record<string, unknown>;
+    }>;
+}
+interface AgentContextMetrics {
+    messageCount: number;
+    charCount: number;
+    toolCallCount: number;
+    turnCount: number;
+}
+interface AgentOverviewSnapshot {
+    updatedAt: number;
+    context: AgentContextMetrics;
+    usageStats: UsageStatsSnapshot;
+    runtime?: AgentRuntimeStateSnapshot;
+    /** 可选：当前使用的模型名（由 agent 实例注入） */
+    modelName?: string;
+    /** 可选：当前使用的预设名（由 agent 实例注入，用于 UI dropdown 高亮） */
+    presetName?: string;
+    /** 可选：当前 LLM 实例的思考强度（由 agent 实例注入，用于 UI 状态同步） */
+    thinkingEffort?: string | null;
+    /** 可选：当前模型的上下文窗口长度（由 agent 实例注入，用于 UI 用量条实时同步） */
+    contextLength?: number;
+    /** 可选：当前模型的压缩阈值百分比（由 agent 实例注入，用于 UI 用量条实时同步） */
+    compressRatio?: number;
+}
+interface TodoTaskSnapshot {
+    id: string;
+    subject: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'deleted';
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface TodoPlanSummary {
+    total: number;
+    pending: number;
+    inProgress: number;
+    completed: number;
+    cancelled: number;
+}
+interface TodoPlanSnapshot {
+    feature: 'todo';
+    updatedAt: number;
+    counter: number;
+    tasks: TodoTaskSnapshot[];
+    summary: TodoPlanSummary;
+    /** 中断目标 task ID（由 ControlledTodoFeature 扩展，null = 无中断目标） */
+    interruptTargetId?: string | null;
+    /** 任务未完强制继续开关状态（由 ControlledTodoFeature 扩展，null = 未上报） */
+    forceContinue?: {
+        enabled: boolean;
+        consecutive: number;
+        max: number;
+    } | null;
+}
+/**
+ * Agent 会话数据（Worker 端）
+ */
+interface AgentSession {
+    id: string;
+    name: string;
+    messages: Message[];
+    tools: ToolMetadata[];
+    createdAt: number;
+    lastActive: number;
+    projectRoot?: string;
+    currentState: Notification | null;
+    callActive?: boolean;
+    runtimeState?: AgentRuntimeStateSnapshot;
+    events: Notification[];
+    lastEventCount: number;
+    logs: DebugLogEntry[];
+    clientId?: string;
+    _lastMessageSig?: string;
+    hookInspector?: HookInspectorSnapshot;
+    overview?: AgentOverviewSnapshot;
+    todoPlan?: TodoPlanSnapshot;
     /**
-     * 获取所有消息的副本
+     * 唯一的活动输入租约。一个 Agent 实例在任意时刻只能由一个输入请求
+     * 消费用户回复；这是跨 reconnect / 多进程路由的归属锚点。
      */
-    getAll(): Message[];
+    inputLease?: InputLease;
+    queuedInputs: QueuedInput[];
     /**
-     * 获取消息数量
-     */
-    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, images?: ImageInput[]): void;
-    /**
-     * 添加助手响应
-     *
-     * 框架合成消息（错误/截断说明）可通过 execution 字段附带执行终态元数据。
-     */
-    addAssistantMessage(response: LLMResponse & {
-        execution?: MessageExecutionMeta;
-    }, turn: number): void;
-    /**
-     * 添加工具结果
-     */
-    addToolMessage(call: ToolCall, result: ToolExecResult, turn: number): void;
-    /**
-     * 添加已经序列化的工具消息。
-     *
-     * 用于 session/handoff 恢复等边界：原始 tool content 已经是 provider 可重放的
-     * 序列化字符串，不应先解析成 ToolExecResult 再重新编码。该入口同时维护
-     * messages[] 与 enrichedMessages[]，并保留工具返回的图片附件。
-     */
-    addSerializedToolMessage(toolCallId: string, content: string, turn: number, images?: ImageInput[], display?: unknown): void;
-    /**
-     * 添加系统消息
-     */
-    addSystemMessage(content: string, turn: number, source?: string, tag?: 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;
-    /**
-     * 捕获当前 Context 的前缀边界。
-     *
-     * 返回一个轻量快照，记录两个数组的长度、sequence 和 generation。
-     * 后续可传给 truncateToBoundary() 恢复到此边界。
-     *
-     * generation 不变：纯读取操作。
-     */
-    captureBoundary(): ContextBoundaryV2;
-    /**
-     * 校验 boundary 是否与当前 Context 兼容。
-     *
-     * @throws 如果 generation 不匹配、长度非法或超出当前数组。
-     */
-    private assertBoundaryCompatible;
-    /**
-     * 将两个数组截断到指定边界。
-     *
-     * 这是合法的 rollback 操作：generation 保持不变，
-     * 截断后同一 lineage 的旧 boundary 仍然可以继续使用。
-     *
-     * 被截尾部进入 tombstone 归档（不物理丢失）：
-     * 通过 listTombstones() / getTombstone() 查询，
-     * Context 仍处于该边界时可通过 restoreTombstone() 完整恢复。
-     *
-     * @throws 如果 boundary 与当前 Context 不兼容（generation 不匹配或长度越界）。
-     */
-    truncateToBoundary(boundary: ContextBoundaryV2): void;
-    /**
-     * 列出 tombstone 摘要（不含消息内容）。
+     * 外部用户回合的接受策略，注册时声明。
+     * 'standard'（默认）：接受聊天邮箱排队与输入租约。
+     * 'none'：拒绝排队注入；测试沙盒等由宿主进程驱动输入的运行时使用。
+     * 输入租约（interactive input request）不受此策略限制，仍由 feature 控制。
      */
-    listTombstones(): ContextTombstoneSummary[];
+    inputPolicy?: 'standard' | 'none';
+}
+interface InputLease {
+    requestId: string;
+    prompt: string;
+    placeholder?: string;
+    initialValue?: string;
+    actions?: UserInputAction[];
+    mode?: UserInputRequestMode;
+    questions?: UserInputQuestion[];
+    timestamp: number;
+}
+/**
+ * 排队的用户输入
+ */
+interface QueuedInput {
+    id: string;
+    text: string;
+    timestamp: number;
+    /** 图片附件（多模态输入） */
+    images?: ImageInput[];
+    /** 稳定的输入来源标识，供宿主诊断和后续路由扩展使用 */
+    source?: string;
+    /** 来源侧事件/请求标识，不承担全局幂等语义 */
+    sourceRef?: string;
+    /** 随消息流动的能力激活通知（capability refs，如 skill.grill-me） */
+    capabilityActivations?: string[];
+}
+/**
+ * 一个不绑定具体 input request 的新用户回合。
+ *
+ * ViewerWorker 会原子决定：若存在兼容的文本 input request，则直接响应；
+ * 否则进入该已连接 runtime 的会话邮箱，等待下一次兼容的文本输入租约。
+ * 这覆盖新建/恢复会话在输入循环尚未打开的启动窗口，不依赖 callActive。
+ */
+interface UserTurnInput {
+    text: string;
+    images?: ImageInput[];
+    source?: string;
+    sourceRef?: string;
+    /** 随消息流动的能力激活通知（capability refs）；经 lease 响应 payload 与排队项原样随行 */
+    capabilityActivations?: string[];
+}
+type UserTurnSubmissionResult = {
+    success: true;
+    delivery: 'input';
+    requestId: string;
+    source?: string;
+    sourceRef?: string;
+} | {
+    success: true;
+    delivery: 'queued';
+    id: string;
+    queueLength: number;
+    source?: string;
+    sourceRef?: string;
+} | {
+    success: false;
+    code: 'agent_not_found' | 'invalid_input' | 'input_mode_conflict' | 'runtime_not_accepting_input';
+    error: string;
+    pendingMode?: UserInputRequestMode;
+};
+/**
+ * DebugHub IPC 消息类型（主进程 → Worker）
+ * 使用 discriminated union 确保类型安全
+ */
+type DebugHubIPCMessage = RegisterAgentMsg | UpdateAgentInspectorMsg | UpdateAgentOverviewMsg | UpdateTodoPlanMsg | PushMessagesMsg | RegisterToolsMsg | UnregisterAgentMsg | PushNotificationMsg | RequestInputMsg | InputRequestCancelledMsg | InterruptAgentMsg | StopMsg;
+/**
+ * 注册新 Agent
+ */
+interface RegisterAgentMsg {
+    type: 'register-agent';
+    agentId: string;
+    name: string;
+    createdAt: number;
+    projectRoot?: string;
     /**
-     * 按 ID 取回 tombstone 完整内容（深拷贝，修改返回值不影响归档）。
+     * 模板装载点：Feature 所属包的真实目录根（junction 已解析）。
+     * Agent 侧是唯一知道权威 mount root 的一层（来自 feature.getPackageInfo()），
+     * 注册只传事实，不做 URL 推导；URL 由 viewer-worker 分配。
      */
-    getTombstone(id: number): ContextTombstoneEntry | undefined;
+    templateMounts?: string[];
     /**
-     * 从 tombstone 恢复被截尾部。
-     *
-     * 仅当 Context 仍精确处于该 tombstone 的边界时允许
-     * （generation、两个数组长度、sequence 全部匹配）——此时恢复是
-     * 截断的精确逆操作，不破坏 lineage。
-     *
-     * 恢复后 sequence 续接被截尾部的最大序号，generation 不变。
-     *
-     * @throws 如果 Context 已离开该边界（例如截断后追加了新消息）。
-     *         此时内容仍可通过 getTombstone() 提取，由调用方决定如何重组。
+     * 模板名 → 装载条目。mount 为 templateMounts 数组下标，
+     * rel 为该 mount root 下的相对路径（POSIX 分隔符）。
      */
-    restoreTombstone(id: number): void;
+    templateEntries?: Record<string, {
+        mount: number;
+        rel: string;
+    }>;
+    hookInspector?: HookInspectorSnapshot;
+    overview?: AgentOverviewSnapshot;
+    activeInputRequest?: ActiveInputRequest;
+    inputPolicy?: 'standard' | 'none';
+}
+interface UpdateAgentInspectorMsg {
+    type: 'update-agent-inspector';
+    agentId: string;
+    hookInspector: HookInspectorSnapshot;
+}
+interface UpdateAgentOverviewMsg {
+    type: 'update-agent-overview';
+    agentId: string;
+    overview: AgentOverviewSnapshot;
+}
+interface UpdateTodoPlanMsg {
+    type: 'update-todo-plan';
+    agentId: string;
+    plan: TodoPlanSnapshot;
+}
+/**
+ * 推送 Agent 消息
+ */
+interface PushMessagesMsg {
+    type: 'push-messages';
+    agentId: string;
+    messages: Message[];
+}
+/**
+  * 注册 Agent 工具
+  */
+interface RegisterToolsMsg {
+    type: 'register-tools';
+    agentId: string;
+    tools: Tool[];
+}
+/**
+ * 活跃的输入请求（用于重连后恢复）
+ */
+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[];
+    mode?: UserInputRequestMode;
+    questions?: UserInputQuestion[];
+}
+/**
+ * 通知 Worker 一个输入请求已被运行时结算/取消（中断、销毁等）。
+ * Worker 持有同名 inputLease 作为 HTTP 投递面；收到后应清除对应租约，
+ * 否则陈旧租约会永久阻塞后续 user-turn（input_mode_conflict）。
+ */
+interface InputRequestCancelledMsg {
+    type: 'input-request-cancelled';
+    agentId: string;
+    requestId: string;
+}
+/**
+ * 中断正在运行的 Agent
+ */
+interface InterruptAgentMsg {
+    type: 'interrupt-agent';
+    agentId: string;
+    clearQueue?: boolean;
+}
+interface UserInputAction {
+    id: string;
+    label: string;
+    kind?: 'rollback' | 'custom';
+    variant?: 'primary' | 'secondary' | 'danger';
+    payload?: Record<string, unknown>;
+}
+type UserInputRequestMode = 'text' | 'choices';
+interface UserInputOption {
+    id: string;
+    label: string;
+    description?: string;
+    /** Whether this option allows supplementary free-text input */
+    allowSupplement?: boolean;
+    /** Whether the supplement text is required (only meaningful when allowSupplement is true) */
+    supplementRequired?: boolean;
+    /** Label shown above the supplement textarea */
+    supplementLabel?: string;
+    /** Placeholder for the supplement textarea */
+    supplementPlaceholder?: string;
+}
+interface UserInputQuestion {
+    id: string;
+    question: string;
+    options: UserInputOption[];
+    allowCustom?: boolean;
+    customLabel?: string;
+    customPlaceholder?: string;
+}
+interface UserInputRequest {
+    prompt: string;
+    placeholder?: string;
+    initialValue?: string;
+    actions?: UserInputAction[];
+    mode?: UserInputRequestMode;
+    questions?: UserInputQuestion[];
+}
+interface UserInputChoiceAnswer {
+    questionId: string;
+    optionId?: string;
+    customText?: string;
+    /** Supplementary free-text provided alongside the selected option */
+    supplementText?: string;
+}
+interface UserInputResponse {
+    kind: 'text' | 'action' | 'choices';
+    text?: string;
+    actionId?: string;
+    choices?: UserInputChoiceAnswer[];
+    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;
+}
+
+/**
+ * 决策上下文（反向钩子参数）
+ *
+ * 所有决策上下文的联合类型
+ */
+type DecisionContext = AgentInitiateContext | AgentDestroyContext | CallStartContext | CallFinishContext | StepStartContext | StepFinishedContext | ToolContext | ToolResult | StepFinishDecisionContext | ToolFinishedDecisionContext | ToolResultTransformContext;
+/**
+ * 平台检测后的 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;
 }
+declare function installConsoleBridge(): void;
+declare function runWithLogScope<T>(scope: LogContextRef, fn: () => T): T;
+declare function emitLog(level: LogLevel, message: string, data?: unknown, options?: {
+    namespace?: string;
+    context?: LogContextRef;
+}): DebugLogEntry;
+declare function createLogger(namespace: string, bindings?: LoggerBindings): Logger;
 
 /**
  * 工具定义
@@ -3261,6 +3344,8 @@ declare class AgentBase {
     private _llmMeta;
     /** 外部消费者通过 onLLMSwap() 注册的回调 */
     private _llmSwapCallbacks;
+    /** 应用层注入的 preset 解析服务（构造时注入；资产留在注入方） */
+    private _modelResolver;
     constructor(config: AgentConfig);
     observeHookInvocations(observer: HookInvocationObserver): () => void;
     /**
@@ -3390,6 +3475,35 @@ declare class AgentBase {
      * 获取当前模型元数据（不可变副本）
      */
     getLLMMeta(): LLMMeta;
+    /**
+     * 按 preset 名一键切换模型
+     *
+     * 编排：resolver.resolve → setLLM（换实例 / 贴 meta 标 / 通知 Feature / 推 Overview）。
+     * preset 表与凭证由应用层注入的 resolver 提供，本方法只编排流程，因此宿主与
+     * Feature 消费同一入口，切换后的模型状态以 getLLMMeta() 为唯一权威。
+     *
+     * 允许在 onCall 运行期间调用（mid-turn swap），语义同 setLLM。
+     *
+     * @param presetName preset 名
+     * @param opts.thinkingEffort 运行时档位覆盖；null 表示清除为厂商默认
+     * @param opts.source 切换发起方标记（'user' / 'feature:<name>' 等），写入 meta 供让位策略区分
+     * @returns false 表示 preset 解析失败（名字不存在 / 凭证缺失），模型未变
+     * @throws 未注入 modelResolver 时抛出 —— 装配缺失应显式失败而非静默
+     */
+    setModel(presetName: string, opts?: {
+        thinkingEffort?: string | null;
+        source?: string;
+    }): boolean;
+    /**
+     * 仅调整思考档位（不动模型）：按当前 presetName 重 resolve。
+     * 档位固化在 LLM 实例构造里，因此调整档位 = 以覆盖档位重造客户端。
+     *
+     * @param effort 档位；null 表示清除为厂商默认
+     * @returns false 表示当前模型无 presetName 可锚定或解析失败
+     */
+    setThinkingEffort(effort: string | null, opts?: {
+        source?: string;
+    }): boolean;
     rollbackToCall(callIndex: number): Promise<{
         draftInput: string;
     }>;
@@ -3479,8 +3593,9 @@ declare class AgentBase {
      * @param callIndex Call 序号
      * @param step Step 序号
      * @param usage 用量数据
+     * @param model 该次请求的模型归因（缺省不计入分段）
      */
-    recordUsage(callIndex: number, step: number, usage: UsageInfo): void;
+    recordUsage(callIndex: number, step: number, usage: UsageInfo, model?: ModelUsageKey): void;
     /**
      * 标记 Call 结束
      * @param callIndex Call 序号
@@ -3966,6 +4081,34 @@ declare function resolveModelCallPolicy(config?: {
     timeoutMs: number | undefined;
 };
 
+/**
+ * Session Events - 会话事件流
+ *
+ * 职责：
+ * - 定义无头模式（headless）消费的会话事件模型（codex exec 风格）
+ * - 提供进程内订阅 API，消息变更单点发射
+ *
+ * 与通知系统（notification.ts）的分工：
+ * - notification 是 UI 状态信号：节流、轻量、面向 Web UI 进度指示
+ * - session event 是审计数据：不节流、完整、面向无头模式 stdout JSONL
+ *
+ * 事件模型（对齐 codex exec JSONL）：
+ * - thread.started  线程（会话）开始
+ * - turn.started    一次用户输入触发的回合开始
+ * - item.started / item.completed  会话条目生命周期
+ * - turn.completed  回合完成（含 token 用量）
+ * - turn.failed     回合失败
+ *
+ * 术语（ADR-0002/Q6，一词不混用）：本事件流里的 `thread.started` 的 thread
+ * 指**会话本身**（codex exec 对外 jsonl 审计契约，永不改义）；框架的接续链概念
+ * 定名 **WorkThread**（见 `core/workthread/`），一处不混用。
+ *
+ * item 类型：
+ * - agent_message  agent 的自然语言回复
+ * - reasoning      agent 的思考摘要
+ * - tool_call      工具调用（参数、结果、错误、状态）
+ */
+
 interface SessionItemBase {
     /** 条目唯一 ID：tool_call 用 LLM 生成的 call.id，其余用递增 item_N */
     id: string;
@@ -4089,6 +4232,22 @@ interface SkillsOptions {
     baseDir?: 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 配置类型
  */
@@ -4973,7 +5132,7 @@ declare class ExampleFeature implements AgentFeature {
     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>;
+    handleStepFinish(_ctx: StepFinishDecisionContext): Promise<typeof Decision.Continue>;
 }
 
 /**
@@ -5297,6 +5456,8 @@ interface BasicAgentConfig {
     projectRoot?: string;
     /** 工具默认操作的工作目录 */
     workspaceDir?: string;
+    /** 模型预设解析器（可选；运行期 setModel / setThinkingEffort 消费，未注入时二者抛错） */
+    modelResolver?: AgentConfig['modelResolver'];
 }
 /**
  * 基础 Agent 类
@@ -6255,7 +6416,6 @@ declare function declareContinuity<T extends AnyFeatureConstructor>(Base: T, des
  */
 declare const WorkThreadCommandStatus: Readonly<{
     readonly PENDING: "pending";
-    readonly IN_FLIGHT: "in_flight";
     readonly DELIVERED: "delivered";
     readonly FAILED: "failed";
     readonly CANCELLED: "cancelled";
@@ -6266,6 +6426,9 @@ declare const WorkThreadCommandKind: Readonly<{
     readonly SYSTEM_CONTINUATION: "system_continuation";
     readonly EXTERNAL: "external";
 }>;
+/** 终态指令保留上限（超出按时间裁剪，防止 commands 无限增长） */
+declare const MAX_RETAINED_TERMINAL_COMMANDS = 200;
+declare function generateCommandId(): string;
 interface WorkThreadCommand {
     commandId: string;
     threadId: string;
@@ -6283,7 +6446,46 @@ interface WorkThreadCommand {
     deliveryRef?: string | null;
     /** 随指令流动的能力激活通知（capability refs），投递时随 user-turn 元数据转发 */
     capabilityActivations?: string[];
+    /** 随指令流动的图片引用（附件名/路径/URL），投递时转发给 viewer user-turn */
+    images?: string[];
 }
+/**
+ * 构造新指令记录（不修改 thread record）。
+ */
+declare function createCommandRecord(opts: {
+    threadId: string;
+    kind?: string;
+    text?: string;
+    source?: string;
+    idempotencyKey?: string;
+    capabilityActivations?: string[];
+    images?: string[];
+}): WorkThreadCommand;
+/**
+ * 幂等追加指令。若 idempotencyKey 命中既有的 pending / delivered
+ * 指令，直接返回既有指令（重复提交不产生副作用）。
+ * @returns {{command: WorkThreadCommand, duplicate: boolean}}
+ */
+declare function appendCommand(record: {
+    commands?: WorkThreadCommand[];
+}, command: WorkThreadCommand): {
+    command: WorkThreadCommand;
+    duplicate: boolean;
+};
+/** 按 createdAt + commandId 稳定排序的 pending 指令。 */
+declare function pendingCommands(record: {
+    commands?: WorkThreadCommand[];
+}): WorkThreadCommand[];
+declare function findCommand(record: {
+    commands?: WorkThreadCommand[];
+}, commandId: string): WorkThreadCommand | null;
+/**
+ * 裁剪终态指令，保留最近 maxRetained 条。pending 永不裁剪。
+ * @returns 是否有被裁掉的（内容变更）
+ */
+declare function pruneCommands(record: {
+    commands?: WorkThreadCommand[];
+}, maxRetained?: number): boolean;
 
 /**
  * WorkThreadStore — WorkThread 锚点层持久化存储
@@ -6398,6 +6600,19 @@ declare class WorkThreadStore {
         record: WorkThreadRecord;
         changed: boolean;
     }>;
+    /**
+     * 删除线程记录文件与 index 条目（破坏性生命周期操作的存储原语）。
+     *
+     * 幂等：记录不存在时返回 { removed: false, alreadyAbsent: true }——
+     * 已删除对象视为删除成功，供宿主的级联删除重试收敛。
+     * 走与 create / update 相同的 per-thread 串行锁；index 条目移除走
+     * _indexLock 串行链（与 updateIndexEntry 同链，并发创建 / 更新其它
+     * 线程时双方的 index 快照不会互相覆盖丢失对方的条目）。
+     */
+    remove(threadId: string): Promise<{
+        removed: boolean;
+        alreadyAbsent: boolean;
+    }>;
 }
 
 interface WorkThreadBridgeSubmitTurnParams {
@@ -6406,6 +6621,7 @@ interface WorkThreadBridgeSubmitTurnParams {
     source: string;
     sourceRef: string;
     capabilityActivations?: string[];
+    images?: string[];
 }
 interface WorkThreadDeliveryOutcome {
     accepted: boolean;
@@ -6449,6 +6665,7 @@ declare class WorkThreadRuntimeBridge implements WorkThreadBridge {
             commandId?: string;
             text?: string;
             capabilityActivations?: string[];
+            images?: string[];
         };
     }): Promise<WorkThreadDeliveryOutcome>;
 }
@@ -6496,12 +6713,28 @@ interface WorkThreadOptions {
      * index）。框架不内置产品身份词汇：返回值即线程归属；空值 = 身份未知。
      */
     identitySource?: (agentId: string, sessionId: string) => Promise<string | null> | string | null;
+    /**
+     * R3：接续恢复指令策略。官方默认为静态文案；宿主可注入替换。
+     * 策略必须是纯同步文本生成——恢复路径禁止叠加 LLM 调用等易碎件。
+     */
+    continuationPolicy?: WorkThreadContinuationPolicy;
+}
+/** 交接移交易上下文（beginSessionHandoff 播种恢复指令时传入策略）。 */
+interface WorkThreadSuccessionContext {
+    threadId: string;
+    fromSessionId: string;
+    reason: string;
+}
+/** R3：接续恢复指令策略接口。compose 必须同步、纯函数。 */
+interface WorkThreadContinuationPolicy {
+    composeSuccessionInstruction(ctx: WorkThreadSuccessionContext): string;
 }
 declare class WorkThread {
     readonly store: WorkThreadStore;
     private readonly _bridge;
     private readonly _identitySource?;
-    constructor({ store, bridge, identitySource }: WorkThreadOptions);
+    private readonly _continuationPolicy;
+    constructor({ store, bridge, identitySource, continuationPolicy }: WorkThreadOptions);
     listThreads(opts?: {
         agentId?: string;
     }): Promise<unknown[]>;
@@ -6534,8 +6767,16 @@ declare class WorkThread {
      */
     isHandoffActive(record: WorkThreadRecord): boolean;
     /**
-     * 标记线程进入交接：写入 pendingSuccession（幂等，重复调用刷新时间戳）。
-     * 同步置 status=rotating（接续编排状态归锚点层）。
+     * 标记线程进入交接：原子写入 pendingSuccession + status=rotating，并在同
+     * 一笔事务内播种接续恢复指令（R3：createdAt 与挡板同拍，早于一切交接期
+     * 积压；幂等键绑移交易 (threadId, fromSessionId)，失败恢复重走不会重复）。
+     *
+     * 门禁（按序）：
+     *   - closed → thread_closed（硬终态）
+     *   - hold → thread_held（归档/行政冻结期不开新交接，K9）
+     *   - 已有 fresh 交接在办 → handoff_in_progress（并发竞争显式拒绝而非
+     *     幂等刷新续命，R8 跨入口 single-flight 锚点；stale 残卷可覆写重开）
+     *   - fromSessionId ≠ 当前 head → head_mismatch
      */
     beginSessionHandoff(opts: {
         threadId: string;
@@ -6549,6 +6790,12 @@ declare class WorkThread {
     /**
      * 标记交接失败为接续编排状态 rotation_failed，不折叠成通用执行失败。
      * pendingSuccession 保留在盘上，供后续 resume 检查被打断的确切 stage。
+     *
+     * K3 守卫（事务内）：失败记录的资格来自「在办移交」本身——
+     *   - closed 线程：硬终态，任何迟到失败不得覆写（返回原记录，零写入）；
+     *   - 无 pendingSuccession（移交已成功推进 / 从未开始）：迟到的失败者
+     *     没有立卷资格，no-op 返回。这两条共同保证：只有「挡板仍在」的在办
+     *     移交失败才会落 rotation_failed。
      */
     failSessionHandoff(threadId: string, opts?: {
         reason?: string;
@@ -6566,6 +6813,7 @@ declare class WorkThread {
         source?: string;
         idempotencyKey?: string;
         capabilityActivations?: string[];
+        images?: string[];
     }): Promise<{
         command: WorkThreadCommand;
         duplicate: boolean;
@@ -6605,6 +6853,10 @@ declare class WorkThread {
     /**
      * 推进线程 head：headSessionId: fromSessionId → toSessionId。
      *
+     * fromSessionId 必填（K23）：它是调用方声明的 CAS 期望值——不传即
+     * 「接受任意当前 head」，幽灵任务防串台将被合法绕过。调用方若不知道
+     * 当前 head，应先读线程再用读到的值调用（CLI 的自动填充即此语义）。
+     *
      * 关键不变量（与 store 原子写共同保证）：任一时刻线程要么明确指向旧 head，
      * 要么明确指向新 head；推进与指令状态 / 清挡板在同一次落盘中变更。
      *
@@ -6622,7 +6874,7 @@ declare class WorkThread {
     advanceHead(opts: {
         threadId: string;
         toSessionId: string;
-        fromSessionId?: string;
+        fromSessionId: string;
         expectedRevision?: number;
         endKind?: string;
     }): Promise<WorkThreadRecord>;
@@ -6828,4 +7080,4 @@ interface PreflightResult {
 }
 declare function preflightAssembly(features: AgentFeature[]): PreflightResult;
 
-export { ANTHROPIC_THINKING_EFFORTS, type APIErrorType, AgentBase as Agent, type AgentConfig, type AgentConfigFile, type AgentDestroyHook, type AgentFeature, type AgentInfo, type AgentInitiateContext, type AgentInitiateHook, type AgentLogsResponse, type AgentOverviewSnapshot, AgentPool, type AgentRuntimeSnapshot, type AgentRuntimeStateSnapshot, type AgentSession, type AgentSessionSnapshot, type AgentdevContinuityDescriptor, BasicAgent, type BasicAgentConfig, CONTINUITY_FIELD_KEY, type CacheStats, type CallContinuationRequest, type CallFinishContext, type CallFinishHook, type CallFinishReason, type CallOutcome, type CallRollbackSnapshot, type CallRollbackSnapshotV2, type CallStartContext, type CallStartHook, type CallUsageSummary, type CapabilityContext, type CapabilityDefinition, type CapabilityEntryPoint, type CapabilityInvokeResult, CapabilityRegistry, type CapabilitySnapshot, type CheckpointContinuationRequest, ClassifiedAPIError, type ConfigProvenanceEntry, type ConfigWarning, type ConnectionErrorDetails, Context, type ContextBoundaryV2, type ContextInjector, type ContextMiddleware, type ContextSnapshot, type ContextTombstoneEntry, type ContextTombstoneSummary, CoreLifecycle, type CustomHeaderEntry, DEFAULT_EXPORT_POLICY, DEFAULT_FIELD_LIMIT, DEFAULT_HARD_LIMIT, DEFAULT_MAX_RETRIES, DEFAULT_MODEL_MAX_RETRIES, DEFAULT_MODEL_TIMEOUT_MS, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, type DebugHubIPCMessage, type DebugLogEntry, Decision, type DecisionResult, type EnrichedMessage, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, type ExecutionError, type ExecutionReason, type ExecutionStatus, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureCheckpoint, type FeatureConfig, type FeatureContext, type FeatureInitContext, type FeatureManifestDefinition, type FeatureManifestSettingProperty, type FeatureStateSnapshot, FileHistoryFeature, type FileHistoryFeatureConfig, FileSessionStore, GENERIC_CONTINUITY_PROTOCOL, type GuardRole, HANDOFF_COMPILER_VERSION, HANDOFF_SCHEMA_VERSION, HandoffSeedFeature, type HandoffSeedFeatureConfig, type HandoffSeedMessage, type HandoffSeedPayload, type HandoffSeedSnapshot, type HookDeclaration, type HookDeclarationIssue, type HookDeclarationIssueCode, type HookDeclarations, type HookInspectorSnapshot, type HookKind, type HookResult, HooksRegistry, type ImageInput, type IncrementalCallRollbackSnapshot, type InlineRenderTemplate, type InputLease, type InputRequestCancelledMsg, type LLMChatOptions, type LLMClient, type LLMMeta, type LLMPhase, type LLMResponse, type LLMRetryData, type LegacyCallRollbackSnapshot, type Logger, type LoggerBindings, LspFeature, type LspFeatureConfig, type MCPConfig, type MCPHTTPConfig, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPToolMappingConfig, type MCPTransportType, type Message, type MessageExecutionMeta, type MessageRole, type MessageTag, type MessageUsage, type ModelConfig, type ModelRequestOutcome, type NamedCheckpoint, type Notification, OPENAI_THINKING_EFFORTS, OPENCODE_BASIC_CONTINUITY_PROTOCOL, OpencodeBasicFeature, type OutputGuardConfig, OutputGuardFeature, type PackageInfo, type ParsedContent, type PlaceholderContext, PlaceholderResolver, type PreflightAssembly, type PreflightCheck, type PreflightIssue, type PreflightResult, type QueuedInput, RENDER_TEMPLATES, type RenderTemplate, type RequestInputMsg, type ResolvedFeatureConfig, type RollbackContinuationRequest, type RuntimeStage, type RuntimeStateWithoutContext, SYSTEM_RENDER_MAP, type ScanFilesAndSkillsResult, type SessionContinuityEntry, type SessionEvent, type SessionEventListener, type SessionItem, type SessionSeedMessage, type SessionStore, type SessionTransformation, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, type SnapshotInfo, type StepFinishDecisionContext, type StepFinishHook, type StepFinishedContext, type StepStartContext, type StepStartHook, SubAgentFeature, type SuccessorSeed, type SummaryExportPolicy, type SummaryPromptOptions, SummaryTransformation, type SummaryTransformationOptions, type SystemContext$1 as SystemContext, TOOL_DISPLAY_NAMES, type TaskStatus, TemplateComposer, TemplateError, TemplateLoader, type TemplateLoaderOptions, type TemplateResult, type TemplateSource, type ThinkingBlock, type ThinkingEffort, TodoFeature, type TodoFeatureConfig, type TodoPlanSnapshot, type TodoTask, type TodoTaskSnapshot, type TodoTaskSummary, type Tool, type ToolCall, type ToolContext, type ToolContextValue, type ToolExecResult, type ToolExecutionContext, type ToolFinishedDecisionContext, type ToolFinishedHook, type ToolMetadata, type ToolProgressData, ToolRegistry, type ToolRenderConfig, type ToolResult, type ToolResultTransformContext, type ToolResultTransformHook, type ToolResultValue, type ToolTerminationReason, type ToolUseHook, type TransformContext, type TransformInput, type TrimExportPolicy, type TrimStats, TrimTranscriptTransformation, type TrimTranscriptTransformationOptions, type TrimTranscriptWithSummaryOptions, TrimTranscriptWithSummaryTransformation, type TrimmedSeedResult, type TruncateOptions, type TruncateResult, type TurnFailure, type TurnUsage, type UsageInfo, UsageStats, type UsageStatsSnapshot, type UserInputAction, UserInputFeature, type UserInputFeatureConfig, type UserInputResponse, type UserTurnInput, type UserTurnSubmissionResult, type WithImagesResult, WorkThread, WorkThreadBoard, type WorkThreadBoardMode, type WorkThreadBoardState, type WorkThreadBoardStatus, type WorkThreadBridge, type WorkThreadChainEntry, type WorkThreadCommand, WorkThreadCommandKind, WorkThreadCommandStatus, type WorkThreadDeliveryOutcome, WorkThreadNotFoundError, type WorkThreadOptions, type WorkThreadPendingSuccession, type WorkThreadRecord, WorkThreadRevisionConflictError, WorkThreadRuntimeBridge, type WorkThreadStartOptions, type WorkThreadStatus, WorkThreadStore, applyTemplate, assistant, buildSummaryPrompt, buildSummarySeedMessage, buildTrimmedSeedMessages, classifyAPIError, classifyAndWrapError, createLLMCharCount, createLLMComplete, createLLMRetry, createListRenderer, createLogger, createMessage, createTool, createToolProgress, declareContinuity, discover, emitLog, emitNotification, emitSessionEvent, extractConnectionErrorDetails, extractErrorCode, generateSummaryText, generateWorkThreadId, getClawRuntimeUrl, getDebugCapabilities, getDefaultSessionStore, getDefaultUDSPath, getPackageInfoFromSource, getRetryDelay, getToolDisplayName, getToolRenderConfig, getToolRenderTemplate, getUserFriendlyMessage, installConsoleBridge, interpolateTemplate, isWithImagesResult, listConfigs, loadConfig, loadConfigSync, loadRenderTemplate, normalizeDecision, normalizeExportPolicy, normalizeSummaryPolicy, parseRetryAfter, preflightAssembly, readContinuityDescriptor, readHookDeclarations, resolveDebugTransportMode, resolveFeatureConfig, resolveModelCallPolicy, runWithLogScope, scanFilesAndSkills, shouldRetry, shrinkArray, sleep, splitFrontmatter, stripCompactAnalysis, stripContinuityField, subscribeSessionEvents, system, toolResult, truncateByLines, truncateHeadTail, truncateJsonNode, truncateOutput, tryJsonTruncate, user, validateHookDeclarations, validatePolicyUniqueness, withDeadline, withImages };
+export { ANTHROPIC_THINKING_EFFORTS, type APIErrorType, AgentBase as Agent, type AgentConfig, type AgentConfigFile, type AgentDestroyHook, type AgentFeature, type AgentInfo, type AgentInitiateContext, type AgentInitiateHook, type AgentLogsResponse, type AgentOverviewSnapshot, AgentPool, type AgentRuntimeSnapshot, type AgentRuntimeStateSnapshot, type AgentSession, type AgentSessionSnapshot, type AgentdevContinuityDescriptor, BasicAgent, type BasicAgentConfig, CONTINUITY_FIELD_KEY, type CacheStats, type CallContinuationRequest, type CallFinishContext, type CallFinishHook, type CallFinishReason, type CallOutcome, type CallRollbackSnapshot, type CallRollbackSnapshotV2, type CallStartContext, type CallStartHook, type CallUsageSummary, type CapabilityContext, type CapabilityDefinition, type CapabilityEntryPoint, type CapabilityInvokeResult, CapabilityRegistry, type CapabilitySnapshot, type CheckpointContinuationRequest, ClassifiedAPIError, type ConfigProvenanceEntry, type ConfigWarning, type ConnectionErrorDetails, Context, type ContextBoundaryV2, type ContextInjector, type ContextMiddleware, type ContextSnapshot, type ContextTombstoneEntry, type ContextTombstoneSummary, CoreLifecycle, type CustomHeaderEntry, DEFAULT_EXPORT_POLICY, DEFAULT_FIELD_LIMIT, DEFAULT_HARD_LIMIT, DEFAULT_MAX_RETRIES, DEFAULT_MODEL_MAX_RETRIES, DEFAULT_MODEL_TIMEOUT_MS, DataSourceRegistry, type DataSourceRenderer, type DebugCapabilities, DebugHub, type DebugHubIPCMessage, type DebugLogEntry, Decision, type DecisionResult, type EnrichedMessage, ExampleFeature, type ExampleFeatureConfig, type ExampleFeatureRuntimeState, type ExampleFeatureSnapshot, type ExecutionError, type ExecutionReason, type ExecutionStatus, ExplorerAgent, type ExplorerAgentConfig, type SystemContext as ExplorerSystemContext, type FeatureCheckpoint, type FeatureConfig, type FeatureContext, type FeatureInitContext, type FeatureManifestDefinition, type FeatureManifestSettingProperty, type FeatureStateSnapshot, FileHistoryFeature, type FileHistoryFeatureConfig, FileSessionStore, GENERIC_CONTINUITY_PROTOCOL, type GuardRole, HANDOFF_COMPILER_VERSION, HANDOFF_SCHEMA_VERSION, HandoffSeedFeature, type HandoffSeedFeatureConfig, type HandoffSeedMessage, type HandoffSeedPayload, type HandoffSeedSnapshot, type HookDeclaration, type HookDeclarationIssue, type HookDeclarationIssueCode, type HookDeclarations, type HookInspectorSnapshot, type HookKind, type HookResult, HooksRegistry, type ImageInput, type IncrementalCallRollbackSnapshot, type InlineRenderTemplate, type InputLease, type InputRequestCancelledMsg, type LLMChatOptions, type LLMClient, type LLMMeta, type LLMPhase, type LLMResponse, type LLMRetryData, type LegacyCallRollbackSnapshot, type Logger, type LoggerBindings, LspFeature, type LspFeatureConfig, MAX_RETAINED_TERMINAL_COMMANDS, type MCPConfig, type MCPHTTPConfig, type MCPSSEConfig, type MCPServerConfig, type MCPSstdioConfig, type MCPToolMappingConfig, type MCPTransportType, type Message, type MessageExecutionMeta, type MessageRole, type MessageTag, type MessageUsage, type ModelConfig, type ModelPresetResolver, type ModelRequestOutcome, type NamedCheckpoint, type Notification, OPENAI_THINKING_EFFORTS, OPENCODE_BASIC_CONTINUITY_PROTOCOL, OpencodeBasicFeature, type OutputGuardConfig, OutputGuardFeature, type PackageInfo, type ParsedContent, type PlaceholderContext, PlaceholderResolver, type PreflightAssembly, type PreflightCheck, type PreflightIssue, type PreflightResult, type QueuedInput, RENDER_TEMPLATES, type RenderTemplate, type RequestInputMsg, type ResolvedFeatureConfig, type ResolvedModelPreset, type RollbackContinuationRequest, type RuntimeStage, type RuntimeStateWithoutContext, SYSTEM_RENDER_MAP, type ScanFilesAndSkillsResult, type SessionContinuityEntry, type SessionEvent, type SessionEventListener, type SessionItem, type SessionSeedMessage, type SessionStore, type SessionTransformation, SkillFeature, type SkillFeatureConfig, type SkillMetadata, type SkillsOptions, type SnapshotInfo, type StepFinishDecisionContext, type StepFinishHook, type StepFinishedContext, type StepStartContext, type StepStartHook, SubAgentFeature, type SuccessorSeed, type SummaryExportPolicy, type SummaryPromptOptions, SummaryTransformation, type SummaryTransformationOptions, type SystemContext$1 as SystemContext, TOOL_DISPLAY_NAMES, type TaskStatus, TemplateComposer, TemplateError, TemplateLoader, type TemplateLoaderOptions, type TemplateResult, type TemplateSource, type ThinkingBlock, type ThinkingEffort, TodoFeature, type TodoFeatureConfig, type TodoPlanSnapshot, type TodoTask, type TodoTaskSnapshot, type TodoTaskSummary, type Tool, type ToolCall, type ToolContext, type ToolContextValue, type ToolExecResult, type ToolExecutionContext, type ToolFinishedDecisionContext, type ToolFinishedHook, type ToolMetadata, type ToolProgressData, ToolRegistry, type ToolRenderConfig, type ToolResult, type ToolResultTransformContext, type ToolResultTransformHook, type ToolResultValue, type ToolTerminationReason, type ToolUseHook, type TransformContext, type TransformInput, type TrimExportPolicy, type TrimStats, TrimTranscriptTransformation, type TrimTranscriptTransformationOptions, type TrimTranscriptWithSummaryOptions, TrimTranscriptWithSummaryTransformation, type TrimmedSeedResult, type TruncateOptions, type TruncateResult, type TurnFailure, type TurnUsage, type UsageInfo, UsageStats, type UsageStatsSnapshot, type UserInputAction, UserInputFeature, type UserInputFeatureConfig, type UserInputResponse, type UserTurnInput, type UserTurnSubmissionResult, type WithImagesResult, WorkThread, WorkThreadBoard, type WorkThreadBoardMode, type WorkThreadBoardState, type WorkThreadBoardStatus, type WorkThreadBridge, type WorkThreadChainEntry, type WorkThreadCommand, WorkThreadCommandKind, WorkThreadCommandStatus, type WorkThreadDeliveryOutcome, WorkThreadNotFoundError, type WorkThreadOptions, type WorkThreadPendingSuccession, type WorkThreadRecord, WorkThreadRevisionConflictError, WorkThreadRuntimeBridge, type WorkThreadStartOptions, type WorkThreadStatus, WorkThreadStore, appendCommand, applyTemplate, assistant, buildSummaryPrompt, buildSummarySeedMessage, buildTrimmedSeedMessages, classifyAPIError, classifyAndWrapError, createCommandRecord, createLLMCharCount, createLLMComplete, createLLMRetry, createListRenderer, createLogger, createMessage, createTool, createToolProgress, declareContinuity, discover, emitLog, emitNotification, emitSessionEvent, extractConnectionErrorDetails, extractErrorCode, findCommand, generateCommandId, generateSummaryText, generateWorkThreadId, getClawRuntimeUrl, getDebugCapabilities, getDefaultSessionStore, getDefaultUDSPath, getPackageInfoFromSource, getRetryDelay, getToolDisplayName, getToolRenderConfig, getToolRenderTemplate, getUserFriendlyMessage, installConsoleBridge, interpolateTemplate, isWithImagesResult, listConfigs, loadConfig, loadConfigSync, loadRenderTemplate, normalizeDecision, normalizeExportPolicy, normalizeSummaryPolicy, parseRetryAfter, pendingCommands, preflightAssembly, pruneCommands, readContinuityDescriptor, readHookDeclarations, resolveDebugTransportMode, resolveFeatureConfig, resolveModelCallPolicy, runWithLogScope, scanFilesAndSkills, shouldRetry, shrinkArray, sleep, splitFrontmatter, stripCompactAnalysis, stripContinuityField, subscribeSessionEvents, system, toolResult, truncateByLines, truncateHeadTail, truncateJsonNode, truncateOutput, tryJsonTruncate, user, validateHookDeclarations, validatePolicyUniqueness, withDeadline, withImages };