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

package/cli/dist-server/types/node/tools/main-agent-meta-tools.d.ts

@@ -0,0 +1,107 @@
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { AgentManager } from '../../vendor/cbc-core/node/index.js';
+import { AgentTaskManager } from '../agent-task/agent-task-protocol';
+import { GoalService } from '../../workspace/cbc-goal/lib/node/index.js';
+import { InterruptionService, Session } from '../../vendor/cbc-core/node/index.js';
+import { BaseTool } from './base-tool';
+import { Tool, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+declare const ListAgentsParameters: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare class ListAgentsTool extends BaseTool implements Tool {
+    protected readonly agentManager: AgentManager;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    needsApproval: boolean;
+    execute(_input: z.infer<typeof ListAgentsParameters>, context?: RunContext<Session>): Promise<ToolResult>;
+}
+declare const InterruptAgentParameters: z.ZodObject<{
+    sessionId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    reason?: string | undefined;
+}, {
+    sessionId: string;
+    reason?: string | undefined;
+}>;
+export declare class InterruptAgentTool extends BaseTool implements Tool {
+    /**
+     * 必须走 AgentTaskManager（与 TaskStop 同一条路）取消**活跃**任务。
+     *
+     * 不要用 `sessionManager.get(id)` 拿目标再 abort —— SessionStore 无活跃缓存，
+     * get() 从磁盘反序列化出一个**全新** Session（sessionFactory 无条件 new
+     * AbortController），abort 打在废弃副本上，对真正在跑的 run 是空操作；
+     * `cancelAllForSession(子会话id)` 也查不到以主会话 id 为键的审批队列。
+     * AgentTask.cancel() 持有活的 subAgentSession 引用，abort 才真正生效。
+     */
+    protected readonly agentTaskManager: AgentTaskManager;
+    protected readonly interruptionService: InterruptionService;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        sessionId: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sessionId: string;
+        reason?: string | undefined;
+    }, {
+        sessionId: string;
+        reason?: string | undefined;
+    }>;
+    needsApproval: boolean;
+    execute(input: z.infer<typeof InterruptAgentParameters>, context?: RunContext<Session>): Promise<ToolResult>;
+    /** 当前会话所属树的主会话 id；解析失败回退自身 id（顶层会话本来就是自身）。 */
+    private currentMainSessionId;
+}
+/**
+ * `GoalService.set` 已是「设定/替换」语义（有目标时先注销再设，见 goal-protocol），
+ * 所以 CreateGoal / UpdateGoal 共用同一个 schema 与同一条执行路径，只是名字不同 ——
+ * 保留两个名字是为了让模型无论选哪个都能成功，而不是两套行为。
+ */
+declare const GoalConditionParameters: z.ZodObject<{
+    condition: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    condition: string;
+}, {
+    condition: string;
+}>;
+export declare class CreateGoalTool extends BaseTool implements Tool {
+    protected readonly goalService: GoalService;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        condition: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        condition: string;
+    }, {
+        condition: string;
+    }>;
+    needsApproval: boolean;
+    execute(input: z.infer<typeof GoalConditionParameters>, context?: RunContext<Session>): Promise<ToolResult>;
+}
+declare const GetGoalParameters: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare class GetGoalTool extends BaseTool implements Tool {
+    protected readonly goalService: GoalService;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    needsApproval: boolean;
+    execute(_input: z.infer<typeof GetGoalParameters>, context?: RunContext<Session>): Promise<ToolResult>;
+}
+export declare class UpdateGoalTool extends BaseTool implements Tool {
+    protected readonly goalService: GoalService;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        condition: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        condition: string;
+    }, {
+        condition: string;
+    }>;
+    needsApproval: boolean;
+    execute(input: z.infer<typeof GoalConditionParameters>, context?: RunContext<Session>): Promise<ToolResult>;
+}
+export {};

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

@@ -0,0 +1,33 @@
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { MemoryManager } from '../memory';
+import { BaseTool } from './base-tool';
+import { Tool, ToolResult } from './tool-protocol';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+declare const MemoryParameters: z.ZodObject<{
+    fact: z.ZodString;
+    scope: z.ZodEnum<["user", "project", "project_local"]>;
+}, "strip", z.ZodTypeAny, {
+    scope: "user" | "project" | "project_local";
+    fact: string;
+}, {
+    scope: "user" | "project" | "project_local";
+    fact: string;
+}>;
+export declare class MemoryTool extends BaseTool implements Tool {
+    protected readonly memoryManager: MemoryManager;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        fact: z.ZodString;
+        scope: z.ZodEnum<["user", "project", "project_local"]>;
+    }, "strip", z.ZodTypeAny, {
+        scope: "user" | "project" | "project_local";
+        fact: string;
+    }, {
+        scope: "user" | "project" | "project_local";
+        fact: string;
+    }>;
+    execute(input: z.infer<typeof MemoryParameters>, context?: RunContext): Promise<ToolResult>;
+}
+export {};

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

@@ -0,0 +1,83 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import { type RunContext, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { SettingsManager } from '../settings/settings-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+/**
+ * MessageColleague —— Agent Home 的 1:1（通讯录可达即能发）。
+ *
+ * 目标是"某个人"（上游 SendToAgent 的语义），不是"某个房间成员"：
+ * 同事发到他的 job 收件箱（死了就拉起）；主 Agent（委托人）发到主会话邮箱
+ * （落盘，主会话 idle 时注入）。频道群对话走 SpeakInChannel，不是这个工具。
+ * 和 Agent Teams 的 SendMessage 无关。
+ */
+export declare class MessageColleagueTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly settingsManager?: SettingsManager;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    /**
+     * 通讯录里没人（且不是自己）时，它既不在工具列表里，也不出现在 ToolSearch 的
+     * "Available deferred tools" 描述里，模型不会知道有这么个东西。
+     */
+    shouldShowInToolSearch: () => boolean;
+    parameters: z.ZodObject<{
+        action: z.ZodOptional<z.ZodEnum<["list", "send", "incoming"]>>;
+        recipient: z.ZodOptional<z.ZodString>;
+        content: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        summary?: string | undefined;
+        text?: string | undefined;
+        content?: string | undefined;
+        action?: "list" | "send" | "incoming" | undefined;
+        from?: string | undefined;
+        recipient?: string | undefined;
+    }, {
+        summary?: string | undefined;
+        text?: string | undefined;
+        content?: string | undefined;
+        action?: "list" | "send" | "incoming" | undefined;
+        from?: string | undefined;
+        recipient?: string | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    /**
+     * 房间 ACL 已经挡住了能联系谁；问候同事不必再走 auto 分类器，
+     * 否则模型已经决定发了，UI 还会再问一次确认。
+     */
+    toAutoClassifierInput(_input: unknown): string;
+    private cachedTargets?;
+    private cachedAt;
+    /** 通讯录里还有别人 → 工具出现。主 Agent 也算（同事要能回报它）。 */
+    private hasReachableTarget;
+    /**
+     * 可见性用的通讯录（**宽松**）：未认领的 job 也解析成默认 Agent → 有人就返回非空。
+     * 动作路径不信这份缓存，自己用 strict 重新解析（见 execute）。
+     */
+    private targets;
+    /**
+     * 极简没有组队 / 互感知：工具不出现。其他人走通讯录（有人就能发）。
+     */
+    isEnabled: (args?: {
+        runContext?: RunContext<Session>;
+        agent?: {
+            name?: string;
+        };
+    }) => Promise<boolean>;
+    /** 每个成员此刻在干嘛：读的是和侧栏同一份 Run 状态，不另开数据源。 */
+    private describeContact;
+    execute(input: {
+        action?: string;
+        recipient?: string;
+        content?: string;
+        summary?: string;
+        from?: string;
+        text?: string;
+    }, context?: RunContext<Session>): Promise<ToolResult>;
+}

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

@@ -0,0 +1,216 @@
+/**
+ * MonitorTool —— 后台监视一个事件源，把增量内容主动推回主 agent。
+ *
+ * 事件源有两种（互斥）：
+ * - `command`（issue #74426）：后台跑命令，把其增量输出推回。
+ * - `ws`（issue #74436）：连一个 `ws://`/`wss://` URL，把服务端推来的每条消息推回。
+ *
+ * 背景 / 设计取舍
+ * ================
+ * 对齐 Claude Code Tools Reference 的 `Monitor` 章节：模型后台监视某个东西，有新内容
+ * 时不用主动轮询 `BashOutput`/`TaskOutput`，而是被系统"主动唤醒"看到增量内容。
+ *
+ * 关键发现（调研已核实）：这不是一个新基础设施，而是把两个已存在的能力接起来：
+ * 1. **反应式推送通道**：`BackgroundTaskNotifier`（`enqueueMessage` + 忙闲判断的
+ *    `scheduleDrain`）——本工具复用其新增的 `notifyEvent()` 方法（区别于
+ *    `notifyCompletion()`：不做 per-task `notified` 幂等，因为"多次增量 tick"本身
+ *    就是预期语义，不是重复通知）。
+ * 2. **文件 tail 能力**：`BackgroundOutputTailPoller`——本工具复用其新增的 `onChunk`
+ *    回调（bash-tool/powershell-tool 不传，行为不变），每次 tick 读到新内容时触发。
+ *
+ * command 源的拉起复用 `SandboxOrchestrator`（与 BashTool 同一条沙箱优先执行路径），
+ * 输出走文件 fd 模式（`prepareBackgroundOutputFiles`），保证子进程/孙进程的
+ * stdout/stderr 落盘、父进程不持有写端。
+ *
+ * ws 源不经过 shell / 沙箱 / 文件 fd（没有进程可言），直接把 socket 消息写进
+ * `TruncateBuffer` 并推事件；生命周期仍复用同一个 `BackgroundTask` 契约，
+ * 因此 `TaskStop` / `TaskOutput` / `TaskList` 全部零改动可用
+ * （已核实 `TaskOutput.executeBackgroundShellTask` 只读 stdout/stderr buffer，
+ * 不依赖 `outputFilePath`，所以纯内存的 ws 任务能正常被查询）。
+ *
+ * 与 BashTool `run_in_background` 的关键区别：
+ * - BashTool 的通知只在任务**终态**（completed/failed/killed）时推送一次。
+ * - MonitorTool 在任务**运行期间**的每个增量 tick 都推送（command 模式合并同一 tick
+ *   内的多行输出成一条 `<monitor-event>`；ws 模式严格一条消息一个事件，见下），
+ *   任务终态时改推一条 status=done 的收尾事件。
+ *
+ * **command 与 ws 的事件粒度刻意不同**：command 模式按 tick 合并多行（避免逐行刷屏）；
+ * ws 模式一条消息 = 一个事件、即使消息跨多行也不拆，因为消息边界是 WebSocket 的协议
+ * 语义，合并会破坏它。（附注：CC 文档描述 command 模式为逐行回传，我们是按 tick 合并，
+ * 这是 #74426 既有的有意偏差，本 issue 不改动 command 侧行为。）
+ *
+ * 停止机制：复用 `TaskStopTool` / `ToolManager.killBackgroundTask` 现有的后台任务
+ * 终止路径——本工具注册的 task 与 bash-tool 的 task 走同一个 `BackgroundTask` 契约，
+ * `TaskStop` 无需任何改动即可停止一个 Monitor（两种事件源都是）。
+ *
+ * 开关：默认开启（cbc-cli 场景不需要任何额外配置）。理由见 issue #74426 的"三次审计
+ * 修正"结论——WorkBuddy 侧 `mode-tools-config.ts` 已有独立生效的工具白名单天然隔离，
+ * agent-cli 侧不需要再叠加一道默认关闭的环境变量；`CODEBUDDY_MONITOR_ENABLED=false`
+ * 仍可显式关闭（与 ReportFindings/PushNotification 同档）。
+ *
+ * ws 源的安全边界（issue #74436，务必理解后再改动）
+ * ================================================
+ * 出站连接的闸门是 **`execute()` 内每次调用都跑的 `checkWsNetworkPolicy`**，
+ * 不是审批弹窗。审批可以被用户的"本会话不再询问"缓存跳过，但网络策略检查不会被跳过，
+ * 所以私有地址 / cloud metadata / 有序网络 deny 规则命中的主机在任何情况下都连不上。
+ * **不要把网络策略检查挪到 `needsApproval` 里**，那样会被审批缓存绕过。
+ *
+ * 已知不对齐 CC 的两项（有意为之，见 monitor-ws-network-policy.ts 文件头详述）：
+ * 不做 DNS 解析（与 WebFetch 现状一致）；无 `allowManagedDomainsOnly` 概念（本仓库不存在该配置）。
+ * 另：CC 要求 ws 审批不提供"同 host 免询问"选项，我们目前提供 —— 这需要改动全局审批
+ * 服务（影响所有工具），风险面与本功能不成比例，故本轮不做；相关的既有缺陷
+ * （`ToolAlwaysApprovalServiceImpl.resolveApprovalRules` 落裸 `[{ toolName }]` 规则，
+ * 叠加 Phase 2 早于 Phase 3 安全检查返回）已单独立项跟踪。
+ */
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { FunctionCallItem, ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { BackgroundTaskNotifier } from '../agent-task/agent-task-protocol';
+import { BashSandboxManager } from '../bash-sandbox/bash-sandbox-protocol';
+import { type SandboxOrchestrator as ISandboxOrchestrator, type SandboxPermissionGateway as ISandboxPermissionGateway } from '../permission';
+import { type SandboxCenterIpcClient as ISandboxCenterIpcClient } from '../sensitive-content/sandbox-center-ipc-client-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+/**
+ * `command` 与 `ws` 互斥。
+ *
+ * **互斥校验刻意放在 `validateRuntimeInput()` 里，不用 `.superRefine()`。** 原因：`superRefine()`
+ * 返回的是 `ZodEffects` 而非 `ZodObject`，而 SDK 的 `ToolExecuteArgument<TParameters>`
+ * 依赖 `TParameters extends ZodObjectLike`（= `ZodObject<any, any>`，见
+ * `@openai/agents-core/dist/utils/zodCompat.d.ts`）。一旦退化成 `ZodEffects`，
+ * `execute(input)` 的 input 类型会从推断出的对象塌成 `string`，编译期就丢掉类型保护
+ * （JSON Schema 侧虽然仍能正确产出 properties，但类型链已断）。
+ *
+ * 同理也没用 `z.union`：union 产出的 `anyOf` 在部分模型上表达力较差、容易生成两个
+ * 字段都带的调用，且同样不是 `ZodObject`。平铺 optional 字段 + 运行时校验，既保住
+ * 类型链，也能给模型明确的错误信息。
+ */
+declare const MonitorParameters: z.ZodObject<{
+    command: z.ZodOptional<z.ZodString>;
+    ws: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        protocols: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        protocols?: string[] | undefined;
+    }, {
+        url: string;
+        protocols?: string[] | undefined;
+    }>>;
+    timeout_ms: z.ZodOptional<z.ZodNumber>;
+    persistent: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    command?: string | undefined;
+    ws?: {
+        url: string;
+        protocols?: string[] | undefined;
+    } | undefined;
+    persistent?: boolean | undefined;
+    timeout_ms?: number | undefined;
+}, {
+    command?: string | undefined;
+    ws?: {
+        url: string;
+        protocols?: string[] | undefined;
+    } | undefined;
+    persistent?: boolean | undefined;
+    timeout_ms?: number | undefined;
+}>;
+type MonitorInput = z.infer<typeof MonitorParameters>;
+/**
+ * 单 tick 内可能有多行输出，合并成一条 `<monitor-event>`，避免逐行刷屏（issue 验收标准）。
+ * 导出供单测直接校验 XML 结构，避免测试依赖完整 IoC 装配跑一次真实 execute()。
+ */
+export declare function buildMonitorEventXml(taskId: string, chunk: string): string;
+/** 收尾事件的终止原因。ws 源新增 `closed` / `oversized` / `error` 三种（issue #74436）。 */
+export type MonitorDoneReason = 'timeout' | 'exit' | 'stopped' | 'closed' | 'oversized' | 'error';
+export declare function buildMonitorDoneEventXml(taskId: string, reason: MonitorDoneReason, detail?: string): string;
+export declare class MonitorTool extends BaseTool implements Tool {
+    protected readonly sandboxOrchestrator: ISandboxOrchestrator;
+    protected readonly sandboxPermissionGateway: ISandboxPermissionGateway;
+    protected readonly logger: Logger;
+    protected readonly backgroundTaskNotifier: BackgroundTaskNotifier;
+    protected readonly bashSandboxManager: BashSandboxManager;
+    protected readonly sandboxCenterClient?: ISandboxCenterIpcClient;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+        ws: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            protocols: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            url: string;
+            protocols?: string[] | undefined;
+        }, {
+            url: string;
+            protocols?: string[] | undefined;
+        }>>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        persistent: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        command?: string | undefined;
+        ws?: {
+            url: string;
+            protocols?: string[] | undefined;
+        } | undefined;
+        persistent?: boolean | undefined;
+        timeout_ms?: number | undefined;
+    }, {
+        command?: string | undefined;
+        ws?: {
+            url: string;
+            protocols?: string[] | undefined;
+        } | undefined;
+        persistent?: boolean | undefined;
+        timeout_ms?: number | undefined;
+    }>;
+    /**
+     * `displayProperties` 是给 command 分支用的（工具调用头只显示命令本身）。
+     * ws 分支没有 `command` 字段，若不加 `formatText` 兜底，`displayProperties`
+     * 的默认渲染逻辑在找不到该属性时会降级成展示完整参数 JSON（含 `ws.url` 等），
+     * 体验上是"未格式化"而非"崩溃"，但既然有专门的格式化钩子就应该用上。
+     */
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: () => boolean;
+    /**
+     * 权限投影。
+     *
+     * **安全关键**：必须按事件源分流。此前只有 command 源时这里硬取 `input.command`，
+     * ws-only 调用会投影出 `value: undefined`，导致权限规则匹配拿到空值 —— 那等于
+     * 静默放行（规则匹配不到任何东西，也就拦不住任何东西）。新增任何非 command
+     * 事件源时都必须同步扩展这里，否则就是开一个权限旁路。
+     */
+    resolveNeedPermissionArgs(_runContext: RunContext, input: MonitorInput, _callId?: string): ToolArg[];
+    /**
+     * Auto mode classifier projection：命令本身即为该动作的风险面，与 BashTool 对齐。
+     * ws 源投影 URL，理由同 `resolveNeedPermissionArgs` —— 不能给 classifier 空输入，
+     * 否则 auto 模式会因「无相关输入」短路放行而不做任何风险评估。
+     */
+    toAutoClassifierInput(input: unknown): string;
+    needsApproval: (runContext: RunContext<Session>, input: unknown) => Promise<boolean>;
+    /**
+     * 按事件源分派。互斥校验由 `validateRuntimeInput()` 完成，原因见 `MonitorParameters`
+     * 上方注释（`superRefine` 会把 schema 退化成 `ZodEffects`，破坏 SDK 的输入类型推断）。
+     */
+    execute(input: MonitorInput, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /** ws 事件源（issue #74436）：连一个出站 WebSocket，把每条消息当事件推回。 */
+    private executeWsSource;
+    /** 把 ws 源的终止原因映射成 BackgroundTask 状态 + 收尾事件措辞。 */
+    private finishWsByReason;
+    /** 解析 timeout_ms / persistent，两种事件源共用。 */
+    private resolveTimeout;
+    /** command 事件源（issue #74426）：后台跑命令，把增量输出推回。行为与本 issue 之前完全一致。 */
+    private executeCommandSource;
+    /** 单 tick 增量文本入队 —— 复用 BackgroundTaskNotifier 的忙闲判断 + drain 调度。 */
+    private pushMonitorEvent;
+    private closeFdSafely;
+    validateRuntimeInput(input: unknown): ToolResult | undefined;
+    private invalidParameterResult;
+    private generateTaskId;
+}
+export {};

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

@@ -0,0 +1,109 @@
+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 MultiEditFileParameters: z.ZodObject<{
+    file_path: z.ZodString;
+    edits: z.ZodArray<z.ZodObject<{
+        old_string: z.ZodString;
+        new_string: z.ZodString;
+        replace_all: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        new_string: string;
+        old_string: string;
+        replace_all: boolean;
+    }, {
+        new_string: string;
+        old_string: string;
+        replace_all?: boolean | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    edits: {
+        new_string: string;
+        old_string: string;
+        replace_all: boolean;
+    }[];
+    file_path: string;
+}, {
+    edits: {
+        new_string: string;
+        old_string: string;
+        replace_all?: boolean | undefined;
+    }[];
+    file_path: string;
+}>;
+export declare class MultiEditTool 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;
+        edits: z.ZodArray<z.ZodObject<{
+            old_string: z.ZodString;
+            new_string: z.ZodString;
+            replace_all: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, "strip", z.ZodTypeAny, {
+            new_string: string;
+            old_string: string;
+            replace_all: boolean;
+        }, {
+            new_string: string;
+            old_string: string;
+            replace_all?: boolean | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        edits: {
+            new_string: string;
+            old_string: string;
+            replace_all: boolean;
+        }[];
+        file_path: string;
+    }, {
+        edits: {
+            new_string: string;
+            old_string: string;
+            replace_all?: boolean | undefined;
+        }[];
+        file_path: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(_runContext: RunContext, input: z.infer<typeof MultiEditFileParameters>, _callId?: string): ToolArg[];
+    /**
+     * Auto mode classifier projection: `${file_path}: ${all new_strings}` (Claude
+     * Edit-content alignment, decision D1) — every edit's new content is inspected
+     * for a dangerous payload.
+     */
+    toAutoClassifierInput(input: unknown): string;
+    /**
+     * 多步编辑的核心逻辑，顺序应用所有编辑操作
+     * 所有编辑操作是原子性的 - 要么全部成功，要么全部失败
+     * 每个编辑操作都在前一个编辑的结果上进行
+     */
+    private applyMultiEdits;
+    /**
+     * 计算多步编辑的最终结果
+     * 验证所有编辑操作的有效性，并计算最终的文件内容
+     */
+    private calculateMultiEdit;
+    /**
+     * 执行多步编辑操作
+     * 原子性操作：要么所有编辑都成功应用，要么全部回滚
+     */
+    execute(params: z.infer<typeof MultiEditFileParameters>, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    private classifyReadError;
+    private isUtf8Encoding;
+    private reportFileAction;
+}
+export {};

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

@@ -0,0 +1,75 @@
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { CodeRatioReportingService } from '../code-ratio';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { TelemetryService } from '../telemetry';
+import { SandboxPermissionFileTool } from './sandbox-permission-file-tool';
+import { ReadFileStateService, Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+import { ToolArg } from '../../vendor/cbc-shared/node/index.js';
+declare const NotebookEditParameters: z.ZodObject<{
+    notebook_path: z.ZodString;
+    cell_id: z.ZodOptional<z.ZodString>;
+    new_source: z.ZodString;
+    cell_type: z.ZodOptional<z.ZodEnum<["code", "markdown"]>>;
+    edit_mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["replace", "insert", "delete"]>>>;
+}, "strip", z.ZodTypeAny, {
+    notebook_path: string;
+    edit_mode: "replace" | "delete" | "insert";
+    new_source: string;
+    cell_id?: string | undefined;
+    cell_type?: "code" | "markdown" | undefined;
+}, {
+    notebook_path: string;
+    new_source: string;
+    cell_id?: string | undefined;
+    cell_type?: "code" | "markdown" | undefined;
+    edit_mode?: "replace" | "delete" | "insert" | undefined;
+}>;
+export declare class NotebookEditTool extends SandboxPermissionFileTool implements Tool {
+    protected readonly telemetryService: TelemetryService;
+    protected readonly readFileStateService: ReadFileStateService;
+    protected readonly codeRatioReportingService?: CodeRatioReportingService;
+    name: string;
+    aliases: string[];
+    description: string;
+    parameters: z.ZodObject<{
+        notebook_path: z.ZodString;
+        cell_id: z.ZodOptional<z.ZodString>;
+        new_source: z.ZodString;
+        cell_type: z.ZodOptional<z.ZodEnum<["code", "markdown"]>>;
+        edit_mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["replace", "insert", "delete"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        notebook_path: string;
+        edit_mode: "replace" | "delete" | "insert";
+        new_source: string;
+        cell_id?: string | undefined;
+        cell_type?: "code" | "markdown" | undefined;
+    }, {
+        notebook_path: string;
+        new_source: string;
+        cell_id?: string | undefined;
+        cell_type?: "code" | "markdown" | undefined;
+        edit_mode?: "replace" | "delete" | "insert" | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(_runContext: RunContext, input: z.infer<typeof NotebookEditParameters>, _callId?: string): ToolArg[];
+    /**
+     * Auto mode classifier projection: `${notebook_path} ${edit_mode}: ${new_source}`
+     * (strict Claude alignment, decision D1) — the new cell source is inspected
+     * for a dangerous payload.
+     */
+    toAutoClassifierInput(input: unknown): string;
+    private validateToolParams;
+    private readNotebookFile;
+    private createNewNotebook;
+    private writeNotebookFile;
+    private findCellIndexById;
+    private generateCellId;
+    private createNewCell;
+    private normalizeSource;
+    execute(params: z.infer<typeof NotebookEditParameters>, _context: RunContext<Session>): Promise<ToolResult>;
+    /** 把 ipynb 的 cell source（string | string[]）还原为字符串。ipynb 约定每行已含结尾 '\n'，join('') 即原文。 */
+    private sourceToString;
+    private reportFileAction;
+}
+export {};