89 lines
3.2 KiB
TypeScript
89 lines
3.2 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>;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
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;
|
|||
|
|
/** 发一轮输入，产出事件流；流结束表示这一回合结束 */
|
|||
|
|
send(text: string, options?: SendOptions): AsyncIterable<RuntimeEvent>;
|
|||
|
|
/** 工具执行完回填回执，运行时据此继续生成后续事件 */
|
|||
|
|
resolveToolResult(callId: string, receipt: ExecutionReceipt): void;
|
|||
|
|
/** 取消当前回合 */
|
|||
|
|
abort(): void;
|
|||
|
|
/** 释放运行时资源（子进程、连接） */
|
|||
|
|
dispose(): Promise<void>;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export interface AgentRuntime {
|
|||
|
|
readonly name: string;
|
|||
|
|
createSession(input: CreateRuntimeSessionInput): Promise<RuntimeSession>;
|
|||
|
|
}
|