Libretto Readonly

---
name: libretto-readonly
description: "Read-only Libretto workflow for diagnosing live browser state without clicks, typing, navigation, or mutation requests."
license: MIT
metadata:
  author: saffron-health
  version: "0.6.45"
---

## How Libretto Read-Only Works

- Use this skill when the browser session must stay strictly read-only.
- Libretto stores read-only vs write-access on the session itself.
- The primary inspection tools are `snapshot` and `readonly-exec`.
- `readonly-exec` reuses Libretto's normal execution pipeline, but it only exposes read-only helpers and denies mutating Playwright methods.
- Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.

## Working Rules

- Announce which session you are using and what page you are inspecting.
- Do not use `exec`, `run`, or any direct Playwright action that could change browser or application state.
- Do not click, type, submit forms, navigate, upload files, dispatch DOM events, or send non-GET requests.
- Prefer `snapshot` first when the visible page state is unclear.
- Use `readonly-exec` for focused inspection: titles, HTML, locator text, counts, visibility checks, and GET requests.
- Keep snippets small and purpose-built. Do not run multiple `readonly-exec` commands at the same time.
- Close disposable sessions before your final response once inspection is complete. Open browsers keep consuming local or hosted resources.
- End with diagnosis and handoff guidance, not an attempted in-browser repair.

## Commands

### `connect`

- Use `connect` to attach to an existing CDP endpoint for a preserved browser session.
- Use `--read-only` when creating the Libretto session handle for a preserved browser session.
- Libretto read-only mode is enforced through Libretto commands; direct CDP clients that skip Libretto are outside this boundary.

```bash
libretto connect http://127.0.0.1:9222 --read-only --session failed-job-debug
```

### `pages`

- Use `pages` when a popup, new tab, or second page exists.
- If `readonly-exec` or `snapshot` complains about multiple pages, list ids first and then pass `--page`.

```bash
libretto pages --session failed-job-debug
```

### `snapshot`

- Use `snapshot` as the first high-level observation tool.
- Run `snapshot <ref>` to inspect a subtree from the latest full snapshot.

### `readonly-exec`

- Use `readonly-exec` for narrow inspection code only.
- Denied operations fail with `ReadonlyExecDenied: ...`.

#### Helpers

- `page` — a read-only Playwright `Page` proxy. Standard Playwright read methods work normally (`url()`, `title()`, `content()`, `frames()`, `getByRole()`, `locator()`, `textContent()`, `isVisible()`, `count()`, `scrollIntoViewIfNeeded()`, etc.). `frames()` returns read-only `Frame` proxies, including from `childFrames()` and `parentFrame()`. Anything that mutates a page or frame (`click`, `fill`, `goto`, `evaluate`, `keyboard`, `mouse`) is blocked.
- `state` — the current Libretto session state object.
- `get(url, options?)` — HTTP client restricted to **GET and HEAD** requests. Replaces `fetch`, which is blocked in readonly mode. Any request with a body or a non-GET/HEAD method throws `ReadonlyExecDenied`.
- `scrollBy(deltaX, deltaY)` — scroll the viewport by pixel offset. Use this to inspect content below the fold without targeting a specific element.

Standard JS globals `console`, `URL`, `Buffer`, `setTimeout`, and `setInterval` are also available.

#### Examples

```bash
libretto readonly-exec "return page.url()" --session failed-job-debug
libretto readonly-exec "return await page.getByRole('heading').first().textContent()" --session failed-job-debug
libretto readonly-exec "return await page.frames()[1]?.getByRole('heading').textContent()" --session failed-job-debug

# HTTP GET inspection
echo "const r = await get('https://api.example.com/status'); return await r.json()" \
  | libretto readonly-exec - --session failed-job-debug

# Scroll down to inspect below-the-fold content
libretto readonly-exec "await scrollBy(0, 500)" --session failed-job-debug
```

### `close`

- Use `close` when the inspection session is no longer needed, unless the user explicitly asks to keep the browser open.

```bash
libretto close --session failed-job-debug
```