paseo-plugin-zcode-provider 0.3.0 → 0.4.1

package/server/vendor/zcode/packages/shared/src/mcp-apps/contract.ts

@@ -0,0 +1,262 @@
+/**
+ * MCP Apps 协议契约：agent、host、renderer 与 main 共用的常量、工具 UI 元数据类型、沙箱句柄与登记载荷。
+ * 页面 ↔ 宿主的线协议（`ui/*` 方法、握手、版本协商、JSON-RPC）由官方 `@modelcontextprotocol/ext-apps` 定义，
+ * 这里只保留 ZCode 自己的扩展键与限额。只放类型与常量；归一化与 schema 在同目录其他文件，经 index.ts 导出。
+ */
+
+/** MCP 扩展标识（规范「Extension Identifier」）；与官方 SDK `EXTENSION_ID` 一致。 */
+export const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** UI 资源 mimeType（规范 MUST）；与官方 SDK `RESOURCE_MIME_TYPE` 一致。 */
+export const MCP_APPS_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** 弃用的扁平键 `_meta["ui/resourceUri"]`；规范要求宿主 MUST 同时兼容，与官方 SDK `RESOURCE_URI_META_KEY` 一致。 */
+export const MCP_APPS_LEGACY_RESOURCE_URI_META_KEY = "ui/resourceUri";
+
+/**
+ * MCP client `initialize` 里的 ui 扩展能力声明（规范「Client (Host) Capabilities」）。
+ * 用 type 而不是 interface：MCP SDK 的 `ClientCapabilities.extensions` 要求值带字符串索引签名。
+ */
+export type McpAppsClientCapability = { mimeTypes: string[] };
+/** agent 对每个 MCP server 宣告的能力片段；放进 `Client` 构造参数的 `capabilities.extensions`。 */
+export function buildMcpAppsClientCapabilities(): {
+  extensions: { [extensionId: string]: McpAppsClientCapability };
+} {
+  return { extensions: { [MCP_APPS_EXTENSION_ID]: { mimeTypes: [MCP_APPS_RESOURCE_MIME_TYPE] } } };
+}
+
+/** 宿主 hostInfo.name；hostInfo.version 只供页面 feature detect，与应用版本无关。 */
+export const MCP_APPS_HOST_NAME = "zcode";
+export const MCP_APPS_HOST_VERSION = "1";
+/** `ui/initialize` 握手超时（端口到达起算）与卸载前 `ui/resource-teardown` 的等待上限。 */
+export const MCP_APPS_HANDSHAKE_TIMEOUT_MS = 15_000;
+export const MCP_APPS_TEARDOWN_TIMEOUT_MS = 500;
+
+export type McpAppsDisplayMode = "inline" | "fullscreen" | "pip";
+export type McpAppsToolVisibility = "model" | "app";
+export const MCP_APPS_DEFAULT_TOOL_VISIBILITY: readonly McpAppsToolVisibility[] = ["model", "app"];
+
+/** MCP Apps 资源级 CSP（`McpUiResourceCsp`）：四类域。资源 `_meta` 为主，工具级 `_meta.ui.csp` 只在资源没有声明时兜底。 */
+export interface McpToolUiCsp {
+  connectDomains?: string[];
+  resourceDomains?: string[];
+  frameDomains?: string[];
+  baseUriDomains?: string[];
+}
+
+/**
+ * 资源级 `_meta["zcode/csp"]`：宿主缺省按规范块（只有 'self' 'unsafe-inline'），不放行 `'unsafe-eval'` /
+ * `'wasm-unsafe-eval'`；需要 eval / WebAssembly 的资源在这里显式声明。宿主经
+ * `hostCapabilities.experimental["zcode/csp"].flags` 宣告支持的键。
+ */
+export const MCP_APPS_CSP_RELAXATION_META_KEY = "zcode/csp";
+export const MCP_APPS_CSP_RELAXATION_FLAGS = ["unsafeEval", "wasmUnsafeEval"] as const;
+export type McpAppCspRelaxationFlag = (typeof MCP_APPS_CSP_RELAXATION_FLAGS)[number];
+export type McpAppCspRelaxations = Partial<Record<McpAppCspRelaxationFlag, boolean>>;
+export function buildMcpAppsCspExperimentalCapability(): {
+  [MCP_APPS_CSP_RELAXATION_META_KEY]: { flags: McpAppCspRelaxationFlag[] };
+} {
+  return { [MCP_APPS_CSP_RELAXATION_META_KEY]: { flags: [...MCP_APPS_CSP_RELAXATION_FLAGS] } };
+}
+
+/**
+ * 资源可声明的浏览器权限（规范草案 `UIResourceMeta.permissions` 的四键），顺序即归一化顺序。
+ * 宿主：未声明一律拒绝；camera / microphone / geolocation 首次使用时原生弹框确认，clipboardWrite 按声明放行。
+ */
+export const MCP_APPS_RESOURCE_PERMISSIONS = [
+  "camera",
+  "microphone",
+  "geolocation",
+  "clipboardWrite",
+] as const;
+export type McpAppsResourcePermission = (typeof MCP_APPS_RESOURCE_PERMISSIONS)[number];
+/** 规范权限键 → 插件 iframe `allow` 的 Permissions Policy 特性名。 */
+export const MCP_APPS_IFRAME_ALLOW_TOKENS: Record<McpAppsResourcePermission, string> = {
+  camera: "camera",
+  microphone: "microphone",
+  geolocation: "geolocation",
+  clipboardWrite: "clipboard-write",
+};
+/** 与官方 SDK `buildAllowAttribute` 同形：`"camera; clipboard-write"`；没有声明返回空串。 */
+export function buildMcpAppsIframeAllow(
+  permissions: readonly McpAppsResourcePermission[] | undefined,
+): string {
+  if (!permissions?.length) return "";
+  return MCP_APPS_RESOURCE_PERMISSIONS.filter((key) => permissions.includes(key))
+    .map((key) => MCP_APPS_IFRAME_ALLOW_TOKENS[key])
+    .join("; ");
+}
+
+/**
+ * `ui://` HTML 资源自己的 `_meta`（`resources/read` 内容项优先）。`heightHint` / `minFrameHeight` 是初始高度与
+ * 最小高度（px）；`showInline` 为 true 时卡片强制常驻、不进折叠区。
+ */
+export interface McpAppResourceMeta {
+  csp?: McpToolUiCsp;
+  cspRelaxations?: McpAppCspRelaxations;
+  /** `_meta.ui.permissions` 声明的浏览器权限（规范四键；顺序固定、去重）。 */
+  permissions?: McpAppsResourcePermission[];
+  prefersBorder?: boolean;
+  heightHint?: number;
+  minFrameHeight?: number;
+  showInline?: boolean;
+}
+/** 随沙箱句柄回到 renderer 的资源级呈现信息；CSP 与放宽只在 main 生效，不回传。 */
+export type PluginSandboxResourceMeta = Omit<McpAppResourceMeta, "csp" | "cspRelaxations">;
+/** 工具 `_meta` 归一化后的 UI 描述；`resourceUri` 非法时整个描述不存在。 */
+export interface McpToolUiDescriptor {
+  resourceUri: string;
+  visibility?: McpAppsToolVisibility[];
+  preferredDisplayMode?: McpAppsDisplayMode;
+  csp?: McpToolUiCsp;
+  prefersBorder?: boolean;
+  /** 工具结果归属的面板 id（清单 `ui.surfaces[].id`）。 */
+  surface?: string;
+  /** 工具级 `openai/widgetShowCodexWidgetInline`，卡片强制常驻。 */
+  showInline?: boolean;
+}
+
+/** `_meta.ui.surface` / 清单 surface id 的长度与字符集（与 sandboxId 同源：可进 CSP host-source）。 */
+export const MCP_APPS_SURFACE_ID_MAX_CHARS = 128;
+export const MCP_APPS_SURFACE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+
+export const MCP_APPS_UI_RESOURCE_SCHEME = "ui://";
+export const MCP_APPS_RESOURCE_URI_MAX_CHARS = 2048;
+/**
+ * `display.ui.structuredContent` / `widgetMeta` / `content` 的持久化上限（JSON 文本的 UTF-8 字节）。
+ * 超限不截断字符串（半截 JSON 没有意义）：字段整个省略，`truncated: true` 且 `truncatedBytes` 记被丢弃的字节数；
+ * 页面侧 `toolOutput` 为 null、`toolResponseMetadata["zcode/truncated"] = { bytes }`，可用 tools/call 重取。
+ */
+export const MCP_APPS_STRUCTURED_CONTENT_MAX_BYTES = 64 * 1024;
+export const MCP_APPS_WIDGET_META_MAX_BYTES = 16 * 1024;
+export const MCP_APPS_CONTENT_MAX_BYTES = 32 * 1024;
+export const MCP_APPS_TRUNCATED_META_KEY = "zcode/truncated";
+/** host 侧接受的 `ui://` HTML 上限与 mimeType 白名单（规范只认带 profile 的；无 profile 的 text/html 是有意的宽松超集）。 */
+// 官方 pdf-server 示例的单文件页面（内联 pdf.js）就有 4.3 MB，4 MiB 会把它拒掉；放到 16 MiB。
+export const MCP_APPS_HTML_MAX_BYTES = 16 * 1024 * 1024;
+export const MCP_APPS_HTML_MIME_TYPES = [MCP_APPS_RESOURCE_MIME_TYPE, "text/html"] as const;
+/**
+ * 页面经 ui/update-model-context 与 ui/message 送来的 image 块：白名单三种位图，单张解码后 ≤ 4 MiB；
+ * 不在白名单或超限整个请求 -32602 `unsupported_content`。
+ */
+export const MCP_APPS_IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/webp"] as const;
+export const MCP_APPS_IMAGE_MAX_BYTES = 4 * 1024 * 1024;
+export {
+  MCP_APPS_UI_READ_RESOURCE_MAX_BYTES,
+  MCP_APPS_UI_READ_RESOURCE_MIME_ALLOWLIST,
+  isMcpAppsUiReadResourceMimeAllowed,
+} from "./resourceMime.js";
+
+/**
+ * `hostCapabilities.experimental` 里 ZCode 扩展的键。官方 SDK 的 zod 会剥掉标准位之外的未知能力键，
+ * 扩展一律放 experimental（规范预留位），页面按键 feature detect。
+ */
+export const MCP_APPS_WIDGET_STATE_EXPERIMENTAL_KEY = "zcode/widgetState";
+export const MCP_APPS_RESOURCE_SUBSCRIBE_EXPERIMENTAL_KEY = "zcode/resourceSubscribe";
+export const MCP_APPS_SURFACE_EXPERIMENTAL_KEY = "zcode/surface";
+/**
+ * ZCode 扩展方法 `ui/set-widget-state { widgetState }`（MCP Apps 无 widgetState）：页面把界面状态交给宿主
+ * renderer 内存保存（不持久化，会话内重挂载可恢复）；初值经 hostContext 的 `zcode/widgetState` 键随握手下发。
+ */
+export const MCP_APPS_SET_WIDGET_STATE_METHOD = "ui/set-widget-state";
+export const MCP_APPS_WIDGET_STATE_CONTEXT_KEY = "zcode/widgetState";
+
+/** 宿主 renderer ↔ relay shell 之间唯一一条 MessageChannel 的名字；上面跑原始 JSON-RPC（官方 AppBridge / App）。 */
+export const PLUGIN_SANDBOX_PORT_NAME = "plugin-sandbox-rpc";
+
+/** MessagePort 的最小结构类型；宿主 renderer 的 Transport 与 relay shell 都只依赖这几个成员。 */
+export interface PluginSandboxTransportPort {
+  postMessage(message: unknown): void;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  start?(): void;
+  close(): void;
+}
+
+/** main → 宿主 renderer 的端口事件（经 preload `window.postMessage` transfer）。 */
+export interface PluginSandboxPortsEvent {
+  sandboxId: string;
+  initId: number;
+  port: PluginSandboxTransportPort;
+}
+/**
+ * renderer 可用的沙箱平台端口，以 `IPlatformService.pluginSandbox` 可选字段挂载；web 端为 undefined，UI 据此回退。
+ * 登记沙箱不在这里：它由 host 经 parentPort 完成，renderer 只拿句柄。
+ */
+export interface PluginSandboxPlatformPort {
+  /** preload 已安装限定的沙箱原子移动适配。 */
+  supportsRetainedMove?: boolean;
+  /** 仅宿主操作可用；Main 校验 owner/代次后复制当前页面内容。 */
+  copyImage?(input: PluginSandboxCaptureRequest): Promise<void>;
+  /** 只为指定代际的 MCP guest 保持可逆后台执行；不改变窗口或其他页面的节流。 */
+  setExecutionActive?(sandboxId: string, initId: number, active: boolean): Promise<void>;
+  /** 宿主窗口 webContents id；prepareSandbox 用它作为 owner，main 在 will-attach 时校验。 */
+  getOwnerWebContentsId(): Promise<number>;
+  /**
+   * 释放沙箱。带 initId 时只释放捕获的登记：新页面使用新 Agent 凭证和 sandboxId，
+   * 两条 IPC 路径不同（host parentPort vs ipcMain），旧 dispose 到得晚也不能误杀新登记。
+   */
+  disposeSandbox(sandboxId: string, initId?: number): Promise<void>;
+  consumeUserGesture(sandboxId: string): Promise<boolean>;
+  onPorts(handler: (event: PluginSandboxPortsEvent) => void): () => void;
+}
+
+export interface PluginSandboxCaptureRequest {
+  sandboxId: string;
+  initId: number;
+  captureRect: { x: number; y: number; width: number; height: number };
+  viewportSize: { width: number; height: number };
+}
+
+/**
+ * 沙箱作用域。工具卡片按 toolCallId，面板（清单 `ui.surfaces[]`）按 surfaceId；
+ * 两者都映射到一个字符串 scopeId 进注册表幂等键与 widgetState 路由，避免 main / host 认识"面板"概念。
+ */
+export type PluginUiScopeRef =
+  | { kind: "toolCall"; toolCallId: string }
+  | { kind: "surface"; surfaceId: string };
+export function buildPluginSandboxScopeId(scope: PluginUiScopeRef): string {
+  return scope.kind === "toolCall" ? `tool:${scope.toolCallId}` : `surface:${scope.surfaceId}`;
+}
+
+/** host → main 登记沙箱内容的消息载荷（模式同 LocalMediaPreviewPathAuthorize*）。 */
+export interface PluginSandboxRegisterRequestPayload {
+  instance: import("./instance.js").McpAppInstance;
+  requestId: string;
+  /** 工作区隔离；旧调用允许缺省，新宿主登记须贯穿实际 workspace 范围。 */
+  workspacePath?: string;
+  workspaceIdentity?: string;
+  ownerWebContentsId: number;
+  sessionId: string;
+  /** Gen UI has Host provenance and never impersonates an MCP plugin. */
+  contentKind?: "gen-ui";
+  pluginId?: string;
+  /** 资源所属的 MCP server 运行时名；沙箱 partition 按它派生（同一 server 的页面共享一份持久存储）。 */
+  serverName?: string;
+  /** `buildPluginSandboxScopeId` 的结果：`tool:<toolCallId>` 或 `surface:<surfaceId>`。 */
+  scopeId: string;
+  html: string;
+  /** 有效 CSP：资源级优先，工具级兜底（host plugin-ui-bridge 已合并）。 */
+  csp?: McpToolUiCsp;
+  /** 资源级 `_meta["zcode/csp"]` 声明的放宽项。 */
+  cspRelaxations?: McpAppCspRelaxations;
+  /** 资源声明的浏览器权限；main 据此放宽 Permissions-Policy 与 iframe allow，并把权限请求交给闸门。 */
+  permissions?: McpAppsResourcePermission[];
+  prefersBorder?: boolean;
+  /** 资源级尺寸提示，原样进句柄回给 renderer。 */
+  heightHint?: number;
+  minFrameHeight?: number;
+  /** 资源级强制常驻标记，随句柄 resourceMeta 回 renderer。 */
+  showInline?: boolean;
+}
+/** host 内部使用的登记输入：去掉传输层 requestId。 */
+export type PluginSandboxRegisterInput = Omit<PluginSandboxRegisterRequestPayload, "requestId">;
+export interface PluginSandboxHandle {
+  instance: import("./instance.js").McpAppInstance;
+  sandboxId: string;
+  initId: number;
+  shellUrl: string;
+  partition: string;
+  /** 资源级呈现信息（prefersBorder / heightHint / minFrameHeight / showInline）；资源没声明时省略。 */
+  resourceMeta?: PluginSandboxResourceMeta;
+}
+export type PluginSandboxRegisterResultPayload =
+  | ({ requestId: string; ok: true } & PluginSandboxHandle)
+  | { requestId: string; ok: false; error: string };

package/server/vendor/zcode/packages/shared/src/mcp-apps/instance.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+/** Agent 签发的内存凭证；Main 的 initId 只用于端口握手。 */
+export const mcpAppInstanceSchema = z
+  .object({
+    runtimeId: z.string().min(1),
+    generation: z.number().int().positive(),
+    appIdentity: z.string().regex(/^[a-f0-9]{64}$/),
+    token: z.string().min(1),
+  })
+  .strict();
+export type McpAppInstance = z.infer<typeof mcpAppInstanceSchema>;

package/server/vendor/zcode/packages/shared/src/mcp-apps/resourceMime.ts

@@ -0,0 +1,73 @@
+/**
+ * 页面发起的 `resources/read`（`mcp/uiReadResource`）单次结果总大小上限，以及 mimeType 白名单。
+ * 白名单项以 `/` 结尾表示前缀匹配（如 `text/`），否则精确匹配（忽略参数与大小写）。
+ */
+export const MCP_APPS_UI_READ_RESOURCE_MAX_BYTES = 8 * 1024 * 1024;
+// 原列表遗漏 PDF 等常见资源，导致插件已握手却读不到文件；按明确 MIME 扩展，保留未知类型拒绝规则。
+export const MCP_APPS_UI_READ_RESOURCE_MIME_ALLOWLIST: readonly string[] = [
+  "text/",
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "application/x-yaml",
+  // 文档与办公文件。
+  "application/pdf",
+  "application/rtf",
+  "application/msword",
+  "application/vnd.ms-excel",
+  "application/vnd.ms-powerpoint",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  "application/vnd.oasis.opendocument.text",
+  "application/vnd.oasis.opendocument.spreadsheet",
+  "application/vnd.oasis.opendocument.presentation",
+  // 图片。
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/svg+xml",
+  "image/gif",
+  "image/avif",
+  "image/bmp",
+  "image/tiff",
+  "image/x-icon",
+  "image/vnd.microsoft.icon",
+  "image/heic",
+  "image/heif",
+  // 音视频。
+  "audio/mpeg",
+  "audio/mp4",
+  "audio/ogg",
+  "audio/wav",
+  "audio/x-wav",
+  "audio/webm",
+  "audio/aac",
+  "audio/flac",
+  "video/mp4",
+  "video/webm",
+  "video/ogg",
+  "video/quicktime",
+  "video/mpeg",
+  // 归档、字体与模型只传输内容，由插件决定如何使用。
+  "application/zip",
+  "application/gzip",
+  "application/x-gzip",
+  "application/x-tar",
+  "application/x-7z-compressed",
+  "application/vnd.rar",
+  "font/woff",
+  "font/woff2",
+  "font/ttf",
+  "font/otf",
+  "model/gltf+json",
+  "model/gltf-binary",
+  "application/octet-stream",
+];
+export function isMcpAppsUiReadResourceMimeAllowed(mimeType: string): boolean {
+  const essence = mimeType.split(";")[0]!.trim().toLowerCase();
+  if (!essence) return false;
+  return MCP_APPS_UI_READ_RESOURCE_MIME_ALLOWLIST.some((entry) =>
+    entry.endsWith("/") ? essence.startsWith(entry) : essence === entry,
+  );
+}

package/server/vendor/zcode/packages/shared/src/mcp-apps/sampling.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { MCP_APPS_IMAGE_MAX_BYTES, MCP_APPS_IMAGE_MIME_TYPES } from "./contract.js";
+
+export const MCP_APPS_SAMPLING_TIMEOUT_MS = 60_000;
+export const MCP_APPS_SAMPLING_TRANSPORT_TIMEOUT_MS = 65_000;
+export const MCP_APPS_SAMPLING_MAX_BYTES = 8 * 1024 * 1024;
+export const MCP_APPS_SAMPLING_MAX_BLOCKS = 64;
+export const MCP_APPS_SAMPLING_MAX_PER_SESSION = 4;
+export const MCP_APPS_SAMPLING_MAX_PER_AGENT = 8;
+export const MCP_APPS_SAMPLING_MAX_OPERATIONS = 4096;
+const utf8Bytes = (text: string) => new TextEncoder().encode(text).byteLength;
+const annotations = z
+  .object({
+    audience: z.array(z.enum(["user", "assistant"])).optional(),
+    priority: z.number().min(0).max(1).optional(),
+    lastModified: z.string().optional(),
+  })
+  .strict()
+  .optional();
+const samplingBlockSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("text"),
+      text: z.string().max(MCP_APPS_SAMPLING_MAX_BYTES),
+      annotations,
+      _meta: z.record(z.string(), z.unknown()).optional(),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("image"),
+      mimeType: z.enum(MCP_APPS_IMAGE_MIME_TYPES),
+      data: z
+        .string()
+        .min(1)
+        .max(Math.ceil(MCP_APPS_IMAGE_MAX_BYTES / 3) * 4)
+        // 重复四字符分组会在 MiB 级图片上耗尽 V8 正则栈；平坦字符检查保持线性。
+        .refine((data) => data.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(data))
+        .refine((data) => decodedBytes(data) <= MCP_APPS_IMAGE_MAX_BYTES),
+      annotations,
+      _meta: z.record(z.string(), z.unknown()).optional(),
+    })
+    .strict(),
+]);
+const priority = z.number().min(0).max(1).optional();
+/** 只开放宿主确实实现的官方子集；不静默剥除 tools/audio/模型配置等字段。 */
+export const mcpAppsSamplingParamsSchema = z
+  .object({
+    messages: z
+      .array(
+        z
+          .object({
+            role: z.enum(["user", "assistant"]),
+            content: z.union([
+              samplingBlockSchema,
+              z.array(samplingBlockSchema).min(1).max(MCP_APPS_SAMPLING_MAX_BLOCKS),
+            ]),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(MCP_APPS_SAMPLING_MAX_BLOCKS),
+    systemPrompt: z.string().max(MCP_APPS_SAMPLING_MAX_BYTES).optional(),
+    maxTokens: z.number().int().positive().safe(),
+    includeContext: z.literal("none").optional(),
+    modelPreferences: z
+      .object({
+        hints: z
+          .array(z.object({ name: z.string().max(256).optional() }).strict())
+          .max(16)
+          .optional(),
+        costPriority: priority,
+        speedPriority: priority,
+        intelligencePriority: priority,
+      })
+      .strict()
+      .optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    _meta: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+  .superRefine((params, ctx) => {
+    const blocks = params.messages.flatMap((message) =>
+      Array.isArray(message.content) ? message.content : [message.content],
+    );
+    let bytes = utf8Bytes(params.systemPrompt ?? "");
+    for (const block of blocks)
+      bytes += block.type === "image" ? decodedBytes(block.data) : utf8Bytes(block.text);
+    // metadata 不转发给 provider，但仍计入边界预算，避免任意扩展字段绕过载荷限制。
+    const metadataBytes = utf8Bytes(
+      JSON.stringify({
+        metadata: params.metadata,
+        _meta: params._meta,
+        blockMetadata: blocks.map((b) => ({ _meta: b._meta, annotations: b.annotations })),
+      }),
+    );
+    if (
+      blocks.length > MCP_APPS_SAMPLING_MAX_BLOCKS ||
+      bytes + metadataBytes > MCP_APPS_SAMPLING_MAX_BYTES
+    )
+      ctx.addIssue({ code: "custom", message: "Sampling content exceeds host limits" });
+  });
+function decodedBytes(data: string): number {
+  return (data.length * 3) / 4 - (data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
+}
+export const mcpAppsSamplingResultSchema = z
+  .object({
+    role: z.literal("assistant"),
+    model: z.string().min(1),
+    content: z
+      .object({ type: z.literal("text"), text: z.string().max(MCP_APPS_SAMPLING_MAX_BYTES) })
+      .strict(),
+    stopReason: z.string().min(1),
+  })
+  .strict();
+export type McpAppsSamplingParams = z.infer<typeof mcpAppsSamplingParamsSchema>;
+export type McpAppsSamplingResult = z.infer<typeof mcpAppsSamplingResultSchema>;

package/server/vendor/zcode/packages/shared/src/mcp-apps/schemas.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import {
+  MCP_APPS_RESOURCE_URI_MAX_CHARS,
+  MCP_APPS_CONTENT_MAX_BYTES,
+  MCP_APPS_STRUCTURED_CONTENT_MAX_BYTES,
+  MCP_APPS_SURFACE_ID_MAX_CHARS,
+  MCP_APPS_SURFACE_ID_PATTERN,
+  MCP_APPS_WIDGET_META_MAX_BYTES,
+} from "./contract.js";
+
+/**
+ * 以下 schema 是 mcp-apps-protocol 的运行时校验面：只覆盖 ZCode 自己的投影 / 元数据形状。
+ * 页面 ↔ 宿主的 `ui/*` 参数由官方 SDK（`McpUi*Schema`）校验，这里不重复。类型见 contract.ts。
+ */
+
+export const mcpAppsDisplayModeSchema = z.enum(["inline", "fullscreen", "pip"]);
+export const mcpAppsToolVisibilitySchema = z.enum(["model", "app"]);
+/** 面板 id。 */
+export const mcpAppsSurfaceIdSchema = z
+  .string()
+  .min(1)
+  .max(MCP_APPS_SURFACE_ID_MAX_CHARS)
+  .regex(MCP_APPS_SURFACE_ID_PATTERN);
+
+export const mcpToolUiCspSchema = z
+  .object({
+    connectDomains: z.array(z.string().min(1).max(512)).optional(),
+    resourceDomains: z.array(z.string().min(1).max(512)).optional(),
+    frameDomains: z.array(z.string().min(1).max(512)).optional(),
+    baseUriDomains: z.array(z.string().min(1).max(512)).optional(),
+  })
+  .strict();
+
+/** 资源级 `_meta["zcode/csp"]` 归一化后的形状（只有为 true 的键）。 */
+export const mcpAppCspRelaxationsSchema = z
+  .object({ unsafeEval: z.boolean().optional(), wasmUnsafeEval: z.boolean().optional() })
+  .strict();
+
+export const mcpToolUiDescriptorSchema = z
+  .object({
+    resourceUri: z.string().min(1).max(MCP_APPS_RESOURCE_URI_MAX_CHARS),
+    visibility: z.array(mcpAppsToolVisibilitySchema).optional(),
+    preferredDisplayMode: mcpAppsDisplayModeSchema.optional(),
+    csp: mcpToolUiCspSchema.optional(),
+    prefersBorder: z.boolean().optional(),
+    surface: mcpAppsSurfaceIdSchema.optional(),
+    showInline: z.boolean().optional(),
+  })
+  .strict();
+
+/**
+ * `display.ui`：agent 投影到 ToolCallRow.display 的插件 UI 元数据。
+ * contracts 与 zcode-protocol-v4 两处 strict schema 都从这里复用，避免三份手写不同步。
+ */
+export const mcpToolDisplayUiSchema = z
+  .object({
+    pluginId: z.string().min(1).max(256),
+    resourceUri: z.string().min(1).max(MCP_APPS_RESOURCE_URI_MAX_CHARS),
+    preferredDisplayMode: mcpAppsDisplayModeSchema.optional(),
+    prefersBorder: z.boolean().optional(),
+    csp: mcpToolUiCspSchema.optional(),
+    // 上限按 UTF-8 字节由 agent 侧保证；这里的 max 按字符数只是兜底（字符数 ≤ 字节数）。
+    structuredContent: z.string().max(MCP_APPS_STRUCTURED_CONTENT_MAX_BYTES).optional(),
+    widgetMeta: z.string().max(MCP_APPS_WIDGET_META_MAX_BYTES).optional(),
+    /** 原始 `content` 数组的 JSON 文本（≤ 32 KiB），页面 tool-result 用它而不是拼接的纯文本。 */
+    content: z.string().max(MCP_APPS_CONTENT_MAX_BYTES).optional(),
+    truncated: z.boolean().optional(),
+    /** 被省略字段的 UTF-8 字节数之和。 */
+    truncatedBytes: z.number().int().nonnegative().optional(),
+    /** MCP 结果 `isError: true`（调用本身完成、工具报错）；页面 tool-result 带 isError，面板不用它覆盖上一份成功快照。 */
+    isError: z.literal(true).optional(),
+    /** 工具级强制常驻（`openai/widgetShowCodexWidgetInline`），卡片不进折叠区。 */
+    showInline: z.literal(true).optional(),
+    // 所属面板；contracts 侧 mcpToolDisplayUiPayloadSchema 同步。
+    surface: mcpAppsSurfaceIdSchema.optional(),
+  })
+  .strict();
+export type McpToolDisplayUi = z.infer<typeof mcpToolDisplayUiSchema>;
+
+/** 当前执行的成功 UI 工具结果；独立于 conversation 订阅，不用于历史回放。 */
+export const pluginUiToolResultNotificationSchema = z
+  .object({
+    sessionId: z.string().min(1),
+    toolCallId: z.string().min(1),
+    serverName: z.string().min(1),
+    ui: mcpToolDisplayUiSchema.refine((ui) => !ui.isError),
+    input: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+export type PluginUiToolResultNotification = z.infer<typeof pluginUiToolResultNotificationSchema>;

package/server/vendor/zcode/packages/shared/src/model-execution.ts

@@ -1,13 +1,37 @@
 import { z } from "zod";
+import { modelSelectionSchema } from "./model-selection.js";
+
+/**
+ * 执行 Selection 退回 Session Selection 的原因。由发起方在 selectionFallback 规则里声明，
+ * CLI 只透传命中规则的原因，不自行解释 provider 错误码。
+ */
+export const modelExecutionSelectionFallbackReasonSchema = z.enum([
+  "highspeed_card_expired",
+  "highspeed_request_failed",
+  "highspeed_selection_unavailable",
+]);
 
 /** 文本与附件发送共用执行约束，凭据只属于单次执行，不进入 Session 配置。 */
 export const modelExecutionSchema = z
   .object({
     memoryExtraction: z.literal("skip").optional(),
     selectionScope: z.literal("execution"),
+    offPeak: z
+      .object({
+        executionId: z.string().min(1),
+        ticketId: z.string().min(1),
+        providerErrorCode: z.string().min(1),
+      })
+      .strict()
+      .optional(),
     requestAuth: z
       .object({
         apiKey: z.string().min(1).optional(),
+        apiKeyId: z.string().trim().min(1).optional(),
+        accountScope: z
+          .string()
+          .regex(/^[a-f0-9]{64}$/)
+          .optional(),
         headers: z.record(z.string().min(1), z.string().min(1)).optional(),
       })
       .strict()
@@ -15,9 +39,42 @@ export const modelExecutionSchema = z
     subagents: z
       .object({
         foregroundModel: z.literal("submission"),
-        background: z.literal("deny"),
+        background: z.enum(["deny", "allow"]),
+      })
+      .strict()
+      .optional(),
+    /**
+     * 本次执行的 Selection 失败时，同一 Turn 内退回原模型继续跑完，而不是让整轮失败。
+     * 触发条件由发起方声明：`providerId` 限定只匹配本轮 execution Selection 指向的 provider；
+     * `rules` 按声明顺序匹配，首个命中的规则决定退回原因，`providerErrorCode` 缺省表示该 provider
+     * 的任何失败（用户取消与上下文超窗除外）。CLI 不按 provider id 前缀、模型名或错误文案硬编码。
+     * 退回目标先取 `target`（发起方抽卡时的提交选择，即会话原模型），再取本轮接纳前复制的 runtime 会话常驻 Selection：
+     * 接纳用户消息时绑定普通提交选择，但常驻选择只在 runtime 内存里，冷恢复竞态下可能未绑定，
+     * 所以发起方必须声明 `target`（docs/highspeed/highspeed-card-spec.md §2.2）。
+     */
+    selectionFallback: z
+      .object({
+        providerId: z.string().min(1),
+        rules: z
+          .array(
+            z
+              .object({
+                reason: modelExecutionSelectionFallbackReasonSchema,
+                providerErrorCode: z.string().min(1).optional(),
+              })
+              .strict(),
+          )
+          .min(1),
+        target: modelSelectionSchema.optional(),
       })
       .strict()
       .optional(),
   })
   .strict();
+
+export type ModelExecution = z.infer<typeof modelExecutionSchema>;
+export type ModelExecutionSelectionFallback = NonNullable<ModelExecution["selectionFallback"]>;
+export type ModelExecutionSelectionFallbackRule = ModelExecutionSelectionFallback["rules"][number];
+export type ModelExecutionSelectionFallbackReason = z.infer<
+  typeof modelExecutionSelectionFallbackReasonSchema
+>;

package/server/vendor/zcode/packages/shared/src/oauth.ts

@@ -149,6 +149,9 @@ export type OAuthCachedSessionRestoreResult =
   | { status: "signed-out" }
   | { status: "reauthentication-required"; reason: "jwt-expired" };
 
+/** OAuth owner 已完成会话凭据变更；不携带用户资料或 token。 */
+export type OAuthSessionState = "signed-in" | "signed-out";
+
 /** Host 在检测到 ZCode JWT 失效后通知 Renderer 展示确认并重启。 */
 export const ZCODE_JWT_INVALID_BROADCAST_CHANNEL = "auth:zcode-jwt-invalid";