[computer-use] Allow opting out of tool groups (e.g. browser.*) to cut per-request tool-prefix cost

[j4y89tnywy]

Summary

Feature request: make the CU provider's tool registration configurable, so deployments can opt out of tool
groups they cannot use (e.g. the browser group). Today all 55 tools are registered unconditionally and their
descriptions/schemas are paid for on every single request (~94 KB / ~23.5k tokens in our environment);
opting out of the browser group alone would save ~20.3% (~4,780 tokens) per request.

We are NOT asking for the browser route to be enabled — only for a way to not register groups we cannot use.

Environment

• @deepseek-ai/dsh 0.1.6-alpha.2
• dsh-computer-use 0.1.6-alpha.2 + dsh-experimental-computer-use-cua-driver-native 0.1.6-alpha.2
• macOS 13.7.8 (Ventura) / Intel x86_64, no third-party browser installed (system Safari only)

Measured cost (prefix, per request)

• all 55 tools: ~94 KB / ~23.5k tokens
• minus the browser group (10 tools): -20.3% / ~4,780 tokens
• minus recording group (5): -6.3%; minus session/config group (9): -7.3%
• minus all three (24 tools; core-only 31): -33.9% / ~7,976 tokens

For server / CI / text-only deployments this is pure overhead.

Current state: no way to opt out (read-only investigation on 0.1.6-alpha.2)

• provider Config = Schema.object({}) — empty schema, no knobs
• driver listToolsJson() accepts only signal
• provider lib/index.js:78 reads the manifest, :81-101 calls tools.register() for each entry with zero filtering
• the capability manifest (authorization_requirement: profile_behavior_and_optional_capability_manifest)
  only affects authorization / behavior, not the registration count — so it cannot reduce the prefix
• the only lever today is disabling the whole provider (disabled: true), which also removes
  click / get_window_state / list_windows — not acceptable

Suggested implementations (any one of them)

1. Config.tools / Config.groups, e.g. { browser: false, recording: false }, filtered before registration
2. let listToolsJson({ signal, filter }) accept a filter, forwarded by the provider
3. if the responsibility belongs to the driver, expose a profile-level "capability group" switch

One related repro

• browser_prepare{allow_launch:true, profile:{mode:isolated_new}} returns
  "refused (browser_route_unavailable): no vendor-signed system Chromium executable is available for
  isolated launch"
• page{action:'get_text'} against Safari returns empty silently (isError=false, length 0). A silent empty
  result is more dangerous than an error — please consider distinguishing "no route available" from
  "the page is empty".
• Note: page{action:'get_text'} does work against an Electron host (the DSH desktop app), so page is not in
  the same category as get_browser_state. If a group-level switch is added, please keep page available
  (or exclude it from the browser group).

[argszero]

The per-request cost you measured is removable today, without waiting for the provider to grow a config knob — and the registration cost is not.

I verified your read-only investigation against the published 0.1.6-alpha.2 artifacts. Your line numbers are exact: dsh-experimental-computer-use-cua-driver-native@0.1.6-alpha.2 lib/index.js:81-101 is the unconditional tools.register() loop, :82 builds publicName = \cua_driver_native__${tool.name}`, and listToolsJson()accepts only{ signal }. So the model-facing names in your environment are cua_driver_native__browser_prepare, cua_driver_native__page`, … — useful to know, because the group you want off can be named from outside the provider.

The seam that already exists

ToolRuntime.restrict(filter) is public, scoped, and already does exactly what a group switch would do to the request prefix. It masks what a scope inherits — the global layer plus every ancestor scope layer — and never the scope's own registrations. A config-mounted provider plugin registers into the global layer, so its tools are maskable from any agent scope.

I ran a probe against the published @deepseek-ai/dsh-tools (global provider layer + an ancestor scope layer + the agent's own layer mounted together):

probe	result
agent.ctx.tools.restrict({ deny: ['cua_driver_native__browser_prepare', …] })	accepted — the names leave schemas()/get() and dispatch as UNKNOWN_TOOL
same, with a name contributed by an ancestor scope layer	accepted, same effect
same, with a name registered in the agent's own layer	throws (own registrations are outside the filter)
same, with a name the agent cannot see	throws, listing the known names

The mask is real, not presentational: the tools leave the model-facing schema prefix, leave the PTC SDK projection (both read the same view), and a call to one now returns unknown tool "…". Other agents are unaffected.

A plugin that turns your group list into that restriction

@argszero/cordis-plugin-preset-tool-filter@0.2.0 — npm i @argszero/cordis-plugin-preset-tool-filter, source at https://github.com/argszero/cordis-plugin-preset-tool-filter (MIT). It already owned this seam for a different case (a preset inheriting global tools it never intended, #5786); 0.2.0 adds the group half:

plugins:
  "@argszero/cordis-plugin-preset-tool-filter":
    groups:
      browser: { names: [cua_driver_native__browser_prepare, cua_driver_native__get_browser_state] }
      recording: { prefix: cua_driver_native__recording }
    disableGroups: [browser, recording]
    # dryRun: true   # rehearse: measure and report, change nothing

Group membership is declared by you (exact names, a namespace prefix, or both), so page stays available exactly as you asked — just leave it out of the browser group. A name the agent cannot see is skipped rather than thrown, and a group that matches nothing warns instead of failing agent creation, so a driver upgrade that renames a tool degrades to a smaller saving rather than an unstartable deployment.

It also prints the measurement you made by hand, taken from the live agent's own schema surface:

preset-tool-filter: hid 4/9 tools (1214 of 2625 schema bytes, 46.2%, ~304 tokens) on "reporter" [browser=2, recording=2]

Set report: false to silence it. You can reproduce your ~94 KB / ~23.5 k and the 20.3 % browser figure with dryRun: true before committing to a config.

30 tests pass on 0.1.2-rc.1, 0.1.3-alpha.2, 0.1.5-rc.2 and 0.1.6-alpha.2 (each run with that @deepseek-ai/dsh-tools actually installed). The plugin declares @deepseek-ai/dsh-tools as an optional peer and its built artifact imports nothing at runtime, so mounting it cannot pull a second harness copy.

What this does not fix

Being precise about the boundary, since your suggestion list is provider-side and one of its items is out of reach from a plugin:

• The provider still registers the whole catalog at startup. That is a one-time cost (plus one listToolsJson()), not a per-request one — but if you want the driver to stop listing groups it will never use, or want listToolsJson({ signal, filter }), that is still a provider/driver change; nothing outside the provider can filter the catalog before registration.
• It does not change the driver's own callTool surface, its capabilities, or its authorization manifest.
• Reserved PTC transport (run_code) cannot be named in a restriction at all; the plugin drops it from a configured deny instead of throwing.

Two smaller findings

1. Diagnostic wording. restrict() rejects a name that is not in restrictableNames with names unknown global tool "x"; known global tools: …. But the accepted set is the whole inherited surface — global layer and every ancestor scope layer — so a name contributed by an ancestor scope is accepted while the message calls the set "global". Anyone debugging a group config will look in the wrong layer. (packages/core/tools/src/index.ts — the throw site and the restrictableNames construction.)

2. Your silent-empty repro. page{action:'get_text'} returning isError: false, length 0 against Safari while working against the Electron host is a driver-side result-classification issue, not a registration one — a group switch would not have surfaced it. Distinguishing "no route available" from "the page is empty" needs the driver to report the route state; worth its own report so it is not lost inside this one.