106 lines
4.1 KiB
TypeScript
106 lines
4.1 KiB
TypeScript
/**
|
||
* 引擎接口（任务 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>;
|
||
} |