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

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

@@ -0,0 +1,23 @@
+export interface ShellRuntimePaths {
+    shimDir: string;
+    nodeShimPath: string;
+    safeBinDir: string;
+    bashEnvPath?: string;
+    genieTrashDir?: string;
+    brokeredShellEnvPath?: string;
+    brokeredBinDir?: string;
+    toyboxBinPath?: string;
+    toyboxSandboxProfilePath?: string;
+    zshBinPath?: string;
+}
+export declare function __resetShellRuntimePathsCacheForTest(): void;
+export declare function canAccess(pathValue: string, mode?: number): boolean;
+export declare function canExecute(pathValue: string): boolean;
+/**
+ * 打包后 shim/native 资源被放进 app.asar.unpacked，而 process.execPath/argv 推导出的
+ * 根路径可能仍指向 app.asar（只读虚拟归档，无法真正访问文件）。这里把 app.asar 段
+ * 额外映射出一个 app.asar.unpacked 候选，两者都参与后续探测。
+ */
+export declare function expandAsarUnpackedCandidates(value: string): string[];
+export declare function resolveShellRuntimePaths(): ShellRuntimePaths | undefined;
+export declare function resolveBrokeredShellRuntimeReadOnlyRoots(runtimePaths?: ShellRuntimePaths | undefined): string[];

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

@@ -0,0 +1,257 @@
+import { Logger } from '@celljs/core';
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import type { IPty } from '@lydell/node-pty';
+import type { Terminal } from '@xterm/headless';
+import { ChildProcess } from 'child_process';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+import { SettingsManager } from '../settings/settings-protocol';
+import { ShellExecuteParams, ShellExecutionHandle, ShellResult, ShellService, ShellSpecialKey } from './shell-protocol';
+import { ShellSnapshotService } from './shell-snapshot-protocol';
+import { type AnsiOutput } from './terminal-serializer';
+/**
+ * 进程是否仍然存在。`process.kill(pid, 0)` 不发信号，只做存在性探测。
+ *
+ * 失败原因必须分开看：
+ * - `ESRCH` —— 进程确实不在了。
+ * - `EPERM` —— 进程在，只是当前用户无权给它发信号（换 uid 的 sudo 子进程等）。
+ *
+ * 旧实现把两者都当成"已退出"，代价有两个：`kill()` 会对一个还活着的进程提前放弃，
+ * 而存活对账会把它误判成终态并给模型发一条假的完成通知。因此除 `ESRCH` 之外的
+ * 任何错误都按"存在"处理——宁可多等一轮，也不要误报终态。
+ *
+ * 注意 `!pid` 这道守卫是承重的：pid 0 在 POSIX 里指"调用者自己的进程组"，
+ * `process.kill(0, 0)` 会成功，后续的 `process.kill(-pid, ...)` 会把信号发给我们自己。
+ */
+export declare function processExists(pid: number): boolean;
+/**
+ * 进程是否已终止：不存在（`ESRCH`），或存在但已是僵尸。
+ *
+ * 这是"还有没有终止事件可等"的判据，供 `settleIfProcessExited` 与后台任务的
+ * 存活对账使用。它与 `isAlive` 刻意分开：`isAlive` 服务于"该不该发信号"，
+ * 把僵尸语义塞进去会波及 grep 等既有调用方。
+ */
+export declare function isProcessTerminated(pid: number): boolean;
+export declare function resolveWindowsHideOption(isWin: boolean): {
+    windowsHide?: true;
+};
+export declare function buildChildProcessEnv(params: {
+    extraEnv: Record<string, string | undefined>;
+    shellRuntimeEnv: Record<string, string | undefined>;
+    rawCommand?: boolean;
+    sandboxBypass?: boolean;
+    processEnv?: NodeJS.ProcessEnv;
+    isWin?: boolean;
+    projectDir?: string;
+    session?: ShellExecuteParams['session'];
+    carrier?: Readonly<Record<string, unknown>>;
+}): Record<string, string | undefined>;
+export { wrapPowerShellCommandWithSafeDelete } from './powershell-safe-delete';
+export declare class ShellServiceImpl implements ShellService {
+    protected readonly workspace: Workspace;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly snapshotService?: ShellSnapshotService;
+    protected readonly prewarmState?: IPrewarmStateService;
+    private cachedSnapshotPath;
+    private readonly activeHandles;
+    private snapshotWarmupTimer?;
+    private snapshotWarmupScheduled;
+    private snapshotWarmupActivationRegistered;
+    private snapshotWarmupDisposed;
+    init(): void;
+    disposeSnapshotWarmup(): void;
+    /**
+     * 调度 snapshot 预热
+     *
+     * 启动路径只做最轻量的调度: 排一个 2s 定时, 所有检查 (环境变量 / Git Bash 探测 /
+     * 服务可用性) 都推迟到定时回调里执行, 避开启动前 2 秒的 CPU/IO 争抢
+     * (AgentManager rebuild / MCP 配置读取 / LSP 初始化等都在这时间窗内).
+     *
+     * 决策矩阵:
+     * - `CODEBUDDY_DISABLE_SHELL_SNAPSHOT=1` → 强制禁用 (所有平台)
+     * - Windows 且无 Git Bash → 默认跳过 (此时 shell 降级为 PowerShell,
+     *   POSIX snapshot 不适用). `CODEBUDDY_ENABLE_SHELL_SNAPSHOT=1` 可覆盖
+     * - 其他情况 → 启用
+     */
+    private scheduleSnapshotWarmup;
+    execute(params: ShellExecuteParams): Promise<ShellExecutionHandle>;
+    disposeAll(): Promise<void>;
+    getActiveHandleCount(): number;
+    private createChildProcessHandle;
+    private createPtyHandle;
+    /**
+     * 确保 shell snapshot 已创建，在首次执行命令时创建 snapshot
+     */
+    private ensureSnapshot;
+    /**
+     * 把用户命令包装成目标 shell 能执行的完整脚本。
+     *
+     * 职责：
+     * 1. source shell snapshot（让子进程继承用户原始的 PATH/alias 等）
+     * 2. 把 WORKBUDDY_EXTRA_PATHS 前置到 PATH（让 Agent 能找到 CLI Connector 装的工具）
+     * 3. 读取并执行 CODEBUDDY_ENV_FILE
+     * 4. 用 eval 执行用户命令
+     *
+     * 按 shell 类型分派：POSIX（bash/zsh/sh）和 PowerShell 语法完全不同，
+     * 不能共用一套模板。
+     */
+    private formatCommand;
+    /**
+     * POSIX shell（bash / zsh / sh）的命令包装。
+     *
+     * Windows + Git Bash 场景注意：`WORKBUDDY_EXTRA_PATHS` 从 desktop 注入时是
+     * Windows 路径风格（`C:\Users\...`）。Git Bash 子进程的 PATH 若含反斜杠形式，
+     * `$0` 在 shim 脚本里解析会走上 MSYS 挂载根（cygpath 转出 `C:\Program Files\Git\Users\...`
+     * 这种错误路径）。因此这里用 `windowsPathToUnix` 统一转换为 `/c/Users/...`
+     * POSIX 形式，让 shim 里的 `dirname` + `cygpath -w` 能正确回转 Windows 路径。
+     */
+    private formatCommandPosix;
+    /**
+     * PowerShell 的命令包装。
+     *
+     * PowerShell 5+ 和 pwsh 7+ 都接受同一套语法：
+     * - `$env:PATH = '...'` 设置环境变量
+     * - `;` 语句分隔
+     * - 命令本身直接交给 PowerShell 解析（不 eval）
+     *
+     * Shell snapshot / CODEBUDDY_ENV_FILE 机制仅对 POSIX shell 生效，这里跳过。
+     */
+    private formatCommandPowerShell;
+    /**
+     * Best-effort read of CODEBUDDY_ENV_FILE as a flat KEY=VALUE map suitable
+     * for process.env. Used on the rawCommand path where no shell is available
+     * to source the file. Complex shell logic in the env file (source/eval/
+     * function defs) is silently skipped.
+     */
+    private readEnvFileAsVars;
+    private isValidDirectory;
+}
+export declare class ShellExecutionHandleImpl implements ShellExecutionHandle {
+    private readonly ptyProcess;
+    private readonly headlessTerminal;
+    readonly command: string;
+    private readonly onOutput?;
+    private readonly abortSignal?;
+    private readonly logger?;
+    private extraPtmxFd?;
+    private readonly onTimeout?;
+    private readonly safeDeleteReportPath?;
+    private _disposed;
+    private _exited;
+    private _interrupted;
+    private _result;
+    private _exitPromise;
+    private _exitResolve;
+    private readonly _onData;
+    private readonly _onExit;
+    private readonly _onAlternateBuffer;
+    readonly onData: import("@celljs/core").Event<string>;
+    readonly onExit: import("@celljs/core").Event<ShellResult>;
+    readonly onAlternateBuffer: import("@celljs/core").Event<void>;
+    private readonly stdoutBuf;
+    private isStreamingRawContent;
+    private sniffedBytes;
+    private readonly MAX_SNIFF_SIZE;
+    private isWriting;
+    private renderTimeout;
+    private timeoutTimer;
+    private _usedAlternateBuffer;
+    constructor(ptyProcess: IPty, headlessTerminal: InstanceType<typeof Terminal>, command: string, onOutput?: ((chunk: {
+        type: "stdout" | "stderr";
+        data: string;
+        timestamp: number;
+    }) => void) | undefined, abortSignal?: AbortSignal | undefined, timeout?: number, logger?: Logger | undefined, extraPtmxFd?: number | undefined, onTimeout?: (() => boolean | undefined) | undefined, safeDeleteReportPath?: string | undefined);
+    get id(): string;
+    get pid(): number;
+    get isAlive(): boolean;
+    write(data: string): void;
+    sendKey(key: ShellSpecialKey): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * 进程已终止、但终止事件始终没来时，手动收口 `wait()`。
+     *
+     * 与 `kill()` 的职责严格分开：本方法**永不发信号**，只负责让一个已经没有
+     * 后续事件可等的句柄收敛到终态。`kill()` 里的兜底只覆盖"进程活着 → 被杀 →
+     * 事件丢失"，而"进程已经死了 → 事件丢失"这条只能由这里收（#92382）。
+     *
+     * @returns 是否真的发生了收口。进程还活着、或已经收口过，都返回 false。
+     */
+    settleIfProcessExited(): boolean;
+    /**
+     * 收口的具体动作。
+     *
+     * `exitStatusUnknown: true` 是关键：退出码无从得知，调用方不能再用
+     * `exitCode ?? 0` 把 null 兜成 0，否则失败的命令会被报成成功。
+     */
+    private settleWithoutExitEvent;
+    getScreen(): string;
+    getColorScreen(): AnsiOutput;
+    usedAlternateBuffer(): boolean;
+    wait(): Promise<ShellResult>;
+    dispose(): void;
+    private handleOutput;
+    private render;
+    private renderFn;
+    private signalNumberToName;
+}
+export declare class ChildProcessExecutionHandleImpl implements ShellExecutionHandle {
+    private readonly shellProcess;
+    readonly command: string;
+    private readonly guardedCommand;
+    private readonly onOutput?;
+    private readonly abortSignal?;
+    private readonly logger?;
+    private readonly onTimeout?;
+    private readonly safeDeleteReportPath?;
+    private _disposed;
+    private _exited;
+    private _interrupted;
+    private _result;
+    private _exitPromise;
+    private _exitResolve;
+    private readonly _onData;
+    private readonly _onExit;
+    private readonly _onAlternateBuffer;
+    readonly onData: import("@celljs/core").Event<string>;
+    readonly onExit: import("@celljs/core").Event<ShellResult>;
+    /** child_process 模式不支持检测 alternate buffer，此事件永不触发 */
+    readonly onAlternateBuffer: import("@celljs/core").Event<void>;
+    private readonly stdoutBuf;
+    private readonly stderrBuf;
+    private readonly outputDecoders;
+    private timeoutTimer;
+    constructor(shellProcess: ChildProcess, command: string, guardedCommand: string, onOutput?: ((chunk: {
+        type: "stdout" | "stderr";
+        data: string;
+        timestamp: number;
+    }) => void) | undefined, abortSignal?: AbortSignal | undefined, timeout?: number, logger?: Logger | undefined, onTimeout?: (() => boolean | undefined) | undefined, safeDeleteReportPath?: string | undefined);
+    get id(): string;
+    get pid(): number;
+    get isAlive(): boolean;
+    write(data: string): void;
+    sendKey(key: ShellSpecialKey): void;
+    resize(_cols: number, _rows: number): void;
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * 进程已终止、但 'exit' 事件始终没来时，手动收口 `wait()`。
+     * 语义与职责边界见 PTY 分支的同名方法。
+     *
+     * @returns 是否真的发生了收口。
+     */
+    settleIfProcessExited(): boolean;
+    /**
+     * 收口的具体动作。
+     * `exitStatusUnknown: true` 的含义见 {@link ShellResult.exitStatusUnknown}。
+     */
+    private settleWithoutExitEvent;
+    getScreen(): string;
+    getColorScreen(): AnsiOutput;
+    usedAlternateBuffer(): boolean;
+    wait(): Promise<ShellResult>;
+    dispose(): void;
+    private handleOutput;
+    private appendOutput;
+    /** 结束时冲刷未完整的尾字节；重复调用不会重复输出。 */
+    private flushPendingTails;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Shell Snapshot 服务协议定义
+ *
+ * Shell Snapshot 用于在 CLI 启动时捕获用户的 shell 环境配置，
+ * 包括函数定义、别名、shell 选项等，并在后续命令执行时 source 该 snapshot，
+ * 以确保命令在用户熟悉的环境中执行。
+ */
+export declare const SNAPSHOT_CREATION_TIMEOUT_MS = 10000;
+export declare const SNAPSHOT_MAX_BUFFER = 1048576;
+export declare const SNAPSHOT_DIR_NAME = "shell-snapshots";
+/**
+ * Shell Snapshot 服务接口
+ */
+export declare const ShellSnapshotService: unique symbol;
+export interface ShellSnapshotService {
+    /**
+     * 获取或创建 shell snapshot
+     * @returns snapshot 文件路径，如果创建失败则返回 undefined
+     */
+    getSnapshot(): Promise<string | undefined>;
+    /**
+     * 预热：提前开始创建 snapshot（不等待完成）
+     * 应在应用启动时调用，这样首次执行命令时 snapshot 可能已经准备好
+     */
+    warmup(): void;
+    /**
+     * 清除缓存的 snapshot，强制重新创建
+     */
+    clearCache(): void;
+}
+/**
+ * Shell 配置文件信息
+ */
+export interface ShellConfigFile {
+    /** shell 类型 */
+    shellType: 'bash' | 'zsh' | 'sh';
+    /** 配置文件路径 */
+    configPath: string;
+    /** 配置文件是否存在 */
+    exists: boolean;
+}
+/**
+ * Snapshot 创建结果
+ */
+export interface SnapshotResult {
+    /** snapshot 文件路径 */
+    filePath: string;
+    /** 文件大小 (bytes) */
+    size: number;
+    /** 创建时间 */
+    createdAt: number;
+}
+/**
+ * 获取 shell 配置文件路径
+ *
+ * - zsh -> ~/.zshrc
+ * - bash -> 按优先级查找: ~/.bash_profile > ~/.bashrc > ~/.profile
+ * - 其他 -> ~/.profile
+ *
+ * Windows Git Bash 环境会优先使用 HOME 环境变量作为用户主目录
+ *
+ * @param shellPath shell 可执行文件路径
+ * @returns 配置文件信息
+ */
+export declare function getShellConfigFile(shellPath: string): ShellConfigFile;
+/**
+ * 获取 snapshot 存储目录
+ * @param codebuddyHome CodeBuddy 主目录 (默认从 CODEBUDDY_CONFIG_DIR 环境变量或 ~/.codebuddy)
+ */
+export declare function getSnapshotDirectory(codebuddyHome?: string): string;
+/**
+ * 生成 snapshot 文件名
+ * @param shellType shell 类型
+ */
+export declare function generateSnapshotFileName(shellType: 'bash' | 'zsh' | 'sh'): string;

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

@@ -0,0 +1,86 @@
+import { Logger } from '@celljs/core';
+import { ShellSnapshotService } from './shell-snapshot-protocol';
+/**
+ * Shell Snapshot 服务实现
+ *
+ * 1. 检测 shell 类型 (bash/zsh)
+ * 2. 查找对应的配置文件 (.bashrc/.zshrc)
+ * 3. 生成 snapshot 脚本并执行
+ * 4. 缓存 snapshot 文件路径供后续使用
+ */
+export declare class ShellSnapshotServiceImpl implements ShellSnapshotService {
+    protected readonly logger: Logger;
+    private cachedSnapshot;
+    private creatingPromise;
+    private disposed;
+    private readonly shutdown;
+    private creationFailed;
+    private cleanupCallback;
+    protected init(): void;
+    /**
+     * 预热：提前开始创建 snapshot（不等待完成）
+     * 与 Claude Code 行为一致：在 shell provider 创建时就启动 snapshot 创建
+     */
+    warmup(): void;
+    /** Drain all snapshot callbacks while the host's dependencies are still available. */
+    dispose(): Promise<void>;
+    getSnapshot(): Promise<string | undefined>;
+    clearCache(): void;
+    /**
+     * 创建 shell snapshot
+     */
+    private createSnapshot;
+    /**
+     * 清理部分创建的 snapshot 文件
+     * 在创建失败（如超时）时调用，避免留下不完整的文件
+     */
+    private cleanupPartialSnapshot;
+    /**
+     * 生成 snapshot 脚本的 FIY 函数逻辑
+     *
+     */
+    private generateSnapshotScript;
+    /**
+     * 生成环境导出脚本（函数、选项、别名）。
+     *
+     * 设计原则：只序列化目标 shell 能可靠重放的状态。
+     * - bash / zsh：保留函数、选项、别名
+     * - sh：仅保留稳定的导出环境变量，避免混入 bash 专属语法
+     */
+    private generateEnvironmentExportScript;
+    /**
+     * 生成 zsh 环境导出脚本。
+     */
+    private generateZshEnvironmentExportScript;
+    /**
+     * 生成 bash 环境导出脚本。
+     */
+    private generateBashEnvironmentExportScript;
+    /**
+     * 生成最小 POSIX sh 环境导出脚本。
+     * 仅保留稳定的导出变量，避免导出 shell 运行态。
+     */
+    private generatePosixShEnvironmentExportScript;
+    /**
+     * 生成别名导出脚本（bash / zsh）。
+     */
+    private generateAliasExportScript;
+    /**
+     * 生成工具配置脚本（PATH 导出等）的 mIY 函数的相关部分
+     *
+     */
+    private generateToolConfigScript;
+    /**
+     * 验证 snapshot 是否可被目标 shell 静默 source。
+     */
+    private validateSnapshot;
+    /**
+     * 执行 snapshot 脚本
+     */
+    private executeSnapshotScript;
+    /**
+     * 注册退出时的清理回调
+     * 与 Claude Code 使用 signal-exit 的 onExit 保持一致的行为
+     */
+    private registerCleanupCallback;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Terminal serializer for xterm headless terminal
+ * Extracts screen content with ANSI color codes preserved
+ */
+import type { Terminal } from '@xterm/headless';
+export interface AnsiToken {
+    text: string;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    dim: boolean;
+    inverse: boolean;
+    fg: string;
+    bg: string;
+}
+export type AnsiLine = AnsiToken[];
+export type AnsiOutput = AnsiLine[];
+export declare const enum ColorMode {
+    DEFAULT = 0,
+    PALETTE = 1,
+    RGB = 2
+}
+/**
+ * Serialize terminal content to structured AnsiOutput
+ */
+export declare function serializeTerminalToObject(terminal: Terminal): AnsiOutput;

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

@@ -0,0 +1,24 @@
+export declare class TruncateBuffer {
+    private readonly headLimit;
+    private readonly tailLimit;
+    private headBuf;
+    private tailBuf;
+    private truncatedBytes;
+    private totalLines;
+    constructor(headLimit?: number, tailLimit?: number);
+    push(data: string): void;
+    toString(withMarker?: boolean): string;
+    getEndOffset(): number;
+    readSince(offset: number): {
+        content: string;
+        fromOffset: number;
+        nextOffset: number;
+        omittedLength: number;
+    };
+    isEmpty(): boolean;
+    getHead(): string;
+    getTail(): string;
+    getTruncatedBytes(): number;
+    getTotalLines(): number;
+    clear(): void;
+}

package/cli/dist-server/types/node/shell/windows-process-utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Windows-specific process management utilities.
+ *
+ * Provides reliable process tree termination and inspection on Windows,
+ * where POSIX signals (SIGTERM, SIGKILL) and process groups are not available.
+ */
+export declare class WindowsProcessUtils {
+    /**
+     * Forcefully terminate a process and all its descendants.
+     *
+     * Uses `taskkill /F /T` which:
+     *   /F = Force termination
+     *   /T = Terminate child processes (tree kill)
+     *
+     * windowsHide: true prevents a visible console window flash.
+     */
+    static killProcessTree(pid: number): Promise<void>;
+    /**
+     * Synchronously kill a process tree. Best-effort — does not throw.
+     */
+    static killProcessTreeSync(pid: number): void;
+    /**
+     * Check if a process with the given PID is still running.
+     *
+     * Uses `tasklist /FI "PID eq <pid>"` and checks if the output
+     * contains the PID. This is more reliable than `process.kill(pid, 0)`
+     * on Windows.
+     */
+    static isProcessAlive(pid: number): boolean;
+    /**
+     * Get the list of child process PIDs for a given parent PID.
+     *
+     * Uses `wmic process where "ParentProcessId=<pid>" get ProcessId`.
+     * Note: wmic is deprecated in modern Windows but still available.
+     * For Windows 10+, could use PowerShell Get-CimInstance instead.
+     */
+    static getChildProcesses(parentPid: number): number[];
+    /**
+     * Recursively collect all descendant PIDs (children, grandchildren, etc.)
+     */
+    static getDescendantProcesses(pid: number): number[];
+}

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

@@ -0,0 +1,41 @@
+import { Disposable, MaybePromise } from '@celljs/core';
+export interface ShortcutHandler {
+    id: string;
+    keyCode: string;
+    handler: () => MaybePromise<void>;
+    description?: string;
+}
+export interface ShortcutInfo {
+    keyCode: string;
+    description?: string;
+}
+export declare const ShortcutManager: unique symbol;
+export interface ShortcutManager {
+    register(keyCode: string, handler: () => MaybePromise<void>, description?: string): Disposable;
+    getShortcuts(): ShortcutInfo[];
+    /** 分发一个输入序列到匹配的快捷键 handler（由 TUI 的 useShortcutBridge 调用） */
+    dispatch(sequence: string): void;
+}
+export declare const TtyInputService: unique symbol;
+export interface TtyInputService {
+    getInputStream(): import('tty').ReadStream | undefined;
+    dispose(): void;
+}
+export declare const KEY_CODES: {
+    readonly CTRL_B: "\u0002";
+    readonly CTRL_C: "\u0003";
+    readonly CTRL_D: "\u0004";
+    readonly CTRL_Z: "\u001A";
+    readonly CTRL_L: "\f";
+    readonly CTRL_R: "\u0012";
+    readonly CTRL_U: "\u0015";
+    readonly CTRL_K: "\v";
+    readonly ESC: "\u001B";
+    readonly TAB: "\t";
+    readonly ENTER: "\r";
+    readonly BACKSPACE: "";
+    readonly ARROW_UP: "\u001B[A";
+    readonly ARROW_DOWN: "\u001B[B";
+    readonly ARROW_LEFT: "\u001B[D";
+    readonly ARROW_RIGHT: "\u001B[C";
+};

package/cli/dist-server/types/node/skills/skill-approval.d.ts

@@ -0,0 +1,31 @@
+import type { Session } from '../../vendor/cbc-core/node/index.js';
+import type { ProductManager, Skill, SkillApprovalRule } from '../../workspace/product/lib/common/index.js';
+export interface SkillLookupResult {
+    skill?: Skill;
+    error?: string;
+}
+type SkillModelInvocationPredicate = (skill: Skill) => boolean | Promise<boolean>;
+export interface ResolvedSkillApprovalDecision {
+    policyId: string;
+    mandatory: boolean;
+    presentation: SkillApprovalRule['presentation'];
+    authorization: SkillApprovalRule['authorization'];
+}
+export declare function findSkillByName(skills: Skill[] | undefined, skillName: string): SkillLookupResult;
+export declare function unwrapSkillInput(input: unknown): Record<string, unknown>;
+export declare function getRequestedSkillName(input: unknown): string;
+export declare function getResolvedSkillApprovalDecision(session: Session, callId: string | undefined): ResolvedSkillApprovalDecision | undefined;
+export declare function clearResolvedSkillApprovalDecision(session: Session, callId: string | undefined): void;
+export declare function bindResolvedSkillApprovalDecision(session: Session, rawItem: {
+    callId?: string;
+    providerData?: Record<string, unknown>;
+}): ResolvedSkillApprovalDecision | undefined;
+export declare function getBoundSkillApprovalDecision(rawItem: {
+    providerData?: Record<string, unknown>;
+}): ResolvedSkillApprovalDecision | undefined;
+export declare function resolveSkillApprovalRejectionContent(rawItem: {
+    providerData?: Record<string, unknown>;
+}): string | undefined;
+export type SkillApprovalFailureReporter = (stage: 'configuration' | 'model', requiresApproval: boolean) => void;
+export declare function needsSkillApproval(productManager: ProductManager, session: Session, input: unknown, reportFailure?: SkillApprovalFailureReporter, callId?: string, isModelInvocable?: SkillModelInvocationPredicate): Promise<boolean>;
+export {};

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

@@ -0,0 +1,5 @@
+export * from './stats-protocol';
+export * from './insights-protocol';
+export * from './stats-service';
+export * from './insights-report-service';
+export * from './session-facet-service';

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

@@ -0,0 +1,59 @@
+/**
+ * Insights 服务协议
+ * 定义 per-session facet 分析和 HTML 报告生成的接口
+ */
+export declare const InsightsReportService: unique symbol;
+export interface InsightsReportService {
+    /**
+     * 生成 HTML 报告并保存到磁盘
+     * @param insightsData 完整的 insights JSON 数据
+     * @param language 可选的语言设置，用于本地化报告
+     * @returns 报告文件的绝对路径
+     */
+    generateReport(insightsData: Record<string, unknown>, language?: string): Promise<string>;
+}
+export declare const SessionFacetService: unique symbol;
+/**
+ * Per-session facet JSON 格式
+ */
+export interface SessionFacet {
+    underlying_goal: string;
+    goal_categories: Record<string, number>;
+    outcome: string;
+    user_satisfaction_counts: Record<string, number>;
+    codebuddy_helpfulness: string;
+    session_type: string;
+    friction_counts: Record<string, number>;
+    friction_detail: string;
+    primary_success: string;
+    brief_summary: string;
+    session_id: string;
+    /** 生成此 facet 时 session 的 updatedAt 时间戳（用于变化检测） */
+    _updatedAt?: number;
+    /** 分析失败标记，避免反复重试 */
+    _error?: boolean;
+    _errorReason?: string;
+}
+/**
+ * Session 分析进度回调
+ * @param analyzed 已分析的数量
+ * @param total 需要分析的总数
+ * @param cached 命中缓存的数量
+ */
+export type SessionAnalysisProgressCallback = (analyzed: number, total: number, cached: number) => void;
+export interface SessionFacetService {
+    /**
+     * 获取 facets 存储目录
+     */
+    getFacetsDir(): string;
+    /**
+     * 增量分析所有 session，返回所有 facet（已有 + 新生成）
+     * 跳过子 agent session
+     * 对无变化的 session 直接读取已有 facet
+     * 对新增/变化的 session 调用模型分析
+     * @param language 可选的语言设置，用于生成本地化的 facet 内容
+     * @param onProgress 可选的进度回调
+     * @param signal 可选的 AbortSignal，用于取消分析
+     */
+    analyzeAllSessions(language?: string, onProgress?: SessionAnalysisProgressCallback, signal?: AbortSignal): Promise<SessionFacet[]>;
+}