@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.10

package/src/plugins.ts

@@ -1,1033 +0,0 @@
-import type { SkillSource } from "agents/skills";
-import type {
-  RuntimeMemoryPort,
-  RuntimePlatformPort,
-  RuntimeProviderPort,
-  RuntimeSandboxPort,
-  RuntimeSchedulePort,
-  RuntimeSubagentPort,
-  RuntimeTurnEventsPort,
-  RuntimeBindings,
-  RuntimeSkillScriptPolicy,
-  WorkspacePort,
-} from "./kernel/bindings";
-import {
-  freezeRuntimeProfile,
-  type RuntimeDenyPolicy,
-  type RuntimeMcpServer,
-  type RuntimeMemoryProfile,
-  type RuntimeProfile,
-  type ThinkingEffort,
-} from "./kernel/profile";
-import type { RuntimeExtensionConfig } from "./kernel/extensions";
-import type { RuntimeDegradation } from "./kernel/degradation";
-import {
-  EXECUTION_LEVELS,
-  type ExecutionLevel,
-} from "./lib/execution-level";
-import {
-  createPiRuntimeAssembly,
-  type PiRuntimeAssembly,
-} from "./pi/assembly/snapshot";
-import type { PiToolCandidate } from "./pi/tool/compiler";
-import { basePiToolCandidates } from "./pi/tool/base";
-import { createWebSearch } from "./pi/tool/web-search";
-import { resolvePiModel } from "./pi/runtime-adapter/models";
-
-/**
- * 本文件实现 Plugin 的准备、贡献、校验和原子候选装配。
- *
- * @remarks
- * 核心术语见包入口 `index.ts`，这里不重复定义。
- */
-
-// #region Plugin 公开契约
-
-/**
- * 标明一个 Plugin 负责哪一类能力。
- *
- * @remarks
- * 应用创建 Plugin 时必须选择其中一个值。
- *
- * Runtime 用它拒绝重复能力并确定贡献顺序，所以不要把它当作自由文本。
- */
-export type PluginKind =
-  | "scope"
-  | "profile"
-  | "provider"
-  | "platform"
-  | "workspace"
-  | "sandbox"
-  | "memory"
-  | "tool"
-  | "skill"
-  | "connector"
-  | "extension"
-  | "schedule"
-  | "subagent"
-  | "turn-events";
-
-export type { RuntimeDegradation } from "./kernel/degradation";
-
-/**
- * 把 loader 读取到的值和本次降级信息一起返回。
- *
- * @remarks
- * `definePlugin` 在准备阶段读取它。
- *
- * 值与诊断一起返回，可以避免 loader 直接修改 Runtime。
- */
-export interface PluginLoadResult<T> {
-  readonly value: T;
-  readonly degradations: readonly RuntimeDegradation[];
-}
-
-/**
- * 表示一个尚未准备的 Runtime Plugin。
- *
- * @remarks
- * 应用把它放进 `AgentConfig.plugins`。
- *
- * Runtime 只调用 `prepare`，不会接触 Plugin 捕获的业务依赖。
- */
-export interface AgentPlugin {
-  readonly kind: PluginKind;
-  /**
-   * 读取这个 Plugin 的配置，并生成一个还未贡献的准备结果。
-   *
-   * @remarks
-   * Runtime 在生成候选结果时调用，应用只需把 Plugin 放进 `AgentConfig`。
-   *
-   * 读取与贡献分开，是为了并行读取外部数据后再按稳定顺序合并。
-   */
-  prepare(): Promise<PreparedPlugin>;
-}
-
-/**
- * 表示 loader 已完成、但还没有写入候选结果的 Plugin。
- *
- * @remarks
- * Runtime 按固定 kind 顺序调用 `contribute`。
- *
- * 准备和贡献分开，才能并行读取数据又保持确定的合并顺序。
- */
-export interface PreparedPlugin {
-  readonly kind: PluginKind;
-  readonly degradations: readonly RuntimeDegradation[];
-  /**
-   * 把已读取的值写进 Runtime 提供的受限候选上下文。
-   *
-   * @remarks
-   * Runtime 在全部 loader 完成后，按 `PluginKind` 固定顺序调用。
-   *
-   * 这一阶段只能使用受限上下文，不能直接安装 Snapshot。
-   */
-  contribute(
-    ctx: RuntimeContributionContext,
-  ): void | Promise<void>;
-}
-
-/**
- * 描述一个 Plugin 应该怎样读取数据并贡献能力。
- *
- * @remarks
- * 应用把该对象传给 `definePlugin`。
- *
- * `loader` 负责读取，`contribute` 负责组装，二者不要互相越权。
- */
-export interface AgentPluginSpec<T> {
-  readonly kind: PluginKind;
-  /**
-   * 在准备阶段读取本 Plugin 所需的数据。
-   *
-   * @remarks
-   * `definePlugin` 包装出的 `prepare` 会在 Runtime 装配开始时调用它。
-   *
-   * 它只返回数据和降级信息，不应直接修改正在运行的 Runtime。
-   */
-  loader(): Promise<PluginLoadResult<T>>;
-  /**
-   * 在贡献阶段把已读取的数据交给 Runtime。
-   *
-   * @remarks
-   * Runtime 准备完所有 Plugin 后，通过 `PreparedPlugin.contribute` 调用它。
-   *
-   * 它必须通过 `RuntimeContributionContext` 写入候选结果，以便统一检查重复与跨能力约束。
-   */
-  contribute(
-    loaded: T,
-    ctx: RuntimeContributionContext,
-  ): void | Promise<void>;
-}
-
-/**
- * 汇总一次 Runtime 装配要使用的全部 Plugin。
- *
- * @remarks
- * `RuntimeAgentDefinition.createConfig` 在首次加载或显式重载时返回它。
- *
- * 它只保存可信函数对象，不用于持久化或跨进程序列化。
- */
-export interface AgentConfig {
-  readonly plugins: readonly AgentPlugin[];
-}
-
-/**
- * 提供 Runtime 核心运行参数。
- *
- * @remarks
- * `profile` Plugin 在贡献阶段调用 `configureProfile` 时传入。
- *
- * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
- */
-export interface RuntimeProfileContribution {
-  readonly model: string;
-  readonly thinking: ThinkingEffort;
-  readonly systemPrompt?: string;
-  readonly executionLevel: ExecutionLevel;
-}
-
-/**
- * 限定 Plugin 可以写入候选 Runtime 的内容。
- *
- * @remarks
- * Plugin 的 `contribute` 回调使用这些方法。
- *
- * Runtime 只暴露绑定和增量添加操作，避免 Plugin 取得 Builder 的可变引用。
- */
-export interface RuntimeContributionContext {
-  /**
-   * 写入唯一的模型、提示词、审批和权限配置。
-   *
-   * @remarks
-   * profile Plugin 在贡献阶段调用一次。
-   *
-   * Runtime 拒绝第二份配置，避免候选结果同时有两个运行参数来源。
-   */
-  configureProfile(profile: RuntimeProfileContribution): void;
-  /**
-   * 写入部署提供的模型端点与凭据。
-   *
-   * @remarks
-   * provider Plugin 在贡献阶段调用一次。
-   *
-   * Runtime 保留单一 Provider 选择，并在生成候选结果时检查默认模型、端点和凭据。
-   */
-  bindProvider(provider: RuntimeProviderPort): void;
-  /**
-   * 写入唯一的 Cloudflare 平台端口。
-   *
-   * @remarks
-   * platform Plugin 在贡献阶段调用一次。
-   *
-   * Loader 和出口函数作为一个整体绑定，不允许从多个平台配置静默拼接。
-   */
-  bindPlatform(platform: RuntimePlatformPort): void;
-  /**
-   * 写入可选的工作区端口。
-   *
-   * @remarks
-   * workspace Plugin 在工作区可用时调用一次。
-   *
-   * Runtime 只允许一个当前工作区；未绑定时依赖它的能力必须降级或在校验时失败。
-   */
-  bindWorkspace(workspace: WorkspacePort): void;
-  /**
-   * 写入可选的 Linux Sandbox 执行端口。
-   *
-   * @remarks
-   * sandbox Plugin 在部署和 Agent 配置都启用该能力时调用。
-   *
-   * Sandbox 必须和持久工作区成对出现，这个跨能力约束在提交前统一校验。
-   */
-  bindSandbox(
-    sandbox: RuntimeSandboxPort,
-  ): void;
-  /**
-   * 写入内存参数，并在启用时提供内存读写端口。
-   *
-   * @remarks
-   * memory Plugin 在贡献阶段调用一次，即使功能关闭也要传入 profile。
-   *
-   * 独立记录“已配置”状态，才能区分未贡献与明确关闭。
-   */
-  configureMemory(
-    profile: RuntimeMemoryProfile,
-    port?: RuntimeMemoryPort,
-  ): void;
-  /**
-   * 添加一个已经过装配期授权、并保留审批元数据的 Pi Tool 候选。
-   *
-   * @remarks
-   * tool Plugin 为当前 Agent 真正可见的 Tool 逐个调用。
-   *
-   * Runtime 在装配期拒绝空名和重名，避免 Pi 开始 Turn 后才发现能力冲突。
-   */
-  addPiTool(candidate: PiToolCandidate): void;
-  /**
-   * 写入唯一的 Turn 期拒绝清单。
-   *
-   * @remarks
-   * tool Plugin 在完成实际可见能力挑选后调用一次。
-   *
-   * 能力的有无在注入前已经决定，这里只保留 Turn 期仍需执行的拒绝规则。
-   */
-  configureDenyPolicy(
-    policy?: RuntimeDenyPolicy,
-  ): void;
-  /**
-   * 添加一个已授权 Skill 的持久化 catalog、内容来源及脚本权限。
-   *
-   * @remarks
-   * skill Plugin 为已解析的外部 Skill 逐个调用。
-   *
-   * catalog、来源与权限一起登记，同时和其他 Skill 来源共享同一名称空间。
-   */
-  addSkillSource(
-    name: string,
-    description: string,
-    source: SkillSource,
-    script?: Partial<RuntimeSkillScriptPolicy>,
-  ): void;
-  /**
-   * 按名称添加一个 MCP Connector。
-   *
-   * @remarks
-   * connector Plugin 为当前 Agent 已授权的连接逐个调用。
-   *
-   * Runtime 在装配期统一规范化名称和 URL，并拒绝空值或重名。
-   */
-  addConnector(server: RuntimeMcpServer): void;
-  /**
-   * 按名称添加一个已验证的 Runtime Extension。
-   *
-   * @remarks
-   * extension Plugin 为当前部署的扩展逐个调用。
-   *
-   * 登记名必须和 manifest 名一致，否则配置选择可能指向错误的执行对象。
-   */
-  addExtension(name: string, extension: RuntimeExtensionConfig): void;
-  /**
-   * 写入唯一的定时任务端口。
-   *
-   * @remarks
-   * schedule Plugin 在贡献阶段调用一次。
-   *
-   * 本端口只描述回到当前 Session 的调用边界；Cloudflare 的实际唤醒和回调路由 Host 与 Agents SDK 管理。
-   */
-  bindSchedule(schedule: RuntimeSchedulePort): void;
-  /**
-   * 标记一个 Subagent 类型在本次 Runtime 中启用。
-   *
-   * @remarks
-   * subagent Plugin 通过部署检查后为每种可用类型调用。
-   *
-   * Runtime 只把已启用名称交给 Pi，并在提交前确认执行端口存在。
-   */
-  enableSubagent(name: string): void;
-  /**
-   * 写入唯一的 Subagent 执行端口。
-   *
-   * @remarks
-   * subagent Plugin 在至少启用一种类型时调用一次。
-   *
-   * 类型选择和实际执行能力分开登记，缺少端口时由统一校验拒绝候选结果。
-   */
-  bindSubagents(subagents: RuntimeSubagentPort): void;
-  /**
-   * 写入唯一的 Turn 完成事件端口。
-   *
-   * @remarks
-   * turn-events Plugin 在贡献阶段调用一次。
-   *
-   * 单一端口保证应用投影只有一个顺序来源，避免同一完成事件被重复写入。
-   */
-  bindTurnEvents(turnEvents: RuntimeTurnEventsPort): void;
-  /**
-   * 添加一个最终提交前必须通过的异步检查。
-   *
-   * @remarks
-   * 会在 loader 执行期间过期的 scope Plugin 在贡献时添加它。
-   *
-   * Runtime 延迟到全部候选内容就绪后再运行 guard，防止旧业务条件被提交。
-   */
-  addCommitGuard(guard: () => Promise<void>): void;
-  /**
-   * 记录一项不阻止启动的能力降级。
-   *
-   * @remarks
-   * Runtime 在贡献每个 PreparedPlugin 前，把它的降级信息逐项写入。
-   *
-   * 记录时会复制并冻结顶层对象，避免已提交诊断被 Plugin 后续改写。
-   */
-  reportDegradation(degradation: RuntimeDegradation): void;
-}
-
-/**
- * 把 loader 与贡献回调包装成 Runtime 可准备的 Plugin。
- *
- * @remarks
- * 应用在创建 `AgentConfig` 时调用它，不需要手写 `prepare`。
- *
- * 包装层会冻结准备结果，避免读取完成后被调用方改写。
- */
-export function definePlugin<T>(
-  spec: AgentPluginSpec<T>,
-): AgentPlugin {
-  return Object.freeze({
-    kind: spec.kind,
-
-    // 作用：读取本 Plugin 的数据，并把结果变成不可变的准备对象。
-    // 调用：Runtime 在候选装配开始时调用，应用不应直接调用。
-    // 原因：此处只准备数据，不贡献能力，才能安全地与其他 loader 并行。
-    async prepare(): Promise<PreparedPlugin> {
-      const loaded = await spec.loader();
-      const degradations = Object.freeze(
-        loaded.degradations.map((degradation) =>
-          Object.freeze({ ...degradation }),
-        ),
-      );
-
-      return Object.freeze({
-        kind: spec.kind,
-        degradations,
-        contribute: (ctx: RuntimeContributionContext) =>
-          spec.contribute(loaded.value, ctx),
-      });
-    },
-  });
-}
-
-// #endregion
-
-// #region 内部候选契约与装配顺序
-
-/**
- * 保存一次已经完成校验、可供 Kernel 使用的 Runtime 结果。
- *
- * @internal
- */
-export interface RuntimeSnapshot {
-  readonly profile: RuntimeProfile;
-  readonly bindings: RuntimeBindings;
-  readonly pi: PiRuntimeAssembly;
-  readonly degradations: readonly RuntimeDegradation[];
-}
-
-/**
- * 保存待提交的 Snapshot 和提交前检查。
- *
- * @internal
- */
-export interface RuntimeCandidate {
-  readonly snapshot: RuntimeSnapshot;
-  readonly commitGuards: readonly (() => Promise<void>)[];
-}
-
-const PLUGIN_ORDER: readonly PluginKind[] = Object.freeze([
-  "scope",
-  "profile",
-  "provider",
-  "platform",
-  "workspace",
-  "sandbox",
-  "memory",
-  "tool",
-  "skill",
-  "connector",
-  "extension",
-  "schedule",
-  "subagent",
-  "turn-events",
-]);
-
-const REQUIRED_PLUGIN_KINDS: readonly PluginKind[] = Object.freeze([
-  "profile",
-  "provider",
-  "platform",
-]);
-
-const DISABLED_MEMORY: RuntimeMemoryProfile = Object.freeze({
-  enabled: false,
-  memoryTokens: 2_000,
-  preferencesTokens: 500,
-  compactAfterTokens: 100_000,
-});
-
-// 作用：把外部名称整理成非空字符串。
-// 调用：Builder 在添加具名 Tool、Skill、Connector 或 Extension 时调用。
-// 原因：统一在入口拒绝空名称，后续 Map 和 Set 才有稳定键值。
-function requiredName(value: string, label: string): string {
-  const name = value.trim();
-  if (!name) throw new Error(`${label} name must not be empty`);
-  return name;
-}
-
-// 作用：检查内存预算都是可用的非负数字。
-// 调用：Builder 在生成候选 Snapshot 前调用。
-// 原因：把检查放在提交前，失败时旧 Snapshot 仍保持不变。
-function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
-  for (const [name, value] of Object.entries(profile)) {
-    if (name === "enabled") continue;
-    if (
-      typeof value !== "number" ||
-      !Number.isFinite(value) ||
-      value < 0
-    ) {
-      throw new Error(`Runtime memory ${name} must be a non-negative number`);
-    }
-  }
-}
-
-// #endregion
-
-// #region RuntimeBuilder 贡献接口
-
-class RuntimeBuilder implements RuntimeContributionContext {
-  private profile?: RuntimeProfileContribution;
-  private provider?: RuntimeProviderPort;
-  private platform?: RuntimePlatformPort;
-  private workspace?: WorkspacePort;
-  private sandbox?: RuntimeSandboxPort;
-  private memoryProfile: RuntimeMemoryProfile = DISABLED_MEMORY;
-  private memory?: RuntimeMemoryPort;
-  private memoryConfigured = false;
-  private denyPolicy?: RuntimeDenyPolicy;
-  private denyPolicyConfigured = false;
-  private readonly piTools = new Map<string, PiToolCandidate>();
-  private readonly skillSources = new Map<
-    string,
-    {
-      name: string;
-      description: string;
-      source: SkillSource;
-      script: RuntimeSkillScriptPolicy;
-    }
-  >();
-  private readonly skillDefinitions = new Set<string>();
-  private readonly connectors = new Map<string, RuntimeMcpServer>();
-  private readonly extensions = new Map<string, RuntimeExtensionConfig>();
-  private schedule?: RuntimeSchedulePort;
-  private readonly enabledSubagents = new Set<string>();
-  private subagents?: RuntimeSubagentPort;
-  private turnEvents?: RuntimeTurnEventsPort;
-  private readonly commitGuards: Array<() => Promise<void>> = [];
-  private readonly degradations: RuntimeDegradation[] = [];
-
-  // 作用：给 Plugin 一组受限的候选写入方法。
-  // 调用：候选装配开始后创建一次，再交给每个 contribute 回调。
-  // 原因：返回冻结门面，防止 Plugin 保留或修改 Builder 自身状态。
-  contributionContext(): RuntimeContributionContext {
-    return Object.freeze({
-      configureProfile: this.configureProfile.bind(this),
-      bindProvider: this.bindProvider.bind(this),
-      bindPlatform: this.bindPlatform.bind(this),
-      bindWorkspace: this.bindWorkspace.bind(this),
-      bindSandbox: this.bindSandbox.bind(this),
-      configureMemory: this.configureMemory.bind(this),
-      addPiTool: this.addPiTool.bind(this),
-      configureDenyPolicy:
-        this.configureDenyPolicy.bind(this),
-      addSkillSource: this.addSkillSource.bind(this),
-      addConnector: this.addConnector.bind(this),
-      addExtension: this.addExtension.bind(this),
-      bindSchedule: this.bindSchedule.bind(this),
-      enableSubagent: this.enableSubagent.bind(this),
-      bindSubagents: this.bindSubagents.bind(this),
-      bindTurnEvents: this.bindTurnEvents.bind(this),
-      addCommitGuard: this.addCommitGuard.bind(this),
-      reportDegradation:
-        this.reportDegradation.bind(this),
-    });
-  }
-
-  // 作用：记录本次装配唯一的运行参数。
-  // 调用：profile Plugin 在贡献阶段调用一次。
-  // 原因：重复配置通常意味着装配歧义，因此立即拒绝。
-  configureProfile(profile: RuntimeProfileContribution): void {
-    if (this.profile) {
-      throw new Error("Runtime profile was contributed more than once");
-    }
-    if (!EXECUTION_LEVELS.includes(profile.executionLevel)) {
-      throw new Error("Runtime execution level is invalid");
-    }
-    this.profile = profile;
-  }
-
-  // 作用：记录本次装配唯一的模型 Provider。
-  // 调用：provider Plugin 在贡献阶段调用一次。
-  // 原因：默认模型和端点必须从同一份配置校验，不能静默合并。
-  bindProvider(provider: RuntimeProviderPort): void {
-    if (this.provider) {
-      throw new Error("Runtime Provider was contributed more than once");
-    }
-    this.provider = provider;
-  }
-
-  // 作用：记录本次装配唯一的平台能力。
-  // 调用：platform Plugin 在贡献阶段调用一次。
-  // 原因：Loader 与出口端口必须来自同一个平台配置，不能静默拼接。
-  bindPlatform(platform: RuntimePlatformPort): void {
-    if (this.platform) {
-      throw new Error("Runtime platform was contributed more than once");
-    }
-    this.platform = platform;
-  }
-
-  // 作用：记录本次装配可选的工作区。
-  // 调用：workspace Plugin 在成功加载工作区后调用。
-  // 原因：工作区只有一个当前目录语义，重复绑定会产生不确定行为。
-  bindWorkspace(workspace: WorkspacePort): void {
-    if (this.workspace) {
-      throw new Error("Runtime workspace was contributed more than once");
-    }
-    this.workspace = workspace;
-  }
-
-  // 作用：记录本次候选唯一的 Linux Sandbox 执行端口。
-  // 调用：sandbox Plugin 在部署与 Agent 双开关都通过后调用。
-  // 原因：一个 Chat 只能指向一个由 Host 选定的 Sandbox，重复绑定必须失败。
-  bindSandbox(
-    sandbox: RuntimeSandboxPort,
-  ): void {
-    if (this.sandbox) {
-      throw new Error("Runtime Sandbox was contributed more than once");
-    }
-    this.sandbox = sandbox;
-  }
-
-  // 作用：记录内存预算和可选读写端口。
-  // 调用：memory Plugin 在贡献阶段调用一次。
-  // 原因：即使内存关闭也要记录“已经配置”，以便拒绝第二份冲突配置。
-  configureMemory(
-    profile: RuntimeMemoryProfile,
-    port?: RuntimeMemoryPort,
-  ): void {
-    if (this.memoryConfigured) {
-      throw new Error("Runtime memory was contributed more than once");
-    }
-    this.memoryConfigured = true;
-    this.memoryProfile = profile;
-    this.memory = port;
-  }
-
-  // 作用：把一个已授权的 Pi Tool 加入候选 Agent 输入。
-  // 调用：tool Plugin 在装配期为实际可见的能力逐个调用。
-  // 原因：Pi Tool 自带名称，同名能力必须在进入 Agent 前失败。
-  addPiTool(candidate: PiToolCandidate): void {
-    const name = requiredName(candidate.tool.name, "Pi Tool");
-    if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
-      throw new Error(`Pi Tool ${name} execution level is invalid`);
-    }
-    if (this.piTools.has(name)) {
-      throw new Error(`Duplicate Runtime Pi Tool: ${name}`);
-    }
-    this.piTools.set(name, candidate);
-  }
-
-  // 作用：记录 Turn 期拒绝清单。
-  // 调用：tool Plugin 完成 Action 挑选后调用一次。
-  // 原因：空策略也是有效配置，所以用独立标记判断是否重复贡献。
-  configureDenyPolicy(
-    policy?: RuntimeDenyPolicy,
-  ): void {
-    if (this.denyPolicyConfigured) {
-      throw new Error(
-        "Runtime deny policy was contributed more than once",
-      );
-    }
-    this.denyPolicyConfigured = true;
-    this.denyPolicy = policy;
-  }
-
-  // 作用：加入一个 Skill 的持久化 catalog、内容来源及其独立脚本权限。
-  // 调用：skill Plugin 为已绑定的 Resource 逐个调用。
-  // 原因：catalog、来源和权限一起登记，装配无需读取来源且权限不会在 Skill 之间漂移。
-  addSkillSource(
-    name: string,
-    description: string,
-    source: SkillSource,
-    script: Partial<RuntimeSkillScriptPolicy> = {},
-  ): void {
-    const normalized = this.addSkillDefinition(name);
-    const normalizedDescription = requiredName(
-      description,
-      `Runtime Skill "${normalized}" description`,
-    );
-    const network = script.network ?? "none";
-    if (network !== "none" && network !== "full") {
-      throw new Error(
-        `Runtime Skill "${normalized}" has invalid network permission`,
-      );
-    }
-    const workspace = script.workspace ?? "none";
-    if (
-      workspace !== "none" &&
-      workspace !== "read" &&
-      workspace !== "read-write"
-    ) {
-      throw new Error(
-        `Runtime Skill "${normalized}" has invalid workspace permission`,
-      );
-    }
-    const tools = [
-      ...new Set(
-        (script.tools ?? []).map((tool) =>
-          requiredName(tool, `Runtime Skill "${normalized}" Tool`),
-        ),
-      ),
-    ];
-    this.skillSources.set(normalized, Object.freeze({
-      name: normalized,
-      description: normalizedDescription,
-      source,
-      script: Object.freeze({
-        network,
-        workspace,
-        tools: Object.freeze(tools),
-      }),
-    }));
-  }
-
-  // 作用：把一个 MCP Connector 加入候选连接表。
-  // 调用：connector Plugin 为每个已授权连接逐个调用。
-  // 原因：名称和 URL 在提交前规范化，避免运行时才发现空地址或重名。
-  addConnector(server: RuntimeMcpServer): void {
-    const name = requiredName(server.name, "Connector");
-    if (this.connectors.has(name)) {
-      throw new Error(`Duplicate Runtime Connector: ${name}`);
-    }
-    if (!server.url.trim()) {
-      throw new Error(`Runtime Connector "${name}" URL must not be empty`);
-    }
-    this.connectors.set(name, Object.freeze({
-      name,
-      url: server.url.trim(),
-    }));
-  }
-
-  // 作用：把一个 Runtime Extension 加入候选扩展表。
-  // 调用：extension Plugin 为每个已部署扩展逐个调用。
-  // 原因：注册名必须等于 manifest 名，防止配置选择和实际执行对象错位。
-  addExtension(name: string, extension: RuntimeExtensionConfig): void {
-    const normalized = requiredName(name, "Extension");
-    if (this.extensions.has(normalized)) {
-      throw new Error(`Duplicate Runtime Extension: ${normalized}`);
-    }
-    if (extension.manifest.name !== normalized) {
-      throw new Error(
-        `Runtime Extension name mismatch: expected "${normalized}", got "${extension.manifest.name}"`,
-      );
-    }
-    this.extensions.set(normalized, extension);
-  }
-
-  // 作用：记录定时任务调用端口。
-  // 调用：schedule Plugin 在贡献阶段调用一次。
-  // 原因：定时任务必须回到当前会话所有者，不能选择多个路由。
-  bindSchedule(schedule: RuntimeSchedulePort): void {
-    if (this.schedule) {
-      throw new Error("Runtime Schedule was contributed more than once");
-    }
-    this.schedule = schedule;
-  }
-
-  // 作用：标记一个 Subagent 类型在本次运行中可用。
-  // 调用：subagent Plugin 完成部署检查后逐个调用。
-  // 原因：只记录已部署类型，避免模型拿到无法执行的名称。
-  enableSubagent(name: string): void {
-    this.enabledSubagents.add(requiredName(name, "Subagent"));
-  }
-
-  // 作用：记录 Subagent 的实际执行端口。
-  // 调用：subagent Plugin 至少启用一种类型时调用一次。
-  // 原因：启用列表与执行能力分开校验，缺端口时在提交前失败。
-  bindSubagents(subagents: RuntimeSubagentPort): void {
-    if (this.subagents) {
-      throw new Error("Runtime Subagents were contributed more than once");
-    }
-    this.subagents = subagents;
-  }
-
-  // 作用：记录 Turn 完成后的应用投影端口。
-  // 调用：turn-events Plugin 在贡献阶段调用一次。
-  // 原因：完成事件只有一个顺序来源，重复绑定可能重复写业务状态。
-  bindTurnEvents(turnEvents: RuntimeTurnEventsPort): void {
-    if (this.turnEvents) {
-      throw new Error("Runtime Turn Events were contributed more than once");
-    }
-    this.turnEvents = turnEvents;
-  }
-
-  // 作用：登记一个提交前必须再次通过的业务检查。
-  // 调用：容易在加载期间过期的 scope Plugin 添加检查时调用。
-  // 原因：检查延迟到最终 commit 前，可阻止过期候选覆盖当前 Runtime。
-  addCommitGuard(guard: () => Promise<void>): void {
-    this.commitGuards.push(guard);
-  }
-
-  // 作用：把一项可继续运行的能力缺失加入诊断。
-  // 调用：Runtime 汇总每个 PreparedPlugin 的降级信息时调用。
-  // 原因：复制并冻结对象，避免 Plugin 在提交后改写诊断。
-  reportDegradation(degradation: RuntimeDegradation): void {
-    this.degradations.push(Object.freeze({ ...degradation }));
-  }
-
-// #endregion
-
-// #region RuntimeBuilder 校验与候选生成
-
-  // 作用：校验全部贡献，并生成一个不可变候选 Runtime。
-  // 调用：所有 Plugin 按固定顺序完成 contribute 后调用一次。
-  // 原因：所有交叉约束都在这里通过后才返回候选，旧 Snapshot 不会半更新。
-  build(): RuntimeCandidate {
-    if (!this.profile) {
-      throw new Error("Runtime profile Plugin did not configure a profile");
-    }
-    if (!this.platform) {
-      throw new Error("Runtime platform Plugin did not bind a platform");
-    }
-    if (!this.provider) {
-      throw new Error("Runtime provider Plugin did not bind a provider");
-    }
-    if (!this.profile.model.trim()) {
-      throw new Error("Runtime model must not be empty");
-    }
-    if (
-      !this.provider.defaultModel.trim() ||
-      this.provider.endpoints.length === 0 ||
-      !this.provider.endpoints.some((endpoint) =>
-        endpoint.models.includes(this.provider!.defaultModel)
-      ) ||
-      this.provider.endpoints.some((endpoint) =>
-        !endpoint.apiKey.trim() ||
-        !endpoint.baseURL.trim() ||
-        endpoint.models.length === 0
-      )
-    ) {
-      throw new Error("No usable Provider credential is configured");
-    }
-    if (!this.platform.loader) {
-      throw new Error("Runtime platform loader is required");
-    }
-    if (typeof this.platform.outbound !== "function") {
-      throw new Error("Runtime platform outbound port is required");
-    }
-
-    assertMemoryProfile(this.memoryProfile);
-    if (this.memoryProfile.enabled && (!this.workspace || !this.memory)) {
-      throw new Error(
-        "Enabled Runtime memory requires Workspace and Memory ports",
-      );
-    }
-    if (this.sandbox && !this.workspace) {
-      throw new Error(
-        "Runtime Sandbox requires a persistent Workspace port",
-      );
-    }
-    if (this.enabledSubagents.size > 0 && !this.subagents) {
-      throw new Error(
-        "Enabled Runtime Subagents require a Subagent port",
-      );
-    }
-    const profile = freezeRuntimeProfile({
-      model: this.profile.model.trim(),
-      thinking: this.profile.thinking,
-      systemPrompt: this.profile.systemPrompt,
-      denyPolicy: this.denyPolicy,
-      enabledSubagents: [...this.enabledSubagents],
-      mcpServers: [...this.connectors.values()],
-      executionLevel: this.profile.executionLevel,
-      memory: this.memoryProfile,
-    });
-    const provider: RuntimeProviderPort = Object.freeze({
-      defaultModel: this.provider.defaultModel,
-      endpoints: Object.freeze(this.provider.endpoints.map(
-        (endpoint) => Object.freeze({
-          ...endpoint,
-          ...(endpoint.headers
-            ? { headers: Object.freeze({ ...endpoint.headers }) }
-            : {}),
-          models: Object.freeze([...endpoint.models]),
-        }),
-      )),
-    });
-    const endpoints = provider.endpoints.filter((endpoint) =>
-      endpoint.models.includes(profile.model)
-    );
-    if (endpoints.length !== 1) {
-      throw new Error(
-        endpoints.length === 0
-          ? `Model is not configured by this deployment: ${profile.model}`
-          : `Model is configured by multiple endpoints: ${profile.model}`,
-      );
-    }
-    const resolvedModel = resolvePiModel(provider, profile.model);
-    const endpoint = endpoints[0]!;
-    const webSearch = endpoint.protocol === "openrouter-chat"
-      ? undefined
-      : createWebSearch({
-        endpoint,
-        model: profile.model,
-        maxTokens: resolvedModel.maxTokens,
-        reasoning: resolvedModel.reasoning,
-      });
-    if (!webSearch) {
-      this.reportDegradation({
-        capability: "web_search",
-        reason: "unavailable",
-        detail: "Native web search is unavailable for openrouter-chat",
-      });
-    }
-    for (const candidate of basePiToolCandidates(webSearch)) {
-      this.addPiTool(candidate);
-    }
-    const bindings: RuntimeBindings = Object.freeze({
-      provider,
-      platform: Object.freeze({ ...this.platform }),
-      ...(this.workspace ? { workspace: this.workspace } : {}),
-      ...(this.memoryProfile.enabled && this.memory
-        ? { memory: this.memory }
-        : {}),
-      skills: Object.freeze({
-        sources: Object.freeze([
-          ...this.skillSources.values(),
-        ]),
-      }),
-      ...(this.turnEvents ? { turnEvents: this.turnEvents } : {}),
-    });
-    const snapshot: RuntimeSnapshot = Object.freeze({
-      profile,
-      bindings,
-      pi: createPiRuntimeAssembly({
-        profile,
-        provider,
-        toolCandidates: [...this.piTools.values()],
-        mcpServers: profile.mcpServers,
-        extensions: [...this.extensions.values()],
-      }),
-      degradations: Object.freeze([
-        ...this.degradations,
-      ]),
-    });
-
-    return Object.freeze({
-      snapshot,
-      commitGuards: Object.freeze([
-        ...this.commitGuards,
-      ]),
-    });
-  }
-
-  // 作用：登记一个 Skill 名称并返回规范化结果。
-  // 调用：Host 文档和外部 Skill 来源写入前调用。
-  // 原因：所有 Skill 来源共享一个命名空间，重名必须在装配时暴露。
-  private addSkillDefinition(name: string): string {
-    const normalized = requiredName(name, "Skill");
-    if (this.skillDefinitions.has(normalized)) {
-      throw new Error(`Duplicate Runtime Skill: ${normalized}`);
-    }
-    this.skillDefinitions.add(normalized);
-    return normalized;
-  }
-}
-
-// 作用：检查 Plugin kind 合法、唯一，并包含所有必需能力。
-// 调用：任何 loader 启动前由 `prepareRuntimeCandidate` 调用。
-// 原因：先校验结构可避免为注定失败的配置执行外部读取。
-function validatePluginKinds(
-  plugins: readonly AgentPlugin[],
-): void {
-  const kinds = new Set<PluginKind>();
-  const knownKinds = new Set(PLUGIN_ORDER);
-
-  for (const plugin of plugins) {
-    if (!knownKinds.has(plugin.kind)) {
-      throw new Error(`Unknown Agent Plugin kind: ${plugin.kind}`);
-    }
-    if (kinds.has(plugin.kind)) {
-      throw new Error(
-        `Duplicate Agent Plugin kind: ${plugin.kind}`,
-      );
-    }
-    kinds.add(plugin.kind);
-  }
-
-  for (const required of REQUIRED_PLUGIN_KINDS) {
-    if (!kinds.has(required)) {
-      throw new Error(
-        `Missing required Agent Plugin: ${required}`,
-      );
-    }
-  }
-}
-
-/**
- * 在不改动当前 Runtime 的前提下生成一个隔离候选。
- *
- * @remarks
- * `AgentRuntimeKernel` 在初始化或重载时调用它。
- *
- * loader 并行执行，贡献按固定 kind 顺序执行，任何失败都不会产生 commit。
- *
- * 该函数有意不从包入口导出，提交生命周期只能由 Kernel 控制。
- *
- * @internal
- */
-export async function prepareRuntimeCandidate(
-  config: AgentConfig,
-): Promise<RuntimeCandidate> {
-  validatePluginKinds(config.plugins);
-
-  const prepared = await Promise.all(
-    config.plugins.map(async (plugin) => {
-      const result = await plugin.prepare();
-      if (result.kind !== plugin.kind) {
-        throw new Error(
-          `Prepared Agent Plugin kind mismatch: expected ${plugin.kind}, got ${result.kind}`,
-        );
-      }
-      return result;
-    }),
-  );
-  const byKind = new Map(
-    prepared.map((plugin) => [plugin.kind, plugin]),
-  );
-  const builder = new RuntimeBuilder();
-  const contributionContext =
-    builder.contributionContext();
-
-  for (const kind of PLUGIN_ORDER) {
-    const plugin = byKind.get(kind);
-    if (!plugin) continue;
-    for (const degradation of plugin.degradations) {
-      builder.reportDegradation(degradation);
-    }
-    await plugin.contribute(contributionContext);
-  }
-
-  return builder.build();
-}
-
-/**
- * 完成候选装配、提交前检查，并在最后一步安装 Snapshot。
- *
- * @remarks
- * `AgentRuntimeKernel.initConfig` 在首次加载或显式重载时调用它。
- *
- * `commit` 只在全部 loader、贡献、校验和 guard 成功后调用一次。
- *
- * @internal
- */
-export async function initializeRuntimeConfig(
-  config: AgentConfig,
-  commit: (snapshot: RuntimeSnapshot) => void,
-): Promise<void> {
-  const candidate = await prepareRuntimeCandidate(config);
-  for (const guard of candidate.commitGuards) {
-    await guard();
-  }
-  commit(candidate.snapshot);
-}
-
-// #endregion