Playwright debugging agent

The Playwright debugging agent investigates failed browser automations and automatically opens pull requests that fix broken scripts. libretto-playwright-debug lets an existing Playwright script keep its current browser provider, retries, logging, and fallback logic while adding one agent call in the failure path.

import { createLibrettoDebugger } from "libretto-playwright-debug";

const librettoDebugger = createLibrettoDebugger({
  github: {
    owner: "acme",
    repo: "automations",
    baseBranch: "main",
  },
  agent: {
    model: "openai/gpt-5.4",
  },
});

The agent.model value uses Libretto’s provider/model-id convention. For example, openai/gpt-5.4 resolves to provider openai and model id gpt-5.4. The first version supports openai/... and anthropic/....

try {
  await runAutomation(page);
} catch (error) {
  await librettoDebugger.debugPlaywrightFailure(error, page);

  await sendToExistingFallbackService(error);
  throw error;
}

What It Captures

debugPlaywrightFailure() captures the error message, stack trace, page URL, page title, screenshot, and DOM snapshot from the failed page. It uses the stack frames — plus any paths you pass in includeFiles — to read the relevant source files from GitHub at baseBranch.

await librettoDebugger.debugPlaywrightFailure(error, page, {
  includeFiles: ["src/workflows/acme.ts"],
});

includeFiles is optional. When the error stack references files inside the repository, the debugger discovers them automatically; pass includeFiles when the stack does not cover the file that needs the fix (for example bundled or minified stacks, or a cross-file change).

How It Investigates

The debugger does not guess a fix from a static snapshot. It runs an agent loop built on the libretto-browser-tools SDK: the model is given the failure context and source files, then drives a real browser to confirm the root cause before proposing a change. It stays attached to the supplied failed Page, preserving its authentication, storage, routes, open tabs, and in-memory state. It can:

browser_status the existing pages in the failed browser context,
browser_snapshot the live accessibility tree (and a screenshot), and
browser_exec Playwright code against the page — for example counting a selector’s matches to check whether it actually resolves.

Only once the live page confirms the cause does the agent submit full-file replacements. The debugger writes those files to a new branch with the GitHub Git API and opens a pull request whose body cites the observed evidence. If the evidence is insufficient for a safe fix, it opens no PR and returns status: "no_changes". The debugger does not launch or close a second browser. Debugger infrastructure failures resolve with status: "debugger_failed" so the caller’s existing fallback and original error handling can continue.

Model Keys

Set the provider API key in the environment where the Playwright script runs:

export OPENAI_API_KEY=...
# or
export ANTHROPIC_API_KEY=...

You can also pass agent.apiKey directly when the key is provided by your secrets manager.

GitHub Authentication

The debugger uses Libretto’s public GitHub App through Libretto Cloud. First use the Libretto setup flow to connect the repository. The flow verifies the GitHub user can access the installed Libretto GitHub App and stores the tenant/repository link. Then provide:

export LIBRETTO_API_KEY=...

With that setup, the debugger asks Libretto Cloud for a short-lived GitHub installation token scoped to the configured owner/repo and only the permissions needed to read/write contents and open pull requests. For local development, you can pass github.token or set LIBRETTO_GITHUB_TOKEN / GITHUB_TOKEN. The token needs permission to read contents, write contents, and open pull requests on the target repository. The GitHub App should request these repository permissions:

Contents: read and write
Pull requests: read and write
Metadata: read

The hosted public Libretto app should be installable by any account. It does not need webhooks or device flow. It does need a callback URL and GitHub App user authorization so Libretto Cloud can verify and store the tenant/repository link before minting installation tokens.

​What It Captures

​How It Investigates

​Model Keys

​GitHub Authentication

What It Captures

How It Investigates

Model Keys

GitHub Authentication