feat(web-fetch): wire @frontagent/mcp-web-fetch into the agent registry & planner (#357) (#359)

Wires the previously-unwired @frontagent/mcp-web-fetch adapter (PR #358) so
the agent can actually call the `web_fetch` tool, and surfaces it to the
two-phase planner. This is increment 3/3 of #357 and closes it.

- runtime-node: register `web_fetch` in WebMCPClient.callTool + listTools,
  delegating to handleWebFetchTool (no browser launch — lazy playwright,
  so web_fetch stays decoupled from the browser tools sharing the client).
- core/agent: add `web_fetch` to registerWebTools() so the executor routes
  it to the 'web' client (mirrors how filesense_* is routed via the 'file'
  client in registerFileTools()).
- core/schemas: add `web_fetch` to ACTION_ENUM so planner-emitted steps with
  action `web_fetch` pass StepSchema validation (url param already exists in
  STEP_PARAMS_SCHEMA). Treated like browser_navigate.
- core/plan-generation: mention web_fetch in both 可用工具 prompt regions +
  param hint, so the planner knows it can fetch external docs/API refs.
- add @frontagent/mcp-web-fetch workspace dep to runtime-node.
- add hermetic mcp-clients.test.ts asserting web_fetch is listed & routed.

MVP scope only: no web_search, no when-to-search heuristics (deferred).
SSRF guards live in the adapter (#358) with tests.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ceilf6

packages/core/src/agent/agent.test.ts

@@ -1,5 +1,6 @@
 import type { ExecutionStep } from '@frontagent/shared';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import { Executor } from '../executor.js';
 import { createAgent } from './agent.js';
 import { generateOutput } from './answer-generation.js';
 
@@ -213,3 +214,25 @@ describe('createAgent', () => {
     expect(executorSnap.actionSkills).toBeInstanceOf(Array);
   });
 });
+
+describe('registerWebTools routing contract', () => {
+  it('routes web_fetch and the browser tools to the web client', () => {
+    const spy = vi.spyOn(Executor.prototype, 'registerToolMapping');
+    try {
+      const agent = createAgent({
+        projectRoot: '/test',
+        llm: { provider: 'openai', model: 'gpt-4', apiKey: 'test-key' },
+      });
+      agent.registerWebTools();
+      const webTools = spy.mock.calls
+        .filter(([, client]) => client === 'web')
+        .map(([tool]) => tool);
+      // web_fetch must route to the same 'web' client as the browser tools so
+      // the executor can dispatch it to WebMCPClient.callTool.
+      expect(webTools).toContain('web_fetch');
+      expect(webTools).toContain('browser_navigate');
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

packages/core/src/agent/agent.ts

@@ -269,6 +269,7 @@ export class FrontAgent {
       'scroll',
       'screenshot',
       'wait_for_selector',
+      'web_fetch',
     ];
     for (const tool of tools) {
       this.executor.registerToolMapping(tool, 'web');

packages/core/src/llm/plan-generation.ts

@@ -129,6 +129,7 @@ export async function generatePlanInTwoPhases(
 - **browser_navigate**: 浏览器访问URL（⚠️ 使用上下文中提供的"开发服务器端口"）
 - **browser_screenshot**: 页面截图
 - **get_page_structure**: 获取页面DOM结构
+- **web_fetch**: 抓取 URL 网页内容并清洗为纯文本（HTML→text），用于查阅库/框架文档、API 参考等外部资料
 
 ${PROGRESSIVE_EXPLORATION_PROTOCOL}
 
@@ -271,6 +272,7 @@ ${options.skillContext ?? '无已激活内容技能'}
   如果上下文中提供了端口信息，使用 http://localhost:{端口}/
 - **browser_screenshot**: params 可选 fullPage: true
 - **get_page_structure**: params 可为空对象
+- **web_fetch**: params 需要 url
 
 # 重要提示
 - create_file 和 apply_patch 必须设置 needsCodeGeneration: true
@@ -422,6 +424,7 @@ async function generatePlanSinglePhase(
 - **browser_navigate**: { url: "地址" }
 - **browser_screenshot**: { fullPage: true }
 - **get_page_structure**: {}
+- **web_fetch**: { url: "地址" }
 
 ${PROGRESSIVE_EXPLORATION_PROTOCOL}
 

packages/core/src/llm/schemas.ts

@@ -13,6 +13,7 @@ const ACTION_ENUM = [
   'browser_click',
   'browser_type',
   'browser_screenshot',
+  'web_fetch',
 ] as const;
 
 const STEP_PARAMS_SCHEMA = z

packages/runtime-node/package.json

@@ -25,6 +25,7 @@
     "@frontagent/mcp-memory": "workspace:*",
     "@frontagent/mcp-shell": "workspace:*",
     "@frontagent/mcp-web": "workspace:*",
+    "@frontagent/mcp-web-fetch": "workspace:*",
     "@frontagent/sdd": "workspace:*",
     "@frontagent/shared": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.29.0",

packages/runtime-node/src/mcp-clients.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { WebMCPClient } from './mcp-clients.js';
+
+describe('WebMCPClient web_fetch wiring', () => {
+  it('lists web_fetch as an available tool', async () => {
+    // Construction is cheap: the playwright browser is launched lazily, not in
+    // the constructor, so this stays hermetic (no browser, no network).
+    const client = new WebMCPClient();
+    const tools = await client.listTools();
+    const names = tools.map((tool) => tool.name);
+
+    expect(names).toContain('web_fetch');
+    // Sanity: the existing browser tools are still present alongside it.
+    expect(names).toContain('browser_navigate');
+  });
+
+  it('throws for an unknown web tool', async () => {
+    const client = new WebMCPClient();
+    await expect(client.callTool('definitely_not_a_tool', {})).rejects.toThrow(/Unknown web tool/);
+  });
+});

packages/runtime-node/src/mcp-clients.ts

@@ -21,6 +21,7 @@ import {
   type RagQueryParams,
 } from '@frontagent/mcp-memory';
 import { type BrowserManager, createBrowserManager } from '@frontagent/mcp-web';
+import { handleWebFetchTool } from '@frontagent/mcp-web-fetch';
 
 export class FileMCPClient implements MCPClient {
   private readonly snapshotManager: SnapshotManager;
@@ -143,6 +144,8 @@ export class WebMCPClient implements MCPClient {
         const { selector, timeout } = args as { selector: string; timeout?: number };
         return this.browserManager.waitForSelector(selector, timeout);
       }
+      case 'web_fetch':
+        return handleWebFetchTool(name, args);
       default:
         throw new Error(`Unknown web tool: ${name}`);
     }
@@ -159,6 +162,11 @@ export class WebMCPClient implements MCPClient {
       { name: 'browser_scroll', description: '滚动页面' },
       { name: 'browser_screenshot', description: '截取页面截图' },
       { name: 'browser_wait_for_selector', description: '等待元素出现' },
+      {
+        name: 'web_fetch',
+        description:
+          '抓取 URL 网页内容并清洗为可读文本（HTML→text），用于查阅文档/API 参考；内置 SSRF 防护',
+      },
     ];
   }