@springbrand/agent-runtime 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/runtime-agent.ts

@@ -652,9 +652,14 @@ export function defineRuntimeAgent<
         const policy = assembly.surfacePolicy;
         return {
           ...assembly,
-          bindings: assembly.bindings?.workspace
-            ? { workspace: assembly.bindings.workspace }
-            : {},
+          bindings: {
+            ...(assembly.bindings?.workspace
+              ? { workspace: assembly.bindings.workspace }
+              : {}),
+            ...(assembly.bindings?.codeExecution
+              ? { codeExecution: assembly.bindings.codeExecution }
+              : {}),
+          },
           memoryProfile: {
             enabled: false,
             memoryTokens: 2_000,

package/src/runtime-assembler.ts

@@ -1,6 +1,5 @@
 import type { SkillSource } from "agents/skills";
 import type {
-  RuntimeCodeExecutionPort,
   RuntimeGatewayPort,
   RuntimeMemoryPort,
   RuntimePlatformPort,
@@ -44,7 +43,11 @@ import type {
   RuntimeSkillContribution,
   RuntimeToolSurfacePolicy,
 } from "./runtime-definition";
-import type { ToolRegistry } from "./tool-registry";
+import {
+  toolRegistryFromPiCandidates,
+  type RuntimeCodeExecutionFactory,
+  type ToolRegistry,
+} from "./tool-registry";
 import { withRuntimeLoadTimeout } from "./kernel/runtime-load";
 import {
   basePiToolCandidates,
@@ -52,6 +55,7 @@ import {
 } from "./pi/tool/base";
 import {
   browserQuickActionPiToolCandidates,
+  codeExecutionPiToolCandidate,
 } from "./pi/tool/core";
 import { skillPiToolCandidates } from "./pi/tool/skill";
 import { createWebSearch } from "./pi/tool/web-search";
@@ -77,7 +81,7 @@ export interface RuntimeAssemblyInput {
   readonly provider: RuntimeProviderPort;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
-  readonly codeExecution?: RuntimeCodeExecutionPort;
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly sandbox?: RuntimeSandboxPort;
   readonly memory?: RuntimeMemoryPort;
   readonly hostTools: readonly PiToolCandidate[];
@@ -150,6 +154,7 @@ function assertMemoryProfile(profile: RuntimeMemoryProfile): void {
 }
 
 interface ToolSurfaceInput {
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly platform: RuntimePlatformPort;
   readonly workspace?: WorkspacePort;
   readonly memory?: {
@@ -215,18 +220,46 @@ async function createToolSurface(
           ...staticCandidates,
           ...candidates,
         ]) {
-          const name = requiredName(candidate.tool.name, "Pi Tool");
+          const name = requiredName(candidate.tool.name, "SpringBrand Tool");
           if (!visible(candidate)) continue;
           if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
-            throw new Error(`Pi Tool ${name} execution level is invalid`);
+            throw new Error(`SpringBrand Tool ${name} execution level is invalid`);
           }
           if (tools.has(name)) {
-            throw new Error(`Duplicate Runtime Pi Tool: ${name}`);
+            throw new Error(`Duplicate Runtime SpringBrand Tool: ${name}`);
           }
           tools.set(name, Object.freeze({ ...candidate }));
         }
 
-        return Object.freeze([...tools.values()]);
+        const finalized = [...tools.values()];
+        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(finalized);
+        }
+        const mergeable = finalized.filter(
+          (candidate) =>
+            !candidate.interaction &&
+            typeof candidate.tool.execute === "function",
+        );
+        const direct = finalized.filter(
+          (candidate) =>
+            candidate.interaction ||
+            typeof candidate.tool.execute !== "function",
+        );
+        return Object.freeze([
+          Object.freeze(codeExecutionPiToolCandidate(
+            input.codeExecution.create(
+              toolRegistryFromPiCandidates(mergeable),
+            ),
+          )),
+          ...direct,
+        ]);
       },
     }),
     extensions: input.extensions.filter(
@@ -246,7 +279,7 @@ class RuntimeBuilder {
   private platform?: RuntimePlatformPort;
   private gateway?: RuntimeGatewayPort;
   private workspace?: WorkspacePort;
-  private codeExecution?: RuntimeCodeExecutionPort;
+  private codeExecution?: RuntimeCodeExecutionFactory;
   private sandbox?: RuntimeSandboxPort;
   private schedule?: RuntimeSchedulePort;
   private memoryProfile: RuntimeMemoryProfile = DISABLED_MEMORY;
@@ -470,6 +503,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
@@ -766,6 +800,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.ts

@@ -187,6 +187,11 @@ interface ActiveTurn {
   agent: PreparedPiTurnAdapter;
 }
 
+interface PlannedContinuationData {
+  readonly submissionId: string;
+  readonly requestId: string;
+}
+
 // 作用：把任意异常整理成可以持久化或发给客户端的文字。
 // 调用：Turn 执行、恢复和业务投影捕获 `unknown` 异常时调用。
 // 原因：错误边界不能假定抛出值一定是 `Error`。
@@ -553,7 +558,7 @@ export abstract class AgentRuntimeKernel<
                 status: "failed" as const,
                 error:
                   receipt.error ??
-                  `Pi recovery ended with status ${receipt.status}`,
+                  `SpringBrand recovery ended with status ${receipt.status}`,
               };
         } catch (error) {
           if (
@@ -651,7 +656,7 @@ export abstract class AgentRuntimeKernel<
     if (contested && !parked) {
       await closeRuntimeGatewaySession(gatewaySession, "gateway.close.contested");
       throw new Error(
-        "Cannot reload Runtime while a revision-pinned Pi Turn is active",
+        "Cannot reload Runtime while a revision-pinned SpringBrand Turn is active",
       );
     }
     const repin = parked
@@ -1186,7 +1191,7 @@ export abstract class AgentRuntimeKernel<
   private preparedPi(): PreparedPiRuntime {
     if (!this.runtimePi) {
       throw new Error(
-        "Pi Runtime must be prepared before starting a Turn",
+        "SpringBrand Runtime must be prepared before starting a Turn",
       );
     }
     return this.runtimePi;
@@ -1695,7 +1700,7 @@ export abstract class AgentRuntimeKernel<
     );
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     return submission;
   }
@@ -1890,7 +1895,7 @@ export abstract class AgentRuntimeKernel<
   ): void {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     const existing = this.db.settlements.find(submissionId, call.toolCallId);
     const args = json(call.args);
@@ -2038,7 +2043,7 @@ export abstract class AgentRuntimeKernel<
     const latest = this.readSubmission(submission.submissionId);
     if (!latest) {
       throw new Error(
-        `Unknown Pi submission: ${submission.submissionId}`,
+        `Unknown SpringBrand submission: ${submission.submissionId}`,
       );
     }
     if (isTerminalSubmissionStatus(latest.status)) return latest;
@@ -2101,7 +2106,7 @@ export abstract class AgentRuntimeKernel<
       ) {
         if (terminal.completedAt == null) {
           throw new Error(
-            `Aborted Pi submission has no completion time: ${latest.submissionId}`,
+            `Aborted SpringBrand submission has no completion time: ${latest.submissionId}`,
           );
         }
         this.transcript.appendTurnAbortedMarker(
@@ -2224,7 +2229,7 @@ export abstract class AgentRuntimeKernel<
         }
       }
     }
-    throw new Error("Pi recovery plan did not converge");
+    throw new Error("SpringBrand recovery plan did not converge");
   }
 
   // #endregion
@@ -2253,7 +2258,7 @@ export abstract class AgentRuntimeKernel<
       typeof userMessage.timestamp !== "number" ||
       !submission.userMessageId
     ) {
-      throw new Error("Queued Pi user message is invalid");
+      throw new Error("Queued SpringBrand user message is invalid");
     }
     const uiMessage = submission.queuedUiMessageJson
       ? JSON.parse(submission.queuedUiMessageJson) as UIMessage & {
@@ -2282,7 +2287,7 @@ export abstract class AgentRuntimeKernel<
       if (!latest || latest.status !== "pending") {
         if (!latest) {
           throw new Error(
-            `Unknown Pi submission: ${submission.submissionId}`,
+            `Unknown SpringBrand submission: ${submission.submissionId}`,
           );
         }
         return latest;
@@ -2290,7 +2295,7 @@ export abstract class AgentRuntimeKernel<
       const running = this.db.submissions.findRunning();
       if (running) {
         throw new Error(
-          `Pi submission ${running.submissionId} is already running`,
+          `SpringBrand submission ${running.submissionId} is already running`,
         );
       }
       if (submission.regenerateMessageId) {
@@ -2307,7 +2312,7 @@ export abstract class AgentRuntimeKernel<
         );
         if (!appended) {
           throw new Error(
-            `Pi Session message ${submission.userMessageId} already exists`,
+            `SpringBrand Session message ${submission.userMessageId} already exists`,
           );
         }
       }
@@ -2317,7 +2322,7 @@ export abstract class AgentRuntimeKernel<
         ["pending"],
       )) {
         throw new Error(
-          `Pi submission ${submission.submissionId} could not activate`,
+          `SpringBrand submission ${submission.submissionId} could not activate`,
         );
       }
       this.db.submissions.clearQueuedPayload(
@@ -2342,7 +2347,7 @@ export abstract class AgentRuntimeKernel<
   ): Promise<StoredSubmission> {
     const submission = this.readSubmission(submissionId);
     if (!submission) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     if (isTerminalSubmissionStatus(submission.status)) {
       return submission;
@@ -2385,7 +2390,7 @@ export abstract class AgentRuntimeKernel<
       this.sendChatTerminal(
         submission.requestId,
         failed.status === "error"
-          ? failed.error ?? "Pi turn failed"
+          ? failed.error ?? "SpringBrand turn failed"
           : undefined,
         recovery,
       );
@@ -2455,7 +2460,7 @@ export abstract class AgentRuntimeKernel<
 
     const ready = this.readSubmission(submissionId);
     if (!ready) {
-      throw new Error(`Unknown Pi submission: ${submissionId}`);
+      throw new Error(`Unknown SpringBrand submission: ${submissionId}`);
     }
     if (isTerminalSubmissionStatus(ready.status)) return ready;
     if (ready.abortReason) {
@@ -2517,6 +2522,7 @@ export abstract class AgentRuntimeKernel<
       agent: adapter,
     };
     let streamId: string | undefined;
+    let runResult: import("./pi/runtime-adapter").PiTurnRunResult | undefined;
 
     const deactivate = this.submissions.activate(submission, turn);
     await this.broadcastApprovals();
@@ -2536,7 +2542,7 @@ export abstract class AgentRuntimeKernel<
           streamId = activeStreamId;
           this.streamBySubmission.set(submissionId, streamId);
           try {
-            await adapter.run({});
+            runResult = await adapter.run({});
           } finally {
             this.streamBySubmission.delete(submissionId);
           }
@@ -2548,10 +2554,27 @@ export abstract class AgentRuntimeKernel<
         if (streamId) this.failRecoverableStream(streamId);
         return this.readSubmission(submissionId)!;
       }
+      if (runResult?.kind === "yielded") {
+        const latest = this.readSubmission(submissionId)!;
+        if (latest.abortReason) {
+          return this.submissions.finish(
+            latest,
+            "aborted",
+            latest.abortReason,
+          );
+        }
+        await this.schedule(
+          0,
+          "_piPlannedContinuation",
+          { submissionId, requestId: submission.requestId },
+          { idempotent: true },
+        );
+        return latest;
+      }
       const intent = terminalIntent ?? {
         outcome: "failed" as const,
         message:
-          "Pi turn ended without an authoritative assistant message",
+          "SpringBrand turn ended without an authoritative assistant message",
       };
       const terminal = await this.submissions.finish(
         submission,
@@ -2713,7 +2736,7 @@ export abstract class AgentRuntimeKernel<
     this.sendChatTerminal(
       turn.requestId,
       submission.status === "error"
-        ? submission.error ?? "Pi turn failed"
+        ? submission.error ?? "SpringBrand turn failed"
         : undefined,
       turn.continuation,
     );
@@ -3562,9 +3585,9 @@ export abstract class AgentRuntimeKernel<
     const adapter = this.createSubmissionExecutionAdapter(submission);
     const spec = adapter.interactionSpec(pending.toolName);
     if (!spec) return { ok: false };
-    if (!spec.validateResponse(response)) return { ok: false };
 
     const input = safeParseJson(pending.inputJson);
+    if (!spec.validateResponse(input, response)) return { ok: false };
     const settled = spec.settle
       ? spec.settle(input, response)
       : defaultInteractionResult(response);
@@ -3687,6 +3710,21 @@ export abstract class AgentRuntimeKernel<
     }
   }
 
+  async _piPlannedContinuation(
+    data?: PlannedContinuationData,
+  ): Promise<void> {
+    if (!data?.submissionId || !data.requestId) return;
+    const submission = this.readSubmission(data.submissionId);
+    if (
+      !submission ||
+      submission.requestId !== data.requestId ||
+      isTerminalSubmissionStatus(submission.status)
+    ) {
+      return;
+    }
+    await this.submissions.recoverAfterCurrent(submission.submissionId);
+  }
+
   // 作用：Agent Tool 子运行开始后重算一次活动投影。
   // 调用：Agents SDK 在登记子运行后调用。
   // 原因：分离的子运行不进 Submission 表，不在这里重算，Host 的列表会显示成已经空闲。

package/src/tool-registry.ts

@@ -1,5 +1,6 @@
 import type { ExecutionLevel } from "./lib/execution-level";
 import type {
+  RuntimeCodeExecutionPort,
   RuntimeMemoryPort,
   RuntimeSubagentPort,
   WorkspacePort,
@@ -37,6 +38,11 @@ export interface ToolSpec {
 /** 一次装配声明的全部 Tool，键即模型可见的工具名。 */
 export type ToolRegistry = Record<string, ToolSpec>;
 
+/** 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。 */
+export interface RuntimeCodeExecutionFactory {
+  create(tools: ToolRegistry): RuntimeCodeExecutionPort;
+}
+
 export function emptyToolRegistry(): ToolRegistry {
   return {};
 }
@@ -66,7 +72,7 @@ export function toolRegistryFromPiCandidates(
   for (const candidate of list) {
     const name = candidate.tool.name;
     if (!name.trim()) {
-      throw new Error("Pi Tool name must not be empty");
+      throw new Error("SpringBrand Tool name must not be empty");
     }
     registry[name] = piCandidateToToolSpec(candidate);
   }
@@ -102,6 +108,7 @@ export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
 /** Kernel 绑定仍需要的执行后端；不出现在 Definition 公开类型里。 */
 export interface RuntimeToolBindings {
   readonly workspace?: WorkspacePort;
+  readonly codeExecution?: RuntimeCodeExecutionFactory;
   readonly memory?: RuntimeMemoryPort;
   readonly subagents?: RuntimeSubagentPort;
 }