@zhushanwen/extension-protocol 0.12.0 → 0.14.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 渲染协议核心类型定义。
@@ -80,6 +80,26 @@ interface GuiComponentProps {
          */
         sections?: GuiComponent[][];
     };
+    /**
+     * 操作按钮栏——GuiComponent 协议首个交互原语（设计 AP-3）。
+     * 点击经宿主壳 provide 的执行器走既有命令链（commandRegistry.execute → WS
+     * plugin.executeCommand），协议不新增回调通道（设计 §3.3 D2）。
+     * 未含此 type 的旧宿主自动降级 ansi-text 可读文本，PROTOCOL_VERSION 不 bump
+     * （设计 §3.3 D8，降级契约 P5）。
+     */
+    'action-bar': {
+        items: {
+            id: string;
+            label: string;
+            /** 视觉档位：只保留当前唯一实际消费的 danger（删除按钮）；更多档位有真实消费方时再加 */
+            kind?: 'danger';
+            disabled?: boolean;
+            /** 缺省 = 纯展示项（不可点、弱化样式） */
+            commandId?: string;
+            /** 只许标量：args 原样传给插件 handler，禁嵌套对象防无 schema 结构化旁路（设计 AP-3 校验） */
+            args?: Record<string, string | number | boolean>;
+        }[];
+    };
     /** 自定义组件——逃生口（仅限内置 extension 编译期注册） */
     'custom': {
         component: string;
@@ -145,6 +165,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 +213,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 +435,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 +497,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 +520,458 @@ 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;
 
+type ScheduleSpec = {
+    mode: 'cron';
+    cronExpression: string;
+} | {
+    mode: 'interval';
+    intervalMs: number;
+};
+type TaskKind = 'once' | 'recurring';
+type TaskStatus = 'success' | 'failed';
+interface ScheduledTask {
+    id: string;
+    name: string;
+    prompt: string;
+    kind: TaskKind;
+    schedule: ScheduleSpec;
+    model?: string;
+    enabled: boolean;
+    createdAt: number;
+    nextRunAt: number;
+    expiresAt?: number;
+    runCount: number;
+    lastRunAt?: number;
+    lastStatus?: TaskStatus;
+    lastError?: string;
+    history: ExecutionRecord[];
+    ownerSessionFile?: string;
+    pending?: boolean;
+}
+interface ExecutionRecord {
+    at: number;
+    status: TaskStatus;
+}
+/**
+ * history 裁剪上限（ext-simplify-08 L5 单点）：runtime 侧 dispatch 累积
+ * （onDispatchSuccess）与 replay 侧 advance 折叠共用同一上限——
+ * 双处各持字面量会漂移（曾 runtime.ts / replay.ts 各写一份 20），收敛到本文件单点导出。
+ */
+declare const HISTORY_LIMIT = 20;
+/**
+ * 追加执行记录并按 HISTORY_LIMIT 裁剪（ext-simplify-17 B4 单点）：runtime 侧 dispatch
+ * 累积与 replay 侧 advance 折叠共用的 push+trim——三处内联时与上限字面量同源存在
+ * 「漏改一处」漂移风险，随上限一并收敛。
+ */
+declare function appendExecutionRecord(task: ScheduledTask, at: number, status: TaskStatus): void;
+/**
+ * pi.appendEntry 写入的 custom entry customType 标识（ext-simplify-17 B1 单点）：
+ * backend.appendEntry 写入 / replay 折叠过滤 / importer 旧 store 导入三处共用——
+ * 各持字面量时「改一处漏两处」会使写入与重放识别脱节（写入新标识、重放不认，任务静默丢失）。
+ */
+declare const TASK_ENTRY_TYPE = "pi-scheduler:task";
+/**
+ * upsert op 携带的全量任务快照（不含 ownerSessionFile / pending）。
+ * ownerSessionFile 放在 op 顶层（见 SchedulerEntryOp.upsert），
+ * pending 是运行时标记不持久化。其余字段与 ScheduledTask 对齐。
+ */
+interface TaskSnapshot {
+    id: string;
+    name: string;
+    prompt: string;
+    kind: TaskKind;
+    schedule: ScheduleSpec;
+    model?: string;
+    enabled: boolean;
+    createdAt: number;
+    nextRunAt: number;
+    expiresAt?: number;
+    runCount: number;
+    lastRunAt?: number;
+    lastStatus?: TaskStatus;
+    lastError?: string;
+    history: ExecutionRecord[];
+}
+/**
+ * pi.appendEntry(TASK_ENTRY_TYPE, SchedulerEntryOp) 写入 session JSONL 的 op 联合类型。
+ *
+ * advance.status 固定为 'success'（CL8）：对齐现有 TaskStatus='success'|'failed'，
+ * 而非继承的 DM-SCHEDULER-OP 词表 'ok'。唯一 emit 值——按 CL7，advance 仅在 dispatch
+ * 成功（nextRunAt 实际推进）时 append，失败 dispatch 不 append（transient 失败重试语义）。
+ * fold 的 `task.lastStatus = entry.status` 直接赋值合法（'success' 属 TaskStatus）。
+ */
+type SchedulerEntryOp = {
+    op: 'upsert';
+    taskId: string;
+    ownerSessionFile: string;
+    task: TaskSnapshot;
+} | {
+    op: 'advance';
+    taskId: string;
+    nextRunAt: number;
+    at: number;
+    status: 'success';
+} | {
+    op: 'toggle';
+    taskId: string;
+    enabled: boolean;
+    nextRunAt?: number;
+} | {
+    op: 'delete';
+    taskId: string;
+};
+/**
+ * TaskSnapshot → ScheduledTask（replay 侧重建）：pending 不持久化故不恢复，
+ * ownerSessionFile 由调用方（replay applyUpsert）从 op 顶层补回。history 逐项深拷贝——
+ * 避免恢复出的运行时 task 与快照共享数组/元素引用（task 后续被 mutate 时不污染快照）。
+ */
+declare function snapshotToTask(snapshot: TaskSnapshot): ScheduledTask;
+
+/**
+ * 折叠期降级日志注入点：包内不持有任何 logger 依赖（零 pi 依赖收敛），由调用方注入。
+ * 省略时降级路径静默（折叠行为不受影响——返回值与注入无关）。
+ */
+interface ReplayFoldOptions {
+    warn?: (message: string, context?: unknown) => void;
+}
+/**
+ * CustomEntry 的最小可识别形状（duck-typed，不依赖 @earendil-works/pi-coding-agent 的
+ * 具体 SessionEntry 类型）。与 pending-notifications/state.ts、goal/ports.ts 同款：
+ * 纯函数可独立单测，调用方传入真实 SessionEntry[] 时按结构兼容。
+ */
+interface SchedulerEntryLike {
+    type: string;
+    customType?: string;
+    data?: unknown;
+}
+/**
+ * 从 CustomEntry 序列折叠恢复 per-task 末态（event sourcing）。
+ *
+ * 两类调用方：
+ * - pi 扩展 session_start 重放：PiSchedulerBackend.loadTasks() 委托本函数，把当前 session 的
+ *   TASK_ENTRY_TYPE custom entries 折叠成运行时任务 Map。
+ * - taiji plugin 条目镜像：对 readEntries 拉取的累计 entries 调用本函数折叠出任务表
+ *   （与扩展同一实现，插件与扩展折叠结果构造性一致）。
+ *
+ * 两步：
+ * ① 全量折叠（foldEntries）——遍历 customType===TASK_ENTRY_TYPE 的 entries，按 op 类型折叠：
+ *    - upsert → 用快照重建任务（ownerSessionFile 来自 op 顶层）
+ *    - advance → nextRunAt=新值 / lastRunAt=at / runCount++ / history.push(裁20) / lastStatus=status（gap2）
+ *    - toggle → enabled=新值
+ *    - delete → 从 Map 移除（后续同 taskId 的 advance/toggle 对不存在 taskId 为 no-op，安全）
+ *   advance/toggle/delete 对不存在的 taskId 为 no-op，因此 fork 继承的完整序列必须先全量折叠，
+ *   不能在处理 upsert 时按 owner 跳过（否则后续无 owner 字段的 op 会作用于「不存在的 taskId」丢失）。
+ * ② 折叠完成后按 task.ownerSessionFile !== currentSessionFile 整体过滤（gap1，filterNonOwnerTasks）：
+ *   移除 fork 继承的非 owner 任务——fork 出的 session B 继承了 owner=A 的 upsert+advance 序列，
+ *   但 B 不应拥有 A 的任务，重放后整体过滤掉。
+ *
+ * append-only 时序保证 nextRunAt 不回退（D1）：advance entry 按写入顺序折叠，自然取到最后推进值。
+ *
+ * getEntries 解析/迭代异常 → options.warn + 返回空 Map（gap4）：降级为无任务而非崩溃调用方。
+ */
+declare function replayFoldEntries(entries: Iterable<SchedulerEntryLike>, currentSessionFile: string | undefined, options?: ReplayFoldOptions): Map<string, ScheduledTask>;
+
+declare const MS_PER_DAY = 86400000;
+declare const MS_PER_HOUR = 3600000;
+declare const MS_PER_MINUTE = 60000;
+declare const MS_PER_SECOND = 1000;
+/** 格式化毫秒数为可读 duration 字符串。优先使用最大单位：300000 → "5m"，不是 "300s"。 */
+declare function formatDuration(ms: number): string;
+/** Format ScheduleSpec to readable string. kind 区分 once/recurring（once 显示 'once in X' 而非误导性的 'every X'）。 */
+declare function formatSchedule(spec: ScheduleSpec, kind?: TaskKind): string;
+/**
+ * 格式化时间戳为相对时间字符串。
+ * 未来: "in 5m"
+ * 过去: "5m ago"
+ * 当前(+-5s): "now"
+ *
+ * now 可选参数：基准时间戳，默认 Date.now()。测试可传固定值快进/锁定，
+ * 生产调用方无需传（参数可选，行为不变）。
+ */
+declare function formatRelativeTime(timestamp: number, now?: number): string;
+
+/**
+ * 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 +1360,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 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_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 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, 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, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, onceCronToDate, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, 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,343 @@ 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/types.ts
+var HISTORY_LIMIT = 20;
+function appendExecutionRecord(task, at, status) {
+  task.history.push({ at, status });
+  if (task.history.length > HISTORY_LIMIT) task.history.shift();
+}
+var TASK_ENTRY_TYPE = "pi-scheduler:task";
+function snapshotToTask(snapshot) {
+  return {
+    id: snapshot.id,
+    name: snapshot.name,
+    prompt: snapshot.prompt,
+    kind: snapshot.kind,
+    schedule: snapshot.schedule,
+    model: snapshot.model,
+    enabled: snapshot.enabled,
+    createdAt: snapshot.createdAt,
+    nextRunAt: snapshot.nextRunAt,
+    expiresAt: snapshot.expiresAt,
+    runCount: snapshot.runCount,
+    lastRunAt: snapshot.lastRunAt,
+    lastStatus: snapshot.lastStatus,
+    lastError: snapshot.lastError,
+    history: snapshot.history.map((h) => ({ ...h }))
+  };
+}
+
+// src/extensions/scheduler/replay.ts
+function toErrorMessage(e) {
+  return e instanceof Error ? e.message : String(e);
+}
+function replayFoldEntries(entries, currentSessionFile, options) {
+  try {
+    const tasks = /* @__PURE__ */ new Map();
+    foldEntries(entries, tasks, options);
+    filterNonOwnerTasks(tasks, currentSessionFile);
+    return tasks;
+  } catch (err) {
+    options?.warn?.("replayFoldEntries failed", { error: toErrorMessage(err) });
+    return /* @__PURE__ */ new Map();
+  }
+}
+function foldEntries(entries, tasks, options) {
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== TASK_ENTRY_TYPE) continue;
+    if (!isSchedulerEntryOp(entry.data)) continue;
+    const op = entry.data;
+    try {
+      applyOp(tasks, op);
+    } catch (err) {
+      options?.warn?.("skipping corrupted scheduler entry", { error: toErrorMessage(err) });
+      continue;
+    }
+  }
+}
+function applyOp(tasks, op) {
+  switch (op.op) {
+    case "upsert":
+      applyUpsert(tasks, op);
+      break;
+    case "advance":
+      applyAdvance(tasks, op);
+      break;
+    case "toggle":
+      applyToggle(tasks, op);
+      break;
+    case "delete":
+      applyDelete(tasks, op);
+      break;
+  }
+}
+function applyUpsert(tasks, op) {
+  tasks.set(op.taskId, { ...snapshotToTask(op.task), ownerSessionFile: op.ownerSessionFile });
+}
+function applyAdvance(tasks, op) {
+  const task = tasks.get(op.taskId);
+  if (!task) return;
+  task.nextRunAt = op.nextRunAt;
+  task.lastRunAt = op.at;
+  task.runCount += 1;
+  appendExecutionRecord(task, op.at, op.status);
+  task.lastStatus = op.status;
+}
+function applyToggle(tasks, op) {
+  const task = tasks.get(op.taskId);
+  if (!task) return;
+  task.enabled = op.enabled;
+  if (op.nextRunAt !== void 0) task.nextRunAt = op.nextRunAt;
+}
+function applyDelete(tasks, op) {
+  tasks.delete(op.taskId);
+}
+function filterNonOwnerTasks(tasks, currentSessionFile) {
+  for (const [id, task] of tasks) {
+    if (task.ownerSessionFile !== currentSessionFile) {
+      tasks.delete(id);
+    }
+  }
+}
+function isSchedulerEntryOp(data) {
+  if (!data || typeof data !== "object") return false;
+  const record = data;
+  const op = record.op;
+  if (op === "upsert") {
+    return typeof record.taskId === "string" && typeof record.task === "object" && record.task !== null;
+  }
+  if (op === "advance") {
+    return typeof record.taskId === "string" && typeof record.nextRunAt === "number" && typeof record.at === "number" && record.status === "success";
+  }
+  if (op === "toggle") {
+    return typeof record.taskId === "string" && typeof record.enabled === "boolean" && (record.nextRunAt === void 0 || typeof record.nextRunAt === "number");
+  }
+  if (op === "delete") {
+    return typeof record.taskId === "string";
+  }
+  return false;
+}
+
+// src/extensions/scheduler/format.ts
+var MS_PER_DAY = 864e5;
+var MS_PER_HOUR = 36e5;
+var MS_PER_MINUTE = 6e4;
+var MS_PER_SECOND = 1e3;
+var NOW_THRESHOLD_MS = 5e3;
+function formatDuration(ms) {
+  if (ms <= 0) return "0s";
+  const units = [
+    ["d", MS_PER_DAY],
+    ["h", MS_PER_HOUR],
+    ["m", MS_PER_MINUTE],
+    ["s", MS_PER_SECOND]
+  ];
+  for (const [suffix, divisor] of units) {
+    if (ms >= divisor && ms % divisor === 0) {
+      return `${ms / divisor}${suffix}`;
+    }
+  }
+  return `${Math.round(ms / MS_PER_SECOND)}s`;
+}
+function formatSchedule(spec, kind) {
+  if (spec.mode === "interval") {
+    return kind === "once" ? `once in ${formatDuration(spec.intervalMs)}` : `every ${formatDuration(spec.intervalMs)}`;
+  }
+  return spec.cronExpression;
+}
+function formatRelativeTime(timestamp, now) {
+  const currentTime = now ?? Date.now();
+  const diff = timestamp - currentTime;
+  if (Math.abs(diff) < NOW_THRESHOLD_MS) return "now";
+  const absDiff = Math.abs(diff);
+  const units = [
+    ["d", MS_PER_DAY],
+    ["h", MS_PER_HOUR],
+    ["m", MS_PER_MINUTE],
+    ["s", MS_PER_SECOND]
+  ];
+  let formatted = "";
+  for (const [suffix, divisor] of units) {
+    if (absDiff >= divisor) {
+      const value = Math.floor(absDiff / divisor);
+      formatted = `${value}${suffix}`;
+      break;
+    }
+  }
+  if (!formatted) {
+    formatted = `${Math.round(absDiff / MS_PER_SECOND)}s`;
+  }
+  return diff > 0 ? `in ${formatted}` : `${formatted} ago`;
+}
+
+// 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";
@@ -362,22 +663,35 @@ export {
   BRIDGE_MARKER,
   BRIDGE_METHODS,
   GUI_WIDGET_MARKER,
+  HISTORY_LIMIT,
   INFLIGHT_REPORT_ACK,
   MAX_TERMINAL_REGISTRY_ENTRIES,
+  MS_PER_DAY,
+  MS_PER_HOUR,
+  MS_PER_MINUTE,
+  MS_PER_SECOND,
   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,
+  TASK_ENTRY_TYPE,
+  UI_FORM_MARKER,
+  appendExecutionRecord,
   applyPendingDiff,
-  askUserInteract,
   callMarkerRpc,
   collectActivePendingIds,
+  dateToOnceCron,
   extractGui,
   firstContentText,
   formatChannelErrorText,
+  formatDuration,
+  formatRelativeTime,
+  formatSchedule,
   getAskUserAnswer,
   getAskUserOther,
   guiComponent,
@@ -391,10 +705,14 @@ export {
   isBridgeSyncPayload,
   isBridgeToolExecuteResponse,
   isChannelErrorResult,
+  isFormAnswers,
+  isFormQuestion,
   isGuiCapable,
   isGuiComponent,
   isGuiRenderResult,
   isInFlightReportAck,
+  isScheduleDraft,
+  isScheduleFormResult,
   isSessionManagerAbortParams,
   isSessionManagerCreateParams,
   isSessionManagerHistoryParams,
@@ -405,7 +723,11 @@ export {
   isSyncedTool,
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
+  onceCronToDate,
+  replayFoldEntries,
   scanPendingEntries,
   setWidgetDual,
+  snapshotToTask,
+  uiFormInteract,
   validateWidgetIconPaths
 };

package/package.json

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