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

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

@@ -0,0 +1,203 @@
+/**
+ * Trace Collector Protocol
+ *
+ * DI Symbol, interface and data types for the in-memory trace collector.
+ * The collector receives data from two sources:
+ *   1. SDK TracingProcessor — automatic agent/generation/function/handoff spans
+ *   2. Hook system — business context enrichment (sessionId, prompt, agent name)
+ */
+export declare const TraceCollectorService: unique symbol;
+export type CollectedSpanType = 'agent' | 'generation' | 'function' | 'handoff' | 'guardrail' | 'response' | 'tool' | 'custom';
+export interface CollectedSpan {
+    traceId: string;
+    spanId: string;
+    parentId: string | null;
+    name: string;
+    type: CollectedSpanType;
+    startedAt: string;
+    endedAt: string | null;
+    duration: number | null;
+    status: 'ok' | 'error' | 'cancelled' | 'running';
+    error: string | null;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    toolName?: string;
+    toolInput?: string;
+    toolOutput?: string;
+    agentName?: string;
+    fromAgent?: string;
+    toAgent?: string;
+    attributes?: Record<string, any>;
+}
+export interface CollectedTrace {
+    traceId: string;
+    name: string;
+    sessionId?: string;
+    agentName?: string;
+    prompt?: string;
+    workerPid?: number;
+    workerHostname?: string;
+    startedAt: string;
+    endedAt: string | null;
+    duration: number | null;
+    status: 'ok' | 'error' | 'cancelled' | 'running';
+    spanCount: number;
+    totalTokens: number;
+    modelInfo?: TraceModelInfo;
+    metadata?: Record<string, any>;
+}
+export type TraceCategory = 'main' | 'auxiliary';
+export interface TraceListItem {
+    traceId: string;
+    name: string;
+    category: TraceCategory;
+    sessionId?: string;
+    agentName?: string;
+    prompt?: string;
+    startedAt: string;
+    endedAt: string | null;
+    duration: number | null;
+    status: 'ok' | 'error' | 'cancelled' | 'running';
+    spanCount: number;
+    totalTokens: number;
+    modelInfo?: TraceModelInfo;
+    /** Number of error spans inside this trace (cancelled spans not counted) */
+    errorCount?: number;
+    /** Truncated message of the first error span, for preview in list view */
+    firstErrorMessage?: string;
+    /** Span id of the first error, for jump-to-error in detail view */
+    firstErrorSpanId?: string;
+    /** Tool/agent name where the first error occurred, used as label */
+    firstErrorWhere?: string;
+}
+export interface TraceBottleneck {
+    spanId: string;
+    name: string;
+    duration: number;
+    percentage: number;
+}
+/** Aggregated error info for a trace, grouped by tool/agent name */
+export interface TraceErrorGroup {
+    /** toolName / agentName / span.name */
+    where: string;
+    /** Span type, used to choose icon */
+    type: CollectedSpanType;
+    /** Number of error spans matching this group */
+    count: number;
+    /** Truncated error message of the first error in this group */
+    sampleMessage: string;
+    /** First error span id (for jump-to-span) */
+    spanId: string;
+}
+export interface TraceErrorSummary {
+    totalErrors: number;
+    /** Aggregated error groups, sorted by count desc */
+    groups: TraceErrorGroup[];
+    /** First (in time order) error span id; same as groups[0].spanId if present */
+    firstErrorSpanId?: string;
+}
+export interface TraceDetail {
+    trace: TraceListItem;
+    spans: CollectedSpan[];
+    bottleneck: TraceBottleneck | null;
+    /** Error aggregation, omitted when totalErrors === 0 */
+    errorSummary?: TraceErrorSummary;
+}
+export interface TraceListResponse {
+    traces: TraceListItem[];
+    total: number;
+}
+export interface TraceModelInfo {
+    models: string[];
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    /** Cached tokens from last LLM call (for cache hit rate calculation) */
+    totalCachedTokens: number;
+    /** Input tokens from last LLM call (denominator for cache hit rate) */
+    lastCallInputTokens: number;
+    callCount: number;
+}
+export interface TraceListFilters {
+    sessionId?: string;
+    workerPid?: number;
+    /** Filter by trace status. 'error' is the most common use for troubleshooting. */
+    status?: 'ok' | 'error' | 'cancelled' | 'running';
+}
+export interface TraceCollectorService {
+    onTraceStart(traceId: string, name: string, metadata?: Record<string, any>): Promise<void>;
+    onTraceEnd(traceId: string): Promise<void>;
+    onSpanStart(span: Partial<CollectedSpan> & {
+        traceId: string;
+        spanId: string;
+    }): Promise<void>;
+    onSpanEnd(spanId: string, updates?: {
+        error?: string;
+        toolInput?: string;
+        toolOutput?: string;
+        inputTokens?: number;
+        outputTokens?: number;
+        model?: string;
+    }): Promise<void>;
+    enrichTrace(sessionId: string, data: {
+        agentName?: string;
+        prompt?: string;
+        modelInfo?: TraceModelInfo;
+    }): Promise<void>;
+    enrichSpan(spanId: string, attributes: Record<string, any>): Promise<void>;
+    /** Persist the final footer after the STOP hook has completed enrichment. */
+    finalizeSession(sessionId: string): Promise<void>;
+    /**
+     * Record a synthetic cancelled function span on the active trace for `sessionId`.
+     * Used by paths that reject a tool call before SDK execution begins (permission
+     * rejection, AskUserQuestion / ExitPlanMode cancel), which would otherwise leave
+     * no span in the trace.
+     *
+     * Returns the synthetic span id, or undefined when no trace is active.
+     */
+    recordCancelledToolSpan(sessionId: string, opts: {
+        toolName: string;
+        callId?: string;
+        toolInput?: unknown;
+        errorMessage?: string;
+        reason?: 'user_rejected' | 'permission_denied' | 'plan_rejected' | 'ask_cancelled';
+    }): string | undefined;
+    /**
+     * Force-end and persist the running trace bound to `sessionId` (if any) to
+     * disk synchronously. Used by abort paths (user reject, ESC cancel, SIGINT)
+     * where the SDK would otherwise abandon the trace in memory: `onTraceEnd`
+     * is never called → `persistTrace` never runs → the trace (including any
+     * cancelled spans recorded just before) is lost when the process exits.
+     *
+     * If `cancelledTool` is provided, a synthetic cancelled function span is
+     * injected before the persist. When NO running trace is bound to the
+     * session AND `cancelledTool` is provided, the most recent disk trace is
+     * located and patched in place — handles the dominant real-world case
+     * where the SDK has already ended the trace (finish_reason=tool_calls)
+     * before the user clicks reject.
+     *
+     * Resolves once the trace file is written. Returns the number of traces
+     * actually flushed (0 if nothing applicable was found).
+     */
+    flushSession(sessionId: string, opts?: {
+        /**
+         * Cancellation source. Forwarded to the synthetic cancelled span as
+         * `attributes.cancel_reason`, so the trace UI can group / filter
+         * by source. The four `*_rejected|denied|cancelled` values are the
+         * concrete tool-call rejection sources; `aborted` / `shutdown` are
+         * generic abort paths used when no specific tool reject is known.
+         */
+        reason?: 'user_rejected' | 'permission_denied' | 'plan_rejected' | 'ask_cancelled' | 'aborted' | 'shutdown';
+        cancelledTool?: {
+            toolName: string;
+            callId?: string;
+            toolInput?: unknown;
+            errorMessage?: string;
+        };
+    }): Promise<number>;
+    listTraces(offset?: number, limit?: number, filters?: TraceListFilters): Promise<TraceListResponse>;
+    getTraceDetail(traceId: string): Promise<TraceDetail | null>;
+    /** Wait for lifecycle/footer writes already accepted by the collector. */
+    flushPendingWrites(): Promise<void>;
+    clear(): Promise<void>;
+}

package/cli/dist-server/types/node/utils/installation-utils.d.ts

@@ -0,0 +1,35 @@
+import { FileSystem } from '../../workspace/runtime/lib/common/index.js';
+export type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'dnf' | 'homebrew' | 'unknown';
+export type InstallMethod = {
+    type: 'package-manager';
+    packageManager: PackageManager;
+} | {
+    type: 'native';
+} | {
+    type: 'unknown';
+};
+export interface Installation {
+    version: string;
+    tag: 'latest' | 'beta' | 'next';
+    method: InstallMethod;
+    path: string;
+    invoked: string;
+}
+export declare abstract class InstallationUtils {
+    static getCurrentInstallation(binary: string, mfs?: FileSystem, findCmd?: (cmd: string) => Promise<string | undefined>): Promise<Installation>;
+    /**
+     * Check if a path is in the native installation directory
+     * - Windows: %LOCALAPPDATA%
+     * - Linux/macOS: ~/.local/
+     */
+    private static isNativeInstallPath;
+    private static detectPackageManager;
+    /**
+     * Infer the package manager from an install path when command-line
+     * detection fails (issue #61217). A path living under a
+     * `node_modules` layout is a package-manager install; we distinguish the
+     * manager by well-known global store markers, defaulting to npm (which
+     * covers the common `/usr/local/lib/node_modules` and nvm layouts).
+     */
+    private static detectPackageManagerFromPath;
+}

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

@@ -0,0 +1,209 @@
+import { TerminalType } from './terminal-detector-utils';
+/**
+ * OSC 通知协议接口
+ */
+export interface OscNotificationProtocol {
+    name: string;
+    supportedTerminals: TerminalType[];
+    priority: number;
+    generate(message: string, title?: string): string;
+}
+/**
+ * OSC 进度协议接口
+ */
+export interface OscProgressProtocol {
+    name: string;
+    supportedTerminals: TerminalType[];
+    priority: number;
+    generate(state: ProgressState, percentage: number): string;
+}
+/**
+ * 进度状态枚举
+ * 用于 OSC 9;4 进度协议
+ */
+export declare enum ProgressState {
+    CLEAR = 0,// 清除进度
+    NORMAL = 1,// 正常进度
+    ERROR = 2,// 错误状态
+    INDETERMINATE = 3,// 不确定进度
+    PAUSED = 4
+}
+/**
+ * OSC 协议工具类
+ * 提供各种 OSC (Operating System Command) 序列的生成和管理
+ */
+export declare abstract class OscProtocolUtils {
+    private static readonly ESC;
+    private static readonly BEL;
+    private static readonly ST;
+    private static readonly DCS;
+    /**
+     * 生成 OSC 777 通知序列 (推荐，广泛支持)
+     * 格式: ESC ] 777 ; notify ; title ; message BEL
+     *
+     * 支持终端: Ghostty, iTerm2, Windows Terminal, VSCode, Cursor, Windsurf,
+     *           Foot, Contour, urxvt, Blink Shell, libvte-based
+     *
+     * @param title 通知标题
+     * @param message 通知消息
+     * @returns OSC 777 序列
+     */
+    static generateOSC777(title: string, message: string): string;
+    /**
+     * 生成 OSC 9 通知序列 (兼容性好)
+     * 格式: ESC ] 9 ; message BEL
+     *
+     * 支持终端: iTerm2, Kitty, Ghostty, Foot, libvte-based
+     *
+     * 注意: 与 ConEmu 的 OSC 9;4 进度报告有冲突
+     *
+     * @param message 通知消息
+     * @returns OSC 9 序列
+     */
+    static generateOSC9(message: string): string;
+    /**
+     * 生成 OSC 99 通知序列 (Kitty 专有)
+     * 格式: ESC ] 99 ; [metadata] ; payload ST
+     *
+     * 支持终端: Kitty (v0.36.0+)
+     *
+     * 特性:
+     * - 支持通知更新 (通过相同的通知 ID)
+     * - 支持通知关闭事件回调
+     * - 适合进度报告
+     *
+     * @param message 通知消息
+     * @param id 可选的通知 ID，用于更新同一通知
+     * @returns OSC 99 序列
+     */
+    static generateOSC99(message: string, id?: string): string;
+    /**
+     * 生成 BEL 字符 (通用 fallback)
+     * 最基础的终端响铃，所有终端都支持
+     *
+     * @returns BEL 字符
+     */
+    static generateBEL(): string;
+    /**
+     * 生成 OSC 9;4 进度序列
+     * 格式: ESC ] 9 ; 4 ; state ; percentage BEL
+     *
+     * 支持终端: Windows Terminal (v1.6+), iTerm2 (v3.6.6+), Ghostty
+     *
+     * @param state 进度状态
+     * @param percentage 进度百分比 (0-100)
+     * @returns OSC 9;4 序列
+     */
+    static generateProgressOSC9_4(state: ProgressState, percentage?: number): string;
+    /**
+     * 生成 OSC 99 进度更新序列 (Kitty)
+     * 使用相同 ID 更新通知来实现进度显示
+     *
+     * @param message 进度消息
+     * @param id 通知 ID
+     * @returns OSC 99 序列
+     */
+    static generateProgressOSC99Kitty(message: string, id: string): string;
+    /**
+     * 通知协议优先级列表
+     * 按优先级从高到低排序
+     */
+    private static readonly NOTIFICATION_PROTOCOLS;
+    /**
+     * 根据终端类型选择最佳通知协议
+     *
+     * 选择策略:
+     * 1. 找到支持当前终端的协议
+     * 2. 按优先级排序
+     * 3. 返回最高优先级的协议
+     * 4. 如果没有匹配，返回 BEL fallback
+     *
+     * @param terminalType 终端类型
+     * @returns 最佳匹配的协议
+     */
+    static selectNotificationProtocol(terminalType: TerminalType): OscNotificationProtocol;
+    /**
+     * 检测是否需要 tmux 包装
+     *
+     * @returns 是否在 tmux 中运行
+     */
+    static needsTmuxWrapping(): boolean;
+    /**
+     * 为 tmux 环境包装 OSC 序列
+     *
+     * tmux 会拦截 OSC 序列，需要使用 DCS tmux 透传协议
+     * 格式: DCS tmux ; <escaped-sequence> ST
+     *
+     * 注意: ESC 字符需要双写以进行转义
+     *
+     * @param oscSequence 原始 OSC 序列
+     * @returns tmux 包装后的序列
+     */
+    static wrapForTmux(oscSequence: string): string;
+    static writeToTerminal(sequence: string): void;
+    /**
+     * 进度协议优先级列表
+     * 按优先级从高到低排序
+     */
+    private static readonly PROGRESS_PROTOCOLS;
+    /**
+     * 根据终端类型选择最佳进度协议
+     *
+     * @param terminalType 终端类型
+     * @returns 最佳匹配的进度协议，如果不支持则返回 null
+     */
+    static selectProgressProtocol(terminalType: TerminalType): OscProgressProtocol | null;
+    /**
+     * 生成进度 OSC 序列（自动选择协议）
+     *
+     * @param terminalType 终端类型
+     * @param state 进度状态
+     * @param percentage 进度百分比 (0-100)
+     * @returns OSC 序列，如果终端不支持则返回 null
+     */
+    static generateProgress(terminalType: TerminalType, state: ProgressState, percentage?: number): string | null;
+    static supportsProgressProtocol(terminalType: TerminalType): boolean;
+    /**
+     * 生成 OSC 52 剪贴板序列
+     * 格式: ESC ] 52 ; c ; <base64-data> BEL
+     *
+     * OSC 52 是一种终端转义序列，允许程序设置或获取系统剪贴板内容。
+     * 它特别适用于 SSH 远程会话，因为数据通过终端转义序列传递到本地终端，
+     * 从而绕过了远程系统无法直接访问本地剪贴板的限制。
+     *
+     * 支持终端: iTerm2, Ghostty, Kitty, Alacritty, WezTerm, Windows Terminal,
+     *           VSCode 集成终端, Cursor, Windsurf, GNOME Terminal, Konsole, XTerm 等
+     *
+     * @param text 要复制到剪贴板的文本
+     * @returns OSC 52 序列
+     */
+    static generateOSC52(text: string): string;
+    /**
+     * 生成带 tmux 包装的 OSC 52 序列
+     * 在 tmux 环境中，需要使用 DCS 透传协议
+     *
+     * @param text 要复制到剪贴板的文本
+     * @returns 适当包装的 OSC 52 序列
+     */
+    static generateOSC52WithTmuxSupport(text: string): string;
+    /**
+     * 检查当前终端是否支持 OSC 52 协议
+     *
+     * @returns 是否支持 OSC 52
+     */
+    static supportsOSC52(): boolean;
+    /**
+     * 检测是否在 SSH 会话中
+     *
+     * @returns 是否在 SSH 会话中
+     */
+    static isSSHSession(): boolean;
+    /**
+     * 通过 OSC 52 协议复制文本到剪贴板
+     * 适用于 SSH 远程环境和支持 OSC 52 的本地终端
+     *
+     * @param text 要复制的文本
+     * @returns 是否成功写入（注意：这只表示序列已发送，不保证终端支持）
+     */
+    static copyToClipboardViaOSC52(text: string): boolean;
+}

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

@@ -0,0 +1,40 @@
+export declare const PROCESS_IDENTITY_MATCH_TOLERANCE_MS = 2000;
+export declare const PROCESS_IDENTITY_QUERY_TIMEOUT_MS = 5000;
+export interface ProcessIdentity {
+    procStart?: string;
+    procStartFt?: string;
+    /** Linux /proc/<pid>/stat field 22, stable for one PID generation. */
+    procStartTicks?: string;
+}
+export declare function unixMsToWindowsFileTime(unixMs: number): string;
+export declare function windowsFileTimeToUnixMs(fileTime: string | undefined): number | undefined;
+export declare function getProcessIdentityStartMs(identity: ProcessIdentity): number | undefined;
+export declare function parseLinuxProcStatStartTicks(raw: string): string | undefined;
+export interface LinuxClockInfo {
+    bootTimeMs: number;
+    ticksPerSecond: number;
+}
+export declare function parseLinuxBootTimeMs(raw: string): number | undefined;
+export declare function parseLinuxAuxvClockTicks(raw: Buffer, wordSize?: number, byteOrder?: 'LE' | 'BE'): number | undefined;
+export declare function getCurrentProcessIdentity(platform?: NodeJS.Platform): ProcessIdentity;
+export declare function queryLinuxProcessStartIdentity(pid: number, readStat?: (path: string) => Promise<string>, getClockInfo?: () => Promise<LinuxClockInfo | undefined>): Promise<ProcessIdentity | undefined>;
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Parse `ps -o etime=` output (`[[dd-]hh:]mm:ss`) into elapsed milliseconds.
+ * Returns undefined when the token is missing or malformed.
+ */
+export declare function parsePsEtimeToMs(raw: string): number | undefined;
+export declare function queryProcessStartIdentity(pid: number, platform?: NodeJS.Platform): Promise<ProcessIdentity | undefined>;
+export declare function compareProcessIdentities(expected: ProcessIdentity, actual: ProcessIdentity): 'same' | 'different' | 'unknown';
+export declare function readProcessIdentity(value: Partial<ProcessIdentity> | Record<string, unknown> | null | undefined): ProcessIdentity;
+export declare function hasProcessIdentity(identity: ProcessIdentity | undefined): boolean;
+/**
+ * True when pid is alive AND (no expected identity / query unknown / identities match).
+ * Identity mismatch means the PID was reused — treat as dead.
+ */
+export declare function isMatchingProcessAlive(pid: number, expected: ProcessIdentity | undefined, options?: {
+    isAlive?: (pid: number) => boolean;
+    queryIdentity?: (pid: number) => Promise<ProcessIdentity | undefined>;
+    currentIdentity?: () => ProcessIdentity;
+    platform?: NodeJS.Platform;
+}): Promise<boolean>;

package/cli/dist-server/types/node/utils/security-audit-log.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 安全审计日志 — agent-cli 层入口
+ *
+ * agent-cli 将运行时安全事件 append 到 `<HomeDir>/audit-log/spool/*.jsonl`；
+ * Desktop Host 在安全中心读取前导入 spool，并补齐正式链上的
+ * sequence/prevHash/hash。
+ *
+ * `<HomeDir>` 由 {@link resolveCliHomeDir} 解析：
+ *   定制版 `dataLayout.configDir.userDirName` → `CODEBUDDY_CONFIG_DIR` 环境变量（非空时）→ `~/.codebuddy`。
+ * Desktop 在 spawn sidecar 时已显式注入 `CODEBUDDY_CONFIG_DIR=<workbuddy
+ * config dir>`，所以 Desktop 端 spool 仍落在 `~/.workbuddy/audit-log/`，
+ * 与正式链根目录一致；独立 codebuddy-code CLI 用户则落在 `~/.codebuddy/
+ * audit-log/`，与 CLI 其他状态目录约定一致。
+ *
+ * 写入受 `CODEBUDDY_ENABLE_SECURITY_AUDIT` 环境变量控制：
+ *   - WorkBuddy Desktop spawn sidecar 时显式设为 `'1'`，spool 持续写入；
+ *     Desktop main 进程定期 drain 到正式审计链。
+ *   - 独立 codebuddy-code CLI 用户未显式设置时，所有 append* 函数 no-op，
+ *     避免给没有审计 UI / drain 链路的环境留下持续增长的 spool 文件。
+ */
+export declare function createCommandPreview(command: string): string;
+export interface SecurityAuditContext {
+    sessionId?: string;
+    requestId?: string;
+    toolCallId?: string;
+}
+export interface SecurityAuditEntry extends SecurityAuditContext {
+    /** 写入 spool 时生成，导入端据此识别已入库的行。 */
+    id?: string;
+    category?: string;
+    eventType?: string;
+    /** i18n key，对齐 `securityCenter.audit.*`。 */
+    messageKey?: string;
+    /** i18n 插值参数，对应 messageKey 模板中的 `{name}`。 */
+    messageParams?: Record<string, string | number>;
+    timestamp?: number;
+    decision?: 'approved' | 'rejected' | 'blocked' | 'allowed' | 'failed' | 'info';
+    commandPreview?: string;
+    commandHash?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function appendToolControlBlockedAuditLog(detail: {
+    toolId: string;
+    toolName: string;
+    serverId?: string;
+    reason: 'tool_disabled' | 'mcp_server_disabled' | 'mcp_tool_disabled' | 'custom_mcp_disabled';
+} & SecurityAuditContext): void;
+export type CommandSafetyAction = 'ask-matched' | 'allow-matched' | 'deny-matched' | 'excluded-command' | 'exec-policy-allow' | 'exec-policy-forbidden' | 'bypass-legacy-silent' | 'session-cache-hit' | 'sensitive-session-cache-hit' | 'pre-exec-bypass-requested' | 'pre-exec-bypass-approved' | 'pre-exec-bypass-rejected' | 'bypass-blocked-by-policy' | 'allow-overridden-by-credential' | 'allow-overridden-by-opaque-host' | 'credential-or-opaque-blocked' | 'safety-filter-ask-override' | 'safety-filter-allow-override' | 'auto-approved' | 'auto-rejected' | 'sandbox-executed' | 'program-blacklist-blocked'
+/**
+ * 网络严格模式的系统层兜底拦截（genie/genie#122764）。
+ *
+ * 与 `program-blacklist-blocked` 同型：都是「不可通过审批或 native 重跑修复」
+ * 的硬拦截，必须自带独立动作。**不能复用 `sandbox-executed`**——那个的
+ * decision 是 `allowed`、文案是「沙箱内执行命令」，与同时落下的
+ * `network-strict.blocked`（blocked）在同一条命令上自相矛盾，安全中心按
+ * 命令安全筛选时会把已拦截的命令误判为放行。
+ */
+ | 'network-strict-blocked' | 'approved' | 'rejected' | 'system-tool-blocked' | 'system-tool-confirm-approved' | 'system-tool-confirm-rejected' | 'system-tool-auto-executed' | 'system-tool-session-cache-hit';
+export type FileSafetyAction = 'block-listed' | 'deny-matched' | 'allow-listed' | 'ask-matched' | 'session-cache-hit' | 'auto-approved' | 'auto-rejected' | 'needs-approval' | 'approved' | 'rejected';
+export type BulkDeleteAuditAction = 'needs-approval' | 'approved' | 'rejected';
+export type SensitiveProtectionAuditAction = 'detected' | 'approval-resolved' | 'approval-timeout' | 'protection-applied' | 'original-reused' | 'protection-reused' | 'failure';
+export interface SensitiveProtectionAuditDetail extends SecurityAuditContext {
+    behavior?: 'fail-open' | 'fail-close';
+    choice?: 'allow-original' | 'allow-and-protect' | 'allow-execution' | 'deny';
+    detectionRef?: string;
+    direction?: 'ingress' | 'egress';
+    entryCount?: number;
+    itemCount?: number;
+    plaintexts?: readonly string[];
+    reasonCode?: string;
+    ruleCount?: number;
+    source?: string;
+    stage?: 'detection' | 'approval' | 'protection';
+}
+interface SecurityAuditLog {
+    entries: SecurityAuditEntry[];
+}
+export interface SandboxBlockAuditLogEvent extends SecurityAuditContext {
+    blockType: 'network';
+    target: string;
+    /** 是否命中恶意网站库。安全中心据此使用面向用户的网络安全文案。 */
+    malicious?: boolean;
+    /** 面向用户的风险类型，例如“黑灰产 / 钓鱼网站”；不包含 DB 等实现信息。 */
+    riskType?: string;
+    /**
+     * 本次拦截是否来自**网络严格模式**的系统层兜底（genie/genie#122764）。
+     *
+     * 与 `malicious` 正交：恶意命中是「域名在黑名单里」，严格模式是「程序绕过了代理，
+     * 被系统层直接拒绝」——后者与具体域名/规则无关。安全中心据此用「严格模式」文案
+     * 而非「域名被拦」文案，让用户看到真实成因，不去找一条并不存在的规则。
+     */
+    networkStrict?: boolean;
+}
+export type NetworkAccessAuditOutcome = 'success' | 'allow-matched' | 'ask-matched' | 'approved' | 'auto-approved' | 'auto-rejected' | 'session-cache-hit' | 'blocked' | 'rejected' | 'failed';
+export declare function appendSecurityAuditEntry(entry: SecurityAuditEntry): void;
+export declare function appendCommandSafetyAuditLog(action: CommandSafetyAction, detail: {
+    command?: string;
+    matchedRule?: string;
+    reason?: string;
+    programs?: string;
+} & SecurityAuditContext): void;
+/**
+ * 文件操作类型，用于审计日志按 DELETE/WRITE/READ 分文案。
+ *
+ * 来源：sandbox 上报的 `actionMask` 位掩码（READ=0x01 / WRITE=0x02 /
+ * DELETE=0x04 / EXECUTE=0x08）。优先级：DELETE > WRITE > READ；其它情况
+ * （仅 EXECUTE 或 0）回退到 `access`，沿用旧文案。
+ */
+export type FileSafetyOperation = 'read' | 'write' | 'delete' | 'access';
+export declare function fileSafetyOperationFromActionMask(actionMask: number | undefined): FileSafetyOperation;
+export declare function appendFileSafetyAuditLog(action: FileSafetyAction, detail: {
+    paths: string[];
+    matchedRule?: string;
+    operation?: FileSafetyOperation;
+} & SecurityAuditContext): void;
+export declare function appendBulkDeleteAuditLog(action: BulkDeleteAuditAction, detail: {
+    command?: string;
+    count?: number;
+    threshold?: number;
+    targets?: string[];
+} & SecurityAuditContext): void;
+export declare function appendSensitiveProtectionAuditLog(action: SensitiveProtectionAuditAction, detail: SensitiveProtectionAuditDetail): void;
+export declare function appendNetworkAccessAuditLog(target: string, outcome: boolean | NetworkAccessAuditOutcome, detail?: {
+    reason?: string;
+    matchedRule?: string;
+    malicious?: boolean;
+    riskType?: string;
+} & SecurityAuditContext): void;
+export declare function appendSandboxBlockAuditLog(event: SandboxBlockAuditLogEvent): void;
+/**
+ * 测试辅助：直接读取当前磁盘上的审计日志快照。生产代码不应使用。
+ */
+export declare function readSecurityAuditLogForTest(): SecurityAuditLog;
+export {};