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

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';

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

@@ -0,0 +1,14 @@
+import type { RegisteredMod } from '../types/index.js';
+export * from './sec-default.js';
+export * from './telemetry.js';
+/**
+ * 宿主自带的 mod，坐在 `builtin` tier。
+ *
+ * tier 顺序是 `prepend → user → append → builtin → core`，builtin 在 user 之内 ——
+ * 用户装的 mod 包在外层，可以观察、改写甚至拦掉内置行为。内置的是**缺省值**，
+ * 不是不可绕过的沙箱；真正不可绕过的边界在宿主自己的权限系统里。
+ *
+ * 顺序也有意义：`telemetry` 排在 `sec-default` 前面，这样后者若要记录自己拦了
+ * 什么，`$.telemetry` 已经 seat 好了。
+ */
+export declare function builtinMods(): readonly RegisteredMod[];

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/builtin/sec-default.d.ts

@@ -0,0 +1,32 @@
+import type { Register } from '../types/index.js';
+/**
+ * 内置 `sec-default` mod —— 给 mod 能力面加一条**最小**的安全底线。
+ *
+ * ## 为什么要有，又为什么要克制
+ *
+ * `--plugin-dir` 加载的是第三方代码，`$.fs.*` 让它能读写任意路径。宿主给一条
+ * 默认底线是合理的；但内置策略过严会**悄悄弄坏**合法 mod，而且用户很难猜到是
+ * 被内置规则拦的。所以这里只拦「几乎不可能有正当理由」的那一类：
+ *
+ * - SSH 私钥、云厂商凭据、`.env`、浏览器/钥匙串数据库；
+ * - 写操作额外拦住 shell 启动文件（`.bashrc`/`.zshrc` 之类）—— 往里写一行就是
+ *   持久化的任意代码执行，而一个 mod 有正当理由改它的情形基本不存在。
+ *
+ * 其余一律放行：真正的收紧应当由用户自己装 policy mod 来做，而不是宿主替他决定。
+ *
+ * ## 坐在 builtin tier，因此可被用户覆盖
+ *
+ * tier 顺序 `prepend → user → append → builtin → core`：用户装的 mod 在**外层**，
+ * 可以先于本 mod 应答、也可以把调用拦在到达这里之前。这是刻意的 —— 内置底线是
+ * 缺省值，不是不可绕过的沙箱。真正不可绕过的边界在宿主自己的权限系统里
+ * （PreToolUse hook、permission 检查），那一层 mod 动不了。
+ *
+ * ## 拒绝必须说清楚是谁拦的
+ *
+ * 否则用户看到的是「mod 读文件失败」，会去查文件权限、查路径拼写，唯独想不到是
+ * 一条内置规则。每条拒绝都带上本 mod 的名字和命中的类别。
+ */
+/** 内置 sec-default mod 的名字。 */
+export declare const BUILTIN_SEC_NAME = "cbc-sec-default";
+/** 内置 sec-default 的 register。 */
+export declare const registerBuiltinSecDefault: Register;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/builtin/telemetry.d.ts

@@ -0,0 +1,43 @@
+import type { Register } from '../types/index.js';
+/**
+ * 内置 `telemetry` mod —— 把 `$.telemetry` 这个 noun 坐实。
+ *
+ * ## 为什么值得内置
+ *
+ * 官方 mod 把「`$.telemetry` 可能根本不存在」写进了代码：`agents-md` 每次调用都
+ * 包在 `Telemetry.quietly()` 里，noun 缺席时整段静默跳过。也就是说不装它并不会
+ * 报错，只会让所有 mod 的埋点**悄悄消失**。内置一份，官方 mod 的遥测路径就是通的，
+ * 而不是「看起来在跑，其实什么都没记」。
+ *
+ * ## 坐在 builtin tier
+ *
+ * tier 顺序是 `prepend → user → append → builtin → core`，builtin 在 user 之内。
+ * 这正是需要的：用户自己装的 mod 包在外层，可以观察、改写甚至拦掉内置行为；反过来
+ * 内置的不该越过用户的决定。
+ *
+ * ## 计数落 `$.store`
+ *
+ * `$.store` 按 plugin 隔离，所以这里的键不会和任何用户 mod 撞。跨会话累计也因此
+ * 免费得到 —— 埋点最常见的问题恰恰是「重启就归零，看不出趋势」。
+ */
+/** 一条埋点。 */
+export interface TelemetryRow {
+    readonly name: string;
+    readonly at: number;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+/** `$.telemetry` 的形状。 */
+export interface TelemetryNoun {
+    /** 记一条。 */
+    log(name: string, data?: Record<string, unknown>): void;
+    /** 打一个标记（官方 `mark` 的位置）。 */
+    mark(name: string, data?: Record<string, unknown>): void;
+    /** 本次会话记下的全部条目。 */
+    rows(): readonly TelemetryRow[];
+    /** 落盘累计计数，返回累计值。 */
+    flush(): Promise<number>;
+}
+/** 内置 telemetry mod 的名字（`$.store` 按它分文件）。 */
+export declare const BUILTIN_TELEMETRY_NAME = "cbc-telemetry";
+/** 内置 telemetry 的 register。 */
+export declare const registerBuiltinTelemetry: Register;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/engine/enable-flag.d.ts

@@ -0,0 +1,41 @@
+/**
+ * cbc-mods 的入口开关。
+ *
+ * ## 默认关 —— 必须显式 opt-in
+ *
+ * 语义：用户不显式声明就当作**未启用**。传 `--plugin-dir <mod>` 也不例外：
+ * 目录本身只表达"想指向这些文件"，而是否把里面的 hook 装配到进程内是独立的
+ * 安全决定，得由 `CBC_ENABLE_FUNCTION_HOOKS=1` 之类的 env 明确同意。
+ *
+ * 需要**显式开**：
+ * - `CBC_ENABLE_FUNCTION_HOOKS=1` / `true` / `on` / `yes`（大小写不敏感、允许前后空格）
+ * - `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` 同上（官方别名）
+ *
+ * 显式关（覆盖任何 ON）：
+ * - `CBC_ENABLE_FUNCTION_HOOKS=0` / `false` / `off` / `no`
+ * - `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=0` 同上
+ *
+ * 任一 alias 显式关就整体关；两个都不显式开即视为**默认关**。
+ * 未识别的字符串（如 `maybe` / 空串）不算 ON，也不算 OFF —— 走默认关。
+ */
+/**
+ * 判断当前环境是否启用 cbc-mods function hooks。
+ *
+ * 语义：
+ * - 任一 alias 显式关闭 → 关
+ * - 无显式关闭且至少一个显式开启 → 开
+ * - 其余（未设 / 空串 / 未识别值） → 关
+ */
+export declare function isFunctionHooksEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare const FUNCTION_HOOKS_ENV_VAR = "CBC_ENABLE_FUNCTION_HOOKS";
+export declare const CLAUDE_COMPAT_ENV_VAR = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
+/** 关闭 mod 隔离沙箱的 env 变量名（默认开，仅用于逃生）。 */
+export declare const MODS_ISOLATE_ENV_VAR = "CBC_MODS_ISOLATE";
+/**
+ * mod 是否走隔离沙箱执行（`isolated-import.ts` 的加固 realm）。
+ *
+ * 与 function hooks 总开关不同，这一项**默认开** —— 隔离是安全默认，只有显式
+ * `CBC_MODS_ISOLATE=0/false/off/no` 才关（逃生阀，供确需直接摸 Node 内建的 mod
+ * 临时降级）。未识别值按「不关」处理，仍然隔离。
+ */
+export declare function isModIsolationEnabled(env?: NodeJS.ProcessEnv): boolean;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/mods/engine/engine-builder.d.ts

@@ -0,0 +1,61 @@
+import type { EngineInterface, RegisteredMod, Tier } from '../types/index.js';
+import { type HooksRegistry } from './hooks-registry.js';
+/** 判断一个值是否 withhold 占位。 */
+export declare function isWithheld(v: unknown): boolean;
+/**
+ * 构造 `$` —— 每个方法都经 `registry.dispatch()`，因此上层 mod 可以拦截、
+ * 改写、拒绝任何一次能力调用（`sec-default` 式管控 / 审计 mod 的基础）。
+ *
+ * 两类方法：
+ * - **Op 方法**（`OP_TABLE`）：分发 `<noun>.<op>` op 事件，结果取 `{ value }`；
+ *   `{ deny }` 则抛错（调用方视为能力被拒）。
+ * - **Event call 方法**（`EVENT_CALL_TABLE`）：分发 middleware 事件，
+ *   原样返回事件结果（`tool.call` / `command.run` / `session.start` …）。
+ *
+ * 每次分发都带上 `origin = { plugin, tier }` —— 官方语义里 `next.origin` 是
+ * **发起调用的那个 plugin**，`sec-default` 的 `tool.register` 就靠它判断
+ * 「调用者是组织装的还是用户装的」。
+ *
+ * @param registry 事件引擎
+ * @param plugin 该 `$` 所属 plugin 的身份（name / root / tier）
+ */
+export declare function buildBaseSurface(registry: HooksRegistry, plugin: {
+    readonly name: string;
+    readonly root: string;
+    readonly tier?: Tier;
+}): EngineInterface;
+/** `engine.create` fold 期间发现的违规。 */
+export interface NounViolation {
+    /** 被试图替换的 noun。 */
+    readonly noun: string;
+    readonly reason: string;
+}
+/**
+ * 跑 `engine.create` fold 组装最终 `$`。
+ *
+ * 语义对齐官方：
+ * - `next(e)` 直接 resolve 成 **`$` 本身**（`NextResult<'engine.create'> =
+ *   EngineInterfaceBuilt`），所以官方 mod 的 `{ ...await next(e), telemetry }`
+ *   能原样工作。
+ * - 一个 step **可以 ADD** noun
+ * - 一个 step **可以 WITHHOLD** noun（返回时不带某个 key，或不调 `next`）
+ * - 一个 step **不可 REPLACE** core 提供的 noun
+ * - fold 完成后 `$` 冻结
+ *
+ * ## 违规不连坐
+ *
+ * 试图替换 core noun 时**不让整个 fold 失败** —— fold 走的是整条 `engine.create`
+ * 链（含所有 mod 的 step），一个 mod 的违规若抛错，会让**其他无辜 mod 和 host
+ * 都拿不到 `$`**。正确的隔离是：丢弃违规那个 noun（换回 core 的原值），通过
+ * `onViolation` 报出来，fold 照常完成。
+ *
+ * @param registry 事件引擎（已 register 全部 mod）
+ * @param mods 参与 fold 的 mod 名单（决定 `engine.create` 的 `plugins` 入参）
+ * @param plugin 这份 `$` 归属的 plugin（含 tier，用于 `next.origin`）
+ * @param onViolation 发现违规时的回调（不传则静默丢弃）
+ */
+export declare function buildEngineInterface(registry: HooksRegistry, mods: readonly RegisteredMod[], plugin: {
+    readonly name: string;
+    readonly root: string;
+    readonly tier?: Tier;
+}, onViolation?: (violation: NounViolation) => void): Promise<EngineInterface>;