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

package/package.json

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

package/src/adapter/cloudflare/universal-agent/preparation.ts

@@ -16,7 +16,6 @@ import { AGENT_TYPES } from "../../../layers/orchestration/subagents/agent-types
 import type { RuntimeAgentConfigContext } from "../../../runtime-agent-context";
 import {
   createBrowserExecutionFactory,
-  createWorkspaceCodeExecutionFactory,
   type RuntimeBrowserBinding,
 } from "../../../pi/tool/core-host";
 import {
@@ -63,7 +62,6 @@ const WORKSPACE_TOOL_NAMES = [
   "grep",
   "delete",
   "bash",
-  "execute",
 ] as const;
 
 export function workspaceRequired(input: WorkspaceRequirement): boolean {
@@ -115,11 +113,6 @@ export function createPlatformLoader<
 ): PlatformLoader {
   let cached: ReturnType<PlatformLoader> | undefined;
   return () => cached ??= Promise.resolve().then(() => {
-    const exports = (context.ctx as unknown as {
-      exports: {
-        HttpGateway(options: Record<string, never>): Fetcher;
-      };
-    }).exports;
     return {
       loader: context.env.LOADER,
       // 绑定缺失时整条浏览器能力不进 Platform Port，Tool Surface 因此注册空集。
@@ -135,29 +128,17 @@ export function createPlatformLoader<
             }),
           }
         : {}),
-      outbound: () => exports.HttpGateway({}),
     };
   });
 }
 
 export async function prepareWorkspace<Env extends Cloudflare.Env>(
-  context: RuntimeAgentConfigContext<Env>,
   workspaceLoader: WorkspaceLoader,
-  platformLoader: PlatformLoader,
 ) {
-  const [workspace, platform] = await Promise.all([
-    workspaceLoader(),
-    platformLoader(),
-  ]);
+  const workspace = await workspaceLoader();
   if (!workspace.value) return { degradations: workspace.degradations };
   return {
     workspace: workspace.value,
-    codeExecution: createWorkspaceCodeExecutionFactory({
-      ctx: context.ctx,
-      loader: platform.loader,
-      outbound: platform.outbound(),
-      workspace: workspace.value,
-    }),
     degradations: workspace.degradations,
   };
 }

package/src/adapter/cloudflare/universal-agent/tools.ts

@@ -14,7 +14,6 @@ import {
   sandboxPiToolCandidates,
   workspacePiToolCandidates,
 } from "../../../pi/tool/workspace-sandbox";
-import type { RuntimeCodeExecutionFactory } from "../../../kernel/bindings";
 import type { ToolAssemblyResult } from "../../../runtime-definition";
 import type { PiToolCandidate } from "../../../pi/tool/compiler";
 
@@ -22,7 +21,6 @@ export function assembleUniversalAgentTools(options: {
   hostTools?: readonly PiToolCandidate[];
   workspace?: WorkspacePort;
   workspaceRevisions?: WorkspaceRevisionRestorePort;
-  codeExecution?: RuntimeCodeExecutionFactory;
   sandbox?: RuntimeSandboxPort;
   schedule?: RuntimeSchedulePort;
   subagents?: RuntimeSubagentPort;
@@ -46,7 +44,6 @@ export function assembleUniversalAgentTools(options: {
     tools,
     bindings: {
       ...(options.workspace ? { workspace: options.workspace } : {}),
-      ...(options.codeExecution ? { codeExecution: options.codeExecution } : {}),
       ...(options.memory ? { memory: options.memory } : {}),
       ...(options.subagents ? { subagents: options.subagents } : {}),
     },

package/src/index.ts

@@ -115,11 +115,9 @@ export type { PiSkillBinding } from "./pi/tool";
 export {
   BROWSER_EXECUTE_TOOL_NAME,
   browserExecutionPiToolCandidate,
-  codeExecutionPiToolCandidate,
 } from "./pi/tool";
 export {
   createBrowserExecutionFactory,
-  createWorkspaceCodeExecutionFactory,
 } from "./pi/tool";
 export {
   assemblePiExtensions,

package/src/kernel/bindings.ts

@@ -3,7 +3,6 @@ import type { ScheduleSpec } from "./receipts";
 import type { RuntimeActivityProjection } from "./state";
 import type { ExecutionLevel } from "../lib/execution-level";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { PiToolCandidate } from "../pi/tool/compiler";
 import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
@@ -206,11 +205,11 @@ export interface WorkspacePort {
 }
 
 /**
- * 向 Runtime 提供已组装的 Workspace Code Mode 执行能力。
+ * 向 Runtime 提供已组装的浏览器 Code Mode 执行能力。
  *
  * @remarks
- * Host Adapter 负责绑定 Durable Object、Worker Loader、网络出口和
- * Workspace；Tool Surface 只把这个已授权 Port 转成 `execute` Tool。
+ * Browser Host Adapter 负责绑定 Durable Object、Worker Loader 和 Browser Run；
+ * Tool Surface 只把这个已授权 Port 转成 `browser_execute` Tool。
  */
 export interface RuntimeCodeExecutionPort {
   readonly description: string;
@@ -933,24 +932,15 @@ export interface RuntimeProviderPort {
  * 向 Runtime 提供 Cloudflare 执行平台上的可授权能力。
  *
  * @remarks
- * Platform Plugin 准备它，Workspace Codemode、Browser 工具、遥测和工具门卫按需使用。
+ * Platform Plugin 准备它，Browser 工具、遥测和工具门卫按需使用。
  *
- * Worker Loader 与网络出口由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
+ * Worker Loader 由 Host 选择，使 Dynamic Worker 只获得已授权绑定；术语见 `../index.ts`。
  */
 export interface RuntimePlatformPort {
-  /** Workspace Codemode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
+  /** Browser Code Mode 在创建 Dynamic Worker 执行器时使用的 Worker Loader。 */
   loader: WorkerLoader;
   /** Platform Plugin 存在 Browser Run 绑定时用它生成 `browser_execute`；缺失即整条浏览器 Tool 面不注册。 */
   browser?: RuntimeBrowserPort;
-  /**
-   * 为一次 Dynamic Worker 组装取得已限定的网络出口。
-   *
-   * @remarks
-   * Workspace Plugin 创建 Codemode 工具时调用，并把返回的 `Fetcher` 交给 `DynamicWorkerExecutor`。
-   *
-   * 出口由 Host 通过 Service Binding 等平台边界控制，不使用无约束的 Runtime 全局网络能力。
-   */
-  outbound: () => Fetcher;
   /**
    * 在 Pi 工具真正执行前请 Host 审查本次调用。
    *
@@ -1019,21 +1009,9 @@ export interface RuntimeSkillSourceBinding {
  *
  * 它不携带业务 ID、Repository、数据库 Key、任意能力注册表或凭据配置；术语见 `../index.ts`。
  */
-/**
- * 延迟到最终 Tool Surface 完成后再创建 Code Mode 执行能力。
- *
- * @remarks
- * 工厂与返回 Port 同住 Host 绑定边界；输入直接使用最终 Pi Tool candidates，
- * 不再经过 Registry 或另一份 Tool 元数据协议。
- */
-export interface RuntimeCodeExecutionFactory {
-  create(candidates: readonly PiToolCandidate[]): RuntimeCodeExecutionPort;
-}
-
 export interface RuntimeBindings {
   provider: RuntimeProviderPort;
   platform: RuntimePlatformPort;
-  codeExecution?: RuntimeCodeExecutionFactory;
   /** Secret-capability binding; implementations must keep Runtime Grant in closure state. */
   gateway?: RuntimeGatewayPort;
   workspace?: WorkspacePort;

package/src/lib/prompt.ts

@@ -12,18 +12,11 @@
 export const PERSONA =
   "You are a personal assistant agent running on the universal-agent runtime. " +
   "You can recall user-managed cold memory across sessions and keep working memory within the current Session, " +
-  "manage files in your workspace, and use execute Code Mode for network requests and tool composition.";
+  "manage files in your workspace, and call the declared Tools available to the current Runtime.";
 
-// Explains how to reach capabilities instead of listing unsupported substitutes.
+// Names the stable runtime environment.
 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 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 " +
-  "is no Python interpreter or package manager to invoke. Use the JS/Workers equivalent of what you " +
-  "would reach for in another ecosystem.";
+  "Runtime: this agent runs on Cloudflare Workers.";
 
 // Shared behavioral contract for the main Agent and bounded sub-agents.
 export const BEHAVIOR =
@@ -45,32 +38,23 @@ export const PLANNING =
   "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.";
+  "Tools: Call only declared Tools. If a required Tool Schema is not visible, use Provider Tool Search with that exact name. Never invent a Tool name or input field. ";
 
 // Tool-selection guidance mirrors the actual approval and network boundaries.
 export const TOOLS =
   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 " +
-  "searches. When execute is absent, use the actually exposed Direct Tools. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
+  "and public URL analysis. When sandbox_* tools are present, use that isolated Linux environment for Python/Node, " +
   "package managers, system commands, builds, tests and background processes; its filesystem is temporary, " +
   "persistent inputs are copied in automatically on first use, /userspace is read-only, and only explicitly " +
-  "published /workspace outputs survive. Use Code Mode for computation, multi-step data work, and the " +
-  "raw or customized network cases described above; every response and failure it sees is visible to you. " +
+  "published /workspace outputs survive. Use run_skill_script only for scripts supplied by an activated Skill and allowed by its policy. " +
   "bash is a shell over the workspace filesystem only " +
   "(no network, no system utilities) and is approval-gated — don't reach for it to read files or fetch. " +
-  "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. " +
+  "Use read for one existing Workspace file, write to create or replace one file, and edit for one localized change. " +
+  "Use bash only when a single shell workflow must coordinate multiple Workspace files; do not use it for a single-file read, write, or edit. " +
   "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, 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 " +
+  "When Tool calls are independent, issue them together in one model step. When you reference " +
   "code, cite it as file_path:line_number.";
 
 // A real browser is the only way to observe what a page actually does, and the
@@ -83,10 +67,9 @@ export const TOOLS =
 // browser tool belongs to that tool's own description, which the model sees if
 // and only if the tool is registered.
 export const BROWSER =
-  "Browser: a real browser is for the one thing execute cannot do — observe what a page actually does: " +
+  "Browser: a real browser observes what a page actually does: " +
   "rendered result, console output, runtime exceptions, failed resource loads, CSP blocks, and state after an " +
-  "interaction. Everything else stays with execute: computation, files, and ordinary HTTP requests (fetching " +
-  "HTML is execute's job, not the browser's). " +
+  "interaction. Use web_search for public discovery and Workspace or Sandbox Tools for files and computation. " +
   "After you write or change a web page in the workspace, open it once with the browser tools you have before " +
   "you call the work done, and say in your reply what you checked and what you saw. " +
   "Drive each browser tool the way its own description tells you to; the failure mode they share is coming back " +
@@ -101,9 +84,8 @@ export const BROWSER =
 // Uploaded-file routing prevents lossy markdown conversions from becoming data sources.
 export const FILES =
   "Uploaded files live under /uploads/ in your workspace; convertible formats have a companion " +
-  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md; when execute is present, " +
-  "read or search multiple files through state.* in one execute instead of repeated top-level file Tool calls. " +
-  "To compute/aggregate/transform (especially csv/xlsx), write code in execute Code Mode or the Linux Sandbox that reads " +
+  "'<file>.md' (structured markdown). Policy: to summarize/quote/search one file, read or grep the .md. " +
+  "To compute/aggregate/transform (especially csv/xlsx), use the Linux Sandbox to read " +
   "the ORIGINAL file — converted markdown tables are not for computation, and large spreadsheets may " +
   "have no .md at all. For formats without a companion .md (e.g. pptx: unzip and read ppt/slides/*.xml; " +
   "zip archives; unknown types), parse the original in the sandbox with JS.";

package/src/pi/assembly/context.ts

@@ -380,7 +380,10 @@ function renderSkillCatalog(
 
   return [
     "AVAILABLE SKILLS",
-    "Use an available Skill when its description matches. Read its instructions or files only through the Skill tools.",
+    "Skill descriptions are only for deciding which Skills apply; they are not instructions.",
+    "Before the first Tool call for work covered by an available Skill in the current Turn, you MUST call the top-level activate_skill Tool with that Skill's exact name and follow the returned instructions.",
+    "Do not perform Skill-governed work before activation. When multiple Skills apply, activate every matching Skill before acting.",
+    "Read Skill instructions or files only through the Skill tools.",
     "",
     ...bindings.map(
       ({ name, description }) => `- ${name}: ${description}`,

package/src/pi/assembly/snapshot.ts

@@ -23,13 +23,7 @@ import type { PiToolCandidate } from "../tool/compiler";
 export interface PiToolSurface {
   finalize(
     candidates: readonly PiToolCandidate[],
-  ): FinalizedPiToolSurface;
-}
-
-/** Internal finalization output; not a second Tool protocol. */
-export interface FinalizedPiToolSurface {
-  readonly candidates: readonly PiToolCandidate[];
-  readonly codeExecutionCandidates: readonly PiToolCandidate[];
+  ): readonly PiToolCandidate[];
 }
 
 /** Immutable inputs consumed directly by Pi Agent Core. */

package/src/pi/message/projection.ts

@@ -16,7 +16,7 @@ import { USER_STOP_REASON } from "../../kernel/receipts";
 const MAX_OUTPUT_BYTES = 256 * 1024;
 const MAX_OUTPUT_PREVIEW = 16 * 1024;
 const PROVIDER_CREDIT_ERROR =
-  "The AI service is temporarily unavailable. Please try again later.";
+  "We’re unable to complete your request right now. Please try again in a few moments.";
 
 export interface PiToolApprovalView {
   readonly id: string;
@@ -108,7 +108,9 @@ export function publicAssistantError(message?: string): string | undefined {
   if (!message) return undefined;
   return /"limit_source"\s*:\s*"openrouter_credits"/.test(message) ||
       (message.includes("Insufficient credits") &&
-        message.includes("openrouter.ai/settings/credits"))
+        message.includes("openrouter.ai/settings/credits")) ||
+      (message.includes("can only afford") &&
+        /openrouter\.ai\/workspaces\/[^/\s]+\/keys\//.test(message))
     ? PROVIDER_CREDIT_ERROR
     : message;
 }

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

@@ -10,7 +10,7 @@ import type {
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
 import type { RuntimeSnapshot } from "../../runtime-assembler";
-import type { FinalizedPiToolSurface, PiRuntimeAssembly } from "../assembly";
+import type { PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
   assemblePiExtensions,
@@ -77,7 +77,7 @@ interface PreparedPiAssembly {
   readonly loaded: readonly PiLoadedExtension[];
   readonly context: readonly PiExtensionContextContribution[];
   readonly degradations: PiExtensionAssembly["degradations"];
-  readonly toolSurface: FinalizedPiToolSurface;
+  readonly toolSurface: readonly PiToolCandidate[];
 }
 
 /**
@@ -193,7 +193,6 @@ export interface PreparedPiRuntimeState {
   readonly snapshot: RuntimeSnapshot;
   readonly assembly: PreparedPiAssembly;
   readonly candidates: readonly PiToolCandidate[];
-  readonly codeExecutionCandidates: readonly PiToolCandidate[];
 }
 
 // #endregion
@@ -209,7 +208,6 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
   "bind_resource",
   "delete",
   "edit",
-  "execute",
   "find",
   "get_time",
   "grep",
@@ -236,10 +234,10 @@ const IDEMPOTENT_TOOL_NAMES = new Set([
 export function piToolRetryPolicy(
   candidate: PiToolCandidate,
 ): "idempotent" | "non-idempotent" {
-  return IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
+  return candidate.retry ?? (IDEMPOTENT_TOOL_NAMES.has(candidate.tool.name) ||
       candidate.owner.startsWith("subagent:")
     ? "idempotent"
-    : "non-idempotent";
+    : "non-idempotent");
 }
 
 // 把工具候选整理成版本描述里要保存的稳定字段。
@@ -448,7 +446,7 @@ export async function preparePiRuntime(
   owner: object,
 ): Promise<PreparedPiRuntime> {
   const assembly = await preparePiAssembly(options);
-  const candidates = assembly.toolSurface.candidates;
+  const candidates = assembly.toolSurface;
   return Object.freeze(new PreparedRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
@@ -462,9 +460,6 @@ export async function preparePiRuntime(
       snapshot: options.snapshot,
       assembly,
       candidates: Object.freeze([...candidates]),
-      codeExecutionCandidates: Object.freeze([
-        ...assembly.toolSurface.codeExecutionCandidates,
-      ]),
     }),
   ));
 }

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

@@ -25,7 +25,6 @@ import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
 import {
-  codeExecutionPiToolCandidate,
   compilePiTools,
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
@@ -543,25 +542,6 @@ export interface CreatePreparedPiTurnOptions {
   readonly durability: PiTurnDurability;
   /** Reports paired model-generation lifecycle facts to the Runtime owner. */
   readonly onGeneration?: PiGenerationLifecycleObserver;
-  /** Reports Code Mode child Tool starts without adding Pi recovery state. */
-  readonly onNestedToolStarted?: (input: Readonly<{
-    parentToolCallId: string;
-    toolCallId: string;
-    toolName: string;
-    input: unknown;
-    occurredAt: number;
-  }>) => void;
-  /** Reports Code Mode child Tool outcomes without adding Pi settlements. */
-  readonly onNestedToolFinished?: (input: Readonly<{
-    parentToolCallId: string;
-    toolCallId: string;
-    toolName: string;
-    outcome: "completed" | "failed" | "cancelled";
-    durationMs: number;
-    output?: import("@earendil-works/pi-agent-core").AgentToolResult<unknown>;
-    error?: unknown;
-    occurredAt: number;
-  }>) => void;
   /** Per-Submission executors for tools whose metadata is fixed at assembly time. */
   readonly toolExecutors?: Readonly<Record<
     string,
@@ -653,7 +633,6 @@ export class PreparedPiTurnAdapter {
   private readonly turn: PiTurnAdapter;
   private readonly abortController = new AbortController();
   private readonly candidates: readonly PiToolCandidate[];
-  private nestedToolOrdinal = 0;
   private assistantOrdinal: number;
   private readonly encoder: PiChunkEncoder;
   private readonly steerMessageIds: string[] = [];
@@ -686,8 +665,6 @@ export class PreparedPiTurnAdapter {
     });
     const bindCandidate = (
       candidate: PiToolCandidate,
-      toolCallIdPrefix?: string,
-      recordRecoveryAttempt = true,
     ): PiToolCandidate => ({
       ...candidate,
       tool: {
@@ -696,9 +673,6 @@ export class PreparedPiTurnAdapter {
         // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
         // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
         execute: async (toolCallId, input, signal, onUpdate) => {
-          if (toolCallIdPrefix) {
-            toolCallId = `${toolCallIdPrefix}:${toolCallId}`;
-          }
           const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
             ? await candidate.requiredExecutionLevelForInput(input)
             : candidate.requiredExecutionLevel;
@@ -809,93 +783,25 @@ export class PreparedPiTurnAdapter {
             }
             return responded.result;
           }
-          if (recordRecoveryAttempt) {
-            const retry = piToolRetryPolicy(candidate);
-            const firstAttempt = options.durability.appendToolInput({
-              toolCallId,
-              toolName: candidate.tool.name,
-              input,
-              retry,
-            });
-            if (!firstAttempt && retry === "non-idempotent") {
-              throw new Error(
-                `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
-              );
-            }
-          }
-          const execute = options.toolExecutors?.[candidate.tool.name] ??
-            candidate.tool.execute;
-          if (recordRecoveryAttempt || !toolCallIdPrefix) {
-            return execute(toolCallId, input, signal, onUpdate);
-          }
-          const startedAt = Date.now();
-          const telemetryToolCallId = `${toolCallId}:${++this.nestedToolOrdinal}`;
-          options.onNestedToolStarted?.({
-            parentToolCallId: toolCallIdPrefix,
-            toolCallId: telemetryToolCallId,
+          const retry = piToolRetryPolicy(candidate);
+          const firstAttempt = options.durability.appendToolInput({
+            toolCallId,
             toolName: candidate.tool.name,
             input,
-            occurredAt: startedAt,
+            retry,
           });
-          try {
-            const output = await execute(toolCallId, input, signal, onUpdate);
-            const occurredAt = Date.now();
-            options.onNestedToolFinished?.({
-              parentToolCallId: toolCallIdPrefix,
-              toolCallId: telemetryToolCallId,
-              toolName: candidate.tool.name,
-              outcome: "completed",
-              durationMs: occurredAt - startedAt,
-              output,
-              occurredAt,
-            });
-            return output;
-          } catch (error) {
-            const occurredAt = Date.now();
-            options.onNestedToolFinished?.({
-              parentToolCallId: toolCallIdPrefix,
-              toolCallId: telemetryToolCallId,
-              toolName: candidate.tool.name,
-              outcome: signal?.aborted ? "cancelled" : "failed",
-              durationMs: occurredAt - startedAt,
-              error,
-              occurredAt,
-            });
-            throw error;
+          if (!firstAttempt && retry === "non-idempotent") {
+            throw new Error(
+              `Non-idempotent Tool outcome is uncertain after recovery: ${candidate.tool.name}`,
+            );
           }
+          const execute = options.toolExecutors?.[candidate.tool.name] ??
+            candidate.tool.execute;
+          return execute(toolCallId, input, signal, onUpdate);
         },
       },
     });
-    this.candidates = state.candidates.map((candidate) => {
-      if (candidate.tool.name !== "execute") return bindCandidate(candidate);
-      const factory = state.snapshot.bindings.codeExecution;
-      if (!factory) {
-        throw new Error("Prepared Code Mode Tool requires a Runtime factory");
-      }
-      return bindCandidate({
-        ...candidate,
-        tool: {
-          ...candidate.tool,
-          execute: (toolCallId, input, signal, onUpdate) => {
-            const runtimeCandidate = codeExecutionPiToolCandidate(
-              factory.create(state.codeExecutionCandidates.map((inner) =>
-                // Code Mode owns replay of its connector calls. Pi persists
-                // only the parent execute attempt/result; recording an inner
-                // input without a Pi settlement creates an orphan recovery
-                // action that cannot be found on the direct Tool surface.
-                bindCandidate(inner, toolCallId, false)
-              )),
-            );
-            return runtimeCandidate.tool.execute(
-              toolCallId,
-              input,
-              signal,
-              onUpdate,
-            );
-          },
-        },
-      });
-    });
+    this.candidates = state.candidates.map(bindCandidate);
     this.turn = new PiTurnAdapter({
       pi: {
         model: state.snapshot.pi.model,

package/src/pi/tool/base.ts

@@ -198,12 +198,17 @@ const setContextParameters = Type.Object({
   label: Type.Union([
     Type.Literal("memory"),
     Type.Literal("preferences"),
-  ]),
-  content: Type.String(),
+  ], {
+    description:
+      "Context block to update: memory for durable facts and active context, preferences for tone and workflow choices.",
+  }),
+  content: Type.String({ description: "Text to store in the selected context block." }),
   action: Type.Optional(Type.Union([
     Type.Literal("replace"),
     Type.Literal("append"),
-  ])),
+  ], {
+    description: 'Whether to replace the block or append to it. Defaults to "replace".',
+  })),
 });
 
 function result<T>(details: T): AgentToolResult<T> {
@@ -273,8 +278,7 @@ export function basePiToolCandidates(
         },
       },
     },
-    {
-      ...candidate({
+    candidate({
         name: "suggest_followups",
         label: "Suggest follow-ups",
         description:
@@ -284,10 +288,7 @@ export function basePiToolCandidates(
           return result({ noted: true, count: input.items.length });
         },
       }),
-      direct: true,
-    },
-    {
-      ...candidate({
+    candidate({
         name: "update_plan",
         label: "Update plan",
         description:
@@ -302,8 +303,6 @@ export function basePiToolCandidates(
           });
         },
       }),
-      direct: true,
-    },
     ...(webSearch ? [webSearchPiToolCandidate(webSearch)] : []),
   ];
 }

package/src/pi/tool/compiler.ts

@@ -48,10 +48,6 @@ export interface PiToolCandidate {
   readonly tool: AgentTool<any, any>;
   /** @internal Send the complete schema but hide it until provider Tool Search finds it. */
   readonly deferLoading?: true;
-  /** Keep this Tool Direct-only instead of also offering it through Code Mode. */
-  readonly direct?: true;
-  /** Offer this Tool only through Code Mode, never as a top-level Tool. */
-  readonly codeExecutionOnly?: true;
   /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
   /** Trusted parameter-level policy, evaluated before approval or dispatch. */
@@ -66,6 +62,8 @@ export interface PiToolCandidate {
    * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
    */
   readonly alwaysRequiresApproval?: boolean;
+  /** Recovery may replay this Tool Call only when the candidate guarantees convergence. */
+  readonly retry?: "idempotent" | "non-idempotent";
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
   readonly interaction?: PiToolInteractionSpec;