@zhushanwen/extension-protocol 0.16.0 → 0.17.0

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';
 };
 
 /**
@@ -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）的类型定义。
  *
@@ -1510,4 +1705,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, 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_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, 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, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSyncedTool, 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";
 
@@ -710,7 +861,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,
@@ -727,6 +882,7 @@ export {
   callMarkerRpc,
   collectActivePendingIds,
   dateToOnceCron,
+  derivePhase,
   extractGui,
   firstContentText,
   formatChannelErrorText,
@@ -752,6 +908,8 @@ export {
   isGuiComponent,
   isGuiRenderResult,
   isInFlightReportAck,
+  isPlanReviewRequest,
+  isPlanReviewResponse,
   isScheduleDraft,
   isScheduleFormResult,
   isSessionManagerAbortParams,
@@ -768,10 +926,15 @@ export {
   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.17.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",