@zhushanwen/extension-protocol 0.11.0 → 0.12.0

package/dist/background-task-entry.js

@@ -171,6 +171,11 @@ import { openSync, readSync, closeSync, statSync } from "fs";
 var TAIL_WINDOW_MARGIN_BYTES = 64;
 function readOutputTail(outputFile, opts, onLog) {
   const { maxBytes, maxLines } = opts;
+  if (!Number.isInteger(maxLines) || maxLines <= 0) {
+    throw new RangeError(
+      `readOutputTail: maxLines must be a positive integer, got ${maxLines} (outputFile: ${outputFile})`
+    );
+  }
   let size;
   try {
     size = statSync(outputFile).size;
@@ -182,7 +187,14 @@ function readOutputTail(outputFile, opts, onLog) {
   let fd;
   try {
     fd = openSync(outputFile, "r");
-    readSync(fd, buffer, 0, windowSize, size - windowSize);
+    let totalRead = 0;
+    while (totalRead < windowSize) {
+      const bytesRead = readSync(fd, buffer, totalRead, windowSize - totalRead, size - windowSize + totalRead);
+      if (bytesRead <= 0) break;
+      totalRead += bytesRead;
+    }
+    const text = (totalRead === windowSize ? buffer : buffer.subarray(0, totalRead)).toString("utf8");
+    return finishTail(text, { size, windowSize, maxBytes, maxLines });
   } catch {
     return void 0;
   } finally {
@@ -194,13 +206,14 @@ function readOutputTail(outputFile, opts, onLog) {
       }
     }
   }
-  const text = buffer.toString("utf8");
+}
+function finishTail(text, bounds) {
   const lines = text.split("\n");
-  const firstLineIsPartial = windowSize < size && lines.length > 0;
+  const firstLineIsPartial = bounds.windowSize < bounds.size && lines.length > 0;
   const effectiveLines = firstLineIsPartial ? lines.slice(1) : lines;
-  const byteTruncated = size > maxBytes;
-  const shown = effectiveLines.slice(-maxLines).join("\n");
-  return { text: shown, truncated: byteTruncated || effectiveLines.length > maxLines };
+  const byteTruncated = bounds.size > bounds.maxBytes;
+  const shown = effectiveLines.slice(-bounds.maxLines).join("\n");
+  return { text: shown, truncated: byteTruncated || effectiveLines.length > bounds.maxLines };
 }
 export {
   atomicWriteRegistry,

package/dist/index.d.ts

@@ -55,7 +55,7 @@ interface GuiComponentProps {
          *  自带编号的文本（goal criteria "1. xxx"）不要开，避免双重编号 */
         numbered?: boolean;
     };
-    /** 垂直组合容器——无视觉样式的透明分组。宿主壳层（WidgetArea）承担卡壳/head/折叠
+    /** 垂直组合容器——无视觉样式的透明分组。宿主壳层（托盘 widget 面板）承担卡壳/head/折叠
      *  后，widget 内容需要多组件组合时的组合根（替代「无头 card」的语义滥用） */
     'group': {
         children: GuiComponent[];
@@ -72,6 +72,13 @@ interface GuiComponentProps {
             active?: boolean;
             status?: 'done' | 'pending';
         }[];
+        /**
+         * 容器化分段（可选）：第 i 段 = tabs[i] 激活时渲染的子树，与 tabs 等长。
+         * 缺省维持「纯展示 tab-bar」现状（旧 extension 一行不改）；宿主本地持有
+         * active（首挂载取 tabs[i].active，点击只切本地索引，后续推送不重置用户
+         * 选择）；与 tabs 长度不等时忽略 sections 退化为纯展示（见协议文档）。
+         */
+        sections?: GuiComponent[][];
     };
     /** 自定义组件——逃生口（仅限内置 extension 编译期注册） */
     'custom': {
@@ -84,7 +91,7 @@ interface GuiRenderResult {
     v: typeof PROTOCOL_VERSION;
     component: GuiComponent;
     /**
-     * widget 宿主元数据（M17 对话流 widget 面板消费）：标题/状态点/进度计数由
+     * widget 宿主元数据（composer 任务托盘的协议 widget 区消费）：标题/状态点/进度计数由
      * 宿主壳层统一渲染成单一 head（含折叠交互），extension 不再用 card 原语
      * 的 header 表达这些（壳层 head 与 payload card header 双头重复的根因修复）。
      * 可选：不发时宿主 fallback 到 viewId 标题、无状态点/进度。
@@ -108,6 +115,21 @@ interface WidgetMeta {
         /** fill 语义色（预算阈值映射）；缺省按 meta.status（done→success，否则 accent） */
         severity?: 'ok' | 'warn' | 'danger';
     };
+    /**
+     * 托盘 icon：icon key 字符串（宿主按 lucide 名解析）或自定义形状 `{ paths }`。
+     * **形状归 extension、风格归宿主锁死**——extension 只给 path d 数组，线宽/颜色/
+     * 尺寸由宿主固定（与 @lucide 细线 icon 同构），故不会出现风格失控。
+     * 自定义形状经 `validateWidgetIconPaths` 白名单校验（字符集/条数/长度上限），
+     * 超限落兜底 icon + warn。缺省 → 宿主按 widgetKey 内置映射 → 通用 widget icon。
+     */
+    icon?: string | {
+        paths: string[];
+    };
+    /**
+     * 托盘 badge：extension 全权格式化的短文本（'2' / '42%' / '!'），建议 ≤6 字符
+     * （宿主超长 truncate 至 6，全文进 title）。缺省 → 宿主按 progress 派生 → 无 badge。
+     */
+    badge?: string;
 }
 interface StatItem {
     label?: string;
@@ -171,7 +193,7 @@ interface GuiContext {
  */
 declare function isGuiCapable(ctx: GuiContext): boolean;
 /**
- * 构造 GuiRenderResult。当前主用途是 guiSetWidget 的载荷（M17 对话流 widget 面板）；
+ * 构造 GuiRenderResult。当前主用途是 guiSetWidget 的载荷（composer 任务托盘的协议 widget 区）；
  * details.__gui__（tool result 通道）为遗留兼容路径，todo/goal 已不再使用。
  * stripUndefined 确保序列化不含 undefined（JSON.stringify 会丢弃 undefined 字段）。
  */
@@ -215,9 +237,43 @@ interface DualWidgetContent {
  * hasUI 守卫留在调用方（goal FR-6.6 语义，本 helper 不感知）。
  */
 declare function setWidgetDual(ctx: GuiContext, key: string, content: DualWidgetContent | undefined): void;
+/** 拒绝原因（宿主 warn 文案与 fallback 分诊用；判定顺序同 validateWidgetIconPaths 实现）。 */
+type WidgetIconPathsRejection = 
+/** 入参不是数组（含 undefined / null / 其他类型） */
+'not-array'
+/** 空数组——渲染无形状，等同无效自定义 icon */
+ | 'empty'
+/** 条数 > 8 */
+ | 'too-many'
+/** 存在非 string 条目 */
+ | 'non-string'
+/** 单条 > 512 字符 */
+ | 'too-long'
+/** 全部条目总长 > 2048 字符 */
+ | 'total-too-long'
+/** 含白名单外字符 */
+ | 'illegal-char';
+/** icon paths 校验判定：合法携带白名单内的 paths 副本；非法携带原因（不抛异常）。 */
+type WidgetIconPathsValidation = {
+    valid: true;
+    paths: string[];
+} | {
+    valid: false;
+    reason: WidgetIconPathsRejection;
+};
+/**
+ * 校验 WidgetMeta.icon 的自定义形状 paths（`{ paths: string[] }` 的内层数组）。
+ * 不抛异常——非法即返回原因，宿主据此落兜底 icon + warn（协议对 extension 的
+ * 宽容边界：坏数据不崩渲染，只是拿不到自定义形状）。
+ */
+declare function validateWidgetIconPaths(value: unknown): WidgetIconPathsValidation;
 /**
  * 从 details 中提取 GuiRenderResult。前端统一用此函数读取 __gui__，
  * 集中校验版本号，避免散落的 as 断言。
+ * component 字段校验（质量收敛批升级）：从「仅查存在性」升级为复用 isGuiComponent
+ * 结构校验（type 字符串 + props 对象——含 null 排除；component 不是函数，可调用性
+ * 检查对其无意义）。非法值 → undefined，走调用方既有降级路径（AnsiText/纯文本兜底），
+ * 畸形 component 不再进渲染层。
  */
 declare function extractGui(details: Record<string, unknown> | undefined): GuiRenderResult | undefined;
 /**
@@ -795,4 +851,4 @@ declare function collectActivePendingIds(entries: unknown[], opts?: CollectPendi
 type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted';
 declare function mapReasonToStatus(reason: string): MappedPendingStatus;
 
-export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, BRIDGE_MARKER, BRIDGE_METHODS, type BridgeErrorResponse, type BridgeInterceptResponse, type BridgeMethod, type BridgeRequest, type BridgeSyncPayload, type BridgeToolExecuteResponse, type ChannelErrorResult, type CollectPendingIdsOptions, type DualWidgetContent, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, INFLIGHT_REPORT_ACK, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_INFLIGHT_MARKER, 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 StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, type TreeItem, type TreeItemIcon, type WidgetMeta, applyPendingDiff, askUserInteract, callMarkerRpc, collectActivePendingIds, extractGui, firstContentText, formatChannelErrorText, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, scanPendingEntries, setWidgetDual };
+export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, BRIDGE_MARKER, BRIDGE_METHODS, type BridgeErrorResponse, type BridgeInterceptResponse, type BridgeMethod, type BridgeRequest, type BridgeSyncPayload, type BridgeToolExecuteResponse, type ChannelErrorResult, type CollectPendingIdsOptions, type DualWidgetContent, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, INFLIGHT_REPORT_ACK, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_INFLIGHT_MARKER, 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 StatItem, type SubagentEngineConfigView, type SubagentEnginesFile, type SubagentInFlightReport, type TreeItem, type TreeItemIcon, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, applyPendingDiff, askUserInteract, callMarkerRpc, collectActivePendingIds, extractGui, firstContentText, formatChannelErrorText, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isBridgeErrorResponse, isBridgeInterceptResponse, isBridgeSyncPayload, isBridgeToolExecuteResponse, isChannelErrorResult, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerSendParams, isSessionManagerStatusParams, isSubagentInFlightReport, isSyncedTool, mapReasonToStatus, scanPendingEntries, setWidgetDual, validateWidgetIconPaths };

package/dist/index.js

@@ -51,9 +51,30 @@ function setWidgetDual(ctx, key, content) {
     ctx.ui.setWidget(key, content.text);
   }
 }
+var ICON_PATH_D_ALLOWED_RE = /^[MLCQAZHVSTmlcqazhvst0-9 ,.\-]+$/;
+var ICON_PATHS_MAX_ENTRIES = 8;
+var ICON_PATH_MAX_CHARS = 512;
+var ICON_PATHS_MAX_TOTAL_CHARS = 2048;
+function validateWidgetIconPaths(value) {
+  if (!Array.isArray(value)) return { valid: false, reason: "not-array" };
+  if (value.length === 0) return { valid: false, reason: "empty" };
+  if (value.length > ICON_PATHS_MAX_ENTRIES) return { valid: false, reason: "too-many" };
+  const entries = value;
+  const paths = [];
+  let total = 0;
+  for (const entry of entries) {
+    if (typeof entry !== "string") return { valid: false, reason: "non-string" };
+    if (entry.length > ICON_PATH_MAX_CHARS) return { valid: false, reason: "too-long" };
+    if (!ICON_PATH_D_ALLOWED_RE.test(entry)) return { valid: false, reason: "illegal-char" };
+    paths.push(entry);
+    total += entry.length;
+  }
+  if (total > ICON_PATHS_MAX_TOTAL_CHARS) return { valid: false, reason: "total-too-long" };
+  return { valid: true, paths };
+}
 function extractGui(details) {
   const g = details?.__gui__;
-  if (g && typeof g === "object" && "v" in g && "component" in g && g.v === PROTOCOL_VERSION) {
+  if (g && typeof g === "object" && "v" in g && isGuiComponent(g.component) && g.v === PROTOCOL_VERSION) {
     return g;
   }
   return void 0;
@@ -385,5 +406,6 @@ export {
   isTerminalBackgroundTaskState,
   mapReasonToStatus,
   scanPendingEntries,
-  setWidgetDual
+  setWidgetDual,
+  validateWidgetIconPaths
 };

package/package.json

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