Pup - the AI's own browser - docs/contract/pup_navigate.json

by adom

pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.

Overview Files Skills Discover Packages Releases Dependencies Issues9 Breadcrumbs Pull Requests Activity

master

History Download

John Lauer docs/contract: golden fixtures recorded from the Node build 2.0.399 for the Rust port 71c0e87 1mo ago

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

{
  "_hint": "Drives the active tab to url and waits for load. Verify with a screenshot before asserting success.",
  "_next": [
    "pup_screenshot {} — screenshot YOUR window (no ids: pup resolves your --ai-thread name to your window)",
    "pup_reload {} — reload it (e.g. after you publish or rebuild something it shows)",
    "pup_my_windows {} — full state of everything your thread owns: windows, tabs, urls, titles",
    "pup_open_window {\"url\":\"...\"} — another page = another TAB in your same window",
    "pup_raise_os_window {\"foregroundReason\":\"...\"} — bring it onto the user's screen (gated)",
    "Windows open MAXIMIZED already. NEVER hunt hwnds (desktop_find_window / desktop_set_window_state) for a pup window — pup verbs already know your window.",
    "pup_screenshot {} captures the PAGE (CDP, pixel-perfect, works in background — the shot you want 99% of the time). Only when you need the browser CHROME in frame (tab strip, toolbar icons): pup_window_info {} hands you this window's hwnd for desktop_screenshot_window — no searching, ever."
  ],
  "_verifyRender": "VERIFY WHAT YOU JUST PUT ON SCREEN — do not assume it rendered. ok:true means the NAVIGATION succeeded; it says NOTHING about whether the page actually painted. Take a screenshot and READ the image: `adom-bridge-cli --ai-thread \"<your thread>\" pup_screenshot {\"sessionId\":\"contract-fx\"}` — it returns a real PNG path you can open. Look for: a blank or white page, an unstyled flash of plain HTML (CSS never loaded), a stack trace or framework error overlay, missing images, a broken or overlapping layout, content cut off past the fold, a dev-server \"Cannot GET /\" page, or the wrong build entirely. If it is wrong: fix the source, `pup_reload`, and screenshot AGAIN — ralph-test that loop until the render is genuinely correct, rather than reporting success after one open. If the viewport is too small to judge, pup_set_viewport first; for a long page use pup_screenshot {fullPage:true}. Showing the user a screenshot of their own working app is also the fastest way to prove it works.",
  "aiThread": "pup-bridge",
  "durationMs": 235,
  "ok": true,
  "pitfalls": [
    "navigation can race SPA routing — confirm with pup_screenshot",
    "some sites need pup_wait for a selector after navigate"
  ],
  "related": [
    "pup_screenshot",
    "pup_wait",
    "pup_reload"
  ],
  "renderCheck": {
    "bodyChars": 129,
    "elements": 5,
    "httpStatus": 200,
    "ok": true,
    "signals": [],
    "title": "Example Domain"
  },
  "sessionId": "contract-fx",
  "status": "ok",
  "tabId": "tab-1",
  "url": "https://example.com/?nav=1",
  "window": "contract-fx"
}