@springbrand/agent-runtime 0.1.3-alpha.0 → 0.1.3-alpha.2

package/src/pi/tool/compiler.ts

@@ -6,7 +6,6 @@ import type {
 import type { ApprovalReceipt } from "../../kernel/receipts";
 import { boundDurableToolOutput } from "../../layers/context/budget/gate";
 import {
-  EXECUTION_LEVELS,
   type ExecutionLevel,
 } from "../../lib/execution-level";
 
@@ -14,7 +13,7 @@ import {
 
 // #region Public contracts
 
-/** 描述一个尚未经过去重、禁用规则和结算包装的 Pi 工具。 */
+/** 描述一个尚未进入最终 Tool Surface 和结算包装的 Pi 工具。 */
 export interface PiToolCandidate {
   readonly owner: string;
   readonly authorized: boolean;
@@ -26,7 +25,6 @@ export interface PiToolCandidate {
 
 /** 控制候选 Pi 工具如何被编译为可执行工具集。 */
 export interface CompilePiToolsOptions {
-  readonly deny?: readonly string[];
   readonly governance?: PiToolGovernance;
   readonly settle: (
     call: SettledPiToolCall,
@@ -248,7 +246,7 @@ export function createPiToolGovernance(
 }
 
 // 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
-// `compilePiTools()` 对通过授权和 deny 筛选的每个候选项调用。
+// `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
 // 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
 function governedTool(
   candidate: PiToolCandidate,
@@ -402,11 +400,9 @@ function governedTool(
 }
 
 /**
- * 把已授权且未被禁用的 Pi 工具候选项编译成可执行工具集。
+ * 把已经 Tool Surface 最终化的候选项包成可执行工具集。
  *
- * Runtime 组装层在启动前用它验证工具集，`PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行包装。
- *
- * 工具名是模型调用和结算的唯一键，所以冲突必须在组装时失败，不能用后来者静默覆盖。
+ * `PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行治理包装。
  */
 export function compilePiTools(
   candidates: readonly PiToolCandidate[],
@@ -415,30 +411,7 @@ export function compilePiTools(
   if (!options?.settle) {
     throw new Error("Pi Tool settlement port is required");
   }
-  const deny = new Set(options.deny ?? []);
-  const tools: AgentTool<any, any>[] = [];
-  const owners = new Map<string, string>();
-
-  for (const candidate of candidates) {
-    if (!EXECUTION_LEVELS.includes(candidate.requiredExecutionLevel)) {
-      throw new Error(
-        `Pi Tool "${candidate.tool.name}" has invalid requiredExecutionLevel`,
-      );
-    }
-    if (!candidate.authorized || deny.has(candidate.tool.name)) continue;
-
-    const existingOwner = owners.get(candidate.tool.name);
-    if (existingOwner !== undefined) {
-      throw new Error(
-        `duplicate tool key "${candidate.tool.name}" (${candidate.owner} collides with ${existingOwner})`,
-      );
-    }
-
-    owners.set(candidate.tool.name, candidate.owner);
-    tools.push(governedTool(candidate, options));
-  }
-
-  return tools;
+  return candidates.map((candidate) => governedTool(candidate, options));
 }
 
 // #endregion

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

@@ -1,52 +1,50 @@
-import {
-  createCodemodeRuntime,
-  DynamicWorkerExecutor,
-  truncateResult,
-} from "@cloudflare/codemode";
 import {
   createWorkspaceStateBackend,
   type WorkspaceFsLike,
 } from "@cloudflare/shell";
-import { StateConnector } from "@cloudflare/shell/workers";
-import type { WorkspacePort } from "../../kernel/bindings";
-import { codeExecutionPiToolCandidate } from "./core";
-import type { PiToolCandidate } from "./compiler";
+import { createExecuteRuntime } from "@cloudflare/think/tools/execute";
+import type {
+  RuntimeCodeExecutionPort,
+  WorkspacePort,
+} from "../../kernel/bindings";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Workspace、Port 和 Tool Candidate 术语。
 
 const CODEMODE_SANDBOX_TIMEOUT_MS = 55_000;
 
 /**
- * 把宿主的 Worker Loader、出站网络和 Workspace 组装成 Pi 代码执行工具候选项。
+ * 把宿主的 Worker Loader、出站网络和 Workspace 组装成代码执行 Port。
  *
  * 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 workspaceCodeExecutionPiToolCandidate(options: {
+export function createWorkspaceCodeExecutionPort(options: {
   readonly ctx: DurableObjectState;
   readonly loader: WorkerLoader;
   readonly outbound: Fetcher;
   readonly workspace: WorkspacePort;
-}): PiToolCandidate {
-  const runtime = createCodemodeRuntime({
+}): RuntimeCodeExecutionPort {
+  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,
   });
-  return codeExecutionPiToolCandidate(runtime);
+  const execute = tool.execute;
+  if (typeof execute !== "function") {
+    throw new Error("Think createExecuteRuntime returned a non-executable tool");
+  }
+  return {
+    execute: (input) => Promise.resolve(execute(input, {
+      toolCallId: "execute",
+      messages: [],
+      context: undefined,
+    })),
+  };
 }

package/src/pi/tool/core.ts

@@ -1,19 +1,16 @@
+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 type { CodemodeRuntimeHandle } from "@cloudflare/codemode";
-import {
-  browserExtract,
-  browserLinks,
-  browserMarkdown,
-  browserScrape,
-  type QuickActionPage,
-} from "agents/browser";
-import type { RuntimeBrowserPort } from "../../kernel/bindings";
+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";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
@@ -30,128 +27,33 @@ 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",
+      authorized: true,
+      requiredExecutionLevel: "low",
+      tool: aiToolToPi(name, tool, {
+        label: BROWSER_TOOL_LABELS[name] ?? name,
+      }),
+    }),
+  );
 }
 
 // #endregion
@@ -210,12 +112,13 @@ const CODEMODE_EXECUTE_TIMEOUT_MS = 60_000;
 /**
  * 把 Cloudflare Codemode Runtime handle 包装为高风险 Pi 代码执行工具候选项。
  *
- * Worker 宿主用 `workspaceCodeExecutionPiToolCandidate()` 组装好持久化 Codemode Runtime 后调用，模型再通过 `execute` 运行代码。
+ * Tool Surface 收到 Host 已组装的 Code Execution Port 后调用，
+ * 模型再通过 `execute` 运行代码。
  *
  * Codemode 代码可访问出站网络和已配置 connector，因此必须保留 high 档和 codemode source 标记，不能降级成普通本地计算工具。
  */
 export function codeExecutionPiToolCandidate(
-  runtime: Pick<CodemodeRuntimeHandle, "execute">,
+  runtime: RuntimeCodeExecutionPort,
 ): PiToolCandidate {
   const tool: AgentTool<typeof executeParameters> = {
     name: "execute",

package/src/pi/tool/mcp.ts

@@ -12,7 +12,7 @@ interface McpCallResult {
 /**
  * Pi 的 MCP 适配器所需的最小 Host 能力。
  *
- * `PreparedAssembly` 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
+ * Tool Surface 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
  * 提供同样的服务器状态快照、工具目录和调用能力，不要在这里复制连接状态。
  *
  * 这里沿用 MCP 的官方术语：Host 是承载 Agent 的应用，Client 是 Host 内连接
@@ -203,7 +203,7 @@ function errorMessage(result: McpCallResult): string {
 /**
  * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
  *
- * `PreparedAssembly.toolCandidates()` 在每次收集本轮工具时调用它。调用方应传入
+ * Tool Surface 在 Runtime 准备时调用它。调用方应传入
  * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
  * 的连接不会进入模型工具目录。
  *

package/src/pi/tool/schedule.ts

@@ -71,6 +71,14 @@ const updateScheduleParameters = Type.Object({
   label: Type.Optional(Type.String()),
   timezone: Type.Optional(Type.String()),
 });
+const changeScheduleAgentParameters = Type.Object({
+  id: Type.String({
+    description: "The exact schedule id returned by `list_schedules`.",
+  }),
+  userAgentId: Type.String({
+    description: "The exact User Agent id selected by the user.",
+  }),
+});
 
 function result<T>(details: T): AgentToolResult<T> {
   return {
@@ -82,11 +90,11 @@ function result<T>(details: T): AgentToolResult<T> {
 function candidate<T extends TSchema>(
   tool: AgentTool<T>,
   options: Partial<
-    Pick<PiToolCandidate, "requiredExecutionLevel" | "summary">
+    Pick<PiToolCandidate, "owner" | "requiredExecutionLevel" | "summary">
   > = {},
 ): PiToolCandidate {
   return {
-    owner: "runtime-base",
+    owner: options.owner ?? "runtime-base",
     authorized: true,
     requiredExecutionLevel: options.requiredExecutionLevel ?? "safe",
     source: "action",
@@ -194,5 +202,41 @@ export function schedulePiToolCandidates(
         summary: "Cancel a scheduled task",
       },
     ),
+    candidate(
+      {
+        name: "list_user_agents",
+        label: "List User Agents",
+        description:
+          "List the enabled User Agents available for scheduled tasks. " +
+          "Use this before changing a schedule Agent.",
+        parameters: noParameters,
+        async execute(_toolCallId, _input, signal) {
+          signal?.throwIfAborted();
+          return result({ agents: await schedule.listAgents() });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
+    candidate(
+      {
+        name: "change_schedule_agent",
+        label: "Change schedule Agent",
+        description:
+          "Change which User Agent executes one scheduled task without " +
+          "changing its id or history. Call `list_schedules` and " +
+          "`list_user_agents` first and use exact ids; ask the user when " +
+          "the target is ambiguous.",
+        parameters: changeScheduleAgentParameters,
+        async execute(_toolCallId, input, signal) {
+          signal?.throwIfAborted();
+          const { ok } = await schedule.changeAgent(
+            input.id,
+            input.userAgentId,
+          );
+          return result({ updated: ok, id: input.id });
+        },
+      },
+      { owner: "schedule-host" },
+    ),
   ];
 }