@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.2

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

@@ -1,293 +0,0 @@
-import {
-  PreparedPiTurnAdapter,
-  type CreatePreparedPiTurnOptions,
-} from "./execution";
-export {
-  ContextOverflowError,
-  RetryableModelError,
-  RetryableModelSessionError,
-} from "./execution";
-import {
-  uiUserMessageToPi,
-} from "../message";
-import type { UIMessage } from "ai";
-import { createModels, type MutableModels } from "@earendil-works/pi-ai";
-import { configurePiModels, createPiModels } from "./models";
-export {
-  MODEL_STREAM_STALL_TIMEOUT_MS,
-  modelRequestUrl,
-  readModelStreamStallDetails,
-  withProviderRetry,
-} from "./models";
-import {
-  pinPiRuntime,
-  preparePiRuntime,
-  readPreparedPiRuntime,
-  type PinPiRuntimeOptions,
-  type PinnedPiRuntime,
-  type PreparePiRuntimeOptions,
-  type PreparedPiRuntime,
-} from "./assembly";
-import {
-  decidePiRecovery,
-  recordPiToolMilestone,
-  type PiToolMilestoneInput,
-  PiRuntimeRecoveryAdapter,
-  type PiRecoveryHost,
-  type PiRecoveryInput,
-} from "./recovery";
-import {
-  PiRuntimeTranscript,
-  type PiTranscriptDurability,
-} from "./transcript";
-import { subagentPiToolCandidates } from "../tool/subagent";
-import type {
-  RuntimeSubagentLifecyclePort,
-  RuntimeSubagentPort,
-} from "../../kernel/bindings";
-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 storage: DurableObjectStorage;
-    readonly durability: PiTranscriptDurability;
-    readonly hasActiveTurn: () => boolean;
-  }): PiRuntimeTranscript {
-    return new PiRuntimeTranscript(
-      options.storage,
-      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" },
-    privateContext?: string,
-  ) {
-    return uiUserMessageToPi(input, privateContext);
-  }
-
-  /**
-   * 加载并预检一份可供后续准入使用的 Prepared Runtime。
-   *
-   * @remarks
-   * 调用方：Runtime 的 `initConfig()` 在取得新快照后调用，再用返回的 revision descriptor 判断是否可以切换配置。
-   *
-   * 实现理由：Extension 加载、Tool candidate 汇总和 Tool 编译预检在配置切换前一次完成。
-   * 返回值绑定当前 Adapter 的 owner，不能交给另一个 Adapter 创建 Turn。
-   */
-  prepare(
-    options: PreparePiRuntimeOptions,
-  ): Promise<PreparedPiRuntime> {
-    if (this.managesModels) {
-      createPiModels(options.snapshot.bindings.provider);
-    }
-    return preparePiRuntime(options, this.owner);
-  }
-
-  hasTool(prepared: PreparedPiRuntime, name: string): boolean {
-    return readPreparedPiRuntime(prepared, this.owner).candidates.some(
-      (candidate) => candidate.tool.name === name,
-    );
-  }
-
-  /**
-   * 用已经通过加载检查的快照启用当前部署声明的模型目录。
-   *
-   * @remarks
-   * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
-   *
-   * 实现理由：`prepare()` 已校验所有 endpoint 模型，这里只把同一份部署目录切换到长期 Models 实例。
-   * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
-   */
-  activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
-    if (this.managesModels) {
-      configurePiModels(this.models, snapshot.bindings.provider);
-    }
-  }
-
-  /**
-   * 在接受 Submission 前固定本次执行使用的动态上下文和审批模式。
-   *
-   * @remarks
-   * 调用方：Runtime 的准入流程为每个新 Submission 调用，并把 descriptor 与其哈希一起持久化。
-   *
-   * 实现理由：memory、workspace 和 Extension context 可能随时间变化，所以把准入时的 Turn 字段保存在 descriptor 中。
-   * 不要把 pin 推迟到 Turn 启动后，否则已持久化的 Submission 将失去可验证的执行基线。
-   */
-  pin(options: PinPiRuntimeOptions): Promise<PinnedPiRuntime> {
-    return pinPiRuntime(options, this.owner);
-  }
-
-  /**
-   * 根据持久化 milestone 和一个命令算出恢复时要写什么、下一步做什么。
-   *
-   * @remarks
-   * 调用方：Runtime 和 approval 生命周期在检查恢复状态、处理审批或提交终态时调用。
-   *
-   * 实现理由：该方法只返回 durable mutations 和一个 effect，实际写库与调度仍由 Runtime 完成。
-   * 恢复规划保留在此入口；正常 Tool 写入复用同一命令 reducer，但不重复规划整个 Turn。
-   */
-  decideRecovery(options: PiRecoveryInput) {
-    return decidePiRecovery(options);
-  }
-
-  /** Active execution records only the indexed Tool fact; cold recovery still replays the full log. */
-  recordToolMilestone(options: PiToolMilestoneInput) {
-    return recordPiToolMilestone(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 格式，再建立本 Turn 独享的 Tool governance 与执行状态。
-   * 不要跨 Turn 复用返回对象；abort、steer、assistant ordinal 和 Tool governance 都是单次执行状态。
-   */
-  /**
-   * 为一个已准入的 Submission 生成绑定 durable lifecycle 的 SubAgent Tool 执行器。
-   *
-   * @remarks
-   * 调用方：Runtime 在创建 Turn 前调用一次，并把结果作为 `createTurn` 的 `toolExecutors` 传入。
-   *
-   * 实现理由：SubAgent Tool 的名称、Schema 和执行语义属于 Pi Tool 层，而父子执行身份属于 Submission。两者在这里汇合：Pi 提供工具，
-   * Runtime 提供本次 Submission 的 lifecycle 端口，因此 Runtime 不需要认识 Tool 模块本身。
-   * 没有可用 SubAgent 类型时返回 `undefined`，让 Turn 继续使用装配期的无 lifecycle 执行器。
-   */
-  subagentToolExecutors(
-    subagents: RuntimeSubagentPort,
-    enabledSubagents: readonly string[],
-    lifecycle: RuntimeSubagentLifecyclePort,
-  ): CreatePreparedPiTurnOptions["toolExecutors"] {
-    const entries = subagentPiToolCandidates(
-      subagents,
-      enabledSubagents,
-      lifecycle,
-    ).flatMap((candidate) =>
-      candidate.tool.execute
-        ? [[candidate.tool.name, candidate.tool.execute] as const]
-        : []
-    );
-    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-  }
-
-  createTurn(
-    options: CreatePreparedPiTurnOptions,
-  ): PreparedPiTurnAdapter {
-    return new PreparedPiTurnAdapter(options, {
-      owner: this.owner,
-      models: this.models,
-    });
-  }
-}
-
-export type {
-  RequestedCapability,
-  UIChatRequestBody,
-} from "../message";
-export type { PiToolApproval } from "../turn";
-export type {
-  PiToolInteraction,
-  PiToolInteractionCancelReason,
-} from "../turn";
-export type {
-  CreatePreparedPiTurnOptions,
-  PiCanonicalUserInput,
-  PiStoredToolSettlement,
-  PiToolSettlement,
-  PiToolInputRecord,
-  PiTurnRunResult,
-  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";