go_history

Instructions

Implementation Reference

• src/tools/browser/navigation/history.ts:10-83 (handler)

  GoHistoryTool class — the main handler for the 'go_history' tool. Extends BrowserToolBase, defines getMetadata (name, description, inputSchema with 'direction' enum) and execute() which performs page.goBack() or page.goForward(), checks console errors, and reports URL/title.

  export class GoHistoryTool extends BrowserToolBase {
    static getMetadata(sessionConfig?: SessionConfig): ToolMetadata {
      return {
        name: 'go_history',
        description: "Navigate browser history (back/forward). Returns: 'Navigated <direction> in browser history', a quick network-idle note if available, 'URL: <current>', and 'Title: <current>' when set. If console errors occur after the navigation, returns an error like 'Console error after history navigation: <message>' including Title when available.",
        annotations: ANNOTATIONS.navigation,
        inputSchema: {
          type: 'object',
          properties: {
            direction: {
              type: 'string',
              description: "History direction to navigate",
              enum: ['back', 'forward']
            },
          },
          required: ['direction'],
        },
      };
    }
  
    async execute(args: any, context: ToolContext): Promise<ToolResponse> {
      this.recordNavigation();
      return this.safeExecute(context, async (page) => {
        const dir: Direction = args.direction === 'forward' ? 'forward' : 'back';
  
        // Capture initial state
        let initialUrl = '';
        let initialTitle = '';
        try { initialUrl = page.url(); } catch {}
        try { initialTitle = await page.title(); } catch {}
  
        // Perform history navigation
        if (dir === 'back') {
          await page.goBack();
        } else {
          await page.goForward();
        }
  
        const verb = dir === 'back' ? 'back' : 'forward';
        const lines: string[] = [`Navigated ${verb} in browser history`];
  
        // Allow network to settle briefly first (best-effort)
        try {
          const note = await quickNetworkIdleNote(page);
          if (note) lines.push(note);
        } catch {}
  
        // After the brief wait, surface console errors since navigation
        try {
          const errs = await gatherConsoleErrorsSince('navigation');
          if (errs.length > 0) {
            let titleInfo = '';
            try {
              const t = await page.title();
              if (t) titleInfo = `\nTitle: ${t}`;
            } catch {}
            return createErrorResponse(`Console error after history navigation: ${errs[0]}${titleInfo}`);
          }
        } catch {}
  
        // Report new URL and Title explicitly
        try {
          const newUrl = page.url();
          lines.push(`URL: ${newUrl}`);
        } catch {}
        try {
          const newTitle = await page.title();
          if (newTitle) lines.push(`Title: ${newTitle}`);
        } catch {}
  
        return createSuccessResponse(lines);
      });
    }
  }

• src/tools/browser/navigation/history.ts:16-26 (schema)

  Input schema for go_history: requires 'direction' (string, enum: ['back', 'forward']).

  inputSchema: {
    type: 'object',
    properties: {
      direction: {
        type: 'string',
        description: "History direction to navigate",
        enum: ['back', 'forward']
      },
    },
    required: ['direction'],
  },

• src/tools/browser/register.ts:56-104 (registration)

  GoHistoryTool is registered in the BROWSER_TOOL_CLASSES array at line 56, alongside other navigation tools.

    GoHistoryTool,
    ScrollToElementTool,
    ScrollByTool,
  
    // Lifecycle (2)
    CloseTool,
    SetColorSchemeTool,
  
    // Interaction (7)
    ClickTool,
    FillTool,
    SelectTool,
    HoverTool,
    UploadFileTool,
    DragTool,
    PressKeyTool,
  
    // Content (3)
    ScreenshotTool,
    GetTextTool,
    GetHtmlTool,
  
    // Inspection (10)
    InspectDomTool,
    GetTestIdsTool,
    QuerySelectorTool,
    FindByTextTool,
    CheckVisibilityTool,
    CompareElementAlignmentTool,
    InspectAncestorsTool,
    ElementExistsTool,
    MeasureElementTool,
    GetComputedStylesTool,
  
    // Evaluation (1)
    EvaluateTool,
  
    // Console (2)
    GetConsoleLogsTool,
    ClearConsoleLogsTool,
  
    // Network (2)
    ListNetworkRequestsTool,
    GetRequestDetailsTool,
  
    // Waiting (2)
    WaitForElementTool,
    WaitForNetworkIdleTool,
  ];

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

  GoHistoryTool is imported from './navigation/history.js' in the registration file.

  import { GoHistoryTool } from './navigation/history.js';

• src/tools/browser/evaluation/evaluate.ts:124-125 (helper)

  Helper reference: evaluate tool suggests using 'go_history' when code patterns like window.location or history.pushState are detected.

    suggestions.push({ key: 'nav', line: '🌐 navigate / go_history — vs window.location / history.pushState' });
  }