@zhushanwen/extension-protocol 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -404,8 +404,9 @@ declare function firstContentText(result: {
  *   {action,params} / 快照帧，不引入内部 stringify 异常面）；
  * - mode 门控留调用方（inflight 在 attachSession 处 / session-manager 无门控——
  *   四态 reason 无 non-rpc 语义）；
- * - `ui.select` 缺席（非 GUI ctx）由调用方前置判定（沿 ask-user askUserInteract 的
- *   `isGuiCapable(ctx) && ctx.ui?.select` 先例）；误用即 throw 明确错误。
+ * - `ui.select` 缺席（非 GUI ctx）由调用方前置判定（沿已退役的 ask-user askUserInteract
+ *   先例——`isGuiCapable(ctx) && ctx.ui?.select`，git 历史可溯；isGuiCapable 现存于本包
+ *   core/helpers 并经包入口导出）；误用即 throw 明确错误。
  *
  * 设计权威源：docs/architecture/ext-simplify-17-shared-extraction.md §3.3 D8（v7 冻结形态）。
  */
@@ -429,15 +430,24 @@ interface MarkerRpcOptions {
 }
 /** 错误回包底层形状：select+marker 通道各协议（session-manager）
  * runtime 侧异常折叠的共用单源（不裸 reject，error 闭环走同一回包通道）。
- * SessionManagerErrorResult 是本形状的 alias（D8 单源化）。 */
+ * SessionManagerErrorResult 是本形状的 alias（D8 单源化）。
+ *
+ * `code`（session-manager-archive-delete U2，additive optional）：结构化错误码
+ * 透传通道（如 ArchiveError 的 `archive_generating`）——旧 runtime 不产出、旧
+ * extension 不消费，只加字段不破坏现有消费方。 */
 interface ChannelErrorResult {
     error: string;
     hint?: string;
+    code?: string;
 }
-/** 运行时形状检查：{error: string}（hint 可选，不校验其类型；排数组） */
+/** 运行时形状检查：{error: string}（hint 可选，不校验其类型；code additive 宽容
+ * ——缺席放行（旧 runtime 兼容象限）、present 须为 string；排数组） */
 declare function isChannelErrorResult(v: unknown): v is ChannelErrorResult;
-/** error + hint 文本拼接（hint 缺席只回 error）——plugin-bridge errorResult 与
- * session-manager 错误闭环文本的共用单源 */
+/** error + code + hint 文本拼接（code/hint 缺席各自省略对应行）——plugin-bridge
+ * errorResult 与 session-manager 错误闭环文本的共用单源。code present 时以
+ * `error_code: <code>` 行拼入（session-manager-archive-delete 决策 5：结构化错误码
+ * 对模型可见——工具 description 教 agent 认的码词在 throw 文本里在场，善后层恢复
+ * 指引的第一跳不断链）；code 缺席（旧 runtime 回包 / canvas 等无码消费方）行为不变 */
 declare function formatChannelErrorText(err: ChannelErrorResult): string;
 /**
  * 经 select 通道发起一次 marker RPC。
@@ -829,14 +839,20 @@ declare function dateToOnceCron(date: Date): string;
 declare function onceCronToDate(cron: string, now?: Date): Date | null;
 
 /**
- * plan 模式生命周期状态机（plan 模式状态机显式化 D1）——纯数据 + 纯函数，零依赖。
+ * plan 模式生命周期状态机（plan 模式状态机显式化 D1）——8 值状态集 + 9 事件
+ * 边表的单一状态契约。表与判定迁移 @zhushanwen/state-machine 基建承载（M4）：
+ * 矩阵改行式声明 + errorPolicy:'result'（表外 `{ ok: false }` 不炸 turn）+ 原型链
+ * 白名单口径统一到机器 coerceState（域内枚举 includes 白名单先例被基建吸收，
+ * V10）；对外 `transition` / `derivePhase` 签名与返回形态保形（消费方零改动，
+ * 消费方清单 = consumers.md）。
  *
  * plan 模式的状态散落在 pi 扩展 entry / runtime 挂起注册表 / renderer 派生公式三处时，
  * 任意两者漂移即产「僵尸/谎言」UI（F1-F5）。本模块是全链路共享的单一状态契约：
  * 8 值状态集 + 9 事件边表 + `transition` 纯函数（检查集中一处）+ `derivePhase` 呈现映射。
  *
  * 语义要点（设计 D1 逐条锚定）：
- * - 非法转移返回 `{ ok: false }`，由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
+ * - 非法转移返回 `{ ok: false }`（机器 errorPolicy:'result' 的表外分支转译——不携带
+ *   next 键、不 throw），由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
  *   （effects-as-data 无已登记消费方属投机间接层），各 action 在转移成功后内联执行自身副作用。
  * - `reviewing --dismiss--> planning`：用户「搁置」（协议级 dismiss 决策，D3）——落盘即
  *   planning，被搁置的审批不复活（F1/F2/F3 构造性消除）。
@@ -857,10 +873,10 @@ declare function onceCronToDate(cron: string, now?: Date): Date | null;
  * - `reviewing --submit--> reviewing`：审批重挂自环（E3 会话重启恢复 / D8「重新提交审批」
  *   按钮——重提交不推进生命周期，落盘回 reviewing 重挂即等价于旧调用方特判放行形态）。
  *
- * 呈现映射（derivePhase）：用户视角四主态 + idle 缺省——四主态是呈现，不是存储
- * （用户口述模型 = 呈现层，reviewing/dispatching 两个挂起态是崩溃恢复的真实分叉点，
- * 存储层保留 8 值）。终态两值（completed = 批准并派发执行 / exited = 主动退出）共享
- * 全部终态规则，呈现层同映 'terminal'（诊断/审计语义保留存储区分）。
+ * 发布位次登记（D7③）：本包（@zhushanwen/extension-protocol）自 M4 起依赖
+ * @zhushanwen/state-machine（workspace 协议），npm 发布顺序必须基建包在先——
+ * 位次断链时 npm 消费者会装到缺依赖的 extension-protocol（changeset 依赖图
+ * 自然保证，发布 PR 人工核对本条）。
  */
 type PlanLifecycleState = 'idle' | 'planning' | 'reviewing' | 'revising' | 'approved' | 'dispatching' | 'completed' | 'exited';
 /** 状态穷举表（运行时消费：E3 恢复查表 / 测试穷举基座）——顺序 = 生命周期自然序。 */
@@ -875,19 +891,20 @@ type PlanTransitionResult = {
     ok: false;
 };
 /**
- * 纯函数转移：`(state, event) → { ok: true, next } | { ok: false }`。
+ * 纯函数转移：`(state, event) → { ok: true, next } | { ok: false }`——机器
+ * errorPolicy:'result' 判定的保形包装（签名与返回形态不变，消费方零改动）。
  *
  * 非法转移（含运行时垃圾 state/event 值——跨版本帧、坏反序列化）返回 `{ ok: false }`
  * 且**不携带 next 键**，由调用方降级（不 throw 炸 turn）。调用方义务：`ok:false` 时
  * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归属划分点的兜底保险）。
  *
- * 入口白名单检查（与 derivePhase 同一机制）：普通对象字面量查表会沿原型链命中继承键——
- * `transition('reviewing', '__proto__')` 取出 Object.prototype、`('__proto__', 'valueOf')`
- * 取出函数，均被误判为合法 next（违背本契约）。故垃圾键必须先挡在查表前。
- * **选「枚举 includes 白名单」而非 null-prototype 表 / Object.hasOwn**：① transition 与
- * derivePhase 共用同一检查形态（单一机制，不并存两种写法）；② PLAN_LIFECYCLE_STATES /
- * PLAN_LIFECYCLE_EVENTS 就是值域 SSOT（测试穷举同源），includes 判定与之同源，
- * 原型键天然不在白名单内。
+ * 垃圾输入的分层判定（原型链白名单口径已统一到基建 coerceState 的同族机制）：
+ * 词表外 state 由机器词表集合拒绝（Set 查询不走原型链）；词表外 event 字符串由
+ * 机器 (from, on) 行索引拒绝（Map 复合键查询不走原型链）；非字符串 event 由基建
+ * 归一 undefined 落入表外拒绝（§5.2 失败路径表第 3 行，不 crash），下方前置守卫
+ * 是域内显式等价拒绝（同结果先行返回，「不炸 turn」契约双保险）。plan 表无
+ * to:null 消亡行（基建 null 语义 = 实体离开机器，plan 8 态全在机器内），state 为
+ * null 的分支运行时不可达，收窄仅为类型完备。
  */
 declare function transition(state: PlanLifecycleState, event: PlanLifecycleEvent): PlanTransitionResult;
 /**
@@ -904,9 +921,10 @@ type PlanPhase = 'idle' | 'planning' | 'reviewing' | 'approved' | 'terminal';
  * 8 存储态 → 5 呈现相位的单点映射（renderer 阶段指示/状态带共用，禁止消费方各自 if 拼）。
  * 运行时垃圾 state（混装格坏帧）降级 'idle'（无 plan 缺省，fail-safe 不误示进行中）。
  *
- * 入口白名单检查（理由同 transition，见彼处）：裸查表对继承键 'constructor' / 'toString'
- * 会取出 Object 构造函数等并经 `?? 'idle'` 流出（非 nullish 不落兜底）——垃圾 state
- * 必须精确落 'idle'，函数/对象不得作为相位流入 renderer。
+ * 入口白名单检查 = 机器 coerceState（原型链白名单口径统一到基建，V10）：裸查表对
+ * 继承键 'constructor' / 'toString' 会取出 Object 构造函数等并经 `?? 'idle'` 流出
+ * （非 nullish 不落兜底）——垃圾 state 必须精确落 'idle'，函数/对象不得作为相位
+ * 流入 renderer。
  */
 declare function derivePhase(state: PlanLifecycleState): PlanPhase;
 
@@ -986,8 +1004,8 @@ declare const PLAN_STATE_CUSTOM_TYPE = "plan-state";
 /**
  * 生命周期状态读取（D2 读方①②共用映射，原扩展 state.ts / runtime extractor 内联拷贝的
  * 单源归并）：
- * ① 新字段直读（值域检查：PLAN_LIFECYCLE_STATES 之外的垃圾值按缺失处理，落映射——
- *    不信任外部写入）；
+ * ① 新字段直读（值域检查 = 机器 coerceState 归化，词表外/原型链键垃圾值按缺失处理，
+ *    落映射——不信任外部写入；M4 白名单口径统一）；
  * ② 旧 entry 无 state（或垃圾 state）时映射 reviewState（awaiting→reviewing /
  *    revising→revising / 其余值→planning|idle 按 isActive）。
  */
@@ -1183,25 +1201,29 @@ declare function isFormAnswers(value: unknown): value is FormAnswers;
  */
 declare const SESSION_MANAGER_MARKER = "\0TAIJI_SESSION_MANAGER";
 /**
- * 7 个 action 的运行时集合（与 SessionManagerAction 类型同源——types.ts 从此派生）。
+ * 9 个 action 的运行时集合（与 SessionManagerAction 类型同源——types.ts 从此派生）。
  * event-adapter 用它把 JSON 解析出的 action 字符串收窄为联合类型，
  * 非法值折叠为 '__malformed__' 哨兵（与 handler default 分支同走 cancelled）。
  *
+ * 'delete' / 'archive'（session-manager-archive-delete U2）：终局操作双 action——
+ * delete 整树废纸篓不可恢复（USER-INITIATED ONLY，约束承载在 extension 工具文案层）、
+ * archive 归档退场可由用户恢复；扩展归属校验在 runtime handler 侧（协议层只定契约）。
+ *
  * 'watch'（notify-once D6）：通知债权的纯应答通道——单键 params={notifyId} 寻址、
  * 不传 timeout、fire-and-forget 长挂 select；必须在本集合内，否则 event-adapter
  * 把它折叠成 '__malformed__'（旧 runtime 兼容象限的静默降级形态），watch 永远到不了
  * handler 路由。
  */
-declare const SESSION_MANAGER_ACTIONS: readonly ["create", "send", "history", "status", "list", "abort", "watch"];
+declare const SESSION_MANAGER_ACTIONS: readonly ["create", "send", "history", "status", "list", "abort", "delete", "archive", "watch"];
 
 /**
  * session-manager extension 的类型定义。
  *
- * 7 个 action 的请求 params 和结果类型，供 handler 和 extension 共用。
+ * 9 个 action 的请求 params 和结果类型，供 handler 和 extension 共用。
  * marker 检测后按 action 分发到对应 handler 分支。
  */
 
-/** session-manager 支持的 7 个 action（从 SESSION_MANAGER_ACTIONS 集合派生，值与类型同源） */
+/** session-manager 支持的 9 个 action（从 SESSION_MANAGER_ACTIONS 集合派生，值与类型同源） */
 type SessionManagerAction = (typeof SESSION_MANAGER_ACTIONS)[number];
 /** 各 action 的请求参数映射 */
 interface SessionManagerParams {
@@ -1211,6 +1233,8 @@ interface SessionManagerParams {
     status: SessionManagerStatusParams;
     list: SessionManagerListParams;
     abort: SessionManagerAbortParams;
+    delete: SessionManagerDeleteParams;
+    archive: SessionManagerArchiveParams;
     watch: SessionManagerWatchParams;
 }
 /** create action 参数 */
@@ -1253,6 +1277,23 @@ type SessionManagerListParams = Record<string, never>;
 interface SessionManagerAbortParams {
     sessionId: string;
 }
+/**
+ * delete action 参数（session-manager-archive-delete U2）：彻底删除目标会话
+ * （进程 + 历史 + 衍生数据整树废纸篓，不可恢复）。人身约束（USER-INITIATED ONLY）
+ * 承载在 extension 工具文案层，协议层只定契约。归属校验用扩展归属校验
+ * （含磁盘回退）在 runtime handler 侧执行。
+ */
+interface SessionManagerDeleteParams {
+    sessionId: string;
+}
+/**
+ * archive action 参数（session-manager-archive-delete U2）：归档目标会话——
+ * 退场进归档区、文件压缩搬移、可由用户恢复。生成中会话拒绝（错误码
+ * archive_generating 经 ChannelErrorResult.code 透传）。
+ */
+interface SessionManagerArchiveParams {
+    sessionId: string;
+}
 /**
  * watch action 参数（notify-once D2/D6）：通知债权的纯应答通道，**单键寻址**——
  * runtime 按 `(调用方 parentSid, notifyId)` 反查 claim，parentSid 取自调用方连接身份、
@@ -1270,9 +1311,11 @@ declare function isSessionManagerCreateParams(v: unknown): v is SessionManagerCr
 declare function isSessionManagerSendParams(v: unknown): v is SessionManagerSendParams;
 /** history：sessionId 必填、tailTurns 可选 number */
 declare function isSessionManagerHistoryParams(v: unknown): v is SessionManagerHistoryParams;
-/** status / abort：sessionId 必填 */
+/** status / abort / delete / archive：sessionId 必填 */
 declare function isSessionManagerStatusParams(v: unknown): v is SessionManagerStatusParams;
 declare function isSessionManagerAbortParams(v: unknown): v is SessionManagerAbortParams;
+declare function isSessionManagerDeleteParams(v: unknown): v is SessionManagerDeleteParams;
+declare function isSessionManagerArchiveParams(v: unknown): v is SessionManagerArchiveParams;
 /** list：无参数（过滤由 handler 固化，params 不携带任何过滤字段） */
 declare function isSessionManagerListParams(v: unknown): v is SessionManagerListParams;
 /**
@@ -1345,6 +1388,24 @@ interface SessionManagerSessionSummary {
 interface SessionManagerAbortResult {
     success: boolean;
 }
+/**
+ * delete 结果（session-manager-archive-delete U2）：字段名以设计 §3.1 交互样例为权威
+ * ——成功回包 `{sessionId, deleted:true}`。侧栏消失 + 整树废纸篓由 runtime delete 链
+ * 内建，协议回包只做完成陈述。
+ */
+interface SessionManagerDeleteResult {
+    deleted: true;
+    sessionId: string;
+}
+/**
+ * archive 结果（session-manager-archive-delete U2）：字段名以设计 §3.1 交互样例为权威
+ * ——成功回包 `{sessionId, archived:true}`。归档成功后该会话全部通知债权由 runtime
+ * handler 三步收尾统一应答 'exited'（协议范围外，契约属 handler 编排）。
+ */
+interface SessionManagerArchiveResult {
+    archived: true;
+    sessionId: string;
+}
 /**
  * watch 应答 reason 词表（封闭 7 值）——与 pending-entries `mapReasonToStatus` 的
  * 4 个新 case 同词形（stopped→aborted、exited/deleted/orphaned→cancelled），
@@ -2438,4 +2499,4 @@ declare function mapReasonToStatus(reason: string): MappedPendingStatus;
  */
 declare const MAPPED_PENDING_STATUSES: ReadonlySet<string>;
 
-export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MAPPED_PENDING_STATUSES, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PendingFieldsScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, 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, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };
+export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MAPPED_PENDING_STATUSES, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PendingFieldsScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerArchiveParams, type SessionManagerArchiveResult, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerDeleteParams, type SessionManagerDeleteResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, 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, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerArchiveParams, isSessionManagerCreateParams, isSessionManagerDeleteParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -110,11 +110,14 @@ function stripUndefined(obj) {
 // src/core/select-rpc.ts
 var RESPONSE_PREVIEW_LENGTH = 200;
 function isChannelErrorResult(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.error === "string";
+  const rec = v;
+  return typeof v === "object" && v !== null && !Array.isArray(v) && typeof rec.error === "string" && (rec.code === void 0 || typeof rec.code === "string");
 }
 function formatChannelErrorText(err) {
-  return err.hint ? `${err.error}
-hint: ${err.hint}` : err.error;
+  const lines = [err.error];
+  if (err.code) lines.push(`error_code: ${err.code}`);
+  if (err.hint) lines.push(`hint: ${err.hint}`);
+  return lines.join("\n");
 }
 function emitRpcLog(opts, msg, detail) {
   opts?.log?.(msg, detail);
@@ -123,7 +126,7 @@ async function callMarkerRpc(ctx, marker, payload, opts) {
   const select = ctx.ui?.select;
   if (!select) {
     throw new Error(
-      `callMarkerRpc() requires ctx.ui.select (marker ${JSON.stringify(marker)}). Non-GUI ctx must be gated by the caller first \u2014 see askUserInteract precedent (isGuiCapable(ctx) && ctx.ui?.select, or a mode check).`
+      `callMarkerRpc() requires ctx.ui.select (marker ${JSON.stringify(marker)}). Non-GUI ctx must be gated by the caller first \u2014 gate with isGuiCapable(ctx) && ctx.ui?.select (exported from @zhushanwen/extension-protocol), or a mode check.`
     );
   }
   let value;
@@ -415,6 +418,7 @@ function onceCronToDate(cron, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/extensions/plan/state-machine.ts
+import { defineStateMachine } from "@zhushanwen/state-machine";
 var PLAN_LIFECYCLE_STATES = [
   "idle",
   "planning",
@@ -436,34 +440,57 @@ var PLAN_LIFECYCLE_EVENTS = [
   "later",
   "exit"
 ];
-var TRANSITION_TABLE = {
-  idle: { enter: "planning" },
-  planning: { submit: "reviewing", exit: "exited" },
-  reviewing: {
-    submit: "reviewing",
-    revise: "revising",
-    dismiss: "planning",
-    review_aborted: "planning",
-    approve: "dispatching",
-    exit: "exited"
+var PLAN_MACHINE = defineStateMachine({
+  name: "plan-lifecycle",
+  states: {
+    idle: {},
+    planning: {},
+    reviewing: {},
+    revising: {},
+    approved: {},
+    dispatching: {},
+    completed: { terminal: true },
+    exited: { terminal: true }
   },
-  revising: { submit: "reviewing", exit: "exited" },
-  approved: { approve: "dispatching", exit: "exited" },
-  dispatching: {
-    review_aborted: "approved",
-    exec_chosen: "completed",
-    later: "approved",
-    exit: "exited"
+  initial: "idle",
+  events: {
+    enter: {},
+    submit: {},
+    revise: {},
+    dismiss: {},
+    review_aborted: {},
+    approve: {},
+    exec_chosen: {},
+    later: {},
+    exit: {}
   },
-  completed: { enter: "planning" },
-  exited: { enter: "planning" }
-};
+  transitions: [
+    { from: "idle", on: "enter", to: "planning" },
+    { from: "planning", on: "submit", to: "reviewing" },
+    { from: "planning", on: "exit", to: "exited" },
+    { from: "reviewing", on: "submit", to: "reviewing" },
+    { from: "reviewing", on: "revise", to: "revising" },
+    { from: "reviewing", on: "dismiss", to: "planning" },
+    { from: "reviewing", on: "review_aborted", to: "planning" },
+    { from: "reviewing", on: "approve", to: "dispatching" },
+    { from: "reviewing", on: "exit", to: "exited" },
+    { from: "revising", on: "submit", to: "reviewing" },
+    { from: "revising", on: "exit", to: "exited" },
+    { from: "approved", on: "approve", to: "dispatching" },
+    { from: "approved", on: "exit", to: "exited" },
+    { from: "dispatching", on: "review_aborted", to: "approved" },
+    { from: "dispatching", on: "exec_chosen", to: "completed" },
+    { from: "dispatching", on: "later", to: "approved" },
+    { from: "dispatching", on: "exit", to: "exited" },
+    { from: ["completed", "exited"], on: "enter", to: "planning" }
+  ],
+  errorPolicy: "result"
+});
 function transition(state, event) {
-  if (!PLAN_LIFECYCLE_STATES.includes(state) || !PLAN_LIFECYCLE_EVENTS.includes(event)) {
-    return { ok: false };
-  }
-  const next = TRANSITION_TABLE[state][event];
-  return next === void 0 ? { ok: false } : { ok: true, next };
+  if (typeof event !== "string") return { ok: false };
+  const result = PLAN_MACHINE.transition(state, event);
+  if (!result.ok) return { ok: false };
+  return result.state === null ? { ok: false } : { ok: true, next: result.state };
 }
 var PHASE_OF_STATE = {
   idle: "idle",
@@ -476,8 +503,9 @@ var PHASE_OF_STATE = {
   exited: "terminal"
 };
 function derivePhase(state) {
-  if (!PLAN_LIFECYCLE_STATES.includes(state)) return "idle";
-  return PHASE_OF_STATE[state];
+  const coerced = PLAN_MACHINE.coerceState(state);
+  if (coerced === null) return "idle";
+  return PHASE_OF_STATE[coerced];
 }
 
 // src/extensions/plan/review-contract.ts
@@ -552,10 +580,8 @@ function isPlanReviewResponse(value) {
 // src/extensions/plan/legacy-entries.ts
 var PLAN_STATE_CUSTOM_TYPE = "plan-state";
 function readLifecycleState(data, isActive) {
-  const raw = data.state;
-  if (typeof raw === "string" && PLAN_LIFECYCLE_STATES.includes(raw)) {
-    return raw;
-  }
+  const coerced = PLAN_MACHINE.coerceState(data.state);
+  if (coerced !== null) return coerced;
   if (data.reviewState === "awaiting") return "reviewing";
   if (data.reviewState === "revising") return "revising";
   return isActive ? "planning" : "idle";
@@ -700,6 +726,12 @@ function isSessionManagerStatusParams(v) {
 function isSessionManagerAbortParams(v) {
   return isSessionIdParams(v);
 }
+function isSessionManagerDeleteParams(v) {
+  return isSessionIdParams(v);
+}
+function isSessionManagerArchiveParams(v) {
+  return isSessionIdParams(v);
+}
 function isSessionManagerListParams(v) {
   return isRecord(v);
 }
@@ -732,7 +764,17 @@ function isSessionManagerWatchRespondPayload(v) {
 
 // src/extensions/session-manager/marker.ts
 var SESSION_MANAGER_MARKER = "\0TAIJI_SESSION_MANAGER";
-var SESSION_MANAGER_ACTIONS = ["create", "send", "history", "status", "list", "abort", "watch"];
+var SESSION_MANAGER_ACTIONS = [
+  "create",
+  "send",
+  "history",
+  "status",
+  "list",
+  "abort",
+  "delete",
+  "archive",
+  "watch"
+];
 
 // src/extensions/subagent-inflight/marker.ts
 var SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
@@ -1284,7 +1326,9 @@ export {
   isScheduleDraft,
   isScheduleFormResult,
   isSessionManagerAbortParams,
+  isSessionManagerArchiveParams,
   isSessionManagerCreateParams,
+  isSessionManagerDeleteParams,
   isSessionManagerHistoryParams,
   isSessionManagerListParams,
   isSessionManagerNotifyId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.22.0",
+  "version": "0.23.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",
@@ -21,6 +21,9 @@
     "README.md"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@zhushanwen/state-machine": "0.2.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "tsup": "^8.5.1",