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

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

@@ -0,0 +1,192 @@
+import { Subject } from 'rxjs';
+import { z } from 'zod';
+export declare const ChannelManager: unique symbol;
+export declare const ChannelEventService: unique symbol;
+export declare const ChannelPermissionAdapter: unique symbol;
+export declare const ChannelSecurityManager: unique symbol;
+export declare const CHANNEL_NOTIFICATION_METHOD = "notifications/claude/channel";
+export declare const CHANNEL_PERMISSION_REQUEST_METHOD = "notifications/claude/channel/permission_request";
+export declare const CHANNEL_PERMISSION_RESPONSE_METHOD = "notifications/claude/channel/permission";
+export declare const CHANNEL_CAPABILITY_KEY = "claude/channel";
+export declare const CHANNEL_PERMISSION_CAPABILITY_KEY = "claude/channel/permission";
+export declare const ChannelNotificationSchema: z.ZodObject<{
+    method: z.ZodLiteral<"notifications/claude/channel">;
+    params: z.ZodObject<{
+        content: z.ZodString;
+        meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        meta?: Record<string, string> | undefined;
+    }, {
+        content: string;
+        meta?: Record<string, string> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    method: "notifications/claude/channel";
+    params: {
+        content: string;
+        meta?: Record<string, string> | undefined;
+    };
+}, {
+    method: "notifications/claude/channel";
+    params: {
+        content: string;
+        meta?: Record<string, string> | undefined;
+    };
+}>;
+export declare const ChannelPermissionRequestSchema: z.ZodObject<{
+    method: z.ZodLiteral<"notifications/claude/channel/permission_request">;
+    params: z.ZodObject<{
+        request_id: z.ZodString;
+        tool_name: z.ZodString;
+        description: z.ZodString;
+        input_preview: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        tool_name: string;
+        request_id: string;
+        input_preview: string;
+    }, {
+        description: string;
+        tool_name: string;
+        request_id: string;
+        input_preview: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    method: "notifications/claude/channel/permission_request";
+    params: {
+        description: string;
+        tool_name: string;
+        request_id: string;
+        input_preview: string;
+    };
+}, {
+    method: "notifications/claude/channel/permission_request";
+    params: {
+        description: string;
+        tool_name: string;
+        request_id: string;
+        input_preview: string;
+    };
+}>;
+export declare const ChannelPermissionResponseSchema: z.ZodObject<{
+    method: z.ZodLiteral<"notifications/claude/channel/permission">;
+    params: z.ZodObject<{
+        request_id: z.ZodString;
+        behavior: z.ZodEnum<["allow", "allow_always", "deny", "deny_and_exit_plan"]>;
+    }, "strip", z.ZodTypeAny, {
+        behavior: "allow" | "deny" | "allow_always" | "deny_and_exit_plan";
+        request_id: string;
+    }, {
+        behavior: "allow" | "deny" | "allow_always" | "deny_and_exit_plan";
+        request_id: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    method: "notifications/claude/channel/permission";
+    params: {
+        behavior: "allow" | "deny" | "allow_always" | "deny_and_exit_plan";
+        request_id: string;
+    };
+}, {
+    method: "notifications/claude/channel/permission";
+    params: {
+        behavior: "allow" | "deny" | "allow_always" | "deny_and_exit_plan";
+        request_id: string;
+    };
+}>;
+export type ChannelNotification = z.infer<typeof ChannelNotificationSchema>;
+export type ChannelPermissionRequestNotification = z.infer<typeof ChannelPermissionRequestSchema>;
+export type ChannelPermissionResponseNotification = z.infer<typeof ChannelPermissionResponseSchema>;
+export interface ChannelEvent {
+    serverName: string;
+    content: string;
+    meta?: Record<string, string>;
+    timestamp: number;
+}
+export interface ChannelPermissionRequest {
+    requestId: string;
+    toolName: string;
+    description: string;
+    inputPreview: string;
+}
+export interface ChannelPermissionResponse {
+    requestId: string;
+    behavior: 'allow' | 'allow_always' | 'deny' | 'deny_and_exit_plan';
+}
+export interface ChannelServerInfo {
+    serverName: string;
+    hasPermissionRelay: boolean;
+    mcpSession: any;
+    instructions?: string;
+}
+export interface ChannelManager {
+    readonly channelServers: Map<string, ChannelServerInfo>;
+    readonly eventSubject: Subject<ChannelEvent>;
+    /** Emits whenever a channel is registered or unregistered */
+    readonly channelServersSubject: Subject<Map<string, ChannelServerInfo>>;
+    /** Channels specified via --channels CLI flag (available before MCP connects) */
+    readonly allowedChannels: Set<string> | undefined;
+    /** Whether channels feature is enabled (can be disabled via settings) */
+    readonly enabled: boolean;
+    registerChannel(serverName: string, mcpSession: any, capabilities: any, instructions?: string): void;
+    unregisterChannel(serverName: string): void;
+    isChannel(serverName: string): boolean;
+    getPermissionRelayChannels(): ChannelServerInfo[];
+    broadcastPermissionRequest(request: ChannelPermissionRequest): void;
+    /**
+     * 为指定 session 添加 channel 事件到队列（在 ChannelEventService 中调用）
+     */
+    enqueueEventForSession(sessionId: string, event: ChannelEvent): void;
+    /**
+     * 消费并清空指定 session 的所有待处理事件（在 ChannelEventAgentRunInterceptor 中调用）
+     */
+    consumeEventsForSession(sessionId: string): ChannelEvent[];
+    /**
+     * Configure channel filtering from session options (--channels CLI flag)
+     * When set, only listed channels are allowed to register.
+     */
+    configureFromSessionOptions(options: {
+        channels?: string;
+        dangerouslyLoadDevelopmentChannels?: string;
+    }): void;
+    /**
+     * Check if a channel should bypass allowlist checks (--dangerously-load-development-channels)
+     */
+    shouldBypassAllowlist(serverName: string): boolean;
+}
+export interface ChannelEventService {
+    pushEventToSession(event: ChannelEvent): void;
+    /**
+     * 获取并清空指定 session 的待处理 channel 事件
+     * 用于在 agent 拦截器中注入事件
+     */
+    consumeEventsForSession(sessionId: string): ChannelEvent[];
+}
+export interface ChannelPermissionAdapter {
+    createPermissionRequest(toolCallId: string, toolName: string, description: string, inputPreview: string): Promise<'allow' | 'allow_always' | 'deny' | 'deny_and_exit_plan'>;
+    handlePermissionResponse(response: ChannelPermissionResponse): void;
+    cancelRequest(toolCallId: string): void;
+    /**
+     * Query whether a request is still pending in adapter state.
+     * Bridge layers use this to prune stale local request mirrors.
+     */
+    isPendingRequest?(requestId: string): boolean;
+}
+export interface ChannelSecurityManager {
+    /**
+     * Initialize allowlist for a channel, loading from disk if exists
+     */
+    initializeAllowlist(channelName: string): Promise<Set<string>>;
+    /**
+     * Check if a sender is in the channel's allowlist
+     */
+    isAllowedSender(channelName: string, senderId: string): Promise<boolean>;
+    /**
+     * Add a sender to the channel's allowlist and persist to disk
+     */
+    addSender(channelName: string, senderId: string): Promise<void>;
+    /**
+     * Remove a sender from the channel's allowlist
+     */
+    removeSender(channelName: string, senderId: string): Promise<void>;
+}

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

@@ -0,0 +1,12 @@
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+import { ChannelSecurityManager } from './channel-protocol';
+export declare class ChannelSecurityManagerImpl implements ChannelSecurityManager {
+    protected readonly logger: Logger;
+    private allowlists;
+    initializeAllowlist(channelName: string): Promise<Set<string>>;
+    isAllowedSender(channelName: string, senderId: string): Promise<boolean>;
+    addSender(channelName: string, senderId: string): Promise<void>;
+    removeSender(channelName: string, senderId: string): Promise<void>;
+    private saveAllowlist;
+    private getAllowlistPath;
+}

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

@@ -0,0 +1,5 @@
+export * from './channel-protocol';
+export * from './channel-manager';
+export * from './channel-event-service';
+export * from './channel-permission-adapter';
+export * from './channel-security-manager';

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

@@ -0,0 +1,20 @@
+export declare const TuiModeService: unique symbol;
+export interface ITuiModeService {
+    /**
+     * 当前 CLI 进程是否处于交互式 TUI 模式。
+     *
+     * 判据与 `DefaultModeStrategy` 里的 `isInteractive`（cli/strategies/default-mode-strategy.ts:111）
+     * 保持一致：`process.stdout.isTTY && !--print && !--input-format=stream-json &&
+     * !--output-format=stream-json && HEADLESS!==true`。
+     *
+     * 直接live-read `process.argv` —— 与 mcp-ready-service 的 `isHeadless()` 同款做法：
+     * prewarm activate 时 `applyPrewarmArgs` 会重写 process.argv 剔除 --prewarm 并注入
+     * 真实业务 flag，之后再读天然拿到最新值。禁止在构造函数 / @PostConstruct 里
+     * cache 结果（会latch 冷启动空argv，见 CODEBUDDY.md §"env 消费同理"章节的同款
+     * 陷阱）。
+     */
+    isTuiMode(): boolean;
+}
+export declare class TuiModeServiceImpl implements ITuiModeService {
+    isTuiMode(): boolean;
+}

package/cli/dist-server/types/node/code-ratio/cli-git-commit-watcher.d.ts

@@ -0,0 +1,142 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { type ICwdService } from '../../workspace/cbc-worktree/lib/node/index.js';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+/**
+ * CLI 端的 git commit 监听 + 上报。
+ *
+ * 设计要点（对齐 plugin-core 但只做 CLI 必要的部分）：
+ *
+ *   - **多仓**：从 `process.cwd()` 出发发现「全部」git 仓库——
+ *     既兼容「直接打开仓库（或其子目录）」（沿父链向上找 `.git`），
+ *     也兼容「打开一个父目录、其下挂多个独立仓库」（向下有限层扫描）。
+ *     每个仓库各自监听 `.git/logs/HEAD`、各自维护 lastHead、各自上报。
+ *   - 监听 `.git/logs/HEAD`（reflog）：覆盖手动 `git commit` / agent Bash 工具
+ *     发起的 commit / `git commit --amend` / rebase 等所有动 HEAD 的操作。
+ *   - 进程退出前再 flush 一次：CLI 是短命进程，最后一次 commit 完成到 fs.watch
+ *     回调真正触发之间可能有几十 ms 间隙，由 watcher.flushOnExit() 兜底。
+ *   - lastHead 持久化到 `~/.codebuddy/code-ratio/cli-watcher-lastHead-<hash>`（按 repoRoot 区分）：
+ *     CLI 重启后能识别"上次跑完之后又有新 commit"并补上报，避免漏；同时也避免
+ *     启动瞬间把当前 HEAD 当成新 commit 重复报。
+ *   - feature gate 不在 watcher 里判：`reporter.observeCommit()` 已经做过
+ *     `isCodeAdoptionRateEnabled` 检查，运行时切换开关也能立即生效。
+ */
+export declare class CliGitCommitWatcher implements ApplicationLifecycle<Application> {
+    protected readonly productManager?: ProductManager;
+    protected readonly cwdService?: ICwdService;
+    protected readonly prewarmState?: IPrewarmStateService;
+    private logger?;
+    private readonly repos;
+    /** feature gate 是否已判定 enabled 并触发过挂载，保证只挂一次（幂等）。 */
+    private gateResolved;
+    /** 等待 late-enable 的配置订阅（未启用时挂，enabled 后退订）。 */
+    private gateSubscription?;
+    /** cwd 变更订阅（首轮种子值 attach、之后变更重绑）。 */
+    private cwdChangeSubscription?;
+    /** 标记是否已完成首轮 attach，区分种子值与后续 cwd 变更。 */
+    private attachedOnce;
+    private initializationStarted;
+    private activationDeferred;
+    initialize(): void;
+    /**
+     * 入库率 feature gate + late-enable 订阅（对齐 plugin-core GitCommitWatcher）。
+     *
+     * 仓库发现扫描（readdirSync 递归）、watcher attach、startup 扫描的开销都在
+     * feature gate 之后才发生——未启用入库率能力时，进程**完全不做**仓库发现，
+     * 避免预热池默认开启后对错误继承的 home 目录做大量无意义扫描。
+     *
+     * ProductManager 未注册（headless / 单测）时保守退回：直接走 cwd 订阅，
+     * 不阻断原有采集路径。
+     */
+    private mountWhenEnabled;
+    /**
+     * 订阅 cwd 变更，把 attach 绑到最新 cwd（对齐 ConfigWatchService）。
+     *
+     * BehaviorSubject 语义：订阅瞬间即收到「当前 cwd」种子值 → 首轮 attach；
+     * 之后任何 setCwdState（预热 activate 后 chdir、worktree 切换）都会再次推送
+     * → 先 dispose 旧 watcher 再按新 cwd 重新 attach。
+     *
+     * 预热待机期 initialize() 整体延后到 activation，因此订阅时收到的种子值已经是
+     * activate 后的 workspace cwd，不会扫描冷启动继承的 home。
+     *
+     * CwdService 未注册（单测）时退回：直接 attach 一次。
+     */
+    private subscribeCwd;
+    /**
+     * 暴露给 process.ts 的 exit 钩子调用，确保最后一个 commit 不会被丢。
+     * 永不抛错。
+     */
+    flushOnExit(): Promise<void>;
+    /**
+     * 让 Bash 工具的 post-exec hook 在跑完 `git commit` 后立即调一下，
+     * 不必等 reflog 事件。永不抛错。
+     */
+    notifyExternalGitCommit(): Promise<void>;
+    /** 关闭 watcher（测试 / 后续若引入显式 deactivate 时使用）。 */
+    dispose(): void;
+    /**
+     * 关闭并清空所有仓库 watcher/timer，但**不**退订 gate/cwd。
+     * 供 cwd 变更重绑复用（先 disposeWatchers 再 attachAll），dispose() 也调用它。
+     */
+    private disposeWatchers;
+    private attachAll;
+    private attachRepo;
+    private scheduleScan;
+    /**
+     * 读 HEAD → 跟 lastHead 比 → 如果是新 commit 就走 `loadCommit` 上报。
+     *
+     * 若 HEAD↔lastHead 之间相差多个 commit（比如启动时补差量、rebase 后），
+     * 用 `git rev-list lastHead..HEAD` 列出来按时间正序逐个上报，每个都加内存
+     * 去重 + 持久化。失败时不更新 lastHead，下次再尝试。
+     */
+    private checkAndReport;
+    /**
+     * 计算需要上报的 commit 序列，时间正序。
+     *
+     *   - lastHead 缺失：只取 HEAD 一个。
+     *   - lastHead 存在但 git rev-list 失败（被 git gc / rebase 抹掉）：fallback 也只取 HEAD。
+     */
+    private listNewCommits;
+    /**
+     * 上报单个 commit。
+     *
+     * 返回值语义：
+     *   - `true`：成功上报
+     *   - `false`：明确不可归因（merge、initial、无文件、无 repoUrl 等），可安全跳过
+     *   - `'failed'`：上报失败（网络/内部错误），需要保留游标重试
+     */
+    private reportOne;
+    /** 懒加载并缓存某仓库本地 `git config user.email`（归一化后）。读不到返回空串。 */
+    private resolveLocalGitEmail;
+    private trimReportedCache;
+}
+/**
+ * 从 `cwd` 发现需要监听的全部 git 仓库根：
+ *
+ *   1. 先沿父链向上找：若 `cwd` 本身或其某个祖先是 git 仓库，则视为「打开了仓库
+ *      （或其子目录）」，直接返回该唯一根。
+ *   2. 否则向下有限层扫描子目录，把每个 git 仓库根收集出来，命中后剪枝不再深入。
+ *
+ * 实际扫描逻辑复用 `discoverVcsRoots`（git/svn 通用），这里只注入 git 专属判定。
+ */
+export declare function discoverGitRepos(cwd: string, deps?: GitRepoDiscoveryDeps): string[];
+export interface GitRepoDiscoveryDeps {
+    /** 沿父链向上找仓库根；默认用 `findRepoRootFromCwd`。 */
+    findUpRoot?: (startPath: string) => string | undefined;
+    /** 判断某目录是否是 git 仓库根；默认用 `GitInfoExtractor.isGitRepository`。 */
+    isRepo?: (dir: string) => boolean;
+    /** 列出某目录下的直接「子目录绝对路径」；默认走 fs.readdirSync。 */
+    listSubdirectories?: (dir: string) => string[];
+    /** 向下扫描最大深度。 */
+    maxDepth?: number;
+    /** 发现的仓库数量上限。 */
+    maxRepos?: number;
+    /** 诊断回调：把扫描过程打到日志。 */
+    onTrace?: (msg: string) => void;
+}
+/**
+ * 从 cwd 起向上找最近的 git 仓库根。复用 GitInfoExtractor 已有的判定，与
+ * `CwdRepoResolver.findRepoRoot` 行为一致；这里不直接 import 后者，避免
+ * 把 watcher 的可测试性绑死在带状态的 resolver 上。
+ */
+export declare function findRepoRootFromCwd(startPath: string): string | undefined;

package/cli/dist-server/types/node/code-ratio/cli-svn-commit-watcher.d.ts

@@ -0,0 +1,111 @@
+import { Application, ApplicationLifecycle } from '@celljs/core';
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { type ICwdService } from '../../workspace/cbc-worktree/lib/node/index.js';
+/**
+ * CLI 端的 svn commit 监听 + 上报。
+ *
+ * 设计要点：
+ *
+ *   - **多仓**：从 `process.cwd()` 出发发现「全部」svn 工作副本——
+ *     既兼容「直接打开工作副本（或其子目录）」（沿父链向上找 `.svn`），
+ *     也兼容「打开一个父目录、其下挂多个独立工作副本」（向下有限层扫描）。
+ *     每个工作副本各自 `fs.watch(.svn/wc.db)`、各自维护 lastRevision、各自上报。
+ *   - 监听 `.svn/wc.db`：svn commit/update 都会动这个文件。
+ *   - lastRevision 持久化到 `~/.codebuddy/code-ratio/cli-svn-watcher-lastRev-<hash>`，
+ *     按 repoRoot 区分，CLI 重启后补差量、避免重复上报。
+ *   - 用户身份过滤交给 `getLikelyCurrentSvnUserCandidates` / `isLikelyCurrentUser`，
+ *     按各仓库 URL 分别匹配 auth realm，「未知身份不放行」避免 svn update 误报。
+ *   - feature gate 不在 watcher 里判：`reporter.observeCommit()` 已做检查。
+ */
+export declare class CliSvnCommitWatcher implements ApplicationLifecycle<Application> {
+    protected readonly productManager?: ProductManager;
+    protected readonly cwdService?: ICwdService;
+    private logger?;
+    private readonly repos;
+    /** feature gate 是否已判定 enabled 并触发过挂载，保证只挂一次（幂等）。 */
+    private gateResolved;
+    /** 等待 late-enable 的配置订阅（未启用时挂，enabled 后退订）。 */
+    private gateSubscription?;
+    /** cwd 变更订阅（首轮种子值 attach、之后变更重绑）。 */
+    private cwdChangeSubscription?;
+    /** 标记是否已完成首轮 attach，区分种子值与后续 cwd 变更。 */
+    private attachedOnce;
+    initialize(): void;
+    /**
+     * 入库率 feature gate + late-enable 订阅（对齐 git watcher / plugin-core）。
+     *
+     * 未启用入库率能力时**完全不做** svn 工作副本发现扫描 / watcher / 轮询定时器，
+     * 避免预热池默认开启后对错误继承的 home 目录做大量无意义扫描。
+     * ProductManager 未注册（headless / 单测）时保守退回：直接走 cwd 订阅。
+     */
+    private mountWhenEnabled;
+    /**
+     * 订阅 cwd 变更，把 attach 绑到最新 cwd（对齐 ConfigWatchService）。
+     * 首轮种子值 attach、之后 cwd 变更先 dispose 旧 watcher 再按新 cwd 重新 attach。
+     * CwdService 未注册（单测）时退回：直接 attach 一次。
+     */
+    private subscribeCwd;
+    /**
+     * 是否仍处于预热（prewarm）待机态：argv 含 `--prewarm` 且 PrewarmServer 状态
+     * 为 `idle`（尚未收到 activate）。详见 git watcher 同名方法的说明。
+     *
+     * 待机时跳过首轮 attach，等 activate 后 dispatcher 的 cwd 广播（状态已转为
+     * activating）再绑定，避免对错误继承的 home 做工作副本发现扫描。
+     */
+    private isPrewarmStandby;
+    flushOnExit(): Promise<void>;
+    notifyExternalSvnCommit(): Promise<void>;
+    dispose(): void;
+    /**
+     * 关闭并清空所有工作副本 watcher/timer，但**不**退订 gate/cwd。
+     * 供 cwd 变更重绑复用（先 disposeWatchers 再 attachAll），dispose() 也调用它。
+     */
+    private disposeWatchers;
+    private attachAll;
+    private attachRepo;
+    private scheduleScan;
+    private checkAndReport;
+}
+export interface SvnDiscoveryDeps {
+    /** 沿父链向上找工作副本根；默认用 `findSvnWorkingCopyRoot`。 */
+    findUpRoot?: (startPath: string) => string | undefined;
+    /** 判断某目录是否是 svn 工作副本根；默认用 `isSvnWorkingCopy`。 */
+    isWorkingCopy?: (dir: string) => boolean;
+    /** 列出某目录下的直接「子目录绝对路径」；默认走 fs.readdirSync。 */
+    listSubdirectories?: (dir: string) => string[];
+    /** 向下扫描最大深度。 */
+    maxDepth?: number;
+    /** 发现的工作副本数量上限。 */
+    maxRepos?: number;
+    /** 诊断回调：把扫描过程打到日志。 */
+    onTrace?: (msg: string) => void;
+}
+/**
+ * 从 `cwd` 发现需要监听的全部 svn 工作副本根：
+ *
+ *   1. 先沿父链向上找：若 `cwd` 本身或其某个祖先是工作副本，则视为「打开了工作
+ *      副本（或其子目录）」，直接返回该唯一根（其下子目录都属于同一个 wc）。
+ *   2. 否则向下有限层扫描子目录，把每个含 `.svn` 的目录当成独立工作副本根，
+ *      命中后剪枝不再深入（兼容 svn 1.7+「整棵 wc 只有顶层一个 .svn」的布局，
+ *      也避免把 1.6 时代每级目录的 .svn 误判成多个仓库）。
+ *
+ * 纯函数 + 依赖注入，便于单测，不直接耦合真实 fs。
+ */
+export declare function discoverSvnWorkingCopies(cwd: string, deps?: SvnDiscoveryDeps): string[];
+interface SvnUserCandidateOptions {
+    env?: NodeJS.ProcessEnv;
+    repoUrls?: Array<string | undefined>;
+    authCacheDirs?: string[];
+    readDir?: (dirPath: string) => string[];
+    readFile?: (filePath: string) => string;
+}
+/**
+ * 计算当前 SVN 用户候选集。不再与操作系统登录用户绑定：
+ *   - 显式环境变量 `SVN_USER` / `SVN_USERNAME`；
+ *   - SVN auth cache（`~/.subversion/auth/svn.simple/*` 或 Windows `%APPDATA%`），
+ *     按当前仓库 URL 匹配 realm 后取 username。
+ * 读不到任何身份时返回空数组，调用方据此「未知身份不放行」，避免 svn update 误报。
+ */
+export declare function getLikelyCurrentSvnUserCandidates(options?: SvnUserCandidateOptions): string[];
+export declare function isLikelyCurrentUser(author: string | undefined, currentUserCandidates?: string[]): boolean;
+export {};

package/cli/dist-server/types/node/code-ratio/code-ratio-reporting-service.d.ts

@@ -0,0 +1,90 @@
+import { Session } from '../../vendor/cbc-core/node/index.js';
+import { CodeRatioReporter } from '../../workspace/code-ratio/lib/common/index.js';
+import { CodeRatioRepoResolver } from './vcs-repo-resolver';
+/**
+ * Service token for the CLI-side code-ratio reporting helper.
+ *
+ * Editor tools depend on this token instead of the raw `CodeRatioReporter`
+ * so they don't need to know how to resolve VCS context, map ChangeType
+ * values or swallow reporter errors. All of that lives here.
+ */
+export declare const CodeRatioReportingService: unique symbol;
+/**
+ * Minimal, CLI-friendly parameters for the edit tools' code-ratio
+ * reporting hook. Tools already have these values on hand after
+ * successfully applying an edit, so building the input is a one-liner.
+ */
+export interface EditChangeReport {
+    /** Absolute path of the file that was just written / edited. */
+    absoluteFilePath: string;
+    /** File content before the edit (empty string for new files). */
+    originalContent: string;
+    /** File content after the edit. */
+    newContent: string;
+    /** Whether this edit created a new file (drives ChangeType). */
+    isNewFile: boolean;
+    /** Tool name (e.g. `Write`, `Edit`, `MultiEdit`, `NotebookEdit`). */
+    toolName?: string;
+    /** Tool call identifier, if available from the agent runtime. */
+    toolCallId?: string;
+    /** Session context, used to derive conversationId / modelId / traceId. */
+    session?: Session;
+}
+/**
+ * CLI-side code-ratio reporting helper.
+ *
+ * Contract: calling `reportEditChange` never throws, never blocks the
+ * edit flow and never affects the tool's return value. Any failure
+ * (missing reporter, non-git workspace, VCS metadata incomplete, etc.)
+ * is logged at debug level and silently dropped.
+ */
+export interface CodeRatioReportingService {
+    /**
+     * Report an AI-authored file change (Write / Edit / MultiEdit /
+     * NotebookEdit / NotebookWrite). Safe to call unconditionally after a
+     * successful file write.
+     */
+    reportEditChange(report: EditChangeReport): void;
+}
+/**
+ * Default implementation. The reporter and resolver are looked up
+ * through the cell container rather than enforced through strict DI,
+ * because `@genie/code-ratio` is an optional peer dependency: builds
+ * that don't bundle it (or tests that don't register it) must still
+ * be able to instantiate the editor tools.
+ *
+ * Constructor arguments exist purely for unit tests; production code
+ * relies on the cell container resolution below.
+ */
+export declare class CodeRatioReportingServiceImpl implements CodeRatioReportingService {
+    protected readonly repoResolver?: CodeRatioRepoResolver;
+    private logger?;
+    private reporterProvider;
+    /**
+     * NOTE: must remain parameter-less.
+     *
+     * 早期版本曾把 unit-test overrides 通过构造函数对象参数注入，触发了一个
+     * 隐蔽的 cell/inversify bug：`@Component` 装饰会让 TS emit
+     * `design:paramtypes` 元数据，把 `overrides?: { ... }` 的对象类型擦成
+     * `Object`；cell 容器实例化时会按 paramtypes 在容器里查找 `Object` 的
+     * 绑定，由于不存在，统一抛出
+     *   "No matching bindings found for serviceIdentifier: Object"
+     * 该错误从 ApplicationLifecycle 一路冒泡，导致整个 CLI 启动失败。
+     *
+     * 修复：constructor 改为无参，单测改用 {@link configureForTesting}
+     * 注入测试桩，从而**完全不让 paramtypes 元数据被生成**。
+     */
+    constructor();
+    /**
+     * Test-only seam. Production code must not call this.
+     *
+     * 不通过 constructor 注入是为了避免 cell 装饰器生成 `design:paramtypes`
+     * 元数据，把测试用的 overrides 对象类型当成 IoC 依赖（详见 constructor
+     * 注释里的 bug 历史）。
+     */
+    configureForTesting(overrides: {
+        repoResolver?: CodeRatioRepoResolver;
+        reporterProvider?: () => CodeRatioReporter | undefined;
+    }): void;
+    reportEditChange(report: EditChangeReport): void;
+}

package/cli/dist-server/types/node/code-ratio/fs-file-reader.d.ts

@@ -0,0 +1,26 @@
+import { CodeRatioFileReader } from '../../workspace/code-ratio/lib/common/index.js';
+/**
+ * CLI-side implementation of CodeRatioFileReader.
+ *
+ * The five editor tools (write / edit / multi-edit / notebook-edit /
+ * notebook-write) already have `originalContent` in hand when they call
+ * into the reporter, so this reader is a defensive fallback: the
+ * reporter itself will invoke it only when the caller omits `oldContent`.
+ *
+ * Input is a POSIX, repo-relative path (per the protocol). We resolve it
+ * against the current repo root (provided by CodeRatioRepoResolver) and
+ * read through `FileUtils.readFileWithEncodingDetection`, which reuses
+ * the same encoding detection that the edit tools use for writing, so
+ * the old/new content pair stays byte-comparable for diffing.
+ *
+ * Failure policy: any error (missing resolver, path outside the repo,
+ * file does not exist, permission denied, encoding failure, ...) is
+ * swallowed and `undefined` is returned. The reporter then treats it as
+ * `invalid-input` and skips the upload, never breaking the tool flow.
+ */
+export declare class FsFileReader implements CodeRatioFileReader {
+    private logger?;
+    constructor();
+    readFile(filePath: string): Promise<string | undefined>;
+    private resolveAbsolute;
+}

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

@@ -0,0 +1,5 @@
+export * from './vcs-repo-resolver';
+export * from './fs-file-reader';
+export * from './code-ratio-reporting-service';
+export * from './cli-git-commit-watcher';
+export * from './cli-svn-commit-watcher';

package/cli/dist-server/types/node/code-ratio/vcs-repo-resolver.d.ts

@@ -0,0 +1,51 @@
+import { CodeRatioRepoContext, CodeRatioRepoResolver } from '../../workspace/code-ratio/lib/common/index.js';
+export { CodeRatioRepoContext, CodeRatioRepoResolver, toPosixRelative } from '../../workspace/code-ratio/lib/common/index.js';
+export interface VcsRoot {
+    repoRoot: string;
+    vcsType: NonNullable<CodeRatioRepoContext['vcsType']>;
+}
+/**
+ * CLI-native implementation of CodeRatioRepoResolver.
+ *
+ * Unlike agent-craft which can lean on the vscode git extension via
+ * VCSManager, the CLI only has filesystem access. We walk up from the
+ * given absolute file path to locate the nearest `.git` directory and
+ * read remote/branch info through GitInfoExtractor (already used by the
+ * existing VCSEventProcessor, so behavior stays consistent).
+ *
+ * Results are cached per repo root with a 5-minute TTL, matching the
+ * cache strategy of VCSEventProcessor.
+ */
+export declare class CwdRepoResolver implements CodeRatioRepoResolver {
+    private readonly cache;
+    private logger?;
+    constructor();
+    resolve(absoluteFilePath: string): CodeRatioRepoContext | undefined;
+    getCurrentRepoRoot(): string | undefined;
+    private getRepoEntry;
+    private readGitRepoEntry;
+    private readSvnRepoEntry;
+}
+/**
+ * Walk upwards from `startPath` looking for the nearest VCS working copy.
+ *
+ * SVN is checked alongside Git at every directory level instead of falling
+ * back after Git lookup. This matters when an SVN working copy lives inside a
+ * Git-managed parent directory: codeDiff must use `vcsType=svn` for files in
+ * that working copy rather than inheriting the outer Git repository.
+ *
+ * Exported for unit testing.
+ */
+export declare function findVcsRoot(startPath: string): VcsRoot | undefined;
+/**
+ * Git-only compatibility helper retained for existing tests/callers.
+ */
+export declare function findRepoRoot(startPath: string): string | undefined;
+/**
+ * Strip credentials from a git remote URL. Mirrors the logic used by
+ * VCSEventProcessor so that both paths produce identical `repoUrl`
+ * values downstream.
+ *
+ * Exported for unit testing.
+ */
+export declare function clearSensitiveData(gitUrl: string): string;