Repository navigation
fix(cli): point wrong browser guesses at Orca's real top-level browser commands - #26100
brennanb2025 wants to merge 5 commits into
Conversation
orca browser --help now lists the top-level browser commands, unknown commands under 'browser' (and 'open'/'navigate' renames) recover to the real verb, typo recovery survives trailing operands like URLs, goto and tab create take the URL as a positional, and the remote orca CLI no longer prints the relay handshake success line to stderr.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configuration
📒 Files selected for processing (2)
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review. 📝 WalkthroughWalkthroughThe CLI now supports browser command grouping in help and command suggestions. The Priority: ⬇️ Low Merge Risk: ⚪ Minimal · up to Nested browser typos no longer receive misleading top-level guidance, and browser synonyms followed by URLs recover correctly. The change is mergeable after normal checks. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🔇 Additional comments (4)
src/relay/relay-handshake.ts (1)
168-179: LGTM!Also applies to: 216-216
src/relay/relay-connect-channel.ts (1)
4-4: LGTM!Also applies to: 44-45
src/relay/relay-handshake-roundtrip.test.ts (1)
10-12: LGTM!Also applies to: 130-161
src/cli/specs/browser-basic.ts-70-70 (1)
70-70: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
⚠️ Unverified finding
Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.Document both supported URL forms in usage. Both commands accept a positional URL and
--url, but their usage strings show only the positional form.
src/cli/specs/browser-basic.ts#L70-L70: add the--url <url>alternative to thegotousage.src/cli/specs/browser-basic.ts#L203-L203: add the--url <url>alternative to thetab createusage.Based on learnings, keep flags listed in usage in parity with
allowedFlags.Source: Learnings
ℹ️ Review info
⚙️ Run configuration
- Configuration used: Repository UI
- Review profile: CHILL
- Plan: Advanced
- Run ID:
7ac16491-252f-4602-9e37-92a66dcdb4df
📒 Files selected for processing (11)
src/cli/browser.test.tssrc/cli/command-spec.tssrc/cli/command-suggestion.test.tssrc/cli/command-suggestion.tssrc/cli/help.tssrc/cli/specs/browser-advanced.tssrc/cli/specs/browser-basic.tssrc/cli/specs/browser-command-discovery.test.tssrc/relay/relay-connect-channel.tssrc/relay/relay-handshake-roundtrip.test.tssrc/relay/relay-handshake.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.
| if (commandPath.length > 1 && isCommandGroupName(specs, group)) { | ||
| nextSteps.push( | ||
| `Orca's ${group} commands run at the top level (orca <command>, not orca ${group} <command>); list them with: orca ${group} --help` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Do not give top-level guidance for nested browser commands. If the user enters orca browser identity gte, this branch says browser commands do not run under browser. The valid command is orca browser identity get. Restrict this guidance to guesses outside a registered nested browser command prefix.
|
Agents using Orca browser commands through an SSH terminal could miss the working commands: This change lists the existing top-level browser commands in browser help, recovers likely commands even with operands, accepts positional URLs for Verified at Live remote browser/SSH QA is blocked and remains unverified. The required first QA driver failed startup before receiving the task; the safety check then found a change in the Windows host's real Codex config hash, so QA stopped before an Electron rig or test container launched. The hash alone does not establish the cause, and the config was not read or restored. There is no Electron UI change, so screenshots are not applicable; no real remote-command output is claimed as evidence. Deployed old/new release pairs, manual WSL/mobile flows and live navigation were not tested in this loop. This PR has not been merged and auto-merge has not been enabled. |
ELI5
Agents running inside an SSH terminal kept failing to use Orca's built-in browser and gave up for Playwright. The browser worked fine; the
orcacommand line steered them into dead ends. Theorca browserhelp said the browser could only manage its "identity", wrong guesses likeorca browser open <url>failed with no hint,orca goto <url>without--urlwas rejected, and every remote call printed a scary-looking relay line to the error stream. This PR makes each of those wrong guesses lead straight to the right command.What Changed
The problem. A user runs Orca on a Mac and an agent (OMP) inside a Linux VM through an Orca SSH terminal. On Sep 25 we reproduced the setup: over SSH,
orcareaches the Mac and every real browser command works (orca tab create --url,orca goto --url,orca snapshot,orca screenshot), including pages served from inside the VM. The failures all came from the command surface, which an agent without the orca-cli skill explores by trial and error:orca browser --helplisted onlybrowser identity get/set. The real browser commands are top-level (orca goto,orca snapshot, ...), so an agent that checked thebrowsergroup concluded Orca's browser can't open pages.orca tab creatsuggestedtab create, butorca tab creat https://example.comsuggested nothing.orca goto https://example.comandorca tab create https://example.comfailed with "Unknown command", because the URL was accepted only as--url.orcacall from an SSH host printed[relay-connect] Handshake OK at version=…to stderr, which an agent can read as a failure.What is different for the user (and their agents):
orca browser --helpnow lists every top-level browser command, under a heading that says to run them asorca <command>.orca browsernames the real command when there is one (browser goto→orca goto,browser screenshot→orca screenshot) and always adds one line pointing atorca browser --help.openandnavigate, the two verbs agents reach for that edit distance can't connect to the real names, recover toorca tab createandorca goto.orca goto <url>andorca tab create <url>accept the URL positionally.--urlstill works; passing both is refused, as for other commands.orcaCLI no longer prints the handshake success line. Errors still print.The mechanism.
groupfield. The browser spec files mark their top-level commandsgroup: 'browser'. The group help lists them, and the existing suggester treatsbrowser <command>as a candidate path for each one. No second suggestion mechanism: it's the same ranking with more candidate paths.tabintab lstis not a typo ofget), keeps only the match that explains the most tokens, and returns only exact hits when there are any. The destructive-command guard (feat(cli): make the CLI self-correcting and self-describing for agents #6303) now checks the token at the candidate's verb position, not the last typed token, so a trailing value can't unlock a delete.--from→--terminaluses.gotoandtab createdeclarepositionalArgs: ['url'], the conventionfile open <path>,artifacts share <file>andsearch <query>already follow: a command's single main value can be positional, and the flag form stays.relay.js --connect), whose stderr Orca captures for connection diagnostics and whichssh-relay-pinned-node.integration.test.tsasserts on, and the remoteorcaCLI (relay.js --orca-cli), whose stderr is the agent's. The helper now hands the accepted version to its caller instead of printing it, and only the bridge prints the line, unchanged. Nothing else reads it (I checkedsrc/mainandsrc/shared).Why
orca browser gotoas an alias. Aliases would double the browser command surface and hide where the commands really live. The request was for wrong guesses to point to the real commands.groupon the spec instead of a hint table in the suggester. The help and the recovery read the same declaration, so a new browser command shows up in both without a second list to keep in sync.openandnavigate. Edit distance handles typos. Without a synonym,browser openis three edits fromhover, which would be a wrong suggestion.Linked Issue
User report (agents on an SSH VM failing at Orca browser commands; reproduced Sep 25). Out of scope: detecting the orca-cli skill on SSH hosts (#18357), onboarding, settings UI.
Visual Proof
Real output from the CLI built from
origin/mainand from this branch, run underenv -iagainst an empty Orca user-data directory so nothing reached a live Orca.Before (main)
After (this branch)
With
--json, the same recovery appears inerror.data.suggestions(["tab create"]) anderror.data.nextSteps. On main both were empty.Relay stderr. A detached relay daemon bundled from each side, with the remote CLI path (
relay.js --orca-cli status, no Orca client attached) and the SSH bridge path (relay.js --connect) run against it:Testing
src/cli/specs/browser-command-discovery.test.ts(new, against the real command registry): group help lists the browser commands; each reported wrong guess recovers to the real command; the group pointer line; typo-plus-URL recovery; positional URL forgotoandtab create; positional and--urltogether is refused.src/cli/command-suggestion.test.ts: operands after a near miss, destructive intent judged at the verb, group-prefixed recovery, synonyms, the destructive guard on group-prefixed candidates, no cross-group leakage.src/cli/browser.test.ts:goto <url>andtab create <url>send the same RPC payload as the--urlform.src/relay/relay-handshake-roundtrip.test.ts: the handshake helper hands the version to its caller and writes no[relay-connect]line; the bridge line format is unchanged.src/cliandsrc/relaywithconfig/vitest.config.ts: 361 passed, 2 skipped.pnpm tc:cli,pnpm tc:nodeandpnpm run check:code-quality:changedpass on top ofa3ecee0dce1.orca goto <url>against a running Orca on this branch. The positional form reaches the handler as the sameurlflag (unit-tested payload), and the--urlpath itself is unchanged and was verified over SSH on Sep 25.ssh-relay-pinned-node.integration.test.ts(the bridge-line assertion) was not run locally. The bridge still prints the identical line, which the roundtrip test pins.Review
Agent skill upstream boundary
docs/reference/agent-skill-sharing-upstream-boundary.mdand copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.Notes
orcaforwards its arguments to the Mac app, so the help, recovery and positional changes take effect when the Mac app updates. The stderr change ships in the relay, which Orca redeploys to the host for each app version. No wire format changes.--urlkeeps working everywhere. Scripts parsingorca agent-context --jsonseepositionalArgs: ["url"]ongotoandtab create. Nothing else in that schema changes.Checklist
N/Awith reason (CLI text output pasted above)pnpm lint,pnpm typecheck,pnpm test, andpnpm buildpass (or CI will cover; local preferred). Ran tc:cli, tc:node, the changed-files gate, and the src/cli + src/relay suites locally; CI covers the rest.