@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/node/tools/tool-search-service.d.ts

@@ -0,0 +1,137 @@
+import { Emitter, Event, Logger } from '@celljs/core';
+import { type Session } from '../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '@openai/agents';
+import { AgentScopedMcpManager } from '../mcp/mcp-protocol';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+import { DeferToolConfigService } from './defer-tool-config-protocol';
+import type { ToolInputParameters } from './tool-protocol';
+import { DeferredToolInfo, DeferredToolsFilterOptions, DeferredToolSummary, ToolSearchOptions, ToolSearchResult, ToolSearchService } from './tool-search-protocol';
+import type { ToolDeferOverlay } from './tool-spec';
+/**
+ * ToolSearchService implementation using MiniSearch.
+ *
+ * MiniSearch provides:
+ * - BM25 ranking algorithm (industry standard, better than TF-IDF)
+ * - Prefix search support
+ * - Zero dependencies
+ *
+ * @see https://github.com/lucaong/minisearch
+ */
+export declare class ToolSearchServiceImpl implements ToolSearchService {
+    private static readonly DEFAULT_TOP_K;
+    private static readonly SEARCH_OPTIONS;
+    /** A2 相关性下限（Issue #113176）：相对最高分的默认比例；ABS_MIN 为绝对兜底（0 = 不启用）。 */
+    private static readonly DEFAULT_MIN_SCORE_RATIO;
+    private static readonly ABS_MIN_SCORE;
+    protected readonly logger: Logger;
+    protected readonly prewarmState?: IPrewarmStateService;
+    protected readonly agentScopedMcpManager: AgentScopedMcpManager;
+    protected readonly deferToolConfigService: DeferToolConfigService;
+    private miniSearch;
+    private deferredTools;
+    /**
+     * agents-core normalizes model-visible function names. Keep an exact,
+     * fail-closed mapping back to the canonical indexed name; `null` denotes
+     * a lossy collision between two canonical names.
+     */
+    private normalizedToolAliases;
+    private toolVisibilityChecks;
+    /**
+     * Per-tool `isEnabled` checks captured at index time, consumed by
+     * {@link filterEnabledDeferredTools}. Only builtin deferred tools register a
+     * check; MCP tools are absent here and therefore always kept.
+     */
+    private toolEnabledChecks;
+    private initialized;
+    private indexInitialized;
+    private activationScheduled;
+    private scopedToolsSubscription?;
+    /**
+     * Fires after any mutation to the deferred-tool index. See
+     * {@link ToolSearchService.onDidChangeIndex} for why consumers need it.
+     */
+    protected readonly onDidChangeIndexEmitter: Emitter<void>;
+    get onDidChangeIndex(): Event<void>;
+    /**
+     * Monotonic counter bumped on every index mutation. Consumers that bake a
+     * snapshot of the index into a longer-lived structure (e.g. the ToolSearch
+     * description frozen into an Agent's tool array at buildTools time) stamp the
+     * epoch they built against, then compare later to detect a stale snapshot.
+     *
+     * `onDidChangeIndex` alone is not enough for those consumers: it only lets
+     * them invalidate a *cache*, but an already-frozen Agent instance is not
+     * rebuilt by a cache invalidation. The run path uses this epoch to decide
+     * whether the resolved agent must be refreshed before the first run.
+     */
+    private _indexEpoch;
+    get indexEpoch(): number;
+    /** Bump the epoch and notify subscribers. Single choke point for both. */
+    protected fireIndexChanged(): void;
+    /**
+     * 共享 MiniSearch 配置工厂：init() 与 createSearchIndex() 必须共用，否则进程级全局索引
+     * 与 session-scoped 临时索引的分词口径不一致，混合查询会漏召回（方案约束1）。
+     * A1 的 camelCase 拆词在此单点接入。
+     */
+    private static buildMiniSearchOptions;
+    protected init(): void;
+    protected dispose(): void;
+    initialize(): Promise<void>;
+    isReady(): boolean;
+    private ensureIndexInitialized;
+    indexTool(tool: {
+        name: string;
+        description: string;
+        summary: string;
+        parameters: ToolInputParameters;
+        defer_loading?: boolean;
+        shouldShow?(): boolean;
+        isEnabled?(): boolean | Promise<boolean>;
+        isBare?: boolean;
+        serverName?: string;
+        rawToolName?: string;
+        annotations?: Record<string, unknown>;
+        sensitiveResultPolicy?: string;
+    }): Promise<void>;
+    search(query: string | string[], topK?: number, options?: ToolSearchOptions): Promise<ToolSearchResult[]>;
+    isHiddenByOverlay(toolName: string, overlay: ToolDeferOverlay | undefined): boolean;
+    describe(toolName: string): DeferredToolInfo | undefined;
+    resolveModelToolName(modelVisibleName: string): string | undefined;
+    describeForSession(toolName: string, session?: Session, overlay?: ToolDeferOverlay): Promise<DeferredToolInfo | undefined>;
+    isBareTool(toolName: string): boolean;
+    getDeferredToolsSummary(options?: DeferredToolsFilterOptions): DeferredToolSummary[];
+    listDeferredToolInfos(options?: DeferredToolsFilterOptions): DeferredToolInfo[];
+    listDeferredToolInfosForSession(session?: Session, options?: DeferredToolsFilterOptions): Promise<DeferredToolInfo[]>;
+    filterEnabledDeferredTools(summaries: DeferredToolSummary[]): Promise<DeferredToolSummary[]>;
+    clearIndex(): void;
+    removeToolsByServer(serverName: string): void;
+    replaceServerTools(serverName: string, tools: DeferredToolInfo[]): void;
+    private collectToolNamesForServer;
+    private discardFromSearchIndex;
+    getAllowedToolsForAgent(agentName: string | undefined, context: RunContext<Session>): Promise<string[] | undefined>;
+    private getAgentAllowedTools;
+    private collectEnabledToolNames;
+    private getSessionAllowedTools;
+    private isToolVisible;
+    private resolveGlobalToolInfo;
+    private resolveToolInfo;
+    private rebuildNormalizedToolAliases;
+    private getVisibleTools;
+    private loadScopedTools;
+    private toDeferredToolInfo;
+    private createSearchIndex;
+    /**
+     * MCP deferred tools are not listed in agent.tools. Prefix and bare-name MCP
+     * entries both bypass agent whitelist filtering; builtin deferred tools must
+     * still be explicitly enabled for the agent.
+     */
+    private isAllowedByAgentTools;
+    private doSearch;
+    /**
+     * A2 相关性下限：丢弃分数低于 `top1 * ratio` 或绝对下限的结果。
+     * `results` 必须已按分数降序（doSearch 输出即降序，后续 filter 保持顺序）。
+     * `ratio <= 0` 时完全跳过（含绝对下限），供 lookup 模糊兜底"总给最接近的一个"。
+     */
+    private applyRelevanceFloor;
+    /** 运行时解析 env 相对阈值；非法或缺省回落到 {@link DEFAULT_MIN_SCORE_RATIO}。 */
+    private resolveMinScoreRatio;
+}

package/cli/dist-server/types/node/tools/tool-search-tool.d.ts

@@ -0,0 +1,103 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { BaseTool } from './base-tool';
+import { DeferToolConfigService } from './defer-tool-config-protocol';
+import { Tool, ToolCallArgumentRenderer, ToolManager, ToolResult } from './tool-protocol';
+import { ToolSearchService } from './tool-search-protocol';
+import { AgentToolDeferOverlayCache } from './tool-spec';
+/**
+ * Parameters for the tool_search tool
+ */
+declare const ToolSearchParameters: z.ZodObject<{
+    queries: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
+    tool_names: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
+    top_k: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    top_k: number;
+    queries?: string[] | undefined;
+    tool_names?: string[] | undefined;
+}, {
+    queries?: unknown;
+    tool_names?: unknown;
+    top_k?: number | undefined;
+}>;
+/**
+ * Tool for searching deferred tools and returning their metadata (name, description, parameter schema).
+ *
+ * Supports two operations via separate parameters:
+ * - "queries": Search by keywords, return top_k results with full details, show remaining as candidates.
+ * - "tool_names": Look up tools by exact name(s), with fuzzy search fallback.
+ *
+ * Tools found by ToolSearch are NOT injected into the LLM tools list.
+ * Instead, the model should use DeferExecuteTool to invoke them, passing the
+ * tool name and parameters learned from the schema returned here.
+ */
+export declare class ToolSearchTool extends BaseTool implements Tool {
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly deferToolConfigService: DeferToolConfigService;
+    protected readonly toolManager: ToolManager;
+    protected readonly agentToolDeferOverlayCache: AgentToolDeferOverlayCache;
+    name: ToolNames;
+    readonly promptCacheStability: "volatile";
+    isEnabled: () => Promise<boolean>;
+    parameters: z.ZodObject<{
+        queries: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
+        tool_names: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
+        top_k: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        top_k: number;
+        queries?: string[] | undefined;
+        tool_names?: string[] | undefined;
+    }, {
+        queries?: unknown;
+        tool_names?: unknown;
+        top_k?: number | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    /**
+     * Tool search does not need user approval
+     */
+    needsApproval: boolean;
+    execute(input: z.infer<typeof ToolSearchParameters>, context: RunContext<Session>): Promise<ToolResult>;
+    /**
+     * Search mode: search by keywords, return top_k with full schema, show remaining as candidates.
+     */
+    private executeSearchMode;
+    /**
+     * Lookup mode: look up tools by exact name(s).
+     * Falls back to search(name, 1) when exact match is not found.
+     */
+    private executeLookupMode;
+    /**
+     * Format search mode results with primary tools (including schema) and optional candidates.
+     */
+    private formatSearchResults;
+    /**
+     * Format lookup mode results with full tool info.
+     */
+    private formatLookupResults;
+    /**
+     * 会话级 `Defer(...)` 命中的内置工具如果未被 product 索引，先懒索引一次。
+     *
+     * - tool_names 模式：只索引用户显式问到的那些（避免 queries 模式无谓全扫）
+     * - queries 模式：把 overlay.forceDefer 精确条目全量索引
+     *
+     * 通配条目（`Defer(mcp__*)`）不在此处理：
+     *   1) MCP 工具的索引由 mcp-manager 异步驱动；
+     *   2) 通配反向枚举不出具体工具名。
+     */
+    private ensureForceDeferIndexed;
+    /**
+     * Resolve max output chars from environment variable, falling back to default.
+     * Read at truncation time so prewarm activation sees the current session env.
+     */
+    private resolveMaxOutputChars;
+    /**
+     * Truncate output string to maxOutputChars limit.
+     * Appends a truncation notice when content exceeds the limit.
+     */
+    private truncateOutput;
+}
+export {};

package/cli/dist-server/types/node/tools/tool-spec/agent-tool-defer-overlay-cache.d.ts

@@ -0,0 +1,45 @@
+import { ToolDeferOverlaySnapshot } from '../../../vendor/cbc-shared/node/index.js';
+export declare const AgentToolDeferOverlayCache: unique symbol;
+/**
+ * Agent 级 defer overlay 缓存（进程级单例）。
+ *
+ * 当 agent 的 `tools` 配置（来自 product.json `agents[].tools` 或 custom agent
+ * frontmatter `tools:`）中包含 `Defer(...)` / `NoDefer(...)` 修饰时，
+ * agent-manager 在第一次构建该 agent 工具集时把解析得到的 overlay snapshot
+ * 写入这里，后续所有消费点（filterTools / ToolSearch / DeferExecuteTool / 等）
+ * 通过 `get(agentName)` 拿到，再与 session-level overlay 合并。
+ *
+ * 缓存归属随声明来源决定：
+ *   - 普通 CLI 的 agent.tools 来自进程 Product 配置，沿用进程级缓存；
+ *   - 解析一次复用即可，避免每次工具检查重新走 parseToolSpecs。
+ *   - 显式注入 query Product 时按该快照隔离，同名 agent 不共享 overlay。
+ *   - 未显式传入 Product 的 Server 插件组合按会话隔离，模式切换时重建。
+ *
+ * 之所以是「独立 service」而非「ToolManager 内嵌」：
+ *   - 关注点单一（agent overlay cache vs 工具 registry），方便后续扩展；
+ *   - 消费点 4 处，单独 @Autowired 比污染 ToolManager 接口更干净。
+ */
+export interface AgentToolDeferOverlayCache {
+    /**
+     * 读取指定 agent 的 overlay snapshot。
+     * 未注册的 agent / agentName 为 undefined 时返回 undefined（消费方应按 EMPTY 处理）。
+     */
+    get(agentName: string | undefined): ToolDeferOverlaySnapshot | undefined;
+    /**
+     * 注册或覆盖某 agent 的 overlay snapshot。
+     * agent-manager 在 buildTools 入口处调用一次。
+     */
+    set(agentName: string, snapshot: ToolDeferOverlaySnapshot): void;
+    /**
+     * 清空所有缓存（测试 / hot reload 场景）。
+     */
+    clear(): void;
+}
+export declare class AgentToolDeferOverlayCacheImpl implements AgentToolDeferOverlayCache {
+    private readonly processCache;
+    private readonly queryCaches;
+    private get cache();
+    get(agentName: string | undefined): ToolDeferOverlaySnapshot | undefined;
+    set(agentName: string, snapshot: ToolDeferOverlaySnapshot): void;
+    clear(): void;
+}

package/cli/dist-server/types/node/tools/tool-spec/index.d.ts

@@ -0,0 +1,6 @@
+export * from './tool-spec-protocol';
+export { canonicalizeToolListName } from './legacy-ide-tool-names';
+export { parseSingleToolSpec, parseToolSpecs } from './tool-spec-parser';
+export { augmentParsedSpecsForDefer } from './tool-spec-augment';
+export { ToolDeferOverlay } from './tool-defer-overlay';
+export { AgentToolDeferOverlayCache, AgentToolDeferOverlayCacheImpl, } from './agent-tool-defer-overlay-cache';

package/cli/dist-server/types/node/tools/tool-spec/legacy-ide-tool-names.d.ts

@@ -0,0 +1,2 @@
+/** 归一单个已剥离修饰符的纯工具名；查不到的原样返回。 */
+export declare function canonicalizeToolListName(pattern: string): string;

package/cli/dist-server/types/node/tools/tool-spec/tool-defer-overlay.d.ts

@@ -0,0 +1,70 @@
+import { ToolDeferOverlaySnapshot } from '../../../vendor/cbc-shared/node/index.js';
+/**
+ * 会话级 defer overlay 的查询封装。
+ *
+ * 由 ParsedToolSpecs.overlay 构造，挂在 SessionOptions 上，被
+ * DeferToolConfigService.isToolDeferLoadingWithOverlay /
+ * isBuiltinToolDeferLoading 在判定优先级最高的位置查询。
+ *
+ * 设计取舍：
+ *   - 通配只支持 `*`（与 ToolNames 中 mcp 工具的命名习惯一致），不引入完整
+ *     minimatch，避免依赖膨胀与 ReDoS 风险。
+ *   - 大小写敏感（与 ToolNames 枚举值的实际形态一致：内置工具大驼峰、MCP 工具
+ *     全小写带 __ 分隔）。
+ *   - NoDefer 优先于 Defer：用户显式 opt-out 是最强意图。
+ */
+export declare class ToolDeferOverlay {
+    /** 全空 overlay 的复用实例。会话默认值，避免空判分散到各调用方。 */
+    static readonly EMPTY: ToolDeferOverlay;
+    /**
+     * 从 SessionOptions.toolDeferOverlay 读出的 snapshot 构造实例。
+     * snapshot 为 undefined 时返回共享 EMPTY，避免每次都 new。
+     *
+     * SessionOptions 上故意只存 snapshot 而非 class 实例，因为 ACP / `--serve`
+     * 模式下 SessionOptions 会跨 JSON 边界，class 方法会丢失。所有消费方在
+     * 用 overlay 前必须经此入口。
+     */
+    static fromSnapshot(snapshot: ToolDeferOverlaySnapshot | undefined): ToolDeferOverlay;
+    /**
+     * 合并多层 overlay snapshot。典型用法：
+     *   merge(sessionOverlay, agentOverlay)
+     *
+     * 合并语义：
+     *   - forceNoDefer：取并集（任一层声明就生效；与 ToolDeferOverlay.decide
+     *     里 NoDefer 永远压过 Defer 的语义保持一致）
+     *   - forceDefer：取并集
+     *
+     * 由于 decide 自身已保证 NoDefer 优先，合并阶段无需再"减去 forceDefer"：
+     *   假设 agent 写 `Defer(X)`、session 写 `NoDefer(X)`，合并后两个桶都含 X，
+     *   decide('X') 仍正确返回 'force-no-defer'。
+     *
+     * 任何参数为 undefined 时按 EMPTY 处理。返回 EMPTY 是惰性的：所有输入都为
+     * 空时直接返回共享 EMPTY 实例，避免热路径上的内存分配。
+     */
+    static merge(...snapshots: Array<ToolDeferOverlaySnapshot | undefined>): ToolDeferOverlay;
+    private readonly forceDeferExact;
+    private readonly forceDeferGlob;
+    private readonly forceNoDeferExact;
+    private readonly forceNoDeferGlob;
+    constructor(snapshot: ToolDeferOverlaySnapshot);
+    isEmpty(): boolean;
+    matchesForceDefer(toolName: string): boolean;
+    matchesForceNoDefer(toolName: string): boolean;
+    /**
+     * 列出 overlay 中 *精确指名* 的 forceDefer 工具。通配条目（如 `mcp__*`）不在
+     * 此返回值里——通配匹配在运行时按工具名查询，无法反向枚举出具体工具集。
+     *
+     * 用途：ToolSearchTool / DeferExecuteTool 在 queries 模式下需要一次性懒索引
+     * 所有被 `Defer(...)` 强制为 defer 的内置工具，否则模型搜不到它们。
+     */
+    listForceDeferExact(): string[];
+    /**
+     * 一站式查询：返回 'force-defer' / 'force-no-defer' / undefined。
+     *
+     * NoDefer 命中优先（即使 Defer 也命中）。已被
+     * DeferToolConfigService.isToolDeferLoadingWithOverlay /
+     * isBuiltinToolDeferLoading 在最高优先级直接调用。
+     */
+    decide(toolName: string): 'force-defer' | 'force-no-defer' | undefined;
+    private match;
+}

package/cli/dist-server/types/node/tools/tool-spec/tool-spec-augment.d.ts

@@ -0,0 +1,17 @@
+import { ParsedToolSpecs } from './tool-spec-protocol';
+/**
+ * 当用户在「工具列表」字段里写了至少一条 `Defer(...)`，自动把 `ToolSearch` /
+ * `DeferExecuteTool` 补进 names（已存在则跳过）。
+ *
+ * 同时给这两个工具加 `forceNoDefer` 护栏：
+ *   用户可能写 `Defer(*)` 把所有工具一刀切收进延迟加载，没有护栏的话两个 defer
+ *   工作流工具自身也会被 defer 掉，模型连搜索能力都失去——`Defer(*)` 就完全失效了。
+ *   `forceNoDefer` 永远胜过 `forceDefer`，所以两个工具能稳定保留在 LLM 工具列表里。
+ *
+ * `NoDefer(...)` 不触发自动附加：它的语义是把工具拉回直接调用，跟 defer 工作流无关。
+ *
+ * 幂等：names 里已有的工具不重复添加；overlay forceNoDefer 同理用 Set 去重。
+ *
+ * 入参 `parsed` *不* 被修改，返回新对象。
+ */
+export declare function augmentParsedSpecsForDefer(parsed: ParsedToolSpecs): ParsedToolSpecs;

package/cli/dist-server/types/node/tools/tool-spec/tool-spec-parser.d.ts

@@ -0,0 +1,38 @@
+import { ParsedToolSpec, ParsedToolSpecs } from './tool-spec-protocol';
+/**
+ * 解析单条 spec 字符串。
+ *
+ * 接受语法：
+ *   - 纯工具名：       Read、mcp__github__create_pr
+ *   - 通配模式：       mcp__github__*、mcp__*、*
+ *   - Defer 修饰：     Defer(Read)、Defer(mcp__*)、Defer(*)
+ *   - NoDefer 修饰：   NoDefer(Bash)
+ *
+ * 拒绝语法（抛 ToolSpecParseError）：
+ *   - 嵌套权限过滤：   Defer(Read(*.md))
+ *   - 嵌套修饰：       Defer(NoDefer(X))
+ *   - 空内容：         ""、Defer()、"   "
+ *   - 误用权限语法：   Read(*.md) 提示去 --allowed-tools
+ *   - 含逗号：         "Read,Write" 上层应已 split
+ */
+export declare function parseSingleToolSpec(raw: string): ParsedToolSpec;
+/**
+ * 批量解析。
+ *
+ * 关键约定：
+ *   - 去重：同一 pattern 多次出现时，names 只保留首次出现的位置，发出
+ *     duplicate-spec warning。
+ *   - 冲突仲裁：同一 pattern 出现 Defer(...) 和 NoDefer(...) 时，以最后
+ *     一次出现的修饰符胜出（与 --allowedTools 的"后定义覆盖"语义一致），
+ *     发出 conflicting-modifier warning。同 pattern 多次重复同一修饰符
+ *     不算冲突，仅记 duplicate-spec。
+ *   - lenient 模式：{ lenient: true } 时，遇到 ToolSpecParseError 不抛错，
+ *     转为 invalid-pattern warning 并丢弃该 spec。供 product agents[].tools
+ *     等老配置在新版 CLI 上兼容降级。
+ *   - 旧名归一：pattern 抽出后先过 `canonicalizeToolListName`，4.x IDE 名收成
+ *     CLI 规范名。必须发生在去重 / overlay 之前，否则 `Defer(read_file)` 的
+ *     overlay 会记成 `read_file`，运行时按 `Read` 查 defer 就丢了修饰。
+ */
+export declare function parseToolSpecs(specs: readonly string[], options?: {
+    lenient?: boolean;
+}): ParsedToolSpecs;

package/cli/dist-server/types/node/tools/tool-spec/tool-spec-protocol.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Tool Spec 解析层契约。
+ *
+ * 「Tool Spec」是用户在 *工具列表* 字段里写的单条字符串，例如：
+ *   - `Read`                       // 普通工具
+ *   - `mcp__github__create_pr`     // MCP 工具
+ *   - `mcp__github__*`             // 通配
+ *   - `Defer(Glob)`                // 强制让 Glob 在该会话变成 defer 工具
+ *   - `NoDefer(Bash)`              // 强制让 Bash 在该会话变成非 defer 工具
+ *
+ * 该层 *只* 负责把一组字符串切分为
+ *   1) 纯工具名/通配数组（`names`），喂给现有可见性逻辑；
+ *   2) 会话级 defer overlay 快照（`overlay`），喂给 `DeferToolConfigService`。
+ *
+ * 它 *不* 做：
+ *   - 工具是否存在的校验（运行时再校验）；
+ *   - 权限语法（`Read(*.md)`）的解析（属于权限层）；
+ *   - 通配匹配本身（由 `ToolDeferOverlay` 封装）。
+ *
+ * 渠道边界：`Defer(...)` / `NoDefer(...)` *仅* 在工具列表字段（`--tools`、agent
+ * frontmatter `tools:`、product `agents[].tools`）有效。权限规则字段必须由权限层
+ * 自行拒绝这两个前缀，避免两套 DSL 互嵌。
+ */
+import type { ToolDeferOverlaySnapshot } from '../../../vendor/cbc-shared/node/index.js';
+/**
+ * Defer 修饰前缀。
+ */
+export type DeferModifier = 'Defer' | 'NoDefer';
+/**
+ * 单条 spec 解析结果。
+ */
+export interface ParsedToolSpec {
+    /** 工具名或通配模式（如 "Read"、"mcp__github__*"），已剥离修饰符。 */
+    pattern: string;
+    /** defer 修饰；undefined 表示该 spec 未指定修饰，由全局默认决定。 */
+    modifier?: DeferModifier;
+    /** 是否含通配（仅 `*` 视作通配元字符）。 */
+    isGlob: boolean;
+    /** 原始字符串，便于报错与审计定位。 */
+    raw: string;
+}
+/**
+ * defer overlay 的纯数据快照。`ToolDeferOverlay` 基于此构造可查询对象。
+ *
+ * 之所以拆 `exact` / `glob` 两桶：
+ *   - exact 用 Set，O(1) 查询；
+ *   - glob 走线性扫描 + 锚定 RegExp，数量通常 <10，开销可忽略。
+ */
+export type { ToolDeferOverlaySnapshot } from '../../../vendor/cbc-shared/node/index.js';
+/**
+ * 一组 spec 批量解析的产物。
+ */
+export interface ParsedToolSpecs {
+    /**
+     * 剥离 defer 修饰后的纯工具名/通配，按首次出现顺序去重。
+     * 直接喂给现有可见性 / 白名单 / 黑名单逻辑，不需要再感知 defer 修饰。
+     */
+    names: string[];
+    /** 会话级 defer overlay 快照。 */
+    overlay: ToolDeferOverlaySnapshot;
+    /** 解析过程中的非阻断警告（如重复条目、修饰符冲突）。 */
+    warnings: ToolSpecWarning[];
+}
+/**
+ * 非阻断警告。调用方按需上报到 telemetry / 控制台。
+ */
+export interface ToolSpecWarning {
+    code: 'duplicate-spec' | 'conflicting-modifier' | 'invalid-pattern';
+    message: string;
+    raw: string;
+}
+/**
+ * 解析期严重错误。
+ *
+ * 默认 `parseToolSpecs` 抛出此错误；调用方传 `{ lenient: true }` 时，错误会被
+ * 转换成 `invalid-pattern` warning 并丢弃当前 spec（用于兼容老版本 CLI 解析
+ * 含 `Defer(...)` 修饰的 product 配置）。
+ */
+export declare class ToolSpecParseError extends Error {
+    readonly raw: string;
+    readonly reason: string;
+    constructor(raw: string, reason: string);
+}

package/cli/dist-server/types/node/tools/video-gen-tool.d.ts

@@ -0,0 +1,88 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { Agent, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { BaseTool } from './base-tool';
+import { ImageService, Tool, ToolResult, VideoService } from './tool-protocol';
+/**
+ * 文生视频 + 图生视频参数 Schema
+ * image 或 last_image 任意一个存在时为图生视频，否则为文生视频
+ */
+declare const VideoGenParameters: z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    last_image: z.ZodOptional<z.ZodString>;
+    resolution: z.ZodOptional<z.ZodEnum<["480P", "720P", "1080P"]>>;
+    seconds: z.ZodOptional<z.ZodNumber>;
+    aspect_ratio: z.ZodOptional<z.ZodEnum<["16:9", "9:16", "1:1"]>>;
+    negative_prompt: z.ZodOptional<z.ZodString>;
+    enable_audio: z.ZodOptional<z.ZodBoolean>;
+    output_dir: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    image?: string | undefined;
+    prompt?: string | undefined;
+    output_dir?: string | undefined;
+    last_image?: string | undefined;
+    resolution?: "480P" | "720P" | "1080P" | undefined;
+    seconds?: number | undefined;
+    aspect_ratio?: "16:9" | "9:16" | "1:1" | undefined;
+    negative_prompt?: string | undefined;
+    enable_audio?: boolean | undefined;
+}, {
+    image?: string | undefined;
+    prompt?: string | undefined;
+    output_dir?: string | undefined;
+    last_image?: string | undefined;
+    resolution?: "480P" | "720P" | "1080P" | undefined;
+    seconds?: number | undefined;
+    aspect_ratio?: "16:9" | "9:16" | "1:1" | undefined;
+    negative_prompt?: string | undefined;
+    enable_audio?: boolean | undefined;
+}>;
+export declare class VideoGenTool extends BaseTool implements Tool {
+    protected readonly videoService: VideoService;
+    protected readonly imageService: ImageService;
+    protected readonly productManager: ProductManager;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        prompt: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        last_image: z.ZodOptional<z.ZodString>;
+        resolution: z.ZodOptional<z.ZodEnum<["480P", "720P", "1080P"]>>;
+        seconds: z.ZodOptional<z.ZodNumber>;
+        aspect_ratio: z.ZodOptional<z.ZodEnum<["16:9", "9:16", "1:1"]>>;
+        negative_prompt: z.ZodOptional<z.ZodString>;
+        enable_audio: z.ZodOptional<z.ZodBoolean>;
+        output_dir: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        image?: string | undefined;
+        prompt?: string | undefined;
+        output_dir?: string | undefined;
+        last_image?: string | undefined;
+        resolution?: "480P" | "720P" | "1080P" | undefined;
+        seconds?: number | undefined;
+        aspect_ratio?: "16:9" | "9:16" | "1:1" | undefined;
+        negative_prompt?: string | undefined;
+        enable_audio?: boolean | undefined;
+    }, {
+        image?: string | undefined;
+        prompt?: string | undefined;
+        output_dir?: string | undefined;
+        last_image?: string | undefined;
+        resolution?: "480P" | "720P" | "1080P" | undefined;
+        seconds?: number | undefined;
+        aspect_ratio?: "16:9" | "9:16" | "1:1" | undefined;
+        negative_prompt?: string | undefined;
+        enable_audio?: boolean | undefined;
+    }>;
+    isEnabled: (_args: {
+        runContext: RunContext<Session>;
+        agent: Agent;
+    }) => Promise<boolean>;
+    execute(input: z.infer<typeof VideoGenParameters>, context: RunContext<Session>): Promise<ToolResult>;
+}
+export {};

package/cli/dist-server/types/node/tools/video-service.d.ts

@@ -0,0 +1,57 @@
+import { RestOperations } from '@celljs/http';
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { LanguageModel, ProductConfiguration, ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { SettingsManager } from '../settings';
+import { type VideoGenerationResult, VideoGenParams, VideoService } from './tool-protocol';
+/**
+ * 视频服务实现
+ * 封装文生视频的任务提交、轮询、下载逻辑
+ */
+export declare class VideoServiceImpl implements VideoService {
+    protected readonly restOperations: RestOperations;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected readonly productManager: ProductManager;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    private outputDir;
+    /**
+     * 初始化视频输出目录
+     */
+    initializeOutputDir(customOutputDir?: string): Promise<void>;
+    /**
+     * 文生视频/图生视频：提交任务 + 轮询 + 下载到本地
+     */
+    generateVideo(params: VideoGenParams, context: RunContext<Session>): Promise<VideoGenerationResult>;
+    /**
+     * 提交视频生成任务
+     */
+    private submitTask;
+    /**
+     * 轮询任务状态直到完成或失败
+     */
+    private pollTask;
+    /**
+     * 下载视频结果到本地
+     */
+    private downloadVideos;
+    /**
+     * 准备请求所需的认证和配置信息
+     */
+    private prepareRequest;
+    /**
+     * 可中断的 sleep
+     */
+    private sleep;
+    /**
+     * 获取指定 tag 的模型列表
+     */
+    getModelsByTag(product: ProductConfiguration, tag: string): LanguageModel[];
+    /**
+     * 解析视频模型
+     * 优先级：session options > 环境变量 > 合并设置 > 配置中第一个对应 tag 的模型 > fallback
+     */
+    resolveModel(session: Session | undefined, tag: string): Promise<string>;
+}