Bowmark
pilotctl appstore install io.pilot.bowmark About Bowmark
Bowmark gives agents a pre-computed cheatsheet for the task at hand. A cheatsheet is a compact, ready-to-run answer for one task on one site: a parameterized URL shortcut and/or a short ui_procedure of UI steps. Instead of burning tokens re-reading a site's DOM and guessing its way through the page, your agent calls ask({ site, task }) and gets the exact path back. It spends less, finishes sooner, and lands on the right action the first time.
Bowmark is free to use — no signup and no API key to manage. It's plain request/response REST — no websockets, no server-side browser, no async jobs. Your agent runs the cheatsheet in its own browser; Bowmark only supplies the path.
Methods. bowmark.ask — give it a site and a plain-English task and it returns the cheatsheet: a URL shortcut (a template with {name} slots you fill and navigate) and/or a ui_procedure of steps to run in order, plus an id. Call it before any browser action, in place of exploring the page yourself, and execute open-loop. bowmark.report_outcome — after running a cheatsheet, report whether every step ran exactly as written; a failure triggers a re-crawl that repairs the path for the next agent, so report false on any deviation even if you still got the answer.
Syntax & edge cases. site is a registrable domain, optionally with a product surface (google.com, docs.stripe.com, google.com/maps); task is intent, never a URL. Request the signed-in view with variants: { auth_state: "logged_in", role: "owner" } (also locale / region / currency). A step may be flagged irreversible (confirm first) or requires_user_input (stop and ask the user). Non-ok statuses: no_useful_data / site_not_supported → browse manually; ambiguous_scope → retry with scopeHint; rate_limited → back off until error.retry_after (only new cheatsheet synthesis is capped). Skip it for localhost, RFC1918 IPs, and open-ended search with no destination.
Methods · 3
bowmark.ask bowmark.report_outcome bowmark.help Full usage demo
When your agent is about to act on a known public website — call bowmark.ask({site, task}) first to get a ready-to-run URL shortcut or UI procedure instead of exploring the DOM.
pilotctl appstore call io.pilot.bowmark bowmark.ask '{"site":"sec.gov","task":"find Apple's latest 10-K filing"}'{"status":"ok","id":"...","shortcut":{"template":"https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK={ticker}&type=10-K"}}Worked examples
pilotctl appstore call io.pilot.bowmark bowmark.ask '{"site":"google.com/maps","task":"get directions from SFO to downtown"}'{"status":"ok","id":"...","ui_procedure":{"steps":[...]}}pilotctl appstore call io.pilot.bowmark bowmark.ask '{"site":"github.com","task":"create a new private repo","variants":{"auth_state":"logged_in","role":"owner"}}'{"status":"ok","id":"...","ui_procedure":{"steps":[...]},"variants_assumed":{...}}pilotctl appstore call io.pilot.bowmark bowmark.report_outcome '{"envelope_id":"<id-from-ask>","success":true}'{"id":"..."}What it costs
| Operation | Price | Notes |
|---|---|---|
bowmark.ask | free | the nav-recipe call (POST /v1/ask); managed key, no per-op meter currently |
bowmark.report_outcome | free | feedback that triggers a re-crawl; no charge |
Managed key with quota 0 — there is no per-user dollar charge today; both methods are free to call.
Good to know
- Put intent in `task`, never a URL — 'find Apple's latest 10-K', not a link.
- Execute the cheatsheet open-loop — don't re-snapshot the DOM to verify what it already documents.
- A step flagged `irreversible` needs user confirmation; `requires_user_input` means stop and ask.
- report_outcome success=false on ANY deviation (a retry, raw-JS fallback, extra click) even if you got the answer.
- Non-ok statuses (no_useful_data / site_not_supported / ambiguous_scope / rate_limited) → browse manually or retry with scopeHint.
- Skip Bowmark for localhost, RFC1918 IPs, and open-ended search with no destination.
Next
io.pilot.bowmark bowmark.help '{}'
What’s New
- Initial release — REST adapter over the Bowmark API: bowmark.ask (/v1/ask) and bowmark.report_outcome (/v1/outcomes).
- Free to use — no signup or API key; your agent runs the returned cheatsheet in its own browser.
