@zhushanwen/extension-protocol 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -98,6 +98,12 @@ interface GuiComponentProps {
             commandId?: string;
             /** 只许标量：args 原样传给插件 handler，禁嵌套对象防无 schema 结构化旁路（设计 AP-3 校验） */
             args?: Record<string, string | number | boolean>;
+            /**
+             * 宿主容器导航（容器扩展点统一 §6.4 导航原语）：声明后点击请求宿主打开
+             * 对应容器（浮层/抽屉）的 tabId 标签页，不经命令链；与 commandId 互为两条
+             * 执行路径（commandId 优先走既有命令链，宿主执行器裁决）。
+             */
+            hostAction?: HostContainerAction;
         }[];
     };
     /**
@@ -180,8 +186,35 @@ interface TreeItem {
     status?: 'running' | 'done' | 'failed';
     depth?: number;
     children?: TreeItem[];
+    /**
+     * 行点击动作（容器扩展点统一 §6.4 导航原语；此前 TreeItem 完全不可点）。
+     * commandId 走既有命令链，hostAction 走宿主容器导航执行器——两条路径汇入
+     * 同一个执行器，缺省 = 纯展示行（维持旧行为）。
+     */
+    action?: {
+        /** 命令链命令 id（无参形态执行；带参命令用 hostAction.params 语义或后续按需扩展） */
+        commandId?: string;
+        /** 宿主容器导航（打开浮层/抽屉的某个标签页） */
+        hostAction?: HostContainerAction;
+    };
 }
 type TreeItemIcon = 'arrow' | 'check' | 'cross' | 'circle' | 'dot' | 'pause' | 'branch';
+/**
+ * 宿主容器导航声明（§6.4 导航原语的公共形状）：请求宿主打开某个容器的某个标签页。
+ * 插件不接触宿主内部状态，只表达「打开哪个容器的哪个 tab、带什么参数」。
+ */
+interface HostContainerAction {
+    /** 容器位置族：overlay = workflow-viz 浮层，drawer = 右抽屉 */
+    kind: 'overlay' | 'drawer';
+    /** 目标标签页 id（全局 id 空间解析，须带插件命名空间前缀）；目标不存在时点击无动作 + 一行 warning */
+    tabId: string;
+    /**
+     * 透传给目标容器选项字段的参数：键 = 目标容器选项的字段名（显式登记为对外契约），
+     * 值只许标量——禁嵌套对象防无 schema 结构化旁路（与 action-bar args 同一校验口径）；
+     * 未知键被忽略 + 一行 warning，不阻断动作。会话上下文由宿主注入（插件不传）。
+     */
+    params?: Record<string, string | number | boolean>;
+}
 /**
  * 计划产物文档元数据——agent 调 register-doc 登记的一份产物。
  * version 由 extension 侧维护：修订后重写文档须重调 register-doc（version+1），
@@ -312,7 +345,8 @@ interface GuiContext {
 declare function isGuiCapable(ctx: GuiContext): boolean;
 /**
  * 构造 GuiRenderResult。当前主用途是 guiSetWidget 的载荷（composer 任务托盘的协议 widget 区）；
- * details.__gui__（tool result 通道）为遗留兼容路径，todo/goal 已不再使用。
+ * details.__gui__（tool result 通道）为 workflow / subagent_batch 等工具的在产通道（经
+ * subagent-workflow 侧 tool/tool-shared.ts 的 withGuiAttach 单点构造，RPC 模式门控）。
  * stripUndefined 确保序列化不含 undefined（JSON.stringify 会丢弃 undefined 字段）。
  */
 declare function guiResult(component: GuiComponent, meta?: WidgetMeta): GuiRenderResult;
@@ -1751,6 +1785,57 @@ interface SubagentEngineConfigView {
     engineDefaults?: Record<string, string>;
 }
 
+/**
+ * subagent 投影判据（占用谓词 / 失败轮 / 失败分类展示词）——插件侧托盘 widget 与
+ * 宿主 renderer 的共享判据单点（dmg-r1-4 判据下沉：此前两侧手抄镜像、靠「两侧单测
+ * 各自锚定」的人工纪律同步，无对拍）。
+ *
+ * 契约两端（同判据同实现，结构性不漂移）：
+ *   - 插件侧：@zhushanwen/pi-subagent-workflow interface/gui/tray-widget.ts（托盘
+ *     widget 树的行状态映射 / 分桶 / meta 状态点）；
+ *   - 宿主侧：packages/renderer lib/subagent-bucket.ts（badge 计数 / streaming 判定
+ *     / SubagentTab 失败展示），经 re-export 同源消费。
+ *
+ * 入参类型 = 两侧 SubagentRecord 的共持形状子集（@taiji/shared 与
+ * @zhushanwen/subagent-core 各持一份 record 类型，本包零运行时依赖、不 import 任何
+ * 一侧词表）；status/stopReason 词表纪律（扩值评估、编译锁）仍归两侧 record 类型
+ * 所在包，本模块只锚判据逻辑本体。
+ */
+/**
+ * 失败分类的最小消费形状（两侧 FailureCause 的共持子集）：判据只读 class/kind 二
+ * 字段。宽入参是刻意的——sdk 判别联合（class×kind 矩阵）对两侧各自持有，本包不
+ * 复制词表防漂移。
+ */
+interface SubagentFailureLike {
+    class: string;
+    kind: string;
+}
+/** 三判据消费的最小字段面（两侧 SubagentRecord 形状子集；字段语义见判据注释）。 */
+interface SubagentProjectionRecord {
+    status: string;
+    stopReason?: string;
+    lastRound?: {
+        failure?: SubagentFailureLike;
+    };
+}
+/**
+ * 占用谓词（「正在跑」严格口径）：running 且无轮收条停因（「轮收条已写 = 本轮不在途」
+ * 的等价信号——轮始清点族在翻 running 时清 stopReason，markRoundIdle 轮终写入停因，
+ * 信号由 stopReason 字段承载）。带停因的 running（轮收条残留）不算占用。
+ */
+declare function isRunningProjection(record: SubagentProjectionRecord): boolean;
+/**
+ * 失败轮判据：lastRound.failure 存在且非 user.cancelled（FailureCause 存在即失败轮；
+ * user.cancelled 是用户主动中止非失败）。返回该 lastRound 供展示消费（泛型保留两侧
+ * 各自的 lastRound 载荷类型）；非失败轮返回 undefined。
+ */
+declare function failedRoundOf<T extends SubagentProjectionRecord>(record: T): T['lastRound'] | undefined;
+/**
+ * 失败分类展示词：`"<class>.<kind>"` 点拼（与 run 终局 failedMembers[].cause 的
+ * 序列化形态同形）。
+ */
+declare function failureCauseLabel(failure: SubagentFailureLike): string;
+
 /**
  * problem-solve-canvas 契约模块 —— marker 与 action 词表（U1 SSOT）。
  *
@@ -2602,4 +2687,4 @@ type ResolvedSettlementReason = SettlementReason | '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, 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 };
+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, type HostContainerAction, 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 SubagentFailureLike, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SubagentProjectionRecord, 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, failedRoundOf, failureCauseLabel, 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, isRunningProjection, 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

@@ -854,6 +854,20 @@ var SUBAGENT_DIRECTIVE_CUSTOM_TYPE = "subagent-directive";
 // src/extensions/subagent-engine/contract.ts
 var SUBAGENTS_ENGINES_FILENAME = "engines.json";
 
+// src/extensions/subagent-projection/predicates.ts
+function isRunningProjection(record) {
+  return record.status === "running" && record.stopReason === void 0;
+}
+function failedRoundOf(record) {
+  const failure = record.lastRound?.failure;
+  if (failure === void 0) return void 0;
+  if (failure.class === "user" && failure.kind === "cancelled") return void 0;
+  return record.lastRound;
+}
+function failureCauseLabel(failure) {
+  return `${failure.class}.${failure.kind}`;
+}
+
 // src/extensions/canvas/marker.ts
 var CANVAS_MARKER = "\0TAIJI_CANVAS";
 var CANVAS_ACTIONS = [
@@ -1358,6 +1372,8 @@ export {
   dateToOnceCron,
   derivePhase,
   extractGui,
+  failedRoundOf,
+  failureCauseLabel,
   firstContentText,
   firstLine,
   formatChannelErrorText,
@@ -1403,6 +1419,7 @@ export {
   isJournalReportAck,
   isPlanReviewRequest,
   isPlanReviewResponse,
+  isRunningProjection,
   isScheduleDraft,
   isScheduleFormResult,
   isSessionManagerAbortParams,

package/package.json

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