Repository navigation
Conversation
Sensitive Change ReviewSensitive files changed:
How to clear this check:
Only the author's comment counts this way. A reviewer can instead |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. This PR adds an agent-facing browser op and changes no dashboard UI. The only file under [UX-REVIEWED] 594ce0d Description read[DESCRIPTION-READ] 0b16c0b476f917b3cfff941bb372f80787fb1b69981dd1838798a70eb5ff7e2a That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: one gated, paged Notes
[DESIGN-REVIEWED] 594ce0d Description read[DESCRIPTION-READ] 7eabef8da6429249fe6cab40396a4d036712eb43ff33ab336a98f31c4ae07ba7 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The new Notes
What this change shipsInventory (9 items) — 8 justifiedIntent: let the agent read a whole web page as text in a few calls instead of a scroll-and-screenshot loop. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 594ce0d Description read[DESCRIPTION-READ] f52df22d42164b433eca3423812a4aea9c06f5aaf7c3501e996da6759139300b That sha256 names the PR description this verdict read. Recompute it with |
12505b6 to
4b5bda0
Compare
|
self-added: yes
|
|
self-added: yes
|
4b5bda0 to
d6c5c88
Compare
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
d6c5c88 to
e3270e9
Compare
|
|
|
|
b7462aa to
22c46b0
Compare
|
snapshot lists only interactive elements and headings, and screenshot returns pixels, so an agent reading a docs page paid one scroll and one screenshot per screen. The new read op returns the page content as text (innerText of the whole page, plus open shadow roots and same-origin frames, which Chromium's innerText does not enter) or as HTML, scoped to a ref when given, and paged by offset. It runs in the walker's isolated world through run_op, so the URL gate, the takeover fence and the ref rules apply as for snapshot. A root with no box gives no text: innerText on it falls back to textContent, script bodies included. Frames are counted as scanFrames counts them, which read reuses as its walk, so an object or embed document is never read. HTML is serialized from a copy imported into a document with no window, so nothing loads or runs and the live DOM is untouched. React mirrors a typed value into the value attribute, so every input's value but a button's, checkbox's or radio's is blanked, and textarea bodies are emptied. Secret or CSRF meta content and attributes, credential query and fragment parameters in URLs, template content and comments are scrubbed too. The html note says it is the light DOM of one document. The gateway redacts the whole content before paging, so a token cannot straddle two pages, and returns a digest that changes with the page. The shim fences the content with a new pair in the shared fence registry and neutralizes look-alikes, so a page cannot forge a note or a hand-back line outside the fence. Rejected: the reflex observe's visibleText() viewport walk, which reads only what is on screen; reopen if a caller needs what is in view rather than the whole page. Separate text and html ops: one op with a format argument shares every gate and the paging; reopen if the two need different gates. Scoping read to a cross-origin frame ref: refused with bad_ref for now; reopen if agents need frame text, through FrameOps. Stripping whole query strings from URLs in html: it breaks doc links; reopen if a credential parameter name escapes the list.
22c46b0 to
594ce0d
Compare
|
|
|
@smeyffret a user on our internal Slack hit exactly this gap: The branch is a draft and now conflicts with main (one file, |
|
@smeyffret thanks for this. To get the fix to the user sooner, we carried it onto current main in #39361, with you as co-author in the commit. Your branch is untouched. What changed on the way: the description conflict is merged with main's |
Add a `read` op to the browser tool. It returns the page's text for the whole page (not only the screen), plus open shadow roots and same-origin frames, or a scrubbed copy of its HTML. Results page at 18,000 characters with `next_offset` and a `digest`. It runs through `run_op`, so the URL gate and the takeover fence apply as for `snapshot`, and it needs no preview setting. The tool description tells agents to prefer it over screenshots and scrolling. `snapshot` lists only controls and headings, so a reading-heavy page (prose, code blocks) came back almost empty and agents fell back to screenshot loops. Carried from #36027 onto current main: the description conflict is merged with main's `type` steps text, the redaction tests use a synthetic GitHub token with the owner's switch on (AWS key IDs stay visible since #37408), and a walker test reads a tutorial-like page. Co-authored-by: smeyffret <smeyffret@gmail.com>
Problem / Motivation
Goal: Let the agent read what a web page says as text or HTML, instead of scrolling and screenshotting it one screen at a time.
The
browsertool'ssnapshotlists only controls and headings, andscreenshotreturns pixels. To read a documentation page, the agent pays one scroll and one screenshot per screen. On a signed-in docs site, nine pages took 60 to 100 screenshots, and the host flagged the repeated scroll calls as a loop.Why it matters
Each frame costs image tokens, and text read off pixels cannot be quoted or searched exactly. A page that only renders in a logged-in browser cannot fall back to
web_fetch, so today the screenshot loop is the only way to read it.Not a goal
queryread by selector (Browser tool: let the agent act by DOM/CSS selector, not snapshot-refs + screenshots #18933).evaluatestays out of the op list.What changed (motivation → approach → change)
One op,
read, with aformatargument, so text and HTML share every gate and the paging. The reflex loop'svisibleText()was not reused because it reads only the viewport.snapshot_walker.js):textis the root'sinnerText(the whole page, not only the viewport), then the text of each open shadow root and same-origin frame, whichinnerTextskips; real Chromium confirms that shadow text is not duplicated. A root with no box returns no text, becauseinnerTextwould fall back totextContentand its script bodies; adisplay: contentsshadow host counts as rendered. The page side caps the content by its JSON-escaped size, so a long non-ASCII page comes backtruncatedrather than failing.htmlserializes a copy imported into a document with no window, so the live DOM is untouched and nothing in the copy runs. The copy blanks every typed-fieldvalue(React mirrors typed values into the attribute), secretmetacontent and secret-named attributes, credential parameters in URLs (the rest of the link stays),templatecontent, iframesrcdocand comments, and emptiesscriptandstylebodies.scanFramesgains an optional start and root callback, soreadcounts skipped frames the same way the screenshot guard does; its default call is unchanged.ops.py): validatesformat,offsetandref, and redacts and fence-neutralizes the full content before paging, so a credential cannot be split across two pages and no page grows past the shim's cap. One result carries 18,000 characters plustotal,next_offsetand adigestthat changes when the page changed between calls. It runs throughrun_op, so the URL gate and the takeover fence apply as forsnapshot.mcp_tools/browser.py, description inmcp_tools/catalog/browser.py): fences the page content and the page title with a new pair in the shared marker registry (context_assembly/markers.py), so a page cannot forge the shim's note or hand-back lines.readcounts as a read-only op after a hand-back.security_posture.pylistsbrowser_harness/ops.pyas inbound page-text redaction, beside the shim.docs/system-specs/modules/browser.md, op lists inconfig/prompt.mdand thekirocrew-commands/SKILL.mdandweb-browse/SKILL.mdbuiltin skills.Backwards compatibility
Compatible: a new op and a new optional walker call; every existing op, argument and result is unchanged.
Removes nothing: the diff only adds an op, a fence pair and an optional
scanFramesparameter whose default keeps today's walk.Tests
test/test_browser_read_op.py: paging reproduces the full content, and the last page has nonext_offset; a credential straddling a page boundary is redacted;bad_format,bad_offsetandbad_refrefusals; a stale ref returnsref_stale; a refused URL refusesreadlikesnapshot; the digest is stable for the same page and changes with it; a forged end fence or hand-back line stays inside the fence; the header and content fit the shim's 20,000 cap.website/src/test/snapshotWalker.read.test.ts(the real walker source in happy-dom): text below the fold (viewport reads stubbed so a viewport reader would stop); shadow-root and direct shadow text; hidden roots and hidden frames give nothing; the HTML scrub (typed values, secret meta and attributes, URL parameters, template content, comments); the live DOM is unchanged.test/test_browser_guard_isolated_count.py: its source pins now match the newscanFrames(signature and stop before thereadsection.Manual verification
The walker's
readwas run in real headless Chromium (Playwright's headless shell) on a page with an open shadow root, a direct shadow text node, a same-origin iframe, a hidden iframe, a hidden script and a textarea.textreturned the light, shadow and frame text once each and nothing from the hidden parts;htmlreported 2 skipped frames and no shadow text. An end-to-end run of the op through a live gateway is not done yet.Screenshots / video
Why no screenshot: the only file under
website/is a unit test; the op has no UI and changes nothing the dashboard renders.Related Issues
Closes #35742
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.