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

package/cli/dist-server/types/node/sandbox-cli/sandbox-rule-sync-service.d.ts

@@ -0,0 +1,310 @@
+import { Logger } from '@celljs/core';
+import { type FileDirectoryApproval } from '../../workspace/sandbox-cli/lib/node/file-policy.js';
+import { type BashSandboxManager as IBashSandboxManager, type ModifyBackupExcludedPathOptions } from '../bash-sandbox/bash-sandbox-protocol';
+import { type SandboxCenterIpcClient as ISandboxCenterIpcClient } from '../sensitive-content/sandbox-center-ipc-client-protocol';
+import { type ISandboxCLILifecycle } from './sandbox-cli-lifecycle-protocol';
+import type { SandboxTurnConfig as ISandboxTurnConfig } from './sandbox-turn-config';
+export declare const SandboxRuleSyncService: unique symbol;
+export declare class FileDirectoryApprovalError extends Error {
+    readonly allowOnce: boolean;
+    constructor(message: string, allowOnce: boolean);
+}
+export type SandboxRuleSyncStatus = 'applied' | 'deferred' | 'failed';
+export interface SandboxRuleSyncResult {
+    status: 'applied' | 'deferred';
+}
+/** path 为本次询问的真实目标，directory 为宿主从该目标推导出的授权目录。 */
+export interface SandboxFileDirectoryApprovalRequest extends FileDirectoryApproval {
+    path: string;
+}
+export interface SandboxRuleSyncService {
+    /**
+     * Turn 开始时同步所有必要的沙箱规则。
+     * 由 interceptor 每轮调用一次，作为 Turn 级规则同步的统一入口。
+     */
+    syncRulesOnTurnStart(sessionId: string, permissionMode?: string): Promise<SandboxRuleSyncResult>;
+    /** 安全中心配置变更时刷新持久规则，不清理当前 Turn 的临时规则。 */
+    syncRulesOnConfigRefresh(sessionId: string, permissionMode?: string): Promise<SandboxRuleSyncResult>;
+    getFilePolicyGeneration(sessionId: string): number;
+    supportsFileDirectoryApproval(sessionId: string): boolean;
+    hasFileDirectoryApprovals(sessionId: string): boolean;
+    /** 新 worker 在首次规则同步前合并宿主保存的已确认目录批准。 */
+    restoreCommittedFileApprovals(sessionId: string, approvals: readonly FileDirectoryApproval[]): void;
+    onFileApprovalCommitted(listener: (approval: FileDirectoryApproval & {
+        sessionId: string;
+    }) => void): () => void;
+    /**
+     * 登记本会话目录批准并重建文件规则；复核目标已被放行后才返回。
+     * 失败时撤回本次登记并恢复原规则。
+     */
+    grantFileApproval(sessionId: string, request: SandboxFileDirectoryApprovalRequest, expectedGeneration: number): Promise<{
+        registered: boolean;
+    }>;
+    /**
+     * 目录授权回滚失败后，原生端可能残留允许规则：执行受保护操作前重新全量下发，
+     * 恢复失败则抛错，调用方必须拒绝执行。其他同步失败不影响。
+     */
+    ensureFileApprovalRulesSettled(sessionId: string): Promise<void>;
+    /**
+     * 订阅 center 重连事件以重推全量规则(可选能力,#126618 规则空窗修复)。
+     * 幂等;由首个消费者(interceptor PostConstruct)调用一次。
+     */
+    subscribeCenterReconnect?(): void;
+    /**
+     * 安全中心文件白名单路径的通用 `~/...` 展开，不继承 sandbox manager 的产品
+     * 目录特殊规则。供 SandboxShellService.applyRulesDelta 在下发增量时复用。
+     */
+    expandSecurityCenterPath(p: string): string;
+    /**
+     * 记录一次「会话级放行」的明文 HTTP host（用户在 HTTP 拦截弹窗选了「本次会话放行」）。
+     *
+     * 该 host 会在后续每次 `syncRulesOnTurnStart` 以 `{target: host, action: 'allow'}`
+     * 前置注入到 HttpInterceptRule 表，确保该会话内此 host 的明文 HTTP 不再被拦。
+     * 按 sessionId 隔离，不同会话的放行不互通。
+     */
+    addSessionAllowHttpHost(sessionId: string, host: string): void;
+    /**
+     * 读取指定会话的「会话级放行」host 集合（只读视图）。
+     * 诊断/测试用途；规则下发走全部会话并集（见 getAllSessionAllowHttpHosts）。
+     */
+    getSessionAllowHttpHosts(sessionId: string): ReadonlySet<string>;
+    /**
+     * 会话结束时清理该会话的「会话级放行」host 集合，防止长跑进程内存缓慢泄漏。
+     */
+    clearSessionAllowHttpHosts(sessionId: string): void;
+    /**
+     * 会话释放的完整收口：清内存集合 + 重建 Center 的进程级 HTTP 拦截规则表。
+     *
+     * SetHttpIntercept 是进程级全局替换，只清内存不重建的话，已结束会话的
+     * allow_session 放行会在 Center 残留——其他会话访问同一 host 会跳过拦截
+     * 确认，相当于未经批准直接放行。
+     *
+     * 由 SessionManager.releaseInMemory（同步上下文）调用，重建为
+     * fire-and-forget：失败仅 log，不阻塞会话清理；残留风险由下一次
+     * turn-start 的全量下发兜底。该会话本就无放行 host 时不触发 IPC。
+     */
+    releaseSessionHttpIntercept(sessionId: string): void;
+    /**
+     * 用最新 config + 会话级放行 host 重算 HttpInterceptRule[] 并全量下发
+     * `SetHttpIntercept`。
+     *
+     * 供 HTTP 拦截弹窗「本次会话放行」后立即调用（`addSessionAllowHttpHost` 之后），
+     * 让放行 host 即时进入 Center 规则表——不等下一个 turn 的
+     * `syncRulesOnTurnStart`，同一 turn 内后续命令即不再被拦。
+     *
+     * fullAccess-relaxed 下直接下发空 rules（fail-open），不施加 HTTP 拦截。
+     */
+    syncHttpIntercept(sessionId: string): Promise<void>;
+    /**
+     * 实时同步网络严格模式开关（genie/genie#122764）。
+     *
+     * 供 `SandboxShellService.applyRulesDelta` 在收到 `networkStrictMode` 增量时调用，
+     * 让开关即时生效——不等下一个 turn 的 `syncRulesOnTurnStart` 全量下发。
+     *
+     * 与 `syncHttpIntercept` 的差别：裸布尔、无 fullAccess 特例、无「读内存集合重算」。
+     * 仅 macOS 下发（非 darwin 直接 no-op）。
+     */
+    syncNetworkStrictMode(sessionId: string, enabled: boolean): Promise<void>;
+}
+export declare function isWindowsAllowWriteNoBackupPath(rulePath: string, options?: Omit<ModifyBackupExcludedPathOptions, 'platform'>): boolean;
+export declare class SandboxRuleSyncServiceImpl implements SandboxRuleSyncService {
+    private readonly sessionSyncQueues;
+    private readonly sessionSyncStates;
+    private readonly sessionSyncGenerations;
+    private readonly sessionLifecycleGenerations;
+    /** 复核期间的暂存批准；原生会话换代时丢弃。 */
+    private readonly sessionFileApprovals;
+    /** 已经通过 Center 复核的批准；原生会话换代后重新编入规则。 */
+    private readonly committedFileApprovals;
+    private readonly fileApprovalCommittedListeners;
+    /** 目录授权回滚失败、原生端可能残留允许规则的会话 → 当时的规则代际。 */
+    private readonly unsettledFileApprovalSessions;
+    private nextFilePolicyGeneration;
+    protected readonly logger: Logger;
+    protected readonly bashSandboxManager?: IBashSandboxManager;
+    protected readonly turnConfig: ISandboxTurnConfig;
+    protected readonly lifecycle?: ISandboxCLILifecycle;
+    protected readonly sandboxCenterClient?: ISandboxCenterIpcClient;
+    /**
+     * 会话级「放行」明文 HTTP host 集合，按 sessionId 隔离。
+     *
+     * 来源:用户在 HTTP 拦截弹窗选「本次会话放行」时 {@link addSessionAllowHttpHost} 写入。
+     * 消费:每次 {@link syncRulesOnTurnStart} 全量下发 + {@link getSessionAllowHttpHosts}
+     * 供 SandboxShellService.applyRulesDelta 实时同步时合并重算。
+     */
+    protected readonly sessionAllowHttpHosts: Map<string, Set<string>>;
+    /**
+     * 最近一次**成功全量下发**规则的会话快照(sessionId → 下发时的 permissionMode)。
+     *
+     * 消费:center 重连时({@link subscribeCenterReconnect})的重推——center 重启后
+     * 内存规则全空(RuleMissing 空窗,#126618),对本快照里的每个会话按当时的
+     * permissionMode 重推全量规则,填上「重连到下一轮 turn-start」之间的空窗。
+     *
+     * 生命周期:syncRules 成功即记录/覆盖;会话释放(releaseSessionHttpIntercept /
+     * clearSessionAllowHttpHosts)同步摘除——已结束的会话不再参与每次重连的全量
+     * 重推(七轮 CR:不清则活跃会话越多,每次闪断重连都向 center 送一堆无人
+     * 消费的规则)。
+     */
+    protected readonly lastSyncedSessions: Map<string, string | undefined>;
+    /**
+     * 订阅 center client 的重连事件(幂等,重复调用只订阅一次)。
+     *
+     * 由模块装配处调用(agent 容器就绪后);client 可选注入,缺失(纯 CLI 无 center)
+     * 时不订阅。重连回调对 {@link lastSyncedSessions} 里每个会话按当时的
+     * permissionMode 重推**全局规则**({@link syncRulesOnConfigRefresh} 路径,
+     * 不清 auto_grant/temp)——fire-and-forget:失败仅留痕(重连瞬间的 center
+     * 可能仍在初始化,下一次 turn-start 的全量下发是兜底,重推只是把空窗收窄)。
+     *
+     * 不走 {@link syncRulesOnTurnStart}(七轮 CR):onReconnect 区分不了 center
+     * 真重启与 socket 闪断。闪断时 center 内存里本轮的临时放行(auto_grant/temp)
+     * 还在,turn-start 路径会先清空它们再写 global——对话中途的确认弹窗会
+     * 重新弹一遍。重连要补的只有全局规则;center 真重启后临时授权本来就要等
+     * 下一轮 turn-start 重建,不靠重推。
+     */
+    subscribeCenterReconnect(): void;
+    /** center 重连订阅的取消句柄(subscribeCenterReconnect 幂等用)。 */
+    private centerReconnectUnsubscribe;
+    addSessionAllowHttpHost(sessionId: string, host: string): void;
+    getSessionAllowHttpHosts(sessionId: string): ReadonlySet<string>;
+    /**
+     * 所有活跃会话的「会话级放行」host 并集。
+     *
+     * SetHttpIntercept 是进程级全局替换：重建规则表时只取当前 session 的
+     * allow hosts，会在别的 session（如 subagent）turn-start 时把父 session
+     * 已审批的 allow_session 放行冲掉。故下发时必须合并全部会话的并集。
+     * 已释放的会话（releaseInMemory → clearSessionAllowHttpHosts）自动退出并集。
+     */
+    private getAllSessionAllowHttpHosts;
+    clearSessionAllowHttpHosts(sessionId: string): void;
+    releaseSessionHttpIntercept(sessionId: string): void;
+    syncHttpIntercept(sessionId: string): Promise<void>;
+    /**
+     * 实时同步网络严格模式开关（delta 路径，genie/genie#122764）。
+     *
+     * 供 `SandboxShellService.applyRulesDelta` 在收到 `networkStrictMode` 增量时调用。
+     *
+     * **直接消费 delta 里的布尔值，不重读 settings.json**。`delta` 就是本次配置
+     * 变更的权威内容（由宿主在落盘后广播），而重读会引入两条错误路径：
+     * - `loadConfig()` 失败时回落到 `DEFAULT_SANDBOX_CONFIG`（不含该字段）→ 读成
+     *   `false`，用户刚打开的总闸被静默写回关闭；
+     * - 读盘有 TTL 缓存，即使 `clearCache` 也存在与广播的时序竞争。
+     * 用户点开 = 期望开启，任何读盘不确定性都不该把它变成关闭。
+     *
+     * 平台门控与 IPC 失败口径见 {@link setNetworkStrictMode}。
+     */
+    syncNetworkStrictMode(sessionId: string, enabled: boolean): Promise<void>;
+    syncRulesOnTurnStart(sessionId: string, permissionMode?: string): Promise<SandboxRuleSyncResult>;
+    syncRulesOnConfigRefresh(sessionId: string, permissionMode?: string): Promise<SandboxRuleSyncResult>;
+    getFilePolicySyncStatus(sessionId: string): SandboxRuleSyncStatus;
+    getFilePolicyGeneration(sessionId: string): number;
+    supportsFileDirectoryApproval(sessionId: string): boolean;
+    hasFileDirectoryApprovals(sessionId: string): boolean;
+    restoreCommittedFileApprovals(sessionId: string, approvals: readonly FileDirectoryApproval[]): void;
+    onFileApprovalCommitted(listener: (approval: FileDirectoryApproval & {
+        sessionId: string;
+    }) => void): () => void;
+    grantFileApproval(sessionId: string, request: SandboxFileDirectoryApprovalRequest, expectedGeneration: number): Promise<{
+        registered: boolean;
+    }>;
+    ensureFileApprovalRulesSettled(sessionId: string): Promise<void>;
+    /** 目录授权及回滚只同步文件规则，不依赖其他类型的规则同步。 */
+    private syncFileRules;
+    private runSessionSync;
+    /** 调用方必须已处于该会话的同步队列内。 */
+    private applySessionSync;
+    private withSessionSyncQueue;
+    private syncRules;
+    /**
+     * fullAccess 下只下发有序规则里的 allow，不下发 deny/ask。
+     *
+     * fullAccess 放开了全部网络规则，但恶意网站库不随之关闭，而 sandbox-cli 的
+     * 网络裁决只有第一层 `allowed_*` 能跳过威胁库查询。不下发白名单会让“请用户
+     * 把域名加入白名单”这个唯一放行出口在 fullAccess 下变成死路，也与 WebFetch
+     * （命中白名单即跳过威胁库）行为不一致。
+     */
+    private buildFullAccessNetworkRules;
+    /**
+     * 安全中心有序规则中的 allow 规则。始终最后追加，供 fullAccess-relaxed 保留
+     * 恶意域名库误报的显式放行入口。
+     *
+     * 三平台一视同仁。此前 Linux 被单独跳过，前提是 `decide_enable_proxy` 在 Linux 恒为
+     * false、规则下发了也没人执行，只会白付一层 `--unshare-net`。sandbox-cli 5.4.0-beta.17
+     * 起 Linux executor 改用 `needs_domain_layer_proxy`（有网络规则或有威胁库即挂
+     * LocalProxy）自行决策，规则会被真正执行，该前提不再成立。
+     */
+    private buildWhitelistNetworkRules;
+    private buildNetworkRules;
+    private syncCenterRules;
+    private setGlobalFileRules;
+    /**
+     * 全量下发明文 HTTP 拦截规则表（`SetHttpIntercept` 是全量替换协议）。
+     *
+     * `rules` 由 {@link buildHttpInterceptRules} 按三态配置 + allow 网络规则 +
+     * 全部会话的放行 host 并集翻译而来。空 `rules` → Center fail-open（放行所有
+     * 明文 HTTP），用于 fullAccess 或全 allow 场景。
+     *
+     * httpIntercept 是进程级全局状态（非 per-session），fullAccess-relaxed 下
+     * 必须下发空 rules——否则 Center 仍拦截产 http_intercept ask/deny 记录，
+     * 而该模式下无审批出口，命令会被 403 拦死。
+     *
+     * IPC 失败与 SetFileRules/SetNetworkRules/SetCmdRules 同口径：log 后抛出，
+     * 让 syncRulesOnTurnStart / applyRulesDelta 的调用方感知失败（Center 残留
+     * 旧规则表时 UI/host 不应误认为更新成功）。
+     */
+    private setHttpIntercept;
+    /**
+     * 下发网络严格模式开关（genie/genie#122764）。
+     *
+     * `SetRulesConfig` 是**进程级**命令（无 session 语义，与 `SetHttpIntercept` 同级），
+     * 一次写入即对本 center 进程内所有会话的新发起命令生效——已运行进程不受影响
+     * （其 SBPL profile 在 spawn 时已固化）。
+     *
+     * 与 httpIntercept 的差别：httpIntercept 要先把三态翻译成 `HttpInterceptRuleItem[]`
+     * 全量替换，本开关是裸布尔，直接透传即可（Center 侧 `networkStrictMode` 为 `Option<bool>`，
+     * 缺省=不改）。
+     *
+     * **仅 macOS 有执行面**：非 mac 平台的 center 收到后会打 warn（配了但不消费），
+     * 是刻意的 fail-visible 而非静默丢弃。平台门控收敛在本方法——两个入口
+     * （turn-start 全量、delta 实时）共用同一收口，避免各自判一次漏一个。
+     *
+     * **不随 fullAccess-relaxed 关闭**：与 httpIntercept 不同（那个在 fullAccess 下
+     * 必须下发空表，否则无审批出口会把命令 403 拦死），严格模式的语义是「逼流量进
+     * 代理」——它不产生 ask 记录，也不会因无审批出口而拦死命令；反过来在 fullAccess
+     * 下静默关掉它，会让「用户明确开了总闸」与「实际没开」不一致。故按配置原值下发。
+     *
+     * IPC 失败口径与 SetFileRules/SetHttpIntercept 一致：log 后抛出，让调用方感知
+     * （Center 残留旧档位时 UI/host 不应误认为已更新）。
+     */
+    private setNetworkStrictMode;
+    /** httpIntercept 前置放行的域名来源：有序网络规则中的 allow 规则。 */
+    private buildHttpInterceptAllowDomains;
+    private buildCenterCommandRules;
+    /**
+     * 将 settings.json 中的程序黑名单同步到 Sandbox Center session 规则层。
+     * Center 返回的是合并后的规则，不携带规则来源；删除时显式限定 session
+     * category，避免影响全局或企业规则。程序黑名单是独立的高风险拦截能力，
+     * 即使 permissionMode=fullAccess 也保持生效。
+     */
+    private syncProgramBlacklist;
+    /** 安全中心文件白名单只做通用 `~/...` 展开，不继承 sandbox manager 的产品目录特殊规则。 */
+    expandSecurityCenterPath(p: string): string;
+    private buildTurnFileRules;
+    private normalizeMacOSUnlinkPolicy;
+    private buildFullAccessFileRules;
+    /**
+     * Linux：放行沙箱内读取/执行托管 Node/Python 运行时目录。
+     *
+     * Linux 上托管 node/python 以「包内受信目录 + 软链」交付：
+     * `~/.workbuddy/binaries/<runtime>/versions/<v>/bin` 是指向包内
+     * `/opt/<App>/resources/runtime/<runtime>/bin` 的软链。沙箱内核会按真实路径裁决，
+     * 故同时下发软链路径与其 realpath（/opt 目标），确保 agent 能在沙箱里 spawn 运行时。
+     */
+    private getLinuxManagedRuntimeReadOnlyRules;
+    private getBrokeredShellRuntimeReadOnlyPaths;
+    private isManagedRuntimeDisabled;
+    private isDirectoryRulePath;
+    private hasDirectoryGlobSuffix;
+    private hasDirectoryRuleSuffix;
+    private isValidDirectory;
+    private getPlatform;
+}

package/cli/dist-server/types/node/sandbox-cli/sandbox-session-preparation.d.ts

@@ -0,0 +1,49 @@
+import type { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { SandboxCenterIpcClient } from '../sensitive-content/sandbox-center-ipc-client-protocol';
+import { type Settings, SettingsManager } from '../settings';
+import type { ISandboxCLILifecycle } from './sandbox-cli-lifecycle-protocol';
+import type { SandboxCLIProcessManager } from './sandbox-cli-protocol';
+import type { SandboxTurnConfig } from './sandbox-turn-config';
+export declare function isFileBackupSupported(): boolean;
+export declare function shouldUseSandboxCLI(settingsEnabled: boolean): boolean;
+export declare function normalizeFileBackupMaxSizeMB(value: unknown): number;
+interface ResolvedSandboxSessionSettings {
+    configuredSandboxEnabled: boolean;
+    useSandboxCLI: boolean;
+    fileBackupEnabled: boolean;
+    fileBackupMaxSizeMB?: number;
+}
+/**
+ * 普通对话通过隔离执行策略校验后，与冷回退共用这份设置解析。
+ *
+ * 企业托管覆盖就落在这里（issue #129503）：这是两条入口唯一共用的解析点。
+ * 之前只在 `sandbox-interceptor` 叠加托管值，冷回退（`loadSandboxSessionSettings`
+ * → 文件回退的 `ensureSandboxReady`）直解原始 settings，于是「企业开启 + 本地
+ * settings 关闭」时普通对话启用沙箱、冷回退却判为关闭并返回 SANDBOX_UNAVAILABLE，
+ * 历史消息回退恢复不了文件。该矛盾状态是可构造的：ACP 配置入口仍允许写入与企业值
+ * 相反的 settings。
+ *
+ * 两个方向都在此收敛，顺序即优先级：
+ * - 托管**关闭** → 一律按关处理（含文件备份），settings 说开也不认；
+ * - 托管**开启** → 先把 `sandbox.enabled` 叠成 true 再按常规解析，让 useSandboxCLI /
+ *   文件备份 / maxSizeMB 全部按「沙箱已启用」一次算出（逐字段打补丁会漏掉文件备份，
+ *   因为它依赖 useSandboxCLI）。
+ *
+ * 强制开仍受**平台能力**约束：下面的 `shouldUseSandboxCLI` 保留平台判定，不支持的
+ * 平台上不会置 true，否则下游会等一个永不就绪的沙箱。
+ */
+export declare function resolveSandboxSessionSettings(mergedSettings: Settings, logger: Logger): ResolvedSandboxSessionSettings;
+/** 无用户消息的文件回退独立读取会话设置；正常对话仍先校验隔离执行策略。 */
+export declare function loadSandboxSessionSettings(settingsManager: SettingsManager, turnConfig: SandboxTurnConfig, logger: Logger, policyPermissionMode?: string): Promise<{
+    configuredSandboxEnabled: boolean;
+    settingsReadFailed: boolean;
+}>;
+/** 备份开关与常规对话共用同一份配置；5.7.0 的回退边界使用完整 file rules 视图。 */
+export declare function syncModifyBackupConfig(sessionId: string, deps: {
+    turnConfig: SandboxTurnConfig;
+    lifecycle?: ISandboxCLILifecycle;
+    centerClient?: SandboxCenterIpcClient;
+    processManager?: SandboxCLIProcessManager;
+    logger: Logger;
+}): Promise<void>;
+export {};

package/cli/dist-server/types/node/sandbox-cli/sandbox-turn-config.d.ts

@@ -0,0 +1,32 @@
+import type { SecurityCenterFileRule } from '../../workspace/sandbox-cli/lib/common/rule-config.js';
+export declare const SandboxTurnConfig: unique symbol;
+export interface SandboxTurnConfig {
+    useSandboxCLI: boolean;
+    /** 文件备份：是否启用 */
+    enableFileBackup: boolean;
+    /** Successful native enable acknowledgment for this Turn; not merely the requested switch. */
+    modifyBackupConfirmed?: boolean;
+    /** 文件备份：总大小上限（MB） */
+    fileBackupMaxSizeMB?: number;
+    /** safe-delete 运行时保护是否启用（来自 sandbox config） */
+    safeDeleteRuntimeEnabled: boolean;
+    /** 当前 filesystem.allowWrite 是否已包含 allow-all 路径 */
+    configAllowsAllWritePath: boolean;
+    /** 当前 session 权限模式，用于决定沙箱规则宽严。 */
+    permissionMode?: string;
+    /** 本轮下发给 Center 的有序文件规则来源快照。 */
+    orderedFileRules?: readonly SecurityCenterFileRule[];
+    /** 本轮最终沙箱规则 profile。 */
+    ruleProfile?: 'sandbox-disabled' | 'default-strict' | 'fullAccess-relaxed';
+}
+export declare class SandboxTurnConfigImpl implements SandboxTurnConfig {
+    useSandboxCLI: boolean;
+    enableFileBackup: boolean;
+    modifyBackupConfirmed: boolean;
+    fileBackupMaxSizeMB?: number;
+    safeDeleteRuntimeEnabled: boolean;
+    configAllowsAllWritePath: boolean;
+    permissionMode?: string;
+    orderedFileRules?: readonly SecurityCenterFileRule[];
+    ruleProfile?: 'sandbox-disabled' | 'default-strict' | 'fullAccess-relaxed';
+}

package/cli/dist-server/types/node/sandbox-cli/threat-domain-checker.d.ts

@@ -0,0 +1,137 @@
+import { Logger } from '@celljs/core';
+import { type SandboxCenterIpcClient as ISandboxCenterIpcClient } from '../sensitive-content/sandbox-center-ipc-client-protocol';
+import { type SandboxTelemetryReporter as ISandboxTelemetryReporter } from '../telemetry/sandbox-telemetry-protocol';
+import { type ISandboxCLILifecycle } from './sandbox-cli-lifecycle-protocol';
+import { type SandboxTurnConfig as ISandboxTurnConfig } from './sandbox-turn-config';
+export interface ThreatDomainCheckResult {
+    available: boolean;
+    malicious: boolean;
+    requestedDomain?: string;
+    matchedDomain?: string;
+    label?: string;
+    mainDomainMatch?: boolean;
+}
+export declare const ThreatDomainChecker: unique symbol;
+export interface ThreatDomainChecker {
+    /** 把持久化状态中的当前 DB 同步到已运行的 sandbox-cli。 */
+    sync(context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<boolean>;
+    /**
+     * 调用方已完成 ensureReady/ensureAlive 时使用，避免重复探活。
+     * 该方法始终复用 lifecycle 当前已打开的 session，不切换或停止进程。
+     */
+    syncReady(context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<boolean>;
+    check(hostname: string, context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<ThreatDomainCheckResult>;
+    /** sandbox-cli 里当前真正加载的库版本，供命中埋点标注是哪一版拦下的；从未加载成功时为空。 */
+    getLoadedVersion(): string | undefined;
+}
+/**
+ * agent-cli 侧恶意域名查询入口。
+ *
+ * SQLite 只由 sandbox-center/Rust 打开；Web 工具通过 `decide_network` 查询，避免在 TS
+ * 再维护一套 SQLite 依赖、域名标准化和主域匹配逻辑。
+ */
+export declare class ThreatDomainCheckerImpl implements ThreatDomainChecker {
+    protected readonly logger: Logger;
+    protected readonly lifecycle?: ISandboxCLILifecycle;
+    protected readonly sandboxCenterClient?: ISandboxCenterIpcClient;
+    protected readonly sandboxTurnConfig?: ISandboxTurnConfig;
+    protected readonly telemetryReporter?: ISandboxTelemetryReporter;
+    private loadedPath?;
+    private loadedGeneration?;
+    private loadedCenterGeneration?;
+    /**
+     * sandbox-cli 进程里当前这个 reader 实际加载的库版本，只在 SetThreatDatabase 成功后才更新。
+     *
+     * 与 state.json 此刻的 activeVersion 分开保存：磁盘可能已经换代而 CLI 仍困在旧 reader 上，
+     * 埋点要报的是后者，否则最需要被发现的那类分叉恰好看不见。
+     */
+    private loadedVersion?;
+    private readonly reportedTelemetryTurns;
+    /** 串行化 manager 进程级 reader 的启用/停用，避免并发 WebFetch 与开关切换互相覆盖。 */
+    private syncQueue;
+    /** 最近一次 SetThreatDatabase 失败，用于抑制高频重试，见 isSetFailureCached。 */
+    private setFailure?;
+    /** 忘掉本代 reader：三个字段必须同进同出，分开清会让埋点报出一个已经不存在的版本。 */
+    private clearLoadedReader;
+    /**
+     * sandbox-cli 里当前真正加载的库版本，供命中埋点标注是哪一版拦下的。
+     *
+     * 与 `resolveThreatDatabaseRuntimeConfig().version`（磁盘视角）不同，这里是进程视角。
+     */
+    getLoadedVersion(): string | undefined;
+    /**
+     * 本代 sandbox-cli 里那个 SQLite reader 是否仍然活着，活着就返回它所在的 session。
+     *
+     * Rust 侧只在收到 `SetThreatDatabase{enabled:false}` 或进程退出时才卸载 reader，所以
+     * 「同步失败」不等于「查不了」。这两件事必须分开报：若同步一失败就一律 `queryAvailable=false`，
+     * Bash 侧还在走沙箱内的旧 reader 继续拦，WebFetch 这条旁路却直接放行——同一个域名两个工具
+     * 给出相反结论，模型据此会得出「换个工具就能过」，而这正是需求明确禁止的。
+     */
+    private getAliveReaderSessionId;
+    /**
+     * 同一 `(path, generation)` 上刚失败过的 SetThreatDatabase 是否应跳过重试。
+     *
+     * 失败不写 `loadedPath`（否则会谎称已加载），于是下一次进来判据依然成立、再发一次。
+     * 而调用密度是每条沙箱命令一次 + 每个 WebFetch URL 一次（重定向逐跳累加），一旦
+     * sandbox-cli 根本不认这个命令——Linux 目前钉在不含威胁库能力的版本，这是必然存在的
+     * 过渡态——就变成每条命令都白付一次 IPC 往返并刷一条 warn。
+     *
+     * 用冷却窗口而不是永久负缓存：进程/版本没变但 IPC 偶发抖动的情况必须还能自己恢复，
+     * 否则防护会静默停在关闭状态直到沙箱重启。path 或 generation 变化时判据自然失效。
+     */
+    private isSetFailureCached;
+    check(hostname: string, context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<ThreatDomainCheckResult>;
+    sync(context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<boolean>;
+    syncReady(context: {
+        sessionId: string;
+        conversationRequestId?: string;
+    }): Promise<boolean>;
+    /**
+     * 确保当前 DB 已同步到 sandbox-cli，返回可用性 + 不生效原因。
+     *
+     * 埋点是严格旁路：同一个 sessionId + conversationRequestId 最多尝试上报一次，
+     * 任何 reporter 异常均被吞掉，不能改变 DB 同步、域名查询或放行/拦截结果。
+     */
+    private syncInternal;
+    private reportSyncTelemetryOnce;
+    /**
+     * 把当前 DB 同步进 sandbox-cli，并区分当前库同步状态与旧 reader 查询能力。
+     * `sync-failed` 覆盖 ensureReady / SetThreatDatabase 失败——后者的 IPC 结果是
+     * Rust 端 `threat_database.load` 的真实成败信号，load 失败会 response_err 抛回。
+     */
+    private syncToSandbox;
+    /**
+     * 关闭开关时停用进程内的 SQLite reader。这里只关闭连接，不删除本地 DB，也不会
+     * 触发下载；再次开启时直接复用 state.json 指向的同一文件。没有活跃 sandbox-cli
+     * 时无需为了“关闭”而启动进程。停用失败时保持 fail-safe（旧 reader 仍生效），
+     * 但错误只记日志/埋点，不阻塞设置保存或命令主链路。
+     */
+    private disableThreatDatabase;
+}
+/**
+ * 解析 daemon 更新器发布的当前 DB。
+ *
+ * 环境变量仅保留为手工测试兜底；正常 Desktop 链路读取 configDir 下的原子状态
+ * 文件，因此 daemon 更新后不需要修改已经启动的 agent-cli 进程环境。
+ */
+export declare function resolveThreatDatabaseRuntimeConfig(): {
+    enabled: boolean;
+    path?: string;
+    /** state.json 记录的库版本，仅用于埋点；env 兜底路径没有版本可言，此时不下发。 */
+    version?: string;
+};

package/cli/dist-server/types/node/security-review/gate.d.ts

@@ -0,0 +1,13 @@
+import { type TurnSecurityReviewPolicy } from '../../workspace/product/lib/common/index.js';
+import type { Session } from '../session';
+import { type SecurityReviewGate as SecurityReviewGateContract } from './protocol';
+export declare class SecurityReviewGateImpl implements SecurityReviewGateContract {
+    private readonly pendingPolicies;
+    private readonly policies;
+    setSessionConfig(session: Session, rawConfig: unknown): TurnSecurityReviewPolicy;
+    beginTurn(session: Session): TurnSecurityReviewPolicy;
+    getTurnPolicy(session: Session): TurnSecurityReviewPolicy;
+    isModelBehaviorReviewEnabled(session: Session): boolean;
+    isRiskContentProtectionEnabled(session: Session): boolean;
+    getAssistedApprovalMode(session: Session, scope?: 'tool' | 'sandbox'): TurnSecurityReviewPolicy['assistedApprovalMode'];
+}

package/cli/dist-server/types/node/security-review/index.d.ts

@@ -0,0 +1,2 @@
+export * from './gate';
+export * from './protocol';

package/cli/dist-server/types/node/security-review/protocol.d.ts

@@ -0,0 +1,14 @@
+import type { TurnSecurityReviewPolicy } from '../../workspace/product/lib/common/index.js';
+import type { Session } from '../session';
+export declare const DEFAULT_TURN_SECURITY_REVIEW_POLICY: TurnSecurityReviewPolicy;
+/** 工具结果类审批受风险内容保护开关约束，其余工具风险审批受模型行为审查开关约束。 */
+export declare function isToolRiskApprovalEnabled(policy: TurnSecurityReviewPolicy | undefined, reviewType: unknown): boolean;
+export declare const SecurityReviewGate: unique symbol;
+export interface SecurityReviewGate {
+    setSessionConfig(session: Session, rawConfig: unknown): TurnSecurityReviewPolicy;
+    beginTurn(session: Session): TurnSecurityReviewPolicy;
+    getTurnPolicy(session: Session): TurnSecurityReviewPolicy;
+    isModelBehaviorReviewEnabled(session: Session): boolean;
+    isRiskContentProtectionEnabled(session: Session): boolean;
+    getAssistedApprovalMode(session: Session, scope?: 'tool' | 'sandbox'): TurnSecurityReviewPolicy['assistedApprovalMode'];
+}

package/cli/dist-server/types/node/sensitive-content/index.d.ts

@@ -0,0 +1,15 @@
+export * from './sensitive-content-protocol';
+export * from './sandbox-center-ipc-client';
+export * from './sandbox-center-port';
+export * from './sensitive-approval-port';
+export * from './sensitive-decision-mediation';
+export * from './sensitive-content-mediation';
+export * from './sensitive-tool-egress-guard';
+export * from './sensitive-protection-metadata';
+export * from './sensitive-local-sideband';
+export * from './settings-sensitive-protection-policy';
+export * from './managed-cipher-stream-restorer';
+export * from './sensitive-model-boundary';
+export * from './sensitive-user-input-review';
+export * from './sensitive-history-admission';
+export * from './sensitive-history-replay';

package/cli/dist-server/types/node/sensitive-content/managed-cipher-stream-restorer.d.ts

@@ -0,0 +1,22 @@
+import type { CipherEntry, SensitivePlaintextProtectionMetadata } from './sensitive-content-protocol';
+export interface RestoredStreamChunk {
+    /** Plaintext consumed by the execution path. */
+    content: string;
+    /** Ciphertext projection consumed by the conversation UI. */
+    displayContent: string;
+    sensitiveProtection?: SensitivePlaintextProtectionMetadata;
+}
+export declare function restoreManagedText(source: string, entries: ReadonlyArray<Readonly<CipherEntry>>): RestoredStreamChunk;
+/**
+ * Restores registered variable-format ciphertexts without buffering an entire model response.
+ * Only a suffix that can still become one registered ciphertext is retained.
+ */
+export declare class ManagedCipherStreamRestorer {
+    private pending;
+    private readonly index;
+    private readonly ciphertexts;
+    constructor(entries: ReadonlyArray<Readonly<CipherEntry>>);
+    push(delta: string): RestoredStreamChunk;
+    flush(): RestoredStreamChunk;
+    private consume;
+}

package/cli/dist-server/types/node/sensitive-content/sandbox-center-ipc-client-protocol.d.ts

@@ -0,0 +1,3 @@
+import type { SandboxCenterClient } from '../../workspace/sandbox-cli/lib/node/sandbox-center-client.js';
+export declare const SandboxCenterIpcClient: unique symbol;
+export type SandboxCenterIpcClient = SandboxCenterClient;

package/cli/dist-server/types/node/sensitive-content/sandbox-center-ipc-client.d.ts

@@ -0,0 +1,7 @@
+import { SandboxCenterClientBase, type SandboxCenterRequestOptions, type SandboxCenterRuntimeContext } from '../../workspace/sandbox-cli/lib/node/sandbox-center-client.js';
+export { type SandboxCenterRequestOptions, type SandboxCenterRuntimeContext, };
+export { SandboxCenterIpcClient } from './sandbox-center-ipc-client-protocol';
+export declare class SandboxCenterIpcClientImpl extends SandboxCenterClientBase {
+    constructor();
+    protected resolveRuntimeContext(options?: SandboxCenterRequestOptions): SandboxCenterRuntimeContext;
+}

package/cli/dist-server/types/node/sensitive-content/sandbox-center-port.d.ts

@@ -0,0 +1,17 @@
+import { type SandboxCenterIpcClient as SandboxCenterIpcClientInterface } from './sandbox-center-ipc-client-protocol';
+import { type CipherEntry, type SandboxCenterPort as SandboxCenterPortInterface, type SensitiveDetectionOutcome } from './sensitive-content-protocol';
+export declare class SandboxCenterPortImpl implements SandboxCenterPortInterface {
+    protected sandboxCenterClient: SandboxCenterIpcClientInterface;
+    private messageSequence;
+    detectSensitiveContent(request: Parameters<SandboxCenterPortInterface['detectSensitiveContent']>[0]): Promise<SensitiveDetectionOutcome>;
+    private pathExists;
+    notifyEncryptionChoice(request: Parameters<SandboxCenterPortInterface['notifyEncryptionChoice']>[0]): Promise<{
+        entries: CipherEntry[];
+    }>;
+    queryEntries(request: Parameters<SandboxCenterPortInterface['queryEntries']>[0]): Promise<CipherEntry[]>;
+    private queryExact;
+    private toPortEntry;
+    private normalizeStrings;
+    private normalizeDetectedItems;
+    private nextDetectionMessageId;
+}