paseo-plugin-zcode-provider 0.3.0 → 0.4.1

package/server/vendor/zcode/packages/shared/src/source-server/contracts.ts

@@ -0,0 +1,426 @@
+import { z } from "zod";
+import type { RemoteTarget } from "../remoteTarget.js";
+import { publicZCodeErrorCodeSchema } from "./errorCodes.js";
+import { REMOTE_ASSET_INSTALL_MODES } from "../remoteAssetInstallMode.js";
+import { isKnownRemoteResourcePackageId } from "../remoteResourcePackages.js";
+import { wslUserSchema } from "../wslUserValidation.js";
+import { serverRemoteWorkspaceInfoSchema } from "../server-remote.js";
+
+const nonEmptyStringSchema = z.string().trim().min(1);
+const credentialKeySchema = nonEmptyStringSchema;
+const timestampSchema = z.number().int().nonnegative();
+
+export const sourceServerTransportKindSchema = z.enum(["ssh", "wsl", "docker"]);
+export type SourceServerTransportKind = z.infer<typeof sourceServerTransportKindSchema>;
+
+export const sshProfileTargetSchema = z
+  .object({
+    kind: z.literal("ssh"),
+    host: nonEmptyStringSchema,
+    port: z.number().int().positive().max(65_535).optional(),
+    username: nonEmptyStringSchema,
+    sshConfigAlias: nonEmptyStringSchema.optional(),
+    privateKeyPath: z.string().optional(),
+    assetInstallMode: z.enum(REMOTE_ASSET_INSTALL_MODES).optional(),
+    resourcePackages: z
+      .object({
+        selectedPackageIds: z.array(z.string().refine(isKnownRemoteResourcePackageId)).optional(),
+      })
+      .strict()
+      .optional(),
+    passwordCredentialKey: credentialKeySchema.optional(),
+    privateKeyPassphraseCredentialKey: credentialKeySchema.optional(),
+  })
+  .strict();
+
+export const wslProfileTargetSchema = z
+  .object({
+    kind: z.literal("wsl"),
+    distro: z.string().optional(),
+    user: wslUserSchema.optional(),
+  })
+  .strict();
+
+export const dockerProfileTargetSchema = z
+  .object({
+    kind: z.literal("docker"),
+    container: nonEmptyStringSchema,
+  })
+  .strict();
+
+export const sourceServerProfileTargetSchema = z.discriminatedUnion("kind", [
+  sshProfileTargetSchema,
+  wslProfileTargetSchema,
+  dockerProfileTargetSchema,
+]);
+
+export type SSHProfileTarget = z.infer<typeof sshProfileTargetSchema>;
+export type WSLProfileTarget = z.infer<typeof wslProfileTargetSchema>;
+export type DockerProfileTarget = z.infer<typeof dockerProfileTargetSchema>;
+export type SourceServerProfileTarget = z.infer<typeof sourceServerProfileTargetSchema>;
+
+/** 升级授权只绑定执行身份，不携带凭据或可变 Profile 内容。 */
+export const sourceServerUpdateTargetSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("ssh"),
+      host: nonEmptyStringSchema.toLowerCase(),
+      port: z.number().int().positive().max(65_535).default(22),
+      username: nonEmptyStringSchema,
+      sshConfigAlias: nonEmptyStringSchema.optional(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("wsl"),
+      distro: nonEmptyStringSchema,
+      user: wslUserSchema.refine((value) => value.length > 0),
+    })
+    .strict(),
+  dockerProfileTargetSchema,
+]);
+export type SourceServerUpdateTarget = z.infer<typeof sourceServerUpdateTargetSchema>;
+
+export function getSourceServerUpdateTarget(
+  target: Exclude<RemoteTarget, { kind: "server" }>,
+): SourceServerUpdateTarget {
+  switch (target.kind) {
+    case "ssh":
+      return sourceServerUpdateTargetSchema.parse({
+        kind: target.kind,
+        host: target.host,
+        port: target.port ?? 22,
+        username: target.username,
+        ...(target.sshConfigAlias?.trim() ? { sshConfigAlias: target.sshConfigAlias.trim() } : {}),
+      });
+    case "wsl":
+      return sourceServerUpdateTargetSchema.parse({
+        kind: target.kind,
+        distro: target.distro,
+        user: target.user,
+      });
+    case "docker":
+      return sourceServerUpdateTargetSchema.parse({
+        kind: target.kind,
+        container: target.container,
+      });
+  }
+}
+
+export function isSameSourceServerUpdateTarget(
+  left: Exclude<RemoteTarget, { kind: "server" }>,
+  right: Exclude<RemoteTarget, { kind: "server" }>,
+): boolean {
+  if (
+    [left, right].some(
+      (target) => target.kind === "wsl" && (!target.distro?.trim() || !target.user?.trim()),
+    )
+  )
+    return false;
+  return (
+    JSON.stringify(getSourceServerUpdateTarget(left)) ===
+    JSON.stringify(getSourceServerUpdateTarget(right))
+  );
+}
+
+export const sourceServerUpdateRequestSchema = z
+  .object({
+    profileId: nonEmptyStringSchema,
+    force: z.boolean().optional(),
+    expectedTarget: sourceServerUpdateTargetSchema.optional(),
+  })
+  .strict();
+export type SourceServerUpdateRequest = z.input<typeof sourceServerUpdateRequestSchema>;
+
+const connectionProfileBaseShape = {
+  profileId: z.string().uuid(),
+  sourceServerId: z.string().uuid().optional(),
+  displayName: nonEmptyStringSchema.optional(),
+  lastConnectedAt: timestampSchema.optional(),
+  lastConnectError: z.string().optional(),
+  createdAt: timestampSchema,
+  lifecycleState: z.enum(["active", "retired"]).default("active"),
+  retiredReason: z.literal("source-reinstalled").optional(),
+  retiredAt: timestampSchema.optional(),
+};
+
+export const connectionProfileSchema = z.discriminatedUnion("transport", [
+  z
+    .object({
+      ...connectionProfileBaseShape,
+      transport: z.literal("ssh"),
+      target: sshProfileTargetSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...connectionProfileBaseShape,
+      transport: z.literal("wsl"),
+      target: wslProfileTargetSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...connectionProfileBaseShape,
+      transport: z.literal("docker"),
+      target: dockerProfileTargetSchema,
+    })
+    .strict(),
+]);
+
+export type ConnectionProfile = z.infer<typeof connectionProfileSchema>;
+
+export const sourceServerRecordSchema = z
+  .object({
+    sourceServerId: z.string().uuid(),
+    displayName: nonEmptyStringSchema,
+    osUser: nonEmptyStringSchema.optional(),
+    hostname: nonEmptyStringSchema.optional(),
+    lastSeenVersion: nonEmptyStringSchema.optional(),
+    lastOnlineAt: timestampSchema.optional(),
+    preferredProfileId: z.string().uuid().optional(),
+    installState: z.enum(["installed", "uninstalled"]).default("installed"),
+    declaredWorkspaces: z
+      .array(
+        z
+          .object({
+            workspacePath: nonEmptyStringSchema,
+            workspaceIdentity: nonEmptyStringSchema,
+            label: nonEmptyStringSchema.optional(),
+          })
+          .strict(),
+      )
+      .default([]),
+  })
+  .strict();
+
+export type SourceServerRecord = z.infer<typeof sourceServerRecordSchema>;
+
+export const sourceServerWorkspaceHistoryEntrySchema = z
+  .object({
+    workspacePath: nonEmptyStringSchema,
+    workspaceIdentity: nonEmptyStringSchema.optional(),
+    legacyWorkspaceIdentity: nonEmptyStringSchema.optional(),
+    profileId: z.string().uuid(),
+    sourceServerId: z.string().uuid().optional(),
+    lastOpenedAt: timestampSchema,
+  })
+  .strict();
+
+export type SourceServerWorkspaceHistoryEntry = z.infer<
+  typeof sourceServerWorkspaceHistoryEntrySchema
+>;
+
+export const sourceServerMigrationConflictSchema = z
+  .object({
+    kind: z.enum(["task-identity", "config-file"]),
+    key: nonEmptyStringSchema,
+    taskId: nonEmptyStringSchema.optional(),
+    relativePath: nonEmptyStringSchema.optional(),
+    sourceKey: nonEmptyStringSchema,
+    canonicalKey: nonEmptyStringSchema,
+    reason: nonEmptyStringSchema,
+  })
+  .strict();
+export type SourceServerMigrationConflict = z.infer<typeof sourceServerMigrationConflictSchema>;
+
+export const sourceServerMigrationReportRowSchema = z
+  .object({
+    migrationId: nonEmptyStringSchema,
+    workspacePath: nonEmptyStringSchema,
+    canonicalKey: nonEmptyStringSchema,
+    variantKeys: z.array(nonEmptyStringSchema),
+    status: z.enum(["running", "completed", "failed", "abandoned", "abandoned-diverged"]),
+    phase: nonEmptyStringSchema.optional(),
+    errorCode: nonEmptyStringSchema.optional(),
+    taskBackupPath: nonEmptyStringSchema.optional(),
+    sessionBackupPath: nonEmptyStringSchema.optional(),
+    updatedAt: timestampSchema,
+    abandonedAt: timestampSchema.optional(),
+    abandonedTrigger: nonEmptyStringSchema.optional(),
+    conflicts: z.array(sourceServerMigrationConflictSchema),
+  })
+  .strict();
+export type SourceServerMigrationReportRow = z.infer<typeof sourceServerMigrationReportRowSchema>;
+
+export const sourceServerMigrationReportSchema = z
+  .object({ rows: z.array(sourceServerMigrationReportRowSchema) })
+  .strict();
+export type SourceServerMigrationReport = z.infer<typeof sourceServerMigrationReportSchema>;
+
+export const sourceServerMigrationPathActionSchema = z
+  .object({
+    workspacePath: nonEmptyStringSchema,
+    migrationId: nonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type SourceServerMigrationPathAction = z.infer<typeof sourceServerMigrationPathActionSchema>;
+
+export const sourceServerResolveWorkspaceRequestSchema = z
+  .object({
+    workspacePath: nonEmptyStringSchema,
+    legacyRouteHint: nonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type SourceServerResolveWorkspaceRequest = z.infer<
+  typeof sourceServerResolveWorkspaceRequestSchema
+>;
+
+export const sourceServerResolveWorkspaceResultSchema = z
+  .object({
+    canonicalWorkspaceKey: nonEmptyStringSchema,
+    mergedKeys: z.array(nonEmptyStringSchema),
+    migrationId: nonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type SourceServerResolveWorkspaceResult = z.infer<
+  typeof sourceServerResolveWorkspaceResultSchema
+>;
+
+export const sourceServerConnectionStateSchema = z.enum([
+  "absent",
+  "bootstrapping",
+  "needs-install",
+  "needs-upgrade",
+  "updating",
+  "online",
+  "retrying",
+  "offline",
+  "identity-change-pending",
+  "failed",
+]);
+export type SourceServerConnectionState = z.infer<typeof sourceServerConnectionStateSchema>;
+
+/** 远端任务 owner 的活动投影；身份用于隔离，实际路径仅用于展示。 */
+export const sourceServerRunningTaskSchema = z
+  .object({
+    sessionId: nonEmptyStringSchema,
+    workspacePath: nonEmptyStringSchema,
+    workspaceIdentity: nonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type SourceServerRunningTask = z.infer<typeof sourceServerRunningTaskSchema>;
+export const sourceServerRunningTasksSchema = z.array(sourceServerRunningTaskSchema);
+
+/** 只读安装预览；sizeBytes 是安装包实际大小，不代表解压后的磁盘占用。 */
+export const sourceServerInstallPreviewSchema = z
+  .object({
+    version: nonEmptyStringSchema,
+    installPath: nonEmptyStringSchema.optional(),
+    sizeBytes: z.number().int().positive(),
+  })
+  .strict();
+export type SourceServerInstallPreview = z.infer<typeof sourceServerInstallPreviewSchema>;
+
+export const sourceServerConnectionStateSnapshotSchema = z
+  .object({
+    profileId: z.string().uuid(),
+    sourceServerId: z.string().uuid().optional(),
+    state: sourceServerConnectionStateSchema,
+    error: z.string().optional(),
+    updateAvailability: z.enum(["none", "available", "required"]).optional(),
+    currentVersion: nonEmptyStringSchema.optional(),
+    availableVersion: nonEmptyStringSchema.optional(),
+    minimumVersion: nonEmptyStringSchema.optional(),
+    upgradeTarget: z.enum(["controller", "server"]).optional(),
+    errorCode: publicZCodeErrorCodeSchema.optional(),
+    retryable: z.boolean().optional(),
+    installPreview: sourceServerInstallPreviewSchema.optional(),
+    runningTasks: sourceServerRunningTasksSchema.optional(),
+    pendingSourceServerId: z.string().uuid().optional(),
+    recoveryAttempt: z.number().int().positive().optional(),
+    recoveryLimit: z.number().int().positive().optional(),
+    recoveryBudgetExhausted: z.boolean().optional(),
+    updatedAt: timestampSchema,
+  })
+  .strict();
+export type SourceServerConnectionStateSnapshot = z.infer<
+  typeof sourceServerConnectionStateSnapshotSchema
+>;
+
+export const sourceServerManagementSnapshotRequestSchema = z
+  .object({
+    refreshMigrationCounts: z.boolean().optional(),
+  })
+  .strict();
+export type SourceServerManagementSnapshotRequest = z.infer<
+  typeof sourceServerManagementSnapshotRequestSchema
+>;
+
+export const sourceServerManagementSnapshotSchema = z
+  .object({
+    generation: z.number().int().nonnegative(),
+    profiles: z.array(connectionProfileSchema),
+    servers: z.array(sourceServerRecordSchema),
+    workspaceHistory: z.array(sourceServerWorkspaceHistoryEntrySchema),
+    states: z.array(sourceServerConnectionStateSnapshotSchema),
+    failedPathCount: z.number().int().nonnegative(),
+    abandonedPathCount: z.number().int().nonnegative(),
+    migrationCounts: z.array(
+      z.discriminatedUnion("status", [
+        z
+          .object({
+            sourceServerId: nonEmptyStringSchema,
+            status: z.literal("available"),
+            failedPathCount: z.number().int().nonnegative(),
+            abandonedPathCount: z.number().int().nonnegative(),
+          })
+          .strict(),
+        z
+          .object({
+            sourceServerId: nonEmptyStringSchema,
+            status: z.literal("requires-connection"),
+          })
+          .strict(),
+        z.object({ sourceServerId: nonEmptyStringSchema, status: z.literal("loading") }).strict(),
+        z
+          .object({ sourceServerId: nonEmptyStringSchema, status: z.literal("unavailable") })
+          .strict(),
+      ]),
+    ),
+  })
+  .strict();
+export type SourceServerManagementSnapshot = z.infer<typeof sourceServerManagementSnapshotSchema>;
+
+export const sourceServerManagementStateDeltaSchema = z
+  .object({
+    generation: z.number().int().positive(),
+    state: sourceServerConnectionStateSnapshotSchema,
+  })
+  .strict();
+export type SourceServerManagementStateDelta = z.infer<
+  typeof sourceServerManagementStateDeltaSchema
+>;
+
+export const sourceServerManagementDirectoryDeltaSchema = z
+  .object({
+    generation: z.number().int().positive(),
+  })
+  .strict();
+export type SourceServerManagementDirectoryDelta = z.infer<
+  typeof sourceServerManagementDirectoryDeltaSchema
+>;
+
+/** Server CLI 的可选逐行进度；终态仍由退出码和最后一行结果决定。 */
+export const sourceServerInstallProgressSchema = z
+  .object({
+    type: z.literal("source-server-install-progress"),
+    phase: z.enum(["verify-archive", "extract", "verify", "restart"]),
+  })
+  .strict();
+export type SourceServerInstallProgress = z.infer<typeof sourceServerInstallProgressSchema>;
+
+export const sourceServerOperationLogSchema = z
+  .object({
+    profileId: z.string().uuid(),
+    operation: z.enum(["connect", "update"]),
+    phase: nonEmptyStringSchema,
+    level: z.enum(["info", "warn", "error"]),
+    message: z.string(),
+    progress: z.number().min(0).max(1).optional(),
+    timestamp: timestampSchema,
+  })
+  .strict();
+export type SourceServerOperationLog = z.infer<typeof sourceServerOperationLogSchema>;
+
+export type SourceServerDeclaredWorkspaceWire = z.infer<typeof serverRemoteWorkspaceInfoSchema>;

package/server/vendor/zcode/packages/shared/src/source-server/errorCodes.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+export const SOURCE_SERVER_INSTALL_REQUIRED_ERROR_CODE =
+  "source-server-install-required" as const;
+export const SOURCE_SERVER_UPGRADE_REQUIRED_ERROR_CODE =
+  "source-server-upgrade-required" as const;
+export const SOURCE_SERVER_UPDATE_RUNNING_TASKS_ERROR_CODE =
+  "source-server-update-running-tasks" as const;
+export const WORKSPACE_TASK_IDENTITY_CONFLICT_ERROR_CODE =
+  "workspace-task-identity-conflict" as const;
+export const WORKSPACE_CONFIG_FILE_CONFLICT_ERROR_CODE =
+  "workspace-config-file-conflict" as const;
+export const WORKSPACE_MIGRATION_PLAN_DIVERGED_ERROR_CODE =
+  "workspace-migration-plan-diverged" as const;
+export const WORKSPACE_SESSION_GENERATION_CHANGED_ERROR_CODE =
+  "workspace-session-generation-changed" as const;
+export const REMOTE_BIND_CANCELED_ERROR_CODE = "remote-bind-canceled" as const;
+export const REMOTE_WORKSPACE_BIND_SESSION_MISSING_ERROR_CODE =
+  "remote-workspace-bind-session-missing" as const;
+export const REMOTE_WORKSPACE_DIRECTORY_UNAVAILABLE_ERROR_CODE =
+  "remote-workspace-directory-unavailable" as const;
+export const REMOTE_RECOVERY_BUDGET_EXHAUSTED_ERROR_CODE =
+  "remote-recovery-budget-exhausted" as const;
+export const SOURCE_SERVER_IDENTITY_CHANGE_PENDING_ERROR_CODE =
+  "source-server-identity-change-pending" as const;
+export const SOURCE_SERVER_REMOVE_CALLBACK_MISSING_ERROR_CODE =
+  "source-server-remove-callback-missing" as const;
+export const SOURCE_SERVER_REMOVE_CALLBACK_FAILED_ERROR_CODE =
+  "source-server-remove-callback-failed" as const;
+export const SOURCE_SERVER_REMOVE_PERSIST_FAILED_ERROR_CODE =
+  "source-server-remove-persist-failed" as const;
+
+export const PUBLIC_ZCODE_ERROR_CODES = [
+  "remote-authentication-failed",
+  "remote-host-unreachable",
+  "remote-connection-timeout",
+  "remote-host-not-found",
+  "remote-host-key-changed",
+  "remote-download-failed",
+  "remote-upload-failed",
+  "remote-preflight-failed",
+  "remote-install-failed",
+  "remote-space-insufficient",
+  "remote-permission-denied",
+  "remote-connection-canceled",
+  "remote-connection-unknown",
+  SOURCE_SERVER_INSTALL_REQUIRED_ERROR_CODE,
+  SOURCE_SERVER_UPGRADE_REQUIRED_ERROR_CODE,
+  SOURCE_SERVER_UPDATE_RUNNING_TASKS_ERROR_CODE,
+  WORKSPACE_TASK_IDENTITY_CONFLICT_ERROR_CODE,
+  WORKSPACE_CONFIG_FILE_CONFLICT_ERROR_CODE,
+  WORKSPACE_MIGRATION_PLAN_DIVERGED_ERROR_CODE,
+  WORKSPACE_SESSION_GENERATION_CHANGED_ERROR_CODE,
+  REMOTE_BIND_CANCELED_ERROR_CODE,
+  REMOTE_WORKSPACE_BIND_SESSION_MISSING_ERROR_CODE,
+  REMOTE_WORKSPACE_DIRECTORY_UNAVAILABLE_ERROR_CODE,
+  REMOTE_RECOVERY_BUDGET_EXHAUSTED_ERROR_CODE,
+  SOURCE_SERVER_IDENTITY_CHANGE_PENDING_ERROR_CODE,
+  SOURCE_SERVER_REMOVE_CALLBACK_MISSING_ERROR_CODE,
+  SOURCE_SERVER_REMOVE_CALLBACK_FAILED_ERROR_CODE,
+  SOURCE_SERVER_REMOVE_PERSIST_FAILED_ERROR_CODE,
+] as const;
+
+export type PublicZCodeErrorCode = (typeof PUBLIC_ZCODE_ERROR_CODES)[number];
+
+export const publicZCodeErrorCodeSchema = z.enum(PUBLIC_ZCODE_ERROR_CODES);
+
+const publicZCodeErrorCodeSet = new Set<string>(PUBLIC_ZCODE_ERROR_CODES);
+
+export function isPublicZCodeErrorCode(
+  value: unknown,
+): value is PublicZCodeErrorCode {
+  return typeof value === "string" && publicZCodeErrorCodeSet.has(value);
+}

package/server/vendor/zcode/packages/shared/src/sqlite-migrations/contract.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import type { DatabaseSync } from "node:sqlite";
+
+/** 历史 SQL 是 checksum 输入，发布后不可修改；apply 只供带数据回填的迁移使用。 */
+export interface SqliteMigration {
+  id: string;
+  /** 开发分支迁移后移时沿用旧记账；所有已存在别名必须具有相同 SQL checksum。 */
+  previousIds?: readonly string[];
+  appVersion: string;
+  sql: string;
+  touchedTables: readonly string[];
+  apply?: (db: DatabaseSync) => void;
+}
+
+export interface MigrationBackupTable {
+  name: string;
+  columns: string[];
+  rows: number;
+  hash: string;
+}
+
+export interface MigrationBackup {
+  version: 1;
+  database: string;
+  journalTable?: "schema_migration" | "tasks_schema_migration";
+  migrations: string[];
+  tables: MigrationBackupTable[];
+  skipped?: "insufficient-space";
+}
+
+export interface MigrationOptions {
+  database: string;
+  transactionOpen?: boolean;
+  onBeforeApply?: (migrationId: string) => void | Promise<void>;
+  onApplied?: (migrationId: string) => void;
+  onCommitting?: () => void | Promise<void>;
+  /** 保留已发布 Host 任务库的三列记账结构；默认使用 CLI/项目四列结构。 */
+  journalTable?: "schema_migration" | "tasks_schema_migration";
+  /** 按优先级排列的可写卷目录；首项通常是 ~/.zcode/backup。 */
+  backupDirectories: readonly string[];
+  /** 首选卷失败后探测；默认枚举平台已挂载卷，测试可注入受控临时目录。 */
+  fallbackBackupDirectories?: () => Promise<readonly string[]>;
+  /** 兼容现有 CLI schema_migration 列名，app 采用 applied_at。 */
+  appliedAtColumn?: "time_applied" | "applied_at";
+  now?: () => number;
+  onBackupSkipped?: (backup: MigrationBackup) => void;
+}
+
+export interface MigrationResult {
+  applied: string[];
+  backupPath?: string;
+  backupSkipped: boolean;
+}
+
+export class MigrationChecksumError extends Error {
+  constructor(readonly migrationId: string) {
+    super(`Migration checksum mismatch: ${migrationId}`);
+    this.name = "MigrationChecksumError";
+  }
+}
+
+export interface SqliteMigrationsContract {
+  /** 串行 admission、校验 checksum、表级备份、单事务迁移；失败回滚并抛错。 */
+  migrate(
+    db: DatabaseSync,
+    migrations: readonly SqliteMigration[],
+    options: MigrationOptions,
+  ): Promise<MigrationResult>;
+  /** 工程恢复：停用业务写者后调用；关闭外键防级联，逐表验证，失败回滚。 */
+  restore(db: DatabaseSync, backupPath: string): Promise<void>;
+}
+
+/** 建窗前的一次性 CLI 命令；不进入会话/消息协议。 */
+export const STORAGE_MIGRATION_COMMAND = "storage-migrate";
+export const storageMigrationReportSchema = z
+  .object({
+    version: z.literal(1),
+    kind: z.literal("storage-migrated"),
+    applied: z.array(z.string()),
+    backupPath: z.string().optional(),
+    backupSkipped: z.boolean(),
+  })
+  .strict();

package/server/vendor/zcode/packages/shared/src/subagent-profile.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { modelSelectionSchema, type ModelSelection } from "./model-selection.js";
+import type { AgentPermissionMode } from "./subagents-types.js";
+
+export type AgentProfileSource = "built-in" | "project" | "user";
+export type AgentMemoryScope = "user" | "project" | "local";
+
+export interface AgentProfile {
+  background?: boolean;
+  color?: "red" | "blue" | "green" | "yellow" | "purple" | "orange" | "pink" | "cyan";
+  description: string;
+  disallowedTools?: readonly string[];
+  injectAgentsMd?: boolean;
+  maxTurns?: number;
+  mcpServers?: readonly string[];
+  memory?: AgentMemoryScope;
+  modelSelection?: ModelSelection;
+  name: string;
+  path?: string;
+  permissionMode?: AgentPermissionMode;
+  skills?: readonly string[];
+  source: AgentProfileSource;
+  systemPrompt: string;
+  tools?: readonly string[];
+}
+
+export interface AgentProfileParseDiagnostic {
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface AgentProfileLoadResult {
+  diagnostics: AgentProfileParseDiagnostic[];
+  profiles: AgentProfile[];
+}
+
+/** 完整运行时 profile 的跨进程边界，不使用 Settings 摘要代替。 */
+export const agentProfileSchema = z
+  .object({
+    name: z.string().min(1),
+    description: z.string(),
+    source: z.enum(["built-in", "project", "user"]),
+    systemPrompt: z.string(),
+    path: z.string().optional(),
+    modelSelection: modelSelectionSchema.optional(),
+    background: z.boolean().optional(),
+    injectAgentsMd: z.boolean().optional(),
+    color: z
+      .enum(["red", "blue", "green", "yellow", "purple", "orange", "pink", "cyan"])
+      .optional(),
+    permissionMode: z
+      .enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "plan"])
+      .optional(),
+    memory: z.enum(["user", "project", "local"]).optional(),
+    maxTurns: z.number().int().positive().optional(),
+    tools: z.array(z.string()).readonly().optional(),
+    disallowedTools: z.array(z.string()).readonly().optional(),
+    skills: z.array(z.string()).readonly().optional(),
+    mcpServers: z.array(z.string()).readonly().optional(),
+  })
+  .strict();

package/server/vendor/zcode/packages/shared/src/subagent-runtime-config.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { modelSelectionSchema } from "./model-selection.js";
+import { agentProfileSchema, type AgentProfile } from "./subagent-profile.js";
+import { createAgentStateId } from "./subagents-types.js";
+
+export const subagentRuntimeStateSchema = z
+  .object({
+    disabledAgentIds: z.array(z.string()),
+    builtInModelSelectionOverrides: z
+      .object({
+        Explore: modelSelectionSchema.optional(),
+        "general-purpose": modelSelectionSchema.optional(),
+      })
+      .strict(),
+    pluginAgentModelSelectionOverrides: z.record(z.string(), modelSelectionSchema),
+  })
+  .strict();
+export type SubagentRuntimeState = z.infer<typeof subagentRuntimeStateSchema>;
+
+/** snapshot 已经解析；读取失败的回退与 RPC 断连错误不能混为一谈。 */
+export const subagentRuntimeConfigSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("ready"),
+      profiles: z.array(agentProfileSchema.refine((profile) => profile.source !== "built-in")),
+      builtInModelSelectionOverrides:
+        subagentRuntimeStateSchema.shape.builtInModelSelectionOverrides,
+      pluginAgentModelSelectionOverrides:
+        subagentRuntimeStateSchema.shape.pluginAgentModelSelectionOverrides,
+    })
+    .strict(),
+  z.object({ kind: z.literal("built-in-fallback") }).strict(),
+]);
+export type SubagentRuntimeConfig = z.infer<typeof subagentRuntimeConfigSchema>;
+
+/** 仅从解析缓存组合结果；启停变化不重新读取或解析 Markdown。 */
+export function resolveSubagentRuntimeProfiles(
+  profiles: readonly AgentProfile[],
+  state: SubagentRuntimeState,
+) {
+  const disabled = new Set(state.disabledAgentIds);
+  return {
+    profiles: profiles.filter(
+      (profile) =>
+        profile.source !== "user" ||
+        !disabled.has(createAgentStateId({ name: profile.name, scope: "user", source: "user" })),
+    ),
+    builtInModelSelectionOverrides: state.builtInModelSelectionOverrides,
+    pluginAgentModelSelectionOverrides: state.pluginAgentModelSelectionOverrides,
+  };
+}