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]>

apps/server/src/modules/agent/http.ts

@@ -0,0 +1,68 @@
+import { createRoute, type RouteConfig } from "@hono/zod-openapi";
+import { type Actor, type ApiScope, apiResponse, type EndpointDef } from "@umt/contracts";
+import type { Context } from "hono";
+import type { z } from "zod";
+import { type AuthEnv, requireScope } from "../../http/auth.ts";
+import type { ModuleApp } from "../types.ts";
+
+// 本模块路由封装:吃 contracts 的 EndpointDef(Api.xxx),createRoute 进 OpenAPI + requireScope + 入参校验,
+// 出参按合同 parse(剥掉多余列)。
+
+// crud() 生成的端点 schema 类型被擦成 z.ZodType(输出 unknown):这时退化为 any,处理器按合同自行使用
+// biome-ignore lint/suspicious/noExplicitAny: 见上
+type Loose<O> = unknown extends O ? any : O;
+type Infer<T> = T extends z.ZodType ? Loose<z.infer<T>> : Record<string, never>;
+
+export interface Input<D extends EndpointDef> {
+  params: Infer<D["params"]>;
+  query: Infer<D["query"]>;
+  body: Infer<D["body"]>;
+  actor: Actor;
+  /** 能力/审计用的调用者 ID:管理员会话 user:<id>,API Key api_key:<id> */
+  actorId: string;
+  c: Context<AuthEnv>;
+}
+
+export function actorIdOf(a: Actor | undefined): string {
+  if (!a) return "system:unknown";
+  return `${a.type === "api_key" ? "api_key" : "user"}:${a.id ?? a.name ?? "?"}`;
+}
+
+export function route<D extends EndpointDef>(
+  app: ModuleApp,
+  def: D,
+  handler: (input: Input<D>) => Promise<unknown>,
+  opts: { tag?: string; status?: 200 | 201 } = {},
+) {
+  const request: RouteConfig["request"] = {};
+  if (def.params) request.params = def.params as never;
+  if (def.query) request.query = def.query as never;
+  if (def.body) request.body = { content: { "application/json": { schema: def.body as never } }, required: true };
+  const status = opts.status ?? 200;
+  const r = createRoute({
+    method: def.method,
+    path: def.path,
+    summary: def.summary,
+    tags: [opts.tag ?? "agent"],
+    middleware: [requireScope(def.scope as ApiScope)] as never,
+    request,
+    responses: {
+      [status]: { description: def.summary, content: { "application/json": { schema: apiResponse(def.response) } } },
+    },
+  });
+  // biome-ignore lint/suspicious/noExplicitAny: 路由泛型在封装里擦除,入参已由 zod-openapi 校验
+  app.openapi(r, (async (c: any) => {
+    const actor = c.get("actor") as Actor | undefined;
+    const input = {
+      params: def.params ? c.req.valid("param") : {},
+      query: def.query ? c.req.valid("query") : {},
+      body: def.body ? c.req.valid("json") : {},
+      actor,
+      actorId: actorIdOf(actor),
+      c,
+    } as Input<D>;
+    const data = def.response.parse(await handler(input));
+    return c.json({ ok: true, data }, status);
+    // biome-ignore lint/suspicious/noExplicitAny: 同上
+  }) as any);
+}