@zhushanwen/extension-protocol 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -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;
@@ -504,6 +524,176 @@ declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuest
  */
 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）。
  *
@@ -972,6 +1162,38 @@ declare function isInFlightReportAck(v: unknown): v is typeof INFLIGHT_REPORT_AC
  */
 declare const SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
 
+/**
+ * subagent-workflow 通知通道的 custom_message customType 词表（单源）。
+ *
+ * 契约两端（值逐字节依赖，改名 = 跨侧破坏性变更）：
+ *   - 写侧：@zhushanwen/pi-subagent-workflow extension（workflow 收口通知 / bg-notify
+ *     送达 / 定向消息留痕，经 pi.sendMessage 落 custom_message entry 进 session JSONL）
+ *     与 @zhushanwen/subagent-core（notifier 送达 + notify ledger 默认通道）；
+ *   - 读侧：taiji 三层——@taiji/shared（COMPLETE_NOTIFY_CUSTOM_TYPES display 覆写
+ *     集合 + parseSubagentDirective 判型）、runtime（event-interpreter W18 失效信号 /
+ *     subagent-extractor legacy 扫描）、core（notify-summary 边界聚合判据）。
+ *
+ * 历史上双侧各持裸字面量、零跨侧锚定（值相等靠手工同步，commit 21578c74f 在案）。
+ * 收敛本单源后两侧 import 同一常量；等值锁 = 壳 __tests__/contract.notify-custom-types.test.ts
+ * （值锚定 + 生产码不得本地重定义，防镜像回潮）。
+ *
+ * 注意与 worker 协议帧的 `type: "workflow-result"`（subagent-core worker-message-pump /
+ * worker-script-builder 的 postMessage 帧 type）是同名不同域——那是引擎进程内 RPC 形状，
+ * 不跨 pi session 边界，不进本词表。
+ */
+/** workflow run 收口通知的送达 customType。runtime event-interpreter 按它识别 run 完成
+ *  并驱动 W18 workflow-record 失效信号；shared 完成通知 display 覆写集合亦按它收录。
+ *  与 SUBAGENT_BG_NOTIFY_CUSTOM_TYPE 通道互斥（互用会让失效信号误判通道语义）。 */
+declare const WORKFLOW_RESULT_CUSTOM_TYPE: "workflow-result";
+/** subagent 后台完成通知的送达 customType（notifier 单条/合批 + notify ledger 默认通道；
+ *  壳 index.ts 的 registerMessageRenderer 同按它注册 TUI 渲染）。legacy 链路的
+ *  subagent-extractor 磁盘扫描、shared display 覆写集合均按它判型。 */
+declare const SUBAGENT_BG_NOTIFY_CUSTOM_TYPE: "subagent-bg-notify";
+/** subagent 定向消息留痕的 customType（composer 四符号 `@` 定向对话：GUI 经 client.prompt
+ *  触发 /subagents message，成功派发后落 custom_message entry——一 entry 双消费：主 agent
+ *  上下文 + renderer 定向气泡）。shared parseSubagentDirective / runtime display 覆写消费。 */
+declare const SUBAGENT_DIRECTIVE_CUSTOM_TYPE: "subagent-directive";
+
 /**
  * plugin-bridge 请求的 title marker。runtime event-adapter 和 pi 侧
  * bridge extension（@zhushanwen/pi-plugin-bridge）双端消费此 marker，
@@ -1170,4 +1392,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 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 };
+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 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, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, onceCronToDate, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -185,6 +185,176 @@ 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";
 
@@ -392,6 +562,11 @@ function isInFlightReportAck(v) {
   return v === INFLIGHT_REPORT_ACK;
 }
 
+// src/extensions/subagent-notify/custom-types.ts
+var WORKFLOW_RESULT_CUSTOM_TYPE = "workflow-result";
+var SUBAGENT_BG_NOTIFY_CUSTOM_TYPE = "subagent-bg-notify";
+var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
+
 // src/extensions/plugin-bridge/marker.ts
 var BRIDGE_MARKER = "\0TAIJI_BRIDGE";
 var BRIDGE_METHODS = ["bridge:sync", "bridge:tool_execute", "bridge:event", "bridge:intercept"];
@@ -493,8 +668,13 @@ 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,
@@ -503,8 +683,13 @@ export {
   SESSION_MANAGER_ACTIONS,
   SESSION_MANAGER_MARKER,
   SUBAGENTS_ENGINES_FILENAME,
+  SUBAGENT_BG_NOTIFY_CUSTOM_TYPE,
+  SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
   SUBAGENT_INFLIGHT_MARKER,
+  TASK_ENTRY_TYPE,
   UI_FORM_MARKER,
+  WORKFLOW_RESULT_CUSTOM_TYPE,
+  appendExecutionRecord,
   applyPendingDiff,
   callMarkerRpc,
   collectActivePendingIds,
@@ -512,6 +697,9 @@ export {
   extractGui,
   firstContentText,
   formatChannelErrorText,
+  formatDuration,
+  formatRelativeTime,
+  formatSchedule,
   getAskUserAnswer,
   getAskUserOther,
   guiComponent,
@@ -544,8 +732,10 @@ export {
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
   onceCronToDate,
+  replayFoldEntries,
   scanPendingEntries,
   setWidgetDual,
+  snapshotToTask,
   uiFormInteract,
   validateWidgetIconPaths
 };

package/package.json

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