paseo-plugin-zcode-provider 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,156 @@
+// ============================================================
+// CreateWorkflow 的工具卡 display 载荷（rows.ts 的 toolCallDisplaySchema 成员）
+// ============================================================
+// 从 rows.ts 拆出：workflow display + 因果图两段 schema 让 rows.ts 越过 max-lines 上限，
+// 且它们是一块自洽的词汇表（与 workspace-hook-review.ts 同一先例——特性级 schema 单独成模块）。
+
+import { z } from "zod";
+
+// CreateWorkflow display 是独立于模型文本的有界投影；诊断条数与单条 message 长度都必须在
+// 协议边界限长，避免类型检查结果把 continuous/replayable 消息扩成无界载荷。
+// causalityGraph 同理：step / 车道 / 边的数量与标签长度在工具输出边界已限长，这里镜像
+// 同一组上界。图的词汇表刻意很小：参与者卡 + 一种箭头（runs after，`back` 只标回边）+
+// 阶段模块 + 返回物标记；分析器的 kind / certainty / exact / region 不进载荷。交接边是因果事实按子代理取商，阶段层
+// 的边是控制流图的阶段商；step / 车道只作运行状态与检视器的键，不再画进图。
+//
+// 名字只在运行时成形（`` agent(`研究员${i + 1}`) ``）时静态能拿到的形状：第一个洞之前的
+// 字面量（head）与最后一个洞之后的字面量（tail）。至少一个在场，两者都已 trim 且含实义字符。
+// 只搬**数据**：渲染成「研究员…」的省略号由 name-pattern.ts 在渲染时加，投影里不存文案
+// （与匿名兜底同一道理——见 lane-name.ts 头部）。
+const namePatternSchema = z
+  .object({
+    head: z.string().min(1).max(128).optional(),
+    tail: z.string().min(1).max(128).optional(),
+  })
+  .strict();
+
+// 一条边 = runs after；交接边与阶段边同形。`back` 只标循环回边（布局排秩与 cycle 计数读），
+// 画法与其他边相同。
+const workflowEdgeSchema = z
+  .object({
+    from: z.string().min(1).max(64),
+    to: z.string().min(1).max(64),
+    back: z.literal(true).optional(),
+  })
+  .strict();
+
+const toolCallCreateWorkflowCausalityGraphSchema = z
+  .object({
+    steps: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(64),
+            kind: z.enum(["ask", "world-read"]),
+            label: z.string().min(1).max(128),
+            // 内联 `agent()` receiver 让 label 落到兜底串时，那个名字的静态形状。
+            labelPattern: namePatternSchema.optional(),
+            line: z.number().int().positive().optional(),
+            column: z.number().int().positive().optional(),
+            lane: z.string().min(1).max(64),
+            lanes: z.array(z.string().min(1).max(64)).max(32).optional(),
+            // 展开自的站点 id，只出现在 may-set 车道展开的拷贝上（实时叠加的关联键）；
+            // 加字段是 additive 的，不带它的旧载荷照常通过 .strict()。
+            source: z.string().min(1).max(64).optional(),
+            // 作者用 `phase("…")` 标记划入的阶段。
+            // 与图的 phases / phaseEdges / exits 同进同退：全在场或全缺席。
+            phase: z.string().min(1).max(64).optional(),
+            repeat: z.enum(["stack", "serial"]).optional(),
+          })
+          .strict(),
+      )
+      .max(64),
+    lanes: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(64),
+            name: z.string().min(1).max(128).optional(),
+            // `name` 缺席而 agent() 首参是带洞的模板串时的静态形状；与 name 互斥。
+            namePattern: namePatternSchema.optional(),
+            line: z.number().int().positive().optional(),
+            column: z.number().int().positive().optional(),
+          })
+          .strict(),
+      )
+      .max(32),
+    // 参与者 = 每阶段一张子代理卡（工作区 / 未解析同形）；数组顺序就是交接序，第一张是开局者。
+    // fan-out 家族按字面量基数展开成 member，基数未知时一张 many 卡。
+    participants: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(64),
+            phase: z.string().min(1).max(64),
+            lane: z.string().min(1).max(64),
+            steps: z.array(z.string().min(1).max(64)).min(1).max(64),
+            member: z
+              .object({ index: z.number().int().nonnegative(), of: z.number().int().positive() })
+              .strict()
+              .optional(),
+            many: z.literal(true).optional(),
+          })
+          .strict(),
+      )
+      .max(64),
+    // 交接 = 参与者之间的 runs after；types 是跨越它的产物类型（检视器素材，不上箭头）。
+    handoffs: z
+      .array(
+        workflowEdgeSchema
+          .extend({ types: z.array(z.string().min(1).max(128)).min(1).max(8).optional() })
+          .strict(),
+      )
+      .max(256),
+    // 阶段词汇表：作者施加的分组结构，主画面以它为节点。与 phaseEdges / exits / Step.phase
+    // 全有或全无——零标记脚本全缺席，UI 据此退回 step/车道视图。零成员阶段也在表里。
+    // `unphased` 无 name，显示名由 UI 本地化。
+    phases: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(64),
+            name: z.string().min(1).max(128).optional(),
+            line: z.number().int().positive().optional(),
+            column: z.number().int().positive().optional(),
+            // 进入本阶段时还在跑的其他阶段（它们的 strand 尚未 join），阶段表序，不含自己，
+            // 为空时缺席。是节点事实而不是边——控制没有从那里转移过来，所以不进 phaseEdges。
+            // 时间轴据此把相邻阶段折成一条分叉的「带」，侧栏迷你轨道画成双线段。
+            alongside: z.array(z.string().min(1).max(64)).min(1).max(32).optional(),
+          })
+          .strict(),
+      )
+      .max(32)
+      .optional(),
+    phaseEdges: z.array(workflowEdgeSchema).max(128).optional(),
+    // 控制流可在其后正常完成的阶段（阶段视图的「阶段 → 返回物」箭头）；组内可为空数组。
+    exits: z.array(z.string().min(1).max(64)).max(32).optional(),
+    sink: z.array(z.string().min(1).max(64)).max(64).optional(),
+    truncated: z.boolean().optional(),
+  })
+  .strict();
+export type ToolCallCreateWorkflowCausalityGraph = z.infer<
+  typeof toolCallCreateWorkflowCausalityGraphSchema
+>;
+
+export const toolCallCreateWorkflowDisplaySchema = z
+  .object({
+    kind: z.literal("create_workflow"),
+    ok: z.boolean(),
+    errorCount: z.number().int().nonnegative(),
+    diagnostics: z
+      .array(
+        z
+          .object({
+            line: z.number().int().nonnegative(),
+            column: z.number().int().nonnegative(),
+            code: z.number().int().nonnegative(),
+            message: z.string().min(1).max(2_048),
+          })
+          .strict(),
+      )
+      .max(100),
+    causalityGraph: toolCallCreateWorkflowCausalityGraphSchema.optional(),
+    truncated: z.boolean().optional(),
+  })
+  .strict();
+export type ToolCallCreateWorkflowDisplay = z.infer<typeof toolCallCreateWorkflowDisplaySchema>;

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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { CuaPermissionKind } from "../cuaAccessibilitySettings.js";
+import { timestampSchema } from "./core.js";
+
+export const cuaRequestAccessStatusSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    platform: z.literal("darwin"),
+    grantOwner: z.string().min(1),
+    accessibility: z.enum(["granted", "stale", "denied"]),
+    screenRecording: z.enum(["granted", "denied", "unknown"]),
+  })
+  .strict();
+export type CuaRequestAccessStatus = z.infer<typeof cuaRequestAccessStatusSchema>;
+
+export function requiredCuaPermissionsForRequestAccessStatus(
+  status: CuaRequestAccessStatus,
+): CuaPermissionKind[] {
+  const required: CuaPermissionKind[] = [];
+  if (status.accessibility === "denied" || status.accessibility === "stale") {
+    required.push("accessibility");
+  }
+  if (status.screenRecording === "denied") {
+    required.push("screen_recording");
+  }
+  return required;
+}
+
+export const cuaPermissionObservationSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    eventId: z.string().min(1),
+    eventSeq: z.number().int().nonnegative(),
+    occurredAt: timestampSchema,
+    sessionId: z.string().min(1),
+    turnId: z.string().min(1).optional(),
+    toolCallId: z.string().min(1),
+    permissionStatus: cuaRequestAccessStatusSchema,
+  })
+  .strict();
+export type CuaPermissionObservation = z.infer<typeof cuaPermissionObservationSchema>;

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

@@ -0,0 +1,147 @@
+// ConversationDelta：七个操作，封闭集合。
+// 没有 row.inserted（中间插入）、没有 row.moved、没有字段级 JSON patch——
+// 凡此模型表达不了的结构变化，服务端一律发 snapshot resync，刻意压缩客户端错误面。
+//
+// 唯一的例外是最后两条 `workflowRun.*`：`workflowRuns` 是一个高频状态键，键级整体替换让
+// 每条引擎事件都要重发整张表（O(N) 字节/事件、O(N²)/run）。它们**只**给这一个键开了一道
+// 按 (runId, siteId, ordinal) 的增量口子，语义仍是「键内整体替换，只是下探了两级」：
+// header 键整键替换、条目整条替换，没有任何字段级深合并。规则在 workflow-runs-delta.ts。
+import { z } from "zod";
+import { streamablePathSchema } from "./core.js";
+import { conversationRowSchema } from "./rows.js";
+import { sharedContextImportStateSchema } from "./shared-context-import.js";
+import {
+  backgroundWorkSummarySchema,
+  commandStateSummarySchema,
+  goalStateSchema,
+  inputRoutingSchema,
+  pendingInteractionSchema,
+  planStateSchema,
+  queueStateSchema,
+  sessionActionAvailabilitySchema,
+  sessionConfigStateSchema,
+  sessionControlSchema,
+  sessionMetaStateSchema,
+  sessionModelTransitionSchema,
+  sessionUsageStateSchema,
+  subagentProjectionStateSchema,
+  workspaceHookAdmissionStateSchema,
+} from "./snapshot.js";
+import {
+  WORKFLOW_RUNS_LIMITS,
+  workflowRunActorSchema,
+  workflowRunNodeSchema,
+  workflowRunSchema,
+  workflowRunsStateSchema,
+} from "./workflow-runs.js";
+
+// StatePatch：键级整体替换（Object.assign），键集合封闭。键内绝不深合并。
+export const statePatchSchema = z.object({
+  revision: z.number().optional(),
+  control: sessionControlSchema.optional(),
+  sharedContextImport: sharedContextImportStateSchema.optional(),
+  availability: sessionActionAvailabilitySchema.optional(),
+  inputRouting: inputRoutingSchema.optional(),
+  meta: sessionMetaStateSchema.optional(),
+  config: sessionConfigStateSchema.optional(),
+  modelTransition: sessionModelTransitionSchema.nullable().optional(),
+  usage: sessionUsageStateSchema.optional(),
+  queue: queueStateSchema.optional(),
+  pendingInteractions: z.array(pendingInteractionSchema).optional(),
+  pendingCommands: z.array(commandStateSummarySchema).optional(),
+  backgroundWorks: z.array(backgroundWorkSummarySchema).optional(),
+  subagents: subagentProjectionStateSchema.optional(),
+  // workflow run 的实时运行态。容器本身不 strict，所以旧桌面收到这个新键只是**剥离一个键**、
+  // 保住 patch 其余全部键——这正是它不需要任何版本偏斜防御的原因。
+  workflowRuns: workflowRunsStateSchema.optional(),
+  goal: goalStateSchema.nullable().optional(),
+  plan: planStateSchema.nullable().optional(),
+  // 软门禁：null = pending 清零(提示条消失);对象 = 待审核状态更新。
+  workspaceHookAdmission: workspaceHookAdmissionStateSchema.nullable().optional(),
+});
+export type StatePatch = z.infer<typeof statePatchSchema>;
+
+/**
+ * run 的 **header** = `workflowRunSchema` 减去 actors / nodes 两张按实例增量同步的表。
+ *
+ * 使用 `.omit` 从同一 schema 派生，避免独立维护的字段表不一致导致订阅解析失败。小集合（reports / artifacts / phases / pendingQuestions…）留在 header 里整键替换——
+ * 它们的上界都是几十条，为它们再开一套增量语法只会多一套能写错的东西。
+ */
+export const workflowRunHeaderSchema = workflowRunSchema.omit({ actors: true, nodes: true });
+export type WorkflowRunHeader = z.infer<typeof workflowRunHeaderSchema>;
+
+/** header 的部分更新：在场的键整键替换，缺席的键保持不动（绝不深合并）。 */
+export const workflowRunHeaderPatchSchema = workflowRunHeaderSchema.partial();
+export type WorkflowRunHeaderPatch = z.infer<typeof workflowRunHeaderPatchSchema>;
+
+/** 变成**缺席**的 header 键。「零条 ⇒ 键缺席」是 reports / pendingQuestions 等键的协议约定，所以增量必须说得出它。 */
+export const workflowRunHeaderKeySchema = workflowRunHeaderSchema.keyof();
+export type WorkflowRunHeaderKey = z.infer<typeof workflowRunHeaderKeySchema>;
+
+/**
+ * 一条被淘汰条目的**身份**（两张表共用的去重键）。从 actor schema 上 `.pick` 而不是手写
+ * 两个字段：这两个字段的界只该有一处定义，理由与 `workflowRunHeaderSchema` 的 `.omit` 逐字相同。
+ *
+ * 刻意**只有身份**：淘汰要说的全部内容就是「这条走了」，带上条目本身只会让消费者以为这是一次
+ * upsert。
+ */
+export const workflowRunEntryRefSchema = workflowRunActorSchema.pick({
+  siteId: true,
+  ordinal: true,
+});
+export type WorkflowRunEntryRef = z.infer<typeof workflowRunEntryRefSchema>;
+
+export const conversationDeltaSchema = z.discriminatedUnion("op", [
+  // 追加到尾部（99%）。
+  z.object({ op: z.literal("row.appended"), row: conversationRowSchema }),
+  // 按 rowId 整行替换（状态机迁移）。
+  z.object({ op: z.literal("row.upserted"), row: conversationRowSchema }),
+  // 删除该行及之后所有（edit/retry 分支）。作用于客户端已加载集合中所有 rowId >= fromRowId 的行。
+  z.object({ op: z.literal("row.removed"), fromRowId: z.number() }),
+  // 流式文本追加。仅允许作用于流式态行（服务端保证，客户端可断言）。
+  z.object({
+    op: z.literal("row.delta"),
+    rowId: z.number(),
+    path: streamablePathSchema,
+    append: z.string(),
+  }),
+  z.object({ op: z.literal("state.updated"), patch: statePatchSchema }),
+  /**
+   * 一条 dwf run 的键级增量。`revision` 是**这次变化之后**的 `workflowRuns.revision`（绝对值）；
+   * 一条引擎事件最多产生一条本 op（节点相位、派生的 actor 状态、用量、水位一起落地，原子）。
+   *
+   * 六个载荷各有各的语义：`run` 按键整体替换、`cleared` 说哪些键变成了缺席、
+   * `removedActors` / `removedNodes` 按 (siteId, ordinal) 删条目、`actors` / `nodes` 按同一个键
+   * 整条 upsert。四张表的界与状态键同值——增量不该能拼出一个非法的状态。
+   *
+   * **施加序是 header → 删除 → upsert**，写在这里也写在字段序上：同一个键在一条 op 里被删又被加
+   * （溢出过的 run 在 resume 时清表重开，或一个条目被淘汰后又回来）必须落在表尾，才与顺序施加
+   * 两条 op 的结果一致。
+   */
+  z.object({
+    op: z.literal("workflowRun.updated"),
+    runId: workflowRunSchema.shape.runId,
+    revision: workflowRunsStateSchema.shape.revision,
+    run: workflowRunHeaderPatchSchema.optional(),
+    cleared: z
+      .array(workflowRunHeaderKeySchema)
+      .max(workflowRunHeaderKeySchema.options.length)
+      .optional(),
+    removedActors: z
+      .array(workflowRunEntryRefSchema)
+      .max(WORKFLOW_RUNS_LIMITS.maxActors)
+      .optional(),
+    removedNodes: z.array(workflowRunEntryRefSchema).max(WORKFLOW_RUNS_LIMITS.maxNodes).optional(),
+    actors: z.array(workflowRunActorSchema).max(WORKFLOW_RUNS_LIMITS.maxActors).optional(),
+    nodes: z.array(workflowRunNodeSchema).max(WORKFLOW_RUNS_LIMITS.maxNodes).optional(),
+  }),
+  /** 这条 run 被生产者淘汰了（只有生产者淘汰，而且必须说出来——客户端永远不自行施加上界）。 */
+  z.object({
+    op: z.literal("workflowRun.removed"),
+    runId: workflowRunSchema.shape.runId,
+    revision: workflowRunsStateSchema.shape.revision,
+  }),
+]);
+export type ConversationDelta = z.infer<typeof conversationDeltaSchema>;
+export type WorkflowRunUpdatedDelta = Extract<ConversationDelta, { op: "workflowRun.updated" }>;
+export type WorkflowRunRemovedDelta = Extract<ConversationDelta, { op: "workflowRun.removed" }>;

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

@@ -0,0 +1,69 @@
+// CLI admission 后的自包含输入事实。
+// queue / guide / runtime / transcript 只能携带同一个 intent，不允许各层重建字段。
+import { z } from "zod";
+import { timestampSchema } from "./core.js";
+import { attachmentRefSchema } from "./attachment-ref.js";
+import { modelSelectionSchema } from "../model-selection.js";
+import { submissionModeSchema } from "./submission.js";
+import { sharedContextRefSchema } from "./shared-context-ref.js";
+
+export const conversationInputDeliverySchema = z
+  .object({
+    requested: z.enum(["auto", "startNow", "queue", "guide"]),
+    admitted: z.enum(["startNow", "queue", "guide"]),
+    fallbackReasonCode: z.string().optional(),
+  })
+  .strict();
+
+export const conversationInputOrderSchema = z
+  .object({
+    admissionSeq: z.number().int().nonnegative(),
+    queuePosition: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+export const conversationInputSteerSchema = z
+  .object({
+    state: z.enum(["notRequested", "submitting", "steering", "guided", "fellBack"]),
+    reasonCode: z.string().optional(),
+  })
+  .strict();
+
+export const conversationInputDispatchSchema = z
+  .object({
+    state: z.enum(["admitted", "queued", "reserved", "promoting", "drained"]),
+    reservationId: z.string().optional(),
+  })
+  .strict();
+
+export const conversationInputIntentSchema = z
+  .object({
+    sourceCommandId: z.string().min(1),
+    queueItemId: z.string().min(1),
+    clientId: z.string().min(1),
+    // compact 是可排队的维护意图；消费时走 compact lifecycle，不投影为 user row。
+    kind: z.enum(["sendText", "sendGoalCommand", "compact"]),
+    text: z.string(),
+    attachments: z.array(attachmentRefSchema).default([]),
+    // optional 只服务旧 snapshot hydration；新 admission 必须填入完整 Submission。
+    modelSelection: modelSelectionSchema.optional(),
+    mode: submissionModeSchema.optional(),
+    planEnabled: z.boolean().optional(),
+    sharedContextRefs: z.array(sharedContextRefSchema).max(1).optional(),
+    delivery: conversationInputDeliverySchema,
+    order: conversationInputOrderSchema,
+    steer: conversationInputSteerSchema,
+    dispatch: conversationInputDispatchSchema,
+    admittedAt: timestampSchema,
+    provenance: z
+      .object({
+        sourceCommandId: z.string().min(1),
+        queueItemId: z.string().min(1).optional(),
+        clientId: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type ConversationInputIntent = z.infer<typeof conversationInputIntentSchema>;