feat(server): W2-D agent assembly, session API, runAgent/resolveDecision and backend e2e

- Capabilities: all 14 registered (AO: inventory.query, download.plan/submit, organize.plan/execute,
  policy.preview/apply; agent: task.inspect/retry/cancel); startup asserts count == 14.
  Registry injects server-side authorize (automation_grant by action/scope/policy version/budget,
  one-shot approval bound to plan id + payload hash + revision + expiry; model claims ignored;
  automation switch), audit_event, server idempotency keys and a capability_invocation op ledger
  (migration 0021) used for crash reconciliation. download.plan creates draft plans only;
  download.submit promotes draft -> reserved after authorization.
- Agent session API: POST/GET /agent/runs, GET /agent/runs/{id} (events by seq, messages, report),
  POST .../messages (wake), POST .../abort; automation-grants, approvals, capabilities invoke, tasks.
- runAgent task: Pi or fake provider from settings (apiKey via secrets), events persisted to
  agent_run_event then published, resume + ledger reconciliation when pendingOperations > 0,
  waits for goal-linked downloads/imports and reports from business tables (submitted != imported).
- Background triggers: decision.created -> bounded plan_only investigation (dedupe per decision);
  decision.updated(resolved) -> resolveDecision executes chosen option.
- W2 closure: all OpenAPI routes registered in contracts api.ts (+ subset test); TMDB key from
  settings secret_ref with env fallback; PUT /sites/{id}/credentials documented as alias of
  /site-accounts; completion events documented as existing status events.
- e2e (real PG + OpenWorkflow + testkit mocks): RSS->library, agent delegation with grant/deny,
  background continuation, worker kill -9 recovery (single qB add), auto investigation dedupe.

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

packages/contracts/src/settings.ts

@@ -68,6 +68,47 @@ export const PiSettings = z.object({
 });
 export type PiSettings = z.infer<typeof PiSettings>;
 
+/**
+ * Agent 运行参数(REQ §10.5、§10.7):单次运行预算、后台自动调查、fake 演示脚本。
+ * 上游/模型/思考档位在 pi 分组;pi.provider = "fake" 时使用脚本化假模型(不联网,演示与 e2e 用)。
+ */
+export const AgentRuntimeSettings = z.object({
+  /** 识别歧义 / 下载失败诊断等待处理事项创建时,自动发起有界只读调查 */
+  autoInvestigate: z.boolean(),
+  /** 单次运行:工具调用次数上限 */
+  maxToolCalls: z.number().int().min(1).max(500),
+  /** 单次运行:时长上限(秒) */
+  maxDurationSec: z
+    .number()
+    .int()
+    .min(10)
+    .max(24 * 3600),
+  /** 单次运行:token 上限(null = 不限) */
+  maxTokensPerRun: z.number().int().positive().nullable(),
+  /** 单次运行:费用上限(美元,null = 不限) */
+  maxCostUsdPerRun: z.number().positive().nullable(),
+  /** 后台自动调查的工具调用上限(比用户委托更小) */
+  investigateMaxToolCalls: z.number().int().min(1).max(100),
+  /** 等待目标关联的下载/入库结束时的轮询间隔(秒) */
+  goalPollSec: z.number().int().min(1).max(3600),
+  /** 等待目标完成的最长时间(小时),超时后以"仍在等待"汇报结束 */
+  goalWaitHours: z
+    .number()
+    .min(0)
+    .max(24 * 30),
+  /** fake 模式脚本(JSON,FakeScript 的可序列化子集);null 用内置演示脚本 */
+  fakeScript: z.string().max(100_000).nullable(),
+});
+export type AgentRuntimeSettings = z.infer<typeof AgentRuntimeSettings>;
+
+/** 元数据源(TMDB):密钥只存 secret 引用;未配置时回退环境变量 TMDB_API_KEY / TMDB_ACCESS_TOKEN */
+export const MetadataSettings = z.object({
+  tmdbApiKeySecretRef: Id.nullable(),
+  /** 自建反代或测试 mock;null 用官方地址 */
+  tmdbBaseUrl: z.url().nullable(),
+});
+export type MetadataSettings = z.infer<typeof MetadataSettings>;
+
 /** 每日预算与并发(REQ §6.4、§10.5) */
 export const BudgetSettings = z.object({
   maxNewTitlesPerDay: z.number().int().min(0),
@@ -85,6 +126,8 @@ export const GlobalSettings = z.object({
   retention: RetentionSettings,
   pi: PiSettings,
   budget: BudgetSettings,
+  agent: AgentRuntimeSettings,
+  metadata: MetadataSettings,
 });
 export type GlobalSettings = z.infer<typeof GlobalSettings>;
 
@@ -115,6 +158,18 @@ export const DEFAULT_SETTINGS: GlobalSettings = {
     agentMaxRunsPerDay: 50,
     agentMaxCostUsdPerDay: 5,
   },
+  agent: {
+    autoInvestigate: false,
+    maxToolCalls: 40,
+    maxDurationSec: 900,
+    maxTokensPerRun: null,
+    maxCostUsdPerRun: null,
+    investigateMaxToolCalls: 8,
+    goalPollSec: 60,
+    goalWaitHours: 72,
+    fakeScript: null,
+  },
+  metadata: { tmdbApiKeySecretRef: null, tmdbBaseUrl: null },
 };
 
 /** PATCH /settings:按分组部分更新;服务端与现值合并后用 GlobalSettings 整体再校验 */
@@ -132,12 +187,21 @@ export const GlobalSettingsUpdate = z.object({
     })
     .optional(),
   budget: BudgetSettings.partial().optional(),
+  agent: AgentRuntimeSettings.partial().optional(),
+  metadata: MetadataSettings.omit({ tmdbApiKeySecretRef: true })
+    .partial()
+    .extend({
+      /** 只写:TMDB API Key(v3 key 或 v4 read token),服务端存为 secret 并回填 tmdbApiKeySecretRef;null 清除 */
+      tmdbApiKey: z.string().min(1).max(4096).nullable().optional(),
+    })
+    .optional(),
 });
 export type GlobalSettingsUpdate = z.infer<typeof GlobalSettingsUpdate>;
 
 /** 合并部分更新(纯函数,web 乐观更新与 server 共用) */
 export function mergeSettings(current: GlobalSettings, patch: GlobalSettingsUpdate): GlobalSettings {
   const { apiKey: _apiKey, compaction, ...pi } = patch.pi ?? {};
+  const { tmdbApiKey: _tmdbApiKey, ...metadata } = patch.metadata ?? {};
   return {
     automation: { ...current.automation, ...patch.automation },
     cache: { ...current.cache, ...patch.cache },
@@ -145,6 +209,8 @@ export function mergeSettings(current: GlobalSettings, patch: GlobalSettingsUpda
     retention: { ...current.retention, ...patch.retention },
     pi: { ...current.pi, ...pi, compaction: { ...current.pi.compaction, ...compaction } },
     budget: { ...current.budget, ...patch.budget },
+    agent: { ...current.agent, ...patch.agent },
+    metadata: { ...current.metadata, ...metadata },
   };
 }