Browser

Browser — the authenticated-browser capability

The browser is an authenticated transport to the user's real sessions. Read data from each site's own internal API (ground truth) and use the DOM only for visuals + the few write buttons. Proven: on a hardened SPA the DOM yields ~0 useful data while an in-page API fetch returns the full structured truth.

Where each concern lives (three homes, one boundary)

• Capability = code. The social capture/search recipes are implemented in

@agstudio/browser-social (the SOCIAL_PLATFORMS adapters + createLinkedInVoyager). Drive the adapter; don't re-derive a recipe by hand.

• Operator "how/when" = corpus playbook. The durable judgement a runtime

agent carries (recon SOP, persona = four signals, person-id scoring, when-to-escalate-stealth, rate-limit + write-gating discipline) is the social-recon corpus playbook overlay, injected into the operator's prompt (projects/guilde/packages/builtins/src/knowledge/social-recon.ts; read path in apps/api/src/mastra/guilde-playbook-processors.ts). A runtime operator cannot read these dev skills — the playbook is its home for that knowledge.

• Dev-SOP = these skills. What you (building/debugging the stack) need:

transport mechanics, the chrome-devtools-mcp tool surface, proven-live gotchas, the per-platform internal-API reference (a superset of what the adapters implement — includes gated write ops). This is the dev-facing mirror.

Golden rules

1. API-first for data — find the site's internal API; the DOM is the slow,

obfuscated, anti-scraping surface. News/content sites are the exception → readability/ld+json (content IS the HTML). See reference/recon.md.

1. Fail fast — ~8 s timeouts, not 60 s. After 5-6 s it's ~90 % a hard hang.
2. Direct URL nav > clicking navigating-links (clicks that navigate hang).
3. Tab/focus discipline — list_pages before acting; re-assert

select_page({pageId, bringToFront:true}) per op under multi-agent contention.

1. Clear cookie/consent gates — CMP banners + login/paywall cookies first.
2. Gate every write — acts as the user; explicit per-action confirmation.
3. Capture cheaply — snapshot/evaluate for data; screenshot only for pixels.
4. Blocked? → stealth. On a hard anti-bot block ("Sorry, you have been

blocked" / Cloudflare / DataDome / 403-429-503), this Chrome chain won't recover — switch to the camofox-stealth MCP on agentproto: mcp_imported_call alias="camofox-stealth" toolName="scrape" (HTTP-first, auto-escalates) or stealth_snapshot. Needs the camofox server on :9377 (launchd com.agentik.camofox). See projects/browser/apps/stealth-mcp/README.md.

Reference (read what you need)

• reference/transport.md — chain, connection/health, Chrome lifecycle,

tabs/focus, timeouts, the 29-tool surface + arg gotchas.

• reference/capture.md — screenshots (full / element by uid / CSS / CDP

clip) + selective content (snapshot / evaluate querySelector / ld+json / readability).

• reference/cookies.md — cookie inspection, CMP consent, paywall/session

injection, the login gate.

• reference/recon.md — the method to find + drive a site's internal API

(the SOP-of-SOP); per-app auth tricks.

• reference/writes.md — gated write discipline + rate-limiting.

Site skills (instances built on this)

linkedin (proven, deepest) · x-twitter · youtube · instagram · tiktok · leboncoin · news-media. Each carries its internal API, auth/cookies, recipes, and capture method. Invoke the site skill for site work; it leans on this skill for the mechanics.

Quickstart

health: api 3040 · tunnel 3600 (/internal/forward→401) · daemon 18790 (/health→200)
   (else: agentproto serve --connect ws://localhost:3600/connect)
list_pages → select your tab → navigate/snapshot/evaluate → (data) in-page API fetch

Helper library (one-call primitives)

projects/guilde/apps/api/scripts/lib/browser.ts → createBrowser(): tabs() · focus(host|id) · nav · snapshot · evaluate · extract(selector) · screenshotElement(uid) · fetchJson(url, csrfCookie) · apiReqs(re) · click/fill/press · newTab/closeTab. LinkedIn layer: createLinkedInVoyager(createBrowser()) — createLinkedInVoyager from @agstudio/browser-social drives this createBrowser() port (liFetch · feed · profileActivity · profile · reactors(activityUrn) · searchContent(query) · messageDraft). searchContent = keyword post search: walks the RSC result cards (hashed DOM, no client-side URNs) then resolves real activity permalinks per /in/ author via Voyager activity; /company/ authors keep the profile URL. STEALTH-preferred equivalent: social-scrape.mts content linkedin "" (camofox, distinct session + WhatsApp re-auth alert). See the linkedin skill. Ad-hoc CLI: tsx scripts/browse.ts . Prefer these over ad-hoc scripts. (Validated: tabs + extract live.)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agentproto
• Source: agentproto/ts
• License: Apache-2.0
• Homepage: https://agentproto.sh

Install and usage instructions live in the source repository linked above.