@springbrand/agent-runtime 0.2.0-alpha.34 → 0.2.0-alpha.36

package/package.json

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

package/src/adapter/cloudflare/index.ts

@@ -13,7 +13,6 @@ export {
 } from "./universal-agent/preparation";
 export {
   assembleUniversalAgentTools,
-  selectTools,
 } from "./universal-agent/tools";
 export { createUniversalAgentHooks } from "./universal-agent/hooks";
 

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -8,31 +8,18 @@ import type {
 import type { RuntimeDegradation } from "../../../kernel/degradation";
 import type { RuntimeMemoryProfile } from "../../../kernel/profile";
 import type { WorkspaceRevisionRestorePort } from "../../../workspace-versioning";
-import { createScheduleTools } from "../../../pi/tool/schedule";
-import { createWorkspaceRevisionTools } from "../../../pi/tool/workspace-revision";
+import { schedulePiToolCandidates } from "../../../pi/tool/schedule";
+import { workspaceRevisionPiToolCandidate } from "../../../pi/tool/workspace-revision";
 import {
-  createSandboxTools,
-  createWorkspaceTools,
+  sandboxPiToolCandidates,
+  workspacePiToolCandidates,
 } from "../../../pi/tool/workspace-sandbox";
-import {
-  mergeToolRegistries,
-  type RuntimeCodeExecutionFactory,
-  type ToolAssemblyResult,
-  type ToolRegistry,
-} from "../../../tool-registry";
-
-export function selectTools(
-  tools: ToolRegistry,
-  names: Iterable<string>,
-): ToolRegistry {
-  const selected = new Set(names);
-  return Object.fromEntries(
-    Object.entries(tools).filter(([name]) => selected.has(name)),
-  );
-}
+import type { RuntimeCodeExecutionFactory } from "../../../kernel/bindings";
+import type { ToolAssemblyResult } from "../../../runtime-definition";
+import type { PiToolCandidate } from "../../../pi/tool/compiler";
 
 export function assembleUniversalAgentTools(options: {
-  hostTools?: ToolRegistry;
+  hostTools?: readonly PiToolCandidate[];
   workspace?: WorkspacePort;
   workspaceRevisions?: WorkspaceRevisionRestorePort;
   codeExecution?: RuntimeCodeExecutionFactory;
@@ -45,15 +32,15 @@ export function assembleUniversalAgentTools(options: {
   degradations?: readonly RuntimeDegradation[];
   dispose?: () => Promise<void>;
 }): ToolAssemblyResult {
-  const tools = mergeToolRegistries(
-    options.hostTools ?? {},
-    options.workspace ? createWorkspaceTools(options.workspace) : {},
-    options.workspaceRevisions
-      ? createWorkspaceRevisionTools(options.workspaceRevisions)
-      : {},
-    options.sandbox ? createSandboxTools(options.sandbox) : {},
-    options.schedule ? createScheduleTools(options.schedule) : {},
-  );
+  const tools = [
+    ...(options.hostTools ?? []),
+    ...(options.workspace ? workspacePiToolCandidates(options.workspace) : []),
+    ...(options.workspaceRevisions
+      ? [workspaceRevisionPiToolCandidate(options.workspaceRevisions)]
+      : []),
+    ...(options.sandbox ? sandboxPiToolCandidates(options.sandbox) : []),
+    ...(options.schedule ? schedulePiToolCandidates(options.schedule) : []),
+  ];
 
   return {
     tools,

package/src/index.ts

@@ -23,7 +23,7 @@
  * - `canonical transcript` 是 Pi 持久化和恢复 Turn 时使用的权威消息历史。
  * - `admission` 是提示进入 Turn 前的接纳、去重和状态登记流程。
  * - `defineRuntimeAgent.load` 返回 config 和已加载 Resource。
- * - `defineRuntimeAgent.tools` 是 Host 第一层 Tool 注册表声明。
+ * - `defineRuntimeAgent.tools` 返回 Host 的 Pi Tool Candidate 装配结果。
  * - `assembleRuntimeSnapshot` 消费该输入与 hooks，产出候选 Snapshot。
  * - `Port` 是 Runtime 调用外部能力时依赖的最小接口（Definition 作者不直接装配）。
  * - `RuntimeBindings` 是本次装配选中的 Port 和可执行对象集合。
@@ -61,11 +61,8 @@ export type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-assembler";
-export { assembleRuntimeSnapshot, toolRegistryPiToolCandidates } from "./runtime-assembler";
+export { assembleRuntimeSnapshot } from "./runtime-assembler";
 export type {
-  PlatformToolContext,
-  PlatformToolRegistry,
-  PlatformToolSpec,
   ProfileOverrides,
   ResolvedConnectors,
   ResolvedResources,
@@ -74,20 +71,8 @@ export type {
   RuntimeSettings,
   RuntimeToolBindings,
   ToolAssemblyResult,
-  ToolContext,
-  ToolRegistry,
-  ToolSpec,
 } from "./runtime-definition";
-export {
-  emptyPlatformToolRegistry,
-  emptyToolRegistry,
-  mergeToolRegistries,
-  normalizeToolAssembly,
-  piCandidateToToolSpec,
-  toolRegistryFromPiCandidates,
-} from "./tool-registry";
 export type { ModelOption } from "./lib/model-catalog";
-export type { RuntimeCodeExecutionFactory } from "./tool-registry";
 export {
   assembleSubagentPrompt,
   assembleSystemPrompt,
@@ -118,26 +103,14 @@ export type {
   PiDeclaredToolCallContext,
   PiDeclaredToolPolicy,
 } from "./pi/tool";
+export { memoryPiToolCandidate } from "./pi/tool";
+export { schedulePiToolCandidates } from "./pi/tool";
 export {
-  createMemoryTools,
-  memoryPiToolCandidate,
-} from "./pi/tool";
-export {
-  createScheduleTools,
-  schedulePiToolCandidates,
-} from "./pi/tool";
-export {
-  createSandboxTools,
-  createWorkspaceRevisionTools,
-  createWorkspaceTools,
   sandboxPiToolCandidates,
   workspaceRevisionPiToolCandidate,
   workspacePiToolCandidates,
 } from "./pi/tool";
-export {
-  createSubagentTools,
-  subagentPiToolCandidates,
-} from "./pi/tool";
+export { subagentPiToolCandidates } from "./pi/tool";
 export { skillPiToolCandidates } from "./pi/tool";
 export type { PiSkillBinding } from "./pi/tool";
 export {

package/src/kernel/bindings.ts

@@ -2,7 +2,8 @@ import type { SkillSource } from "agents/skills";
 import type { ScheduleSpec } from "./receipts";
 import type { RuntimeActivityProjection } from "./state";
 import type { ExecutionLevel } from "../lib/execution-level";
-import type { ToolRegistry } from "./tool-surface";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolCandidate } from "../pi/tool/compiler";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -213,7 +214,7 @@ export interface WorkspacePort {
  */
 export interface RuntimeCodeExecutionPort {
   readonly description: string;
-  execute(input: { code: string }): Promise<unknown>;
+  execute(input: { code: string }): Promise<AgentToolResult<unknown>>;
 }
 
 /**
@@ -1022,12 +1023,11 @@ export interface RuntimeSkillSourceBinding {
  * 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。
  *
  * @remarks
- * 定义在这里而不是 `tool-registry.ts`：它的返回类型是本文件的
- * `RuntimeCodeExecutionPort`，而 `RuntimeBindings` 又要引用这个工厂 —— 放在
- * tool-registry 会让两个模块互相 import。`tool-registry.ts` 继续对外导出它。
+ * 工厂与返回 Port 同住 Host 绑定边界；输入直接使用最终 Pi Tool candidates，
+ * 不再经过 Registry 或另一份 Tool 元数据协议。
  */
 export interface RuntimeCodeExecutionFactory {
-  create(tools: ToolRegistry): RuntimeCodeExecutionPort;
+  create(candidates: readonly PiToolCandidate[]): RuntimeCodeExecutionPort;
 }
 
 export interface RuntimeBindings {

package/src/pi/assembly/extensions.ts

@@ -3,7 +3,6 @@ import {
   type ExtensionManifest,
   type ExtensionPermissions,
 } from "@cloudflare/think/extensions";
-import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { asSchema } from "ai";
 import type {
   LoadedRuntimeExtension,
@@ -14,6 +13,7 @@ import type { RuntimeDegradation } from "../../kernel/degradation";
 import { withRuntimeLoadTimeout } from "../../kernel/runtime-load";
 import { sanitizeExtensionName } from "../../lib/extension-name";
 import type { PiToolCandidate } from "../tool/compiler";
+import { createPiDeclaredToolCandidate } from "../tool/declared";
 
 export interface PiExtensionContextContribution {
   readonly extensionName: string;
@@ -563,45 +563,30 @@ export async function assemblePiExtensions({
       const toolName = `${prefix}_${descriptor.name}`;
       toolNames.push(toolName);
       const description = `[${name}] ${descriptor.description}`;
-      // 作用：把 Extension 的原始执行结果包装成 Pi Agent Core 的 Tool 结果。
-      // 调用：编译后的共享 Tool 调度器在模型发起该 Extension Tool 时调用。
-      // 原因：所有 Extension 结果在这个边界统一变成 text content，同时在 details 保留未损失的原值。
-      const execute: AgentTool<any, {
-        extension: string;
-        result: unknown;
-      }>["execute"] = async (_toolCallId, params, signal) => {
-        const result = await loaded.execute(
+      const candidate = createPiDeclaredToolCandidate(
+        {
+          name: descriptor.name,
+          title: `${name}: ${descriptor.name}`,
+          description,
+          inputSchema: descriptor.inputSchema,
+        },
+        (input, { signal }) => loaded.execute(
           descriptor.name,
-          params as Readonly<Record<string, unknown>>,
+          input,
           signal,
-        );
-        return {
-          content: [{
-            type: "text" as const,
-            text: resultText(result),
-          }],
-          details: {
-            extension: name,
-            result,
-          },
-        };
-      };
-      const tool: AgentTool<any, {
-        extension: string;
-        result: unknown;
-      }> = Object.freeze({
-        name: toolName,
-        label: `${name}: ${descriptor.name}`,
-        description,
-        parameters: descriptor.inputSchema as AgentTool["parameters"],
-        execute,
-      });
-      candidates.push(Object.freeze({
-        owner: `extension:${name}@${extension.manifest.version}`,
-        requiredExecutionLevel,
-        summary: description,
-        tool,
-      }));
+        ),
+        {
+          owner: `extension:${name}@${extension.manifest.version}`,
+          modelName: toolName,
+          requiredExecutionLevel,
+          summary: description,
+          project: (result) => ({
+            content: [{ type: "text", text: resultText(result) }],
+            details: { extension: name, result },
+          }),
+        },
+      );
+      candidates.push(Object.freeze({ ...candidate, requiredExecutionLevel }));
     }
     loadedExtensions.push(Object.freeze({
       name,

package/src/pi/assembly/snapshot.ts

@@ -23,7 +23,13 @@ import type { PiToolCandidate } from "../tool/compiler";
 export interface PiToolSurface {
   finalize(
     candidates: readonly PiToolCandidate[],
-  ): readonly PiToolCandidate[];
+  ): FinalizedPiToolSurface;
+}
+
+/** Internal finalization output; not a second Tool protocol. */
+export interface FinalizedPiToolSurface {
+  readonly candidates: readonly PiToolCandidate[];
+  readonly codeExecutionCandidates: readonly PiToolCandidate[];
 }
 
 /** Immutable inputs consumed directly by Pi Agent Core. */

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

@@ -10,7 +10,7 @@ import type {
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
 import type { RuntimeSnapshot } from "../../runtime-assembler";
-import type { PiRuntimeAssembly } from "../assembly";
+import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
   assemblePiExtensions,
@@ -77,7 +77,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  readonly candidates: readonly PiToolCandidate[];
+  readonly toolSurface: FinalizedPiToolSurface;
 }
 
 /**
@@ -193,6 +193,7 @@ export interface PreparedPiRuntimeState {
   readonly snapshot: RuntimeSnapshot;
   readonly assembly: PreparedPiAssembly;
   readonly candidates: readonly PiToolCandidate[];
+  readonly codeExecutionCandidates: readonly PiToolCandidate[];
 }
 
 // #endregion
@@ -411,21 +412,22 @@ async function preparePiAssembly(
       });
     },
   });
+  const toolSurface = snapshot.pi.toolSurface.finalize([
+    ...extensions.candidates,
+    listExtensionsPiToolCandidate(extensions.loaded),
+    ...(options.gatewaySession
+      ? createPiGatewayToolCandidates(options.gatewaySession)
+      : []),
+    ...createPiMcpToolCandidates(
+      options.mcpHost,
+      snapshot.profile.mcpServers,
+    ),
+  ]);
   return Object.freeze({
     loaded: extensions.loaded,
     context: extensions.context,
     degradations: extensions.degradations,
-    candidates: snapshot.pi.toolSurface.finalize([
-      ...extensions.candidates,
-      listExtensionsPiToolCandidate(extensions.loaded),
-      ...(options.gatewaySession
-        ? createPiGatewayToolCandidates(options.gatewaySession)
-        : []),
-      ...createPiMcpToolCandidates(
-        options.mcpHost,
-        snapshot.profile.mcpServers,
-      ),
-    ]),
+    toolSurface,
   });
 }
 
@@ -446,7 +448,7 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.candidates;
+  const candidates = assembly.toolSurface.candidates;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
@@ -460,6 +462,9 @@ export async function preparePiRuntime(
       snapshot: options.snapshot,
       assembly,
       candidates: Object.freeze([...candidates]),
+      codeExecutionCandidates: Object.freeze([
+        ...assembly.toolSurface.codeExecutionCandidates,
+      ]),
     }),
   ));
 }

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

@@ -49,7 +49,6 @@ import {
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
 import { projectToolOutputForModel } from "../../layers/context/budget/gate";
 import type { SpillWorkspace } from "../../lib/artifacts";
-import { toolRegistryFromPiCandidates } from "../../tool-registry";
 
 // #region Single-run Pi bridge
 
@@ -816,7 +815,7 @@ export class PreparedPiTurnAdapter {
       },
     });
     this.candidates = state.candidates.map((candidate) => {
-      if (!candidate.codeExecutionTools) return bindCandidate(candidate);
+      if (candidate.tool.name !== "execute") return bindCandidate(candidate);
       const factory = state.snapshot.bindings.codeExecution;
       if (!factory) {
         throw new Error("Prepared Code Mode Tool requires a Runtime factory");
@@ -827,14 +826,12 @@ export class PreparedPiTurnAdapter {
           ...candidate.tool,
           execute: (toolCallId, input, signal, onUpdate) => {
             const runtimeCandidate = codeExecutionPiToolCandidate(
-              factory.create(toolRegistryFromPiCandidates(
-                candidate.codeExecutionTools!.map((inner) =>
-                  // Code Mode owns replay of its connector calls. Pi persists
-                  // only the parent execute attempt/result; recording an inner
-                  // input without a Pi settlement creates an orphan recovery
-                  // action that cannot be found on the direct Tool surface.
-                  bindCandidate(inner, toolCallId, false)
-                ),
+              factory.create(state.codeExecutionCandidates.map((inner) =>
+                // Code Mode owns replay of its connector calls. Pi persists
+                // only the parent execute attempt/result; recording an inner
+                // input without a Pi settlement creates an orphan recovery
+                // action that cannot be found on the direct Tool surface.
+                bindCandidate(inner, toolCallId, false)
               )),
             );
             return runtimeCandidate.tool.execute(

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

@@ -15,7 +15,10 @@ import {
   type PiToolRecoveryState,
 } from "../turn";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import {
+  createToolResultMessage,
+  type AgentToolResult,
+} from "@earendil-works/pi-agent-core";
 import { isEqual } from "lodash-es";
 import {
   aiSdkRecoveryCodec,
@@ -34,12 +37,8 @@ export interface PiRecoveryIdentity {
 }
 
 export interface PiRecoveredToolSettlement {
-  readonly toolCallId: string;
-  readonly toolName: string;
   readonly args: unknown;
-  readonly result: Omit<AgentToolResult<unknown>, "terminate">;
-  readonly isError: boolean;
-  readonly createdAt: number;
+  readonly message: ToolResultMessage;
 }
 
 export type PiRecoveryCommand =
@@ -211,21 +210,10 @@ function recoveredToolSettlements(
       (item) => item.toolCallId === toolResult.toolCallId,
     );
     return {
-      toolCallId: toolResult.toolCallId,
-      toolName: toolResult.toolName,
       args:
         tool?.input ??
         (approval ? JSON.parse(approval.inputJson) : {}),
-      result: {
-        content: toolResult.content,
-        details: toolResult.details,
-        ...(toolResult.usage ? { usage: toolResult.usage } : {}),
-        ...(toolResult.addedToolNames?.length
-          ? { addedToolNames: toolResult.addedToolNames }
-          : {}),
-      },
-      isError: toolResult.isError,
-      createdAt: toolResult.timestamp,
+      message: toolResult,
     };
   });
 }
@@ -251,14 +239,13 @@ function interactionToolResult(
   if (!interaction) {
     throw new Error("SpringBrand Tool interaction is missing for its response");
   }
-  return {
-    ...result,
-    role: "toolResult",
+  return createToolResultMessage({
     toolCallId: interaction.toolCallId,
     toolName: interaction.toolName,
+    result,
     isError: false,
     timestamp,
-  };
+  });
 }
 
 // 把纯恢复计划翻译成持久化操作和 Runtime 下一步动作。
@@ -441,9 +428,9 @@ export function decidePiRecovery(
     const existing = state.toolCalls[record.toolCallId];
     if (existing) {
       if (
-      existing.toolName !== record.toolName ||
-      existing.retry !== record.retry ||
-      !isEqual(existing.input, record.input)
+        existing.toolName !== record.toolName ||
+        existing.retry !== record.retry ||
+        !isEqual(existing.input, record.input)
       ) {
         throw new Error(
           `Conflicting SpringBrand Tool input for ${record.toolCallId}`,
@@ -601,19 +588,13 @@ export function decidePiRecovery(
   }
   if (input.command.kind === "record-tool-result") {
     const command = input.command;
-    const toolResult: ToolResultMessage = {
-      role: "toolResult",
+    const toolResult = createToolResultMessage({
       toolCallId: command.toolCallId,
       toolName: command.toolName,
-      content: command.result.content,
-      details: command.result.details,
-      ...(command.result.usage ? { usage: command.result.usage } : {}),
-      ...(command.result.addedToolNames?.length
-        ? { addedToolNames: command.result.addedToolNames }
-        : {}),
+      result: command.result,
       isError: command.isError,
       timestamp: command.timestamp,
-    };
+    });
     const existing = state.toolCalls[command.toolCallId]?.result;
     if (existing) {
       if (!isEqual(existing, toolResult)) {

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

@@ -344,18 +344,11 @@ export class PiRuntimeTranscript {
     settlement: PiRecoveredToolSettlement,
   ): boolean {
     return this.append(
-      `${submissionId}:tool:${settlement.toolCallId}`,
-      {
-        ...settlement.result,
-        role: "toolResult",
-        toolCallId: settlement.toolCallId,
-        toolName: settlement.toolName,
-        isError: settlement.isError,
-        timestamp: settlement.createdAt,
-      },
+      `${submissionId}:tool:${settlement.message.toolCallId}`,
+      settlement.message,
       {
         submissionId,
-        createdAt: settlement.createdAt,
+        createdAt: settlement.message.timestamp,
       },
     );
   }
@@ -383,8 +376,8 @@ export class PiRuntimeTranscript {
     }
     return [...settlements].sort(
       (left, right) =>
-        (callOrder.get(left.toolCallId) ?? Number.MAX_SAFE_INTEGER) -
-        (callOrder.get(right.toolCallId) ?? Number.MAX_SAFE_INTEGER),
+        (callOrder.get(left.message.toolCallId) ?? Number.MAX_SAFE_INTEGER) -
+        (callOrder.get(right.message.toolCallId) ?? Number.MAX_SAFE_INTEGER),
     );
   }
 

package/src/pi/tool/base.ts

@@ -8,10 +8,6 @@ import type { RuntimeMemoryPort } from "../../kernel/bindings";
 import type { RuntimeMemoryProfile } from "../../kernel/profile";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
@@ -368,14 +364,3 @@ export function memoryPiToolCandidate(
 }
 
 /** 从 Memory Port 生成 `set_context` Tool。 */
-export function createMemoryTools(
-  memory: RuntimeMemoryPort,
-  profile: Pick<
-    RuntimeMemoryProfile,
-    "memoryTokens" | "preferencesTokens"
-  >,
-): ToolRegistry {
-  return toolRegistryFromPiCandidates([
-    memoryPiToolCandidate(memory, profile),
-  ]);
-}

package/src/pi/tool/compiler.ts

@@ -52,8 +52,6 @@ export interface PiToolCandidate {
   readonly direct?: true;
   /** Offer this Tool only through Code Mode, never as a top-level Tool. */
   readonly codeExecutionOnly?: true;
-  /** @internal Tools also callable through this Code Mode candidate. */
-  readonly codeExecutionTools?: readonly PiToolCandidate[];
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
   /** Trusted parameter-level policy, evaluated before approval or dispatch. */