@springbrand/agent-runtime 0.1.3-alpha.3 → 0.1.3-alpha.5

package/src/{plugins.ts → runtime-assembler.ts}

@@ -1,6 +1,7 @@
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeCodeExecutionPort,
+  RuntimeGatewayPort,
   RuntimeMemoryPort,
   RuntimePlatformPort,
   RuntimeProviderPort,
@@ -32,212 +33,64 @@ import {
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { PiToolCandidate } from "./pi/tool/compiler";
+import type {
+  AssembleRuntimeSnapshotInput,
+  RuntimeAgentHooks,
+  RuntimeSettings,
+  RuntimeExtensionContribution,
+  RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
+} from "./runtime-definition";
+import type { ToolRegistry } from "./tool-registry";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
 } from "./pi/tool/base";
 import {
   browserQuickActionPiToolCandidates,
-  codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
-import {
-  sandboxPiToolCandidates,
-  workspacePiToolCandidates,
-} from "./pi/tool/workspace-sandbox";
-import { schedulePiToolCandidates } from "./pi/tool/schedule";
 import { skillPiToolCandidates } from "./pi/tool/skill";
-import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { createWebSearch } from "./pi/tool/web-search";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
 
-/**
- * 本文件实现 Plugin 的准备、声明合并、校验和原子候选装配。
- *
- * @remarks
- * 核心术语见包入口 `index.ts`，这里不重复定义。
- */
-
-// #region Plugin 公开契约
-
-/**
- * 标明一个 Plugin 负责哪一类能力。
- *
- * @remarks
- * 应用创建 Plugin 时必须选择其中一个值。
- *
- * Runtime 用它拒绝重复能力并确定贡献顺序，所以不要把它当作自由文本。
- */
-export type PluginKind =
-  | "scope"
-  | "profile"
-  | "provider"
-  | "platform"
-  | "workspace"
-  | "sandbox"
-  | "memory"
-  | "tool"
-  | "skill"
-  | "connector"
-  | "extension"
-  | "schedule"
-  | "subagent"
-  | "turn-events";
+/** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
 export type { RuntimeDegradation } from "./kernel/degradation";
-
-/**
- * 提供 Runtime 核心运行参数。
- *
- * @remarks
- * `profile` Plugin 在准备结果中返回它。
- *
- * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
- */
-export interface RuntimeProfileContribution {
-  readonly model: string;
-  readonly thinking: ThinkingEffort;
-  readonly systemPrompt?: string;
-  readonly executionLevel: ExecutionLevel;
-}
-
-/**
- * 描述一个已准备 Skill。
- */
-export interface RuntimeSkillContribution {
-  readonly name: string;
-  readonly description: string;
-  readonly source: SkillSource;
-  readonly script?: Partial<RuntimeSkillScriptPolicy>;
-}
-
-/**
- * 描述一个已准备 Extension。
- */
-export interface RuntimeExtensionContribution {
-  readonly name: string;
-  readonly extension: RuntimeExtensionConfig;
-}
-
-/**
- * 描述 Agent 对最终 Tool Surface 的可见性约束。
- *
- * Host 只提供策略；Runtime 在唯一 Tool Surface seam 中对所有
- * Port 和 Resource 生成的候选项统一应用。
- */
-export interface RuntimeToolSurfacePolicy {
-  readonly denyPolicy?: RuntimeDenyPolicy;
-  readonly allowsTool?: (name: string) => boolean;
-  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
-}
-
-interface PluginResultByKind {
-  readonly scope: {
-    readonly commitGuards: readonly (() => Promise<void>)[];
-  };
-  readonly profile: { readonly profile: RuntimeProfileContribution };
-  readonly provider: { readonly provider: RuntimeProviderPort };
-  readonly platform: {
-    readonly platform: RuntimePlatformPort;
-  };
-  readonly workspace: {
-    readonly workspace?: WorkspacePort;
-    readonly codeExecution?: RuntimeCodeExecutionPort;
-  };
-  readonly sandbox: {
-    readonly sandbox?: RuntimeSandboxPort;
-  };
-  readonly memory: {
-    readonly memoryProfile: RuntimeMemoryProfile;
-    readonly memoryPort?: RuntimeMemoryPort;
-  };
-  readonly tool: {
-    readonly hostTools: readonly PiToolCandidate[];
-    readonly policy?: RuntimeToolSurfacePolicy;
-  };
-  readonly skill: {
-    readonly skills: readonly RuntimeSkillContribution[];
-  };
-  readonly connector: {
-    readonly connectors: readonly RuntimeMcpServer[];
-  };
-  readonly extension: {
-    readonly extensions: readonly RuntimeExtensionContribution[];
-  };
-  readonly schedule: {
-    readonly schedule: RuntimeSchedulePort;
-  };
-  readonly subagent: {
-    readonly enabledSubagents: readonly string[];
-    readonly subagents?: RuntimeSubagentPort;
-  };
-  readonly "turn-events": {
-    readonly turnEvents: RuntimeTurnEventsPort;
-  };
-}
-
-export type PluginPreparation<K extends PluginKind> = Readonly<
-  PluginResultByKind[K] & {
-    readonly degradations: readonly RuntimeDegradation[];
-  }
->;
-
-export type PreparedPlugin<K extends PluginKind = PluginKind> =
-  K extends PluginKind
-    ? Readonly<PluginPreparation<K> & { readonly kind: K }>
-    : never;
-
-interface AgentPluginContract<K extends PluginKind> {
-  readonly kind: K;
-  prepare(): Promise<PreparedPlugin<K>>;
-}
-
-export type AgentPlugin<K extends PluginKind = PluginKind> =
-  K extends PluginKind ? AgentPluginContract<K> : never;
-
-export interface AgentPluginSpec<K extends PluginKind> {
-  readonly kind: K;
-  prepare(): Promise<PluginPreparation<K>>;
-}
-
-/**
- * 汇总一次 Runtime 装配要使用的全部 Plugin。
- */
-export interface AgentConfig {
-  readonly plugins: readonly AgentPlugin[];
-}
-
-/**
- * 定义一个只准备声明式结果的 Runtime Plugin。
- *
- * Runtime 内部负责排序、合并、冲突检查和提交。
- */
-export function definePlugin<K extends PluginKind>(
-  spec: AgentPluginSpec<K>,
-): AgentPlugin<K> {
-  return Object.freeze({
-    kind: spec.kind,
-
-    async prepare(): Promise<PreparedPlugin<K>> {
-      const prepared = await spec.prepare();
-      const degradations = Object.freeze(
-        prepared.degradations.map((degradation) =>
-          Object.freeze({ ...degradation }),
-        ),
-      );
-
-      return Object.freeze({
-        ...prepared,
-        kind: spec.kind,
-        degradations,
-      }) as PreparedPlugin<K>;
-    },
-  }) as AgentPlugin<K>;
+export type {
+  RuntimeExtensionContribution,
+  RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
+} from "./runtime-definition";
+
+/** Host Planner 与 Runtime Assembler 之间的一次性内部 seam。 */
+export interface RuntimeAssemblyInput {
+  readonly profile: RuntimeProfileContribution;
+  readonly memoryProfile: RuntimeMemoryProfile;
+  readonly toolPolicy?: RuntimeToolSurfacePolicy;
+  readonly enabledSubagents: readonly string[];
+  readonly provider: RuntimeProviderPort;
+  readonly platform: RuntimePlatformPort;
+  readonly workspace?: WorkspacePort;
+  readonly codeExecution?: RuntimeCodeExecutionPort;
+  readonly sandbox?: RuntimeSandboxPort;
+  readonly memory?: RuntimeMemoryPort;
+  readonly hostTools: readonly PiToolCandidate[];
+  readonly skills: readonly RuntimeSkillContribution[];
+  readonly connectors: readonly RuntimeMcpServer[];
+  readonly gateway?: RuntimeGatewayPort;
+  readonly extensions: readonly RuntimeExtensionContribution[];
+  readonly subagents?: RuntimeSubagentPort;
+  readonly schedule?: RuntimeSchedulePort;
+  readonly turnEvents?: RuntimeTurnEventsPort;
+  readonly commitGuards: readonly (() => Promise<void>)[];
+  readonly degradations: readonly RuntimeDegradation[];
 }
 
-// #endregion
-
-// #region 内部候选契约与装配顺序
+// #region 内部候选契约
 
 /**
  * 保存一次已经完成校验、可供 Kernel 使用的 Runtime 结果。
@@ -259,31 +112,10 @@ export interface RuntimeSnapshot {
 export interface RuntimeCandidate {
   readonly snapshot: RuntimeSnapshot;
   readonly commitGuards: readonly (() => Promise<void>)[];
+  readonly hooks?: RuntimeAgentHooks<Cloudflare.Env, unknown, never, never>;
+  readonly turnEvents?: RuntimeTurnEventsPort;
 }
 
-const PLUGIN_ORDER: readonly PluginKind[] = Object.freeze([
-  "scope",
-  "profile",
-  "provider",
-  "platform",
-  "workspace",
-  "sandbox",
-  "memory",
-  "tool",
-  "skill",
-  "connector",
-  "extension",
-  "schedule",
-  "subagent",
-  "turn-events",
-]);
-
-const REQUIRED_PLUGIN_KINDS: readonly PluginKind[] = Object.freeze([
-  "profile",
-  "provider",
-  "platform",
-]);
-
 const DISABLED_MEMORY: RuntimeMemoryProfile = Object.freeze({
   enabled: false,
   memoryTokens: 2_000,
@@ -322,12 +154,8 @@ interface ToolSurfaceInput {
     readonly port: RuntimeMemoryPort;
     readonly profile: RuntimeMemoryProfile;
   };
-  readonly codeExecution?: RuntimeCodeExecutionPort;
-  readonly sandbox?: RuntimeSandboxPort;
   readonly hostTools: readonly PiToolCandidate[];
   readonly skills: readonly RuntimeSkillSourceBinding[];
-  readonly schedule?: RuntimeSchedulePort;
-  readonly subagents?: RuntimeSubagentPort;
   readonly enabledSubagents: readonly string[];
   readonly webSearch: Parameters<typeof basePiToolCandidates>[0];
   readonly extensions: readonly RuntimeExtensionConfig[];
@@ -355,50 +183,24 @@ async function createToolSurface(
   const browserCandidates = input.platform.browser
     ? browserQuickActionPiToolCandidates(input.platform.browser)
     : [];
-  const workspaceCandidates = input.workspace
-    ? workspacePiToolCandidates(input.workspace)
-    : [];
-  const executionCandidates = input.workspace && input.codeExecution
-    ? [codeExecutionPiToolCandidate(input.codeExecution)]
-    : [];
-  const sandboxCandidates = input.sandbox
-    ? sandboxPiToolCandidates(input.sandbox)
-    : [];
-  const subagentCandidates = subagentPiToolCandidates(
-    input.subagents,
-    input.enabledSubagents,
-  );
-  const scheduleCandidates = input.schedule
-    ? schedulePiToolCandidates(input.schedule)
-    : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
     ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
     : [];
   const scriptCandidates = [
     ...browserCandidates,
-    ...workspaceCandidates,
-    ...executionCandidates,
-    ...sandboxCandidates,
     ...input.hostTools,
-    ...scheduleCandidates,
-    ...subagentCandidates,
     ...baseCandidates,
     ...memoryCandidates,
   ].filter(visible);
   const staticCandidates = [
     ...browserCandidates,
-    ...workspaceCandidates,
-    ...executionCandidates,
-    ...sandboxCandidates,
     ...input.hostTools,
     ...(await skillPiToolCandidates(input.skills, {
       loader: input.platform.loader,
       ...(input.workspace ? { workspace: input.workspace } : {}),
       tools: scriptCandidates,
     })),
-    ...scheduleCandidates,
-    ...subagentCandidates,
     ...baseCandidates,
     ...memoryCandidates,
   ];
@@ -441,6 +243,7 @@ class RuntimeBuilder {
   private profile?: RuntimeProfileContribution;
   private provider?: RuntimeProviderPort;
   private platform?: RuntimePlatformPort;
+  private gateway?: RuntimeGatewayPort;
   private workspace?: WorkspacePort;
   private codeExecution?: RuntimeCodeExecutionPort;
   private sandbox?: RuntimeSandboxPort;
@@ -466,68 +269,36 @@ class RuntimeBuilder {
   private readonly commitGuards: Array<() => Promise<void>> = [];
   private readonly degradations: RuntimeDegradation[] = [];
 
-  merge(prepared: PreparedPlugin): void {
-    for (const degradation of prepared.degradations) {
+  merge(input: RuntimeAssemblyInput): void {
+    for (const degradation of input.degradations) {
       this.reportDegradation(degradation);
     }
-
-    switch (prepared.kind) {
-      case "scope":
-        this.commitGuards.push(...prepared.commitGuards);
-        break;
-      case "profile":
-        if (!EXECUTION_LEVELS.includes(prepared.profile.executionLevel)) {
-          throw new Error("Runtime execution level is invalid");
-        }
-        this.profile = prepared.profile;
-        break;
-      case "provider":
-        this.provider = prepared.provider;
-        break;
-      case "platform":
-        this.platform = prepared.platform;
-        break;
-      case "workspace":
-        this.workspace = prepared.workspace;
-        this.codeExecution = prepared.codeExecution;
-        break;
-      case "sandbox":
-        this.sandbox = prepared.sandbox;
-        break;
-      case "memory":
-        this.memoryProfile = prepared.memoryProfile;
-        this.memory = prepared.memoryPort;
-        break;
-      case "tool":
-        this.hostTools.push(...prepared.hostTools);
-        this.toolPolicy = prepared.policy;
-        break;
-      case "skill":
-        for (const skill of prepared.skills) this.addSkill(skill);
-        break;
-      case "connector":
-        for (const connector of prepared.connectors) {
-          this.addConnector(connector);
-        }
-        break;
-      case "extension":
-        for (const { name, extension } of prepared.extensions) {
-          this.addExtension(name, extension);
-        }
-        break;
-      case "schedule":
-        this.schedule = prepared.schedule;
-        break;
-      case "subagent":
-        for (const name of prepared.enabledSubagents) {
-          this.enabledSubagents.add(requiredName(name, "Subagent"));
-        }
-        this.subagents = prepared.subagents;
-        break;
-      case "turn-events":
-        this.turnEvents = prepared.turnEvents;
-        break;
+    if (!EXECUTION_LEVELS.includes(input.profile.executionLevel)) {
+      throw new Error("Runtime execution level is invalid");
     }
+    this.profile = input.profile;
+    this.provider = input.provider;
+    this.platform = input.platform;
+    this.workspace = input.workspace;
+    this.codeExecution = input.codeExecution;
+    this.sandbox = input.sandbox;
+    this.memoryProfile = input.memoryProfile;
+    this.memory = input.memory;
+    this.hostTools.push(...input.hostTools);
+    this.toolPolicy = input.toolPolicy;
+    for (const skill of input.skills) this.addSkill(skill);
+    for (const connector of input.connectors) this.addConnector(connector);
+    this.gateway = input.gateway;
+    for (const { name, extension } of input.extensions) {
+      this.addExtension(name, extension);
+    }
+    this.schedule = input.schedule;
+    for (const name of input.enabledSubagents) {
+      this.enabledSubagents.add(requiredName(name, "Subagent"));
+    }
+    this.subagents = input.subagents;
+    this.turnEvents = input.turnEvents;
+    this.commitGuards.push(...input.commitGuards);
   }
 
   private addSkill(skill: RuntimeSkillContribution): void {
@@ -614,17 +385,17 @@ class RuntimeBuilder {
 // #region RuntimeBuilder 校验与候选生成
 
   // 作用：校验全部声明，并生成一个不可变候选 Runtime。
-  // 调用：所有 Plugin 按固定顺序完成合并后调用一次。
+  // 调用：扁平 Assembly Input 合并完成后调用一次。
   // 原因：所有交叉约束都在这里通过后才返回候选，旧 Snapshot 不会半更新。
   async build(): Promise<RuntimeCandidate> {
     if (!this.profile) {
-      throw new Error("Runtime profile Plugin did not configure a profile");
+      throw new Error("Runtime assembly did not configure a profile");
     }
     if (!this.platform) {
-      throw new Error("Runtime platform Plugin did not bind a platform");
+      throw new Error("Runtime assembly did not bind a platform");
     }
     if (!this.provider) {
-      throw new Error("Runtime provider Plugin did not bind a provider");
+      throw new Error("Runtime assembly did not bind a provider");
     }
     if (!this.profile.model.trim()) {
       throw new Error("Runtime model must not be empty");
@@ -653,17 +424,7 @@ class RuntimeBuilder {
     assertMemoryProfile(this.memoryProfile);
     if (this.memoryProfile.enabled && (!this.workspace || !this.memory)) {
       throw new Error(
-        "Enabled Runtime memory requires Workspace and Memory ports",
-      );
-    }
-    if (this.sandbox && !this.workspace) {
-      throw new Error(
-        "Runtime Sandbox requires a persistent Workspace port",
-      );
-    }
-    if (this.enabledSubagents.size > 0 && !this.subagents) {
-      throw new Error(
-        "Enabled Runtime Subagents require a Subagent port",
+        "Enabled Runtime memory requires Workspace and Memory bindings",
       );
     }
     const profile = freezeRuntimeProfile({
@@ -713,12 +474,8 @@ class RuntimeBuilder {
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: { port: this.memory, profile: this.memoryProfile } }
         : {}),
-      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
-      ...(this.sandbox ? { sandbox: this.sandbox } : {}),
       hostTools: this.hostTools,
       skills: skillSources,
-      ...(this.schedule ? { schedule: this.schedule } : {}),
-      ...(this.subagents ? { subagents: this.subagents } : {}),
       enabledSubagents: [...this.enabledSubagents],
       webSearch,
       extensions: [...this.extensions.values()],
@@ -730,6 +487,7 @@ class RuntimeBuilder {
     const bindings: RuntimeBindings = Object.freeze({
       provider,
       platform: Object.freeze({ ...this.platform }),
+      ...(this.gateway ? { gateway: this.gateway } : {}),
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: this.memory }
@@ -764,75 +522,23 @@ class RuntimeBuilder {
 
 }
 
-// 作用：检查 Plugin kind 合法、唯一，并包含所有必需能力。
-// 调用：任何 prepare 启动前由 `prepareRuntimeCandidate` 调用。
-// 原因：先校验结构可避免为注定失败的配置执行外部读取。
-function validatePluginKinds(
-  plugins: readonly AgentPlugin[],
-): void {
-  const kinds = new Set<PluginKind>();
-  const knownKinds = new Set(PLUGIN_ORDER);
-
-  for (const plugin of plugins) {
-    if (!knownKinds.has(plugin.kind)) {
-      throw new Error(`Unknown Agent Plugin kind: ${plugin.kind}`);
-    }
-    if (kinds.has(plugin.kind)) {
-      throw new Error(
-        `Duplicate Agent Plugin kind: ${plugin.kind}`,
-      );
-    }
-    kinds.add(plugin.kind);
-  }
-
-  for (const required of REQUIRED_PLUGIN_KINDS) {
-    if (!kinds.has(required)) {
-      throw new Error(
-        `Missing required Agent Plugin: ${required}`,
-      );
-    }
-  }
-}
-
 /**
  * 在不改动当前 Runtime 的前提下生成一个隔离候选。
  *
  * @remarks
  * `AgentRuntimeKernel` 在初始化或重载时调用它。
  *
- * prepare 并行执行，声明按固定 kind 顺序合并，任何失败都不会产生 commit。
+ * 任何合并、校验或 Tool Surface 构建失败都不会产生 commit。
  *
  * 该函数有意不从包入口导出，提交生命周期只能由 Kernel 控制。
  *
  * @internal
  */
 export async function prepareRuntimeCandidate(
-  config: AgentConfig,
+  input: RuntimeAssemblyInput,
 ): Promise<RuntimeCandidate> {
-  validatePluginKinds(config.plugins);
-
-  const prepared = await Promise.all(
-    config.plugins.map(async (plugin) => {
-      const result = await plugin.prepare();
-      if (result.kind !== plugin.kind) {
-        throw new Error(
-          `Prepared Agent Plugin kind mismatch: expected ${plugin.kind}, got ${result.kind}`,
-        );
-      }
-      return result;
-    }),
-  );
-  const byKind = new Map(
-    prepared.map((plugin) => [plugin.kind, plugin]),
-  );
   const builder = new RuntimeBuilder();
-
-  for (const kind of PLUGIN_ORDER) {
-    const plugin = byKind.get(kind);
-    if (!plugin) continue;
-    builder.merge(plugin);
-  }
-
+  builder.merge(input);
   return builder.build();
 }
 
@@ -846,15 +552,242 @@ export async function prepareRuntimeCandidate(
  *
  * @internal
  */
-export async function initializeRuntimeConfig(
-  config: AgentConfig,
+export async function assembleRuntime(
+  input: RuntimeAssemblyInput,
   commit: (snapshot: RuntimeSnapshot) => void,
 ): Promise<void> {
-  const candidate = await prepareRuntimeCandidate(config);
+  const candidate = await prepareRuntimeCandidate(input);
   for (const guard of candidate.commitGuards) {
     await guard();
   }
   commit(candidate.snapshot);
 }
 
+export function toolRegistryPiToolCandidates(
+  registry: ToolRegistry,
+  settings?: Pick<RuntimeSettings, "toolPolicy">,
+): PiToolCandidate[] {
+  const deny = new Set(settings?.toolPolicy?.denyPolicy?.deny ?? []);
+  const allowsTool = settings?.toolPolicy?.allowsTool;
+  const candidates: PiToolCandidate[] = [];
+  for (const [name, spec] of Object.entries(registry)) {
+    if (deny.has(name)) continue;
+    if (allowsTool?.(name) === false) continue;
+    const normalized = requiredName(name, "Platform Tool");
+    candidates.push(Object.freeze({
+      owner: "platform",
+      authorized: true,
+      requiredExecutionLevel: spec.requiredExecutionLevel,
+      ...(spec.alwaysRequiresApproval
+        ? { alwaysRequiresApproval: true }
+        : {}),
+      tool: Object.freeze({
+        name: normalized,
+        label: spec.label,
+        description: spec.description,
+        parameters: spec.parameters,
+        async execute(
+          toolCallId: string,
+          input: unknown,
+          signal?: AbortSignal,
+        ) {
+          const result = await spec.execute(input, {
+            toolCallId,
+            signal: signal ?? new AbortController().signal,
+          });
+          if (
+            result != null &&
+            typeof result === "object" &&
+            "content" in result &&
+            Array.isArray((result as { content?: unknown }).content)
+          ) {
+            return result as import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
+          }
+          let text: string;
+          try {
+            text = JSON.stringify(result) ?? String(result);
+          } catch {
+            text = String(result);
+          }
+          return {
+            content: [{ type: "text" as const, text }],
+            details: result,
+          };
+        },
+      } as AgentTool<any, any>),
+    }));
+  }
+  return candidates;
+}
+
+function hooksToTurnEventsPort<
+  Env extends Cloudflare.Env,
+  Config,
+  Command,
+  Change,
+>(
+  ctx: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>["ctx"],
+  hooks?: RuntimeAgentHooks<Env, Config, Command, Change>,
+): RuntimeTurnEventsPort | undefined {
+  if (!hooks) return undefined;
+  if (
+    !hooks.onTurnEnd &&
+    !hooks.onModelUsage &&
+    !hooks.onToolSettled &&
+    !hooks.onApproval &&
+    !hooks.onActivityChanged &&
+    !hooks.onSubmissionTerminal
+  ) {
+    return undefined;
+  }
+  return {
+    onResponse: hooks.onTurnEnd
+      ? (messages) => hooks.onTurnEnd!(ctx, messages)
+      : async () => undefined,
+    ...(hooks.onModelUsage ? { onModelUsage: hooks.onModelUsage } : {}),
+    ...(hooks.onToolSettled ? { onToolSettled: hooks.onToolSettled } : {}),
+    ...(hooks.onApproval ? { onApproval: hooks.onApproval } : {}),
+    ...(hooks.onActivityChanged
+      ? { onActivityChanged: hooks.onActivityChanged }
+      : {}),
+    ...(hooks.onSubmissionTerminal
+      ? { onSubmissionTerminal: hooks.onSubmissionTerminal }
+      : {}),
+  };
+}
+
+/**
+ * 从 Config、Tool 和已加载 Resource 装配 Runtime 候选 Snapshot。
+ *
+ * @internal
+ */
+export async function assembleRuntimeSnapshot<
+  Env extends Cloudflare.Env,
+  Config,
+  Command = never,
+  Change = never,
+>(
+  input: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>,
+): Promise<RuntimeCandidate> {
+  const resources = input.resources;
+  const toolAssembly = input.tools;
+  const settings = resources.settings;
+  const provider = resources.provider;
+  let profile = settings.profile;
+  if (input.hooks?.profileOverrides) {
+    const overrides = await input.hooks.profileOverrides(
+      input.ctx,
+      input.config,
+    );
+    if (overrides.systemPrompt !== undefined) {
+      profile = { ...profile, systemPrompt: overrides.systemPrompt };
+    }
+    if (overrides.executionLevel !== undefined) {
+      profile = { ...profile, executionLevel: overrides.executionLevel };
+    }
+  }
+
+  const hostTools = toolRegistryPiToolCandidates(
+    toolAssembly.tools,
+    settings,
+  );
+
+  const commitGuards: Array<() => Promise<void>> = [];
+  if (toolAssembly.commitGuard) commitGuards.push(toolAssembly.commitGuard);
+  if (input.hooks?.beforeCommit) {
+    for (const guard of input.hooks.beforeCommit) {
+      commitGuards.push(() => guard(input.ctx, input.config));
+    }
+  }
+
+  const platform: RuntimePlatformPort = input.hooks?.gateTool
+    ? Object.freeze({
+        ...resources.platform,
+        gateTool: (request: {
+          toolCallId: string;
+          toolName: string;
+          input: unknown;
+          requiredExecutionLevel: import("./lib/execution-level").ExecutionLevel;
+          signal: AbortSignal;
+        }) => input.hooks!.gateTool!(request),
+      })
+    : resources.platform;
+
+  const memoryProfile =
+    toolAssembly.memoryProfile ?? settings.memoryProfile;
+  const enabledSubagents =
+    toolAssembly.enabledSubagents ?? settings.enabledSubagents;
+  const turnEvents = hooksToTurnEventsPort(input.ctx, input.hooks);
+
+  const toolPolicy: RuntimeToolSurfacePolicy | undefined =
+    settings.toolPolicy || toolAssembly.surfacePolicy
+      ? {
+          ...(settings.toolPolicy?.denyPolicy
+            ? { denyPolicy: settings.toolPolicy.denyPolicy }
+            : {}),
+          ...(settings.toolPolicy?.allowsTool
+            ? { allowsTool: settings.toolPolicy.allowsTool }
+            : {}),
+          ...(settings.toolPolicy?.allowsExtension
+            ? { allowsExtension: settings.toolPolicy.allowsExtension }
+            : {}),
+          ...(toolAssembly.surfacePolicy?.allowsTool
+            ? { allowsTool: toolAssembly.surfacePolicy.allowsTool }
+            : {}),
+          ...(toolAssembly.surfacePolicy?.allowsExtension
+            ? { allowsExtension: toolAssembly.surfacePolicy.allowsExtension }
+            : {}),
+        }
+      : undefined;
+
+  const assemblyInput: RuntimeAssemblyInput = {
+    profile,
+    memoryProfile,
+    ...(toolPolicy ? { toolPolicy } : {}),
+    enabledSubagents: [...enabledSubagents],
+    provider,
+    platform,
+    ...(toolAssembly.bindings?.workspace
+      ? { workspace: toolAssembly.bindings.workspace }
+      : {}),
+    ...(memoryProfile.enabled && toolAssembly.bindings?.memory
+      ? { memory: toolAssembly.bindings.memory }
+      : {}),
+    hostTools,
+    skills: resources.skills,
+    connectors: resources.connectors.servers,
+    ...(resources.connectors.gateway
+      ? { gateway: resources.connectors.gateway }
+      : {}),
+    extensions: resources.extensions,
+    ...(turnEvents ? { turnEvents } : {}),
+    commitGuards: [],
+    degradations: [
+      ...(toolAssembly.degradations ?? []),
+      ...(resources.degradations ?? []),
+      ...resources.connectors.degradations,
+    ],
+  };
+
+  const candidate = await prepareRuntimeCandidate(assemblyInput);
+  return Object.freeze({
+    snapshot: candidate.snapshot,
+    commitGuards: Object.freeze([
+      ...candidate.commitGuards,
+      ...commitGuards,
+    ]),
+    ...(input.hooks
+      ? {
+          hooks: input.hooks as unknown as RuntimeAgentHooks<
+            Cloudflare.Env,
+            unknown,
+            never,
+            never
+          >,
+        }
+      : {}),
+    ...(turnEvents ? { turnEvents } : {}),
+  });
+}
+
 // #endregion