feat(navigator): let N2ComputerAgent serve and dispatch caller tools

[lawrencechen98]

Problem

chat.completions.create already accepts caller-supplied tools, but N2ComputerAgent implements only the tools in its set, so it has nowhere to dispatch one. api.md said as much:

N2ComputerAgent implements only the tools in the set … To actually run custom tools, drive chat.completions.create in your own loop.

That is a steep price for adding one function: you give up the batch mechanics, coordinate mapping, image window, compaction, budgets and callbacks, and re-implement them.

Change

N2ComputerAgent(tools=[...]) forwards the definitions with every request and dispatches a call to one of them to the computer's run_custom_tool(name, arguments). The returned text becomes the tool result, and the call carries the post-action frame the way a GUI batch does: {"type": "input_image", "image_url": ..., "result": "<tool text>"}. A custom tool acts on the machine — a navigation replaces the page — so leaving it text-only sent the model back for a screenshot it should already have had. bash, read, write and edit stay text-only: they change nothing on screen.

It follows the families the loop already has (SHELL_ACTION_HANDLERS, FILE_ACTION_HANDLERS, BROWSER_ACTION_HANDLERS): one action type, one handler-map entry, one adapter hook. parse_n2_tool_calls takes custom_tool_names so the routing is testable on its own.

Behaviour preserved at both edges:

• an adapter with no run_custom_tool gets the same recoverable "not supported" result the other families produce, instead of an AttributeError mid-run
• a name the caller did not declare still fails with [ERROR] Invalid <name> call: … does not expose <name>, so a typo in a definition surfaces

Name collisions are left to the server, which already refuses a definition shadowing a served name; duplicating that check here would only drift.

Why

Evaluating n2 on the OSWorld driver's browser tools (goto_url, go_back, go_forward, refresh, extract_elements, find, set_element_value, execute_js) alongside the canonical desktop set — computer_batch, bash, read, write, edit. No published tool set serves that combination: the browser-navigation sets predate the shell and file tools, so they cannot be combined by picking a different tool_set.

Test

Four tests in tests/test_navigator_n2_harness.py cover routing, the served request, the adapter hook receiving name and arguments, the text-result rendering, and both failure edges. Full n2 suites pass: 139 passed.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes the n2 agent loop’s tool dispatch and when screenshots attach to tool results, which affects model turns and token usage; failures are recoverable and covered by new harness tests.

Overview
N2ComputerAgent now accepts tools=, forwards those OpenAI-shaped definitions on every completion request, and routes matching model calls through a single run_custom_tool(name, arguments) hook on the computer adapter instead of treating them as unsupported set tools.

parse_n2_tool_calls takes custom_tool_names so declared names become run_custom_tool actions; undeclared names still get recoverable does not expose errors, and adapters without the hook get a recoverable [ERROR] rather than crashing the run.

Observation policy: caller custom tools and built-in goto_url no longer return text-only results like bash—their tool output is input_image with adapter text plus a post-action screenshot, so the model is not left blind after navigation-style actions.

api.md documents the new agent path; tests/test_navigator_n2_harness.py adds four tests for routing, serving, execution, and failure edges.

^{Reviewed by Cursor Bugbot for commit 06ad7fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 65c7457. Configure here.}