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

package/cli/dist-server/types/node/tools/wait-for-mcp-servers-tool.d.ts

@@ -0,0 +1,79 @@
+import { Logger } from '@celljs/core';
+import { z } from 'zod';
+import { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import { McpManager } from '../mcp/mcp-protocol';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+declare const WaitForMcpServersParameters: z.ZodObject<{
+    servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    servers?: string[] | undefined;
+}, {
+    servers?: string[] | undefined;
+}>;
+type WaitForMcpServersInput = z.infer<typeof WaitForMcpServersParameters>;
+interface WaitForMcpServersOutput {
+    ready: boolean;
+    connected: string[];
+    failed: string[];
+    stillPending: string[];
+    needsAuth: string[];
+    disabled: string[];
+    unknown: string[];
+}
+/**
+ * WaitForMcpServers — wait for MCP servers that are still connecting.
+ *
+ * When a user's request needs tools from a still-connecting server, the LLM
+ * can call this tool to block until the server finishes connecting. Once
+ * connected, its tools are added to the tool list and can be used directly.
+ *
+ * Returns ready=true when all target servers are connected, ready=false if
+ * any failed to connect, need authentication, or are disabled.
+ */
+export declare class WaitForMcpServersTool extends BaseTool implements Tool {
+    protected readonly mcpManager: McpManager;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        servers?: string[] | undefined;
+    }, {
+        servers?: string[] | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    /** No approval needed — this is a read-only wait operation. */
+    needsApproval: boolean;
+    /**
+     * Enabled iff the feature is not explicitly disabled via env
+     * CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLED=0/false.
+     *
+     * Historically this also returned false when no MCP server was in
+     * CONNECTING state. That coupling caused a time-of-check race with the
+     * ToolSearch description: the description is rendered once per session
+     * with the "still connecting" hint baked in, but isEnabled() was
+     * re-evaluated on every LLM request — so a server that finished
+     * connecting between description-render and tool-list-fetch would leave
+     * the hint pointing at a tool the LLM no longer had access to.
+     *
+     * Always exposing the tool removes that drift: when no server is
+     * connecting, execute() returns ready=true immediately (cost ~1ms) and
+     * the tool description itself tells the LLM what it is for, so the
+     * model won't invoke it gratuitously.
+     *
+     * Default: enabled. WB sets this env var to '0' to disable.
+     */
+    isEnabled: () => Promise<boolean>;
+    execute(input: WaitForMcpServersInput, _context: RunContext<Session>): Promise<ToolResult>;
+    private getPendingServerNames;
+    private matchTargets;
+    private classifyResults;
+    private buildResult;
+    private sleep;
+}
+export { WaitForMcpServersParameters };
+export type { WaitForMcpServersInput, WaitForMcpServersOutput };

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

@@ -0,0 +1,164 @@
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { PromptRenderer, Session } from '../../vendor/cbc-core/node/index.js';
+import { type FunctionCallItem, RunContext, ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { ClientInfoProvider, ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { GalileoService } from '../galileo';
+import { CustomHeadersProvider } from '../http';
+import { ThreatDomainChecker } from '../sandbox-cli/threat-domain-checker';
+import { type SandboxCenterIpcClient } from '../sensitive-content/sandbox-center-ipc-client-protocol';
+import { SettingsManager } from '../settings';
+import { type SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../telemetry/sandbox-telemetry-protocol';
+import { BaseTool } from './base-tool';
+import { type SandboxWriteRuleGuard } from './sandbox-write-rule-guard';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const WebFetchParameters: z.ZodObject<{
+    url: z.ZodString;
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    prompt: string;
+}, {
+    url: string;
+    prompt: string;
+}>;
+export declare class WebFetchTool extends BaseTool implements Tool {
+    protected readonly promptRenderer: PromptRenderer;
+    protected readonly logger: Logger;
+    protected readonly sandboxCenterClient?: SandboxCenterIpcClient;
+    protected readonly sandboxWriteRuleGuard?: SandboxWriteRuleGuard;
+    protected readonly productManager: ProductManager;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected readonly clientInfoProvider: ClientInfoProvider;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly customHeadersProvider: CustomHeadersProvider;
+    protected readonly galileoService: GalileoService;
+    protected readonly threatDomainChecker?: ThreatDomainChecker;
+    protected readonly sandboxTelemetryReporter?: ISandboxTelemetryReporter;
+    private readonly WEB_FETCH_API_PATH;
+    name: ToolNames;
+    resolveSensitiveEgress(input: z.infer<typeof WebFetchParameters>, context: RunContext<Session>): Promise<{
+        source: "web-fetch";
+        inspectionContent: string;
+        destinationKey: string;
+    } | undefined>;
+    parameters: z.ZodObject<{
+        url: z.ZodString;
+        prompt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        prompt: string;
+    }, {
+        url: string;
+        prompt: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    private static cache;
+    /**
+     * 已落审计的恶意域名拦截，键为 `sessionId + requestId + target`。
+     *
+     * 模型在同一个 turn 里换 path / query 反复访问同一个恶意域名很常见，逐次落审计会把
+     * 安全中心刷成同一条内容的重复记录。沙箱侧有 `dedupeMaliciousNetworkBlockRecords` 做同样的事，
+     * WebFetch 这条旁路缺了等价保护。静态成员按进程共享，与 `cache` 一致。
+     */
+    private static auditedMaliciousBlocks;
+    resolveNeedPermissionArgs(_runContext: RunContext, input: z.infer<typeof WebFetchParameters>, _callId?: string): ToolArg[];
+    needsApproval: (runContext: RunContext<Session>, input: z.infer<typeof WebFetchParameters>, callId?: string) => Promise<boolean>;
+    /** Auto mode classifier projection: `${url}: ${prompt}` (Claude alignment, decision D1). */
+    toAutoClassifierInput(input: unknown): string;
+    execute(params: z.infer<typeof WebFetchParameters>, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /**
+     * 图片 / 二进制没有可摘要文本。直接返回 Bash+Read 指引，
+     * 跳过 AI summary，也不写入缓存——同一 URL 下次可能变成普通页面。
+     */
+    private returnNonTextResourceGuidance;
+    private recordMaliciousWebsiteAudit;
+    /** Check whether the remote API is disabled via environment variable or product feature. */
+    private isRemoteApiDisabled;
+    /**
+     * Race strategy: launch remote API and local fetch concurrently.
+     * - If remote succeeds within WEB_FETCH_API_TIMEOUT_MS (20s), use remote result.
+     * - If remote fails or times out, use local fetch result (already in-flight).
+     * This eliminates sequential latency — local fetch warms up in parallel.
+     *
+     * When CODEBUDDY_DISABLE_WEB_FETCH_REMOTE_API=true, skip remote API entirely and use local fetch only.
+     */
+    private fetchWithFallback;
+    private validateParams;
+    private normalizeUrl;
+    private getCachedEntry;
+    private setCachedContent;
+    private cleanExpiredCache;
+    /**
+     * Fetch content via the backend /agenttool/v1/webfetch API which returns markdown directly.
+     * The caller owns the deadline via `abortSignal` — when triggered, both the promise rejects
+     * and the underlying socket is closed.
+     */
+    private fetchContentViaApi;
+    private resolveCurrentModelName;
+    /**
+     * Local fallback: fetch the URL directly and convert HTML to markdown using turndown.
+     */
+    private fetchAndProcessLocally;
+    /**
+     * Extract useful information from HTML meta tags when body content is empty.
+     * This is particularly useful for SPA pages where the actual content is rendered by JavaScript.
+     */
+    private extractMetaContent;
+    private fetchWithTimeout;
+    /**
+     * WebFetch 的统一 URL 放行入口。
+     *
+     * 判定层级：有序规则首命中 → 恶意库。命中 allow 则跳过恶意库；其余再查
+     * sandbox-cli/Rust 只读 SQLite，与沙箱网络请求共用同一套哈希、主域和子域匹配。
+     */
+    private assertUrlAllowed;
+    private networkTargetKey;
+    /**
+     * 恶意域名库判定：命中抛 `MaliciousWebsiteBlockedError`，其余情形静默返回。
+     *
+     * 从 `assertUrlAllowed` 拆出来，是为了让 `*` deny / default_rule 排在本检查之后。
+     * 写成一段顺序代码的话，中间那几个「不查库」的早退（没有 checker、IP 字面量、
+     * 库不可用）会连这条有序规则一起跳过，把 catch-all deny 放成通过。
+     */
+    private assertNotMaliciousDomain;
+    private processContentWithAI;
+    private createAnalysisPrompt;
+    private createFallbackPrompt;
+    private createFallbackResponse;
+    private createContentSummary;
+    /**
+     * 安全中心：网络拒绝/放行域名检查。
+     *
+     * allow/ask/deny 与是否命中 allow 一律来自 Center `decide_network`。
+     * 有序规则首命中后才查恶意库。`*` deny 在 sandbox 侧会映射成 `cfg.default_rule`，
+     * Center 带 `deferToThreatCheck`，好让恶意库先认领归因——否则 catch-all 期间
+     * 所有恶意命中都会被记成普通策略拒绝。判决两种顺序都是拦，差的只有归因。
+     *
+     * 规则同步和运行时裁决都由 Center 负责，避免 Genie 与 Sandbox 使用不同的
+     * 本地配置快照。
+     */
+    private checkNetworkPolicy;
+    private interpretCenterNetworkDecision;
+    /**
+     * Emit a structured webfetch event to Galileo. Captures:
+     *   - which fetch path won (cache / api / local fallback)
+     *   - whether AI summary was triggered
+     *   - per-branch content lengths and durations (so the dashboard can compare api vs. local)
+     *   - URL host only (no full URL — avoid PII / sensitive query strings)
+     * Failures are swallowed; telemetry must not break the tool's main flow.
+     */
+    private reportTelemetry;
+    /**
+     * Extract host + path from URL safely. Returns host/path separately so the dashboard
+     * can group by host or drill into a specific page. Querystring is intentionally dropped
+     * to avoid leaking tokens / search keywords / other PII embedded in URL params.
+     */
+    private safeUrlParts;
+    /** Truncate string to N chars to keep telemetry attribute payloads bounded. */
+    private truncate;
+}
+export {};

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

@@ -0,0 +1,79 @@
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { ClientInfoProvider, 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 { type FunctionCallItem } from '../../vendor/cbc-shared/node/index.js';
+import { CustomHeadersProvider } from '../http';
+import { ThreatDomainChecker } from '../sandbox-cli/threat-domain-checker';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { SettingsManager } from '../settings';
+import type { SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../telemetry/sandbox-telemetry-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+declare const WebSearchParameters: z.ZodObject<{
+    query: z.ZodString;
+    allowed_domains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    blocked_domains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    freshness: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    allowed_domains?: string[] | undefined;
+    blocked_domains?: string[] | undefined;
+    freshness?: string | undefined;
+}, {
+    query: string;
+    allowed_domains?: string[] | undefined;
+    blocked_domains?: string[] | undefined;
+    freshness?: string | undefined;
+}>;
+export declare class WebSearchTool extends BaseTool implements Tool {
+    protected readonly productManager: ProductManager;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected readonly clientInfoProvider: ClientInfoProvider;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly customHeadersProvider: CustomHeadersProvider;
+    protected readonly logger: Logger;
+    protected readonly threatDomainChecker?: ThreatDomainChecker;
+    protected readonly sandboxTelemetryReporter?: ISandboxTelemetryReporter;
+    private readonly WEB_SEARCH_API_PATH;
+    private readonly WEB_SEARCH_TIMEOUT_MS;
+    name: ToolNames;
+    resolveSensitiveEgress(input: z.infer<typeof WebSearchParameters>): {
+        source: "web-search";
+        inspectionContent: string;
+        destinationKey: string;
+    } | undefined;
+    parameters: z.ZodObject<{
+        query: z.ZodString;
+        allowed_domains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        blocked_domains: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        freshness: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        query: string;
+        allowed_domains?: string[] | undefined;
+        blocked_domains?: string[] | undefined;
+        freshness?: string | undefined;
+    }, {
+        query: string;
+        allowed_domains?: string[] | undefined;
+        blocked_domains?: string[] | undefined;
+        freshness?: string | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    aliases: string[];
+    /** Auto mode classifier projection: the search query (Claude alignment, decision D1). */
+    toAutoClassifierInput(input: unknown): string;
+    execute(params: z.infer<typeof WebSearchParameters>, _context: RunContext<Session>, _details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    private filterUnsafeResults;
+    private recordMaliciousDomainHit;
+    private validateParams;
+    private performWebSearch;
+    private buildRequestBody;
+    private buildStructuredResult;
+    private formatSearchResults;
+}
+export {};

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

@@ -0,0 +1,43 @@
+/**
+ * WechatReply Tool
+ *
+ * Allows the AI to send replies back to WeChat users via the WechatChannelBridge.
+ * Dynamically enabled/disabled based on WeChat connection status.
+ */
+import { z } from 'zod';
+import type { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, type ToolResult } from './tool-protocol';
+export declare class WechatReplyTool extends BaseTool implements Tool {
+    name: string;
+    description: string;
+    needsApproval: boolean;
+    /**
+     * Only enabled when WeChat is connected.
+     * Checks WechatClient status dynamically at each agent run.
+     */
+    isEnabled: () => boolean;
+    parameters: z.ZodObject<{
+        chat_id: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        file_path: z.ZodOptional<z.ZodString>;
+        context_token: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        chat_id: string;
+        text?: string | undefined;
+        file_path?: string | undefined;
+        context_token?: string | undefined;
+    }, {
+        chat_id: string;
+        text?: string | undefined;
+        file_path?: string | undefined;
+        context_token?: string | undefined;
+    }>;
+    execute(input: {
+        chat_id: string;
+        text?: string;
+        file_path?: string;
+        context_token?: string;
+    }, context?: RunContext<Session>): Promise<ToolResult>;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * WeComReply Tool
+ *
+ * Allows the AI to send replies back to WeCom (企业微信) users via the WecomBotChannelBridge.
+ * Dynamically enabled/disabled based on WeCom connection status.
+ * Supports multiple client instances — any connected instance enables the tool.
+ *
+ * Supports:
+ *   - text: plain markdown text
+ *   - image_url: image URL (data: or http:) to upload and send
+ *   - file_path: local file path to upload and send
+ *   - file_url: remote file URL to download and send
+ */
+import { z } from 'zod';
+import type { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, type ToolResult } from './tool-protocol';
+export declare class WecomReplyTool extends BaseTool implements Tool {
+    name: string;
+    description: string;
+    needsApproval: boolean;
+    /**
+     * Enabled when any WeCom client instance is connected.
+     */
+    isEnabled: () => boolean;
+    parameters: z.ZodObject<{
+        chat_id: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        image_url: z.ZodOptional<z.ZodString>;
+        file_path: z.ZodOptional<z.ZodString>;
+        file_url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        chat_id: string;
+        text?: string | undefined;
+        image_url?: string | undefined;
+        file_path?: string | undefined;
+        file_url?: string | undefined;
+    }, {
+        chat_id: string;
+        text?: string | undefined;
+        image_url?: string | undefined;
+        file_path?: string | undefined;
+        file_url?: string | undefined;
+    }>;
+    execute(input: {
+        chat_id: string;
+        text?: string;
+        image_url?: string;
+        file_path?: string;
+        file_url?: string;
+    }, context?: RunContext<Session>): Promise<ToolResult>;
+    /**
+     * Upload and send media via WebSocket (WecomBotClient.uploadMedia + sendMediaMessage).
+     */
+    private sendMedia;
+    /**
+     * Detect WeCom media type from filename extension.
+     */
+    private detectMediaType;
+    /**
+     * Convert URL (data: or http:) or local path to Buffer.
+     */
+    private urlToBuffer;
+}

package/cli/dist-server/types/node/tools/workflow-background-task.d.ts

@@ -0,0 +1,54 @@
+/**
+ * WorkflowBackgroundTaskTracker —— 把后台 workflow run 接入 BackgroundTask 通知通道。
+ *
+ * WorkflowTool 与 `/deep-research` 等命令共用:注册 BackgroundTask(task.id == runId,
+ * TaskOutput 可按 runId 查) → done 时落盘 output、翻终态、推 `<task-notification>`。
+ *
+ * `showResultInChat`:命令入口没有模型在等结果,交互式 TUI 下把最终结果原样写进对话流,
+ * 通知改为 deferDrain(模型在下次用户输入时知道任务已结束),不再额外烧一轮模型复述。
+ * 非交互路径(ACP / stream-json / print)不写历史,照常 drain 让主 agent 转述结果。
+ *
+ * 不进 tools barrel:只被 workflow-tool / deep-research-command-executor 引用,
+ * lite-wb 把这两个入口 alias 掉后本文件随之出图(见 hooks/webpack-lite-wb.ts)。
+ */
+import { BackgroundTask, Session, SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { type WorkflowManager, type WorkflowStartHandle } from '../../workspace/cbc-workflow/lib/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { AgentTaskOutputFileManager, BackgroundTaskNotifier } from '../agent-task/agent-task-protocol';
+export interface WorkflowBackgroundTaskOptions {
+    /** 透传给 BackgroundTaskNotifier 拼 `<tool-use-id>`;命令入口无此值 */
+    toolUseId?: string;
+    /** 交互式 TUI 下把最终结果原样写进对话流(命令入口用) */
+    showResultInChat?: boolean;
+}
+export declare class WorkflowBackgroundTaskTracker {
+    protected readonly logger: Logger;
+    protected readonly manager: WorkflowManager;
+    protected readonly backgroundTaskNotifier: BackgroundTaskNotifier;
+    protected readonly outputFileManager: AgentTaskOutputFileManager;
+    protected readonly sessionManager: SessionManager;
+    /**
+     * 注册 BackgroundTask 并挂上 done 收口(fire-and-forget,不 await done)。
+     */
+    track(session: Session, handle: WorkflowStartHandle, options?: WorkflowBackgroundTaskOptions): BackgroundTask;
+    /**
+     * 把 workflow run 注册到 ToolManager 的后台任务池。
+     * - task.id 复用 runId,让 TaskOutput 能直接按 task_id 查到
+     * - stdout/stderr 留空 buffer:workflow 没有流式输出,但接口要求非空
+     * - kill wire 到 manager.abort,让模型/UI 调 KillBash 之类等价操作能终止 workflow
+     * - toolName 固定为 Workflow,notifier 据此输出 "Dynamic workflow" 文案
+     */
+    private registerBackgroundTask;
+    /**
+     * Workflow 完成 / 失败 / abort 时:
+     *   1. 把 record.output 落盘到用户隔离临时目录的 agent-tasks/<runId>.output
+     *   2. 翻 task 状态,通知 UI 更新
+     *   3. 调 BackgroundTaskNotifier 推 `<task-notification>` 给主 agent
+     */
+    private finalizeBackgroundTask;
+    /**
+     * 把最终结果作为命令输出写进对话流。失败自吞并返回 false,回退为常规通知 drain,
+     * 保证结果至少能经主 agent 送达。
+     */
+    private appendResultToChat;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * WorkflowTool —— 把 Dynamic Workflow 暴露给 LLM 主 agent 的 Tool 入口。
+ *
+ * 单一职责:协议适配。校验 input → 转交 WorkflowManager.start() → **立刻**返回 runId,
+ * 不阻塞主对话。workflow 在后台跑,主 agent 可以继续做其他事。
+ *
+ * 设计取舍(对齐 Claude Code 的 async_launched 行为,见反编译 `wf_full.txt:251499`):
+ * - cc 的 Workflow tool 是 fire-and-forget:`(async () => { ... })().catch(...)` 后立刻
+ *   `return { data: { status: "async_launched", ... } }`。我们对齐这个语义。
+ * - **Sub-agent 静音**:adapter 用 detached:true,不刷屏到主对话区;用户在 status-line /
+ *   `/workflows` panel 看实时进度。
+ * - **后台任务复用**:workflow run 当成一个 BackgroundTask 注册到 ToolManager,
+ *   完成时复用 BackgroundTaskNotifier 推 `<task-notification>` 给主 agent
+ *   (与 bash run_in_background / PowerShell 后台任务共用同一通知通道)。
+ *   `<output-file>` 落盘到用户隔离临时目录的 `agent-tasks/<runId>.output`,模型用
+ *   TaskOutput 工具拉完整结果。
+ *
+ * 使用约定(opt-in,见 description):
+ * - 主 agent 默认不调用此工具。
+ * - 仅在用户明确说 "use a workflow"、"run a workflow"、或在 prompt 中写
+ *   `ultracode` 关键词、或调用一个已保存的 workflow 命令时才用。
+ * - 用户日常请求(单轮可解、不需要多 agent 并行)不要起 workflow。
+ */
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { type Agent, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { type WorkflowManager, type WorkflowToolInput } from '../../workspace/cbc-workflow/lib/node/index.js';
+import { type ICwdService } from '../../workspace/cbc-worktree/lib/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { type FunctionCallItem, type RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { WorkflowBackgroundTaskTracker } from './workflow-background-task';
+export declare class WorkflowTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly manager: WorkflowManager;
+    protected readonly cwdService: ICwdService;
+    protected readonly workflowBackgroundTaskTracker: WorkflowBackgroundTaskTracker;
+    name: ToolNames;
+    /**
+     * 真正的描述来自 product.tools[].description (=> 模板 `workflow-tool-description`),
+     * 由框架在工具装配时通过 PromptManager 解出来覆写 BaseTool.description。
+     * 这里的占位仅在 product 配置里没声明该工具时兜底。
+     */
+    description: string;
+    parameters: z.ZodObject<{
+        script: z.ZodOptional<z.ZodString>;
+        scriptPath: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodString>;
+        resumeFromRunId: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        name?: string | undefined;
+        args?: string | undefined;
+        script?: string | undefined;
+        scriptPath?: string | undefined;
+        resumeFromRunId?: string | undefined;
+    }, {
+        name?: string | undefined;
+        args?: string | undefined;
+        script?: string | undefined;
+        scriptPath?: string | undefined;
+        resumeFromRunId?: string | undefined;
+    }>;
+    /**
+     * 工具卡片的标题:`Workflow(<source>)`,对齐 Claude TUI 截图。
+     * <source> 优先级 = name > scriptPath > "dynamic workflow"
+     */
+    argumentRenderer: ToolCallArgumentRenderer;
+    needsApproval: boolean;
+    /**
+     * 总开关:env 或 settings 任一标记禁用时,本工具就不会被装配进 agent 工具集,
+     * LLM 看不到也调不到。对齐 CC 的 `disableWorkflows` 能力。
+     * 实现细节:见 workflow/workflow-disabled.ts。
+     */
+    isEnabled: (_args: {
+        runContext: RunContext<Session>;
+        agent: Agent;
+    }) => Promise<boolean>;
+    execute(input: WorkflowToolInput, context?: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+}

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

@@ -0,0 +1,80 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { type FunctionCallItem, ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { CodeRatioReportingService } from '../code-ratio';
+import { TelemetryService } from '../telemetry';
+import { type FileChangeArtifactPublisher as FileChangeArtifactPublisherContract } from './file-change-artifact-publisher';
+import { SandboxPermissionFileTool } from './sandbox-permission-file-tool';
+import { ReadFileStateService, Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const WriteParameters: z.ZodObject<{
+    file_path: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    file_path: string;
+}, {
+    content: string;
+    file_path: string;
+}>;
+export declare class WriteTool extends SandboxPermissionFileTool implements Tool {
+    protected readonly workspace: Workspace;
+    protected readonly telemetryService: TelemetryService;
+    protected readonly readFileStateService: ReadFileStateService;
+    protected readonly codeRatioReportingService?: CodeRatioReportingService;
+    protected readonly fileChangeArtifactPublisher?: FileChangeArtifactPublisherContract;
+    name: ToolNames;
+    aliases: string[];
+    parameters: z.ZodObject<{
+        file_path: z.ZodString;
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        file_path: string;
+    }, {
+        content: string;
+        file_path: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(runContext: RunContext, input: z.infer<typeof WriteParameters>, callId?: string): ToolArg[];
+    /**
+     * Auto mode classifier projection: `${file_path}: ${content}` (strict Claude
+     * alignment, decision D1). The full content is intentionally projected — the
+     * classifier judges whether the written content is dangerous / a payload.
+     */
+    toAutoClassifierInput(input: unknown): string;
+    /**
+     * Map thrown non-ToolExecutionError failures to tool-specific error codes.
+     * Sandbox-related failures are kept here so hook manager no longer hard-codes
+     * Write-tool message matching.
+     */
+    resolveThrownErrorCode(error: unknown): string | undefined;
+    execute(input: z.infer<typeof WriteParameters>, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /**
+     * 将 Write 工具底层异常映射到 2000 段细分错误码。
+     * 重点覆盖沙箱 ModifyBackup 失败（pre-tool 或 write 阶段），避免落 99999。
+     */
+    private classifyWriteError;
+    private validateToolParams;
+    private checkFileExists;
+    private writeFileContent;
+    private prepareFileContent;
+    private isUtf8Encoding;
+    /**
+     * Prepend a UTF-8 BOM for new CSV/TSV files so Windows Excel decodes CJK
+     * characters correctly (#54660), or re-add the original file's BOM on
+     * overwrite (the model-supplied content usually lacks one).
+     */
+    private shouldWriteUtf8Bom;
+    private reportFileAction;
+    /**
+     * 全文 diff 超时兜底：无法精确到「变化的行」，退化为按整份行数/字符数估算。
+     * 新建文件 old 为空 → removed=0；覆盖已有文件视为「删旧全部 + 写新全部」（会把未改动的保留行也计入，数值偏大）。
+     * 仅超大文件覆写触发 diff 超时时才走到，极罕见。
+     */
+    private estimateChangesByLineCount;
+}
+export {};