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

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;
+}

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

@@ -0,0 +1,353 @@
+/**
+ * `/goal` 命令背后的 service 实现。
+ *
+ * Claude Code 官方文档定义：
+ * > The /goal command is a built-in shortcut for a session-scoped
+ * > prompt-based Stop hook.
+ *
+ * 实现思路：
+ *  - `/goal <condition>` 通过 ScopedHookRegistry 注册一个 prompt-type Stop hook，
+ *    scopeId 由 `policy.scopeIdFor(sessionId)` 生成（含 nonce 防漂移），
+ *    并把 `condition` 与 scopeId 写入 `session.meta.activeGoal`。
+ *  - hook 评估返回 `{ok:true}` 则模型自然停止，输出 "Goal achieved"，自动注销。
+ *  - 评估返回 `{ok:false}` 则 hook 返回 block + continueRequest，模型继续工作。
+ *  - 评估返回 `{ok:false, impossible:true}` 则视作"目标不可达"，停止循环，
+ *    输出 "Goal could not be achieved: <reason>"，自动注销。
+ *  - 通过 PromptHookDefinition.onResult 回调订阅评估结果。
+ *
+ * 设计点（可维护性 / 可测试性）：
+ *  - 所有契约都从 `goal-protocol` 引入，方便业务侧只依赖 Symbol + interface。
+ *  - 所有 mutable 副作用都封装在 protected 方法，便于子类化定制 / spy。
+ *  - `configure({ policy, metrics })` 注入测试替身，无需绕开 DI。
+ *  - onResult 回调先校验 `current.scopeId === goal.scopeId`，避免对早已被
+ *    替换或清除的 goal 做副作用。
+ */
+import { AcpBroadcastService } from '../../../../../node/acp/acp-protocol.js';
+import { AcpDrainTrigger } from '../../../../../node/agent-task/agent-task-protocol.js';
+import { HookInput, PromptHookDefinition, ScopedHookRegistry } from '../../../../../node/hooks/hook-protocol.js';
+import { AgentService, MessageQueueManager, NotificationInjectionBuffer, Session, SessionManager } from '../../../../cbc-core/lib/node/index.js';
+import { GoalResultItem, PromptHookResult } from '../../../../cbc-shared/lib/node/index.js';
+import { Logger } from '../../../../telemetry/lib/common/index.js';
+import { ActiveGoal, GoalMetricSink, GoalService, GoalServicePolicy, GoalStatusPayload, type HostGoalSnapshot } from './goal-protocol.js';
+export declare class GoalServiceImpl implements GoalService {
+    protected readonly logger: Logger;
+    protected readonly scopedHookRegistry: ScopedHookRegistry;
+    protected readonly sessionManager: SessionManager;
+    /**
+     * AgentService 用 @Optional() 注入：
+     *   - 单测里我们不挂 AgentService（kick-off 可被 stub 关闭）；
+     *   - headless / 异常 IoC 场景下没有 AgentService 时 set() 仍然能完成
+     *     hook 注册，只是不会自动 kick off。
+     */
+    protected readonly agentService?: AgentService;
+    protected readonly acpBroadcastService?: AcpBroadcastService;
+    /**
+     * ACP / Web UI 的 kick-off 不能直接 runDefault：那条 run 没有
+     * createEventForwardingPromise 覆盖事件转发，思考/工具到不了前端，输入框也会一直
+     * 停在 running。**由谁起这一轮**按模式分：
+     *   - Mode A：进 session.queue，等 AcpView 的 drain 带转发消费；
+     *   - Mode B：session.queue 只归 rich queue 镜像，drain 读的是注入缓冲，所以
+     *     kick-off 也走缓冲（与后台通知同一投递通道，见 BackgroundTaskNotifier）。
+     */
+    protected readonly messageQueueManager?: MessageQueueManager;
+    /**
+     * Mode B（deferred dispatch）下 `session.queue` 是 rich queue 的展示镜像，ACP 的
+     * drain 只读注入缓冲（#89130）。目标 kick-off 是「无宿主 prompt 也要自己起一轮」的
+     * 系统注入项，与后台通知同构，因此 Mode B 走同一个缓冲，靠 AcpDrainTrigger 投递。
+     */
+    protected readonly notificationBuffer?: NotificationInjectionBuffer;
+    /**
+     * HTTP PUT / 暂停后继续 走 GoalService 时，当前并不在 AcpView.executePrompt 里，
+     * 只入队没有人 drain。注入 AcpDrainTrigger，把 kick-off 送进带转发的 drain。
+     */
+    protected readonly acpDrainTrigger?: AcpDrainTrigger;
+    /**
+     * 可注入的策略层。生产用 `DEFAULT_GOAL_POLICY`；测试可通过 configure() 替换。
+     * 故意 protected 而非 private，方便子类化做小幅定制。
+     */
+    protected policy: GoalServicePolicy;
+    /** 进行中的 Stop hook 对象，pause 时要就地关掉续跑。 */
+    protected readonly goalHooks: Map<string, PromptHookDefinition>;
+    /**
+     * 宿主权威登记：session → 登记时的宿主连接 id（会话当时没有连接 id 记空串）。
+     *
+     * 用 WeakMap 而不是 WeakSet：连接关闭时 AcpServer 只拿得到 connectionId，
+     * 靠它一次性失效该连接名下的所有 session，不必枚举会话表。
+     */
+    private readonly hostOwnedSessions;
+    /**
+     * 处于「活跃」状态的宿主连接 id（AcpServer 在 transport 建立时登记、关闭时删除）。
+     *
+     * 用活跃集合而不是「已关闭集合」：后者只进不出（--serve 长驻下无界增长），
+     * 而且 connectionId 复用（stdio-main 这种固定名）时旧记录会把新连接误判成已关闭。
+     */
+    private readonly liveHostConnections;
+    /**
+     * history 里从未出现过「决定性 goal 状态项」的会话：跳过每轮 prompt 的 O(n) 倒扫。
+     * 任何一次 goal 状态写入（setMeta / emit）都会失效该缓存。
+     */
+    private readonly noGoalHistorySessions;
+    /** 可注入的 metric 发送器；默认走 logger。 */
+    protected metrics: GoalMetricSink;
+    protected init(): void;
+    /** 测试钩子：替换 policy / metrics（例：service.configure({ policy: stub })). */
+    configure(opts: Partial<{
+        policy: GoalServicePolicy;
+        metrics: GoalMetricSink;
+    }>): void;
+    /**
+     * 宿主持久态 → CLI 执行镜像。
+     *
+     * @param options.continueRun 目标处于运行态且本进程无回合时，是否立刻续跑一轮。
+     *   **只有宿主的镜像回灌（attach / 换进程自愈）才允许为 true**：动作类请求（pause /
+     *   clear / set / resume）自己会 abort 或 kickoff，若在恢复阶段先投一轮，就会出现
+     *   「点暂停前先起一轮」「换条件用旧条件起一轮」这类反向副作用。
+     */
+    restoreFromHost(session: Session, snapshot: HostGoalSnapshot | null, options?: {
+        continueRun?: boolean;
+    }): Promise<void>;
+    /**
+     * 宿主权威判定：登记过宿主回灌，且登记时那条宿主连接**仍活跃**。
+     *
+     * 「宿主权威」= 宿主持久态是唯一真源，CLI 只维护执行镜像，因此 persistMeta
+     * 不对该 session 落盘——写了会与宿主抢权威，下次回灌又被打回去。
+     *
+     * 生命周期两端（各只有一条路径）：
+     *   - 进：restoreFromHost（记住当时的 meta.acpConnectionId 作为 owner；拿不到连接
+     *     身份**不登记**——没有连接可判定存活就等于没有出口）；
+     *   - 出：releaseHostOwnershipForConnection（该连接名下的所有 session，AcpServer
+     *     在连接关闭时调用，正常与异常关闭都走）。
+     *
+     * 为什么不能只看 meta.acpConnectionId 是否存在：那个字段在连接关闭后不会被清
+     * （acp-view 只在绑定时写），无法表达「已交出权威」。为什么不能只靠一个 session
+     * 集合：一条连接可以服务多个会话，连接关闭时只放一个会让其余的永久失效。
+     */
+    protected isHostOwned(session: Session): boolean;
+    /**
+     * 该会话是否走**结构化控制**语义（宿主 / Web UI 通过控制通道驱动，而不是用户手打 prompt）。
+     *
+     * 与「宿主权威」（isHostOwned：只在宿主回灌过快照之后为真）刻意分开：同条件 set=resume、
+     * 编辑 / 清除打断在途回合这些都属控制通道语义，**不带快照的旧 core 或第三方 ACP 同样适用**；
+     * 拿 isHostOwned 当判据会让它们落回「cleared + set」（计时清零、换 hook），与
+     * acp-goal-control 里「控制通道自己判同条件 set=resume」的承诺分叉。
+     */
+    protected isStructuredControlSession(session: Session): boolean;
+    /**
+     * 该 session 是否仍挂着一条「没被报告关闭」的宿主连接。
+     *
+     * 未登记过连接 id 的会话按「活」处理：宁可乐观，也不要在信息不足时把宿主能力关掉。
+     */
+    protected hasLiveHostConnection(session: Session): boolean;
+    /**
+     * 登记一条活跃的宿主连接（AcpServer 在 transport 建立时调用）。
+     *
+     * 与 releaseHostOwnershipForConnection 对称：id 复用时新连接重新登记，
+     * 不会因为旧记录被误判成「已关闭」。
+     */
+    registerHostConnection(connectionId: string): void;
+    /**
+     * 交出**某条连接**名下所有会话的宿主权威。
+     *
+     * 连接关闭时 AcpServer 只拿得到 connectionId（它并不知道这条连接服务过哪些会话），
+     * 因此失效按连接做：登记时记 owner，这里把 owner 标成已关闭 —— `isHostOwned`
+     * 随后对该连接的每个 session 都返回 false。
+     */
+    releaseHostOwnershipForConnection(connectionId: string): void;
+    /**
+     * 宿主持快照恢复后：目标处于运行态且本进程没有在跑的回合时，立刻续跑一轮。
+     *
+     * 为什么必须在恢复路径上续跑：WorkBuddy 运行时刷新会因 env 指纹变化重启 worker
+     * （实测 runtime refresh requires worker restart → killWorker），把刚起的那一轮连同
+     * kick-off 一起杀掉；只在动作时 kick-off 的话，用户看到的就是「条在跑、对话不动」。
+     * 宿主持久态说目标在跑，新进程就该把它接着跑起来。
+     */
+    protected continueRunIfIdle(session: Session): Promise<void>;
+    set(session: Session, condition: string): Promise<void>;
+    clear(session: Session): Promise<void>;
+    pause(session: Session): Promise<void>;
+    resume(session: Session): Promise<void>;
+    show(session: Session): Promise<void>;
+    restoreFromMeta(session: Session): Promise<void>;
+    has(session: Session): boolean;
+    get(session: Session): ActiveGoal | undefined;
+    /**
+     * 用 history 里的 goal-status 项把 activeGoal 恢复到 `session.meta`。
+     *
+     * 为什么需要：**served 会话不落 session-meta**（见 cbc-core session-store 的
+     * "served sessions never write"），而 WorkBuddy 的 runtime 会随插件刷新 / 回收换进程。
+     * 新进程的 `session.meta` 里没有 activeGoal，于是「进行中 / 已暂停」的目标在新进程里
+     * 查无此物：点继续 / 清除退化成 no-goal，刷新重开也恢复不出状态条。
+     * history 里的 goalStatus 项是持久真源，语义与 Web UI 的 activeGoalAfterStatus 一致。
+     *
+     * 幂等：派生结果与 meta 一致则原样返回；只有条件 / 暂停态变化才覆盖并补注册 hook。
+     */
+    /**
+     * @remarks 有副作用：会写 session.meta（setMeta / clearMeta）、按需落盘、按需挂 Stop hook。
+     *
+     * 从 history 的 goal-status 项重建 activeGoal。**有副作用，不是纯查询**：
+     * 会 setMeta / clearMeta、按需 persistMeta，并在目标续跑中时补挂 Stop hook。
+     *
+     * 返回三态（与 deriveGoalFromHistory 的入参语义对齐）：
+     *   - 目标对象：镜像与 history 一致（或已按 history 重建）；
+     *   - undefined：history 里没有 goal 状态项 + 当前也没有目标（保持现状）；
+     *   - undefined（同上）：history 明确 cleared 且当前无目标 —— 两种 undefined 对调用方
+     *     的表现一致（都表现为「无目标」），因此不再额外区分类型。
+     */
+    reconcileFromHistory(session: Session): ActiveGoal | undefined;
+    /**
+     * 从 history 末尾往回找最近一条**决定性**的 goal-status 项：
+     *   - `set` / `active` / `resumed` → 目标存在且未暂停
+     *   - `paused` → 目标存在且暂停
+     *   - `cleared` / `no-goal` → 没有目标
+     *   - 其它（set-replaced / too-long / usage …）不改变状态，继续往前找
+     * 返回 undefined = history 里根本没有 goal 状态项。
+     */
+    protected deriveGoalFromHistory(session: Session): GoalFromHistory | null | undefined;
+    /**
+     * 倒序扫 session.history 找最近一条 goal-result 终态项。复杂度 O(n)，
+     * goal 终态项稀疏（一次 /goal 周期才一条），实测开销可忽略。
+     *
+     * 注意：history 直接持有 AgentInputItem 引用，调用方不应就地修改。
+     * 这里 cast 为 GoalResultItem——`type === 'goal-result'` 已是判别量。
+     */
+    getLatestResult(session: Session): GoalResultItem | undefined;
+    protected registerGoalHook(session: Session, goal: ActiveGoal): void;
+    protected unregisterHook(scopeId: string): void;
+    protected persistMeta(session: Session): Promise<void>;
+    protected setMeta(session: Session, goal: ActiveGoal): void;
+    protected clearMeta(session: Session): void;
+    protected areHooksDisabled(): boolean;
+    /**
+     * `set()` / 续跑完成后的"启动目标第一轮"副作用。
+     *
+     * 抽成独立 protected 方法的好处：
+     *   - 单测可以 spy / stub 它，断言 set() 是否在正确时机触发；
+     *   - 后续更换投递通道时不动 set()。
+     *
+     * 实现细节：
+     *   - 走 policy 拿启动文案（i18n / 业务定制点）；
+     *   - 把 kick-off 消息标记为 `providerData.isMeta=true`，与 cc 行为对齐：
+     *     模型在 transcript 里能看到目标条件，但 UI 不渲染这条 user message
+     *     （`conversation-box.tsx` / `queue-display.tsx` / `structured-output-view-filter`
+     *      均按 isMeta 过滤），也不会进输入框上方的「运行中命令」条
+     *     （`InputItemUtils.isEditableQueuedMessage` 把 isMeta 判为不可编辑）。
+     *   - **这一轮完全归 CLI 自己起**：宿主（WorkBuddy / Web UI）只发结构化控制方法，
+     *     不会再补发任何合成本文 prompt 来"承载"目标轮（合成 prompt 会冒充用户消息，
+     *     画假气泡）。因此这里必须把 kick-off 送到**带事件转发的 drain 通道**上，
+     *     由 AcpView 起轮，思考/工具/产出才到得了宿主的 ACP 连接。
+     *   - 走 @Optional 注入的 AgentService，若不可用（headless 极简栈 / 单测）
+     *     则跳过 + warn，set() 仍然完成，hook 仍然注册；
+     *   - fire-and-forget；任何异常落 logger，不冒泡到调用方。
+     */
+    protected kickoffAgentRun(session: Session, condition: string): Promise<void>;
+    /**
+     * `/goal` slash 自己的 skipRun 窗口。AgentService.run() 先 RUN_PREPARING
+     * 再进命令拦截器，这时 abort 会掐掉正在执行的这次 slash，随后 triggerDrain
+     * 被 aborted 守卫丢掉——Web UI 手打 `/goal` 换条件会自伤。
+     */
+    private static readonly SLASH_OWNED_STATUSES;
+    protected isRunInFlight(session: Session): boolean;
+    protected abortInFlightRun(session: Session): void;
+    protected ensureAbortControllerReady(session: Session): void;
+    protected replaceAbortController(session: Session): void;
+    /**
+     * 读取 session.usage.totalTokens 作为统计起点 / 终点。
+     * - usage 字段在 fresh session 上是 Usage 实例（含 totalTokens 数值）。
+     * - 单测 / 老 session 上 usage 可能不存在，按 0 处理避免 NaN。
+     */
+    protected readSessionTokens(session: Session): number;
+    /**
+     * 给当前 active goal 累加 turn 计数并持久化到 session.meta。
+     * 防漂移：找不到 goal（已被替换 / 清除）时静默忽略。
+     */
+    protected bumpTurnCount(session: Session, delta: number): void;
+    /**
+     * 把 stdout 文本以 local-command-stdout 形式写入 session.history。
+     *
+     * `status` 参数可选：当 emit 的是 /goal 状态文案（set / cleared / active 等）
+     * 时，调用方传入结构化 GoalStatusPayload。该 payload 会写到
+     * `providerData.goalStatus`，让 ACP 转换层把它转成 `session_info_update +
+     * _meta` 推 Web UI 用 i18n 渲染（Web UI 不依赖英文文本格式）；TUI 仍按
+     * stdout 原样渲染英文文案，与 cc parity 保持一致。
+     */
+    protected emit(session: Session, text: string, status?: GoalStatusPayload): Promise<void>;
+    /**
+     * Prompt hook 的 onResult 回调。
+     * 注意：hook-manager 已经处理了 block / continueRequest 逻辑；这里只负责
+     *   - 在 ok:true（达成）和 impossible（不可达）两种「终态」时清理 hook + UI 提示
+     *   - ok:false（条件还没满足）维持现状，模型仍被 block 着工作
+     *
+     * 防御性：回调可能在用户已经手动 `/goal clear` 或替换为新 goal 之后才异步
+     * 触发，这种情况下不应对当前 session.meta 做副作用。
+     */
+    protected handleHookResult(session: Session, goal: ActiveGoal, result: PromptHookResult, _input: HookInput): Promise<void>;
+    /**
+     * 把 stop-hook evaluator 的 reason 反馈给模型（cc parity）。
+     *
+     * 设计要点：
+     *   - 只在 reason 非空时 emit——空 reason 喂给模型只是噪声；
+     *   - 文本格式与 cc jsonl 严格对齐："Stop hook feedback: [<condition>]: <reason>"
+     *     这样模型在 transcript 里看到的格式是它训练时见过的稳定模式；
+     *   - providerData.isMeta=true 让 UI 过滤（避免用户看到内部反馈条），
+     *     同时也能被 SystemReminderAgentRunInterceptor 等识别为非真实用户输入。
+     *   - 不参与对话链（无 parentId）：这是个旁路注入，不影响树结构。
+     */
+    protected emitFeedbackToModel(session: Session, _goal: ActiveGoal, reason?: string): Promise<void>;
+    /**
+     * 把 goal 变更推给 Web UI。slash 路径还有 combineSubject，HTTP API / idle 连接只靠这里。
+     */
+    protected notifyAcpClients(session: Session, item?: {
+        type?: string;
+        providerData?: unknown;
+    }, busy?: boolean): Promise<void>;
+    /**
+     * 把 goal 终态结果以 `goal-result` history item 形式写入 session.history。
+     * 由 chat-view 的 GoalResultMessageBox 渲染为可折叠状态条（对齐 cc UI）。
+     *
+     * 字段语义：
+     *   - durationMs：goal.createdAt 起到现在的耗时
+     *   - turnCount：至少 1（防御 0 turn 异常 case，UI 不显示 "0 turns"）
+     *   - tokenDelta：(当前 totalTokens - tokensAtStart)，下界 0
+     */
+    protected emitGoalResult(session: Session, goal: ActiveGoal, outcome: {
+        ok: boolean;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * 把 goal 进行中状态以 `goal-progress` history item 形式写入 session.history。
+     * 由 chat-view 的 GoalProgressMessageBox 渲染为 cc 同款可折叠状态条
+     * `◯ Goal not yet met… continuing`。
+     *
+     * 触发时机：每次 stop-condition hook 评估返回 ok:false（非 impossible），
+     * 表示模型还要继续工作。reason 来自 evaluator 的判定理由，仅在用户
+     * Ctrl+O 展开时才显示，避免污染对话流。
+     *
+     * 不参与对话链，也不喂给 LLM —— 由 CUSTOM_INPUT_ITEM_TYPES 兜底过滤。
+     */
+    protected emitGoalProgress(session: Session, goal: ActiveGoal, reason?: string): Promise<void>;
+}
+/** history 派生出的目标状态（不含 scopeId / token 统计等运行时字段）。 */
+export interface GoalFromHistory {
+    condition: string;
+    createdAt: number;
+    paused?: boolean;
+    pausedAt?: number;
+}
+/**
+ * 从 history 末尾往回找最近一条**决定性**的 goal-status 项，派生出目标状态。
+ *
+ *   - `set` / `active` / `resumed` → 目标存在且未暂停
+ *   - `paused` → 目标存在且暂停
+ *   - `cleared` / `no-goal` → 明确没有目标（返回 null）
+ *   - 其它（set-replaced / too-long / usage …）不改变状态，继续往前找
+ *
+ * 返回 `undefined` = history 里根本没有 goal 状态项。
+ *
+ * **为什么需要它**：served 会话不落 session-meta（cbc-core session-store 明确规定），
+ * 而宿主 runtime 会随插件刷新 / 空闲回收换进程。换进程后 `session.meta.activeGoal`
+ * 为空，只能靠 history 里的 goalStatus 项把状态条 / 继续 / 清除恢复出来。
+ * 口径与 Web UI 的 activeGoalAfterStatus 一致。
+ */
+export declare function deriveGoalFromHistory(session: {
+    history?: unknown;
+}): GoalFromHistory | null | undefined;

package/cli/dist-server/types/workspace/cbc-goal/lib/node/goal/goal-session-start-hook.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SessionStart hook：在 session 恢复（`source === 'resume'` / `'compact'`）
+ * 时，根据 `session.meta.activeGoal` 重新注册 prompt-type Stop hook。
+ *
+ * 走 internal Hook 路径而非命令拦截器，是因为：
+ *   1. SESSION_START 事件已经是 hooks 系统的标准入口；不必为 /goal 专门接
+ *      session-manager 生命周期。
+ *   2. Hook 自带 priority + source 匹配，与 `StructuredOutputSessionStartHook`
+ *      模式一致，新增/移除都是局部改动，可维护。
+ *   3. 单测时只需 mock GoalService，断言 restoreFromMeta 是否被调用。
+ *
+ * 不抛错 / 不阻塞：恢复失败不应阻断 session 启动，只记录 warn。
+ */
+import { Hook, HookInput, HookPriority } from '../../../../../node/hooks/hook-protocol.js';
+import { HookEvent, HookExecutionResult } from '../../../../cbc-shared/lib/node/index.js';
+import { Logger } from '../../../../telemetry/lib/common/index.js';
+import { GoalService } from './goal-protocol.js';
+export declare class GoalSessionStartHook implements Hook {
+    readonly event = HookEvent.SESSION_START;
+    readonly priority = HookPriority.Normal;
+    protected readonly logger: Logger;
+    protected readonly goalService: GoalService;
+    protected init(): void;
+    execute(input: HookInput): Promise<HookExecutionResult | undefined>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Goal 模块的纯工具函数。可被 service / spec / 其他消费方直接 import，
+ * 不依赖 DI、不依赖 Session 之外的 runtime。
+ */
+import { PromptHookDefinition } from '../../../../../node/hooks/hook-protocol.js';
+import { ActiveGoal, GoalPromptHookCallback, GoalServicePolicy } from './goal-protocol.js';
+/**
+ * 安全解析 `session.meta.activeGoal`。schema 不合法返回 undefined。
+ *
+ * 把它做成纯函数后，Service 的两个公开方法（`get` / `restoreFromMeta`）都
+ * 不再重复手写 type guard，避免漂移。
+ */
+export declare function parseActiveGoal(raw: unknown): ActiveGoal | undefined;
+/**
+ * 按当前 policy 与 goal 实例构造一个 prompt-type Stop hook。
+ *
+ * 抽离成纯函数后，单测可断言：
+ *   - hook 类型为 `prompt`
+ *   - prompt 文本包含用户 condition
+ *   - `treatImpossibleAsAllow` 为 true（CC parity 三态语义）
+ *   - `onResult` 回调被原样串联
+ */
+export declare function buildGoalPromptHook(policy: GoalServicePolicy, goal: ActiveGoal, onResult: GoalPromptHookCallback): PromptHookDefinition;

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

@@ -0,0 +1,6 @@
+export * from './goal-format.js';
+export * from './goal-protocol.js';
+export * from './goal-policy.js';
+export * from './goal-utils.js';
+export * from './goal-service.js';
+export * from './goal-session-start-hook.js';

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

@@ -0,0 +1,12 @@
+/**
+ * @genie/cbc-goal — CodeBuddy Code `/goal` 命令子系统。
+ *
+ * 目录布局镜像 agent-cli：`src/node/goal/**` 与拆分前保持一致，git 历史通过 `git mv` 继承。
+ * agent-cli 侧原来所有 `../goal/xxx` 相对 import 改为 `@genie/cbc-goal` 主入口；
+ * 主 barrel 通过 `export * from '@genie/cbc-goal'` 反向消费本入口。
+ *
+ * 与 `@genie/agent-cli` 之间允许循环依赖：goal service / hook 需要
+ * `import { X } from '@genie/agent-cli/node/<子路径>/...'` 拿到 agent-cli 源码 live binding；
+ * 运行时安全前提是本包顶层无立即消费 agent-cli 运行时值的语句。
+ */
+export * from './goal/index.js';

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

@@ -0,0 +1,35 @@
+/**
+ * @genie/cbc-plugins — CodeBuddy Code 插件系统运行时。
+ *
+ * 目录布局镜像 agent-cli：`src/node/plugins/**` 与拆分前保持一致，git 历史通过 `git mv` 继承。
+ * agent-cli 侧 `src/node/plugins/index.ts` 已删除，原先所有 `../plugins/xxx` 相对 import
+ * 改指向 `@genie/cbc-plugins` 主入口；主 barrel 通过 `export * from '@genie/cbc-plugins'`
+ * 反向消费本入口（`packages/agent-cli/src/node/index-shared.ts`）。
+ *
+ * 与 `@genie/agent-cli` 之间允许循环依赖：plugins 内 loader / installer / marketplace 等实现
+ * 通过 `import { X } from '@genie/agent-cli/node/<子路径>/<leaf>'` 拿到 agent-cli 源码 live binding；
+ * 运行时安全前提是本包顶层无立即消费 agent-cli 运行时值的语句（Symbol 值走 `-protocol.ts` 叶子文件；
+ * 见 `.codebuddy/commands/cli/split-package.md` 铁律 4）。
+ */
+export * from './plugins/index.js';
+/**
+ * Function Hooks / Claude Mods 运行时（`src/node/mods/**`）。
+ *
+ * 与 `plugins/**` 的分工：`plugins` 管「插件从哪来、怎么装、怎么发现」
+ * （marketplace / installer / loader / MCPB）；`mods` 管「装上之后怎么参与
+ * 引擎执行」—— tier 化的 middleware 引擎、`$` capability surface、
+ * `engine.create` fold、以及从 `.codebuddy-plugin` / `.claude-plugin` +
+ * `hooks/hooks.json` 真实加载一个 mod 目录（等价 `--plugin-dir`）。
+ *
+ * **走命名空间导出**：mods 沿用上游 claude-code 的类型命名（`Hook` / `Settings` /
+ * `On` / `DispatchOptions` 等），这些通用名与 agent-cli 既有导出会撞；用
+ * `Mods.*` 收口既保住「与官方等价」的命名，又不污染顶层 barrel。
+ *
+ * ```ts
+ * import { Mods } from '@genie/cbc-plugins';
+ * const result = await Mods.bootstrapModsFromPluginDirs({ core });
+ * ```
+ *
+ * 对齐依据见 `src/node/mods/API-ALIGNMENT.md`。
+ */
+export * as Mods from './mods/index.js';