paseo-plugin-zcode-provider 0.3.0 → 0.4.0

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/rows.ts

@@ -1,10 +1,18 @@
+import { conversationQuotesSchema } from "../conversationSelection.js";
+import { botGroupInputSourceSchema } from "../bots.js";
 // ConversationRow：行类型自包含。
 // 三条结构性规则：row 自包含（渲染任一行不需看别的行）；
 // 结构变化换整行（row.upserted），文本增长用 append（row.delta）；turn 是 row 上的标签不是容器。
 import { z } from "zod";
+import { highspeedMessageMetaSchema } from "../highspeed.js";
 import { executionOutputPreviewSchema } from "../execution-output-preview.js";
 import { timestampSchema } from "./core.js";
-import { backgroundResultOriginMetaSchema, workflowLaunchMetaSchema } from "./workflow-row-meta.js";
+import { conversationInputSourceSchema } from "./input-intent.js";
+import {
+  backgroundResultOriginMetaSchema,
+  workflowLaunchMetaSchema,
+} from "./workflow-row-meta.js";
+import { attachmentRefSchema } from "./attachment-ref.js";
 
 // RowBase。rowId：session 内单调、永不复用、事件日志的确定性纯函数。
 const rowBaseFields = {
@@ -35,10 +43,12 @@ export type RowActions = NonNullable<z.infer<typeof rowActionsSchema>>;
 // workflow 轮的行级元数据拆到了 workflow-row-meta.ts（max-lines）；名字在此原样再导出。
 export {
   backgroundResultOriginMetaSchema,
+  workflowBlockedMetaSchema,
   workflowLaunchMetaSchema,
   workflowNotificationMetaSchema,
   workflowSettingsAmendMetaSchema,
   type BackgroundResultOriginMeta,
+  type WorkflowBlockedMeta,
   type WorkflowLaunchMeta,
   type WorkflowNotificationMeta,
   type WorkflowSettingsAmendMeta,
@@ -79,6 +89,12 @@ export const turnHeaderRowSchema = z.object({
   endedAt: timestampSchema.optional(),
   // 权威工时：排除权限等待/用户输入等待/verifier 等待。
   activeMs: z.number().optional(),
+  // 当前 product turn 内主链路 ModelComplete 的 output usage 累计；optional 兼容旧快照。
+  outputTokens: z.number().int().nonnegative().optional(),
+  // CLI 从运行时事件聚合的真实耗时；optional 兼容旧快照及普通 turn。
+  modelDurationMs: z.number().nonnegative().optional(),
+  toolDurationMs: z.number().nonnegative().optional(),
+  otherDurationMs: z.number().nonnegative().optional(),
   // guide 不切 product turn，但每条 accepted guide 都开启独立视觉工作段。
   // 普通 turn 缺省以保持旧 snapshot 兼容；一旦出现 guide，CLI 负责完整投影首段与后续段。
   workSegments: z.array(turnWorkSegmentSchema).optional(),
@@ -100,6 +116,9 @@ export type TurnHeaderRow = z.infer<typeof turnHeaderRowSchema>;
 export const userInputRowSchema = z.object({
   ...rowBaseFields,
   kind: z.literal("userInput"),
+  inputOrigin: z.enum(["desktop", "mobile"]).optional(),
+  botGroupSource: botGroupInputSourceSchema.optional(),
+  conversationQuotes: conversationQuotesSchema.optional(),
   text: z.string(),
   // text 从此下标起是引擎附加文本（dwf ask 尾注 /
   // nudge），GUI 把它折进默认收起的披露；0 = 整条都是；缺席 = 无（老转录、非工作流会话）。
@@ -135,17 +154,12 @@ export const userInputRowSchema = z.object({
   rootSourceCommandId: z.string().optional(),
   // 提交端身份由 CLI admission 写入；旧 transcript 可缺省。
   clientId: z.string().optional(),
-  attachments: z
-    .array(
-      z.object({
-        ref: z.string(),
-        fileName: z.string(),
-        mime: z.string(),
-        bytes: z.number(),
-        previewRef: z.string().optional(),
-      }),
-    )
-    .optional(),
+  // accelerated 历史展示的持久事实；缺省兼容普通消息和旧 snapshot。
+  highspeed: highspeedMessageMetaSchema.optional(),
+  // 重复定义曾在出队后的 row 校验中剥掉来源，导致历史附件丢失预览入口；与入站引用共用 schema。
+  attachments: z.array(attachmentRefSchema).optional(),
+  // 插件 UI 代发的消息带来源；卡片显示"来自插件 X"。旧 transcript 可缺省。
+  source: conversationInputSourceSchema.optional(),
 });
 export type UserInputRow = z.infer<typeof userInputRowSchema>;
 
@@ -203,9 +217,10 @@ export const toolCallRowSchema = z.object({
   // display 解析失败只丢这张卡的载荷，不拒整条 row（理由见 toolDisplay.ts 的 toolOutputSchema
   // 注释：装饰载荷不得决定 row/帧/订阅的生死）。
   display: toolCallDisplaySchema.optional().catch(undefined),
+  // （2026-09-12）：原 widgetState / widgetStateVisibility 已删除，插件 UI 界面状态不再进 row。
   // status=error 时必带。
   error: z.object({ code: z.string(), message: z.string() }).optional(),
-  // 仅 replayable 档运行中出现，终态清除。
+  // 运行中出现（ToolCallProgress 事件），终态清除。
   progress: toolProgressSchema.optional(),
   // continuous/replayable 共用的有界 Bash 内容，终态或后台移交时清除。
   outputPreview: executionOutputPreviewSchema.optional(),

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/sessions-index-workflow-activity.ts

@@ -41,6 +41,12 @@ export const sessionWorkflowPhaseSummarySchema = z.object({
    * 退化路（已进入的 phase）是按进入序拼出来的，没有并行可言，所以那时整个键缺席。
    */
   alongside: z.array(z.number().int().nonnegative()).max(WORKFLOW_RUNS_LIMITS.maxPhases).optional(),
+  /**
+   * 这一站是一处**还开着的留白**（docs/dynamic-workflow/presentation.md「Holes on the timeline」）：
+   * `open` = 还没走到，`waiting` = run 停在这里等主代理补全。侧栏据此把灯画成虚线（等待时警示色）。
+   * 补全之后它就是一个普通的站，键缺席。只有声明表那条路有这个事实（`run.phaseHoles`）。
+   */
+  hole: z.enum(["open", "waiting"]).optional(),
 });
 export type SessionWorkflowPhaseSummary = z.infer<typeof sessionWorkflowPhaseSummarySchema>;
 
@@ -62,6 +68,12 @@ export const sessionWorkflowRunSummarySchema = z.object({
   currentPhase: z.string().min(1).max(WORKFLOW_RUNS_LIMITS.maxPhaseNameLength).optional(),
   /** status === "running" 的子代理数（tooltip 的「{n} agents working」）。 */
   agentsWorking: z.number().int().nonnegative(),
+  /**
+   * 正在等主代理补全的留白名（`run.holes` 里第一条 waiting 的 `name`）：侧栏运行行写
+   * 「{name} · 等待补全」（docs/dynamic-workflow/presentation.md「Holes on the timeline」的「The sidebar」）。
+   * 没有停驻的留白时缺席。
+   */
+  waitingHole: z.string().min(1).max(WORKFLOW_RUNS_LIMITS.maxPhaseNameLength).optional(),
 });
 export type SessionWorkflowRunSummary = z.infer<typeof sessionWorkflowRunSummarySchema>;
 
@@ -98,16 +110,26 @@ function phaseNameMatches(stationName: string, stamp: string): boolean {
   );
 }
 
-function derivePhases(run: WorkflowRunState): SessionWorkflowPhaseSummary[] {
+/**
+ * 站点表的唯一推导。侧栏运行行（经 `summarizeRun`）与任务岛的 run 行都读它，所以两处的灯
+ * 永远对同一件事说同一句话；任务岛不另写第二套。
+ */
+export function deriveSessionWorkflowPhases(run: WorkflowRunState): SessionWorkflowPhaseSummary[] {
   const entered = new Set((run.phases ?? []).map((phase) => phase.name));
   const current = run.currentPhase;
   let names: string[];
   // 「同时在跑」的下标说的是**声明表**里的位置，所以只有走声明表这条路时它才有意义；退化路
   // （已进入的 phase + 当前 phase）是另一个下标空间，那时整张表不带。
   let alongside: readonly (readonly number[])[] | undefined;
+  // 还开着的留白（声明表的下标）；等待中的按名字从 `run.holes` 认——留白名按规则 9012 唯一。
+  let holeIndexes: ReadonlySet<number> = new Set();
+  const waitingNames = new Set(
+    (run.holes ?? []).filter((hole) => hole.state === "waiting").map((hole) => hole.name),
+  );
   if (run.phaseNames !== undefined && run.phaseNames.length > 0) {
     names = run.phaseNames;
     alongside = run.phaseAlongside;
+    holeIndexes = new Set(run.phaseHoles ?? []);
   } else {
     names = (run.phases ?? []).map((phase) => phase.name);
     if (current !== undefined && !entered.has(current)) names = [...names, current];
@@ -139,7 +161,14 @@ function derivePhases(run: WorkflowRunState): SessionWorkflowPhaseSummary[] {
     const beside = (alongside?.[index] ?? []).filter(
       (other) => Number.isInteger(other) && other >= 0 && other < emitted && other !== index,
     );
-    return { name, status, ...(beside.length === 0 ? {} : { alongside: beside }) };
+    // 留白站：等待中的按 `run.holes` 认（名字唯一），其余下标表点名的是还没走到的留白。
+    const hole = waitingNames.has(name) ? "waiting" : holeIndexes.has(index) ? "open" : undefined;
+    return {
+      name,
+      status,
+      ...(beside.length === 0 ? {} : { alongside: beside }),
+      ...(hole === undefined ? {} : { hole }),
+    };
   });
 }
 
@@ -148,6 +177,10 @@ function summarizeRun(
   work: BackgroundWorkSummary | undefined,
 ): SessionWorkflowRunSummary {
   const name = work?.title.trim();
+  // 在跑的 run 才有「等补全」可言：终态 run 的 waiting 记录已被 reducer 剥掉，这里再守一道。
+  const waitingHole = isSessionWorkflowRunLive(run.status)
+    ? (run.holes ?? []).find((hole) => hole.state === "waiting")?.name
+    : undefined;
   return {
     runId: run.runId,
     ...(run.toolCallId === undefined ? {} : { toolCallId: run.toolCallId }),
@@ -155,9 +188,10 @@ function summarizeRun(
     status: run.status,
     ...(run.stopReason === undefined ? {} : { stopReason: run.stopReason }),
     ...(work === undefined ? {} : { startedAt: work.startedAt }),
-    phases: derivePhases(run),
+    phases: deriveSessionWorkflowPhases(run),
     ...(run.currentPhase === undefined ? {} : { currentPhase: run.currentPhase }),
     agentsWorking: run.actors.filter((actor) => actor.status === "running").length,
+    ...(waitingHole === undefined ? {} : { waitingHole }),
   };
 }
 

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/sessions-index.ts

@@ -35,6 +35,7 @@ export const sessionSummarySchema = z.object({
   // custom = 用户显式重命名；default/generated 都不是产品语义上的手动标题。
   // optional 是为了兼容旧 sessions-index frame / 旧持久化摘要。
   titleSource: sessionMetaStateSchema.shape.titleSource.optional(),
+  lastOutcome: z.enum(["completed", "error", "interrupted"]).optional(),
   phase: sessionPhaseSchema,
   sessionEnded: z.boolean(),
   // 列表小圆点用（此处保留布尔，避免为侧栏订阅整个 backgroundWorks）。
@@ -72,6 +73,41 @@ export const sessionsIndexDeltaSchema = z.discriminatedUnion("op", [
 ]);
 export type SessionsIndexDelta = z.infer<typeof sessionsIndexDeltaSchema>;
 
+/** snapshot 缺席不是删除；按明确 ID 查询持久事实，不会创建或恢复运行实例。 */
+export const sessionsIndexReconcileParamsSchema = z
+  .object({
+    workspaceId: z.string().min(1),
+    sessionIds: z.array(z.string().min(1)).max(256),
+  })
+  .strict();
+export type SessionsIndexReconcileParams = z.infer<typeof sessionsIndexReconcileParamsSchema>;
+export const sessionsIndexReconcileResultSchema = z
+  .object({
+    sessions: z
+      .array(
+        z.discriminatedUnion("exists", [
+          z
+            .object({ sessionId: z.string(), exists: z.literal(false), deleted: z.literal(false) })
+            .strict(),
+          z
+            .object({
+              sessionId: z.string(),
+              exists: z.literal(true),
+              deleted: z.boolean(),
+              title: z.string(),
+              titleSource: sessionMetaStateSchema.shape.titleSource,
+              createdAt: timestampSchema,
+              updatedAt: timestampSchema,
+              lastOutcome: z.enum(["completed", "error", "interrupted"]).optional(),
+            })
+            .strict(),
+        ]),
+      )
+      .max(256),
+  })
+  .strict();
+export type SessionsIndexReconcileResult = z.infer<typeof sessionsIndexReconcileResultSchema>;
+
 /** sessions-index topic key 构造（与 parseSessionsIndexTopic 对偶）。 */
 export function sessionsIndexTopic(workspaceId: string): string {
   return `sessions-index/${workspaceId}`;

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/snapshot.ts

@@ -60,6 +60,7 @@ export const activeWorkSummarySchema = z.object({
     "turnSteer",
   ]),
   foregroundExecutionId: z.string().min(1).optional(),
+  sourceCommandId: z.string().min(1).optional(),
   startedAt: timestampSchema,
 });
 export type ActiveWorkSummary = z.infer<typeof activeWorkSummarySchema>;
@@ -99,6 +100,10 @@ export const errorAttributionSchema = z
     statusCode: z.number().int().min(100).max(599).optional(),
     providerErrorCode: z.string().min(1).max(160).optional(),
     retryable: z.boolean().optional(),
+    /** string=使用该 Highspeed 卡，null=明确未使用，undefined=旧 Agent 未发布。 */
+    highspeedCardId: z.string().nullable().optional(),
+    /** true=本轮 Highspeed 失败已命中退回声明但无可用退回目标；Renderer 据此作废匹配卡。 */
+    highspeedFallbackUnavailable: z.boolean().optional(),
   })
   .strict();
 export type ErrorAttribution = z.infer<typeof errorAttributionSchema>;
@@ -467,7 +472,21 @@ export const workspaceHookAdmissionStateSchema = z.object({
 });
 export type WorkspaceHookAdmissionSnapshotState = z.infer<typeof workspaceHookAdmissionStateSchema>;
 
+// 冷历史可读不代表 runtime 已可执行；缺席兼容旧发送端。
+export const runtimeInitializationSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("initializing"), attemptId: z.string().min(1) }),
+  z.object({ status: z.literal("ready"), attemptId: z.string().min(1) }),
+  z.object({
+    status: z.literal("failed"),
+    attemptId: z.string().min(1),
+    reasonCode: z.string(),
+    message: z.string(),
+  }),
+]);
+export type RuntimeInitialization = z.infer<typeof runtimeInitializationSchema>;
+
 export const conversationSnapshotSchema = z.object({
+  runtimeInitialization: runtimeInitializationSchema.optional(),
   protocolVersion: z.literal(1),
   sessionId: z.string(),
   logEpoch: z.string(),
@@ -503,6 +522,8 @@ export const conversationSnapshotSchema = z.object({
   // 旧快照/旧发送端不携带此字段 → 解析得 null,不破坏兼容性(遵守冻结规则)。
   // pendingCount === 0 时投影层置 null(提示条消失)。
   workspaceHookAdmission: workspaceHookAdmissionStateSchema.nullable().default(null),
+  // （2026-09-12）：原 additive 字段 pluginUiSurfaces 已删除，插件面板 widgetState 只留在
+  // 宿主 renderer 内存。
   // B 区
   rows: rowsWindowSchema,
 });

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/submission.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
 
 /** Composer 可以显式提交的 Agent mode；auto 是 Runtime 内部状态，不进入用户 Submission。 */
-export const submissionModeSchema = z.enum(["build", "edit", "plan", "yolo"]);
+export const submissionModeSchema = z.enum(["build", "edit", "plan", "yolo", "guarded"]);
 export type SubmissionMode = z.infer<typeof submissionModeSchema>;

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/toolDisplay.ts

@@ -6,6 +6,7 @@ import { bashOutputDisplaySchema } from "../bash-output-display.js";
 import { timestampSchema } from "./core.js";
 import { OFFICIAL_MCP_TOOL_ERROR_CODES } from "../official-mcp-tool-error.js";
 import { cuaRequestAccessStatusSchema } from "./cuaPermission.js";
+import { mcpToolDisplayUiSchema } from "../mcp-apps/schemas.js";
 import { toolCallCreateWorkflowDisplaySchema } from "./create-workflow-display.js";
 import {
   toolCallEvalWorkflowSnippetDisplaySchema,
@@ -20,7 +21,7 @@ import {
 // errorCode/suggestedAction/media(screenshot) 等结构化内容带到 renderer）。consume-main 之前
 // 缺这个 union + toolOutputSchema.display 字段——协议层 zod 校验会把 agent 下发的 display 整个
 // strip 掉，导致 UI 永远拿不到 display?.kind==="cua"，CUA 工具调用退化成 fallback 渲染。
-const toolResultDisplaySchema = z.discriminatedUnion("kind", [
+export const toolResultDisplaySchema = z.discriminatedUnion("kind", [
   bashOutputDisplaySchema,
   z.object({
     kind: z.literal("file_diff"),
@@ -133,6 +134,8 @@ const toolResultDisplaySchema = z.discriminatedUnion("kind", [
       .object({ code: z.enum(OFFICIAL_MCP_TOOL_ERROR_CODES) })
       .strict()
       .optional(),
+    // 插件 UI 元数据；与 CLI contracts 的 mcpToolResultDisplayPayloadSchema 同源复用，见 mcp-apps/schemas.ts。
+    ui: mcpToolDisplayUiSchema.optional(),
   }),
   // buildToolOutput 把 CLI 侧 ToolResultDisplayPayload 原样塞进 toolOutput.display，
   // 而这条 union 是 strict 的——create_workflow 不在成员里，CreateWorkflow 的 display 会被整段
@@ -150,8 +153,27 @@ const toolResultDisplaySchema = z.discriminatedUnion("kind", [
 ]);
 export type ToolResultDisplay = z.infer<typeof toolResultDisplaySchema>;
 
-// toolCall。终态 output 全档统一 head+tail 截断，超出走 truncated.ref 按需拉。
-// display 是展示载荷；版本不兼容时降级为无卡片，避免同一内容导致整条订阅反复恢复失败。
+// §4.4.5 toolCall。终态 output 全档统一 head+tail 截断（R-10），超出走 truncated.ref 按需拉。
+//
+// ⚠ display 在信封层**不设门**（`.optional().catch(undefined)`）：解析不过就退化成「这张卡没有
+// 载荷」，而不是让整条 row、整帧、整条订阅失败。四个嵌入点共用这条规则——本文件的
+// toolOutputSchema、rows.ts 的 toolCallRow、snapshot.ts 的确认预览、workflow-row-meta.ts 的
+// 启动行图；spec 见 docs/v4-refactor/10-protocol-spec.md §4.4.5 与
+// docs/v4-refactor/04-sync-and-recovery.md 封闭规则 11。
+//
+// 根因（2026-09-21，sess_4142de31）：display 是装饰载荷，却长在 liveness 关键的信封里。CLI 给
+// `list_workflow_runs` 的 run 行加了两个 lineage 键，本侧镜像没跟上 → 整帧被
+// `proto.frameAssemblyInvalidPayload` 拒 → 恢复阶梯在同一份内容上重试 → 会话停在
+// `fault.subscription.recoveryFailed`；而每次快照都重放同一份存量载荷，会话永不自愈。同款事故
+// 2026-09-17 已经发生过一次（`get_workflow_run` 的 `providerStop`），当时只修了那一个字段。
+//
+// 严格性没有丢，只是回到该在的那一层：渲染侧 readToolResultDisplay
+// （packages/ui/src/ToolCallBlocks/toolResultDisplay.ts）本来就按 kind 逐个 strict 解析，失败即
+// 回 undefined、卡片退化成纯文本——这正是各 spec 一直承诺的行为。信封层那道门是重复的第二道
+// 门，唯一的独有效果是杀死会话。
+//
+// 成员 schema 仍然 `.strict()`：它们定义「本端认得的形状」，catch 只把「不认得」从致命降级为
+// 无卡。代价是 skew 变静默，补偿手段是构造侧与镜像侧的 parity 测试，而不是让线上订阅去发现。
 export const toolOutputSchema = z.object({
   text: z.string(),
   display: toolResultDisplaySchema.optional().catch(undefined),
@@ -164,9 +186,14 @@ export const toolOutputSchema = z.object({
 });
 export type ToolOutput = z.infer<typeof toolOutputSchema>;
 
+// 工具运行中的进度（）：MCP `notifications/progress` 经 ToolCallProgress 事件投影到行上。
+// fraction 由 payload progress/total 推得（total 缺失时不填）；bytes / previewLine 保留给 shell 输出型进度。
 export const toolProgressSchema = z.object({
-  bytes: z.number(),
+  bytes: z.number().optional(),
   previewLine: z.string().optional(),
+  fraction: z.number().min(0).max(1).optional(),
+  total: z.number().optional(),
+  message: z.string().max(200).optional(),
   updatedAt: timestampSchema,
 });
 export type ToolProgress = z.infer<typeof toolProgressSchema>;
@@ -245,6 +272,7 @@ const toolCallMcpDisplaySchema = z
       .object({ code: z.enum(OFFICIAL_MCP_TOOL_ERROR_CODES) })
       .strict()
       .optional(),
+    ui: mcpToolDisplayUiSchema.optional(),
   })
   .strict();
 

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/transport.ts

@@ -35,6 +35,7 @@ export const hostCapabilitiesSchema = z.object({
    * `state.updated`，并且先经 `clampWorkflowRunsForLegacy` 裁到旧界。
    */
   workflowRunDeltas: z.boolean().optional(),
+  historyFirst: z.boolean().optional(),
 });
 export type HostCapabilities = z.infer<typeof hostCapabilitiesSchema>;
 
@@ -82,6 +83,7 @@ export const clientHelloSchema = z
          * 是 `.strict()` 的，老 Host 见到不认识的键会整条 clientHello 解析失败、连接握不上手。
          */
         workflowRunDeltas: z.boolean().optional(),
+        historyFirst: z.boolean().optional(),
       })
       .strict()
       .optional(),
@@ -112,6 +114,8 @@ export const subscribeParamsSchema = z
     topic: z.string(),
     // 水位不变量：仅当客户端真持有该时刻一致状态才允许带。
     base: z.object({ logEpoch: z.string(), seq: z.number() }).optional(),
+    // 手动重试仅消费当前 failed attempt；普通重连不重跑 hook。
+    retryInitialization: z.string().min(1).optional(),
     // QoS hint，只影响调度，不影响语义。
     visibility: z.enum(["foreground", "background"]).optional(),
   })
@@ -142,6 +146,7 @@ export const conversationOpenTimingSchema = z
     cliRequestMs: openTimingMsSchema,
     cliBootstrapMs: openTimingMsSchema,
     cliSessionRestoreMs: openTimingMsSchema,
+    historyReadyMs: openTimingMsSchema,
     initialFrameEncodeMs: openTimingMsSchema,
     cliProcessState: z.enum(["spawned", "reused"]).optional(),
     sessionRuntimeState: z.enum(["cold", "warm"]).optional(),
@@ -335,6 +340,7 @@ export const V4_METHODS = {
   controllerResync: "v4/controller/resync",
   controllerUnsubscribe: "v4/controller/unsubscribe",
   conversationSubscribe: "v4/conversation/subscribe",
+  sessionsIndexReconcile: "v4/sessionsIndex/reconcile",
   conversationResync: "v4/conversation/resync",
   conversationUnsubscribe: "v4/conversation/unsubscribe",
   // 行分页 query（rows/range）：只读、无状态、超时重发安全。
@@ -343,6 +349,7 @@ export const V4_METHODS = {
   conversationPlans: "v4/conversation/plans",
   conversationFileChanges: "v4/conversation/fileChanges",
   backgroundBashOutput: "v4/conversation/backgroundBashOutput",
+  offPeakControl: "v4/conversation/offPeakControl",
   conversationFileRewindPreview: "v4/conversation/fileRewindPreview",
   // workflow run 的事件日志分页（详情页审计面）：只读、无状态、超时重发安全。
   // 新方法天然偏斜安全——旧桌面根本不会调用它。
@@ -405,6 +412,7 @@ export type V4ConnectionFlowParams = z.infer<typeof v4ConnectionFlowParamsSchema
 export const v4ConnectionFlowResultSchema = z.object({}).strict();
 
 export const V4_NOTIFICATIONS = {
+  offPeakLifecycle: "v4/offPeak/lifecycle",
   // 下行帧（snapshot / deltas），params = ConversationTopicFrame。
   conversationFrame: "v4/conversation/frame",
   // 仅 live ingest 的无正文事实；不进入 topic snapshot/recovery。
@@ -412,6 +420,7 @@ export const V4_NOTIFICATIONS = {
   localTtftFacts: "v4/telemetry/local-ttft",
   // 仅当前进程 live ToolCallResult 产生；历史与 replayable 链路不得补造。
   cuaPermissionObservation: "v4/cua/permission-observation",
+  pluginUiToolResult: "v4/plugin-ui/tool-result",
 } as const;
 
 /** 3.3.6 SSH 历史任务归属证明与 sessions-index 冷种子共享同一有界窗口。 */
@@ -420,6 +429,7 @@ export const MAX_LEGACY_TASK_IDS_PER_SUBSCRIBE = 200;
 // subscribe 请求 = 通用 SubscribeParams + connectionId（重订阅替换按
 // (connectionId, topic) 判定；stdio 单管道场景由 host 为每个下游客户端分配）。
 export const v4ConversationSubscribeParamsSchema = subscribeParamsSchema.extend({
+  additionalDirectories: z.array(z.string().trim().min(1)).max(256).optional(),
   connectionId: z.string(),
   clientMode: z.enum(["desktop-continuous", "web-remote-replayable"]),
   // 当前可信 attachment 的 workspace；cold resume 优先使用它恢复身份，live 不消费。
@@ -434,6 +444,7 @@ export const v4ConversationSubscribeParamsSchema = subscribeParamsSchema.extend(
    * 不是某一次订阅可以自选的口味。缺席 = 按旧消费者处理（整键 patch + 旧界裁剪）。
    */
   workflowRunDeltas: z.boolean().optional(),
+  historyFirst: z.boolean().optional(),
 });
 export type V4ConversationSubscribeParams = z.infer<typeof v4ConversationSubscribeParamsSchema>;
 
@@ -596,13 +607,24 @@ export type V4ConversationFileChangesResult = z.infer<typeof v4ConversationFileC
 // （`appendEvent` 单调分配），在 workflowRuns[].lastEventSequence 抬升时重取。
 // 刻意**不是** v4 command：command 的 ACK 结果是 commandResultSchema 那个封闭的「变更结果」
 // 判别联合，把一页只读事件塞进去等于把读放进写的词汇表，还要白背 baseRevision/幂等那套机制。
+
+/**
+ * 事件日志一页的两道界，网关按它们取数（apps/zcode-cli/packages/dynamic-workflow/docs/execution-engine.md
+ * 「Reading the journal」）。字节按存储里的序列化字节计、取协议单帧上限的四分之一：条数单独
+ * 管不住字节，500 条带着大 report item 的事件足以顶到单帧上限。
+ */
+export const WORKFLOW_RUN_EVENTS_PAGE_LIMITS = {
+  maxEvents: 500,
+  maxBytes: PROTOCOL_V4_LIMITS.logicalFrameAssemblyMaxBytes / 4,
+} as const;
+
 export const v4ConversationWorkflowRunEventsParamsSchema = z
   .object({
     sessionId: z.string().min(1),
     runId: z.string().min(1),
     /** 只取 sequence 严格大于该值的事件；缺省从头取。 */
     afterSequence: z.number().int().nonnegative().optional(),
-    limit: z.number().int().positive().max(500).optional(),
+    limit: z.number().int().positive().max(WORKFLOW_RUN_EVENTS_PAGE_LIMITS.maxEvents).optional(),
   })
   .strict();
 export type V4ConversationWorkflowRunEventsParams = z.infer<
@@ -623,7 +645,7 @@ export const v4ConversationWorkflowRunEventsResultSchema = z
         })
         .strict(),
     ),
-    /** 本页取满 limit 且后面仍有事件。 */
+    /** 本页之后仍有事件（页可能因条数或字节上界提前收尾）。 */
     hasMore: z.boolean(),
   })
   .strict();
@@ -1016,8 +1038,9 @@ export const v4AttachmentReadResultSchema = z
         (value) =>
           value.startsWith("image/") ||
           value.startsWith("video/") ||
-          value.split(";", 1)[0]?.trim().toLowerCase() === "application/pdf",
-        "attachment preview only supports image/video/pdf media types",
+          value.split(";", 1)[0]?.trim().toLowerCase() === "application/pdf" ||
+          value.split(";", 1)[0]?.trim().toLowerCase() === "text/plain",
+        "attachment preview only supports image/video/pdf/plain text types",
       ),
     totalBytes: z.number().int().nonnegative().max(PROTOCOL_V4_LIMITS.attachmentPreviewMaxBytes),
     nextOffset: z.number().int().positive().nullable(),
@@ -1025,7 +1048,9 @@ export const v4AttachmentReadResultSchema = z
   .strict()
   .superRefine((value, context) => {
     if (
-      value.mediaType.startsWith("image/") &&
+      // 根因：运行时已支持材料文本，响应 schema 仍只接受媒体，导致跨进程预览失败。
+      (value.mediaType.startsWith("image/") ||
+        value.mediaType.split(";", 1)[0]?.trim().toLowerCase() === "text/plain") &&
       value.totalBytes > PROTOCOL_V4_LIMITS.attachmentMaxBytes
     ) {
       context.addIssue({
@@ -1033,7 +1058,7 @@ export const v4AttachmentReadResultSchema = z
         maximum: PROTOCOL_V4_LIMITS.attachmentMaxBytes,
         origin: "number",
         inclusive: true,
-        message: "image preview exceeds total byte limit",
+        message: "image/text preview exceeds total byte limit",
         path: ["totalBytes"],
       });
     }

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-assembler.ts

@@ -192,7 +192,10 @@ export class TopicWireFrameAssembler<F> {
   accept(wire: TopicWireFrameCandidate, now = Date.now()): TopicWireAssemblyEvent<F>[] {
     const events = this.expire(now);
     const key = routeKey(wire.topic, wire.subscriptionId);
-    if (!Number.isSafeInteger(wire.logicalFrameOrdinal) || wire.logicalFrameOrdinal < 1) {
+    if (
+      !Number.isSafeInteger(wire.logicalFrameOrdinal) ||
+      wire.logicalFrameOrdinal < 1
+    ) {
       events.push(this.fault(wire, "proto.frameAssemblyMetadataMismatch"));
       return events;
     }

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/wire-fault.ts

@@ -1,11 +1,14 @@
 // V4 physical assembly fault 的分类：**内容确定性失败** vs 瞬态失败。
+// spec：docs/v4-refactor/04-sync-and-recovery.md 封闭规则 11、
+// docs/v4-refactor/05-transport-and-backpressure.md「客户端规则」。
 //
 // 恢复阶梯默认把 fault 当瞬态处理：先 same-sub resync（服务端可能回 resume），再断档则升级
 // forceSnapshot，仍不成则 fail closed。这套升级对丢片、超时、校验和不符是对的——重投一次很可能
 // 就好了。对 **schema 拒收** 却是错的：字节已经过了 length/checksum/UTF-8/JSON 四道关，被拒说明
 // 本端读不懂对端发来的**内容**，而 resume 档只会把同一批 delta 再投一遍，必然同样被拒。
 //
-// 工具卡载荷出现不兼容字段时，重投相同内容无法恢复；应尝试快照后明确报告内容不兼容。
+// 2026-09-21（sess_4142de31）的事故就是这条：一个工具卡载荷多带两个键，恢复阶梯在同一份内容上
+// 烧掉三帧后 fail closed，用户手动「重新连接」两次、每次再烧三帧，会话再也打不开。
 //
 // 本模块只回答「这个 reason code 是不是确定性内容失败」，不决定怎么处置——处置在两个 store 里
 // （conversationProjectionStore / sessionsIndexStore）。

package/server/vendor/zcode/packages/shared/src/zcode-protocol-v4/workflow-artifacts.ts

@@ -49,8 +49,49 @@ export const WORKFLOW_ARTIFACT_LIMITS = {
   maxItemsPerPage: 500,
   /** 一页的缺省条数（调用方不传 limit 时网关用它）。 */
   defaultItemsPerPage: 200,
+  /**
+   * `workflowRunArtifactData` 一页的字节上界（按存储里的序列化字节计），由网关传给存储层。
+   * 取协议单帧上限（16 MiB）的四分之一：条数上界单独管不住字节——500 条 × 32 KiB 就顶到了
+   * 单帧上限，于是一页可能根本发不出去。一页至少带一条，所以单条的上限（`REPORT_CAPS`）
+   * 必须远小于单帧上限。
+   */
+  maxPageBytes: PROTOCOL_V4_LIMITS.logicalFrameAssemblyMaxBytes / 4,
+  /** `workflowRunArtifactData` 一次最多点名几个字段路径（一张看板的 spec 用不到这么多）。 */
+  maxFieldsPerRequest: 32,
+  /** 一个字段路径的最大长度。 */
+  maxFieldPathLength: 256,
+  /**
+   * 一个字段值的序列化字节上界。超过的值回成一段截短的字符串（前 1,000 个字符加「…」）：
+   * 图表只用数值，表格与看板的格子本来就只显示短文本。
+   */
+  maxFieldValueBytes: 4096,
 } as const;
 
+/**
+ * 按点路径从一条 report item 里取值："timing.after"、"rounds.0.ms"（docs/execution-engine.md
+ * 「Reading the journal」）。
+ *
+ * 这是**协议上的契约**，不只是渲染器的工具函数：看板取数时 CLI 在 SQLite 里按同一套规则把
+ * 字段取出来（adapters 的 dwf-journal-fields.ts），渲染器拿到的值必须与它自己从整条 item 里
+ * 取出来的逐字相同。规则：按 `.` 切段；当前值是数组时，段按 `Number(段)` 当下标（非负整数且
+ * 在界内才算）；是对象时按键取；走不通（null、标量、越界、缺键）得 `undefined`。
+ */
+export function readWorkflowArtifactField(item: unknown, path: string): unknown {
+  let cursor: unknown = item;
+  for (const segment of path.split(".")) {
+    if (cursor === null || cursor === undefined) return undefined;
+    if (Array.isArray(cursor)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= cursor.length) return undefined;
+      cursor = cursor[index];
+      continue;
+    }
+    if (typeof cursor !== "object") return undefined;
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return cursor;
+}
+
 /**
  * 一个产物版本的**元数据**（journal `dwf_node.result_json` 上 `ArtifactVersionRecord` 的
  * zod 镜像）。字节不在这里——`uri` 指向 tool-artifact store，取字节走
@@ -120,7 +161,7 @@ export type WorkflowRunArtifact = z.infer<typeof workflowRunArtifactSchema>;
  * `workflowRunArtifactRead` 取字节）按需拉——权威始终在 journal。
  *
  * `itemCount` 在这里的职责是**刷新信号**：看板 hook 见它变化就带 `afterSequence` 增量取数。
- * 把标签 report 的原值放进快照会让 256 条 × 32KB 的最坏情形把状态帧撑到 2MB。
+ * 把标签 report 的原值放进这个高频状态键，一个 run 的条目有多少字节，每一帧就要搬多少字节。
  */
 export const workflowRunArtifactSummarySchema = z
   .object({
@@ -174,6 +215,18 @@ export const v4ConversationWorkflowRunArtifactDataParamsSchema = z
     afterSequence: z.number().int().nonnegative().optional(),
     /** 缺省 200、钳 [1, 500]——两者都在网关侧执行（存储层不得自造页大小，也不得再钳）。 */
     limit: z.number().int().positive().max(WORKFLOW_ARTIFACT_LIMITS.maxItemsPerPage).optional(),
+    /**
+     * 只取这些字段路径（{@link readWorkflowArtifactField} 的规则），而不是整条 item：看板只读
+     * spec 里点名的字段，一条 1 MiB 的 item 不该为了一个数被整条搬进渲染器。给了它，结果每条
+     * 带 `fields` 而不带 `item`。缺省 = 整条 item（老渲染器的形状）。
+     *
+     * 偏斜：老 CLI 的 strict schema 不认这个键、整条请求被拒；渲染器据此退回不带它重试。
+     */
+    fields: z
+      .array(z.string().min(1).max(WORKFLOW_ARTIFACT_LIMITS.maxFieldPathLength))
+      .min(1)
+      .max(WORKFLOW_ARTIFACT_LIMITS.maxFieldsPerRequest)
+      .optional(),
   })
   .strict();
 export type V4ConversationWorkflowRunArtifactDataParams = z.infer<
@@ -193,14 +246,19 @@ export const v4ConversationWorkflowRunArtifactDataResultSchema = z
           /**
            * 条目原值，**不做预览序列化**：看板的纯函数要按字段路径取数
            * （`ChartSpec.x.field` 形如 "timing.after"），拿到一段 pretty JSON 文本就没法取了。
-           * 单条在线上已由 `REPORT_CAPS.maxItemSerializedBytes`（32KB）与事件载荷有界化
-           * 双重保证，这里不再叠一层界。
+           * 单条由写入侧的 `REPORT_CAPS.maxItemSerializedBytes` 有界，一页由
+           * `WORKFLOW_ARTIFACT_LIMITS.maxPageBytes` 有界。请求带 `fields` 时缺席。
            */
           item: z.unknown(),
+          /**
+           * 请求带 `fields` 时：路径 → 值。走不通的路径不在表里（= `undefined`）；超过
+           * `maxFieldValueBytes` 的值是一段截短的字符串。
+           */
+          fields: z.record(z.string(), z.unknown()).optional(),
         })
         .strict(),
     ),
-    /** 本页取满 limit 且后面仍有条目（网关多取一条判定）。 */
+    /** 本页之后仍有条目（页可能因条数或字节上界提前收尾；由存储层判定）。 */
     hasMore: z.boolean(),
   })
   .strict();