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

package/cli/dist-server/types/node/runtime/host-detection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Host detection — identifies which host launched the agent-cli process.
+ *
+ * WorkBuddy Desktop injects CODEBUDDY_HOST='workbuddy-desktop' via its
+ * sidecar-manager.ts buildCliEnv() function. Other hosts (plain CLI,
+ * VSCode ACP, Web UI serve mode) do not set this env var.
+ *
+ * Use this to gate host-specific behavior such as telemetry events that
+ * only make sense for a specific host.
+ */
+/**
+ * Known host identifiers.
+ *
+ * - `workbuddy-desktop`: launched by WorkBuddy Desktop sidecar-manager
+ * - `vscode-acp`: ACP mode (usually IDE integrations like VSCode)
+ * - `web-ui`: --serve mode serving the Web UI
+ * - `cli`: plain terminal usage (default when nothing else matches)
+ */
+export type HostName = 'workbuddy-desktop' | 'vscode-acp' | 'web-ui' | 'cli';
+/**
+ * Get the current host name from the active process state.
+ *
+ * Prewarm rewrites `process.argv` and merges session env during activation, so
+ * this value must not be cached while the process is still in standby.
+ */
+export declare function getHostName(): HostName;
+/**
+ * Convenience helper: true when running inside WorkBuddy Desktop.
+ */
+export declare function isWorkBuddyDesktop(): boolean;
+/**
+ * Compatibility no-op for tests that used to reset the host cache.
+ */
+export declare function __resetHostDetectionCache(): void;

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

@@ -0,0 +1,8 @@
+export * from './external-uri-opener';
+export * from './workspace';
+export * from './file-local-storage';
+export * from './workspace-folder-manager';
+export * from './add-dir-middleware';
+export * from './host-detection';
+export * from './cli-capabilities';
+export * from './host-capability-provider';

package/cli/dist-server/types/node/runtime/workspace-folder-manager.d.ts

@@ -0,0 +1,45 @@
+import { Session, SessionManager } from '../../vendor/cbc-core/node/index.js';
+import { SettingsManager, SettingsScope } from '../settings';
+export declare const WorkspaceFolderManager: unique symbol;
+/**
+ * 工作目录的落点：
+ * - 'session'：仅当前会话生效，存 session.options.addDir，不落盘
+ * - SettingsScope：持久化到对应的配置文件（user / project / project-local）
+ */
+type WorkspaceFolderTarget = 'session' | SettingsScope;
+export interface WorkspaceFolderManager {
+    /**
+     * 添加工作目录
+     */
+    addWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<void>;
+    /**
+     * 移除工作目录
+     */
+    removeWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<void>;
+    /**
+     * 从所有落点（session + 所有持久化 scope）移除工作目录
+     */
+    removeWorkspaceFolderEverywhere(directory: string): Promise<void>;
+    /**
+     * 获取所有工作目录
+     */
+    getWorkspaceFolders(target?: WorkspaceFolderTarget): Promise<string[]>;
+    /**
+     * 判断是否包含工作目录
+     */
+    hasWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<boolean>;
+}
+export declare class WorkspaceFolderManagerImpl implements WorkspaceFolderManager {
+    protected readonly sessionManager: SessionManager;
+    protected readonly settingsManager: SettingsManager;
+    protected currentSession: Session | undefined;
+    protected init(): void;
+    private getScopeDirectories;
+    private operateWorkspaceFolder;
+    addWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<void>;
+    removeWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<void>;
+    removeWorkspaceFolderEverywhere(directory: string): Promise<void>;
+    getWorkspaceFolders(target?: WorkspaceFolderTarget): Promise<string[]>;
+    hasWorkspaceFolder(directory: string, target: WorkspaceFolderTarget): Promise<boolean>;
+}
+export {};

package/cli/dist-server/types/node/runtime/workspace.d.ts

@@ -0,0 +1,5 @@
+import { Workspace, WorkspaceFolder } from '../../workspace/runtime/lib/common/index.js';
+export declare class CliWorkspace implements Workspace {
+    private readonly cwdService;
+    get workspaceFolders(): readonly WorkspaceFolder[];
+}

package/cli/dist-server/types/node/sandbox-cli/sandbox-backend-support.d.ts

@@ -0,0 +1,7 @@
+import { WORKBUDDY_ENABLE_LINUX_SANDBOX_CLI } from '../../workspace/product/lib/common/index.js';
+export { WORKBUDDY_ENABLE_LINUX_SANDBOX_CLI };
+export type SandboxHostBackend = 'sandbox-cli' | 'legacy';
+export declare function isWorkBuddyLinuxSandboxCLIEnabled(): boolean;
+/** sandbox-cli 是否在当前 host 受支持。Linux 仅由 WorkBuddy 显式放量。 */
+export declare function isSandboxCLIPlatformSupported(): boolean;
+export declare function resolveSandboxBackendForHost(): SandboxHostBackend;

package/cli/dist-server/types/node/sandbox-cli/sandbox-cli-lifecycle-protocol.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Sandbox CLI Lifecycle Protocol
+ *
+ * 定义 SandboxCLILifecycle 的 DI Symbol、BootstrapOptions 以及 ISandboxCLILifecycle 接口。
+ *
+ * SandboxCLILifecycle 专管 sandbox-cli 进程与 session 级 IPC 骨架的生命周期：
+ * spawn → connect → OpenSession → 探活 → session 切换 → 优雅停止。
+ *
+ * 通过 onSessionReady callback 机制让外部模块注册 post-OpenSession 逻辑
+ * （如规则同步），lifecycle 保证每次 OpenSession 成功后统一触发。
+ * 通过 getReadyGeneration() 计数器语义性地向外暴露 "发生过几次 OpenSession 成功"，
+ * 让外部按需做各自的重新初始化。
+ */
+import type { SandboxCLIClient as ISandboxCLIClient } from './sandbox-cli-protocol';
+export declare const SandboxCLILifecycle: unique symbol;
+/**
+ * Lifecycle 首次启动时固化的引导参数。
+ *
+ * 后续 ensureReady(...) 调用传入的 options 会被忽略（幂等保证只启动一次）。
+ * 决定性调用方为 SandboxAgentRunInterceptor，在每轮 prompt 到达时通过
+ * ensureReady 确保 sandbox-cli 就绪；session 切换时先 stop 再重新 ensureReady。
+ */
+export interface BootstrapOptions {
+    /** 首次 OpenSession 要用的 sessionId（必填） */
+    sessionId: string;
+    /**
+     * 宿主 App 家目录，透传到 sandbox-cli 的 `--app_home` 参数。
+     * 由 SandboxAgentRunInterceptor 在调用 ensureReady 时传入。
+     * 缺省时 sandbox-cli 回退到平台默认路径
+     * （Windows: `%LOCALAPPDATA%\WorkBuddy`；其他: `$HOME/.local/share/WorkBuddy`）。
+     */
+    appHomeDir?: string;
+    /**
+     * （仅 macOS）App Group ID，透传到 sandbox-cli 的 `--app_group_id` 参数，
+     * 非 macOS 下被忽略。
+     */
+    appGroupId?: string;
+    /** sandbox-cli 是否显示独立控制台窗口 */
+    showConsoleWindow?: boolean;
+    /**
+     * 当前轮 conversationRequestId（来源：`session.conversationRequestId`），仅作为
+     * `sandbox.daemon.failure` 上报字段透传，不参与 daemon 启动协议。
+     */
+    conversationRequestId?: string;
+}
+/**
+ * OpenSession 成功后传递给回调的上下文。
+ */
+export interface SessionReadyContext {
+    /** 本次 OpenSession 的 sessionId */
+    sessionId: string;
+    /** 本次就绪后的 generation（递增计数器） */
+    generation: number;
+    /** 触发原因 */
+    reason: 'bootstrap' | 'restart';
+}
+/**
+ * 注册到 lifecycle 的 session-ready 回调。
+ * lifecycle 会 await 所有回调完成后才对外 resolve ensureReady。
+ */
+export type SessionReadyCallback = (ctx: SessionReadyContext) => Promise<void>;
+/**
+ * SandboxCLILifecycle 接口
+ */
+export interface ISandboxCLILifecycle {
+    /**
+     * 幂等启动：spawn + connect + OpenSession。
+     * 已启动则直接返回。首次调用时 options 会被固化。
+     */
+    ensureReady(options: BootstrapOptions): Promise<void>;
+    /**
+     * ping 探活，失败则 restart。
+     */
+    ensureAlive(): Promise<void>;
+    /**
+     * 当前已 OpenSession 的 sessionId。
+     */
+    getOpenedSessionId(): string | undefined;
+    /**
+     * 获取已连接的 IPC client。
+     */
+    getClient(): ISandboxCLIClient;
+    /**
+     * 每次 OpenSession 成功（首次启动 / restart 后重建）递增。
+     * 外部用它判断 "是否发生了新的 OpenSession"，用于触发各自的重新初始化。
+     */
+    getReadyGeneration(): number;
+    /**
+     * 等待 sandbox-cli 就绪（不触发启动）。
+     *
+     * 仅消费已有的启动 Promise，不会主动创建新的启动流程。
+     * 若 ensureReady 从未被调用或上次启动失败，立即 reject。
+     * 调用方应 try-catch 并自行决定降级策略。
+     */
+    waitReady(): Promise<void>;
+    /**
+     * 优雅停止 sandbox-cli。
+     */
+    stop(): Promise<void>;
+    /**
+     * 注册 OpenSession 成功后的回调。
+     * 每次 OpenSession 成功（bootstrap / restart / session-switch）都会依次调用
+     * 所有已注册的回调，单个回调失败不阻断后续回调。
+     *
+     * @param callback 回调函数
+     * @returns 取消注册的 disposer
+     */
+    onSessionReady(callback: SessionReadyCallback): () => void;
+}

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

@@ -0,0 +1,376 @@
+/**
+ * Sandbox CLI Protocol
+ *
+ * 定义 agent-cli 与 SandboxManager 之间的 IPC 通信协议。
+ * 与 Rust 侧 `sandbox/src/ipc/protocol.rs` 中的 `IpcMessage` 结构完全对齐，
+ * 使用统一的 NDJSON（Newline-Delimited JSON）格式通信。
+ *
+ * 消息区分规则：
+ * - 请求消息：`success` 字段为 undefined（不存在）
+ * - 响应消息：`success` 字段为 boolean（true=成功, false=失败）
+ *
+ * 消息流向：
+ * - 正向请求：agent-cli → SandboxManager（如 OpenSession, RunExecutable 等）
+ * - 正向响应：SandboxManager → agent-cli（对正向请求的响应）
+ * - 反向事件：SandboxManager → agent-cli（ProcessOutput / ProcessExit，fire-and-forget）
+ *
+ * **命令名称一律采用 PascalCase**，以 Rust 侧 `ipc/protocol.rs::commands` 常量为唯一真相源。
+ */
+import type { IpcMessage as ProtocolIpcMessage, JsonValue as ProtocolJsonValue, SandboxCommand as ProtocolSandboxCommand } from '../../workspace/sandbox-cli/lib/common/protocol.generated.js';
+import type { SandboxCliRequestContext } from '../../workspace/sandbox-cli/lib/node/sandbox-cli-client.js';
+import type { SandboxDaemonFailurePayload, SandboxDaemonFailurePhase } from '../../workspace/telemetry/lib/common/index.js';
+import type { HttpInterceptPolicyConfig } from '../bash-sandbox/bash-sandbox-protocol';
+export * from '../../workspace/sandbox-cli/lib/common/protocol.generated.js';
+/**
+ * Agent CLI 内部兼容视图。Sandbox IPC 已统一为 DecisionRecord；现有业务层继续
+ * 使用 FileBlockRecord / NetworkBlockRecord，转换只发生在 IPC 边界。
+ */
+export declare const FORBIDDEN_PROGRAM_BLOCK_REASON: "forbidden_program";
+export type FileBlockReason = typeof FORBIDDEN_PROGRAM_BLOCK_REASON;
+export type NetworkBlockReason = 'whitelist' | 'blacklist' | 'loopback' | 'http_intercept_block' | 'http_intercept_ask' | 'malicious' | 'runtime_decision' | 'default_allow' | 'default_deny' | 'center_deny' | 'center_ask'
+/**
+ * 网络严格模式的系统层拦截（genie/genie#122764）。
+ *
+ * 进程不读 `HTTP_PROXY` 直连出网 → 被 SBPL 在系统层拦下（`reason=network_strict`）。
+ * **与 `center_deny`（规则命中拦截）刻意区分**：成因不同——规则拦截是命中了某条
+ * 配置的规则，严格模式拦截与任何规则无关（那条规则并不存在）。
+ */
+ | 'network_strict';
+export interface FileBlockRecord {
+    path: string;
+    actionMask: number;
+    source: string;
+    options: string[];
+    command?: string;
+    raw?: ProtocolJsonValue;
+    reason?: FileBlockReason;
+}
+export interface NetworkBlockRecord {
+    host: string;
+    port?: number;
+    scheme: string;
+    actionMask: number;
+    options: string[];
+    command?: string;
+    raw?: ProtocolJsonValue;
+    reason?: NetworkBlockReason;
+}
+export declare function isForbiddenProgramBlockRecord(record: Pick<FileBlockRecord, 'reason'> | null | undefined): boolean;
+/** macOS Apple Sandbox operation for reading file-system metadata only. */
+export declare const FILE_READ_METADATA_OPERATION: "file-read-metadata";
+/**
+ * Return the platform operation attached to a structured file block record.
+ * Non-syslog backends may not populate `raw.operation`.
+ */
+export declare function getFileBlockOperation(record: Pick<FileBlockRecord, 'raw'> | null | undefined): string | undefined;
+/** Whether the record is specifically a metadata-only read denial. */
+export declare function isFileReadMetadataBlockRecord(record: Pick<FileBlockRecord, 'raw'> | null | undefined): boolean;
+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 SandboxCommand = ProtocolSandboxCommand;
+export interface AddFileRuleItem {
+    ruleRef?: string;
+    path: string;
+    action: string;
+    category?: string;
+    isDirectory?: boolean;
+}
+export interface AddNetworkRuleItem {
+    ruleRef?: string;
+    endpoint: string;
+    action: string;
+    category?: string;
+}
+export declare const SandboxCLIClient: unique symbol;
+export declare const SandboxShellService: unique symbol;
+export declare const SandboxCLIProcessManager: unique symbol;
+export type SandboxCLIStartupFailurePhase = Extract<SandboxDaemonFailurePhase, `startup-${string}`>;
+/** startup failure 结构；字段与 daemon.failure 保持同源。 */
+export interface SandboxCLIStartupFailure extends Pick<SandboxDaemonFailurePayload, 'errorMsg' | 'exitCode' | 'signal'> {
+    phase: SandboxCLIStartupFailurePhase;
+    errorCode: string;
+}
+/**
+ * sandbox-cli 进程启动选项
+ */
+export interface SandboxCLIProcessStartOptions {
+    /**
+     * 宿主 App 家目录，透传到 sandbox-cli 的 `--app_home` 参数。
+     * Rust 侧在此目录下派生 `sandbox/logs/`、`sandbox/projfs/`、
+     * `sandbox/sessions/<id>/` 等子目录。
+     * **由调用方显式传入，ProcessManager 不做默认猜测。**
+     */
+    appHomeDir?: string;
+    /**
+     * （仅 macOS）App Group ID，透传到 sandbox-cli 的 `--app_group_id` 参数。
+     * Rust 侧据此推导 `$HOME/Library/Group Containers/<gid>` 作为 overlay 目录，
+     * 以便 FileProvider Extension 直读。非 macOS 下忽略。
+     */
+    appGroupId?: string;
+    /**
+     * 是否让 sandbox-cli 分配独立的控制台窗口（通过 --console 触发 AllocConsole）。
+     * 开发调试时设为 true 可直接在独立窗口中观察 sandbox-cli 的实时日志。
+     * 默认为 false。
+     * 也可通过环境变量 SANDBOX_CLI_SHOW_CONSOLE=1 开启。
+     */
+    showConsoleWindow?: boolean;
+    /**
+     * 启动上下文，仅供 process-manager 内部 `sandbox.daemon.failure` 埋点关联到当前
+     * 用户操作（startup-* phase 全部、runtime-exit 一处）。值在 daemon 整个生命周期内
+     * 缓存：runtime-exit 上报的是"daemon 起来时为哪次请求服务的"，对长生命周期 daemon
+     * 是一种合理近似（精确的"崩溃时"上下文 lifecycle 的 runtime-* phase 各自独立维护）。
+     */
+    sessionId?: string;
+    conversationRequestId?: string;
+}
+/**
+ * SandboxCLI 进程管理器接口
+ *
+ * 负责 sandbox-cli 后端进程的生命周期管理：
+ * - 启动 sandbox-cli 子进程（通过 --config 传入 JSON 配置，通过 --app_home/--app_group_id 传入路径）
+ * - 生成随机 IPC 地址并注入配置
+ * - 进程监控和优雅关闭
+ */
+export interface SandboxCLIProcessManager {
+    /**
+     * 启动 sandbox-cli 进程并返回 IPC 地址。
+     * 随机生成 IPC 地址，通过 --config JSON 参数传入 sandbox-cli。
+     * 如果进程已在运行，返回缓存的地址。
+     * @param options 可选的启动选项
+     * @returns IPC 地址字符串（如 "WorkBuddy_<hex>"）
+     */
+    start(options?: SandboxCLIProcessStartOptions): Promise<string>;
+    /** OpenSession 成功后调用；只用于区分 startup close 与 runtime-exit 遥测。 */
+    markSessionEstablished?(): void;
+    /** 取走 OpenSession 建立前的进程退出原因，供 lifecycle 统一失败出口归因。 */
+    consumeStartupFailure?(): SandboxCLIStartupFailure | undefined;
+    /**
+     * 停止 sandbox-cli 进程。
+     * 先发送 SIGTERM，超时后 SIGKILL。
+     */
+    stop(): Promise<void>;
+    /**
+     * 进程是否正在运行
+     */
+    isRunning(): boolean;
+    /** daemon.failure 事件 uptimeMs 字段的起点；非 running 状态返回 undefined */
+    getStartedAtMs(): number | undefined;
+}
+/**
+ * SandboxCLI 客户端配置
+ */
+export interface SandboxCLIConfig {
+    /** 会话 ID，用于标识当前连接对应的 Session */
+    sessionId: string;
+    /** IPC 连接地址（Named Pipe 路径或 Unix Socket 路径），由 SandboxCLIProcessManager.start() 返回 */
+    address: string;
+    /** 连接超时时间（毫秒） */
+    connectTimeoutMs?: number;
+    /** 请求超时时间（毫秒） */
+    requestTimeoutMs?: number;
+    /** 心跳间隔（毫秒） */
+    heartbeatIntervalMs?: number;
+    /** 心跳超时时间（毫秒） */
+    heartbeatTimeoutMs?: number;
+    /** 是否自动重连 */
+    autoReconnect?: boolean;
+    /** 最大重连次数 */
+    maxReconnectAttempts?: number;
+}
+export declare const DEFAULT_SANDBOX_CLI_CONFIG: SandboxCLIConfig;
+/**
+ * 判断消息是否为响应（success 字段存在）
+ */
+export declare function isIpcResponse(msg: ProtocolIpcMessage): boolean;
+/**
+ * 创建请求消息
+ */
+export declare function createIpcRequest(messageId: string, sessionId: string, command: string, data?: ProtocolJsonValue): ProtocolIpcMessage;
+/**
+ * 创建成功响应消息
+ */
+export declare function createIpcResponseOk(messageId: string, sessionId: string, command: string, data?: ProtocolJsonValue): ProtocolIpcMessage;
+/**
+ * 创建失败响应消息
+ */
+export declare function createIpcResponseErr(messageId: string, sessionId: string, command: string, error: string): ProtocolIpcMessage;
+/** 反向事件 listener 的过滤选项 */
+export interface ReverseListenerOptions {
+    /** 仅转发匹配的 command 名称列表（白名单） */
+    commands: string[];
+}
+/**
+ * SandboxCLI 客户端接口
+ *
+ * 封装与 SandboxManager 进程的 IPC 通信，提供：
+ * - 连接管理（connect/disconnect）
+ * - 正向请求/响应（sendRequest）
+ * - 反向事件处理（onReverseRequest / addReverseListener）
+ * - 消息 ID 自动生成与关联
+ */
+export interface SandboxCLIClient {
+    /**
+     * 建立与 SandboxManager 的 IPC 连接
+     */
+    connect(config: SandboxCLIConfig): Promise<void>;
+    /**
+     * 断开 IPC 连接
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 检查是否已连接
+     */
+    isConnected(): boolean;
+    /**
+     * 发送正向请求并等待响应。
+     *
+     * 内部自动生成 messageId，序列化为 NDJSON 发送，
+     * 并通过 messageId 匹配返回的响应消息。
+     *
+     * @param sessionId - 会话 ID（管理器级命令可传空字符串）
+     * @param command - 命令名称（建议使用 SANDBOX_COMMANDS.* 常量）
+     * @param data - 命令参数
+     * @param context - 可选上下文；conversationRequestId 用于 per-request 精确关联遥测，
+     * timeoutMs 用于给轻量控制命令设置独立短超时，避免继承执行命令的 120 秒上限
+     * @returns 响应消息的 data 字段
+     * @throws 当响应 success=false 时抛出错误（携带 error 字段）
+     */
+    sendRequest<T = ProtocolJsonValue>(sessionId: string, command: SandboxCommand, data?: ProtocolJsonValue, context?: SandboxCliRequestContext<T>): Promise<T>;
+    /**
+     * 返回当前 in-flight 请求关联的 conversationRequestId 集合。
+     * 用于 daemon 崩溃时精确关联到受影响的用户操作。
+     */
+    getPendingConversationRequestIds(): string[];
+    /**
+     * 注册反向事件处理器（fallback handler）。
+     *
+     * 当反向事件未被任何 addReverseListener 匹配消费时，
+     * 走此 handler 处理。用于需要回复的反向请求（非 fire-and-forget）。
+     *
+     * @deprecated 优先使用 addReverseListener 注册 fire-and-forget 事件监听。
+     * @param handler - 反向事件处理函数，接收 IpcMessage，返回响应 data
+     */
+    onReverseRequest(handler: (message: ProtocolIpcMessage) => Promise<ProtocolJsonValue | undefined>): void;
+    /**
+     * 注册反向事件 listener（支持按 command 过滤）。
+     *
+     * 仅接收 fire-and-forget 类反向事件。注册的 command 会自动被识别为
+     * fire-and-forget（不需要向 RS 侧回复响应）。
+     *
+     * @param options - 过滤选项，commands 指定感兴趣的命令白名单
+     * @param handler - 事件处理函数（fire-and-forget，无需返回值）
+     * @returns 取消订阅函数
+     */
+    addReverseListener(options: ReverseListenerOptions, handler: (message: ProtocolIpcMessage) => void | Promise<void>): () => void;
+    /**
+     * 注册连接断开监听器。
+     *
+     * 当底层 socket 异常关闭（sandbox-cli 进程崩溃、被 kill、IPC 行缓冲超限等）
+     * 触发 _handleDisconnect 时回调。订阅方可以在此把所有依赖反向通知的 handle
+     * 强制收尾，避免上层 Promise 永久挂起（参见 BashTool 38 分钟卡死问题）。
+     *
+     * @param handler - 断连回调，无参数
+     * @returns 取消订阅的函数
+     */
+    onDisconnect(handler: () => void): () => void;
+    /**
+     * 发送 ping 探测，验证 sandbox-cli 进程是否存活。
+     * 使用较短超时（heartbeatTimeoutMs），成功返回，超时或失败抛出错误。
+     */
+    ping(): Promise<void>;
+}
+/**
+ * 安全中心规则的增量变更描述。
+ * 由 UI 操作方直接构造（add/remove 操作本身即增量），随 control signal 透传到
+ * SandboxShellService，用于实时同步到当前活跃 sandbox session。
+ *
+ * 结构镜像自 workbuddy-server 的 SecurityCenterSandboxRulesDelta（SSOT，见
+ * packages/workbuddy-server/src/security-center/contract.ts）。两份定义无编译期约束，
+ * 改动需手动同步。
+ */
+export interface SandboxRulesDelta {
+    /** 规则顺序或动作变化时，从 settings 重新构建并全量下发当前规则。 */
+    refresh?: boolean;
+    network?: {
+        added?: Array<{
+            endpoint: string;
+            type: 'no_access' | 'inherit_user';
+        }>;
+        removed?: Array<{
+            endpoint: string;
+        }>;
+        maliciousDomainProtectionEnabled?: boolean;
+    };
+    file?: {
+        added?: Array<{
+            path: string;
+            type: 'inherit_user' | 'no_access';
+        }>;
+        removed?: Array<{
+            path: string;
+        }>;
+    };
+    program?: {
+        added?: string[];
+        removed?: string[];
+    };
+    /**
+     * HTTP 明文拦截三态策略全量变更。
+     *
+     * SetHttpIntercept 是**全量替换**协议(无 ADD/REMOVE 增量命令)，故 delta 用整体
+     * 配置而非 add/remove。sidecar 收到后用 `buildHttpInterceptRules` 把用户三态
+     * (remote/local)翻译成 Center 的 HttpInterceptRule[]，全量下发 SET_HTTP_INTERCEPT。
+     */
+    httpIntercept?: HttpInterceptPolicyConfig;
+    /**
+     * 网络严格模式开关（genie/genie#122764）。
+     *
+     * 语义「感知不到 = 拦截」：开启后 macOS SBPL 追加系统级出站兜底，不读 HTTP_PROXY
+     * 的程序（nc / bash /dev/tcp / 原生 socket / ssh / DB 客户端）无法绕过 LocalProxy。
+     *
+     * 与 httpIntercept 同为**进程级全局**配置（非 per-session）——下发命令
+     * `sandbox.rules.set_config` 同样无 session 语义，一次写入即对所有会话的新命令生效。
+     * sidecar 收到后直接 SET_CONFIG 下发（无需翻译成规则数组）。
+     *
+     * 仅 macOS 有执行面：非 darwin 平台由下发侧直接跳过（不进 IPC）。
+     */
+    networkStrictMode?: boolean;
+}
+/** 运行时校验：确认 body 形如 SandboxRulesDelta，拒绝 network/file/program/httpIntercept 等畸形 payload。 */
+export declare function isValidSandboxRulesDelta(value: unknown): value is SandboxRulesDelta;
+/**
+ * SandboxShellService 的扩展接口，暴露规则热同步能力。
+ * 通过 SandboxShellService Symbol 注入后可 cast 到此接口。
+ *
+ * @throws 当任一 IPC 调用失败时抛出 SandboxRulesApplyError（聚合所有失败项），
+ * 调用方（Controller）据此向安全中心报告真实的 synced 状态。
+ */
+export interface ISandboxShellService {
+    applyRulesDelta(delta: SandboxRulesDelta): Promise<void>;
+}
+/**
+ * applyRulesDelta 内某一/多个 IPC 命令失败时抛出。聚合各失败项，
+ * 避免像本次修复的 payload-shape bug 那样被 `.catch` 静默吞掉。
+ * 目标编译到 ES2020，运行环境的原生 AggregateError（ES2021+）不可用，故自行实现。
+ */
+export declare class SandboxRulesApplyError extends Error {
+    readonly errors: Error[];
+    constructor(errors: Error[]);
+}