@springbrand/agent-runtime 0.3.0-alpha.20 → 0.3.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.20",
+  "version": "0.3.0-alpha.21",
   "type": "module",
   "files": [
     "src",

package/src/adapter/cloudflare/agent.ts

@@ -19,6 +19,7 @@ import {
   isTerminalSubmissionStatus,
   SubmissionLifecycle,
   SubmissionAdmission,
+  ADMISSION_ATTEMPT_WINDOW_MS,
   SubmissionDelivery,
   SubmissionFinalizer,
   projectSubmissionReceipt,
@@ -33,6 +34,8 @@ import {
   type SubmissionReceipt,
   type SubmissionExecutionMode,
   type SubmissionHandle,
+  type StoredRuntimeKey,
+  type RuntimeKeyRewrite,
   type RuntimeUnattendedExecutionGrant,
 } from "../../submission";
 import type { ExecutionLevel } from "../../lib/execution-level";
@@ -43,7 +46,6 @@ import {
   RuntimeLoadTracker,
   prepareRuntimeCandidate,
   projectRuntimeAssembly,
-  type PreparedPiRuntime,
   type RuntimeAssemblyInput,
   type RuntimeAssemblyView,
   type RuntimeCandidate,
@@ -88,7 +90,10 @@ import {
   type TemporaryAgentRequest,
   type TemporaryAgentRunContext,
 } from "../../tools";
-import { sha256Hex } from "../../lib/artifacts";
+import {
+  ASK_USER_TOOL_NAME,
+  askUserPiToolCandidate,
+} from "../../tools/assistant/ask-user";
 import { RuntimeDatabase } from "./database";
 
 /**
@@ -156,17 +161,22 @@ export abstract class AgentRuntimeKernel<
   };
 
   protected abstract ensureRuntimeReady(): Promise<void>;
-  /** Prepare per-Submission Host state before the first assembly pin. */
+  /** Prepare per-Submission Host state before first execution. */
   protected prepareRuntimeForSubmission(_submissionId: string): Promise<void> {
     return this.ensureRuntimeReady();
   }
 
   /** Runs before a new Submission records its Runtime key. */
-  protected prepareRuntimeForAdmission(): Promise<void> {
-    return this.ensureRuntimeReady();
+  protected async prepareRuntimeForAdmission(): Promise<{
+    runtimeKey: string;
+    admission?: ActiveRuntime["admission"];
+  }> {
+    await this.ensureRuntimeReady();
+    const runtime = this.requireRuntime();
+    return { runtimeKey: runtime.runtimeKey, admission: runtime.admission };
   }
 
-  protected ensureRuntimeVersion(_runtimeKey: string): Promise<void> {
+  protected ensureRuntimeVersion(_runtimeKey: string, _force = false): Promise<void> {
     return this.ensureRuntimeReady();
   }
   protected get submissionContext() {
@@ -176,6 +186,37 @@ export abstract class AgentRuntimeKernel<
     };
   }
 
+  /** Narrow storage seam for Host-validated, one-time Agent identity upgrades. */
+  protected savedRuntimeKeys(): readonly StoredRuntimeKey[] {
+    return this.db.submissions.listRuntimeKeys();
+  }
+
+  protected rewriteSavedRuntimeKeys(rewrites: readonly RuntimeKeyRewrite[]): void {
+    this.db.submissions.rewriteRuntimeKeys(rewrites);
+  }
+
+  /** One Runtime-owned fact for Host lifecycle guards; includes async preparation. */
+  protected hasUnfinishedRuntimeWork(): boolean {
+    return this.submissions.isBusy() ||
+      this.db.submissionAdmissions.countPending(Date.now() - ADMISSION_ATTEMPT_WINDOW_MS) > 0 ||
+      this.db.agentTools.hasRunning() ||
+      Boolean(
+        this.state.turn?.activeSubmissionId ||
+        this.state.approvals?.length ||
+        (this.state.activity?.activity && this.state.activity.activity !== "idle"),
+      );
+  }
+
+  /** True while a Submission owns this Chat's active execution slice. */
+  protected isSubmissionExecuting(): boolean {
+    return this.submissions.currentActive() !== undefined;
+  }
+
+  /** External Runtime changes share the same serial queue as Submission execution. */
+  protected runConfigControl<T>(run: () => Promise<T>): Promise<T> {
+    return this.submissions.runConfigControl(run);
+  }
+
   /** Let the Host prepare a validated client response before Tool settlement. */
   protected prepareToolInteractionResponse(
     input: ToolInteractionResponsePreparation,
@@ -318,7 +359,6 @@ export abstract class AgentRuntimeKernel<
       createExtensionHostBinding: (permissions, labels) =>
         this.createExtensionHostBinding(permissions, labels),
       advance: (phase) => this.runtimeLoad.advance(phase),
-      isExecuting: () => Boolean(this.submissions.currentActive()),
       commit: (runtime) => {
         this.telemetry.configure(candidate.telemetry);
         this.activeRuntime = runtime;
@@ -516,57 +556,7 @@ export abstract class AgentRuntimeKernel<
 
   // #endregion
 
-  // #region Submission 准入与配置固定
-
-  /** Pin dynamic Context and execution policy before the first assembly is used. */
-  private async admissionPin(fresh: boolean, submissionId: string): Promise<{
-    revision: string;
-    descriptor: string;
-  }> {
-    if (fresh) await this.prepareRuntimeForSubmission(submissionId);
-    const submission = this.db.submissions.find(submissionId);
-    if (!submission) {
-      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
-    }
-    return this.currentAssemblyPin(submission.origin !== "scheduled");
-  }
-
-  // initConfig can call this inside its serialized load; re-entering ensureRuntimeReady would deadlock.
-  private async currentAssemblyPin(includeMemory = true): Promise<{
-    revision: string;
-    descriptor: string;
-  }> {
-    await this.runtimeTurnEvents.drain();
-    const runtime = this.activeRuntime;
-    if (!runtime) {
-      throw new Error("Runtime revision is not initialized");
-    }
-    return this.pinAssembly(runtime.pi, runtime.revision, includeMemory);
-  }
-
-  private async pinAssembly(
-    prepared: PreparedPiRuntime,
-    baseRevision: string,
-    includeMemory: boolean,
-  ): Promise<{ revision: string; descriptor: string }> {
-    const pinned = await this.pi.pin({
-      prepared,
-      baseRevision,
-      includeMemory,
-      readExtensionContext: ({ label }) =>
-        this._hostGetContext(label),
-    });
-    if (pinned.degradations.length > 0) {
-      console.warn(
-        "[runtime-context:degraded]",
-        json({ degradations: pinned.degradations }),
-      );
-    }
-    return {
-      revision: await sha256Hex(pinned.descriptor),
-      descriptor: pinned.descriptor,
-    };
-  }
+  // #region Submission 准入与当前配置
 
   private get admission(): SubmissionAdmission {
     return this.submissionAdmission ??= new SubmissionAdmission({
@@ -574,10 +564,7 @@ export abstract class AgentRuntimeKernel<
       steers: this.db.steers,
       submissions: this.db.submissions,
       transaction: (run) => this.db.transaction(run),
-      prepareRuntime: async () => {
-        await this.prepareRuntimeForAdmission();
-        return { runtimeKey: this.activeRuntime!.runtimeKey, admission: this.activeRuntime?.admission };
-      },
+      prepareRuntime: () => this.prepareRuntimeForAdmission(),
       findUserMessage: (id) => this.transcript.findUserMessage(id),
       onAdmitted: (submission, hostAccepted) =>
         this.runtimeTurnEvents.submissionAdmitted(submission, hostAccepted),
@@ -783,27 +770,32 @@ export abstract class AgentRuntimeKernel<
   ): Promise<StoredSubmission> {
     const continuation = mode !== "fresh";
     const submissionId = submission.submissionId;
-    submission = await this.admission.pin(
+    submission = await this.admission.prepareCurrentRuntime(
       submission,
-      () => this.admissionPin(mode === "fresh", submissionId),
-      (key) => this.ensureRuntimeVersion(key),
+      (key) => this.ensureRuntimeVersion(key, true),
     );
+    if (!continuation) await this.prepareRuntimeForSubmission(submissionId);
+    await this.runtimeTurnEvents.drain();
     const activeRuntime = this.requireRuntime();
     // A fresh provider Session per Submission keeps one failing upstream route from pinning later turns.
     const recovery = new ModelRecovery(submissionId);
-    const harnessInput = this.pi.harnessInputs(
+    const harnessInput = await this.pi.harnessInputs(
       activeRuntime.pi,
-      submission.assemblyDescriptor,
       {
-          modelSessionId: () => recovery.sessionId(),
-          assertRequestAllowed: () => {
-            const current = this.db.submissions.find(submissionId);
-            if (current?.abortReason || current?.unattendedFailure) throw new Error(current.abortReason ?? current.unattendedFailure!);
-          },
-          onGeneration: (event) => this.telemetry.generation(submissionId, event),
-          onCompactionGeneration: (event) => this.runtimeTurnEvents.compactionGeneration(submissionId, event),
+        modelSessionId: () => recovery.sessionId(),
+        assertRequestAllowed: () => {
+          const current = this.db.submissions.find(submissionId);
+          if (current?.abortReason || current?.unattendedFailure) throw new Error(current.abortReason ?? current.unattendedFailure!);
+        },
+        onGeneration: (event) => this.telemetry.generation(submissionId, event),
+        onCompactionGeneration: (event) => this.runtimeTurnEvents.compactionGeneration(submissionId, event),
+        includeMemory: submission.origin !== "scheduled",
+        readExtensionContext: ({ label }) => this._hostGetContext(label),
       },
     );
+    if (harnessInput.degradations.length > 0) {
+      console.warn("[runtime-context:degraded]", json({ degradations: harnessInput.degradations }));
+    }
     const prepareToolInput = (toolName: string, input: unknown): unknown => {
       const prepare = harnessInput.candidates.find(({ tool }) =>
         tool.name === toolName
@@ -906,7 +898,6 @@ export abstract class AgentRuntimeKernel<
         this.db.submissions.transition(submissionId, "running", ["pending"]);
         this.telemetry.capture("turnStarted", {
           submissionId,
-          assemblyRevision: submission.assemblyRevision,
         });
         submission = this.db.submissions.find(submissionId)!;
       }
@@ -1533,11 +1524,19 @@ export abstract class AgentRuntimeKernel<
     if (!submission || isTerminalSubmissionStatus(submission.status)) {
       return { ok: false };
     }
-    await this.ensureRuntimeReady();
-    const spec = this.pi.harnessInputs(
-      this.requireRuntime().pi,
-      submission.assemblyDescriptor,
-    ).candidates.find(({ tool }) => tool.name === pending.toolName)?.interaction;
+    const active = this.submissions.currentActive();
+    if (active && active.submissionId !== submission.submissionId) {
+      return { ok: false };
+    }
+    // ask_user has a Config-independent validator. A parked answer must not
+    // replace the Gateway; the continuation loads current Config instead.
+    const askUser = pending.toolName === ASK_USER_TOOL_NAME;
+    if (!askUser && !active) {
+      await this.ensureRuntimeVersion(submission.runtimeKey, true);
+    }
+    const spec = askUser
+      ? askUserPiToolCandidate().interaction
+      : this.pi.interaction(this.requireRuntime().pi, pending.toolName);
     if (!spec) return { ok: false };
 
     const accepted = await this.humanDecisions.respond(

package/src/adapter/cloudflare/define-agent.ts

@@ -12,6 +12,8 @@ import type {
   MessageDelivery,
   MessageDispatchReceipt,
   SubmissionReceipt,
+  StoredRuntimeKey,
+  RuntimeKeyRewrite,
 } from "../../submission";
 import type { RuntimeState } from "../../conversation";
 import type {
@@ -31,7 +33,9 @@ import {
 } from "../../lib/execution-level";
 import {
   assembleRuntimeSnapshot,
+  verifyRuntimeCandidateGuards,
   type RuntimeCandidate,
+  type RuntimeSubmissionAdmissionHook,
 } from "../../config";
 import type {
   ResolvedResources,
@@ -71,6 +75,7 @@ export type {
   RuntimeAgentToolResult,
   RuntimeAssemblyContext,
 } from "../../config";
+export type { RuntimeKeyRewrite, StoredRuntimeKey } from "../../submission";
 
 /** Host 一次性准备的完整 Runtime 加载结果。 */
 export interface LoadedRuntime<Config> {
@@ -99,9 +104,9 @@ interface RuntimeAgentDefinitionBase<
   /** Refresh Host-owned inputs before a new Submission records its Runtime key. */
   readonly beforeSubmission?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ) => Promise<boolean>;
+  ) => Promise<void>;
 
-  /** Prepare per-Submission Host state after admission and before its first assembly pin. */
+  /** Prepare per-Submission Host state after admission and before first execution. */
   readonly afterSubmission?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
   ) => Promise<void>;
@@ -111,6 +116,12 @@ interface RuntimeAgentDefinitionBase<
     requestedRuntimeKey?: string,
   ) => Promise<LoadedRuntime<Config>>;
 
+  /** Resolve saved identities; unfinished work must still belong to the selected Agent. */
+  readonly migrateStoredRuntimeKeys?: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    keys: readonly StoredRuntimeKey[],
+  ) => Promise<readonly RuntimeKeyRewrite[]>;
+
   readonly tools: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     config: Config,
@@ -321,6 +332,7 @@ declare class RuntimeAgentHostSeam {
   protected prepareToolInteractionResponse(
     input: import("./agent").ToolInteractionResponsePreparation,
   ): Promise<unknown | null>;
+  protected hasUnfinishedRuntimeWork(): boolean;
 }
 
 /**
@@ -364,6 +376,7 @@ const TERMINAL_AGENT_TOOL_STATUSES = [
   "interrupted",
 ] as const;
 const AGENT_TOOL_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const STABLE_RUNTIME_KEY_MIGRATION = "agent-runtime:stable-runtime-key-migration-v1";
 
 function parseTemporaryAgentLaunch(input: unknown): TemporaryAgentLaunchSelection {
   const record = input != null && typeof input === "object"
@@ -421,6 +434,8 @@ export function defineRuntimeAgent<
       context: RuntimeAgentPlanningContext<Env, Command, Change>,
     ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>)(context);
   };
+  const migrateSavedKeys = definition.migrateStoredRuntimeKeys as
+    RuntimeAgentDefinitionBase<Env, Config, Command, Change>["migrateStoredRuntimeKeys"];
 
   const GeneratedRuntimeAgent = {
     [definition.name]: class extends AgentToolRuntimeKernel<Env> {
@@ -432,6 +447,68 @@ export function defineRuntimeAgent<
       private temporaryLaunch?: TemporaryAgentLaunchSelection;
       private temporaryDispose?: () => Promise<void>;
       private temporaryCleanup?: Promise<void>;
+      private storedKeyMigration?: Promise<void>;
+
+      async onStart(): Promise<void> {
+        await this.migrateStoredRuntimeKeys();
+        await super.onStart();
+      }
+
+      private async resolveSavedKeyRewrites(
+        keys: readonly StoredRuntimeKey[],
+      ): Promise<readonly RuntimeKeyRewrite[]> {
+        if (!migrateSavedKeys) {
+          return keys.map(({ runtimeKey }) => ({ from: runtimeKey, to: runtimeKey }));
+        }
+        const rewrites = await migrateSavedKeys(this.createDefinitionContext(), keys);
+        if (
+          rewrites.length !== keys.length ||
+          rewrites.some(({ from, to }, index) =>
+            from !== keys[index]?.runtimeKey || !to.trim())
+        ) {
+          throw new Error("Saved Runtime key migration returned an invalid rewrite plan");
+        }
+        return rewrites;
+      }
+
+      private migrateStoredRuntimeKeys(): Promise<void> {
+        if (!migrateSavedKeys) return Promise.resolve();
+        if (this.storedKeyMigration) return this.storedKeyMigration;
+        const migration = (async () => {
+          if (await this.ctx.storage.get<boolean>(STABLE_RUNTIME_KEY_MIGRATION)) return;
+          const savedLaunch = await this.ctx.storage.get<unknown>(TEMPORARY_AGENT_LAUNCH_KEY);
+          const launch = savedLaunch === undefined
+            ? undefined
+            : parseTemporaryAgentLaunch(savedLaunch);
+          const keysByValue = new Map(
+            this.savedRuntimeKeys().map((key) => [key.runtimeKey, key]),
+          );
+          if (launch) {
+            keysByValue.set(launch.runtimeKey, {
+              runtimeKey: launch.runtimeKey,
+              unfinished: keysByValue.get(launch.runtimeKey)?.unfinished ?? true,
+            });
+          }
+          const keys = [...keysByValue.values()];
+          if (keys.length > 0) {
+            const rewrites = await this.resolveSavedKeyRewrites(keys);
+            this.rewriteSavedRuntimeKeys(rewrites);
+            if (launch) {
+              const runtimeKey = rewrites.find(({ from }) => from === launch.runtimeKey)?.to;
+              if (!runtimeKey) throw new Error("Saved temporary Agent key was not migrated");
+              const currentLaunch = { ...launch, runtimeKey };
+              await this.ctx.storage.put(TEMPORARY_AGENT_LAUNCH_KEY, currentLaunch);
+              this.temporaryLaunch = currentLaunch;
+            }
+          }
+          await this.ctx.storage.put(STABLE_RUNTIME_KEY_MIGRATION, true);
+        })().catch((error) => {
+          this.storedKeyMigration = undefined;
+          throw error;
+        });
+        this.storedKeyMigration = migration;
+        return migration;
+      }
 
       protected get role(): RuntimeAgentRole {
         return this.parentPath.at(-1)?.className === definition.name
@@ -446,19 +523,20 @@ export function defineRuntimeAgent<
         return this.ensureConfig();
       }
 
-      protected override ensureRuntimeVersion(runtimeKey: string): Promise<void> {
-        return this.ensureConfig(runtimeKey);
+      protected override ensureRuntimeVersion(runtimeKey: string, force = false): Promise<void> {
+        return this.ensureConfig(runtimeKey, force);
       }
 
-      protected async prepareRuntimeForAdmission(): Promise<void> {
+      protected async prepareRuntimeForAdmission(): Promise<{
+        runtimeKey: string;
+        admission?: RuntimeSubmissionAdmissionHook;
+      }> {
         const beforeSubmission = definition.beforeSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["beforeSubmission"];
-        try {
-          const changed = await beforeSubmission?.(this.createDefinitionContext());
-          await this.ensureConfig(undefined, changed === true);
-        } catch (error) {
-          this.hasLoadedRuntime = false;
-          throw error;
-        }
+        await beforeSubmission?.(this.createDefinitionContext());
+        const requestedKey = this.role === "temporary"
+          ? this.loadedRuntimeKey ?? this.temporaryLaunch?.runtimeKey
+          : undefined;
+        return this.inspectCandidate(requestedKey);
       }
 
       protected async prepareRuntimeForSubmission(submissionId: string): Promise<void> {
@@ -479,7 +557,7 @@ export function defineRuntimeAgent<
         runtimeKey?: string,
         options?: { force?: boolean },
       ): Promise<void> {
-        await this.ensureConfig(runtimeKey, options?.force === true);
+        await this.runConfigControl(() => this.ensureConfig(runtimeKey, options?.force === true));
       }
 
       async updateConfig(
@@ -492,26 +570,36 @@ export function defineRuntimeAgent<
         if (!update) {
           return { change: undefined as Change, runtime: "unchanged" };
         }
-        const result = await update(this.createDefinitionContext(), command);
-        if (!result.changed) {
-          return { change: result.change, runtime: "unchanged" };
-        }
-        try {
-          await this.ensureConfig(undefined, true);
-          return { change: result.change, runtime: "reloaded" };
-        } catch (reloadError) {
-          if (result.rollback) {
-            try {
-              await result.rollback();
-            } catch (rollbackError) {
-              throw new AggregateError(
-                [reloadError, rollbackError],
-                "Runtime Config rollback failed",
-              );
+        const deferActivation = this.isSubmissionExecuting();
+        const apply = async (): Promise<RuntimeConfigUpdateResult<Change>> => {
+          const result = await update(this.createDefinitionContext(), command);
+          if (!result.changed) {
+            return { change: result.change, runtime: "unchanged" };
+          }
+          try {
+            if (deferActivation) {
+              await this.inspectCandidate();
+              return { change: result.change, runtime: "deferred" };
+            }
+            await this.ensureConfig(undefined, true);
+            return { change: result.change, runtime: "reloaded" };
+          } catch (reloadError) {
+            if (result.rollback) {
+              try {
+                await result.rollback();
+              } catch (rollbackError) {
+                throw new AggregateError(
+                  [reloadError, rollbackError],
+                  "Runtime Config rollback failed",
+                );
+              }
             }
+            return { change: result.change, runtime: "reload-failed" };
           }
-          return { change: result.change, runtime: "reload-failed" };
-        }
+        };
+        return deferActivation
+          ? apply()
+          : this.runConfigControl(apply);
       }
 
       async getRuntimeAssembly(): Promise<RuntimeAssemblyView> {
@@ -563,13 +651,105 @@ export function defineRuntimeAgent<
         if (this.role !== "temporary") {
           throw new Error("Agent Tool runs require a temporary child facet");
         }
-        const launch = parseTemporaryAgentLaunch(input);
+        const parsed = parseTemporaryAgentLaunch(input);
+        const [rewrite] = await this.resolveSavedKeyRewrites([
+          { runtimeKey: parsed.runtimeKey, unfinished: true },
+        ]);
+        const runtimeKey = rewrite?.to;
+        if (!runtimeKey) throw new Error("Temporary Agent runtime key must not be empty");
+        const launch = { ...parsed, runtimeKey };
         this.temporaryLaunch = launch;
         await this.ctx.storage.put(TEMPORARY_AGENT_LAUNCH_KEY, launch);
         await this.reloadRuntime(launch.runtimeKey, { force: true });
         return launch.task;
       }
 
+      /** One definition load and assembly path for admission and execution. */
+      private async prepareCandidate(requestedRuntimeKey?: string): Promise<{
+        candidate: RuntimeCandidate;
+        runtimeKey: string;
+        dispose?: () => Promise<void>;
+      }> {
+        const loadContext = this.createDefinitionContext();
+        const loaded = await withRuntimeLoadTimeout(
+          "definition.load",
+          () => (
+            definition.load as (
+              context: RuntimeAgentPlanningContext<Env, Command, Change>,
+              requestedRuntimeKey?: string,
+            ) => Promise<LoadedRuntime<Config>>
+          )(loadContext, requestedRuntimeKey),
+          { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
+        );
+        const runtimeKey = loaded.runtimeKey.trim();
+        if (!runtimeKey) {
+          throw new Error("Resolved Runtime key must not be empty");
+        }
+        if (requestedRuntimeKey && runtimeKey !== requestedRuntimeKey) {
+          throw new Error(
+            `Requested Runtime key ${requestedRuntimeKey} resolved to ${runtimeKey}`,
+          );
+        }
+        const context = this.createDefinitionContext({ value: loaded.config });
+        let tools = await withRuntimeLoadTimeout(
+          "definition.tools",
+          () => (
+            definition.tools as (
+              context: RuntimeAgentPlanningContext<Env, Command, Change>,
+              config: Config,
+            ) => ToolAssemblyResult | Promise<ToolAssemblyResult>
+          )(context, loaded.config),
+          { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
+        );
+        const dispose = tools.dispose;
+        try {
+          let resources = loaded.resources;
+          let commitGuard = loaded.commitGuard;
+          if (!this.telemetryResolved) {
+            this.resolvedTelemetry = await resolveDefinitionTelemetry(context);
+            this.telemetryResolved = true;
+          }
+          const telemetry = this.resolvedTelemetry;
+          if (this.role === "temporary") {
+            tools = this.applyTemporaryToolPolicy(tools);
+            resources = await this.applyTemporaryResources(resources);
+            commitGuard = undefined;
+          }
+          const candidate = await assembleRuntimeSnapshot({
+            ctx: context,
+            tools,
+            resources,
+            ...(commitGuard ? { commitGuard } : {}),
+            ...(telemetry ? { telemetry } : {}),
+          });
+          return {
+            candidate: { ...candidate, runtimeKey },
+            runtimeKey,
+            ...(dispose ? { dispose } : {}),
+          };
+        } catch (error) {
+          await dispose?.();
+          throw error;
+        }
+      }
+
+      /** Validate a candidate without changing the active Runtime or its Gateway. */
+      private async inspectCandidate(requestedRuntimeKey?: string): Promise<{
+        runtimeKey: string;
+        admission?: RuntimeSubmissionAdmissionHook;
+      }> {
+        const prepared = await this.prepareCandidate(requestedRuntimeKey);
+        try {
+          await verifyRuntimeCandidateGuards(prepared.candidate, "admission");
+          return {
+            runtimeKey: prepared.runtimeKey,
+            admission: prepared.candidate.admission,
+          };
+        } finally {
+          await prepared.dispose?.();
+        }
+      }
+
       // 作用：把首次加载和按 key 重载合并成一个串行入口。
       // 调用：Runtime readiness、Session 配置和重载都会调用。
       // 原因：共享同一个 Promise 可合并并发首加载，显式切 key 则等待前序完成后再判断。
@@ -618,69 +798,16 @@ export function defineRuntimeAgent<
           // 先创建局部 Promise，再赋给 `loading`，失败时也能在 finally 中放开重试。
           const pending = (async () => {
             this.runtimeLoad.begin();
-            const loadContext = this.createDefinitionContext();
-            const loaded = await withRuntimeLoadTimeout(
-              "definition.load",
-              () => (
-                definition.load as (
-                  context: RuntimeAgentPlanningContext<Env, Command, Change>,
-                  requestedRuntimeKey?: string,
-                ) => Promise<LoadedRuntime<Config>>
-              )(
-                loadContext,
-                requestedRuntimeKey,
-              ),
-              { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
-            );
-            const resolvedRuntimeKey = loaded.runtimeKey.trim();
-            if (!resolvedRuntimeKey) {
-              throw new Error("Resolved Runtime key must not be empty");
-            }
-            if (requestedRuntimeKey && resolvedRuntimeKey !== requestedRuntimeKey) {
-              throw new Error(
-                `Requested Runtime key ${requestedRuntimeKey} resolved to ${resolvedRuntimeKey}`,
-              );
-            }
-            const context = this.createDefinitionContext({
-              value: loaded.config,
-            });
-            let tools = await withRuntimeLoadTimeout(
-              "definition.tools",
-              () => (
-                definition.tools as (
-                  context: RuntimeAgentPlanningContext<Env, Command, Change>,
-                  config: Config,
-                ) => ToolAssemblyResult | Promise<ToolAssemblyResult>
-              )(context, loaded.config),
-              { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
-            );
-            let resources = loaded.resources;
-            let commitGuard = loaded.commitGuard;
-            if (!this.telemetryResolved) {
-              this.resolvedTelemetry = await resolveDefinitionTelemetry(context);
-              this.telemetryResolved = true;
-            }
-            const telemetry = this.resolvedTelemetry;
-            if (this.role === "temporary") {
-              this.temporaryDispose = tools.dispose;
-              tools = this.applyTemporaryToolPolicy(tools);
-              resources = await this.applyTemporaryResources(resources);
-              commitGuard = undefined;
+            const prepared = await this.prepareCandidate(requestedRuntimeKey);
+            try {
+              await this.initCandidate(prepared.candidate);
+            } catch (error) {
+              await prepared.dispose?.();
+              throw error;
             }
-            const candidate = await assembleRuntimeSnapshot({
-              ctx: context,
-              tools,
-              resources,
-              ...(commitGuard ? { commitGuard } : {}),
-              ...(telemetry ? { telemetry } : {}),
-            });
-
-            await this.initCandidate({
-              ...candidate,
-              runtimeKey: resolvedRuntimeKey,
-            });
+            if (this.role === "temporary") this.temporaryDispose = prepared.dispose;
             this.hasLoadedRuntime = true;
-            this.loadedRuntimeKey = resolvedRuntimeKey;
+            this.loadedRuntimeKey = prepared.runtimeKey;
             this.runtimeLoad.complete();
             // 提交之前 turnEvents 绑定还不存在，此前每一次广播都到不了 Host。
             // Host 的会话列表把装配后的第一次投影当作「facet 已就绪」的信号。