@springbrand/agent-runtime 0.1.3-alpha.8 → 0.2.0-alpha.14

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

@@ -201,7 +201,7 @@ function milestoneMutation(
 // 缺少身份时立即失败，避免把无归属的记录混入另一次 Turn 的恢复日志。
 function recoveryIdentity(input: PiRecoveryInput) {
   if (!input.identity) {
-    throw new Error("Pi recovery command is missing its Turn revision");
+    throw new Error("SpringBrand recovery command is missing its Turn revision");
   }
   return { version: 1 as const, ...input.identity };
 }
@@ -255,7 +255,7 @@ function interactionToolResult(
   timestamp: number,
 ): ToolResultMessage {
   if (!interaction) {
-    throw new Error("Pi Tool interaction is missing for its response");
+    throw new Error("SpringBrand Tool interaction is missing for its response");
   }
   return {
     role: "toolResult",
@@ -417,7 +417,7 @@ export function decidePiRecovery(
         (milestone) => milestone.type === "approval",
       );
       if (!approval || approval.type !== "approval") {
-        throw new Error("Pi approval decision milestone is missing");
+        throw new Error("SpringBrand approval decision milestone is missing");
       }
       mutations.push({
         kind: "decide-approval",
@@ -453,7 +453,7 @@ export function decidePiRecovery(
         JSON.stringify(existing.input) !== JSON.stringify(record.input)
       ) {
         throw new Error(
-          `Conflicting Pi Tool input for ${record.toolCallId}`,
+          `Conflicting SpringBrand Tool input for ${record.toolCallId}`,
         );
       }
     } else {
@@ -482,7 +482,7 @@ export function decidePiRecovery(
         existing.inputJson !== approval.inputJson
       ) {
         throw new Error(
-          `Conflicting Pi Tool approval: ${approval.executionId}`,
+          `Conflicting SpringBrand Tool approval: ${approval.executionId}`,
         );
       }
     } else {
@@ -530,7 +530,7 @@ export function decidePiRecovery(
         existing.inputJson !== interaction.inputJson
       ) {
         throw new Error(
-          `Conflicting Pi Tool interaction: ${interaction.interactionId}`,
+          `Conflicting SpringBrand Tool interaction: ${interaction.interactionId}`,
         );
       }
     } else {
@@ -580,7 +580,7 @@ export function decidePiRecovery(
         (milestone) => milestone.type === "interaction",
       );
       if (!record || record.type !== "interaction") {
-        throw new Error("Pi interaction settlement milestone is missing");
+        throw new Error("SpringBrand interaction settlement milestone is missing");
       }
       mutations.push({
         kind: "settle-interaction",
@@ -621,7 +621,7 @@ export function decidePiRecovery(
     if (existing) {
       if (JSON.stringify(existing) !== JSON.stringify(toolResult)) {
         throw new Error(
-          `Conflicting Pi Tool result for ${command.toolCallId}`,
+          `Conflicting SpringBrand Tool result for ${command.toolCallId}`,
         );
       }
     } else {
@@ -676,7 +676,7 @@ export function decidePiRecovery(
       plan.continuationKey !== input.command.continuationKey
     ) {
       throw new Error(
-        `Pi continuation is not ready: ${input.command.continuationKey}`,
+        `SpringBrand continuation is not ready: ${input.command.continuationKey}`,
       );
     }
     const committed = commitPiRecoveryContinuation(
@@ -686,7 +686,7 @@ export function decidePiRecovery(
     );
     if (!committed) {
       throw new Error(
-        `Pi continuation could not be committed: ${plan.continuationKey}`,
+        `SpringBrand continuation could not be committed: ${plan.continuationKey}`,
       );
     }
     const mutation = milestoneMutation(
@@ -809,13 +809,13 @@ export class PiRuntimeRecoveryAdapter
     if (!durable) {
       return {
         kind: "fail",
-        reason: "Recovered Pi submission is missing",
+        reason: "Recovered SpringBrand submission is missing",
       } as const;
     }
     if (durable.terminal) {
       return {
         kind: "ignore",
-        reason: "Pi submission is already terminal",
+        reason: "SpringBrand submission is already terminal",
       } as const;
     }
     const decision = decidePiRecovery({
@@ -827,20 +827,20 @@ export class PiRuntimeRecoveryAdapter
       if (decision.effect.reason === "approval") {
         return {
           kind: "park",
-          reason: "Pi Turn is waiting for Tool approval",
+          reason: "SpringBrand Turn is waiting for Tool approval",
         } as const;
       }
       if (decision.effect.reason === "interaction") {
         return {
           kind: "park",
-          reason: "Pi Turn is waiting for a client Tool interaction response",
+          reason: "SpringBrand Turn is waiting for a client Tool interaction response",
         } as const;
       }
       if (decision.effect.reason === "uncertain-tool") {
         return {
           kind: "park",
           reason:
-            "Pi Turn is parked on an uncertain non-idempotent Tool",
+            "SpringBrand Turn is parked on an uncertain non-idempotent Tool",
           incidentStatus: "failed",
         } as const;
       }
@@ -848,12 +848,12 @@ export class PiRuntimeRecoveryAdapter
         return {
           kind: "fail",
           reason:
-            "Pi recovery is complete but the Submission is not terminal",
+            "SpringBrand recovery is complete but the Submission is not terminal",
         } as const;
       }
       return {
         kind: "park",
-        reason: "Pi recovery is waiting for durable input",
+        reason: "SpringBrand recovery is waiting for durable input",
       } as const;
     }
     return {

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

@@ -526,7 +526,7 @@ export class PiRuntimeTranscript {
    */
   importSnapshot(snapshot: PiCanonicalTranscriptSnapshot): void {
     if (this.hasActiveTurn()) {
-      throw new Error("Cannot import messages while a Pi Turn is active");
+      throw new Error("Cannot import messages while a SpringBrand Turn is active");
     }
     this.durability.transaction(() => {
       let currentSubmissionId: string | undefined;
@@ -551,7 +551,7 @@ export class PiRuntimeTranscript {
             : {}),
         });
         if (!appended) {
-          throw new Error(`Pi Session message "${entry.id}" already exists`);
+          throw new Error(`SpringBrand Session message "${entry.id}" already exists`);
         }
       }
     });

package/src/pi/tool/base.ts

@@ -15,47 +15,122 @@ import {
 import { webSearchPiToolCandidate } from "./web-search";
 import type { WebSearch } from "./web-search/api";
 
-const askUserParameters = Type.Object({
+const askUserQuestion = Type.Object({
   question: Type.String({
+    minLength: 1,
     description: "The question to put to the user.",
   }),
-  options: Type.Array(Type.String(), {
+  options: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
     minItems: 2,
     maxItems: 6,
+    uniqueItems: true,
     description: "2-6 mutually distinct options for the user to choose from.",
-  }),
+  })),
   multiSelect: Type.Optional(Type.Boolean({
     description:
       "Whether the user may select more than one option. Defaults to false.",
   })),
+  allowCustom: Type.Optional(Type.Boolean({
+    description:
+      "Whether the user may add free text. Defaults to false with options and true without options.",
+  })),
+});
+
+const askUserParameters = Type.Object({
+  questions: Type.Array(askUserQuestion, {
+    minItems: 1,
+    maxItems: 4,
+    description:
+      "All user decisions needed to continue. Ask them together in one call.",
+  }),
 });
 
 /**
  * `ask_user` 的客户端响应体。
  *
- * `selections` 是选中的选项原文（多选时多于一项），`text` 是可选的补充说明。
+ * `answers` 与 Tool 输入的 `questions` 按下标一一对应。
  * 刻意用结构化数组而不是拼好的字符串 —— 选项本身可能含分隔符，拼了再拆是有损的。
  */
 const askUserResponse = Type.Object({
-  selections: Type.Array(Type.String()),
-  text: Type.Optional(Type.String()),
+  answers: Type.Array(Type.Object({
+    selections: Type.Array(Type.String()),
+    text: Type.Optional(Type.String()),
+  })),
 });
 
-// 手写校验而不是拉 TypeBox 的 compiler：这里只需要判真假，
-// 且校验必须在 Worker 冷启动路径上零成本。
-function isAskUserResponse(value: unknown): boolean {
-  if (typeof value !== "object" || value === null) return false;
-  const record = value as Record<string, unknown>;
-  if (!Array.isArray(record.selections)) return false;
-  if (!record.selections.every((item) => typeof item === "string")) {
-    return false;
+type AskUserInput = Static<typeof askUserParameters>;
+type AskUserResponse = Static<typeof askUserResponse>;
+
+function recordOf(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function questionsOf(value: unknown): AskUserInput["questions"] | null {
+  const questions = recordOf(value)?.questions;
+  if (!Array.isArray(questions) || questions.length < 1 || questions.length > 4) {
+    return null;
   }
-  if (record.text !== undefined && typeof record.text !== "string") {
+  for (const value of questions) {
+    const question = recordOf(value);
+    if (!question || typeof question.question !== "string" || !question.question) {
+      return null;
+    }
+    if (
+      question.multiSelect !== undefined &&
+      typeof question.multiSelect !== "boolean"
+    ) return null;
+    if (
+      question.allowCustom !== undefined &&
+      typeof question.allowCustom !== "boolean"
+    ) return null;
+    if (question.options !== undefined) {
+      if (
+        !Array.isArray(question.options) ||
+        question.options.length < 2 ||
+        question.options.length > 6 ||
+        !question.options.every((option) =>
+          typeof option === "string" && option.length > 0
+        ) ||
+        new Set(question.options).size !== question.options.length
+      ) return null;
+    }
+  }
+  return questions as AskUserInput["questions"];
+}
+
+// 手写校验而不是拉 TypeBox compiler：这里只需要判真假，
+// 且校验位于 Worker 响应信任边界，不应为每次回答编译 schema。
+function isAskUserResponse(input: unknown, value: unknown): boolean {
+  const questions = questionsOf(input);
+  const answers = recordOf(value)?.answers;
+  if (!questions || !Array.isArray(answers) || answers.length !== questions.length) {
     return false;
   }
-  // 什么都没选、也没写字，等于没回答 —— 不该被当成一次有效结算。
-  return record.selections.length > 0 ||
-    (typeof record.text === "string" && record.text.trim().length > 0);
+
+  return questions.every((question, index) => {
+    const answer = recordOf(answers[index]);
+    if (!answer || !Array.isArray(answer.selections)) return false;
+    if (!answer.selections.every((item) => typeof item === "string")) {
+      return false;
+    }
+    if (answer.text !== undefined && typeof answer.text !== "string") {
+      return false;
+    }
+
+    const options = question.options ?? [];
+    const text = typeof answer.text === "string" ? answer.text : "";
+    if (text.length > 2_000) return false;
+    if (answer.selections.some((selection) => !options.includes(selection))) {
+      return false;
+    }
+    if (new Set(answer.selections).size !== answer.selections.length) return false;
+    if (!question.multiSelect && answer.selections.length > 1) return false;
+    const allowCustom = options.length === 0 || question.allowCustom === true;
+    if (!allowCustom && text.trim()) return false;
+    return answer.selections.length > 0 || text.trim().length > 0;
+  });
 }
 
 const suggestFollowupsParameters = Type.Object({
@@ -162,7 +237,7 @@ export function basePiToolCandidates(
         name: "ask_user",
         label: "Ask user",
         description:
-          "Ask the user to choose among a small set of options. Call this tool whenever you need the user to make a choice from limited options — do NOT write plain text like 'please pick A / B / C'. The user's choice comes back to you as this tool's result, so just continue once you have it. Do NOT end your turn after calling this tool.",
+          "Ask all 1-4 user questions needed to continue in one call. Each question may offer 2-6 options, allow multiple selections, and/or allow a custom answer. Do not make one call per question or write plain text like 'please pick A / B / C'. The answers return as this tool's result, so continue the same turn after calling it.",
         parameters: askUserParameters,
         // 永远不会被调用：执行链在 interaction 闸就 park 住了。留一个失败关闭的
         // 实现，是为了万一哪次改动绕过了那道闸，能立刻炸出来而不是静默返回空答案。
@@ -174,18 +249,29 @@ export function basePiToolCandidates(
       }),
       interaction: {
         validateResponse: isAskUserResponse,
-        settle: (_input, response) => {
-          const answer = response as Static<typeof askUserResponse>;
-          const parts = [
-            ...answer.selections,
-            ...(answer.text?.trim() ? [answer.text.trim()] : []),
-          ];
+        settle: (input, response) => {
+          const questions = (input as AskUserInput).questions;
+          const responseAnswers = (response as AskUserResponse).answers;
+          const answers = questions.map((question, index) => {
+            const answer = responseAnswers[index]!;
+            return {
+              question: question.question,
+              selections: answer.selections,
+              ...(answer.text !== undefined ? { text: answer.text.trim() } : {}),
+            };
+          });
           return {
             content: [{
               type: "text",
-              text: `The user answered: ${parts.join(" / ")}`,
+              text: `The user answered:\n${answers.map((answer, index) => {
+                const parts = [
+                  ...answer.selections,
+                  ...(answer.text ? [answer.text] : []),
+                ];
+                return `${index + 1}. ${answer.question}\n   ${parts.join(" / ")}`;
+              }).join("\n")}`,
             }],
-            details: answer,
+            details: { answers },
           };
         },
       },

package/src/pi/tool/compiler.ts

@@ -4,7 +4,16 @@ import type {
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import type { ApprovalReceipt } from "../../kernel/receipts";
-import { boundDurableToolOutput } from "../../layers/context/budget/gate";
+import {
+  boundDurableToolOutput,
+  type BudgetPolicy,
+  spillDurableToolOutput,
+} from "../../layers/context/budget/gate";
+import {
+  type ArtifactRef,
+  serializeOutput,
+  type SpillWorkspace,
+} from "../../lib/artifacts";
 import {
   type ExecutionLevel,
 } from "../../lib/execution-level";
@@ -24,8 +33,8 @@ import {
  * 会让下一次模型调用非法。
  */
 export interface PiToolInteractionSpec {
-  /** 校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
-  readonly validateResponse: (response: unknown) => boolean;
+  /** 结合 Tool 输入校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (input: unknown, response: unknown) => boolean;
   /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
   readonly settle?: (
     input: unknown,
@@ -54,11 +63,14 @@ export interface PiToolCandidate {
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
   readonly interaction?: PiToolInteractionSpec;
+  /** Large payloads spill by default; protocol-shaped results opt into structure. */
+  readonly outputBudget?: BudgetPolicy;
 }
 
 /** 控制候选 Pi 工具如何被编译为可执行工具集。 */
 export interface CompilePiToolsOptions {
   readonly governance?: PiToolGovernance;
+  readonly workspace?: SpillWorkspace;
   readonly settle: (
     call: SettledPiToolCall,
   ) => void | Promise<void>;
@@ -200,6 +212,52 @@ function emitToolTelemetry(
   }
 }
 
+// Most Pi adapters keep the original Tool value in details and its serialized
+// model form in one text block. Spill that original once instead of duplicating
+// it inside an AgentToolResult JSON envelope.
+function spillPayload(result: AgentToolResult<unknown>): unknown {
+  const text = result.content.length === 1 && result.content[0]?.type === "text"
+    ? result.content[0].text
+    : undefined;
+  if (text !== undefined && serializeOutput(result.details).text === text) {
+    return result.details;
+  }
+  return result;
+}
+
+function artifactResult(
+  result: AgentToolResult<unknown>,
+  ref: ArtifactRef,
+): AgentToolResult<unknown> {
+  return {
+    ...result,
+    content: [{
+      type: "text",
+      text: [
+        ref.note,
+        `Path: ${ref.path}`,
+        `Bytes: ${ref.bytes}`,
+        `Preview:\n${ref.preview}`,
+      ].join("\n"),
+    }],
+    details: ref,
+  };
+}
+
+async function durableResult(
+  result: AgentToolResult<unknown>,
+  candidate: PiToolCandidate,
+  workspace: SpillWorkspace | undefined,
+): Promise<AgentToolResult<unknown>> {
+  if ((candidate.outputBudget ?? { kind: "spill" }).kind === "spill") {
+    const ref = await spillDurableToolOutput(spillPayload(result), {
+      workspace,
+    });
+    if (ref) return artifactResult(result, ref);
+  }
+  return boundDurableToolOutput(result) as AgentToolResult<unknown>;
+}
+
 // 记录一次工具失败并在 Turn 达到上限时打开断路器。
 // 受治理 execute 方法在工具或结算失败后调用。
 // 同时记录单输入次数和 Turn 总数，是为了既阻止原样重试又防止换参数无限失败。
@@ -341,9 +399,11 @@ function governedTool(
 
       let result: AgentToolResult<unknown>;
       try {
-        result = boundDurableToolOutput(
+        result = await durableResult(
           await execute(toolCallId, args, signal, onUpdate),
-        ) as AgentToolResult<unknown>;
+          candidate,
+          options.workspace,
+        );
       } catch (cause) {
         const message = errorMessage(cause);
         const result = boundDurableToolOutput({
@@ -442,7 +502,7 @@ export function compilePiTools(
   options: CompilePiToolsOptions,
 ): AgentTool<any, any>[] {
   if (!options?.settle) {
-    throw new Error("Pi Tool settlement port is required");
+    throw new Error("SpringBrand Tool settlement port is required");
   }
   return candidates.map((candidate) => governedTool(candidate, options));
 }

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

@@ -3,10 +3,14 @@ import {
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
 import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
+import { jsonSchema, tool as aiTool, type ToolSet } from "ai";
 import type {
-  RuntimeCodeExecutionPort,
   WorkspacePort,
 } from "../../kernel/bindings";
+import type {
+  RuntimeCodeExecutionFactory,
+  ToolRegistry,
+} from "../../tool-registry";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
@@ -19,32 +23,55 @@ const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
  *
  * Think 的独立 execute factory 接受显式宿主参数，不要求 Agent 继承 Think；这里只借它组装 Codemode Runtime、Dynamic Worker executor 和已限定范围的 Workspace state connector。
  */
-export function createWorkspaceCodeExecutionPort(options: {
+function codeExecutionTools(tools: ToolRegistry): ToolSet {
+  return Object.fromEntries(Object.entries(tools).map(([name, spec]) => [
+    name,
+    aiTool({
+      description: spec.description,
+      inputSchema: jsonSchema(spec.parameters as never),
+      execute: (input, options) => spec.execute(input, {
+        toolCallId: options?.toolCallId ?? name,
+        signal: options?.abortSignal ?? new AbortController().signal,
+      }),
+    }),
+  ]));
+}
+
+export function createWorkspaceCodeExecutionFactory(options: {
   readonly ctx: DurableObjectState;
   readonly loader: WorkerLoader;
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
-}): RuntimeCodeExecutionPort {
-  const { tool } = createExecuteRuntime({
-    ctx: options.ctx,
-    loader: options.loader,
-    globalOutbound: options.outbound,
-    // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
-    timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-    state: createWorkspaceStateBackend(
-      options.workspace as unknown as WorkspaceFsLike,
-    ),
-    name: "execute",
-  });
-  const execute = tool.execute;
-  if (typeof execute !== "function") {
-    throw new Error("Think createExecuteRuntime returned a non-executable tool");
-  }
+}): RuntimeCodeExecutionFactory {
   return {
-    execute: (input) => Promise.resolve(execute(input, {
-      toolCallId: "execute",
-      messages: [],
-      context: undefined,
-    })),
+    create(tools) {
+      const { tool } = createExecuteRuntime({
+        ctx: options.ctx,
+        loader: options.loader,
+        globalOutbound: options.outbound,
+        tools: codeExecutionTools(tools),
+        // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
+        timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
+        state: createWorkspaceStateBackend(
+          options.workspace as unknown as WorkspaceFsLike,
+        ),
+        name: "execute",
+      });
+      const { description, execute } = tool;
+      if (typeof description !== "string" || description.length === 0) {
+        throw new Error("Think createExecuteRuntime returned a tool without a description");
+      }
+      if (typeof execute !== "function") {
+        throw new Error("Think createExecuteRuntime returned a non-executable tool");
+      }
+      return {
+        description,
+        execute: (input) => Promise.resolve(execute(input, {
+          toolCallId: "execute",
+          messages: [],
+          context: undefined,
+        })),
+      };
+    },
   };
 }

package/src/pi/tool/core.ts

@@ -12,10 +12,6 @@ import { serializeOutput } from "../../lib/artifacts";
 import type { PiLoadedExtension } from "../assembly/extensions";
 import { aiToolToPi } from "./ai-adapter";
 import type { PiToolCandidate } from "./compiler";
-import {
-  toolRegistryFromPiCandidates,
-  type ToolRegistry,
-} from "../../tool-registry";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
 
@@ -125,16 +121,7 @@ export function codeExecutionPiToolCandidate(
   const tool: AgentTool<typeof executeParameters> = {
     name: "execute",
     label: "Execute JavaScript",
-    description:
-      "Run JavaScript in a short-lived Code Mode Dynamic Worker and return a value. This is your " +
-      "raw-network and tool-composition instrument, not a general web-search tool. Call fetch directly " +
-      "when you need a raw response, custom headers/method/body, a structured API, or content that " +
-      "web_search could not retrieve. Check res.status; when several known endpoints are necessary, " +
-      "fetch them in one invocation. Also available: " +
-      "state.* for your workspace filesystem (readFile/writeFile/glob/searchFiles/replaceInFiles, " +
-      "each taking one object argument), and codemode.step(name, fn) to run a side-effecting block " +
-      "exactly once so it survives replay. Write plain JavaScript — TypeScript type annotations are " +
-      "a syntax error. Use return for the result and console.log for notes.",
+    description: runtime.description,
     parameters: executeParameters,
     // 把模型提供的 JavaScript 交给 Codemode Runtime 执行。
     // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。
@@ -173,19 +160,11 @@ export function codeExecutionPiToolCandidate(
   return {
     owner: "core:codemode",
     requiredExecutionLevel: "high",
+    outputBudget: { kind: "structure" },
     source: "codemode",
     summary: "Run JavaScript with network and configured connector access",
     tool,
   };
 }
 
-/** 从 Codemode Runtime Port 生成 `execute` Tool。 */
-export function createCodeExecutionTool(
-  runtime: RuntimeCodeExecutionPort,
-): ToolRegistry {
-  return toolRegistryFromPiCandidates([
-    codeExecutionPiToolCandidate(runtime),
-  ]);
-}
-
 // #endregion

package/src/pi/tool/index.ts

@@ -30,4 +30,5 @@ export * from "./schedule";
 export * from "./skill";
 export * from "./subagent";
 export * from "./workspace-sandbox";
+export * from "./workspace-revision";
 export * from "./web-search";

package/src/pi/tool/mcp.ts

@@ -59,7 +59,8 @@ export interface PiMcpHost {
      * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
      */
     callTool(
-      ...args: Parameters<MCPClientManager["callTool"]>
+      params: Parameters<MCPClientManager["callTool"]>[0],
+      options?: { signal?: AbortSignal },
     ): Promise<unknown>;
   };
 }
@@ -333,7 +334,6 @@ export function createPiMcpToolCandidates(
           name: mcpTool.name,
           arguments: args,
         },
-        undefined,
         { signal },
       ),
       {