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

package/cli/dist-server/types/node/bash-sandbox/bash-sandbox-manager.d.ts

@@ -0,0 +1,125 @@
+import { Logger } from '@celljs/core';
+import { type SandboxExecPolicy as ISandboxExecPolicy } from '../permission/sandbox-exec-policy-protocol';
+import { type SensitiveCommandDetector as ISensitiveCommandDetector } from '../permission/sensitive-command-detector';
+import { SandboxTurnConfig } from '../sandbox-cli/sandbox-turn-config';
+import { type SettingsManager as ISettingsManager } from '../settings/settings-protocol';
+import { BashSandboxManager as IBashSandboxManager, SandboxConfig, SandboxDependencyError } from './bash-sandbox-protocol';
+export declare function expandWindowsNativeDirectoryGlobs(paths: readonly string[] | undefined, platform?: NodeJS.Platform): string[];
+/**
+ * Bash 沙箱管理器实现
+ * 封装 @anthropic-ai/sandbox-runtime 并提供配置管理和自动初始化
+ */
+export declare class BashSandboxManagerImpl implements IBashSandboxManager {
+    protected readonly settingsManager: ISettingsManager;
+    protected readonly logger: Logger;
+    /**
+     * Optional so that environments that boot the sandbox manager without the
+     * policy module registered (e.g. legacy headless paths) keep working;
+     * when present we forward `settings.sandbox.execPolicy` updates on each
+     * config load so the policy's user rules stay in sync with settings.
+     */
+    protected readonly execPolicy?: ISandboxExecPolicy;
+    protected readonly sensitiveCommandDetector?: ISensitiveCommandDetector;
+    protected readonly sandboxTurnConfig: SandboxTurnConfig;
+    private initialized;
+    private cachedConfig;
+    /** Last user-rules payload we pushed into the ExecPolicy; used to avoid
+     *  redundant `setUserRules` calls when settings are unchanged. */
+    private lastExecPolicyUserRulesKey;
+    private lastOrderedCommandRulesKey;
+    /**
+     * 获取当前沙箱配置
+     */
+    getConfig(): Promise<SandboxConfig | undefined>;
+    /**
+     * 使用沙箱包装命令
+     *
+     * 仅 Linux 上调用 `@anthropic-ai/sandbox-runtime` 的 `wrapWithSandbox`，
+     * 把命令包装成 `bwrap ... -- bash -c <cmd>` 形式后返回，供
+     * `LegacySandboxShellService` 交给 `LocalShellService` 执行。
+     *
+     * 其它平台（macOS/Windows）由 `sandbox-cli` 接管命令执行，不经过这条
+     * JS 侧包装路径；此处直接返回原命令，避免 `AnthropicSandboxManager`
+     * 在未初始化的前提下被调用。
+     */
+    wrapCommand(command: string): Promise<string>;
+    /**
+     * 检查命令是否应该在沙箱中执行
+     */
+    shouldSandbox(command: string): Promise<boolean>;
+    /**
+     * 检查命令是否属于系统级工具（如 WSL）。
+     * 复用 {@link getCommandRoots} 解析器提取命令根。
+     */
+    isSystemLevelTool(command: string): boolean;
+    /**
+     * 确保沙箱处于正确状态(检查配置变化并初始化/重新初始化)
+     */
+    private ensureSandboxReady;
+    /**
+     * 应用配置变化(智能初始化/重新初始化)
+     */
+    private applyConfigChange;
+    /**
+     * 检查 Linux 平台沙箱所需的依赖
+     * @returns 缺失的依赖列表
+     */
+    private checkLinuxDependencies;
+    /**
+     * 检查 Linux 依赖并返回错误（如果有缺失）
+     * 供外部调用（如 /sandbox 命令）显示给用户
+     */
+    checkDependencies(): Promise<SandboxDependencyError | undefined>;
+    /**
+     * 初始化沙箱
+     *
+     * 仅 Linux 需要走 `@anthropic-ai/sandbox-runtime`（bwrap + socat）这条
+     * 老路径——对应 `LegacySandboxShellService`。macOS/Windows 已改为由
+     * `SandboxShellService` 驱动 Rust `sandbox-cli` 二进制，`AnthropicSandboxManager`
+     * 在那两个平台上不承担任何运行时职责，即便调用也只是内存里重设一份永远
+     * 不会被读到的配置，因此直接跳过以避免额外开销和潜在的兼容性问题。
+     */
+    private initialize;
+    /**
+     * 重置沙箱
+     *
+     * 与 `initialize` 对称：只有 Linux 上才真正持有 AnthropicSandboxManager
+     * 的状态，其它平台只要翻转 `this.initialized` 即可。
+     */
+    private reset;
+    /**
+     * 从设置中加载沙箱配置
+     */
+    private loadConfig;
+    /**
+     * 判断两个配置是否相等(通过 deepEqual 比较)
+     */
+    private isConfigEqual;
+    /**
+     * 将 SandboxConfig 转换为 SandboxRuntimeConfig
+     */
+    private toRuntimeConfig;
+    /**
+     * 扩展路径中的波浪号
+     */
+    private expandPaths;
+    /**
+     * Push user-authored ExecPolicy rules into the policy component.
+     *
+     * `undefined` fingerprint means "no execPolicy set" — we also forward
+     * `undefined` so the policy clears any previously loaded user rules
+     * (important when a user removes the settings block entirely).
+     */
+    private syncExecPolicyUserRules;
+    private syncOrderedCommandRules;
+    /** Prefix commands that wrap the real command — skip them to find the actual executable. */
+    private static readonly SHELL_PREFIX_COMMANDS;
+    /** Standalone builtins whose arguments are NOT commands — skip the whole sub-command. */
+    private static readonly SHELL_STANDALONE_BUILTINS;
+    /**
+     * Extract command roots from ALL sub-commands in a compound command
+     * (separated by &&, ||, ;, |). Each sub-command yields at most one
+     * root — the first non-assignment, non-shell-prefix string token.
+     */
+    private getCommandRoots;
+}

package/cli/dist-server/types/node/bash-sandbox/index.d.ts

@@ -0,0 +1,4 @@
+export * from './bash-sandbox-protocol';
+export * from './bash-sandbox-manager';
+export * from './legacy-sandbox-shell-protocol';
+export * from './legacy-sandbox-shell-service';

package/cli/dist-server/types/node/bash-sandbox/legacy-sandbox-shell-protocol.d.ts

@@ -0,0 +1,33 @@
+import type { ShellService } from '../shell/shell-protocol';
+/**
+ * DI symbol for the legacy sandbox shell service.
+ *
+ * Rationale
+ * ---------
+ * The primary sandbox implementation is `SandboxShellService`, which drives
+ * a persistent Rust `sandbox-cli` binary over IPC. That binary ships today
+ * for macOS and Windows only — there is no Linux build yet.
+ *
+ * To keep Linux users covered by SOME sandbox layer we retain the older
+ * `@anthropic-ai/sandbox-runtime` path (`sandbox-exec` wrapping on Darwin
+ * back in the day, `bwrap + socat` on Linux today) as a "legacy" backend.
+ * It lives behind this dedicated symbol so that:
+ *
+ *   - the router (`DelegatingShellService`) can pick the right backend by
+ *     platform without leaking implementation details into the tools;
+ *   - the orchestrator (`SandboxOrchestrator`) can disable post-exec
+ *     escalation on this backend, since `bwrap` does not emit the structured
+ *     `fileBlockRecords[]` we rely on for the "sandbox first, bypass on
+ *     approval" flow.
+ *
+ * Behaviour parity with `SandboxShellService` is intentionally LIMITED:
+ *   - no InterceptNotification
+ *   - no structured sandboxDenied signal
+ *   - no session-level approval escalation on Linux (see the orchestrator)
+ *
+ * Everything else (local execution when sandbox is disabled / `off`,
+ * ExecPolicy, dangerouslyDisableSandbox → local bypass) still works the
+ * same way as on macOS/Windows.
+ */
+export declare const LegacySandboxShellService: unique symbol;
+export type LegacySandboxShellService = ShellService;

package/cli/dist-server/types/node/bash-sandbox/legacy-sandbox-shell-service.d.ts

@@ -0,0 +1,33 @@
+import { Logger } from '@celljs/core';
+import { type ShellExecuteParams, type ShellExecutionHandle, type ShellService } from '../shell/shell-protocol';
+import { BashSandboxManager as IBashSandboxManager } from './bash-sandbox-protocol';
+/**
+ * Shell service backed by `@anthropic-ai/sandbox-runtime` (bwrap/socat on
+ * Linux).
+ *
+ * Implementation strategy: transform the caller's command into its sandboxed
+ * equivalent via `BashSandboxManager.wrapCommand()`, then hand the wrapped
+ * command to `LocalShellService`. Execution semantics (PTY, env propagation,
+ * cwd, timeout) therefore mirror the regular local pipeline — the sandbox
+ * layer is just a `bwrap ...` / `sandbox-exec ...` prefix injected at the
+ * command string level.
+ *
+ * Known limitations (Linux):
+ *
+ * - No structured violation reporting. Failures surface as a non-zero exit
+ *   code plus free-form stderr from bwrap / the launched process. The
+ *   orchestrator therefore suppresses its `[4] escalation` branch for this
+ *   backend; denied commands just fail and the model sees the stderr.
+ * - `wrapCommand()` returns the original command verbatim when the sandbox
+ *   is globally disabled or its native deps (bwrap / socat) are missing. In
+ *   that case we still dispatch through `LocalShellService` for a graceful
+ *   degradation instead of spawning a broken sandbox.
+ */
+export declare class LegacySandboxShellServiceImpl implements ShellService {
+    protected readonly localShellService: ShellService;
+    protected readonly bashSandboxManager: IBashSandboxManager;
+    protected readonly logger: Logger;
+    execute(params: ShellExecuteParams): Promise<ShellExecutionHandle>;
+    disposeAll(): Promise<void>;
+    getActiveHandleCount(): number;
+}

package/cli/dist-server/types/node/blob-store/blob-store-protocol.d.ts

@@ -0,0 +1,104 @@
+import type { AgentInputItem } from '../../vendor/cbc-shared/node/index.js';
+export declare const BlobStore: unique symbol;
+export declare const ImageBlobService: unique symbol;
+/** Blob 引用（替代 base64 内嵌在历史中） */
+export interface ImageBlobRef {
+    type: 'image_blob_ref';
+    /** sha256 hash */
+    blob_id: string;
+    /** MIME type, e.g. 'image/png' */
+    mime: string;
+    /** 原始二进制字节数 */
+    size: number;
+    /** 来源路径或 'generated' */
+    source?: string;
+    /** 完整 blob 文件路径, e.g. ~/.codebuddy/blobs/ab/ab3f7c...png */
+    blob_path: string;
+    /** 用户上传时的原始文件名, e.g. 'test1.jpeg' */
+    original_filename?: string;
+}
+/** Durable content identity used to resolve a blob without trusting its path. */
+export type ImageBlobIdentity = Pick<ImageBlobRef, 'type' | 'blob_id' | 'mime' | 'size'>;
+export declare function isImageBlobIdentity(value: unknown): value is ImageBlobIdentity;
+/** BlobStore 底层存储接口 */
+export interface BlobStore {
+    /** 存储 base64 数据，返回 ImageBlobRef */
+    store(base64Data: string, mime: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    /**
+     * 存储二进制数据，返回 ImageBlobRef。
+     * 调用方已持有 Buffer 时走这里，避免为了适配 base64 入参而多造一份
+     * base64 字符串 + 一份解码回来的 Buffer（大图下这两份副本各约原图的 1.33x / 1x）。
+     */
+    storeBuffer(data: Buffer, mime: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    /** 根据 blobId 读取 base64 数据 */
+    read(blobId: string, mime?: string, expectedSize?: number): Promise<string | undefined>;
+    /** 检查 blob 是否存在 */
+    exists(blobId: string, mime?: string): Promise<boolean>;
+    /** 获取 blob 文件路径 */
+    getBlobPath(blobId: string, mime?: string): string;
+}
+/** ImageBlobService 高层服务接口 */
+export interface ImageBlobService {
+    /**
+     * 将 base64 data URI 存入 BlobStore，返回 ImageBlobRef
+     * @param dataUri 完整的 data:mime;base64,... 字符串
+     * @param source 来源路径
+     * @param originalFilename 用户上传时的原始文件名
+     */
+    storeFromDataUri(dataUri: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    /**
+     * 将图片文件存入 BlobStore，返回 ImageBlobRef
+     * @param filePath 图片文件路径
+     * @param contents 调用方已读到的文件内容；传入时复用它，避免二次读盘
+     */
+    storeFromFile(filePath: string, contents?: Buffer): Promise<ImageBlobRef>;
+    /**
+     * 从 BlobRef 还原完整的 data URI
+     */
+    rehydrate(ref: ImageBlobIdentity, options?: {
+        original?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * 生成文本占位符
+     */
+    createPlaceholder(ref: ImageBlobRef): string;
+    /**
+     * 判断对象是否为 ImageBlobRef
+     */
+    isImageBlobRef(obj: unknown): obj is ImageBlobRef;
+    /**
+     * 记录图片已发送给模型，返回发送状态：
+     * - 'new': 首次发送或同路径文件已更新，应返回完整图片
+     * - 'unchanged': 同路径同内容（文件未变化），应返回确认消息
+     * - 'duplicate': 不同路径但相同内容，去重
+     *
+     * @param blobId 图片内容的 SHA256 哈希
+     * @param source 图片来源路径（可选，传入时启用路径级别的变更检测）
+     */
+    trackImageDelivered(blobId: string, source?: string): 'new' | 'unchanged' | 'duplicate';
+    /**
+     * 重置图片发送跟踪（新的 agent run 开始时调用）
+     */
+    resetImageTracking(): void;
+    /**
+     * 为本轮（一次 agent run）再读入一张图片申请字节预算。
+     *
+     * 图片解码/重编码走的是纯 JS 编码器，单张的临时内存开销是原图体积的数十倍，
+     * 而模型可以在同一轮里并行发起任意多个 Read。没有总量约束时，单轮海量大图
+     * 会把 V8 堆撑爆（硬 OOM 绕过所有异常处理，崩溃后零取证）。这里给"单轮读入
+     * 的图片原始字节总量"设上限，超出后调用方应返回文本占位而不是继续读盘。
+     *
+     * @param bytes 待读入图片的原始字节数
+     * @returns true 表示预算够用（已扣减）；false 表示本轮配额已用尽
+     */
+    tryReserveImageBytes(bytes: number): boolean;
+    /** 本轮图片字节预算上限，供调用方组织提示文案。 */
+    readonly maxImageBytesPerRun: number;
+    /**
+     * 对历史消息数组做 rehydration / 占位符替换
+     * @param history 历史消息数组
+     * @param retainRounds 保留最近 N 轮图片的完整 base64（默认 2）
+     * @returns 处理后的历史数组（浅拷贝，不修改原始数据）
+     */
+    processHistoryForApi(history: AgentInputItem[], retainRounds: number): Promise<AgentInputItem[]>;
+}

package/cli/dist-server/types/node/blob-store/blob-store-service.d.ts

@@ -0,0 +1,22 @@
+import { Logger } from '@celljs/core';
+import { type BlobStore, type ImageBlobRef } from './blob-store-protocol';
+export declare class BlobStoreImpl implements BlobStore {
+    protected readonly logger: Logger;
+    protected init(): void;
+    store(base64Data: string, mime: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    storeBuffer(buffer: Buffer, mime: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    /**
+     * blob 落盘失败是否可降级（跳过缓存而非崩 turn）。
+     * 仅对「环境不可写」类文件系统 errno 降级：只读/served FS（EROFS）、
+     * 分片目录缺失（ENOENT）、权限（EACCES/EPERM）、空间/配额（ENOSPC/EDQUOT）、
+     * 底层 IO/目录形态（EIO/ENOTDIR/EISDIR/EBUSY）。
+     * 明确**不**降级 Node 的 `ERR_*` 编程错误（如 ERR_INVALID_ARG_TYPE）——
+     * 这些带 `code` 但不是 FS errno，属于调用面 bug，应继续抛出以暴露而非被缓存降级咽掉。
+     */
+    private static readonly DEGRADABLE_FS_ERRNOS;
+    private isDegradableWriteError;
+    read(blobId: string, mime?: string, expectedSize?: number): Promise<string | undefined>;
+    exists(blobId: string, mime?: string): Promise<boolean>;
+    protected pathExists(filePath: string): Promise<boolean>;
+    getBlobPath(blobId: string, mime?: string): string;
+}

package/cli/dist-server/types/node/blob-store/image-blob-service.d.ts

@@ -0,0 +1,121 @@
+import { Logger } from '@celljs/core';
+import type { AgentInputItem } from '../../vendor/cbc-shared/node/index.js';
+import { type BlobStore, type ImageBlobIdentity, type ImageBlobRef, type ImageBlobService } from './blob-store-protocol';
+/** 图片内容本身无法通过统一 preparation；与 Blob 磁盘 I/O 异常严格区分。 */
+export declare class InvalidImageDataError extends Error {
+    constructor(reason: string);
+}
+export declare class ImageBlobServiceImpl implements ImageBlobService {
+    protected readonly blobStore: BlobStore;
+    protected readonly logger: Logger;
+    protected init(): void;
+    storeFromDataUri(dataUri: string, source?: string, originalFilename?: string): Promise<ImageBlobRef>;
+    storeFromFile(filePath: string, contents?: Buffer): Promise<ImageBlobRef>;
+    rehydrate(ref: ImageBlobIdentity, options?: {
+        original?: boolean;
+    }): Promise<string | undefined>;
+    createPlaceholder(ref: ImageBlobRef): string;
+    isImageBlobRef(obj: unknown): obj is ImageBlobRef;
+    /**
+     * 跟踪已发送图片：key = source 路径, value = 已发送的 blob_id。
+     * 用于检测同路径文件是否更新。
+     */
+    private deliveredImages;
+    /**
+     * 所有已发送的 blob_id（含有/无 source 的）。
+     * 用于跨路径内容去重。
+     */
+    private deliveredBlobIds;
+    trackImageDelivered(blobId: string, source?: string): 'new' | 'unchanged' | 'duplicate';
+    resetImageTracking(): void;
+    /**
+     * 单轮（一次 agent run）允许读入的图片原始字节总量默认上限。
+     *
+     * **为什么换了原生编解码器仍然需要它**（实测推翻过一次直觉）：原生后端把编解码搬到
+     * Rust 原生内存，单次编码的 V8 堆增量确实降到 0，但真正决定「一轮能处理多少张」的是
+     * **与后端无关的累积量**——每张图读入的原始 Buffer、压缩结果 base64、data URL、
+     * tool result JSON，以及 SDK 对 turn input 的深拷贝。实测两个后端的 OOM 临界点完全
+     * 相同（48 张 × 10MB：heap=1024 都崩、heap=2048 都过），所以配额不能因为换后端而取消。
+     *
+     * 定标：完全不限量时 `--max-old-space-size=1024`（生产默认 ~4GB 的 1/4）下
+     * 24 张 × 10MB 刚好通过、48 张必崩。默认 128MB（约 12 张 10MB 图）距离 240MB
+     * 临界点留 2x 余量，实测 heap=512 / heap=1024 下都稳定通过。常见截图 0.5~3MB，
+     * 相当于一轮 40~250 张，正常用法完全无感。
+     *
+     * 配额按轮重置（见 resetImageTracking），超限只影响**当前这一轮**，模型下一轮
+     * 仍可继续读剩下的图，不是永久拒绝。
+     */
+    private static readonly DEFAULT_MAX_IMAGE_MB_PER_RUN;
+    /**
+     * 覆盖单轮图片字节预算，单位 MB。
+     *
+     * - 未设 / 空 → 默认 128MB
+     * - `0` → 完全不限制（**自担风险**：单轮图片够多时仍会硬 OOM，与编解码后端无关）
+     * - 其它正整数 → 按该 MB 数限制
+     * - 非法值 → 回落默认并告警
+     */
+    private static readonly MAX_IMAGE_MB_PER_TURN_ENV;
+    private reservedImageBytes;
+    /** 本轮生效的预算（字节）；0 表示不限制。每轮重置时重新解析 env。 */
+    private maxImageBytesThisRun?;
+    private resolveMaxImageBytesPerRun;
+    tryReserveImageBytes(bytes: number): boolean;
+    /** 本轮图片字节预算上限（0 表示不限制），供调用方组织提示文案。 */
+    get maxImageBytesPerRun(): number;
+    /** 同一 source 路径的图片在最近 N 轮中最多保留的版本数 */
+    private static readonly MAX_VERSIONS_PER_SOURCE;
+    processHistoryForApi(history: AgentInputItem[], retainRounds: number): Promise<AgentInputItem[]>;
+    /**
+     * 构建需要 rehydrate 的 item 索引集合。
+     *
+     * 规则：
+     * 1. 相同 blob_id 只保留最后一次出现
+     * 2. 同一 source 路径的不同版本只保留最后 MAX_VERSIONS_PER_SOURCE 个
+     * 3. 不同 source / 无 source 的图片互不干扰
+     */
+    private buildRehydrateSet;
+    /**
+     * 从 item 中提取所有 ImageBlobRef 的 { blob_id, source }
+     */
+    private collectBlobRefs;
+    /**
+     * 从 JSON 字符串中提取 blob_id 和 source
+     */
+    private extractBlobRefsFromString;
+    /**
+     * 检查 item 中是否包含 ImageBlobRef
+     */
+    private itemHasBlobRef;
+    /**
+     * 还原 item 中的 ImageBlobRef 为完整 data URI
+     */
+    private rehydrateItem;
+    /**
+     * 将 item 中的 ImageBlobRef 替换为文本占位符
+     */
+    private dehydrateItem;
+    /**
+     * 还原 FunctionCallResult 中的 ImageBlobRef
+     */
+    private rehydrateFunctionCallResult;
+    /**
+     * 将 FunctionCallResult 中的 ImageBlobRef 替换为占位符
+     */
+    private dehydrateFunctionCallResult;
+    /**
+     * 异步处理 content 数组中的 ImageBlobRef（rehydrate）
+     */
+    private processContentArray;
+    /**
+     * 同步处理 content 数组中的 ImageBlobRef（dehydrate -> 占位符）
+     */
+    private processContentArraySync;
+    /**
+     * 从 image_url.url 中提取 ImageBlobRef。
+     * url 可能是：
+     * - ImageBlobRef 对象（直接返回）
+     * - JSON 字符串化的 ImageBlobRef（解析后返回）
+     * - 正常的 data URI 或 http URL（返回 undefined）
+     */
+    private extractBlobRefFromUrl;
+}

package/cli/dist-server/types/node/blob-store/index.d.ts

@@ -0,0 +1,4 @@
+export * from './blob-store-protocol';
+export * from './blob-store-service';
+export * from './image-blob-service';
+export * from './tool-result-blob-service';

package/cli/dist-server/types/node/blob-store/tool-result-blob-service.d.ts

@@ -0,0 +1,109 @@
+import { Logger } from '@celljs/core';
+/**
+ * Symbol for dependency injection
+ */
+export declare const ToolResultBlobService: unique symbol;
+/**
+ * Reference object for a previously externalized tool result (reserved for future use).
+ */
+export interface ToolResultRef {
+    type: 'tool_result_ref';
+    /** Original content size in bytes */
+    size: number;
+    /** Full path to the persisted output file */
+    filePath: string;
+}
+/**
+ * Service interface for externalizing large tool results to disk.
+ *
+ * Follows the Claude Code pattern: when a tool result exceeds a size threshold,
+ * the full output is saved to a file under `~/.codebuddy/tool-results/{sessionDir}/`,
+ * and the in-memory/persisted history stores only a `<persisted-output>` placeholder
+ * with a preview of the first 2KB.
+ *
+ * This prevents unbounded memory growth in long-running monorepo sessions where
+ * tools like Grep/Read/TaskOutput can return very large outputs.
+ */
+export interface ToolResultBlobService {
+    /**
+     * Check if a tool result output should be externalized based on size.
+     * @param output The tool result output string
+     * @returns true if the output exceeds the externalization threshold
+     */
+    shouldExternalize(output: string): boolean;
+    /**
+     * Save a large tool result to disk and return the placeholder text
+     * that should be stored in the history instead.
+     *
+     * @param callId The tool_use_id (e.g., "call_00_abc123")
+     * @param output The full tool result output
+     * @param sessionStoreId The session's storeId (used for directory naming)
+     * @param parentSessionId Optional parent session ID (for subagents)
+     * @returns The placeholder text to store in history
+     */
+    externalize(callId: string, output: string, sessionStoreId: string, parentSessionId?: string): Promise<string>;
+    /**
+     * Read back a previously externalized tool result.
+     * @param filePath Path to the persisted output file
+     * @returns The original full content, or undefined if file is missing
+     */
+    read(filePath: string): Promise<string | undefined>;
+    /**
+     * Clean up all externalized tool results for a session.
+     * @param sessionStoreId The session's storeId
+     * @param parentSessionId Optional parent session ID (for subagents)
+     */
+    cleanupSession(sessionStoreId: string, parentSessionId?: string): Promise<void>;
+    /**
+     * Get the file path where a tool result's full output would be spilled to disk.
+     * Used by tools (e.g., BashTool) to create an OutputSpiller that streams
+     * full output to this path before truncation happens.
+     */
+    getSpillFilePath(callId: string, sessionStoreId: string, parentSessionId?: string): string;
+    /**
+     * Create an externalization placeholder for a tool result whose full output
+     * has already been written to disk by an OutputSpiller.
+     * Unlike externalize(), this does NOT write the file — it only generates the placeholder.
+     *
+     * @param callId The tool_use_id
+     * @param totalBytes Total bytes written to the spill file
+     * @param spillFilePath Path to the existing spill file
+     * @param truncatedOutput The truncated output text (used for preview)
+     * @returns The placeholder text to store in history
+     */
+    externalizeFromSpillFile(callId: string, totalBytes: number, spillFilePath: string, truncatedOutput: string): string;
+}
+export declare class ToolResultBlobServiceImpl implements ToolResultBlobService {
+    protected readonly logger: Logger;
+    init(): void;
+    shouldExternalize(output: string): boolean;
+    /**
+     * Save a large tool result to disk and return the placeholder text
+     * that should be stored in the history instead.
+     *
+     * @param callId The tool_use_id (e.g., "call_00_abc123")
+     * @param output The full tool result output
+     * @param sessionStoreId The session's storeId (used for directory naming)
+     * @param parentSessionId Optional parent session ID (for subagents)
+     * @returns The placeholder text to store in history
+     */
+    externalize(callId: string, output: string, sessionStoreId: string, parentSessionId?: string): Promise<string>;
+    read(filePath: string): Promise<string | undefined>;
+    getSpillFilePath(callId: string, sessionStoreId: string, parentSessionId?: string): string;
+    externalizeFromSpillFile(callId: string, totalBytes: number, spillFilePath: string, truncatedOutput: string): string;
+    cleanupSession(sessionStoreId: string, parentSessionId?: string): Promise<void>;
+    /**
+     * Get the directory for storing tool results for a specific session.
+     *
+     * For main sessions: ~/.codebuddy/projects/{projectId}/{sessionId}/tool-results/
+     * For subagents: ~/.codebuddy/projects/{projectId}/{parentSessionId}/subagents/{storeId}/tool-results/
+     *
+     * This mirrors the session history file layout:
+     *   {sessionId}.jsonl          ← main session history
+     *   {sessionId}/tool-results/  ← main session tool results
+     *   {parentSessionId}/subagents/
+     *     ├── agent-xxx.jsonl      ← subagent history
+     *     └── agent-xxx/tool-results/ ← subagent tool results
+     */
+    private getSessionToolResultDir;
+}

package/cli/dist-server/types/node/channel/channel-event-service.d.ts

@@ -0,0 +1,18 @@
+import { SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { ChannelEvent, ChannelEventService, ChannelManager } from './channel-protocol';
+export declare class ChannelEventServiceImpl implements ChannelEventService {
+    protected readonly logger: Logger;
+    protected readonly channelManager: ChannelManager;
+    protected readonly sessionManager: SessionManager;
+    initialize(): void;
+    /**
+     * 将 channel 事件添加到当前 session 的事件队列
+     * 事件将在 ChannelEventAgentRunInterceptor 中被消费并注入到 agent input 中
+     */
+    pushEventToSession(event: ChannelEvent): void;
+    /**
+     * 消费指定 session 的所有待处理 channel 事件
+     */
+    consumeEventsForSession(sessionId: string): ChannelEvent[];
+}

package/cli/dist-server/types/node/channel/channel-manager.d.ts

@@ -0,0 +1,41 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { Subject } from 'rxjs';
+import { SettingsManager } from '../settings';
+import { ChannelEvent, ChannelManager, ChannelPermissionRequest, ChannelServerInfo } from './channel-protocol';
+export declare class ChannelManagerImpl implements ChannelManager {
+    protected readonly logger: Logger;
+    protected readonly settingsManager?: SettingsManager;
+    private _enabled;
+    get enabled(): boolean;
+    readonly channelServers: Map<string, ChannelServerInfo>;
+    readonly eventSubject: Subject<ChannelEvent>;
+    readonly channelServersSubject: Subject<Map<string, ChannelServerInfo>>;
+    private sessionEventQueues;
+    allowedChannels: Set<string> | undefined;
+    private developmentChannels;
+    /**
+     * 注册 channel 服务器
+     * 在 MCP 连接成功后调用，检测 experimental capabilities
+     */
+    registerChannel(serverName: string, mcpSession: any, capabilities: any, instructions?: string): void;
+    unregisterChannel(serverName: string): void;
+    isChannel(serverName: string): boolean;
+    getPermissionRelayChannels(): ChannelServerInfo[];
+    /**
+     * 广播权限请求到所有支持 permission relay 的 channels
+     */
+    broadcastPermissionRequest(request: ChannelPermissionRequest): void;
+    /**
+     * 为 session 添加 channel 事件到队列
+     */
+    enqueueEventForSession(sessionId: string, event: ChannelEvent): void;
+    /**
+     * 消费并清空指定 session 的所有待处理事件
+     */
+    consumeEventsForSession(sessionId: string): ChannelEvent[];
+    configureFromSessionOptions(options: {
+        channels?: string;
+        dangerouslyLoadDevelopmentChannels?: string;
+    }): void;
+    shouldBypassAllowlist(serverName: string): boolean;
+}

package/cli/dist-server/types/node/channel/channel-permission-adapter.d.ts

@@ -0,0 +1,27 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { ChannelManager, ChannelPermissionAdapter, ChannelPermissionResponse } from './channel-protocol';
+export declare class ChannelPermissionAdapterImpl implements ChannelPermissionAdapter {
+    protected readonly logger: Logger;
+    protected readonly channelManager: ChannelManager;
+    private pendingRequests;
+    private toolCallToRequestId;
+    /**
+     * 生成符合规范的 request_id
+     * 5 个小写字母，排除 'l'
+     */
+    private generateRequestId;
+    /**
+     * 创建权限请求并广播到 channels
+     * 返回 Promise，与本地 UI 审批竞速
+     */
+    createPermissionRequest(toolCallId: string, toolName: string, description: string, inputPreview: string): Promise<'allow' | 'allow_always' | 'deny' | 'deny_and_exit_plan'>;
+    /**
+     * 处理来自 channel 的权限响应
+     */
+    handlePermissionResponse(response: ChannelPermissionResponse): void;
+    /**
+     * 当本地 UI 已经做出决定时，取消待处理的 channel 请求
+     */
+    cancelRequest(toolCallId: string): void;
+    isPendingRequest(requestId: string): boolean;
+}