pilot_frames

Instructions

Implementation Reference

• src/tools/iframe.ts:7-38 (handler)

  The main handler for the 'pilot_frames' tool. Calls bm.listFrames() to get all frames, formats them with index, type ([main]/[iframe]), URL, and marks the active frame with '→'. Returns '(no iframes — only the main frame)' if only main frame exists.

    server.tool(
      'pilot_frames',
      `List all frames (iframes) on the current page with their indices, names, and URLs.
  Use when the user wants to see what iframes exist on the page, find an iframe to interact with, or verify the page structure before switching frame context. The main frame is always index 0. Use pilot_frame_select to switch into an iframe.
  
  Parameters: (none)
  
  Returns: Numbered list of frames showing index, type ([main] or [iframe name="..."]), URL, and an arrow (→) marking the currently active frame. Returns "(no iframes — only the main frame)" if no iframes exist.
  
  Errors: None.`,
      {},
      async () => {
        await bm.ensureBrowser();
        try {
          const frames = await bm.listFrames();
          if (frames.length <= 1) {
            return { content: [{ type: 'text' as const, text: '(no iframes — only the main frame)' }] };
          }
          const activeFrame = bm.getActiveFrame();
          const page = bm.getPage();
          const allFrames = page.frames();
          const text = frames.map(f => {
            const isCurrent = allFrames[f.index] === activeFrame;
            const marker = isCurrent ? '→ ' : '  ';
            const label = f.isMain ? '[main]' : `[iframe${f.name ? ` name="${f.name}"` : ''}]`;
            return `${marker}[${f.index}] ${label} ${f.url}`;
          }).join('\n');
          return { content: [{ type: 'text' as const, text }] };
        } catch (err) {
          return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
        }
      }

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

  Registration call: registerIframeTools(effectiveServer, bm) which registers 'pilot_frames' among other frame tools.

  registerIframeTools(effectiveServer, bm);

• src/tools/register.ts:49-52 (registration)

  'pilot_frames' listed in the STANDARD_TOOLS set, meaning it's available in 'standard' and 'full' tool profiles.

    'pilot_frames', 'pilot_frame_select', 'pilot_frame_reset',
    // session + config
    'pilot_auth', 'pilot_block', 'pilot_find',
  ]);

• src/browser-manager.ts:340-348 (helper)

  Helper method listFrames() used by the handler. Returns an array of frame objects with index, url, name, and isMain by mapping over page.frames().

  async listFrames(): Promise<Array<{ index: number; url: string; name: string; isMain: boolean }>> {
    const page = this.getPage();
    return page.frames().map((f, i) => ({
      index: i,
      url: f.url(),
      name: f.name() || '',
      isMain: f === page.mainFrame(),
    }));
  }

• src/browser-manager.ts:327-333 (helper)

  Helper method getActiveFrame() used by the handler to determine which frame is currently active for the arrow marker.

  getActiveFrame(): Frame {
    if (this.activeFrame && !this.activeFrame.isDetached()) {
      return this.activeFrame;
    }
    this.activeFrame = null;
    return this.getPage().mainFrame();
  }