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

package/cli/dist-server/types/node/tools/produced-artifact-report.d.ts

@@ -0,0 +1,35 @@
+import { type ArtifactDeclarationOutcome } from './produced-artifact';
+/** Environment variable naming the report file for the current command. */
+export declare const ARTIFACT_REPORT_ENV = "CODEBUDDY_ARTIFACTS";
+export interface ArtifactReportLogger {
+    debug?: (message: string) => void;
+}
+/**
+ * Create this command's report file path and record it on `env`.
+ *
+ * The name carries pid, timestamp and a random suffix rather than the tool
+ * call id. Concurrent commands are isolated either way, but a call id
+ * originates from `details.toolCall.callId` — model-influenced input, which
+ * would need traversal checks before being spliced into a path. Random naming
+ * has no such exposure.
+ *
+ * Returns `undefined` when the directory cannot be created; callers treat that
+ * as "no channel this run" rather than failing the command, since a command
+ * that produces no artifacts is by far the common case.
+ */
+export declare function ensureArtifactReportPath(env: Record<string, string>): string | undefined;
+/**
+ * Read and delete this command's report file.
+ *
+ * Deletion happens even when parsing fails, so a stale file cannot leak into a
+ * later command that happens to draw the same path.
+ */
+export declare function readArtifactReport(reportPath: string | undefined, logger?: ArtifactReportLogger): ArtifactDeclarationOutcome;
+/**
+ * Drop the report file without reading it.
+ *
+ * Used when a run is voided and retried — sandbox escalation reruns the whole
+ * command, and the abandoned attempt's declarations must not survive into the
+ * result. The script re-appends on the retry, since `>>` recreates the file.
+ */
+export declare function discardArtifactReport(reportPath: string | undefined): void;

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

@@ -0,0 +1,55 @@
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { TerminalNotificationService } from '../notification/notification-protocol';
+import { 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 PushNotificationParameters: z.ZodObject<{
+    message: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    title?: string | undefined;
+}, {
+    message: string;
+    title?: string | undefined;
+}>;
+/**
+ * PushNotification 工具（issue #74424）——允许模型在长任务/后台任务/定时任务完成时
+ * 主动触发一次终端/桌面通知，填补现有通知机制的空白：`sendNotification` 目前只在
+ * PERMISSION_PROMPT（需要审批）和 IDLE_PROMPT（空闲 60 秒后）两种场景触发，模型自己
+ * 判断"任务刚完成、该提醒一下"这个时机是空白的。
+ *
+ * 默认开启（不同于 ComputerUse 默认关闭），可用 CODEBUDDY_PUSH_NOTIFICATION_ENABLED 覆盖。
+ *
+ * 不做企微/微信转发：这部分与已有的 WeComReply/WeChatReply 工具重叠（模型在 channel
+ * session 里会自己抢先调用它们），且转发目标依赖 session.meta 上的覆盖式单值字段
+ * （channelChatId 等），同一 session 同时连接多个渠道时只认最后联系过的那个，行为
+ * 不可预期，因此本工具只保留终端通知这一确定性的部分。
+ */
+export declare class PushNotificationTool extends BaseTool implements Tool {
+    protected readonly terminalNotificationService: TerminalNotificationService;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        message: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        title?: string | undefined;
+    }, {
+        message: string;
+        title?: string | undefined;
+    }>;
+    needsApproval: boolean;
+    private isPushNotificationEnabled;
+    isEnabled: (_args?: unknown) => Promise<boolean>;
+    /**
+     * 同步镜像 isEnabled 的 gate，用于 ToolSearch 延迟工具列表可见性过滤。
+     * gate 未开时不应出现在 "Available deferred tools" 描述里，避免模型误判此工具可用。
+     */
+    shouldShowInToolSearch: () => boolean;
+    execute(input: z.infer<typeof PushNotificationParameters>, context: RunContext<Session>): Promise<ToolResult>;
+}
+export {};

package/cli/dist-server/types/node/tools/read-file-state-service.d.ts

@@ -0,0 +1,27 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { ReadFileStateService } from './tool-protocol';
+/**
+ * Read-before-edit ledger. The ledger is conversation state — which files THIS
+ * session has read, and the mtime it saw — so each session resolved through
+ * the run-scope seam owns its own map, keyed by session identity and collected
+ * with it. The process-level map only backs contexts with no resolvable
+ * session (bin single-session modes) and keeps the legacy
+ * reset-on-session-switch semantics.
+ *
+ * File freshness goes through statPath, so a mounted sandbox answers before
+ * the host filesystem; sandbox stats missing mtime degrade to epoch, which
+ * this guard reads as never-modified.
+ */
+export declare class ReadFileStateServiceImpl implements ReadFileStateService, ApplicationLifecycle<Application> {
+    private readonly sessionLedgers;
+    private readonly processLedger;
+    initialize(): void;
+    readFile(filePath: string, fileStats: {
+        mtime: Date;
+    }): void;
+    hasBeenRead(filePath: string): boolean;
+    hasBeenModifiedSinceLastRead(filePath: string): Promise<boolean>;
+    refreshFile(filePath: string): Promise<void>;
+    private scope;
+    private normalize;
+}

package/cli/dist-server/types/node/tools/read-mcp-resource-tool.d.ts

@@ -0,0 +1,71 @@
+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 { McpResourceCatalogService } from '../mcp/mcp-resource-catalog-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 ReadMcpResourceParameters: z.ZodObject<{
+    server: z.ZodString;
+    uri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uri: string;
+    server: string;
+}, {
+    uri: string;
+    server: string;
+}>;
+type ReadMcpResourceInput = z.infer<typeof ReadMcpResourceParameters>;
+/**
+ * ReadMcpResource — read a single resource from a connected MCP server.
+ *
+ * Pairs with `ListMcpResources`. Mirrors the original `FetchMcpResource`
+ * read path; resource catalog is no longer baked into the description (use
+ * `ListMcpResources` to discover resources first). Issue #40458.
+ */
+export declare class ReadMcpResourceTool extends BaseTool implements Tool {
+    protected readonly mcpManager: McpManager;
+    protected readonly catalogService: McpResourceCatalogService;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    parameters: z.ZodObject<{
+        server: z.ZodString;
+        uri: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        uri: string;
+        server: string;
+    }, {
+        uri: string;
+        server: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    /** Read-only — no approval needed. */
+    needsApproval: boolean;
+    /**
+     * Enable the tool when a connected server declares the `resources`
+     * capability. Gating on a live listing instead made this tool vanish
+     * mid-session whenever one slow server timed out — see the longer note on
+     * `ListMcpResourcesTool.isEnabled` (issue #102572).
+     */
+    isEnabled: () => Promise<boolean>;
+    execute(input: ReadMcpResourceInput, _context: RunContext<Session>): Promise<ToolResult>;
+    /**
+     * Walk the contents array and convert each item into a model-friendly form:
+     *  - text items pass through as `{uri, mimeType, text}`
+     *  - binary blobs are decoded, written to `<cwd>/.mcp-resources/<random>.<ext>`
+     *    and surfaced as `{uri, mimeType, blobSavedTo, text}` where `text` is a
+     *    short hint pointing the model to the saved file.
+     */
+    private persistContents;
+    /**
+     * Decode a base64 blob and write it to `<cwd>/.mcp-resources/<random>.<ext>`,
+     * creating the directory on demand. Returns the absolute file path.
+     */
+    private persistBlob;
+    private errorResult;
+}
+export { ReadMcpResourceParameters };
+export type { ReadMcpResourceInput };

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

@@ -0,0 +1,71 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { ToolArg, ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { ImageBlobService } from '../blob-store';
+import { BaseTool } from './base-tool';
+import { ReadFileStateService, Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const ReadParameters: z.ZodObject<{
+    file_path: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, {
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
+export declare class ReadTool extends BaseTool implements Tool {
+    protected readonly workspace: Workspace;
+    protected readonly readFileStateService: ReadFileStateService;
+    protected readonly logger: Logger;
+    protected readonly imageBlobService: ImageBlobService;
+    name: ToolNames;
+    aliases: string[];
+    parameters: z.ZodObject<{
+        file_path: z.ZodString;
+        offset: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        file_path: string;
+        offset?: number | undefined;
+        limit?: number | undefined;
+    }, {
+        file_path: string;
+        offset?: number | undefined;
+        limit?: number | undefined;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    resolveNeedPermissionArgs(runContext: RunContext, input: z.infer<typeof ReadParameters>, callId?: string): ToolArg[];
+    /**
+     * Auto mode classifier projection: the file path (Claude alignment, decision
+     * D1). Read is in the read-only history set (dropped from history), so this is
+     * only consulted if Read is the current action being classified.
+     */
+    toAutoClassifierInput(input: unknown): string;
+    execute(input: z.infer<typeof ReadParameters>, context: RunContext<Session>): Promise<ToolResult>;
+    private validateToolParams;
+    private readFileContent;
+    private readFileContentStreaming;
+    private processFileContent;
+    private formatContentWithLineNumbers;
+    private readJupyterNotebook;
+    private formatJupyterNotebook;
+    /**
+     * 检查文件是否为图片文件
+     */
+    private isImageFile;
+    /**
+     * 读取图片文件并返回包含图片内容的 ToolResult
+     *
+     * 去重策略：同一 agent run 中相同内容的图片（相同 blob_id）只返回一次完整 base64，
+     * 后续重复读取返回文本占位符，避免向模型发送冗余的大体积图片数据。
+     */
+    private readImageFile;
+}
+export {};

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

@@ -0,0 +1,10 @@
+export * from './repl-protocol';
+export * from './repl-catalog-protocol';
+export * from './repl-catalog-render';
+export * from './repl-catalog-source';
+export * from './repl-import-rewrite';
+export * from './repl-worker-source';
+export * from './repl-bridge-broker';
+export * from './repl-bridge-host';
+export * from './repl-tool';
+export * from './repl-worker-manager';

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

@@ -0,0 +1,150 @@
+/**
+ * REPLBridgeBroker —— worker 的 toolCall / replApi / resolve / bridgeOp 落点(主线程)。
+ *
+ * 三条分流(见 docs/repl-code-mode/mcp-code-mode-design.md §4.1):
+ *  - 工具调用 callTool → 主动 checkPermission → 产品交互工具走 nested interruption，
+ *    其余 DeferExecuteTool.routeToolCall
+ *  - 工具发现 searchTools / describeTool(s) → ToolSearchService(只读,不过权限判定)
+ *  - 外部桥   resolve / invoke → BridgeHost
+ *
+ * agent-cli 对外部桥零业务:只认 BridgeHost SPI,不知道 browser/computer 具体是什么。
+ */
+import { InterruptionService, Session } from '../../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { AgentScopedMcpManager, McpManager } from '../../mcp/mcp-protocol';
+import { ToolManager } from '../tool-protocol';
+import { ToolSearchService } from '../tool-search-protocol';
+import { AgentToolDeferOverlayCache } from '../tool-spec';
+import { BridgeEntry, SearchToolsOptions, ToolDescriptor, ToolSearchHit } from './repl-catalog-protocol';
+import { BridgeApiDescriptor, BridgeCallOpts, BridgeHost, BridgeInvokeOp, BridgeResult, REPLBridgeBroker } from './repl-protocol';
+export declare class REPLBridgeBrokerImpl implements REPLBridgeBroker {
+    protected readonly logger: Logger;
+    protected readonly host?: BridgeHost;
+    protected readonly toolSearchService: ToolSearchService;
+    protected readonly toolManager: ToolManager;
+    protected readonly overlayCache: AgentToolDeferOverlayCache;
+    protected readonly mcpManager?: McpManager;
+    protected readonly agentScopedMcpManager?: AgentScopedMcpManager;
+    protected readonly interruptionService?: InterruptionService;
+    resolve(_session: Session, specifier: string): Promise<BridgeApiDescriptor | null>;
+    invoke(session: Session, op: BridgeInvokeOp, opts?: BridgeCallOpts): Promise<BridgeResult>;
+    listBridges(_session: Session): Promise<BridgeEntry[]>;
+    callTool(context: RunContext<Session>, toolName: string, params: Record<string, unknown>, opts?: BridgeCallOpts): Promise<{
+        result?: unknown;
+        error?: string;
+    }>;
+    private callProductInteractionTool;
+    /**
+     * 主动跑权限判定。**必须主动调**:REPL 的 toolCall 不经 AgentService,不调则
+     * deny rules 与命令安全检查全被绕过(模型可在 code 里写 Bash({command:"rm -rf /"}))。
+     *
+     * 拦截口径分两类:
+     *  - **deny**:恒拦(deny 规则 / --disallowed-tools / dontAsk 转 deny / auto 分类器 deny)。
+     *  - **危险操作的 ask**:命令安全检查(CRITICAL/HIGH/unsafe 命令,`type:'toolValidation'`)
+     *    与敏感文件访问(`type:'sensitiveFile'`)产出的是 `ask` 而非 `deny`。直连 Bash 会
+     *    对这类 ask 弹窗让用户拦下,但 REPL 内层不弹窗——若同 deny 一样只看 behavior,
+     *    模型把 `rm -rf` / 读 SSH key 包进 code 就能绕过这道安全确认(比直连更弱)。故这里
+     *    把安全类 ask 也视为拦截,回错误给沙箱(不 abort 父 REPL,模型可 r.error 改路)。
+     *
+     * 其余 ask(`strategy`/`default`/`mode` 等"该工具默认需审批")仍放行:用户已对整段
+     * code 批准过一次,不对 code 内每个普通工具重复打扰。见 §4.8。
+     *
+     * @returns 被拒时返回错误文案；通过返回 undefined。
+     */
+    private checkPermission;
+    /**
+     * 对齐直连：在核心权限判定为 ask 时触发 command PermissionRequest hook（与
+     * tool-permission-service.ts:631 同一入口 SessionHookManager.executePermissionRequestHooks）。
+     * broker 只调核心解析器 checkPermission(:107)，不经外层 needsApproval 包装，故这里补发。
+     * hook 可通过 hookSpecificOutput.decision 覆盖为 allow/deny；无表态时返回 undefined，
+     * 交回调用方按既有 PTC 安全门（安全类 ask 拦、普通 ask 放行）处理。suggestions 首版传 undefined。
+     */
+    private dispatchReplPermissionRequest;
+    /**
+     * checkPermission 自身异常时的 fail 方向。返回 true = 拒绝（fail-closed）。
+     *
+     * 只有同时满足以下三条才允许放行（fail-open）——即正常路径上 deny 无从产生：
+     *  1. 无任何 deny 规则（settings `permissions.deny` 各 scope + `--disallowed-tools`）；
+     *  2. 非 print 模式（`shouldAvoidPermissionPrompts` 会把未 allow 的工具默认 deny）；
+     *  3. 权限模式在白名单内：Default / AcceptEdits（ask 在 broker 本就不拦）、
+     *     BypassPermissions / FullAccess（用户显式全放行）。DontAsk（ask→deny）、
+     *     Auto（分类器可 deny）、Plan / Delegate / 未知模式一律 fail-closed。
+     */
+    private mustFailClosedOnPermissionError;
+    /**
+     * 本会话是否配置了任何 deny 规则（settings `permissions.deny` 各 scope +
+     * `--disallowedTools`）。口径与 ToolPermissionService Phase 1 的
+     * `allDenyRules = [...denyRules, ...disallowedTools]` 同源。
+     */
+    private hasAnyDenyRule;
+    searchTools(context: RunContext<Session>, query: string | string[], opts?: SearchToolsOptions): Promise<ToolSearchHit[]>;
+    describeTool(context: RunContext<Session>, name: string): Promise<ToolDescriptor | null>;
+    describeTools(context: RunContext<Session>, names: string[]): Promise<Record<string, ToolDescriptor | null>>;
+    private overlayOf;
+    /**
+     * `Defer(X)` overlay 命中的内置工具可能尚未索引（索引按 product 静态配置建）。
+     * 点名查只索引问到的那个；关键词搜索引全部精确条目。
+     * 通配条目（`Defer(mcp__*)`）不处理——模式反向枚举不出工具名，且 MCP 索引由
+     * mcp-manager 异步驱动。见 §4.3.3 易漏点 ③。
+     */
+    private ensureForceDeferIndexed;
+    /**
+     * 模型面名 → canonical 路由名。
+     * `mcp_github.list_prs` → `mcp__github__list_prs`；内置单段名原样返回。
+     * sandbox global 一律带 `mcp_` 前缀（§4.7），此处还原成真 server 名。
+     */
+    private toCanonicalName;
+    private toHit;
+    private toDescriptor;
+    /** 目录教 `mcp_github`，hit.server 仍是裸 id `github`，两边都认。 */
+    private matchesSearchServer;
+    private serverNameOf;
+    /**
+     * 沙箱内置工具的**有效白名单**：模式级列表（极简 Bash/Edit/Skill、PTC+overlay 协调器
+     * 白名单）与 agent / session `--tools` 白名单取交集；模式列表缺省（站立 PTC）= 上游
+     * 原样。与骨架目录（repl-catalog-source）共用 `intersectModeSandboxTools`，只收窄、
+     * 不放宽 —— 子代理继承模式后不能被模式列表放出自己定义里没有的工具。
+     *
+     * `undefined` = 上游「不过滤」（主会话 Code Mode 的常态）且无模式列表。
+     */
+    private sandboxBuiltinAllowlist;
+    /**
+     * 内置工具是否真的会出现在沙箱里：与骨架目录（repl-catalog-source）和 searchTools 同源，
+     * 都取 `getAllowedToolsForAgent`（它会 await 每个工具的 isEnabled），Code Mode 收窄时与
+     * `sandboxTools` **取交集**（模式列表只做收窄 —— 子代理继承模式后不能被它放出白名单外的工具）。
+     *
+     * MCP 工具不走这里（不在 agent.tools 里），由 isMcpToolAllowedForAgent / isMcpToolReplExposed 判。
+     * 白名单读取失败时放行，避免发现能力因一次 IO 抖动整体失效（执行层仍有自己的门）。
+     *
+     * `precomputedAllowedTools` 只给循环内的调用方（searchTools）复用一次性取到的白名单，
+     * 语义与缺省完全一致（undefined = 拿不到 → 放行）；单次调用方（describeTool）不传。
+     */
+    private isBuiltinAllowedForSandbox;
+    /** 注册表里该工具的别名（deny 规则按 [name, ...aliases] 匹配，与 AgentManager 同口径）。 */
+    private aliasesOf;
+    /** 每工具 isEnabled：拿不到工具或不支持该钩子按放行处理（与骨架 isSandboxToolEnabled 同口径）。 */
+    private isToolEnabledInSandbox;
+    /**
+     * repl_expose 白名单（执行层，与 repl-catalog-source.ts 同口径）：只约束 `mcp__`
+     * 前缀工具与会话 MCP 的 server 级 opt-in。内置工具不走此路径；宿主透明代理
+     * 工具使用目录中记录的所属 server，不能因裸名而跳过会话暴露配置。
+     *
+     * **fail-closed**：查不到 server config / McpManager 缺失 / list() 抛错时一律拒绝
+     * （返回 false）。理由与发现层一致——白名单默认 false，"拿不到配置"必须等价于"未
+     * 暴露"，否则查询失败会变成绕过白名单的旁路。
+     */
+    private isMcpToolReplExposed;
+    /**
+     * 该工具是否「裸名 MCP」（`isBare`，无 `mcp__` 前缀）—— 两个调用点（callTool 的白名单门、
+     * checkPermission 的内置工具门）共用一份判定，避免将来再次分叉。
+     *
+     * 判定会打到 `describeForSession` → `loadScopedTools`（异步加载 scoped MCP，可抛），
+     * 所以必须接住异常；但**接住之后不能替调用方决定方向** —— 两个调用点的 fail 方向相反，
+     * 详见 {@link BareMcpResolution}。上一版在这里 `catch → return true`（把「判不出来」和
+     * 「确实是 MCP」压成同一个布尔），对 callTool 是对的、对 checkPermission 是放行，
+     * 被安全走查抓出（#128343 回归）。
+     */
+    private resolveIsBareMcpTool;
+    private describeScopedMcpTool;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * RemoteBridgeHost —— BridgeHost 的真实现(agent-cli 侧客户端)。
+ *
+ * 传输 = 一条**本地 socket / 命名管道**(Unix domain socket / Windows 命名管道),零端口。
+ * 由 spawn agent-cli 的一方(如 WorkBuddy)经 env 传入:
+ *   - `CODEBUDDY_REPL_HOST_PIPE_PATH` —— Unix domain socket 路径(mac/linux)或命名管道 `\\.\pipe\...`(Windows)。
+ *   - `CODEBUDDY_REPL_HOST_TOKEN`     —— 授权 token(**强制**)。
+ * agent-cli 只 `net.connect(path)`(跨平台透明)、写 `{op,...,token}\n`、读 `<json>\n`。
+ *
+ * 安全:**token 强制**——host 是高权限(浏览器/电脑控制),裸 socket 会被同机其它进程利用。
+ *   pipe 或 token 任一未配置 → 无桥(不连接)→ `import("@wb/x")` 抛 not available。
+ * 跨平台:Node `net` 对 Unix socket / Windows 命名管道透明,由提供方按平台给正确的 path。
+ * 二进制:参数/返回值里的 Uint8Array/ArrayBuffer 在 socket 边界自动 ⇄ `{ $bytes: base64 }`,对模型/桥透明。
+ * 超时:单次桥调用超时随 cell 预算(opts.timeoutMs / opts.signal),不写死。
+ * 端到端验证需真提供方 + 真能力(本环境不具备);此为客户端半边 + 协议契约。见 docs/repl-code-mode/bridge-contract.md。
+ */
+import { Logger } from '../../../workspace/telemetry/lib/common/index.js';
+import { BridgeApiDescriptor, BridgeCallOpts, BridgeHost, BridgeInvokeRequest, BridgeResult } from './repl-protocol';
+export declare class RemoteBridgeHost implements BridgeHost {
+    protected readonly logger: Logger;
+    listBridges(): Promise<string[]>;
+    resolveBridge(specifier: string): Promise<BridgeApiDescriptor | null>;
+    invokeBridge(req: BridgeInvokeRequest, opts?: BridgeCallOpts): Promise<BridgeResult>;
+    /**
+     * 一次连接一次请求:写 `{...,token}\n`,读 `<json>\n`。
+     * pipe 或 token 未配置 → undefined(无桥,不连接)。失败/超时 → undefined(调用方降级)。
+     */
+    private post;
+}

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

@@ -0,0 +1,149 @@
+/**
+ * REPL 目录契约 —— 骨架目录（进 prompt）与发现 API（沙箱运行时）的共享类型。
+ *
+ * 设计见 docs/repl-code-mode/mcp-code-mode-design.md §4.3。
+ * 要点:
+ *  - 只有一份目录产物(骨架目录),档 A 给工具级明细 / 档 B 给 server 级索引,合起来全量收录。
+ *  - 没有枚举 API:"有哪些工具"读骨架目录即可,零调用零 token。
+ *  - 发现 API 只补骨架做不到的两件事:档 B 里找工具(searchTools)、完整 schema(describeTool)。
+ */
+import type { Session } from '../../../vendor/cbc-core/node/index.js';
+import type { RunContext } from '@openai/agents';
+/** 工具归属：内置工具占顶层全局，MCP 工具收在 server 二级命名空间下。 */
+export type REPLToolCategory = 'builtin' | 'mcp';
+/** 采集层产出的单个工具元信息（渲染骨架与注入 sandbox 共用）。 */
+export interface REPLCatalogTool {
+    /** canonical 路由名："Bash" / "mcp__github__list_pull_requests"。 */
+    name: string;
+    /** 模型面调用名："Bash" / "mcp_github.list_pull_requests"（§4.7 统一前缀）。 */
+    displayName: string;
+    category: REPLToolCategory;
+    /** 一行摘要（渲染时再按预算截断）。 */
+    summary: string;
+    /**
+     * 沙箱返回值形状，渲染在参数骨架后面、摘要前面。
+     * 必须单独成字段：摘要会被 SUMMARY_MAX_CHARS 截断，返回值不能被吃掉。
+     */
+    returns?: string;
+    /** JSON Schema；渲染骨架与 describeTool 都用它。 */
+    parameters: Record<string, unknown>;
+    /** MCP 所属 server 名（category==='mcp' 时必有）。 */
+    server?: string;
+    /** MCP 原始 tool name。 */
+    serverToolName?: string;
+}
+/** 一个 MCP server 及其工具（分档的最小单位——整组降档，不半截）。 */
+export interface REPLCatalogServerGroup {
+    /** 真实 server 名（用于 canonical 名与 `{server}` 过滤）。 */
+    server: string;
+    /** sandbox 全局键名；一律 `mcp_<server>`（§4.7），不是撞保留字才加前缀。 */
+    globalName: string;
+    description?: string;
+    tools: REPLCatalogTool[];
+}
+/** 采集层产物。骨架渲染与 sandbox 注入同源于此，避免两处口径漂移。 */
+export interface REPLCatalog {
+    /** 内置工具（延迟 + 非延迟合并后）。 */
+    builtin: REPLCatalogTool[];
+    mcp: REPLCatalogServerGroup[];
+    /** 目录版本号 = ToolSearchService.indexEpoch，用于新鲜度对账（§4.3.4）。 */
+    epoch: number;
+}
+export declare const ReplCatalogSource: unique symbol;
+/**
+ * 目录采集层 —— **无状态**：每次 collect 现采，不缓存。
+ *
+ * 不缓存的理由：调用频率极低（agent 构建时一次，见 §4.3.4「注入时机与生产次数」），
+ * 而缓存 key 需覆盖 agent 白名单 / session --tools / overlay / 动态 shouldShow 四个维度
+ * 并跟随 indexEpoch 失效——失效逻辑比重新采集更贵，且易出 stale bug。
+ */
+export interface ReplCatalogSource {
+    /**
+     * 采集当前会话可见的全部工具。
+     *
+     * 收 `RunContext` 而非 `Session`：agent 工具白名单入口
+     * `getAllowedToolsForAgent(agentName, context)` 需要 RunContext 才能跑
+     * `isEnabled`，且 RunContext 无法从 Session 反推（§4.3.3 易漏点 ①）。
+     *
+     * `opts.sandboxAgentName`：沙箱身份覆盖（见 ReplCatalogSource 实现的说明 ——
+     * Code Mode 的 REPL schema 在共享 agent 实例上物化，分子代理目录要靠派发侧传身份）。
+     */
+    collect(context: RunContext<Session>, opts?: {
+        sandboxAgentName?: string;
+    }): Promise<REPLCatalog>;
+}
+export interface SearchToolsOptions {
+    /** 默认 10，钳制到 [1, 50]。上限防止拿它当枚举用——枚举应读骨架目录。 */
+    topK?: number;
+    category?: REPLToolCategory;
+    /** 只搜某个 MCP server（隐含 category: 'mcp'）。 */
+    server?: string;
+}
+export interface ToolSearchHit {
+    /** 模型面调用名，可直接当 describeTool 的入参。 */
+    name: string;
+    category: REPLToolCategory;
+    server?: string;
+    /** 一行摘要（按 SUMMARY_MAX_CHARS 截断——索引里存的是 full description）。 */
+    description: string;
+    /** BM25 相关度，降序。 */
+    score: number;
+}
+export interface ToolDescriptor {
+    name: string;
+    category: REPLToolCategory;
+    description: string;
+    /** 完整 JSON Schema（含嵌套结构、约束与逐字段描述）。 */
+    parameters: Record<string, unknown>;
+    server?: string;
+    serverToolName?: string;
+}
+export interface BridgeEntry {
+    /** 桥标识："@wb/browser"。 */
+    specifier: string;
+}
+/** worker 侧注入 sandbox 全局所需的最小描述（结构化克隆友好）。 */
+export interface REPLToolDescriptor {
+    name: string;
+    displayName: string;
+    category: REPLToolCategory;
+    server?: string;
+    serverToolName?: string;
+}
+/** init / toolsUpdate 推给 worker 的载荷。 */
+export interface REPLToolsPayload {
+    epoch: number;
+    /**
+     * 本会话能力指纹（表面 / 身份 / 可见频道集合，见 repl-sandbox-capability）。
+     *
+     * worker 的去重键是 `(epoch, capability)` **两者一起**：能力变化时 epoch 可以不变
+     * （indexEpoch / surfaceEpoch 都不动），只按 epoch 去重会把这次重推静默丢掉 ——
+     * 新加入的频道工具于是永远停在 `undefined`。
+     */
+    capability?: string;
+    builtins: REPLToolDescriptor[];
+    /** globalName → 该 server 下工具的 displayName 尾段与 canonical 名映射。 */
+    servers: Array<{
+        globalName: string;
+        server: string;
+        tools: Array<{
+            method: string;
+            canonical: string;
+        }>;
+    }>;
+}
+export declare const REPL_SEARCH_TOOLS_DEFAULT_TOP_K = 10;
+export declare const REPL_SEARCH_TOOLS_MAX_TOP_K = 50;
+/** describeTools 的条数上限：精准批量，不是全量拉取。 */
+export declare const REPL_DESCRIBE_TOOLS_MAX = 10;
+/**
+ * 所有 MCP server 的 sandbox global 统一前缀（§4.7）。
+ *
+ * 沙箱里 MCP 工具的可调用名是 `<前缀><serverName>.<rawToolName>`，其中
+ * `serverName` / `rawToolName` 取自 `DeferredToolInfo`（见 mcp-manager 的索引段），
+ * **不是** canonical 名 `mcp__server__tool` 的字符串切分——transparent_proxy 场景下
+ * canonical 段可能与 serverName 不同（例如 connector-proxy 代管的服务）。
+ * 放在 protocol 里是为了让目录构造（repl-catalog-source）与引导文案
+ * （main-agent-session）用同一个前缀，避免两处各写一份漂移。
+ */
+export declare const MCP_SANDBOX_GLOBAL_PREFIX = "mcp_";

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

@@ -0,0 +1,56 @@
+/**
+ * 骨架目录渲染 —— 把 REPLCatalog 渲成拼进 `code` 参数描述的纯文本。
+ *
+ * 设计见 docs/repl-code-mode/mcp-code-mode-design.md §4.3.2。
+ *
+ * 分档降级（档 A/B）是本文件的核心：
+ *  - 档 A（工具级，~100B/工具）：每工具一行 `name({ 参数骨架 }) — 描述`
+ *  - 档 B（server 级，~70B/server）：一行 `name (N tools) — 描述`
+ *
+ * 降级单位是 **server 整组**，不半截——半截会让模型以为该 server 只有那几个工具。
+ * 档 B 体积几乎不随工具数增长，所以任意规模都装得下：装不下的只是档 A。
+ */
+import { REPLCatalog, REPLCatalogServerGroup, REPLCatalogTool } from './repl-catalog-protocol';
+/** 骨架总预算，对齐 DEFAULT_DEFERRED_TOOLS_CHAR_BUDGET（~20000 chars ≈ ~5000 tokens）。 */
+export declare const SKELETON_CHAR_BUDGET = 20000;
+/** 单工具最多列几个顶层参数，超出记 `…+N`。 */
+export declare const MAX_PARAMS_PER_TOOL = 6;
+/** 单工具一行摘要的截断长度（searchTools 的出参共用该常量）。 */
+export declare const SUMMARY_MAX_CHARS = 80;
+/** 档 B 里 server 描述的截断长度。 */
+export declare const SERVER_DESC_MAX_CHARS = 100;
+export declare function truncate(text: string, max: number): string;
+/**
+ * 类型渲染：枚举原样列出（≤4 项），数组给壳，嵌套对象一律折叠成 `object`。
+ *
+ * 折叠是刻意的——完整嵌套 schema 可达数 KB（实测 AskUserQuestion 3966B vs 骨架 73B，
+ * 54 倍）。代价是 `object` 对模型是信息不足的信号，因此兜底说明必须告诉它
+ * "看到 object 就调 describeTool"，否则模型会把它当成"接受任意对象"。
+ */
+export declare function renderType(def: unknown): string;
+/**
+ * 从 JSON Schema 派生单个参数对象的骨架：只取顶层 properties，必填优先。
+ *
+ * REPL 预注入函数的运行时契约始终是 `Tool(params)`，不是多个位置参数。这里必须
+ * 保留对象花括号；否则 `Artifact(filePath: string, ...)` 会误导模型传入字符串，导致
+ * 工具侧收到的 `input.filePath` 为 undefined。
+ */
+export declare function renderParameterSkeleton(schema: Record<string, unknown> | undefined): string;
+/** 档 B 一行：`name (N tools) — description`。 */
+export declare function renderServerTierB(group: REPLCatalogServerGroup): string;
+export interface TierAllocation {
+    tierA: REPLCatalogServerGroup[];
+    tierB: REPLCatalogServerGroup[];
+}
+/**
+ * 档 A/B 分配：builtin 无条件档 A（不参与预算竞争）；MCP 按工具数升序填至预算，
+ * 溢出的整组降档 B。
+ *
+ * 按工具数升序是性价比优先：一个小 server 只要几百字节，先进档 A 能覆盖更多 server。
+ */
+export declare function allocateTiers(builtin: REPLCatalogTool[], mcpGroups: REPLCatalogServerGroup[], budget?: number): TierAllocation;
+/**
+ * 渲染骨架目录全文。档 A + 档 B 合起来**全量收录**——所以模型读它即知会话里有什么，
+ * 不需要任何枚举 API。
+ */
+export declare function renderSkeletonCatalog(catalog: REPLCatalog, budget?: number): string;