aps-agent/contracts/events.ts

/**
 * 协议 v1 的事件模型（JSON Schema 为准，这里是 TS 镜像）。
 *
 * 界面只依赖这一套事件：引擎换 Pi 还是 Codex，事件不变（架构设计 5.2）。
 * 改事件必须同时改：contracts/schemas/events.schema.json、本文件、docs/spec/protocol.md。
 */
import type { ExecutionReceipt } from './protocol.js';

export const PROTOCOL_VERSION = 1;

/** 所有事件共有的信封字段 */
export interface EventEnvelope<TType extends string, TData> {
  /** 协议版本；改协议就加版本，不改这一版 */
  v: typeof PROTOCOL_VERSION;
  /** 会话内单调递增：断点续传与去重靠它 */
  seq: number;
  /** 整数毫秒（ADR-0007） */
  ts: number;
  sessionId: string;
  /** 一次运行（回合）的标识 */
  runId?: string;
  type: TType;
  data: TData;
}

export type ExecutionStatus = ExecutionReceipt['status'];

export interface MessageUserData {
  messageId: string;
  text: string;
}

export interface MessageDeltaData {
  messageId: string;
  text: string;
}

export interface MessageCompletedData {
  messageId: string;
  finishReason?: 'stop' | 'cancelled' | 'error' | 'length';
}

export interface ToolCallData {
  callId: string;
  capabilityId: string;
  /** 参数摘要，不是参数明文 */
  argsDigest: string;
}

export interface ToolResultData {
  callId: string;
  executionId: string;
  status: ExecutionStatus;
}

export interface ExecutionUpdatedData {
  executionId: string;
  status: ExecutionStatus;
  errorKind?: string;
}

export interface ApprovalRequestedData {
  approvalId: string;
  capabilityId: string;
  paramsDigest: string;
  /** 确认卡正文：影响范围与关键参数摘要 */
  impactSummary: string;
  /** 目标数据版本；版本变了确认就失效 */
  revision: number;
  expiresAt: number;
}

export interface ApprovalResolvedData {
  approvalId: string;
  decision: 'approved' | 'rejected' | 'expired';
}

export interface RunStateData {
  state: 'idle' | 'running' | 'cancelling' | 'cancelled';
}

export interface SessionUpdatedData {
  title?: string;
  status?: 'active' | 'archived';
}

export interface ErrorData {
  code: string;
  message: string;
  retryable: boolean;
  errorKind?: string;
}

export type MessageUserEvent = EventEnvelope<'message.user', MessageUserData>;
export type MessageDeltaEvent = EventEnvelope<'message.delta', MessageDeltaData>;
export type MessageCompletedEvent = EventEnvelope<'message.completed', MessageCompletedData>;
export type ToolCallEvent = EventEnvelope<'tool.call', ToolCallData>;
export type ToolResultEvent = EventEnvelope<'tool.result', ToolResultData>;
export type ExecutionUpdatedEvent = EventEnvelope<'execution.updated', ExecutionUpdatedData>;
export type ApprovalRequestedEvent = EventEnvelope<'approval.requested', ApprovalRequestedData>;
export type ApprovalResolvedEvent = EventEnvelope<'approval.resolved', ApprovalResolvedData>;
export type RunStateEvent = EventEnvelope<'run.state', RunStateData>;
export type SessionUpdatedEvent = EventEnvelope<'session.updated', SessionUpdatedData>;
export type ErrorEvent = EventEnvelope<'error', ErrorData>;
export type HeartbeatEvent = EventEnvelope<'heartbeat', Record<string, never>>;

/** 平台事件：客户端唯一认识的事件形态 */
export type PlatformEvent =
  | MessageUserEvent
  | MessageDeltaEvent
  | MessageCompletedEvent
  | ToolCallEvent
  | ToolResultEvent
  | ExecutionUpdatedEvent
  | ApprovalRequestedEvent
  | ApprovalResolvedEvent
  | RunStateEvent
  | SessionUpdatedEvent
  | ErrorEvent
  | HeartbeatEvent;

export type PlatformEventType = PlatformEvent['type'];