@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.11

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,20 +13,52 @@ 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 { AgentConfig } from "./plugins";
-import { AgentRuntimeKernel } from "./runtime";
+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 {
+  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";
 
 /**
- * 本文件把应用提供的 `createConfig` 接到 Cloudflare Agent 生命周期。
+ * 本文件把应用提供的 Config Definition 与 Planner 接到 Cloudflare Agent 生命周期。
  *
  * @remarks
  * 核心术语见包入口 `index.ts`。
@@ -35,201 +66,81 @@ 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;
+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;
 }
 
-/**
- * 表示一次 Agent Tool 执行返回给 Runtime 的稳定字段。
- *
- * @remarks
- * Subagent 端口在调用 `RuntimeAgentConfigContext.runAgentTool` 后读取它。
- *
- * 这里只保留 Runtime 需要的结果，避免把 SDK 内部运行对象暴露给应用。
- */
-export interface RuntimeAgentToolResult {
-  status: string;
-  runId: string;
-  output?: unknown;
-  summary?: string;
-  error?: string;
+export interface RuntimeConfigUpdate<Change> {
+  readonly changed: boolean;
+  readonly change: Change;
 }
 
-/**
- * 这是应用创建 Config 时唯一可以接触的 Agent 实例能力。
- *
- * 身份通过实时 getter 暴露。
- *
- * 待确认：原注释把 getter 的必要性归因于 facet 元数据在 Durable Object
- * 构造后恢复，但当前 SDK 会在用户 `onStart` 前完成恢复。
- */
-export interface RuntimeAgentConfigContext<
-  Env extends Cloudflare.Env = Cloudflare.Env,
+interface RuntimeAgentDefinitionBase<
+  Env extends Cloudflare.Env,
+  Config,
+  Command,
+  Change,
 > {
-  /** 读取当前 Durable Object 的状态句柄。 */
-  readonly ctx: DurableObjectState;
-  /** 读取当前 Worker 的环境绑定。 */
-  readonly env: Env;
-  /** 读取当前 Agent 实例名称。 */
+  /** 必须等于 Worker 导出名（Wrangler `class_name`）。 */
   readonly name: string;
-  /** 读取从根节点到直接父节点的 Agent 路径。 */
-  readonly parentPath: readonly RuntimeAgentPathStep[];
-  /**
-   * 告诉生成类本次配置最终解析到了哪个 Runtime key。
-   *
-   * @remarks
-   * `createConfig` 在完成业务寻址后调用，同一次创建只能报告一个非空值。
-   *
-   * 生成类用该 key 合并重复加载；它只是运行时选择，不会写回业务配置。
-   */
-  setResolvedRuntimeKey(runtimeKey: string): void;
-  /**
-   * 请求重新装配一次 Runtime，让业务侧刚写入的配置立刻生效。
-   *
-   * @remarks
-   * 给「运行中改变自身可用能力」的 Tool 使用：先把变更写进持久层，再调用它，
-   * 新的 Snapshot 会按同一条解析链重新装配。不要在 Plugin 的 loader 里调用，
-   * 那会让装配递归。
-   */
-  reloadRuntime(): Promise<void>;
-  /**
-   * 通过当前 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>;
+
+  readonly load: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    requestedRuntimeKey?: string,
+  ) => Promise<LoadedRuntime<Config>>;
+
+  readonly tools: (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    config: Config,
+  ) => ToolRegistry | ToolAssemblyResult | Promise<ToolRegistry | ToolAssemblyResult>;
+
+  readonly hooks?:
+    | RuntimeAgentHooks<Env, Config, Command, Change>
+    | ((context: RuntimeAgentPlanningContext<Env, Command, Change>) =>
+      RuntimeAgentHooks<Env, Config, Command, Change>);
 }
 
-/**
- * 告诉 Runtime 如何定义 Agent 类并创建配置。
- *
- * @remarks
- * Worker 入口把它传给 `defineRuntimeAgent`。
- *
- * `createConfig` 只负责业务寻址和 Plugin 创建，原子装配由 Runtime 完成。
- */
-export interface RuntimeAgentDefinition<
+export interface ReadonlyRuntimeAgentDefinition<
   Env extends Cloudflare.Env = Cloudflare.Env,
-> {
-  /**
-   * 必须等于 Worker 导出名。
-   *
-   * 顶层 Agent 还必须与 Wrangler `class_name` 一致。
-   *
-   * 纯子 facet 不需要自己的顶层绑定。
-   *
-   * Agents SDK 使用构造器名称解析 facet 回调。
-   */
-  className: string;
-  /**
-   * 为当前 Agent 实例创建一次完整的 Plugin 配置。
-   *
-   * @remarks
-   * 生成类在首次执行需求和显式切换 Runtime key 时调用。
-   *
-   * 返回值尚未生效，只有 Runtime 完成校验和提交后才会替换当前 Snapshot。
-   */
-  createConfig(
+  Config = unknown,
+> extends RuntimeAgentDefinitionBase<Env, Config, never, never> {
+  readonly update?: never;
+}
+
+export interface MutableRuntimeAgentDefinition<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Config = unknown,
+  Command = unknown,
+  Change = unknown,
+> extends RuntimeAgentDefinitionBase<Env, Config, Command, Change> {
+  readonly update: (
     context: RuntimeAgentConfigContext<Env>,
-    runtimeKey?: string,
-  ): Promise<AgentConfig>;
+    command: Command,
+  ) => Promise<RuntimeConfigUpdate<Change>>;
 }
 
+export type RuntimeAgentDefinition<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Config = unknown,
+  Command = never,
+  Change = never,
+> = [Command] extends [never]
+  ? ReadonlyRuntimeAgentDefinition<Env, Config>
+  : MutableRuntimeAgentDefinition<Env, Config, Command, Change>;
+
 /**
  * 这是生成 Runtime Agent 的稳定公开控制面。
  *
@@ -257,6 +168,14 @@ export interface RuntimeAgentControls {
    * 待确认：当前 `refreshContext` 只检查 Snapshot 已安装，没有重新读取 Context 或刷新缓存。
    */
   refreshMemoryContext(): Promise<void>;
+  /**
+   * Read the Runtime Snapshot currently installed on this Session facet.
+   *
+   * @remarks
+   * Debug panels and Host tooling call this to inspect skills, subagents,
+   * extensions, and degradations that were actually assembled.
+   */
+  getRuntimeAssembly(): Promise<RuntimeAssemblyView>;
   /**
    * 读取 canonical transcript 的浏览器投影。
    *
@@ -286,6 +205,16 @@ export interface RuntimeAgentControls {
     executionId: string,
     decision: ApprovalDecision,
   ): Promise<{ ok: boolean }>;
+  /**
+   * 把客户端投递的响应作为某次 Tool 调用的结果并续跑原 Turn。
+   *
+   * @remarks
+   * 前端经 WS RPC 调用，只带 `toolCallId`。查无、已结算或响应体不过校验都返回 `{ ok: false }`。
+   */
+  respondToolInteraction(
+    toolCallId: string,
+    response: unknown,
+  ): Promise<{ ok: boolean }>;
   /**
    * 登记一条受管临时 Agent 发起的审批请求。
    *
@@ -375,6 +304,12 @@ export interface RuntimeAgentControls {
   ): Promise<{ ok: boolean }>;
 }
 
+export interface RuntimeAgentConfigControls<Command, Change> {
+  updateConfig(
+    command: Command,
+  ): Promise<RuntimeConfigUpdateResult<Change>>;
+}
+
 /**
  * 表示 `defineRuntimeAgent` 生成类的实例。
  *
@@ -383,7 +318,10 @@ export interface RuntimeAgentControls {
  */
 export type RuntimeAgentInstance<
   Env extends Cloudflare.Env = Cloudflare.Env,
-> = Agent<Env, RuntimeState> & RuntimeAgentControls;
+  Command = never,
+  Change = never,
+> = Agent<Env, RuntimeState> & RuntimeAgentControls &
+  RuntimeAgentConfigControls<Command, Change> & AgentToolChildAdapter<unknown, string>;
 
 /**
  * 表示 `defineRuntimeAgent` 返回的 Durable Object 类构造器。
@@ -393,26 +331,58 @@ export type RuntimeAgentInstance<
  */
 export interface RuntimeAgentClass<
   Env extends Cloudflare.Env = Cloudflare.Env,
+  Command = never,
+  Change = never,
 > {
-  new (ctx: DurableObjectState, env: Env): RuntimeAgentInstance<Env>;
+  new (
+    ctx: DurableObjectState,
+    env: Env,
+  ): RuntimeAgentInstance<Env, Command, Change>;
 }
 
 // #endregion
 
 // #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,
+  };
 }
 
 /**
@@ -425,20 +395,44 @@ function assertClassName(className: string): void {
  */
 export function defineRuntimeAgent<
   Env extends Cloudflare.Env = Cloudflare.Env,
+  Config = unknown,
+  Command = never,
+  Change = never,
 >(
-  definition: RuntimeAgentDefinition<Env>,
-): RuntimeAgentClass<Env> {
-  assertClassName(definition.className);
+  definition:
+    | 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 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 路径调用。
-      // 原因：Session 本地读取不应支付 Config、Plugin、MCP 和 Pi 装配成本。
+      // 原因：Session 本地读取不应支付 Config、Assembly、MCP 和 Pi 装配成本。
       protected ensureRuntimeReady(): Promise<void> {
         return this.ensureConfig();
       }
@@ -453,6 +447,28 @@ export function defineRuntimeAgent<
         await this.ensureConfig(runtimeKey, options?.force === true);
       }
 
+      async updateConfig(
+        command: Command,
+      ): Promise<RuntimeConfigUpdateResult<Change>> {
+        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" };
+        }
+        try {
+          await this.ensureConfig(undefined, true);
+          return { change: result.change, runtime: "reloaded" };
+        } catch {
+          return { change: result.change, runtime: "reload-failed" };
+        }
+      }
+
       // 作用：确保 Runtime 可用后请求 Kernel 刷新 Session Context。
       // 调用：Inbox 等 RPC 调用方在外部 Context 变更后调用。
       // 待确认：当前 Kernel 的 `refreshContext` 只检查 Snapshot，并未执行实际刷新。
@@ -461,6 +477,11 @@ export function defineRuntimeAgent<
         await this.refreshContext();
       }
 
+      async getRuntimeAssembly(): Promise<RuntimeAssemblyView> {
+        await this.ensureRuntimeReady();
+        return this.readRuntimeAssembly();
+      }
+
       dispatchMessage(
         message: UIMessage,
         delivery: MessageDelivery,
@@ -481,6 +502,13 @@ export function defineRuntimeAgent<
         return super.cancelSubmissionById(submissionId, reason);
       }
 
+      respondToolInteraction(
+        toolCallId: string,
+        response: unknown,
+      ): Promise<{ ok: boolean }> {
+        return super.respondToolInteraction(toolCallId, response);
+      }
+
       stopTurn(
         requestId?: string,
         reason?: string,
@@ -488,155 +516,366 @@ 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,
+          },
+        };
+      }
+
+      private async createTemporaryHooks(): Promise<
+        RuntimeAgentHooks<Env, Config, Command, Change>
+      > {
+        const launch = this.temporaryLaunch ??
+          await this.ctx.storage.get<TemporaryAgentLaunch<Config>>(
+            TEMPORARY_AGENT_LAUNCH_KEY,
+          );
+        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);
+          },
+        };
+      }
+
+      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);
+        }
+      }
 
-        // 先创建局部 Promise，再赋给 `loading`，失败时也能在 finally 中放开重试。
-        const pending = (async () => {
-          this.beginRuntimeLoad();
-          let resolvedRuntimeKey: string | undefined;
-          const agent = this;
-          const config = await definition.createConfig(
-            {
-              ctx: this.ctx,
-              env: this.env,
-              // 作用：在创建配置时读取当前 Agent 实例名。
-              // 调用：应用的 `createConfig` 在解析 Session 身份时读取。
-              // 原因：使用实时 getter，不在上下文创建时复制 SDK 身份值。
-              get name() {
-                return agent.name;
-              },
-              // 作用：在创建配置时读取根到直接父节点的路径。
-              // 调用：应用的 `createConfig` 在解析 facet 归属时读取。
-              // 原因：路径由 Agents SDK 维护，Runtime 只转发而不另存副本。
-              get parentPath() {
-                return agent.parentPath;
-              },
-              // 作用：记住本次配置解析出的 Runtime key。
-              // 调用：应用的 `createConfig` 在完成业务寻址后调用。
-              // 原因：只接受一个非空结果，防止同一次装配在两个业务身份之间摇摆。
-              setResolvedRuntimeKey(runtimeKey) {
-                const normalized = runtimeKey.trim();
-                if (!normalized) {
+      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);
+        });
+        return this.temporaryCleanup;
+      }
+
+      protected createDefinitionContext(
+        runtimeConfig?: { value: Config },
+      ): RuntimeAgentPlanningContext<
+        Env,
+        Command,
+        Change
+      > {
+        const agent = this;
+        return {
+          ctx: this.ctx,
+          env: this.env,
+          get name() {
+            return agent.name;
+          },
+          get parentPath() {
+            return agent.parentPath;
+          },
+          get role() {
+            return agent.role;
+          },
+          ...(agent.role === "primary"
+            ? {
+                updateConfig: (command: Command) =>
+                  agent.updateConfig(command),
+              }
+            : {}),
+          runAgentTool: async (agentClass, options) =>
+            agent.runAgentTool(
+              agentClass,
+              options as never,
+            ) as Promise<RuntimeAgentToolResult>,
+          clearAgentToolRuns: (options) =>
+            agent.clearAgentToolRuns(options),
+          executionLevel: () => agent.executionLevel(),
+          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(
-                    "Resolved Runtime key must not be empty",
+                    result.error ??
+                      `temporary agent ended with status ${result.status}`,
                   );
                 }
                 if (
-                  resolvedRuntimeKey &&
-                  resolvedRuntimeKey !== normalized
+                  typeof result.summary !== "string" ||
+                  !result.summary.trim()
                 ) {
                   throw new Error(
-                    "Resolved Runtime key cannot change during Config creation",
+                    "temporary agent completed without final text",
                   );
                 }
-                resolvedRuntimeKey = normalized;
+                return result.summary;
               },
-              // 作用：强制按当前业务数据重新装配 Runtime。
-              // 调用：会修改自身配置的 Tool 在持久化成功后调用。
-              // 原因：配置内容可能已变而 key 不变，因此不能复用已加载标记。
-              reloadRuntime: () => agent.ensureConfig(undefined, true),
-              // 作用：通过当前 Agent 启动一个受 SDK 管理的子运行。
-              // 调用：subagent 端口在委派 Agent Tool 时调用。
-              // 原因：保留 Agents SDK 的运行登记、事件、取消和清理边界。
-              runAgentTool: async (agentClass, options) =>
-                agent.runAgentTool(
-                  agentClass,
-                  options as never,
-                ) as Promise<RuntimeAgentToolResult>,
-              // 作用：清理符合明确策略的已保留子运行。
-              // 调用：subagent 端口在执行运行保留期回收时调用。
-              // 原因：清理仍由 Agents SDK 执行，Runtime 不越过 SDK 直接修改子运行存储。
-              clearAgentToolRuns: (options) =>
-                agent.clearAgentToolRuns(options),
-              // 作用：返回当前已装配 User Agent 的执行档位。
-              // 调用：Plugin 在装配临时 Agent 审批桥时调用。
-              // 原因：只读 Profile，不再维护 Session 覆盖状态。
-              executionLevel: () => agent.executionLevel(),
-              // 作用：在当前 Session 中执行一次性临时 Agent。
-              // 调用：temporary-agent 端口在 Tool 需要调用内委派时调用。
-              // 原因：交给 Kernel 统一管理重名、取消和审批，不创建持久 facet。
-              runTemporaryAgent: (request, runContext, execute) =>
-                agent.runTemporaryAgent(request, runContext, execute),
-            },
-            requestedRuntimeKey,
-          );
-
-          // 只有原子提交成功后才更新已加载标记和 key。
-          await this.initConfig(config);
-          this.hasLoadedRuntime = true;
-          this.loadedRuntimeKey =
-            resolvedRuntimeKey ?? requestedRuntimeKey;
-          this.completeRuntimeLoad();
-        })().catch((error) => {
-          this.failRuntimeLoad();
-          throw error;
-        });
-
-        if (fromQueue) return pending;
-
-        // 无论成功失败都清掉进行中标记，后续调用才可以重试或切 key。
-        let tracked: Promise<void>;
-        tracked = pending.finally(() => {
-          if (this.loading === tracked) this.loading = undefined;
-        });
-        this.loading = tracked;
-        return tracked;
+            );
+          },
+        };
       }
     },
-  }[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}"`,
     );
   }
 
   // Decorator syntax renames this computed class during Worker bundling.
   // 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,
@@ -646,9 +885,17 @@ export function defineRuntimeAgent<
     GeneratedRuntimeAgent.prototype.cancelSubmissionById,
     callableContext,
   );
+  callable()(
+    GeneratedRuntimeAgent.prototype.respondToolInteraction,
+    callableContext,
+  );
   callable()(GeneratedRuntimeAgent.prototype.stopTurn, callableContext);
 
-  return GeneratedRuntimeAgent as RuntimeAgentClass<Env>;
+  return GeneratedRuntimeAgent as unknown as RuntimeAgentClass<
+    Env,
+    Command,
+    Change
+  >;
 }
 
 // #endregion