@xyz-agent/extension-protocol 0.4.0 → 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 的富交互类型定义。
@@ -266,4 +309,4 @@ declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuest
  */
 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, 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;
@@ -118,5 +125,6 @@ export {
   guiSetWidget,
   isAskUserQuestion,
   isGuiCapable,
-  isGuiComponent
+  isGuiComponent,
+  isGuiRenderResult
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xyz-agent/extension-protocol",
-  "version": "0.4.0",
+  "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",