Make the tool menu the selection surface

[rgarcia]

Summary

Phase 3. /tools built its rows from the list the CLI had already composed, so it could only subtract:

export function describeTools(tools: readonly CuaCliTool[]): ToolSelectionItem[] {
  return tools.map(...)   // exactly what the app passed the harness
}

Everything else CUA can offer was invisible — playwright_execute, the computer toolset, a provider-native surface the default didn't pick, browser_act on a model whose default excluded it. The tool menu is the differentiator and the CLI hid most of it.

The menu decides availability by compiling

cuaToolMenu(model, selected) returns every offerable tool, each marked available or not. It does not restate the compiler's rules — it compiles the candidate catalog and reports the result:

try { compileCuaToolCatalog({ model, requestedTools: candidate }); available = true }
catch (error) { available = false; reason = error.message }

So the menu cannot drift from what harness.setTools() accepts: a row is available exactly when selecting it compiles, and the reason shown is the compiler's own message. compileCuaToolCatalog is documented as pure and declaration-only — it builds no executable tools and retains none of its inputs — so probing per entry is cheap and side-effect-free.

A test asserts that equivalence directly, across a model with a native browser surface, one with a native computer surface, one with neither, one carrying a quirk, and one synthesized from an id pi-ai's registry doesn't carry.

Availability is pairwise, so rows are re-evaluated as you stage

Two providers' native surfaces can't coexist, and a native surface derives a transport the rest of the selection must suit. A per-tool boolean computed once can't express that. The picker rebuilds its rows after every toggle, unavailable rows can't be staged, and bulk actions skip them.

open: 43 rows, 38 available, 5 selected
added playwright: 25 tools (baseline 24)
dropped google native: 5 tools, native row available=true
browser_act still blocked by the quirk: true

cua tools

Same menu, no TUI, with --json:

model: google:gemini-3.6-flash

TOOL                   GROUP     STATE        NOTE
browser_wait_for       browser   unavailable  provider google does not accept the schema used by "browser_wait_for"
browser_act            browser   unavailable  provider google does not accept the schema used by "browser_act"
computer               native    unavailable  provider.openai.native.computer.v1 requires a openai model; selected google:gemini-3.6-flash
google native browser  native    default      Google's predefined browser action set (20 actions), selected as one unit.

Testing

• npm run typecheck clean; 94 / 296 / 142 tests pass.
• The /tools tests were rewritten rather than deleted, and gained one that pins the new capability: enabling playwright_execute on a model whose baseline never included it.
• Picker behavior preserved: baseline order, ctrl+r restoring model defaults, staged-until-confirm, the mutation queue against a /model switch, and refusal to open mid-turn.

One caveat worth flagging: a vitest file-level collect failure reports as "Test Files 1 failed" without any × line, so a grep watching only for failed assertions can miss it entirely. I hit that mid-change and only caught it because the total test count dropped.

---

Note

Medium Risk
Expands which tools a session can enable and changes transport/catalog combinations users can stage, though harness.setTools() still compiles before applying; mistakes affect agent behavior rather than security boundaries.

Overview
cuaToolMenu(model, selected) in @onkernel/cua-ai lists every offerable CUA tool for a model and marks each row available only when adding it to the current selection would make compileCuaToolCatalog succeed, surfacing the compiler’s error when it would not. Availability is relative to the staged selection (native surfaces, transport pinning), so callers rebuild the menu after each change.

The CLI /tools picker no longer mirrors only the composed baseline: it shows the full menu plus application tools, lets users add tools the app never composed (e.g. playwright_execute, computer tools), shows unavailable rows with reasons, and restages rows after every toggle/bulk action. Applies use menu order via toolsForSelection; ctrl+r still restores model defaults. cua tools prints the same menu to stdout (--json optional).

describeMenu preserves live spec instances for already-installed tools (e.g. Anthropic native browser options) so a no-op apply does not drop configuration.

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

[rgarcia]

bugbot run

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Ctrl+A wait matches prior footer
  • I changed the Ctrl+A synchronization wait to ${selectable}/${selectable} enabled, which uniquely matches the post-select-all footer and eliminates the stale pre-keypress match race.

Or push these changes by commenting:

@cursor push ad56e4b65d

Preview (ad56e4b65d)

diff --git a/packages/cli/test/tui.fixture.test.ts b/packages/cli/test/tui.fixture.test.ts
--- a/packages/cli/test/tui.fixture.test.ts
+++ b/packages/cli/test/tui.fixture.test.ts
@@ -389,7 +389,7 @@
 		// ctrl+a enables every selectable row — including tools the application
 		// never composed — and ctrl+x clears it; both are staged.
 		session.press(KeyCtrlA);
-		await session.waitForVisible(`/${selectable} enabled`, { timeoutMs: WAIT_MS });
+		await session.waitForVisible(`${selectable}/${selectable} enabled`, { timeoutMs: WAIT_MS });
 		await session.waitForStable(STABLE_MS, { timeoutMs: WAIT_MS });
 		const enabledAll = /(\d+)\/\d+ enabled/.exec(session.snapshot().visible);
 		assert.ok(enabledAll && Number(enabledAll[1]) > baseline, "ctrl+a grows the selection past the baseline");

_{You can send follow-ups to the cloud agent here.}

[rgarcia]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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