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

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

@@ -0,0 +1,23 @@
+import { type ModsBridge, type ModsExecutionContext, type Session } from '../../vendor/cbc-core/node/index.js';
+import { Mods } from '../../workspace/cbc-plugins/lib/node/index.js';
+import type { FunctionalHooksRegister } from './functional-hooks-protocol';
+export interface FunctionalHooks {
+    readonly bridge: ModsBridge;
+}
+export interface FunctionalHooksHost {
+    readonly name: string;
+    readonly signal: AbortSignal;
+    readonly report: (message: string) => void;
+    readonly getSession: () => ModsExecutionContext | undefined;
+}
+/** Existing dispatch sites can use the scoped runtime without the CLI singleton. */
+export declare function currentFunctionalHooksRuntime(): Pick<Mods.ModsRuntime, 'dispatch'> | undefined;
+/** A Server turn ends at query settlement, including approval continuations. */
+export declare function withFunctionalHookTurn<T extends {
+    stopReason: string;
+    assistantText: string;
+}>(turnId: string, run: () => Promise<T>): Promise<T>;
+export declare function prepareSessionFunctionalHooks(session: Session, bridge?: ModsBridge): Promise<void>;
+export declare function closeSessionFunctionalHooks(session: Session): Promise<void>;
+/** Host registration is application-owned; plugin registrations belong to a mounted session. */
+export declare function createFunctionalHooks(register: FunctionalHooksRegister, host: FunctionalHooksHost): Promise<FunctionalHooks>;

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

@@ -0,0 +1,50 @@
+import { Logger } from '@celljs/core';
+export interface RefreshOsCertificatesResult {
+    changed: boolean;
+}
+export declare class CertificateManager {
+    private static readonly CERT_REGEX;
+    private readonly customCAPath;
+    private cachedCertificates;
+    protected logger: Logger;
+    /**
+     * 从 PEM 文件读取证书
+     */
+    protected readCertificatesFromFile(filePath: string, source: string): string[];
+    /**
+     * 获取自定义CA证书
+     */
+    protected getCustomCACertificates(): string[];
+    /**
+     * 获取完整的CA证书包（系统证书 + 自定义证书）
+     */
+    getCABundle(): string[];
+    /**
+     * 从 OS 证书库 dump 一次并并入当前进程信任根（只增不重建）。
+     *
+     * dump + 冷却由 {@link runTlsCaRefresh} 负责。没变化则不改默认信任库。
+     * `ca` 选项会整表替换默认根，因此 bundle 仍是 Mozilla + extra。
+     * 若存在 `tls.setDefaultCACertificates`，同步写进程默认信任库，
+     * 让 undici / fetch / OTLP 与 axios 看到同一份根。
+     *
+     * `options.force` 透传给 {@link runTlsCaRefresh}：用户主动发消息的
+     * chat 请求置 true，绕过常规 20s 冷却（#127262 装根后冷却窗口内
+     * 重发自愈）；默认 false，后台请求行为不变。
+     */
+    refreshFromOperatingSystem(options?: {
+        force?: boolean;
+    }): Promise<RefreshOsCertificatesResult>;
+    /**
+     * 清除证书缓存（用于热重载）
+     */
+    clearCache(): void;
+    private applyDefaultCACertificates;
+    /**
+     * 验证证书文件格式
+     */
+    validateCertificateFile(filePath: string): {
+        valid: boolean;
+        error?: string;
+        count?: number;
+    };
+}

package/cli/dist-server/types/node/http/classify-network-error.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI 侧网络失败原因分类器。
+ *
+ * 与 daemon 侧 `@genie/workbuddy-server` 的 `net/classify-network-error.ts` 保持
+ * 同一套判定口径（代理 / PAC / CA / DNS / 超时 / 重置 / 拒绝），但因 agent-cli 是
+ * 独立发布、不依赖 workbuddy-server，这里单独维护一份纯函数实现。改动分类规则时
+ * 两处需同步。
+ *
+ * 目的：让 CLI 的网络失败日志能一眼区分「代理连不上 / PAC 出问题 / CA 证书校验
+ * 失败」，而不是笼统一句 `fetch failed`。
+ */
+export type CliNetworkErrorCategory = 'ca' | 'pac' | 'proxy' | 'dns' | 'timeout' | 'reset' | 'refused' | 'unknown';
+export interface CliNetworkErrorClassification {
+    category: CliNetworkErrorCategory;
+    code?: string;
+    detail: string;
+    chain: string;
+}
+export declare function classifyCliNetworkError(error: unknown): CliNetworkErrorClassification;
+/** 产出一行可直接落日志的 CLI 网络错误分类字符串。 */
+export declare function formatCliNetworkErrorForLog(error: unknown): string;

package/cli/dist-server/types/node/http/custom-header-http-interceptor.d.ts

@@ -0,0 +1,14 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { RestOperations } from '@celljs/http';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { CustomHeadersProvider } from './custom-headers-provider';
+/**
+ * 把 CODEBUDDY_CUSTOM_HEADERS 注入到打向平台 endpoint 的 RestOperations 请求。
+ * 覆盖 imagegen / videogen 以及其它走 axios 单例的平台接口。
+ */
+export declare class CustomHeaderHttpInterceptor implements ApplicationLifecycle<Application> {
+    protected readonly restOperations: RestOperations;
+    protected readonly productManager: ProductManager;
+    protected readonly customHeadersProvider: CustomHeadersProvider;
+    initialize(): void;
+}

package/cli/dist-server/types/node/http/custom-headers-provider.d.ts

@@ -0,0 +1,26 @@
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { SettingsManager } from '../settings';
+/**
+ * 解析并注入 CODEBUDDY_CUSTOM_HEADERS。
+ *
+ * 仅对平台 endpoint 的出站请求写入；第三方 URL（COS、MCP、WebFetch 直连兜底等）不注入。
+ * 写入规则：目标 header 缺失才写，且跳过认证 / hop-by-hop / 请求唯一 ID 黑名单。
+ */
+export declare class CustomHeadersProvider {
+    protected readonly settingsManager: SettingsManager;
+    protected readonly productManager: ProductManager;
+    /**
+     * 解析 `Name: Value` 列表。字面量 `\n` 优先于真实换行符。
+     * 无冒号或 key/value 为空的行丢弃。
+     */
+    static parseCustomHeaders(customHeadersString?: string): Record<string, string>;
+    protected getEnvironment(): NodeJS.ProcessEnv;
+    resolve(): Promise<Record<string, string>>;
+    isPlatformUrl(url: string): boolean;
+    /**
+     * 就地写入自定义 header。
+     * 传了 `url` 时先做平台 origin 判定；工具调用点已知打的是平台接口，可省略。
+     */
+    applyTo(headers: Record<string, string>, url?: string): Promise<void>;
+    private collectPlatformOrigins;
+}

package/cli/dist-server/types/node/http/fetch-proxy.d.ts

@@ -0,0 +1,22 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+/**
+ * CLI 侧 fetch 代理补丁。
+ *
+ * 使用 ProxyResolver 按优先级链自治解析代理，
+ * 失败时清除 OS 缓存并直连重试。
+ */
+export declare class FetchProxy implements ApplicationLifecycle<Application> {
+    protected readonly logger: Logger;
+    private originFetch;
+    /**
+     * settingsPath 显式注入，确保 WORKBUDDY_CONFIG_DIR 被尊重
+     * （见 ProxyResolver class JSDoc 顶部 invariant）。
+     *
+     * #57186：daemon 注入 `WORKBUDDY_PAC_RPC_*` env 时自动启用 L0 PAC 反查；env
+     * 缺失时退化为 L1-L4 自治链。
+     */
+    private proxyResolver;
+    initialize(): Promise<void>;
+    onStop(): Promise<void>;
+}

package/cli/dist-server/types/node/http/http-proxy-interceptor.d.ts

@@ -0,0 +1,116 @@
+import { Application, ApplicationLifecycle, Logger } from '@celljs/core';
+import { RestOperations } from '@celljs/http';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { HttpProxyAgent } from 'http-proxy-agent';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { ConsoleManager } from '../console';
+import { GalileoService } from '../galileo/galileo-protocol';
+import { CertificateManager } from './certificate-manager';
+/**
+ * CLI 侧 HTTP 代理拦截器。
+ *
+ * 使用 ProxyResolver 按优先级链自治解析代理（配置文件 > env > OS > 直连），
+ * 不再依赖主进程 spawn 时注入的静态环境变量。
+ *
+ * 失败自愈：检测到代理相关错误时清除 OS 缓存重新解析，用新代理重试一次。
+ */
+export declare class HttpProxyInterceptor implements ApplicationLifecycle<Application> {
+    protected readonly productManager: ProductManager;
+    protected readonly restOperations: RestOperations;
+    protected readonly certificateManager: CertificateManager;
+    protected readonly consoleManager: ConsoleManager;
+    protected logger: Logger;
+    protected readonly galileo?: GalileoService;
+    /** 代理 Agent 缓存，按 proxyUrl + version 做 key */
+    agentCache: Map<string, {
+        http?: HttpProxyAgent<string>;
+        https?: HttpsProxyAgent<string>;
+    }>;
+    /**
+     * 自治式代理解析器。settingsPath 显式注入，确保 WORKBUDDY_CONFIG_DIR 被尊重，
+     * 不依赖 ProxyResolver 内部默认值（见 ProxyResolver class JSDoc 顶部 invariant）。
+     *
+     * #57186：当 daemon 注入 `WORKBUDDY_PAC_RPC_*` env 时（WorkBuddy Desktop 路径），
+     * 自动启用 L0 PAC 反查 hook，per-request 走 daemon→main 的 Chromium PAC 引擎，
+     * 完整识别企业 PAC 脚本的 per-URL 决策。env 缺失（独立 cbc CLI / 单测 / headless）
+     * 时 hook 为 undefined，行为退化为 L1-L4 自治链，向后完全兼容。
+     */
+    private proxyResolver;
+    /**
+     * keep-alive 参数，对抗中间 LB/NAT 的 TCP idle timeout。
+     * 背景：2026-04-25 偶发 502 socket hang up。
+     */
+    private static readonly KEEP_ALIVE_OPTS;
+    private defaultHttpsAgent?;
+    /**
+     * configuration 变更订阅句柄。当前拦截器为单例、生命周期与进程一致，泄漏风险低；
+     * 显式持有以便 onStop 注销，避免后续若改为按会话/按窗口实例化时订阅泄漏、
+     * 在旧实例上重复 disableTlsVerification 打日志（评审 #69542）。
+     */
+    private tlsConfigSub?;
+    private getDefaultHttpsAgent;
+    private getCABundle;
+    private getSSLOptions;
+    /**
+     * 命中 DisableTlsVerification 时幂等地设置 NODE_TLS_REJECT_UNAUTHORIZED='0'。
+     * 加 env 守卫，避免在每次 configuration 变更时重复设置与重复打日志。
+     */
+    private applyTlsVerificationFromConfig;
+    /** 进程停止时注销 configuration 订阅，释放 applyTlsVerificationFromConfig 闭包（评审 #69542）。 */
+    onStop(): void;
+    private applyConfigFallbackAddress;
+    initialize(): Promise<void>;
+    private finishChatSuccess;
+    private attachChatAddressLayer;
+    private replayChatAddress;
+    private continueChatAddressReplay;
+    /**
+     * 网关在错误体里下发 `retry_policy.retry === false` 时，备站与钉 IP 重放都不再发起。
+     *
+     * 只对会触发重放的 HTTP 状态（408/502/503/504）读错误体，其余错误不引入额外等待。
+     * 读取结果按响应缓存，模型层请求级判定复用同一份，流只消费一次。读取期间请求被取消时
+     * 同样不重放；读不到（超时 / 超限 / 流出错）按无策略处理，照常重放。
+     */
+    private isChatReplayBlockedByRetryPolicy;
+    /** 钉 IP 直连不能再被请求拦截器挂回代理，并把 IP 留给后续上报。 */
+    private notePinnedChatAttempt;
+    /**
+     * 聊天、图片、视频都上报 wb.api.request，source 按路径区分。
+     * 钉住的 IP 只回落到聊天补全；工具请求不借用聊天那一跳的 pin，也不改写聊天域名记忆。
+     */
+    private reportObservedChatApi;
+    private resolveChatTargetUrl;
+    /**
+     * 读取本次请求地址层钉住的 IP，供 wb.api.request 的 pin 维度使用。
+     * Chat 钉 IP 状态在 CHAT_ADDRESS_SLOT_KEY 上（candidates[index]）；
+     * config.fetch 的最终兜底钉 IP 直接记录在 CONFIG_FETCH_FALLBACK_ADDRESS_KEY。
+     * 两者都没有时返回 undefined（维度归 none，即域名/代理解析路径）。
+     */
+    private readChatPinnedAddress;
+    private replayChatOrigin;
+    /** RestOperations 与 ChatAddressConfig 分属两套 Axios 类型，只在发送边界收窄一次。 */
+    private restRequest;
+    /**
+     * TLS 叶证书失败：从 OS 证书库同步一次。
+     * 手动 Whistle/Charles 走 source=config/env，不能走关校验的 system 分支。
+     * 指纹变了则清 agent 后重试当前请求；未变或 dump 失败则返回 undefined，交给后续逻辑。
+     */
+    private retryAfterOsCaRefresh;
+    /** TLS 证书验证失败（代理可达但 CA 不受信） */
+    private isTlsCertError;
+    /**
+     * CA 刷新自愈路径专用的 TLS 错误判定：{@link isTlsCertError} 的超集。
+     *
+     * 额外覆盖 `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`——MITM 代理根不在本地信任库时
+     * OpenSSL 的典型报错（链上找不到受信签发者）。#127262 场景（装根/换根后发
+     * 消息失败）若命中此码，此前因不在 isTlsCertError 清单内而永不触发 OS CA
+     * 刷新，自愈链路整体失效，只能重启进程。
+     *
+     * 只用于无安全副作用的 CA 刷新重试（{@link retryAfterOsCaRefresh}）；
+     * `disableTlsVerification` 等关校验降级分支继续使用 isTlsCertError，
+     * 不扩大进程级关闭证书校验的触发面。
+     */
+    private isTlsTrustChainError;
+    /** 连接级错误（代理不可达） */
+    private isConnectionError;
+}

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

@@ -0,0 +1,6 @@
+export * from './fetch-proxy';
+export * from './classify-network-error';
+export * from './http-proxy-interceptor';
+export * from './certificate-manager';
+export * from './custom-headers-provider';
+export * from './custom-header-http-interceptor';

package/cli/dist-server/types/node/ide-integration/ide-edit-manager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Manages IDE diff preview and input transformation workflow.
+ * Coordinates between CLI confirmation and IDE editing (race condition).
+ */
+import { Logger } from '@celljs/core';
+import { RunToolApprovalItem } from '../../vendor/cbc-shared/node/index.js';
+import { Session } from '../../vendor/cbc-core/node/index.js';
+export declare const IDEEditManager: unique symbol;
+/** IDE diff preview info stored by IdeEditDiffPanel */
+export interface IDEDiffPreview {
+    tabName: string;
+    idePromise: Promise<{
+        accepted: boolean;
+        finalContent?: string;
+    }>;
+    originalContent: string;
+    proposedContent: string;
+    filePath: string;
+    lineEnding?: 'CRLF' | 'LF' | 'MIXED';
+}
+/** Transformed tool input after IDE editing */
+export interface TransformedToolInput {
+    transformed: boolean;
+    arguments: any;
+    shouldSkip: boolean;
+    error?: string;
+}
+export interface IDEEditManager {
+    /** Store IDE diff preview and monitor result (races with CLI approval) */
+    storeIdeDiffPreview(item: RunToolApprovalItem, preview: IDEDiffPreview, session: Session, onIdeComplete: (accepted: boolean) => void): void;
+    /** Handle CLI approval - close IDE tab and proceed with original args */
+    handleCliApproval(item: RunToolApprovalItem): Promise<void>;
+    /** Handle CLI rejection - close IDE tab and cancel */
+    handleCliRejection(item: RunToolApprovalItem): Promise<void>;
+    /** Check if item has pending IDE preview */
+    hasPendingPreview(item: RunToolApprovalItem | null | undefined): boolean;
+    /** Get transformed tool input (one-time consumption) */
+    getTransformedInput(callId: string): TransformedToolInput | undefined;
+}
+export declare class IDEEditManagerImpl implements IDEEditManager {
+    private ideService;
+    protected readonly logger: Logger;
+    private pendingIdeDiffPreviews;
+    private transformedInputsMap;
+    private completedItems;
+    storeIdeDiffPreview(item: RunToolApprovalItem, preview: IDEDiffPreview, session: Session, onIdeComplete: (accepted: boolean) => void): void;
+    handleCliApproval(item: RunToolApprovalItem): Promise<void>;
+    handleCliRejection(item: RunToolApprovalItem): Promise<void>;
+    getTransformedInput(callId: string): TransformedToolInput | undefined;
+    /** Transform tool arguments based on IDE result */
+    private transformArgumentsBasedOnIdeResult;
+    hasPendingPreview(item: RunToolApprovalItem | null | undefined): boolean;
+}