refactor(contracts,agent): single capability spec and agent run event definitions in contracts

B3: CapabilityDescriptor gains replay; CapabilitySpec + capabilitySpec(id) assemble
CAPABILITY_CATALOG + CAPABILITY_IO; drop CapabilityDefinition/CapabilityRisk. agent
registry registers contracts CapabilitySpec (kind/allowedKinds instead of its own
scope enum; approve also requires authorize). AgentRun port renamed AgentRunHandle.

B9: contracts AgentRunEvent/AgentRunEventBody/AgentRunEventRow/AgentUsageTotals with
row and SSE mapping helpers; agent onEvent receives AgentRunEvent, delivered serially
in seq order, firstSeq continues numbering across processes.

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

packages/contracts/src/capabilities-io.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { MediaAsset } from "./assets.ts";
-import type { KnownCapabilityId } from "./capability.ts";
+import { CAPABILITY_CATALOG, type CapabilitySpec, type KnownCapabilityId } from "./capability.ts";
 import { Id, JsonObject, NonNegInt } from "./common.ts";
 import { MediaEntity, MediaKind } from "./content.ts";
 import { AcquisitionPlan, DownloadTask, Task, TaskStatus } from "./execution.ts";
@@ -188,6 +188,23 @@ export const CAPABILITY_IO = {
   "inventory.query": { input: InventoryQueryInput, output: InventoryQueryOutput },
 } as const satisfies Record<KnownCapabilityId, { input: z.ZodType; output: z.ZodType }>;
 
+type CapabilityIo = typeof CAPABILITY_IO;
+/** 首批能力 id 对应的运行时规格类型(input/output 为该能力的具体 schema) */
+export type KnownCapabilitySpec<K extends KnownCapabilityId> = CapabilitySpec<
+  CapabilityIo[K]["input"],
+  CapabilityIo[K]["output"]
+>;
+
+/**
+ * 首批能力的运行时规格:CAPABILITY_CATALOG 的元数据 + CAPABILITY_IO 的 schema。
+ * server 各模块注册处理器时一律用它,不要手写描述:
+ * `registry.register(capabilitySpec("release.search"), handler)`
+ */
+export function capabilitySpec<K extends KnownCapabilityId>(id: K): KnownCapabilitySpec<K> {
+  const { inputSchema: _i, outputSchema: _o, ...meta } = CAPABILITY_CATALOG[id];
+  return { ...meta, inputSchema: CAPABILITY_IO[id].input, outputSchema: CAPABILITY_IO[id].output };
+}
+
 export type CatalogLookupInput = z.infer<typeof CatalogLookupInput>;
 export type CatalogLookupOutput = z.infer<typeof CatalogLookupOutput>;
 export type ReleaseSearchInput = z.infer<typeof ReleaseSearchInput>;