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

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

@@ -0,0 +1,10 @@
+export * from './delegating-shell-service';
+export * from './driver-shell-service';
+export * from './output-spiller';
+export * from './shell-protocol';
+export * from './shell-service';
+export * from './shell-snapshot-protocol';
+export * from './shell-snapshot-service';
+export * from './terminal-serializer';
+export * from './truncate-buffer';
+export * from './windows-process-utils';

package/cli/dist-server/types/node/shell/language-shim-env.d.ts

@@ -0,0 +1,11 @@
+import type { ShellRuntimePaths } from './shell-runtime-paths';
+export interface LanguageShimEnvOptions {
+    nodeShimEnabled?: boolean;
+    pythonShimEnabled?: boolean;
+    sessionId?: string;
+    conversationRequestId?: string;
+    toolCallId?: string;
+}
+export declare function injectNodeShimEnv(env: Record<string, string>, runtimePaths: Pick<ShellRuntimePaths, 'nodeShimPath'>): void;
+export declare function injectPythonShimEnv(env: Record<string, string>, runtimePaths: Pick<ShellRuntimePaths, 'shimDir'>): void;
+export declare function injectLanguageShimEnv(env: Record<string, string>, runtimePaths: Pick<ShellRuntimePaths, 'shimDir' | 'nodeShimPath'>, options?: LanguageShimEnvOptions): void;

package/cli/dist-server/types/node/shell/output-spiller.d.ts

@@ -0,0 +1,39 @@
+/**
+ * OutputSpiller - 流式将完整输出写入磁盘临时文件。
+ *
+ * 与 TruncateBuffer 配合使用：TruncateBuffer 在内存中只保留 head+tail（给 LLM），
+ * OutputSpiller 将完整输出流式写入磁盘（供用户按需读取）。
+ *
+ * 使用方式：
+ *   const spiller = new OutputSpiller(filePath);
+ *   // 在每次收到数据时同时 push
+ *   spiller.push(chunk);
+ *   // 完成后关闭
+ *   await spiller.close();
+ *   // 获取文件路径和总字节数
+ *   spiller.filePath;  // 磁盘文件路径
+ *   spiller.totalBytes; // 写入的总字节数
+ */
+export declare class OutputSpiller {
+    readonly filePath: string;
+    private stream;
+    private _totalBytes;
+    private _closed;
+    private _hasError;
+    constructor(filePath: string);
+    push(data: string): void;
+    close(): Promise<void>;
+    get totalBytes(): number;
+    get hasError(): boolean;
+    get isClosed(): boolean;
+    /**
+     * Remove the spill file (e.g. if output wasn't actually truncated).
+     *
+     * Closes the underlying WriteStream first to release the fd; otherwise the
+     * stream lingers until V8 GC collects it, at which point Node logs
+     * "Closing file descriptor X on garbage collection" and may throw EBADF
+     * if the fd number was reused. See bash-tool auto-background path where
+     * cleanup() runs without buildForegroundResult having closed the spiller.
+     */
+    cleanup(): Promise<void>;
+}

package/cli/dist-server/types/node/shell/powershell-safe-delete.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PowerShell safe-delete 预置脚本。
+ *
+ * 目标：在 PowerShell 路径下统一把 `rm` / `del` / `erase` / `ri` / `rmdir` /
+ * `unlink` 路由到回收站删除逻辑，并对失败场景保持 fail-closed（拒绝真删）。
+ *
+ * 说明：
+ * - 优先调用 genie-trash native helper（若存在）。
+ * - binary 不可用时回退到 Microsoft.VisualBasic 回收站 API。
+ * - 仅在当前 PowerShell 进程内生效；通过全局标记避免重复定义。
+ */
+export declare const POWERSHELL_SAFE_DELETE_PRELUDE: string;
+export declare function wrapPowerShellCommandWithSafeDelete(command: string, options?: {
+    enabled?: boolean;
+    inlineEnv?: Record<string, string | undefined>;
+}): string;

package/cli/dist-server/types/node/shell/safe-delete/bulk-guard/contract.d.ts

@@ -0,0 +1,61 @@
+export type BulkGuardApprovalScope = 'turn';
+export declare const DEFAULT_SAFE_DELETE_BULK_THRESHOLD = 50;
+export declare const SAFE_DELETE_BULK_STATE_DIR_NAME = "codebuddy-safe-delete-bulk";
+export interface BulkGuardContextInput {
+    stateRoot: string;
+    sessionId: string;
+    toolCallId: string;
+    threshold: number;
+    conversationRequestId?: string;
+}
+export interface BulkGuardContext extends BulkGuardContextInput {
+    requestId: string;
+    sessionHash: string;
+    sessionDir: string;
+    statePath: string;
+}
+export interface BulkGuardConfirmPayload {
+    count: number;
+    threshold: number;
+    scope: BulkGuardApprovalScope;
+    targets: string[];
+    targetCount: number;
+}
+export type BulkGuardRejectedPayload = BulkGuardConfirmPayload;
+export type BulkGuardDecision = {
+    kind: 'allow';
+} | {
+    kind: 'confirmRequired';
+    payload: BulkGuardConfirmPayload;
+} | {
+    kind: 'rejected';
+    payload: BulkGuardRejectedPayload;
+};
+export interface BulkGuardRequestState {
+    count: number;
+    updatedAt: number;
+}
+export interface BulkGuardToolApprovalState {
+    approved: boolean;
+    updatedAt: number;
+}
+export interface BulkGuardRequestRejectionState {
+    rejected: boolean;
+    count: number;
+    threshold: number;
+    targets: string[];
+    targetCount: number;
+    updatedAt: number;
+}
+export interface BulkGuardState {
+    requests: Record<string, BulkGuardRequestState>;
+    toolApprovals: Record<string, BulkGuardToolApprovalState>;
+    requestRejections?: Record<string, BulkGuardRequestRejectionState>;
+}
+export type BulkGuardSignal = {
+    type: 'confirmRequired';
+    payload: BulkGuardConfirmPayload;
+} | {
+    type: 'rejected';
+    payload: BulkGuardRejectedPayload;
+};

package/cli/dist-server/types/node/shell/safe-delete/bulk-guard/index.d.ts

@@ -0,0 +1,3 @@
+export * from './contract';
+export * from './marker';
+export * from './service';

package/cli/dist-server/types/node/shell/safe-delete/bulk-guard/marker.d.ts

@@ -0,0 +1,5 @@
+import type { BulkGuardConfirmPayload } from './contract';
+export declare const SAFE_DELETE_BULK_CONFIRM_MARKER = "[safe-delete][SAFE_DELETE_BULK_CONFIRM_REQUIRED]";
+export declare const SAFE_DELETE_BULK_ERROR_MARKER = "[safe-delete][SAFE_DELETE_BULK_GUARD_ERROR]";
+export declare function formatSafeDeleteBulkConfirmMarker(payload: BulkGuardConfirmPayload): string;
+export declare function parseSafeDeleteBulkConfirmMarker(output: string): BulkGuardConfirmPayload | undefined;

package/cli/dist-server/types/node/shell/safe-delete/bulk-guard/service.d.ts

@@ -0,0 +1,12 @@
+import type { BulkGuardApprovalScope, BulkGuardConfirmPayload, BulkGuardContext, BulkGuardContextInput, BulkGuardDecision, BulkGuardSignal } from './contract';
+export declare function createSafeDeleteBulkGuardContext(input: BulkGuardContextInput): BulkGuardContext;
+export declare function checkSafeDeleteBulkGuard(context: BulkGuardContext, targets: readonly string[]): BulkGuardDecision;
+export declare function approveSafeDeleteBulkGuard(context: BulkGuardContext, scope?: BulkGuardApprovalScope): void;
+export declare function rejectSafeDeleteBulkGuard(context: BulkGuardContext, payload: BulkGuardConfirmPayload): void;
+/**
+ * 从 side-channel 信号文件读取 bulk-guard 决策结果。
+ *
+ * 返回 undefined 表示无信号（guard 未触发 / 文件不存在）。
+ * 读取后自动删除信号文件，防止后续 tool call 误读到陈旧信号。
+ */
+export declare function readBulkGuardSignalFile(context: BulkGuardContext): BulkGuardSignal | undefined;

package/cli/dist-server/types/node/shell/safe-delete/index.d.ts

@@ -0,0 +1,17 @@
+export { buildPowerShellSafeDeleteEnv, buildSafeDeleteEnv, type SafeDeleteEnvBuildOptions } from './safe-delete-env';
+export { buildSafeDeletePosixBootstrap } from './safe-delete-bootstrap';
+export { isSafeDeleteHelperProcessExecRecord, isSafeDeleteHelperPath } from './safe-delete-attribution';
+export { appendSafeDeleteReportEvent, attachSafeDeleteReportEvents, ensureSafeDeleteReportPath, readSafeDeleteReport, SAFE_DELETE_REPORT_ENV, type SafeDeleteReportEvent, } from './safe-delete-report';
+export { movePathToTrash, type MovePathToTrashOptions } from './safe-delete-trash-service';
+export { logSafeDeleteInjection, parseSafeDeleteBulkThreshold, resolveSafeDeleteRuntimeConfig, resolveSafeDeleteRuntimeEnabled, type SafeDeleteRuntimeConfig, } from './safe-delete-settings';
+export { approveSafeDeleteBulkGuard, createSafeDeleteBulkGuardContext, DEFAULT_SAFE_DELETE_BULK_THRESHOLD, readBulkGuardSignalFile, rejectSafeDeleteBulkGuard, SAFE_DELETE_BULK_STATE_DIR_NAME, type BulkGuardSignal, } from './bulk-guard';
+export { resolveWindowsRecycleBinAuditPath, filterSafeDeleteTempProbeNoise, matchesSafeDeleteEscalationCommand, parseSafeDeleteBulkConfirmInfo, shouldEscalateSafeDeleteBulkConfirm, shouldEscalateSafeDeleteFailClosed, normalizeWindowsShellPathForAudit, SAFE_DELETE_BULK_CONFIRM_MARKER_RE, SAFE_DELETE_FAIL_CLOSED_MARKER_RE, type SafeDeleteBulkConfirmInfo, } from './safe-delete-sandbox-helpers';
+/**
+ * 从 sandbox 配置判定 safe-delete 运行时是否启用。
+ *
+ * 默认启用（fail-open）：未配置或读取失败时返回 true，
+ * 只有显式设为 false 才禁用。
+ */
+export declare function isSafeDeleteRuntimeEnabled(sandboxConfig: {
+    safeDeleteRuntimeEnabled?: boolean;
+} | undefined): boolean;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-attribution.d.ts

@@ -0,0 +1,16 @@
+/**
+ * safe-delete 归因辅助——判定 sandbox 拦截记录是否属于 safe-delete 链路。
+ *
+ * 被 sandbox-attribution-analyzer 消费，用于把 safe-delete helper
+ * （genie-trash / osascript / perl SAFE_DELETE 包装）的 process-exec*
+ * 拦截归类为「可恢复」，允许走本地重跑降级。
+ */
+import type { FileBlockRecord } from '../../sandbox-cli/sandbox-cli-protocol';
+export declare function isSafeDeleteHelperPath(blockedPath: string | undefined): boolean;
+/**
+ * 判定 block record 是否属于 safe-delete helper 链路的 process-exec* 拦截。
+ *
+ * 内部先检查 operation 是否为 process-exec*，再判定路径/签名。
+ * 非 process-exec* 操作直接返回 false。
+ */
+export declare function isSafeDeleteHelperProcessExecRecord(record: FileBlockRecord): boolean;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-bootstrap.d.ts

@@ -0,0 +1 @@
+export declare function buildSafeDeletePosixBootstrap(shell: string): string;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-env.d.ts

@@ -0,0 +1,42 @@
+import { type LanguageShimEnvOptions } from '../language-shim-env';
+import { type ShellRuntimePaths } from '../shell-runtime-paths';
+import type { SafeDeleteRuntimeConfig } from './safe-delete-settings';
+export interface SafeDeleteEnvBuildOptions extends LanguageShimEnvOptions {
+    /**
+     * 是否启用运行时 safe-delete 环境变量注入。
+     * 默认为 true（兼容历史行为）。
+     */
+    enabled?: boolean;
+    bulkThreshold?: number;
+}
+/**
+ * 注入 safe-delete 自身所需环境变量。
+ * brokered shell / toybox / zsh 由 shell-runtime-env.ts 负责组合。
+ */
+export declare function injectSafeDeleteEnv(env: Record<string, string>, runtimePaths: ShellRuntimePaths, options?: SafeDeleteEnvBuildOptions): void;
+export declare function buildSafeDeleteEnv(baseEnv?: Record<string, string>, options?: SafeDeleteEnvBuildOptions): Record<string, string>;
+/**
+ * 构建 PowerShell 子进程的 safe-delete 上下文环境变量。
+ *
+ * 对齐 BashTool 的 buildBashContextEnv + safe-delete 注入：
+ * - session ID：Node/Python shim 的启动条件（无 ID 时 shim 直接 return）
+ * - NODE_OPTIONS / PYTHONPATH / PATH / BASH_ENV 等：shim 加载路径
+ *
+ * 确保 PowerShell 里再执行 `node -e "fs.unlinkSync(...)"` 或
+ * `python -c "os.remove(...)"` 时 safe-delete shim 能正常生效。
+ */
+export declare function buildPowerShellSafeDeleteEnv(sessionManager: {
+    sessionSubject: {
+        value: {
+            id?: string;
+            conversationRequestId?: string;
+        } | null | undefined;
+    };
+}, safeDeleteRuntimeConfig: SafeDeleteRuntimeConfig, options?: {
+    toolCallId?: string;
+    bulkThreshold?: number;
+    session?: {
+        id?: string;
+        conversationRequestId?: string;
+    };
+}): Record<string, string>;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-report.d.ts

@@ -0,0 +1,18 @@
+export declare const SAFE_DELETE_REPORT_ENV = "CODEBUDDY_SAFE_DELETE_REPORT_PATH";
+export type SafeDeleteRuntime = 'bash' | 'node' | 'powershell' | 'python';
+export interface SafeDeleteReportEvent {
+    operation: 'trash';
+    path: string;
+    runtime?: SafeDeleteRuntime;
+    timestamp?: number;
+}
+export interface SafeDeleteReportLogger {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+}
+export declare function appendSafeDeleteReportEvent(reportPath: string | undefined, event: SafeDeleteReportEvent): Promise<void>;
+export declare function ensureSafeDeleteReportPath(env: Record<string, string>): string | undefined;
+export declare function readSafeDeleteReport(reportPath: string | undefined, logger?: SafeDeleteReportLogger): SafeDeleteReportEvent[];
+export declare function attachSafeDeleteReportEvents<T extends object>(result: T, reportPath: string | undefined, logger?: SafeDeleteReportLogger): T & {
+    safeDeleteEvents?: SafeDeleteReportEvent[];
+};

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-sandbox-helpers.d.ts

@@ -0,0 +1,39 @@
+/**
+ * safe-delete 沙箱辅助逻辑——从 sandbox-orchestrator.ts 提取的纯函数。
+ *
+ * 包括：
+ * - Windows 回收站路径反解析（$I/$R → 原始路径）
+ * - safe-delete fail-closed 审批判定
+ * - safe-delete 临时探针噪声过滤
+ */
+import type { FileBlockRecord } from '../../sandbox-cli/sandbox-cli-protocol';
+import type { ShellResult } from '../shell-protocol';
+import { type BulkGuardConfirmPayload } from './bulk-guard';
+export declare const SAFE_DELETE_FAIL_CLOSED_MARKER_RE: RegExp;
+export declare const SAFE_DELETE_BULK_CONFIRM_MARKER_RE: RegExp;
+export declare function extractWindowsRecycleBinOriginalPathFromInfoBuffer(buffer: Buffer): string | undefined;
+export declare function normalizeWindowsShellPathForAudit(targetPath: string): string;
+/**
+ * Convert Windows recycle-bin internal artifacts (`$I*` / `$R*`) back to
+ * the user-facing delete target when the original command is available.
+ */
+export declare function resolveWindowsRecycleBinAuditPath(record: {
+    path: string;
+    command?: string;
+}, fallbackCommand?: string, fallbackOutput?: string): string | undefined;
+/**
+ * 过滤 safe-delete 临时探针噪声——rm / python safe-delete 场景下，
+ * 回收站内部路径和临时目录写入不应触发用户审批。
+ */
+export declare function filterSafeDeleteTempProbeNoise(actionableFileBlocks: FileBlockRecord[], command: string, sandboxResult: ShellResult): FileBlockRecord[];
+export declare function matchesSafeDeleteEscalationCommand(command: string): boolean;
+/**
+ * 判定是否应触发 safe-delete fail-closed 审批。
+ *
+ * 仅在无结构化拦截记录（attribution=error）但 stderr/stdout 命中
+ * safe-delete fail-closed 标记时触发。
+ */
+export declare function shouldEscalateSafeDeleteFailClosed(command: string, sandboxResult: ShellResult, actionableFileBlockCount: number): boolean;
+export type SafeDeleteBulkConfirmInfo = BulkGuardConfirmPayload;
+export declare function parseSafeDeleteBulkConfirmInfo(output: string): SafeDeleteBulkConfirmInfo | undefined;
+export declare function shouldEscalateSafeDeleteBulkConfirm(command: string, sandboxResult: ShellResult, actionableFileBlockCount: number): SafeDeleteBulkConfirmInfo | undefined;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-settings.d.ts

@@ -0,0 +1,42 @@
+/**
+ * safe-delete 运行时开关读取与注入日志——消除 ShellService / SandboxShellService /
+ * PowerShellTool 三处重复。
+ */
+export declare const MIN_SAFE_DELETE_BULK_THRESHOLD = 1;
+export declare const MAX_SAFE_DELETE_BULK_THRESHOLD = 99999;
+export interface SafeDeleteSettingsReader {
+    list(): Promise<{
+        sandbox?: {
+            safeDeleteBulkThreshold?: number;
+            safeDeleteRuntimeEnabled?: boolean;
+        };
+    }>;
+}
+export interface SafeDeleteLogger {
+    info?(...args: unknown[]): void;
+    warn?(...args: unknown[]): void;
+}
+export interface SafeDeleteRuntimeConfig {
+    enabled: boolean;
+    bulkThreshold: number;
+}
+/**
+ * 解析批量删除阈值。合法时返回该值，非法时返回 undefined（由调用方决定 fallback）。
+ *
+ * 注意：workbuddy-server 和 agent-ui 各有同名 `normalizeSafeDeleteBulkThreshold` 函数，
+ * 语义为"总返回有效 number"。CLI 端此函数显式返回 undefined 以区分"配置缺失"与"有效值"。
+ */
+export declare function parseSafeDeleteBulkThreshold(value: unknown): number | undefined;
+/**
+ * 从 SettingsManager 读取 sandbox.safeDeleteRuntimeEnabled，读取失败默认 true。
+ */
+export declare function resolveSafeDeleteRuntimeEnabled(settingsManager: SafeDeleteSettingsReader, logger: SafeDeleteLogger | undefined, source: string): Promise<boolean>;
+/**
+ * 从 SettingsManager 读取 sandbox.safeDeleteRuntimeEnabled 和 safeDeleteBulkThreshold。
+ * 读取失败默认启用 runtime safe-delete，批量删除阈值使用默认常量。
+ */
+export declare function resolveSafeDeleteRuntimeConfig(settingsManager: SafeDeleteSettingsReader, logger: SafeDeleteLogger | undefined, source: string): Promise<SafeDeleteRuntimeConfig>;
+/**
+ * 记录 safe-delete 环境变量注入日志——统一格式。
+ */
+export declare function logSafeDeleteInjection(logger: SafeDeleteLogger | undefined, source: string, env: Record<string, string | undefined>, safeDeleteRuntimeEnabled: boolean): void;

package/cli/dist-server/types/node/shell/safe-delete/safe-delete-trash-service.d.ts

@@ -0,0 +1,12 @@
+import { type SafeDeleteRuntime } from './safe-delete-report';
+export interface MovePathToTrashOptions {
+    force?: boolean;
+    recursive?: boolean;
+    reportPath?: string;
+    runtime?: SafeDeleteRuntime;
+    trashDir?: string;
+    fallbackTrash?: (path: string) => Promise<void>;
+    /** 原生 trash 失败、即将尝试 fallback 时回调，供调用方记录原始失败原因。 */
+    onNativeTrashError?: (error: unknown) => void;
+}
+export declare function movePathToTrash(path: string, options?: MovePathToTrashOptions): Promise<void>;

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

@@ -0,0 +1,287 @@
+import { Disposable, Event } from '@celljs/core';
+import type { AnsiOutput } from './terminal-serializer';
+export declare const DEFAULT_BASH_TIMEOUT_MS = 120000;
+export declare const DEFAULT_BASH_MAX_TIMEOUT_MS = 600000;
+export declare const DEFAULT_BASH_MAX_OUTPUT_LENGTH = 30000;
+export declare const MAX_BASH_OUTPUT_LENGTH_CAP = 150000;
+/**
+ * 主 agent 前台阻塞预算（Kairos 式，对齐 Claude Code ASSISTANT_BLOCKING_BUDGET_MS=15000）。
+ *
+ * 默认值 0 = 禁用（CC 公开版 `feature('KAIROS')` 也默认为 false，此机制在公开版不生效）。
+ * 设置为 >0 时，主 thread 的前台 Bash 命令超过此时间会自动转为后台任务，
+ * 让主 agent 继续响应其他操作；命令本身不被 kill，继续在后台跑。
+ *
+ * 可通过 env `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` 覆盖。
+ */
+export declare const DEFAULT_BASH_ASSISTANT_BUDGET_MS = 0;
+/** Resolve the foreground assistant budget from the current runtime environment. */
+export declare function resolveBashAssistantBudgetMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * 从给定的环境变量字典解析 bash 超时配置。
+ * 显式传入的 settings env 优先；缺失或无效字段回退到运行时 process.env，再回退默认值。
+ */
+export declare function resolveBashTimeoutFromEnv(env?: Record<string, string>): {
+    defaultTimeout: number;
+    maxTimeout: number;
+};
+/** Resolve the model-facing shell output budget from the current runtime environment. */
+export declare function resolveMaxShellOutputLength(env?: NodeJS.ProcessEnv): number;
+export declare const ShellService: unique symbol;
+/**
+ * 本地 Shell 服务 Symbol，用于标识原始的 ShellServiceImpl。
+ * DelegatingShellService 通过此 Symbol 注入本地执行实现。
+ */
+export declare const LocalShellService: unique symbol;
+export interface ShellService {
+    execute(params: ShellExecuteParams): Promise<ShellExecutionHandle>;
+    disposeAll(): Promise<void>;
+    getActiveHandleCount(): number;
+}
+export interface ShellOutputChunk {
+    type: 'stdout' | 'stderr';
+    data: string;
+    timestamp: number;
+}
+export interface ShellExecuteParams {
+    /** Optional captured host environment; defaults to process.env. */
+    processEnv?: NodeJS.ProcessEnv;
+    command: string;
+    /**
+     * The run's session, passed explicitly by tool callers. Multi-session
+     * surfaces (agent-cli/server) route on it — never rely on the
+     * current-session slot or ambient context for shell dispatch.
+     */
+    session?: import('../../vendor/cbc-core/node/index.js').Session;
+    /**
+     * Execute a trusted executable with an already-tokenized argument vector.
+     * No shell or command-line parser is involved. This is intended for
+     * internal callers such as Grep that need identical argv in local and
+     * sandbox-backed execution paths.
+     */
+    directCommand?: {
+        executable: string;
+        args: string[];
+        displayCommand?: string;
+        pathOverride?: string;
+    };
+    cwd?: string;
+    timeout?: number;
+    cols?: number;
+    rows?: number;
+    env?: Record<string, string>;
+    onOutput?: (chunk: ShellOutputChunk) => void;
+    abortSignal?: AbortSignal;
+    /** Set to false to force child_process fallback (skip PTY). Defaults to true. */
+    usePty?: boolean;
+    /**
+     * Optional callback for handling sandbox intercept events.
+     * When sandbox-cli blocks a command due to policy violation, this callback is invoked
+     * with the intercept details. Return user's choice: 'allow_once' | 'allow_session' | 'deny'.
+     *
+     * Provided by BashTool to bridge sandbox intercepts into the standard
+     * InterruptionService/Permission flow using the current tool call context.
+     * If not provided, SandboxShellService uses ACP requestPermission callback or auto-allows.
+     */
+    onSandboxIntercept?: (event: {
+        interceptType: string;
+        command: string;
+        operation: string;
+        target: string;
+        details: unknown;
+    }) => Promise<'allow_once' | 'allow_session' | 'deny'>;
+    /**
+     * Optional tool call ID for correlating sandbox intercepts with the originating tool call.
+     * Used by SandboxShellService to route InterceptNotification to the correct handler.
+     */
+    toolCallId?: string;
+    /**
+     * When true, SandboxShellService executes with executionMode: 'sandbox_bypass',
+     * bypassing sandbox isolation. Corresponds to BashTool's dangerouslyDisableSandbox parameter.
+     */
+    sandboxBypass?: boolean;
+    /**
+     * When true, `command` is already a complete command line
+     * (e.g. `pwsh -NoProfile -Command "..."`) and MUST NOT be wrapped by
+     * shell-service machinery.
+     *
+     *  - SandboxShellService: passes `command` through to sandbox-cli verbatim
+     *    (no `buildSandboxCommand`).
+     *  - LocalShellService: parses `command` via `parseCommandLine(...)` and
+     *    calls `spawn(exe, args[])` directly — no bash `-c`, no shopt guard,
+     *    no `eval`, no snapshot sourcing. `CODEBUDDY_ENV_FILE` is loaded as
+     *    KEY=VALUE pairs and merged into the child's `env`. PTY is forced
+     *    off on this path (node-pty would re-introduce a shell).
+     *
+     * Used by PowerShellTool to pass raw PowerShell invocations through the
+     * sandbox orchestrator without bash-mangling on Windows.
+     */
+    rawCommand?: boolean;
+    /**
+     * Invoked by SandboxShellService immediately before a post-exec escalation retry.
+     * Callers that accumulate streaming output (e.g. BashTool's buffers) should clear
+     * their state here so the retry output is observed as a fresh stream rather than
+     * appended to the first-attempt output. Not invoked in non-retry execution paths
+     * or by LocalShellService.
+     */
+    onSandboxRetryStart?: () => void;
+    /**
+     * 命令到达 `timeout` 时的自定义处理回调。
+     *
+     * 如果返回 `true`，shell-service 认为调用方已接管后续处理（典型场景：
+     * BashTool 把命令转为后台任务继续跑），shell-service **不再发送 SIGTERM**，
+     * 子进程继续运行；`wait()` 返回的结果由调用方自行管理。
+     *
+     * 如果返回 `false` 或没有提供此回调，shell-service 维持原行为：
+     * 设置 `interrupted = true` 并调 `kill('SIGTERM')`。
+     *
+     * 同步返回值；异步决策需要调用方在外部处理（例如先快照 handle、再在外部监听）。
+     *
+     * @returns true 表示已接管；false/undefined 表示走默认 kill 路径。
+     */
+    onTimeout?: () => boolean | undefined;
+    /**
+     * 当提供时，子进程的 stdout 直接写入这个文件描述符，**不通过 pipe 回传到父进程**。
+     *
+     * 仅 LocalShellService 的 ChildProcess 路径生效（即 `usePty: false` 或 PTY 不可用时）；
+     * PTY 路径和 SandboxShellService 会忽略此参数（PTY 必须接管 stdio，sandbox 走 IPC 协议）。
+     *
+     * 用于解决"后台任务的孙进程持有父进程 pipe fd 导致 EOF 不来 / nohup 残留 defunct"问题：
+     * 当 stdout 直接写文件，孙进程继承的也是这个文件 fd，父 bash 退出立即触发 'exit'，
+     * 不依赖 grandchild 关闭 fd。参考 Claude Code `Shell.ts` 的实现。
+     *
+     * **fd 生命周期由调用方负责**：调用方 open 这个 fd，spawn 完成后 child 已 dup 自己的副本，
+     * 调用方应立即 close 父侧 fd（避免父进程持有写端导致后续读取卡住）；ShellService 不会 close。
+     */
+    stdoutFd?: number;
+    /**
+     * 同 {@link stdoutFd}，给 stderr。
+     *
+     * 可与 stdoutFd 指向同一个 fd（依赖 POSIX O_APPEND 的原子写入语义），
+     * 也可分开写两个文件（codebuddy 的默认做法，便于 UI 区分 stderr）。
+     */
+    stderrFd?: number;
+}
+/**
+ * 网络拦截记录的业务视图（ShellResult 暴露给上层 tools / orchestrator / telemetry 的形态）。
+ *
+ * Sandbox ProcessExit 仅上送 DecisionRecord；执行句柄在 IPC 边界将其投影为本
+ * 业务视图，保持 tools / orchestrator / telemetry 的既有接口不变。
+ */
+export interface ShellNetworkBlockRecord {
+    /** 被拦截的目标主机（优先域名，无域名时为 IP） */
+    host: string;
+    /** 端口号（可选） */
+    port?: number;
+    /** 协议类型: "tcp" / "udp" / "dns" / "https" 等（vendor 协议层字段名为 `scheme`，本视图统一为 `protocol`） */
+    protocol: string;
+    /** 操作类型 bitmask: 0x01=CONNECT, 0x02=DNS_RESOLVE, 0x04=SENDTO */
+    actionMask: number;
+    /** 沙箱建议的可选处理方式。 */
+    options?: string[];
+    /** 触发拦截的命令（若 Sandbox 能提供）。 */
+    command?: string;
+    /** Vendor 原始记录，保留用于诊断。 */
+    raw?: import('../sandbox-cli/sandbox-cli-protocol.js').JsonValue;
+    /**
+     * 网络拦截成因；DecisionRecord 投影使用 center_ask / center_deny 区分三态。
+     */
+    reason?: import('../sandbox-cli/sandbox-cli-protocol.js').NetworkBlockReason;
+    /** 恶意域名 DB 命中时的威胁标签。 */
+    maliciousLabel?: string;
+    /** DB 实际命中的候选域名（可能是请求域名的父域）。 */
+    matchedDomain?: string;
+    /** DB 中原始的主域匹配字段。 */
+    mainDomainMatch?: boolean;
+}
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    /** 命令是否被中断（超时或用户取消） */
+    interrupted: boolean;
+    /**
+     * `exitCode` / `signal` 是否不可信。
+     *
+     * 缺省（undefined / false）表示这份结果来自真实的进程终止事件，退出码可以直接用。
+     * 置 `true` 表示句柄是靠"进程已不存在"这个状态兜底收口的——终止事件始终没到，
+     * 退出码无从得知，此时 `exitCode: null` 不代表成功，调用方**不能**再用
+     * `exitCode ?? 0` 这类兜底把它归一成 0。
+     *
+     * 为什么需要它：线上实测约 11% 的后台子进程收不到终止事件（#92382），
+     * 没有这个标记，兜底收口会把一个失败的命令报成 completed。
+     */
+    exitStatusUnknown?: boolean;
+    /** safe-delete shim 成功把目标移入系统回收站的 side-channel 事件，不进入 stdout/stderr。 */
+    safeDeleteEvents?: import('./safe-delete/index.js').SafeDeleteReportEvent[];
+    /** 由 DecisionRecord 在 IPC 边界映射出的旧文件拦截业务视图。 */
+    fileBlockRecords?: import('../sandbox-cli/sandbox-cli-protocol.js').FileBlockRecord[];
+    /** Center authority records from the current process execution. */
+    decisionRecords?: import('../sandbox-cli/sandbox-cli-protocol.js').DecisionRecord[];
+    /** 由 DecisionRecord 在 IPC 边界映射出的旧网络拦截业务视图。 */
+    networkBlockRecords?: ShellNetworkBlockRecord[];
+    /** 沙箱是否拒绝了操作导致命令失败 */
+    sandboxDenied?: boolean;
+    /** 命中用户配置的硬拒绝规则，当前 Agent run 应直接结束 */
+    policyDenied?: boolean;
+    /**
+     * 安全规则终局拒绝的结构化说明。
+     *
+     * 文件 / 网络裁决发生在沙箱首跑之后：命令已经真跑过一遍，OS 层的
+     * `Operation not permitted` 早已通过 `onData` 流进工具的输出缓冲。置位该字段
+     * 表示"这次失败的权威原因是安全规则，不是命令本身"，工具层应当用它替代缓冲区
+     * 里的原始报错来展示。
+     *
+     * 与 `policyDenied` 正交：后者会终止整个 Agent run，此字段只影响展示。
+     */
+    denialMessage?: string;
+    /** 被沙箱阻止的文件路径列表 */
+    sandboxBlockedPaths?: string[];
+    /** 用户是否已拒绝提权请求 (区分 "没走提权" 和 "走了但用户拒绝") */
+    sandboxEscalationDenied?: boolean;
+    /** 命令因系统级工具安全策略被拦截（区分于通用 sandboxDenied） */
+    systemToolBlocked?: boolean;
+    /** 沙箱提权后重试成功，BashTool 应使用 ShellResult.stdout/stderr 而非 execCtx buffer */
+    sandboxRetried?: boolean;
+    /**
+     * Populated by the SandboxOrchestrator when the command ended up running
+     * outside the sandbox (e.g. after `dangerouslyDisableSandbox` approval, a
+     * cached `allow_session` decision, or a post-exec escalation). Downstream tools can surface this to the LLM so it
+     * knows the command did not run under sandbox isolation.
+     */
+    sandboxBypassed?: boolean;
+    /** Reason recorded when `sandboxBypassed` is true; see SandboxBypassReason. */
+    sandboxBypassReason?: 'dangerously-disable-sandbox' | 'session-approved' | 'escalation-approved' | 'exec-policy-allow' | 'system-tool-approved';
+}
+export interface ShellExecutionHandle extends Disposable {
+    readonly id: string;
+    readonly pid: number;
+    readonly isAlive: boolean;
+    readonly command: string;
+    write(data: string): void;
+    sendKey(key: ShellSpecialKey): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    getScreen(): string;
+    getColorScreen(): AnsiOutput;
+    usedAlternateBuffer(): boolean;
+    wait(): Promise<ShellResult>;
+    /**
+     * 若进程已终止而终止事件始终没来，则手动收口 {@link wait}；否则什么都不做。
+     *
+     * 与 {@link kill} 的职责严格分开：本方法**永不发信号**。`kill` 内部的兜底只覆盖
+     * 「进程活着 → 被杀 → 事件丢失」，而「进程已经死了 → 事件丢失」这条只能由本方法
+     * 收口——线上实测约 11% 的后台子进程走到后一种情形（#92382），不收口则 `wait()`
+     * 永久挂起，依赖它的后台任务终态判定与通知全部停摆。
+     *
+     * 可选：sandbox 侧的句柄实现暂未接入，调用方需用 `?.` 并对 undefined 做兜底。
+     *
+     * @returns 是否真的发生了收口；进程仍存活或已收口过都返回 false。
+     */
+    settleIfProcessExited?(): boolean;
+    readonly onData: Event<string>;
+    readonly onExit: Event<ShellResult>;
+    /** 当检测到程序进入 alternate screen buffer 时触发（TUI 程序特征） */
+    readonly onAlternateBuffer: Event<void>;
+}
+export type ShellSpecialKey = 'CTRL_A' | 'CTRL_B' | 'CTRL_C' | 'CTRL_D' | 'CTRL_E' | 'CTRL_F' | 'CTRL_G' | 'CTRL_H' | 'CTRL_I' | 'CTRL_J' | 'CTRL_K' | 'CTRL_L' | 'CTRL_M' | 'CTRL_N' | 'CTRL_O' | 'CTRL_P' | 'CTRL_Q' | 'CTRL_R' | 'CTRL_S' | 'CTRL_T' | 'CTRL_U' | 'CTRL_V' | 'CTRL_W' | 'CTRL_X' | 'CTRL_Y' | 'CTRL_Z' | 'ENTER' | 'TAB' | 'ESCAPE' | 'BACKSPACE' | 'DELETE' | 'UP' | 'DOWN' | 'LEFT' | 'RIGHT' | 'HOME' | 'END' | 'PAGE_UP' | 'PAGE_DOWN';