@springbrand/agent-runtime 0.2.0-alpha.41 → 0.2.0-alpha.43

package/src/runtime-assembler.ts

@@ -30,11 +30,15 @@ import {
 } from "./lib/execution-level";
 import {
   createPiRuntimeAssembly,
+  type FinalizedPiToolSurface,
   type PiToolSurface,
   type PiRuntimeAssembly,
 } from "./pi/assembly/snapshot";
 import type { AgentTool } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "./pi/tool/compiler";
+import type {
+  PiToolCandidate,
+  ToolExposureMode,
+} from "./pi/tool/compiler";
 import type {
   AssembleRuntimeSnapshotInput,
   RuntimeSettings,
@@ -43,6 +47,7 @@ import type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
+import type { RuntimeCodeExecutionFactory } from "./kernel/bindings";
 import {
   basePiToolCandidates,
   memoryPiToolCandidate,
@@ -50,6 +55,7 @@ import {
 import {
   BROWSER_EXECUTE_TOOL_NAME,
   browserExecutionPiToolCandidate,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
 import { createWebSearch } from "./pi/tool/web-search";
@@ -80,6 +86,7 @@ export interface RuntimeAssemblyInput {
   readonly provider: RuntimeProviderPort;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly sandbox?: RuntimeSandboxPort;
   readonly memory?: RuntimeMemoryPort;
   readonly hostTools: readonly PiToolCandidate[];
@@ -153,6 +160,7 @@ function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
 }
 
 interface ToolSurfaceInput {
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
   readonly memory?: {
@@ -173,6 +181,10 @@ interface ToolSurface {
   readonly degradations: readonly RuntimeDegradation[];
 }
 
+function exposureOf(candidate: PiToolCandidate): ToolExposureMode {
+  return candidate.exposureMode ?? "both";
+}
+
 // 唯一 Tool Surface seam：只读取已配置 Port、Resource 和 Agent policy，
 // 统一生成可见 Tool，并在一处做名称、执行档位与冲突校验。
 async function createToolSurface(
@@ -198,10 +210,15 @@ async function createToolSurface(
     });
   // 平台没有浏览器能力时注册空集：宁可没有这个 Tool，也不注册一个必然失败的 Tool 误导模型。
   // `create()` 推迟到确认这个名字真的可见之后，被 deny 的装配不白建一个浏览器连接器。
+  // `direct` exposure 使它只走 Direct 调用，不再被并进 `execute` 的工具集——两个 Code Mode 类工具互相嵌套
+  // 会让「哪次执行被记录、被重放」变得无法解释，而它们的分工本就由 System Prompt 划清。
   const browserVisible = !deny.has(BROWSER_EXECUTE_TOOL_NAME) &&
     allowsTool?.(BROWSER_EXECUTE_TOOL_NAME) !== false;
   const browserCandidates = input.platform.browser && browserVisible
-    ? [browserExecutionPiToolCandidate(input.platform.browser.create())]
+    ? [{
+        ...browserExecutionPiToolCandidate(input.platform.browser.create()),
+        exposureMode: "direct" as const,
+      }]
     : [];
   const baseCandidates = basePiToolCandidates(input.webSearch);
   const memoryCandidates = input.memory
@@ -238,16 +255,87 @@ async function createToolSurface(
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
             throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
-          if (name === "execute") {
-            throw new Error("SpringBrand reserved Runtime Tool name: execute");
-          }
           if (tools.has(name)) {
             throw new Error(`Duplicate Runtime SpringBrand Tool: ${name}`);
           }
-          tools.set(name, classify(candidate));
+          tools.set(name, Object.freeze({ ...candidate }));
         }
 
-        return Object.freeze([...tools.values()]);
+        const finalized = [...tools.values()];
+        const directVisible = finalized.filter(
+          (candidate) => exposureOf(candidate) !== "codemode",
+        );
+        if (tools.has("execute")) {
+          throw new Error("SpringBrand reserved Runtime Tool name: execute");
+        }
+        if (
+          !input.codeExecution ||
+          deny.has("execute") ||
+          allowsTool?.("execute") === false
+        ) {
+          return Object.freeze({
+            candidates: Object.freeze(directVisible.map(classify)),
+            codeExecutionCandidates: Object.freeze([]),
+          }) satisfies FinalizedPiToolSurface;
+        }
+        const mergeable = finalized.filter(
+          (candidate) =>
+            exposureOf(candidate) !== "direct" &&
+            !candidate.interaction &&
+            typeof candidate.tool.execute === "function",
+        );
+        const codeExecutionCandidates = Object.freeze([...mergeable]);
+        const codeExecutionToolNames = new Set(
+          codeExecutionCandidates.map(({ tool }) => tool.name),
+        );
+        const codeExecution = input.codeExecution.create(
+          codeExecutionCandidates,
+        );
+        const topLevelOnly = directVisible.filter(
+          ({ tool }) => !codeExecutionToolNames.has(tool.name),
+        );
+        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 " +
+            "`tools.materialize_skill_resource({ name, path, destination })`; " +
+            "no Direct Tool is registered for it. " +
+            "Copy multiple resources sequentially in one execute so durable replay preserves call order.\n\n"
+          : "";
+        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(
@@ -275,6 +363,7 @@ class RuntimeBuilder {
   private platform?: RuntimePlatformPort;
   private gateway?: RuntimeGatewayPort;
   private workspace?: WorkspacePort;
+  private codeExecution?: RuntimeCodeExecutionFactory;
   private sandbox?: RuntimeSandboxPort;
   private schedule?: RuntimeSchedulePort;
   private memoryProfile: RuntimeMemoryProfile = DISABLED_MEMORY;
@@ -310,6 +399,7 @@ class RuntimeBuilder {
     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;
@@ -449,6 +539,9 @@ class RuntimeBuilder {
     if (!this.platform.loader) {
       throw new Error("Runtime platform loader is required");
     }
+    if (typeof this.platform.outbound !== "function") {
+      throw new Error("Runtime platform outbound port is required");
+    }
 
     assertMemoryProfile(this.memoryProfile);
     if (this.memoryProfile.enabled && (!this.workspace || !this.memory)) {
@@ -498,6 +591,7 @@ class RuntimeBuilder {
     });
     const skillSources = [...this.skillSources.values()];
     const toolSurface = await createToolSurface({
+      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       platform: this.platform,
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
@@ -522,6 +616,7 @@ class RuntimeBuilder {
     const bindings: RuntimeBindings = Object.freeze({
       provider,
       platform: Object.freeze({ ...this.platform }),
+      ...(this.codeExecution ? { codeExecution: this.codeExecution } : {}),
       ...(this.gateway ? { gateway: this.gateway } : {}),
       ...(this.workspace ? { workspace: this.workspace } : {}),
       ...(this.memoryProfile.enabled && this.memory
@@ -666,6 +761,9 @@ export async function assembleRuntimeSnapshot<
     ...(toolAssembly.bindings?.workspace
       ? { workspace: toolAssembly.bindings.workspace }
       : {}),
+    ...(toolAssembly.bindings?.codeExecution
+      ? { codeExecution: toolAssembly.bindings.codeExecution }
+      : {}),
     ...(memoryProfile.enabled && toolAssembly.bindings?.memory
       ? { memory: toolAssembly.bindings.memory }
       : {}),

package/src/runtime-definition.ts

@@ -33,6 +33,7 @@ export interface ToolSurfaceSelectionPolicy {
 /** 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;
 }

package/src/runtime.ts

@@ -899,6 +899,7 @@ export abstract class AgentRuntimeKernel<
     return this.pi.createTurn({
       prepared: this.preparedPi(),
       pinnedDescriptor: submission.assemblyDescriptor,
+      modelSessionId: this.name,
       submission: {
         id: submission.submissionId,
         requestId: submission.requestId,
@@ -975,6 +976,29 @@ export abstract class AgentRuntimeKernel<
           occurredAt: event.timestamp,
         });
       },
+      onNestedToolStarted: (event) => {
+        this.telemetry.capture("toolStarted", {
+          submissionId: submission.submissionId,
+          ...event,
+        });
+      },
+      onNestedToolFinished: (event) => {
+        this.telemetry.capture("toolFinished", {
+          submissionId: submission.submissionId,
+          parentToolCallId: event.parentToolCallId,
+          toolCallId: event.toolCallId,
+          toolName: event.toolName,
+          outcome: event.outcome,
+          durationMs: event.durationMs,
+          ...(event.output ? {
+            output: event.output,
+            outputBytes: json(event.output).length,
+          } : {}),
+          ...(event.error ? { error: errorText(event.error) } : {}),
+          occurredAt: event.occurredAt,
+        });
+        this.projectNestedToolSettlement(submission.submissionId, event);
+      },
       ...(toolExecutors && Object.keys(toolExecutors).length > 0
         ? { toolExecutors }
         : {}),
@@ -2178,6 +2202,32 @@ export abstract class AgentRuntimeKernel<
     return this.drainRuntimeEvents();
   }
 
+  private projectNestedToolSettlement(
+    submissionId: string,
+    event: Readonly<{
+      toolCallId: string;
+      toolName: string;
+      outcome: "completed" | "failed" | "cancelled";
+      occurredAt: number;
+    }>,
+  ): void {
+    const settlement: RuntimeToolSettlementEvent = {
+      eventId: `${submissionId}:tool:${event.toolCallId}`,
+      submissionId,
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      status: event.outcome === "completed" ? "success" : "error",
+    };
+    this.db.transaction(() => {
+      this.db.runtimeEvents.insert({
+        eventId: settlement.eventId,
+        body: json({ type: "tool-settlement", event: settlement }),
+        createdAt: event.occurredAt,
+      });
+    });
+    this.ctx.waitUntil(this.drainRuntimeEvents());
+  }
+
   // 终态事务用这个同步内核先补齐 ToolResult，再在同一事务末尾写 marker。
   private settleToolSync(
     submissionId: string,