@springbrand/agent-runtime 0.1.0

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

@@ -0,0 +1,552 @@
+import type {
+  RuntimeBindings,
+  RuntimePlatformPort,
+} from "../../kernel/bindings";
+import type { RuntimeDegradation } from "../../kernel/degradation";
+import type {
+  RuntimeExtensionPermissions,
+} from "../../kernel/extensions";
+import type { RuntimeProfile } from "../../kernel/profile";
+import type { ExecutionLevel } from "../../lib/execution-level";
+import type { RuntimeSnapshot } from "../../plugins";
+import type { PiRuntimeAssembly } from "../assembly";
+import {
+  assemblePiSystemContext,
+  assemblePiExtensions,
+  loadPiExtension,
+  type PiExtensionAssembly,
+  type PiExtensionContextContribution,
+  type PiLoadedExtension,
+} from "../assembly";
+import {
+  compilePiTools,
+  createPiMcpToolCandidates,
+  listExtensionsPiToolCandidate,
+  type PiMcpHost,
+  type PiToolCandidate,
+} from "../tool";
+
+/**
+ * 本文件负责准备 Pi 的扩展与工具，并为每次提交固定可恢复的运行描述。
+ *
+ * @remarks
+ * 核心术语见本目录入口 `./index.ts`，这里不重复定义。
+ */
+
+// #region 装配契约
+
+// 只保留加载扩展和收集工具所需的快照字段。
+// preparePiAssembly 在 Runtime 配置阶段接收这个收窄后的视图。
+// 边界保持精简，避免装配代码依赖无关的运行状态。
+interface PiAssemblySnapshot {
+  readonly pi: Pick<
+    PiRuntimeAssembly,
+    "extensions" | "toolCandidates"
+  >;
+  readonly profile: Pick<
+    RuntimeProfile,
+    "denyPolicy" | "enabledExtensions" | "mcpServers"
+  >;
+  readonly bindings: {
+    readonly platform: Pick<RuntimePlatformPort, "loader">;
+    readonly workspace?: RuntimeBindings["workspace"];
+  };
+}
+
+// 汇集装配扩展和 MCP 工具所需的输入。
+// preparePiRuntime 在配置期间把这些值交给 preparePiAssembly。
+// Host 绑定由 Worker 持有，所以创建函数不能下沉到本模块。
+interface PreparePiAssemblyOptions {
+  readonly snapshot: PiAssemblySnapshot;
+  readonly mcpHost: PiMcpHost;
+  // 为一个扩展生成带权限参数的 Host Fetcher。
+  // loadPiExtension 在扩展需要 Host 能力时调用它。
+  // Worker 掌握真实绑定，装配层只保存这个窄函数，不能自行扩大权限。
+  readonly createExtensionHostBinding: (
+    permissions: RuntimeExtensionPermissions,
+    ownContextLabels: readonly string[],
+  ) => Fetcher;
+}
+
+// 暴露后续准备和固定阶段会读取的扩展装配结果。
+// preparePiRuntime 读取工具与降级，pinPiRuntime 读取上下文贡献。
+// 访问器直接代理扩展装配，避免维护会漂移的副本。
+interface PreparedPiAssembly {
+  readonly loaded: readonly PiLoadedExtension[];
+  readonly context: readonly PiExtensionContextContribution[];
+  readonly degradations: PiExtensionAssembly["degradations"];
+  // 生成当前可供 Pi 编译的完整工具候选列表。
+  // preparePiAssembly 用它预检，preparePiRuntime 再读取并冻结最终列表。
+  // MCP 就绪状态由 Host 提供，因此这里不能只拼接初始化时的静态数组。
+  toolCandidates(): PiToolCandidate[];
+}
+
+/**
+ * 提供准备 Pi 所需的已校验 Runtime 快照和 Host 端口。
+ *
+ * @remarks
+ * `PiRuntimeAdapter.prepare` 在加载 Runtime 配置时传入它。
+ *
+ * 扩展绑定仍由 Host 创建，因为 Cloudflare 绑定属于 Worker 的能力边界。
+ *
+ * @see https://developers.cloudflare.com/workers/runtime-apis/bindings/
+ */
+export interface PreparePiRuntimeOptions {
+  readonly snapshot: RuntimeSnapshot;
+  readonly mcpHost: PiMcpHost;
+  /**
+   * 为一个扩展创建受限的 Host 绑定。
+   *
+   * @remarks
+   * Runtime 配置只会在加载需要 Host 能力的已启用扩展时调用它。
+   *
+   * 权限和自有上下文标签必须显式传入，Host 才能执行同一条授权边界。
+   */
+  readonly createExtensionHostBinding: (
+    permissions: RuntimeExtensionPermissions,
+    ownContextLabels: readonly string[],
+  ) => Fetcher;
+}
+
+/**
+ * 表示已经准备好、但尚未固定到某次提交的 Pi 配置。
+ *
+ * @remarks
+ * Runtime 在配置完成后保存这个句柄，并在提交准入或创建 Turn 时传回。
+ *
+ * 公开形状只给出版本描述和加载降级，调用方不会直接拿到可变的装配状态。
+ */
+export interface PreparedPiRuntime {
+  readonly revisionDescriptor: string;
+  readonly degradations: readonly RuntimeDegradation[];
+}
+
+/**
+ * 提供把一次提交固定到当前 Runtime 所需的值。
+ *
+ * @remarks
+ * Runtime 在写入提交前的准入阶段把它交给 `PiRuntimeAdapter.pin`。
+ *
+ * 扩展没有可读上下文时不需要读取函数，所以该端口保持可选。
+ */
+export interface PinPiRuntimeOptions {
+  readonly prepared: PreparedPiRuntime;
+  readonly baseRevision: string;
+  /**
+   * 读取一个扩展要写入固定系统提示词的上下文。
+   *
+   * @remarks
+   * pinPiRuntime 在准入阶段为已加载扩展声明的上下文贡献调用它。
+   *
+   * 本模块不持有扩展上下文存储，所以读取端口必须留在 Host。
+   */
+  readonly readExtensionContext?: (
+    contribution: PiExtensionContextContribution,
+  ) => Promise<string | null>;
+}
+
+/**
+ * 返回已经固定到一次提交的描述和上下文降级。
+ *
+ * @remarks
+ * Runtime 在准入时持久化描述，并在创建 Turn 时传回。
+ *
+ * 固定这些值可让恢复继续使用当时已经准入的配置。
+ */
+export interface PinnedPiRuntime {
+  readonly descriptor: string;
+  readonly degradations: readonly RuntimeDegradation[];
+}
+
+/**
+ * 描述一条已存提交可以恢复到哪份 Pi 配置。
+ *
+ * @remarks
+ * `PreparedPiTurnAdapter` 在重建 Turn 前读取这个 JSON 结构。
+ *
+ * 版本号和基础版本校验用于阻止恢复落到不兼容的 Runtime 状态。
+ */
+export interface PinnedPiRuntimeDescriptor {
+  readonly version: 1;
+  readonly baseRevision: string;
+  readonly model: string;
+  readonly provider: string;
+  readonly thinking: RuntimeSnapshot["pi"]["thinkingLevel"];
+  readonly systemPrompt: string;
+  readonly executionLevel: ExecutionLevel;
+  readonly deny: readonly string[];
+  readonly tools: readonly ReturnType<typeof describeTools>[number][];
+  readonly [key: string]: unknown;
+}
+
+/**
+ * 保存创建 Pi Turn 所需的内部准备结果。
+ *
+ * @remarks
+ * readPreparedPiRuntime 只向持有原适配器身份标记的代码返回它。
+ *
+ * 工具候选与快照放在一起，确保后续 Turn 使用准备阶段最终冻结的同一份列表。
+ */
+export interface PreparedPiRuntimeState {
+  readonly snapshot: RuntimeSnapshot;
+  readonly assembly: PreparedPiAssembly;
+  readonly candidates: readonly PiToolCandidate[];
+}
+
+// #endregion
+
+// #region 版本描述与准备句柄
+
+const IDEMPOTENT_TOOL_NAMES = new Set([
+  "activate_skill",
+  "browser_extract",
+  "browser_links",
+  "browser_markdown",
+  "browser_scrape",
+  "bind_resource",
+  "find",
+  "get_time",
+  "grep",
+  "list",
+  "list_resources",
+  "list_extensions",
+  "list_schedules",
+  "read",
+  "read_skill_resource",
+  "sandbox_process_logs",
+  "web_search",
+  "unbind_resource",
+]);
+
+/**
+ * 判断工具在执行结果不确定时能否安全重试。
+ *
+ * @remarks
+ * Turn 执行在记录第一次尝试前调用它，恢复流程随后使用这条持久化结论。
+ *
+ * 白名单故意保持保守，未知工具和新工具都会默认按不可重复执行处理。
+ */
+export function piToolRetryPolicy(
+  candidate: PiToolCandidate,
+): "idempotent" | "non-idempotent" {
+  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name)
+    ? "idempotent"
+    : "non-idempotent";
+}
+
+// 把工具候选整理成版本描述里要保存的稳定字段。
+// describeRuntime 在准备 Runtime 配置时调用它。
+// 按名称排序可避免仅因候选注册顺序变化就产生新版本。
+function describeTools(candidates: readonly PiToolCandidate[]) {
+  return candidates
+    .map((candidate) => ({
+      name: candidate.tool.name,
+      owner: candidate.owner,
+      label: candidate.tool.label,
+      description:
+        candidate.tool.description ?? candidate.tool.label,
+      parameters: candidate.tool.parameters,
+      requiredExecutionLevel: candidate.requiredExecutionLevel,
+      ...(candidate.source ? { source: candidate.source } : {}),
+      retry: piToolRetryPolicy(candidate),
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+// 把本模块认定会影响版本的准备结果序列化出来。
+// preparePiRuntime 创建一次，Runtime 接受快照前再对结果求哈希。
+// 集合排序保证等价输入稳定；增删字段会改变版本哈希和恢复兼容性。
+function describeRuntime(
+  snapshot: RuntimeSnapshot,
+  candidates: readonly PiToolCandidate[],
+  loadedExtensions: readonly PiLoadedExtension[],
+): string {
+  return JSON.stringify({
+    version: 1,
+    model: snapshot.pi.model.id,
+    provider: snapshot.pi.model.provider,
+    thinking: snapshot.pi.thinkingLevel,
+    systemPrompt: snapshot.pi.systemPrompt,
+    executionLevel: snapshot.profile.executionLevel,
+    deny: [...(snapshot.profile.denyPolicy?.deny ?? [])].sort(),
+    memory: { ...snapshot.profile.memory },
+    tools: describeTools(candidates),
+    skills: snapshot.bindings.skills.sources
+      .map((binding) => ({
+        name: binding.name,
+        description: binding.description,
+        script: {
+          network: binding.script.network,
+          workspace: binding.script.workspace,
+          tools: [...binding.script.tools].sort(),
+        },
+      }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+    extensions: loadedExtensions
+      .map((extension) => ({
+        name: extension.name,
+        version: extension.version,
+      }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+    subagents: [...snapshot.profile.enabledSubagents].sort(),
+    mcpServers: snapshot.profile.mcpServers
+      .map((server) => ({ name: server.name, url: server.url }))
+      .sort((left, right) => left.name.localeCompare(right.name)),
+  });
+}
+
+class PreparedRuntime implements PreparedPiRuntime {
+  // 把公开版本数据与受身份保护的内部准备状态放在同一个句柄里。
+  // 只有 preparePiRuntime 会构造它，并在返回前冻结实例。
+  // owner 使用对象身份区分 PiRuntimeAdapter，避免不同适配器的句柄被混用。
+  constructor(
+    readonly revisionDescriptor: string,
+    readonly degradations: readonly RuntimeDegradation[],
+    private readonly owner: object,
+    private readonly state: PreparedPiRuntimeState,
+  ) {}
+
+  // 在调用方证明适配器身份后返回内部准备状态。
+  // readPreparedPiRuntime 在固定配置或创建 Turn 前调用它。
+  // 公开接口没有可信的来源字段，所以这里必须比较对象身份。
+  read(owner: object): PreparedPiRuntimeState {
+    if (owner !== this.owner) {
+      throw new Error(
+        "Prepared Pi Runtime belongs to another PiRuntimeAdapter",
+      );
+    }
+    return this.state;
+  }
+}
+
+/**
+ * 为创建它的 PiRuntimeAdapter 打开准备句柄。
+ *
+ * @remarks
+ * 固定配置和创建 Turn 都会先调用它，再读取快照、装配结果或工具候选。
+ *
+ * 具体类检查与 owner 检查一起拒绝伪造句柄和跨适配器复用。
+ */
+export function readPreparedPiRuntime(
+  prepared: PreparedPiRuntime,
+  owner: object,
+): PreparedPiRuntimeState {
+  if (!(prepared instanceof PreparedRuntime)) {
+    throw new Error("Prepared Pi Runtime handle is invalid");
+  }
+  return prepared.read(owner);
+}
+
+/**
+ * 校验已存的固定描述是否仍与当前准备好的 Runtime 兼容。
+ *
+ * @remarks
+ * `PreparedPiTurnAdapter` 在新建或恢复 Pi Turn 前调用它。
+ *
+ * 只有固定阶段写入的提示词允许不同，其余准备字段及基础版本必须匹配。
+ */
+export function readPinnedPiRuntime(
+  prepared: PreparedPiRuntime,
+  owner: object,
+  descriptorBody: string,
+  baseRevision: string,
+): {
+  readonly state: PreparedPiRuntimeState;
+  readonly descriptor: PinnedPiRuntimeDescriptor;
+} {
+  const state = readPreparedPiRuntime(prepared, owner);
+  let value: unknown;
+  try {
+    value = JSON.parse(descriptorBody);
+  } catch {
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error("Pinned Runtime assembly descriptor is invalid");
+  }
+  const descriptor = value as PinnedPiRuntimeDescriptor;
+  const expected = JSON.parse(prepared.revisionDescriptor) as Record<
+    string,
+    unknown
+  >;
+  const actual = descriptor as unknown as Record<string, unknown>;
+  const incompatible = Object.keys(expected).some((key) =>
+    key !== "systemPrompt" &&
+    JSON.stringify(actual[key]) !== JSON.stringify(expected[key])
+  );
+  if (
+    descriptor.version !== 1 ||
+    descriptor.baseRevision !== baseRevision ||
+    typeof descriptor.systemPrompt !== "string" ||
+    incompatible
+  ) {
+    throw new Error(
+      "Pinned Runtime revision is unavailable for Pi recovery",
+    );
+  }
+  return { state, descriptor };
+}
+
+// #endregion
+
+// #region 扩展与工具装配
+
+class PreparedAssembly implements PreparedPiAssembly {
+  // 把准备快照、已加载扩展和 MCP Host 放在一个装配对象里。
+  // preparePiAssembly 在扩展加载完成后构造它。
+  // 这里保留源对象而不复制列表，让每个访问器都读取同一份结果。
+  constructor(
+    private readonly snapshot: PiAssemblySnapshot,
+    private readonly extensions: PiExtensionAssembly,
+    private readonly mcpHost: PiMcpHost,
+  ) {}
+
+  // 返回成功加载的扩展。
+  // preparePiRuntime 在生成版本描述时读取这个列表。
+  // 直接代理扩展装配，避免维护可能漂移的第二份列表。
+  get loaded(): readonly PiLoadedExtension[] {
+    return this.extensions.loaded;
+  }
+
+  // 返回已加载扩展声明的上下文贡献。
+  // pinPiRuntime 在提交准入时把它们交给系统上下文装配器。
+  // 上下文值在固定阶段才读取，所以不能提前写死在准备阶段的提示词中。
+  get context(): readonly PiExtensionContextContribution[] {
+    return this.extensions.context;
+  }
+
+  // 返回准备阶段被降级处理、而不是继续抛出的扩展失败。
+  // preparePiRuntime 把它们与快照降级合并，用于报告 Runtime 加载结果。
+  // 直接代理可保留扩展装配器生成的原始降级记录。
+  get degradations(): PiExtensionAssembly["degradations"] {
+    return this.extensions.degradations;
+  }
+
+  // 汇总内置、扩展列表、扩展和当前已就绪的 MCP 工具。
+  // 准备流程先调用它做校验，再冻结一份列表供后续 Turn 使用。
+  // 每次重新生成是因为 MCP 候选来自 Host 当前的连接状态。
+  toolCandidates(): PiToolCandidate[] {
+    return [
+      ...this.snapshot.pi.toolCandidates,
+      ...this.extensions.candidates,
+      listExtensionsPiToolCandidate(this.extensions.loaded),
+      ...createPiMcpToolCandidates(
+        this.mcpHost,
+        this.snapshot.profile.mcpServers,
+      ),
+    ];
+  }
+}
+
+// 加载已启用扩展，并确认汇总后的工具可以正常编译。
+// preparePiRuntime 为每份待配置的 Runtime 快照调用它一次。
+// 工作区能力在共享加载边界校验，单个扩展加载失败则保留为降级结果。
+async function preparePiAssembly(
+  options: PreparePiAssemblyOptions,
+): Promise<PreparedPiAssembly> {
+  const { snapshot } = options;
+  const extensionNames = new Set(
+    snapshot.pi.extensions.map((extension) =>
+      extension.manifest.name.trim()
+    ),
+  );
+  const extensions = await assemblePiExtensions({
+    extensions: snapshot.pi.extensions,
+    published: extensionNames,
+    enabled: new Set(snapshot.profile.enabledExtensions),
+    authorized: extensionNames,
+    load: async (extension) => {
+      const workspacePermission =
+        extension.manifest.permissions?.workspace ?? "none";
+      if (workspacePermission !== "none" && !snapshot.bindings.workspace) {
+        throw new Error(
+          "Extension workspace permission requires a Runtime Workspace",
+        );
+      }
+      return loadPiExtension(extension, {
+        loader: snapshot.bindings.platform.loader,
+        createHostBinding: options.createExtensionHostBinding,
+      });
+    },
+  });
+  const prepared = new PreparedAssembly(
+    snapshot,
+    extensions,
+    options.mcpHost,
+  );
+  // 待确认：MCP 就绪状态可能在下一次 toolCandidates() 前改变，
+  // 因而最终冻结的候选可能与这里校验的集合不同。
+  compilePiTools(prepared.toolCandidates(), {
+    deny: snapshot.profile.denyPolicy?.deny,
+    settle: () => undefined,
+  });
+  return prepared;
+}
+
+// #endregion
+
+// #region Runtime 准备与提交固定
+
+/**
+ * 为一份已校验的 Runtime 快照准备扩展和工具状态。
+ *
+ * @remarks
+ * `PiRuntimeAdapter.prepare` 在 Runtime 配置阶段、快照生效前调用它。
+ *
+ * 冻结句柄会保存最终候选列表，对外只提供版本描述和降级结果。
+ */
+export async function preparePiRuntime(
+  options: PreparePiRuntimeOptions,
+  owner: object,
+): Promise<PreparedPiRuntime> {
+  const assembly = await preparePiAssembly(options);
+  const candidates = assembly.toolCandidates();
+  return Object.freeze(new PreparedRuntime(
+    describeRuntime(options.snapshot, candidates, assembly.loaded),
+    Object.freeze([
+      ...options.snapshot.degradations,
+      ...assembly.degradations,
+    ]),
+    owner,
+    Object.freeze({
+      snapshot: options.snapshot,
+      assembly,
+      candidates: Object.freeze([...candidates]),
+    }),
+  ));
+}
+
+/**
+ * 把请求时的上下文和执行档位固定到一次提交的描述中。
+ *
+ * @remarks
+ * Runtime 在持久化提交并启动 Turn 前的准入阶段调用它。
+ *
+ * 此时重建上下文可避免把动态记忆和扩展上下文写进 Pi 消息，同时让恢复继续使用已准入的结果。
+ */
+export async function pinPiRuntime(
+  options: PinPiRuntimeOptions,
+  owner: object,
+): Promise<PinnedPiRuntime> {
+  const state = readPreparedPiRuntime(options.prepared, owner);
+  const { snapshot, assembly } = state;
+  const context = await assemblePiSystemContext({
+    baseSystemPrompt: snapshot.pi.systemPrompt,
+    memory: snapshot.profile.memory,
+    memoryPort: snapshot.bindings.memory,
+    workspace: snapshot.bindings.workspace,
+    skills: snapshot.bindings.skills.sources,
+    extensionContexts: assembly.context,
+    readExtensionContext: options.readExtensionContext,
+  });
+  return Object.freeze({
+    descriptor: JSON.stringify({
+      ...JSON.parse(options.prepared.revisionDescriptor),
+      systemPrompt: context.systemPrompt,
+      baseRevision: options.baseRevision,
+    }),
+    degradations: context.degradations,
+  });
+}
+
+// #endregion