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

package/cli/dist-server/types/node/telemetry/status-reporter.d.ts

@@ -0,0 +1,39 @@
+import { Application, ApplicationLifecycle, IntervalTimer } from '@celljs/core';
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { EventService, Logger, PluginStatusTelemetry } from '../../workspace/telemetry/lib/common/index.js';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+interface PluginStatusDailyState {
+    version: 1;
+    reports: Record<string, string>;
+}
+export declare class PluginStatusServiceImpl implements ApplicationLifecycle<Application> {
+    protected readonly productManager: ProductManager;
+    protected readonly logger: Logger;
+    protected readonly eventService: EventService;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected readonly prewarmState: IPrewarmStateService;
+    protected readonly timer: IntervalTimer;
+    protected pluginStartReportPending: boolean;
+    protected readonly checkInterval: number;
+    private stopped;
+    private activationDeferred;
+    private cancelAuthWait?;
+    initialize(): void;
+    protected init(): void;
+    protected doInit(): void;
+    onStop(): void;
+    protected startPeriodicChecking(): Promise<void>;
+    protected reportPluginStatusOnStart(): void;
+    protected doReportPluginStatusOnStart(): Promise<void>;
+    protected waitAuthReadyForPluginStart(): Promise<void>;
+    protected delay(ms: number): Promise<void>;
+    protected checkAndReportDaily(): Promise<void>;
+    protected reportOncePerAccountPerDay(payload: PluginStatusTelemetry): Promise<boolean>;
+    protected getAccountUid(): string | undefined;
+    protected getLocalDateKey(date?: Date): string;
+    protected getDailyReportStatePath(): string;
+    protected readDailyReportState(): Promise<PluginStatusDailyState>;
+    protected writeDailyReportState(state: PluginStatusDailyState): Promise<void>;
+}
+export {};

package/cli/dist-server/types/node/telemetry/telemetry-client-carrier.d.ts

@@ -0,0 +1,14 @@
+import { type Session } from '../../vendor/cbc-core/node/index.js';
+/**
+ * 把发起本次请求的客户端遥测信息（`session.telemetryClientInfo`）作为临时载体字段
+ * 塞进 event payload，供 {@link TelemetryClientInfoEventProcessor} 在 processor 阶段展开成
+ * 正式公共字段后删除（对齐 `fileUri` → `VCSEventProcessor` 的临时载体范式）。
+ *
+ * - 无session 或 session 未携带客户端信息（普通 CLI）→ 原样返回 payload，processor 走进程级兜底。
+ * - **就地写入并返回同一对象**：调用点 `report(code, attachTelemetryClientCarrier(payload, session))`
+ *   即可，不改变原有 report 调用形态（await / options / 是否 modelEventService 均不受影响）。
+ *
+ * 供`TelemetryServiceImpl` 及包外上报点（friction / credit-refund / mcp 等持有 session 者）复用，
+ * 避免每处重复拼载体。
+ */
+export declare function attachTelemetryClientCarrier<T extends object>(payload: T, session: Session | undefined): T;

package/cli/dist-server/types/node/telemetry/telemetry-client-info-event-processor.d.ts

@@ -0,0 +1,8 @@
+import { EventProcessContext, EventProcessor } from '../../workspace/telemetry/lib/common/index.js';
+/**
+ * processor 顺序不保证；客户端值有值即覆盖，进程级 processor 只兜底空值。
+ * 载体是内部字段，用后删除，避免泄漏进最终上报 payload。
+ */
+export declare class TelemetryClientInfoEventProcessor implements EventProcessor {
+    process({ event }: EventProcessContext): Promise<void>;
+}

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

@@ -0,0 +1,137 @@
+import type { ToolCallLoopEventKind, ToolCallLoopEvidence } from '../../vendor/cbc-core/node/index.js';
+import { ModelCallGeneration, ModelResponseMetadata, Session } from '../../vendor/cbc-core/node/index.js';
+import { RunResult, StreamedRunResult } from '../../vendor/cbc-shared/node/index.js';
+import { ChatMessageSendTelemetry } from '../../workspace/telemetry/lib/common/event/types/craft.js';
+export declare const TelemetryService: unique symbol;
+export type UserTaskFailedCreditRefundReason = 'loop_detected' | 'abnormal_finish_reason';
+export interface TelemetryService {
+    /**
+     * 记录当前 rootRequestId 下出现过的 conversationRequestId，用于失败退费逐条上报。
+     */
+    recordCreditRefundConversationRequest(session: Session): void;
+    /**
+     * 记录当前 conversationRequestId 的模型 finish_reason，用于过滤未进入 Tool Calls 的请求。
+     */
+    recordCreditRefundConversationRequestEnd(session: Session, finishReason: string | undefined): void;
+    /**
+     * 标记当前 conversationRequestId 不参与退费上报。
+     */
+    suppressCreditRefundConversationRequest(session: Session): void;
+    /**
+     * 上报用户任务失败退费检测事件；触发后消费当前 rootRequestId 的累积 request 列表。
+     */
+    reportUserTaskFailedCreditRefund(session: Session, reason: UserTaskFailedCreditRefundReason): Promise<void>;
+    /**
+     * 上报工具调用循环观测事件：弹窗展示（suspected）、用户继续（continue）、
+     * 弹不出窗的自动继续（auto_continue）、用户停止（detected）。
+     * 只做观测，不影响退费；退费仍走 reportUserTaskFailedCreditRefund。
+     */
+    reportToolCallLoopEvent(kind: ToolCallLoopEventKind, session: Session, evidence: ToolCallLoopEvidence): Promise<void>;
+    /**
+     * 创建并发送消息发送埋点
+     * @param headers 请求头
+     * @param body 请求体
+     * @param isStream 是否为流式请求
+     * @param session Session the model call belongs to; defaults to the current one
+     * @returns 发送埋点数据
+     */
+    reportMessageSendTelemetry(headers: Record<string, string>, body: any, isStream: boolean, session?: Session): ChatMessageSendTelemetry & {
+        sendTime: number;
+        isStream: boolean;
+    };
+    /**
+     * 发送非流式消息响应埋点
+     * @param session 会话对象
+     * @param sendTelemetry 发送埋点数据
+     * @param axiosResponse 响应对象（用于从 data.usage 提取 token）
+     * @param isSuccessful 是否成功
+     * @param error 错误信息（可选）
+     */
+    reportMessageResponseTelemetryNonStream(session: Session, sendTelemetry: ChatMessageSendTelemetry & {
+        sendTime: number;
+        isStream: boolean;
+    }, axiosResponse: any, isSuccessful: boolean, error?: any): Promise<void>;
+    /**
+     * 发送聊天请求埋点
+     * @param session 会话对象
+     */
+    reportChatRequestSendTelemetry(session: Session): Promise<void>;
+    /**
+     * 上报等待模型 X-Request-ID 的增长埋点。
+     * @param session 会话对象
+     * @param requestId 实际 /v2/chat/completions 请求头 X-Request-ID
+     */
+    flushPendingGrowthTelemetry(session: Session, requestId: string): Promise<void>;
+    /**
+     * 发送请求响应埋点
+     * @param session 会话对象
+     * @param result 运行结果
+     * @param isSuccessful 是否成功
+     * @param error 错误信息（可选）
+     * @param modelResponseMetadata 模型响应元数据（可选）
+     */
+    reportChatRequestResponseTelemetry(session: Session, result?: RunResult<any, any> | StreamedRunResult<any, any> | undefined, isSuccessful?: boolean, error?: any, modelResponseMetadata?: ModelResponseMetadata): Promise<void>;
+    /**
+     * 上报流式请求的消息响应埋点
+     * @param session 会话对象
+     */
+    reportMessageResponseTelemetryStream(session: Session, usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        requests?: number | undefined;
+        inputTokensDetails?: Record<string, number> | undefined;
+        outputTokensDetails?: Record<string, number> | undefined;
+    }, modelResponseMetadata?: ModelResponseMetadata, error?: any): Promise<void>;
+    /**
+     * 上报模型工具调用埋点
+     * @param session 会话对象
+     * @param functionCallResultItem 工具调用结果项
+     */
+    reportModelToolCall(session: Session, functionCallResultItem: any): Promise<void>;
+    /**
+     * 上报手动工具调用埋点
+     * @param session 会话对象
+     * @param toolCallItem 工具调用项
+     * @param toolCallSuccessful 调用是否成功
+     * @param toolStatus 工具状态
+     * @param toolErrorCode 错误代码
+     */
+    reportManualToolCall(session: Session, toolCallItem: any, toolCallSuccessful: boolean, toolStatus: string, toolErrorCode: unknown): Promise<void>;
+    /**
+     * 上报聊天文件操作埋点
+     * @param session 会话对象
+     * @param fileActionData 文件操作数据
+     */
+    reportChatFileAction(session: Session, fileActionData: {
+        languageId: string;
+        isNewFile: boolean;
+        addLineCount: number;
+        removedLines: number;
+        addCharCount: number;
+        deleteCharCount: number;
+    }): Promise<void>;
+    /**
+     * 上报消息状态埋点（成功或失败）
+     * @param session 会话对象
+     * @param messageErrorCode 错误代码，成功时为 '0'
+     * @param generation 该状态所属的那次模型调用，与同一调用的 chat_message_send / response 同 id
+     */
+    reportChatMessageStatus(session: Session, messageErrorCode: string, generation: ModelCallGeneration, error?: unknown): Promise<void>;
+    /**
+     * 上报达到最大 Token 限制埋点
+     * @param session 会话对象
+     * @param responseModelId 响应模型 ID（可选）
+     */
+    reportChatMaxTokenReached(session: Session, responseModelId?: string): Promise<void>;
+    /**
+     * 上报代码编辑统计埋点
+     * @param languageId 语言 ID
+     * @param fileCount 变更文件数
+     * @param lineCount 变更行数
+     * @param characterCount 变更字符数
+     * @param traceId 关联 trace（仅在有 session 上下文时透传）
+     * @param session 发起本次请求的 session，用于按客户端来源端归属公共字段
+     */
+    reportCodeEdit(languageId: string, fileCount: number, lineCount: number, characterCount: number, traceId?: string, session?: Session): Promise<void>;
+}

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

@@ -0,0 +1,115 @@
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { ModelCallGeneration, ModelResponseMetadata, Session } from '../../vendor/cbc-core/node/index.js';
+import { type ToolCallLoopEventKind, type ToolCallLoopEvidence } from '../../vendor/cbc-core/node/index.js';
+import { type FunctionCallItem, type FunctionCallResultItem, RunResult, StreamedRunResult } from '../../vendor/cbc-shared/node/index.js';
+import { ClientInfoProvider, ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Workspace } from '../../workspace/runtime/lib/common/index.js';
+import { EventService, Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { ChatMessageSendTelemetry } from '../../workspace/telemetry/lib/common/event/types/craft.js';
+import { AgentMetricsAggregator } from '../galileo/agent-metrics-aggregator';
+import { CostService } from './cost-protocol';
+import { FrictionAnalysisService } from './friction-analysis';
+import { TelemetryService, type UserTaskFailedCreditRefundReason } from './telemetry-protocol';
+export declare class TelemetryServiceImpl implements TelemetryService {
+    protected readonly productManager: ProductManager;
+    protected readonly eventService: EventService;
+    protected readonly modelEventService: EventService;
+    protected readonly logger: Logger;
+    protected readonly costService: CostService;
+    protected readonly metricsAggregator: AgentMetricsAggregator | undefined;
+    private readonly creditRefundTelemetry;
+    protected readonly workspace: Workspace;
+    protected readonly clientInfoProvider: ClientInfoProvider;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected readonly frictionAnalysisService: FrictionAnalysisService;
+    private safeJSONParse;
+    private getSessionMode;
+    /** 获取 ACP 入口采纳的专家 ID；专家使用场景下 mode 仍可能是 craft。 */
+    private getSessionExpertId;
+    /**
+     * chat_message_send/response cover exactly the agent-loop model calls of the
+     * current async chain (see `isMainLoopModelCall`), so each reported message
+     * owns one `totalStepCount` and the sequence has no gaps. Auxiliary calls
+     * (title, summaries, WebFetch analysis, ...) are not reported.
+     */
+    private shouldReportMessageTelemetry;
+    private isRecord;
+    recordCreditRefundConversationRequest(session: Session): void;
+    recordCreditRefundConversationRequestEnd(session: Session, finishReason: string | undefined): void;
+    suppressCreditRefundConversationRequest(session: Session): void;
+    reportUserTaskFailedCreditRefund(session: Session, reason: UserTaskFailedCreditRefundReason): Promise<void>;
+    reportToolCallLoopEvent(kind: ToolCallLoopEventKind, session: Session, evidence: ToolCallLoopEvidence): Promise<void>;
+    private clearCreditRefundAccumulatorForRoot;
+    private parseGrowthEvents;
+    private appendGrowthEvent;
+    private queuePendingGrowthTelemetry;
+    flushPendingGrowthTelemetry(session: Session, requestId: string): Promise<void>;
+    reportChatRequestSendTelemetry(session: Session): Promise<void>;
+    reportChatRequestResponseTelemetry(session: Session, result: RunResult<any, any> | StreamedRunResult<any, any> | undefined, isSuccessful: boolean, error?: any, modelResponseMetadata?: ModelResponseMetadata): Promise<void>;
+    /**
+     * 获取敏感词过滤的原因类型
+     * 用于区分 SAAS 安全和模型安全
+     * @param finishReason 完成原因
+     * @returns 'model_safety' 表示模型安全，undefined 表示非敏感词过滤
+     */
+    private getContentFilterReason;
+    reportMessageSendTelemetry(headers: Record<string, string>, body: any, isStream: boolean, callSession?: Session): ChatMessageSendTelemetry & {
+        sendTime: number;
+        isStream: boolean;
+    };
+    reportMessageResponseTelemetryNonStream(session: Session, sendTelemetry: ChatMessageSendTelemetry & {
+        sendTime: number;
+        isStream: boolean;
+    }, axiosResponse: any, isSuccessful: boolean, error?: any): Promise<void>;
+    /**
+     * 根据 modelId 从产品配置查找模型定义。找不到返回 undefined。
+     * 兼容自定义本地模型前缀（custom-local:）与 aliases。
+     */
+    private getModelConfig;
+    /**
+     * 判断是否为自定义模型。判定口径与 model-provider.isCustomModelRequest 保持一致：
+     * id 前缀 custom-local: / custom: ｜ trustLevel=custom ｜ tags 含 'custom'。
+     */
+    private isCustomModel;
+    /** 产品形态映射到上报口径：saas / hosted / exclusive。 */
+    private mapProductConfigType;
+    /**
+     * 自定义模型调用埋点（custom_model_usage → /llm/data/report）。
+     * 仅当判定为自定义模型时上报，非自定义模型直接跳过。仅覆盖 chat/craft 主链路。
+     *
+     * billing / creditUsage / creditVersion / viaCopilotServer 自定义模型场景不涉及，不传。
+     */
+    private reportCustomModelUsage;
+    reportMessageResponseTelemetryStream(session: Session, usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        requests?: number | undefined;
+        inputTokensDetails?: Record<string, number> | undefined;
+        outputTokensDetails?: Record<string, number> | undefined;
+    }, modelResponseMetadata?: ModelResponseMetadata, error?: any): Promise<void>;
+    reportModelToolCall(session: Session, rawItem: FunctionCallResultItem): Promise<void>;
+    /**
+     * 上报 Skill 工具调用的 skill_info 事件（仅 WorkBuddy Desktop 宿主）。
+     *
+     * skillName 通过 callId 反向查找同会话的 function_call item，从其 arguments 中解析。
+     * fileCount 使用 product.json 里加载的 skills 总数作为近似值。
+     */
+    private reportSkillInfo;
+    /**
+     * 从 session.history 中找到与 rawItem.callId 对应的 function_call 条目，解析 arguments 得到 skillName。
+     */
+    private extractSkillName;
+    reportManualToolCall(session: Session, toolCallItem: FunctionCallItem, toolCallSuccessful: boolean, toolStatus: string, toolErrorCode: unknown): Promise<void>;
+    reportChatFileAction(session: Session, fileActionData: {
+        languageId: string;
+        isNewFile: boolean;
+        addLineCount: number;
+        removedLines: number;
+        addCharCount: number;
+        deleteCharCount: number;
+    }): Promise<void>;
+    reportChatMessageStatus(session: Session, messageErrorCode: string, generation: ModelCallGeneration, error?: unknown): Promise<void>;
+    reportChatMaxTokenReached(session: Session, responseModelId?: string): Promise<void>;
+    reportCodeEdit(languageId: string, fileCount: number, lineCount: number, characterCount: number, traceId?: string, session?: Session): Promise<void>;
+}

package/cli/dist-server/types/node/telemetry/turn-baggage-processor.d.ts

@@ -0,0 +1,23 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { EventProcessContext, EventProcessor, TracerProvider } from '../../workspace/telemetry/lib/common/index.js';
+type TelemetryAttributeValue = string | number | boolean;
+/** Baggage entries of the current turn; `{}` outside a turn. */
+export declare function currentTurnBaggageAttributes(): Record<string, string>;
+/** Merge current turn baggage with explicit values taking precedence. */
+export declare function mergeCurrentTurnBaggage<T extends TelemetryAttributeValue>(explicit: Readonly<Record<string, T>> | undefined): Record<string, string | T>;
+/** Stamps turn baggage onto report events without replacing explicit fields. */
+export declare class TurnBaggageEventProcessor implements EventProcessor {
+    process({ event }: EventProcessContext): Promise<void>;
+}
+/**
+ * Single registration point for the baggage-to-span-attribute processor.
+ * TracerProvider.attachSpanProcessor is idempotent per instance and re-attaches
+ * to the Galileo global provider when that registers later, so no other code
+ * path needs to know this processor exists.
+ */
+export declare class TurnBaggageSpanProcessorLifecycle implements ApplicationLifecycle<Application> {
+    protected readonly tracerProvider?: TracerProvider;
+    private readonly processor;
+    initialize(): void;
+}
+export {};

package/cli/dist-server/types/node/telemetry/vcs-event-processor.d.ts

@@ -0,0 +1,19 @@
+import { EventProcessContext, EventProcessor } from '../../workspace/telemetry/lib/common/index.js';
+/**
+ * CLI 环境下的 VCS 事件处理器
+ * 基于工程根目录，通过读取 .git 文件系统获取 Git 信息
+ */
+export declare class VCSEventProcessor implements EventProcessor {
+    private cache?;
+    private readonly cacheTTL;
+    process({ event }: EventProcessContext): Promise<void>;
+    private getVcsInfo;
+    /**
+     * 读取 HEAD 引用，解析出完整 commit SHA
+     */
+    private getRevisionId;
+    /**
+     * 清除 Git URL 中的敏感信息（用户名/密码）
+     */
+    private clearSensitiveData;
+}

package/cli/dist-server/types/node/tips/builtin-tips.d.ts

@@ -0,0 +1,2 @@
+import { Tip } from './tips-protocol';
+export declare const BUILTIN_TIPS: Tip[];

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

@@ -0,0 +1,4 @@
+export * from './tips-protocol';
+export * from './tips-manager';
+export * from './user-state-manager';
+export * from './builtin-tips';

package/cli/dist-server/types/node/tips/tips-manager.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from '@celljs/core';
+import { Tip, TipsManager, UserStateManager } from './tips-protocol';
+export declare class TipsManagerImpl implements TipsManager {
+    protected readonly logger: Logger;
+    protected readonly userStateManager: UserStateManager;
+    private tips;
+    protected init(): void;
+    registerTip(tip: Tip): void;
+    registerTips(tips: Tip[]): void;
+    getRelevantTip(): Promise<{
+        id: string;
+        content: string;
+    } | undefined>;
+}

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

@@ -0,0 +1,42 @@
+import { Event } from '@celljs/core';
+export declare const TipsManager: unique symbol;
+export declare const UserStateManager: unique symbol;
+export interface Tip {
+    id: string;
+    content: string | (() => Promise<string>);
+    cooldownSessions: number;
+    isRelevant: () => Promise<boolean>;
+}
+export interface UserState {
+    numStartups: number;
+    lastPlanModeUse?: number;
+    memoryUsageCount: number;
+    promptQueueUseCount: number;
+    sessionsSinceLastTip: number;
+    lastTipShown?: string;
+    tipShowHistory: {
+        [tipId: string]: {
+            count: number;
+            lastShown: number;
+        };
+    };
+}
+export interface UserStateManager {
+    readonly onDidChange: Event<UserState>;
+    getState(): Promise<UserState>;
+    setState(state: Partial<UserState>): Promise<void>;
+    incrementStartup(): Promise<void>;
+    updatePlanModeUse(): Promise<void>;
+    incrementMemoryUsage(): Promise<void>;
+    incrementPromptQueue(): Promise<void>;
+    recordTipShown(tipId: string): Promise<void>;
+    incrementSession(): Promise<void>;
+}
+export interface TipsManager {
+    getRelevantTip(): Promise<{
+        id: string;
+        content: string;
+    } | undefined>;
+    registerTip(tip: Tip): void;
+    registerTips(tips: Tip[]): void;
+}

package/cli/dist-server/types/node/tips/user-state-manager.d.ts

@@ -0,0 +1,25 @@
+import { Emitter, Logger } from '@celljs/core';
+import { UserState, UserStateManager } from './tips-protocol';
+export declare class UserStateManagerImpl implements UserStateManager {
+    protected readonly logger: Logger;
+    protected readonly onDidChangeEmitter: Emitter<UserState>;
+    readonly onDidChange: import("@celljs/core").Event<UserState>;
+    private cachedState?;
+    /**
+     * server 面缺省 no-op（CODEBUDDY_DISABLE_USER_STATE=1）：消费者全是交互
+     * 产品面（tips 展示冷却/启动计数），pod 上无消费者；写盘还会把多租户
+     * 状态混进进程全局文件。no-op 而非内存假状态——假共享不如无共享
+     * （local_storage 同判例）。
+     */
+    private get disabled();
+    getState(): Promise<UserState>;
+    setState(state: Partial<UserState>): Promise<void>;
+    incrementStartup(): Promise<void>;
+    updatePlanModeUse(): Promise<void>;
+    incrementMemoryUsage(): Promise<void>;
+    incrementPromptQueue(): Promise<void>;
+    incrementSession(): Promise<void>;
+    recordTipShown(tipId: string): Promise<void>;
+    private getStateFilePath;
+    private save;
+}

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

@@ -0,0 +1 @@
+export * from './tool-control-policy';

package/cli/dist-server/types/node/tool-control/tool-control-policy.d.ts

@@ -0,0 +1,34 @@
+export declare const TOOL_CONTROL_BLOCKED_MARKER = "WORKBUDDY_TOOL_CONTROL_BLOCKED";
+export declare const ToolControlPolicy: unique symbol;
+export type ToolControlBlockReason = 'tool_disabled' | 'mcp_server_disabled' | 'mcp_tool_disabled' | 'custom_mcp_disabled';
+export interface ToolControlAuditContext {
+    sessionId?: string;
+    requestId?: string;
+    toolCallId?: string;
+}
+export interface ToolControlMcpContext extends ToolControlAuditContext {
+    serverId: string;
+    toolName: string;
+    custom: boolean;
+    toolControlId?: string;
+    compatibleToolControlIds?: readonly string[];
+}
+export interface ToolControlPolicy {
+    assertToolExecutionAllowed(toolName: string, context?: ToolControlAuditContext): Promise<void>;
+    assertMcpToolExecutionAllowed(context: ToolControlMcpContext): Promise<void>;
+}
+export declare class ToolControlBlockedError extends Error {
+    readonly code = "WORKBUDDY_TOOL_CONTROL_BLOCKED";
+    readonly retryable = false;
+    readonly reason: ToolControlBlockReason;
+    readonly toolId: string;
+    readonly serverId?: string;
+    constructor(toolId: string, toolName: string, reason: ToolControlBlockReason, serverId?: string);
+}
+export declare function isToolControlBlockedError(error: unknown): error is ToolControlBlockedError;
+export declare class ToolControlPolicyImpl implements ToolControlPolicy {
+    private readSettings;
+    private block;
+    assertToolExecutionAllowed(toolName: string, context?: ToolControlAuditContext): Promise<void>;
+    assertMcpToolExecutionAllowed(context: ToolControlMcpContext): Promise<void>;
+}

package/cli/dist-server/types/node/tools/a2a-cancel-task-tool.d.ts

@@ -0,0 +1,55 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { AbTestService } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { A2aAgentRegistry, A2aClientService, A2aDiscoveryReadyService } from '../a2a/a2a-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const A2ACancelTaskParameters: z.ZodObject<{
+    agent_id: z.ZodString;
+    task_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agent_id: string;
+    task_id: string;
+}, {
+    agent_id: string;
+    task_id: string;
+}>;
+/**
+ * A2ACancelTask — request cancellation of a previously created A2A task
+ * (issue #99451, CloudAgent Phase 1). Cancellation is a best-effort request,
+ * not a guarantee per the A2A spec: an already-terminal task cannot be
+ * canceled (surfaced as `A2ATaskNotCancelableError`), and the remote agent
+ * may still be mid-flight when this call returns.
+ *
+ * Restricted to the main session, same recursive-delegation guard as
+ * `A2ASendMessageTool` (see that tool's doc comment).
+ */
+export declare class A2ACancelTaskTool extends BaseTool implements Tool {
+    protected readonly registry?: A2aAgentRegistry;
+    protected readonly client?: A2aClientService;
+    protected readonly abTestService?: AbTestService;
+    protected readonly discoveryReadyService?: A2aDiscoveryReadyService;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    parameters: z.ZodObject<{
+        agent_id: z.ZodString;
+        task_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        agent_id: string;
+        task_id: string;
+    }, {
+        agent_id: string;
+        task_id: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (args: {
+        runContext: RunContext<Session>;
+    }) => Promise<boolean>;
+    execute(input: z.infer<typeof A2ACancelTaskParameters>, context: RunContext<Session>): Promise<ToolResult>;
+}
+export {};

package/cli/dist-server/types/node/tools/a2a-get-agent-card-tool.d.ts

@@ -0,0 +1,59 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { ToolNames } from '../../vendor/cbc-shared/node/index.js';
+import { AbTestService } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import type { RunContext } from '@openai/agents';
+import { z } from 'zod';
+import { A2aAgentRegistry, A2aDiscoveryReadyService } from '../a2a/a2a-protocol';
+import { BaseTool } from './base-tool';
+import { Tool, ToolCallArgumentRenderer, ToolResult } from './tool-protocol';
+declare const A2AGetAgentCardParameters: z.ZodObject<{
+    agent_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agent_id: string;
+}, {
+    agent_id: string;
+}>;
+/**
+ * A2AGetAgentCard — resolve one outbound A2A agent by its stable `agent_id`
+ * and return its full Agent Card (issue #99451; id-only addressing per issue
+ * #114840). The available agents are advertised in this tool's description
+ * (`<available_A2A_agents>`, each line prefixed with its `[id]`), populated
+ * dynamically at render time from the process-global `A2aAgentRegistry` (see
+ * the `A2A_GET_AGENT_CARD` case in tool-manager.ts). The registry is filled by
+ * lazy discovery against `CODEBUDDY_REMOTE_AGENTS_URL` (see
+ * `A2aDiscoveryReadyService`) plus a background startup trigger and a bounded
+ * first-run prewait, so the block reflects the currently authorized agents
+ * with no session-startup network cost. The model calls this to get an agent's
+ * full skills/interfaces before `A2ASendMessage`; the `agent_id` it passes here
+ * is the same one it passes to the send/get/cancel tools.
+ *
+ * Lookup is an exact `agentId` match (`deriveA2aAgentId` gives distinct ids to
+ * distinct endpoints, so it is never ambiguous). A miss returns
+ * `AGENT_NOT_FOUND` listing the available `name (id)` pairs.
+ *
+ * Restricted to the main session, same recursive-delegation guard as the
+ * other 3 A2A tools (see `isSubSession` in a2a-tool-guards.ts).
+ */
+export declare class A2AGetAgentCardTool extends BaseTool implements Tool {
+    protected readonly registry?: A2aAgentRegistry;
+    protected readonly abTestService?: AbTestService;
+    protected readonly discoveryReadyService?: A2aDiscoveryReadyService;
+    protected readonly logger: Logger;
+    name: ToolNames;
+    description: string;
+    needsApproval: boolean;
+    parameters: z.ZodObject<{
+        agent_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        agent_id: string;
+    }, {
+        agent_id: string;
+    }>;
+    argumentRenderer: ToolCallArgumentRenderer;
+    isEnabled: (args: {
+        runContext: RunContext<Session>;
+    }) => Promise<boolean>;
+    execute(input: z.infer<typeof A2AGetAgentCardParameters>, context: RunContext<Session>): Promise<ToolResult>;
+}
+export {};