@springbrand/agent-runtime 0.1.3-alpha.4 → 0.1.3-alpha.6

package/src/runtime-agent.ts

@@ -1,9 +1,8 @@
 import {
   callable,
   type Agent,
-  type AgentToolRunStatus,
+  type AgentToolChildAdapter,
   type ChatCapableAgentClass,
-  type RunAgentToolOptions,
 } from "agents";
 import type { UIMessage } from "ai";
 import type { PiCanonicalTranscriptSnapshot } from "./pi/runtime-adapter";
@@ -14,19 +13,49 @@ import type {
   MessageDispatchReceipt,
   SubmissionReceipt,
 } from "./kernel/receipts";
-import type { ExecutionLevel } from "./lib/execution-level";
 import type { RuntimeState } from "./kernel/state";
 import type {
   TemporaryAgentApprovalDecision,
   TemporaryAgentApprovalRequest,
-  TemporaryAgentExecutor,
-  TemporaryAgentRequest,
-  TemporaryAgentRunContext,
+  TemporaryAgentLaunch,
 } from "./layers/orchestration/temporary-agent/core";
-import type { RuntimeAssemblyInput } from "./runtime-assembler";
+import { TEMPORARY_AGENT_LAUNCH_KEY } from "./layers/orchestration/temporary-agent/core";
+import {
+  temporaryAgentExtensionIsSafe,
+  temporaryAgentToolAllowed,
+} from "./layers/orchestration/temporary-agent/runner";
+import {
+  EXECUTION_LEVELS,
+  requiresExecutionApproval,
+  type ExecutionLevel,
+} from "./lib/execution-level";
+import {
+  assembleRuntimeSnapshot,
+  type RuntimeCandidate,
+} from "./runtime-assembler";
+import type {
+  ResolvedResources,
+  RuntimeAgentHooks,
+} from "./runtime-definition";
+import {
+  normalizeToolAssembly,
+  type ToolAssemblyResult,
+  type ToolRegistry,
+} from "./tool-registry";
 import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
 import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
-import { AgentRuntimeKernel } from "./runtime";
+import {
+  logRuntimeLoadFailure,
+  RUNTIME_LOAD_TIMEOUT_MS,
+  withRuntimeLoadTimeout,
+} from "./kernel/runtime-load";
+import { AgentToolRuntimeKernel } from "./agent-tool-runtime";
+import type {
+  RuntimeAgentConfigContext,
+  RuntimeAgentPlanningContext,
+  RuntimeAgentRole,
+  RuntimeAgentToolResult,
+} from "./runtime-agent-context";
 
 /**
  * 本文件把应用提供的 Config Definition 与 Planner 接到 Cloudflare Agent 生命周期。
@@ -37,165 +66,21 @@ import { AgentRuntimeKernel } from "./runtime";
 
 // #region Agent 身份与公开契约
 
-const RESERVED_IDENTIFIERS = new Set([
-  "arguments",
-  "await",
-  "break",
-  "case",
-  "catch",
-  "class",
-  "const",
-  "continue",
-  "debugger",
-  "default",
-  "delete",
-  "do",
-  "else",
-  "enum",
-  "eval",
-  "export",
-  "extends",
-  "false",
-  "finally",
-  "for",
-  "function",
-  "if",
-  "implements",
-  "import",
-  "in",
-  "instanceof",
-  "interface",
-  "let",
-  "new",
-  "null",
-  "package",
-  "private",
-  "protected",
-  "public",
-  "return",
-  "static",
-  "super",
-  "switch",
-  "this",
-  "throw",
-  "true",
-  "try",
-  "typeof",
-  "var",
-  "void",
-  "while",
-  "with",
-  "yield",
-]);
-const JAVASCRIPT_IDENTIFIER =
-  /^[$_\p{ID_Start}][$\u200C\u200D\p{ID_Continue}]*$/u;
-
-/**
- * 描述 Agent 寻址路径中的一级父子节点。
- *
- * @remarks
- * Cloudflare Agents SDK 用 `parentPath` 暴露根节点到直接父节点的路径。
- *
- * 调用方通常只读取，不应自行构造后写回 SDK。
- */
-export interface RuntimeAgentPathStep {
-  className: string;
-  name: string;
-}
-
-/**
- * 表示一次 Agent Tool 执行返回给 Runtime 的稳定字段。
- *
- * @remarks
- * Subagent 端口在调用 `RuntimeAgentConfigContext.runAgentTool` 后读取它。
- *
- * 这里只保留 Runtime 需要的结果，避免把 SDK 内部运行对象暴露给应用。
- */
-export interface RuntimeAgentToolResult {
-  status: string;
-  runId: string;
-  output?: unknown;
-  summary?: string;
-  error?: string;
-}
-
-/**
- * 这是应用创建 Config 时唯一可以接触的 Agent 实例能力。
- *
- * 身份通过实时 getter 暴露。
- *
- * 待确认：原注释把 getter 的必要性归因于 facet 元数据在 Durable Object
- * 构造后恢复，但当前 SDK 会在用户 `onStart` 前完成恢复。
- */
-export interface RuntimeAgentConfigContext<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-> {
-  /** 读取当前 Durable Object 的状态句柄。 */
-  readonly ctx: DurableObjectState;
-  /** 读取当前 Worker 的环境绑定。 */
-  readonly env: Env;
-  /** 读取当前 Agent 实例名称。 */
-  readonly name: string;
-  /** 读取从根节点到直接父节点的 Agent 路径。 */
-  readonly parentPath: readonly RuntimeAgentPathStep[];
-  /**
-   * 通过当前 Agent 调用一个受 SDK 管理的子 Agent Tool。
-   *
-   * @remarks
-   * subagent 端口在父 Agent 需要保留子运行状态、事件和取消边界时调用。
-   *
-   * 调用必须经过当前 Agent 实例，才能使用 Cloudflare Agents SDK 的受管子运行登记。
-   */
-  runAgentTool(
-    agentClass: ChatCapableAgentClass,
-    options: RunAgentToolOptions<unknown>,
-  ): Promise<RuntimeAgentToolResult>;
-  /**
-   * 清理符合年龄和状态条件的 SDK 子运行记录。
-   *
-   * @remarks
-   * subagent 清理逻辑在需要回收已保留运行时调用。
-   *
-   * 必须显式提供年龄和状态筛选，避免无边界地删除仍需查询的子运行。
-   */
-  clearAgentToolRuns(options: {
-    olderThan: number;
-    status: AgentToolRunStatus[];
-  }): Promise<void>;
-  /** 读取当前已装配 User Agent 的执行档位。 */
-  executionLevel(): ExecutionLevel;
-  /**
-   * 在当前 Session Runtime 中执行一个仅对本次调用存活的临时 Agent。
-   *
-   * @remarks
-   * temporary-agent 端口在 Tool 需要一次性委派时调用。
-   *
-   * 它复用当前 Session 的 Runtime 和取消信号，但不创建持久 facet。
-   */
-  runTemporaryAgent(
-    request: TemporaryAgentRequest,
-    context: TemporaryAgentRunContext,
-    execute: TemporaryAgentExecutor,
-  ): Promise<string>;
-}
-
-export interface RuntimeAgentPlanningContext<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Command = never,
-  Change = never,
-> extends RuntimeAgentConfigContext<Env> {
-  /** 仅可变 Definition 提供；Host Tool 用它复用生成类的更新与重载编排。 */
-  readonly updateConfig?: (
-    command: Command,
-  ) => Promise<RuntimeConfigUpdateResult<Change>>;
-}
-
-/**
- * Config 读取的显式结果；runtimeKey 是生成类唯一的缓存键。
- */
-export interface ResolvedRuntimeConfig<Config> {
+export type {
+  RuntimeAgentConfigContext,
+  RuntimeAgentContext,
+  RuntimeAgentPathStep,
+  RuntimeAgentPlanningContext,
+  RuntimeAgentRole,
+  RuntimeAgentToolResult,
+  RuntimeAssemblyContext,
+} from "./runtime-agent-context";
+
+/** Host 一次性准备的完整 Runtime 加载结果。 */
+export interface LoadedRuntime<Config> {
   readonly runtimeKey: string;
   readonly config: Config;
+  readonly resources: ResolvedResources;
 }
 
 export interface RuntimeConfigUpdate<Change> {
@@ -203,60 +88,36 @@ export interface RuntimeConfigUpdate<Change> {
   readonly change: Change;
 }
 
-export interface RuntimeAgentConfigDefinition<
+interface RuntimeAgentDefinitionBase<
   Env extends Cloudflare.Env,
   Config,
   Command,
   Change,
 > {
-  read(
-    context: RuntimeAgentConfigContext<Env>,
+  /** 必须等于 Worker 导出名（Wrangler `class_name`）。 */
+  readonly name: string;
+
+  readonly load: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
     requestedRuntimeKey?: string,
-  ): Promise<ResolvedRuntimeConfig<Config>>;
-  update?(
-    context: RuntimeAgentConfigContext<Env>,
-    command: Command,
-  ): Promise<RuntimeConfigUpdate<Change>>;
-}
+  ) => Promise<LoadedRuntime<Config>>;
 
-/**
- * 告诉 Runtime 如何读取有效配置，并把它规划为一次扁平装配输入。
- *
- * @remarks
- * Worker 入口把它传给 `defineRuntimeAgent`。
- *
- * Config 只负责业务寻址，Planner 把已读取配置投影为装配输入。
- */
-interface RuntimeAgentDefinitionBase<
-  Env extends Cloudflare.Env,
-  Config,
-  Command,
-  Change,
-> {
-  /**
-   * 必须等于 Worker 导出名。
-   *
-   * 顶层 Agent 还必须与 Wrangler `class_name` 一致。
-   *
-   * 纯子 facet 不需要自己的顶层绑定。
-   *
-   * Agents SDK 使用构造器名称解析 facet 回调。
-   */
-  className: string;
-  planRuntime(
+  readonly tools: (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
     config: Config,
-  ): Promise<RuntimeAssemblyInput>;
+  ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>;
+
+  readonly hooks?:
+    | RuntimeAgentHooks<Env, Config, Command, Change>
+    | ((context: RuntimeAgentPlanningContext<Env, Command, Change>) =>
+      RuntimeAgentHooks<Env, Config, Command, Change>);
 }
 
 export interface ReadonlyRuntimeAgentDefinition<
   Env extends Cloudflare.Env = Cloudflare.Env,
   Config = unknown,
 > extends RuntimeAgentDefinitionBase<Env, Config, never, never> {
-  readonly config: Omit<
-    RuntimeAgentConfigDefinition<Env, Config, never, never>,
-    "update"
-  > & { readonly update?: never };
+  readonly update?: never;
 }
 
 export interface MutableRuntimeAgentDefinition<
@@ -265,14 +126,10 @@ export interface MutableRuntimeAgentDefinition<
   Command = unknown,
   Change = unknown,
 > extends RuntimeAgentDefinitionBase<Env, Config, Command, Change> {
-  readonly config: RuntimeAgentConfigDefinition<
-    Env,
-    Config,
-    Command,
-    Change
-  > & Required<
-    Pick<RuntimeAgentConfigDefinition<Env, Config, Command, Change>, "update">
-  >;
+  readonly update: (
+    context: RuntimeAgentConfigContext<Env>,
+    command: Command,
+  ) => Promise<RuntimeConfigUpdate<Change>>;
 }
 
 export type RuntimeAgentDefinition<
@@ -447,14 +304,11 @@ export interface RuntimeAgentControls {
   ): Promise<{ ok: boolean }>;
 }
 
-export type RuntimeAgentConfigControls<Command, Change> =
-  [Command] extends [never]
-    ? Record<never, never>
-    : {
-        updateConfig(
-          command: Command,
-        ): Promise<RuntimeConfigUpdateResult<Change>>;
-      };
+export interface RuntimeAgentConfigControls<Command, Change> {
+  updateConfig(
+    command: Command,
+  ): Promise<RuntimeConfigUpdateResult<Change>>;
+}
 
 /**
  * 表示 `defineRuntimeAgent` 生成类的实例。
@@ -467,7 +321,7 @@ export type RuntimeAgentInstance<
   Command = never,
   Change = never,
 > = Agent<Env, RuntimeState> & RuntimeAgentControls &
-  RuntimeAgentConfigControls<Command, Change>;
+  RuntimeAgentConfigControls<Command, Change> & AgentToolChildAdapter<unknown, string>;
 
 /**
  * 表示 `defineRuntimeAgent` 返回的 Durable Object 类构造器。
@@ -490,18 +344,45 @@ export interface RuntimeAgentClass<
 
 // #region 生成类的构造与生命周期
 
-// 作用：确认导出类名是可以安全创建的 JavaScript 标识符。
-// 调用：`defineRuntimeAgent` 在生成类之前调用一次。
-// 原因：动态计算类名时提前拒绝关键字，避免部署后才出现寻址失败。
-function assertClassName(className: string): void {
+const TERMINAL_AGENT_TOOL_STATUSES = [
+  "completed",
+  "error",
+  "aborted",
+  "interrupted",
+] as const;
+const AGENT_TOOL_RETENTION_MS = 24 * 60 * 60 * 1_000;
+
+function parseTemporaryAgentLaunch<Config>(
+  input: unknown,
+): TemporaryAgentLaunch<Config> {
+  const record = input != null && typeof input === "object"
+    ? input as Record<string, unknown>
+    : {};
+  const read = (name: string, max: number) => {
+    const value = record[name];
+    if (typeof value !== "string" || !value.trim() || value.length > max) {
+      throw new Error(`invalid temporary agent ${name}`);
+    }
+    return value.trim();
+  };
+  const executionLevel = record.executionLevel;
   if (
-    !JAVASCRIPT_IDENTIFIER.test(className) ||
-    RESERVED_IDENTIFIERS.has(className)
+    typeof executionLevel !== "string" ||
+    !EXECUTION_LEVELS.includes(executionLevel as ExecutionLevel)
   ) {
-    throw new Error(
-      `Invalid Runtime Agent className "${className}": expected a non-reserved JavaScript identifier`,
-    );
+    throw new Error("invalid temporary agent executionLevel");
+  }
+  if (!("config" in record)) {
+    throw new Error("invalid temporary agent config");
   }
+  return {
+    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,
+  };
 }
 
 /**
@@ -512,20 +393,6 @@ function assertClassName(className: string): void {
  *
  * 生成类把首次加载、并发去重、按 key 重载和失败重试收口到一个入口。
  */
-export function defineRuntimeAgent<
-  Env extends Cloudflare.Env,
-  Config,
-  Command,
-  Change,
->(
-  definition: MutableRuntimeAgentDefinition<Env, Config, Command, Change>,
-): RuntimeAgentClass<Env, Command, Change>;
-export function defineRuntimeAgent<
-  Env extends Cloudflare.Env = Cloudflare.Env,
-  Config = unknown,
->(
-  definition: ReadonlyRuntimeAgentDefinition<Env, Config>,
-): RuntimeAgentClass<Env>;
 export function defineRuntimeAgent<
   Env extends Cloudflare.Env = Cloudflare.Env,
   Config = unknown,
@@ -536,17 +403,32 @@ export function defineRuntimeAgent<
     | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
     | ReadonlyRuntimeAgentDefinition<Env, Config>,
 ): RuntimeAgentClass<Env, Command, Change> {
-  assertClassName(definition.className);
-  const planRuntime = definition.planRuntime as (
+  const resolveDefinitionHooks = (
     context: RuntimeAgentPlanningContext<Env, Command, Change>,
-    config: Config,
-  ) => Promise<RuntimeAssemblyInput>;
+  ): 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 GeneratedRuntimeAgent = {
-    [definition.className]: class extends AgentRuntimeKernel<Env> {
+    [definition.name]: class extends AgentToolRuntimeKernel<Env> {
       private hasLoadedRuntime = false;
       private loadedRuntimeKey?: string;
       private loading?: Promise<void>;
+      private temporaryLaunch?: TemporaryAgentLaunch<Config>;
+      private temporaryDispose?: () => Promise<void>;
+      private temporaryCleanup?: Promise<void>;
+
+      protected get role(): RuntimeAgentRole {
+        return this.parentPath.at(-1)?.className === definition.name
+          ? "temporary"
+          : "primary";
+      }
 
       // 作用：在 Kernel 真正消费 RuntimeSnapshot 前确保配置已完整提交。
       // 调用：Submission 准入、恢复、审批续跑与 Runtime Workspace 路径调用。
@@ -568,8 +450,13 @@ export function defineRuntimeAgent<
       async updateConfig(
         command: Command,
       ): Promise<RuntimeConfigUpdateResult<Change>> {
-        const update = definition.config.update;
-        if (!update) throw new Error("Runtime Agent Config is read-only");
+        if (this.role === "temporary") {
+          throw new Error("Temporary agents cannot update Runtime Config");
+        }
+        const update = definition.update;
+        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" };
@@ -629,90 +516,268 @@ export function defineRuntimeAgent<
         return super.stopTurn(requestId, reason);
       }
 
+      protected override async prepareAgentToolRun(
+        input: unknown,
+      ): Promise<string> {
+        if (this.role !== "temporary") {
+          throw new Error("Agent Tool runs require a temporary child facet");
+        }
+        const launch = parseTemporaryAgentLaunch<Config>(input);
+        this.temporaryLaunch = launch;
+        await this.ctx.storage.put(TEMPORARY_AGENT_LAUNCH_KEY, launch);
+        await this.reloadRuntime(launch.runtimeKey, { force: true });
+        return launch.task;
+      }
+
       // 作用：把首次加载和按 key 重载合并成一个串行入口。
       // 调用：Runtime readiness、Session 配置和重载都会调用。
       // 原因：共享同一个 Promise 可合并并发首加载，显式切 key 则等待前序完成后再判断。
-      private ensureConfig(
+      protected ensureConfig(
         requestedRuntimeKey?: string,
         force = false,
         fromQueue = false,
       ): Promise<void> {
-        if (this.loading && !fromQueue) {
-          if (!requestedRuntimeKey && !force) return this.loading;
-
-          // 显式 key 或强制刷新不能被正在进行的其他加载吞掉，必须等它结束后重新核对。
-          const queued = this.loading
-            .catch(() => undefined)
-            .then(() => {
-              if (
-                !force &&
-                this.hasLoadedRuntime &&
-                this.loadedRuntimeKey === requestedRuntimeKey
-              ) {
-                return;
-              }
-              return this.ensureConfig(
+          if (this.loading && !fromQueue) {
+            if (!requestedRuntimeKey && !force) return this.loading;
+
+            // 显式 key 或强制刷新不能被正在进行的其他加载吞掉，必须等它结束后重新核对。
+            const queued = this.loading
+              .catch(() => undefined)
+              .then(() => {
+                if (
+                  !force &&
+                  this.hasLoadedRuntime &&
+                  this.loadedRuntimeKey === requestedRuntimeKey
+                ) {
+                  return;
+                }
+                return this.ensureConfig(
+                  requestedRuntimeKey,
+                  force,
+                  true,
+                );
+              });
+            let tracked: Promise<void>;
+            tracked = queued.finally(() => {
+              if (this.loading === tracked) this.loading = undefined;
+            });
+            this.loading = tracked;
+            return tracked;
+          }
+
+          if (
+            !force &&
+            this.hasLoadedRuntime &&
+            (!requestedRuntimeKey ||
+              requestedRuntimeKey === this.loadedRuntimeKey)
+          ) {
+            return Promise.resolve();
+          }
+
+          // 先创建局部 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,
-                force,
-                true,
-              );
+              ),
+              { 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 = normalizeToolAssembly(await withRuntimeLoadTimeout(
+              "definition.tools",
+              () => (
+                definition.tools as (
+                  context: RuntimeAgentPlanningContext<Env, Command, Change>,
+                  config: Config,
+                ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>
+              )(context, loaded.config),
+              { timeoutMs: RUNTIME_LOAD_TIMEOUT_MS },
+            ));
+            let hooks = resolveDefinitionHooks(context);
+            if (this.role === "temporary") {
+              this.temporaryDispose = tools.dispose;
+              tools = this.applyTemporaryToolPolicy(tools);
+              hooks = await this.createTemporaryHooks();
+            }
+            const candidate = await assembleRuntimeSnapshot({
+              ctx: context,
+              config: loaded.config,
+              tools,
+              resources: loaded.resources,
+              hooks,
             });
+
+            await this.initCandidate(candidate);
+            this.hasLoadedRuntime = true;
+            this.loadedRuntimeKey = resolvedRuntimeKey;
+            this.runtimeLoad.complete();
+            // 提交之前 turnEvents 绑定还不存在，此前每一次广播都到不了 Host。
+            // Host 的会话列表把装配后的第一次投影当作「facet 已就绪」的信号。
+            await this.broadcastApprovals();
+          })().catch((error) => {
+            logRuntimeLoadFailure("runtime", error);
+            this.runtimeLoad.fail();
+            throw error;
+          });
+
+          if (fromQueue) return pending;
+
+          // 无论成功失败都清掉进行中标记，后续调用才可以重试或切 key。
           let tracked: Promise<void>;
-          tracked = queued.finally(() => {
+          tracked = pending.finally(() => {
             if (this.loading === tracked) this.loading = undefined;
           });
           this.loading = tracked;
           return tracked;
         }
 
-        if (
-          !force &&
-          this.hasLoadedRuntime &&
-          (!requestedRuntimeKey ||
-            requestedRuntimeKey === this.loadedRuntimeKey)
-        ) {
-          return Promise.resolve();
-        }
+      private applyTemporaryToolPolicy(
+        assembly: ToolAssemblyResult,
+      ): ToolAssemblyResult {
+        const policy = assembly.surfacePolicy;
+        return {
+          ...assembly,
+          bindings: assembly.bindings?.workspace
+            ? { workspace: assembly.bindings.workspace }
+            : {},
+          memoryProfile: {
+            enabled: false,
+            memoryTokens: 2_000,
+            preferencesTokens: 500,
+          },
+          enabledSubagents: [],
+          surfacePolicy: {
+            allowsTool: (name) =>
+              temporaryAgentToolAllowed(name) &&
+              policy?.allowsTool?.(name) !== false,
+            allowsExtension: (extension) =>
+              temporaryAgentExtensionIsSafe(extension) &&
+              policy?.allowsExtension?.(extension) !== false,
+          },
+        };
+      }
 
-        // 先创建局部 Promise，再赋给 `loading`，失败时也能在 finally 中放开重试。
-        const pending = (async () => {
-          this.runtimeLoad.begin();
-          const context = this.createDefinitionContext();
-          const resolved = await definition.config.read(
-            context,
-            requestedRuntimeKey,
+      private async createTemporaryHooks(): Promise<
+        RuntimeAgentHooks<Env, Config, Command, Change>
+      > {
+        const launch = this.temporaryLaunch ??
+          await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+            TEMPORARY_AGENT_LAUNCH_KEY,
           );
-          const resolvedRuntimeKey = resolved.runtimeKey.trim();
-          if (!resolvedRuntimeKey) {
-            throw new Error("Resolved Runtime key must not be empty");
-          }
-          const input = await planRuntime(context, resolved.config);
-
-          // 只有原子提交成功后才更新已加载标记和 key。
-          await this.initConfig(input);
-          this.hasLoadedRuntime = true;
-          this.loadedRuntimeKey = resolvedRuntimeKey;
-          this.runtimeLoad.complete();
-          // 提交之前 turnEvents 绑定还不存在，此前每一次广播都到不了 Host。
-          // Host 的会话列表把装配后的第一次投影当作「facet 已就绪」的信号。
-          await this.broadcastApprovals();
-        })().catch((error) => {
-          this.runtimeLoad.fail();
-          throw error;
-        });
+        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);
+          },
+        };
+      }
 
-        if (fromQueue) return pending;
+      private async requestParentTemporaryApproval(
+        launch: TemporaryAgentLaunch<Config>,
+        request: {
+          toolCallId: string;
+          toolName: string;
+          input: unknown;
+          requiredExecutionLevel: ExecutionLevel;
+          signal: AbortSignal;
+        },
+      ): Promise<void> {
+        if (request.signal.aborted) {
+          throw new Error("temporary agent was cancelled", {
+            cause: request.signal.reason,
+          });
+        }
+        const parent = await this.parentAgent(
+          this.constructor as ChatCapableAgentClass,
+        ) as unknown as Pick<
+          RuntimeAgentControls,
+          "requestTemporaryAgentApproval" | "cancelTemporaryAgentApproval"
+        >;
+        const executionId =
+          `temporary-agent:${this.name}:${request.toolCallId}`;
+        let onAbort = () => {};
+        const aborted = new Promise<never>((_resolve, reject) => {
+          onAbort = () => {
+            void parent.cancelTemporaryAgentApproval(
+              executionId,
+              "temporary agent was cancelled",
+            );
+            reject(new Error("temporary agent was cancelled", {
+              cause: request.signal.reason,
+            }));
+          };
+          request.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+          const decision = await Promise.race([
+            parent.requestTemporaryAgentApproval({
+              executionId,
+              subagentName: launch.subagentName,
+              requestId: `temporary-agent:${this.name}`,
+              toolCallId: request.toolCallId,
+              toolName: request.toolName,
+              executionLevel: launch.executionLevel,
+              requiredExecutionLevel: request.requiredExecutionLevel,
+              input: request.input,
+            }),
+            aborted,
+          ]);
+          if (!decision.approved) {
+            throw new Error(
+              `temporary agent "${launch.subagentName}" Tool ` +
+                `"${request.toolName}" was rejected: ` +
+                `${decision.reason?.trim() || "rejected by user"}`,
+            );
+          }
+        } finally {
+          request.signal.removeEventListener("abort", onAbort);
+        }
+      }
 
-        // 无论成功失败都清掉进行中标记，后续调用才可以重试或切 key。
-        let tracked: Promise<void>;
-        tracked = pending.finally(() => {
-          if (this.loading === tracked) this.loading = undefined;
+      protected override cleanupAgentToolRun(): Promise<void> {
+        if (this.temporaryCleanup) return this.temporaryCleanup;
+        this.temporaryCleanup = (async () => {
+          if (!this.temporaryDispose) {
+            const launch = this.temporaryLaunch ??
+              await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+                TEMPORARY_AGENT_LAUNCH_KEY,
+              );
+            if (launch) await this.ensureConfig(launch.runtimeKey);
+          }
+          await this.temporaryDispose?.();
+        })().catch((error) => {
+          console.warn("Temporary Agent resource cleanup failed", error);
         });
-        this.loading = tracked;
-        return tracked;
+        return this.temporaryCleanup;
       }
 
-      private createDefinitionContext(): RuntimeAgentPlanningContext<
+      protected createDefinitionContext(
+        runtimeConfig?: { value: Config },
+      ): RuntimeAgentPlanningContext<
         Env,
         Command,
         Change
@@ -727,7 +792,10 @@ export function defineRuntimeAgent<
           get parentPath() {
             return agent.parentPath;
           },
-          ...(definition.config.update
+          get role() {
+            return agent.role;
+          },
+          ...(agent.role === "primary"
             ? {
                 updateConfig: (command: Command) =>
                   agent.updateConfig(command),
@@ -741,16 +809,64 @@ export function defineRuntimeAgent<
           clearAgentToolRuns: (options) =>
             agent.clearAgentToolRuns(options),
           executionLevel: () => agent.executionLevel(),
-          runTemporaryAgent: (request, runContext, execute) =>
-            agent.runTemporaryAgent(request, runContext, execute),
+          runTemporaryAgent: (request, runContext) => {
+            if (agent.role !== "primary" || !runtimeConfig) {
+              throw new Error("Temporary Agent cannot delegate again");
+            }
+            return agent.runTemporaryAgent(
+              request,
+              runContext,
+              async (normalized) => {
+                await agent.clearAgentToolRuns({
+                  olderThan: Date.now() - AGENT_TOOL_RETENTION_MS,
+                  status: [...TERMINAL_AGENT_TOOL_STATUSES],
+                });
+                const result = await agent.runAgentTool(
+                  agent.constructor as ChatCapableAgentClass,
+                  {
+                    input: {
+                      ...normalized,
+                      runtimeKey: agent.loadedRuntimeKey,
+                      config: runtimeConfig.value,
+                      executionLevel: agent.executionLevel(),
+                    },
+                    runId: `temporary-agent:${runContext.toolCallId}`,
+                    parentToolCallId: runContext.toolCallId,
+                    signal: runContext.signal,
+                    inputPreview: normalized.task,
+                    display: {
+                      name: normalized.subagentName,
+                      displayName: normalized.subagentName,
+                      kind: "temporary",
+                    },
+                  },
+                );
+                if (result.status !== "completed") {
+                  throw new Error(
+                    result.error ??
+                      `temporary agent ended with status ${result.status}`,
+                  );
+                }
+                if (
+                  typeof result.summary !== "string" ||
+                  !result.summary.trim()
+                ) {
+                  throw new Error(
+                    "temporary agent completed without final text",
+                  );
+                }
+                return result.summary;
+              },
+            );
+          },
         };
       }
     },
-  }[definition.className];
+  }[definition.name];
 
-  if (GeneratedRuntimeAgent.name !== definition.className) {
+  if (GeneratedRuntimeAgent.name !== definition.name) {
     throw new Error(
-      `Runtime Agent class name mismatch: expected "${definition.className}", got "${GeneratedRuntimeAgent.name}"`,
+      `Runtime Agent class name mismatch: expected "${definition.name}", got "${GeneratedRuntimeAgent.name}"`,
     );
   }
 
@@ -758,6 +874,8 @@ export function defineRuntimeAgent<
   // Apply the same decorator function after class-name inference instead.
   const callableContext = {} as ClassMethodDecoratorContext;
   callable()(GeneratedRuntimeAgent.prototype.reloadRuntime, callableContext);
+  callable()(GeneratedRuntimeAgent.prototype.updateConfig, callableContext);
+  callable()(GeneratedRuntimeAgent.prototype.getRuntimeAssembly, callableContext);
   callable()(GeneratedRuntimeAgent.prototype.dispatchMessage, callableContext);
   callable()(
     GeneratedRuntimeAgent.prototype.steerQueuedSubmission,
@@ -767,21 +885,17 @@ export function defineRuntimeAgent<
     GeneratedRuntimeAgent.prototype.cancelSubmissionById,
     callableContext,
   );
-  callable()(GeneratedRuntimeAgent.prototype.stopTurn, callableContext);
   callable()(
     GeneratedRuntimeAgent.prototype.respondToolInteraction,
     callableContext,
   );
-  callable()(GeneratedRuntimeAgent.prototype.getRuntimeAssembly, callableContext);
-  if (definition.config.update) {
-    callable()(GeneratedRuntimeAgent.prototype.updateConfig, callableContext);
-  } else {
-    delete (GeneratedRuntimeAgent.prototype as {
-      updateConfig?: unknown;
-    }).updateConfig;
-  }
+  callable()(GeneratedRuntimeAgent.prototype.stopTurn, callableContext);
 
-  return GeneratedRuntimeAgent as RuntimeAgentClass<Env, Command, Change>;
+  return GeneratedRuntimeAgent as unknown as RuntimeAgentClass<
+    Env,
+    Command,
+    Change
+  >;
 }
 
 // #endregion