@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.11

package/src/pi/tool/compiler.ts

@@ -13,14 +13,47 @@ import {
 
 // #region Public contracts
 
+/**
+ * 声明一个 Tool 的结果由客户端投递，而不是由 `execute()` 产出。
+ *
+ * 带这个字段的 Tool 会在执行链里 park 住，等宿主经 `respondToolInteraction` 把响应送进来，
+ * 再用 `settle` 把响应映射成这次 `toolCallId` 的权威 ToolResult。它的 `execute` 不会被调用。
+ *
+ * 这是 AI SDK 里「没有 execute 的 user-interaction tool」的等价物；差别是我们 park 住整个 Turn，
+ * 而不是让 tool part 悬空到下一次请求 —— 我们的 transcript 是服务端权威的，悬空的 tool_use
+ * 会让下一次模型调用非法。
+ */
+export interface PiToolInteractionSpec {
+  /** 校验客户端响应体；不通过则拒绝投递，park 保持不变。 */
+  readonly validateResponse: (response: unknown) => boolean;
+  /** 把通过校验的响应映射成 ToolResult；缺省是原样回传。 */
+  readonly settle?: (
+    input: unknown,
+    response: unknown,
+  ) => AgentToolResult<unknown>;
+}
+
 /** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
 export interface PiToolCandidate {
   readonly owner: string;
-  readonly authorized: boolean;
   readonly tool: AgentTool<any, any>;
+  /** Conservative maximum used in the stable Runtime descriptor. */
   readonly requiredExecutionLevel: ExecutionLevel;
+  /** Trusted parameter-level policy, evaluated before approval or dispatch. */
+  readonly requiredExecutionLevelForInput?: (
+    input: unknown,
+  ) => ExecutionLevel | Promise<ExecutionLevel>;
+  /**
+   * 无条件需要人来决定：不看执行档位矩阵，每次调用都 park 出审批。
+   *
+   * 档位差是「够不够格自己跑」，不是「该不该问人」。花用户钱、改变账户
+   * 状态这类工具，一旦 Agent 档位被 `allow_level` 永久拉高就会静默执行，
+   * 那是失效不是降级。`deny` 仍然优先，被 deny 的工具根本不会注入。
+   */
+  readonly alwaysRequiresApproval?: boolean;
   readonly summary?: string;
   readonly source?: ApprovalReceipt["source"];
+  readonly interaction?: PiToolInteractionSpec;
 }
 
 /** 控制候选 Pi 工具如何被编译为可执行工具集。 */

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

@@ -1,13 +1,8 @@
-import {
-  createCodemodeRuntime,
-  DynamicWorkerExecutor,
-  truncateResult,
-} from "@cloudflare/codemode";
 import {
   createWorkspaceStateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
-import { StateConnector } from "@cloudflare/shell/workers";
+import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
 import type {
   RuntimeCodeExecutionPort,
   WorkspacePort,
@@ -22,7 +17,7 @@ const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
  *
  * Worker 宿主在具备 Durable Object state 和完整平台绑定时调用，然后把返回值交给 Runtime 工具组装。
  *
- * Cloudflare Codemode 把持久化 Runtime 和无状态 Dynamic Worker executor 分开；这里必须用 StateConnector 显式注入已限定范围的 Workspace，并在返回模型前用官方 `truncateResult` 限制结果。
+ * Think 的独立 execute factory 接受显式宿主参数，不要求 Agent 继承 Think；这里只借它组装 Codemode Runtime、Dynamic Worker executor 和已限定范围的 Workspace state connector。
  */
 export function createWorkspaceCodeExecutionPort(options: {
   readonly ctx: DurableObjectState;
@@ -30,26 +25,26 @@ export function createWorkspaceCodeExecutionPort(options: {
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
 }): RuntimeCodeExecutionPort {
-  const runtime = createCodemodeRuntime({
+  const { tool } = createExecuteRuntime({
     ctx: options.ctx,
-    executor: new DynamicWorkerExecutor({
-      loader: options.loader,
-      globalOutbound: options.outbound,
-      // 先于外层 60s 截止结束，给 Runtime RPC 结算和 Worker 释放留出时间。
-      timeout: CODEMODE_SANDBOX_TIMEOUT_MS,
-    }),
-    connectors: [
-      new StateConnector(
-        options.ctx,
-        createWorkspaceStateBackend(
-          options.workspace as unknown as WorkspaceFsLike,
-        ),
-      ),
-    ],
+    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",
-    transformResult: truncateResult,
   });
+  const execute = tool.execute;
+  if (typeof execute !== "function") {
+    throw new Error("Think createExecuteRuntime returned a non-executable tool");
+  }
   return {
-    execute: (input) => runtime.execute(input),
+    execute: (input) => Promise.resolve(execute(input, {
+      toolCallId: "execute",
+      messages: [],
+      context: undefined,
+    })),
   };
 }

package/src/pi/tool/core.ts

@@ -1,22 +1,21 @@
+import { createQuickActionTools } from "@cloudflare/think/tools/browser";
 import type {
   AgentTool,
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
-import {
-  browserExtract,
-  browserLinks,
-  browserMarkdown,
-  browserScrape,
-  type QuickActionPage,
-} from "agents/browser";
 import type {
   RuntimeBrowserPort,
   RuntimeCodeExecutionPort,
 } from "../../kernel/bindings";
 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 术语。
 
@@ -32,128 +31,32 @@ function result(details: unknown): AgentToolResult<unknown> {
 
 // #region Browser Quick Actions
 
-const pageParameters = {
-  url: Type.Optional(Type.String({ format: "uri" })),
-  html: Type.Optional(Type.String({ minLength: 1 })),
+const BROWSER_TOOL_LABELS: Readonly<Record<string, string>> = {
+  browser_markdown: "Read web page",
+  browser_extract: "Extract web data",
+  browser_links: "List web links",
+  browser_scrape: "Scrape web elements",
 };
-const browserPageParameters = Type.Object(pageParameters);
-const browserExtractParameters = Type.Object({
-  ...pageParameters,
-  prompt: Type.Optional(Type.String({ minLength: 1 })),
-  schema: Type.Optional(Type.Unknown()),
-});
-const browserScrapeParameters = Type.Object({
-  ...pageParameters,
-  selectors: Type.Array(Type.String({ minLength: 1 }), {
-    minItems: 1,
-  }),
-});
-
-// 把工具输入收窄为 Browser Quick Action 接受的页面来源。
-// 四个 Browser Quick Action execute 方法在调用 Agents SDK 前共用它。
-// 实际运行时再拒绝空输入，而同时给出 url 和 html 时优先 url，不能把不完整来源传给宿主绑定。
-function page(input: {
-  url?: string;
-  html?: string;
-}): QuickActionPage {
-  if (input.url) return { url: input.url };
-  if (input.html) return { html: input.html };
-  throw new Error("Provide either 'url' or 'html'");
-}
 
 /**
  * 为 Cloudflare Browser Run 的四个一次性 Quick Action 创建 Pi 工具候选项。
  *
  * Runtime 在宿主提供 Browser port 时调用，模型分别用它读取 Markdown、抽取数据、列出链接或按选择器抓取。
  *
- * Cloudflare 官方将 Quick Actions 定位为只需 browser binding 的无状态单次操作，所以这里直接调用四个宿主函数，不引入额外会话或重试状态。
+ * Cloudflare 官方将 Quick Actions 定位为只需 browser binding 的无状态单次操作，这里直接复用官方工厂。
  */
 export function browserQuickActionPiToolCandidates(
   browser: RuntimeBrowserPort,
 ): PiToolCandidate[] {
-  const markdown: AgentTool<typeof browserPageParameters> = {
-    name: "browser_markdown",
-    label: "Read web page",
-    description:
-      "Load a web page (or render raw HTML) and return its content as Markdown. Best for reading articles, docs, or any page as text.",
-    parameters: browserPageParameters,
-    // 把 URL 或 HTML 读成 Markdown。
-    // Pi 工具循环在模型选择 `browser_markdown` 时调用，调用前允许 Turn 取消。
-    // 取消检查必须放在 Browser binding 调用前，避免已终止 Turn 继续发起页面请求。
-    async execute(_toolCallId, input, signal) {
-      signal?.throwIfAborted();
-      return result(await browserMarkdown(browser, page(input)));
-    },
-  };
-  const extract: AgentTool<typeof browserExtractParameters> = {
-    name: "browser_extract",
-    label: "Extract web data",
-    description:
-      "Extract structured data from a web page using AI. Describe what you want in 'prompt'. Passing a JSON Schema in 'schema' is strongly recommended — without one the extractor often fails to produce JSON.",
-    parameters: browserExtractParameters,
-    // 按自然语言提示或 JSON Schema 从页面抽取数据。
-    // Pi 工具循环在模型选择 `browser_extract` 时调用，至少需要 prompt 或 schema 之一。
-    // schema 必须转成 Browser Run 期望的 `json_schema` response_format，而空抽取要求必须在发起请求前失败。
-    async execute(
-      _toolCallId,
-      { prompt, schema, ...input },
-      signal,
-    ) {
-      signal?.throwIfAborted();
-      if (!prompt && schema === undefined) {
-        throw new Error("Provide either 'prompt' or 'schema'");
-      }
-      return result(await browserExtract(browser, {
-        ...page(input),
-        prompt,
-        response_format: schema === undefined
-          ? undefined
-          : { type: "json_schema", schema },
-      }));
-    },
-  };
-  const links: AgentTool<typeof browserPageParameters> = {
-    name: "browser_links",
-    label: "List web links",
-    description:
-      "Return every link found on a web page (including ones not visible). Useful for discovering pages to follow.",
-    parameters: browserPageParameters,
-    // 列出 URL 或 HTML 页面中的链接。
-    // Pi 工具循环在模型选择 `browser_links` 时调用，调用前允许 Turn 取消。
-    // 保留 Agents SDK 的原始结果形状，让统一 result 边界负责文本投影而不在此处二次整形。
-    async execute(_toolCallId, input, signal) {
-      signal?.throwIfAborted();
-      return result(await browserLinks(browser, page(input)));
-    },
-  };
-  const scrape: AgentTool<typeof browserScrapeParameters> = {
-    name: "browser_scrape",
-    label: "Scrape web elements",
-    description:
-      "Scrape specific elements from a web page by CSS selector. Returns the matched elements' text, HTML, and attributes.",
-    parameters: browserScrapeParameters,
-    // 按 CSS 选择器抓取 URL 或 HTML 页面的指定元素。
-    // Pi 工具循环在模型选择 `browser_scrape` 时调用，并把简化的字符串列表传入。
-    // Browser Run 需要 `{ selector }` 对象列表，因此这个适配只在边界做一次形状转换。
-    async execute(
-      _toolCallId,
-      { selectors, ...input },
-      signal,
-    ) {
-      signal?.throwIfAborted();
-      return result(await browserScrape(browser, {
-        ...page(input),
-        elements: selectors.map((selector) => ({ selector })),
-      }));
-    },
-  };
-
-  return [markdown, extract, links, scrape].map((tool) => ({
-    owner: "core:browser",
-    authorized: true,
-    requiredExecutionLevel: "low",
-    tool,
-  }));
+  return Object.entries(createQuickActionTools({ browser })).map(
+    ([name, tool]) => ({
+      owner: "core:browser",
+      requiredExecutionLevel: "low",
+      tool: aiToolToPi(name, tool, {
+        label: BROWSER_TOOL_LABELS[name] ?? name,
+      }),
+    }),
+  );
 }
 
 // #endregion
@@ -190,7 +93,6 @@ export function listExtensionsPiToolCandidate(
   };
   return {
     owner: "core:extensions",
-    authorized: true,
     requiredExecutionLevel: "low",
     tool,
   };
@@ -270,7 +172,6 @@ export function codeExecutionPiToolCandidate(
   };
   return {
     owner: "core:codemode",
-    authorized: true,
     requiredExecutionLevel: "high",
     source: "codemode",
     summary: "Run JavaScript with network and configured connector access",
@@ -278,4 +179,13 @@ export function codeExecutionPiToolCandidate(
   };
 }
 
+/** 从 Codemode Runtime Port 生成 `execute` Tool。 */
+export function createCodeExecutionTool(
+  runtime: RuntimeCodeExecutionPort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates([
+    codeExecutionPiToolCandidate(runtime),
+  ]);
+}
+
 // #endregion

package/src/pi/tool/gateway.ts

@@ -0,0 +1,54 @@
+import type { RuntimeGatewaySession } from "../../kernel/bindings";
+import type { PiToolCandidate } from "./compiler";
+import { createPiMcpToolCandidate } from "./mcp";
+
+const GATEWAY_TOOLS = [
+  "search_capabilities",
+  "execute_capability",
+] as const;
+
+/** Builds the two platform Gateway tools from one authenticated logical MCP Session. */
+export function createPiGatewayToolCandidates(
+  session: RuntimeGatewaySession,
+): PiToolCandidate[] {
+  const tools = new Map(session.tools.map((tool) => [tool.name, tool]));
+  if (
+    tools.size !== GATEWAY_TOOLS.length ||
+    GATEWAY_TOOLS.some((name) => !tools.has(name))
+  ) {
+    throw new Error("Connector Gateway returned an invalid MCP catalog");
+  }
+
+  return GATEWAY_TOOLS.map((name) => {
+    const tool = tools.get(name)!;
+    const execute = name === "execute_capability";
+    return createPiMcpToolCandidate(
+      { ...tool, serverId: "gateway" },
+      (input, signal) => session.callTool(name, input, signal),
+      {
+        owner: "gateway",
+        modelName: name,
+        requiredExecutionLevel: execute ? "high" : "safe",
+        ...(execute
+          ? {
+              requiredExecutionLevelForInput: async (input: unknown) => {
+                const reference = input && typeof input === "object" &&
+                    !Array.isArray(input)
+                  ? (input as Record<string, unknown>).name
+                  : undefined;
+                if (typeof reference !== "string" || !reference) {
+                  throw new Error(
+                    "Gateway Capability Reference is not verified",
+                  );
+                }
+                return (await session.resolveCapabilityRisk(reference)) ===
+                    "none"
+                  ? "safe" as const
+                  : "high" as const;
+              },
+            }
+          : {}),
+      },
+    );
+  });
+}

package/src/pi/tool/index.ts

@@ -24,9 +24,11 @@ export * from "./base";
 export * from "./compiler";
 export * from "./core";
 export * from "./core-host";
+export * from "./gateway";
 export * from "./mcp";
 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

@@ -9,6 +9,22 @@ interface McpCallResult {
   isError?: boolean;
 }
 
+export interface PiDiscoveredMcpTool {
+  readonly serverId: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly inputSchema?: unknown;
+  readonly annotations?: { readonly title?: string } & Record<string, unknown>;
+}
+
+interface PiMcpCandidatePolicy {
+  readonly owner: string;
+  readonly modelName: string;
+  readonly requiredExecutionLevel: PiToolCandidate["requiredExecutionLevel"];
+  readonly requiredExecutionLevelForInput?: PiToolCandidate["requiredExecutionLevelForInput"];
+}
+
 /**
  * Pi 的 MCP 适配器所需的最小 Host 能力。
  *
@@ -43,7 +59,8 @@ export interface PiMcpHost {
      * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
      */
     callTool(
-      ...args: Parameters<MCPClientManager["callTool"]>
+      params: Parameters<MCPClientManager["callTool"]>[0],
+      options?: { signal?: AbortSignal },
     ): Promise<unknown>;
   };
 }
@@ -200,16 +217,76 @@ function errorMessage(result: McpCallResult): string {
     : "MCP tool call failed";
 }
 
+/** 共享 MCP 结果投影；Gateway 与用户配置的 Remote MCP 均经过此边界。 */
+export function createPiMcpToolCandidate(
+  mcpTool: PiDiscoveredMcpTool,
+  callTool: (
+    input: Readonly<Record<string, unknown>>,
+    signal?: AbortSignal,
+  ) => Promise<unknown>,
+  policy: PiMcpCandidatePolicy,
+): PiToolCandidate {
+  const label =
+    mcpTool.title ??
+    mcpTool.annotations?.title ??
+    mcpTool.name;
+  const tool: AgentTool<any, {
+    kind: "mcp";
+    toolName: string;
+  }> = {
+    name: policy.modelName,
+    label,
+    description: mcpTool.description ?? label,
+    parameters: structuredClone(
+      mcpTool.inputSchema ?? {
+        type: "object",
+        additionalProperties: true,
+      },
+    ) as AgentTool["parameters"],
+    execute: async (_toolCallId, args, signal) => {
+      const result = normalizeCallResult(
+        await callTool(args as Record<string, unknown>, signal),
+      );
+      if (result.isError) throw new Error(errorMessage(result));
+      const structuredContent = result.structuredContent === undefined
+        ? undefined
+        : publicMcpValue(result.structuredContent);
+      const content = resultContent({ ...result, structuredContent });
+      return {
+        content,
+        details: {
+          kind: "mcp",
+          toolName: mcpTool.name,
+          output: structuredContent ?? content,
+        },
+      };
+    },
+  };
+  return {
+    owner: policy.owner,
+    tool,
+    summary: label,
+    requiredExecutionLevel: policy.requiredExecutionLevel,
+    ...(policy.requiredExecutionLevelForInput
+      ? {
+          requiredExecutionLevelForInput:
+            policy.requiredExecutionLevelForInput,
+        }
+      : {}),
+    source: "action",
+  };
+}
+
 /**
- * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
+ * 把当前已配置且 ready 的 MCP 工具转换成 Pi 候选工具。
  *
  * Tool Surface 在 Runtime 准备时调用它。调用方应传入
  * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
  * 的连接不会进入模型工具目录。
  *
  * “候选工具”是进入 Pi 编译和统一治理前的内部描述。连接、凭据和恢复由 Host
- * 与 Agents SDK 管理；本函数只做授权快照过滤、Schema 转接和公开结果投影。
- * 远端 Server 提供的 annotations 只是提示，不是本地授权边界，所以所有动态
+ * 与 Agents SDK 管理；本函数只做动态连接状态过滤、Schema 转接和公开结果投影。
+ * 远端 Server 提供的 annotations 只是提示，不是本地审批边界，所以所有动态
  * MCP 工具继续标为高风险，不能据此绕过审批。
  *
  * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
@@ -249,71 +326,22 @@ export function createPiMcpToolCandidates(
       state: "ready",
     })
     .filter((tool) => selectedIds.has(tool.serverId))
-    .map((mcpTool): PiToolCandidate => {
-      const label =
-        mcpTool.title ??
-        mcpTool.annotations?.title ??
-        mcpTool.name;
-      const tool: AgentTool<any, {
-        kind: "mcp";
-        toolName: string;
-      }> = {
-        name: modelVisibleName(mcpTool.serverId, mcpTool.name),
-        label,
-        description: mcpTool.description ?? label,
-        parameters: structuredClone(
-          mcpTool.inputSchema ?? {
-            type: "object",
-            additionalProperties: true,
-          },
-        ) as AgentTool["parameters"],
-        // 作用：执行模型选中的远端 MCP 工具并返回公开结果。
-        // 调用：Pi 在参数校验和统一工具治理通过后调用。
-        // 原因：调用交给 Agents SDK，并在边界处统一处理错误、
-        // 私有元数据和非原生内容。
-        execute: async (_toolCallId, args, signal) => {
-          const result = normalizeCallResult(
-            await host.mcp.callTool(
-              {
-                serverId: mcpTool.serverId,
-                name: mcpTool.name,
-                arguments: args as Record<string, unknown>,
-              },
-              undefined,
-              { signal },
-            ),
-          );
-          if (result.isError) {
-            throw new Error(errorMessage(result));
-          }
-          const structuredContent =
-            result.structuredContent === undefined
-              ? undefined
-              : publicMcpValue(result.structuredContent);
-          const content = resultContent({
-            ...result,
-            structuredContent,
-          });
-          return {
-            content,
-            details: {
-              kind: "mcp",
-              toolName: mcpTool.name,
-              output: structuredContent ?? content,
-            },
-          };
+    .map((mcpTool) => createPiMcpToolCandidate(
+      mcpTool,
+      (args, signal) => host.mcp.callTool(
+        {
+          serverId: mcpTool.serverId,
+          name: mcpTool.name,
+          arguments: args,
         },
-      };
-      return {
+        { signal },
+      ),
+      {
         owner: `mcp:${mcpTool.serverId}`,
-        authorized: true,
-        tool,
-        summary: label,
-        // MCP annotations are supplied by the remote server and are not an
-        // authorization boundary. Until the Host supplies trusted per-method
-        // policy, every dynamic MCP method must take the approval path.
+        modelName: modelVisibleName(mcpTool.serverId, mcpTool.name),
+        // Remote MCP annotations are untrusted; all user-configured methods
+        // retain the existing high-risk approval policy.
         requiredExecutionLevel: "high",
-        source: "action",
-      };
-    });
+      },
+    ));
 }

package/src/pi/tool/schedule.ts

@@ -10,6 +10,10 @@ import type {
 import type { ScheduleSpec } from "../../kernel/receipts";
 import { serializeOutput } from "../../lib/artifacts";
 import type { PiToolCandidate } from "./compiler";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 const scheduleTriggerParameters = Type.Union([
   Type.Object({
@@ -90,15 +94,20 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(
   tool: AgentTool<T>,
   options: Partial<
-    Pick<PiToolCandidate, "owner" | "requiredExecutionLevel" | "summary">
+    Pick<
+      PiToolCandidate,
+      "alwaysRequiresApproval" | "owner" | "requiredExecutionLevel" | "summary"
+    >
   > = {},
 ): PiToolCandidate {
   return {
     owner: options.owner ?? "runtime-base",
-    authorized: true,
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
     tool,
+    ...(options.alwaysRequiresApproval
+      ? { alwaysRequiresApproval: true }
+      : {}),
     ...(options.summary ? { summary: options.summary } : {}),
   };
 }
@@ -107,24 +116,30 @@ export function schedulePiToolCandidates(
   schedule: RuntimeSchedulePort,
 ): PiToolCandidate[] {
   return [
-    candidate({
-      name: "schedule",
-      label: "Schedule prompt",
-      description:
-        "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
-      parameters: scheduleParameters,
-      async execute(_toolCallId, input, signal) {
-        signal?.throwIfAborted();
-        const spec: ScheduleSpec = {
-          trigger: input.trigger,
-          job: { kind: "prompt", prompt: input.prompt },
-          label: input.label,
-          ...(input.timezone ? { tz: input.timezone } : {}),
-        };
-        const { id } = await schedule.create(spec);
-        return result({ scheduled: true, id });
+    candidate(
+      {
+        name: "schedule",
+        label: "Schedule prompt",
+        description:
+          "Schedule a prompt to run LATER, autonomously. Use when the user asks to be reminded, or to run something after a delay / at a time / on a recurring basis. The user always reviews the proposed schedule before it is created. The scheduled prompt runs in its own dedicated session at each trigger with NO memory of this conversation, so phrase `prompt` as a fully standalone instruction. After scheduling, tell the user what you set.",
+        parameters: scheduleParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const spec: ScheduleSpec = {
+            trigger: input.trigger,
+            job: { kind: "prompt", prompt: input.prompt },
+            label: input.label,
+            ...(input.timezone ? { tz: input.timezone } : {}),
+          };
+          const { id } = await schedule.create(spec);
+          return result({ scheduled: true, id });
+        },
       },
-    }),
+      {
+        alwaysRequiresApproval: true,
+        summary: "Create a scheduled task",
+      },
+    ),
     candidate({
       name: "list_schedules",
       label: "List schedules",
@@ -240,3 +255,10 @@ export function schedulePiToolCandidates(
     ),
   ];
 }
+
+/** 从 {@link RuntimeSchedulePort} 生成定时任务 Tool 集。 */
+export function createScheduleTools(
+  schedule: RuntimeSchedulePort,
+): ToolRegistry {
+  return toolRegistryFromPiCandidates(schedulePiToolCandidates(schedule));
+}