history related tools

[esokullu]

should we add a histroy related tools for tasks like go back go forward

[Ayush7614]

Assessment: yes — straightforward and already anticipated

Hello @esokullu I like to work on this issue

Today there is no history navigation tool in the Act-mode schema. Models that need "go back" often try execute_js({code:"history.back()"}), which fails on Chrome (MV3 CSP blocks execute_js via new Function()). We even have an LLM test scenario (test/llm/scenarios/030.json) where the expected behavior is to tell the user to press the browser Back button manually.

So this issue fills a real gap — not just convenience.

---

Proposed tools

Option A (recommended): two Act-only tools

• go_back — navigate one step back in the current tab's session history
• go_forward — navigate one step forward

Optional params (mirror navigate):

• steps (default 1, clamp e.g. 1–10) for history.go(-n) / history.go(+n)
• force (default false) — same unsaved-changes guard as navigate

Option B: single tool

• browser_history({ direction: "back" | "forward", steps?: number, force?: boolean })

Option A is easier for small local models (clearer tool names, less enum confusion).

Optional read-only helper (Ask + Act):

• get_history_state → { canGoBack, canGoForward, currentUrl }
  Useful before acting; note history.length is unreliable on many SPAs, so prefer "attempt + verify URL changed" or CDP Page.getNavigationHistory on Chrome.

---

Implementation sketch (Chrome)

Per docs/adding-a-tool.md, changes in three layers:

1. Schema — src/chrome/src/agent/tools.js

Add tool definitions next to navigate. Act-only (not in ASK_ONLY_TOOLS).

Update compact/mid prompts to mention back/forward alongside navigate.

2. Handler — src/chrome/src/agent/agent.js (executeTool)

Handle in the background block (same area as navigate), not via execute_js.

Preferred path: chrome.scripting.executeScript with a fixed injected function:

() => {
  const before = location.href;
  history.back(); // or forward / go(-steps)
  return { before, after: location.href };
}

This works even when execute_js is CSP-blocked — the navigate unsaved-changes probe already uses scripting.executeScript for the same reason.

Reuse navigate's unsaved-changes guard before leaving the page (attached files + dirty fields). Block unless force:true.

After navigation, wait briefly + read chrome.tabs.get(tabId).url (same pattern as navigate).

Chrome CDP fallback (optional): if debugger already attached, Page.getNavigationHistory + Page.navigateToHistoryEntry can be more reliable on bfcache / SPA edge cases. Not required for v1.

3. Classification / permissions

• Add to Agent.NAV_TOOLS, STATE_CHANGE_TOOLS, NAV_PRONE_TOOLS
• permission-gate.js: map to Capability.NAVIGATE (host = current tab origin, like other same-tab navigation)
• i18n labels in src/chrome/src/ui/locales/*.js

4. Firefox mirror

Same tools in src/firefox/src/agent/tools.js + agent.js via browser.tabs.executeScript (Firefox has no execute_js in Chrome's sense, but dedicated tools are still cleaner).

---

Edge cases to handle

Case	Behavior
chrome://, about:, extension pages	Return { success: false, error: "no history navigation on internal pages" }
No history entry	Return { success: false, canGoBack: false } — don't claim success if URL unchanged
Unsaved form / attached files	Block unless force:true (same UX as navigate)
SPA history.pushState back	history.back() still works; pair with wait_for_stable before re-reading AX tree
User asked "go back" in Ask mode	Tool unavailable; model should explain limitation (current behavior)

---

Tests to update/add

1. Update test/llm/scenarios/030.json — ideal next tool becomes go_back, not done with manual instructions.
2. Fixture (optional): local HTML with two pages + link; Playwright scenario "click link then go_back returns to first page".
3. Unit: unsaved-changes guard applies to go_back same as navigate.

---

Scope estimate

~150–250 lines across Chrome + Firefox (schema, handler, guards, i18n, tests). Low risk, high value. No new manifest permissions needed (scripting + tabs already granted).

Happy to take a PR if useful — this is a good first-contributor-sized feature.

[esokullu]

pls do, I've assigned it to you. the only argument to add here is the more tools we add, the more smaller models can hallucinate. we gotta be very careful with that.