@springbrand/agent-runtime 0.1.0

package/src/pi/runtime-adapter/index.ts

@@ -0,0 +1,232 @@
+import {
+  PreparedPiTurnAdapter,
+  type CreatePreparedPiTurnOptions,
+} from "./execution";
+import {
+  uiUserMessageToPi,
+} from "../message";
+import type { UIMessage } from "ai";
+import { createModels, type MutableModels } from "@earendil-works/pi-ai";
+import { configurePiModels, resolvePiApiKey } from "./models";
+export { withProviderRetry } from "./models";
+import {
+  pinPiRuntime,
+  preparePiRuntime,
+  type PinPiRuntimeOptions,
+  type PinnedPiRuntime,
+  type PreparePiRuntimeOptions,
+  type PreparedPiRuntime,
+} from "./assembly";
+import {
+  decidePiRecovery,
+  PiRuntimeRecoveryAdapter,
+  type PiRecoveryHost,
+  type PiRecoveryInput,
+} from "./recovery";
+import {
+  PiRuntimeTranscript,
+  type PiTranscriptDurability,
+} from "./transcript";
+import type { SqlTaggedTemplate } from "agents/chat";
+
+/**
+ * Runtime 只通过这个入口使用 Pi 的装配、执行、消息和恢复能力。
+ *
+ * @remarks
+ * Runtime、Pi、Turn、Tool Candidate 和 canonical transcript 等核心术语见包入口 `../../index.ts`。
+ * 本适配器只补充以下局部术语。
+ *
+ * - Prepared Runtime 是配置加载期产生的不透明句柄。
+ *   它包含已加载 Extension、Tool candidate 和快照，但 Runtime 只能读取 revision descriptor 与 degradation。
+ * - revision descriptor 是影响执行行为的已排序 JSON 描述。
+ *   Runtime 会对它取哈希，用来识别当前 Prepared Runtime 的基础版本。
+ * - Pinned Runtime 是 Submission 准入时固定的描述符。
+ *   它在 Prepared Runtime 基础上加入动态 system context、approval mode 和 base revision。
+ * - recovery milestone 是可重放的持久化恢复记录。
+ *   recovery effect 是重放后交给 Runtime 执行的唯一下一步动作。
+ *
+ * 调用方：`AgentRuntimeKernel` 在配置加载、请求准入、Turn 执行和中断恢复时调用这些粗粒度能力。
+ *
+ * 实现理由：较早的入口曾直接公开 assembly、message、session、tool 和 recovery 命名空间。
+ * 当前边界刻意隐藏这些细节，避免 Runtime 同时维护第二套 Pi 状态或绕过统一校验。
+ * 不要为了调用某个内部 helper 重新导出子模块；应先判断它是否属于 Runtime 真正需要的边界能力。
+ */
+export class PiRuntimeAdapter {
+  private readonly owner = {};
+  private readonly models: MutableModels;
+  private readonly managesModels: boolean;
+
+  /**
+   * 创建一个持有独立 Pi 模型目录的 Runtime 适配器。
+   *
+   * @remarks
+   * 调用方：生产 Runtime 使用零参数构造，测试或专用宿主可以注入已经配置好的模型目录。
+   *
+   * 实现理由：适配器只管理自己创建的目录；注入目录的生命周期和配置权仍属于注入方。
+   * 不要让 `activate()` 重配注入目录，否则会覆盖调用方准备的 provider 和模型替身。
+   */
+  constructor(options: { models?: MutableModels } = {}) {
+    this.models = options.models ?? createModels();
+    this.managesModels = !options.models;
+  }
+
+  /**
+   * 创建负责 canonical transcript、浏览器投影和上下文压缩的对象。
+   *
+   * @remarks
+   * 调用方：Runtime 构造函数为当前实例创建一次，并提供 SQLite、事务和 Submission 投影回调。
+   *
+   * 实现理由：transcript 与 Turn 共用同一个模型目录，让上下文压缩和实际执行看到相同的 provider 配置。
+   * 不要把 RuntimeDatabase 直接传进 Pi 层；持久化职责应继续通过这里的窄回调提供。
+   */
+  createTranscript(options: {
+    readonly sql: SqlTaggedTemplate;
+    readonly durability: PiTranscriptDurability;
+    readonly hasActiveTurn: () => boolean;
+  }): PiRuntimeTranscript {
+    return new PiRuntimeTranscript(
+      options.sql,
+      options.durability,
+      this.models,
+      options.hasActiveTurn,
+    );
+  }
+
+  /**
+   * 把已校验的浏览器用户消息转换成 Pi 可以写入 transcript 的用户消息。
+   *
+   * @remarks
+   * 调用方：Runtime 收到 submit 或 regenerate 请求并完成结构校验后，在持久化 Submission 前调用。
+   *
+   * 实现理由：转换只生成 Pi UserMessage 的 content 和 timestamp，原始浏览器视图由 transcript sidecar 另行保存。
+   * 不要把 UI id、metadata 或原始 part 结构并入 canonical message。
+   */
+  normalizeUserInput(input: UIMessage & { role: "user" }) {
+    return uiUserMessageToPi(input);
+  }
+
+  resolveApiKey(
+    ...args: Parameters<typeof resolvePiApiKey>
+  ): ReturnType<typeof resolvePiApiKey> {
+    return resolvePiApiKey(...args);
+  }
+
+  /**
+   * 加载并预检一份可供后续准入使用的 Prepared Runtime。
+   *
+   * @remarks
+   * 调用方：Runtime 的 `initConfig()` 在取得新快照后调用，再用返回的 revision descriptor 判断是否可以切换配置。
+   *
+   * 实现理由：Extension 加载、Tool candidate 汇总和 Tool 编译预检在配置切换前一次完成。
+   * 返回值绑定当前 Adapter 的 owner，不能交给另一个 Adapter 创建 Turn。
+   */
+  prepare(
+    options: PreparePiRuntimeOptions,
+  ): Promise<PreparedPiRuntime> {
+    return preparePiRuntime(options, this.owner);
+  }
+
+  /**
+   * 用已经通过加载检查的快照启用当前部署声明的模型目录。
+   *
+   * @remarks
+   * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
+   *
+   * 实现理由：激活会校验并注册所有 endpoint 中声明的模型，而不只校验当前选中的模型。
+   * 这解释了为什么一个未被选中的无效模型也会让配置启动失败；不要把激活误当成首次推理请求。
+   * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
+   */
+  activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
+    if (this.managesModels) {
+      configurePiModels(this.models, snapshot.bindings.provider);
+    }
+  }
+
+  /**
+   * 在接受 Submission 前固定本次执行使用的动态上下文和审批模式。
+   *
+   * @remarks
+   * 调用方：Runtime 的准入流程为每个新 Submission 调用，并把 descriptor 与其哈希一起持久化。
+   *
+   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，恢复必须使用准入时的描述符检查兼容性。
+   * 不要把 pin 推迟到 Turn 启动后，否则已持久化的 Submission 将失去可验证的执行基线。
+   */
+  pin(options: PinPiRuntimeOptions): Promise<PinnedPiRuntime> {
+    return pinPiRuntime(options, this.owner);
+  }
+
+  /**
+   * 根据持久化 milestone 和一个命令算出恢复时要写什么、下一步做什么。
+   *
+   * @remarks
+   * 调用方：Runtime 和 approval 生命周期在检查状态、记录 Tool 输入结果、处理审批或提交终态时调用。
+   *
+   * 实现理由：该方法只返回 durable mutations 和一个 effect，实际写库与调度仍由 Runtime 完成。
+   * replay、plan、stage、commit 和 encode 必须保持在同一决策入口，避免宿主与 Pi 各自推导出不同状态。
+   */
+  decideRecovery(options: PiRecoveryInput) {
+    return decidePiRecovery(options);
+  }
+
+  /**
+   * 把 Runtime 提供的持久化和重试回调包装成通用聊天恢复端口。
+   *
+   * @remarks
+   * 调用方：`AgentRuntimeKernel.createRecoveryPort()` 在恢复引擎需要分类、重试、终结或读取部分输出时创建并复用它。
+   *
+   * 实现理由：Durable Object 被驱逐或休眠后内存状态不会保留，因此恢复判断必须从宿主持久化状态和 stream chunk 重建。
+   * Pi 负责解释 milestone，Runtime 仍负责数据库写入、Submission 重试和终态提交；不要合并这两个所有权边界。
+   */
+  createRecovery(host: PiRecoveryHost) {
+    return new PiRuntimeRecoveryAdapter(host);
+  }
+
+  /**
+   * 为一个已准入的 Submission 创建一次可执行的 Pi Turn。
+   *
+   * @remarks
+   * 调用方：Runtime 在首次执行和恢复继续时各创建一个新 Turn，并提供 canonical messages、durable Tool 回调和流事件回调。
+   *
+   * 实现理由：构造时会校验 Prepared Runtime 的 owner、pinned descriptor 和 base revision，再建立本 Turn 独享的 Tool governance 与执行状态。
+   * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
+   */
+  createTurn(
+    options: CreatePreparedPiTurnOptions,
+  ): PreparedPiTurnAdapter {
+    return new PreparedPiTurnAdapter(options, {
+      owner: this.owner,
+      models: this.models,
+    });
+  }
+}
+
+export type {
+  UIChatRequestBody,
+} from "../message";
+export type { PiToolApproval } from "../turn";
+export type {
+  CreatePreparedPiTurnOptions,
+  PiCanonicalUserInput,
+  PiStoredToolSettlement,
+  PiToolSettlement,
+  PiToolInputRecord,
+  PreparedPiTurnAdapter,
+} from "./execution";
+export type {
+  PinPiRuntimeOptions,
+  PinnedPiRuntime,
+  PreparePiRuntimeOptions,
+  PreparedPiRuntime,
+} from "./assembly";
+export type {
+  PiChatRecoveryData,
+  PiDurableMutation,
+  PiDurableRecoveryState,
+  PiRecoveryCommand,
+  PiRecoveryDecision,
+  PiRecoveryHost,
+} from "./recovery";
+export type {
+  PiRuntimeTranscript,
+  PiCanonicalTranscriptSnapshot,
+} from "./transcript";

package/src/pi/runtime-adapter/models.ts

@@ -0,0 +1,243 @@
+import type { StreamFn } from "@earendil-works/pi-agent-core";
+import {
+  createModels,
+  createProvider,
+  type Api,
+  type Model,
+  type MutableModels,
+} from "@earendil-works/pi-ai";
+import {
+  anthropicMessagesApi,
+} from "@earendil-works/pi-ai/api/anthropic-messages.lazy";
+import {
+  openAICompletionsApi,
+} from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import {
+  googleGenerativeAIApi,
+} from "@earendil-works/pi-ai/api/google-generative-ai.lazy";
+import {
+  openAICodexResponsesApi,
+} from "@earendil-works/pi-ai/api/openai-codex-responses.lazy";
+import {
+  anthropicProvider,
+} from "@earendil-works/pi-ai/providers/anthropic";
+import {
+  openaiProvider,
+} from "@earendil-works/pi-ai/providers/openai";
+import {
+  googleProvider,
+} from "@earendil-works/pi-ai/providers/google";
+import {
+  openaiCodexProvider,
+} from "@earendil-works/pi-ai/providers/openai-codex";
+import type {
+  RuntimeModelEndpoint,
+  RuntimeModelProtocol,
+  RuntimeProviderPort,
+} from "../../kernel/bindings";
+
+const CATALOGS = {
+  "openai-chat": openaiProvider().getModels(),
+  "anthropic-messages": anthropicProvider().getModels(),
+  "google-generative-ai": googleProvider().getModels(),
+  "openai-codex-responses": openaiCodexProvider().getModels(),
+} satisfies Record<RuntimeModelProtocol, readonly Model<Api>[]>;
+
+const PROVIDER_MAX_RETRIES = 2;
+
+/**
+ * 给模型请求补上可中断的 provider 瞬时错误重试。
+ *
+ * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Pi 前调用；显式传入的重试次数优先。
+ *
+ * Pi 0.83 默认 `maxRetries` 为 0，这里只补 2 次默认值，避免瞬时网络错误直接终止，同时不覆盖调用方策略。
+ */
+export function withProviderRetry(streamFn: StreamFn): StreamFn {
+  return (model, context, options) =>
+    streamFn(model, context, {
+      ...options,
+      maxRetries: options?.maxRetries ?? PROVIDER_MAX_RETRIES,
+    });
+}
+
+// 找出部署把这个模型放在哪个端点，并保留该端点在配置中的位置。
+// resolvePiModel 和 resolvePiApiKey 在组装运行快照、发起模型请求前调用它，调用方只需传部署配置和 modelId。
+// 这里复用同一条查找路径，避免模型与密钥落到不同端点；同一 modelId 若配置多次会取第一个，是否应改为拒绝重复配置仍待确认。
+function endpointFor(
+  provider: RuntimeProviderPort,
+  modelId: string,
+): { endpoint: RuntimeModelEndpoint; index: number } {
+  const index = provider.endpoints.findIndex((endpoint) =>
+    endpoint.models.includes(modelId),
+  );
+  if (index < 0) {
+    throw new Error(`Model is not configured by this deployment: ${modelId}`);
+  }
+  return { endpoint: provider.endpoints[index], index };
+}
+
+// 给一个部署端点生成 Pi 内部使用的 provider 标识。
+// configuredModel 和 configurePiModels 必须用相同参数调用它，让模型上的 provider 与注册进 MutableModels 的 provider 对得上。
+// Pi 当前按 provider.id 存取和替换 provider，所以编号用于区分同协议端点；格式和端点顺序会影响路由身份，不能只改其中一处。
+function providerId(endpoint: RuntimeModelEndpoint, index: number): string {
+  return `model-api-${endpoint.protocol}-${index}`;
+}
+
+function apiFor(protocol: RuntimeModelProtocol): Api {
+  switch (protocol) {
+    case "openai-chat":
+      return "openai-completions";
+    case "anthropic-messages":
+      return "anthropic-messages";
+    case "google-generative-ai":
+      return "google-generative-ai";
+    case "openai-codex-responses":
+      return "openai-codex-responses";
+  }
+}
+
+function piApiFor(protocol: RuntimeModelProtocol) {
+  switch (protocol) {
+    case "openai-chat":
+      return openAICompletionsApi();
+    case "anthropic-messages":
+      return anthropicMessagesApi();
+    case "google-generative-ai":
+      return googleGenerativeAIApi();
+    case "openai-codex-responses":
+      return openAICodexResponsesApi();
+  }
+}
+
+// 把部署声明的模型改造成可由对应自定义端点执行的 Pi 模型。
+// resolvePiModel 为单个运行快照调用它，configurePiModels 则在注册端点时为端点中的每个 modelId 调用它。
+// Pi 的内置 OpenAI、Anthropic provider 提供上下文窗口、费用和推理能力等元数据；这里保留这些元数据，但以部署协议、provider 标识和 baseURL 覆盖内置路由，未知模型会在初始化阶段直接报错，而不是拖到请求阶段。
+function configuredModel(
+  endpoint: RuntimeModelEndpoint,
+  index: number,
+  modelId: string,
+): Model<Api> {
+  const catalogModel = CATALOGS[endpoint.protocol].find(
+    (model) => model.id === modelId,
+  );
+  if (!catalogModel) {
+    throw new Error(
+      `Model is not in Pi's built-in catalog for ${endpoint.protocol}: ${modelId}`,
+    );
+  }
+  // 待确认：当前统一丢弃 catalogModel.compat；现有提交历史没有说明这样做对 Anthropic 兼容参数的影响，修改前需先验证 Pi 的流式请求行为。
+  const {
+    api: _api,
+    provider: _provider,
+    baseUrl: _baseUrl,
+    compat: _compat,
+    headers: catalogHeaders,
+    ...metadata
+  } = catalogModel;
+  const headers = {
+    ...catalogHeaders,
+    ...endpoint.headers,
+  };
+  return {
+    ...metadata,
+    api: apiFor(endpoint.protocol),
+    provider: providerId(endpoint, index),
+    baseUrl: endpoint.baseURL,
+    ...(Object.keys(headers).length > 0 ? { headers } : {}),
+  };
+}
+
+/**
+ * 把部署允许的 modelId 解析成 Pi 可以直接执行的模型。
+ *
+ * Runtime 组装不可变运行快照时调用它；标题生成器和临时 Agent 也会先解析默认模型，再把返回值交给 Pi 的 Models 实例。
+ * 调用方应传入同一份 `RuntimeProviderPort`，随后用 {@link configurePiModels} 或 {@link createPiModels} 注册与该模型匹配的 provider。
+ *
+ * 解析先检查部署端点，再借用 Pi 当前内置 OpenAI、Anthropic catalog 的能力和计费元数据，同时把实际协议、provider 与 baseURL 改成部署配置。
+ * 这两道检查不能随便跳过，否则未获部署授权的模型或 Pi 不认识的模型会延迟到执行阶段才失败。
+ *
+ * @throws 当部署未配置该 modelId，或 Pi 内置 catalog 中没有该 modelId 时抛出错误。
+ */
+export function resolvePiModel(
+  provider: RuntimeProviderPort,
+  modelId: string,
+): Model<Api> {
+  const { endpoint, index } = endpointFor(provider, modelId);
+  return configuredModel(endpoint, index, modelId);
+}
+
+/**
+ * 取出负责指定模型的部署端点密钥。
+ *
+ * Runtime 在创建一次模型执行或压缩上下文前调用它；辅助的标题生成器也在请求 Pi 时使用它。
+ * 调用方应传入与 {@link resolvePiModel} 相同的 provider 和 modelId，并只把返回值用于当前请求。
+ *
+ * 它与模型解析共用 endpointFor，确保密钥和模型总是选择同一个端点，也让未配置的模型在密钥离开部署边界前失败。
+ * 不要另写按协议选密钥的分支，否则同协议的多个端点会拿错凭据。
+ *
+ * @throws 当部署未配置该 modelId 时抛出错误。
+ */
+export function resolvePiApiKey(
+  provider: RuntimeProviderPort,
+  modelId: string,
+): string {
+  return endpointFor(provider, modelId).endpoint.apiKey;
+}
+
+/**
+ * 用当前部署端点完整重建一个已有的 Pi 模型集合。
+ *
+ * PiRuntimeAdapter 激活新运行快照时调用它；需要复用 MutableModels 的调用方也可以调用，并继续使用返回的同一实例。
+ * 该函数会先清空集合，所以调用方必须把传入对象视为由 Runtime 独占管理，不能期待自定义 provider 被保留。
+ *
+ * Pi 当前用 provider.id 在 Map 中注册和路由请求，因此每个部署端点都必须同时注册唯一 provider、对应模型、认证解析器和协议实现。
+ * 先 clearProviders 是为了避免配置更新后旧端点继续可用；所有模型在注册时都会经过 catalog 校验，因此任一未知 modelId 会让整次配置失败。
+ *
+ * @returns 传入并已重建完成的 `models` 实例。
+ * @throws 当任一部署模型不在 Pi 内置 OpenAI、Anthropic catalog 中时抛出错误。
+ */
+export function configurePiModels(
+  models: MutableModels,
+  provider: RuntimeProviderPort,
+): MutableModels {
+  models.clearProviders();
+  provider.endpoints.forEach((endpoint, index) => {
+    models.setProvider(createProvider({
+      id: providerId(endpoint, index),
+      name: endpoint.protocol,
+      baseUrl: endpoint.baseURL,
+      auth: {
+        apiKey: {
+          name: `${endpoint.protocol} API key`,
+          resolve: async () => ({
+            auth: { apiKey: endpoint.apiKey },
+            source: "deployment binding",
+          }),
+        },
+      },
+      models: endpoint.models.map((modelId) =>
+        configuredModel(endpoint, index, modelId),
+      ),
+      api: piApiFor(endpoint.protocol),
+    }));
+  });
+  return models;
+}
+
+/**
+ * 新建一个只包含当前部署端点的 Pi 模型集合。
+ *
+ * 标题生成器和临时 Agent 在需要独立、短生命周期的 Models 实例时调用它；长期 Runtime 通常复用自身集合并调用 {@link configurePiModels}。
+ * 调用方拿到实例后可直接配合 {@link resolvePiModel} 执行请求。
+ *
+ * Pi 的 createModels 当前只创建空集合，这里立即复用 configurePiModels 填充它，保证新建和重配只有一套注册规则。
+ * 不要在此重复 provider 组装，否则两条初始化路径会逐渐产生不同的模型、认证或协议行为。
+ *
+ * @returns 已按部署配置完成的全新 Pi 模型集合。
+ * @throws 当任一部署模型不在 Pi 内置 OpenAI、Anthropic catalog 中时抛出错误。
+ */
+export function createPiModels(
+  provider: RuntimeProviderPort,
+): MutableModels {
+  return configurePiModels(createModels(), provider);
+}