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/capability.ts

@@ -24,37 +24,31 @@ export const MutationPlan = z.object({
 });
 export type MutationPlan = z.infer<typeof MutationPlan>;
 
-/** 能力风险级别 */
-export const CapabilityRisk = z.enum(["read", "preview", "write", "destructive"]);
-export type CapabilityRisk = z.infer<typeof CapabilityRisk>;
-
 /** 能力 ID:`域.动作`,如 download.submit */
 export const CapabilityId = z.string().regex(/^[a-z][a-z0-9]*\.[a-z][a-z0-9_]*$/);
 export type CapabilityId = z.infer<typeof CapabilityId>;
 
-/** 能力定义(注册中心元数据;处理器在 server 侧挂载) */
-export interface CapabilityDefinition<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
-  id: CapabilityId;
-  version: number;
-  description: string;
-  input: I;
-  output: O;
-  scopes: string[];
-  risk: CapabilityRisk;
-  idempotent: boolean;
-  supportsPreview: boolean;
-}
-
 // ── 能力描述符与首批能力(任务书 §3.1-9;REQ §10.3) ──
 
 /** 风险级别:low 只读;medium 预览/可撤回写入;high 触发下载、文件变更或策略发布 */
 export const RiskLevel = z.enum(["low", "medium", "high"]);
 export type RiskLevel = z.infer<typeof RiskLevel>;
 
-/** 接口类别(REQ §12.3):read / preview / propose / approve / execute */
+/**
+ * 接口类别(REQ §12.3),由弱到强:
+ * - read:只读查询
+ * - preview:生成预览/方案,不落任何变更
+ * - propose:生成并保存变更计划(MutationPlan),等待授权
+ * - approve:对计划作出授权决定
+ * - execute:产生外部副作用(下载提交、Copy/Move、策略发布…)
+ */
 export const CapabilityKind = z.enum(["read", "preview", "propose", "approve", "execute"]);
 export type CapabilityKind = z.infer<typeof CapabilityKind>;
 
+/** 崩溃恢复时 harness 能否用持久化参数重跑:有副作用的一律 never,只读用 safe */
+export const CapabilityReplay = z.enum(["safe", "never"]);
+export type CapabilityReplay = z.infer<typeof CapabilityReplay>;
+
 /** 首批能力 ID */
 export const CAPABILITY_IDS = [
   "catalog.lookup",
@@ -78,7 +72,11 @@ export type KnownCapabilityId = z.infer<typeof KnownCapabilityId>;
 /** schema 引用:指向 contracts 中导出的 schema 名(如 "ReleaseSearchInput"),便于序列化给 UI/MCP 列表 */
 export const SchemaRef = z.string().regex(/^[A-Z][A-Za-z0-9]*$/);
 
-/** 能力注册中心的可序列化描述(处理器在 server 侧挂载;模型只能看到白名单内的描述) */
+/**
+ * 能力的可序列化描述(唯一定义;处理器在 server 侧挂载,模型只能看到白名单内的描述)。
+ * 运行时注册用 `CapabilitySpec`(同字段,inputSchema/outputSchema 换成真实 zod schema),
+ * 首批能力的 spec 用 `capabilitySpec(id)` 从 CAPABILITY_CATALOG + CAPABILITY_IO 组装。
+ */
 export const CapabilityDescriptor = z.object({
   id: CapabilityId,
   version: z.number().int().min(1),
@@ -87,14 +85,24 @@ export const CapabilityDescriptor = z.object({
   kind: CapabilityKind,
   inputSchema: SchemaRef,
   outputSchema: SchemaRef,
-  /** 调用所需 API scope */
+  /** 经 HTTP/MCP 调用时所需的 API scope */
   scope: ApiScope,
   riskLevel: RiskLevel,
   idempotent: z.boolean(),
   supportsPreview: z.boolean(),
+  replay: CapabilityReplay,
 });
 export type CapabilityDescriptor = z.infer<typeof CapabilityDescriptor>;
 
+/** 运行时能力规格:描述符字段 + 真实的输入/输出 zod schema(注册中心、Pi 工具、HTTP 共用) */
+export type CapabilitySpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> = Omit<
+  CapabilityDescriptor,
+  "inputSchema" | "outputSchema"
+> & { inputSchema: I; outputSchema: O };
+
+/** 需要走授权回调(automation_grant / approval)的类别 */
+export const AUTHORIZED_KINDS: readonly CapabilityKind[] = ["propose", "approve", "execute"];
+
 /** 首批能力的描述(inputSchema/outputSchema 名对应 capabilities-io.ts 中的导出) */
 export const CAPABILITY_CATALOG: Record<KnownCapabilityId, CapabilityDescriptor> = {
   "catalog.lookup": d(
@@ -276,5 +284,7 @@ function d(
     riskLevel,
     idempotent,
     supportsPreview,
+    // 有副作用的类别一律不可重放
+    replay: kind === "read" || kind === "preview" ? "safe" : "never",
   };
 }