@springbrand/agent-runtime 0.1.0

package/src/runtime-agent.ts

@@ -0,0 +1,654 @@
+import {
+  callable,
+  type Agent,
+  type AgentToolRunStatus,
+  type ChatCapableAgentClass,
+  type RunAgentToolOptions,
+} from "agents";
+import type { UIMessage } from "ai";
+import type { PiCanonicalTranscriptSnapshot } from "./pi/runtime-adapter";
+import type {
+  ApprovalDecision,
+  ApprovalReceipt,
+  MessageDelivery,
+  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,
+} from "./layers/orchestration/temporary-agent/core";
+import type { AgentConfig } from "./plugins";
+import { AgentRuntimeKernel } from "./runtime";
+
+/**
+ * 本文件把应用提供的 `createConfig` 接到 Cloudflare Agent 生命周期。
+ *
+ * @remarks
+ * 核心术语见包入口 `index.ts`。
+ */
+
+// #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[];
+  /**
+   * 告诉生成类本次配置最终解析到了哪个 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>;
+}
+
+/**
+ * 告诉 Runtime 如何定义 Agent 类并创建配置。
+ *
+ * @remarks
+ * Worker 入口把它传给 `defineRuntimeAgent`。
+ *
+ * `createConfig` 只负责业务寻址和 Plugin 创建，原子装配由 Runtime 完成。
+ */
+export interface RuntimeAgentDefinition<
+  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(
+    context: RuntimeAgentConfigContext<Env>,
+    runtimeKey?: string,
+  ): Promise<AgentConfig>;
+}
+
+/**
+ * 这是生成 Runtime Agent 的稳定公开控制面。
+ *
+ * Pi 与 Cloudflare Agent 生命周期钩子和 Kernel 实现方法有意不进入这个 API。
+ */
+export interface RuntimeAgentControls {
+  /**
+   * 确保当前 Runtime 已加载，或按给定 key 显式重载。
+   *
+   * @remarks
+   * RPC 调用方在业务配置变更后调用；`force` 用于 key 没变但配置内容已变的情况。
+   *
+   * 实现与首次启动共用同一串行入口，避免并发重载安装不同的 Snapshot。
+   */
+  reloadRuntime(
+    runtimeKey?: string,
+    options?: { force?: boolean },
+  ): Promise<void>;
+  /**
+   * 确保 Runtime 已加载，再请求 Kernel 刷新当前 Session Context。
+   *
+   * @remarks
+   * 业务侧在外部 Context 变更后调用，例如 Inbox 需要让已存在的聊天立即重读内容。
+   *
+   * 待确认：当前 `refreshContext` 只检查 Snapshot 已安装，没有重新读取 Context 或刷新缓存。
+   */
+  refreshMemoryContext(): Promise<void>;
+  /**
+   * 读取 canonical transcript 的浏览器投影。
+   *
+   * @remarks
+   * UI 或 fork 流程需要当前消息历史时调用。
+   *
+   * 返回值由 Pi transcript 统一生成，调用方不应另建第二份权威历史。
+   */
+  getMessages(): Promise<UIMessage[]>;
+  /**
+   * 把一组既有消息一次性导入 canonical transcript。
+   *
+   * @remarks
+   * 只供真实 fork 或 import 流程在新 Session 初始化时调用。
+   *
+   * 普通发送必须经过 `submitPrompt`，否则会绕过 admission 和回执状态。
+   */
+  getCanonicalSnapshot(
+    throughMessageId: string,
+  ): Promise<PiCanonicalTranscriptSnapshot>;
+  /** Import a server-authored canonical transcript snapshot into a new Session. */
+  addCanonicalSnapshot(snapshot: PiCanonicalTranscriptSnapshot): Promise<void>;
+  /** 读取一条仍待决定的审批，供 Host 可信处理 `allow_level`。 */
+  getPendingApproval(executionId: string): ApprovalReceipt | null;
+  /** 对当前待审批执行应用一次决定。 */
+  decideApproval(
+    executionId: string,
+    decision: ApprovalDecision,
+  ): Promise<{ ok: boolean }>;
+  /**
+   * 登记一条受管临时 Agent 发起的审批请求。
+   *
+   * @remarks
+   * temporary-agent runner 在子执行调用需审批的 Tool 时调用并等待结果。
+   *
+   * Kernel 按 execution id 保留唯一等待项并广播给 UI，重复 id 会立即失败。
+   */
+  requestTemporaryAgentApproval(
+    request: TemporaryAgentApprovalRequest,
+  ): Promise<TemporaryAgentApprovalDecision>;
+  /**
+   * 移除已不再等待的临时 Agent 审批请求。
+   *
+   * @remarks
+   * temporary-agent runner 在子执行取消或提前结束时调用。
+   *
+   * 取消会以拒绝结果解除原等待，并刷新 UI；找不到 id 时返回 `ok: false`。
+   */
+  cancelTemporaryAgentApproval(
+    executionId: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }>;
+  /**
+   * 提交一个用户提示，并返回可查询的回执。
+   *
+   * @remarks
+   * RPC 调用方需要程序化启动 Turn 时调用，可传入幂等 key 复用已接纳提交。
+   *
+   * 方法在 admission 后立即返回，完成 Promise 交给 Durable Object `waitUntil`，调用方用回执另行查询。
+   */
+  submitPrompt(
+    text: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<SubmissionReceipt>;
+  dispatchMessage(
+    message: UIMessage,
+    delivery: MessageDelivery,
+  ): Promise<MessageDispatchReceipt>;
+  steerQueuedSubmission(
+    submissionId: string,
+  ): Promise<MessageDispatchReceipt>;
+  /**
+   * 等待 Session 稳定后提交提示，并在准入后返回当前回执。
+   *
+   * @remarks
+   * schedule 端口在 Cloudflare Agents SDK 唤醒对应回调后调用。
+   *
+   * 它与普通提示共用 admission，但最多等待当前实现的 30 秒稳定期，超时返回 `skipped`。
+   */
+  submitScheduledPrompt(
+    prompt: string,
+    opts?: { idempotencyKey?: string },
+  ): Promise<SubmissionReceipt>;
+  /**
+   * 按提交编号查询当前处理状态。
+   *
+   * @remarks
+   * RPC 调用方在 `submitPrompt` 返回后跟踪结果时调用。
+   *
+   * 结果来自持久化的 submission 生命周期，不存在的编号返回 `null`。
+   */
+  getSubmission(submissionId: string): Promise<SubmissionReceipt | null>;
+  /**
+   * 按提交编号取消尚未结束的请求。
+   *
+   * @remarks
+   * RPC 调用方已知 submission id 时调用，可附带面向记录的原因。
+   *
+   * Kernel 把取消交给 submission 生命周期，由它区分等待、运行和已终止状态。
+   */
+  cancelSubmissionById(
+    submissionId: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }>;
+  /**
+   * 停止当前或指定请求的 Turn。
+   *
+   * @remarks
+   * UI 或 RPC 调用方在用户主动停止生成时调用；省略 request id 表示当前 Turn。
+   *
+   * Kernel 通过 submission 生命周期向当前 Pi 执行传递中止，不直接修改 transcript。
+   */
+  stopTurn(
+    requestId?: string,
+    reason?: string,
+  ): Promise<{ ok: boolean }>;
+}
+
+/**
+ * 表示 `defineRuntimeAgent` 生成类的实例。
+ *
+ * @remarks
+ * RPC 调用方使用这个交叉类型访问 Cloudflare Agent 能力和稳定控制面。
+ */
+export type RuntimeAgentInstance<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> = Agent<Env, RuntimeState> & RuntimeAgentControls;
+
+/**
+ * 表示 `defineRuntimeAgent` 返回的 Durable Object 类构造器。
+ *
+ * @remarks
+ * Worker 入口导出该类，Cloudflare Runtime 负责实例化它。
+ */
+export interface RuntimeAgentClass<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+> {
+  new (ctx: DurableObjectState, env: Env): RuntimeAgentInstance<Env>;
+}
+
+// #endregion
+
+// #region 生成类的构造与生命周期
+
+// 作用：确认导出类名是可以安全创建的 JavaScript 标识符。
+// 调用：`defineRuntimeAgent` 在生成类之前调用一次。
+// 原因：动态计算类名时提前拒绝关键字，避免部署后才出现寻址失败。
+function assertClassName(className: string): void {
+  if (
+    !JAVASCRIPT_IDENTIFIER.test(className) ||
+    RESERVED_IDENTIFIERS.has(className)
+  ) {
+    throw new Error(
+      `Invalid Runtime Agent className "${className}": expected a non-reserved JavaScript identifier`,
+    );
+  }
+}
+
+/**
+ * 生成一个不向应用暴露 Kernel 继承细节的 Cloudflare Agent 类。
+ *
+ * @remarks
+ * Worker 入口调用一次，并把返回类作为稳定导出。
+ *
+ * 生成类把首次加载、并发去重、按 key 重载和失败重试收口到一个入口。
+ */
+export function defineRuntimeAgent<
+  Env extends Cloudflare.Env = Cloudflare.Env,
+>(
+  definition: RuntimeAgentDefinition<Env>,
+): RuntimeAgentClass<Env> {
+  assertClassName(definition.className);
+
+  const GeneratedRuntimeAgent = {
+    [definition.className]: class extends AgentRuntimeKernel<Env> {
+      private hasLoadedRuntime = false;
+      private loadedRuntimeKey?: string;
+      private loading?: Promise<void>;
+
+      // 作用：在 Kernel 真正消费 RuntimeSnapshot 前确保配置已完整提交。
+      // 调用：Submission 准入、恢复、审批续跑与 Runtime Workspace 路径调用。
+      // 原因：Session 本地读取不应支付 Config、Plugin、MCP 和 Pi 装配成本。
+      protected ensureRuntimeReady(): Promise<void> {
+        return this.ensureConfig();
+      }
+
+      // 作用：加载默认 Runtime，或切换到调用方指定的 key。
+      // 调用：RPC 控制面在业务配置需要刷新时调用。
+      // 原因：复用 `ensureConfig`，让手动重载遵守和首次启动相同的原子规则。
+      async reloadRuntime(
+        runtimeKey?: string,
+        options?: { force?: boolean },
+      ): Promise<void> {
+        await this.ensureConfig(runtimeKey, options?.force === true);
+      }
+
+      // 作用：确保 Runtime 可用后请求 Kernel 刷新 Session Context。
+      // 调用：Inbox 等 RPC 调用方在外部 Context 变更后调用。
+      // 待确认：当前 Kernel 的 `refreshContext` 只检查 Snapshot，并未执行实际刷新。
+      async refreshMemoryContext(): Promise<void> {
+        await this.ensureRuntimeReady();
+        await this.refreshContext();
+      }
+
+      dispatchMessage(
+        message: UIMessage,
+        delivery: MessageDelivery,
+      ): Promise<MessageDispatchReceipt> {
+        return super.dispatchMessage(message, delivery);
+      }
+
+      steerQueuedSubmission(
+        submissionId: string,
+      ): Promise<MessageDispatchReceipt> {
+        return super.steerQueuedSubmission(submissionId);
+      }
+
+      cancelSubmissionById(
+        submissionId: string,
+        reason?: string,
+      ): Promise<{ ok: boolean }> {
+        return super.cancelSubmissionById(submissionId, reason);
+      }
+
+      stopTurn(
+        requestId?: string,
+        reason?: string,
+      ): Promise<{ ok: boolean }> {
+        return super.stopTurn(requestId, reason);
+      }
+
+      // 作用：把首次加载和按 key 重载合并成一个串行入口。
+      // 调用：Runtime readiness、Session 配置和重载都会调用。
+      // 原因：共享同一个 Promise 可合并并发首加载，显式切 key 则等待前序完成后再判断。
+      private 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(
+                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.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),
+            },
+            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];
+
+  if (GeneratedRuntimeAgent.name !== definition.className) {
+    throw new Error(
+      `Runtime Agent class name mismatch: expected "${definition.className}", 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.dispatchMessage, callableContext);
+  callable()(
+    GeneratedRuntimeAgent.prototype.steerQueuedSubmission,
+    callableContext,
+  );
+  callable()(
+    GeneratedRuntimeAgent.prototype.cancelSubmissionById,
+    callableContext,
+  );
+  callable()(GeneratedRuntimeAgent.prototype.stopTurn, callableContext);
+
+  return GeneratedRuntimeAgent as RuntimeAgentClass<Env>;
+}
+
+// #endregion