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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.2.0-alpha.36",
+  "version": "0.2.0-alpha.38",
   "type": "module",
   "files": [
     "src",
@@ -23,6 +23,8 @@
     "@cloudflare/think": "0.15.0",
     "@earendil-works/pi-agent-core": "0.83.0",
     "@earendil-works/pi-ai": "0.83.0",
+    "@types/lodash-es": "^4.17.12",
+    "cron-schedule": "6.0.0",
     "isomorphic-git": "1.38.6",
     "lodash-es": "^4.18.1",
     "zod": "^4.4.3"

package/src/adapter/cloudflare/dynamic-worker-observability.ts

@@ -0,0 +1,84 @@
+import type { RuntimePlatformPort } from "../../kernel/bindings";
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+export type DynamicWorkerObservation = {
+  source: string;
+  attributes?: Readonly<Record<string, string>>;
+};
+
+type TailProps = DynamicWorkerObservation & {
+  workerId: string;
+  mainModule: string;
+};
+
+type ExportContext = Pick<DurableObjectState, "exports">;
+
+function attachTail(
+  context: ExportContext,
+  code: WorkerLoaderWorkerCode,
+  observation: DynamicWorkerObservation,
+  workerId: string,
+): WorkerLoaderWorkerCode {
+  const entrypoint = (context.exports as unknown as {
+    DynamicWorkerTail(options: { props: TailProps }): Fetcher;
+  }).DynamicWorkerTail;
+  const tail = entrypoint({
+    props: { ...observation, workerId, mainModule: code.mainModule },
+  });
+  return { ...code, tails: [...(code.tails ?? []), tail] };
+}
+
+export function observeDynamicWorkers(
+  context: ExportContext,
+  loader: WorkerLoader,
+  observation: DynamicWorkerObservation,
+): WorkerLoader {
+  return {
+    load: (code) =>
+      loader.load(attachTail(context, code, observation, crypto.randomUUID())),
+    get: (name, getCode) => {
+      const workerId = name ?? crypto.randomUUID();
+      return loader.get(name, async () =>
+        attachTail(context, await getCode(), observation, workerId)
+      );
+    },
+  };
+}
+
+export function observeDynamicWorkerPlatform(
+  context: ExportContext,
+  load: () => Promise<RuntimePlatformPort>,
+  observation: DynamicWorkerObservation,
+): () => Promise<RuntimePlatformPort> {
+  return async () => {
+    const platform = await load();
+    return {
+      ...platform,
+      loader: observeDynamicWorkers(context, platform.loader, observation),
+    };
+  };
+}
+
+export class DynamicWorkerTail extends WorkerEntrypoint<Cloudflare.Env, TailProps> {
+  tail(events: TraceItem[]): void {
+    for (const event of events) {
+      console.log({
+        ...this.ctx.props.attributes,
+        source: "dynamic-worker-tail",
+        dynamicWorkerSource: this.ctx.props.source,
+        dynamicWorkerId: this.ctx.props.workerId,
+        durableObjectId: event.durableObjectId ?? null,
+        mainModule: this.ctx.props.mainModule,
+        eventTimestamp: event.eventTimestamp,
+        scriptName: event.scriptName,
+        entrypoint: event.entrypoint,
+        outcome: event.outcome,
+        truncated: event.truncated,
+        cpuTime: event.cpuTime,
+        wallTime: event.wallTime,
+        logs: event.logs,
+        exceptions: event.exceptions,
+      });
+    }
+  }
+}

package/src/adapter/cloudflare/index.ts

@@ -14,7 +14,17 @@ export {
 export {
   assembleUniversalAgentTools,
 } from "./universal-agent/tools";
-export { createUniversalAgentHooks } from "./universal-agent/hooks";
+export {
+  DynamicWorkerTail,
+  observeDynamicWorkerPlatform,
+  observeDynamicWorkers,
+  type DynamicWorkerObservation,
+} from "./dynamic-worker-observability";
+export {
+  isValidTimeZone,
+  nextCronOccurrence,
+  zoneOffsetMs,
+} from "./scheduling/zoned-cron";
 
 export {
   CloudflareSandboxAdapter,

package/src/adapter/cloudflare/scheduling/zoned-cron.ts

@@ -0,0 +1,114 @@
+import { parseCronExpression } from "cron-schedule";
+
+export function zoneOffsetMs(instant: number, timeZone: string): number {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  }).formatToParts(new Date(instant));
+  const field = (type: Intl.DateTimeFormatPartTypes) =>
+    Number(parts.find((part) => part.type === type)?.value ?? 0);
+  const wallAsUtc = Date.UTC(
+    field("year"),
+    field("month") - 1,
+    field("day"),
+    field("hour") % 24,
+    field("minute"),
+    field("second"),
+  );
+  return wallAsUtc - Math.floor(instant / 1_000) * 1_000;
+}
+
+export function nextCronOccurrence(
+  cron: string,
+  timeZone: string,
+  after = Date.now(),
+): number {
+  const parsed = parseCronExpression(cron);
+  const secondPrecision = parsed.seconds.length !== 1 || parsed.seconds[0] !== 0;
+  const step = secondPrecision ? 1_000 : 60_000;
+  for (
+    let instant = Math.floor(after / step) * step + step;
+    instant <= after + 3 * 3_600_000;
+    instant += step
+  ) {
+    if (matches(parsed, instant + zoneOffsetMs(instant, timeZone))) return instant;
+  }
+
+  const wallAfter = after + zoneOffsetMs(after, timeZone);
+  const wallDate = new Date(wallAfter);
+  const firstDay = Date.UTC(
+    wallDate.getUTCFullYear(),
+    wallDate.getUTCMonth(),
+    wallDate.getUTCDate(),
+  );
+  for (let dayOffset = 0; dayOffset <= 366 * 5; dayOffset += 1) {
+    const day = firstDay + dayOffset * 86_400_000;
+    if (!matchesDate(parsed, new Date(day))) continue;
+    for (const hour of parsed.hours) {
+      for (const minute of parsed.minutes) {
+        for (const second of parsed.seconds) {
+          const wall = day + hour * 3_600_000 + minute * 60_000 + second * 1_000;
+          if (wall <= wallAfter) continue;
+          const resolved = wallTimeCandidates(wall, timeZone, after)[0];
+          if (resolved !== undefined) return resolved;
+        }
+      }
+    }
+  }
+  throw new Error("Cron has no occurrence in the next five years");
+}
+
+export function isValidTimeZone(timeZone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function wallTimeCandidates(wallUtc: number, timeZone: string, after: number): number[] {
+  const offsets = new Set([
+    zoneOffsetMs(after, timeZone),
+    zoneOffsetMs(wallUtc - 2 * 86_400_000, timeZone),
+    zoneOffsetMs(wallUtc, timeZone),
+    zoneOffsetMs(wallUtc + 2 * 86_400_000, timeZone),
+  ]);
+  return [...offsets]
+    .map((offset) => wallUtc - offset)
+    .filter((instant) =>
+      instant > after && instant + zoneOffsetMs(instant, timeZone) === wallUtc
+    )
+    .sort((left, right) => left - right);
+}
+
+function matches(
+  cron: ReturnType<typeof parseCronExpression>,
+  wallUtc: number,
+): boolean {
+  const wall = new Date(wallUtc);
+  return cron.seconds.includes(wall.getUTCSeconds()) &&
+    cron.minutes.includes(wall.getUTCMinutes()) &&
+    cron.hours.includes(wall.getUTCHours()) &&
+    matchesDate(cron, wall);
+}
+
+function matchesDate(
+  cron: ReturnType<typeof parseCronExpression>,
+  wall: Date,
+): boolean {
+  if (!cron.months.includes(wall.getUTCMonth())) return false;
+  const daysRestricted = cron.days.length !== 31;
+  const weekdaysRestricted = cron.weekdays.length !== 7;
+  const dayMatches = cron.days.includes(wall.getUTCDate());
+  const weekdayMatches = cron.weekdays.includes(wall.getUTCDay());
+  return daysRestricted && weekdaysRestricted
+    ? dayMatches || weekdayMatches
+    : dayMatches && weekdayMatches;
+}

package/src/index.ts

@@ -24,7 +24,7 @@
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
  * - `defineRuntimeAgent.load` 返回 config 和已加载 Resource。
  * - `defineRuntimeAgent.tools` 返回 Host 的 Pi Tool Candidate 装配结果。
- * - `assembleRuntimeSnapshot` 消费该输入与 hooks，产出候选 Snapshot。
+ * - `assembleRuntimeSnapshot` 消费已加载 Resource 与 Tool，产出候选 Snapshot。
  * - `Port` 是 Runtime 调用外部能力时依赖的最小接口（Definition 作者不直接装配）。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
  * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
@@ -63,11 +63,9 @@ export type {
 } from "./runtime-assembler";
 export { assembleRuntimeSnapshot } from "./runtime-assembler";
 export type {
-  ProfileOverrides,
   ResolvedConnectors,
   ResolvedResources,
   RuntimeAgentContext,
-  RuntimeAgentHooks,
   RuntimeSettings,
   RuntimeToolBindings,
   ToolAssemblyResult,
@@ -104,6 +102,7 @@ export type {
   PiDeclaredToolPolicy,
 } from "./pi/tool";
 export { memoryPiToolCandidate } from "./pi/tool";
+export { GET_TIME_TOOL_NAME, getTimePiToolCandidate } from "./pi/tool";
 export { schedulePiToolCandidates } from "./pi/tool";
 export {
   sandboxPiToolCandidates,

package/src/pi/tool/index.ts

@@ -32,6 +32,7 @@ export * from "./mcp";
 export * from "./schedule";
 export * from "./skill";
 export * from "./subagent";
+export * from "./time";
 export * from "./workspace-sandbox";
 export * from "./workspace-revision";
 export * from "./web-search";

package/src/pi/tool/time.ts

@@ -0,0 +1,31 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { Type } from "@earendil-works/pi-ai";
+import type { PiToolCandidate } from "./compiler";
+
+export const GET_TIME_TOOL_NAME = "get_time";
+
+const parameters = Type.Object({});
+
+/** Product-neutral current-time Tool for Host registries. */
+export function getTimePiToolCandidate(owner = "utilities"): PiToolCandidate {
+  return {
+    owner,
+    requiredExecutionLevel: "safe",
+    source: "action",
+    summary: "Get the current server time as an ISO string.",
+    tool: {
+      name: GET_TIME_TOOL_NAME,
+      label: "Get Time",
+      parameters,
+      description: "Get the current server time as an ISO string.",
+      async execute(_toolCallId, _input, signal) {
+        signal?.throwIfAborted();
+        const details = { now: new Date().toISOString() };
+        return {
+          content: [{ type: "text", text: JSON.stringify(details) }],
+          details,
+        } satisfies AgentToolResult<typeof details>;
+      },
+    },
+  };
+}

package/src/runtime-agent.ts

@@ -35,7 +35,6 @@ import {
 } from "./runtime-assembler";
 import type {
   ResolvedResources,
-  RuntimeAgentHooks,
   ToolAssemblyResult,
 } from "./runtime-definition";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
@@ -78,6 +77,7 @@ export interface LoadedRuntime<Config> {
   readonly runtimeKey: string;
   readonly config: Config;
   readonly resources: ResolvedResources;
+  readonly commitGuard?: () => Promise<void>;
 }
 
 export interface RuntimeConfigUpdate<Change> {
@@ -106,11 +106,6 @@ interface RuntimeAgentDefinitionBase<
     config: Config,
   ) => ToolAssemblyResult | Promise<ToolAssemblyResult>;
 
-  readonly hooks?:
-    | RuntimeAgentHooks<Env, Config, Command, Change>
-    | ((context: RuntimeAgentPlanningContext<Env, Command, Change>) =>
-      RuntimeAgentHooks<Env, Config, Command, Change>);
-
   /** Prepare the optional telemetry consumer for this concrete Agent facet. */
   readonly telemetry?: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
@@ -407,18 +402,6 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  const resolveDefinitionHooks = (
-    context: RuntimeAgentPlanningContext<Env, Command, Change>,
-  ): RuntimeAgentHooks<Env, Config, Command, Change> | undefined => {
-    const hooks = definition.hooks;
-    if (!hooks) return undefined;
-    return typeof hooks === "function"
-      ? (hooks as (
-          ctx: RuntimeAgentPlanningContext<Env, Command, Change>,
-        ) => RuntimeAgentHooks<Env, Config, Command, Change>)(context)
-      : hooks as RuntimeAgentHooks<Env, Config, Command, Change>;
-  };
-
   const resolveDefinitionTelemetry = (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
   ): AgentTelemetryBinding | undefined => {
@@ -634,7 +617,8 @@ export function defineRuntimeAgent<
               )(context, loaded.config),
               { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
             );
-            let hooks = resolveDefinitionHooks(context);
+            let resources = loaded.resources;
+            let commitGuard = loaded.commitGuard;
             if (!this.telemetryResolved) {
               this.resolvedTelemetry = resolveDefinitionTelemetry(context);
               this.telemetryResolved = true;
@@ -643,14 +627,14 @@ export function defineRuntimeAgent<
             if (this.role === "temporary") {
               this.temporaryDispose = tools.dispose;
               tools = this.applyTemporaryToolPolicy(tools);
-              hooks = await this.createTemporaryHooks();
+              resources = await this.applyTemporaryResources(resources);
+              commitGuard = undefined;
             }
             const candidate = await assembleRuntimeSnapshot({
               ctx: context,
-              config: loaded.config,
               tools,
-              resources: loaded.resources,
-              hooks,
+              resources,
+              ...(commitGuard ? { commitGuard } : {}),
               ...(telemetry ? { telemetry } : {}),
             });
 
@@ -709,9 +693,9 @@ export function defineRuntimeAgent<
         };
       }
 
-      private async createTemporaryHooks(): Promise<
-        RuntimeAgentHooks<Env, Config, Command, Change>
-      > {
+      private async applyTemporaryResources(
+        resources: ResolvedResources,
+      ): Promise<ResolvedResources> {
         const launch = this.temporaryLaunch ??
           await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
             TEMPORARY_AGENT_LAUNCH_KEY,
@@ -719,17 +703,27 @@ export function defineRuntimeAgent<
         if (!launch) throw new Error("Temporary Agent is not initialized");
         this.temporaryLaunch = launch;
         return {
-          profileOverrides: () => ({
-            systemPrompt: launch.instructions,
-            executionLevel: "high",
-          }),
-          gateTool: async (request) => {
-            if (!requiresExecutionApproval(
-              launch.executionLevel,
-              request.requiredExecutionLevel,
-            )) return;
-            await this.requestParentTemporaryApproval(launch, request);
+          ...resources,
+          settings: {
+            ...resources.settings,
+            profile: {
+              ...resources.settings.profile,
+              systemPrompt: launch.instructions,
+              executionLevel: "high",
+            },
+          },
+          platform: {
+            ...resources.platform,
+            gateTool: async (request) => {
+              if (!requiresExecutionApproval(
+                launch.executionLevel,
+                request.requiredExecutionLevel,
+              )) return;
+              await this.requestParentTemporaryApproval(launch, request);
+            },
           },
+          turnEvents: undefined,
+          admission: undefined,
         };
       }
 

package/src/runtime-assembler.ts

@@ -7,6 +7,7 @@ import type {
   RuntimeSandboxPort,
   RuntimeSchedulePort,
   RuntimeSkillSourceBinding,
+  RuntimeSubmissionAdmissionHook,
   RuntimeSubagentPort,
   RuntimeTurnEventsPort,
   RuntimeBindings,
@@ -37,7 +38,6 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { PiToolCandidate } from "./pi/tool/compiler";
 import type {
   AssembleRuntimeSnapshotInput,
-  RuntimeAgentHooks,
   RuntimeSettings,
   RuntimeExtensionContribution,
   RuntimeProfileContribution,
@@ -45,7 +45,6 @@ import type {
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
 import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
-import { withRuntimeLoadTimeout } from "./kernel/runtime-load";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
@@ -122,8 +121,7 @@ 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;
+  readonly admission?: RuntimeSubmissionAdmissionHook;
   readonly telemetry?: AgentTelemetryBinding;
 }
 
@@ -690,110 +688,34 @@ export async function assembleRuntime(
   commit(candidate.snapshot);
 }
 
-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.onSubagentUsage &&
-    !hooks.onLifecycleFact &&
-    !hooks.onToolStart &&
-    !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.onSubagentUsage ? { onSubagentUsage: hooks.onSubagentUsage } : {}),
-    ...(hooks.onLifecycleFact ? { onLifecycleFact: hooks.onLifecycleFact } : {}),
-    ...(hooks.onToolStart ? { onToolStart: hooks.onToolStart } : {}),
-    ...(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。
+ * 从 Tool 和已加载 Resource 装配 Runtime 候选 Snapshot。
  *
  * @internal
  */
 export async function assembleRuntimeSnapshot<
   Env extends Cloudflare.Env,
-  Config,
   Command = never,
   Change = never,
 >(
-  input: AssembleRuntimeSnapshotInput<Env, Config, Command, Change>,
+  input: AssembleRuntimeSnapshotInput<Env, 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 withRuntimeLoadTimeout(
-      "profile-overrides",
-      () => 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 profile = settings.profile;
 
   const hostTools = toolAssembly.tools;
 
   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;
+  if (input.commitGuard) commitGuards.push(input.commitGuard);
 
   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
@@ -828,7 +750,7 @@ export async function assembleRuntimeSnapshot<
     ...(toolPolicy ? { toolPolicy } : {}),
     enabledSubagents: [...enabledSubagents],
     provider,
-    platform,
+    platform: resources.platform,
     ...(toolAssembly.bindings?.workspace
       ? { workspace: toolAssembly.bindings.workspace }
       : {}),
@@ -851,9 +773,9 @@ export async function assembleRuntimeSnapshot<
       ? { gateway: resources.connectors.gateway }
       : {}),
     extensions: resources.extensions,
-    ...(turnEvents ? { turnEvents } : {}),
+    ...(resources.turnEvents ? { turnEvents: resources.turnEvents } : {}),
     ...(input.telemetry ? { telemetry: input.telemetry } : {}),
-    commitGuards: [],
+    commitGuards,
     degradations: [
       ...(toolAssembly.degradations ?? []),
       ...(resources.degradations ?? []),
@@ -863,22 +785,8 @@ export async function assembleRuntimeSnapshot<
 
   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 } : {}),
+    ...candidate,
+    ...(resources.admission ? { admission: resources.admission } : {}),
     ...(candidate.telemetry ? { telemetry: candidate.telemetry } : {}),
   });
 }

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,12 +15,10 @@ 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";
@@ -83,14 +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 interface ResolvedConnectors {
   readonly servers: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
@@ -101,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;
@@ -185,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: 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();

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);
-    },
-  };
-}