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

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

@@ -0,0 +1,44 @@
+import { Logger } from '@celljs/core';
+import { type BashSandboxManager as IBashSandboxManager } from '../bash-sandbox/bash-sandbox-protocol';
+import { type ShellExecuteParams, type ShellExecutionHandle, type ShellService } from './shell-protocol';
+/**
+ * Platform-dependent sandbox backend dispatch.
+ *
+ *   - `sandbox-cli`: the persistent Rust binary + IPC
+ *   - `legacy`:      `@anthropic-ai/sandbox-runtime` wrapping
+ *   - `off`:         local execution, no sandbox
+ *
+ * The distinction matters because `SandboxOrchestrator` disables post-exec
+ * escalation on the `legacy` backend — see that file for details.
+ */
+export type SandboxBackend = 'sandbox-cli' | 'legacy' | 'off';
+/**
+ * 委托 Shell 服务
+ *
+ * 注册在 ShellService Symbol 上，替代原来的 ShellServiceImpl 作为默认实现。
+ * 根据 `settings.sandbox.enabled` + 平台 决定委托给哪个后端：
+ *   - sandbox 开启 → SandboxShellService (sandbox-cli)
+ *   - 其他情况     → LocalShellService
+ */
+export declare class DelegatingShellService implements ShellService {
+    protected readonly localShellService: ShellService;
+    protected readonly sandboxShellService?: ShellService;
+    protected readonly legacySandboxShellService?: ShellService;
+    protected readonly bashSandboxManager?: IBashSandboxManager;
+    protected readonly driverShellService: ShellService;
+    protected readonly logger: Logger;
+    execute(params: ShellExecuteParams): Promise<ShellExecutionHandle>;
+    disposeAll(): Promise<void>;
+    getActiveHandleCount(): number;
+    /**
+     * Resolve the sandbox backend for the current process.
+     *
+     * Single source of truth for the enable/disable decision is
+     * `settings.sandbox.enabled` (same file the TUI `/sandbox` panel and the
+     * Desktop SandboxConfigBar write). Linux sandbox-cli is additionally gated
+     * by a WorkBuddy host capability env so shared CodeBuddy/CBC Linux keeps the
+     * previous legacy backend unless WorkBuddy explicitly opts in.
+     */
+    resolveBackend(): Promise<SandboxBackend>;
+    private pickDelegate;
+}

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

@@ -0,0 +1,8 @@
+import type { ShellExecuteParams, ShellExecutionHandle, ShellService } from './shell-protocol';
+export declare const DriverShellService: unique symbol;
+export declare class DriverShellServiceImpl implements ShellService {
+    private activeHandles;
+    execute(params: ShellExecuteParams): Promise<ShellExecutionHandle>;
+    disposeAll(): Promise<void>;
+    getActiveHandleCount(): number;
+}

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>;