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

package/src/runtime-assembler.ts

@@ -29,6 +29,7 @@ import {
 } from "./lib/execution-level";
 import {
   createPiRuntimeAssembly,
+  type FinalizedPiToolSurface,
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
@@ -43,11 +44,7 @@ import type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
-import {
-  toolRegistryFromPiCandidates,
-  type RuntimeCodeExecutionFactory,
-  type ToolRegistry,
-} from "./tool-registry";
+import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
 import { withRuntimeLoadTimeout } from "./kernel/runtime-load";
 import {
   basePiToolCandidates,
@@ -198,9 +195,13 @@ async function createToolSurface(
   const classify = (candidate: PiToolCandidate): PiToolCandidate =>
     Object.freeze({
       ...candidate,
-      ...(defersTool?.(candidate.tool.name) === true
-        ? { deferLoading: true as const }
-        : { deferLoading: undefined }),
+      ...(defersTool
+        ? {
+            deferLoading: defersTool(candidate.tool.name) === true
+              ? true as const
+              : undefined,
+          }
+        : {}),
     });
   // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
   // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
@@ -267,7 +268,10 @@ async function createToolSurface(
           deny.has("execute") ||
           allowsTool?.("execute") === false
         ) {
-          return Object.freeze(directVisible.map(classify));
+          return Object.freeze({
+            candidates: Object.freeze(directVisible.map(classify)),
+            codeExecutionCandidates: Object.freeze([]),
+          }) satisfies FinalizedPiToolSurface;
         }
         const mergeable = finalized.filter(
           (candidate) =>
@@ -275,11 +279,40 @@ async function createToolSurface(
             !candidate.interaction &&
             typeof candidate.tool.execute === "function",
         );
-        const codeExecutionTools = Object.freeze([...mergeable]);
+        const codeExecutionCandidates = Object.freeze([...mergeable]);
+        const codeExecutionToolNames = new Set(
+          codeExecutionCandidates.map(({ tool }) => tool.name),
+        );
         const codeExecution = input.codeExecution.create(
-          toolRegistryFromPiCandidates(codeExecutionTools),
+          codeExecutionCandidates,
+        );
+        const topLevelOnly = directVisible.filter(
+          ({ tool }) => !codeExecutionToolNames.has(tool.name),
         );
-        const materializeGuidance = codeExecutionTools.some(
+        const routeList = (deferred: boolean) => {
+          const matches = topLevelOnly.filter((candidate) =>
+            (defersTool?.(candidate.tool.name) === true) === deferred
+          );
+          return matches.length > 0
+            ? matches.map(({ tool }) =>
+                `- \`${tool.name}\` — ${(tool.label ?? tool.name)
+                  .replaceAll(/\s+/g, " ").trim().replaceAll("`", "'")}`
+              ).join("\n")
+            : "- None.";
+        };
+        const routeGuidance = [
+          "## Tool routing",
+          "Top-level deferred Tools are not callable through `tools.*`. Use Provider Tool Search with their exact name, then call them directly.",
+          "Top-level immediate Tools are already available outside execute; call them directly.",
+          "",
+          "## Top-level deferred Tools",
+          routeList(true),
+          "",
+          "## Top-level immediate Tools",
+          routeList(false),
+          "",
+        ].join("\n");
+        const materializeGuidance = codeExecutionCandidates.some(
             ({ tool }) => tool.name === "materialize_skill_resource",
           )
           ? "Skill resource copying is available only inside execute through " +
@@ -287,18 +320,17 @@ async function createToolSurface(
             "no Direct Tool is registered for it. " +
             "Use a loop or Promise.all when copying multiple resources.\n\n"
           : "";
-        return Object.freeze([
-          classify({
-            ...codeExecutionPiToolCandidate(
-              {
-                ...codeExecution,
-                description: materializeGuidance + codeExecution.description,
-              },
-            ),
-            codeExecutionTools,
-          }),
-          ...directVisible.map(classify),
-        ]);
+        return Object.freeze({
+          candidates: Object.freeze([
+            classify(codeExecutionPiToolCandidate({
+              ...codeExecution,
+              description:
+                routeGuidance + "\n" + materializeGuidance + codeExecution.description,
+            })),
+            ...directVisible.map(classify),
+          ]),
+          codeExecutionCandidates,
+        }) satisfies FinalizedPiToolSurface;
       },
     }),
     extensions: input.extensions.filter(
@@ -658,67 +690,6 @@ export async function assembleRuntime(
   commit(candidate.snapshot);
 }
 
-export function toolRegistryPiToolCandidates(
-  registry: ToolRegistry,
-  settings?: Pick<RuntimeSettings, "toolPolicy">,
-): PiToolCandidate[] {
-  const deny = new Set(settings?.toolPolicy?.denyPolicy?.deny ?? []);
-  const allowsTool = settings?.toolPolicy?.allowsTool;
-  const candidates: PiToolCandidate[] = [];
-  for (const [name, spec] of Object.entries(registry)) {
-    if (deny.has(name)) continue;
-    if (allowsTool?.(name) === false) continue;
-    const normalized = requiredName(name, "Platform Tool");
-    const {
-      label,
-      description,
-      parameters,
-      execute,
-      owner = "platform",
-      ...metadata
-    } = spec;
-    candidates.push(Object.freeze({
-      ...metadata,
-      owner,
-      tool: Object.freeze({
-        name: normalized,
-        label,
-        description,
-        parameters,
-        async execute(
-          toolCallId: string,
-          input: unknown,
-          signal?: AbortSignal,
-        ) {
-          const result = await execute(input, {
-            toolCallId,
-            signal: signal ?? new AbortController().signal,
-          });
-          if (
-            result != null &&
-            typeof result === "object" &&
-            "content" in result &&
-            Array.isArray((result as { content?: unknown }).content)
-          ) {
-            return result as import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
-          }
-          let text: string;
-          try {
-            text = JSON.stringify(result) ?? String(result);
-          } catch {
-            text = String(result);
-          }
-          return {
-            content: [{ type: "text" as const, text }],
-            details: result,
-          };
-        },
-      } as AgentTool<any, any>),
-    }));
-  }
-  return candidates;
-}
-
 function hooksToTurnEventsPort<
   Env extends Cloudflare.Env,
   Config,
@@ -795,10 +766,7 @@ export async function assembleRuntimeSnapshot<
     }
   }
 
-  const hostTools = toolRegistryPiToolCandidates(
-    toolAssembly.tools,
-    settings,
-  );
+  const hostTools = toolAssembly.tools;
 
   const commitGuards: Array<() => Promise<void>> = [];
   if (toolAssembly.commitGuard) commitGuards.push(toolAssembly.commitGuard);

package/src/runtime-definition.ts

@@ -22,13 +22,41 @@ import type {
 import type { RuntimeExtensionConfig } from "./kernel/extensions";
 import type { RuntimeActivityProjection } from "./kernel/state";
 import type { RuntimeDegradation } from "./kernel/degradation";
+import type { PiToolCandidate } from "./pi/tool/compiler";
 import type {
   RuntimeAgentContext,
   RuntimeAssemblyContext,
   RuntimeAgentPlanningContext,
 } from "./runtime-agent-context";
 import type { AgentTelemetryBinding } from "./telemetry/contract";
-import type { ToolSurfaceSelectionPolicy } from "./tool-registry";
+
+/** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
+export interface ToolSurfaceSelectionPolicy {
+  readonly allowsTool?: (name: string) => boolean;
+  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
+  readonly defersTool?: (name: string) => boolean;
+}
+
+/** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
+export interface RuntimeToolBindings {
+  readonly workspace?: import("./kernel/bindings").WorkspacePort;
+  readonly codeExecution?: import("./kernel/bindings").RuntimeCodeExecutionFactory;
+  readonly memory?: import("./kernel/bindings").RuntimeMemoryPort;
+  readonly subagents?: import("./kernel/bindings").RuntimeSubagentPort;
+}
+
+/** Host 一次装配原子提交的 Tool candidates 与 Runtime 绑定。 */
+export interface ToolAssemblyResult {
+  readonly tools: readonly PiToolCandidate[];
+  readonly bindings?: RuntimeToolBindings;
+  readonly memoryProfile?: RuntimeMemoryProfile;
+  readonly enabledSubagents?: readonly string[];
+  readonly degradations?: readonly RuntimeDegradation[];
+  readonly surfacePolicy?: ToolSurfaceSelectionPolicy;
+  readonly commitGuard?: () => Promise<void>;
+  /** 释放本次装配创建的外部资源；临时 Agent 终止后由 Runtime 调用。 */
+  readonly dispose?: () => Promise<void>;
+}
 
 export interface RuntimeProfileContribution {
   readonly model: string;
@@ -63,24 +91,6 @@ export interface GateToolRequest {
   readonly signal: AbortSignal;
 }
 
-export type {
-  PlatformToolContext,
-  PlatformToolRegistry,
-  PlatformToolSpec,
-  RuntimeToolBindings,
-  ToolAssemblyResult,
-  ToolContext,
-  ToolRegistry,
-  ToolSpec,
-} from "./tool-registry";
-export {
-  emptyPlatformToolRegistry,
-  emptyToolRegistry,
-  mergeToolRegistries,
-  normalizeToolAssembly,
-  toolRegistryFromPiCandidates,
-} from "./tool-registry";
-
 export interface ResolvedConnectors {
   readonly servers: readonly RuntimeMcpServer[];
   readonly gateway?: RuntimeGatewayPort;
@@ -181,7 +191,7 @@ export interface AssembleRuntimeSnapshotInput<
 > {
   readonly ctx: RuntimeAgentPlanningContext<Env, Command, Change>;
   readonly config: Config;
-  readonly tools: import("./tool-registry").ToolAssemblyResult;
+  readonly tools: ToolAssemblyResult;
   readonly resources: ResolvedResources;
   readonly hooks?: RuntimeAgentHooks<Env, Config, Command, Change>;
   readonly telemetry?: AgentTelemetryBinding;

package/src/runtime.ts

@@ -2279,15 +2279,30 @@ export abstract class AgentRuntimeKernel<
   ): PiRecoveryDecision {
     let decision = this.decidePiRecovery(submission);
     for (const settlement of decision.recoveredToolSettlements) {
+      const message = settlement.message;
       if (
         this.readToolSettlement(
           submission.submissionId,
-          settlement.toolCallId,
+          message.toolCallId,
         )
       ) {
         continue;
       }
-      this.settleToolSync(submission.submissionId, settlement);
+      this.settleToolSync(submission.submissionId, {
+        toolCallId: message.toolCallId,
+        toolName: message.toolName,
+        args: settlement.args,
+        result: {
+          content: message.content,
+          details: message.details,
+          ...(message.usage ? { usage: message.usage } : {}),
+          ...(message.addedToolNames?.length
+            ? { addedToolNames: message.addedToolNames }
+            : {}),
+        },
+        isError: message.isError,
+        createdAt: message.timestamp,
+      });
       decision = this.decidePiRecovery(submission);
     }
     const results = this.transcript.orderRecoveredToolSettlements(
@@ -4198,7 +4213,7 @@ export abstract class AgentRuntimeKernel<
         );
       }
       const result = decision.recoveredToolSettlements.find(
-        (item) => item.toolCallId === approval.toolCallId,
+        (item) => item.message.toolCallId === approval.toolCallId,
       );
       if (!result) {
         throw new Error(

package/src/kernel/tool-surface.ts

@@ -1,42 +0,0 @@
-import type { ExecutionLevel } from "../lib/execution-level";
-import type { PiToolCandidate } from "../pi/tool/compiler";
-
-/**
- * Tool Surface 的形状类型。
- *
- * @remarks
- * `kernel/bindings.ts` 和 `tool-registry.ts` 都要用它们，所以它们不能住在其中任何
- * 一边：`RuntimeBindings.codeExecution` 的工厂签名需要 `ToolRegistry`，而
- * `tool-registry.ts` 又需要 bindings 里的各个 Port —— 两边互相 import 就形成了
- * depcruise 的 no-circular 违规（`bindings → tool-registry → bindings`）。
- *
- * 这里只放形状，不放行为：注册表的合并、筛选和构造仍然留在 `tool-registry.ts`。
- *
- * 术语见 `../index.ts`。
- */
-
-/** 模型调用 Tool 时传给 `execute` 的上下文。 */
-export interface ToolContext {
-  readonly toolCallId: string;
-  readonly signal: AbortSignal;
-}
-
-/** Definition 作者声明的一个 Tool。 */
-export interface ToolSpec extends Partial<
-  Omit<PiToolCandidate, "tool" | "requiredExecutionLevel">
-> {
-  readonly label: string;
-  readonly description: string;
-  readonly parameters: unknown;
-  readonly requiredExecutionLevel: ExecutionLevel;
-  /** Require a fresh human decision for every call, regardless of execution level. */
-  readonly alwaysRequiresApproval?: boolean;
-  /** Preserve adapted Pi result envelopes; only details-only adapters may unwrap them. */
-  readonly execute: (
-    input: unknown,
-    ctx: ToolContext,
-  ) => Promise<unknown>;
-}
-
-/** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
-export type ToolRegistry = Record<string, ToolSpec>;

package/src/tool-registry.ts

@@ -1,142 +0,0 @@
-import type {
-  RuntimeCodeExecutionFactory,
-  RuntimeMemoryPort,
-  RuntimeSubagentPort,
-  WorkspacePort,
-} from "./kernel/bindings";
-import type { RuntimeExtensionConfig } from "./kernel/extensions";
-import type { RuntimeDegradation } from "./kernel/degradation";
-import type {
-  ToolContext,
-  ToolRegistry,
-  ToolSpec,
-} from "./kernel/tool-surface";
-import type { PiToolCandidate } from "./pi/tool/compiler";
-import { validateToolArguments } from "@earendil-works/pi-ai";
-
-// Tool Surface 的形状类型住在 `kernel/tool-surface.ts`：bindings 也要用它们，放在这里
-// 会让 `bindings → tool-registry → bindings` 成环。这里继续导出是为了保持调用方不变。
-export type {
-  RuntimeCodeExecutionFactory,
-  ToolContext,
-  ToolRegistry,
-  ToolSpec,
-};
-
-/** Tool Surface 筛选策略（不含 Manifest deny 列表）。 */
-export interface ToolSurfaceSelectionPolicy {
-  readonly allowsTool?: (name: string) => boolean;
-  readonly allowsExtension?: (extension: RuntimeExtensionConfig) => boolean;
-  readonly defersTool?: (name: string) => boolean;
-}
-
-export function emptyToolRegistry(): ToolRegistry {
-  return {};
-}
-
-export function mergeToolRegistries(...registries: ToolRegistry[]): ToolRegistry {
-  const merged: ToolRegistry = {};
-  for (const registry of registries) {
-    for (const [name, spec] of Object.entries(registry)) {
-      if (name in merged) {
-        throw new Error(`Duplicate Runtime Tool: ${name}`);
-      }
-      merged[name] = spec;
-    }
-  }
-  return merged;
-}
-
-export function toolRegistryFromPiCandidates(
-  candidates:
-    | readonly PiToolCandidate[]
-    | Record<string, PiToolCandidate>,
-): ToolRegistry {
-  const list = Array.isArray(candidates)
-    ? candidates
-    : Object.values(candidates);
-  const registry: ToolRegistry = {};
-  for (const candidate of list) {
-    const name = candidate.tool.name;
-    if (!name.trim()) {
-      throw new Error("SpringBrand Tool name must not be empty");
-    }
-    registry[name] = piCandidateToToolSpec(candidate);
-  }
-  return registry;
-}
-
-export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
-  const { tool, ...metadata } = candidate;
-  const name = tool.name;
-  return {
-    ...metadata,
-    label: tool.label ?? name,
-    description: tool.description,
-    parameters: tool.parameters,
-    execute: async (input, ctx) => {
-      const execute = tool.execute;
-      if (typeof execute !== "function") {
-        throw new Error(`Tool "${name}" is not executable`);
-      }
-      const validated = validateToolArguments(tool, {
-        type: "toolCall",
-        id: ctx.toolCallId,
-        name,
-        arguments: input as Record<string, unknown>,
-      });
-      return execute(
-        ctx.toolCallId,
-        validated,
-        ctx.signal,
-        undefined,
-      );
-    },
-  };
-}
-
-/** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
-export interface RuntimeToolBindings {
-  readonly workspace?: WorkspacePort;
-  readonly codeExecution?: RuntimeCodeExecutionFactory;
-  readonly memory?: RuntimeMemoryPort;
-  readonly subagents?: RuntimeSubagentPort;
-}
-
-/**
- * Worker `tools()` 可返回纯注册表，或附带 Kernel 绑定与降级信息。
- */
-export interface ToolAssemblyResult {
-  readonly tools: ToolRegistry;
-  readonly bindings?: RuntimeToolBindings;
-  readonly memoryProfile?: import("./kernel/profile").RuntimeMemoryProfile;
-  readonly enabledSubagents?: readonly string[];
-  readonly degradations?: readonly RuntimeDegradation[];
-  readonly surfacePolicy?: ToolSurfaceSelectionPolicy;
-  readonly commitGuard?: () => Promise<void>;
-  /** 释放本次装配创建的外部资源；临时 Agent 终止后由 Runtime 调用。 */
-  readonly dispose?: () => Promise<void>;
-}
-
-export function normalizeToolAssembly(
-  input: ToolRegistry | ToolAssemblyResult,
-): ToolAssemblyResult {
-  if ("tools" in input && typeof input.tools === "object" && input.tools !== null) {
-    return input as ToolAssemblyResult;
-  }
-  return { tools: input as ToolRegistry };
-}
-
-/** @deprecated 使用 `ToolSpec`。 */
-export type PlatformToolSpec = ToolSpec;
-
-/** @deprecated 使用 `ToolContext`。 */
-export type PlatformToolContext = ToolContext;
-
-/** @deprecated 使用 `ToolRegistry`。 */
-export type PlatformToolRegistry = ToolRegistry;
-
-/** @deprecated 使用 `emptyToolRegistry`。 */
-export function emptyPlatformToolRegistry(): ToolRegistry {
-  return emptyToolRegistry();
-}