refactor(agent): runAgent uses Agent upstreams only; deprecate legacy settings.pi fields

pi.provider / baseUrl / model / thinkingLevel / apiKeySecretRef are now
DEPRECATED_SETTINGS_FIELDS: kept in the schema for stored JSON, dropped
from PATCH /settings and from the settings sections, never read by the
server. runAgent fails with a clear message when no upstream is set.
The agent demo gate checks the default upstream provider; e2e seeds a
fake upstream as default. OpenAPI summaries say Agent upstream.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/contracts/src/settings.ts

@@ -54,13 +54,14 @@ export type ThinkingLevel = z.infer<typeof ThinkingLevel>;
  * Pi Agent 设置(REQ §10.5)。W7-A 起上游改为 pi_upstream 表(多上游共存,见 contracts/pi.ts 与 /pi/upstreams),
  * 这里只留默认上游与运行预算(上下文预算/压缩/子代理)。
  *
- * provider / baseUrl / model / thinkingLevel / apiKeySecretRef 是 v0.1 的旧字段:0027 迁移把已保存的旧值转成一条上游
- * 并设为默认;之后仅在 defaultUpstreamId 为 null 时作为兼容回退(provider = "fake" 的 e2e/演示也走这里)。
+ * provider / baseUrl / model / thinkingLevel / apiKeySecretRef 是 v0.1 的旧字段(DEPRECATED_SETTINGS_FIELDS):
+ * 0027 迁移已把保存的旧值转成一条上游并设为默认。W8-A 起服务端不再读取、PATCH 不再接受(传了会被丢弃),
+ * 设置页不展示;保留在 schema 里只为兼容已存的 JSON。runAgent 只走上游,没有上游直接失败。
  */
 export const PiSettings = z.object({
-  /** 缺省上游(runAgent 未指定 upstreamId 时使用);null = 回退到旧字段 */
+  /** 缺省上游(runAgent 未指定 upstreamId 时使用);null = 未配置,Agent 运行直接失败 */
   defaultUpstreamId: Id.nullable(),
-  /** @deprecated 旧字段,见上 */
+  /** @deprecated 旧字段,不再读取,见上 */
   provider: z.string().min(1),
   /** @deprecated */
   baseUrl: z.url().nullable(),
@@ -226,14 +227,22 @@ export const GlobalSettingsUpdate = z.object({
   cache: CacheShape.partial().optional(),
   organize: OrganizeSettings.partial().optional(),
   retention: RetentionSettings.partial().optional(),
-  /** defaultUpstreamId 只能经 /pi/upstreams(makeDefault)修改,保证指向存在的上游 */
-  pi: PiSettings.omit({ apiKeySecretRef: true, defaultUpstreamId: true })
+  /**
+   * defaultUpstreamId 只能经 /pi/upstreams(makeDefault)修改,保证指向存在的上游;
+   * 旧字段(provider / baseUrl / model / thinkingLevel / apiKey)不再接受,传了会被丢弃。
+   */
+  pi: PiSettings.omit({
+    apiKeySecretRef: true,
+    defaultUpstreamId: true,
+    provider: true,
+    baseUrl: true,
+    model: true,
+    thinkingLevel: true,
+  })
     .partial()
     .extend({
       compaction: PiSettings.shape.compaction.partial().optional(),
       subagents: PiSettings.shape.subagents.partial().optional(),
-      /** 只写:明文上游密钥,服务端存为 secret 并回填 apiKeySecretRef;传 null 表示清除 */
-      apiKey: z.string().min(1).max(4096).nullable().optional(),
     })
     .optional(),
   budget: BudgetSettings.partial().optional(),
@@ -250,7 +259,7 @@ export type GlobalSettingsUpdate = z.infer<typeof GlobalSettingsUpdate>;
 
 /** 合并部分更新(纯函数,web 乐观更新与 server 共用) */
 export function mergeSettings(current: GlobalSettings, patch: GlobalSettingsUpdate): GlobalSettings {
-  const { apiKey: _apiKey, compaction, subagents, ...pi } = patch.pi ?? {};
+  const { compaction, subagents, ...pi } = patch.pi ?? {};
   const { tmdbApiKey: _tmdbApiKey, ...metadata } = patch.metadata ?? {};
   return {
     automation: { ...current.automation, ...patch.automation },
@@ -290,8 +299,17 @@ export const SettingEntry = z.object({
 });
 export type SettingEntry = z.infer<typeof SettingEntry>;
 
+/** 已弃用、不归属任何设置分区的旧字段(见 PiSettings 注释) */
+export const DEPRECATED_SETTINGS_FIELDS = [
+  "pi.provider",
+  "pi.baseUrl",
+  "pi.model",
+  "pi.thinkingLevel",
+  "pi.apiKeySecretRef",
+] as const;
+
 // ── 设置页分区(docs/design/console-ia.md §3.4) ──
-// 只是"展示分区 → 字段"的映射,不改存储 key;每个字段恰好归属一个分区(测试断言)。
+// 只是"展示分区 → 字段"的映射,不改存储 key;除 DEPRECATED_SETTINGS_FIELDS 外每个字段恰好归属一个分区(测试断言)。
 // 非 settings 表的对象(实例、站点、API Key、Pi 上游、账户)用 resources 标注,不进 fields。
 
 export const SettingsSectionId = z.enum([
@@ -413,15 +431,10 @@ export const SETTINGS_SECTIONS: readonly SettingsSectionDef[] = [
     ],
     fields: [
       "pi.defaultUpstreamId",
-      "pi.provider",
-      "pi.baseUrl",
-      "pi.model",
-      "pi.thinkingLevel",
       "pi.contextBudget",
       "pi.compaction",
       "pi.subagentsEnabled",
       "pi.subagents",
-      "pi.apiKeySecretRef",
       "budget.agentMaxRunsPerDay",
       "budget.agentMaxCostUsdPerDay",
       "agent.autoInvestigate",