Pup - the AI's own browser

Make pup behave like the human-directed session it actually is (bot-wall roadmap)

Context (John, 2026-08-20): chip-fetcher crawls many vendor sites through pup. A pup session runs on the user's own machine, in their own profile, at their explicit direction — there is a real human on the other end of every request. So when a wall scores us as a bot, that is usually a false positive we earned, and the fix is to stop earning it rather than to defeat the detector.

Today's trigger, measured: mouser.com served a DataDome challenge (ct.captcha-delivery.com, var dd={…,'t':'fe'}) while ti.com and digikey.com loaded fine from the same browser, same profile, same minute. pup's identity was already correct — Chrome/148 UA, navigator.webdriver:false, Sec-CH-UA brands "Google Chrome"/"Chromium" — so this was not a user-agent problem. The likely cause was our own access pattern: mouser.com opened twice in ~15 min while three distributor sites were opened simultaneously from one IP.

Doctrine and detail now live in dev-skills/pup-bot-walls. This issue tracks the build items.

Roadmap

• 1. Detect and REPORT a wall instead of returning a blank page. Add botWall {vendor, challenged, url} + an errorCode + an _hint that says stop retrying and hand off. Highest value: today a challenged page returns ok:true with an empty body, so callers retry blindly — the exact wrong reflex, which escalates a soft challenge into a hard block.
• 2. pup_request_human {sessionId, reason} — a first-class handoff: raise-or-flash, tell the user what is needed, poll until real content appears, return how long it waited.
• 3. A politeness engine, per domain — concurrency 1, jittered delays, exponential backoff on challenge, hard requests/minute cap. Route chip-fetcher's whole ladder through it. This addresses the actual measured cause.
• 4. Warm-profile discipline for crawls — always reuse the durable profile so DataDome clearance cookies and history accumulate. One human solve then buys a long quiet period. A cold isolated profile per fetch looks far more like a bot than a browser a person has used for months.
• 5. Real input for click-throughs — CDP Input.dispatchMouseEvent with move → hover → click rather than instant synthetic clicks at exact coordinates. Reuse the isTrusted input shape already built for nb.
• 6. Per-domain wall registry — record which wall each domain runs and the preferred rail (API / nb / pup+handoff), so the sourcing ladder is data rather than folklore.
• 7. Investigate CDP observability honestly — establish whether DataDome-class walls detect CDP attachment, and whether there is a SUPPORTED way to reduce that signal. If the only answer is fingerprint spoofing, write that down and stop: an arms race we re-lose on every vendor update is worse than a clean handoff.

Explicitly out of scope

Solving CAPTCHAs on the user's behalf. A CAPTCHA asks "is a person there?" and in Adom the honest answer is yes, and here they are — pup is headful and on-screen precisely so the user can click it. Also out of scope: forging canvas/WebGL/audio fingerprints.

Rule of thumb for anything built here

Use the front door when the vendor offers one. Mouser and DigiKey both have real APIs that Adom already wraps (adom-mouser, adom-digikey, adom-parts-search), so search, pricing, stock and part lookup must never go through a pup crawl — only the things an API cannot serve (CAD bundles, gated downloads) belong in pup.