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

package/src/runtime-agent.ts

@@ -23,11 +23,13 @@ import type {
   TemporaryAgentRequest,
   TemporaryAgentRunContext,
 } from "./layers/orchestration/temporary-agent/core";
-import type { AgentConfig } from "./plugins";
+import type { RuntimeAssemblyInput } from "./runtime-assembler";
+import type { RuntimeAssemblyView } from "./kernel/runtime-assembly-view";
+import type { RuntimeConfigUpdateResult } from "./kernel/runtime-config";
 import { AgentRuntimeKernel } from "./runtime";
 
 /**
- * 本文件把应用提供的 `createConfig` 接到 Cloudflare Agent 生命周期。
+ * 本文件把应用提供的 Config Definition 与 Planner 接到 Cloudflare Agent 生命周期。
  *
  * @remarks
  * 核心术语见包入口 `index.ts`。
@@ -136,24 +138,6 @@ export interface RuntimeAgentConfigContext<
   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。
    *
@@ -195,16 +179,59 @@ export interface RuntimeAgentConfigContext<
   ): 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> {
+  readonly runtimeKey: string;
+  readonly config: Config;
+}
+
+export interface RuntimeConfigUpdate<Change> {
+  readonly changed: boolean;
+  readonly change: Change;
+}
+
+export interface RuntimeAgentConfigDefinition<
+  Env extends Cloudflare.Env,
+  Config,
+  Command,
+  Change,
+> {
+  read(
+    context: RuntimeAgentConfigContext<Env>,
+    requestedRuntimeKey?: string,
+  ): Promise<ResolvedRuntimeConfig<Config>>;
+  update?(
+    context: RuntimeAgentConfigContext<Env>,
+    command: Command,
+  ): Promise<RuntimeConfigUpdate<Change>>;
+}
+
 /**
- * 告诉 Runtime 如何定义 Agent 类并创建配置。
+ * 告诉 Runtime 如何读取有效配置，并把它规划为一次扁平装配输入。
  *
  * @remarks
  * Worker 入口把它传给 `defineRuntimeAgent`。
  *
- * `createConfig` 只负责业务寻址和 Plugin 创建，原子装配由 Runtime 完成。
+ * Config 只负责业务寻址，Planner 把已读取配置投影为装配输入。
  */
-export interface RuntimeAgentDefinition<
-  Env extends Cloudflare.Env = Cloudflare.Env,
+interface RuntimeAgentDefinitionBase<
+  Env extends Cloudflare.Env,
+  Config,
+  Command,
+  Change,
 > {
   /**
    * 必须等于 Worker 导出名。
@@ -216,20 +243,47 @@ export interface RuntimeAgentDefinition<
    * Agents SDK 使用构造器名称解析 facet 回调。
    */
   className: string;
-  /**
-   * 为当前 Agent 实例创建一次完整的 Plugin 配置。
-   *
-   * @remarks
-   * 生成类在首次执行需求和显式切换 Runtime key 时调用。
-   *
-   * 返回值尚未生效，只有 Runtime 完成校验和提交后才会替换当前 Snapshot。
-   */
-  createConfig(
-    context: RuntimeAgentConfigContext<Env>,
-    runtimeKey?: string,
-  ): Promise<AgentConfig>;
+  planRuntime(
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    config: Config,
+  ): Promise<RuntimeAssemblyInput>;
 }
 
+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 };
+}
+
+export interface MutableRuntimeAgentDefinition<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+  Config = unknown,
+  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">
+  >;
+}
+
+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 +311,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 +348,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 +447,15 @@ export interface RuntimeAgentControls {
   ): Promise<{ ok: boolean }>;
 }
 
+export type RuntimeAgentConfigControls<Command, Change> =
+  [Command] extends [never]
+    ? Record<never, never>
+    : {
+        updateConfig(
+          command: Command,
+        ): Promise<RuntimeConfigUpdateResult<Change>>;
+      };
+
 /**
  * 表示 `defineRuntimeAgent` 生成类的实例。
  *
@@ -383,7 +464,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>;
 
 /**
  * 表示 `defineRuntimeAgent` 返回的 Durable Object 类构造器。
@@ -393,8 +477,13 @@ 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
@@ -423,12 +512,35 @@ 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,
+  Command = never,
+  Change = never,
 >(
-  definition: RuntimeAgentDefinition<Env>,
-): RuntimeAgentClass<Env> {
+  definition:
+    | MutableRuntimeAgentDefinition<Env, Config, Command, Change>
+    | ReadonlyRuntimeAgentDefinition<Env, Config>,
+): RuntimeAgentClass<Env, Command, Change> {
   assertClassName(definition.className);
+  const planRuntime = definition.planRuntime as (
+    context: RuntimeAgentPlanningContext<Env, Command, Change>,
+    config: Config,
+  ) => Promise<RuntimeAssemblyInput>;
 
   const GeneratedRuntimeAgent = {
     [definition.className]: class extends AgentRuntimeKernel<Env> {
@@ -438,7 +550,7 @@ export function defineRuntimeAgent<
 
       // 作用：在 Kernel 真正消费 RuntimeSnapshot 前确保配置已完整提交。
       // 调用：Submission 准入、恢复、审批续跑与 Runtime Workspace 路径调用。
-      // 原因：Session 本地读取不应支付 Config、Plugin、MCP 和 Pi 装配成本。
+      // 原因：Session 本地读取不应支付 Config、Assembly、MCP 和 Pi 装配成本。
       protected ensureRuntimeReady(): Promise<void> {
         return this.ensureConfig();
       }
@@ -453,6 +565,23 @@ export function defineRuntimeAgent<
         await this.ensureConfig(runtimeKey, options?.force === true);
       }
 
+      async updateConfig(
+        command: Command,
+      ): Promise<RuntimeConfigUpdateResult<Change>> {
+        const update = definition.config.update;
+        if (!update) throw new Error("Runtime Agent Config is read-only");
+        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 +590,11 @@ export function defineRuntimeAgent<
         await this.refreshContext();
       }
 
+      async getRuntimeAssembly(): Promise<RuntimeAssemblyView> {
+        await this.ensureRuntimeReady();
+        return this.readRuntimeAssembly();
+      }
+
       dispatchMessage(
         message: UIMessage,
         delivery: MessageDelivery,
@@ -481,6 +615,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,
@@ -535,83 +676,28 @@ export function defineRuntimeAgent<
 
         // 先创建局部 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) {
-                  throw new Error(
-                    "Resolved Runtime key must not be empty",
-                  );
-                }
-                if (
-                  resolvedRuntimeKey &&
-                  resolvedRuntimeKey !== normalized
-                ) {
-                  throw new Error(
-                    "Resolved Runtime key cannot change during Config creation",
-                  );
-                }
-                resolvedRuntimeKey = normalized;
-              },
-              // 作用：强制按当前业务数据重新装配 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),
-            },
+          this.runtimeLoad.begin();
+          const context = this.createDefinitionContext();
+          const resolved = await definition.config.read(
+            context,
             requestedRuntimeKey,
           );
+          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(config);
+          await this.initConfig(input);
           this.hasLoadedRuntime = true;
-          this.loadedRuntimeKey =
-            resolvedRuntimeKey ?? requestedRuntimeKey;
-          this.completeRuntimeLoad();
+          this.loadedRuntimeKey = resolvedRuntimeKey;
+          this.runtimeLoad.complete();
+          // 提交之前 turnEvents 绑定还不存在，此前每一次广播都到不了 Host。
+          // Host 的会话列表把装配后的第一次投影当作「facet 已就绪」的信号。
+          await this.broadcastApprovals();
         })().catch((error) => {
-          this.failRuntimeLoad();
+          this.runtimeLoad.fail();
           throw error;
         });
 
@@ -625,6 +711,40 @@ export function defineRuntimeAgent<
         this.loading = tracked;
         return tracked;
       }
+
+      private createDefinitionContext(): RuntimeAgentPlanningContext<
+        Env,
+        Command,
+        Change
+      > {
+        const agent = this;
+        return {
+          ctx: this.ctx,
+          env: this.env,
+          get name() {
+            return agent.name;
+          },
+          get parentPath() {
+            return agent.parentPath;
+          },
+          ...(definition.config.update
+            ? {
+                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, execute) =>
+            agent.runTemporaryAgent(request, runContext, execute),
+        };
+      }
     },
   }[definition.className];
 
@@ -637,6 +757,7 @@ export function defineRuntimeAgent<
   // 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.dispatchMessage, callableContext);
   callable()(
     GeneratedRuntimeAgent.prototype.steerQueuedSubmission,
@@ -647,8 +768,20 @@ export function defineRuntimeAgent<
     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;
+  }
 
-  return GeneratedRuntimeAgent as RuntimeAgentClass<Env>;
+  return GeneratedRuntimeAgent as RuntimeAgentClass<Env, Command, Change>;
 }
 
 // #endregion