docs(browser): Add recovery guidance for incomplete page extraction
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29.5k
- Forks
- 2.9k
- Avg merge
- 15h 36m
- Merged PRs (30d)
- 70
Description
## Description
The browser skill documents session handling, DOM/AX snapshots, selectors, and extraction separately, but it does not yet connect them into a recovery path when a document extraction returns empty or incomplete data. An agent can keep changing selectors on the wrong page, or treat a virtualized grid's visible rows as the entire document.
This request comes from an offline review of a real agent session using OpenCLI 1.6.1. It is a documentation/agent-guidance improvement, not a claim that the historical session-loss behavior reproduces on current 1.8.8/main.
Related work: #1058 and #1467 discuss historical page/session loss, and #2478 already improves current session observability and binding guidance. This issue focuses on extraction recovery and completeness, building on that work rather than requesting another session implementation.
## Steps to Reproduce
The original environment is not available for a deterministic live reproduction. The following observations are from the recorded workflow, with internal URLs and data omitted:
1. Open a logged-in document and inspect its contents. The title was correct, but DOM extraction returned empty code-card containers and no code/parameter text.
2. Read a virtualized spreadsheet. The visible page text contained only two unique rows despite a larger sheet.
3. Continue separate inspection calls. Four recorded results showed `URL: about:blank`, an empty title and zero interactive elements; other calls returned an empty body.
4. An `eval` enumerated `document.querySelectorAll('*')` and labeled a button with array position `i=216`. The agent passed `216` to `click`, then repeated it after another navigation. Both returned `Element not found: 216`. This was an agent-side target-contract mistake, not evidence of an OpenCLI click bug.
5. The agent ultimately needed the user to paste the complete column before it could finish extracting the list.
The current documentation gap can be checked at main commit `8271afc67e8504bda94c147f446ee29775d08274` in `skills/opencli-browser/SKILL.md`: the Extract section explains `web read`, `eval`, and the text continuation cursor, but does not distinguish exhausting extracted text from covering all rows of a virtualized widget.
## Expected Behavior
Add concise guidance that helps agents:
- Verify URL/title in the same named session before diagnosing selectors when extraction is unexpectedly empty.
- Restore the intended target using the existing owned/bound session rules, then refresh the snapshot.
- Try AX for missing code-card/custom-control text, without treating AX as a guaranteed full-data reader.
- Use a data API, export, or verified traversal for virtualized sheets and check row coverage before claiming completeness. Exhausting a text cursor does not prove that unloaded rows were read.
- Use only actual `state`/`find` refs for numeric targets, never arbitrary DOM array positions.
- Report partial coverage explicitly and avoid repeating failed operations without new evidence.
## OpenCLI Version
Observed historical workflow: 1.6.1. Current documentation checked: 1.8.8 / main `8271afc67e8504bda94c147f446ee29775d08274`.
## Node.js Version
Not recorded in the supplied session.
## Operating System
macOS in the original workflow. Chrome and Browser Bridge extension versions were not recorded.
## Logs / Screenshots
Sanitized examples from the transcript:
```text
URL: about:blank
url: about:blank
title:
interactive: 0 | iframes: 0
{"body":"","scrolls":[]}
Error: Element not found: 216
```
No original transcript, private document URL, authentication data, or internal record values are attached. PR #2483 adds the focused skill documentation; it does not claim to fix the old runtime/session-loss cause.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read skills/opencli-browser/SKILL.md, especially the Extract section, and review PR #2483 for the focused documentation work already in progress. Confirm that the guidance covers session verification, AX fallback, virtualized-row completeness, valid refs, and explicit partial-coverage reporting without changing runtime behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100