@zhushanwen/extension-protocol 0.16.0 → 0.18.0

package/README.md

@@ -7,9 +7,15 @@ pi extension 跨层契约包：类型 + helper 函数 + 共享行为原语，零
 - `core/` —— 通用协议层（所有 extension 共用：`GuiComponent` + 布局原语 + 传输编码 + 双模 widget helper）
 - `extensions/` —— 有运行时定制逻辑的 extension（marker + helper）
   - `ask-user/` —— 富交互（select 通道 + marker）
+  - `plan/` —— plan 生命周期状态机 + 审阅回传值域契约 + 旧 entry legacy 读取（纯函数零 pi 依赖，扩展 / runtime / renderer 三层共用）
+  - `scheduler/` —— scheduler 任务条目契约 + entry 重放折叠（replayFoldEntries）+ 时间格式化（纯契约与纯函数，零 pi/node 依赖）
+  - `scheduler-create/` —— scheduler 创建确认共享资产（ScheduleDraft / ScheduleFormResult 类型 + 形状与时间折叠守卫 + marker）
   - `session-manager/` —— agent-managed session 嵌套 `{action, params}` 契约（select 通道 + marker）
-  - `plugin-bridge/` —— plugin system bridge（插件工具/事件/拦截经 select 通道 + marker 桥接）
   - `subagent-engine/` —— 引擎可发现性（`engines.json` 状态文件 + 引擎配置视图）
+  - `subagent-inflight/` —— subagent 在途聚合上报（绝对计数报告 + marker，select 通道）
+  - `subagent-notify/` —— subagent-workflow 通知通道 customType 常量唯一来源（workflow 结果 / 后台通知 / subagent 指令三类）
+  - `ui-form/` —— 统一提问表单协议（ask-user / scheduler / plan 三方提问统一入口：类型 + marker + 交互 helper + 守卫）
+  - 完整子协议清单以 `src/index.ts` 导出为准
 - `pending-entries` —— pending 事件流差集核心（register 去重 + unregister 抵消，纯算法）
 - `background-task` —— base-tool-enhance 后台任务 `registry.json` 文件契约
 - 子出口 `@zhushanwen/extension-protocol/background-task` —— 后台任务行为原语（进程处置 / registry 文件 IO / output tail，含 node 内建依赖，不进 index 桶出口）

package/dist/index.d.ts

@@ -183,27 +183,45 @@ interface PlanDocMeta {
 /**
  * submit-review 挂起审批时的 select payload（序列化为 options[0] JSON）。
  * extension 侧解析失败走 E5（logger.warn + tool result 报错提示重挂，垃圾数据不进对话流）。
+ *
+ * selfReview（自审结论，D9①③）：agent 提交审批前的自审摘要，投影面到审批请求帧为止
+ * （不进 PlanStateView / session.planState 帧）；有界性由写侧 4KB 单点截断保证
+ * （canonical 上限与截断 = src/extensions/plan/review-contract.ts，R3）。**optional 是兼容契约**：
+ * 旧扩展不携带 → 宿主自审行不渲染的降级形态；submit-review 的必填硬门在 tool 层执行
+ * （缺失/空 → tool result 错误纠偏，不 throw），wire 帧不设必填。
  */
 interface PlanReviewRequest {
     docs: PlanDocMeta[];
+    selfReview?: string;
 }
-/** 审批两键裁决。revise 携带评论、approve 不携带（结构上不可混带）。 */
-type PlanReviewDecision = 'approve' | 'revise';
+/**
+ * 审批三键裁决（D3）：approve 确认执行 / revise 提交修订（必带评论）/ dismiss 搁置
+ * （非破坏：不杀 turn、不丢状态，计划进度保留）。revise 携带评论、approve/dismiss
+ * 不携带（结构上不可混带）。值域守卫 canonical 版 = src/extensions/plan/review-contract.ts
+ * （运行时判别 TS 穷尽性管不到——未知值域降级语义见该模块「降级双分源」）。
+ */
+type PlanReviewDecision = 'approve' | 'revise' | 'dismiss';
 /** 用户对某文档划选段落的一条评论：quote 是划选引文（agent 定位段落用），comment 是评语。 */
 interface PlanReviewComment {
     quote: string;
     comment: string;
 }
 /**
- * 审批条 respond 回传（判别联合：approve 无评论字段，revise 必带评论数组）。
- * extension 消费：approve → 走现状 complete 执行方式 select；revise → 评论清单以
- * 显式 deliverAs:'steer' 注入 + reviewState=revising。
+ * 审批条 respond 回传（判别联合：approve/dismiss 无评论字段，revise 必带评论数组）。
+ * extension 消费：approve → 走 complete 执行方式 select（transfer：reviewing→dispatching）；
+ * revise → 评论清单以显式 deliverAs:'steer' 注入 + 转移 reviewing→revising；
+ * dismiss（D3 搁置）→ 转移 reviewing→planning 落盘，tool result 告知 agent「用户搁置了
+ * 本次审阅：plan 模式保持、文档与进度不变；简短告知用户已搁置并询问下一步，不要实施改动」。
+ * 未知 decision 值域降级 = 版本错配信号：与 malformed 同款 bad-response 出口引导重挂，
+ * 消费方额外 logger.warn 留痕（D3①）——判别与降级枚举见 src/extensions/plan/review-contract.ts。
  */
 type PlanReviewResponse = {
     decision: 'approve';
 } | {
     decision: 'revise';
     comments: PlanReviewComment[];
+} | {
+    decision: 'dismiss';
 };
 
 /**
@@ -374,18 +392,18 @@ declare function firstContentText(result: {
 /**
  * select+marker 通道 RPC 原语（D8）。
  *
- * 三消费方（plugin-bridge / session-manager / subagent-workflow inflight-reporter）
- * 此前各自手写「ctx.ui.select(marker, [payload], opts) + 失败折叠 + JSON 检测」传输核，
+ * 消费方（session-manager / subagent-workflow inflight-reporter）各自手写过
+ * 「ctx.ui.select(marker, [payload], opts) + 失败折叠 + JSON 检测」传输核，
  * 形态同构、留痕/超时策略各异。本原语只收敛传输核与失败折叠契约，真差异留在调用方：
  *
  * - 判别结果而非抛错（调用方统一按 reason 折叠 isError / 重试）；
  * - 回包只做 JSON 合法性检测（`non-json` 判别 + 留痕），parsed 结果的消费留调用方——
- *   value 恒 raw string（session-manager raw 透传 / plugin-bridge 各形状守卫 / inflight
- *   ack 全等匹配，三态回包消费是真差异，不进原语）；
+ *   value 恒 raw string（session-manager raw 透传 / inflight ack 全等匹配，回包消费
+ *   是真差异，不进原语）；
  * - payload 调用方已序列化（原语不 stringify——各协议序列化形状各异：嵌套
- *   {action,params} / BridgeRequest / 快照帧，不引入内部 stringify 异常面）；
- * - mode 门控留调用方（三方现状各异：plugin-bridge 在 callBridge 内 / inflight 在
- *   attachSession 处 / session-manager 无门控——四态 reason 无 non-rpc 语义）；
+ *   {action,params} / 快照帧，不引入内部 stringify 异常面）；
+ * - mode 门控留调用方（inflight 在 attachSession 处 / session-manager 无门控——
+ *   四态 reason 无 non-rpc 语义）；
  * - `ui.select` 缺席（非 GUI ctx）由调用方前置判定（沿 ask-user askUserInteract 的
  *   `isGuiCapable(ctx) && ctx.ui?.select` 先例）；误用即 throw 明确错误。
  *
@@ -409,9 +427,9 @@ interface MarkerRpcOptions {
      * 日志策略（级别 / 前缀 / 防刷屏）归调用方——真差异保留。 */
     log?: (msg: string, detail?: object) => void;
 }
-/** 错误回包底层形状：select+marker 通道各协议（plugin-bridge / session-manager）
+/** 错误回包底层形状：select+marker 通道各协议（session-manager）
  * runtime 侧异常折叠的共用单源（不裸 reject，error 闭环走同一回包通道）。
- * BridgeErrorResponse / SessionManagerErrorResult 是本形状的 alias（D8 单源化）。 */
+ * SessionManagerErrorResult 是本形状的 alias（D8 单源化）。 */
 interface ChannelErrorResult {
     error: string;
     hint?: string;
@@ -803,6 +821,183 @@ declare function isScheduleFormResult(value: unknown): value is ScheduleFormResu
 declare function dateToOnceCron(date: Date): string;
 declare function onceCronToDate(cron: string, now?: Date): Date | null;
 
+/**
+ * plan 模式生命周期状态机（plan 模式状态机显式化 D1）——纯数据 + 纯函数，零依赖。
+ *
+ * plan 模式的状态散落在 pi 扩展 entry / runtime 挂起注册表 / renderer 派生公式三处时，
+ * 任意两者漂移即产「僵尸/谎言」UI（F1-F5）。本模块是全链路共享的单一状态契约：
+ * 8 值状态集 + 9 事件边表 + `transition` 纯函数（守卫集中一处）+ `derivePhase` 呈现映射。
+ *
+ * 语义要点（设计 D1 逐条锚定）：
+ * - 非法转移返回 `{ ok: false }`，由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
+ *   （effects-as-data 无已登记消费方属投机间接层），各 action 在转移成功后内联执行自身副作用。
+ * - `reviewing --dismiss--> planning`：用户「搁置」（协议级 dismiss 决策，D3）——落盘即
+ *   planning，被搁置的审批不复活（F1/F2/F3 构造性消除）。
+ * - `reviewing --review_aborted--> planning`：挂起期外部 turn abort / TUI 取消（D3 连带）。
+ * - `dispatching --review_aborted--> approved`：批准事实保留——任一「无选择解散」出口
+ *   （外部 turn abort 级联 / 表单取消 / 超时 / 交互通道故障折叠）统一落 approved，
+ *   不把「已批准」打回规划期（F5 不复活）。
+ * - `dispatching --later--> approved`：用户显式选「暂不执行」——是明确选择不是解散，
+ *   不得进 review_aborted 文案桶（A9 反向）。
+ * - `dispatching --exec_chosen--> completed`：选定执行方式并派发执行（终态）。
+ * - `approved --approve--> dispatching`：批准后 agent 再调 `complete` 重新选择执行方式
+ *   （D1「approved 上 agent 再调 complete → dispatching」）。事件命名裁决：9 事件表无
+ *   `complete` 员，本边取「执行确认」语义族最近员 `approve`（用户点确认执行与批准后重选
+ *   执行方式同为「确认执行、进入执行方式选择」的决策事件）——消费面接线见 consumers.md。
+ * - `approved` 其余转移仅 `exit`；活跃族非终态 `--exit--> exited`；idle 从未进入，
+ *   exit 非法（防从未进 plan 的会话落噪音 exited entry）；终态 `--enter--> planning`
+ *   （新一轮）；`revising` 保留独立态（E3 恢复文案分叉依赖，前提 P-7）。
+ * - `reviewing --submit--> reviewing`：审批重挂自环（E3 会话重启恢复 / D8「重新提交审批」
+ *   按钮——重提交不推进生命周期，落盘回 reviewing 重挂即等价于旧调用方特判放行形态）。
+ *
+ * 呈现映射（derivePhase）：用户视角四主态 + idle 缺省——四主态是呈现，不是存储
+ * （用户口述模型 = 呈现层，reviewing/dispatching 两个挂起态是崩溃恢复的真实分叉点，
+ * 存储层保留 8 值）。终态两值（completed = 批准并派发执行 / exited = 主动退出）共享
+ * 全部终态规则，呈现层同映 'terminal'（诊断/审计语义保留存储区分）。
+ */
+type PlanLifecycleState = 'idle' | 'planning' | 'reviewing' | 'revising' | 'approved' | 'dispatching' | 'completed' | 'exited';
+/** 状态穷举表（运行时消费：E3 恢复查表 / 测试穷举基座）——顺序 = 生命周期自然序。 */
+declare const PLAN_LIFECYCLE_STATES: readonly ["idle", "planning", "reviewing", "revising", "approved", "dispatching", "completed", "exited"];
+type PlanLifecycleEvent = 'enter' | 'submit' | 'revise' | 'dismiss' | 'review_aborted' | 'approve' | 'exec_chosen' | 'later' | 'exit';
+/** 事件穷举表——顺序 = 设计 D1 枚举序。 */
+declare const PLAN_LIFECYCLE_EVENTS: readonly ["enter", "submit", "revise", "dismiss", "review_aborted", "approve", "exec_chosen", "later", "exit"];
+type PlanTransitionResult = {
+    ok: true;
+    next: PlanLifecycleState;
+} | {
+    ok: false;
+};
+/**
+ * 纯函数转移：`(state, event) → { ok: true, next } | { ok: false }`。
+ *
+ * 非法转移（含运行时垃圾 state/event 值——跨版本帧、坏反序列化）返回 `{ ok: false }`
+ * 且**不携带 next 键**，由调用方降级（不 throw 炸 turn）。调用方义务：`ok:false` 时
+ * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归口点的兜底保险）。
+ *
+ * 入口白名单守卫（与 derivePhase 同一机制）：普通对象字面量查表会沿原型链命中继承键——
+ * `transition('reviewing', '__proto__')` 取出 Object.prototype、`('__proto__', 'valueOf')`
+ * 取出函数，均被误判为合法 next（违背本契约）。故垃圾键必须先挡在查表前。
+ * **选「枚举 includes 白名单」而非 null-prototype 表 / Object.hasOwn**：① transition 与
+ * derivePhase 共用同一守卫形态（单一机制，不并存两种写法）；② PLAN_LIFECYCLE_STATES /
+ * PLAN_LIFECYCLE_EVENTS 就是值域 SSOT（测试穷举同源），includes 判定与之同源，
+ * 原型键天然不在白名单内。
+ */
+declare function transition(state: PlanLifecycleState, event: PlanLifecycleEvent): PlanTransitionResult;
+/**
+ * 用户视角呈现相位（四主态 + idle）：
+ * - 'planning'（规划中）= planning | revising
+ * - 'reviewing'（待审批）= reviewing
+ * - 'approved'（已批准）= approved | dispatching（dispatching 呈「③审阅确认 · 已完成」，
+ *   阶段不倒退——F5 修正；细化渲染由消费方查 state，不另造相位）
+ * - 'terminal'（终态）= completed | exited（两值同映，区分只留存储/审计层）
+ * - 'idle'（无 plan）= idle
+ */
+type PlanPhase = 'idle' | 'planning' | 'reviewing' | 'approved' | 'terminal';
+/**
+ * 8 存储态 → 5 呈现相位的单点映射（renderer 阶段指示/状态带共用，禁止消费方各自 if 拼）。
+ * 运行时垃圾 state（混装格坏帧）降级 'idle'（无 plan 缺省，fail-safe 不误示进行中）。
+ *
+ * 入口白名单守卫（理由同 transition，见彼处）：裸查表对继承键 'constructor' / 'toString'
+ * 会取出 Object 构造函数等并经 `?? 'idle'` 流出（非 nullish 不落兜底）——垃圾 state
+ * 必须精确落 'idle'，函数/对象不得作为相位流入 renderer。
+ */
+declare function derivePhase(state: PlanLifecycleState): PlanPhase;
+
+/**
+ * plan 审阅回传值域契约（plan 模式状态机显式化 D3①⑤ / D9③）——纯函数守卫，零依赖。
+ *
+ * 为什么守卫是契约级承重：TS 判别联合的穷尽性（switch/never 断言）管不到运行时值域——
+ * respond 通道透传的是任意字符串 parse 出的 unknown（P-2），值域守卫漏改即「搁置应答被判
+ * 垃圾 → bad-response 引导重挂」再入循环（F1 复活路径）。canonical 守卫与判别联合同住
+ * 契约包，消费面（extensions/universal/plan tool.ts）接线见同目录 consumers.md。
+ *
+ * 降级双分源（D3①）——parse 失败必须区分两类（envelope 判别保留），消费面出口同款：
+ * - `unknown-decision`（对象合法但 decision 不在值域）：版本错配信号（R2），消费方
+ *   额外 logger.warn 留痕；出口与文案与 malformed 同款——bad-response 报错提示重挂。
+ *   裁决与重审触发（候选替代 = 恢复独立 version-mismatch 不重挂出口）登记于消费方
+ *   extensions/universal/plan/src/tool.ts「条目 7 降级」注释段。
+ * - `malformed`（非对象 / 缺 decision / 形状不合法）：垃圾数据（E5 判据），bad-response
+ *   报错提示重挂。
+ *
+ * selfReview 有界字段（D9③ / R3）：有界性由**写侧单点截断**保证（截断点 = 扩展 payload
+ * 构造处），4KB 上限与 UTF-8 字节界安全截断的唯一权威在本模块；透传层（runtime）不截、
+ * 入站守卫不二次截（上限已在写侧达成）。
+ */
+
+/** selfReview 上限：4KB（UTF-8 字节）。超限即截（全文可要求 agent 贴对话流，R3）。 */
+declare const PLAN_SELF_REVIEW_MAX_BYTES = 4096;
+/**
+ * selfReview 写侧单点截断：按 UTF-8 字节预算截到**完整码点边界**（多字节字符不截半，
+ * 无替换字符噪音）。预算内原样返回；不追加省略号（消费方渲染时自行提示截断）。
+ */
+declare function truncateSelfReview(text: string): string;
+/**
+ * `PlanReviewRequest` 形状守卫（E5 垃圾数据判据）：
+ * docs 必为 `PlanDocMeta[]`（逐项形状）；selfReview 缺省或 string——**optional 是兼容契约**
+ * （旧扩展不携带 → 自审行不渲染的降级形态，D9③），值域上限不在此拒绝（写侧截断已界）。
+ * 空载荷（undefined/null/非对象/缺 docs）与非法形态（docs 非数组 / 元素形状不合法 /
+ * selfReview 非 string）一律 false，不 throw。
+ */
+declare function isPlanReviewRequest(value: unknown): value is PlanReviewRequest;
+/**
+ * respond 回传解析结果（error envelope 单源）：
+ * - ok：归一化后的合法 `PlanReviewResponse`（多余键已剥——approve/dismiss 不携带评论是
+ *   结构保证，不信任宿主回传的附加形态）。
+ * - `unknown-decision`：decision 是 string 但不在值域 → 版本错配信号（消费方额外
+ *   logger.warn 留痕；出口与 malformed 同款 bad-response 引导重挂，见文件头「降级双分源」）。
+ * - `malformed`：空载荷 / 非对象 / 形状不合法 → E5 判据，报错提示重挂。
+ */
+type PlanReviewResponseEnvelope = {
+    ok: true;
+    response: PlanReviewResponse;
+} | {
+    ok: false;
+    code: 'unknown-decision';
+    decision: string;
+} | {
+    ok: false;
+    code: 'malformed';
+};
+/**
+ * respond 回传解析（值域守卫的判别版）：dismiss 样本必通（D3 主干），未知 decision 值域
+ * 落降级枚举而非垃圾（两类降级可判别分离；消费面出口同款引导重挂，见文件头「降级双分源」）。
+ */
+declare function parsePlanReviewResponse(value: unknown): PlanReviewResponseEnvelope;
+/**
+ * `PlanReviewResponse` 值域守卫（含 dismiss 员，D3①）——`parsePlanReviewResponse` 的谓词形。
+ * 消费方需要区分 unknown-decision / malformed 两类降级时用 parse 版。
+ */
+declare function isPlanReviewResponse(value: unknown): value is PlanReviewResponse;
+
+/**
+ * plan-state entry 的 customType（pi appendEntry custom entry 判别键）。磁盘形态冻结：
+ * 扩展写读两侧（persistPlanState / isPlanStateEntry）与 runtime 投影链（plan-state-extractor /
+ * session-records）均消费本常量，值同源——改值即历史会话全部失联，禁改（冻结锚测试见
+ * 本目录 legacy-entries.test.ts）。
+ */
+declare const PLAN_STATE_CUSTOM_TYPE = "plan-state";
+/**
+ * 生命周期状态读取（D2 读方①②共用映射，原扩展 state.ts / runtime extractor 内联拷贝的
+ * 单源归并）：
+ * ① 新字段直读（值域守卫：PLAN_LIFECYCLE_STATES 之外的垃圾值按缺失处理，落映射——
+ *    不信任外部写入）；
+ * ② 旧 entry 无 state（或垃圾 state）时映射 reviewState（awaiting→reviewing /
+ *    revising→revising / 其余值→planning|idle 按 isActive）。
+ */
+declare function readLifecycleState(data: {
+    state?: unknown;
+    reviewState?: unknown;
+}, isActive: boolean): PlanLifecycleState;
+/**
+ * resumeHint 读取（D2 读方①②共用映射）：新字段直读（只认 'resubmit' 一字面量）+
+ * 旧 reviewStateSource 同义映射（'explain' 等存量值归无值——explain 交互已删）；
+ * resumeHint 存在但非法（垃圾值）时不挡 reviewStateSource 映射（与原两份拷贝逐字同构）。
+ */
+declare function readResumeHint(data: {
+    resumeHint?: unknown;
+    reviewStateSource?: unknown;
+}): 'resubmit' | undefined;
+
 /**
  * 统一提问表单协议（ui-form）的类型定义。
  *
@@ -1234,8 +1429,7 @@ interface SubagentInFlightReport {
     inFlight: number;
     /**
      * 上报所属 session（ctx.sessionManager.getSessionId()）。pi 延迟写入窗口内可能取
-     * 不到（plugin-bridge getSessionId 同款防御）——缺席时消费方按无法归属丢弃整帧
-     * （不镜像），不视为协议错误。
+     * 不到——缺席时消费方按无法归属丢弃整帧（不镜像），不视为协议错误。
      */
     sessionId?: string;
     /** 产生时点（ms epoch，pi 进程内取值）。诊断/乱序排查用，消费方不依赖其单调性。 */
@@ -1273,6 +1467,92 @@ declare function isInFlightReportAck(v: unknown): v is typeof INFLIGHT_REPORT_AC
  */
 declare const SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
 
+/**
+ * journal 事件推送的类型定义（event-push-channel 协议面）。
+ *
+ * 契约两端：
+ *   - 写侧（生产）：@zhushanwen/pi-subagent-workflow 壳层（src/host/journal-reporter.ts）
+ *     监听 subagent-core 的 journal 落盘出口回调（notifyJournalAppended），经 select
+ *     通道带回执推送；
+ *   - 读侧（消费）：taiji runtime event-adapter 的 marker 路由分支 → journal-report-router
+ *     → SessionEventProjection（applyJournalReport：seq 缺口判定 → 缺口触发本地补读 → fold）。
+ *
+ * 语义锚点（设计 §3.3）：推送报告只携带事件本体（事件信封自带 seq），不另设水位协商
+ * ——消费方 per 文件持两个水位（字节偏移 = 补读起点、已折叠最大 seq = 去重判据），
+ * 重复投递由域 fold 的 seq 单调检查构造性幂等。确认回执 = runtime 同步 fold 应用后
+ * resolve（回执 = 「已应用」而非「已接收」）。
+ */
+/** journal 两域（单 marker 载荷判别字段——设计 §3.4 D2：两域推送方/接收方/通道语义同构，不拆双 marker）。 */
+type SubagentJournalDomain = 'run' | 'record';
+/**
+ * 单条 journal 事件（run 域 = run journal 行 / record 域 = record 事件行——域内
+ * 词表校验归读侧与文件行同一解析器，本层只校验跨域共同信封）。
+ */
+interface SubagentJournalEvent {
+    /** 事件类型（域词表成员资格由读侧按域校验）。 */
+    type: string;
+    /** 事件时点（ms epoch；信封必填）。 */
+    ts: number;
+    /**
+     * journal 行序号（写入方 JsonlEventStream.append 统一分配）。缺省 = W1 前存量
+     * 无 seq 行（设计 §3.3 兼容条款：无 seq 事件不参与缺口判定，fold 按状态机语义幂等）。
+     */
+    seq?: number;
+    /** 域内载荷字段原样透传（写侧 = 刚落盘的行对象，无二次塑形）。 */
+    [key: string]: unknown;
+}
+/**
+ * 单帧 journal 事件报告（pi 进程 → runtime，经 select 通道，title = SUBAGENT_JOURNAL_MARKER，
+ * options = [JSON.stringify(本形状)]）。单帧只覆盖一个文件（fileKey 单数——设计 §3.4：
+ * fileKey = runId 或 sa-id；多文件积压由写侧按组逐帧发送）。
+ */
+interface SubagentJournalReport {
+    /** 事件所属域（run / record 判别）。 */
+    domain: SubagentJournalDomain;
+    /** 文件键：run 域 = runId，record 域 = record id（sa-id）。 */
+    fileKey: string;
+    /** 本帧事件（写入序；写侧落盘提交点之后的增量批次）。 */
+    events: SubagentJournalEvent[];
+    /**
+     * 上报所属 session（ctx.sessionManager.getSessionId()）。pi 延迟写入窗口内可能取
+     * 不到——缺席时消费方按无法归属丢弃整帧（不 fold 不 ack），不视为协议错误
+     * （归属权威 = 连接的 sessionId，本字段只作在场性判据——inflight 同款先例）。
+     */
+    sessionId?: string;
+    /** 产生时点（ms epoch，pi 进程内取值）。诊断/乱序排查用，消费方不依赖其单调性。 */
+    emittedAt: number;
+}
+/**
+ * select 通道的确认回包（runtime event-adapter 处理完帧后 resolve 给 pi 侧的
+ * JSON 字符串）。回执语义 = 「已应用」（runtime 同步完成 fold 应用后 resolve，
+ * 设计 §3.4 D7 生效回执）——写侧非本字符串即未确认：首败 warn 留证 + 缓冲丢弃
+ * 不重推（完整性由消费方 seq 缺口补读收敛，设计 §3.3 D5）。
+ */
+declare const JOURNAL_REPORT_ACK: "{\"ack\":true}";
+/**
+ * SubagentJournalReport 形状守卫：domain 落两域词表、fileKey 非空串、events 逐条
+ * 过信封守卫、sessionId 缺席或 string。event-adapter 路由分支消费；非法帧返回
+ * false（调用方丢弃，不 fold 不 ack）。
+ */
+declare function isSubagentJournalReport(v: unknown): v is SubagentJournalReport;
+/** 确认回包形状守卫（pi 侧 reporter 消费——非本字符串即未确认）。 */
+declare function isJournalReportAck(v: unknown): v is typeof JOURNAL_REPORT_ACK;
+
+/**
+ * journal 事件推送的 title marker。runtime event-adapter 检测此 marker 区分
+ * journal 事件报告与普通 select；pi 侧壳层（@zhushanwen/pi-subagent-workflow 的
+ * host/journal-reporter）经同一 marker 以带回执语义推送 SubagentJournalReport
+ * 帧（单一来源，两端口径必然一致）。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 与 SUBAGENT_INFLIGHT_MARKER / ASK_USER_MARKER / SESSION_MANAGER_MARKER 同理。
+ *
+ * 设计权威源：.tmp/tech-design/event-push-channel.md §3.1/§3.4（journal 写入方
+ * subagent-core 在落盘提交点经本 marker 通道把新事件批量推给 runtime，通道数量
+ * = 1 个，载荷内 domain 字段判别 run/record 两域）。
+ */
+declare const SUBAGENT_JOURNAL_MARKER = "\0TAIJI_SUBAGENT_JOURNAL";
+
 /**
  * subagent-workflow 通知通道的 custom_message customType 词表（单源）。
  *
@@ -1305,99 +1585,6 @@ declare const SUBAGENT_BG_NOTIFY_CUSTOM_TYPE: "subagent-bg-notify";
  *  上下文 + renderer 定向气泡）。shared parseSubagentDirective / runtime display 覆写消费。 */
 declare const SUBAGENT_DIRECTIVE_CUSTOM_TYPE: "subagent-directive";
 
-/**
- * plugin-bridge 请求的 title marker。runtime event-adapter 和 pi 侧
- * bridge extension（@zhushanwen/pi-plugin-bridge）双端消费此 marker，
- * 在 select 通道上区分 bridge 帧与普通 select（单一来源，两端口径必然一致）。
- *
- * NUL 前缀确保不会与 extension 正常的 select title 冲突。
- * 与 ASK_USER_MARKER / SESSION_MANAGER_MARKER / GUI_WIDGET_MARKER 同理。
- */
-declare const BRIDGE_MARKER = "\0TAIJI_BRIDGE";
-/**
- * 协议 v2 的 4 个 method 运行时集合（与 BridgeMethod 类型同源——types.ts 从此派生）。
- * event-adapter 用它校验 marker 帧的 method 合法性，
- * 非法值折叠为 'bridge:malformed' 哨兵（handler 回 malformed 错误，不静默丢弃）。
- */
-declare const BRIDGE_METHODS: readonly ["bridge:sync", "bridge:tool_execute", "bridge:event", "bridge:intercept"];
-
-/**
- * plugin-bridge 协议 v2 的类型定义。
- *
- * select + BRIDGE_MARKER 通道上的请求/回包形状，pi 侧 bridge extension
- * （序列化发送方）与 runtime bridge-handler（解析与回包方）共用。
- * 向后不兼容旧 bridge:* method 承载（旧链路本来就不通，改名无收益）。
- * marker 检测后按 method 分发到对应 handler 分支。
- */
-
-/** 协议 v2 的 4 个 method（从 BRIDGE_METHODS 集合派生，值与类型同源） */
-type BridgeMethod = (typeof BRIDGE_METHODS)[number];
-/** bridge 请求的统一形状（pi bridge extension → runtime via select 通道） */
-interface BridgeRequest {
-    method: BridgeMethod;
-    /** tool_execute 专属：工具名 */
-    toolName?: string;
-    /** tool_execute 专属：工具调用 id */
-    toolCallId?: string;
-    /** tool_execute 专属：工具入参 */
-    params?: Record<string, unknown>;
-    /** 发起请求的 session（tool_execute/event/intercept 携带，供 runtime 按 session 路由
-     * 防跨 session 串台；bridge:sync 全局快照请求不带） */
-    sessionId?: string;
-    /** event / intercept 专属：pi 原生事件名 */
-    eventName?: string;
-    /** event / intercept 专属：事件负载 */
-    data?: unknown;
-}
-/** tool_execute 回包：插件工具执行结果 */
-interface BridgeToolExecuteResponse {
-    content: string;
-    isError?: boolean;
-}
-/** sync 回包：工具清单快照（pi 侧命令发现不走本协议，另走 getCommands 通路） */
-interface BridgeSyncPayload {
-    tools: Array<{
-        name: string;
-        description: string;
-        parameters: Record<string, unknown>;
-    }>;
-    success: true;
-}
-/** intercept 回包：before_agent_start 拦截决策（bridge 侧把 injectedMessages 映射为单条 CustomMessage） */
-interface BridgeInterceptResponse {
-    blocked?: boolean;
-    reason?: string;
-    injectedMessages: unknown[];
-}
-/** 错误回包：runtime 侧异常折叠（不裸 reject；bridge 侧解析后以 isError 返回）。
- * D8 单源化：底层形状 alias 到 core 的 ChannelErrorResult（导出名与文件位置不变，
- * public API 零破坏）。 */
-type BridgeErrorResponse = ChannelErrorResult;
-
-/**
- * plugin-bridge 回包形状守卫族（D11 自 extensions/taiji/plugin-bridge index.ts 零改动迁入）。
- *
- * 「marker + types + 守卫」同住惯例（session-manager / subagent-inflight 先例）：
- * 回包形状的运行时检测与类型定义同源维护。当前唯一消费方 = pi 侧 bridge
- * extension；runtime bridge-handler 的 5 处 `as string` 断言是后续批次的第二
- * 消费方（换校验的铺路，设计 D11 登记项）。
- *
- * isRecord 为模块内私有副本（排数组严版——与 subagent-inflight / session-manager
- * 副本同款同义）：protocol 不依赖 extensions 层的 ext-guards（分层边界裁决，D3
- * 明确排除），包内三份私有副本并存是裁决下的既有惯例，语义必须一致。
- *
- * 设计权威源：docs/architecture/ext-simplify-17-shared-extraction.md §3.3 D11。
- */
-
-/** runtime 错误闭环形状 {error, hint?}（设计 §3.3-D1：不裸 reject）——检测逻辑单源于
- * core 的 isChannelErrorResult（D8），本名保留为守卫族整体成员（D11 迁移） */
-declare function isBridgeErrorResponse(v: unknown): v is BridgeErrorResponse;
-declare function isBridgeToolExecuteResponse(v: unknown): v is BridgeToolExecuteResponse;
-declare function isBridgeSyncPayload(v: unknown): v is BridgeSyncPayload;
-declare function isBridgeInterceptResponse(v: unknown): v is BridgeInterceptResponse;
-/** sync 清单里的单个工具条目（parameters 顶层必须 type:'object'——OpenAI 兼容红线） */
-declare function isSyncedTool(v: unknown): v is BridgeSyncPayload['tools'][number];
-
 /**
  * 子代理引擎契约（U7 引擎可发现性 + GUI 引擎选择）。
  *
@@ -1510,4 +1697,4 @@ declare function collectActivePendingIds(entries: unknown[], opts?: CollectPendi
 type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted';
 declare function mapReasonToStatus(reason: string): MappedPendingStatus;
 
-export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, BRIDGE_MARKER, BRIDGE_METHODS, type BridgeErrorResponse, type BridgeInterceptResponse, type BridgeMethod, type BridgeRequest, type BridgeSyncPayload, type BridgeToolExecuteResponse, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_REVIEW_MARKER, PROTOCOL_VERSION, type PendingEntriesScan, type PlanDocMeta, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type ReplayFoldOptions, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, TASK_ENTRY_TYPE, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, appendExecutionRecord, applyPendingDiff, callMarkerRpc, collectActivePendingIds, dateToOnceCron, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, onceCronToDate, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, uiFormInteract, validateWidgetIconPaths };
+export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, TASK_ENTRY_TYPE, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, appendExecutionRecord, applyPendingDiff, callMarkerRpc, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -413,6 +413,157 @@ function onceCronToDate(cron, now = /* @__PURE__ */ new Date()) {
   return null;
 }
 
+// src/extensions/plan/state-machine.ts
+var PLAN_LIFECYCLE_STATES = [
+  "idle",
+  "planning",
+  "reviewing",
+  "revising",
+  "approved",
+  "dispatching",
+  "completed",
+  "exited"
+];
+var PLAN_LIFECYCLE_EVENTS = [
+  "enter",
+  "submit",
+  "revise",
+  "dismiss",
+  "review_aborted",
+  "approve",
+  "exec_chosen",
+  "later",
+  "exit"
+];
+var TRANSITION_TABLE = {
+  idle: { enter: "planning" },
+  planning: { submit: "reviewing", exit: "exited" },
+  reviewing: {
+    submit: "reviewing",
+    revise: "revising",
+    dismiss: "planning",
+    review_aborted: "planning",
+    approve: "dispatching",
+    exit: "exited"
+  },
+  revising: { submit: "reviewing", exit: "exited" },
+  approved: { approve: "dispatching", exit: "exited" },
+  dispatching: {
+    review_aborted: "approved",
+    exec_chosen: "completed",
+    later: "approved",
+    exit: "exited"
+  },
+  completed: { enter: "planning" },
+  exited: { enter: "planning" }
+};
+function transition(state, event) {
+  if (!PLAN_LIFECYCLE_STATES.includes(state) || !PLAN_LIFECYCLE_EVENTS.includes(event)) {
+    return { ok: false };
+  }
+  const next = TRANSITION_TABLE[state][event];
+  return next === void 0 ? { ok: false } : { ok: true, next };
+}
+var PHASE_OF_STATE = {
+  idle: "idle",
+  planning: "planning",
+  reviewing: "reviewing",
+  revising: "planning",
+  approved: "approved",
+  dispatching: "approved",
+  completed: "terminal",
+  exited: "terminal"
+};
+function derivePhase(state) {
+  if (!PLAN_LIFECYCLE_STATES.includes(state)) return "idle";
+  return PHASE_OF_STATE[state];
+}
+
+// src/extensions/plan/review-contract.ts
+var PLAN_SELF_REVIEW_MAX_BYTES = 4096;
+var UTF8_1_BYTE_CP_MAX = 127;
+var UTF8_2_BYTE_CP_MAX = 2047;
+var UTF8_3_BYTE_CP_MAX = 65535;
+function utf8ByteLengthOfCodePoint(cp) {
+  if (cp <= UTF8_1_BYTE_CP_MAX) return 1;
+  if (cp <= UTF8_2_BYTE_CP_MAX) return 2;
+  if (cp <= UTF8_3_BYTE_CP_MAX) return 3;
+  return 4;
+}
+function truncateSelfReview(text) {
+  let bytes = 0;
+  let i = 0;
+  while (i < text.length) {
+    const cp = text.codePointAt(i);
+    if (cp === void 0) break;
+    const size = utf8ByteLengthOfCodePoint(cp);
+    if (bytes + size > PLAN_SELF_REVIEW_MAX_BYTES) break;
+    bytes += size;
+    i += cp > UTF8_3_BYTE_CP_MAX ? 2 : 1;
+  }
+  return text.slice(0, i);
+}
+function isPlanDocMeta(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const doc = value;
+  return typeof doc.fileName === "string" && typeof doc.absPath === "string" && typeof doc.sourceSkill === "string" && typeof doc.version === "number";
+}
+function isPlanReviewRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const req = value;
+  if (!Array.isArray(req.docs) || !req.docs.every(isPlanDocMeta)) return false;
+  if (req.selfReview !== void 0 && typeof req.selfReview !== "string") return false;
+  return true;
+}
+function normalizeComments(value) {
+  if (!Array.isArray(value)) return null;
+  const comments = [];
+  for (const item of value) {
+    if (typeof item !== "object" || item === null) return null;
+    const c = item;
+    if (typeof c.quote !== "string" || typeof c.comment !== "string") return null;
+    comments.push({ quote: c.quote, comment: c.comment });
+  }
+  return { decision: "revise", comments };
+}
+function parsePlanReviewResponse(value) {
+  if (typeof value !== "object" || value === null) return { ok: false, code: "malformed" };
+  const raw = value;
+  const decision = raw.decision;
+  if (typeof decision !== "string") return { ok: false, code: "malformed" };
+  switch (decision) {
+    case "approve":
+      return { ok: true, response: { decision: "approve" } };
+    case "dismiss":
+      return { ok: true, response: { decision: "dismiss" } };
+    case "revise": {
+      const response = normalizeComments(raw.comments);
+      return response === null ? { ok: false, code: "malformed" } : { ok: true, response };
+    }
+    default:
+      return { ok: false, code: "unknown-decision", decision };
+  }
+}
+function isPlanReviewResponse(value) {
+  return parsePlanReviewResponse(value).ok;
+}
+
+// src/extensions/plan/legacy-entries.ts
+var PLAN_STATE_CUSTOM_TYPE = "plan-state";
+function readLifecycleState(data, isActive) {
+  const raw = data.state;
+  if (typeof raw === "string" && PLAN_LIFECYCLE_STATES.includes(raw)) {
+    return raw;
+  }
+  if (data.reviewState === "awaiting") return "reviewing";
+  if (data.reviewState === "revising") return "revising";
+  return isActive ? "planning" : "idle";
+}
+function readResumeHint(data) {
+  if (data.resumeHint === "resubmit") return "resubmit";
+  return data.reviewStateSource === "resubmit" ? "resubmit" : void 0;
+}
+
 // src/extensions/ui-form/marker.ts
 var UI_FORM_MARKER = "\0TAIJI_UI_FORM";
 
@@ -601,35 +752,44 @@ function isInFlightReportAck(v) {
   return v === INFLIGHT_REPORT_ACK;
 }
 
-// src/extensions/subagent-notify/custom-types.ts
-var WORKFLOW_RESULT_CUSTOM_TYPE = "workflow-result";
-var SUBAGENT_BG_NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
-var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
-
-// src/extensions/plugin-bridge/marker.ts
-var BRIDGE_MARKER = "\0TAIJI_BRIDGE";
-var BRIDGE_METHODS = ["bridge:sync", "bridge:tool_execute", "bridge:event", "bridge:intercept"];
+// src/extensions/subagent-journal/marker.ts
+var SUBAGENT_JOURNAL_MARKER = "\0TAIJI_SUBAGENT_JOURNAL";
 
-// src/extensions/plugin-bridge/guards.ts
+// src/extensions/subagent-journal/types.ts
+var JOURNAL_REPORT_ACK = '{"ack":true}';
 function isRecord3(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-function isBridgeErrorResponse(v) {
-  return isChannelErrorResult(v);
-}
-function isBridgeToolExecuteResponse(v) {
-  return isRecord3(v) && typeof v.content === "string" && (v.isError === void 0 || typeof v.isError === "boolean");
-}
-function isBridgeSyncPayload(v) {
-  return isRecord3(v) && v.success === true && Array.isArray(v.tools);
+function isSubagentJournalEvent(v) {
+  if (!isRecord3(v)) return false;
+  if (typeof v.type !== "string" || v.type === "") return false;
+  if (typeof v.ts !== "number" || !Number.isFinite(v.ts)) return false;
+  if (v.seq !== void 0 && (typeof v.seq !== "number" || !Number.isSafeInteger(v.seq) || v.seq < 1)) {
+    return false;
+  }
+  return true;
 }
-function isBridgeInterceptResponse(v) {
-  return isRecord3(v) && Array.isArray(v.injectedMessages);
+function isSubagentJournalReport(v) {
+  if (!isRecord3(v)) return false;
+  if (v.domain !== "run" && v.domain !== "record") return false;
+  if (typeof v.fileKey !== "string" || v.fileKey === "") return false;
+  if (!Array.isArray(v.events)) return false;
+  for (const event of v.events) {
+    if (!isSubagentJournalEvent(event)) return false;
+  }
+  if (typeof v.emittedAt !== "number") return false;
+  if (v.sessionId !== void 0 && typeof v.sessionId !== "string") return false;
+  return true;
 }
-function isSyncedTool(v) {
-  return isRecord3(v) && typeof v.name === "string" && typeof v.description === "string" && isRecord3(v.parameters) && v.parameters.type === "object";
+function isJournalReportAck(v) {
+  return v === JOURNAL_REPORT_ACK;
 }
 
+// src/extensions/subagent-notify/custom-types.ts
+var WORKFLOW_RESULT_CUSTOM_TYPE = "workflow-result";
+var SUBAGENT_BG_NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
+var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
+
 // src/extensions/subagent-engine/contract.ts
 var SUBAGENTS_ENGINES_FILENAME = "engines.json";
 
@@ -698,11 +858,10 @@ export {
   BACKGROUND_TASK_REGISTRY_FILENAME,
   BACKGROUND_TASK_REGISTRY_VERSION,
   BASE_TOOL_ENHANCE_DIRNAME,
-  BRIDGE_MARKER,
-  BRIDGE_METHODS,
   GUI_WIDGET_MARKER,
   HISTORY_LIMIT,
   INFLIGHT_REPORT_ACK,
+  JOURNAL_REPORT_ACK,
   MAX_TERMINAL_REGISTRY_ENTRIES,
   MS_PER_DAY,
   MS_PER_HOUR,
@@ -710,7 +869,11 @@ export {
   MS_PER_SECOND,
   PENDING_REGISTER_ENTRY_TYPE,
   PENDING_UNREGISTER_ENTRY_TYPE,
+  PLAN_LIFECYCLE_EVENTS,
+  PLAN_LIFECYCLE_STATES,
   PLAN_REVIEW_MARKER,
+  PLAN_SELF_REVIEW_MAX_BYTES,
+  PLAN_STATE_CUSTOM_TYPE,
   PROTOCOL_VERSION,
   SCHEDULE_CREATE_MARKER,
   SESSION_MANAGER_ACTIONS,
@@ -719,6 +882,7 @@ export {
   SUBAGENT_BG_NOTIFY_CUSTOM_TYPE,
   SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
   SUBAGENT_INFLIGHT_MARKER,
+  SUBAGENT_JOURNAL_MARKER,
   TASK_ENTRY_TYPE,
   UI_FORM_MARKER,
   WORKFLOW_RESULT_CUSTOM_TYPE,
@@ -727,6 +891,7 @@ export {
   callMarkerRpc,
   collectActivePendingIds,
   dateToOnceCron,
+  derivePhase,
   extractGui,
   firstContentText,
   formatChannelErrorText,
@@ -741,10 +906,6 @@ export {
   isActiveBackgroundTaskState,
   isAskUserQuestion,
   isBackgroundTaskRegistryEntry,
-  isBridgeErrorResponse,
-  isBridgeInterceptResponse,
-  isBridgeSyncPayload,
-  isBridgeToolExecuteResponse,
   isChannelErrorResult,
   isFormAnswers,
   isFormQuestion,
@@ -752,6 +913,9 @@ export {
   isGuiComponent,
   isGuiRenderResult,
   isInFlightReportAck,
+  isJournalReportAck,
+  isPlanReviewRequest,
+  isPlanReviewResponse,
   isScheduleDraft,
   isScheduleFormResult,
   isSessionManagerAbortParams,
@@ -764,14 +928,19 @@ export {
   isSessionManagerWatchParams,
   isSessionManagerWatchRespondPayload,
   isSubagentInFlightReport,
-  isSyncedTool,
+  isSubagentJournalReport,
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
   onceCronToDate,
+  parsePlanReviewResponse,
+  readLifecycleState,
+  readResumeHint,
   replayFoldEntries,
   scanPendingEntries,
   setWidgetDual,
   snapshotToTask,
+  transition,
+  truncateSelfReview,
   uiFormInteract,
   validateWidgetIconPaths
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Cross-layer pi extension contract package: dual-mode (TUI/GUI) rendering helpers, session/background-task/pending-entries protocols, and shared behavior primitives",
   "type": "module",
   "main": "dist/index.js",