feat(contracts,db): Pi upstream contracts and pi_upstream table

- contracts/pi.ts: 41 builtin provider ids + openai-compatible + fake, auth kinds,
  upstream row/view/create/update, provider capability table (oauth modes, termsNote),
  test/models/oauth start/complete schemas
- settings.pi gains defaultUpstreamId; legacy single-upstream fields kept for fallback
- api.ts: /pi/providers, /pi/upstreams CRUD, test, models, oauth start/complete/logout
  (writes and login are console-session only)
- migration 0027: pi_upstream, agent_run.upstream_id, one-time conversion of saved
  legacy settings.pi into a default upstream

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

packages/contracts/test/db-sync.test.ts

@@ -39,7 +39,8 @@ type Obj = z.ZodObject;
 const ROWS: Record<string, { row: Obj; dbOnly?: string[]; apiOnly?: string[] }> = {
   AcquisitionPlan: { row: C.AcquisitionPlan },
   AcquisitionSlot: { row: C.AcquisitionSlot, apiOnly: ["currentAsset"] },
-  AgentRun: { row: C.AgentRun },
+  // upstream_id 只在服务端使用(runAgent 选上游),不在 AgentRun 视图里
+  AgentRun: { row: C.AgentRun, dbOnly: ["upstreamId"] },
   AgentRunEvent: { row: C.AgentRunEventRow },
   AgentRunMessage: { row: C.AgentRunMessage },
   CapabilityInvocation: { row: C.CapabilityInvocation },
@@ -99,6 +100,8 @@ const ROWS: Record<string, { row: Obj; dbOnly?: string[]; apiOnly?: string[] }>
   SlotDeferral: { row: C.SlotDeferral },
   SlotUnit: { row: C.SlotUnit },
   SubscriptionHistory: { row: C.SubscriptionHistory },
+  // W7-A Pi 上游(0027):secret_ref 不出 API
+  PiUpstream: { row: C.PiUpstreamRow, dbOnly: ["secretRef"] },
 };
 
 /** 引擎自有表(@umt/tasks 内部使用,不经 API 暴露),不要求 Row schema */
@@ -191,6 +194,9 @@ const ENUMS: Record<string, z.ZodEnum> = {
   ReconcileRunMode: C.ReconcileMode,
   ReconcileRunStatus: C.ReconcileStatus,
   SecretPurpose: C.SecretPurpose,
+  PiUpstreamAuthKind: C.PiAuthKind,
+  PiUpstreamStatus: C.PiUpstreamStatus,
+  PiUpstreamThinkingLevel: C.PiThinkingLevel,
   ServerMappingItemType: C.ServerItemType,
   ServerMappingMatchStatus: C.ServerMatchStatus,
   SiteAdapter: C.SiteAdapter,

packages/contracts/test/pi.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import * as C from "../src/index.ts";
+
+// W7-A Pi 上游合同:跨字段约束的正反例、设置兼容。
+
+describe("PiUpstreamCreate", () => {
+  const ok = (v: unknown) => C.PiUpstreamCreate.safeParse(v).success;
+
+  it("正例:api_key / oauth / none / 自定义端点", () => {
+    expect(ok({ name: "OpenAI 主号", provider: "openai", authKind: "api_key", apiKey: "sk-1" })).toBe(true);
+    expect(ok({ name: "Codex", provider: "openai-codex", authKind: "oauth", thinkingLevel: "max" })).toBe(true);
+    expect(
+      ok({
+        name: "Bedrock",
+        provider: "amazon-bedrock",
+        authKind: "none",
+        extra: { env: { AWS_REGION: "us-east-1" } },
+      }),
+    ).toBe(true);
+    expect(
+      ok({
+        name: "本地 vLLM",
+        provider: "openai-compatible",
+        authKind: "none",
+        baseUrl: "http://llm.local/v1",
+        defaultModel: "qwen3",
+        extra: { api: "openai-completions", compat: { supportsDeveloperRole: false } },
+      }),
+    ).toBe(true);
+    expect(ok({ name: "fake", provider: "fake", authKind: "none" })).toBe(true);
+  });
+
+  it("反例:未知 provider、oauth 带 apiKey / baseUrl、自定义端点缺 baseUrl 或模型、extra 多余字段、名字为空", () => {
+    expect(ok({ name: "x", provider: "google-gemini-cli", authKind: "oauth" })).toBe(false);
+    expect(ok({ name: "x", provider: "anthropic", authKind: "oauth", apiKey: "sk" })).toBe(false);
+    expect(ok({ name: "x", provider: "anthropic", authKind: "oauth", baseUrl: "https://p.local" })).toBe(false);
+    expect(ok({ name: "x", provider: "openai-compatible", authKind: "api_key", defaultModel: "m" })).toBe(false);
+    expect(ok({ name: "x", provider: "openai-compatible", authKind: "api_key", baseUrl: "http://a/v1" })).toBe(false);
+    expect(ok({ name: "x", provider: "openai", authKind: "api_key", extra: { secret: "sk" } })).toBe(false);
+    expect(ok({ name: "  ", provider: "openai", authKind: "api_key" })).toBe(false);
+    expect(ok({ name: "x", provider: "openai", authKind: "token" })).toBe(false);
+  });
+
+  it("provider 枚举 = 41 个内置 + openai-compatible + fake", () => {
+    expect(C.PI_BUILTIN_PROVIDER_IDS).toHaveLength(41);
+    expect(C.PiProviderId.options).toHaveLength(43);
+  });
+});
+
+describe("OAuth 请求", () => {
+  it("start/complete 的边界", () => {
+    expect(C.PiOAuthStartRequest.safeParse({}).success).toBe(true);
+    expect(C.PiOAuthStartRequest.safeParse({ mode: "popup" }).success).toBe(false);
+    expect(C.PiOAuthCompleteRequest.safeParse({ sessionId: "s" }).success).toBe(true);
+    expect(C.PiOAuthCompleteRequest.safeParse({ sessionId: "s", waitMs: 120_000 }).success).toBe(false);
+    expect(C.PiOAuthCompleteRequest.safeParse({ pastedUrlOrCode: "x" }).success).toBe(false);
+  });
+});
+
+describe("settings.pi 兼容", () => {
+  it("缺省 defaultUpstreamId = null;旧字段仍可读写;PATCH 不能直接改 defaultUpstreamId", () => {
+    expect(C.DEFAULT_SETTINGS.pi.defaultUpstreamId).toBeNull();
+    expect(C.GlobalSettings.safeParse(C.DEFAULT_SETTINGS).success).toBe(true);
+    const patch = C.GlobalSettingsUpdate.parse({
+      pi: { defaultUpstreamId: "7d3f7f5e-8a8c-4b8e-9f0a-1b2c3d4e5f60", provider: "fake", contextBudget: 64_000 },
+    });
+    expect(patch.pi).toEqual({ provider: "fake", contextBudget: 64_000 });
+    const current = { ...C.DEFAULT_SETTINGS, pi: { ...C.DEFAULT_SETTINGS.pi, defaultUpstreamId: "keep-me" } };
+    expect(C.mergeSettings(current as never, patch).pi.defaultUpstreamId).toBe("keep-me");
+  });
+});