/**
 * 引擎接口（任务 A3.1，架构设计 5.2）。
 *
 * 接口只描述「怎么驱动一个循环」，不描述「允许做什么」——权限与门禁全在 Core。
 * 三个固定点：领域类型、工具出口（Core.invoke）、状态（平台保存）。
 *
 * 两个实现：FakeRuntime（A3.2，用于一致性测试与评测）、PiRuntime（A3.3，长驻子进程）。
 * 与设计文档的两处补充：
 *   1. createSession 带 sessionId，便于适配层关联平台会话
 *   2. RuntimeSession 增加 resolveToolResult——工具回执要能回流（Pi 由扩展桥触发，假引擎走内存回调）
 */
import type { ChatMessage, ExecutionReceipt } from '@aps/contracts';
import type { ErrorKind } from '@aps/provider-sdk';

/** 工具描述：能力目录向引擎的投影（只有引擎需要的那部分） */
export interface ToolDescriptor {
  /** 能力 id，如 aps.schedule.preview */
  capabilityId: string;
  /** 引擎侧的工具名（Pi/Codex 的工具名规则不同，由适配层翻译） */
  toolName: string;
  description: string;
  parameters: Record<string, unknown>;
  /** 业务黑话与同义词：来自能力描述，供引擎与规则计划器使用 */
  synonyms?: string[];
  /** 能力分级：写操作要过确认（A4） */
  effect?: 'read' | 'draft' | 'write';
}

export interface RuntimeUsage {
  inputTokens?: number;
  outputTokens?: number;
  turns?: number;
}

/** 运行时提出的确认请求：与协议 v1 的 approval.requested 数据一致 */
export interface RuntimeApprovalRequest {
  approvalId: string;
  capabilityId: string;
  paramsDigest: string;
  impactSummary: string;
  revision: number;
  expiresAt: number;
}

interface RuntimeEventMap {
  text: { delta: string };
  tool_call: { callId: string; capabilityId: string; args: unknown };
  tool_result: { callId: string; receipt: ExecutionReceipt };
  approval_required: { request: RuntimeApprovalRequest };
  turn_end: { reason: 'stop' | 'cancelled' | 'error'; usage?: RuntimeUsage };
  error: { kind: ErrorKind; message: string };
}

/** 统一运行时事件：客户端与 Core 都不感知引擎原生协议 */
export type RuntimeEvent = {
  [K in keyof RuntimeEventMap]: { type: K } & RuntimeEventMap[K];
}[keyof RuntimeEventMap];

export type RuntimeEventType = RuntimeEvent['type'];

export interface CreateRuntimeSessionInput {
  /** 平台会话 id，用于适配层关联 */
  sessionId: string;
  subject: { userId: string; tenantId: string };
  projectId: string | null;
  /** 系统提示词；A3.1 起由应用服务提供 */
  system?: string;
  /** 能力目录投影 */
  tools: ToolDescriptor[];
  /** 平台保存的历史：换进程或重启后据此恢复（架构设计 5.1「会话落库」） */
  history?: ChatMessage[];
}

export interface SendOptions {
  signal?: AbortSignal;
}

export interface RuntimeSession {
  readonly id: string;
  /** 与运行时的 toolExecution 一致：决定工具由平台执行还是引擎自己执行 */
  readonly toolExecution: 'platform' | 'runtime';
  /** 发一轮输入，产出事件流；流结束表示这一回合结束 */
  send(text: string, options?: SendOptions): AsyncIterable<RuntimeEvent>;
  /** 工具执行完回填回执，运行时据此继续生成后续事件 */
  resolveToolResult(callId: string, receipt: ExecutionReceipt): void;
  /** 取消当前回合 */
  abort(): void;
  /** 释放运行时资源（子进程、连接） */
  dispose(): Promise<void>;
  /**
   * 可选的引擎 stderr 快照：进程管理层用它做日志轮转（只保留尾部）。
   * 不是所有引擎都有子进程 stderr，缺省实现可以不给。
   */
  stderrTail?(): string;
}

export interface AgentRuntime {
  readonly name: string;
  /**
   * 工具由谁执行：
   *   platform —— 运行时只发 tool_call，平台经 Core.invoke 执行后把回执送回来（假引擎走这条）
   *   runtime  —— 工具在引擎子进程里执行（Pi 走扩展桥，扩展自己回调平台的内部端点）
   */
  readonly toolExecution: 'platform' | 'runtime';
  createSession(input: CreateRuntimeSessionInput): Promise<RuntimeSession>;
}