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

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/wake-detector.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Wake Detector — 防 idle sleep + 系统唤醒检测
+ *
+ * 两个职责：
+ * 1. 防 idle sleep：平台感知，使用各 OS 原生工具阻止系统自动休眠
+ *    - macOS: caffeinate -i -w <pid>（系统自带）
+ *    - Linux: systemd-inhibit（如可用）
+ *    - Windows: powercfg /requestsoverride
+ *    - Fallback: 纯定时器保活
+ *
+ * 2. 唤醒检测：定时器跳跃法（Timer Skew Detection），全平台通用
+ *    每 15 秒检查 Date.now() 与上次检查的差值，超过阈值则判定系统曾休眠。
+ */
+import { Subject } from 'rxjs';
+import { type IWakeDetector } from './daemon-protocol.js';
+export declare class WakeDetectorImpl implements IWakeDetector {
+    private readonly logger;
+    readonly onWake: Subject<{
+        sleepDurationMs: number;
+    }>;
+    private timer;
+    private lastCheck;
+    private inhibitorProcess;
+    start(): void;
+    stop(): void;
+    private startSleepInhibitor;
+    /**
+     * macOS: caffeinate -i -w <pid>
+     * -i: prevent idle sleep
+     * -w <pid>: wait for process to exit (auto-release)
+     */
+    private startMacOSInhibitor;
+    /**
+     * Linux: systemd-inhibit --what=idle --who=codebuddy --why="Daemon running" --mode=block sleep infinity
+     * Wraps `sleep infinity` with an idle-sleep inhibition lock.
+     * Only works on systemd-based distributions.
+     */
+    private startLinuxInhibitor;
+    /**
+     * Windows: powercfg /requestsoverride PROCESS <exe> SYSTEM
+     * Overrides power requests for the named executable.
+     * NOTE: Persistent system-level override, NOT auto-cleared on exit.
+     * stopSleepInhibitor() removes it; if process crashes, override persists.
+     */
+    private startWindowsInhibitor;
+    private stopSleepInhibitor;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @genie/cbc-daemon — CodeBuddy Code Daemon 运行时。
+ *
+ * 目录布局镜像 agent-cli：`src/node/daemon/**` 与拆分前保持一致，git 历史通过 `git mv` 继承。
+ * agent-cli 侧对 `../daemon/*` 相对 import 改为主入口 `@genie/cbc-daemon`；本包内部对
+ * agent-cli 的引用一律走 `@genie/agent-cli/node/<子路径>` 精确 subpath（走 src 源码），
+ * 与 cbc-workflow / cbc-tui / cbc-cron 一致。
+ *
+ * 与 `@genie/agent-cli` 之间允许循环依赖：本包顶层不允许直接消费 agent-cli 运行时值。
+ */
+export * from './daemon/index.js';

package/cli/dist-server/types/workspace/cbc-goal/lib/node/goal/goal-format.d.ts

@@ -0,0 +1,25 @@
+/**
+ * /goal 终态展示用的格式化辅助函数。集中存放是为了让 chat-view 的
+ * GoalResultMessageBox 与 input/panel 的 GoalRecapPanel 共享同一套
+ * "(6s · 1 turn · 12.4k tokens)" 文案，避免视觉漂移。
+ *
+ * 全部纯函数，没有 React / DI 依赖；UI 之外（spec、SDK consumer）也可直接
+ * 引用。
+ */
+/**
+ * Token 数 humanize：
+ *   - <1000：原样展示（如 "437"）
+ *   - >=1000：保留一位小数的 k 单位（如 "12.4k"）
+ *   - >=1_000_000：保留一位小数的 M 单位（防御极端长会话）
+ *
+ * 阈值与 cc 行为对齐——cc 在小数量级仍展示原始值，避免 "0.4k" 这种丢精度文案。
+ */
+export declare function formatGoalTokenCount(tokens: number): string;
+/**
+ * 把 (durationMs, turns, tokens) 渲染为 cc 同款 "(6s · 1 turn · 12.4k tokens)"
+ * 字符串。语义细节：
+ *   - duration: 向上取整到 1 秒，避免在测试 / 极快 case 显示 "0s"
+ *   - turn: 单/复数切换
+ *   - token: 单/复数切换；>=1000 时 humanize 为 "12.4k" 形式
+ */
+export declare function formatGoalStats(durationMs: number, turns: number, tokens: number): string;

package/cli/dist-server/types/workspace/cbc-goal/lib/node/goal/goal-policy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Goal 默认策略层：文案、prompt 模板、scope id 生成。
+ *
+ * 全部为纯逻辑，单测里直接 import 即可断言（不依赖 DI / Service）。
+ * 业务侧若要定制（i18n、品牌词替换、scope 命名规则）可构造自定义
+ * `GoalServicePolicy` 注入到 `GoalServiceImpl.configure()`。
+ */
+import { ActiveGoal, GoalServicePolicy } from './goal-protocol.js';
+/**
+ * 与 cc 二进制中的 stop-condition user message 对齐。
+ *
+ * 设计原因：
+ *   - JSON schema、三态语义、impossible 强约束都已在 evaluator agent 的
+ *     `prompt-hook-evaluator-instructions.tpl` 里集中说明（system prompt），
+ *     user message 只负责把"问题"抛给模型即可——避免与 system prompt 重复
+ *     甚至产生冲突说法（之前两态 vs 三态就出过这种漂移）；
+ *   - 文案与 cc 的 user message 字字对齐："Based on the conversation
+ *     transcript above, has the following stopping condition been satisfied?
+ *     Answer based on transcript evidence only."
+ *   - prompt-hook-service 会自动把 ARGUMENTS JSON 追加到末尾，无需在此手拼。
+ *
+ * 评估窗口约束：当同一 session 在历史上设置过多个 goal 时，旧 goal 的
+ * 成功响应仍留在 transcript 里。如果不告诉模型"评估窗口"，它很容易把
+ * 上一次的 "已完成" 错误地归到当前 goal 头上（实测 deepseek 等网关
+ * 会立即返回 ok=true）。`createdAt` 以 ISO 8601 字符串注入，让 evaluator
+ * 知道从哪个时刻起的对话才算数。
+ */
+export declare function buildStopConditionPrompt(goal: ActiveGoal): string;
+/**
+ * 生成 scope id：`goal:<sessionId>:<nonce>`。
+ *
+ * 加 nonce 后缀是为了让 onResult 回调的"防漂移"判断生效：用户用 `/goal`
+ * 替换当前目标后，旧目标的 hook 评估回调如果延迟到达，能通过对比 scopeId
+ * 识别出"我已经不是当前活跃的目标"并 silently ignore，避免对新目标做副作用。
+ *
+ * nonce 用 8 位 base36 随机数；同进程内冲突概率可忽略。
+ */
+export declare function generateGoalScopeId(sessionId: string): string;
+/**
+ * 构造 `/goal <condition>` 设置完成后立即发送给 agent 的"启动消息"。
+ *
+ * 这条消息会被 GoalServiceImpl.set() fire-and-forget 地通过 agentService.runDefault
+ * 投递，让 agent 立刻开始工作；之后 Stop hook 会在 agent 每次自然停下来时
+ * 评估目标是否达成。
+ *
+ * 文本与 Claude Code `/goal` 的注入 prompt 对齐——本质是一段 system-reminder
+ * 风格的指令（而非普通 user 提问），目的是：
+ *   1. 简短致意 + 立刻开始/继续工作，不要回头问用户做什么；
+ *   2. 把 condition 本身当作"指令"消费；
+ *   3. 解释 stop hook 的 block 语义（不会让你停下来）；
+ *   4. 解释 auto-clear 语义——达成后不要叫用户跑 `/goal clear`，
+ *      那只用于"提前放弃"。
+ */
+export declare function buildGoalKickoffMessage(condition: string): string;
+export declare const DEFAULT_GOAL_POLICY: GoalServicePolicy;

package/cli/dist-server/types/workspace/cbc-goal/lib/node/goal/goal-protocol.d.ts

@@ -0,0 +1,204 @@
+/**
+ * `/goal` 功能的对外契约。
+ *
+ * 与实现 (`goal-service.ts`) 解耦：业务侧只需要依赖本文件的 Symbol + interface
+ * 即可注入并测试，不必拉到具体实现类（DI / mock 都更轻）。
+ *
+ * 模块组织（doctor / memory / checkpoint 同模式）：
+ *   - goal-protocol.ts    Symbol + interface + 数据契约 + 常量
+ *   - goal-policy.ts      纯文案 / prompt 模板 / 默认 policy
+ *   - goal-utils.ts       纯函数：parseActiveGoal / buildGoalPromptHook
+ *   - goal-service.ts     `@Component(GoalService)` 唯一实现
+ *   - goal-session-start-hook.ts SessionStart 路径自动 restore
+ */
+import { PromptHookDefinition } from '../../../../../node/hooks/hook-protocol.js';
+import { Session } from '../../../../cbc-core/lib/node/index.js';
+import { GoalResultItem, PromptHookResult } from '../../../../cbc-shared/lib/node/index.js';
+export declare const GoalService: unique symbol;
+export interface ActiveGoal {
+    condition: string;
+    /** scope id；唯一定位一次 set() 注册的 hook 实例。详见 GoalServicePolicy.scopeIdFor。 */
+    scopeId: string;
+    createdAt: number;
+    /**
+     * goal set 时的 session.usage.totalTokens 快照。
+     * 终态时用 (当前 totalTokens - tokensAtStart) 计算 goal 期间的增量 token，
+     * 与 cc 的 "Goal achieved (… · N tokens)" 语义对齐。
+     * 缺省（旧 session resume 时）按 0 处理 → tokenDelta 退化为 totalTokens。
+     */
+    tokensAtStart?: number;
+    /**
+     * goal 期间已发生的 turn 数（kick-off + 每次 stop-hook 评估算一轮）。
+     * 终态时随 GoalResultItem 一起持久化。
+     * 该字段会被 GoalServiceImpl.setMeta 持久化到 session.meta，
+     * 因此即便跨 hook 回调也能稳定累加。
+     */
+    turnCount?: number;
+    /**
+     * 暂停：卸掉 Stop hook、打断当前回合，保留 condition / createdAt。
+     * 暂停后不再自动续轮。
+     */
+    paused?: boolean;
+    /** 点暂停时的墙钟，用来冻住 elapsed。 */
+    pausedAt?: number;
+}
+export type HostGoalSnapshot = Pick<ActiveGoal, 'condition' | 'createdAt' | 'paused' | 'pausedAt' | 'tokensAtStart' | 'turnCount'>;
+export interface GoalService {
+    /** 从宿主持久状态恢复执行镜像与 hook；不启动回合、不写历史或 session meta 文件。 */
+    /**
+     * 宿主持久态 → CLI 执行镜像。
+     *
+     * `continueRun` 只有宿主的镜像回灌（attach / 换进程自愈）才可为 true：
+     * 动作类请求自己会 abort 或 kickoff，恢复阶段先起一轮会造成反向副作用。
+     */
+    restoreFromHost(session: Session, goal: HostGoalSnapshot | null, options?: {
+        continueRun?: boolean;
+    }): Promise<void>;
+    /**
+     * 交出**某条连接**名下所有会话的宿主权威（连接关闭时调用）。
+     *
+     * 一条连接可以服务多个会话，而关闭事件只带 connectionId——按连接失效才能覆盖全。
+     */
+    releaseHostOwnershipForConnection(connectionId: string): void;
+    /** 登记一条活跃宿主连接（transport 建立时调用，与上面那条对称）。 */
+    registerHostConnection(connectionId: string): void;
+    /** 设定/替换当前 session 的目标。若已有目标则先注销并提示替换。 */
+    set(session: Session, condition: string): Promise<void>;
+    /** 清除当前目标，并注销已注册的 hook。 */
+    clear(session: Session): Promise<void>;
+    /**
+     * 暂停目标：卸 Stop hook、冻计时，并打断当前回合。
+     * 保留目标状态，继续时重新挂 hook。
+     */
+    pause(session: Session): Promise<void>;
+    /**
+     * 继续已暂停的目标：重新注册 hook。
+     * 当前回合还在跑就只恢复续跑；空闲才 kick-off。
+     */
+    resume(session: Session): Promise<void>;
+    /** 显示当前目标。无目标时输出引导文案。 */
+    show(session: Session): Promise<void>;
+    /**
+     * 从 session.meta 中已存的 activeGoal 重新注册 hook（resume 路径）。
+     * 幂等：若 scopeId 已经在 registry 内则跳过。
+     */
+    restoreFromMeta(session: Session): Promise<void>;
+    /** 当前 session 是否有 active goal。 */
+    has(session: Session): boolean;
+    /**
+     * 用 history 里的 goal-status 项兜底恢复 `session.meta.activeGoal`。
+     *
+     * served 会话不落 session-meta，宿主 runtime 换进程后新进程查不到 goal；
+     * 恢复后再走 pause / resume / clear 才是对的语义（否则退化成 no-goal）。
+     */
+    reconcileFromHistory(session: Session): ActiveGoal | undefined;
+    /** 当前 session 的 active goal（仅读 meta，不查 registry）。 */
+    get(session: Session): ActiveGoal | undefined;
+    /**
+     * 取 session.history 中最近一次（按 append 顺序）的 goal-result 终态项。
+     *
+     * 用于无参 `/goal` 的 recap 面板：在没有 active goal 时把最后一次达成 /
+     * 不可达的目标 surface 出来，对齐 cc `/goal` 的 banner 行为
+     * （`✔ Goal achieved` + Goal: + stats，Esc to dismiss）。
+     *
+     * 实现层只读 history、不写副作用——便于 panel 直接订阅。
+     */
+    getLatestResult(session: Session): GoalResultItem | undefined;
+}
+/** condition 字符长度软上限（与 cc 文档对齐：4000 字符）。 */
+export declare const GOAL_CONDITION_MAX_CHARS = 4000;
+/** scopeId 前缀；所有 goal hook 的 scope 都以此打头。 */
+export declare const GOAL_SCOPE_PREFIX = "goal:";
+/** 已知的 goal metric 名（保持与 cc 字面对齐，便于跨工具检索）。 */
+export declare const GOAL_METRICS: {
+    readonly SET: 'tengu_goal_set';
+    readonly CLEARED: 'tengu_goal_cleared';
+    readonly ACHIEVED: 'tengu_goal_achieved';
+    readonly MET: 'goal_met';
+    readonly FAILED: 'tengu_goal_failed';
+    readonly RESTORED: 'tengu_goal_restored_on_resume';
+};
+export type GoalMetricName = typeof GOAL_METRICS[keyof typeof GOAL_METRICS];
+/** Goal metric 发送通道。生产由 service 注入实现，单测可换 spy。 */
+export interface GoalMetricSink {
+    record(name: GoalMetricName, payload?: Record<string, unknown>): void;
+}
+/**
+ * Goal 文案表。集中所有面向用户的英文 string 以便未来 i18n / 个性化。
+ * 都是 `(args) => string` 形式，便于参数化。
+ */
+export interface GoalMessages {
+    usage(): string;
+    tooLong(actual: number, max: number): string;
+    hooksDisabled(): string;
+    cleared(prev: string): string;
+    set(condition: string): string;
+    clearedOnly(prev: string): string;
+    noGoal(): string;
+    active(condition: string): string;
+    paused(condition: string): string;
+    resumed(condition: string): string;
+    achieved(reason?: string): string;
+    impossible(reason?: string): string;
+}
+/**
+ * 可替换的策略层。集中所有可变常量与小算法，便于：
+ *   - 测试时注入 stub policy 控制行为；
+ *   - 未来切换文案 / scope 命名规则 / prompt 模板时不动 service。
+ */
+export interface GoalServicePolicy {
+    maxConditionChars: number;
+    scopeIdFor(sessionId: string): string;
+    /**
+     * 构造发给 stop-condition evaluator 的 user prompt。
+     *
+     * @param goal 当前 active goal（含 condition、createdAt 等上下文）
+     *
+     * 接收整个 goal 而不仅是 condition，是为了让 prompt 能告知 evaluator
+     * "评估窗口"——只看 goal 设置之后的对话，避免被同 session 中上一个 goal
+     * 的成功响应误判（实测在国内 deepseek 等网关上很容易出现"刚 set 完
+     * 立刻 achieved"的现象）。
+     */
+    buildStopConditionPrompt(goal: ActiveGoal): string;
+    /**
+     * 构造 `/goal <condition>` 设置完成后立即下发给 agent 的"启动消息"。
+     *
+     * 设计原因（与 Claude Code 行为对齐）：
+     *   - cc 的 `/goal` 设置后会立即 kick off agent run，而我们之前的实现只
+     *     注册了 Stop hook 等待用户下次输入触发 agent，导致表现"什么都没发生"；
+     *   - 把启动文案抽到 policy，方便 i18n 与单测断言。
+     *
+     * 返回 falsy（''/null/undefined）表示"不要 kick off"——给业务侧（或测试）
+     * 一个关闭自动启动的旁门。
+     */
+    buildKickoffMessage(condition: string): string;
+    messages: GoalMessages;
+}
+/** Hook callback 类型别名，方便 utils 引用。 */
+export type GoalPromptHookCallback = NonNullable<PromptHookDefinition['onResult']>;
+/** 内部使用：onResult 收到的回调入参。 */
+export type GoalPromptHookResult = PromptHookResult;
+/**
+ * `/goal` 命令各种状态文案的"事件类型"枚举。
+ *
+ * 后端 GoalServiceImpl 把每条状态文案 emit 到 history 时同时挂上结构化的
+ * `providerData.goalStatus`，让 Web UI / 其它 ACP 客户端拿到**与 locale
+ * 无关**的事件 + 字段，自己用 i18n 字典渲染本地化文案。
+ *
+ * 列表与 `GoalServicePolicy.messages` 一一对应，方便后续新增字段时机械同步。
+ */
+export type GoalStatusKind = 'usage' | 'too-long' | 'hooks-disabled' | 'set' | 'set-replaced' | 'cleared' | 'no-goal' | 'active' | 'paused' | 'resumed';
+export interface GoalStatusPayload {
+    kind: GoalStatusKind;
+    /** set / set-replaced / active / paused / resumed 携带新条件 */
+    condition?: string;
+    /** set-replaced / cleared 携带被替换/被清除的旧条件 */
+    prev?: string;
+    /** too-long 错误诊断字段 */
+    actual?: number;
+    max?: number;
+    /** set / active / paused 携带 goal.createdAt，给 Web UI 输入框 elapsed 用 */
+    createdAt?: number;
+    /** paused 携带冻结时刻，给 Web UI 冻 elapsed */
+    pausedAt?: number;
+}