@springbrand/agent-runtime 0.2.0-alpha.34 → 0.2.0-alpha.38

package/src/runtime-definition.ts

@@ -2,16 +2,11 @@ import type { SkillSource } from "agents/skills";
 import type { ExecutionLevel } from "./lib/execution-level";
 import type {
   RuntimeGatewayPort,
-  RuntimeModelUsageEvent,
-  RuntimeSubmissionAdmissionHook,
-  RuntimeSubagentUsageEvent,
-  RuntimeLifecycleFact,
-  RuntimeEventConfirmation,
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSkillScriptPolicy,
-  RuntimeToolStartEvent,
-  RuntimeTurnMessage,
+  RuntimeSubmissionAdmissionHook,
+  RuntimeTurnEventsPort,
 } from "./kernel/bindings";
 import type {
   RuntimeDenyPolicy,
@@ -20,15 +15,41 @@ import type {
   ThinkingEffort,
 } from "./kernel/profile";
 import type { RuntimeExtensionConfig } from "./kernel/extensions";
-import type { RuntimeActivityProjection } from "./kernel/state";
 import type { RuntimeDegradation } from "./kernel/degradation";
+import type { PiToolCandidate } from "./pi/tool/compiler";
 import type {
   RuntimeAgentContext,
-  RuntimeAssemblyContext,
   RuntimeAgentPlanningContext,
 } from "./runtime-agent-context";
 import type { AgentTelemetryBinding } from "./telemetry/contract";
-import type { ToolSurfaceSelectionPolicy } from "./tool-registry";
+
+/** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
+export interface ToolSurfaceSelectionPolicy {
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+  readonly defersTool?: (name: string) => boolean;
+}
+
+/** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
+export interface RuntimeToolBindings {
+  readonly workspace?: import("./kernel/bindings").WorkspacePort;
+  readonly codeExecution?: import("./kernel/bindings").RuntimeCodeExecutionFactory;
+  readonly memory?: import("./kernel/bindings").RuntimeMemoryPort;
+  readonly subagents?: import("./kernel/bindings").RuntimeSubagentPort;
+}
+
+/** Host 一次装配原子提交的 Tool candidates 与 Runtime 绑定。 */
+export interface ToolAssemblyResult {
+  readonly tools: readonly PiToolCandidate[];
+  readonly bindings?: RuntimeToolBindings;
+  readonly memoryProfile?: RuntimeMemoryProfile;
+  readonly enabledSubagents?: readonly string[];
+  readonly degradations?: readonly RuntimeDegradation[];
+  readonly surfacePolicy?: ToolSurfaceSelectionPolicy;
+  readonly commitGuard?: () => Promise<void>;
+  /** 释放本次装配创建的外部资源；临时 Agent 终止后由 Runtime 调用。 */
+  readonly dispose?: () => Promise<void>;
+}
 
 export interface RuntimeProfileContribution {
   readonly model: string;
@@ -55,32 +76,6 @@ export interface RuntimeToolSurfacePolicy extends ToolSurfaceSelectionPolicy {
 
 export type { RuntimeAgentContext, RuntimeAssemblyContext } from "./runtime-agent-context";
 
-export interface GateToolRequest {
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly input: unknown;
-  readonly requiredExecutionLevel: ExecutionLevel;
-  readonly signal: AbortSignal;
-}
-
-export type {
-  PlatformToolContext,
-  PlatformToolRegistry,
-  PlatformToolSpec,
-  RuntimeToolBindings,
-  ToolAssemblyResult,
-  ToolContext,
-  ToolRegistry,
-  ToolSpec,
-} from "./tool-registry";
-export {
-  emptyPlatformToolRegistry,
-  emptyToolRegistry,
-  mergeToolRegistries,
-  normalizeToolAssembly,
-  toolRegistryFromPiCandidates,
-} from "./tool-registry";
-
 export interface ResolvedConnectors {
   readonly servers: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
@@ -91,81 +86,14 @@ export interface ResolvedResources {
   readonly settings: RuntimeSettings;
   readonly provider: RuntimeProviderPort;
   readonly platform: RuntimePlatformPort;
+  readonly turnEvents?: RuntimeTurnEventsPort;
+  readonly admission?: RuntimeSubmissionAdmissionHook;
   readonly skills: readonly RuntimeSkillContribution[];
   readonly extensions: readonly RuntimeExtensionContribution[];
   readonly connectors: ResolvedConnectors;
   readonly degradations?: readonly RuntimeDegradation[];
 }
 
-export interface ProfileOverrides {
-  readonly systemPrompt?: string;
-  readonly executionLevel?: ExecutionLevel;
-}
-
-export interface ApprovalHookInput {
-  readonly submissionId: string;
-  readonly approvalExecutionId: string;
-}
-
-export interface SubmissionTerminalHookInput {
-  readonly submissionId: string;
-  readonly status: "completed" | "aborted" | "skipped" | "error";
-  readonly error?: string;
-  readonly resultMessageId?: string;
-}
-
-export interface RuntimeToolSettlementEvent {
-  readonly eventId: string;
-  readonly submissionId: string;
-  readonly toolCallId: string;
-  readonly toolName: string;
-  readonly status: "success" | "error";
-}
-
-export interface RuntimeAgentHooks<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Config = unknown,
-  Command = never,
-  Change = never,
-> {
-  readonly beforeCommit?: ReadonlyArray<
-    (
-      ctx: RuntimeAssemblyContext<Env, Command, Change>,
-      config: Config,
-    ) => Promise<void>
-  >;
-
-  readonly onTurnEnd?: (
-    ctx: RuntimeAssemblyContext<Env, Command, Change>,
-    messages: readonly RuntimeTurnMessage[],
-  ) => Promise<void>;
-  readonly onModelUsage?: (event: RuntimeModelUsageEvent) => Promise<void>;
-  readonly onSubagentUsage?: (
-    event: RuntimeSubagentUsageEvent,
-  ) => Promise<RuntimeEventConfirmation | void>;
-  readonly onLifecycleFact?: (
-    event: RuntimeLifecycleFact,
-  ) => Promise<RuntimeEventConfirmation | void>;
-  /** Single admission seam shared by chat, RPC, regenerate and scheduled submissions. */
-  readonly onSubmissionAdmission?: RuntimeSubmissionAdmissionHook;
-  readonly onToolStart?: (event: RuntimeToolStartEvent) => Promise<void>;
-  readonly onToolSettled?: (event: RuntimeToolSettlementEvent) => Promise<void>;
-  readonly onApproval?: (input: ApprovalHookInput) => Promise<void>;
-  readonly onActivityChanged?: (
-    projection: RuntimeActivityProjection,
-  ) => Promise<void>;
-  readonly onSubmissionTerminal?: (
-    input: SubmissionTerminalHookInput,
-  ) => Promise<void>;
-
-  readonly gateTool?: (request: GateToolRequest) => Promise<void>;
-
-  readonly profileOverrides?: (
-    ctx: RuntimeAssemblyContext<Env, Command, Change>,
-    config: Config,
-  ) => ProfileOverrides | Promise<ProfileOverrides>;
-}
-
 export interface RuntimeSettings {
   readonly profile: RuntimeProfileContribution;
   readonly memoryProfile: RuntimeMemoryProfile;
@@ -175,14 +103,12 @@ export interface RuntimeSettings {
 
 export interface AssembleRuntimeSnapshotInput<
   Env extends Cloudflare.Env,
-  Config,
   Command = never,
   Change = never,
 > {
   readonly ctx: RuntimeAgentPlanningContext<Env, Command, Change>;
-  readonly config: Config;
-  readonly tools: import("./tool-registry").ToolAssemblyResult;
+  readonly tools: ToolAssemblyResult;
   readonly resources: ResolvedResources;
-  readonly hooks?: RuntimeAgentHooks<Env, Config, Command, Change>;
+  readonly commitGuard?: () => Promise<void>;
   readonly telemetry?: AgentTelemetryBinding;
 }

package/src/runtime.ts

@@ -36,7 +36,11 @@ import {
   type SubmissionReceipt,
 } from "./kernel/receipts";
 import type { ExecutionLevel } from "./lib/execution-level";
-import type { RuntimeGatewaySession } from "./kernel/bindings";
+import type {
+  RuntimeGatewaySession,
+  RuntimeSubmissionAdmissionHook,
+  RuntimeTurnEventsPort,
+} from "./kernel/bindings";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 import { projectRuntimeAssembly } from "./kernel/runtime-assembly";
 import type {
@@ -57,8 +61,6 @@ import {
   type RuntimeCandidate,
   type RuntimeSnapshot,
 } from "./runtime-assembler";
-import type { RuntimeAgentHooks } from "./runtime-definition";
-import type { RuntimeTurnEventsPort } from "./kernel/bindings";
 import {
   RuntimeTelemetryCoordinator,
 } from "./telemetry";
@@ -199,6 +201,14 @@ interface ActiveTurn {
   agent: PreparedPiTurnAdapter;
 }
 
+interface ActiveRuntime {
+  readonly snapshot: RuntimeSnapshot;
+  readonly revision: string;
+  readonly pi: PreparedPiRuntime;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly admission?: RuntimeSubmissionAdmissionHook;
+}
+
 interface PlannedContinuationData {
   readonly submissionId: string;
   readonly requestId: string;
@@ -414,12 +424,7 @@ export abstract class AgentRuntimeKernel<
 
   protected abstract ensureRuntimeReady(): Promise<void>;
 
-  private runtimeSnapshot?: RuntimeSnapshot;
-  private runtimeRevision?: string;
-  private runtimePi?: PreparedPiRuntime;
-  private runtimeGatewaySession?: RuntimeGatewaySession;
-  private runtimeTurnEvents?: RuntimeTurnEventsPort;
-  private runtimeHooks?: RuntimeAgentHooks;
+  private activeRuntime?: ActiveRuntime;
   private telemetryCoordinator?: RuntimeTelemetryCoordinator;
   private piAdapter?: PiRuntimeAdapter;
   private readonly transcript: PiRuntimeTranscript;
@@ -464,7 +469,7 @@ export abstract class AgentRuntimeKernel<
     return this.runtimeLoadTracker ??= new RuntimeLoadTracker({
       read: () => this.state.runtimeLoad,
       publish: (runtimeLoad) => this.setState({ ...this.state, runtimeLoad }),
-      isAvailable: () => Boolean(this.runtimeSnapshot),
+      isAvailable: () => Boolean(this.activeRuntime),
     });
   }
 
@@ -715,14 +720,11 @@ export abstract class AgentRuntimeKernel<
   }
 
   private turnEventsPort(): RuntimeTurnEventsPort | undefined {
-    return this.runtimeTurnEvents ?? this.runtimeSnapshot?.bindings.turnEvents;
+    return this.activeRuntime?.snapshot.bindings.turnEvents;
   }
 
   protected async initCandidate(candidate: RuntimeCandidate): Promise<void> {
-    this.runtimeTurnEvents =
-      candidate.turnEvents ?? candidate.snapshot.bindings.turnEvents;
-    this.runtimeHooks = candidate.hooks;
-    const previous = this.runtimeSnapshot;
+    const previous = this.activeRuntime;
     const candidateSnapshot = candidate.snapshot;
     this.runtimeLoad.advance("assembly");
     this.runtimeLoad.advance("mcp");
@@ -776,7 +778,7 @@ export abstract class AgentRuntimeKernel<
     // 没有任何工具在执行 —— 换装配对它是安全的，而且这正是「决定时才装上
     // 新能力，同一轮接着跑」所依赖的那一步。真正在执行的 Turn 仍然被挡住。
     const contested = Boolean(previous) &&
-      revision !== this.runtimeRevision &&
+      revision !== previous?.revision &&
       this.submissions.isBusy();
     const parked = contested && this.db.everyUnfinishedSubmissionParked();
     if (contested && !parked) {
@@ -791,8 +793,17 @@ export abstract class AgentRuntimeKernel<
           () => this.prepareParkedSubmissionRepin(prepared, revision),
         )
       : undefined;
+    const next = Object.freeze({
+      snapshot: candidateSnapshot,
+      revision,
+      pi: prepared,
+      ...(gatewaySession ? { gatewaySession } : {}),
+      ...(candidate.admission
+        ? { admission: candidate.admission }
+        : {}),
+    }) satisfies ActiveRuntime;
     let activated = false;
-    const previousGatewaySession = this.runtimeGatewaySession;
+    const previousGatewaySession = previous?.gatewaySession;
     try {
       for (const [index, guard] of candidate.commitGuards.entries()) {
         await withRuntimeLoadTimeout(`commit-guard:${index}`, guard);
@@ -800,14 +811,11 @@ export abstract class AgentRuntimeKernel<
       this.pi.activate(candidateSnapshot);
       activated = true;
       repin?.commit();
-      this.runtimeSnapshot = candidateSnapshot;
-      this.runtimeRevision = revision;
-      this.runtimePi = prepared;
-      this.runtimeGatewaySession = gatewaySession;
       this.telemetry.configure(candidate.telemetry);
+      this.activeRuntime = next;
     } catch (error) {
       repin?.abort();
-      if (activated && previous) this.pi.activate(previous);
+      if (activated && previous) this.pi.activate(previous.snapshot);
       await closeRuntimeGatewaySession(gatewaySession, "gateway.close.aborted");
       throw error;
     }
@@ -1101,22 +1109,22 @@ export abstract class AgentRuntimeKernel<
       try {
         const payload = JSON.parse(row.body) as RuntimeEventOutboxPayload;
         if (payload.type === "model-usage") {
-          if (!turnEvents.onModelUsage) continue;
-          await turnEvents.onModelUsage(payload.event);
+          await turnEvents.onModelUsage?.(payload.event);
         } else if (payload.type === "tool-settlement") {
-          if (!turnEvents.onToolSettled) continue;
-          await turnEvents.onToolSettled(payload.event);
+          await turnEvents.onToolSettled?.(payload.event);
         } else if (payload.type === "subagent-usage") {
-          if (!turnEvents.onSubagentUsage) continue;
-          const confirmation = await turnEvents.onSubagentUsage(payload.event);
-          if (confirmation?.confirmed !== true) {
-            throw new Error("Runtime event was not confirmed");
+          if (turnEvents.onSubagentUsage) {
+            const confirmation = await turnEvents.onSubagentUsage(payload.event);
+            if (confirmation?.confirmed !== true) {
+              throw new Error("Runtime event was not confirmed");
+            }
           }
         } else {
-          if (!turnEvents.onLifecycleFact) continue;
-          const confirmation = await turnEvents.onLifecycleFact(payload.event);
-          if (confirmation?.confirmed !== true) {
-            throw new Error("Runtime event was not confirmed");
+          if (turnEvents.onLifecycleFact) {
+            const confirmation = await turnEvents.onLifecycleFact(payload.event);
+            if (confirmation?.confirmed !== true) {
+              throw new Error("Runtime event was not confirmed");
+            }
           }
         }
         this.db.transaction(() =>
@@ -1320,12 +1328,12 @@ export abstract class AgentRuntimeKernel<
   // 调用：所有需要模型、工作区、扩展或投影绑定的运行时路径调用。
   // 原因：未初始化时立即失败，比在深层路径触发空值更容易定位。
   private assembly(): RuntimeSnapshot {
-    if (!this.runtimeSnapshot) {
+    if (!this.activeRuntime) {
       throw new Error(
         "Runtime must be assembled before use",
       );
     }
-    return this.runtimeSnapshot;
+    return this.activeRuntime.snapshot;
   }
 
   private async normalizeUIUserInput(
@@ -1377,10 +1385,14 @@ export abstract class AgentRuntimeKernel<
   // 调用：Session facet 的 `getRuntimeAssembly` RPC。
   // 原因：UI 需要读取真实装配结果，而不是上层配置声明。
   protected readRuntimeAssembly(): RuntimeAssemblyView {
+    const runtime = this.activeRuntime;
+    if (!runtime) {
+      throw new Error("Runtime must be assembled before use");
+    }
     return projectRuntimeAssembly(
-      this.assembly(),
-      this.runtimeRevision ?? null,
-      this.preparedPi(),
+      runtime.snapshot,
+      runtime.revision,
+      runtime.pi,
     );
   }
 
@@ -1442,12 +1454,12 @@ export abstract class AgentRuntimeKernel<
   }
 
   private preparedPi(): PreparedPiRuntime {
-    if (!this.runtimePi) {
+    if (!this.activeRuntime) {
       throw new Error(
         "SpringBrand Runtime must be prepared before starting a Turn",
       );
     }
-    return this.runtimePi;
+    return this.activeRuntime.pi;
   }
 
   // #endregion
@@ -1474,10 +1486,11 @@ export abstract class AgentRuntimeKernel<
     descriptor: string;
   }> {
     await this.drainRuntimeEvents();
-    if (!this.runtimeRevision) {
+    const runtime = this.activeRuntime;
+    if (!runtime) {
       throw new Error("Runtime revision is not initialized");
     }
-    return this.pinAssembly(this.preparedPi(), this.runtimeRevision);
+    return this.pinAssembly(runtime.pi, runtime.revision);
   }
 
   private async pinAssembly(
@@ -1731,7 +1744,7 @@ export abstract class AgentRuntimeKernel<
             "Regenerate request must match an existing user message",
           );
         }
-        const hook = this.runtimeHooks?.onSubmissionAdmission;
+        const hook = this.activeRuntime?.admission;
         let existing: StoredSubmissionAdmission | null = null;
         if (hook) {
           const attemptedAt = Date.now();
@@ -2279,15 +2292,30 @@ export abstract class AgentRuntimeKernel<
   ): PiRecoveryDecision {
     let decision = this.decidePiRecovery(submission);
     for (const settlement of decision.recoveredToolSettlements) {
+      const message = settlement.message;
       if (
         this.readToolSettlement(
           submission.submissionId,
-          settlement.toolCallId,
+          message.toolCallId,
         )
       ) {
         continue;
       }
-      this.settleToolSync(submission.submissionId, settlement);
+      this.settleToolSync(submission.submissionId, {
+        toolCallId: message.toolCallId,
+        toolName: message.toolName,
+        args: settlement.args,
+        result: {
+          content: message.content,
+          details: message.details,
+          ...(message.usage ? { usage: message.usage } : {}),
+          ...(message.addedToolNames?.length
+            ? { addedToolNames: message.addedToolNames }
+            : {}),
+        },
+        isError: message.isError,
+        createdAt: message.timestamp,
+      });
       decision = this.decidePiRecovery(submission);
     }
     const results = this.transcript.orderRecoveredToolSettlements(
@@ -4198,7 +4226,7 @@ export abstract class AgentRuntimeKernel<
         );
       }
       const result = decision.recoveredToolSettlements.find(
-        (item) => item.toolCallId === approval.toolCallId,
+        (item) => item.message.toolCallId === approval.toolCallId,
       );
       if (!result) {
         throw new Error(

package/src/adapter/cloudflare/universal-agent/hooks.ts

@@ -1,57 +0,0 @@
-import type {
-  RuntimeSubmissionAdmissionHook,
-  RuntimeTurnEventsPort,
-} from "../../../kernel/bindings";
-import type { RuntimeAgentHooks } from "../../../runtime-definition";
-
-export function createUniversalAgentHooks<
-  Env extends Cloudflare.Env,
-  Config,
-  Command = never,
-  Change = never,
->(adapter: {
-  guard(config: Config): Promise<void>;
-  turnEvents(): RuntimeTurnEventsPort | Promise<RuntimeTurnEventsPort>;
-  onSubmissionAdmission?: RuntimeSubmissionAdmissionHook;
-}): RuntimeAgentHooks<Env, Config, Command, Change> {
-  const turnEvents = () => Promise.resolve(adapter.turnEvents());
-  return {
-    beforeCommit: [async (_context, config) => adapter.guard(config)],
-    onTurnEnd: async (_context, messages) => {
-      await (await turnEvents()).onResponse(messages);
-    },
-    onModelUsage: async (event) => {
-      await (await turnEvents()).onModelUsage?.(event);
-    },
-    ...(adapter.onSubmissionAdmission
-      ? { onSubmissionAdmission: adapter.onSubmissionAdmission }
-      : {}),
-    // 一个不订阅这两类事实的 Host 不能把 outbox 堵住：Runtime 只有拿到确认才
-    // 会标记投递，而 `undefined` 表示"没投出去"。因此没有 Host 实现时这里就地确认，
-    // 语义等同于旧版本"Host 不关心就丢弃"，而不是让整条队列在队头无限重试。
-    onSubagentUsage: async (event) => {
-      const port = await turnEvents();
-      return port.onSubagentUsage
-        ? port.onSubagentUsage(event)
-        : { confirmed: true };
-    },
-    onLifecycleFact: async (event) => {
-      const port = await turnEvents();
-      return port.onLifecycleFact
-        ? port.onLifecycleFact(event)
-        : { confirmed: true };
-    },
-    onToolSettled: async (event) => {
-      await (await turnEvents()).onToolSettled?.(event);
-    },
-    onApproval: async (input) => {
-      await (await turnEvents()).onApproval?.(input);
-    },
-    onActivityChanged: async (projection) => {
-      await (await turnEvents()).onActivityChanged?.(projection);
-    },
-    onSubmissionTerminal: async (input) => {
-      await (await turnEvents()).onSubmissionTerminal?.(input);
-    },
-  };
-}

package/src/kernel/tool-surface.ts

@@ -1,42 +0,0 @@
-import type { ExecutionLevel } from "../lib/execution-level";
-import type { PiToolCandidate } from "../pi/tool/compiler";
-
-/**
- * Tool Surface 的形状类型。
- *
- * @remarks
- * `kernel/bindings.ts` 和 `tool-registry.ts` 都要用它们，所以它们不能住在其中任何
- * 一边：`RuntimeBindings.codeExecution` 的工厂签名需要 `ToolRegistry`，而
- * `tool-registry.ts` 又需要 bindings 里的各个 Port —— 两边互相 import 就形成了
- * depcruise 的 no-circular 违规（`bindings → tool-registry → bindings`）。
- *
- * 这里只放形状，不放行为：注册表的合并、筛选和构造仍然留在 `tool-registry.ts`。
- *
- * 术语见 `../index.ts`。
- */
-
-/** 模型调用 Tool 时传给 `execute` 的上下文。 */
-export interface ToolContext {
-  readonly toolCallId: string;
-  readonly signal: AbortSignal;
-}
-
-/** Definition 作者声明的一个 Tool。 */
-export interface ToolSpec extends Partial<
-  Omit<PiToolCandidate, "tool" | "requiredExecutionLevel">
-> {
-  readonly label: string;
-  readonly description: string;
-  readonly parameters: unknown;
-  readonly requiredExecutionLevel: ExecutionLevel;
-  /** Require a fresh human decision for every call, regardless of execution level. */
-  readonly alwaysRequiresApproval?: boolean;
-  /** Preserve adapted Pi result envelopes; only details-only adapters may unwrap them. */
-  readonly execute: (
-    input: unknown,
-    ctx: ToolContext,
-  ) => Promise<unknown>;
-}
-
-/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
-export type ToolRegistry = Record<string, ToolSpec>;