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

package/cli/dist-server/types/node/tools/repl/repl-catalog-source.d.ts

@@ -0,0 +1,108 @@
+/**
+ * ReplCatalogSource —— 骨架目录与发现 API 的统一采集层（主线程）。
+ *
+ * 设计见 docs/repl-code-mode/mcp-code-mode-design.md §4.3.2「目录数据源」。
+ *
+ * 三个数据源，各补一块：
+ *  - ToolSearchService.listDeferredToolInfosForSession() → 全局及会话延迟工具，带 parameters
+ *  - ToolManager.listRegisteredTools()        → 非延迟内置工具（不在延迟索引里）
+ *  - McpManager.getConnectedServers()         → 补"已连接但尚无工具"的空分组
+ *
+ * **无状态**：每次 collect 现采、不缓存。理由见 protocol 里 ReplCatalogSource 的注释。
+ */
+import type { Session } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { CliRuntimeOptions } from '../../cli/cli-runtime-options';
+import { AgentScopedMcpManager, McpManager } from '../../mcp/mcp-protocol';
+import { ToolManager } from '../tool-protocol';
+import { ToolSearchService } from '../tool-search-protocol';
+import { AgentToolDeferOverlayCache } from '../tool-spec';
+import { REPLCatalog, ReplCatalogSource } from './repl-catalog-protocol';
+/**
+ * 所有 MCP server 的 sandbox global 统一加 `mcp_` 前缀（§4.7，常量定义在 protocol）。
+ * 与内置工具 / 基础设施（Bash、Read、REPL、tools…）彻底隔离，骨架目录里
+ * 看到 `mcp_xxx:` 就能照抄。canonical 全名（mcp__server__tool）不受影响。
+ * worker 侧 `INFRA_GLOBALS` 仍是第二道防线，防止漏改名的 catalog 顶掉 SDK。
+ */
+export declare class ReplCatalogSourceImpl implements ReplCatalogSource {
+    protected readonly logger: Logger;
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly toolManager: ToolManager;
+    protected readonly overlayCache: AgentToolDeferOverlayCache;
+    protected readonly mcpManager?: McpManager;
+    protected readonly agentScopedMcpManager?: AgentScopedMcpManager;
+    protected readonly cliRuntimeOptions?: CliRuntimeOptions;
+    /**
+     * @param opts.sandboxAgentName 采集用的**沙箱身份**覆盖（缺省按 session 推）。
+     *   Code Mode 的 REPL 工具 schema 在 agent 构建期物化，那一刻用的是合成会话（没有子会话身份），
+     *   继承模式的子代理就会拿到「模式的全量目录」而不是自己的白名单。派发侧知道子代理身份，
+     *   经此显式传入（见 AgentManager.sandboxScopedAgentView）。运行时路径（broker / worker）
+     *   仍然按 live session 推，不受影响。
+     */
+    collect(context: RunContext<Session>, opts?: {
+        sandboxAgentName?: string;
+    }): Promise<REPLCatalog>;
+    /**
+     * 构建期兜底：当 live session 未携带 `--tools`（agent 构建早于会话建立，
+     * getCurrent() 为 undefined）时，用进程级 CliRuntimeOptions 的 `--tools`
+     * 合成一个带 options.tools 的 context，交给 getAllowedToolsForAgent 走同一套
+     * 白名单解析。
+     *
+     * 优先级与 ToolManager.resolveSessionToolContext 对齐：live session 已有
+     * options.tools 时**不覆盖**（它是权威值）；仅在缺失时才回退到 CLI 快照。
+     * 未装配 CliRuntimeOptions（headless/单测）或无 `--tools` 时原样返回。
+     */
+    private contextWithCliTools;
+    private ensureGroup;
+    private appendEmptyServerGroups;
+    /**
+     * 采集全部 MCP server 的配置，建立 serverName → McpConfig 映射，供 repl_expose 判定用。
+     * 失败时返回空 map —— 白名单默认 false，等价于"任何 MCP 都不暴露给沙箱"，安全兜底。
+     */
+    private collectServerConfigs;
+    /**
+     * repl_expose 白名单判定（仅约束 MCP 工具，内置工具不走此路径）。
+     * 只认 server 级：显式 repl_expose:true 才暴露，其余（含未配置）一律默认 false。
+     */
+    private isReplExposed;
+    private toBuiltinTool;
+    /**
+     * 整工具级 deny 规则命中的**内置**工具名集合（MCP 由调用方按单名逐个判）。
+     *
+     * 与 `AgentManager.isToolDisallowed` 严格同口径：匹配时**带上 aliases**——
+     * `--disallowed-tools read` 要能同时命中 LSP / BashOutput 等把 `read` 声明为
+     * 别名的工具（isToolDisallowed 用的是 `[toolName, ...aliases]`）。
+     *
+     * 无任何 deny 规则时立刻返回，避免为绝大多数会话白跑一遍 O(工具数×规则数)。
+     */
+    private collectWholeToolDenyNames;
+    private toMcpTool;
+    /** 裸名 MCP 工具没有 serverName 也不带 mcp__ 前缀，此时返回 undefined 归入 builtin 段。 */
+    private serverNameOf;
+    /**
+     * 内置工具的 agent 白名单判定：与 ToolSearchService.isAllowedByAgentTools 同口径
+     * （MCP 工具豁免，内置工具必须显式启用）。
+     */
+    private isAllowedBuiltin;
+    /**
+     * PTC 跳过直连白名单之后，仍要过工具自己的 isEnabled。
+     * 否则 WorkBuddy 的沙箱骨架会列出 SpeakInChannel / MessageColleague。
+     */
+    private isSandboxToolEnabled;
+    /**
+     * 归一化成 JSON Schema。三种入参形态都要处理：
+     *  - 已是 JSON Schema 对象 → 原样
+     *  - zod schema → `zodToJsonSchema`
+     *  - **函数**（`parameters(): ZodTypeAny` / `async () => ...`）→ 先调用再转
+     *
+     * 第三种必须处理：`ToolManager.init()` 对函数式 `parameters` **刻意跳过**转换
+     * （留给 `get()` 时动态生成），而这里走 `listRegisteredTools()` 拿的是原始 toolMap，
+     * `parameters` 仍是函数。漏掉它会让 Bash / PowerShell / Agent / StructuredOutput
+     * 在骨架目录里渲染成无参的 `Bash()` —— 而 Bash 恰是价值最高的工具。
+     *
+     * 函数必须带 `thisArg`：Agent 的 `parameters()` 是 `return this.buildParametersSchema()`，
+     * 抽成裸 `()` 调用会在 strict 下把 schema 打成 `{}`。
+     */
+    private asJsonSchema;
+}

package/cli/dist-server/types/node/tools/repl/repl-import-rewrite.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 预处理用户 REPL 代码,在包进 async-IIFE 之前用 acorn 做两趟变换:
+ *   1. 动态 import(x) → __replImport(x)(bridge resolver 全局;Bun 的 vm.SyntheticModule 有 bug,只能源码改写)。
+ *   2. 顶层声明提升 + 末尾表达式 → return:
+ *      - const/let/var/function/class 改写成对持久 vm.Context 的 global 赋值,让变量跨 cell 存活
+ *        (kernel/cell 模型的关键——否则 IIFE 一结束声明就没了,`const x = 5` 下个 cell 就读不到);
+ *      - 最后一条裸表达式前缀 `return`,所以 `return` 和末尾表达式两种写法都能拿到结果。
+ *
+ * 变换后由 manager 包进 (async () => { ... })()。顶层 await/return 落进这个 async 函数;顶层声明已经被改成
+ * 对 global 的 bare 赋值——非严格模式下 bare 赋值写到 vm.Context 的 global,于是跨 cell 持久。
+ */
+/** import() → __replImport() + 顶层声明提升到 global + 末尾表达式 → return。解析失败则原样返回(交给 vm.Script 报错)。
+ *
+ * async：内部走 acorn/acorn-walk lazy chunk（standby 不 parse）；本函数是 hot path
+ * 上唯一使用者。caller `repl-worker-manager.executeCell` 在 async 上下文，加 await 即可。
+ */
+export declare function transformReplCode(source: string): Promise<string>;

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

@@ -0,0 +1,210 @@
+/**
+ * REPL / code-mode 平台契约(接口级)。
+ *
+ * 设计见 docs/repl-code-mode/architecture.md。
+ * 核心:
+ *  - 模型只见 1 个 REPL 工具;内部经 `await import("@wb/...")` 拿桥门面。
+ *  - vm 在 agent-cli 的常驻 node worker 里跑(starved,无 seatbelt);能力在 WorkBuddy。
+ *  - agent-cli 只认 BridgeHost 三方法 SPI,零业务、不硬编码任何桥。
+ */
+import type { Session } from '../../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '@openai/agents';
+import type { BridgeEntry, SearchToolsOptions, ToolDescriptor, ToolSearchHit } from './repl-catalog-protocol';
+export type { BridgeEntry, SearchToolsOptions, ToolDescriptor, ToolSearchHit };
+/** 模型 import 一个桥时得到的 API 描述符(→ 生成门面 + documentation())。 */
+export interface BridgeApiDescriptor {
+    /** 桥标识,如 "@wb/browser"。 */
+    specifier: string;
+    version?: string;
+    /** 顶层导出名,如 ["browser", "default"]。门面按此生成。 */
+    exports: string[];
+    /** 模型面文档(声明式生成或整段字符串);门面的 documentation() 返回它。 */
+    documentation: string;
+    /** 可选:方法/签名声明,用于更严格的门面/校验;不给则门面走全通 Proxy。 */
+    methods?: Array<{
+        path: string;
+        signature: string;
+        doc?: string;
+    }>;
+}
+/** 一次桥方法调用(门面 → broker → BridgeHost)。 */
+export interface BridgeInvokeRequest {
+    specifier: string;
+    /** 方法路径,如 "page.click" / "cua.computer.click"。 */
+    method: string;
+    args: unknown[];
+    /** 归属哪个 REPL 调用(取消/关联)。 */
+    callId: string;
+    /** 归属哪个会话(WorkBuddy 侧定位浏览器/桌面上下文)。 */
+    sessionRef: string;
+}
+/** broker 收到的一次调用(worker 不知道 sessionRef,由 broker 补)。 */
+export type BridgeInvokeOp = Omit<BridgeInvokeRequest, 'sessionRef'>;
+/** 多模态图片内容(data URL 或远端 URL)。 */
+export interface BridgeImage {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+}
+/** 桥调用结果。截图等作为 value 内联返回({ $media, data } 或 image_url 块),由模型 return 出去渲染。 */
+export interface BridgeResult {
+    ok: boolean;
+    /** 结构化返回值(需可结构化克隆)。 */
+    value?: unknown;
+    error?: string;
+}
+/** 单次桥调用的取消/超时控制(随 cell 预算,不写死)。 */
+export interface BridgeCallOpts {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /**
+     * 本次内层工具所属外层 REPL 的 tool-call id（UI function_call_group 的 callId）。
+     * 由 worker-manager 从当前 ActiveRun 显式透传，供 Hook 展示归属到正确的外层 REPL。
+     * 不走 Session 全局标量：多个外层 REPL 交错时标量会串位/清空（见 #124851 评审）。
+     */
+    replParentCallId?: string;
+}
+/**
+ * BridgeHost —— agent-cli 只认这三个方法,零业务知识。
+ * WorkBuddy 侧实现它;资源布局/加载/结构对 agent-cli 完全透明。
+ */
+export declare const BridgeHost: unique symbol;
+export interface BridgeHost {
+    /** 发现:当前可用的 specifier 列表(可选;可懒——先不给 descriptor)。 */
+    listBridges(): Promise<string[]>;
+    /** 解析:模型 import 时拿描述符;null = 不可用。WorkBuddy 可在此才真正 load 桥代码。 */
+    resolveBridge(specifier: string): Promise<BridgeApiDescriptor | null>;
+    /** 调用:门面方法落点。agent-cli 在调用前已过权限;此处只执行。opts 携带 cell 的超时/abort。 */
+    invokeBridge(req: BridgeInvokeRequest, opts?: BridgeCallOpts): Promise<BridgeResult>;
+}
+/** 一次 REPL 执行的结果。 */
+export interface CellResult {
+    ok: boolean;
+    result?: unknown;
+    /** Worker-side transfer budget truncated the structured return value. */
+    resultTruncated?: boolean;
+    stdout: string;
+    stderr: string;
+    images: BridgeImage[];
+    error?: string;
+    /**
+     * 输出超阈值且完整内容已落盘（OutputSpiller）时的落盘信息。
+     *
+     * 存在即表示模型面 content 应收敛为 `<persisted-output>` 占位符（与 Bash 截断路径
+     * 对齐）：模型拿 2KB 预览 + 文件路径，完整输出留在磁盘供 Read 读取，避免跨轮重复
+     * 发送全量结果撑爆上下文。
+     */
+    persisted?: {
+        callId: string;
+        filePath: string;
+        totalBytes: number;
+    };
+}
+/**
+ * REPL cell 执行中的进度快照（流式上报用）。
+ *
+ * duration 一律由消费方用 `Date.now() - startedAt` 算 —— `startedAt` 是 cell 启动的
+ * 固定墙钟，保证运行时长单调递增（不像内部子工具各自从 0 计时那样反复重置）。
+ */
+export interface ReplProgressSnapshot {
+    /** cell 启动的墙钟时刻（固定基准）。 */
+    startedAt: number;
+    /** 截至当前的累积 stdout 快照。 */
+    stdout: string;
+    /** 截至当前的累积 stderr 快照。 */
+    stderr: string;
+    /** 最近一次子工具调用标识（如 `Bash` 或 `Bash · sleep 5`）。 */
+    lastTool?: string;
+}
+export interface REPLRunOptions {
+    timeoutMs: number;
+    signal?: AbortSignal;
+    /**
+     * cell 执行中的进度回调：每秒一次（对齐 bash 的 startStreamingUpdates），以及每次
+     * 收到 worker 的 output / toolCall 消息时即时触发一次。上层据此推 UI 聚合流式。
+     */
+    onProgress?: (snapshot: ReplProgressSnapshot) => void;
+    /**
+     * 本次外层 REPL 的 tool-call id（与 UI function_call_group 一致）。worker-manager 存到
+     * ActiveRun，并在每次内层 toolCall 时透传给 broker，用于内层 Hook 的展示归属。
+     */
+    replCallId?: string;
+}
+/**
+ * 每 session 一个常驻 node worker(= cell,状态跨调用存活)的管理者。
+ * `run` get-or-spawn worker → post exec → await done。
+ */
+export declare const REPLWorkerManager: unique symbol;
+export interface REPLWorkerManager {
+    /**
+     * 收 `RunContext<Session>` 而非 `Session`:发现类 broker 方法需要 RunContext 才能拿
+     * agent 工具白名单(`getAllowedToolsForAgent`),且 RunContext 无法从 Session 反推。
+     * 见 docs/repl-code-mode/mcp-code-mode-design.md §4.3.3 易漏点 ①。
+     */
+    run(context: RunContext<Session>, code: string, opts: REPLRunOptions): Promise<CellResult>;
+    /** 协作取消(hard=true → worker.terminate() 硬杀失控 async)。 */
+    abort(session: Session, callId: string, hard?: boolean): void;
+    /** session 结束/闲置:拆 worker。 */
+    dispose(session: Session): Promise<void>;
+}
+/**
+ * BridgeBroker —— worker 的 resolve / bridgeOp / toolCall / replApi 落点(主线程)。
+ *
+ * 三条分流:
+ *  - 工具调用 `callTool` → 主动 checkPermission → DeferExecuteTool 两条现成路由
+ *  - 工具发现 `searchTools` / `describeTool(s)` → ToolSearchService(只读,不过权限)
+ *  - 外部桥 `resolve` / `invoke` → BridgeHost
+ *
+ * 批准在 REPL 工具层(整段 code 批一次);发现类是只读元数据查询,把关的是可见性而非权限。
+ */
+export declare const REPLBridgeBroker: unique symbol;
+export interface REPLBridgeBroker {
+    resolve(session: Session, specifier: string): Promise<BridgeApiDescriptor | null>;
+    invoke(session: Session, op: BridgeInvokeOp, opts?: BridgeCallOpts): Promise<BridgeResult>;
+    /**
+     * 工具调用。**主动**跑 `checkPermission` 再执行——REPL 的 toolCall 不经 AgentService,
+     * 不主动跑则 deny rules 与命令安全检查全部被绕过。
+     * 被拒时返回 `{ error }` 而不 throw(§4.8)。
+     */
+    callTool(context: RunContext<Session>, toolName: string, params: Record<string, unknown>, opts?: BridgeCallOpts): Promise<{
+        result?: unknown;
+        error?: string;
+    }>;
+    /** BM25 检索。发现类方法一律收 RunContext(agent 白名单需要它)。 */
+    searchTools(context: RunContext<Session>, query: string | string[], opts?: SearchToolsOptions): Promise<ToolSearchHit[]>;
+    /** 单个工具完整 schema;未知返回 null（**不做 fuzzy fallback**）。 */
+    describeTool(context: RunContext<Session>, name: string): Promise<ToolDescriptor | null>;
+    /** 精准批量（≤ REPL_DESCRIBE_TOOLS_MAX 条），不是全量拉取。 */
+    describeTools(context: RunContext<Session>, names: string[]): Promise<Record<string, ToolDescriptor | null>>;
+    /** 外部桥目录（需 import 后用，与工具发现隔离）。 */
+    listBridges(session: Session): Promise<BridgeEntry[]>;
+}
+/**
+ * REPL 桥传输 = 一条**本地 socket / 命名管道**(Unix domain socket / Windows 命名管道),
+ * 0600 owner-only + token 授权,零端口。
+ *
+ * spawn agent-cli 的一方(如 WorkBuddy)通过 env 传入**管道路径** + **授权 token**:
+ *   - `CODEBUDDY_REPL_HOST_PIPE_PATH`:mac/linux = Unix domain socket 路径;Windows = 命名管道 `\\.\pipe\...`。
+ *     Node `net.connect(path)` 对两者透明,由提供方按平台给正确的 path → agent-cli 代码天然跨平台。
+ *   - `CODEBUDDY_REPL_HOST_TOKEN`:随每次请求带上,提供方校验(Windows 命名管道无 Unix peer creds,用 token 通用)。
+ *
+ * 协议:一次连接一次请求——agent-cli 写 `<json>\n`,读 `<json>\n`。agent-cli 不认提供方身份、不做发现、
+ * 不走 MCP 工具。**零端口。** 未配置 = 无桥。
+ */
+export declare const REPL_HOST_PIPE_ENV = "CODEBUDDY_REPL_HOST_PIPE_PATH";
+export declare const REPL_HOST_TOKEN_ENV = "CODEBUDDY_REPL_HOST_TOKEN";
+/**
+ * REPL 总闸 env。开启 code-mode(REPL 工具暴露 + 骨架目录注入)的唯一开关。
+ * 单一实现放协议层,供 REPLTool(isEnabled / 骨架渲染)与 AgentManager(首轮
+ * MCP prewait 判定)复用,避免各处内联 env 判定漂移。
+ */
+export declare const REPL_ENABLED_ENV = "CODEBUDDY_REPL_ENABLED";
+export declare function isReplEnabled(agentName?: string, session?: {
+    meta?: Record<string, unknown>;
+    agentName?: string;
+}): boolean;
+/** REPL 工具入参上限:默认 60s,上限 600s。 */
+export declare const REPL_DEFAULT_TIMEOUT_MS = 60000;
+export declare const REPL_MAX_TIMEOUT_MS = 600000;
+export declare function clampReplTimeout(ms?: number): number;

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

@@ -0,0 +1,142 @@
+/**
+ * REPLTool —— 模型面唯一入口:写 JS、import WorkBuddy 桥来编排。
+ *
+ * 见 docs/repl-code-mode/architecture.md。
+ * - 暴露面:1 个工具;能力经 `await import("@wb/...")` 桥,不做直连工具、暂不给 tools.*。
+ * - 执行委托 REPLWorkerManager(每 session 常驻 kernel = cell,状态跨调用存活)。
+ * - 高权限:能触达桥,needsApproval=true;必须投影 code 给 auto 分类器(否则静默放行)。
+ * - feature-gate:CODEBUDDY_REPL_ENABLED。
+ */
+import { Session, type SessionManager as ISessionManager } from '../../../vendor/cbc-core/node/index.js';
+import { type 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 { ToolResultBlobService } from '../../blob-store/tool-result-blob-service';
+import { BaseTool } from '../base-tool';
+import { type ShellStreamPusherService } from '../shell-stream-pusher';
+import { Tool, ToolCallArgumentRenderer, ToolManager, ToolResult } from '../tool-protocol';
+import { ReplCatalogSource } from './repl-catalog-protocol';
+import { REPLWorkerManager } from './repl-protocol';
+/**
+ * `parameters()` 收到的 agent 配置。除产品字段外多一个 CLI 内部注记：
+ *
+ * `sandboxAgentName` —— 沙箱目录（骨架）按哪个身份收窄。Code Mode 的 agent 实例是
+ * **进程级共享**的（`agentManager.get('ptc')` 命中的是同一个对象），schema 在构建期物化时
+ * 用合成会话采集，拿不到「这一轮是谁在跑」；继承模式的子代理（Explore 等）就会看到模式
+ * 的全量目录。派发侧知道子代理身份，经本字段显式传入（见 AgentManager.sandboxScopedAgentView）。
+ * 不是产品配置字段，只为 REPL 的动态 schema 服务。
+ */
+interface ReplParametersAgentConfig {
+    name?: string;
+    sandboxAgentName?: string;
+}
+/**
+ * 入参形状。运行时 schema 由 `parameters()` 动态生成（要把骨架目录拼进 code 描述），
+ * 这里只声明 `execute` 的入参类型——两处字段必须保持一致。
+ */
+interface ReplToolInput {
+    code: string;
+    timeout?: number;
+    description?: string;
+}
+export declare class REPLTool extends BaseTool implements Tool {
+    protected readonly logger: Logger;
+    protected readonly shellStreamPusher: ShellStreamPusherService;
+    protected readonly workers: REPLWorkerManager;
+    protected readonly catalogSource: ReplCatalogSource;
+    protected readonly sessionManager?: ISessionManager;
+    protected readonly toolManager?: ToolManager;
+    protected readonly toolResultBlobService?: ToolResultBlobService;
+    name: ToolNames;
+    readonly promptCacheStability: "volatile";
+    description: string;
+    /**
+     * 动态 schema：把骨架目录注入 `code` 参数描述，让模型写 code 前就知道有哪些工具
+     * 及其参数形状（一次写对、不盲写）。ToolManager.get() 在 parameters 是函数时会
+     * 调用它并转成 JSON Schema，且把正在构建的 agent 传进来。
+     *
+     * **异常必须自吞**：ToolManager 对 parameters() 抛错的兜底是把 parameters 置为
+     * undefined，那对 REPL 是灾难（没有 code 参数就完全不可用）。所以采集失败一律
+     * 降级为"无目录但可用"。
+     *
+     * `agentConfig.sandboxAgentName`（CLI 内部注记）会把骨架目录按子代理身份收窄 ——
+     * 共享模式 agent 实例的 schema 本来分不清「谁在跑」，见该字段的说明。
+     */
+    parameters: (agentConfig?: ReplParametersAgentConfig) => Promise<z.ZodTypeAny>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (args?: unknown) => Promise<boolean>;
+    /** 必须 override:REPL 能跑桥(含高权限),auto 模式不能静默放行。投影 code 给分类器。 */
+    toAutoClassifierInput(input: unknown): string;
+    resolveNeedPermissionArgs(_rc: RunContext, input: unknown): ToolArg[];
+    execute(input: ReplToolInput, context?: RunContext<Session>, details?: {
+        toolCall: FunctionCallItem;
+    }): Promise<ToolResult>;
+    /**
+     * details.toolCall.callId 缺失时（部分非交互路径），从 session.history 倒序反查本次 REPL
+     * function_call 的 callId——对齐 bash 的 findCallId。拿到与 UI 侧 function_call_group 一致
+     * 的 callId，流式进度帧才能就地并入同一条工具结果，而不是在对话流里堆积孤立行（issue #101579）。
+     * 用 code 精确匹配，避免命中同一会话里更早的 REPL 调用。
+     */
+    private findReplCallId;
+    /**
+     * 推一条聚合流式进度到 UI（复用 bash 的 `function_call_result` + `isStreaming` 模式，
+     * 不新增 sessionUpdate 类型）。用外层 REPL tool-call 的 callId + 固定 resultId，
+     * use-message-groups 据此就地更新同一条 in_progress 结果；运行时长由固定 startedAt
+     * 算，单调递增，天然取代内部子工具那种各自从 0 反复重置的孤立条目。
+     */
+    private emitStreaming;
+    /**
+     * 渲染骨架目录。**必须自吞全部异常并返回空串**——见 parameters 的注释。
+     *
+     * 总闸 `CODEBUDDY_REPL_ENABLED` 关闭时直接短路。`isEnabled` 只把工具从 LLM tools
+     * 列表里剔除，管不到这里：`parameters` 是动态函数，ToolManager 构建 agent tools 时
+     * **无条件** `await tool.parameters()`（tool-manager.ts:396-404）。不短路的话，总闸
+     * 关着也会为一个永不暴露给模型的工具跑一遍全量目录采集。
+     *
+     * 细闸 `CODEBUDDY_REPL_TOOLS_INJECT_CATALOG=0`（或 `false`）可单独关掉目录注入（工具仍
+     * 预加载，只是模型不提前知情，退化为纯渐进披露）。默认开启。
+     *
+     * 另有 `CODEBUDDY_REPL_TOOLS_INJECT_BUILTIN` 控制**内置工具**是否加载到 REPL
+     * （PTC/Minimal 默认开，其余模式默认关；`1`/`0` 强开强关）。控制点在
+     * ReplCatalogSource.collect（关闭时 catalog.builtin 为空，骨架目录与 sandbox
+     * 注入同时不含内置工具），不在本方法。
+     */
+    private renderSkeleton;
+    /**
+     * Code Mode 对齐标准模式的技能注入：标准模式的 `<available_skills>` 目录长在
+     * Skill 工具描述里；Code Mode 模型面只有 REPL、骨架每行摘要只截 80 字符，
+     * 目录会整体丢失。这里把 ToolManager 渲染的完整 Skill 描述（同一份字符预算 /
+     * skillOverrides 逻辑）附到 code 参数描述末尾，token 成本与标准模式等价。
+     *
+     * 与 catalog.collect 分开：骨架摘要每行只截 80 字符，技能列表会丢掉。
+     * 即使当前会话不是 Code Mode（正在 freeze ptc agent），只要
+     * specForReplParameters 认成 PTC/Minimal，也要把完整 Skill 描述打进去。
+     */
+    private renderSkillCatalogSection;
+    /** ACP 在 ALS 外 getCurrent 会抛；不能让整个 parameters() 失败。 */
+    private currentSessionSafe;
+    /**
+     * ToolManager ↔ REPL 循环依赖时 @Optional 注入会是 undefined。
+     * parameters() 在所有组件装配之后才跑，这时再懒取一次。
+     */
+    private resolveToolManager;
+    /**
+     * 完成态工具结果。
+     * - `content`：模型面结构化 JSON（`buildReplToolContent`，含 result/stdout/stderr[/images]）。
+     *   输出超阈值且已落盘时收敛为 `<persisted-output>` 占位符（2KB 预览 + 文件路径），
+     *   与 Bash 截断路径对齐——完整内容留在磁盘供 Read，避免跨轮重复发送全量结果。
+     * - `renderer.value`：人面展示。**不再显示 "ok"**——改为「耗时置顶 + 执行详情」：
+     *   耗时用 `formatTurnDuration`（"50s" / "1m 05s"，无 "ago"）置于首行且始终可见
+     *   （不被折叠吃掉）；执行详情（`buildReplDisplayText`）在下方，超 DEFAULT_DISPLAY_ROWS
+     *   自动折叠，`ctrl+o` 展开完整详情——与 bash 的结果行体验一致。
+     */
+    private toToolResult;
+    /**
+     * REPL 输出超阈值且完整内容已落盘时，把模型面 content 换成 `<persisted-output>` 占位符。
+     * 与 Bash buildForegroundResult 的 externalizeFromSpillFile 路径对齐；占位失败
+     * （service 缺失/异常）时保留截断文本兜底。
+     */
+    private externalizeReplOutput;
+}
+export {};

package/cli/dist-server/types/node/tools/repl/repl-worker-manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * REPLWorkerManager 实现(checkpoint 2b:常驻 Bun worker,perf/错误隔离)。
+ *
+ * - 每个 session 一个常驻 worker = kernel,里面一个持久 vm.Context = cell,状态跨多次 run 存活。
+ * - worker 建在 @genie/cbc-worker 的 kit 上(rpc + 加固 realm),只用 builtins;acorn 的 import() 改写在主线程做好再发进去。
+ * - 主线程侧是 @genie/cbc-worker 的 WorkerHost:exec 是带 rid 的请求,__replImport / facade / 工具调用是
+ *   worker → host 的请求,经 inSession 落在会话的 rootScope 里 → broker.resolve / broker.invoke / broker.callTool。
+ *   帧见 repl-worker-protocol.ts。心跳只在没有 active cell 时计缺失(cell 同步占线程时 pong 发不出来)。
+ * - lifecycle:cell 超时/取消只结束这次 cell(abort 它在途的 bridge 调用让它 unwind),kernel 和状态都留着;
+ *   只有 worker 崩溃/退出,或 hard abort(= reset),才销毁 worker、下次 run 重建。像 Jupyter / node_repl 的 kernel。
+ *
+ * 见 docs/repl-code-mode/architecture.md。
+ */
+import { Session } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { ToolResultBlobService } from '../../blob-store/tool-result-blob-service';
+import { ToolSearchService } from '../tool-search-protocol';
+import { ReplCatalogSource } from './repl-catalog-protocol';
+import { CellResult, REPLBridgeBroker, REPLRunOptions, REPLWorkerManager } from './repl-protocol';
+export declare class REPLWorkerManagerImpl implements REPLWorkerManager {
+    protected readonly logger: Logger;
+    protected readonly broker: REPLBridgeBroker;
+    protected readonly catalogSource: ReplCatalogSource;
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly toolResultBlobService?: ToolResultBlobService;
+    private readonly workers;
+    private callSeq;
+    run(context: RunContext<Session>, code: string, opts: REPLRunOptions): Promise<CellResult>;
+    /** 取消当前 cell:软取消(默认)结束这次 cell、保留 kernel;硬取消(hard=true)销毁 worker,下次 run 重建(= reset)。 */
+    abort(session: Session, _callId: string, hard?: boolean): void;
+    dispose(session: Session): Promise<void>;
+    /**
+     * 记一次 bridge 交互的起讫,驱动 idle 超时:发起 inflightBridges++,结算 --并刷新 lastBridgeActivity。
+     * 有在途调用(inflightBridges>0)idle 就续期,故 AskUserQuestion 等用户、长任务在途都不会被超时打断。
+     * active 用发起时捕获的引用——即便结算时 cell 已被换,写旧 active 也无副作用(其计数已无人读)。
+     */
+    private withBridgeActivity;
+    private ensureWorker;
+    /**
+     * 把当前工具集同步进 sandbox。
+     *
+     * 首次是全量 `init`；之后 `(epoch, 能力指纹)` 变了才推 `toolsUpdate` 增量。cell 执行中到达的
+     * 变更排队到 `done` 之后（见 flushPendingTools）——否则模型 code 跑到一半时
+     * `const g = github` 脚下的对象会被换掉。
+     *
+     * 为什么键里要有能力指纹：工具可见性不止由索引/overlay 版本决定（房间类工具还要看
+     * Agent Home 表面 / 身份 / 已加入频道），那些变化不推进任何 epoch。只比 epoch 会让新
+     * 加入频道的会话永远拿不到 SpeakInChannel（见 repl-sandbox-capability 头注释）。
+     */
+    private syncTools;
+    /** cell 结束后补推排队的工具变更。 */
+    private flushPendingTools;
+    /**
+     * 推一次进度快照给本次 run 的 onProgress。
+     *
+     * 带 `callId` 校验：进度定时器/异步消息可能在 cell 已被 abandon（超时/取消）或换成
+     * 下一次 run 之后才触发，此时 entry.active 已是别的 cell 或 undefined，不能误推。
+     * 回调异常一律吞掉——UI 侧问题绝不能影响 cell 执行。
+     */
+    private emitProgress;
+    private postCatalog;
+    private bindWorkerHandlers;
+    /** 发现类 API 分流。只读，不过权限判定（把关的是可见性，见 §4.8）。 */
+    private dispatchReplApi;
+    /**
+     * exec 回执的 async 收尾：只认当前 cell（被 abandon 的旧 cell 的回执已被 WorkerHost 丢弃，
+     * callId 不符的也直接丢，别误清新 cell 的 active）。
+     *
+     * 在 settle 前把 spill 文件收口（追加 result 文本 + 判定截断），这样上层拿到
+     * CellResult.persisted 时文件已完整可读。
+     */
+    private handleDone;
+    /** 被放弃 cell 的 continuation 终于 unwind 完：worker 已自行收尾，取消宽限、不必 terminate，kernel 状态保留。 */
+    private onUnwound;
+    /** 执行期把完整 stdout/stderr 流式落盘（懒创建：无输出的 cell 不产生文件）。 */
+    private pushSpill;
+    /**
+     * 收尾本次 run 的 spill 文件：
+     * 1. 把完整 result 文本追加进文件（模型面只剩 head/tail 时，完整内容留给 Read）；
+     * 2. 关闭文件流；
+     * 3. 任一 buffer 截断且落盘成功 → 返回 persisted（上层把模型面收敛为占位符）；
+     *    未截断 / 落盘失败 → 删除临时文件，不产生垃圾。
+     *
+     * result 截断判定与 buildReplToolContent 的 truncateReplResult 同口径
+     * （replResultToText 文本的 UTF-8 字节数超本次 run 的输出预算）。
+     */
+    private finalizeSpiller;
+    private createSpiller;
+    /** 中止/失败的 cell 不留落盘文件（内容不完整，Read 也没有意义）。 */
+    private cleanupSpiller;
+    /** cell 超时/软取消:让这次 cell 以错误结束,并 abort 它在途的 bridge 调用(cell 的 await 会抛错、自行 unwind);
+     *  worker(= kernel)保留,vm.Context 里的状态不丢——像 Jupyter / node_repl 那样。真卡死(CPU 打满)时靠 hard abort 重建。 */
+    private abandonCell;
+    /** 起 unwind 宽限；到期 worker 仍未发回 unwound 就 terminate 重建。 */
+    private armAbandonGrace;
+    /** 清 unwind 宽限计时器（收到 unwound / hard abort / 崩溃时调用；不动 abandonedCallId）。 */
+    private clearGrace;
+    /** 失败当前运行(崩溃/退出/dispose);active 的 promise 以错误态 settle，并清理 abandon 宽限。 */
+    private failActive;
+    /** 销毁 worker(崩溃/退出,或 hard abort / reset)并下线;下次 run 重建。 */
+    private killWorker;
+}

package/cli/dist-server/types/node/tools/repl/repl-worker-source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * REPL worker source string for `new Worker(src, { eval: true })`.
+ *
+ * The worker is authored as TypeScript in `./worker/repl-worker.ts` and bundled by
+ * `scripts/gen-repl-worker-source.mjs` (vite) into `./repl-worker-source.generated.ts`.
+ * This module only re-exports the generated constant so the import path stays stable.
+ *
+ * Why a string constant rather than a worker file:
+ *   - agent-cli ships as a Bun single-file executable; there is no worker file to point at.
+ *   - A string is opaque to rspack, so the worker's own `require` calls are never rewritten.
+ *   - An inline worker inside the SFE has no node_modules, so the worker uses Node builtins
+ *     only; acorn's import() rewrite runs on the main thread before the code is sent in.
+ *
+ * Protocol and sandbox rules are documented at the top of `./worker/repl-worker.ts`.
+ */
+export { REPL_WORKER_SOURCE } from './repl-worker-source.generated';

package/cli/dist-server/types/node/tools/repl/repl-worker-source.generated.d.ts

@@ -0,0 +1,2 @@
+/** Worker script for `new Worker(source, { eval: true })`. */
+export declare const REPL_WORKER_SOURCE: string;