paseo-plugin-zcode-provider 0.2.0 → 0.4.0

package/server/vendor/zcode/packages/shared/src/subagents-types.ts

@@ -0,0 +1,164 @@
+import type { ZCodeProvider } from "./zcode-task-types-core.js";
+import { modelSelectionSchema, type ModelSelection } from "./model-selection.js";
+
+export type AgentScope = "built-in" | "workspace" | "user";
+
+export type AgentSource = "built-in" | "user" | "plugin";
+
+export type BuiltInSubagentName = "general-purpose" | "Explore";
+
+export type BuiltInSubagentModelSelectionOverrides = Partial<
+  Record<BuiltInSubagentName, ModelSelection>
+>;
+
+export type PluginSubagentModelSelectionOverrides = Readonly<Record<string, ModelSelection>>;
+
+/** 正式 reader 只接受结构化覆盖，不在读取时解释旧双 map 或重新匹配 Provider。 */
+export function parsePluginSubagentModelSelectionOverrides(
+  value: unknown,
+): PluginSubagentModelSelectionOverrides {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([id, candidate]) => {
+      const selection = modelSelectionSchema.safeParse(candidate);
+      return id.startsWith("plugin:") && selection.success ? [[id, selection.data]] : [];
+    }),
+  );
+}
+
+export type AgentPermissionMode =
+  | "acceptEdits"
+  | "auto"
+  | "bypassPermissions"
+  | "default"
+  | "dontAsk"
+  | "plan";
+
+export type AgentColor =
+  | "red"
+  | "blue"
+  | "green"
+  | "yellow"
+  | "purple"
+  | "orange"
+  | "pink"
+  | "cyan";
+
+export type SubagentsListMode = "allRuntimeScopes" | "settingsUserOnly";
+
+export interface AgentSummary {
+  id: string;
+  name: string;
+  description: string;
+  systemPrompt: string;
+  color?: AgentColor;
+  modelSelection?: ModelSelection;
+  defaultModelSelection?: ModelSelection;
+  modelSelectionOverride?: ModelSelection;
+  tools?: string[];
+  disallowedTools?: string[];
+  injectAgentsMd?: boolean;
+  skills?: string[];
+  permissionMode?: AgentPermissionMode;
+  maxTurns?: number;
+  background?: boolean;
+  mcpServers?: unknown[];
+  path: string;
+  scope: AgentScope;
+  source: AgentSource;
+  enabled: boolean;
+  readOnly?: boolean;
+  projectPath?: string;
+  pluginId?: string;
+  pluginName?: string;
+  diagnostics?: AgentDiagnostic[];
+}
+
+export interface AgentDiagnostic {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface AgentsCapability {
+  userScopeAvailable: boolean;
+  userScopeReason?: "desktop_only";
+}
+
+export interface AgentsListResult {
+  agents: AgentSummary[];
+  userAgents: AgentSummary[];
+  pluginAgents: AgentSummary[];
+  capability: AgentsCapability;
+  diagnostics?: AgentDiagnostic[];
+}
+
+/** Agent 配置，用于创建/更新 agent */
+export interface SubAgentConfig {
+  name: string;
+  description: string;
+  systemPrompt: string;
+  color?: AgentColor;
+  modelSelection?: ModelSelection;
+  tools?: string[];
+  disallowedTools?: string[];
+  injectAgentsMd?: boolean;
+  skills?: string[];
+  permissionMode?: AgentPermissionMode;
+  maxTurns?: number;
+  background?: boolean;
+  mcpServers?: unknown[];
+}
+
+/** Agent 创建参数 */
+export interface AgentCreateParams {
+  config: SubAgentConfig;
+  provider: ZCodeProvider;
+  scope?: "user" | "workspace";
+  workspacePath?: string;
+  workspaceIdentity?: string;
+}
+
+/** Agent 更新参数 */
+export interface AgentUpdateParams {
+  agentId: string;
+  config: SubAgentConfig;
+  oldFilePath?: string;
+  provider: ZCodeProvider;
+  scope?: "user" | "workspace";
+  workspacePath?: string;
+  workspaceIdentity?: string;
+}
+
+/** Agent 删除参数 */
+export interface AgentDeleteParams {
+  agentId: string;
+  filePath: string;
+}
+
+export interface BuiltInSubagentModelOverrideParams {
+  agentName: BuiltInSubagentName;
+  modelSelection?: ModelSelection;
+}
+
+export interface PluginSubagentModelOverrideParams {
+  agentId: string;
+  modelSelection?: ModelSelection;
+}
+
+/**
+ * 插件 subagent 的稳定 id：`plugin:<pluginId>:<裸名小写>`。
+ * pluginId 为 `<name>@<marketplace>`，不含版本，插件升级后 id 不变，覆盖随之保留。
+ * services 与 CLI bootstrap 都用它做 agents-state.json 的键，必须共用一处实现。
+ */
+export function createPluginAgentStateId(pluginId: string, agentName: string): string {
+  return `plugin:${pluginId}:${agentName.trim().toLowerCase()}`;
+}
+
+export function createAgentStateId(input: {
+  name: string;
+  scope: AgentScope;
+  source: AgentSource;
+}): string {
+  return `${input.source}:${input.scope}:${input.name.trim().toLowerCase()}`;
+}

package/server/vendor/zcode/packages/shared/src/usage-stats.ts

@@ -44,6 +44,20 @@ export interface CodingPlanUsageRequest {
   timeZone?: string;
 }
 
+/** Highspeed 只读取普通 Pro/Max decode TPS，不触发完整 Coding Plan 用量聚合。 */
+export interface CodingPlanRegularTpsRequest {
+  preferredProviderId: string;
+  /**
+   * Registry 静态访问类别，或调用边界已解析的动态账号访问上下文。
+   *
+   * Bug 原因：此前该请求只带 organizationId/projectId，请求期鉴权靠 host 自行按 provider
+   * 猜测账号。Provider 重构后 Coding Plan 授权统一由 accountAccess 解析（Team scope 也内含
+   * 其中），缺失时 resolveAuthorization 必定返回 null，节省时间会静默不展示。
+   */
+  accountAccess: ZCodeProviderAccountAccess | ZCodeAccountAccess;
+  timeZone?: string;
+}
+
 export interface UsageEntitlementRequest {
   /** 购买或领取完成后，使对应 Start Plan balance 短期缓存失效。 */
   invalidateBalanceCache?: boolean;

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

@@ -1,15 +1,23 @@
 /* oxlint-disable eslint(max-lines) -- AppSettings schema 聚合历史迁移、默认值和 patch 校验，拆分会削弱设置迁移的单一入口。 */
 import { z } from "zod";
+import { appToolSearchModeSchema } from "./app-runtime-preferences.js";
 import type { AppSettings } from "./protocol.js";
 import { REMOTE_ASSET_INSTALL_MODES } from "./remoteAssetInstallMode.js";
 import { isKnownRemoteResourcePackageId } from "./remoteResourcePackages.js";
 import { wslUserSchema } from "./wslUserValidation.js";
+import { ZCODE_ENABLED_AGENT_PROVIDERS } from "./zcode-agent-policy.js";
+import { DYNAMIC_WORKFLOW_MODES } from "./dynamic-workflow-feature.js";
 import { normalizeZCodeEndpointOrigin } from "./zcodeEndpoint.js";
 import {
   DEFAULT_EMBEDDED_BROWSER_VIEWPORT_PREFERENCE,
   embeddedBrowserViewportPreferenceSchema,
 } from "./browser-use/command-metadata.js";
 import { providerFamilyConnectionSelectionSettingsSchema } from "./provider-family-connection-selection.js";
+import {
+  connectionProfileSchema,
+  sourceServerRecordSchema,
+  sourceServerWorkspaceHistoryEntrySchema,
+} from "./source-server/contracts.js";
 
 /** 引导职业枚举；单独导出供 onboarding 记录回填 settings 时做窄化校验。 */
 const appSettingsOccupationSchema = z.enum([
@@ -33,8 +41,11 @@ export const appSettingsOccupationEnum = appSettingsOccupationSchema;
 const nonEmptyStringSchema = z.string().trim().min(1);
 
 export const localeSchema = z.enum(["zh-CN", "en-US"]);
-const localePreferenceSchema = z.enum(["system", "zh-CN", "en-US"]);
+export const localePreferenceSchema = z.enum(["system", "zh-CN", "en-US"]);
 const zcodeInteractionBehaviorSchema = z.enum(["queue", "guide"]);
+// launch.md「The user's choice」：读文件时未知取值（降级后读到新版本写的值）按「跟随」处理，
+// 不能让一个偏好字段把整份设置读坏。
+const dynamicWorkflowModeSettingSchema = z.enum(DYNAMIC_WORKFLOW_MODES).optional().catch(undefined);
 const electronReleaseChannelSchema = z.enum(["stable", "preview"]);
 const desktopZoomLevelSchema = z.number().int().min(-3).max(5);
 const desktopWindowSizeSchema = z.object({
@@ -54,6 +65,10 @@ export const integratedTerminalShellSelectionSchema = z.discriminatedUnion("mode
     path: nonEmptyStringSchema,
   }),
 ]);
+const enabledBuiltinAgentCliProvidersSchema = z
+  // 兼容旧 settings：历史列表可能残留三方 CLI provider，解析后统一归一为 ZCode Agent。
+  .array(z.enum(["claude", "opencode", "gemini", "codex", "glm"]))
+  .transform(() => [...ZCODE_ENABLED_AGENT_PROVIDERS]);
 const providerFamilyDomainSchema = z.enum(["zai", "bigmodel"]);
 
 export const postUpdateReleaseNotesPayloadSchema = z.object({
@@ -100,6 +115,14 @@ const remoteWorkspaceTargetSchema = z.discriminatedUnion("kind", [
     kind: z.literal("docker"),
     container: nonEmptyStringSchema,
   }),
+  z.object({
+    kind: z.literal("server"),
+    url: z.string().url(),
+    name: nonEmptyStringSchema.optional(),
+    workspacePath: z.string().optional(),
+    serverId: nonEmptyStringSchema.optional(),
+    tokenCredentialKey: nonEmptyStringSchema.optional(),
+  }),
 ]);
 
 const appWorkspaceSessionEntrySchema = z.discriminatedUnion("kind", [
@@ -111,6 +134,7 @@ const appWorkspaceSessionEntrySchema = z.discriminatedUnion("kind", [
   z.object({
     kind: z.literal("remote"),
     workspacePath: nonEmptyStringSchema,
+    workspacePurpose: z.enum(["project", "conversation"]).default("project"),
     localWorkspacePath: nonEmptyStringSchema.optional(),
     workspaceIdentity: nonEmptyStringSchema.optional(),
     target: remoteWorkspaceTargetSchema,
@@ -120,6 +144,26 @@ const appWorkspaceSessionEntrySchema = z.discriminatedUnion("kind", [
   }),
 ]);
 
+const webRemoteControlRelayV2DeviceSchema = z.object({
+  deviceSid: z.string().min(1),
+  userId: z.string().min(1),
+  endpointOrigin: z.url(),
+});
+const remoteConversationWorkspaceRecordSchema = z
+  .object({
+    workspacePath: nonEmptyStringSchema,
+    lastResolvedAt: z.number().int().nonnegative(),
+  })
+  .strict();
+
+const webRemoteControlExternalRelayDeviceSchema = z.object({
+  deviceSid: nonEmptyStringSchema,
+});
+const webRemoteControlLastEnabledContextSchema = z.object({
+  workspacePath: nonEmptyStringSchema,
+  workspaceIdentity: nonEmptyStringSchema.optional(),
+  initialTaskId: nonEmptyStringSchema.optional(),
+});
 const zcodeEndpointOriginSchema = z.preprocess((value) => {
   if (typeof value !== "string") {
     return undefined;
@@ -190,6 +234,28 @@ function sanitizeEmbeddedBrowserViewportPreference(value: unknown): unknown {
   return next;
 }
 
+function migrateRemoteBoundaryIntroAcknowledgement(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const raw = value as Record<string, unknown>;
+  if (raw.remoteBoundaryOnboardingVersion !== 3) return value;
+  // 原因：旧客户端只接受 2，写 3 会让整份设置回退默认值。迁移已确认的 3 到新字段，
+  // 同时恢复旧字段合同；不能仅收窄 schema，否则修复版读取存量 3 也会丢设置。
+  return {
+    ...raw,
+    remoteBoundaryOnboardingVersion: 2,
+    remoteBoundaryIntroAcknowledgedVersion: 1,
+  };
+}
+
+function migrateTaskAutoArchiveReset(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const raw = value as Record<string, unknown>;
+  if (raw.taskAutoArchiveResetVersion === 1) return value;
+  // 旧版开关开启后可能未执行；修复后直接沿用会在启动时突然归档历史会话。
+  // 首次读取统一关闭并持久化标记，用户重新开启后不再重置。
+  return { ...raw, taskAutoArchiveEnabled: false, taskAutoArchiveResetVersion: 1 };
+}
+
 function migrateCloseToTrayOnWindowsDefault(value: unknown): unknown {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return value;
@@ -258,6 +324,24 @@ const legacyRemoteWorkspaceHistoryEntrySchema = z.object({
   lastConnectionError: z.string().optional(),
 });
 
+function migrateLegacyBuiltinAgentCliProviders(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+
+  const raw = value as {
+    enabledBuiltinAgentCliProviders?: unknown;
+  };
+
+  // Bugfix: 单 ZCode Agent 迁移后，旧 setting.json 可能还保存已移除的第三方 CLI provider
+  // 的启用状态。若这些值继续进入 UI / bot 的 provider 选项，会和 server 侧唯一 glm 状态打架。
+  // 这里在 schema 入口统一归一到 ZCode Agent，让核心 provider 状态只有一个事实源。
+  return {
+    ...raw,
+    enabledBuiltinAgentCliProviders: [...ZCODE_ENABLED_AGENT_PROVIDERS],
+  };
+}
+
 function stripHistoricalRemoteResourcePackages(target: unknown): unknown {
   if (!target || typeof target !== "object" || Array.isArray(target)) {
     return target;
@@ -437,9 +521,12 @@ const appSettingsObjectSchema = z.object({
   // default 只对缺省字段生效，显式存过 false 的用户仍保持展示。
   computerUseComposerEntryHidden: z.boolean().default(true),
   taskAutoArchiveEnabled: z.boolean().default(false),
-  taskAutoArchiveOlderThanDays: z.number().int().positive().max(365).default(7),
+  taskAutoArchiveResetVersion: z.literal(1).default(1),
+  taskAutoArchiveOlderThanDays: z.number().int().positive().max(365).default(30),
   closeToTrayOnWindows: z.boolean().default(true),
   closeToTrayOnWindowsMigrationInitialized: z.boolean().default(true),
+  // default(false)：新装与存量用户首次启动都视为未归位，由 main 进程按平台决定是否迁移。
+  closeToTrayLinuxMigrationInitialized: z.boolean().default(false),
   keepAwakeWhileRunning: z.boolean().default(false),
   desktopZoomLevel: desktopZoomLevelSchema.optional(),
   desktopWindowSize: desktopWindowSizeSchema.optional(),
@@ -453,16 +540,34 @@ const appSettingsObjectSchema = z.object({
   zcodeInteractionBehavior: zcodeInteractionBehaviorSchema.default("queue"),
   askUserQuestionAutoResolutionEnabled: z.boolean().default(true),
   modelIoFullRetentionEnabled: z.boolean().default(false),
+  dynamicWorkflowMode: dynamicWorkflowModeSettingSchema,
+  enabledBuiltinAgentCliProviders: enabledBuiltinAgentCliProvidersSchema.default([
+    ...ZCODE_ENABLED_AGENT_PROVIDERS,
+  ]),
   startPlanRecommendationDismissed: z.boolean().default(false),
   providerFamilyConnectionSelections: providerFamilyConnectionSelectionSettingsSchema.default({}),
   providerFamilyDomain: providerFamilyDomainSchema.optional(),
   providerFamilyDomainUpdatedAt: z.number().int().nonnegative().optional(),
   providerFamilyDomainMigrated: z.boolean().default(false),
   nativeSearchEnhancementsEnabled: z.boolean().default(true),
+  toolSearchMode: appToolSearchModeSchema.default("off"),
   onboardingOccupation: appSettingsOccupationSchema.nullish(),
   proactiveSuggestionsEnabled: z.boolean().optional(),
   memoryEnabled: z.boolean().default(false),
   lastWorkspaceSession: z.array(appWorkspaceSessionEntrySchema).default([]),
+  lastActiveWorkspace: appWorkspaceSessionEntrySchema.nullable().optional(),
+  remoteConversationWorkspaceBySourceServerId: z
+    .record(nonEmptyStringSchema, remoteConversationWorkspaceRecordSchema)
+    .optional(),
+  sourceServers: z.array(sourceServerRecordSchema).default([]),
+  connectionProfiles: z.array(connectionProfileSchema).default([]),
+  sourceServerWorkspaceHistory: z.array(sourceServerWorkspaceHistoryEntrySchema).default([]),
+  // Bug 原因：该开关过去只声明在 patch schema，SettingService 合并后再走完整 schema 时会把
+  // 显式 false 剥离，导致重启后恢复为默认开启。完整 schema 必须拥有这项持久化事实。
+  remoteStartupAutoReconnectEnabled: z.boolean().optional(),
+  sourceServerDirectoryMigrationVersion: z.literal(1).optional(),
+  remoteBoundaryOnboardingVersion: z.literal(2).optional(),
+  remoteBoundaryIntroAcknowledgedVersion: z.literal(1).optional(),
   lastActiveTabIndex: z.number().int().nonnegative().default(0),
   lastActiveTaskByWorkspace: z.record(z.string(), z.string()).optional(),
   dataBaseDir: z.string().trim().min(1).optional(),
@@ -471,6 +576,9 @@ const appSettingsObjectSchema = z.object({
   autoDownloadAndInstallUpdates: z.boolean().default(false),
   skippedElectronUpdateVersions: skippedElectronUpdateVersionsSchema,
   settingsSyncFirstRunPromptHandled: z.boolean().optional(),
+  webRemoteControlRelayV2Device: webRemoteControlRelayV2DeviceSchema.optional(),
+  webRemoteControlExternalRelayDevice: webRemoteControlExternalRelayDeviceSchema.optional(),
+  webRemoteControlLastEnabledContext: webRemoteControlLastEnabledContextSchema.optional(),
   zcodeEndpointOrigin: zcodeEndpointOriginSchema.optional(),
 });
 
@@ -481,7 +589,13 @@ export const appSettingsSchema = z.preprocess(
         migrateMessageStreamShowReasoningDefault(
           migrateCloseToTrayOnWindowsDefault(
             migrateLegacyLocalePreference(
-              sanitizeZCodeEndpointOrigin(migrateLegacyWorkspaceSession(value)),
+              sanitizeZCodeEndpointOrigin(
+                migrateLegacyWorkspaceSession(
+                  migrateLegacyBuiltinAgentCliProviders(
+                    migrateRemoteBoundaryIntroAcknowledgement(migrateTaskAutoArchiveReset(value)),
+                  ),
+                ),
+              ),
             ),
           ),
         ),
@@ -509,6 +623,7 @@ export const appSettingsPatchSchema = z.object({
   closeToTrayOnWindows: z.boolean().optional(),
   keepAwakeWhileRunning: z.boolean().optional(),
   closeToTrayOnWindowsMigrationInitialized: z.boolean().optional(),
+  closeToTrayLinuxMigrationInitialized: z.boolean().optional(),
   desktopZoomLevel: desktopZoomLevelSchema.optional(),
   desktopWindowSize: desktopWindowSizeSchema.optional(),
   desktopChromiumHardwareAccelerationEnabled: z.boolean().optional(),
@@ -521,12 +636,16 @@ export const appSettingsPatchSchema = z.object({
   zcodeInteractionBehavior: zcodeInteractionBehaviorSchema.optional(),
   askUserQuestionAutoResolutionEnabled: z.boolean().optional(),
   modelIoFullRetentionEnabled: z.boolean().optional(),
+  // 空串是「删除选择、回到跟随」的哨兵：RPC 会吞掉 undefined，normalizeSettingsPatch 把它归一成删除。
+  dynamicWorkflowMode: z.union([z.enum(DYNAMIC_WORKFLOW_MODES), z.literal("")]).optional(),
+  enabledBuiltinAgentCliProviders: enabledBuiltinAgentCliProvidersSchema.optional(),
   startPlanRecommendationDismissed: z.boolean().optional(),
   providerFamilyConnectionSelections: providerFamilyConnectionSelectionSettingsSchema.optional(),
   providerFamilyDomain: z.union([providerFamilyDomainSchema, z.literal("")]).optional(),
   providerFamilyDomainUpdatedAt: z.number().int().nonnegative().optional(),
   providerFamilyDomainMigrated: z.boolean().optional(),
   nativeSearchEnhancementsEnabled: z.boolean().optional(),
+  toolSearchMode: appToolSearchModeSchema.optional(),
   onboardingOccupation: z
     .enum([
       "office",
@@ -548,6 +667,17 @@ export const appSettingsPatchSchema = z.object({
   proactiveSuggestionsEnabled: z.boolean().optional(),
   memoryEnabled: z.boolean().optional(),
   lastWorkspaceSession: z.array(appWorkspaceSessionEntrySchema).optional(),
+  lastActiveWorkspace: appWorkspaceSessionEntrySchema.nullable().optional(),
+  remoteConversationWorkspaceBySourceServerId: z
+    .record(nonEmptyStringSchema, remoteConversationWorkspaceRecordSchema)
+    .optional(),
+  sourceServers: z.array(sourceServerRecordSchema).optional(),
+  connectionProfiles: z.array(connectionProfileSchema).optional(),
+  sourceServerWorkspaceHistory: z.array(sourceServerWorkspaceHistoryEntrySchema).optional(),
+  remoteStartupAutoReconnectEnabled: z.boolean().optional(),
+  sourceServerDirectoryMigrationVersion: z.literal(1).optional(),
+  remoteBoundaryOnboardingVersion: z.literal(2).optional(),
+  remoteBoundaryIntroAcknowledgedVersion: z.literal(1).optional(),
   lastActiveTabIndex: z.number().int().nonnegative().optional(),
   lastActiveTaskByWorkspace: z.record(z.string(), z.string()).optional(),
   dataBaseDir: z.string().trim().min(1).optional(),
@@ -558,5 +688,8 @@ export const appSettingsPatchSchema = z.object({
     .partialRecord(electronReleaseChannelSchema, nonEmptyStringSchema)
     .optional(),
   settingsSyncFirstRunPromptHandled: z.boolean().optional(),
+  webRemoteControlRelayV2Device: webRemoteControlRelayV2DeviceSchema.optional(),
+  webRemoteControlExternalRelayDevice: webRemoteControlExternalRelayDeviceSchema.optional(),
+  webRemoteControlLastEnabledContext: webRemoteControlLastEnabledContextSchema.optional(),
   zcodeEndpointOrigin: zcodeEndpointOriginSchema.optional(),
 });

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

@@ -0,0 +1,13 @@
+// 由各 bundler 通过 define 注入，避免运行时 JSON import 的跨 bundler 兼容问题。
+// 非构建环境（如 e2e 测试的 mocha）下 define 不存在，
+// 用 typeof 检查 + fallback 避免 ReferenceError。
+declare const __ZCODE_VERSION__: string;
+declare const __ZCODE_COMMIT__: string;
+declare const __ZCODE_BUILD_TIME__: string;
+
+export const ZCODE_VERSION: string =
+  typeof __ZCODE_VERSION__ !== "undefined" ? __ZCODE_VERSION__ : "0.0.0-dev";
+export const ZCODE_COMMIT: string =
+  typeof __ZCODE_COMMIT__ !== "undefined" ? __ZCODE_COMMIT__ : "unknown";
+export const ZCODE_BUILD_TIME: string =
+  typeof __ZCODE_BUILD_TIME__ !== "undefined" ? __ZCODE_BUILD_TIME__ : "unknown";

package/server/vendor/zcode/packages/shared/src/zcode-agent-policy.ts

@@ -6,7 +6,18 @@ export const ZCODE_AGENT_PROVIDER = "glm" satisfies ZCodeProvider;
 export const ZCODE_AGENT_PROVIDER_LABEL = "ZCode Agent";
 export const ZCODE_COMMAND_AGENT_SOURCE = "zcodeAgent" satisfies CommandAgentSource;
 
-export const zcodeAgentProviderSchema = z.literal(ZCODE_AGENT_PROVIDER);
+/**
+ * 解析持久化/relay 数据时的 provider 归一 schema：
+ * 已移除的第三方 provider 历史值仅作为归一化输入保留，统一收敛为 glm；
+ * 其它非法值保持拒绝，与收窄前的校验边界一致。
+ */
+export const legacyZCodeProviderSchema = z
+  .enum(["claude", "opencode", "gemini", "codex", "glm"])
+  .transform((): typeof ZCODE_AGENT_PROVIDER => ZCODE_AGENT_PROVIDER);
+
+export const ZCODE_ENABLED_AGENT_PROVIDERS = [
+  ZCODE_AGENT_PROVIDER,
+] as const satisfies readonly ZCodeProvider[];
 
 export const ZCODE_COMMAND_AGENT_SOURCES = [
   ZCODE_COMMAND_AGENT_SOURCE,
@@ -18,6 +29,18 @@ export function normalizeAgentProviderToZCodeAgent(
   return ZCODE_AGENT_PROVIDER;
 }
 
+export function normalizeAgentProvidersToZCodeAgent(
+  _providers?: ReadonlyArray<ZCodeProvider> | null,
+): ZCodeProvider[] {
+  return [...ZCODE_ENABLED_AGENT_PROVIDERS];
+}
+
+export function normalizeCommandAgentSourceToZCodeAgent(
+  _agentSource?: CommandAgentSource | null,
+): CommandAgentSource {
+  return ZCODE_COMMAND_AGENT_SOURCE;
+}
+
 export function isZCodeAgentProvider(
   provider: ZCodeProvider | null | undefined,
 ): provider is typeof ZCODE_AGENT_PROVIDER {