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

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,19 +13,51 @@ import {
 
 // #region Public contracts
 
-/** 描述一个尚未经过去重、禁用规则和结算包装的 Pi 工具。 */
+/**
+ * 声明一个 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 工具如何被编译为可执行工具集。 */
 export interface CompilePiToolsOptions {
-  readonly deny?: readonly string[];
   readonly governance?: PiToolGovernance;
   readonly settle: (
     call: SettledPiToolCall,
@@ -248,7 +279,7 @@ export function createPiToolGovernance(
 }
 
 // 为一个候选工具包上输出限额、持久化结算、重试治理和遥测。
-// `compilePiTools()` 对通过授权和 deny 筛选的每个候选项调用。
+// `compilePiTools()` 对最终 Tool Surface 中的每个候选项调用。
 // 一个共享包装边界可确保所有工具无论成功还是失败都经过 settle，不能由各工具自行选择是否持久化。
 function governedTool(
   candidate: PiToolCandidate,
@@ -402,11 +433,9 @@ function governedTool(
 }
 
 /**
- * 把已授权且未被禁用的 Pi 工具候选项编译成可执行工具集。
+ * 把已经 Tool Surface 最终化的候选项包成可执行工具集。
  *
- * Runtime 组装层在启动前用它验证工具集，`PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行包装。
- *
- * 工具名是模型调用和结算的唯一键，所以冲突必须在组装时失败，不能用后来者静默覆盖。
+ * `PiTurnAdapter` 在每个 Turn 及手动重试时用它创建执行治理包装。
  */
 export function compilePiTools(
   candidates: readonly PiToolCandidate[],
@@ -415,30 +444,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,20 +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 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";
+import {
+  toolRegistryFromPiCandidates,
+  type ToolRegistry,
+} from "../../tool-registry";
 
 // 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
 
@@ -30,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
@@ -188,7 +93,6 @@ export function listExtensionsPiToolCandidate(
   };
   return {
     owner: "core:extensions",
-    authorized: true,
     requiredExecutionLevel: "low",
     tool,
   };
@@ -210,12 +114,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",
@@ -267,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",
@@ -275,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";