@zhushanwen/extension-protocol 0.12.0 → 0.13.0

package/dist/{background-task-Cu0p02O-.d.ts → background-task-B6pdI5nq.d.ts}

@@ -7,8 +7,8 @@
  *    guard 写 exited 终态。写入协议：原子写 temp+rename + 统一文件锁内 RMW；
  *    解析失败/形状非法 → 重命名 .corrupt 保留现场 + 按空表重建。
  *  - 读侧：taiji runtime 后台任务收殓器——按属主判定处置孤儿（见 ownerPiPid
- *    字段注释），orphaned 终态由 runtime 写入（收殓下沉，设计 docs/design/
- *    file-lock-unification-and-reaper-sink.md D2）。
+ *    字段注释），orphaned 终态由 runtime 写入（收殓下沉，设计
+ *    docs/architecture/file-lock-unification-and-reaper-sink.md D2）。
  *
  * 目录布局（per-session 隔离）：
  *   <agentDir>/base-tool-enhance/<sessionId>/registry.json

package/dist/background-task-entry.d.ts

@@ -1,4 +1,4 @@
-import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './background-task-Cu0p02O-.js';
+import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './background-task-B6pdI5nq.js';
 
 /**
  * 后台任务进程原语（pid 判活 / 进程树处置 / start time 身份判据）——跨端单一实现。

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { b as BACKGROUND_TASK_ID_PREFIX, c as BACKGROUND_TASK_REGISTRY_FILENAME, d as BACKGROUND_TASK_REGISTRY_VERSION, e as BASE_TOOL_ENHANCE_DIRNAME, f as BackgroundTaskEndReason, a as BackgroundTaskRegistryEntry, g as BackgroundTaskRegistryFile, B as BackgroundTaskState, M as MAX_TERMINAL_REGISTRY_ENTRIES, i as isActiveBackgroundTaskState, h as isBackgroundTaskRegistryEntry, j as isTerminalBackgroundTaskState } from './background-task-Cu0p02O-.js';
+export { b as BACKGROUND_TASK_ID_PREFIX, c as BACKGROUND_TASK_REGISTRY_FILENAME, d as BACKGROUND_TASK_REGISTRY_VERSION, e as BASE_TOOL_ENHANCE_DIRNAME, f as BackgroundTaskEndReason, a as BackgroundTaskRegistryEntry, g as BackgroundTaskRegistryFile, B as BackgroundTaskState, M as MAX_TERMINAL_REGISTRY_ENTRIES, i as isActiveBackgroundTaskState, h as isBackgroundTaskRegistryEntry, j as isTerminalBackgroundTaskState } from './background-task-B6pdI5nq.js';
 
 /**
  * GUI 渲染协议核心类型定义。
@@ -145,6 +145,46 @@ interface TreeItem {
     children?: TreeItem[];
 }
 type TreeItemIcon = 'arrow' | 'check' | 'cross' | 'circle' | 'dot' | 'pause' | 'branch';
+/**
+ * 计划产物文档元数据——agent 调 register-doc 登记的一份产物。
+ * version 由 extension 侧维护：修订后重写文档须重调 register-doc（version+1），
+ * 前端凭 version 变化重拉 file.read 刷新渲染。
+ */
+interface PlanDocMeta {
+    /** 文件名（drawer L2 文档 tab 标题，不含目录） */
+    fileName: string;
+    /** 文件绝对路径（前端 file.read RPC 带 sessionId 读取） */
+    absPath: string;
+    /** 来源技能名（挂载 --skills 时产出该文档的技能；模板流程产出时为空串） */
+    sourceSkill: string;
+    /** 修订版本，从 1 起，每次修订重登记 +1 */
+    version: number;
+}
+/**
+ * submit-review 挂起审批时的 select payload（序列化为 options[0] JSON）。
+ * extension 侧解析失败走 E5（logger.warn + tool result 报错提示重挂，垃圾数据不进对话流）。
+ */
+interface PlanReviewRequest {
+    docs: PlanDocMeta[];
+}
+/** 审批两键裁决。revise 携带评论、approve 不携带（结构上不可混带）。 */
+type PlanReviewDecision = 'approve' | 'revise';
+/** 用户对某文档划选段落的一条评论：quote 是划选引文（agent 定位段落用），comment 是评语。 */
+interface PlanReviewComment {
+    quote: string;
+    comment: string;
+}
+/**
+ * 审批条 respond 回传（判别联合：approve 无评论字段，revise 必带评论数组）。
+ * extension 消费：approve → 走现状 complete 执行方式 select；revise → 评论清单以
+ * 显式 deliverAs:'steer' 注入 + reviewState=revising。
+ */
+type PlanReviewResponse = {
+    decision: 'approve';
+} | {
+    decision: 'revise';
+    comments: PlanReviewComment[];
+};
 
 /**
  * 通用传输 marker。extension 用 guiSetWidget 编码进 string[]，
@@ -153,6 +193,17 @@ type TreeItemIcon = 'arrow' | 'check' | 'cross' | 'circle' | 'dot' | 'pause' | '
  * NUL 字符开头的 marker，不会出现在正常文本中。
  */
 declare const GUI_WIDGET_MARKER = "\0TAIJI_GUI_WIDGET:";
+/**
+ * plan 审阅请求的 select title marker。plan extension 的 submit-review 挂起审批时
+ * 以此 marker 为 title 发 ctx.ui.select（options[0] = PlanReviewRequest JSON，
+ * 类型见 core/types.ts），runtime event-adapter 检测后广播 extension_ui_request
+ * （planReview 标记，与 askUser 标记同构分流），前端审批条渲染三键审批而非
+ * 原始 dialog——marker 控制符 title 落入通用 dialog 会渲染成乱码。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突，
+ * 与 GUI_WIDGET_MARKER / ASK_USER_MARKER 同族（select 通道 marker）。
+ */
+declare const PLAN_REVIEW_MARKER = "\0TAIJI_PLAN_REVIEW:";
 
 /**
  * helpers 需要的 ctx 最小接口。
@@ -364,13 +415,15 @@ declare function callMarkerRpc(ctx: GuiContext, marker: string, payload: string,
 /**
  * ask-user extension 的富交互类型定义。
  *
- * custom() 在 RPC 模式不可用（Component 是代码不是数据），ask-user 的「表单类」
- * 交互改走 select 通道：askUserInteract() 把 AskUserQuestion[] 序列化进 select 的
- * options[0]，runtime event-adapter 检测 ASK_USER_MARKER 透传 questions，
- * 前端 AskUserOverlay 渲染富交互 UI。
+ * GUI 提问交互已迁移统一表单协议（../ui-form：FormQuestion 类型化问题集 +
+ * UI_FORM_MARKER + uiFormInteract，前端 FormOverlay 渲染）——ask_user 工具的
+ * 问题在 ask-user 包内归一 adapter 转为 FormQuestion（choice/text 形态）发送。
  *
- * 这是 ask-user 的定制协议，不是通用富交互协议。
- * 设计参考 ask-user 的 Question 结构。
+ * 本模块保留的 AskUserQuestion / AskUserAnswers 是 ask-user 的 LLM 入参契约与
+ * TUI/解码消费形态：FormAnswers 的 choice/text 部分与 AskUserAnswers 逐字兼容
+ * （键位规则与多选序列化一致），解码 helper（getAskUserAnswer/getAskUserOther）
+ * 消费本类型。legacy 帧（ASK_USER_MARKER）由 runtime event-adapter 分支归一转
+ * FormQuestion（D7 兼容窗口，归一层在 runtime 侧），随窗口末清理退役。
  */
 /**
  * ask-user 富交互问题声明。
@@ -424,30 +477,18 @@ type AskUserAnswers = Record<string, string>;
 declare const ASK_USER_MARKER = "\0TAIJI_ASK_USER";
 
 /**
- * ask-user extension 的富交互 helper（定制层）。
+ * ask-user extension 的富交互 helper（解码层）。
  *
- * askUserInteract() 是 ask-user extension 在 RPC 模式下的交互入口。
- * TUI 模式下 extension 必须自行调 ctx.ui.custom()。
+ * GUI 提问交互已迁移统一表单协议（ui-form 模块的 uiFormInteract + UI_FORM_MARKER，
+ * 设计 ui-presentation-protocol D3）——askUserInteract 传输 helper 随之退役，不保留
+ * deprecated 别名；AskUserQuestion↔FormQuestion 的归一职责下沉 ask-user 包内 adapter
+ * （extensions/universal/ask-user/src/form-adapter.ts）。
  *
- * 走 select 通道 + marker（ASK_USER_MARKER），复用 select 的全部管道逻辑
- * （队列 / 超时 / 回传 / abort），零重复代码。
+ * 本模块保留 answers 解码 helper（getAskUserAnswer / getAskUserOther）：FormAnswers 的
+ * choice/text 部分与 AskUserAnswers 逐字兼容（键位规则：key = header ?? question，
+ * 多选 = JSON 数组，Other = `${key}__other`），解码契约在此单源。
  */
 
-/**
- * ask-user 富交互入口（RPC 模式专用）。
- *
- * RPC 模式：用 select 通道携带 questions 数据，前端渲染富交互 UI。
- * TUI 模式：抛错。extension 必须自行调 ctx.ui.custom()。
- *
- * @param ctx        ExtensionContext（pi 提供）
- * @param questions  交互问题声明
- * @param options    可选：signal（abort）、allowCancel（前端是否显示取消按钮）
- * @returns          answers（key=header/question, value=JSON编码的答案），用户取消返回 null
- */
-declare function askUserInteract(ctx: GuiContext, questions: AskUserQuestion[], options?: {
-    signal?: AbortSignal;
-    allowCancel?: boolean;
-}): Promise<AskUserAnswers | null>;
 /**
  * 从 answers 中提取某个问题的选中值（单选返回 string，多选返回 string[]）。
  *
@@ -459,10 +500,288 @@ declare function getAskUserAnswer(answers: AskUserAnswers, question: AskUserQues
 declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
 /**
  * 类型守卫：验证 unknown 是否为合法的 AskUserQuestion。
- * 用于前端从 runtime 透传的 askUserQuestions（unknown[]）中安全收窄。
+ * 供 legacy 帧消费方（runtime marker 分支侧形状参照 / 扩展自测）收窄 unknown[] 用。
  */
 declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
 
+/**
+ * scheduler 创建确认弹框的协议类型（Draft / FormResult）。
+ *
+ * GUI 创建确认已迁移统一表单协议（ui-form 模块的 uiFormInteract + UI_FORM_MARKER，
+ * 交互入口 extensions/universal/scheduler/src/tool.ts：Draft 经 initial 预填为
+ * ScheduleQuestion 单问整表单，前端 FormOverlay 的 schedule 渲染器回传
+ * ScheduleFormResult）——ScheduleDraft / ScheduleFormResult 即该表单的预填与
+ * 回传形状，TUI 侧 ScheduleCreateComponent 同用本类型。
+ *
+ * 取消不走 FormResult：interact 取消 resolve undefined，execute 返回
+ * cancelled result（D5），任务不创建。
+ *
+ * SCHEDULE_CREATE_MARKER / ScheduleCreateOverlay 为 legacy 窗口语义（旧 npm 帧
+ * 由 runtime event-adapter 识别 / 迁移溯源锚点），随 D7 窗口末清理退役。
+ *
+ * 这是 scheduler 创建路径的定制协议，不是通用富交互协议（与 ask-user 同理）。
+ */
+/**
+ * 执行模式：once = 一次性（schedule 为 dateToOnceCron 折叠的一次性 cron）；
+ * recurring = 循环（duration 或 cron）。
+ */
+type ScheduleKind = 'once' | 'recurring';
+/** 创建确认草稿（extension → 前端，LLM 参数即预填值） */
+interface ScheduleDraft {
+    /** LLM 判定的执行模式，用户可改 */
+    kind: ScheduleKind;
+    /**
+     * recurring：duration（如 5m/2h）或 cron；once：已折叠的一次性 cron
+     * （唯一时间来源，表单时间初值由 onceCronToDate 还原，D2）
+     */
+    schedule: string;
+    /** scoped model id；缺省 = 跟随会话当前模型 */
+    model?: string;
+    /** agent 起草的提示词 */
+    prompt: string;
+    /** 任务名（同现有工具参数，高级选项） */
+    name?: string;
+    /** 过期时间（同现有工具参数，高级选项） */
+    expires?: string;
+    /** scoped models 列表，前端不再自取 */
+    models: string[];
+    /** 会话当前模型 id（前端预选标记） */
+    currentModel?: string;
+}
+/**
+ * 创建确认回传（前端 → extension）。
+ * 取消不走此形状：select resolve undefined → execute 返回 cancelled result（D5）。
+ */
+interface ScheduleFormResult {
+    action: 'create';
+    kind: ScheduleKind;
+    /** 用户确认后的最终形态（once = 经 dateToOnceCron 折叠的一次性 cron） */
+    schedule: string;
+    /** 用户最终选择；未选 = 缺省（跟随会话当前模型） */
+    model?: string;
+    prompt: string;
+    name?: string;
+    expires?: string;
+}
+
+/**
+ * scheduler 创建确认请求的 title marker。runtime event-adapter 和前端 useExtensionUI
+ * 检测此 marker 区分 schedule 创建确认请求与普通 select。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 与 ASK_USER_MARKER 同规范（ask-user 模块同包 marker.ts）。
+ */
+declare const SCHEDULE_CREATE_MARKER = "\0TAIJI_SCHEDULE_CREATE";
+
+/**
+ * scheduler 创建确认的共享协议资产（定制交互 helper 已退役）。
+ *
+ * scheduleCreateInteract() 已随统一提问表单协议迁移退役（ui-presentation-protocol
+ * D3/u6，直接退役不保留 deprecated 别名）：scheduler 的创建确认改走
+ * uiFormInteract() + UI_FORM_MARKER（ScheduleQuestion 形态，initial 预填草稿），
+ * 交互入口在 extensions/universal/scheduler/src/tool.ts。
+ *
+ * 本模块保留三类跨端共享资产：
+ * - isScheduleDraft / isScheduleFormResult 形状守卫：前者供 runtime event-adapter
+ *   legacy 分支（SCHEDULE_CREATE_MARKER 帧 payload 判定）与 ui-form 守卫的
+ *   schedule 分支（initial 深度校验）消费；后者供 scheduler 包回包判别
+ *   （uiFormInteract answers[key] 解包后收窄为 ScheduleFormResult）。
+ * - dateToOnceCron / onceCronToDate 时间折叠单点（D2）：GUI（ScheduleForm 渲染器）
+ *   与 TUI（ScheduleCreateComponent）共用本实现，禁止双端各写一份——时间语义
+ *   漂移正是本协议要关闭的失败模式（F1）。
+ *
+ * 时区语义：按本地墙钟时间（croner 对 cron 默认本地解释，datetime 控件与 TUI
+ * 掩码编辑均产出本地墙钟时间）。
+ */
+
+/**
+ * 类型守卫：验证 unknown 是否为合法的 ScheduleDraft。
+ * 用于 runtime event-adapter 判定 marker select 的 payload 是否为本协议 draft
+ * （检测失败降级普通 select），以及前端从 runtime 透传值中安全收窄。
+ * 字段白名单校验（与 isAskUserQuestion 同构）：可选字段校验类型，未知附加字段忽略。
+ */
+declare function isScheduleDraft(value: unknown): value is ScheduleDraft;
+/** 回传形状守卫（导出消费：scheduler 包对 uiFormInteract answers[key] 解包值收窄；
+ *  FormOverlay schedule 渲染器提交的 value = JSON.stringify(ScheduleFormResult)） */
+declare function isScheduleFormResult(value: unknown): value is ScheduleFormResult;
+/**
+ * 本地墙钟时刻 → 一次性 cron（5 段 `分 时 日 月 *`）。
+ *
+ * 一次性 cron 语义：具体日 + 具体月 + 星期通配 → croner 天然只命中一次（S8/D2），
+ * scheduler 现有 parseSchedule 直接接受，service 层零感知。
+ */
+declare function dateToOnceCron(date: Date): string;
+declare function onceCronToDate(cron: string, now?: Date): Date | null;
+
+/**
+ * 统一提问表单协议（ui-form）的类型定义。
+ *
+ * 把 plan / scheduler / ask-user 三个 extension 的提问交互收口为一个表单协议：
+ * 问题即数据（类型化问题集），GUI 链路统一（wire 协议 + 渲染器）——多问 = 多 tab，
+ * 单问 = 单视图。extension 侧经 uiFormInteract() 序列化进 select 的 options[0]，
+ * runtime event-adapter 检测 UI_FORM_MARKER 广播 form 帧，前端 FormOverlay
+ * 按问题 type 分派渲染器（choice / text / schedule）。
+ *
+ * 这是提问交互的通用协议（区别于 ask-user / scheduler-create 的定制协议）。
+ * formQuestions 在 TUI 无呈现语义——TUI 数据通路各 extension 自行渲染（设计 D8
+ * 有意取舍），消费方为 extension 自有组件。
+ */
+
+/**
+ * choice 问题：互斥/多选选项。
+ * 对应现 AskUserQuestion 有 options 的形态（multiSelect → multi 重命名）。
+ */
+interface ChoiceQuestion {
+    type: 'choice';
+    /** Tab 标签 / 简短标题。answers key 缺省 fallback 到 question 全文（与 askUserKey 同规则） */
+    header?: string;
+    /** 完整问题文本。也作为 answers 的 fallback key（header 缺失时） */
+    question: string;
+    /** 上下文摘要（可选）。显示在问题上方，帮用户理解背景 */
+    context?: string;
+    /** 互斥选项列表（无 options 的纯自由文本问题用 TextQuestion 表达） */
+    options: FormOption[];
+    /** 是否允许多选 */
+    multi?: boolean;
+    /** 是否允许自由文本输入（Other）。默认 true（同 ask-user 现状），设 false 则不追加 */
+    allowOther?: boolean;
+}
+/** 选项声明（label 即选中值：协议无独立 value 字段，回传统一用 label） */
+interface FormOption {
+    label: string;
+    /** 描述（可选）。显示在 label 下方，解释 tradeoff */
+    description?: string;
+}
+/**
+ * text 问题：纯自由文本输入（无 options）。
+ * 协议值域完备性要求保留：AskUserQuestion.options 声明可选，归一层 type 推断
+ * 与消费端必须能表达「无 options」的合法旧形态（设计 D2）。
+ */
+interface TextQuestion {
+    type: 'text';
+    header?: string;
+    question: string;
+    context?: string;
+}
+/**
+ * schedule 问题：时间输入领域原语（非 scheduler 专属形状）。
+ * 渲染器 = scheduler 创建确认整表单（ScheduleForm，单 tab 整表单收编，设计 D2）；
+ * 预填草稿经 initial 直传，打开即可一键确认。
+ */
+interface ScheduleQuestion {
+    type: 'schedule';
+    header?: string;
+    question: string;
+    context?: string;
+    /** 预填草稿（可选）。ScheduleDraft 复用 scheduler-create 模块定义（零新增依赖方向） */
+    initial?: ScheduleDraft;
+}
+/** 类型化问题集（判别联合：按 type 分派渲染器） */
+type FormQuestion = ChoiceQuestion | TextQuestion | ScheduleQuestion;
+/**
+ * 统一表单回传结果。key = header ?? question（fallback 规则与 askUserKey 一致）。
+ *
+ * 答案编码规则（choice/text 部分与现 AskUserAnswers 逐字兼容，含 Other 键规则
+ * 与多选序列化——ask-user 消费方 getAskUserAnswer / getAskUserOther 零改动）：
+ * - choice 单选：value = 选中项的 label
+ * - choice 多选：value = JSON.stringify(选中项 label 数组)，如 '["pg","mysql"]'
+ * - Other 文本：单独 key `${key}__other`，value = 自由文本（不混进选中项数组）
+ * - text：value = 自由文本，**键位 `${key}__other`**（逐字继承现状纯 other 形态——
+ *   无 options 题答案只写 __other 不写主 key，写主 key 会令 getAskUserAnswer 键位翻转）
+ * - schedule：value = JSON.stringify(ScheduleFormResult)（单问表单下 answers 恰一键）
+ */
+type FormAnswers = Record<string, string>;
+
+/**
+ * 统一提问表单（ui-form）请求的 title marker。runtime event-adapter 和前端
+ * useExtensionUI 检测此 marker 区分表单请求与普通 select。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 与 ASK_USER_MARKER 同规范（ask-user 模块同包 marker.ts）。
+ */
+declare const UI_FORM_MARKER = "\0TAIJI_UI_FORM";
+
+/**
+ * 统一提问表单（ui-form）协议 helper。
+ *
+ * uiFormInteract() 是 plan / scheduler / ask-user 三方提问在 RPC 模式下的统一入口
+ * （设计 ui-presentation-protocol D3）。走 select 通道 + marker（UI_FORM_MARKER），
+ * 传输核复用 callMarkerRpc 原语，四态判别返回而非抛错（除 RPC 门外）：
+ * - cancelled / timeout → 调用方按「用户未作答」折叠；
+ * - channel-error → 通道契约破坏（含 echo 检测命中的旧宿主组合），调用方按各自
+ *   策略折叠（scheduler 禁用工具 + throw / plan 折 cancelled result 留 plan mode）；
+ * - non-json → 协议版本错配类故障。
+ *
+ * TUI 模式不代劳渲染（formQuestions 在 TUI 无呈现语义，各 extension 自有组件
+ * 消费，设计 D8）：误调抛错指明恢复动作，返回判别失败会与「用户取消」混淆。
+ */
+
+/** uiFormInteract 的判别结果：成功收窄为 FormAnswers；失败按 callMarkerRpc 四态折叠。
+ * message 仅 channel-error 的 echo 命中态携带（升级指引，见 uiFormInteract 内注释），
+ * 供调用方折叠时透出——各调用方对 channel-error 的折叠策略不同，文案由调用方决定是否使用 */
+type UiFormInteractResult = {
+    ok: true;
+    answers: FormAnswers;
+} | {
+    ok: false;
+    reason: 'cancelled' | 'timeout' | 'channel-error' | 'non-json';
+    message?: string;
+};
+interface UiFormInteractOptions {
+    /** 透传 select dialog：abort 后 pi 本地 resolve(undefined) → cancelled */
+    signal?: AbortSignal;
+    /** 前端是否显示取消按钮（默认 true，沿已退役的 askUserInteract 的默认值先例） */
+    allowCancel?: boolean;
+    /**
+     * 源元数据：本次表单提交后是否有 turn 预期（respond 分型判据，form-submit-busy-convergence D1）。
+     *
+     * 三态语义（D2）：`true | undefined` = 有 turn 预期——提交型桥接 message_start 照旧
+     * （undefined 为缺省态：存量扩展与未声明者，桥接 = 现状，方向安全）；
+     * `false` = 无 turn 预期——命令 handler 内 select（提交后结构性无 turn），respond 侧
+     * 提交即收尾，消除 30s 假忙。消费方判定必须是 `=== false` 显式式：truthy 简化
+     * （`!expectTurn`）会把 undefined 也当无 turn、误清桥接（D2 被否谱系）。
+     *
+     * 缺省（undefined）经 stripUndefined 剥键——未声明者的 wire payload 逐字节不变，
+     * 旧 runtime 读不到即忽略（JSON.parse 容忍未知键）。
+     */
+    expectTurn?: boolean;
+    /** 失败留痕注入（echo 命中 / 形状错），日志策略归调用方 */
+    log?: (msg: string, detail?: object) => void;
+}
+/**
+ * 统一提问表单入口（RPC 模式专用）。
+ *
+ * RPC 模式：select 通道携带类型化问题集，前端 FormOverlay 渲染表单，回传 FormAnswers。
+ * TUI 模式：抛错，extension 自行渲染（ctx.ui.custom 或原生 select）。
+ *
+ * 确认交互不设墙钟超时（任务级正常路径无墙钟，AGENTS.md 超时默认原则）：
+ * options 不提供 timeout 入口，timeout 态仅由「未 abort 的 undefined resolve」产生。
+ */
+declare function uiFormInteract(ctx: GuiContext, form: FormQuestion[], opts?: UiFormInteractOptions): Promise<UiFormInteractResult>;
+
+/**
+ * 统一提问表单（ui-form）的形状守卫。
+ *
+ * isFormQuestion 按 type 判别分支逐项校验（白名单风格：必填字段类型校验、可选
+ * 字段校验、未知字段忽略——与 isAskUserQuestion / isScheduleDraft 同构语义）。
+ * 三个消费点失败策略各异（设计 D2）：
+ * - 发送侧（uiFormInteract 内）：不合法项抛错（调用方编码 bug，fail-fast）；
+ * - event-adapter：逐项过滤，合法项 ≥1 才产 form 帧、全不合法降级普通 select；
+ * - renderer：复核守卫，不合法项跳过 + warn，全部不合法 → overlay 错误占位仅取消可点。
+ *
+ * isFormAnswers 校验回包形状（Record<string, string>）：键动态（key = header ??
+ * question）无法枚举白名单，故只校验值域全 string；JSON 合法但非本形状由
+ * uiFormInteract 折叠 non-json（协议版本错配类故障）。
+ */
+
+/**
+ * 类型守卫：验证 unknown 是否为合法的 FormQuestion（choice / text / schedule 三分支）。
+ * 用于发送侧 fail-fast、event-adapter 逐项过滤与 renderer 复核（三消费点见文件头）。
+ */
+declare function isFormQuestion(value: unknown): value is FormQuestion;
+/** 类型守卫：验证 unknown 是否为合法的 FormAnswers（值域全 string 的普通对象） */
+declare function isFormAnswers(value: unknown): value is FormAnswers;
+
 /**
  * session-manager 请求的 title marker。runtime event-adapter 和 handler
  * 检测此 marker 区分 session-manager 请求与普通 select。
@@ -851,4 +1170,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 CollectPendingIdsOptions, type DualWidgetContent, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, INFLIGHT_REPORT_ACK, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_INFLIGHT_MARKER, 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 StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, type TreeItem, type TreeItemIcon, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, applyPendingDiff, askUserInteract, callMarkerRpc, collectActivePendingIds, extractGui, firstContentText, formatChannelErrorText, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, scanPendingEntries, setWidgetDual, 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 FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, INFLIGHT_REPORT_ACK, 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, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_INFLIGHT_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, 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 StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, applyPendingDiff, callMarkerRpc, collectActivePendingIds, dateToOnceCron, extractGui, firstContentText, formatChannelErrorText, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, onceCronToDate, scanPendingEntries, setWidgetDual, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -14,6 +14,7 @@ var PROTOCOL_VERSION = 1;
 
 // src/core/markers.ts
 var GUI_WIDGET_MARKER = "\0TAIJI_GUI_WIDGET:";
+var PLAN_REVIEW_MARKER = "\0TAIJI_PLAN_REVIEW:";
 
 // src/core/helpers.ts
 function isGuiCapable(ctx) {
@@ -158,31 +159,6 @@ async function callMarkerRpc(ctx, marker, payload, opts) {
 var ASK_USER_MARKER = "\0TAIJI_ASK_USER";
 
 // src/extensions/ask-user/helpers.ts
-async function askUserInteract(ctx, questions, options) {
-  if (questions.length === 0) return {};
-  if (isGuiCapable(ctx) && ctx.ui?.select) {
-    const payload = JSON.stringify(stripUndefined({
-      questions,
-      allowCancel: options?.allowCancel ?? true
-    }));
-    const value = await ctx.ui.select(
-      ASK_USER_MARKER,
-      // title = marker，runtime/前端据此识别
-      [payload],
-      // options[0] = JSON payload（runtime 解析）
-      { signal: options?.signal }
-    );
-    if (value === void 0) return null;
-    try {
-      return JSON.parse(value);
-    } catch {
-      return null;
-    }
-  }
-  throw new Error(
-    "askUserInteract() is only available in RPC mode. In TUI mode, use ctx.ui.custom() with your own Component directly."
-  );
-}
 function askUserKey(question) {
   return question.header ?? question.question;
 }
@@ -209,18 +185,173 @@ function isAskUserQuestion(value) {
   return typeof q.question === "string" && (q.header === void 0 || typeof q.header === "string") && (q.options === void 0 || Array.isArray(q.options)) && (q.multiSelect === void 0 || typeof q.multiSelect === "boolean") && (q.allowOther === void 0 || typeof q.allowOther === "boolean");
 }
 
+// src/extensions/scheduler-create/marker.ts
+var SCHEDULE_CREATE_MARKER = "\0TAIJI_SCHEDULE_CREATE";
+
+// src/extensions/scheduler-create/helpers.ts
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOptionalString(v) {
+  return v === void 0 || typeof v === "string";
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((m) => typeof m === "string");
+}
+function isScheduleDraft(value) {
+  if (!isPlainRecord(value)) return false;
+  const d = value;
+  return (d.kind === "once" || d.kind === "recurring") && typeof d.schedule === "string" && isOptionalString(d.model) && typeof d.prompt === "string" && isOptionalString(d.name) && isOptionalString(d.expires) && isStringArray(d.models) && isOptionalString(d.currentModel);
+}
+function isScheduleFormResult(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const r = value;
+  return r.action === "create" && (r.kind === "once" || r.kind === "recurring") && typeof r.schedule === "string" && (r.model === void 0 || typeof r.model === "string") && typeof r.prompt === "string" && (r.name === void 0 || typeof r.name === "string") && (r.expires === void 0 || typeof r.expires === "string");
+}
+function dateToOnceCron(date) {
+  return `${date.getMinutes()} ${date.getHours()} ${date.getDate()} ${date.getMonth() + 1} *`;
+}
+var ONCE_CRON_FIELD_COUNT = 5;
+var CRON_MINUTE_MAX = 59;
+var CRON_HOUR_MAX = 23;
+var CRON_DAY_MIN = 1;
+var CRON_DAY_MAX = 31;
+var CRON_MONTH_MIN = 1;
+var CRON_MONTH_MAX = 12;
+var ONCE_CRON_MAX_YEAR_LOOKAHEAD = 8;
+function parseOnceCronNumbers(parts) {
+  const [minute, hour, day, month] = parts;
+  if (![minute, hour, day, month].every((seg) => /^\d+$/.test(seg))) return null;
+  return [Number(minute), Number(hour), Number(day), Number(month)];
+}
+function isOnceCronValueOutOfRange(m, h, d, mon) {
+  return m > CRON_MINUTE_MAX || h > CRON_HOUR_MAX || d < CRON_DAY_MIN || d > CRON_DAY_MAX || mon < CRON_MONTH_MIN || mon > CRON_MONTH_MAX;
+}
+function onceCronToDate(cron, now = /* @__PURE__ */ new Date()) {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== ONCE_CRON_FIELD_COUNT || parts[4] !== "*") return null;
+  const numbers = parseOnceCronNumbers(parts);
+  if (numbers === null) return null;
+  const [m, h, d, mon] = numbers;
+  if (isOnceCronValueOutOfRange(m, h, d, mon)) return null;
+  const startYear = now.getFullYear();
+  for (let year = startYear; year <= startYear + ONCE_CRON_MAX_YEAR_LOOKAHEAD; year++) {
+    const candidate = new Date(year, mon - 1, d, h, m, 0, 0);
+    if (candidate.getMonth() !== mon - 1 || candidate.getDate() !== d) continue;
+    if (candidate.getTime() >= now.getTime()) return candidate;
+  }
+  return null;
+}
+
+// src/extensions/ui-form/marker.ts
+var UI_FORM_MARKER = "\0TAIJI_UI_FORM";
+
+// src/extensions/ui-form/guards.ts
+function isPlainRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFormOption(value) {
+  if (!isPlainRecord2(value)) return false;
+  const o = value;
+  return typeof o.label === "string" && (o.description === void 0 || typeof o.description === "string");
+}
+function isFormOptionArray(value) {
+  return Array.isArray(value) && value.every(isFormOption);
+}
+function isFormQuestion(value) {
+  if (!isPlainRecord2(value)) return false;
+  const q = value;
+  if (typeof q.question !== "string") return false;
+  if (q.header !== void 0 && typeof q.header !== "string") return false;
+  if (q.context !== void 0 && typeof q.context !== "string") return false;
+  if (q.type === "choice") {
+    return isFormOptionArray(q.options) && (q.multi === void 0 || typeof q.multi === "boolean") && (q.allowOther === void 0 || typeof q.allowOther === "boolean");
+  }
+  if (q.type === "text") return true;
+  if (q.type === "schedule") {
+    return q.initial === void 0 || isScheduleDraft(q.initial);
+  }
+  return false;
+}
+function isFormAnswers(value) {
+  if (!isPlainRecord2(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+// src/extensions/ui-form/helpers.ts
+var RESPONSE_PREVIEW_LENGTH2 = 200;
+var ECHO_UPGRADE_HINT = "taiji host too old for form protocol \u2014 upgrade taiji or pin extension version";
+function assertFormQuestionsValid(form) {
+  const invalidIndex = form.findIndex((q) => !isFormQuestion(q));
+  if (invalidIndex >= 0) {
+    throw new Error(
+      `uiFormInteract(): form[${invalidIndex}] is not a valid FormQuestion (type must be 'choice' | 'text' | 'schedule' with required fields present) \u2014 fix the question definition at the call site.`
+    );
+  }
+}
+function assertRpcModeAvailable(ctx) {
+  if (!(isGuiCapable(ctx) && ctx.ui?.select)) {
+    throw new Error(
+      "uiFormInteract() is only available in RPC mode. In TUI mode, use ctx.ui.custom() with your own Component directly."
+    );
+  }
+}
+function parseFormAnswersResponse(rpcValue, payload, opts) {
+  if (rpcValue === payload) {
+    opts?.log?.("ui-form response echoed the request payload (host does not understand UI_FORM_MARKER)", {
+      responseHead: rpcValue.slice(0, RESPONSE_PREVIEW_LENGTH2)
+    });
+    return { ok: false, reason: "channel-error", message: ECHO_UPGRADE_HINT };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rpcValue);
+  } catch {
+    return { ok: false, reason: "non-json" };
+  }
+  if (!isFormAnswers(parsed)) {
+    opts?.log?.("ui-form response is not a FormAnswers record", {
+      responseHead: rpcValue.slice(0, RESPONSE_PREVIEW_LENGTH2)
+    });
+    return { ok: false, reason: "non-json" };
+  }
+  return { ok: true, answers: parsed };
+}
+async function uiFormInteract(ctx, form, opts) {
+  if (form.length === 0) return { ok: true, answers: {} };
+  assertFormQuestionsValid(form);
+  assertRpcModeAvailable(ctx);
+  const payload = JSON.stringify(stripUndefined({
+    formQuestions: form,
+    allowCancel: opts?.allowCancel ?? true,
+    // expectTurn 原样透传、不设 ?? true 缺省：undefined 由 stripUndefined 剥键保持
+    // 存量 wire 逐字节不变，三态归 respond 分型按 === false 显式判定（D1/D2）
+    expectTurn: opts?.expectTurn
+  }));
+  const rpcResult = await callMarkerRpc(
+    ctx,
+    UI_FORM_MARKER,
+    payload,
+    { signal: opts?.signal, log: opts?.log }
+  );
+  if (!rpcResult.ok) {
+    return { ok: false, reason: rpcResult.reason };
+  }
+  return parseFormAnswersResponse(rpcResult.value, payload, opts);
+}
+
 // src/extensions/session-manager/types.ts
 function isRecord(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-function isOptionalString(v) {
+function isOptionalString2(v) {
   return v === void 0 || typeof v === "string";
 }
 function isSessionIdParams(v) {
   return isRecord(v) && typeof v.sessionId === "string";
 }
 function isSessionManagerCreateParams(v) {
-  return isRecord(v) && isOptionalString(v.cwd) && isOptionalString(v.label) && isOptionalString(v.prompt);
+  return isRecord(v) && isOptionalString2(v.cwd) && isOptionalString2(v.label) && isOptionalString2(v.prompt);
 }
 function isSessionManagerSendParams(v) {
   return isRecord(v) && typeof v.sessionId === "string" && typeof v.prompt === "string";
@@ -366,15 +497,18 @@ export {
   MAX_TERMINAL_REGISTRY_ENTRIES,
   PENDING_REGISTER_ENTRY_TYPE,
   PENDING_UNREGISTER_ENTRY_TYPE,
+  PLAN_REVIEW_MARKER,
   PROTOCOL_VERSION,
+  SCHEDULE_CREATE_MARKER,
   SESSION_MANAGER_ACTIONS,
   SESSION_MANAGER_MARKER,
   SUBAGENTS_ENGINES_FILENAME,
   SUBAGENT_INFLIGHT_MARKER,
+  UI_FORM_MARKER,
   applyPendingDiff,
-  askUserInteract,
   callMarkerRpc,
   collectActivePendingIds,
+  dateToOnceCron,
   extractGui,
   firstContentText,
   formatChannelErrorText,
@@ -391,10 +525,14 @@ export {
   isBridgeSyncPayload,
   isBridgeToolExecuteResponse,
   isChannelErrorResult,
+  isFormAnswers,
+  isFormQuestion,
   isGuiCapable,
   isGuiComponent,
   isGuiRenderResult,
   isInFlightReportAck,
+  isScheduleDraft,
+  isScheduleFormResult,
   isSessionManagerAbortParams,
   isSessionManagerCreateParams,
   isSessionManagerHistoryParams,
@@ -405,7 +543,9 @@ export {
   isSyncedTool,
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
+  onceCronToDate,
   scanPendingEntries,
   setWidgetDual,
+  uiFormInteract,
   validateWidgetIconPaths
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.12.0",
+  "version": "0.13.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",