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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.1.3-alpha.0",
+  "version": "0.1.3-alpha.1",
   "type": "module",
   "files": [
     "src",

package/src/index.ts

@@ -23,11 +23,9 @@
  * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
  * - `AgentConfig` 是应用交给 Runtime 的一次完整装配说明。
- * - `AgentPlugin` 是一种能力的加载与贡献单元。
- * - `PluginKind` 是 Plugin 的固定类别，也是贡献时的稳定排序依据。
- * - `loader` 读取业务数据或外部绑定，并返回本次装配要使用的值。
- * - `prepare` 执行 `loader`，但不会改动正在运行的 Runtime。
- * - `RuntimeContributionContext` 是 Plugin 写入候选配置的受限接口。
+ * - `AgentPlugin` 是一种能力的声明式准备单元。
+ * - `PluginKind` 同时收窄 Plugin 可以准备的字段，并作为内部稳定合并顺序。
+ * - `prepare` 读取业务数据或外部绑定，但不会改动正在运行的 Runtime。
  * - `Port` 是 Runtime 调用外部能力时依赖的最小接口。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
  * - `RuntimeBuilder` 是包内实现，用来校验贡献并生成候选结果。
@@ -40,8 +38,7 @@
  *
  * Snapshot 不允许替换已选集合，但不承诺把每个 Port 的内部对象深冻结。
  *
- * 正常调用顺序是 `loader → prepare → contribute → validate → guard → commit`。
- * 待确认：当前实现先校验 Plugin kind，再在 `prepare` 中调用 `loader`；这里的阶段简写是否仍应作为对外文档保留，需要与实际命名统一。
+ * 正常调用顺序是 `prepare → merge → validate → freeze → guard → commit`。
  *
  * 应用只创建 `AgentConfig` 和 Plugin。
  *
@@ -62,11 +59,13 @@ export type {
   AgentPlugin,
   AgentPluginSpec,
   PluginKind,
-  PluginLoadResult,
+  PluginPreparation,
   PreparedPlugin,
-  RuntimeContributionContext,
   RuntimeDegradation,
+  RuntimeExtensionContribution,
   RuntimeProfileContribution,
+  RuntimeSkillContribution,
+  RuntimeToolSurfacePolicy,
 } from "./plugins";
 export type { ModelOption } from "./lib/model-catalog";
 export {
@@ -105,7 +104,7 @@ export {
   browserQuickActionPiToolCandidates,
 } from "./pi/tool";
 export {
-  workspaceCodeExecutionPiToolCandidate,
+  createWorkspaceCodeExecutionPort,
 } from "./pi/tool";
 export {
   assemblePiExtensions,
@@ -119,7 +118,6 @@ export type {
   TemporaryAgentRunContext,
 } from "./layers/orchestration/temporary-agent/core";
 export {
-  bridgeTemporaryAgentToolApprovals,
   temporaryAgentExtensionIsSafe,
   temporaryAgentToolAllowed,
 } from "./layers/orchestration/temporary-agent/runner";

package/src/kernel/bindings.ts

@@ -186,6 +186,17 @@ export interface WorkspacePort {
   glob(pattern: string): Promise<WorkspaceFileInfo[]>;
 }
 
+/**
+ * 向 Runtime 提供已组装的 Workspace Code Mode 执行能力。
+ *
+ * @remarks
+ * Host Adapter 负责绑定 Durable Object、Worker Loader、网络出口和
+ * Workspace；Tool Surface 只把这个已授权 Port 转成 `execute` Tool。
+ */
+export interface RuntimeCodeExecutionPort {
+  execute(input: { code: string }): Promise<unknown>;
+}
+
 /**
  * 汇总一个已限定作用域的 Workspace 用量。
  *
@@ -540,6 +551,14 @@ export interface RuntimeScheduleUpdate {
   tz?: string;
 }
 
+/** 定时任务可切换到的已授权 User Agent 摘要。 */
+export interface RuntimeScheduleAgentSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  isDefault: boolean;
+}
+
 /**
  * 让 Runtime 通过 Host 管理当前用户的定时任务。
  *
@@ -573,6 +592,10 @@ export interface RuntimeSchedulePort {
   ): Promise<{ ok: boolean }>;
   pause(id: string): Promise<{ ok: boolean }>;
   resume(id: string): Promise<{ ok: boolean }>;
+  /** 列出当前用户可用于执行定时任务的 User Agent。 */
+  listAgents(): Promise<RuntimeScheduleAgentSummary[]>;
+  /** 更换一条定时任务的执行 Agent。 */
+  changeAgent(id: string, userAgentId: string): Promise<{ ok: boolean }>;
   /**
    * 按 ID 取消一条定时任务。
    *
@@ -786,7 +809,7 @@ export interface RuntimeModelEndpoint {
  * 向 Runtime 提供本次装配可用的模型端点。
  *
  * @remarks
- * Provider Plugin 贡献它，Builder 在提交前校验，Pi Adapter 在激活与每次解析模型时读取。
+ * Provider Plugin 准备它，Builder 在提交前校验，Pi Adapter 在激活与每次解析模型时读取。
  *
  * Runtime 只依赖已解析结果，不知道环境变量或业务模型配置的来源。
  */
@@ -800,7 +823,7 @@ export interface RuntimeProviderPort {
  * 向 Runtime 提供 Cloudflare 执行平台上的可授权能力。
  *
  * @remarks
- * Platform Plugin 贡献它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
+ * Platform Plugin 准备它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
  *
  * Worker Loader 与网络出口由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
  */
@@ -853,7 +876,7 @@ export interface RuntimeSkillBindings {
  * 限定一个 Skill 脚本可使用的网络、Workspace 和工具。
  *
  * @remarks
- * Skill Plugin 在贡献来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
+ * Skill Plugin 在准备来源时设置，Pi Skill 工具在决定是否注入脚本执行能力时读取。
  *
  * 这是已授权结果，执行期不应为某个 Skill 自动放宽。
  */

package/src/kernel/extensions.ts

@@ -43,7 +43,7 @@ export interface RuntimeExtensionContextDefinition {
  * 把 Extension 的 manifest 与待加载源码放在同一份配置里。
  *
  * @remarks
- * extension Plugin 在贡献阶段提供它，Pi Extension 适配器在候选 Runtime 装配时加载。
+ * extension Plugin 在准备结果中提供它，Pi Extension 适配器在候选 Runtime 装配时加载。
  *
  * manifest 与源码一起传递，可避免授权信息与实际执行代码在不同查找步骤中错位。
  *

package/src/kernel/profile.ts

@@ -22,7 +22,7 @@ export type ThinkingEffort =
  * 保存一次装配选定的内存开关与上下文预算。
  *
  * @remarks
- * memory Plugin 在贡献阶段提供它，Runtime 在构建上下文和触发压缩时读取。
+ * memory Plugin 在准备结果中提供它，Runtime 在构建上下文时读取。
  *
  * 预算与开关放在同一个 Profile 中，确保一次 Snapshot 只使用一套内存配置。
  *
@@ -32,14 +32,13 @@ export interface RuntimeMemoryProfile {
   enabled: boolean;
   memoryTokens: number;
   preferencesTokens: number;
-  compactAfterTokens: number;
 }
 
 /**
  * 指明本次装配允许连接的一个 MCP 服务。
  *
  * @remarks
- * connector Plugin 在贡献阶段加入它，Pi 工具装配只选择 Host 已就绪且 URL 匹配的连接。
+ * connector Plugin 在准备结果中加入它，Pi 工具装配只选择 Host 已就绪且 URL 匹配的连接。
  *
  * 这里只保留名称和 URL；连接生命周期、凭据与重试仍由 Host 管理。
  *
@@ -71,7 +70,7 @@ export interface RuntimeDenyPolicy {
  * 保存一次装配中真正会影响执行的参数。
  *
  * @remarks
- * `RuntimeBuilder` 在所有 Plugin 贡献完成后生成它，Kernel 只通过已提交的 Snapshot 读取。
+ * `RuntimeBuilder` 在所有 Plugin 声明合并完成后生成它，Kernel 只通过已提交的 Snapshot 读取。
  *
  * 它不包含业务身份、归属键或存储地址，因为这些选择属于 Host，不应被冻结成执行参数。
  *

package/src/layers/orchestration/temporary-agent/runner.ts

@@ -1,9 +1,4 @@
 import type { RuntimeExtensionConfig } from "../../../kernel/extensions";
-import {
-  requiresExecutionApproval,
-  type ExecutionLevel,
-} from "../../../lib/execution-level";
-import type { PiToolCandidate } from "../../../pi/tool/compiler";
 
 const BLOCKED_TOOLS = new Set([
   "dispatch_background",
@@ -46,66 +41,6 @@ export function temporaryAgentToolAllowed(
   );
 }
 
-/**
- * 给临时 Agent 里需要审批的 Tool 包上父 Session 审批。
- *
- * @remarks
- * 宿主在筛完 Tool 候选项后调用；返回的候选项可直接交给临时 Agent 的 Pi Tool 编译流程。
- *
- * 包装层先按父 Agent 的执行档位请求批准，然后才调原 `execute`；审批完成后把包装候选降为 `safe`，避免临时 Agent 重复审批。
- *
- * Runtime、Session 和 Tool 的术语见 `src/index.ts`。
- */
-export function bridgeTemporaryAgentToolApprovals(
-  candidates: readonly PiToolCandidate[],
-  executionLevel: ExecutionLevel,
-  requestApproval: (request: {
-    toolName: string;
-    executionLevel: ExecutionLevel;
-    requiredExecutionLevel: ExecutionLevel;
-    input: unknown;
-    toolCallId: string;
-    signal: AbortSignal;
-  }) => Promise<void>,
-): PiToolCandidate[] {
-  return candidates.map((candidate) => {
-    if (!requiresExecutionApproval(
-      executionLevel,
-      candidate.requiredExecutionLevel,
-    )) {
-      return candidate;
-    }
-    const execute = candidate.tool.execute;
-    return {
-      ...candidate,
-      requiredExecutionLevel: "safe",
-      tool: {
-        ...candidate.tool,
-        // 作用：在执行原 Tool 前向父 Session 请求审批。
-        // 调用：Pi Tool 执行器调用，参数和进度回调原样传给原 Tool。
-        // 原因：某些调用方不传 signal，但审批契约需要一个 `AbortSignal`，因此只在缺失时创建一个不会自行取消的信号。
-        async execute(toolCallId, input, signal, onUpdate) {
-          const activeSignal = signal ?? new AbortController().signal;
-          await requestApproval({
-            toolName: candidate.tool.name,
-            executionLevel,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
-            input,
-            toolCallId,
-            signal: activeSignal,
-          });
-          return execute(
-            toolCallId,
-            input,
-            activeSignal,
-            onUpdate,
-          );
-        },
-      },
-    };
-  });
-}
-
 /**
  * 判断一个 Extension 是否安全到可以交给临时 Agent。
  *

package/src/pi/assembly/context.ts

@@ -116,7 +116,7 @@ export async function compactPiContext(input: Readonly<{
     const settings = DEFAULT_COMPACTION_SETTINGS;
     if (
       !settings.enabled ||
-      estimateContextTokens(currentMessages).tokens <=
+      estimateContextTokens(currentMessages).tokens <
         input.compactAfterTokens
     ) {
       return {
@@ -479,7 +479,6 @@ export async function assemblePiSystemContext(input: Readonly<{
   ) => Promise<string | null>;
 }>): Promise<Readonly<{
   systemPrompt: string;
-  compactAfterTokens: number;
   degradations: readonly RuntimeDegradation[];
 }>> {
   const [memory, extensions] = await Promise.all([
@@ -499,7 +498,6 @@ export async function assemblePiSystemContext(input: Readonly<{
 
   return Object.freeze({
     systemPrompt: parts.join("\n\n"),
-    compactAfterTokens: input.memory.compactAfterTokens,
     degradations: Object.freeze([
       ...memory.degradations,
       ...extensions.degradations,

package/src/pi/assembly/snapshot.ts

@@ -16,13 +16,22 @@ import { assembleSystemPrompt } from "../../lib/prompt";
 import { resolvePiModel } from "../runtime-adapter/models";
 import type { PiToolCandidate } from "../tool/compiler";
 
+/**
+ * 收集完动态 Extension/MCP 候选后，一次性生成最终 Tool Surface。
+ */
+export interface PiToolSurface {
+  finalize(
+    authorizedCandidates: readonly PiToolCandidate[],
+  ): readonly PiToolCandidate[];
+}
+
 /** Immutable inputs consumed directly by Pi Agent Core. */
 export interface PiRuntimeAssembly {
   readonly model: Model<Api>;
   readonly thinkingLevel: ThinkingLevel;
   readonly systemPrompt: string;
   readonly messages: readonly AgentMessage[];
-  readonly toolCandidates: readonly PiToolCandidate[];
+  readonly toolSurface: PiToolSurface;
   readonly mcpServers: readonly RuntimeMcpServer[];
   readonly extensions: readonly RuntimeExtensionConfig[];
 }
@@ -34,7 +43,7 @@ interface PiRuntimeAssemblyInput {
   >;
   readonly provider: RuntimeProviderPort;
   readonly messages?: readonly AgentMessage[];
-  readonly toolCandidates: readonly PiToolCandidate[];
+  readonly toolSurface: PiToolSurface;
   readonly mcpServers: readonly RuntimeMcpServer[];
   readonly extensions: readonly RuntimeExtensionConfig[];
 }
@@ -172,15 +181,11 @@ export function createPiRuntimeAssembly(
   input: PiRuntimeAssemblyInput,
 ): PiRuntimeAssembly {
   const messages = [...(input.messages ?? [])];
-  const toolCandidates = input.toolCandidates.map(
-    (candidate) => Object.freeze({ ...candidate }),
-  );
   const mcpServers = input.mcpServers.map(
     (server) => Object.freeze({ ...server }),
   );
   const extensions = input.extensions.map(freezeExtension);
   Object.freeze(messages);
-  Object.freeze(toolCandidates);
   Object.freeze(mcpServers);
   Object.freeze(extensions);
 
@@ -193,7 +198,7 @@ export function createPiRuntimeAssembly(
       input.profile.systemPrompt,
     ),
     messages,
-    toolCandidates,
+    toolSurface: input.toolSurface,
     mcpServers,
     extensions,
   });

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

@@ -19,7 +19,6 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
-  compilePiTools,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -41,7 +40,7 @@ import {
 interface PiAssemblySnapshot {
   readonly pi: Pick<
     PiRuntimeAssembly,
-    "extensions" | "toolCandidates"
+    "extensions" | "toolSurface"
   >;
   readonly profile: Pick<
     RuntimeProfile,
@@ -75,10 +74,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  // 生成当前可供 Pi 编译的完整工具候选列表。
-  // preparePiAssembly 用它预检，preparePiRuntime 再读取并冻结最终列表。
-  // MCP 就绪状态由 Host 提供，因此这里不能只拼接初始化时的静态数组。
-  toolCandidates(): PiToolCandidate[];
+  readonly candidates: readonly PiToolCandidate[];
 }
 
 /**
@@ -391,54 +387,7 @@ export function readPinnedPiRuntime(
 
 // #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,
-      ),
-    ];
-  }
-}
-
-// 加载已启用扩展，并确认汇总后的工具可以正常编译。
+// 加载已启用扩展，并把 Extension/MCP 候选交给唯一 Tool Surface 最终化。
 // preparePiRuntime 为每份待配置的 Runtime 快照调用它一次。
 // 工作区能力在共享加载边界校验，单个扩展加载失败则保留为降级结果。
 async function preparePiAssembly(
@@ -469,18 +418,19 @@ async function preparePiAssembly(
       });
     },
   });
-  const prepared = new PreparedAssembly(
-    snapshot,
-    extensions,
-    options.mcpHost,
-  );
-  // 待确认：MCP 就绪状态可能在下一次 toolCandidates() 前改变，
-  // 因而最终冻结的候选可能与这里校验的集合不同。
-  compilePiTools(prepared.toolCandidates(), {
-    deny: snapshot.profile.denyPolicy?.deny,
-    settle: () => undefined,
+  return Object.freeze({
+    loaded: extensions.loaded,
+    context: extensions.context,
+    degradations: extensions.degradations,
+    candidates: snapshot.pi.toolSurface.finalize([
+      ...extensions.candidates,
+      listExtensionsPiToolCandidate(extensions.loaded),
+      ...createPiMcpToolCandidates(
+        options.mcpHost,
+        snapshot.profile.mcpServers,
+      ),
+    ]),
   });
-  return prepared;
 }
 
 // #endregion
@@ -500,7 +450,7 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.toolCandidates();
+  const candidates = assembly.candidates;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([

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

@@ -34,6 +34,8 @@ import { resolvePiApiKey, withProviderRetry } from "./models";
 
 // #region Single-run Pi bridge
 
+const MAX_MODEL_TURNS = 30;
+
 /**
  * 把 Pi 的终止原因翻译成本仓的回合结局。
  *
@@ -81,7 +83,6 @@ interface PiTurnAdapterOptions {
   // PiTurnAdapter.run 在创建 PiCore 前调用它，宿主应返回当时最新的 transcript。
   // 这里保留为延迟读取，是为了避免适配器创建后新增的恢复消息被旧快照漏掉。
   readonly canonicalMessages: () => Promise<readonly AgentMessage[]>;
-  readonly denyTools?: readonly string[];
   // 把工具的最终结果交回宿主持久化。
   // 共享工具编译器在向 Pi 返回成功或规范化失败前调用它。
   // 这个先落库再发布结果的顺序是恢复边界，不能改成事后异步补写。
@@ -113,10 +114,9 @@ class PiTurnAdapter {
 
   // 把 Tool candidate 变成 Pi 可以执行的受治理 Tool。
   // 正常运行会编译 Pinned Runtime 的整份列表，恢复时只编译指定 Tool candidate。
-  // 拒绝规则、重名检查、输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
+  // 输出限额和持久化结算统一走共享编译器，避免恢复另开旁路。
   private compile(candidates: readonly PiToolCandidate[]) {
     return compilePiTools(candidates, {
-      deny: this.opts.denyTools,
       governance: this.governance,
       settle: this.opts.settle,
     });
@@ -162,11 +162,13 @@ class PiTurnAdapter {
       readonly signal?: AbortSignal;
     },
     listener: (event: AgentEvent) => void | Promise<void>,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const { systemPrompt, signal } = opts;
     signal?.throwIfAborted();
     const canonicalMessages = await this.opts.canonicalMessages();
     const tools = this.compile(opts.tools);
+    let modelTurns = 0;
+    let reachedModelTurnLimit = false;
     const pi = new PiCore({
       convertToLlm,
       streamFn: withProviderRetry(
@@ -175,6 +177,10 @@ class PiTurnAdapter {
       getApiKey: () => this.opts.apiKey,
       transformContext: this.opts.transformContext,
       afterToolCall: this.governance.afterToolCall,
+      shouldStopAfterTurn: () => {
+        reachedModelTurnLimit = ++modelTurns >= MAX_MODEL_TURNS;
+        return signal?.aborted === true || reachedModelTurnLimit;
+      },
       initialState: {
         model: this.opts.pi.model,
         systemPrompt,
@@ -203,6 +209,7 @@ class PiTurnAdapter {
         pi.abort();
       }
       await running;
+      return reachedModelTurnLimit;
     } finally {
       signal?.removeEventListener("abort", abort);
       unsubscribe();
@@ -524,7 +531,6 @@ export class PreparedPiTurnAdapter {
         state.snapshot.pi.model.id,
       ),
       canonicalMessages: options.canonicalMessages,
-      denyTools: descriptor.deny,
       settle: options.durability.settleTool,
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
@@ -597,7 +603,7 @@ export class PreparedPiTurnAdapter {
     options: PiPreparedTurnRunOptions,
   ): Promise<void> {
     this.terminalIntent = undefined;
-    await this.turn.run(
+    const reachedModelTurnLimit = await this.turn.run(
       {
         systemPrompt: this.systemPrompt,
         tools: this.candidates,
@@ -605,6 +611,12 @@ export class PreparedPiTurnAdapter {
       },
       (event) => this.handleEvent(event),
     );
+    if (reachedModelTurnLimit && !this.terminalIntent) {
+      this.terminalIntent = {
+        outcome: "failed",
+        message: `Pi stopped after ${MAX_MODEL_TURNS} model turns`,
+      };
+    }
     if (this.terminalIntent) {
       await this.options.onTerminal(this.terminalIntent);
     }

package/src/pi/tool/compiler.ts

@@ -6,7 +6,6 @@ import type {
 import type { ApprovalReceipt } from "../../kernel/receipts";
 import { boundDurableToolOutput } from "../../layers/context/budget/gate";
 import {
-  EXECUTION_LEVELS,
   type ExecutionLevel,
 } from "../../lib/execution-level";
 
@@ -14,7 +13,7 @@ import {
 
 // #region Public contracts
 
-/** 描述一个尚未经过去重、禁用规则和结算包装的 Pi 工具。 */
+/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
 export interface PiToolCandidate {
   readonly owner: string;
   readonly authorized: boolean;
@@ -26,7 +25,6 @@ export interface PiToolCandidate {
 
 /** 控制候选 Pi 工具如何被编译为可执行工具集。 */
 export interface CompilePiToolsOptions {
-  readonly deny?: readonly string[];
   readonly governance?: PiToolGovernance;
   readonly settle: (
     call: SettledPiToolCall,
@@ -248,7 +246,7 @@ export function createPiToolGovernance(
 }
 
 // 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
-// `compilePiTools()` 对通过授权和 deny 筛选的每个候选项调用。
+// `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
 // 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
 function governedTool(
   candidate: PiToolCandidate,
@@ -402,11 +400,9 @@ function governedTool(
 }
 
 /**
- * 把已授权且未被禁用的 Pi 工具候选项编译成可执行工具集。
+ * 把已经 Tool Surface 最终化的候选项包成可执行工具集。
  *
- * Runtime 组装层在启动前用它验证工具集，`PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行包装。
- *
- * 工具名是模型调用和结算的唯一键，所以冲突必须在组装时失败，不能用后来者静默覆盖。
+ * `PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行治理包装。
  */
 export function compilePiTools(
   candidates: readonly PiToolCandidate[],
@@ -415,30 +411,7 @@ export function compilePiTools(
   if (!options?.settle) {
     throw new Error("Pi Tool settlement port is required");
   }
-  const deny = new Set(options.deny ?? []);
-  const tools: AgentTool<any, any>[] = [];
-  const owners = new Map<string, string>();
-
-  for (const candidate of candidates) {
-    if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
-      throw new Error(
-        `Pi Tool "${candidate.tool.name}" has invalid requiredExecutionLevel`,
-      );
-    }
-    if (!candidate.authorized || deny.has(candidate.tool.name)) continue;
-
-    const existingOwner = owners.get(candidate.tool.name);
-    if (existingOwner !== undefined) {
-      throw new Error(
-        `duplicate tool key "${candidate.tool.name}" (${candidate.owner} collides with ${existingOwner})`,
-      );
-    }
-
-    owners.set(candidate.tool.name, candidate.owner);
-    tools.push(governedTool(candidate, options));
-  }
-
-  return tools;
+  return candidates.map((candidate) => governedTool(candidate, options));
 }
 
 // #endregion

package/src/pi/tool/core-host.ts

@@ -8,27 +8,28 @@ import {
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
 import { StateConnector } from "@cloudflare/shell/workers";
-import type { WorkspacePort } from "../../kernel/bindings";
-import { codeExecutionPiToolCandidate } from "./core";
-import type { PiToolCandidate } from "./compiler";
+import type {
+  RuntimeCodeExecutionPort,
+  WorkspacePort,
+} from "../../kernel/bindings";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
 
 /**
- * 把宿主的 Worker Loader、出站网络和 Workspace 组装成 Pi 代码执行工具候选项。
+ * 把宿主的 Worker Loader、出站网络和 Workspace 组装成代码执行 Port。
  *
  * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
  *
  * Cloudflare Codemode 把持久化 Runtime 和无状态 Dynamic Worker executor 分开；这里必须用 StateConnector 显式注入已限定范围的 Workspace，并在返回模型前用官方 `truncateResult` 限制结果。
  */
-export function workspaceCodeExecutionPiToolCandidate(options: {
+export function createWorkspaceCodeExecutionPort(options: {
   readonly ctx: DurableObjectState;
   readonly loader: WorkerLoader;
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
-}): PiToolCandidate {
+}): RuntimeCodeExecutionPort {
   const runtime = createCodemodeRuntime({
     ctx: options.ctx,
     executor: new DynamicWorkerExecutor({
@@ -48,5 +49,7 @@ export function workspaceCodeExecutionPiToolCandidate(options: {
     name: "execute",
     transformResult: truncateResult,
   });
-  return codeExecutionPiToolCandidate(runtime);
+  return {
+    execute: (input) => runtime.execute(input),
+  };
 }