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

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

@@ -12,12 +12,14 @@ import type {
   MessageDelivery,
   MessageDispatchReceipt,
   SubmissionReceipt,
+  StoredRuntimeKey,
+  RuntimeKeyRewrite,
 } from "../../submission";
 import type { RuntimeState } from "../../conversation";
 import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentLaunch,
+  TemporaryAgentLaunchSelection,
 } from "../../tools";
 import { TEMPORARY_AGENT_LAUNCH_KEY } from "../../tools";
 import {
@@ -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> {
@@ -83,7 +88,7 @@ export interface LoadedRuntime<Config> {
 export interface RuntimeConfigUpdate<Change> {
   readonly changed: boolean;
   readonly change: Change;
-  /** Restore any committed config state when the replacement Runtime cannot load. */
+  /** Restore committed state if an immediate replacement fails. */
   readonly rollback?: () => Promise<void>;
 }
 
@@ -96,16 +101,27 @@ interface RuntimeAgentDefinitionBase<
   /** 必须等于 Worker 导出名（Wrangler `class_name`）。 */
   readonly name: string;
 
-  /** Refresh Host-owned inputs before a new Submission is pinned. Never runs on continuation/recovery. */
+  /** 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 first execution. */
+  readonly afterSubmission?: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+  ) => Promise<void>;
 
   readonly load: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     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,
@@ -114,7 +130,7 @@ interface RuntimeAgentDefinitionBase<
   /** Prepare the optional telemetry consumer for this concrete Agent facet. */
   readonly telemetry?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ) => AgentTelemetryBinding | undefined;
+  ) => AgentTelemetryBinding | undefined | Promise<AgentTelemetryBinding | undefined>;
 }
 
 export interface ReadonlyRuntimeAgentDefinition<
@@ -262,7 +278,12 @@ export interface RuntimeAgentControls {
    */
   submitScheduledPrompt(
     prompt: string,
-    opts?: { idempotencyKey?: string },
+    opts?: {
+      idempotencyKey?: string;
+      scheduledMaxExecutionLevel?: import("../../lib/execution-level").ExecutionLevel;
+      /** @deprecated Retained for rolling upgrades; ignored by Runtime. */
+      unattendedExecutionGrant?: import("../../submission").RuntimeUnattendedExecutionGrant;
+    },
   ): Promise<SubmissionReceipt>;
   /**
    * 按提交编号查询当前处理状态。
@@ -311,6 +332,7 @@ declare class RuntimeAgentHostSeam {
   protected prepareToolInteractionResponse(
     input: import("./agent").ToolInteractionResponsePreparation,
   ): Promise<unknown | null>;
+  protected hasUnfinishedRuntimeWork(): boolean;
 }
 
 /**
@@ -354,10 +376,9 @@ 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<Config>(
-  input: unknown,
-): TemporaryAgentLaunch<Config> {
+function parseTemporaryAgentLaunch(input: unknown): TemporaryAgentLaunchSelection {
   const record = input != null && typeof input === "object"
     ? input as Record<string, unknown>
     : {};
@@ -375,17 +396,15 @@ function parseTemporaryAgentLaunch<Config>(
   ) {
     throw new Error("invalid temporary agent executionLevel");
   }
-  if (!("config" in record)) {
-    throw new Error("invalid temporary agent config");
-  }
-  return {
+  const selection: TemporaryAgentLaunchSelection = {
     subagentName: read("subagentName", 128),
     instructions: read("instructions", 65_536),
     task: read("task", 65_536),
     runtimeKey: read("runtimeKey", 512),
-    config: record.config as Config,
     executionLevel: executionLevel as ExecutionLevel,
   };
+  if ("config" in record) throw new Error("unexpected temporary agent config");
+  return selection;
 }
 
 /**
@@ -406,15 +425,17 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  const resolveDefinitionTelemetry = (
+  const resolveDefinitionTelemetry = async (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ): AgentTelemetryBinding | undefined => {
+  ): Promise<AgentTelemetryBinding | undefined> => {
     const telemetry = definition.telemetry;
     if (!telemetry) return undefined;
-    return (telemetry as (
+    return await (telemetry as (
       context: RuntimeAgentPlanningContext<Env, Command, Change>,
-    ) => AgentTelemetryBinding | undefined)(context);
+    ) => 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> {
@@ -423,9 +444,71 @@ export function defineRuntimeAgent<
       private loading?: Promise<void>;
       private telemetryResolved = false;
       private resolvedTelemetry?: AgentTelemetryBinding;
-      private temporaryLaunch?: TemporaryAgentLaunch<Config>;
+      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
@@ -440,15 +523,27 @@ 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 prepareRuntimeForSubmission(submissionId: string): Promise<void> {
+      protected async prepareRuntimeForAdmission(): Promise<{
+        runtimeKey: string;
+        admission?: RuntimeSubmissionAdmissionHook;
+      }> {
         const beforeSubmission = definition.beforeSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["beforeSubmission"];
+        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> {
+        const afterSubmission = definition.afterSubmission as RuntimeAgentDefinitionBase<Env, Config, Command, Change>["afterSubmission"];
         try {
-          const changed = await beforeSubmission?.(this.createDefinitionContext(undefined, submissionId));
-          await this.ensureConfig(undefined, changed === true);
+          await this.ensureRuntimeReady();
+          await afterSubmission?.(this.createDefinitionContext(undefined, submissionId));
         } catch (error) {
           this.hasLoadedRuntime = false;
           throw error;
@@ -462,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(
@@ -475,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> {
@@ -546,13 +651,105 @@ export function defineRuntimeAgent<
         if (this.role !== "temporary") {
           throw new Error("Agent Tool runs require a temporary child facet");
         }
-        const launch = parseTemporaryAgentLaunch<Config>(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 则等待前序完成后再判断。
@@ -601,64 +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");
-            }
-            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 = 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 已就绪」的信号。
@@ -718,7 +867,7 @@ export function defineRuntimeAgent<
         resources: ResolvedResources,
       ): Promise<ResolvedResources> {
         const launch = this.temporaryLaunch ??
-          await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+          await this.ctx.storage.get<TemporaryAgentLaunchSelection>(
             TEMPORARY_AGENT_LAUNCH_KEY,
           );
         if (!launch) throw new Error("Temporary Agent is not initialized");
@@ -749,7 +898,7 @@ export function defineRuntimeAgent<
       }
 
       private async requestParentTemporaryApproval(
-        launch: TemporaryAgentLaunch<Config>,
+        launch: TemporaryAgentLaunchSelection,
         request: {
           toolCallId: string;
           toolName: string;
@@ -815,7 +964,7 @@ export function defineRuntimeAgent<
         this.temporaryCleanup = (async () => {
           if (!this.temporaryDispose) {
             const launch = this.temporaryLaunch ??
-              await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+              await this.ctx.storage.get<TemporaryAgentLaunchSelection>(
                 TEMPORARY_AGENT_LAUNCH_KEY,
               );
             if (launch) await this.ensureConfig(launch.runtimeKey);
@@ -885,7 +1034,6 @@ export function defineRuntimeAgent<
                     input: {
                       ...normalized,
                       runtimeKey: agent.loadedRuntimeKey,
-                      config: runtimeConfig.value,
                       executionLevel: agent.executionLevel(),
                     },
                     runId: `temporary-agent:${runContext.toolCallId}`,

package/src/adapter/cloudflare/index.ts

@@ -23,8 +23,26 @@ export {
 export {
   isValidTimeZone,
   nextCronOccurrence,
+  wallTimeInstants,
   zoneOffsetMs,
 } from "./scheduling/zoned-cron";
+export {
+  DEFAULT_LATENESS_WINDOW_MS,
+  isWithinLatenessWindow,
+  nextScheduledOccurrence,
+  resolveScheduleOccurrences,
+  toScheduleRuleSpec,
+  validateScheduleRuleSpec,
+  type LocalScheduleTrigger,
+  type ScheduledOccurrence,
+  type ScheduleOccurrence,
+  type ScheduleOccurrenceResolution,
+  type ScheduleRuleError,
+  type ScheduleRuleErrorCode,
+  type ScheduleRuleSpec,
+  type ScheduleSkipReason,
+  type SkippedOccurrence,
+} from "./scheduling/schedule-rule";
 
 export {
   CloudflareSandboxAdapter,