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

package/src/{plugins.ts → runtime-assembler.ts}

@@ -1,6 +1,7 @@
 import type { SkillSource } from "agents/skills";
 import type {
   RuntimeCodeExecutionPort,
+  RuntimeGatewayPort,
   RuntimeMemoryPort,
   RuntimePlatformPort,
   RuntimeProviderPort,
@@ -51,38 +52,7 @@ import { subagentPiToolCandidates } from "./pi/tool/subagent";
 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";
+/** Runtime Assembler：校验一份扁平输入并生成可原子提交的 Snapshot。 */
 
 export type { RuntimeDegradation } from "./kernel/degradation";
 
@@ -90,7 +60,7 @@ export type { RuntimeDegradation } from "./kernel/degradation";
  * 提供 Runtime 核心运行参数。
  *
  * @remarks
- * `profile` Plugin 在准备结果中返回它。
+ * Host Planner 在装配输入中提供它。
  *
  * 这里只放业务可配置字段，冻结和最终结构由 Runtime 负责。
  */
@@ -131,113 +101,31 @@ export interface RuntimeToolSurfacePolicy {
   readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
 }
 
-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;
-  };
-}
-
-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>>;
-}
-
-/**
- * 汇总一次 Runtime 装配要使用的全部 Plugin。
- */
-export interface AgentConfig {
-  readonly plugins: readonly AgentPlugin[];
-}
-
-/**
- * 定义一个只准备声明式结果的 Runtime Plugin。
- *
- * Runtime 内部负责排序、合并、冲突检查和提交。
- */
-export function definePlugin<K extends PluginKind>(
-  spec: AgentPluginSpec<K>,
-): AgentPlugin<K> {
-  return Object.freeze({
-    kind: spec.kind,
-
-    async prepare(): Promise<PreparedPlugin<K>> {
-      const prepared = await spec.prepare();
-      const degradations = Object.freeze(
-        prepared.degradations.map((degradation) =>
-          Object.freeze({ ...degradation }),
-        ),
-      );
-
-      return Object.freeze({
-        ...prepared,
-        kind: spec.kind,
-        degradations,
-      }) as PreparedPlugin<K>;
-    },
-  }) as AgentPlugin<K>;
+/** Host Planner 与 Runtime Assembler 之间唯一的一次性 seam。 */
+export interface RuntimeAssemblyInput {
+  readonly profile: RuntimeProfileContribution;
+  readonly memoryProfile: RuntimeMemoryProfile;
+  readonly toolPolicy?: RuntimeToolSurfacePolicy;
+  readonly enabledSubagents: readonly string[];
+  readonly provider: RuntimeProviderPort;
+  readonly platform: RuntimePlatformPort;
+  readonly workspace?: WorkspacePort;
+  readonly codeExecution?: RuntimeCodeExecutionPort;
+  readonly sandbox?: RuntimeSandboxPort;
+  readonly memory?: RuntimeMemoryPort;
+  readonly hostTools: readonly PiToolCandidate[];
+  readonly skills: readonly RuntimeSkillContribution[];
+  readonly connectors: readonly RuntimeMcpServer[];
+  readonly gateway?: RuntimeGatewayPort;
+  readonly extensions: readonly RuntimeExtensionContribution[];
+  readonly subagents?: RuntimeSubagentPort;
+  readonly schedule?: RuntimeSchedulePort;
+  readonly turnEvents?: RuntimeTurnEventsPort;
+  readonly commitGuards: readonly (() => Promise<void>)[];
+  readonly degradations: readonly RuntimeDegradation[];
 }
 
-// #endregion
-
-// #region 内部候选契约与装配顺序
+// #region 内部候选契约
 
 /**
  * 保存一次已经完成校验、可供 Kernel 使用的 Runtime 结果。
@@ -261,29 +149,6 @@ export interface RuntimeCandidate {
   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,
@@ -441,6 +306,7 @@ class RuntimeBuilder {
   private profile?: RuntimeProfileContribution;
   private provider?: RuntimeProviderPort;
   private platform?: RuntimePlatformPort;
+  private gateway?: RuntimeGatewayPort;
   private workspace?: WorkspacePort;
   private codeExecution?: RuntimeCodeExecutionPort;
   private sandbox?: RuntimeSandboxPort;
@@ -466,68 +332,36 @@ class RuntimeBuilder {
   private readonly commitGuards: Array<() => Promise<void>> = [];
   private readonly degradations: RuntimeDegradation[] = [];
 
-  merge(prepared: PreparedPlugin): void {
-    for (const degradation of prepared.degradations) {
+  merge(input: RuntimeAssemblyInput): void {
+    for (const degradation of input.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 (!EXECUTION_LEVELS.includes(input.profile.executionLevel)) {
+      throw new Error("Runtime execution level is invalid");
     }
+    this.profile = input.profile;
+    this.provider = input.provider;
+    this.platform = input.platform;
+    this.workspace = input.workspace;
+    this.codeExecution = input.codeExecution;
+    this.sandbox = input.sandbox;
+    this.memoryProfile = input.memoryProfile;
+    this.memory = input.memory;
+    this.hostTools.push(...input.hostTools);
+    this.toolPolicy = input.toolPolicy;
+    for (const skill of input.skills) this.addSkill(skill);
+    for (const connector of input.connectors) this.addConnector(connector);
+    this.gateway = input.gateway;
+    for (const { name, extension } of input.extensions) {
+      this.addExtension(name, extension);
+    }
+    this.schedule = input.schedule;
+    for (const name of input.enabledSubagents) {
+      this.enabledSubagents.add(requiredName(name, "Subagent"));
+    }
+    this.subagents = input.subagents;
+    this.turnEvents = input.turnEvents;
+    this.commitGuards.push(...input.commitGuards);
   }
 
   private addSkill(skill: RuntimeSkillContribution): void {
@@ -614,17 +448,17 @@ class RuntimeBuilder {
 // #region RuntimeBuilder 校验与候选生成
 
   // 作用：校验全部声明，并生成一个不可变候选 Runtime。
-  // 调用：所有 Plugin 按固定顺序完成合并后调用一次。
+  // 调用：扁平 Assembly Input 合并完成后调用一次。
   // 原因：所有交叉约束都在这里通过后才返回候选，旧 Snapshot 不会半更新。
   async build(): Promise<RuntimeCandidate> {
     if (!this.profile) {
-      throw new Error("Runtime profile Plugin did not configure a profile");
+      throw new Error("Runtime assembly did not configure a profile");
     }
     if (!this.platform) {
-      throw new Error("Runtime platform Plugin did not bind a platform");
+      throw new Error("Runtime assembly did not bind a platform");
     }
     if (!this.provider) {
-      throw new Error("Runtime provider Plugin did not bind a provider");
+      throw new Error("Runtime assembly did not bind a provider");
     }
     if (!this.profile.model.trim()) {
       throw new Error("Runtime model must not be empty");
@@ -730,6 +564,7 @@ class RuntimeBuilder {
     const bindings: RuntimeBindings = Object.freeze({
       provider,
       platform: Object.freeze({ ...this.platform }),
+      ...(this.gateway ? { gateway: this.gateway } : {}),
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
         ? { memory: this.memory }
@@ -764,75 +599,23 @@ class RuntimeBuilder {
 
 }
 
-// 作用：检查 Plugin kind 合法、唯一，并包含所有必需能力。
-// 调用：任何 prepare 启动前由 `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` 在初始化或重载时调用它。
  *
- * prepare 并行执行，声明按固定 kind 顺序合并，任何失败都不会产生 commit。
+ * 任何合并、校验或 Tool Surface 构建失败都不会产生 commit。
  *
  * 该函数有意不从包入口导出，提交生命周期只能由 Kernel 控制。
  *
  * @internal
  */
 export async function prepareRuntimeCandidate(
-  config: AgentConfig,
+  input: RuntimeAssemblyInput,
 ): 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();
-
-  for (const kind of PLUGIN_ORDER) {
-    const plugin = byKind.get(kind);
-    if (!plugin) continue;
-    builder.merge(plugin);
-  }
-
+  builder.merge(input);
   return builder.build();
 }
 
@@ -846,11 +629,11 @@ export async function prepareRuntimeCandidate(
  *
  * @internal
  */
-export async function initializeRuntimeConfig(
-  config: AgentConfig,
+export async function assembleRuntime(
+  input: RuntimeAssemblyInput,
   commit: (snapshot: RuntimeSnapshot) => void,
 ): Promise<void> {
-  const candidate = await prepareRuntimeCandidate(config);
+  const candidate = await prepareRuntimeCandidate(input);
   for (const guard of candidate.commitGuards) {
     await guard();
   }