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

package/package.json

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

package/src/kernel/interaction-lifecycle.ts

@@ -12,7 +12,7 @@ import type {
   PiToolInteraction,
   PiToolInteractionCancelReason,
 } from "../pi/runtime-adapter";
-import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 
 // #region 类型约定
 
@@ -43,10 +43,10 @@ export interface InteractionRecord extends PiToolInteraction {
  * `content` / `details` 由 Tool 自己的 `settle` 映射产出 —— 本流程不解释响应体语义。
  * 取消不带载荷，由纯函数层用固定文案兜底。
  */
-export interface InteractionSettlementPayload {
-  readonly content: ToolResultMessage["content"];
-  readonly details: unknown;
-}
+export type InteractionSettlementPayload = Omit<
+  AgentToolResult<unknown>,
+  "terminate"
+>;
 
 // 宿主用这些依赖把 interaction 状态机接入数据库、Pi 恢复计算和 Turn 续跑。
 interface InteractionLifecycleOptions<

package/src/kernel/tool-surface.ts

@@ -31,6 +31,7 @@ export interface ToolSpec extends Partial<
   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,

package/src/lib/prompt.ts

@@ -18,8 +18,7 @@ export const PERSONA =
 export const RUNTIME =
   "Runtime: this agent runs on Cloudflare Workers. When execute is present, its Code Mode Dynamic Worker is your " +
   "instrument — code there runs with outbound network access (fetch), your " +
-  "workspace filesystem (state.*), and your other tools (tools.* when that connector is available). Put repeated or multi-step work " +
-  "in one execute instead of making consecutive top-level Tool calls. Use it for raw or customized HTTP " +
+  "workspace filesystem (state.*), and the tools.* methods listed in its own description. Use it for raw or customized HTTP " +
   "requests, parsing a payload, hitting several known endpoints, or computing over a file. Write plain " +
   "JavaScript — the sandbox evaluates " +
   "it directly, so TypeScript type annotations (`: number`, `as Type`) are a syntax error, and there " +
@@ -33,7 +32,9 @@ export const BEHAVIOR =
   "When uncertain, investigate before answering rather than guess or confirm a belief. Match response " +
   "length to the task — a short question gets a short answer; skip filler preamble and don't restate " +
   "what you just did. Be proactive when asked to *do* something (take the needed follow-up actions too), " +
-  "but when the user only asks *how* to approach something, answer first and don't jump into changes.";
+  "but when the user only asks *how* to approach something, answer first and don't jump into changes. " +
+  "A failed Tool call produced no requested result. Never infer completion or fabricate URLs, files, identifiers, or business results " +
+  "from a failed call's arguments or identifiers; correct the Tool route or report the failure.";
 
 // The main Agent alone owns user-visible planning.
 export const PLANNING =
@@ -43,15 +44,18 @@ export const PLANNING =
   "one step in_progress at a time and don't batch completions. Do not make a plan for a single trivial " +
   "step or a purely conversational reply — just do it.";
 
+const TOOL_ROUTING =
+  "Tools: execute can call only the tools.* methods explicitly listed in its description; that list is exhaustive. Never guess a tools.* method. " +
+  "If a required top-level Tool is not visible, do not use execute. Call top-level Tool Search with that exact name, then call the discovered Tool directly. " +
+  "codemode.search searches only methods already installed inside execute; it cannot discover deferred top-level Tools.";
+
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
-  "Tools: When execute is present, call a top-level Tool directly only for a single standalone Tool call or when that Tool is unavailable " +
-  "inside execute. Any operation that needs the same Tool more than once, two or more related file, Skill, Extension, MCP, or Host Tool calls, " +
-  "or branching or repetition MUST use one execute. Do not make repeated top-level calls for that work. Inside execute, use state.* for " +
-  "workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
-  "Tools available only at the top level must stay Direct. " +
-  "Some Tools may be deferred and absent from the initial list. When Tool Search is available, before saying that a requested capability or named Tool is unavailable, use the available Tool Search once. " +
-  "If the user names a Tool, search that exact name by itself first. Searchable categories may include workspace and files, browser and web, interaction and planning, memory and scheduling, Skills, Extensions, MCP, Plugins, and Host capabilities; discover them only when needed. " +
+  TOOL_ROUTING +
+  " Relatedness, repetition, or multiple calls never overrides this availability rule. " +
+  "When every required Tool is available inside execute, use one execute for repeated or related calls, branching, or repetition. Inside execute, " +
+  "use state.* for workspace file operations, tools.* for other host capabilities, a loop for repeated calls, and Promise.all for independent calls. " +
+  "Top-level-only Tools remain Direct even when called repeatedly. " +
   "For web tasks, use web_search for web discovery, current facts, cited research, " +
   "and public URL analysis. For web access specifically, use execute Code Mode only for raw or customized network requests, structured " +
   "API calls, or when web_search cannot retrieve the required content; do not use execute for ordinary web " +
@@ -65,7 +69,7 @@ export const TOOLS =
   "When execute is present, make related file changes in one execute with state.*; when execute is absent, use one write or bash operation instead of serial edits. " +
   "Do not re-plan or explain between consecutive tool calls. When a run is within the last five model turns, stop expanding scope and " +
   "prioritize verification, saving durable results, and the final response. " +
-  "When related Tool calls can run independently and execute is present, run them inside that execute rather than as parallel top-level calls; " +
+  "When related Tool calls can run independently, all are available inside execute, and execute is present, run them inside that execute rather than as parallel top-level calls; " +
   "only independent top-level-only Direct Tools should be issued together in one turn. When you reference " +
   "code, cite it as file_path:line_number.";
 
@@ -166,5 +170,5 @@ export function assembleSystemPrompt(base?: string | null): string {
  * Agent、Runtime 和 Memory 的术语见 `src/index.ts`。
  */
 export function assembleSubagentPrompt(persona: string): string {
-  return [persona, RUNTIME, BEHAVIOR].join("\n\n");
+  return [persona, RUNTIME, BEHAVIOR, TOOL_ROUTING].join("\n\n");
 }

package/src/pi/message/contract.ts

@@ -4,7 +4,7 @@ export type UIChatTrigger = "submit-message" | "regenerate-message";
 
 /** A user-selected Runtime capability persisted with the visible UIMessage. */
 export interface RequestedCapability {
-  readonly kind: "skill" | "plan";
+  readonly kind: "skill" | "tool" | "plan";
   readonly name: string;
   readonly label: string;
 }

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

@@ -18,6 +18,7 @@ export {
 import {
   pinPiRuntime,
   preparePiRuntime,
+  readPreparedPiRuntime,
   type PinPiRuntimeOptions,
   type PinnedPiRuntime,
   type PreparePiRuntimeOptions,
@@ -143,6 +144,12 @@ export class PiRuntimeAdapter {
     return preparePiRuntime(options, this.owner);
   }
 
+  hasTool(prepared: PreparedPiRuntime, name: string): boolean {
+    return readPreparedPiRuntime(prepared, this.owner).candidates.some(
+      (candidate) => candidate.tool.name === name,
+    );
+  }
+
   /**
    * 用已经通过加载检查的快照启用当前部署声明的模型目录。
    *

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

@@ -15,6 +15,8 @@ import {
   type PiToolRecoveryState,
 } from "../turn";
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { isEqual } from "lodash-es";
 import {
   aiSdkRecoveryCodec,
   shouldCreditStreamProgress,
@@ -35,10 +37,7 @@ export interface PiRecoveredToolSettlement {
   readonly toolCallId: string;
   readonly toolName: string;
   readonly args: unknown;
-  readonly result: {
-    readonly content: ToolResultMessage["content"];
-    readonly details: unknown;
-  };
+  readonly result: Omit<AgentToolResult<unknown>, "terminate">;
   readonly isError: boolean;
   readonly createdAt: number;
 }
@@ -75,10 +74,7 @@ export type PiRecoveryCommand =
         | {
             readonly kind: "respond";
             readonly response: unknown;
-            readonly result: {
-              readonly content: ToolResultMessage["content"];
-              readonly details: unknown;
-            };
+            readonly result: Omit<AgentToolResult<unknown>, "terminate">;
           }
         | {
             readonly kind: "cancel";
@@ -89,10 +85,7 @@ export type PiRecoveryCommand =
       readonly kind: "record-tool-result";
       readonly toolCallId: string;
       readonly toolName: string;
-      readonly result: {
-        readonly content: ToolResultMessage["content"];
-        readonly details: unknown;
-      };
+      readonly result: AgentToolResult<unknown>;
       readonly isError: boolean;
       readonly timestamp: number;
       readonly needsContinuation?: boolean;
@@ -226,6 +219,10 @@ function recoveredToolSettlements(
       result: {
         content: toolResult.content,
         details: toolResult.details,
+        ...(toolResult.usage ? { usage: toolResult.usage } : {}),
+        ...(toolResult.addedToolNames?.length
+          ? { addedToolNames: toolResult.addedToolNames }
+          : {}),
       },
       isError: toolResult.isError,
       createdAt: toolResult.timestamp,
@@ -248,21 +245,17 @@ function approvalExecutionId(continuationKey: string): string | null {
 // 记录必须已经存在 —— 拿不到 toolCallId/toolName 就无法把结果绑回原调用，这时失败关闭而不是编一个 id。
 function interactionToolResult(
   interaction: PiToolInteraction | undefined,
-  result: {
-    readonly content: ToolResultMessage["content"];
-    readonly details: unknown;
-  },
+  result: Omit<AgentToolResult<unknown>, "terminate">,
   timestamp: number,
 ): ToolResultMessage {
   if (!interaction) {
     throw new Error("SpringBrand Tool interaction is missing for its response");
   }
   return {
+    ...result,
     role: "toolResult",
     toolCallId: interaction.toolCallId,
     toolName: interaction.toolName,
-    content: result.content,
-    details: result.details,
     isError: false,
     timestamp,
   };
@@ -448,9 +441,9 @@ export function decidePiRecovery(
     const existing = state.toolCalls[record.toolCallId];
     if (existing) {
       if (
-        existing.toolName !== record.toolName ||
-        existing.retry !== record.retry ||
-        JSON.stringify(existing.input) !== JSON.stringify(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}`,
@@ -614,12 +607,16 @@ export function decidePiRecovery(
       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 }
+        : {}),
       isError: command.isError,
       timestamp: command.timestamp,
     };
     const existing = state.toolCalls[command.toolCallId]?.result;
     if (existing) {
-      if (JSON.stringify(existing) !== JSON.stringify(toolResult)) {
+      if (!isEqual(existing, toolResult)) {
         throw new Error(
           `Conflicting SpringBrand Tool result for ${command.toolCallId}`,
         );

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

@@ -346,11 +346,10 @@ export class PiRuntimeTranscript {
     return this.append(
       `${submissionId}:tool:${settlement.toolCallId}`,
       {
+        ...settlement.result,
         role: "toolResult",
         toolCallId: settlement.toolCallId,
         toolName: settlement.toolName,
-        content: settlement.result.content,
-        details: settlement.result.details,
         isError: settlement.isError,
         timestamp: settlement.createdAt,
       },

package/src/pi/tool/compiler.ts

@@ -39,7 +39,7 @@ export interface PiToolInteractionSpec {
   readonly settle?: (
     input: unknown,
     response: unknown,
-  ) => AgentToolResult<unknown>;
+  ) => Omit<AgentToolResult<unknown>, "terminate">;
 }
 
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */

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

@@ -18,6 +18,10 @@ import type {
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
+const CODEMODE_TOOL_SURFACE_GUIDANCE =
+  "The `tools.*` Available list below is exhaustive, not examples. Inside execute, call only methods in that list; " +
+  "never guess or construct a `tools.*` method name. If a required Tool is absent, leave execute and call it at the top level, " +
+  "using top-level Tool Search first when it is deferred. `codemode.search` cannot add methods to `tools.*`.";
 
 /**
  * 宿主的 Browser Rendering 绑定，只取本仓真正用到的那一面。
@@ -42,10 +46,18 @@ function codeExecutionTools(tools: ToolRegistry): ToolSet {
     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,
-      }),
+      execute: async (input, options) => {
+        const result = await spec.execute(input, {
+          toolCallId: options?.toolCallId ?? name,
+          signal: options?.abortSignal ?? new AbortController().signal,
+        });
+        return result != null &&
+            typeof result === "object" &&
+            "content" in result &&
+            Array.isArray((result as { content?: unknown }).content)
+          ? (result as { details?: unknown }).details ?? result
+          : result;
+      },
     }),
   ]));
 }
@@ -183,10 +195,10 @@ export function createWorkspaceCodeExecutionFactory(options: {
       const port = toCodeExecutionPort(tool, "execute");
       return {
         ...port,
-        description: port.description.replace(
+        description: `${CODEMODE_TOOL_SURFACE_GUIDANCE}\n\n${port.description.replace(
           "- Do not use `fetch` — use connector SDKs.",
           "- Raw `fetch` is available inside `codemode.step(...)`; prefer connector SDKs when one owns the target.",
-        ),
+        )}`,
       };
     },
   };

package/src/pi/turn/tool-recovery.ts

@@ -1,4 +1,5 @@
 import type { ToolResultMessage } from "@earendil-works/pi-ai";
+import { isEqual } from "lodash-es";
 import { EXECUTION_LEVELS } from "../../lib/execution-level";
 import {
   decidePiToolApproval,
@@ -444,11 +445,10 @@ function sameToolInput(
     { type: "tool-input" }
   >,
 ): boolean {
-  // 待确认：JSON.stringify 对对象键顺序敏感；当前写入链会保留输入顺序，重建输入的调用方可能产生语义相同但顺序不同的对象。
   return (
     previous.toolName === milestone.toolName &&
     previous.retry === milestone.retry &&
-    JSON.stringify(previous.input) === JSON.stringify(milestone.input)
+    isEqual(previous.input, milestone.input)
   );
 }
 

package/src/runtime.ts

@@ -360,7 +360,7 @@ function requestedCapabilitiesOf(metadata: unknown): RequestedCapability[] {
     }
     const capability = value as Record<string, unknown>;
     if (
-      (capability.kind !== "skill" && capability.kind !== "plan") ||
+      (capability.kind !== "skill" && capability.kind !== "tool" && capability.kind !== "plan") ||
       typeof capability.name !== "string" ||
       !capability.name.trim() ||
       typeof capability.label !== "string" ||
@@ -1352,6 +1352,16 @@ export abstract class AgentRuntimeKernel<
         );
         continue;
       }
+      if (capability.kind === "tool") {
+        if (!this.pi.hasTool(this.preparedPi(), capability.name)) {
+          throw new Error(`Requested Tool is not installed: ${capability.name}`);
+        }
+        context.push(
+          `requested capability: tool/${capability.name}`,
+          `required action: call tool "${capability.name}" when handling the task`,
+        );
+        continue;
+      }
       if (capability.name !== "plan") {
         throw new Error(`Unknown plan capability: ${capability.name}`);
       }
@@ -4076,10 +4086,7 @@ export abstract class AgentRuntimeKernel<
     const settled = spec.settle
       ? spec.settle(input, response)
       : defaultInteractionResult(response);
-    return this.interactions.respond(pending.interactionId, response, {
-      content: settled.content,
-      details: settled.details,
-    });
+    return this.interactions.respond(pending.interactionId, response, settled);
   }
 
   /**

package/src/tool-registry.ts

@@ -85,13 +85,12 @@ export function piCandidateToToolSpec(candidate: PiToolCandidate): ToolSpec {
         name,
         arguments: input as Record<string, unknown>,
       });
-      const result = await execute(
+      return execute(
         ctx.toolCallId,
         validated,
         ctx.signal,
         undefined,
       );
-      return result.details ?? result;
     },
   };
 }