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

package/cli/dist-server/types/workspace/sandbox-cli/lib/common/protocol.generated.d.ts

@@ -0,0 +1,392 @@
+/** JSON 值类型，对应 Rust 侧的 `serde_json::Value`。 */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const SANDBOX_COMMANDS: {
+    readonly PING: 'Ping';
+    readonly OPEN_SESSION: 'OpenSession';
+    readonly CLOSE_SESSION: 'CloseSession';
+    readonly DELETE_SESSION: 'DeleteSession';
+    readonly RUN_EXECUTABLE: 'RunExecutable';
+    readonly GET_STATISTICS: 'GetStatistics';
+    readonly REPORT_BLOCK_CHOICE: 'ReportBlockChoice';
+    readonly PROCESS_WRITE: 'ProcessWrite';
+    readonly PROCESS_SEND_KEY: 'ProcessSendKey';
+    readonly PROCESS_RESIZE: 'ProcessResize';
+    readonly PROCESS_KILL: 'ProcessKill';
+    readonly PROCESS_IS_ALIVE: 'ProcessIsAlive';
+    readonly PROCESS_OUTPUT: 'ProcessOutput';
+    readonly PROCESS_EXIT: 'ProcessExit';
+    readonly REPORT_EVENT: 'ReportEvent';
+    readonly RECORD_STATISTICS: 'RecordStatistics';
+    readonly APPEND_USER_CHOICE: 'AppendUserChoice';
+};
+export type IpcCommandNameValue = (typeof SANDBOX_COMMANDS)[keyof typeof SANDBOX_COMMANDS];
+/** 管理器级命令（宿主 → SandboxManager） */
+export type ManagerCommand = 'Ping' | 'OpenSession' | 'CloseSession' | 'DeleteSession';
+/** 会话级命令（宿主 → 会话 Handler） */
+export type SessionCommand = 'RunExecutable' | 'GetStatistics' | 'ReportBlockChoice' | 'ProcessWrite' | 'ProcessSendKey' | 'ProcessResize' | 'ProcessKill' | 'ProcessIsAlive';
+/** 反向命令与事件（SandboxManager → 宿主） */
+export type ReverseCommand = 'ProcessOutput' | 'ProcessExit' | 'ReportEvent';
+/** 所有合法的对外 IPC 命令（不含 Rust 内部调度命令）。 */
+export type SandboxCommand = ManagerCommand | SessionCommand | ReverseCommand;
+export type ExecutionMode = 'sandbox' | 'sandbox_bypass';
+export type DecisionDomain = 'file' | 'network' | 'cmd';
+export type DecisionReason = 'rule_missing' | 'rule' | 'http_intercept' | 'forbidden_program' | 'dangerous_url' | 'sensitive_info' | 'ipc_fail' | 'network_strict';
+export type RuleCategory = 'temp' | 'global' | 'session' | 'auto_grant' | 'enterprise';
+export type RuleAction = 'allow' | 'deny' | 'ask';
+export type DecisionOperation = 'read' | 'write' | 'delete' | 'rename' | 'execute' | 'connect' | 'dns_resolve' | 'sendto';
+export type DecisionRecordSource = 'center_rule' | 'syslog_deny' | 'cli_synthesized';
+export type CipherRuleSource = 'user' | 'preset' | 'enterprise';
+export type ApprovalDecision = 'deny' | 'allow_plaintext' | 'allow_cipher';
+/**
+ * IPC 消息格式，用于 SandboxManager 与宿主之间的 NDJSON 通信。
+ *
+ * 请求消息必须包含 command，响应消息必须包含 success。
+ * 通过 success 字段是否存在来区分请求与响应。
+ */
+export interface IpcMessage {
+    sessionId: string;
+    messageId: string;
+    command: string;
+    data?: JsonValue;
+    success?: boolean;
+    error?: string;
+    noReply?: boolean;
+}
+/** runExecutable 请求 data。 */
+export interface RunExecutableRequest {
+    executable: string;
+    args: string[];
+    displayCommand?: string;
+    env?: Record<string, string>;
+    cwdDir: string;
+    timeoutMs?: number;
+    executionMode: ExecutionMode;
+    stdoutMode?: 'sync' | 'pty' | 'pipe';
+    cols?: number;
+    rows?: number;
+    pathOverride?: string;
+    stdinMode?: 'null' | 'pipe';
+    sandboxExtensionClasses?: string[];
+    killProcessTree?: boolean;
+    /**
+     * 单进程输出上限（防输出洪峰击穿 IPC 流式队列）。任一超限即停止读取并终止
+     * 该进程树，经 ProcessExit 回报 outputTruncated=true（语义是"截断"而非"失败"）。
+     * 缺省 0 = 不限制（现有调用方零变化）；两个上限独立生效，任一先到即触发。
+     * 设计文档：docs/ipc-stream-queue-overflow-isolation-plan.md §S3。
+     */
+    maxOutputBytes?: number;
+    maxOutputMessages?: number;
+}
+/**
+ * runExecutable 同步模式响应 data — 一次性返回执行结果。
+ *        流式模式（pty/pipe）不走此结构，见 RunExecutableStreamResponse。
+ *        decisionRecords 为 center 权威 DecisionRecord（统一决策记录，全态含
+ *        action/domain/reason/matchRule）；无拦截时输出空数组。
+ */
+export interface RunExecutableResponse {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    timedOut?: boolean;
+    decisionRecords: DecisionRecord[];
+}
+/**
+ * runExecutable 流式模式（pty/pipe）响应 data — 携带进程句柄。
+ *        流式输出通过 ProcessOutput 反向事件推送，退出通过 ProcessExit 通知。
+ */
+export interface RunExecutableStreamResponse {
+    processId: string;
+    pid: number;
+}
+/**
+ * OpenSession 请求 data — 创建一个新的沙盒会话。
+ *        会话直接以 workingDir 作为源目录建立（源目录直通，无投影层）。
+ *        是否启用网络代理（LocalProxy）由 Rust 内部决策：Windows 与 macOS 均
+ *        固定启用内置 LocalProxy（macOS 的 NetworkExtension 透明代理已移除）；
+ *        其他平台不支持代理。
+ */
+export interface OpenSessionRequest {
+    name?: string;
+    workingDir: string;
+}
+/** OpenSession 响应 data。 */
+export interface OpenSessionResponse {
+    workingDir: string;
+}
+/** reportBlockChoice 请求 data（宿主 → SandboxManager）。 */
+export interface ReportBlockChoiceRequest {
+    recordId: number;
+    blockType: string;
+    choice: string;
+}
+/** processWrite 请求 data — 向交互式进程的 stdin 写入数据。 */
+export interface ProcessWriteRequest {
+    processId: string;
+    data: string;
+}
+/** processSendKey 请求 data — 发送特殊按键到交互式进程。 */
+export interface ProcessSendKeyRequest {
+    processId: string;
+    key: string;
+}
+/** processResize 请求 data — 调整交互式进程的虚拟终端大小。 */
+export interface ProcessResizeRequest {
+    processId: string;
+    cols: number;
+    rows: number;
+}
+/** processKill 请求 data — 终止交互式进程。 */
+export interface ProcessKillRequest {
+    processId: string;
+    signal?: string;
+}
+/** processIsAlive 请求 data — 查询交互式进程是否仍在运行。 */
+export interface ProcessIsAliveRequest {
+    processId: string;
+}
+/** processIsAlive 响应 data。 */
+export interface ProcessIsAliveResponse {
+    alive: boolean;
+}
+/** processOutput 反向事件 data — 流式进程输出数据。 */
+export interface ProcessOutputEvent {
+    processId: string;
+    data: string;
+    stream?: 'stdout' | 'stderr';
+}
+/**
+ * processExit 反向事件 data — 交互式进程退出通知。
+ *
+ * `decisionRecords` 为本次进程生命周期内累积的拦截记录（center 权威
+ * DecisionRecord：action + domain + reason + matchRule，判定态由 record.action
+ * 承载）；对于未触发任何拦截的进程，字段为空数组。
+ */
+export interface ProcessExitEvent {
+    processId: string;
+    exitCode: number;
+    killed?: boolean;
+    decisionRecords: DecisionRecord[];
+    /**
+     * 通用进程级指标透传 map（随 ProcessExit 带回宿主）。key 由业务侧约定。
+     * center 决策指标约定 key（见 protocol_impl decision_ipc_metrics_keys）：
+     *   centerDecideCount   = 该进程生命周期内决策 IPC 总次数（file+network+command）
+     *   centerDecideCostUs  = 同窗口决策处理总耗时（微秒，center 内）
+     *   centerDecideFileCount / centerDecideNetworkCount / centerDecideCommandCount = 三类分量
+     * 数据源：center 侧 L3 (session,pid) 决策分桶（sandbox.monitor.query_session），
+     * 桶随该 (session,pid) 首条 decide 懒创建，故计数即生命周期总量（无需差值）；
+     * cli 退出时单次查询消费，并以 firstSeenMs 校验桶出生时间防 pid 复用残留。
+     * center 不可达/校验失败时 metrics 缺省（fail-open）。
+     * 注意：并发进程的计数按 (session,pid) 天然隔离，可跨进程求和；
+     * 会话总量看 GetStatistics.decisionIpcTotal（center session 级聚合）。
+     * （旧 decisionIpcBefore/After 为 cli 本地计数器口径，已随决策 IPC 迁 center 退役。）
+     * 用 map 而非专用结构：后续新增维度只加 key，免改 proto/codegen。
+     */
+    metrics?: Record<string, string>;
+    /**
+     * 该进程输出是否因超限被截断（含两种来源：maxOutputBytes/maxOutputMessages
+     * 主动限流、流式队列溢出后按 process 隔离）。CLI 侧据此把结果标记为
+     * "输出已截断"而非"失败"，用户可感知并重试更窄的查询。
+     */
+    outputTruncated?: boolean;
+}
+/**
+ * sandbox 端运行中业务事件统一上报通道。
+ *        ReportEventRequest 是 sandbox-cli 专用 IPC 信封，host 端固定映射为
+ *        sandbox_event；scene / action / status 决定具体场景，ext1~ext6 为
+ *        JSON 字符串承载场景相关额外字段（与 host 端 ext1~ext6 列语义一致，
+ *        本期默认只用 ext1，ext2~ext6 为预留扩展位，避免后续每加一个场景都
+ *        要改 proto / 改类型）。
+ *        sandbox 模块通过 EventReporter trait 调用，host 端在 onReverseRequest
+ *        中识别 "ReportEvent" 命令并透传给 SandboxTelemetryReporter.ingestRawEvent。
+ */
+export interface ReportEventRequest {
+    scene: string;
+    action: string;
+    status: string;
+    costMs?: number;
+    toolCallId?: string;
+    ext1?: string;
+    ext2?: string;
+    ext3?: string;
+    ext4?: string;
+    ext5?: string;
+    ext6?: string;
+}
+/**
+ * bidirectional：cli 侧消费 center 响应时需反序列化（ProcessExit 统一决策记录
+ * 透传链路，见 docs/process-exit-block-record-unification-design.md §4.4）。
+ * 决策响应统一记录（原 BlockRecord，2026-08-21 评审优化更名）——
+ *        allow/deny/ask **全态必返**（Decide* 响应 decisionRecord 恒有值，
+ *        审计闭环不分态），action 内嵌进 record：脱离响应上下文转发
+ *        （audit_shmem / ProcessExit）后仍可判态，业务侧据 action 即知为何，
+ *        reason 无需分态值。
+ *        结构：action（裁决本体，allow|deny|ask）+ domain（来源裁决入口）+
+ *        reason（成因，center 权威值域）+ matchRule（命中规则摘要）。
+ *        allow 的 record：reason 为命中类（命中 allow 规则）或 RULE_MISSING
+ *        （fail-open 放行，如 network 空库）；matchRule 随命中填充。
+ *        演进说明（error_code/error_description 模式）：reason 枚举即
+ *        error_code（机器可 switch，center 权威定义，见枚举 doc）；matchRule
+ *        的 ruleHint/pattern/category 承担 error_description 角色（人读 +
+ *        规则列表 join key）。接线前的待启用值（http_intercept /
+ *        forbidden_program / dangerous_url）由判定层接入时逐个点亮，单测锁死
+ *        「当前判定层实际产出值集合」防漂移。
+ *        例外路径（sandbox-exec 静态 profile）：本地拦截无 center 判定上下文，
+ *        消费侧（sandbox-cli）从后置日志拿到被拦文件后回放一次 center
+ *        Decide* 请求获得权威 record（Phase 2 接入项）。
+ *        授权申请资格由消费端按设计文档 §1.3 契约从 record.action 推导（仅
+ *        ask 触发申请，一切 deny 静默失败），不上 wire。
+ */
+export interface DecisionRecord {
+    action: RuleAction;
+    domain?: DecisionDomain;
+    reason?: DecisionReason;
+    /** 命中规则摘要：命中类来源时填充，RULE_MISSING 时缺省。 */
+    matchRule?: MatchedRuleInfo;
+    /**
+     * 实际资源事实：与 matchRule（命中规则摘要）分离，供 ProcessExit 脱离请求
+     * 上下文后仍能精确审批、展示和审计。字段按 domain 选择性填充。
+     */
+    path?: string;
+    destinationPath?: string;
+    operation?: DecisionOperation;
+    host?: string;
+    port?: number;
+    scheme?: string;
+    /**
+     * 决策时点的敏感检测命中明细：仅 reason=SENSITIVE_INFO（decide_file 按需检测，
+     * allow→ask 升级路径）时填充，元素结构与 DetectSensitiveInfoResponse.detectedItems
+     * 同源（DetectedItem：明文+规则名+来源+加密能力）。无时效快照（展示/分流素材）。
+     * 通道边界（v6 设计 docs/decide-file-sensitive-items-passthrough-design.md §3.9）：
+     * 仅完整 record JSON wire（同机已鉴权 client，先例 detect 响应本就在送明文）；
+     * 不进 shmem 定长事件（Windows 折叠路径无此键，cli 上 wire 前经 DETECT 缓存补全）；
+     * 不进任何日志；不截断（1MB 检测上限天然上界）。
+     */
+    sensitiveItems?: DetectedItem[];
+    /**
+     * Notify 受理凭证：center 在 decide_file 命中时铸造并登记 PendingDetections
+     * （TTL 5min，claim 一次性）；cli 在 ProcessExit 上 wire 前统一刷新（缓存命中重铸，
+     * 保新鲜）；上层 NotifyEncryptionChoice 直接携带。
+     * **同文件多条记录共享同一 id（按 path 去重契约）**：一次命令内同文件 N 次读
+     * 产生 N 条 ask 记录，cli 补全按 path 去重后回填同一 id——Notify claim 一次性
+     * 消费，上层必须**按 path 维度确认并 Notify 一次**（逐条 Notify 时第二条必然
+     * claim 失败，属预期拒绝而非错误）。
+     */
+    detectionId?: string;
+    /**
+     * 记录组装来源（2026-09-16 新增）——**record 可信度判别**，与 reason 正交
+     * （reason=为什么被拦，source=字段是谁算出来的）。见 DecisionRecordSource 值域：
+     * center_rule / syslog_deny 的 operation 维度权威（内核或判定层给出），
+     * cli_synthesized 的是 cli 从 SBPL 文本反推的推定值——下游**不得**据后者做按维
+     * 回查/审批归因，应以 path 为主体改按 Read 维裁决。缺省（不传）等价
+     * center_rule（老 client 兼容）。
+     */
+    source?: DecisionRecordSource;
+}
+/**
+ * bidirectional：cli 侧消费 center 响应时需反序列化（同 DecisionReason）。
+ * 命中规则摘要（匹配素材分层，不散落 record 顶层）。命中类来源
+ *        （rule / http_intercept / forbidden_program / dangerous_url——pattern
+ *        分别为规则 pattern/target/program 名/域名）时填充；RULE_MISSING
+ *        （无任何命中，兜底策略）时整个子结构缺省（结果由 record.action 表达）。
+ */
+export interface MatchedRuleInfo {
+    /**
+     * 命中规则的原始标识串（零加工透传，规则列表 join key —— 宿主规则清单显示
+     * 什么就回什么，可按 pattern 回找/编辑命中规则）：file=original_path（用户
+     * 下发 path 原文，目录 \** 增强与占位符展开不回显；** 兜底裁决时为兜底规则
+     * 原文，通常即 "**"）；network=endpoint 原文；cmd=cmd 主字段（args 不拼接）。
+     */
+    pattern?: string;
+    /**
+     * 规则自带的原因文本（当前仅 cmd_rules 的 reason 字段有值，file/network
+     * 规则模型无 reason 字段，缺省）。
+     */
+    ruleHint?: string;
+    /**
+     * 命中规则所属层（enterprise/temp/global/session/auto_grant）。
+     * 授权申请资格不按 category 分支（决策 #15：仅 ask 触发，一切 deny 静默
+     * 失败），category 仅作审计/展示（规则列表 join key 的一部分）。
+     */
+    category?: RuleCategory;
+    /** 宿主提供的不透明规则身份；沙箱仅随实际胜出规则透传，不用于裁决。 */
+    ruleRef?: string;
+}
+/**
+ * 单条敏感信息命中项,携带来源信息,供审批询问展示与对账。
+ *       **全链路唯一结构**:detect 响应 / PendingDetections 登记 / 审批请求 / 审批响应 都用它,
+ *       不额外定义 ApprovalItem。rule_name 直接存规则名(非 rule_id):协调器经 DetectView
+ *       传入的规则名映射快照在 detect 出口就映射好,下游(pending/审批)不再二次映射。
+ *       rule_id 为命中规则的 id(通路 B),仅供 center 内部给自动生成的 CipherEntry 派生展示名
+ *       (判 source:自定义规则用 rule.name、系统预置规则用 rule.id),不对外展示;
+ *       与 rule_name 不冗余——rule_name 服务审批展示,rule_id 服务内部命名。
+ *       - 通路 A(明文密钥对精确匹配)命中:rule_name 为空、rule_id 为空,source="plaintext"(命中已记录明文条目);
+ *       - 通路 B(betterleaks 正则规则)命中:rule_name 为命中规则的 name、rule_id 为命中规则的 id,source="regex";
+ *         若 rule_id 在映射快照中找不到(规则被删/未加载),rule_name 为空但 source 仍为 "regex"(rule_id 仍带出)。
+ *       - 逆向检测(detect_mode=reverse)命中:rule_name/rule_id/category 均空,source="cipher",cipher 字段填命中的
+ *         cipher 串(上层替换依据),plaintext 为该 cipher 反查得到的明文。逆向只走 cipher 精确多模式匹配,不走 betterleaks。
+ *       bidirectional 因 detect 响应(需 Serialize 发出)、审批请求(center 发,Serialize)、
+ *       审批响应(原样带回,center 收,Deserialize)三处都要用。
+ */
+export interface DetectedItem {
+    plaintext: string;
+    ruleName?: string;
+    source: string;
+    /**
+     * 命中规则的 id(通路 B,仅 center 内部消费:给 allow_cipher 自动生成的 CipherEntry 派生展示名、
+     * extract_prefix 前缀提取反查规则 regex;判 source:自定义/企业规则用 rule.name、system 预置用 rule.id)。
+     * 通路 A / betterleaks 空 RuleID / 逆向检测为空。client 回传方向(notify/approval-response 回带)
+     * 携带时 center 以命中集为权威、忽略回传值(CR#2 防伪造前缀)。
+     */
+    ruleId?: string;
+    /**
+     * 命中数据的来源层级(2026-09-08 评审定档):上层据此前置分流(如 enterprise 命中不可降级、
+     * system 条目走默认审批文案)。值 = 胜出数据源的 CipherRuleSource:
+     * - 通路 B 命中:胜出规则(同明文多条规则命中按 enterprise > user > system 取胜者)的 source;
+     * - 通路 A 命中:胜出条目(同明文多 entry 命中按 enterprise > user > system 取胜者)的 source;
+     * - 逆向检测(source="cipher"):反查到的 entry 的 source。
+     * 与 source(检测通路)正交:source 答「哪条通路找到的」,cipherSource 答「胜出数据属于哪一层」。
+     * client 回传方向(notify/approval-response 回带)携带时 center 以命中集为权威、忽略回传值。
+     */
+    cipherSource?: CipherRuleSource;
+    category?: string;
+    cipher?: string;
+    /**
+     * 命中项的裁决 action(2026-09-08 评审定档,center 下发前已按多规则合并定档):
+     * - allow:命中项放行明文——**center 侧已在检测出口剔除,正常链路不会下发 allow 项**
+     *   (防御位:逆向/缓存重放等特殊路径若出现,上层按放行处理);
+     * - deny:命中项拒绝访问——decide_file 按需检测路径据此直接合成 deny(异步确认模式);
+     *   普通 detect 保留上报(审计可见性),上层据此前置分流;
+     * - ask:走既有加密授权链路(现状行为)。
+     * 值 = 胜出规则(通路 B)或胜出 entry(通路 A)的 action,缺省 ask;
+     * 跨通路冲突取最严(deny > ask > allow)。多规则命中合并见 DetectRule.action @doc。
+     * client 回传方向携带时 center 以命中集为权威、忽略回传值。
+     */
+    action?: RuleAction;
+    /**
+     * 命中项的审批选项集(Q3 定档 + 能力归一,2026-09-08 评审):
+     * - 值 = 胜出规则的 DetectRule.ask_options(空=缺省全集 {allow_cipher, allow_plaintext, deny}),
+     *   **再 ∩ 命中项加密能力**——center 下发前已归一,不可加密命中项(高熵宽泛规则/workbuddy 规则/
+     *   无合法派生来源,原 supports_encryption=false 语义)的选项集**不含 allow_cipher**(可退化为
+     *   [allow_plaintext, deny] 或仅 [deny]);通路 A 命中取 entry 自身 ask_options
+     *   (entry 级定制,Q11 追加定档;缺省 None=全集),不再恒缺省全集。
+     * - **取代原 supports_encryption 字段 5**(随本变更退役,字段号不复用):"是否可加密"由
+     *   ask_options 是否含 allow_cipher 表达,信息无损且上层零二次计算——审批 UI 直接按选项集渲染,
+     *   不再存在"规则选项 ∩ 能力"的双读(原 supports_encryption 与 ask_options 两字段交叉判定的合并逻辑
+     *   收敛到 center 下发前单点完成);center apply_decision 拦截逻辑同样改读 ask_options。
+     * - **随胜者**(Q3 改档,2026-09-08):同明文多规则合并时选项集随胜出规则(与归因同源),
+     *   center 单点下发已归一值;原「上层取交集」口径废弃——上层不得再对多命中取交集
+     *   (交集可能意外收窄,如 [allow_cipher,deny]∩[allow_plaintext,deny]=[deny],
+     *   两个合法定制合并后只剩拒绝)。
+     * - **弱脱敏判据**(2026-09-09 中文/混合明文增强,阈值 0.90):center 按 flip 结构
+     *   预判翻转后**原样保留**占比(前缀段 + 符号/中文等不可映射位 / 明文总位数,与 flip
+     *   输出逐位同构,不真跑哈希);保留 ≥90% → 剔除 allow_cipher(密文 90%+ 与明文相同,
+     *   「允许脱敏」选项无意义——如中文规则命中的纯中文/中文主体明文)。归一入口与加密
+     *   能力(supports_encryption)同点:normalize_ask_options 的
+     *   can_encrypt = supports_encryption && !weak_mask。
+     * - client 回传方向(notify/approval-response 回带)携带时 center 以命中集为权威、忽略回传值。
+     * - 逆向检测(source="cipher")省略本字段(逆向是还原,不触发审批选项)。
+     */
+    askOptions?: ApprovalDecision[];
+}

package/cli/dist-server/types/workspace/sandbox-cli/lib/node/file-policy.d.ts

@@ -0,0 +1,48 @@
+import { type FilePolicyRule, type FileRuleAction, type FileRuleOperation } from '../common/file-policy.js';
+export interface FilePolicyRuntimeFacts {
+    platform: NodeJS.Platform;
+    homeDir: string;
+    workspacePath: string;
+    /** Product-specific paths are supplied by the host, not discovered through agent-cli. */
+    writableDirectories?: readonly string[];
+    protectedRules?: readonly FilePolicyRule[];
+    readOnlyRuntimeDirectories?: readonly string[];
+    /** Whether modify backup was successfully enabled for the native session. */
+    modifyBackupEnabled?: boolean;
+    /** Whether the generated catch-all rule should allow deletion. */
+    allowDeleteFallback?: boolean;
+    /** Per-delete action for the generated fallback; takes precedence over the legacy boolean. */
+    deleteFallbackAction?: FileRuleAction;
+    isDirectory?: (filePath: string) => boolean;
+}
+export declare function expandFilePolicyPath(rulePath: string, facts: Pick<FilePolicyRuntimeFacts, 'platform' | 'homeDir' | 'workspacePath'>): string;
+/** Compile configuration only. No permission matching, approval or IPC occurs here. */
+export declare function buildFileRules(configuredRules: readonly FilePolicyRule[] | undefined, facts: FilePolicyRuntimeFacts): FilePolicyRule[];
+/** 会话目录批准：目录内（含子目录）指定操作由 ask 转为 allow。directory 须为真实绝对路径。 */
+export interface FileDirectoryApproval {
+    directory: string;
+    operation: FileRuleOperation;
+}
+/**
+ * Center 规则 DSL 没有转义：`*`/`?` 是通配，`{NAME}`/`$VAR`（Windows 还有 `%VAR%`）会被展开，
+ * 非 Windows 上 `\` 被当作分隔符。含这些字符的真实目录无法按字面写进规则，不能获得目录批准。
+ */
+export declare function isLiteralApprovalDirectory(directory: string, platform: NodeJS.Platform): boolean;
+/**
+ * 在 buildFileRules 生成的完整有序规则上编译目录批准，不新增 Center 能力或兜底规则。
+ *
+ * Center 按首条命中裁决。对每条原规则 R，在其正前方插入子规则 R_in：
+ * 路径为 R 与批准目录交集的**可精确表达的子集**，动作仅把已批准操作中的
+ * ask/未声明改为 allow，deny 与其他操作原样保留。R_in 命中的路径若没有被
+ * 更早规则命中，原本必然由 R 命中，因此只有“R 的 ask 被批准”这一处变化，
+ * 无法表达交集时不插入（保持询问）。结果只能等于或窄于
+ * “基础裁决为 ask 才转 allow”，不会越过 deny。
+ *
+ * 文件规则变更时须全量重建，重新计算原规则与批准目录的交集和顺序。
+ *
+ * Center SetFileRules 按 path 原文去重（保留首次位置、取最后一次内容），
+ * 输出不能含重复 path，否则后面的规则内容会被搬到前面的位置。
+ */
+export declare function applyFileDirectoryApprovals(rules: readonly FilePolicyRule[], approvals: readonly FileDirectoryApproval[], platform: NodeJS.Platform): FilePolicyRule[];
+/** 原生回显的是原始规则路径，目录规则尚未追加 /**；非通配规则已由原生确认匹配。 */
+export declare function canApplyFileDirectoryApproval(pattern: string, directory: string, platform: NodeJS.Platform): boolean;

package/cli/dist-server/types/workspace/sandbox-cli/lib/node/resolver.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 构造当前平台对应的「同级平台核心包」名。
+ *
+ * 格式：`@tencent-ai/sandbox-cli-<platform>-<arch>`，
+ * 如 `@tencent-ai/sandbox-cli-darwin-arm64`、`@tencent-ai/sandbox-cli-win32-x64`。
+ *
+ * sandbox 二进制不再随 `@genie/sandbox-cli` 本包，而是作为独立的按平台 npm 包，
+ * 经 `optionalDependencies` 安装到同级 `node_modules`。故 resolver 解析的是
+ * 这个同级平台包，而非本包内的 `platforms/` 子目录。
+ *
+ * 注意：sandbox-cli **不发** universal binary，统一按 process.arch 分拆平台包。
+ * 在 macOS Rosetta 下 Node 的 process.arch 会是 'x64'（即便宿主机是 arm64），
+ * 此时会落到 darwin-x64 包，对应的 sandbox-cli 二进制也是 x64 slice。这与
+ * 宿主 Electron app 的架构期望一致（如果 Electron 是 arm64 native，Node 会是
+ * arm64 → process.arch === 'arm64'），不需要额外的 native arch 探测。
+ *
+ * 如果未来引入 universal Electron 但 sandbox-cli 仍走单 arch，需要在这里
+ * 增加 native arch 兜底（通过 `sysctl.proc_translated` 或 `uname -m`）。
+ */
+export declare function sandboxPackageName(platform: string, arch: string): string;
+/**
+ * 当前平台对应的 sandbox-cli 可执行文件名。仅 Windows 带 `.exe` 后缀。
+ */
+export declare function sandboxExeName(platform: string): string;
+/**
+ * 获取当前平台对应的平台包 bin 目录绝对路径。
+ *
+ * @param resolveFrom 安装平台包的宿主模块目录；省略时保持原解析位置。
+ * @returns bin 目录路径，若平台包未安装或目录不存在则返回 undefined
+ */
+export declare function getSandboxCliBinDir(resolveFrom?: string): string | undefined;
+/**
+ * 获取当前平台对应的 sandbox-cli 可执行文件路径。
+ *
+ * 查找优先级：
+ * 1. 环境变量 SANDBOX_CLI_PATH（开发调试用）
+ * 2. Desktop 正式包 cli/vendor/sandbox/<version>/
+ * 3. Bun SFE 可执行文件同级 vendor/sandbox/<version>/
+ * 4. 从同级平台包 bin/ 目录 resolve
+ *
+ * @param resolveFrom 只指定平台包 fallback 的宿主模块目录，不改变 env/vendor 优先级。
+ * @returns 可执行文件绝对路径，若平台包不存在则返回 undefined
+ */
+export declare function getSandboxCliPath(resolveFrom?: string): string | undefined;
+/**
+ * 获取当前平台对应的 sandbox-cli 期望路径，**不验证存在性**。
+ *
+ * 用于错误信息上报：调用方需要列出"我探测过哪些路径"，
+ * 即便 fs.existsSync 失败也得能拿到这个字符串。
+ *
+ * 优先级与 {@link getSandboxCliPath} 一致：env > 平台包 bin。
+ * 解析包根失败时返回 undefined（这种情况平台包本身没装）。
+ * @param resolveFrom 与实际 binary 解析使用同一个宿主模块目录。
+ */
+export declare function getExpectedSandboxCliPath(resolveFrom?: string): string | undefined;
+/**
+ * 获取 tsbx_rules.json 默认配置文件路径。
+ *
+ * 规则文件随平台核心包以 `bin/tsbx_rules.json` 投放——与 sandbox-cli 同目录。
+ */
+export declare function getTsbxRulesPath(): string | undefined;
+/**
+ * 当前平台对应的 sandbox-center 可执行文件名。仅 Windows 带 `.exe` 后缀。
+ */
+export declare function sandboxCenterExeName(platform: string): string;
+/**
+ * 当前平台对应的 betterleaks 可执行文件名（敏感信息检测引擎通路 B，Go 子进程）。仅 Windows 带 `.exe` 后缀。
+ */
+export declare function betterleaksExeName(platform: string): string;
+/**
+ * 获取当前平台对应的 sandbox-center 可执行文件路径。
+ *
+ * 查找优先级（覆盖 dev / packaged / 调试全形态）：
+ * 1. 环境变量 `SANDBOX_CENTER_PATH`（开发调试用，命中即返回不校验存在性）；
+ * 2. `SANDBOX_CLI_PATH` 同目录的 sandbox-center（宿主只注入 sandbox-cli 路径时，center 随之同目录）；
+ * 3. desktop 正式包 `cli/vendor/sandbox/<version>/sandbox-center[.exe]`（copy-cli.js 版本隔离布局，兼容平铺回落）；
+ * 4. Bun SFE 可执行文件同级 `vendor/sandbox/<version>/sandbox-center[.exe]`（goreleaser 归档布局，兼容平铺回落）；
+ * 5. 同级平台包 `bin/sandbox-center[.exe]`（`@tencent-ai/sandbox-cli-<os>-<arch>`，dev fallback）。
+ *
+ * 三个拉起方（workbuddy-desktop 主进程 / daemon sensitive-protection-management /
+ * agent-cli 检测链）统一走这里，避免各自复制「平台包解析 + 路径拼接」。
+ *
+ * @returns 可执行文件绝对路径；均未命中返回 undefined（静默降级）。
+ */
+export declare function getSandboxCenterPath(): string | undefined;
+/**
+ * 获取当前平台对应的 betterleaks 可执行文件路径（敏感信息检测引擎通路 B，Go 子进程）。
+ *
+ * 缺失时 center 走 UnavailableBackend 降级（通路 A 仍工作），故缺失返回 undefined，调用方省略注入。
+ * 优先级：env `SANDBOX_BETTERLEAKS_PATH` → 与 sandbox-center 同目录（{@link getSandboxCenterPath}
+ * 的全优先级链）；center 解析不到即 undefined（三件套同目录契约，不独立混版解析）。
+ *
+ * @returns 可执行文件绝对路径；缺失返回 undefined。
+ */
+export declare function getBetterleaksPath(): string | undefined;

package/cli/dist-server/types/workspace/sandbox-cli/lib/node/sandbox-cli-client.d.ts

@@ -0,0 +1,78 @@
+import { type IpcMessage, type JsonValue, type SandboxCommand } from '../common/protocol.generated.js';
+export interface SandboxCliClientLogger {
+    info?(message: string): void;
+    error?(message: string): void;
+}
+export interface SandboxCliClientConfig {
+    sessionId: string;
+    address: string;
+    connectTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    heartbeatIntervalMs?: number;
+    heartbeatTimeoutMs?: number;
+    autoReconnect?: boolean;
+    maxReconnectAttempts?: number;
+}
+export interface SandboxCliReverseListenerOptions {
+    commands: string[];
+}
+/** 同步和异步 listener 的错误都由分发侧捕获。 */
+export type SandboxCliReverseListener = (message: IpcMessage) => void | Promise<void>;
+export interface SandboxCliRequestContext<T> {
+    conversationRequestId?: string;
+    timeoutMs?: number;
+    /**
+     * Synchronous setup after a successful response, before resolving the Promise
+     * or dispatching the next wire message. Use this to register handles for
+     * immediately following events. Runs in the caller's async context;
+     * a thrown error rejects the request.
+     * Returning undefined deliberately excludes async callbacks.
+     */
+    onResponse?: (response: T) => undefined;
+}
+export interface SandboxCliClient {
+    connect(config: SandboxCliClientConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    sendRequest<T = JsonValue>(sessionId: string, command: SandboxCommand, data?: JsonValue, context?: SandboxCliRequestContext<T>): Promise<T>;
+    getPendingConversationRequestIds(): string[];
+    onReverseRequest(handler: (message: IpcMessage) => Promise<JsonValue | undefined>): void;
+    addReverseListener(options: SandboxCliReverseListenerOptions, handler: SandboxCliReverseListener): () => void;
+    onDisconnect(handler: () => void): () => void;
+    ping(): Promise<void>;
+}
+export declare function isSandboxCLIConnectTimeoutError(error: unknown): boolean;
+export declare function createSandboxCliClient(logger?: SandboxCliClientLogger): SandboxCliClient;
+export declare function resolveSandboxCliIpcPath(address: string, platform?: NodeJS.Platform): string;
+/** sandbox-cli NDJSON client shared by agent-cli and daemon runtimes. */
+export declare class SandboxCliClientImpl implements SandboxCliClient {
+    protected logger: SandboxCliClientLogger | undefined;
+    private _connected;
+    private _messageCounter;
+    private _socket;
+    private _lineBuffer;
+    private _config;
+    private readonly _pendingRequests;
+    private _reverseRequestHandler?;
+    private readonly _reverseListeners;
+    private readonly _disconnectListeners;
+    constructor(logger?: SandboxCliClientLogger);
+    protected setLogger(logger: SandboxCliClientLogger): void;
+    connect(config: SandboxCliClientConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    sendRequest<T = JsonValue>(sessionId: string, command: SandboxCommand, data?: JsonValue, context?: SandboxCliRequestContext<T>): Promise<T>;
+    getPendingConversationRequestIds(): string[];
+    onReverseRequest(handler: (message: IpcMessage) => Promise<JsonValue | undefined>): void;
+    addReverseListener(options: SandboxCliReverseListenerOptions, handler: SandboxCliReverseListener): () => void;
+    onDisconnect(handler: () => void): () => void;
+    ping(): Promise<void>;
+    private _tryConnect;
+    private _onSocketData;
+    private _handleMessage;
+    private _sendResponse;
+    private _rejectAllPending;
+    private _cleanupSocket;
+    private _handleDisconnect;
+    private _fireDisconnectListeners;
+}