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

package/cli/dist-server/types/node/tools/bash-sandbox-approval-requester.d.ts

@@ -0,0 +1,55 @@
+import { Logger } from '@celljs/core';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { FunctionCallItem } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext } from '@openai/agents';
+import { type SandboxApprovalRequest, type SandboxApprovalRequester } from '../permission';
+/**
+ * 涉及内置专家、内置市场插件或内置 Skill 文件的命令触发的沙箱规则审批，按 AI 安全防护关闭处理：
+ * 不交给沙箱 Reviewer，沙箱的 ask 仍由用户在原审批卡中决定。
+ * 文件与命令规则审批需异步核验来源，包含不带路径的插件 bin 调用；判定期间取消则不再入队。
+ */
+export declare function enqueueWithSandboxReviewSkip<T>(request: SandboxApprovalRequest, toolName: string, abortSignal: AbortSignal | undefined, enqueue: (skipSecurityReview: boolean) => Promise<T>, session: Session, toolCallId?: string): Promise<T>;
+/**
+ * Session-related context required to surface a sandbox approval request.
+ *
+ * This mirrors `BashToolSessionInfo` in `bash-tool.ts`; we accept the minimal
+ * subset (`runContext` + `details.toolCall`) that the requester actually needs,
+ * so the tool side keeps the wider type for its other call paths.
+ */
+export interface SandboxApprovalRequesterContext {
+    runContext: RunContext<Session>;
+    details?: {
+        toolCall: FunctionCallItem;
+    };
+    /** Tool name shown by the shared sandbox approval UI. Defaults to Bash. */
+    toolName?: string;
+}
+/**
+ * Build a SandboxApprovalRequester that surfaces SandboxOrchestrator approval
+ * prompts through the standard InterruptionService flow.
+ *
+ * Behavior (unchanged from the original inline implementation in BashTool):
+ *
+ * 1. Unrestricted sessions (`fullAccess`, or bypass + `CODEBUDDY_IS_SANDBOX`)
+ *    auto-allow every sandbox approval, including HIGH/CRITICAL and
+ *    sandbox policy-classified / 安全中心 ask-list requests. `disableBypassPermissionsMode`
+ *    still blocks the CLI bypass path.
+ * 2. sandbox policy-classified requests skip the legacy `CommandUtils.checkCommandSafety`
+ *    auto-approval and always surface the UI — sandbox policy is more precise.
+ * 3. In Bypass permission mode, non-HIGH/CRITICAL commands are auto-approved
+ *    without surfacing the UI (mirrors tool-permission-service Phase 5).
+ * 4. Server-bound sessions use their `canUseTool` callback. Without that binding,
+ *    the CLI synthesises a `RunToolApprovalItem` carrying `_sandboxResolve` and
+ *    delivers it through InterruptionService or `interruptionSubject`.
+ *
+ * The InterruptionService is resolved **once** at the top of each request: it's
+ * a singleton DI service whose identity does not change during a sandbox
+ * approval, so per-branch lookups would just be noise. If DI is unavailable we
+ * degrade to direct-push fallback for every branch in this request.
+ */
+export declare function createSandboxApprovalRequester(logger: Logger, sessionInfo?: SandboxApprovalRequesterContext, abortSignal?: AbortSignal): SandboxApprovalRequester;
+export declare function buildSandboxApprovalItem(request: SandboxApprovalRequest, toolCall: FunctionCallItem, settle: (choice: 'allow_once' | 'allow_session' | 'deny', source?: 'auto') => void, toolName: string, options?: {
+    displayCommand?: string;
+    describeSensitiveCommand?: boolean;
+    skipSecurityReview?: boolean;
+}): any;

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

@@ -0,0 +1,211 @@
+import { Logger } from '@celljs/core';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { PluginManager } from '../../workspace/cbc-plugins/lib/node/index.js';
+import { FunctionCallItem, ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import type { RunContext, ToolExecuteArgument } from '@openai/agents';
+import { z } from 'zod';
+import { type AcpTerminalPublisher } from '../acp/acp-protocol';
+import { BackgroundTaskNotifier } from '../agent-task/agent-task-protocol';
+import { BashSandboxManager } from '../bash-sandbox';
+import { ToolResultBlobService } from '../blob-store/tool-result-blob-service';
+import { EndpointProvider } from '../loopback/server-protocol';
+import { type SandboxOrchestrator as ISandboxOrchestrator, type SandboxPermissionGateway as ISandboxPermissionGateway } from '../permission';
+import { SettingsManager } from '../settings';
+import { ShellService } from '../shell';
+import { ShortcutManager } from '../shortcut/shortcut-protocol';
+import { BaseTool } from './base-tool';
+import { type ShellStreamPusherService } from './shell-stream-pusher';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const BashParameters: z.ZodObject<{
+    readonly command: z.ZodString;
+    readonly timeout: z.ZodOptional<z.ZodNumber>;
+    readonly description: z.ZodOptional<z.ZodString>;
+    readonly run_in_background: z.ZodOptional<z.ZodBoolean>;
+    readonly dangerouslyDisableSandbox: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    timeout?: number | undefined;
+    description?: string | undefined;
+    run_in_background?: boolean | undefined;
+    dangerouslyDisableSandbox?: boolean | undefined;
+}, {
+    command: string;
+    timeout?: number | undefined;
+    description?: string | undefined;
+    run_in_background?: boolean | undefined;
+    dangerouslyDisableSandbox?: boolean | undefined;
+}>;
+type BashInput = z.infer<typeof BashParameters>;
+export declare class BashTool extends BaseTool implements Tool {
+    protected readonly shellService: ShellService;
+    protected readonly sandboxOrchestrator: ISandboxOrchestrator;
+    protected readonly sandboxPermissionGateway: ISandboxPermissionGateway;
+    protected readonly shortcutManager: ShortcutManager;
+    protected readonly logger: Logger;
+    protected readonly shellStreamPusher: ShellStreamPusherService;
+    protected readonly sandboxManager: BashSandboxManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly pluginManager?: PluginManager;
+    protected readonly toolResultBlobService: ToolResultBlobService;
+    protected readonly backgroundTaskNotifier: BackgroundTaskNotifier;
+    protected readonly endpointProvider: EndpointProvider;
+    /**
+     * 尝试解析 service proxy 端点 URL。
+     * server 模式下立即可得；非 server 模式（TUI/SDK）下 deferred 永不解锁，
+     * @returns URL 字符串，解析失败返回 null
+     */
+    private resolveServiceProxyUrl;
+    /**
+     * ACP v2 终端推送器。惰性解析而非 @Autowired：纯 TUI / SDK 运行时不会加载 acp 模块，
+     * 此时容器里没有这个绑定，取不到就整体降级为不推送。
+     */
+    private terminalPublisherRef?;
+    protected shouldUsePty(session: Session | undefined): boolean;
+    protected get terminalPublisher(): AcpTerminalPublisher | undefined;
+    /**
+     * 把一段终端输出投给 ACP 客户端。三个 spawn 路径（file-fd poller / pipe onOutput /
+     * 前台促升）最终都汇到这里，所以门控与异常吞噬只需要在一处成立。
+     *
+     * 整段自吞异常：推送是旁路观测，绝不能让它影响命令执行。
+     *
+     * @param bytes `Buffer` = 来自文件的原始字节（字节保真）；`string` = 来自 PTY / pipe
+     *              的解码结果（保真度较弱，见各调用点说明）。
+     */
+    private publishTerminalOutput;
+    /** 促升路径用：任务还没促升时 task 为 undefined，天然不推。 */
+    private publishBackgroundOutput;
+    name: ToolNames;
+    aliases: string[];
+    /**
+     * Tool schema is a **method** (not a static field) so ToolManager.get()
+     * re-evaluates it per invocation against the current process env. When
+     * CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS is truthy the `run_in_background`
+     * field is omitted, so the model never sees it (issue #63114 — background
+     * shell results cannot flow back in request-response SDK / print-mode
+     * consumers, so the host disables the capability outright). The runtime
+     * guard in `execute()` still coerces `run_in_background=true` from
+     * stale/cached tool calls back to foreground.
+     */
+    parameters(): z.ZodTypeAny;
+    /**
+     * On Windows, BashTool requires Git Bash. If Git Bash is not installed,
+     * this tool is disabled and PowerShellTool becomes the sole shell tool.
+     */
+    isEnabled: () => boolean;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(_runContext: RunContext, input: BashInput, _callId?: string): ToolArg[];
+    /** Auto mode classifier projection: the command is the action's risk surface. */
+    toAutoClassifierInput(input: unknown): string;
+    needsApproval: (runContext: RunContext<Session>, input: ToolExecuteArgument<any>, callId?: string) => Promise<boolean>;
+    execute(input: BashInput, context: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    private executeForeground;
+    private createExecutionContext;
+    private createShellPromise;
+    private createBackgroundPromise;
+    /**
+     * shell-service 超时触发时的处理：尝试把命令转为后台任务而不是 kill。
+     *
+     * 对齐 Claude Code 的 `shellCommand.onTimeout → startBackgrounding` 行为
+     * (src/tools/BashTool/BashTool.tsx:967-971)。返回 true 告诉 shell-service "已接管,
+     * 不要 SIGTERM"，子进程继续跑；返回 false 走原 kill 路径（向后兼容老行为）。
+     *
+     * 关闭条件：
+     *   - env CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED=1 → 全局关闭
+     *   - print 模式（-p，非 stdio stream-json）→ 禁止（#61140，进程随主 turn 退出无法续跑后台任务）
+     *   - 命令在 auto-background 黑名单内（如 `sleep`） → 按原路径 kill
+     *   - execCtx.promoteToBackground 未就绪（理论上不会发生）
+     */
+    private tryPromoteToBackgroundOnTimeout;
+    private handleBackgroundedResult;
+    private buildForegroundResult;
+    /**
+     * 后台任务输出文件大小看门狗的扫描间隔。
+     */
+    private static readonly BG_SIZE_WATCHDOG_INTERVAL_MS;
+    /**
+     * 后台任务 stdout+stderr 总大小上限，超过则 SIGKILL（防写爆磁盘）。
+     * 默认 50MB；可通过 env `CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES` 调整。
+     * 参考 Claude Code `ShellCommand.ts:239-261` 的 size watchdog 机制。
+     */
+    private static readonly BG_DEFAULT_MAX_OUTPUT_BYTES;
+    private getBgMaxOutputBytes;
+    /**
+     * 给当前后台任务分配一对 stdout/stderr 落盘文件 + fd，用于直接接收子进程的 stdio。
+     *
+     * 返回 `null` 表示当前路径不适合走文件 fd（例如要走 sandbox 后端，
+     * IPC 协议不消费 fd），调用方应回退到 onOutput pipe 模式。
+     *
+     * 实际的"建目录 + 开 fd"逻辑抽到 {@link prepareBackgroundOutputFiles}（独立 module）
+     * 以便单测；此方法只做"是否走文件 fd"的策略判断。
+     */
+    private maybePrepareBackgroundOutputFiles;
+    private executeInBackground;
+    /** 关 fd 的小工具；忽略已关闭/无效错误。spawn 之后必须立刻调用，不要让父进程持有写端。 */
+    private closeFdSafely;
+    private createBackgroundTask;
+    /**
+     * 晋升路径的终端退出通知。任务未晋升（execCtx.currentBackgroundTask 为空）时静默跳过。
+     *
+     * 任何终止分支都必须调用：`exitStatus` 是客户端判定"已结束"的唯一依据，漏一条就会让
+     * 卡片永远停在运行中。
+     */
+    private notifyTerminalExit;
+    private updateBackgroundTaskStatus;
+    /**
+     * 收集本次命令声明的产物，并就地打完相关告警。
+     *
+     * 唯一来源是 `$CODEBUDDY_ARTIFACTS` 带外通道；stdout 不再被解析（原因见
+     * produced-artifact.ts 模块头）。
+     *
+     * 只返回 artifacts。malformed 不上抛是有意的：它唯一的用途就是告警，作者看不到
+     * 这个文件，被跳过的行只能靠日志暴露。
+     */
+    private collectDeclarations;
+    private buildBackgroundResult;
+    private startStreamingUpdates;
+    private stopStreamingUpdates;
+    private createStreamingText;
+    private pushStreamingText;
+    private cleanup;
+    private shouldAutoApproveInSandbox;
+    validateRuntimeInput(input: unknown): ToolResult | undefined;
+    private validateInput;
+    private errorResult;
+    /**
+     * 把参数校验类的失败原因映射到 8000 段细分错误码：
+     * 命令根无法识别（权限/解析域）→ 8014，其余保持 90000。
+     */
+    private resolveBashValidationErrorCode;
+    /**
+     * 根据 shell 执行结果推导结构化错误码。
+     * 返回 '0' 表示成功（无错误），非零纯数字为错误码。
+     */
+    private resolveBashErrorCode;
+    private findCallId;
+    private getCommandRoot;
+    /**
+     * shell-quote 抛错时的命令根兜底：按空白切分，跳过前导环境变量赋值，取第一个
+     * 非空 token 的 basename。用于 heredoc 写文件等 shell-quote 无法解析、但完全合法
+     * 的命令，保证它们仍能被识别命令根并正常执行，而不是让整轮 run 崩溃。
+     */
+    private getCommandRootFallback;
+    private isEnvAssignment;
+    private generateTaskId;
+    private resolveTimeout;
+    /**
+     * Build a SandboxApprovalRequester that surfaces SandboxOrchestrator
+     * approval prompts through the standard InterruptionService flow.
+     *
+     * The full implementation lives in `bash-sandbox-approval-requester.ts`
+     * — this method is a thin shim that injects the tool's logger.
+     */
+    private _createApprovalRequester;
+    /**
+     * Emit a single structured log line summarising the orchestrator outcome,
+     * so it is easy to grep for bypass decisions during diagnostics.
+     */
+    private _logOrchestratorOutcome;
+}
+export {};

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

@@ -0,0 +1,26 @@
+import { CliProvider } from '../cli/cli-protocol';
+export declare const BriefModeService: unique symbol;
+/**
+ * Brief 模式（issue #82025，对齐 claude-code `--brief`）的运行时开关读取入口。
+ *
+ * 开启后启用 `SendUserMessage` 工具作为 Agent 面向用户的主要可见输出通道，
+ * 并在系统提示中注入 brief 引导。开关只控制工具是否**可见/可调用**，
+ * 工具本身常驻工具列表，运行时由本服务的 opt-in 状态决定启用。
+ */
+export interface BriefModeService {
+    /**
+     * 是否已开启 Brief 模式。
+     *
+     * 由 `--brief` CLI flag 或 `CODEBUDDY_BRIEF` 环境变量任一激活。
+     */
+    isBriefEnabled(): boolean;
+}
+export declare class BriefModeServiceImpl implements BriefModeService {
+    protected readonly cliProvider: CliProvider;
+    /**
+     * 运行时 live 读 flag / env —— 绝不在 constructor / @PostConstruct 固化，
+     * 以兼容 prewarm：activate 时 `applyPrewarmArgs` 会重写 process.argv，
+     * 之后本方法首次被消费才读，天然拿到透传后的真实值。
+     */
+    isBriefEnabled(): boolean;
+}

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

@@ -0,0 +1,174 @@
+/**
+ * ChannelTasks —— 频道任务板（黑板 + 单写者认领）。
+ *
+ * 事件经 applyChannelTaskEvent 落板 + transcript（kind=task），再定向叫醒。
+ * 纪律：先 claim 再动手；产出写文件 / 分支，refs 只传引用不贴正文。
+ * 只对 Agent Home 自治表面开放（TUI / 通用 ACP / 子代理拿不到）。
+ */
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { ChannelWakeService } from '../agent-home/channel-wake-service';
+import { SettingsManager } from '../settings/settings-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolNames, ToolResult } from './tool-protocol';
+export declare class ChannelTasksTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly wakeService?: ChannelWakeService;
+    protected readonly settingsManager?: SettingsManager;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    shouldShowInToolSearch: () => boolean;
+    parameters: z.ZodObject<{
+        action: z.ZodEnum<["list", "create", "update", "delete", "claim", "complete", "release", "dispatch", "escalate"]>;
+        channel: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        subject: z.ZodOptional<z.ZodString>;
+        detail: z.ZodOptional<z.ZodString>;
+        assignAgentId: z.ZodOptional<z.ZodString>;
+        refs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<["issue", "file", "pr", "commit", "url"]>;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            kind: "file" | "url" | "commit" | "pr" | "issue";
+        }, {
+            value: string;
+            kind: "file" | "url" | "commit" | "pr" | "issue";
+        }>, "many">>;
+        requestId: z.ZodOptional<z.ZodString>;
+        assignments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            subject: z.ZodString;
+            detail: z.ZodOptional<z.ZodString>;
+            assignAgentId: z.ZodString;
+            refs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                kind: z.ZodEnum<["issue", "file", "pr", "commit", "url"]>;
+                value: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }, {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            subject: string;
+            assignAgentId: string;
+            detail?: string | undefined;
+            refs?: {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }[] | undefined;
+        }, {
+            subject: string;
+            assignAgentId: string;
+            detail?: string | undefined;
+            refs?: {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }[] | undefined;
+        }>, "many">>;
+        escalate: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodEnum<["nudge", "release"]>;
+            taskIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            maxStaleMs: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            mode: "release" | "nudge";
+            taskIds?: string[] | undefined;
+            maxStaleMs?: number | undefined;
+        }, {
+            mode: "release" | "nudge";
+            taskIds?: string[] | undefined;
+            maxStaleMs?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        action: "list" | "delete" | "create" | "complete" | "update" | "release" | "dispatch" | "claim" | "escalate";
+        detail?: string | undefined;
+        requestId?: string | undefined;
+        subject?: string | undefined;
+        channel?: string | undefined;
+        taskId?: string | undefined;
+        refs?: {
+            value: string;
+            kind: "file" | "url" | "commit" | "pr" | "issue";
+        }[] | undefined;
+        escalate?: {
+            mode: "release" | "nudge";
+            taskIds?: string[] | undefined;
+            maxStaleMs?: number | undefined;
+        } | undefined;
+        assignAgentId?: string | undefined;
+        assignments?: {
+            subject: string;
+            assignAgentId: string;
+            detail?: string | undefined;
+            refs?: {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }[] | undefined;
+        }[] | undefined;
+    }, {
+        action: "list" | "delete" | "create" | "complete" | "update" | "release" | "dispatch" | "claim" | "escalate";
+        detail?: string | undefined;
+        requestId?: string | undefined;
+        subject?: string | undefined;
+        channel?: string | undefined;
+        taskId?: string | undefined;
+        refs?: {
+            value: string;
+            kind: "file" | "url" | "commit" | "pr" | "issue";
+        }[] | undefined;
+        escalate?: {
+            mode: "release" | "nudge";
+            taskIds?: string[] | undefined;
+            maxStaleMs?: number | undefined;
+        } | undefined;
+        assignAgentId?: string | undefined;
+        assignments?: {
+            subject: string;
+            assignAgentId: string;
+            detail?: string | undefined;
+            refs?: {
+                value: string;
+                kind: "file" | "url" | "commit" | "pr" | "issue";
+            }[] | undefined;
+        }[] | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    toAutoClassifierInput(_input: unknown): string;
+    isEnabled: (args?: {
+        runContext?: RunContext<Session>;
+        agent?: {
+            name?: string;
+        };
+    }) => Promise<boolean>;
+    execute(input: {
+        action?: string;
+        channel?: string;
+        taskId?: string;
+        subject?: string;
+        detail?: string;
+        assignAgentId?: string;
+        refs?: {
+            kind: 'issue' | 'file' | 'pr' | 'commit' | 'url';
+            value: string;
+        }[];
+        requestId?: string;
+        assignments?: {
+            subject: string;
+            detail?: string;
+            assignAgentId: string;
+            refs?: {
+                kind: 'issue' | 'file' | 'pr' | 'commit' | 'url';
+                value: string;
+            }[];
+        }[];
+        escalate?: {
+            mode: 'nudge' | 'release';
+            taskIds?: string[];
+            maxStaleMs?: number;
+        };
+    }, context?: RunContext<Session>): Promise<ToolResult>;
+}

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

@@ -0,0 +1,86 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { 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 { BaseTool } from './base-tool';
+import { Tool, ToolResult } from './tool-protocol';
+declare const ComputerUseParameters: z.ZodObject<{
+    action: z.ZodEnum<["screenshot", "left_click", "right_click", "middle_click", "double_click", "triple_click", "mouse_move", "left_click_drag", "type", "key", "hold_key", "scroll", "wait", "cursor_position"]>;
+    coordinate: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    start_coordinate: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    text: z.ZodOptional<z.ZodString>;
+    scroll_direction: z.ZodOptional<z.ZodEnum<["up", "down", "left", "right"]>>;
+    scroll_amount: z.ZodOptional<z.ZodNumber>;
+    duration: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "key" | "type" | "scroll" | "screenshot" | "double_click" | "wait" | "left_click" | "right_click" | "middle_click" | "triple_click" | "mouse_move" | "left_click_drag" | "hold_key" | "cursor_position";
+    text?: string | undefined;
+    duration?: number | undefined;
+    scroll_direction?: "left" | "right" | "up" | "down" | undefined;
+    scroll_amount?: number | undefined;
+    coordinate?: number[] | undefined;
+    start_coordinate?: number[] | undefined;
+}, {
+    action: "key" | "type" | "scroll" | "screenshot" | "double_click" | "wait" | "left_click" | "right_click" | "middle_click" | "triple_click" | "mouse_move" | "left_click_drag" | "hold_key" | "cursor_position";
+    text?: string | undefined;
+    duration?: number | undefined;
+    scroll_direction?: "left" | "right" | "up" | "down" | undefined;
+    scroll_amount?: number | undefined;
+    coordinate?: number[] | undefined;
+    start_coordinate?: number[] | undefined;
+}>;
+type ComputerUseInput = z.infer<typeof ComputerUseParameters>;
+export declare class ComputerUseTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        action: z.ZodEnum<["screenshot", "left_click", "right_click", "middle_click", "double_click", "triple_click", "mouse_move", "left_click_drag", "type", "key", "hold_key", "scroll", "wait", "cursor_position"]>;
+        coordinate: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        start_coordinate: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+        text: z.ZodOptional<z.ZodString>;
+        scroll_direction: z.ZodOptional<z.ZodEnum<["up", "down", "left", "right"]>>;
+        scroll_amount: z.ZodOptional<z.ZodNumber>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        action: "key" | "type" | "scroll" | "screenshot" | "double_click" | "wait" | "left_click" | "right_click" | "middle_click" | "triple_click" | "mouse_move" | "left_click_drag" | "hold_key" | "cursor_position";
+        text?: string | undefined;
+        duration?: number | undefined;
+        scroll_direction?: "left" | "right" | "up" | "down" | undefined;
+        scroll_amount?: number | undefined;
+        coordinate?: number[] | undefined;
+        start_coordinate?: number[] | undefined;
+    }, {
+        action: "key" | "type" | "scroll" | "screenshot" | "double_click" | "wait" | "left_click" | "right_click" | "middle_click" | "triple_click" | "mouse_move" | "left_click_drag" | "hold_key" | "cursor_position";
+        text?: string | undefined;
+        duration?: number | undefined;
+        scroll_direction?: "left" | "right" | "up" | "down" | undefined;
+        scroll_amount?: number | undefined;
+        coordinate?: number[] | undefined;
+        start_coordinate?: number[] | undefined;
+    }>;
+    /**
+     * 启用条件：必须 macOS 且 env CODEBUDDY_COMPUTER_USE_ENABLED=1/true。
+     */
+    private isComputerUseEnabled;
+    isEnabled: (_args?: unknown) => Promise<boolean>;
+    /**
+     * 同步镜像 isEnabled 的 gate，用于 ToolSearch 延迟工具列表可见性过滤。
+     * gate 未开时不应出现在 "Available deferred tools" 描述里，避免模型误判此工具可用。
+     */
+    shouldShowInToolSearch: () => boolean;
+    execute(input: ComputerUseInput, _context?: RunContext<Session>): Promise<ToolResult>;
+    /**
+     * screenshot 返图：严格照抄 read-tool 形态——读 JPEG base64 → image_url data URI。
+     */
+    private formatScreenshot;
+    private dispatch;
+    /**
+     * 非 screenshot action 返 JSON content（string 形态）+ text renderer。
+     * rawResponse 保留原始 payload 供 PostToolUse hook 消费。
+     */
+    private formatResult;
+    private describeAction;
+}
+export {};

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

@@ -0,0 +1,82 @@
+/**
+ * CreateChannel —— agent 自主建频道 / 拉人（自治组队第二步）。
+ *
+ * create：2–6 个常驻同事（主 Agent 不是成员，不算名额），lead 缺省创建者（同事）否则第一个成员；给了 kickoff 就作为第一句发言并
+ *   全员唤醒（没有 job 的同事会当场起 job）。invite：把已有同事加进来，
+ *   同样可选 kickoff 唤醒。
+ * 规则（成员解析 / 配额 / lead）全在 agent-home-channel-create，工具只做编排。
+ */
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '../../vendor/cbc-shared/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { z } from 'zod';
+import { ChannelWakeService } from '../agent-home/channel-wake-service';
+import { SettingsManager } from '../settings/settings-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolNames, ToolResult } from './tool-protocol';
+declare const CreateChannelParameters: z.ZodObject<{
+    action: z.ZodEnum<["create", "invite"]>;
+    name: z.ZodOptional<z.ZodString>;
+    memberAgentIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    kickoff: z.ZodOptional<z.ZodString>;
+    leadAgentId: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "create" | "invite";
+    name?: string | undefined;
+    channel?: string | undefined;
+    leadAgentId?: string | undefined;
+    memberAgentIds?: string[] | undefined;
+    kickoff?: string | undefined;
+}, {
+    action: "create" | "invite";
+    name?: string | undefined;
+    channel?: string | undefined;
+    leadAgentId?: string | undefined;
+    memberAgentIds?: string[] | undefined;
+    kickoff?: string | undefined;
+}>;
+type CreateChannelInput = z.infer<typeof CreateChannelParameters>;
+export declare class CreateChannelTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly wakeService?: ChannelWakeService;
+    protected readonly settingsManager?: SettingsManager;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    shouldShowInToolSearch: () => boolean;
+    parameters: z.ZodObject<{
+        action: z.ZodEnum<["create", "invite"]>;
+        name: z.ZodOptional<z.ZodString>;
+        memberAgentIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        kickoff: z.ZodOptional<z.ZodString>;
+        leadAgentId: z.ZodOptional<z.ZodString>;
+        channel: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        action: "create" | "invite";
+        name?: string | undefined;
+        channel?: string | undefined;
+        leadAgentId?: string | undefined;
+        memberAgentIds?: string[] | undefined;
+        kickoff?: string | undefined;
+    }, {
+        action: "create" | "invite";
+        name?: string | undefined;
+        channel?: string | undefined;
+        leadAgentId?: string | undefined;
+        memberAgentIds?: string[] | undefined;
+        kickoff?: string | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    toAutoClassifierInput(_input: unknown): string;
+    isEnabled: (args?: {
+        runContext?: RunContext<Session>;
+        agent?: {
+            name?: string;
+        };
+    }) => Promise<boolean>;
+    execute(input: CreateChannelInput, context?: RunContext<Session>): Promise<ToolResult>;
+    /** 发言（有 kickoff）+ 唤醒。返回实际唤醒人数；无 wakeService 时返回 0 并记日志。 */
+    private speakAndWake;
+}
+export {};