@zhushanwen/extension-protocol 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -100,6 +100,23 @@ interface GuiComponentProps {
             args?: Record<string, string | number | boolean>;
         }[];
     };
+    /**
+     * 文本输入——GuiComponent 协议输入原语（provider-plugin-access D8：粘贴 PAT、
+     * 填回调地址）。值变更即经 plugin.uiEvent 回传（{ viewId, componentId: id,
+     * event, value }，插件侧始终持有最新值）；确认动作复用 action-bar 按钮点击——
+     * 「输入 + 确认」两者组合完成，无表单聚合原语（single-select / form 砍除）。
+     * 宿主只做形状校验（value 标量、深度 ≤ 2），业务校验归插件。渲染端缺
+     * uiEvent 出口时输入框禁用 + warn（TabBar 降级出声范式）。
+     */
+    'text-input': {
+        /** 组件 id（uiEvent 回传的 componentId，插件定位输入项的键） */
+        id: string;
+        label?: string;
+        placeholder?: string;
+        /** 当前值（插件推树携带，宿主受控渲染——单值权威在插件侧） */
+        value?: string;
+        multiline?: boolean;
+    };
     /** 自定义组件——逃生口（仅限内置 extension 编译期注册） */
     'custom': {
         component: string;
@@ -242,6 +259,18 @@ declare const GUI_WIDGET_MARKER = "\0TAIJI_GUI_WIDGET:";
  * 与 GUI_WIDGET_MARKER / ASK_USER_MARKER 同族（select 通道 marker）。
  */
 declare const PLAN_REVIEW_MARKER = "\0TAIJI_PLAN_REVIEW:";
+/**
+ * permission 审批 select 的 title 首行判定键。pi-permission 扩展的 RPC 审批 select
+ * （extensions/universal/permission approval.ts buildApprovalFieldSet 单点构造，
+ * title 可多行、首行恒为此串）与 runtime event-adapter 判定（isPermissionApprovalSelect
+ * 按首行精确匹配，命中后广播帧附加 permission: true 键）双端共用本常量——
+ * 与 PLAN_REVIEW_MARKER 的 planReview: true 键同构分流（select 通道标记）。
+ *
+ * 与上方 NUL marker 家族的形态区别：这是用户可见文案（审批对话框标题），
+ * 无控制符前缀；单源价值同族——双端各自手抄字面量时，生产端改文案 → 消费端
+ * 静默不命中 → 侧栏 permission 等待可见性失效，零报错信号。
+ */
+declare const PERMISSION_APPROVAL_TITLE = "[pi-permission] Approval required";
 
 /**
  * helpers 需要的 ctx 最小接口。
@@ -388,6 +417,22 @@ declare function firstContentText(result: {
         text?: string;
     }>;
 }): string;
+/**
+ * 从 pi toolResult（unknown 入参）安全读取 details.summary（一行摘要读侧单点）。
+ * result / details 非对象形态、summary 非字符串或空串一律 undefined——调用方以
+ * `?? 回退文本` 表达降级。读侧检查单点化：extension 的 renderResult 不再各自
+ * 手抄取值函数（历史 8 处手抄 + 2 处 as 断言已收编）。
+ */
+declare function readDetailsSummary(result: unknown): string | undefined;
+/**
+ * pi toolResult 通用形状提取的 unknown 检查式版（firstContentText 的宽入参形态）：
+ * content 数组缺失或 content[0] 非 text 块时兜底空串。renderResult 入参是 unknown
+ * （容错历史持久化 entry），无法直接满足 firstContentText 的强类型入参——本函数
+ * 内化取值检查，调用方不再各自包装 contentText。
+ */
+declare function resultContentText(result: unknown): string;
+/** 文本首行（按首个换行切分；无换行返回原文）。折叠态一行摘要形态的共用切分。 */
+declare function firstLine(text: string): string;
 
 /**
  * select+marker 通道 RPC 原语（D8）。
@@ -1491,7 +1536,8 @@ type SessionManagerErrorResult = ChannelErrorResult & {
 interface SubagentInFlightReport {
     /**
      * 绝对计数：该 pi 进程当前「非 idle 句柄数」（hasLiveProcessHandle && !hasIdleTimer
-     * 双谓词过滤，与 notify-host.ts hasRunningBackground 同源）。非增量——消费方整帧
+     * 双谓词过滤；原「与 notify-host.ts hasRunningBackground 同源」的表述随该谓词
+     * 退役删除——subagent-observability §3.3.7③）。非增量——消费方整帧
      * 覆盖镜像，不做加减。
      */
     inFlight: number;
@@ -1900,6 +1946,13 @@ interface ReviewReport {
     round: number;
     maxRounds: number;
     entries: ReviewEntry[];
+    /**
+     * 最近一次报告写回（review-append）的轮次。零发现轮的完成事实：空 entries 也是
+     * 审查结论，条目存在性判不了「本轮 run 已完成」——轮次推进与 maxRounds 预算的
+     * 完成判定以本字段为准（有条目轮两条判据皆成立）。optional = 尚无任何写回 /
+     * 旧快照兼容（缺省按无写回处理，不阻碍既有数据重放）。
+     */
+    lastRunRound?: number;
     /** 非 converged 终态的停回说明（聚合 2 不变量 2：max-rounds / escalated / stuck 必附）。 */
     stopNote?: string;
     /** 恢复动作建议（停回说明的配套：升级裁决后可再发起）。 */
@@ -2425,6 +2478,14 @@ interface PendingEntriesScan {
      * 末次合法值（后条非法不抹除前条合法值）。
      */
     unregisterStatuses: Map<string, MappedPendingStatus>;
+    /**
+     * 注销条目结清视图（subagent-observability §3.3.6 债权结清新权威通道）：id →
+     * 结清枚举（封闭五值 + 词表外解析缺省 unknown）。读注销 entry 的 reason 事实经
+     * resolveSettlementReason 解析（不经 mapReasonToStatus 旧映射）；string reason
+     * 一律解析（fail-visible 值照常入视图），非 string reason 视为畸形不入视图；
+     * 同 id 多条注销取末次带 string reason 的值（后条畸形不抹除前值）。
+     */
+    unregisterSettlements: Map<string, ResolvedSettlementReason>;
 }
 /**
  * 单趟扫描 entries 按 customType 分流（容错对齐 pending 侧 S-10：null/非对象
@@ -2436,16 +2497,18 @@ interface PendingEntriesScan {
  * 收敛——消费方禁止本地复制映射段）。
  */
 declare function scanPendingEntries(entries: readonly unknown[]): PendingEntriesScan;
-/** scanPendingFields 的结果：collect 链路消费的字段映射投影（首见 type + 注销 status）。 */
+/** scanPendingFields 的结果：collect 链路消费的字段映射投影（首见 type + 注销 status 视图 + 注销结清视图）。 */
 interface PendingFieldsScan {
     registerTypes: Map<string, string>;
     unregisterStatuses: Map<string, MappedPendingStatus>;
+    /** 注销结清视图（§3.3.6 权威通道，见 {@link PendingEntriesScan.unregisterSettlements}）。 */
+    unregisterSettlements: Map<string, ResolvedSettlementReason>;
 }
 /**
  * collect 终局回填的字段视图（MF-2-1 单点入口）：scanPendingEntries 产物中
- * register 首见 type + 全部注销 status 的 MAPPED 成员投影。消费方（delivery-port
- * 快照基线 / pending-notifications consume 后回填）按 id 查表补 type/outcome，
- * 查无保持 undefined（诚实缺省，不虚构终态）。
+ * register 首见 type + 全部注销 status 的 MAPPED 成员投影 + 注销 reason 事实的
+ * 结清解析投影。消费方（delivery-port 快照基线 / pending-notifications consume 后
+ * 回填）按 id 查表补 type/outcome，查无保持 undefined（诚实缺省，不虚构终态）。
  */
 declare function scanPendingFields(entries: readonly unknown[]): PendingFieldsScan;
 /**
@@ -2475,19 +2538,27 @@ declare function collectActivePendingIds(entries: unknown[], opts?: CollectPendi
  *
  * [notify-once D3 族映射] session-manager watch 应答的 4 个新 reason 同族接入：
  * stopped→aborted（用户 UI 掐断含债权轮）、exited/deleted/orphaned→cancelled
- * （终局死亡/删除/orphan 吸收态）。**不扩 MappedPendingStatus/PendingStatus 词表**——
- * 四个新 reason 全仓零读方按 status 分流（countActiveFromEntries 只用 register−unregister
- * 差集、notify-summary outcome 读 details 不读 entry.status），精确状态由通知正文与
- * get_session_status 承载，高于 G2 感知线。
+ * （终局死亡/删除/orphan 吸收态）。
+ *
+ * [subagent-observability §3.3.6/§3.3.11④] 本通道保留为**历史 reason 解析兼容通道**
+ * （解析词表纪律：旧值保留解析）；债权结清的新权威通道 = resolveSettlementReason
+ * （下方 SettlementReason 封闭五值），双通道以新写入方为权威。缺省方向废除
+ * fail-open：词表外 reason → unknown（不再产假成功）。
  *
  * 返回值 MappedPendingStatus（本文件封闭字面量联合）：PendingStatus 枚举留在
- * pending-notifications（本包不引 extension 侧类型），本联合是其终态子集——消费方
- * 免 as 收窄直接赋值。
+ * pending-notifications（本包不引 extension 侧类型），本联合是其终态子集+解析缺省
+ * unknown——消费方免 as 收窄直接赋值。
  */
-/** mapReasonToStatus 的封闭返回值域：pending-notifications PendingStatus 的终态子集
- * （不含初始态 active）。protocol 不引 extension 侧类型（分层裁决不变），以自有
- * 字面量联合锁定值域，switch 分支编译期受限。 */
-type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted';
+/**
+ * mapReasonToStatus 的封闭返回值域：pending-notifications PendingStatus 的终态子集
+ * （不含初始态 active）+ 解析缺省 unknown。protocol 不引 extension 侧类型（分层裁决
+ * 不变），以自有字面量联合锁定值域，switch 分支编译期受限。
+ *
+ * [subagent-observability §3.3.6/§3.3.11④ fail-open 废除] 第七成员 unknown = 词表外
+ * reason 的解析缺省（fail-visible——解析词表纪律的缺省方向与旧 fail-open=completed
+ * 相反：不可判读时如实标注，不产假成功）。
+ */
+type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted' | 'unknown';
 declare function mapReasonToStatus(reason: string): MappedPendingStatus;
 /**
  * MappedPendingStatus 的值集（MF-1-5 词表单源）：由 REASON_STATUS_MAP 派生——映射表
@@ -2496,7 +2567,39 @@ declare function mapReasonToStatus(reason: string): MappedPendingStatus;
  * import 本常量，禁止本地复制六值 Set（曾两包各持一份本地拷贝注释自认「同步维护」）。
  * Set 成员与 MappedPendingStatus 联合的相等性由 pending-entries.test.ts 断言锁定。
  * string 元素类型是消费面要求（对任意落盘 status 做成员判定，窄化前的原始值）。
+ *
+ * [subagent-observability §3.3.11④] 值集含解析缺省 unknown（fail-visible）——词表外
+ * 落盘 status 由成员判定放行进入字段视图（不再静默丢弃），消费方按「不可判读」呈现。
  */
 declare const MAPPED_PENDING_STATUSES: ReadonlySet<string>;
+/**
+ * 债权结清词表（封闭五值；值域语义与 subagent-core run-vocabulary ALL_SETTLEMENT_REASONS
+ * 同源——「债权」= pending-notifications 的 collect 挂起债，结清 = 该债以何种事实形态
+ * 兑现或消灭）：
+ *   completed — 轮正常收尾兑现；
+ *   failed    — 轮失败结清（含预算/超时轮失败）；
+ *   cancelled — 轮中止、run 取消、编排性收尾打断（interrupted 族宿主侧打断）；
+ *   lost      — 失联清点（宿主重启代际 + pid 探活事实，§3.3.4 合并清点产物）；
+ *   no_result — 无果：退出无 settle 无结果、清理扫描无事实可依、或轮被扩展接管
+ *               （细因经轮收条 promptDisposition 披露；与 lost 的边界 = 有无
+ *               「宿主重启」事实）。
+ *
+ * 依赖方向：core → 本包（权威写侧产值在 core run-vocabulary；本包按协议单点纪律
+ * 自持同值字面量，双包字面量一致性由各自枚举完整性测试 + core 侧对账测试锁定）。
+ */
+declare const SETTLEMENT_REASONS: readonly ["completed", "failed", "cancelled", "lost", "no_result"];
+/** 债权结清词表（封闭五值；值域语义见 {@link SETTLEMENT_REASONS}）。 */
+type SettlementReason = (typeof SETTLEMENT_REASONS)[number];
+/**
+ * 结清解析产出类型：词表外 reason 解析缺省 `unknown`（fail-visible——不可判读时
+ * 如实标注，不产假成功；缺省方向与旧 fail-open=completed 相反）。
+ */
+type ResolvedSettlementReason = SettlementReason | 'unknown';
+/**
+ * pending 注销 reason → 债权结清枚举解析（新权威通道；双通道以新写入方为权威——
+ * 新写入方直接产 SettlementReason 字面量，本函数服务历史 reason 与防御性解析）。
+ * mapReasonToStatus（六值+unknown 历史通道）保留并行，两表键集一致性由测试锁定。
+ */
+declare function resolveSettlementReason(reason: string): ResolvedSettlementReason;
 
-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 };
+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, PERMISSION_APPROVAL_TITLE, 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 ResolvedSettlementReason, 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, SETTLEMENT_REASONS, 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 SettlementReason, 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, firstLine, 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, readDetailsSummary, readLifecycleState, readResumeHint, replayFoldEntries, resolveSettlementReason, resultContentText, scanPendingEntries, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -15,6 +15,7 @@ var PROTOCOL_VERSION = 1;
 // src/core/markers.ts
 var GUI_WIDGET_MARKER = "\0TAIJI_GUI_WIDGET:";
 var PLAN_REVIEW_MARKER = "\0TAIJI_PLAN_REVIEW:";
+var PERMISSION_APPROVAL_TITLE = "[pi-permission] Approval required";
 
 // src/core/helpers.ts
 function isGuiCapable(ctx) {
@@ -94,6 +95,23 @@ function firstContentText(result) {
   const first = result.content[0];
   return first?.type === "text" ? first.text ?? "" : "";
 }
+function readDetailsSummary(result) {
+  if (result === null || typeof result !== "object") return void 0;
+  const details = result.details;
+  if (details === null || typeof details !== "object") return void 0;
+  const summary = details.summary;
+  return typeof summary === "string" && summary !== "" ? summary : void 0;
+}
+function resultContentText(result) {
+  if (result === null || typeof result !== "object") return "";
+  const content = result.content;
+  if (!Array.isArray(content)) return "";
+  return firstContentText({ content });
+}
+function firstLine(text) {
+  const idx = text.indexOf("\n");
+  return idx === -1 ? text : text.slice(0, idx);
+}
 function stripUndefined(obj) {
   if (obj === null || obj === void 0) return obj;
   if (typeof obj !== "object") return obj;
@@ -1150,7 +1168,8 @@ function scanPendingEntries(entries) {
     registerEntries: [],
     unregisteredIds: /* @__PURE__ */ new Set(),
     registerTypes: /* @__PURE__ */ new Map(),
-    unregisterStatuses: /* @__PURE__ */ new Map()
+    unregisterStatuses: /* @__PURE__ */ new Map(),
+    unregisterSettlements: /* @__PURE__ */ new Map()
   };
   const seenRegisterIds = /* @__PURE__ */ new Set();
   for (const raw of entries) {
@@ -1158,26 +1177,36 @@ function scanPendingEntries(entries) {
     const entry = raw;
     const data = entry.data ?? {};
     if (entry.customType === PENDING_REGISTER_ENTRY_TYPE) {
-      scan.registerEntries.push({ data });
-      if (typeof data.id === "string" && data.id !== "" && !seenRegisterIds.has(data.id)) {
-        seenRegisterIds.add(data.id);
-        if (typeof data.type === "string") scan.registerTypes.set(data.id, data.type);
-      }
+      absorbRegisterEntry(scan, data, seenRegisterIds);
     } else if (entry.customType === PENDING_UNREGISTER_ENTRY_TYPE) {
-      if (typeof data.id === "string") {
-        scan.unregisteredIds.add(data.id);
-        const status = data.status;
-        if (data.id !== "" && typeof status === "string" && MAPPED_PENDING_STATUSES.has(status)) {
-          scan.unregisterStatuses.set(data.id, status);
-        }
-      }
+      absorbUnregisterEntry(scan, data);
     }
   }
   return scan;
 }
+function absorbRegisterEntry(scan, data, seenRegisterIds) {
+  scan.registerEntries.push({ data });
+  if (typeof data.id === "string" && data.id !== "" && !seenRegisterIds.has(data.id)) {
+    seenRegisterIds.add(data.id);
+    if (typeof data.type === "string") scan.registerTypes.set(data.id, data.type);
+  }
+}
+function absorbUnregisterEntry(scan, data) {
+  if (typeof data.id !== "string") return;
+  scan.unregisteredIds.add(data.id);
+  if (data.id === "") return;
+  const status = data.status;
+  if (typeof status === "string" && MAPPED_PENDING_STATUSES.has(status)) {
+    scan.unregisterStatuses.set(data.id, status);
+  }
+  const reason = data.reason;
+  if (typeof reason === "string") {
+    scan.unregisterSettlements.set(data.id, resolveSettlementReason(reason));
+  }
+}
 function scanPendingFields(entries) {
-  const { registerTypes, unregisterStatuses } = scanPendingEntries(entries);
-  return { registerTypes, unregisterStatuses };
+  const { registerTypes, unregisterStatuses, unregisterSettlements } = scanPendingEntries(entries);
+  return { registerTypes, unregisterStatuses, unregisterSettlements };
 }
 function applyPendingDiff(scan) {
   const active = [];
@@ -1216,12 +1245,60 @@ var REASON_STATUS_MAP = {
   stopped: "aborted",
   exited: "cancelled",
   deleted: "cancelled",
-  orphaned: "cancelled"
+  orphaned: "cancelled",
+  // ── [subagent-observability §3.3.6] 三组词表外字面量显式映射（原直落 default）──
+  running: "completed",
+  closed: "cancelled",
+  "parent-shutdown": "aborted",
+  "parent-fork": "aborted",
+  "parent-new": "aborted",
+  "user-close": "cancelled",
+  disconnected: "aborted",
+  gc: "unknown"
 };
 function mapReasonToStatus(reason) {
-  return REASON_STATUS_MAP[reason] ?? "completed";
+  return REASON_STATUS_MAP[reason] ?? "unknown";
 }
+var MAPPED_REASON_KEYS = new Set(Object.keys(REASON_STATUS_MAP));
 var MAPPED_PENDING_STATUSES = new Set(Object.values(REASON_STATUS_MAP));
+var SETTLEMENT_REASONS = [
+  "completed",
+  "failed",
+  "cancelled",
+  "lost",
+  "no_result"
+];
+var SETTLEMENT_REASON_MAP = {
+  completed: "completed",
+  failed: "failed",
+  cancelled: "cancelled",
+  lost: "lost",
+  no_result: "no_result",
+  expired: "no_result",
+  time_limited: "failed",
+  budget_limited: "failed",
+  aborted: "cancelled",
+  interrupted: "cancelled",
+  "interrupted-by-restart": "cancelled",
+  "interrupted-by-parent": "cancelled",
+  stopped: "cancelled",
+  exited: "cancelled",
+  deleted: "cancelled",
+  orphaned: "cancelled",
+  reopened: "completed",
+  running: "no_result",
+  closed: "cancelled",
+  "parent-shutdown": "cancelled",
+  "parent-fork": "cancelled",
+  "parent-new": "cancelled",
+  "user-close": "cancelled",
+  disconnected: "no_result",
+  gc: "no_result"
+};
+function resolveSettlementReason(reason) {
+  return SETTLEMENT_REASON_MAP[reason] ?? "unknown";
+}
+var SETTLEMENT_REASON_KEYS = new Set(Object.keys(SETTLEMENT_REASON_MAP));
 export {
   ACTION_EVENT_MAP,
   ASK_USER_MARKER,
@@ -1250,6 +1327,7 @@ export {
   NON_TOOL_ACTIONS,
   PENDING_REGISTER_ENTRY_TYPE,
   PENDING_UNREGISTER_ENTRY_TYPE,
+  PERMISSION_APPROVAL_TITLE,
   PLAN_LIFECYCLE_EVENTS,
   PLAN_LIFECYCLE_STATES,
   PLAN_REVIEW_MARKER,
@@ -1260,6 +1338,7 @@ export {
   SCHEDULE_CREATE_MARKER,
   SESSION_MANAGER_ACTIONS,
   SESSION_MANAGER_MARKER,
+  SETTLEMENT_REASONS,
   SUBAGENTS_ENGINES_FILENAME,
   SUBAGENT_BG_NOTIFY_CUSTOM_TYPE,
   SUBAGENT_DIRECTIVE_CUSTOM_TYPE,
@@ -1280,6 +1359,7 @@ export {
   derivePhase,
   extractGui,
   firstContentText,
+  firstLine,
   formatChannelErrorText,
   formatDuration,
   formatRelativeTime,
@@ -1342,9 +1422,12 @@ export {
   mapReasonToStatus,
   onceCronToDate,
   parsePlanReviewResponse,
+  readDetailsSummary,
   readLifecycleState,
   readResumeHint,
   replayFoldEntries,
+  resolveSettlementReason,
+  resultContentText,
   scanPendingEntries,
   scanPendingFields,
   setWidgetDual,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.23.0",
+  "version": "0.25.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",
@@ -33,6 +33,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }