feat: add `assistant browser` CLI with decoupled operations contract by noanflaherty · Pull Request #26235 · vellum-ai/vellum-assistant

noanflaherty · 2026-04-17T21:53:44Z

Summary

Introduces a first-class assistant browser command namespace with 17 subcommands (navigate, click, type, screenshot, etc.) that are fully decoupled from the existing browser_* skill tools. The implementation adds a shared browser operations contract that both tool wrappers and the CLI consume, creating a clean removal path for browser_* tools later.

Self-review result

GAPS FOUND — 5 gaps fixed across 2 fix PRs

PRs merged into feature branch

refactor: add browser operations contract decoupled from tool wrappers #26193: refactor: add browser operations contract decoupled from tool wrappers
refactor: make browser skill wrappers thin adapters over browser operations #26199: refactor: make browser skill wrappers thin adapters over browser operations
feat: add browser_execute CLI IPC route for daemon-side browser operations #26200: feat: add browser_execute CLI IPC route for daemon-side browser operations
feat: add assistant browser command namespace with 17 browser subcommands #26207: feat: add assistant browser command namespace with 17 browser subcommands
refactor: centralize browser identifier sets across permissions and side-effects #26223: refactor: centralize browser identifier sets across permissions and side-effects

Fix PRs

fix: IPC timeout for browser operations, JSDoc accuracy, and misleading comments #26233: fix: IPC timeout for browser operations, JSDoc accuracy, and misleading comments
fix: stale comment and error message wording for wait_for_download #26234: fix: stale comment and error message wording for wait_for_download

Part of plan: assistant-browser-cli-decoupling.md

#26193) * refactor: add browser operations contract decoupled from tool wrappers * fix: remove TOOLS.json literal from doc comment to pass static analysis guard * fix: remove bundled-skills reference from doc comment to pass static analysis guard

…ations (#26199)

…tions (#26200)

…mmands (#26207) * feat: add assistant browser command namespace with 17 browser subcommands * fix: address review feedback — daemon terminology, help text examples, boolean flags, write error handling 1. Replace "daemon" and "CLI IPC socket" with user-friendly terminology in all user-facing text per AGENTS.md guidelines. 2. Add optional `helpText` field to `BrowserOperationMeta` type and populate it for all 16 operations with behavioral notes and 2-3 concrete examples per CLI AGENTS.md Help Text Standards. `buildSubcommand` now calls `subcmd.addHelpText("after", ...)`. 3. Fix boolean flags to support explicit `false` values via Commander's `--no-<flag>` negation pattern. `fieldToFlag` now emits `--flag, --no-flag` for booleans, and `parseFieldValue` passes through the actual boolean value instead of always coercing to `true`. 4. Wrap `writeFileSync` for screenshot `--output` in try/catch, producing structured error output (JSON or log) instead of an unhandled stack trace on invalid path or permission errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: add enum choices validation and fix boolean option negation for Commander 13 - Use Commander's Option class with .choices() when field.enum is defined, enforcing valid values at the CLI level and showing allowed choices in --help. Required enum fields also call .makeOptionMandatory(true). - Fix boolean option negation by declaring only --flag (not --flag, --no-flag). Commander 13 auto-generates --no-flag; the dual-declaration pattern caused --flag to parse as false. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…ide-effects (#26223)

…26234)

…ng comments (#26233)

… state

noanflaherty · 2026-04-17T21:59:01Z

@codex review this PR again — the previous issues have been fixed in commit 9a6c64f

noanflaherty · 2026-04-17T21:59:07Z

@devin review this PR again — the previous issues have been fixed in commit 9a6c64f

devin-ai-integration

Devin Review found 1 new potential issue.

View 7 additional findings in Devin Review.

devin-ai-integration · 2026-04-17T22:03:31Z

  registerDefaultAction(program);
  registerBackupCommand(program);
  registerBashCommand(program);
+  registerBrowserCommand(program);


🚩 CLI browser command bypasses browser feature flag gate

The browser CLI command is registered unconditionally in assistant/src/cli/program.ts:68, and the IPC route at assistant/src/ipc/routes/browser.ts:71 dispatches directly through executeBrowserOperation — which calls into browser-execution.ts functions without checking the browser feature flag. In contrast, the LLM-facing path gates browser tool availability on the feature flag (as shown in browser-skill-endstate.test.ts with _setOverridesForTesting({ browser: true })). This means assistant browser navigate --url ... works even when the feature flag is disabled, while the LLM cannot invoke browser tools. This may be intentional (CLI as an independent entrypoint), but it's worth confirming the design intent since the feature flag is meant to control browser availability.

Was this helpful? React with 👍 or 👎 to provide feedback.

chatgpt-codex-connector · 2026-04-17T22:04:59Z

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

noanflaherty · 2026-04-17T22:44:42Z

Review Summary

Pulled this branch into a dedicated worktree and did a full diff review with targeted validation.

Validation run

bun test src/browser/__tests__/operations.test.ts src/ipc/__tests__/browser-ipc.test.ts src/cli/commands/__tests__/browser.test.ts src/config/bundled-skills/browser/tools/__tests__/wrapper-adapters.test.ts src/__tests__/browser-identifier-parity-guard.test.ts src/__tests__/browser-skill-endstate.test.ts
bunx tsc --noEmit

Both passed after installing package deps in the worktree.

Findings

1) [P2] `assistant browser` drops `browser_mode` parity with existing browser tools

Where:

assistant/src/browser/operations.ts (lines 222-224)
assistant/src/cli/commands/browser.ts (subcommands are generated from meta.fields only)

Issue:
The new CLI intentionally omits browser_mode from operation metadata and therefore exposes no --browser-mode flag. Existing browser_* tools all support browser_mode overrides today.

Impact:
This is a capability regression for workflows that need deterministic backend pinning (extension, cdp-inspect, local) for debugging/recovery. It also weakens the migration goal of eventually replacing tool usage with CLI usage.

Suggested fix:
Add a shared --browser-mode <mode> option (with enum validation) at the assistant browser command level or per subcommand, and pass it through in IPC input as browser_mode.

2) [P3] Policy modules now import a heavy browser runtime graph via `BROWSER_TOOL_NAMES`

Where:

assistant/src/permissions/defaults.ts (line 3)
assistant/src/permissions/workspace-policy.ts (line 4)
assistant/src/tools/side-effects.ts (line 7)
assistant/src/browser/operations.ts (lines 16-35)

Issue:
BROWSER_TOOL_NAMES is sourced from browser/operations.ts, which imports browser-execution, browser-manager, and browser-mode. That means policy/scoping modules now eagerly pull in the browser execution stack even when only identifier lists are needed.

Impact:
Unnecessary startup/module-load coupling in non-browser codepaths, and increased risk of future dependency cycles or environment-specific breakage.

Suggested fix:
Move identifier-only exports (BROWSER_OPERATIONS, BROWSER_TOOL_NAMES, name mapping helpers) into a lightweight module with no runtime browser imports (e.g. assistant/src/browser/identifiers.ts or extend browser/types.ts), and have both operations.ts and policy modules import from there.

noanflaherty and others added 7 commits April 17, 2026 16:13

refactor: make browser skill wrappers thin adapters over browser oper…

80014db

…ations (#26199)

feat: add browser_execute CLI IPC route for daemon-side browser opera…

21c9729

…tions (#26200)

refactor: centralize browser identifier sets across permissions and s…

81c586e

…ide-effects (#26223)

fix: stale comment and error message wording for wait_for_download (#…

842b73f

…26234)

fix: IPC timeout for browser operations, JSDoc accuracy, and misleadi…

45aae52

…ng comments (#26233)

noanflaherty requested review from awlevin and siddseethepalli as code owners April 17, 2026 21:53

noanflaherty self-assigned this Apr 17, 2026

This comment was marked as resolved.

Sign in to view

fix: update stale JSDoc on executeWaitForDownload to describe current…

9a6c64f

… state

devin-ai-integration Bot reviewed Apr 17, 2026

View reviewed changes

noanflaherty merged commit e14fe23 into main Apr 17, 2026
12 checks passed

noanflaherty deleted the noanflaherty/assistant-browser-cli-decoupling branch April 17, 2026 22:42

noanflaherty mentioned this pull request Apr 17, 2026

refactor: decouple browser identifiers, add --browser-mode CLI flag #26249

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `assistant browser` CLI with decoupled operations contract#26235

feat: add `assistant browser` CLI with decoupled operations contract#26235
noanflaherty merged 8 commits into
mainfrom
noanflaherty/assistant-browser-cli-decoupling

noanflaherty commented Apr 17, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

noanflaherty commented Apr 17, 2026

Uh oh!

noanflaherty commented Apr 17, 2026

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Apr 17, 2026

Uh oh!

chatgpt-codex-connector Bot commented Apr 17, 2026

Uh oh!

Uh oh!

noanflaherty commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

noanflaherty commented Apr 17, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Self-review result

PRs merged into feature branch

Fix PRs

Uh oh!

This comment was marked as resolved.

Uh oh!

noanflaherty commented Apr 17, 2026

Uh oh!

noanflaherty commented Apr 17, 2026

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot commented Apr 17, 2026

Uh oh!

Uh oh!

noanflaherty commented Apr 17, 2026

Review Summary

Validation run

Findings

1) [P2] assistant browser drops browser_mode parity with existing browser tools

2) [P3] Policy modules now import a heavy browser runtime graph via BROWSER_TOOL_NAMES

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

noanflaherty commented Apr 17, 2026 •

edited by devin-ai-integration Bot

Loading

1) [P2] `assistant browser` drops `browser_mode` parity with existing browser tools

2) [P3] Policy modules now import a heavy browser runtime graph via `BROWSER_TOOL_NAMES`