@springbrand/agent-runtime 0.1.0

package/src/pi/tool/core.ts

@@ -0,0 +1,251 @@
+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 { serializeOutput } from "../../lib/artifacts";
+import type { PiLoadedExtension } from "../assembly/extensions";
+import type { PiToolCandidate } from "./compiler";
+
+// 本文件沿用 `../../index.ts` 入口定义的 Extension、Port 和 Tool Candidate 术语。
+
+// 把核心工具的结构化值投影为 Pi 同时需要的文本和 details。
+// 本文件中所有核心工具 execute 方法在返回宿主结果时调用它。
+// 统一使用 `serializeOutput()` 可以保持模型可见文本和持久化 details 来自同一个值。
+function result(details: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: serializeOutput(details).text }],
+    details,
+  };
+}
+
+// #region Browser Quick Actions
+
+const pageParameters = {
+  url: Type.Optional(Type.String({ format: "uri" })),
+  html: Type.Optional(Type.String({ minLength: 1 })),
+};
+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 的无状态单次操作，所以这里直接调用四个宿主函数，不引入额外会话或重试状态。
+ */
+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,
+  }));
+}
+
+// #endregion
+
+// #region Extension discovery
+
+const noParameters = Type.Object({});
+
+/**
+ * 为当前已加载 Extension 列表创建一个 Pi 工具候选项。
+ *
+ * Runtime 组装层在 Extension 装载完成后调用，模型需要发现当前可用扩展时使用该工具。
+ *
+ * 候选项捕获准备阶段的只读列表，这与 pinned Runtime 组装保持一致，不能在执行时重新扫描出另一份 Extension 集合。
+ */
+export function listExtensionsPiToolCandidate(
+  extensions: readonly PiLoadedExtension[],
+): PiToolCandidate {
+  const tool: AgentTool<typeof noParameters> = {
+    name: "list_extensions",
+    label: "List extensions",
+    description: "List all currently loaded extensions and their tools.",
+    parameters: noParameters,
+    // 返回这个 pinned Runtime 已加载的 Extension 快照。
+    // Pi 工具循环在模型选择 `list_extensions` 时调用，调用前允许 Turn 取消。
+    // 同时返回 count 和原列表，使模型既能快速判空又不丢失 Extension 细节。
+    async execute(_toolCallId, _input, signal) {
+      signal?.throwIfAborted();
+      return result({
+        count: extensions.length,
+        extensions,
+      });
+    },
+  };
+  return {
+    owner: "core:extensions",
+    authorized: true,
+    requiredExecutionLevel: "low",
+    tool,
+  };
+}
+
+// #endregion
+
+// #region Code Mode
+
+const executeParameters = Type.Object({
+  code: Type.String({
+    minLength: 1,
+    description:
+      "Plain JavaScript async function. TypeScript annotations are not supported.",
+  }),
+});
+
+/**
+ * 把 Cloudflare Codemode Runtime handle 包装为高风险 Pi 代码执行工具候选项。
+ *
+ * Worker 宿主用 `workspaceCodeExecutionPiToolCandidate()` 组装好持久化 Codemode Runtime 后调用，模型再通过 `execute` 运行代码。
+ *
+ * Codemode 代码可访问出站网络和已配置 connector，因此必须保留 high 档和 codemode source 标记，不能降级成普通本地计算工具。
+ */
+export function codeExecutionPiToolCandidate(
+  runtime: Pick<CodemodeRuntimeHandle, "execute">,
+): PiToolCandidate {
+  const tool: AgentTool<typeof executeParameters> = {
+    name: "execute",
+    label: "Execute JavaScript",
+    description:
+      "Run JavaScript in a short-lived Code Mode Dynamic Worker and return a value. This is your " +
+      "raw-network and tool-composition instrument, not a general web-search tool. Call fetch directly " +
+      "when you need a raw response, custom headers/method/body, a structured API, or content that " +
+      "web_search could not retrieve. Check res.status; when several known endpoints are necessary, " +
+      "fetch them in one invocation. Also available: " +
+      "state.* for your workspace filesystem (readFile/writeFile/glob/searchFiles/replaceInFiles, " +
+      "each taking one object argument), and codemode.step(name, fn) to run a side-effecting block " +
+      "exactly once so it survives replay. Write plain JavaScript — TypeScript type annotations are " +
+      "a syntax error. Use return for the result and console.log for notes.",
+    parameters: executeParameters,
+    // 把模型提供的 JavaScript 交给 Codemode Runtime 执行。
+    // Pi 工具循环在模型选择 `execute` 时调用，调用前允许 Turn 取消。
+    // 必须通过 Runtime handle 而不是直接调用 executor，因为 Cloudflare Codemode 把重放、审批和执行日志放在持久化 Runtime 层。
+    async execute(_toolCallId, input, signal) {
+      signal?.throwIfAborted();
+      return result(await runtime.execute(input));
+    },
+  };
+  return {
+    owner: "core:codemode",
+    authorized: true,
+    requiredExecutionLevel: "high",
+    source: "codemode",
+    summary: "Run JavaScript with network and configured connector access",
+    tool,
+  };
+}
+
+// #endregion

package/src/pi/tool/index.ts

@@ -0,0 +1,32 @@
+import {
+  compilePiTools,
+  createPiToolGovernance,
+} from "./compiler";
+import { listExtensionsPiToolCandidate } from "./core";
+import { createPiMcpToolCandidates } from "./mcp";
+
+/**
+ * 集中暴露 Pi 工具候选项的组装与治理入口。
+ *
+ * Runtime 组装层在收集内建、Extension 和 MCP 工具时使用，具体调用约定由各导出函数的 TSDoc 说明。
+ *
+ * 这里只是稳定的薄汇总，不复制工具注册状态；Tool Candidate、Tool Settlement 和 Governance 等核心术语统一见 `../../index.ts` 入口说明。
+ */
+export const piTools = Object.freeze({
+  compile: compilePiTools,
+  createGovernance: createPiToolGovernance,
+  createMcpCandidates: createPiMcpToolCandidates,
+  listExtensionsCandidate: listExtensionsPiToolCandidate,
+});
+
+export * from "./ai-adapter";
+export * from "./base";
+export * from "./compiler";
+export * from "./core";
+export * from "./core-host";
+export * from "./mcp";
+export * from "./schedule";
+export * from "./skill";
+export * from "./subagent";
+export * from "./workspace-sandbox";
+export * from "./web-search";

package/src/pi/tool/mcp.ts

@@ -0,0 +1,319 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { MCPClientManager } from "agents/mcp/client";
+import type { RuntimeMcpServer } from "../../kernel/profile";
+import type { PiToolCandidate } from "./compiler";
+
+interface McpCallResult {
+  content: unknown[];
+  structuredContent?: unknown;
+  isError?: boolean;
+}
+
+/**
+ * Pi 的 MCP 适配器所需的最小 Host 能力。
+ *
+ * `PreparedAssembly` 在收集本轮工具时传入真正的 Agent Host；其他调用方只应
+ * 提供同样的服务器状态快照、工具目录和调用能力，不要在这里复制连接状态。
+ *
+ * 这里沿用 MCP 的官方术语：Host 是承载 Agent 的应用，Client 是 Host 内连接
+ * 单个 Server 的客户端，Server 是对外提供工具的服务。连接持久化、OAuth 和
+ * 恢复仍由 Agents SDK 的 MCP Client 管理，本接口只读取和调用。
+ *
+ * `Host` 与 `Pi` 等项目核心术语见 `../../index.ts`。
+ */
+export interface PiMcpHost {
+  /**
+   * 返回 Agents SDK 当前保存的 MCP 服务器及连接状态。
+   *
+   * `createPiMcpToolCandidates` 在收集本轮工具时调用；调用方应返回 SDK 的当前
+   * 快照，不要另存一份状态，否则恢复或断线后可能继续暴露旧目录。
+   */
+  getMcpServers(): {
+    servers: Record<string, {
+      server_url: string;
+      state: string;
+    }>;
+  };
+  /** 提供原始工具发现，以及对指定 MCP Server 的一次工具调用。 */
+  readonly mcp: Pick<MCPClientManager, "listTools"> & {
+    /**
+     * 调用一个已发现的 MCP 工具。
+     *
+     * `createPiMcpToolCandidates` 生成的 `execute` 方法在模型选中工具后调用它；
+     * 参数和中止信号必须原样交给 Agents SDK，避免另造一套传输生命周期。
+     */
+    callTool(
+      ...args: Parameters<MCPClientManager["callTool"]>
+    ): Promise<unknown>;
+  };
+}
+
+// 作用：给一个远端 MCP 工具生成 Pi 模型可见的稳定名称。
+// 调用：候选工厂在映射每个已发现工具时调用。
+// 原因：服务器前缀隔离同名工具，去掉连字符则保持现有 Pi 工具名格式。
+function modelVisibleName(serverId: string, toolName: string): string {
+  return `tool_${serverId.replace(/-/g, "")}_${toolName}`;
+}
+
+// 作用：把任意 MCP 返回值尽量转换成可展示文本。
+// 调用：结果归一化和内容投影遇到非文本值时调用。
+// 原因：JSON 优先保留结构；循环引用等不可序列化值再退回 String，
+// 避免遮蔽原结果。
+function safeText(value: unknown): string {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+// 作用：把 Agents SDK 的未知调用结果收敛为本文件处理的统一结构。
+// 调用：MCP 工具的 execute 在 callTool 返回后立即调用。
+// 原因：不同 Server 可能返回标准 content 或兼容层的 toolResult，
+// 先收口可让后续只走一条投影路径。
+function normalizeCallResult(value: unknown): McpCallResult {
+  if (typeof value !== "object" || value === null) {
+    return { content: [{ type: "text", text: safeText(value) }] };
+  }
+  const record = value as Record<string, unknown>;
+  if (Array.isArray(record.content)) {
+    return {
+      content: record.content,
+      structuredContent: record.structuredContent,
+      isError: record.isError === true,
+    };
+  }
+  return {
+    content: [{
+      type: "text",
+      text: safeText(record.toolResult ?? value),
+    }],
+    isError: record.isError === true,
+  };
+}
+
+// 作用：递归删除 MCP 结果中只供 Host 使用的 `_meta` 字段。
+// 调用：结构化结果和非原生内容块公开给模型前调用。
+// 原因：现有回归测试覆盖 `_meta` 可能携带凭据，
+// 不能把 Host 私有元数据写进对话记录。
+function publicMcpValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(publicMcpValue);
+  }
+  if (typeof value !== "object" || value === null) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => key !== "_meta")
+      .map(([key, entry]) => [key, publicMcpValue(entry)]),
+  );
+}
+
+// 作用：把一个非原生 MCP 内容块裁成可公开给模型的值。
+// 调用：resultContent 处理文本和图片以外的内容块时调用。
+// 原因：除递归移除 `_meta` 外还去掉 Server 提供的 annotations，
+// 避免把提示性元数据当成执行结果。
+function publicMcpPart(part: unknown): unknown {
+  const sanitized = publicMcpValue(part);
+  if (
+    typeof sanitized !== "object" ||
+    sanitized === null ||
+    Array.isArray(sanitized)
+  ) {
+    return sanitized;
+  }
+  const {
+    annotations: _annotations,
+    ...publicPart
+  } = sanitized as Record<string, unknown>;
+  return publicPart;
+}
+
+// 作用：把 MCP 内容转换为 Pi 能直接返回的文本或图片列表。
+// 调用：每次 MCP 调用成功后由工具 execute 调用。
+// 原因：原生保留文本和图片，其余类型安全转成文本；
+// 空 content 时仍要返回结构化结果或明确成功消息。
+function resultContent(result: McpCallResult): Array<
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+> {
+  const content: ReturnType<typeof resultContent> = [];
+  for (const part of result.content ?? []) {
+    if (
+      typeof part === "object" &&
+      part !== null &&
+      "type" in part &&
+      part.type === "text" &&
+      "text" in part &&
+      typeof part.text === "string"
+    ) {
+      content.push({ type: "text", text: part.text });
+      continue;
+    }
+    if (
+      typeof part === "object" &&
+      part !== null &&
+      "type" in part &&
+      part.type === "image" &&
+      "data" in part &&
+      typeof part.data === "string" &&
+      "mimeType" in part &&
+      typeof part.mimeType === "string"
+    ) {
+      content.push({
+        type: "image",
+        data: part.data,
+        mimeType: part.mimeType,
+      });
+      continue;
+    }
+    content.push({
+      type: "text",
+      text: safeText(publicMcpPart(part)),
+    });
+  }
+  if (content.length > 0) return content;
+  if (result.structuredContent !== undefined) {
+    return [{
+      type: "text",
+      text: safeText(result.structuredContent),
+    }];
+  }
+  return [{ type: "text", text: "MCP tool completed successfully" }];
+}
+
+// 作用：从 MCP 的失败结果中提取一条稳定、可读的错误消息。
+// 调用：工具 execute 发现 isError 为 true 时调用。
+// 原因：优先保留 Server 返回的首条文本，否则使用固定兜底，
+// 避免抛出无信息的对象。
+function errorMessage(result: McpCallResult): string {
+  const first = result.content?.[0];
+  return typeof first === "object" &&
+    first !== null &&
+    "type" in first &&
+    first.type === "text" &&
+    "text" in first &&
+    typeof first.text === "string"
+    ? first.text
+    : "MCP tool call failed";
+}
+
+/**
+ * 把当前已连接且获授权的 MCP 工具转换成 Pi 候选工具。
+ *
+ * `PreparedAssembly.toolCandidates()` 在每次收集本轮工具时调用它。调用方应传入
+ * Agent Host，以及同一 Runtime 快照中的 MCP 配置；未就绪、未配置或重复 URL
+ * 的连接不会进入模型工具目录。
+ *
+ * “候选工具”是进入 Pi 编译和统一治理前的内部描述。连接、凭据和恢复由 Host
+ * 与 Agents SDK 管理；本函数只做授权快照过滤、Schema 转接和公开结果投影。
+ * 远端 Server 提供的 annotations 只是提示，不是本地授权边界，所以所有动态
+ * MCP 工具继续标为高风险，不能据此绕过审批。
+ *
+ * `Host`、`Pi`、`Runtime Snapshot` 与“候选工具”见 `../../index.ts`。
+ */
+export function createPiMcpToolCandidates(
+  host: PiMcpHost,
+  configured: readonly RuntimeMcpServer[],
+): PiToolCandidate[] {
+  // TODO(待确认)：Runtime 配置目前只 trim URL，而 agents@0.19.0 会用
+  // new URL(url).href 保存连接地址；`https://x` 与 `https://x/`
+  // 可能因此精确匹配失败。
+  const configuredUrls = new Set(
+    configured.map((server) => server.url),
+  );
+  const selectedUrls = new Set<string>();
+  const selectedServerIds: string[] = [];
+
+  for (const [serverId, server] of Object.entries(
+    host.getMcpServers().servers,
+  )) {
+    if (
+      server.state !== "ready" ||
+      !configuredUrls.has(server.server_url) ||
+      selectedUrls.has(server.server_url)
+    ) {
+      continue;
+    }
+    selectedUrls.add(server.server_url);
+    selectedServerIds.push(serverId);
+  }
+  if (selectedServerIds.length === 0) return [];
+
+  const selectedIds = new Set(selectedServerIds);
+  return host.mcp
+    .listTools({
+      serverId: selectedServerIds,
+      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,
+            },
+          };
+        },
+      };
+      return {
+        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.
+        requiredExecutionLevel: "high",
+        source: "action",
+      };
+    });
+}