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

package/src/plugins.ts

@@ -1,10 +1,12 @@
 import type { SkillSource } from "agents/skills";
 import type {
+  RuntimeCodeExecutionPort,
   RuntimeMemoryPort,
   RuntimePlatformPort,
   RuntimeProviderPort,
   RuntimeSandboxPort,
   RuntimeSchedulePort,
+  RuntimeSkillSourceBinding,
   RuntimeSubagentPort,
   RuntimeTurnEventsPort,
   RuntimeBindings,
@@ -27,15 +29,30 @@ import {
 } from "./lib/execution-level";
 import {
   createPiRuntimeAssembly,
+  type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
 import type { PiToolCandidate } from "./pi/tool/compiler";
-import { basePiToolCandidates } from "./pi/tool/base";
+import {
+  basePiToolCandidates,
+  memoryPiToolCandidate,
+} from "./pi/tool/base";
+import {
+  browserQuickActionPiToolCandidates,
+  codeExecutionPiToolCandidate,
+} from "./pi/tool/core";
+import {
+  sandboxPiToolCandidates,
+  workspacePiToolCandidates,
+} from "./pi/tool/workspace-sandbox";
+import { schedulePiToolCandidates } from "./pi/tool/schedule";
+import { skillPiToolCandidates } from "./pi/tool/skill";
+import { subagentPiToolCandidates } from "./pi/tool/subagent";
 import { createWebSearch } from "./pi/tool/web-search";
 import { resolvePiModel } from "./pi/runtime-adapter/models";
 
 /**
- * 本文件实现 Plugin 的准备、贡献、校验和原子候选装配。
+ * 本文件实现 Plugin 的准备、声明合并、校验和原子候选装配。
  *
  * @remarks
  * 核心术语见包入口 `index.ts`，这里不重复定义。
@@ -70,332 +87,152 @@ export type PluginKind =
 export type { RuntimeDegradation } from "./kernel/degradation";
 
 /**
- * 把 loader 读取到的值和本次降级信息一起返回。
+ * 提供 Runtime 核心运行参数。
  *
  * @remarks
- * `definePlugin` 在准备阶段读取它。
+ * `profile` Plugin 在准备结果中返回它。
  *
- * 值与诊断一起返回，可以避免 loader 直接修改 Runtime。
+ * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
  */
-export interface PluginLoadResult<T> {
-  readonly value: T;
-  readonly degradations: readonly RuntimeDegradation[];
+export interface RuntimeProfileContribution {
+  readonly model: string;
+  readonly thinking: ThinkingEffort;
+  readonly systemPrompt?: string;
+  readonly executionLevel: ExecutionLevel;
 }
 
 /**
- * 表示一个尚未准备的 Runtime Plugin。
- *
- * @remarks
- * 应用把它放进 `AgentConfig.plugins`。
- *
- * Runtime 只调用 `prepare`，不会接触 Plugin 捕获的业务依赖。
+ * 描述一个已准备 Skill。
  */
-export interface AgentPlugin {
-  readonly kind: PluginKind;
-  /**
-   * 读取这个 Plugin 的配置，并生成一个还未贡献的准备结果。
-   *
-   * @remarks
-   * Runtime 在生成候选结果时调用，应用只需把 Plugin 放进 `AgentConfig`。
-   *
-   * 读取与贡献分开，是为了并行读取外部数据后再按稳定顺序合并。
-   */
-  prepare(): Promise<PreparedPlugin>;
+export interface RuntimeSkillContribution {
+  readonly name: string;
+  readonly description: string;
+  readonly source: SkillSource;
+  readonly script?: Partial<RuntimeSkillScriptPolicy>;
 }
 
 /**
- * 表示 loader 已完成、但还没有写入候选结果的 Plugin。
- *
- * @remarks
- * Runtime 按固定 kind 顺序调用 `contribute`。
- *
- * 准备和贡献分开，才能并行读取数据又保持确定的合并顺序。
+ * 描述一个已准备 Extension。
  */
-export interface PreparedPlugin {
-  readonly kind: PluginKind;
-  readonly degradations: readonly RuntimeDegradation[];
-  /**
-   * 把已读取的值写进 Runtime 提供的受限候选上下文。
-   *
-   * @remarks
-   * Runtime 在全部 loader 完成后，按 `PluginKind` 固定顺序调用。
-   *
-   * 这一阶段只能使用受限上下文，不能直接安装 Snapshot。
-   */
-  contribute(
-    ctx: RuntimeContributionContext,
-  ): void | Promise<void>;
+export interface RuntimeExtensionContribution {
+  readonly name: string;
+  readonly extension: RuntimeExtensionConfig;
 }
 
 /**
- * 描述一个 Plugin 应该怎样读取数据并贡献能力。
- *
- * @remarks
- * 应用把该对象传给 `definePlugin`。
+ * 描述 Agent 对最终 Tool Surface 的可见性约束。
  *
- * `loader` 负责读取，`contribute` 负责组装，二者不要互相越权。
+ * Host 只提供策略；Runtime 在唯一 Tool Surface seam 中对所有
+ * Port 和 Resource 生成的候选项统一应用。
  */
-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>;
+export interface RuntimeToolSurfacePolicy {
+  readonly denyPolicy?: RuntimeDenyPolicy;
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
 }
 
-/**
- * 汇总一次 Runtime 装配要使用的全部 Plugin。
- *
- * @remarks
- * `RuntimeAgentDefinition.createConfig` 在首次加载或显式重载时返回它。
- *
- * 它只保存可信函数对象，不用于持久化或跨进程序列化。
- */
-export interface AgentConfig {
-  readonly plugins: readonly AgentPlugin[];
+interface PluginResultByKind {
+  readonly scope: {
+    readonly commitGuards: readonly (() => Promise<void>)[];
+  };
+  readonly profile: { readonly profile: RuntimeProfileContribution };
+  readonly provider: { readonly provider: RuntimeProviderPort };
+  readonly platform: {
+    readonly platform: RuntimePlatformPort;
+  };
+  readonly workspace: {
+    readonly workspace?: WorkspacePort;
+    readonly codeExecution?: RuntimeCodeExecutionPort;
+  };
+  readonly sandbox: {
+    readonly sandbox?: RuntimeSandboxPort;
+  };
+  readonly memory: {
+    readonly memoryProfile: RuntimeMemoryProfile;
+    readonly memoryPort?: RuntimeMemoryPort;
+  };
+  readonly tool: {
+    readonly hostTools: readonly PiToolCandidate[];
+    readonly policy?: RuntimeToolSurfacePolicy;
+  };
+  readonly skill: {
+    readonly skills: readonly RuntimeSkillContribution[];
+  };
+  readonly connector: {
+    readonly connectors: readonly RuntimeMcpServer[];
+  };
+  readonly extension: {
+    readonly extensions: readonly RuntimeExtensionContribution[];
+  };
+  readonly schedule: {
+    readonly schedule: RuntimeSchedulePort;
+  };
+  readonly subagent: {
+    readonly enabledSubagents: readonly string[];
+    readonly subagents?: RuntimeSubagentPort;
+  };
+  readonly "turn-events": {
+    readonly turnEvents: RuntimeTurnEventsPort;
+  };
 }
 
-/**
- * 提供 Runtime 核心运行参数。
- *
- * @remarks
- * `profile` Plugin 在贡献阶段调用 `configureProfile` 时传入。
- *
- * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
- */
-export interface RuntimeProfileContribution {
-  readonly model: string;
-  readonly thinking: ThinkingEffort;
-  readonly systemPrompt?: string;
-  readonly executionLevel: ExecutionLevel;
+export type PluginPreparation<K extends PluginKind> = Readonly<
+  PluginResultByKind[K] & {
+    readonly degradations: readonly RuntimeDegradation[];
+  }
+>;
+
+export type PreparedPlugin<K extends PluginKind = PluginKind> =
+  K extends PluginKind
+    ? Readonly<PluginPreparation<K> & { readonly kind: K }>
+    : never;
+
+interface AgentPluginContract<K extends PluginKind> {
+  readonly kind: K;
+  prepare(): Promise<PreparedPlugin<K>>;
+}
+
+export type AgentPlugin<K extends PluginKind = PluginKind> =
+  K extends PluginKind ? AgentPluginContract<K> : never;
+
+export interface AgentPluginSpec<K extends PluginKind> {
+  readonly kind: K;
+  prepare(): Promise<PluginPreparation<K>>;
 }
 
 /**
- * 限定 Plugin 可以写入候选 Runtime 的内容。
- *
- * @remarks
- * Plugin 的 `contribute` 回调使用这些方法。
- *
- * Runtime 只暴露绑定和增量添加操作，避免 Plugin 取得 Builder 的可变引用。
+ * 汇总一次 Runtime 装配要使用的全部 Plugin。
  */
-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;
+export interface AgentConfig {
+  readonly plugins: readonly AgentPlugin[];
 }
 
 /**
- * 把 loader 与贡献回调包装成 Runtime 可准备的 Plugin。
- *
- * @remarks
- * 应用在创建 `AgentConfig` 时调用它，不需要手写 `prepare`。
+ * 定义一个只准备声明式结果的 Runtime Plugin。
  *
- * 包装层会冻结准备结果，避免读取完成后被调用方改写。
+ * Runtime 内部负责排序、合并、冲突检查和提交。
  */
-export function definePlugin<T>(
-  spec: AgentPluginSpec<T>,
-): AgentPlugin {
+export function definePlugin<K extends PluginKind>(
+  spec: AgentPluginSpec<K>,
+): AgentPlugin<K> {
   return Object.freeze({
     kind: spec.kind,
 
-    // 作用：读取本 Plugin 的数据，并把结果变成不可变的准备对象。
-    // 调用：Runtime 在候选装配开始时调用，应用不应直接调用。
-    // 原因：此处只准备数据，不贡献能力，才能安全地与其他 loader 并行。
-    async prepare(): Promise<PreparedPlugin> {
-      const loaded = await spec.loader();
+    async prepare(): Promise<PreparedPlugin<K>> {
+      const prepared = await spec.prepare();
       const degradations = Object.freeze(
-        loaded.degradations.map((degradation) =>
+        prepared.degradations.map((degradation) =>
           Object.freeze({ ...degradation }),
         ),
       );
 
       return Object.freeze({
+        ...prepared,
         kind: spec.kind,
         degradations,
-        contribute: (ctx: RuntimeContributionContext) =>
-          spec.contribute(loaded.value, ctx),
-      });
+      }) as PreparedPlugin<K>;
     },
-  });
+  }) as AgentPlugin<K>;
 }
 
 // #endregion
@@ -451,7 +288,6 @@ const DISABLED_MEMORY: RuntimeMemoryProfile = Object.freeze({
   enabled: false,
   memoryTokens: 2_000,
   preferencesTokens: 500,
-  compactAfterTokens: 100_000,
 });
 
 // 作用：把外部名称整理成非空字符串。
@@ -479,22 +315,140 @@ function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
   }
 }
 
+interface ToolSurfaceInput {
+  readonly platform: RuntimePlatformPort;
+  readonly workspace?: WorkspacePort;
+  readonly memory?: {
+    readonly port: RuntimeMemoryPort;
+    readonly profile: RuntimeMemoryProfile;
+  };
+  readonly codeExecution?: RuntimeCodeExecutionPort;
+  readonly sandbox?: RuntimeSandboxPort;
+  readonly hostTools: readonly PiToolCandidate[];
+  readonly skills: readonly RuntimeSkillSourceBinding[];
+  readonly schedule?: RuntimeSchedulePort;
+  readonly subagents?: RuntimeSubagentPort;
+  readonly enabledSubagents: readonly string[];
+  readonly webSearch: Parameters<typeof basePiToolCandidates>[0];
+  readonly extensions: readonly RuntimeExtensionConfig[];
+  readonly policy?: RuntimeToolSurfacePolicy;
+}
+
+interface ToolSurface {
+  readonly surface: PiToolSurface;
+  readonly extensions: readonly RuntimeExtensionConfig[];
+  readonly degradations: readonly RuntimeDegradation[];
+}
+
+// 唯一 Tool Surface seam：只读取已授权 Port、Resource 和 Agent policy，
+// 统一生成可见 Tool，并在一处做名称、执行档位与冲突校验。
+async function createToolSurface(
+  input: ToolSurfaceInput,
+): Promise<ToolSurface> {
+  const deny = new Set(input.policy?.denyPolicy?.deny ?? []);
+  const allowsTool = input.policy?.allowsTool;
+  const allowsExtension = input.policy?.allowsExtension;
+  const visible = (candidate: PiToolCandidate) =>
+    candidate.authorized &&
+    !deny.has(candidate.tool.name) &&
+    allowsTool?.(candidate.tool.name) !== false;
+  const browserCandidates = input.platform.browser
+    ? browserQuickActionPiToolCandidates(input.platform.browser)
+    : [];
+  const workspaceCandidates = input.workspace
+    ? workspacePiToolCandidates(input.workspace)
+    : [];
+  const executionCandidates = input.workspace && input.codeExecution
+    ? [codeExecutionPiToolCandidate(input.codeExecution)]
+    : [];
+  const sandboxCandidates = input.sandbox
+    ? sandboxPiToolCandidates(input.sandbox)
+    : [];
+  const subagentCandidates = subagentPiToolCandidates(
+    input.subagents,
+    input.enabledSubagents,
+  );
+  const scheduleCandidates = input.schedule
+    ? schedulePiToolCandidates(input.schedule)
+    : [];
+  const baseCandidates = basePiToolCandidates(input.webSearch);
+  const memoryCandidates = input.memory
+    ? [memoryPiToolCandidate(input.memory.port, input.memory.profile)]
+    : [];
+  const scriptCandidates = [
+    ...browserCandidates,
+    ...workspaceCandidates,
+    ...executionCandidates,
+    ...sandboxCandidates,
+    ...input.hostTools,
+    ...scheduleCandidates,
+    ...subagentCandidates,
+    ...baseCandidates,
+    ...memoryCandidates,
+  ].filter(visible);
+  const staticCandidates = [
+    ...browserCandidates,
+    ...workspaceCandidates,
+    ...executionCandidates,
+    ...sandboxCandidates,
+    ...input.hostTools,
+    ...(await skillPiToolCandidates(input.skills, {
+      loader: input.platform.loader,
+      ...(input.workspace ? { workspace: input.workspace } : {}),
+      tools: scriptCandidates,
+    })),
+    ...scheduleCandidates,
+    ...subagentCandidates,
+    ...baseCandidates,
+    ...memoryCandidates,
+  ];
+
+  return {
+    surface: Object.freeze({
+      finalize(authorizedCandidates: readonly PiToolCandidate[]) {
+        const tools = new Map<string, PiToolCandidate>();
+
+        for (const candidate of [
+          ...staticCandidates,
+          ...authorizedCandidates,
+        ]) {
+          const name = requiredName(candidate.tool.name, "Pi Tool");
+          if (!visible(candidate)) continue;
+          if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
+            throw new Error(`Pi Tool ${name} execution level is invalid`);
+          }
+          if (tools.has(name)) {
+            throw new Error(`Duplicate Runtime Pi Tool: ${name}`);
+          }
+          tools.set(name, Object.freeze({ ...candidate }));
+        }
+
+        return Object.freeze([...tools.values()]);
+      },
+    }),
+    extensions: input.extensions.filter(
+      (extension) => allowsExtension?.(extension) !== false,
+    ),
+    degradations: [],
+  };
+}
+
 // #endregion
 
-// #region RuntimeBuilder 贡献接口
+// #region RuntimeBuilder 合并
 
-class RuntimeBuilder implements RuntimeContributionContext {
+class RuntimeBuilder {
   private profile?: RuntimeProfileContribution;
   private provider?: RuntimeProviderPort;
   private platform?: RuntimePlatformPort;
   private workspace?: WorkspacePort;
+  private codeExecution?: RuntimeCodeExecutionPort;
   private sandbox?: RuntimeSandboxPort;
+  private schedule?: RuntimeSchedulePort;
   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 hostTools: PiToolCandidate[] = [];
+  private toolPolicy?: RuntimeToolSurfacePolicy;
   private readonly skillSources = new Map<
     string,
     {
@@ -504,156 +458,88 @@ class RuntimeBuilder implements RuntimeContributionContext {
       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`);
+  merge(prepared: PreparedPlugin): void {
+    for (const degradation of prepared.degradations) {
+      this.reportDegradation(degradation);
+    }
+
+    switch (prepared.kind) {
+      case "scope":
+        this.commitGuards.push(...prepared.commitGuards);
+        break;
+      case "profile":
+        if (!EXECUTION_LEVELS.includes(prepared.profile.executionLevel)) {
+          throw new Error("Runtime execution level is invalid");
+        }
+        this.profile = prepared.profile;
+        break;
+      case "provider":
+        this.provider = prepared.provider;
+        break;
+      case "platform":
+        this.platform = prepared.platform;
+        break;
+      case "workspace":
+        this.workspace = prepared.workspace;
+        this.codeExecution = prepared.codeExecution;
+        break;
+      case "sandbox":
+        this.sandbox = prepared.sandbox;
+        break;
+      case "memory":
+        this.memoryProfile = prepared.memoryProfile;
+        this.memory = prepared.memoryPort;
+        break;
+      case "tool":
+        this.hostTools.push(...prepared.hostTools);
+        this.toolPolicy = prepared.policy;
+        break;
+      case "skill":
+        for (const skill of prepared.skills) this.addSkill(skill);
+        break;
+      case "connector":
+        for (const connector of prepared.connectors) {
+          this.addConnector(connector);
+        }
+        break;
+      case "extension":
+        for (const { name, extension } of prepared.extensions) {
+          this.addExtension(name, extension);
+        }
+        break;
+      case "schedule":
+        this.schedule = prepared.schedule;
+        break;
+      case "subagent":
+        for (const name of prepared.enabledSubagents) {
+          this.enabledSubagents.add(requiredName(name, "Subagent"));
+        }
+        this.subagents = prepared.subagents;
+        break;
+      case "turn-events":
+        this.turnEvents = prepared.turnEvents;
+        break;
     }
-    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",
-      );
+  private addSkill(skill: RuntimeSkillContribution): void {
+    const normalized = requiredName(skill.name, "Skill");
+    if (this.skillSources.has(normalized)) {
+      throw new Error(`Duplicate Runtime Skill: ${normalized}`);
     }
-    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,
+      skill.description,
       `Runtime Skill "${normalized}" description`,
     );
+    const script = skill.script ?? {};
     const network = script.network ?? "none";
     if (network !== "none" && network !== "full") {
       throw new Error(
@@ -680,7 +566,7 @@ class RuntimeBuilder implements RuntimeContributionContext {
     this.skillSources.set(normalized, Object.freeze({
       name: normalized,
       description: normalizedDescription,
-      source,
+      source: skill.source,
       script: Object.freeze({
         network,
         workspace,
@@ -689,10 +575,7 @@ class RuntimeBuilder implements RuntimeContributionContext {
     }));
   }
 
-  // 作用：把一个 MCP Connector 加入候选连接表。
-  // 调用：connector Plugin 为每个已授权连接逐个调用。
-  // 原因：名称和 URL 在提交前规范化，避免运行时才发现空地址或重名。
-  addConnector(server: RuntimeMcpServer): void {
+  private addConnector(server: RuntimeMcpServer): void {
     const name = requiredName(server.name, "Connector");
     if (this.connectors.has(name)) {
       throw new Error(`Duplicate Runtime Connector: ${name}`);
@@ -706,10 +589,10 @@ class RuntimeBuilder implements RuntimeContributionContext {
     }));
   }
 
-  // 作用：把一个 Runtime Extension 加入候选扩展表。
-  // 调用：extension Plugin 为每个已部署扩展逐个调用。
-  // 原因：注册名必须等于 manifest 名，防止配置选择和实际执行对象错位。
-  addExtension(name: string, extension: RuntimeExtensionConfig): void {
+  private addExtension(
+    name: string,
+    extension: RuntimeExtensionConfig,
+  ): void {
     const normalized = requiredName(name, "Extension");
     if (this.extensions.has(normalized)) {
       throw new Error(`Duplicate Runtime Extension: ${normalized}`);
@@ -722,54 +605,7 @@ class RuntimeBuilder implements RuntimeContributionContext {
     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 {
+  private reportDegradation(degradation: RuntimeDegradation): void {
     this.degradations.push(Object.freeze({ ...degradation }));
   }
 
@@ -777,10 +613,10 @@ class RuntimeBuilder implements RuntimeContributionContext {
 
 // #region RuntimeBuilder 校验与候选生成
 
-  // 作用：校验全部贡献，并生成一个不可变候选 Runtime。
-  // 调用：所有 Plugin 按固定顺序完成 contribute 后调用一次。
+  // 作用：校验全部声明，并生成一个不可变候选 Runtime。
+  // 调用：所有 Plugin 按固定顺序完成合并后调用一次。
   // 原因：所有交叉约束都在这里通过后才返回候选，旧 Snapshot 不会半更新。
-  build(): RuntimeCandidate {
+  async build(): Promise<RuntimeCandidate> {
     if (!this.profile) {
       throw new Error("Runtime profile Plugin did not configure a profile");
     }
@@ -834,7 +670,7 @@ class RuntimeBuilder implements RuntimeContributionContext {
       model: this.profile.model.trim(),
       thinking: this.profile.thinking,
       systemPrompt: this.profile.systemPrompt,
-      denyPolicy: this.denyPolicy,
+      denyPolicy: this.toolPolicy?.denyPolicy,
       enabledSubagents: [...this.enabledSubagents],
       mcpServers: [...this.connectors.values()],
       executionLevel: this.profile.executionLevel,
@@ -864,23 +700,32 @@ class RuntimeBuilder implements RuntimeContributionContext {
     }
     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 webSearch = createWebSearch({
+      endpoint,
+      model: profile.model,
+      maxTokens: resolvedModel.maxTokens,
+      reasoning: resolvedModel.reasoning,
+    });
+    const skillSources = [...this.skillSources.values()];
+    const toolSurface = await createToolSurface({
+      platform: this.platform,
+      ...(this.workspace ? { workspace: this.workspace } : {}),
+      ...(this.memoryProfile.enabled && this.memory
+        ? { memory: { port: this.memory, profile: this.memoryProfile } }
+        : {}),
+      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
+      ...(this.sandbox ? { sandbox: this.sandbox } : {}),
+      hostTools: this.hostTools,
+      skills: skillSources,
+      ...(this.schedule ? { schedule: this.schedule } : {}),
+      ...(this.subagents ? { subagents: this.subagents } : {}),
+      enabledSubagents: [...this.enabledSubagents],
+      webSearch,
+      extensions: [...this.extensions.values()],
+      ...(this.toolPolicy ? { policy: this.toolPolicy } : {}),
+    });
+    for (const degradation of toolSurface.degradations) {
+      this.reportDegradation(degradation);
     }
     const bindings: RuntimeBindings = Object.freeze({
       provider,
@@ -890,9 +735,7 @@ class RuntimeBuilder implements RuntimeContributionContext {
         ? { memory: this.memory }
         : {}),
       skills: Object.freeze({
-        sources: Object.freeze([
-          ...this.skillSources.values(),
-        ]),
+        sources: Object.freeze(skillSources),
       }),
       ...(this.turnEvents ? { turnEvents: this.turnEvents } : {}),
     });
@@ -902,9 +745,9 @@ class RuntimeBuilder implements RuntimeContributionContext {
       pi: createPiRuntimeAssembly({
         profile,
         provider,
-        toolCandidates: [...this.piTools.values()],
+        toolSurface: toolSurface.surface,
         mcpServers: profile.mcpServers,
-        extensions: [...this.extensions.values()],
+        extensions: toolSurface.extensions,
       }),
       degradations: Object.freeze([
         ...this.degradations,
@@ -919,21 +762,10 @@ class RuntimeBuilder implements RuntimeContributionContext {
     });
   }
 
-  // 作用：登记一个 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` 调用。
+// 调用：任何 prepare 启动前由 `prepareRuntimeCandidate` 调用。
 // 原因：先校验结构可避免为注定失败的配置执行外部读取。
 function validatePluginKinds(
   plugins: readonly AgentPlugin[],
@@ -968,7 +800,7 @@ function validatePluginKinds(
  * @remarks
  * `AgentRuntimeKernel` 在初始化或重载时调用它。
  *
- * loader 并行执行，贡献按固定 kind 顺序执行，任何失败都不会产生 commit。
+ * prepare 并行执行，声明按固定 kind 顺序合并，任何失败都不会产生 commit。
  *
  * 该函数有意不从包入口导出，提交生命周期只能由 Kernel 控制。
  *
@@ -994,16 +826,11 @@ export async function prepareRuntimeCandidate(
     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);
+    builder.merge(plugin);
   }
 
   return builder.build();
@@ -1015,7 +842,7 @@ export async function prepareRuntimeCandidate(
  * @remarks
  * `AgentRuntimeKernel.initConfig` 在首次加载或显式重载时调用它。
  *
- * `commit` 只在全部 loader、贡献、校验和 guard 成功后调用一次。
+ * `commit` 只在全部准备、合并、校验和 guard 成功后调用一次。
  *
  * @internal
  */