pilot_network

Instructions

Implementation Reference

• src/tools/inspection.ts:66-87 (handler)

  The main tool handler for 'pilot_network' — registers and implements the MCP tool. Retrieves network requests from a circular buffer, with optional clear. Returns formatted entries showing method, URL, status, duration, and size.

    server.tool(
      'pilot_network',
      `Retrieve network requests (XHR, fetch, navigation, static assets) from a circular buffer.
  Use when the user wants to debug API calls, check request/response status codes, monitor network activity, or verify that a request was made after an action.
  
  Parameters:
  - clear: Set to true to clear the buffer after reading (useful for isolating new requests after an action)
  
  Returns: List of requests showing method, URL, status code, duration in ms, and response size in bytes. Or "(no network requests)" if the buffer is empty.
  
  Errors: None — returns empty message if no entries exist.`,
        { clear: z.boolean().optional().describe('Clear the buffer after reading') },
      async ({ clear }) => {
        await bm.ensureBrowser();
        if (clear) { networkBuffer.clear(); return { content: [{ type: 'text' as const, text: 'Network buffer cleared.' }] }; }
        if (networkBuffer.length === 0) return { content: [{ type: 'text' as const, text: '(no network requests)' }] };
        const text = networkBuffer.toArray().map(e =>
          `${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
        ).join('\n');
        return { content: [{ type: 'text' as const, text }] };
      }
    );

• src/buffers.ts:79-86 (schema)

  NetworkEntry interface — defines the shape of network request data stored in the circular buffer (timestamp, method, url, status, duration, size).

  export interface NetworkEntry {
    timestamp: number;
    method: string;
    url: string;
    status?: number;
    duration?: number;
    size?: number;
  }

• src/tools/register.ts:73-87 (registration)

  registerAllTools calls registerInspectionTools which registers 'pilot_network'. The tool is included in the 'full' profile (not in core or standard).

  export function registerAllTools(server: McpServer, bm: BrowserManager, profile: ToolProfile = 'full'): void {
    const allowed = PROFILE_TOOLS[profile];
    const effectiveServer = allowed ? createFilteredServer(server, allowed) : server;
  
    registerNavigationTools(effectiveServer, bm);
    registerSnapshotTools(effectiveServer, bm);
    registerInteractionTools(effectiveServer, bm);
    registerPageTools(effectiveServer, bm);
    registerInspectionTools(effectiveServer, bm);
    registerVisualTools(effectiveServer, bm);
    registerTabTools(effectiveServer, bm);
    registerSettingsTools(effectiveServer, bm);
    registerIframeTools(effectiveServer, bm);
    registerAutomationTools(effectiveServer, bm);
  }

• src/buffers.ts:96-103 (helper)

  CircularBuffer<NetworkEntry> instance and addNetworkEntry helper — the data store backing the pilot_network tool. Entries are populated by Playwright page event listeners in browser-manager.ts.

  // ─── Buffer Instances ───────────────────────────────────────
  
  const HIGH_WATER_MARK = 50_000;
  
  export const consoleBuffer = new CircularBuffer<LogEntry>(HIGH_WATER_MARK);
  export const networkBuffer = new CircularBuffer<NetworkEntry>(HIGH_WATER_MARK);
  export const dialogBuffer = new CircularBuffer<DialogEntry>(HIGH_WATER_MARK);

• src/browser-manager.ts:911-947 (helper)

  Playwright event listeners that populate the network buffer — page.on('request') captures method/URL, page.on('response') captures status/duration, page.on('requestfinished') captures response size.

  page.on('request', (req) => {
    addNetworkEntry({
      timestamp: Date.now(),
      method: req.method(),
      url: req.url(),
    });
  });
  
  page.on('response', (res) => {
    const url = res.url();
    const status = res.status();
    for (let i = networkBuffer.length - 1; i >= 0; i--) {
      const entry = networkBuffer.get(i);
      if (entry && entry.url === url && !entry.status) {
        networkBuffer.set(i, { ...entry, status, duration: Date.now() - entry.timestamp });
        break;
      }
    }
  });
  
  page.on('requestfinished', async (req) => {
    try {
      const res = await req.response();
      if (res) {
        const url = req.url();
        const body = await res.body().catch(() => null);
        const size = body ? body.length : 0;
        for (let i = networkBuffer.length - 1; i >= 0; i--) {
          const entry = networkBuffer.get(i);
          if (entry && entry.url === url && !entry.size) {
            networkBuffer.set(i, { ...entry, size });
            break;
          }
        }
      }
    } catch {}
  });