jackwener / jackwener/OpenCLI

docs(browser): Add recovery guidance for incomplete page extraction

Open
#2,482 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.