paseo-plugin-zcode-provider 0.3.0 → 0.4.0

package/server/vendor/zcode/packages/shared/src/dynamic-workflow-feature.ts

@@ -0,0 +1,137 @@
+// ============================================================
+// Dynamic Workflow 灰度：服务端 feature key 的取值域与客户端快照
+// ============================================================
+// 服务端 `/api/v1/client/configs` 下发 `data.configs.dynamicWorkflow.mode`。
+
+// 这里只放三端（Host services、Desktop main、UI）共用的取值域、归一化与快照形状；
+// 读取远端、覆盖与下发都在各自的 owner 里，不在 shared 层发请求。
+
+export const DYNAMIC_WORKFLOW_MODES = ["disabled", "onDemand", "alwaysOn"] as const;
+export type DynamicWorkflowMode = (typeof DYNAMIC_WORKFLOW_MODES)[number];
+
+/**
+ * 本地覆盖用的环境变量。语义按构建档位分三层，由 Desktop main 在 fork Host 前**改写或删除**
+ * （desktopRuntimeEnv.ts 的 buildHostProcessEnv），Host 只消费不再分辨来源：
+ *   - 未打包 dev：透传开发者 shell 里的合法取值；
+ *   - 打包 preview：固定写入 `alwaysOn`，忽略 shell；
+ *   - 打包 production：删除继承值，永不写入。
+ * 没有 main 的 Web/server Host 直接读进程环境（运维/开发者设置）。
+ */
+export const ZCODE_DYNAMIC_WORKFLOW_MODE_ENV = "ZCODE_DYNAMIC_WORKFLOW_MODE";
+
+/** 服务端缺省、格式非法或请求失败时的取值：fail-closed，与闲时任务灰度一致。 */
+export const DEFAULT_DYNAMIC_WORKFLOW_MODE: DynamicWorkflowMode = "disabled";
+
+export function normalizeDynamicWorkflowMode(value: unknown): DynamicWorkflowMode | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return (DYNAMIC_WORKFLOW_MODES as readonly string[]).includes(trimmed)
+    ? (trimmed as DynamicWorkflowMode)
+    : undefined;
+}
+
+/**
+ * 「功能是否提供」的折叠：`onDemand` 与 `alwaysOn` 同为开启——目录里的 `/workflow`、技能、
+ * 自动化页的工作流 tab 与 Resume 入口在两种模式下都在。两者的差别只在模型工具面的注册时机
+ * （launch.md「On demand: activation」），由 CLI 侧按 mode 本身裁决，这里不参与。
+ */
+export function isDynamicWorkflowModeEnabled(mode: DynamicWorkflowMode): boolean {
+  return mode !== "disabled";
+}
+
+/** 快照的来源：观测用，UI 与日志据此区分「服务端关」与「本地覆盖」。只描述「提供」来自哪里。 */
+export type DynamicWorkflowClientConfigSource = "remote" | "override" | "default";
+
+/**
+ * 灰度快照（launch.md「Gray release」「The user's choice」）。两层：
+ *   - 提供（offer）：服务端 key 或本地覆盖决定默认是哪个模式，记在 `offeredMode`（disabled 也只是默认值）；
+ *   - 生效（effective）：用户在设置里的明确选择永远取代提供的模式，记在 `mode` / `enabled`。
+ * 旧消费者读 `mode` / `enabled` 即得生效值；设置页读 `offeredMode` 决定「默认」标签。
+ */
+export interface DynamicWorkflowClientConfig {
+  /** 生效模式：用户有选择时是用户选择，否则等于 offeredMode。 */
+  readonly mode: DynamicWorkflowMode;
+  /** 等于 isDynamicWorkflowModeEnabled(mode)；单独落字段免得每个消费者各写一遍折叠规则。 */
+  readonly enabled: boolean;
+  readonly source: DynamicWorkflowClientConfigSource;
+  /** 服务端（或本地覆盖）提供的模式：用户没选时的生效模式，也是设置页的「默认」选项。 */
+  readonly offeredMode: DynamicWorkflowMode;
+  /** 实际生效的用户选择；缺席表示跟随提供的模式（未选择或非法值）。 */
+  readonly userMode?: DynamicWorkflowMode;
+}
+
+export function createDynamicWorkflowClientConfig(
+  offeredMode: DynamicWorkflowMode,
+  source: DynamicWorkflowClientConfigSource,
+): DynamicWorkflowClientConfig {
+  return {
+    mode: offeredMode,
+    enabled: isDynamicWorkflowModeEnabled(offeredMode),
+    source,
+    offeredMode,
+  };
+}
+
+/**
+ * 读快照里服务端提供的默认模式（与用户选择无关）；设置行与中枢的「工作流设置」只在读得到时出现。
+ * disabled 也是合法的默认值：此时行照样出现，「默认」标签落在「关闭」上。
+ *
+ * 快照可能来自没有 offeredMode 的旧 Host（新 UI——例如手机远控 bundle——连旧桌面）。旧 Host 不认
+ * 用户选择，摆出设置行只会把选择写进一个不生效的设置，所以缺席或读不懂的 offeredMode 返回 undefined：
+ * 只有认用户选择的 Host 才会写这个字段。
+ */
+export function readDynamicWorkflowOfferedMode(
+  config: DynamicWorkflowClientConfig,
+): DynamicWorkflowMode | undefined {
+  return normalizeDynamicWorkflowMode(config.offeredMode);
+}
+
+/**
+ * 「服务端给默认、用户选择永远生效」规则的唯一实现（launch.md「The user's choice」）：
+ *   - 合法的用户选择取代提供的模式，提供的是 disabled 也一样——功能已全量，服务端只决定默认值；
+ *   - 缺席或非法值（旧文件、未来版本写入的新值）按跟随提供的模式处理。
+ * 只从 `offeredMode` 推导，所以对已应用过选择的快照再次应用是覆盖而不是叠加：Host 闩住的是提供，
+ * 每次使用都用最新选择重新应用。
+ */
+export function applyDynamicWorkflowUserMode(
+  config: DynamicWorkflowClientConfig,
+  userMode: unknown,
+): DynamicWorkflowClientConfig {
+  const offer = createDynamicWorkflowClientConfig(config.offeredMode, config.source);
+  const choice = normalizeDynamicWorkflowMode(userMode);
+  if (!choice) return offer;
+  return {
+    ...offer,
+    mode: choice,
+    enabled: isDynamicWorkflowModeEnabled(choice),
+    userMode: choice,
+  };
+}
+
+/**
+ * 纯函数：把远端 envelope 的 `configs.dynamicWorkflow` 与本地覆盖环境变量折叠成「提供」，再应用用户选择。
+ * 提供的优先级：覆盖 > 远端合法值 > 缺省。远端成功但**未下发**该 key 也视为 disabled——
+ * 服务端撤掉 key 等于关闭，不能沿用旧快照（与 desktopContextPromptRollout 同一裁决）。
+ */
+export function resolveDynamicWorkflowClientConfig(input: {
+  remote: unknown;
+  env?: Record<string, string | undefined>;
+  userMode?: unknown;
+}): DynamicWorkflowClientConfig {
+  return applyDynamicWorkflowUserMode(resolveDynamicWorkflowOffer(input), input.userMode);
+}
+
+function resolveDynamicWorkflowOffer(input: {
+  remote: unknown;
+  env?: Record<string, string | undefined>;
+}): DynamicWorkflowClientConfig {
+  const override = normalizeDynamicWorkflowMode(input.env?.[ZCODE_DYNAMIC_WORKFLOW_MODE_ENV]);
+  if (override) return createDynamicWorkflowClientConfig(override, "override");
+  const remoteMode = normalizeDynamicWorkflowMode(
+    typeof input.remote === "object" && input.remote !== null
+      ? (input.remote as { mode?: unknown }).mode
+      : undefined,
+  );
+  if (remoteMode) return createDynamicWorkflowClientConfig(remoteMode, "remote");
+  return createDynamicWorkflowClientConfig(DEFAULT_DYNAMIC_WORKFLOW_MODE, "default");
+}

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

@@ -8,6 +8,9 @@ export type ArmsRumEnv = "local" | "prod";
 // 非构建环境（如 e2e 测试的 mocha）下 define 不存在，用 typeof 检查 + fallback 避免 ReferenceError
 declare const __ZCODE_ENV__: string;
 declare const __ZCODE_PRODUCT_FLAVOR__: string;
+declare const __ZCODE_ARMS_RUM_ENDPOINT__: string;
+declare const __ZCODE_TELEMETRY_REPORT_ENDPOINT__: string;
+declare const __ZCODE_AUTO_UPDATE_ENABLED__: boolean;
 
 export function normalizeZCodeEnv(value: string | undefined): ZCodeEnv {
   return value?.trim().toLowerCase() === "production" ? "production" : "test";
@@ -45,17 +48,18 @@ export const ZCODE_BUILD_COMMIT_ID_ENV = "ZCODE_BUILD_COMMIT_ID" as const;
 export const RUNTIME_ZCODE_DEBUG =
   typeof process !== "undefined" ? process.env.ZCODE_DEBUG : undefined;
 
-// 恢复原因：写死 false 会让运行时已配置的数仓/ARMS 永远空转。
-// 功能保持可用；实际出网由各出口的运行时端点检查决定，未配置不上报。
-export const ZCODE_TELEMETRY_ENABLED: boolean = true;
-
-/** 数仓事件上报端点：由运行时环境变量提供，未配置即停用，构建产物不内嵌。 */
-export const ZCODE_TELEMETRY_REPORT_ENDPOINT =
-  typeof process !== "undefined" ? (process.env.ZCODE_TELEMETRY_REPORT_ENDPOINT ?? "") : "";
-
-/** ARMS RUM 接入端点：由运行时环境变量提供，未配置即停用，构建产物不内嵌。 */
-export const ZCODE_ARMS_RUM_ENDPOINT =
-  typeof process !== "undefined" ? (process.env.ZCODE_ARMS_RUM_ENDPOINT ?? "") : "";
+// ── 构建期可选能力（见 docs/desktop/build-time-optional-capabilities.md），未注入时一律关闭 ──
+/** ARMS RUM 上报地址；为空时 SDK 以 enable=false 初始化，不产生上报。 */
+export const ZCODE_ARMS_RUM_ENDPOINT: string =
+  typeof __ZCODE_ARMS_RUM_ENDPOINT__ !== "undefined" ? __ZCODE_ARMS_RUM_ENDPOINT__ : "";
+/** 事件上报（数仓）地址；为空时不上报。 */
+export const ZCODE_TELEMETRY_REPORT_ENDPOINT: string =
+  typeof __ZCODE_TELEMETRY_REPORT_ENDPOINT__ !== "undefined"
+    ? __ZCODE_TELEMETRY_REPORT_ENDPOINT__
+    : "";
+/** 桌面自动更新是否启用。 */
+export const ZCODE_AUTO_UPDATE_ENABLED: boolean =
+  typeof __ZCODE_AUTO_UPDATE_ENABLED__ !== "undefined" ? __ZCODE_AUTO_UPDATE_ENABLED__ : false;
 
 /** 将本地运行态与编译期 ZCODE_ENV 映射为 ARMS 控制台识别的上报环境标签 */
 export function mapZCodeEnvToArmsRumEnv(runtimeEnv: ZCodeRuntimeEnv): ArmsRumEnv {

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

@@ -0,0 +1,232 @@
+import { z } from "zod";
+import {
+  modelExecutionSelectionFallbackReasonSchema,
+  type ModelExecutionSelectionFallback,
+} from "./model-execution.js";
+import type { ModelSelection } from "./model-selection.js";
+import { BUILTIN_MODEL_PROVIDER_IDS } from "./model-provider-types.js";
+
+/**
+ * 卡在 Turn 中过期时加速网关返回的业务错误码（HTTP 400 / provider_code=3402）。
+ * 见 docs/highspeed/highspeed-card-spec.md：命中它要保留上下文并退回原模型跑完本轮。
+ */
+export const HIGHSPEED_CARD_EXPIRED_PROVIDER_ERROR_CODE = "3402";
+
+/**
+ * 加速卡的隐藏 Built-in Provider；端点与模型名单由 ZCode Built-in Provider Config 提供
+ * （config/provider/zcode-builtin.json），这里只保留跨层引用的 ID。
+ * 与 Off-Peak 同规则按账号 Family 拆分：卡是对当前账号 Coding Plan 权益的抽取，
+ * 不跨 Family 静默迁移。
+ */
+export const HIGHSPEED_PROVIDER_IDS = {
+  zai: "account:zai-highspeed-card",
+  bigmodel: "account:bigmodel-highspeed-card",
+} as const;
+
+export function resolveHighspeedProviderId(
+  family: "zai" | "bigmodel",
+): (typeof HIGHSPEED_PROVIDER_IDS)[typeof family] {
+  return HIGHSPEED_PROVIDER_IDS[family];
+}
+
+/**
+ * 判定一次 Selection 是否指向加速卡 Provider。拆 Family 之后不能再和单个常量比较，
+ * 否则 BigModel 账号的卡在队列提升时会被判成「非加速」而静默丢卡。
+ */
+export function isHighspeedProviderId(providerId: string | undefined): boolean {
+  if (providerId === undefined) return false;
+  return Object.values(HIGHSPEED_PROVIDER_IDS).some((id) => id === providerId);
+}
+
+/**
+ * draw body 的 provider 契约值：服务端 highspeed 白名单只认 Coding Plan 的 builtin 身份
+ * （builtin:zai-coding-plan / builtin:bigmodel-coding-plan，2026-09-17 与服务端确认；
+ * 设计文档示例里的 "zai" 是缩写示意，非线上取值）。Start Plan、Off-Peak、API Key 与
+ * 自定义 Provider 都不在白名单内，必须解析为 null 后降级，禁止映射后发送。
+ */
+export const HIGHSPEED_DRAW_PROVIDER_IDS = {
+  zai: "builtin:zai-coding-plan",
+  bigmodel: "builtin:bigmodel-coding-plan",
+} as const;
+
+const HIGHSPEED_DRAW_PROVIDER_ID_BY_PROVIDER_ID = new Map<string, string>([
+  [BUILTIN_MODEL_PROVIDER_IDS.zaiIndividualCodingPlan, HIGHSPEED_DRAW_PROVIDER_IDS.zai],
+  [BUILTIN_MODEL_PROVIDER_IDS.zaiTeamCodingPlan, HIGHSPEED_DRAW_PROVIDER_IDS.zai],
+  [BUILTIN_MODEL_PROVIDER_IDS.bigmodelIndividualCodingPlan, HIGHSPEED_DRAW_PROVIDER_IDS.bigmodel],
+  [BUILTIN_MODEL_PROVIDER_IDS.bigmodelTeamCodingPlan, HIGHSPEED_DRAW_PROVIDER_IDS.bigmodel],
+]);
+
+/** 把会话选择的 Provider ID 解析成 draw body 可用的白名单 provider 值；不命中返回 null。 */
+export function resolveHighspeedDrawProviderId(providerId: string): string | null {
+  return HIGHSPEED_DRAW_PROVIDER_ID_BY_PROVIDER_ID.get(providerId) ?? null;
+}
+
+export const highspeedCardSchema = z.object({
+  card_id: z.string().min(1),
+  task_id: z.string().min(1),
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  issued_at: z.number().int().nonnegative(),
+  expires_at: z.number().int().nonnegative(),
+});
+
+/**
+ * 写入 message.data 的协议级卡快照。版本字段保证后续扩展仍能宽容读取旧消息。
+ */
+export const highspeedMessageMetaSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    cardId: z.string().min(1),
+    taskId: z.string().min(1),
+    provider: z.string().min(1),
+    model: z.string().min(1),
+    issuedAt: z.number().int().nonnegative(),
+    expiresAt: z.number().int().nonnegative(),
+    /** 发送该轮时从 Coding Plan 健康检查采样的普通 Pro/Max decode TPS。 */
+    regularTps: z.number().positive().optional(),
+    /** 完成态统计；这些字段由同一次 CLI 持久化更新原子写入。 */
+    outputTokens: z.number().int().nonnegative().optional(),
+    durationMs: z.number().nonnegative().optional(),
+    /** 卡到期后从 Highspeed healthy usage 采样的卡级平均 completion TPS。 */
+    highspeedTps: z.number().positive().optional(),
+    savedDurationMs: z.number().nonnegative().optional(),
+    /** CLI 从运行时事件聚合的真实耗时拆分；缺省时客户端回退到 20/80 估算。 */
+    modelDurationMs: z.number().nonnegative().optional(),
+    toolDurationMs: z.number().nonnegative().optional(),
+    otherDurationMs: z.number().nonnegative().optional(),
+    /** Turn 内加速请求失败并回落普通模型的时刻；只用于投影降级提示，不改变分享统计。 */
+    fallbackAt: z.number().int().nonnegative().optional(),
+    /** 回落原因：卡过期或其他加速请求失败；Renderer 据此选择提示文案，缺省按卡过期处理旧数据。 */
+    fallbackReason: modelExecutionSelectionFallbackReasonSchema.optional(),
+  })
+  .strict();
+
+export const highspeedDrawRequestSchema = z.object({
+  task_id: z.string().min(1),
+  provider: z.string().min(1),
+  model: z.string().min(1),
+});
+
+export const highspeedDrawResponseSchema = z.object({
+  code: z.number().int(),
+  msg: z.string(),
+  data: z.object({
+    card: highspeedCardSchema.nullable(),
+    next_draw_at: z.number().int().nonnegative(),
+  }),
+});
+
+export const highspeedHealthyResponseSchema = z.object({
+  code: z.number().int(),
+  msg: z.string(),
+  data: z.object({
+    card_id: z.string().min(1),
+    prompt_tokens: z.number().int().nonnegative(),
+    completion_tokens: z.number().int().nonnegative(),
+    duration_seconds: z.number().int().nonnegative(),
+  }),
+});
+
+export type HighspeedCardApi = z.infer<typeof highspeedCardSchema>;
+export type HighspeedMessageMeta = z.infer<typeof highspeedMessageMetaSchema>;
+export type HighspeedDrawRequest = z.infer<typeof highspeedDrawRequestSchema>;
+export type HighspeedDrawResponse = z.infer<typeof highspeedDrawResponseSchema>;
+export type HighspeedHealthyResponse = z.infer<typeof highspeedHealthyResponseSchema>;
+
+export interface HighspeedCardUsage {
+  cardId: string;
+  promptTokens: number;
+  completionTokens: number;
+  durationSeconds: number;
+}
+
+export interface HighspeedCardSnapshot {
+  cardId: string;
+  taskId: string;
+  provider: string;
+  model: string;
+  issuedAt: number;
+  expiresAt: number;
+  regularTps?: number;
+}
+
+export type HighspeedPrepareFallbackReason =
+  | "automation"
+  | "cooldown"
+  | "draw-miss"
+  | "draw-timeout"
+  | "expired"
+  | "foreign-card"
+  | "no-coding-plan"
+  | "unavailable";
+
+export interface HighspeedPrepareTurnParams {
+  taskId: string;
+  /**
+   * 会话模型选择的 Provider ID。draw body 的 provider 契约是白名单里的 Coding Plan
+   * builtin 身份（builtin:zai-coding-plan / builtin:bigmodel-coding-plan），由服务层
+   * 发送前解析；调用方禁止直接传白名单值或把完整 providerId 透传上链路
+   * （透传会被服务端白名单拒绝并返回 3001 参数错误）。
+   */
+  providerId: string;
+  /**
+   * 会话当前选择的模型。除 provider 白名单外，模型还必须属于所选 Coding Plan Provider 的
+   * 模型目录（Built-in Provider Config 投影）才会发起新 draw；陈旧的 (coding-plan provider,
+   * 已下线模型) 组合按 unavailable 降级（spec §3 规则 14）。
+   */
+  model: string;
+  /**
+   * 会话当前生效的思考档位。加速只换端点不换模型，卡的 modelSelection 必须带上与会话
+   * 一致的 reasoningLevel；否则 CLI Registry 会因 execution 选择缺档位判定
+   * reasoning-level-missing，抛出 "Reasoning level is required" 让整轮发送失败。
+   * 模型无思考档位时省略（不写 options）。
+   */
+  reasoningLevel?: string;
+  /** 仅表示本轮由 Automation 派发；不得用 Task 上粘性的 cronAutomationId 代替。 */
+  automationId?: string;
+  waitBudgetMs?: number;
+}
+
+/**
+ * 单轮加速执行材料。静态事实（端点、API 形态、模型能力）由 Built-in Provider Config
+ * 提供，这里只携带「本轮选哪个模型」和「本次执行的动态鉴权」，禁止再下发 provider 定义。
+ */
+export interface HighspeedTurnExecution {
+  modelSelection: ModelSelection;
+  requestAuth: { apiKey: string; headers: Record<string, string> };
+  /**
+   * 加速请求任何失败时退回原模型跑完本轮；卡过期（3402）与其他失败按规则给出不同原因。
+   * 退回目标 `target` 是抽卡时的提交选择（会话原模型 + 档位），CLI 优先用它，缺省才退回会话常驻选择。
+   */
+  selectionFallback: ModelExecutionSelectionFallback;
+}
+
+export type HighspeedPrepareTurnResult =
+  | {
+      kind: "accelerated";
+      card: HighspeedCardSnapshot;
+      nextDrawAt: number;
+      /** Mock 只保留加速业务语义，省略该字段即可继续使用 session 普通推理路由。 */
+      execution?: HighspeedTurnExecution;
+    }
+  | {
+      kind: "fallback";
+      reason: HighspeedPrepareFallbackReason;
+      card?: HighspeedCardSnapshot;
+      nextDrawAt: number | null;
+    };
+
+export interface HighspeedServiceSnapshot {
+  card: HighspeedCardSnapshot | null;
+  nextDrawAt: number | null;
+  drawing: boolean;
+}
+
+export type HighspeedMockScenario =
+  | "hit-fast"
+  | "miss"
+  | "hit-after-timeout"
+  | "hit-invalid-model"
+  | "hit-queue-edit"
+  | "existing-foreign-task-card"
+  | "expired-card";

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

@@ -0,0 +1,148 @@
+import { z } from "zod";
+
+/**
+ * App-Provided Tools（MCP Apps 规范「App-Provided Tools」）：页面在 `ui/initialize` 声明 `tools` 能力后，
+ * 宿主 `tools/list` 发现页面工具、登记到 agent 暴露给模型；模型调用经"实例信箱"（live-only 投影增量
+ * `pluginUi.appToolCall`，按 scopeId + generation 投递）到达渲染端，页面 `tools/call` 执行后回传。
+ * 这里只有限额、描述符归一化与模型侧命名；纯 domain，零 IO。
+ */
+
+/** 每个页面实例最多登记的工具数（规范推荐值）。 */
+export const MCP_APPS_APP_TOOLS_MAX_PER_INSTANCE = 50;
+export const MCP_APPS_APP_TOOL_NAME_MAX_CHARS = 128;
+export const MCP_APPS_APP_TOOL_TITLE_MAX_CHARS = 256;
+export const MCP_APPS_APP_TOOL_DESCRIPTION_MAX_CHARS = 4096;
+/** inputSchema / outputSchema 序列化后的上限（UTF-8 字节）。 */
+export const MCP_APPS_APP_TOOL_SCHEMA_MAX_BYTES = 64 * 1024;
+/** 渲染端认领待执行调用的期限；超时视为页面未运行（信箱投递不重发）。 */
+export const MCP_APPS_APP_TOOL_CLAIM_TIMEOUT_MS = 5_000;
+/** 认领后页面执行 tools/call 的期限（规范推荐值）。 */
+export const MCP_APPS_APP_TOOL_CALL_TIMEOUT_MS = 30_000;
+/** 单次结果序列化上限（规范推荐值）。 */
+export const MCP_APPS_APP_TOOL_RESULT_MAX_BYTES = 10 * 1024 * 1024;
+/** 模型调用参数进信箱前的上限；超限直接以错误结束，不下发。 */
+export const MCP_APPS_APP_TOOL_ARGUMENTS_MAX_BYTES = 1024 * 1024;
+/** list_changed 触发的重新登记最小间隔。 */
+export const MCP_APPS_APP_TOOLS_REFRESH_INTERVAL_MS = 1_000;
+export const MCP_APPS_APP_TOOL_ERROR_MESSAGE_MAX_CHARS = 4096;
+export const MCP_APPS_APP_TOOL_CALL_ID_MAX_CHARS = 128;
+/** 模型侧名字前缀：与 server 工具的 `mcp__` 天然不冲突。 */
+export const MCP_APPS_APP_TOOL_MODEL_NAME_PREFIX = "app__";
+
+const utf8Bytes = (value: string) => new TextEncoder().encode(value).length;
+
+/** 与 agent 的 MCP 工具名同一清洗规则：非 `[A-Za-z0-9_-]` 替换为 `_` 并合并连续下划线。 */
+export function sanitizeMcpAppsModelNamePart(name: string): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9_-]/g, "_").replace(/_+/g, "_");
+  return sanitized.length > 0 ? sanitized : "unknown";
+}
+
+/** 模型侧名字 `app__<server>__<tool>`。 */
+export function buildMcpAppsAppToolModelName(serverName: string, toolName: string): string {
+  return `${MCP_APPS_APP_TOOL_MODEL_NAME_PREFIX}${sanitizeMcpAppsModelNamePart(serverName)}__${sanitizeMcpAppsModelNamePart(toolName)}`;
+}
+
+const objectSchemaSchema = z
+  .record(z.string(), z.unknown())
+  .refine((value) => value.type === "object", { message: "schema type must be object" })
+  .refine((value) => utf8Bytes(JSON.stringify(value)) <= MCP_APPS_APP_TOOL_SCHEMA_MAX_BYTES, {
+    message: "schema is too large",
+  });
+
+export const mcpAppsAppToolAnnotationsSchema = z.strictObject({
+  title: z.string().max(MCP_APPS_APP_TOOL_TITLE_MAX_CHARS).optional(),
+  readOnlyHint: z.boolean().optional(),
+  destructiveHint: z.boolean().optional(),
+  idempotentHint: z.boolean().optional(),
+  openWorldHint: z.boolean().optional(),
+});
+export type McpAppsAppToolAnnotations = z.infer<typeof mcpAppsAppToolAnnotationsSchema>;
+
+export const mcpAppsAppToolDescriptorSchema = z.strictObject({
+  name: z.string().min(1).max(MCP_APPS_APP_TOOL_NAME_MAX_CHARS),
+  title: z.string().max(MCP_APPS_APP_TOOL_TITLE_MAX_CHARS).optional(),
+  description: z.string().max(MCP_APPS_APP_TOOL_DESCRIPTION_MAX_CHARS).optional(),
+  inputSchema: objectSchemaSchema,
+  outputSchema: objectSchemaSchema.optional(),
+  annotations: mcpAppsAppToolAnnotationsSchema.optional(),
+});
+export type McpAppsAppToolDescriptor = z.infer<typeof mcpAppsAppToolDescriptorSchema>;
+
+const ANNOTATION_BOOLEAN_KEYS = [
+  "readOnlyHint",
+  "destructiveHint",
+  "idempotentHint",
+  "openWorldHint",
+] as const;
+
+/**
+ * 渲染端用：把页面 `tools/list` 的结果收窄成可登记的描述符。不合规的项跳过（不让整次登记失败），
+ * 超过 50 个只取前 50 个；返回被跳过的名字与原因供日志。
+ */
+export function normalizeMcpAppsAppTools(tools: readonly unknown[]): {
+  tools: McpAppsAppToolDescriptor[];
+  skipped: Array<{ name: string | null; reason: string }>;
+} {
+  const accepted: McpAppsAppToolDescriptor[] = [];
+  const skipped: Array<{ name: string | null; reason: string }> = [];
+  const seen = new Set<string>();
+  for (const raw of tools) {
+    const record = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : null;
+    const name = typeof record?.name === "string" ? record.name : null;
+    if (accepted.length >= MCP_APPS_APP_TOOLS_MAX_PER_INSTANCE) {
+      skipped.push({ name, reason: "limit" });
+      continue;
+    }
+    if (!record || name === null) {
+      skipped.push({ name, reason: "invalid" });
+      continue;
+    }
+    if (seen.has(name)) {
+      skipped.push({ name, reason: "duplicate" });
+      continue;
+    }
+    const rawAnnotations =
+      record.annotations && typeof record.annotations === "object"
+        ? (record.annotations as Record<string, unknown>)
+        : null;
+    const annotations: Record<string, unknown> = {};
+    if (typeof rawAnnotations?.title === "string") annotations.title = rawAnnotations.title;
+    for (const key of ANNOTATION_BOOLEAN_KEYS) {
+      if (typeof rawAnnotations?.[key] === "boolean") annotations[key] = rawAnnotations[key];
+    }
+    const candidate = {
+      name,
+      ...(typeof record.title === "string" ? { title: record.title } : {}),
+      ...(typeof record.description === "string" ? { description: record.description } : {}),
+      inputSchema: record.inputSchema,
+      ...(record.outputSchema !== undefined ? { outputSchema: record.outputSchema } : {}),
+      ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+    };
+    const parsed = mcpAppsAppToolDescriptorSchema.safeParse(candidate);
+    if (!parsed.success) {
+      skipped.push({ name, reason: parsed.error.issues[0]?.message ?? "invalid" });
+      continue;
+    }
+    seen.add(name);
+    accepted.push(parsed.data);
+  }
+  return { tools: accepted, skipped };
+}
+
+/** 页面 `tools/call` 的结果（MCP CallToolResult 形状，字段集宽松：content 项原样保留）。 */
+export const mcpAppsAppToolCallResultSchema = z.object({
+  content: z.array(z.record(z.string(), z.unknown())),
+  structuredContent: z.unknown().optional(),
+  isError: z.boolean().optional(),
+  _meta: z.record(z.string(), z.unknown()).optional(),
+});
+export type McpAppsAppToolCallResult = z.infer<typeof mcpAppsAppToolCallResultSchema>;
+
+/** 信箱里的一次待执行调用：按 (scopeId, generation) 投递给唯一实例。 */
+export interface McpAppsAppToolCallRequest {
+  activity?: boolean;
+  cancelled?: boolean;
+  callId: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+}