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

package/cli/dist-server/types/node/galileo/galileo-session-bridge-protocol.d.ts

@@ -0,0 +1,134 @@
+/**
+ * GalileoSessionBridge 协议半边（token + 契约类型）。
+ *
+ * 从实现文件分离（step-3 galileo exit 归位）：session-manager/tool-hook-manager
+ * 等图内消费方引本文件——实现文件不再被图内深引，galileo 桶可整体出闭包。
+ */
+export declare const GalileoSessionBridge: unique symbol;
+/**
+ * 会话遥测快照 —— 来自 session.telemetry，必须在 reportChatRequestResponseTelemetry **之前**抓取
+ * （那个方法末尾会清空 session.telemetry，之后取值会全部 undefined）。
+ */
+export interface SessionTelemetrySnapshot {
+    modelId?: string;
+    modelName?: string;
+    currentTurn?: number;
+    traceId?: string;
+}
+/** Session 的最小契约（只取 bridge 需要的字段，避免引入 session-protocol 的循环依赖） */
+export interface SessionLike {
+    id: string;
+    conversationRequestId?: string;
+    /** Renderer 透传的全链路业务关联 ID（仅 desktop 入口有；裸 CLI / IDE 为 undefined） */
+    promptRequestId?: string;
+    messageId?: string;
+    traceId?: string;
+    agentName?: string;
+    agentPurpose?: string;
+    meta?: Record<string, unknown>;
+    telemetry?: {
+        modelId?: string;
+        modelName?: string;
+        traceId?: string;
+        currentTurn?: number;
+    };
+    conversationRequestRootSpan?: {
+        addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    };
+    _toolSpans?: Map<string, {
+        addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    }>;
+}
+/** 模型响应元信息（由 session-manager 持有，传入 bridge 用于补充 finishReason） */
+export interface ModelResponseLike {
+    finishReason?: string;
+}
+export interface GalileoSessionBridge {
+    /** LLM request 已发出、开始处理响应时调用 → reporter.reportRequestStart */
+    emitRequestStart(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined): void;
+    /** Task 级成功 → reporter.reportRequestSuccess */
+    emitRequestSuccess(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, modelResponse?: ModelResponseLike): void;
+    /** Task 级失败 → reporter.reportRequestError */
+    emitRequestError(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown, modelResponse?: ModelResponseLike): void;
+    /** Message 级失败 → reporter.reportMessageError */
+    emitMessageError(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown): void;
+    /**
+     * Message 级成功 → reporter.reportMessageSuccess
+     *
+     * 与 emitRequestSuccess 不同：message 级成功上报点位于 stream 处理过程中，
+     * 此时 session.telemetry 尚未被清理，可以直接读取，因此不强制要求传 snapshot。
+     */
+    emitMessageSuccess(session: SessionLike): void;
+    /**
+     * Message 级开始 → reporter.reportMessageStart
+     *
+     * 触发时机：LLM request 已发出、开始处理响应流之前。
+     * 由 session-manager 在 resultSubject 收到结果后尽早调用，不等待首个 chunk。
+     */
+    emitMessageStart(session: SessionLike): void;
+    /** Tool 调用开始（PreToolUse） → reporter.reportToolStart */
+    emitToolStart(session: SessionLike, params: ToolEmitParams): void;
+    /** Tool 调用成功（PostToolUse 且 response 非 error） → reporter.reportToolSuccess */
+    emitToolSuccess(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+    }): void;
+    /**
+     * Skill 工具调用业务粒度日志 → `wb.skill.execute`。
+     * 关联键复用 buildToolBaseEventFields（与 agent.tool.*_detail 同源），再追加
+     * skill_name / outcome / duration_ms，使单次 skill 调用可归属到具体会话。
+     */
+    emitSkillExecute(session: SessionLike, params: {
+        skillName: string;
+        outcome: 'success' | 'failed';
+        durationMs: number;
+        callId: string;
+    }): void;
+    /**
+     * Tool 调用失败 → reporter.reportToolError。
+     * 失败来源 errorSource：'thrown'（PostToolUseFailure）/ 'response_flag'（PostToolUse + is_error）。
+     */
+    emitToolError(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+        errorType: string;
+        errorMessage: string;
+        errorSource: 'thrown' | 'response_flag';
+    }): void;
+    /** 把 Galileo detail 事件同步写入当前 @genie/telemetry span，便于 Trace 后台同屏查看。 */
+    addRequestSuccessSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, modelResponse?: ModelResponseLike): void;
+    addRequestErrorSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown, modelResponse?: ModelResponseLike): void;
+    addMessageSuccessSpanEvent(session: SessionLike): void;
+    addMessageErrorSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown): void;
+    addToolStartSpanEvent(session: SessionLike, params: ToolEmitParams): void;
+    addToolSuccessSpanEvent(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+    }): void;
+    addToolErrorSpanEvent(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+        errorType: string;
+        errorMessage: string;
+        errorSource: 'thrown' | 'response_flag';
+    }): void;
+}
+/** Tool emit 共享参数（hook 已知字段） */
+export interface ToolEmitParams {
+    toolName: string;
+    callId: string;
+    /** 仅 toolName === 'Skill' 时有意义：具体 skill 名，用于 capability_id 下钻 */
+    skillId?: string;
+    /**
+     * connector 真实 serverShortName（来自 PostToolUse 时 tool_response._meta['workbuddy.ai/connectorServer']）。
+     * 提供时把 connector capability_id 从占位 connector-proxy 升级为真实 id。
+     */
+    connectorServer?: string;
+    /**
+     * 当 toolName === 'DeferExecuteTool' 时，实际被代理的目标工具名。
+     * 从 tool_input.toolName 提取，用于 Galileo 下钻区分 DeferExecuteTool 调了哪个真实工具。
+     */
+    targetToolName?: string;
+    /** 稳定错误码（纯数字字符串，如 '1001'），值来自 ToolErrorCode 枚举 */
+    toolErrorCode?: string;
+    /** 稳定错误名（如 'ReadFileNotFoundError'） */
+    toolErrorName?: string;
+    /** 可读错误原因（如 '文件不存在'） */
+    errorReason?: string;
+}

package/cli/dist-server/types/node/galileo/galileo-session-bridge.d.ts

@@ -0,0 +1,105 @@
+/**
+ * GalileoSessionBridge — Session ↔ GalileoChatReporter 桥接层
+ *
+ * 职责：把 session-manager 中"从 Session/error 提取字段 → 构造 reporter Context → 调用 reporter →
+ * try/catch 兜住异常"的样板代码集中维护，让 session-manager 的业务流程保持清爽。
+ *
+ * 设计原则：
+ * - 只承接「字段构造 + try/catch 守护」，**不承接 trigger 判断**（isSuccessful 分支等）—— 调用时机仍由
+ *   session-manager 决定，确保架构上 session 状态机的可读性
+ * - 不持有任何 session 状态：每次方法调用都接收完整上下文（session + telemetrySnapshot + error 等）
+ * - 所有异常都被 try/catch 吞下，仅 logger.warn 一行，**绝不向上抛**：伽利略上报失败不能影响业务流程
+ * - 与 P2-5 时机约束兼容：调用方仍负责在 telemetry 被清理之前快照 session.telemetry，并把快照传进来
+ */
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { GalileoSessionBridge, type ModelResponseLike, type SessionLike, type SessionTelemetrySnapshot, type ToolEmitParams } from './galileo-session-bridge-protocol';
+export declare class GalileoSessionBridgeImpl implements GalileoSessionBridge {
+    private readonly reporter;
+    protected readonly logger: Logger;
+    protected readonly auth: AuthenticationManager;
+    private readonly galileo;
+    private readonly mcpPluginRegistry;
+    emitRequestStart(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined): void;
+    emitRequestSuccess(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, modelResponse?: ModelResponseLike): void;
+    emitRequestError(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown, modelResponse?: ModelResponseLike): void;
+    emitMessageError(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown): void;
+    emitMessageSuccess(session: SessionLike): void;
+    emitMessageStart(session: SessionLike): void;
+    emitToolStart(session: SessionLike, params: ToolEmitParams): void;
+    emitToolSuccess(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+    }): void;
+    emitSkillExecute(session: SessionLike, params: {
+        skillName: string;
+        outcome: 'success' | 'failed';
+        durationMs: number;
+        callId: string;
+    }): void;
+    emitToolError(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+        errorType: string;
+        errorMessage: string;
+        errorSource: 'thrown' | 'response_flag';
+    }): void;
+    /**
+     * session.messageId 为空时的降级拼接，保证 conversation_message_id 非空可下钻。
+     * 格式：{conversation_request_id}_{tool_name}_{call_id}
+     */
+    private buildFallbackMessageId;
+    addRequestSuccessSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, modelResponse?: ModelResponseLike): void;
+    addRequestErrorSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown, modelResponse?: ModelResponseLike): void;
+    addMessageSuccessSpanEvent(session: SessionLike): void;
+    addMessageErrorSpanEvent(session: SessionLike, snapshot: SessionTelemetrySnapshot | undefined, error: unknown): void;
+    addToolStartSpanEvent(session: SessionLike, params: ToolEmitParams): void;
+    addToolSuccessSpanEvent(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+    }): void;
+    addToolErrorSpanEvent(session: SessionLike, params: ToolEmitParams & {
+        durationMs: number;
+        errorType: string;
+        errorMessage: string;
+        errorSource: 'thrown' | 'response_flag';
+    }): void;
+    /**
+     * 从 session + tool params 构造 ToolStartContext 共享字段（关联 ID + 上下文维度）。
+     * 内部复用，不导出。
+     */
+    private buildToolBaseContext;
+    private buildRequestSuccessEventFields;
+    private buildRequestErrorEventFields;
+    private buildMessageErrorEventFields;
+    private buildToolBaseEventFields;
+    /** 推导工具的能力归属（capability_type + capability_id），plugin 判定走注入的 registry。 */
+    private resolveCapability;
+    private addRootSpanEvent;
+    private addToolSpanEvent;
+    private cleanSpanEventAttributes;
+    /**
+     * 提取用户 uid。
+     * 优先 `session.meta['codebuddy.ai/userId']`（Renderer 透传，desktop 场景必需，
+     * 因为 CLI 是子进程没本地登录态）；缺失时回落到 CLI 本地 `AuthenticationManager`
+     * （裸 cli / IDE 插件场景）。两者都没有则返回 ''。
+     */
+    private extractUid;
+    /** 从 session.meta['codebuddy.ai/mode'] 取场景标识；缺失返回 '' */
+    private extractScene;
+    /**
+     * 取 expert 会话标识（Renderer 召唤 expert 后经 ACP _meta 透传，
+     * 由 applyUpstreamMeta 写入 session.meta['codebuddy.ai/expertId']）。
+     * 非 expert 会话 / 裸 CLI 返回 ''，不影响其它归因。
+     */
+    private extractExpertId;
+    /** 优先取 session.agentName，再 fallback 到 session.meta.agentName */
+    private extractAgentName;
+    /** Role of the Session's agent loop, for request-level events. */
+    private extractAgentType;
+    /** Role of the call in the current async chain (X-Agent-Type), for tool events. */
+    private extractCallAgentType;
+    /** 从 error.status / error.response.status 提取 HTTP 状态码 */
+    private extractHttpStatus;
+    /** 从 error.code 提取 Node.js errno（ECONNRESET 等） */
+    private extractNodeErrorCode;
+    /** 从嵌套 error 提取最具体的 message-level errorCode（保留旧 session-manager 逻辑） */
+    private extractMessageErrorCode;
+}

package/cli/dist-server/types/node/galileo/galileo-timing-hook.d.ts

@@ -0,0 +1,115 @@
+/**
+ * GalileoTimingHook — 模型级耗时打点
+ *
+ * 通过监听 session.modelSubject 上的事件，计算并上报：
+ *   - agent.ttfb: 首个有意义 token 延迟
+ *   - agent.model.streaming: 模型流式输出耗时（首 token → 流结束）
+ *   - agent.task_total: 端到端耗时（sendTime → prompt 完成）
+ *
+ * 此 hook 不修改 model-provider.ts，而是通过 session 上的 observable 被动监听。
+ * 如需更精确的计时（如 prompt build），需要在 model-provider 中直接插入打点。
+ */
+export declare class GalileoTimingHook {
+    private readonly galileo;
+    private readonly aggregator;
+    private readonly sessionErrorTracker;
+    /**
+     * 上报 TTFB（首 token 延迟）。
+     * 调用时机：model-provider.ts 中 firstMeaningfulTokenReceived 后。
+     */
+    reportTTFB(ttfbMs: number, dimensions?: {
+        model?: string;
+        requestId?: string;
+        agentName?: string;
+        conversationRequestId?: string;
+        messageId?: string;
+        promptRequestId?: string;
+    }): void;
+    /**
+     * 上报 message 维度用户视角 TTFT（用户点击发送 → 本轮首个 meaningful token）。
+     * 起点为 renderer 透传的 clientSendTime，含 IPC 传输 + prompt build 全链路开销。
+     * 每条用户消息上报 1 次（由 messageTtfbReported flag 控制）。
+     */
+    reportMessageTTFBUser(ttfbMs: number, dimensions?: {
+        messageId?: string;
+        promptRequestId?: string;
+        conversationRequestId?: string;
+        model?: string;
+        agentName?: string;
+        scene?: string;
+    }): void;
+    /**
+     * 上报 message 维度模型视角 TTFT（CLI 进入 prompt → 本轮首个 meaningful token）。
+     * 起点为 promptStartTime，含 prompt build 但不含跨进程 IPC。
+     * 每条用户消息上报 1 次（由 messageTtfbReported flag 控制）。
+     */
+    reportMessageTTFBModel(ttfbMs: number, dimensions?: {
+        messageId?: string;
+        promptRequestId?: string;
+        conversationRequestId?: string;
+        model?: string;
+        agentName?: string;
+        scene?: string;
+    }): void;
+    /**
+     * 上报模型流式生成耗时（首 token → 流结束）。
+     * 调用时机：model-provider.ts stream completed 后。
+     */
+    reportModelStreaming(streamingMs: number, dimensions?: {
+        model?: string;
+        agentName?: string;
+        conversationRequestId?: string;
+    }): void;
+    /**
+     * 上报 Task 端到端耗时。
+     * 调用时机：ACP prompt 完成时，从 _meta['codebuddy.ai/sendTime'] 计算。
+     */
+    reportTaskTotal(taskTotalMs: number, dimensions?: {
+        taskId?: string;
+        modelCalls?: number;
+        toolCalls?: number;
+        model?: string;
+        agentName?: string;
+        agentPurpose?: string;
+    }): void;
+    /**
+     * 上报 Prompt Build 耗时（组装 prompt → 发出 HTTP 请求之间的时间）。
+     * 调用时机：model-provider.ts 中 HTTP 请求发出前。
+     */
+    reportPromptBuild(promptBuildMs: number, dimensions?: {
+        model?: string;
+        agentName?: string;
+    }): void;
+    /**
+     * 上报 Tool 等用户确认耗时。
+     * 调用时机：permission 确认/拒绝后。
+     */
+    reportToolUserWait(waitMs: number, dimensions?: {
+        toolName?: string;
+        permissionType?: string;
+        model?: string;
+    }): void;
+    /**
+     * 上报上下文压缩耗时。
+     * 调用时机：compact 操作完成后。
+     */
+    reportContextCompact(compactMs: number, dimensions?: {
+        compactType?: string;
+        model?: string;
+    }): void;
+    /**
+     * 记录模型生成的 tool_calls 数量。
+     * 调用时机：model response 解析到 tool_calls 后。
+     */
+    reportToolCallsGenerated(count: number): void;
+    /**
+     * 上报模型请求结果到 aggregator。
+     * 调用时机：model response 完成或错误后。
+     */
+    reportRequestResult(statusCode: number, errorCode?: string, model?: string, msg?: string, conversationRequestId?: string, modelName?: string, sessionId?: string): void;
+    /**
+     * 记录单次 LLM call 的 token 消耗。
+     * 调用时机：model response 完成后（usage 数据可用时）。
+     */
+    reportTokenUsage(input: number, output: number, cached: number, model: string, conversationRequestId?: string, modelName?: string): void;
+}

package/cli/dist-server/types/node/galileo/galileo-tool-error-report-hook.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tool 失败两路 → Galileo Log（`agent.tool.error_detail`）
+ *
+ * - 路径①（PostToolUse + `is_error=true`）：tool 内部捕获错误转成"成功响应+错误标记"
+ *   → `error_source = response_flag`
+ * - 路径②（PostToolUseFailure）：tool 真正抛异常 → `error_source = thrown`
+ *
+ * 用户主动取消（`is_interrupt=true`）不上报，避免污染错误率（与 chat-reporter 对齐）。
+ */
+import { HookEvent, HookExecutionResult } from '../../vendor/cbc-shared/node/index.js';
+import { Hook, HookInput, HookPriority } from '../hooks/hook-protocol';
+/**
+ * 从 tool_response._meta 提取 connector 真实 serverShortName（connector-proxy 回传）。
+ * 用于把 connector capability_id 从占位 connector-proxy 升级为真实 id。
+ */
+export declare function extractConnectorServer(toolResponse: unknown): string | undefined;
+/** 路径①：PostToolUse + tool_response.is_error=true → error_source=response_flag */
+export declare class GalileoToolResponseErrorReportHook implements Hook {
+    readonly event = HookEvent.POST_TOOL_USE;
+    readonly priority = HookPriority.Low;
+    private readonly bridge;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}
+/** 路径②：PostToolUseFailure → error_source=thrown（用户取消除外） */
+export declare class GalileoToolThrownErrorReportHook implements Hook {
+    readonly event = HookEvent.POST_TOOL_USE_FAILURE;
+    readonly priority = HookPriority.Low;
+    private readonly bridge;
+    private readonly aggregator;
+    private readonly sessionErrorTracker;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

package/cli/dist-server/types/node/galileo/galileo-tool-post-hook.d.ts

@@ -0,0 +1,18 @@
+import { HookEvent, HookExecutionResult } from '../../vendor/cbc-shared/node/index.js';
+import { Hook, HookInput, HookPriority } from '../hooks/hook-protocol';
+/**
+ * Galileo Tool Post Hook
+ *
+ * Runs on PostToolUse to record tool execution duration and tool result.
+ *
+ * 与 trace 的 ToolExecutionPostHook 解耦：trace hook 负责 span，本 hook 负责 Galileo 打点。
+ */
+export declare class GalileoToolPostHook implements Hook {
+    readonly event = HookEvent.POST_TOOL_USE;
+    readonly priority = HookPriority.Low;
+    private readonly galileo;
+    private readonly aggregator;
+    private readonly sessionErrorTracker;
+    private readonly bridge;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

package/cli/dist-server/types/node/galileo/galileo-tool-pre-hook.d.ts

@@ -0,0 +1,16 @@
+import { HookEvent, HookExecutionResult } from '../../vendor/cbc-shared/node/index.js';
+import { Hook, HookInput, HookPriority } from '../hooks/hook-protocol';
+/**
+ * Galileo Tool Pre Hook
+ *
+ * Runs on PreToolUse to record tool start time for duration metrics,
+ * and count tool_calls generated for callback rate calculation.
+ *
+ * 与 trace 的 ToolExecutionPreHook 解耦：trace hook 负责 span，本 hook 负责 Galileo 打点。
+ */
+export declare class GalileoToolPreHook implements Hook {
+    readonly event = HookEvent.PRE_TOOL_USE;
+    readonly priority = HookPriority.Low;
+    private readonly aggregator;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

package/cli/dist-server/types/node/galileo/galileo-tool-start-report-hook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tool PreToolUse → Galileo Log（`agent.tool.start_detail`）
+ *
+ * 与 `galileo-tool-pre-hook` 区分：那条算 metrics（startTime / 计数），本 hook 走
+ * 详情视图（含 tool_name / agent_name / scene 等多维度，便于搜索与下钻）。
+ */
+import { HookEvent, HookExecutionResult } from '../../vendor/cbc-shared/node/index.js';
+import { Hook, HookInput, HookPriority } from '../hooks/hook-protocol';
+export declare class GalileoToolStartReportHook implements Hook {
+    readonly event = HookEvent.PRE_TOOL_USE;
+    readonly priority = HookPriority.Low;
+    private readonly bridge;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

package/cli/dist-server/types/node/galileo/galileo-tool-success-report-hook.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tool PostToolUse（非 error）→ Galileo Log（`agent.tool.success_detail`）
+ *
+ * `tool_response.is_error=true` 由 `GalileoToolErrorReportHook` 处理，两路严格互斥。
+ * 耗时取自 `session._toolStartTimes`（由 `GalileoToolPreHook` 写入），本 hook 只读不删。
+ */
+import { HookEvent, HookExecutionResult } from '../../vendor/cbc-shared/node/index.js';
+import { Hook, HookInput, HookPriority } from '../hooks/hook-protocol';
+export declare class GalileoToolSuccessReportHook implements Hook {
+    readonly event = HookEvent.POST_TOOL_USE;
+    readonly priority = HookPriority.Low;
+    private readonly bridge;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

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

@@ -0,0 +1,15 @@
+export * from './galileo-protocol';
+export * from './galileo-service';
+export * from './agent-metrics-aggregator';
+export * from './task-outcome';
+export * from './task-outcome-resolver';
+export * from './session-error-tracker';
+export * from './galileo-timing-hook';
+export * from './galileo-tool-pre-hook';
+export * from './galileo-tool-post-hook';
+export * from './galileo-tool-start-report-hook';
+export * from './galileo-tool-success-report-hook';
+export * from './galileo-tool-error-report-hook';
+export * from './error-category';
+export * from './galileo-chat-reporter';
+export * from './galileo-session-bridge';

package/cli/dist-server/types/node/galileo/session-error-tracker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SessionErrorTracker — per-prompt 轻量级错误追踪
+ *
+ * 独立模块，不修改任何已有逻辑。已有 hook 通过插桩调用本模块记录错误事件，
+ * prompt 结束时由 acp-agent 读取快照来精细判定 TaskOutcome。
+ *
+ * 生命周期：prompt() 入口 reset → hook 写入 → prompt() 出口 snapshot + cleanup
+ * 内存占用：每个活跃 session 约 32 bytes，cleanup 后释放。
+ */
+export declare const SessionErrorTracker: unique symbol;
+export interface ErrorSnapshot {
+    /** 本次 prompt 内模型请求失败次数 */
+    modelErrorCount: number;
+    /** 本次 prompt 内模型请求成功次数（在错误之后的成功视为"恢复"） */
+    modelSuccessAfterErrorCount: number;
+    /** 本次 prompt 内工具执行失败次数 */
+    toolErrorCount: number;
+}
+export interface SessionErrorTracker {
+    /** prompt 开始时重置计数器 */
+    reset(sessionId: string): void;
+    /** 记录一次模型请求失败 */
+    recordModelError(sessionId: string): void;
+    /** 记录一次模型请求成功 */
+    recordModelSuccess(sessionId: string): void;
+    /** 记录一次工具执行失败 */
+    recordToolError(sessionId: string): void;
+    /** 取当前快照（不清除） */
+    snapshot(sessionId: string): ErrorSnapshot;
+    /** 清理该 session 的计数器 */
+    cleanup(sessionId: string): void;
+}
+export declare class SessionErrorTrackerImpl implements SessionErrorTracker {
+    private counters;
+    reset(sessionId: string): void;
+    recordModelError(sessionId: string): void;
+    recordModelSuccess(sessionId: string): void;
+    recordToolError(sessionId: string): void;
+    snapshot(sessionId: string): ErrorSnapshot;
+    cleanup(sessionId: string): void;
+    private getOrCreate;
+    /** 防御性清理：移除超时未活动的 session 计数器 */
+    private evictStale;
+}

package/cli/dist-server/types/node/galileo/task-outcome-resolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TaskOutcomeResolver — 独立的 outcome 解析器
+ *
+ * 将 stopReason + errorMessage(category) + ErrorSnapshot 三个信号源
+ * 组装为 TaskOutcomeContext，然后调用已有的 determineTaskOutcome()。
+ *
+ * 独立模块，不修改 task-outcome.ts 的判定逻辑。
+ */
+import type { StopReason } from '../../workspace/agent-client-protocol/lib/common/index.js';
+import type { ErrorSnapshot } from './session-error-tracker';
+import { TaskOutcome } from './task-outcome';
+/**
+ * 根据 prompt 结束时的多维信号精细判定 TaskOutcome。
+ *
+ * @param stopReason   - ACP 协议的 stopReason
+ * @param errorMessage - createEventForwardingPromise 传回的 errorMessage（JSON-RPC 格式或纯文本）
+ * @param errorSnapshot - SessionErrorTracker 的快照
+ */
+export declare function resolveTaskOutcome(stopReason: StopReason, errorMessage: string | undefined, errorSnapshot: ErrorSnapshot): TaskOutcome;
+/**
+ * 从 errorMessage JSON 中提取 category 字段。
+ *
+ * errorMessage 格式（由 classifyErrorAsRequestError().toErrorResponse() 生成）：
+ *   { "code": -32001, "message": "...", "data": { "category": "network", ... } }
+ * 或嵌套：
+ *   { "error": { "code": ..., "data": { "category": "..." } } }
+ */
+export declare function extractCategoryFromErrorMessage(errorMessage: string | undefined): string | undefined;

package/cli/dist-server/types/node/galileo/task-outcome.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Task Outcome — Agent 任务最终结果判定
+ *
+ * 根据 session history 中的模型响应和工具执行结果，判定本次 task 的 outcome。
+ * 用于 SLA 聚合上报。
+ */
+export type TaskOutcome = 'SUCCESS' | 'PARTIAL_SUCCESS' | 'FAILED_MODEL_REQUEST' | 'FAILED_TOOL_EXECUTION' | 'FAILED_AGENT_LOOP' | 'REFUSED_OR_BLOCKED' | 'CANCELLED' | 'PERMISSION_DENIED' | 'UNKNOWN';
+export interface TaskOutcomeContext {
+    /** 是否有模型正常返回 stop/end_turn */
+    hasFinalAnswer: boolean;
+    /** 是否有未恢复的模型请求错误 */
+    hasUnrecoveredModelError: boolean;
+    /** 是否有未恢复的工具执行错误 */
+    hasUnrecoveredToolError: boolean;
+    /** 是否被用户主动取消 */
+    wasCancelled: boolean;
+    /** 是否触发了 agent loop 限制（maxSteps / maxTurns） */
+    hitLoopLimit: boolean;
+    /** 是否被安全策略拒绝 */
+    wasRefused: boolean;
+}
+/**
+ * 根据上下文判定 Task Outcome。
+ *
+ * 判定优先级：
+ *   1. 用户取消 → CANCELLED
+ *   2. 安全策略拒绝 → REFUSED_OR_BLOCKED
+ *   3. 有 finalAnswer 且无错误 → SUCCESS
+ *   4. 有 finalAnswer 但有错误 → PARTIAL_SUCCESS
+ *   5. 无 finalAnswer + 模型错误 → FAILED_MODEL_REQUEST
+ *   6. 无 finalAnswer + 工具错误 → FAILED_TOOL_EXECUTION
+ *   7. 触发循环限制 → FAILED_AGENT_LOOP
+ *   8. 兜底 → UNKNOWN
+ */
+export declare function determineTaskOutcome(ctx: TaskOutcomeContext): TaskOutcome;

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

@@ -0,0 +1,78 @@
+import type { Mods } from '../../workspace/cbc-plugins/lib/node/index.js';
+/** The shared Mods API; headless capability behavior is documented by the host. */
+export type FunctionalHookApi = Mods.EngineInterface;
+type Inputs = {
+    [E in Mods.EventName]: Mods.Args<E>;
+} & {
+    'session.start': {
+        cwd: string;
+        surface: null;
+        isInteractive: boolean;
+    };
+    'session.id': Record<never, never>;
+    'session.cwd': Record<never, never>;
+    'engine.create': {
+        plugins: readonly string[];
+    };
+    'plugin.register': Mods.PluginRegisterInput;
+};
+type Results = Mods.ResultOf & {
+    'session.start': {
+        cwd: string;
+    };
+    'session.id': {
+        value: string;
+    } | {
+        deny: string;
+    };
+    'session.cwd': {
+        value: string;
+    } | {
+        deny: string;
+    };
+    'engine.create': Partial<FunctionalHookApi>;
+    'plugin.register': Mods.PluginRegisterResult;
+};
+export type FunctionalHookEvent = Mods.EventName;
+type Namespace = FunctionalHookEvent extends `${infer N}.${string}` ? N : never;
+type PositivePattern = FunctionalHookEvent | `${Namespace}.*` | '*';
+export type FunctionalHookPattern = PositivePattern | `!${PositivePattern}`;
+type Selected<P extends FunctionalHookPattern> = P extends `!${infer Q extends PositivePattern}` ? Exclude<FunctionalHookEvent, Selected<Q>> : P extends '*' ? FunctionalHookEvent : P extends `${infer N}.*` ? Extract<FunctionalHookEvent, `${N}.${string}`> : Extract<P, FunctionalHookEvent>;
+type Frozen<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: Frozen<T[K]>;
+} : T;
+type Matcher<T> = {
+    readonly [K in keyof T]?: Mods.MatcherValue<T[K]>;
+};
+type Narrow<T, M> = T extends object ? T & {
+    [K in keyof M & keyof T]: M[K] extends string | number | boolean ? M[K] : T[K];
+} : T;
+type Input<P extends FunctionalHookPattern, M> = Narrow<Inputs[Selected<P>], M>;
+type Result<P extends FunctionalHookPattern> = Results[Selected<P>];
+/** Same next()/is()/catch() correlation as Mods, using the shared event vocabulary. */
+export interface FunctionalHookNext<P extends FunctionalHookPattern, M = unknown> {
+    <T extends string>(input: Input<P, M> & {
+        tool: T;
+    }): Promise<P extends 'tool.call' ? Mods.ToolCallResult<T> : Result<P>>;
+    (input: Input<P, M>): Promise<Result<P>>;
+    readonly event: Selected<P>;
+    readonly signal: AbortSignal;
+    readonly origin: Mods.Origin;
+    readonly budget: Mods.NextBudget;
+    readonly trace: readonly Mods.TraceEntry[];
+    readonly is: <Q extends FunctionalHookPattern>(pattern: Q, input: unknown) => input is Frozen<Inputs[Extract<Selected<P>, Selected<Q>>]>;
+}
+type Hook<P extends FunctionalHookPattern, M = unknown> = (api: P extends 'engine.create' ? Record<string, never> : FunctionalHookApi, input: Frozen<Input<P, M>>, next: FunctionalHookNext<P, M>) => Result<P> | undefined | Promise<Result<P> | undefined>;
+interface Registration<P extends FunctionalHookPattern, M> {
+    readonly catch: (handler: (api: FunctionalHookApi, input: Frozen<Input<P, M>>, next: FunctionalHookNext<P, M> & {
+        readonly error: Mods.HookFailure;
+        readonly called: boolean;
+    }) => Result<P> | undefined | Promise<Result<P> | undefined>) => void;
+}
+export interface FunctionalHookOn {
+    <P extends FunctionalHookPattern>(pattern: P, hook: NoInfer<Hook<P>>): Registration<P, unknown>;
+    <P extends FunctionalHookPattern, const M extends Matcher<Inputs[Selected<P>]>>(pattern: P, matcher: M, hook: NoInfer<Hook<P, M>>): Registration<P, M>;
+}
+/** Registration is awaited; event handlers are active only after it succeeds. */
+export type FunctionalHooksRegister = (on: FunctionalHookOn, options: Mods.PluginOptions) => unknown;
+export {};