@xyz-agent/extension-protocol 0.3.1 → 0.5.0

package/dist/index.d.mts

@@ -49,6 +49,14 @@ interface GuiComponentProps {
     /** 列表树——替代 TUI 的 ⎿ ├─ └─ 缩进 */
     'list-tree': {
         items: TreeItem[];
+        /** 行首显示弱化序号（1/2/3…，mono tabular-nums）。扁平有序清单用（todo）；
+         *  自带编号的文本（goal criteria "1. xxx"）不要开，避免双重编号 */
+        numbered?: boolean;
+    };
+    /** 垂直组合容器——无视觉样式的透明分组。宿主壳层（WidgetArea）承担卡壳/head/折叠
+     *  后，widget 内容需要多组件组合时的组合根（替代「无头 card」的语义滥用） */
+    'group': {
+        children: GuiComponent[];
     };
     /** 双列网格——替代 TUI 的 │ 列分隔 */
     'columns': {
@@ -73,6 +81,31 @@ interface GuiRenderResult {
     /** 版本协商，前端检测，不认识降级 ansi-text */
     v: typeof PROTOCOL_VERSION;
     component: GuiComponent;
+    /**
+     * widget 宿主元数据（M17 对话流 widget 面板消费）：标题/状态点/进度计数由
+     * 宿主壳层统一渲染成单一 head（含折叠交互），extension 不再用 card 原语
+     * 的 header 表达这些（壳层 head 与 payload card header 双头重复的根因修复）。
+     * 可选：不发时宿主 fallback 到 viewId 标题、无状态点/进度。
+     */
+    meta?: WidgetMeta;
+}
+/** widget 宿主元数据——head 渲染契约（title + 状态点 + 进度 + 折叠 chevron）。 */
+interface WidgetMeta {
+    /** head 标题（todo → "Todo"；goal → slug） */
+    title: string;
+    /** head 状态点语义：running=accent / done=success / failed=danger / idle=neutral 弱点 */
+    status?: 'running' | 'done' | 'failed' | 'idle';
+    /** head 进度（mini bar + 计数文本）；progress-bar 原语从 body 移入 head 的承载 */
+    progress?: {
+        /** fill 比例 = current/total */
+        current: number;
+        total: number;
+        /** 计数显示文本（head 空间有限，extension 全权格式化：todo "2/5"、goal "42%"）。
+         *  缺省 `${current}/${total}` */
+        label?: string;
+        /** fill 语义色（预算阈值映射）；缺省按 meta.status（done→success，否则 accent） */
+        severity?: 'ok' | 'warn' | 'danger';
+    };
 }
 interface StatItem {
     label?: string;
@@ -135,23 +168,26 @@ interface GuiContext {
  */
 declare function isGuiCapable(ctx: GuiContext): boolean;
 /**
- * 构造 GuiRenderResult，放进 details.__gui__。
+ * 构造 GuiRenderResult。当前主用途是 guiSetWidget 的载荷（M17 对话流 widget 面板）；
+ * details.__gui__（tool result 通道）为遗留兼容路径，todo/goal 已不再使用。
  * stripUndefined 确保序列化不含 undefined（JSON.stringify 会丢弃 undefined 字段）。
  */
-declare function guiResult(component: GuiComponent): GuiRenderResult;
+declare function guiResult(component: GuiComponent, meta?: WidgetMeta): GuiRenderResult;
 /**
  * 构造 GuiComponent，带类型推断。
  * 类型参数 T 约束 props 到对应类型的 props 形状。
  */
 declare function guiComponent<T extends GuiComponentType>(type: T, props: GuiComponentProps[T]): GuiComponent<T>;
 /**
- * 设置 GUI widget。RPC 模式下用 marker 编码 GuiComponent JSON 进 string[]，
- * runtime event-adapter 检测 marker 解码为结构化 WS 帧。
- * TUI 模式下此函数无操作（extension 应在 TUI 分支调原生 ctx.ui.setWidget 传 Component factory）。
+ * 设置 GUI widget。RPC 模式下用 marker 编码 GuiRenderResult JSON 进 string[]，
+ * runtime event-adapter 检测 marker 解码为结构化 WS 帧（component + meta）。
+ * 本函数无 isGui 守卫（仅查 ctx.ui?.setWidget 存在性），调用方需先判定
+ * isGuiCapable(ctx)——TUI 模式误调会把 marker 编码行推给原生 widget 造成乱码。
  *
- * 传 undefined 清除 widget。
+ * meta（标题/状态/进度）由宿主壳层渲染成统一 head；extension 不再用 card 原语
+ * header 表达这些。传 undefined 清除 widget。
  */
-declare function guiSetWidget(ctx: GuiContext, key: string, component: GuiComponent | undefined): void;
+declare function guiSetWidget(ctx: GuiContext, key: string, result: GuiRenderResult | undefined): void;
 /**
  * 从 details 中提取 GuiRenderResult。前端统一用此函数读取 __gui__，
  * 集中校验版本号，避免散落的 as 断言。
@@ -163,6 +199,13 @@ declare function extractGui(details: Record<string, unknown> | undefined): GuiRe
  * 不校验 type 是否为已知值（GuiComponentRenderer 对未知 type 有 AnsiText 降级）。
  */
 declare function isGuiComponent(value: unknown): value is GuiComponent;
+/**
+ * v1.1 wire 格式校验：判断 unknown 值是否为合法 GuiRenderResult 信封
+ * （v === PROTOCOL_VERSION + component 是合法 GuiComponent）。meta 可选不校验深度。
+ * event-adapter 据此区分 v1.1 信封（解包 component + meta）与 v1 裸 component
+ * （旧版 extension 发出的 wire 格式，兼容窗口内两种并存）。
+ */
+declare function isGuiRenderResult(value: unknown): value is GuiRenderResult;
 
 /**
  * ask-user extension 的富交互类型定义。
@@ -195,14 +238,10 @@ interface AskUserQuestion {
      *  - 有 options 时：默认 true，前端在选项末尾追加 Other 输入框；设 false 则不追加
      *  - 无 options 时：整个问题就是自由输入，此字段被忽略 */
     allowOther?: boolean;
-    /** 是否允许附加评论。选中后可追加短文本（4.0.1 restore：0.3.0 误删导致 pi-ask-user@4.0.0 ESM import 崩溃，见 .changeset/restore-ask-user-comment.md） */
-    allowComment?: boolean;
 }
 interface AskUserOption {
-    /** 显示标签 */
+    /** 显示标签，回传时作为选中值（D1：proto 无独立 value，选中值统一用 label） */
     label: string;
-    /** 回传值。未提供时用 label */
-    value?: string;
     /** 描述（可选）。显示在 label 下方，解释 tradeoff */
     description?: string;
 }
@@ -210,16 +249,14 @@ interface AskUserOption {
  * ask-user 富交互回传结果。key = question.header（header 缺失时用 question 文本）。
  *
  * 答案编码规则（避免逗号歧义）：
- * - 单选：value = 选中项的 value string（或 label）
- * - 多选：value = JSON.stringify(选中项 value 数组)，如 '["pg","mysql"]'
- *   （不用逗号 join——option value 可能含逗号导致 split 歧义）
+ * - 单选：value = 选中项的 label
+ * - 多选：value = JSON.stringify(选中项 label 数组)，如 '["pg","mysql"]'
+ *   （不用逗号 join——option label 可能含逗号导致 split 歧义）
  * - Other 文本：单独 key `${header}__other`，value = 自由文本（不混进选中项数组）
- * - comment：单独 key `${header}__comment`，value = 评论文本
  *
  * extension 解析示例：
  *   const selected = JSON.parse(answers[header])  // 多选 → string[]
  *   const other = answers[`${header}__other`]     // Other 自由文本
- *   const comment = answers[`${header}__comment`] // 评论
  */
 type AskUserAnswers = Record<string, string>;
 
@@ -266,12 +303,10 @@ declare function askUserInteract(ctx: GuiContext, questions: AskUserQuestion[],
 declare function getAskUserAnswer(answers: AskUserAnswers, question: AskUserQuestion): string | string[] | undefined;
 /** 从 answers 中提取 Other 自由文本 */
 declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
-/** 从 answers 中提取评论（4.0.1 restore：ask-user TUI 评论模式与 renderer AskUserOverlay 仍消费此 helper） */
-declare function getAskUserComment(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
 /**
  * 类型守卫：验证 unknown 是否为合法的 AskUserQuestion。
  * 用于前端从 runtime 透传的 askUserQuestions（unknown[]）中安全收窄。
  */
 declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
 
-export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, PROTOCOL_VERSION, type StatItem, type TreeItem, type TreeItemIcon, askUserInteract, extractGui, getAskUserAnswer, getAskUserComment, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isGuiCapable, isGuiComponent };
+export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, PROTOCOL_VERSION, type StatItem, type TreeItem, type TreeItemIcon, type WidgetMeta, askUserInteract, extractGui, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult };

package/dist/index.mjs

@@ -8,19 +8,21 @@ var GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:";
 function isGuiCapable(ctx) {
   return ctx.mode === "rpc";
 }
-function guiResult(component) {
-  return {
+function guiResult(component, meta) {
+  const result = {
     v: PROTOCOL_VERSION,
     component: stripUndefined(component)
   };
+  if (meta !== void 0) result.meta = stripUndefined(meta);
+  return result;
 }
 function guiComponent(type, props) {
   return { type, props };
 }
-function guiSetWidget(ctx, key, component) {
+function guiSetWidget(ctx, key, result) {
   if (!ctx.ui?.setWidget) return;
-  if (component) {
-    const encoded = [GUI_WIDGET_MARKER + JSON.stringify(stripUndefined(component))];
+  if (result) {
+    const encoded = [GUI_WIDGET_MARKER + JSON.stringify(stripUndefined(result))];
     ctx.ui.setWidget(key, encoded);
   } else {
     ctx.ui.setWidget(key, void 0);
@@ -38,6 +40,11 @@ function isGuiComponent(value) {
   const obj = value;
   return typeof obj.type === "string" && obj.props !== null && obj.props !== void 0 && typeof obj.props === "object";
 }
+function isGuiRenderResult(value) {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value;
+  return obj.v === PROTOCOL_VERSION && isGuiComponent(obj.component);
+}
 function stripUndefined(obj) {
   if (obj === null || obj === void 0) return obj;
   if (typeof obj !== "object") return obj;
@@ -100,13 +107,10 @@ function getAskUserAnswer(answers, question) {
 function getAskUserOther(answers, question) {
   return answers[`${askUserKey(question)}__other`];
 }
-function getAskUserComment(answers, question) {
-  return answers[`${askUserKey(question)}__comment`];
-}
 function isAskUserQuestion(value) {
   if (typeof value !== "object" || value === null) return false;
   const q = 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") && (q.allowComment === void 0 || typeof q.allowComment === "boolean");
+  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");
 }
 export {
   ASK_USER_MARKER,
@@ -115,12 +119,12 @@ export {
   askUserInteract,
   extractGui,
   getAskUserAnswer,
-  getAskUserComment,
   getAskUserOther,
   guiComponent,
   guiResult,
   guiSetWidget,
   isAskUserQuestion,
   isGuiCapable,
-  isGuiComponent
+  isGuiComponent,
+  isGuiRenderResult
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyz-agent/extension-protocol",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Extension GUI rendering protocol: types and helpers for pi extension dual-mode (TUI/GUI) rendering",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",