A lost response should not create a second post.
Original, copyable browser-agent prompts for verified writes, bounded retries and resumable tasks — with a real local browser demo.
12 prompt modules · 4 workflow templates · reproducible recovery demos
Install the Agent Skill · Build a task profile online · Quick start · Browser crash experiment · Copy a module · Project overview · Demo guide · Download the v0.2.3 source bundle · See the boundaries · 中文
Built and maintained by @LydiaTools. Follow the account for small, reproducible Agent tools; star this repository if you want to keep the modules and recovery cases handy.
Listed in Awesome-AI-Agents under Reference Repo.
For standalone action/readback reports and a recorded-check CI gate, see the companion StepReceipt. Its checks are supplied by the integration; it is a separate tool, not automatically connected to these demos.
Your browser agent clicks Save. The response times out. A new session starts. Should it click again?
An action ledger gives the host a better question: what actually happened? This project makes that distinction explicit in prompts and executable examples.
| Failure | Included contract |
|---|---|
| The agent says “done” after a click | Define and read the actual postcondition |
| A timeout causes a duplicate submission | Persist the readback as PENDING_REVIEW; require a recorded review before replay |
| A long task loses its place | Checkpoint verified work; resume from state |
| A small loop becomes a large batch | Count cumulative writes across resumes |
| A webpage tells the agent to change its task | Keep observations outside trusted authority |
| A disabled control is bypassed through script | Use visible prerequisites or stop; do not alter page state |
| Every task loads a giant instruction dump | Assemble only the necessary modules |
| Status messages fill with boilerplate | Apply a narration blacklist without altering user copy |
The demo runs a real browser against a synthetic local page. Its decisions
are deterministic: no model API key, social account or cloud-browser account is
needed. It exercises host-side controls; it is not an LLM behavior benchmark.
The local allowlist rejects an evaluate action before its executor runs. That
test covers this example controller only; a real host must also withhold
unapproved browser tools and other direct action paths.
The graphic combines the unaltered fixture capture with the local run's save-count readback. It shows a deterministic recovery test, not a live model or production deployment. See how it was made, then run the two commands below to check the result on your machine.
For a project using Codex, the current repository includes a self-contained browser-task-recovery skill:
npx skills@1.7.4 add LydiaTools/browser-agent-blueprint --skill browser-task-recovery --agent codexThis optional third-party installer needs Node 22.20+. The skill routes uncertain writes and resumed tasks to the relevant original references; its bundled helper can export all six profiles after installation. Installation, manual copy and validation scope. Project-scope installation and exact resource/helper output are tested; live agent selection and other hosts are not. Test installs are excluded from adoption claims. The v0.2.3 bundle includes the skill; fixed older ZIPs remain unchanged.
Open the task-profile builder. Choose a task, optionally add an integration contract and a workflow, then copy or download the exact text. Included files, UTF-8 bytes and SHA-256 are shown. The six base profiles match the CLI byte for byte. 中文界面.
The builder uses the original English source text; changing its interface language does not translate the prompts. Review the output, map it to your actual tools and merge compatible guidance. It does not install a connector or run an agent. No model calls, uploads or analytics run on this page.
For an offline copy, extract the v0.2.3 source bundle and open builder/index.html inside its browser-agent-blueprint folder. Node is not needed for this page. The original v0.1.0 ZIP remains a fixed older snapshot without the builder. The current prompt modules are v0.1.1.
Start with risk checks, uncertain writes and retries, or external memory. Each file is plain text.
For a complete task profile, install Node.js 20+ and run:
git clone https://github.com/LydiaTools/browser-agent-blueprint.git
cd browser-agent-blueprint
npm run assemble -- contentThe output is dist/content.txt. Review it, map conceptual tools to your actual
host schemas, and place it in a supported trusted instruction surface.
Assembly has no npm dependencies. It reports bytes and a hash, not token savings.
Without Git, download the v0.2.3 source bundle,
extract it, and run the commands from its browser-agent-blueprint folder. The
ZIP is a fixed release snapshot; the online synthetic page follows the current
repository version.
Start with the demo guide to choose between the online fixture and the local recovery runner. For a quick look at the page used by the tests, open the browser-only synthetic fixture. Save a draft, reload, and inspect the persisted record and save count. The fixture is a synthetic test page; it does not run an agent or the recovery checks. Run the commands below to exercise the host-side controls.
npm install
npx playwright install chromium
npm test
npm run test:browser
npm run demoOn Linux, install the browser system dependencies when needed:
npx playwright install --with-deps chromiumIf you already have a compatible Chrome installation, you may use
BLUEPRINT_BROWSER_CHANNEL=chrome npm run demo instead of downloading Chromium.
Compatibility depends on your installation.
npm run demo:prepare
npm run demo:resumeThe first command saves one synthetic draft, verifies it, writes a checkpoint, exports synthetic localStorage and exits. The second starts a new process, validates the checkpoint, restores the fixture and verifies that the save count is still 1. It refuses to dispatch the completed action ID again.
The local runner uses loopback port 4179; an occupied port causes a visible error.
Output goes to ignored runs/: checkpoint, synthetic browser state and screenshots.
No existing browser profile is used. The all-in-one demo intentionally performs
two saves to exercise lost-acknowledgement recovery; run demo:prepare before
demo:resume for the one-save cross-process case.
npm run demo:crash-boundariesTwo actual SIGKILL cases: the fresh process restores 0 records before
the export, and 1 after it, without replaying Save. This macOS/Linux
experiment tests explicit snapshot recovery; it does not kill the browser or
prove disk-flush durability. Method, actual report and limits.
Use current source or v0.2.3; the fixed v0.1.1 ZIP predates this experiment.
npm run demo:checkpoint-killSeven deterministic process-kill cases compare direct overwrite with the existing temporary-file/fsync/rename writer. A fresh process must read the complete old checkpoint, the complete new one, or reject missing/invalid state; it must never replay the recorded operation. No browser, model or dependency installation is needed. English method · 中文. Use current source or v0.2.3; the fixed v0.2.2 ZIP predates this addition.
npm run demo:browser-killReopen the same disposable browser profile after an actual browser-process
SIGKILL, without importing a snapshot. The included macOS run restored old
or missing data after four acknowledged writes. Read the controls, raw report
and scope in the English method or
中文. Use current source or v0.2.3; the fixed v0.2.2
ZIP predates this experiment.
npm run demo:write-aheadThe destination stays running while the worker is killed. A fresh process reads
0 before the write or 1 after it, then persists the observation as
PENDING_REVIEW. Strict mode blocks new writes until a review decision records
whether it landed; a failed recovery read stays unresolved. An unguarded two-click
control produces 2 records on the same target. The host binds a stable
operation ID, payload reference and hash; changing the attempt ID cannot replay
an unresolved or confirmed operation. Run it and inspect the evidence.
Use current source or v0.2.3, macOS/Linux. This is a synthetic host-control test; the destination has no server-side deduplication. It is not a production exactly-once guarantee.
Ran the demo or mapped a module to your own browser host? Share one integration observation with the module version, synthetic or live-host scope, and expected versus observed result. One report is evidence for that run, not a reliability claim.
| Scenario | What the example demonstrates |
|---|---|
| Saved draft verification | Title, body and save count match after reload |
| Batch risk gate | A high-risk batch is rejected before dispatch |
| Cross-process resume | A new process reads the checkpoint without re-saving |
| Lost acknowledgement | An actual local save is reconciled without automatic replay |
| Hostile page instruction | Page text does not grant host permission to publish |
| Transient read recovery | A classified read retries within a finite budget |
See evaluation scope, architecture and recorded local verification. Passing these examples does not establish model obedience or production safety.
The project guide, demo guide, and synthetic fixture offer optional Google Analytics 4 measurement only after you allow it. It records page paths, allow-listed campaign tags, the referrer origin, LydiaTools GitHub destination paths, and a generic event after a fixture save is verified. It never sends the fixture title, body, saved record, or save count. Rejecting or postponing consent keeps analytics off; change a saved choice from Privacy settings in the footer.
| File | Purpose |
|---|---|
| 00_core.txt | Outcome, scope, execution loop |
| 01_output.txt | Narration blacklist and compact status |
| 02_authority.txt | Trusted authorization and page-content boundary |
| 03_browser.txt | Pre-call checks, fresh targets and saved-state reads |
| 04_risk.txt | Four risk levels, batch bounds and page-enforced control state |
| 05_retries.txt | Six failure classes; reconcile uncertain writes |
| 06_memory.txt | External checkpoint and readback requirements |
| 07_lifecycle.txt | Pause, rollover, host wake and manual resume |
| 08_evidence.txt | Verification rules and honest completion claims |
| 09_modules.txt | Optional loading and context budget rules |
| 10_content.txt | Approved content entry and per-record validation |
| 11_social.txt | Draft/schedule/publication distinctions |
Profiles: minimal, long, content, validation, social, full.
The minimal profile keeps eight mandatory policies. Optional loading is a host
responsibility; the assembler supports static selection.
- Cloud browser session: reconnect boundaries and session references.
- Website content entry: approved field mapping and fresh saved reads.
- Page data validation: discrepancy reports without silent repairs.
- Social operations: bounded account actions and verified publication states.
The repository includes three integration contracts, not vendor plugins or verified connectors.
| Target | Included | Live-tested status |
|---|---|---|
| Muse | Operator mapping and capability checklist | Not tested |
| Grok | Model/tool-loop and dispatcher responsibilities | Not tested |
| Codex | Project-guidance mapping and browser-tool requirements | Not tested |
No vendor endorsement or compatibility guarantee is implied. The host must provide actual browser tools, durable memory, permissions, context telemetry and scheduling where required. A prompt alone cannot keep a process alive, increase its context window, or schedule a wake.
This is independently authored, AI-assisted work based on public model capabilities and engineering patterns. It is not any vendor's leaked internal system prompt. No CL4R1T4S prompt text is reused. See provenance.
These templates guide behavior; they are not a security sandbox or a substitute
for runtime checks. The local controller is intentionally small and fixture-specific.
The disabled-control rule is prompt guidance, not a fix for a vendor agent: the
upstream Browser Use reproduction
reported one model bypassing a rule added through extend_system_message.
This repository's evaluate check applies only to actions routed through its
example allowlist.
Without a persistence callback, action state stays in memory until explicit
checkpointing; the original snapshot runner has a pre-checkpoint crash gap.
The optional write-ahead runner flushes DISPATCHED before
execution and reads the destination after worker death. It does not provide
server-side idempotency or exactly-once delivery. Production hosts still need
schema validation, scoped authority, locking and protected secret storage.
The repository provides manual cross-process resume, not an automatic scheduler. Context-threshold handling and the full failure taxonomy are prompt contracts, not implemented provider integrations. The digest detects corruption, not malicious rewriting by someone with file access. The injection fixture tests a fixed host policy, not an LLM's resistance to adversarial content.
Use authorized accounts and data, respect platform automation rules, and keep credentials and private material out of prompts, checkpoints and public issues. No CAPTCHA bypass, rate-limit evasion, mass unsolicited messaging or fabricated engagement is provided. Screenshots and exported state contain synthetic data.
There are no claims of industrial readiness, guaranteed completion, measured token reduction, virality or Star growth. Those require their own evidence.
A small failure case is more useful than a broad claim. Share a synthetic reproduction, expected/observed behavior and exact environment through Issues.
See contributing. Useful next contributions include concurrent-host locking, live-model evaluations and tested adapter mappings.
MIT for this repository's original work. Dependencies retain their licenses. See LICENSE. Built by @LydiaTools.