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]>
This commit is contained in:
rootandClaude Opus 5.5 committed
1 parent
8f59bf3772
commit
db5352eecd
18 files changed
+553
-293
No files matched your search
@@ -1,52 +1,14 @@
|
||||
import type { CapabilityScope } from "../capability/types.ts";
|
||||
import type {
|
||||
AgentBudgetKind,
|
||||
AgentFailureReason,
|
||||
AgentRunEvent,
|
||||
AgentUsageTotals,
|
||||
CapabilityKind,
|
||||
} from "@umt/contracts";
|
||||
import type { AgentSettings } from "../settings.ts";
|
||||
|
||||
/** 本包对外的用量统计(与 SDK 类型解耦) */
|
||||
export interface AgentUsage {
|
||||
inputTokens: number;
|
||||
outputTokens: number;
|
||||
cacheReadTokens: number;
|
||||
cacheWriteTokens: number;
|
||||
totalTokens: number;
|
||||
costUsd: number;
|
||||
}
|
||||
|
||||
export type AgentFailureReason = "budget" | "aborted" | "error";
|
||||
|
||||
export type AgentEventBody =
|
||||
| { type: "run_started"; goal: string; resumed: boolean }
|
||||
| { type: "text_delta"; delta: string }
|
||||
| { type: "thinking_delta"; delta: string }
|
||||
| {
|
||||
type: "tool_call_start";
|
||||
toolCallId: string;
|
||||
capabilityId: string;
|
||||
/** 已脱敏、截断的输入摘要 */
|
||||
inputSummary: string;
|
||||
recovery: boolean;
|
||||
}
|
||||
| {
|
||||
type: "tool_call_end";
|
||||
toolCallId: string;
|
||||
capabilityId: string;
|
||||
isError: boolean;
|
||||
/** 已脱敏、截断的输出摘要 */
|
||||
outputSummary: string;
|
||||
recovery: boolean;
|
||||
}
|
||||
| { type: "tool_call_rejected"; toolCallId: string; toolName: string; capabilityId?: string; reason: string }
|
||||
| {
|
||||
type: "compaction";
|
||||
phase: "start" | "end";
|
||||
reason: "manual" | "threshold" | "overflow";
|
||||
status?: "completed" | "declined" | "aborted" | "failed";
|
||||
}
|
||||
| { type: "run_completed"; finalText: string; usage: AgentUsage }
|
||||
| { type: "run_failed"; reason: AgentFailureReason; message: string; usage: AgentUsage; budget?: BudgetKind };
|
||||
|
||||
export type BudgetKind = "tool_calls" | "duration" | "tokens" | "cost";
|
||||
|
||||
export type AgentEvent = AgentEventBody & { runId: string; seq: number; at: string };
|
||||
// 事件、用量、失败原因的类型统一取自 @umt/contracts(AgentRunEvent / AgentUsageTotals / AgentFailureReason /
|
||||
// AgentBudgetKind);本文件只定义运行时端口。
|
||||
|
||||
/** 调用能力时使用的业务身份;授权回调据此到 automation_grant / approval 查询 */
|
||||
export interface AgentActor {
|
||||
@@ -54,8 +16,8 @@ export interface AgentActor {
|
||||
/** 持久任务 ID(agent_run 所属任务) */
|
||||
taskId: string;
|
||||
scopeIds: string[];
|
||||
/** 本次运行允许触达的作用域上限;"先给方案"模式传 ['read','preview','propose'] */
|
||||
allowedScopes?: CapabilityScope[];
|
||||
/** 本次运行允许触达的能力类别上限;"先给方案"模式传 ['read','preview','propose'] */
|
||||
allowedKinds?: CapabilityKind[];
|
||||
}
|
||||
|
||||
export interface CreateRunSpec {
|
||||
@@ -69,26 +31,32 @@ export interface CreateRunSpec {
|
||||
/** 应用数据目录下的会话目录;会话文件为 sessionDir/<runId>.jsonl */
|
||||
sessionDir: string;
|
||||
actor: AgentActor;
|
||||
/**
|
||||
* 本进程第一个事件的 seq。续跑(崩溃恢复/多轮对话)时传该 run 已落库事件的 max(seq)+1
|
||||
* (agent_run_event 中无记录时为 0),保证 (run_id, seq) 不冲突;默认 0。
|
||||
*/
|
||||
firstSeq?: number;
|
||||
}
|
||||
|
||||
export interface RunOutcome {
|
||||
status: "completed" | "failed";
|
||||
reason?: AgentFailureReason;
|
||||
budget?: BudgetKind;
|
||||
budget?: AgentBudgetKind;
|
||||
message?: string;
|
||||
finalText: string;
|
||||
usage: AgentUsage;
|
||||
usage: AgentUsageTotals;
|
||||
}
|
||||
|
||||
export interface AgentRun {
|
||||
/** 一次运行的句柄(区别于 contracts 的 AgentRun 行) */
|
||||
export interface AgentRunHandle {
|
||||
readonly runId: string;
|
||||
readonly sessionPath: string;
|
||||
/** 打开已有会话时发现的未完成操作数;>0 时应调用 resume() */
|
||||
readonly pendingOperations: number;
|
||||
/** 从 fromSeq(含)开始回放并持续推送事件;close() 后结束 */
|
||||
events(fromSeq?: number): AsyncIterable<AgentEvent>;
|
||||
/** 已产生的全部事件快照 */
|
||||
history(): AgentEvent[];
|
||||
events(fromSeq?: number): AsyncIterable<AgentRunEvent>;
|
||||
/** 本进程已产生的全部事件快照 */
|
||||
history(): AgentRunEvent[];
|
||||
/** 发送一条用户消息并驱动到本轮结束;text 省略时使用 goal */
|
||||
prompt(text?: string): Promise<RunOutcome>;
|
||||
/** 崩溃/重启后继续未完成的操作 */
|
||||
@@ -100,9 +68,9 @@ export interface AgentRun {
|
||||
|
||||
/** 领域/服务层只依赖这个端口,不直接接触 Pi SDK 类型 */
|
||||
export interface AgentRuntimePort {
|
||||
createRun(spec: CreateRunSpec): Promise<AgentRun>;
|
||||
createRun(spec: CreateRunSpec): Promise<AgentRunHandle>;
|
||||
}
|
||||
|
||||
export function emptyUsage(): AgentUsage {
|
||||
export function emptyUsage(): AgentUsageTotals {
|
||||
return { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, totalTokens: 0, costUsd: 0 };
|
||||
}
|
||||
Reference in new issue
Block a user