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

package/package.json

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

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/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 绑定，只取本仓真正用到的那一面。
@@ -183,10 +187,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/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}`);
       }