{"_id":"@cogitator-ai/browser","_rev":"4-ff865e8bb396e8c2361875858ed8d855","name":"@cogitator-ai/browser","dist-tags":{"latest":"0.1.6"},"versions":{"0.1.2":{"name":"@cogitator-ai/browser","version":"0.1.2","license":"MIT","_id":"@cogitator-ai/browser@0.1.2","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"f9ee1c00be032838e8607748fa744cecfaae84fa","tarball":"https://registry.npmjs.org/@cogitator-ai/browser/-/browser-0.1.2.tgz","fileCount":106,"integrity":"sha512-uflie2KayoEfzPmiPjI83S0ZMj4SZ9Hlb2V8UCie8wihHUDJQuy8t6N7JDh/hXDATo8ZzjVAIA550/QcFu368w==","signatures":[{"sig":"MEYCIQDBIXkDTP31GgXeea8FExPhmyUofpBqFZ6aM/2VcDnsGAIhAPFsfpuNIhPZsyeQMLuxwQXzN3HpDIjxWIWb4HK2bB69","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":493728},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"065f1c25fc4837fbf561a31bd7bfec864705b249","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/browser"},"_npmVersion":"10.9.0","description":"Browser automation tools for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","playwright":"^1.50.0","@cogitator-ai/core":"workspace:*","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/browser_0.1.2_1772552508122_0.26276940443116525","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@cogitator-ai/browser","version":"0.1.4","license":"MIT","_id":"@cogitator-ai/browser@0.1.4","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"3eae898d2963064070630c62234a3e72246e079f","tarball":"https://registry.npmjs.org/@cogitator-ai/browser/-/browser-0.1.4.tgz","fileCount":106,"integrity":"sha512-uOlMrmg03IAJRz1S1BbQanzQBGizJ0sj0ULp4NxfUCKPKSUBP+ltMu4lTXL9JI67CowyDl6SEjTG47wwGZmZ7Q==","signatures":[{"sig":"MEYCIQDq9gGhfWuY8VKM6dpZGFDzil7eS7WJq/W2Uxd3SgqOWwIhAMdGYWvZIgvHSWgDIVAO4JXjKy4ydtZ5ZJLasAHbIWlh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":493728},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"33b6a8cb29bfdd7d2255acfa240b2df5d558354e","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/browser"},"_npmVersion":"10.9.0","description":"Browser automation tools for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","playwright":"^1.50.0","@cogitator-ai/core":"workspace:*","@cogitator-ai/types":"workspace:*"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/browser_0.1.4_1778881297491_0.12029452218173575","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@cogitator-ai/browser","version":"0.1.5","license":"MIT","_id":"@cogitator-ai/browser@0.1.5","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"dist":{"shasum":"22a96c6cc7070b3afde307298396b81929a0ec11","tarball":"https://registry.npmjs.org/@cogitator-ai/browser/-/browser-0.1.5.tgz","fileCount":107,"integrity":"sha512-rYoBHQJipWb3SHHHar/gfSNCvS7FGDb6EyRFMwbcTR56uJ1XF3xSf+oRu3DqWP6kUH6hUi7YeLa6wWcOxQOD4Q==","signatures":[{"sig":"MEYCIQDlfMbc4lcoc2j5z85fw3PKy1hkr+Mj0z1Q50IcPcPy4wIhAJmq67yxkY5ELaXk4+fwq8CQIr6cGh6YHtwuNlGQFVc8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":494796},"main":"./dist/index.js","type":"module","_from":"file:cogitator-ai-browser-0.1.5.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"_resolved":"/private/var/folders/20/4d95hdvj45j337gtqpbx3v1m0000gn/T/c7abfbe5194d874b27549f2044e39b12/cogitator-ai-browser-0.1.5.tgz","_integrity":"sha512-rYoBHQJipWb3SHHHar/gfSNCvS7FGDb6EyRFMwbcTR56uJ1XF3xSf+oRu3DqWP6kUH6hUi7YeLa6wWcOxQOD4Q==","repository":{"url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","type":"git","directory":"packages/browser"},"_npmVersion":"10.9.0","description":"Browser automation tools for Cogitator AI agents","directories":{},"_nodeVersion":"22.11.0","dependencies":{"zod":"^4.3.6","playwright":"^1.50.0","@cogitator-ai/core":"0.19.3","@cogitator-ai/types":"0.22.2"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.18","typescript":"^5.3.0"},"_npmOperationalInternal":{"tmp":"tmp/browser_0.1.5_1778882229016_0.016336906050444577","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@cogitator-ai/browser","version":"0.1.6","description":"Browser automation tools for Cogitator AI agents","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"playwright":"^1.50.0","zod":"^4.3.6","@cogitator-ai/core":"0.19.4","@cogitator-ai/types":"0.22.3"},"devDependencies":{"typescript":"^5.3.0","vitest":"^4.0.18"},"repository":{"type":"git","url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","directory":"packages/browser"},"publishConfig":{"access":"public","registry":"https://npm.pkg.github.com"},"license":"MIT","scripts":{"build":"tsc","dev":"tsc --watch","clean":"rm -rf dist","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest"},"_id":"@cogitator-ai/browser@0.1.6","bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","_integrity":"sha512-t9B1GeteEBebE8VFoKvM3P6W3Td8SK8guZqJMvqjLNNPQAUuWr6q7AVxEl2YVaNjv9LVV33pvSCXudYhZfTgDA==","_resolved":"/private/var/folders/20/4d95hdvj45j337gtqpbx3v1m0000gn/T/86a33ed6cdbae209227ad7198fc7881e/cogitator-ai-browser-0.1.6.tgz","_from":"file:cogitator-ai-browser-0.1.6.tgz","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-t9B1GeteEBebE8VFoKvM3P6W3Td8SK8guZqJMvqjLNNPQAUuWr6q7AVxEl2YVaNjv9LVV33pvSCXudYhZfTgDA==","shasum":"fa954a6a89c8c62a6b0826ab86da7c5482124cb3","tarball":"https://registry.npmjs.org/@cogitator-ai/browser/-/browser-0.1.6.tgz","fileCount":107,"unpackedSize":515476,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDvJJ/IwPk7kF9Asbsg1IQn3SSQ2CglOZroE2OWy3nt4QIgD+ey6CqloAQ99DIUAeyN64ZnDeEr4YVVjUK8nA6hM7g="}]},"_npmUser":{"name":"el1fe","email":"piuro.pavel@gmail.com"},"directories":{},"maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser_0.1.6_1785059631515_0.8198420107545503"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-03T15:41:48.012Z","modified":"2026-07-26T09:53:51.809Z","0.1.2":"2026-03-03T15:41:48.489Z","0.1.4":"2026-05-15T21:41:37.676Z","0.1.5":"2026-05-15T21:57:09.206Z","0.1.6":"2026-07-26T09:53:51.657Z"},"bugs":{"url":"https://github.com/cogitator-ai/Cogitator-AI/issues"},"license":"MIT","homepage":"https://github.com/cogitator-ai/Cogitator-AI#readme","repository":{"type":"git","url":"git+https://github.com/cogitator-ai/Cogitator-AI.git","directory":"packages/browser"},"description":"Browser automation tools for Cogitator AI agents","maintainers":[{"name":"el1fe","email":"piuro.pavel@gmail.com"}],"readme":"# @cogitator-ai/browser\n\nBrowser automation tools for Cogitator AI agents. Playwright-based with 32 tools across 5 modules, vision mode, stealth system, structured data extraction, and network control.\n\n## Features\n\n- **32 Browser Tools** across 5 modules (navigation, interaction, extraction, vision, network)\n- **BrowserSession** -- managed browser lifecycle with tabs, cookies, proxy\n- **Stealth Mode** -- fingerprint evasion, human-like typing/mouse, UA rotation\n- **Vision Mode** -- screenshot + accessibility tree for vision LLM navigation\n- **Smart Extraction** -- tables, structured data, links, clean text\n- **Network Control** -- request interception, HAR capture, resource blocking, API monitoring\n- **Playwright-powered** -- Chromium, Firefox, WebKit support\n\n## Installation\n\n```bash\npnpm add @cogitator-ai/browser playwright\n```\n\n## Quick Start\n\n```typescript\nimport { BrowserSession, browserTools } from '@cogitator-ai/browser';\nimport { Agent, Cogitator } from '@cogitator-ai/core';\n\nconst session = new BrowserSession({ headless: true });\nawait session.start();\n\nconst agent = new Agent({\n  name: 'web-researcher',\n  model: 'gpt-4o',\n  instructions: 'You browse the web and extract information.',\n  tools: browserTools(session),\n});\n\nconst cog = new Cogitator({ llm: { defaultProvider: 'openai' } });\nconst result = await cog.run(agent, {\n  input: 'Go to https://news.ycombinator.com and get the top 5 story titles',\n});\n\nconsole.log(result.output);\nawait session.close();\n```\n\n## Tool Modules\n\n### Navigation (7 tools)\n\n| Tool                          | Description                                                  |\n| ----------------------------- | ------------------------------------------------------------ |\n| `browser_navigate`            | Navigate to a URL. Returns final URL, title, and HTTP status |\n| `browser_go_back`             | Go back in browser history                                   |\n| `browser_go_forward`          | Go forward in browser history                                |\n| `browser_reload`              | Reload the current page                                      |\n| `browser_wait_for_navigation` | Wait for navigation to a URL matching a pattern              |\n| `browser_get_current_url`     | Get current page URL and title                               |\n| `browser_wait_for_selector`   | Wait for a CSS selector to appear on the page                |\n\n### Interaction (9 tools)\n\n| Tool                    | Description                                                                       |\n| ----------------------- | --------------------------------------------------------------------------------- |\n| `browser_click`         | Click an element by CSS selector. Supports button, clickCount, position           |\n| `browser_type`          | Type text into an input. Stealth mode adds human-like keystroke delays            |\n| `browser_select_option` | Select from a `<select>` element by value, label, or index                        |\n| `browser_hover`         | Hover over an element                                                             |\n| `browser_scroll`        | Scroll the page or a specific element in any direction                            |\n| `browser_press_key`     | Press a keyboard key with optional modifier keys                                  |\n| `browser_drag_and_drop` | Drag an element onto another element                                              |\n| `browser_fill_form`     | Smart form filler -- finds inputs by name, placeholder, aria-label, or label text |\n| `browser_upload_file`   | Upload files to a file input element                                              |\n\n### Extraction (7 tools)\n\n| Tool                         | Description                                                        |\n| ---------------------------- | ------------------------------------------------------------------ |\n| `browser_get_text`           | Extract text from the page or a specific element                   |\n| `browser_get_html`           | Get inner or outer HTML of the page or an element                  |\n| `browser_get_attribute`      | Get the value of a DOM attribute                                   |\n| `browser_get_links`          | Extract all links with text, href, and title                       |\n| `browser_query_selector_all` | Query all matching elements with tag, text, attributes, visibility |\n| `browser_extract_table`      | Extract structured data from HTML tables (headers + rows)          |\n| `browser_extract_structured` | Extract clean readable text, stripping scripts/styles/SVG          |\n\n### Vision (4 tools)\n\n| Tool                           | Description                                                                             |\n| ------------------------------ | --------------------------------------------------------------------------------------- |\n| `browser_screenshot`           | Screenshot the page or element. Returns base64 PNG/JPEG                                 |\n| `browser_screenshot_element`   | Screenshot a specific element with bounding box coordinates                             |\n| `browser_find_by_description`  | Find elements by natural language using the accessibility tree                          |\n| `browser_click_by_description` | Click an element by natural language description (tries role, text, label, placeholder) |\n\n### Network (5 tools)\n\n| Tool                        | Description                                                          |\n| --------------------------- | -------------------------------------------------------------------- |\n| `browser_intercept_request` | Intercept HTTP requests -- block, modify, or continue by URL pattern |\n| `browser_wait_for_response` | Wait for an HTTP response matching a URL pattern                     |\n| `browser_block_resources`   | Block resource types (image, stylesheet, font, media, script)        |\n| `browser_capture_har`       | Start/stop HAR traffic capture. Returns all captured entries on stop |\n| `browser_get_api_calls`     | Get captured XHR/fetch calls, filtered by URL pattern or method      |\n\n## Stealth Mode\n\nStealth mode makes the browser harder to detect as automated. It applies evasion scripts on context creation and enables human-like input simulation.\n\n```typescript\nconst session = new BrowserSession({\n  stealth: true, // enable all defaults\n});\n\n// or configure individually\nconst session = new BrowserSession({\n  stealth: {\n    humanLikeTyping: true, // random delays between keystrokes (50-150ms)\n    humanLikeMouse: true, // bezier curve mouse movement\n    fingerprintRandomization: true, // canvas/WebGL/plugin spoofing\n    blockWebDriver: true, // navigator.webdriver = false\n    evasionScripts: [], // custom init scripts to inject\n  },\n});\n```\n\nWhat stealth mode does:\n\n- Sets `navigator.webdriver` to `false`\n- Spoofs `navigator.plugins` with realistic Chrome plugins\n- Sets `navigator.languages` to `['en-US', 'en']`\n- Randomizes canvas fingerprint (1-bit pixel noise)\n- Spoofs WebGL vendor/renderer (Intel Iris)\n- Injects `window.chrome` runtime stubs\n- Overrides `Permissions.query` for notifications\n- Rotates User-Agent strings per browser type\n- Adds human-like typing delays (50-150ms per character)\n- Uses bezier curve mouse movement for clicks\n\n## Vision Mode\n\nVision tools let agents interact with pages using natural language instead of CSS selectors:\n\n```typescript\nimport { BrowserSession, browserTools } from '@cogitator-ai/browser';\n\nconst session = new BrowserSession();\nawait session.start();\n\nconst tools = browserTools(session, { modules: ['navigation', 'vision'] });\n\n// Agent can now use:\n// browser_screenshot -- take a screenshot for visual analysis\n// browser_find_by_description -- \"find the login button\"\n// browser_click_by_description -- \"click the Submit button\"\n```\n\n`browser_find_by_description` walks the accessibility tree and matches elements by role and name against the description. `browser_click_by_description` tries multiple strategies: role button, role link, text content, label, and placeholder.\n\n## Network Control\n\n```typescript\nimport { BrowserSession, createNavigationTools, createNetworkTools } from '@cogitator-ai/browser';\n\nconst session = new BrowserSession();\nawait session.start();\n\nconst tools = [...createNavigationTools(session), ...createNetworkTools(session)];\n\n// Agent can intercept requests:\n// browser_intercept_request({ urlPattern: \"**/ads/**\", action: \"block\" })\n\n// Block resource types to speed up loading:\n// browser_block_resources({ types: [\"image\", \"font\", \"stylesheet\"] })\n\n// Monitor API calls made by the page:\n// browser_get_api_calls({ urlPattern: \"/api/\", method: \"POST\" })\n\n// Capture HAR traffic:\n// browser_capture_har({ action: \"start\" })\n// ... navigate and interact ...\n// browser_capture_har({ action: \"stop\", path: \"./traffic.har\" })\n```\n\n## BrowserSession API\n\n### Constructor\n\n```typescript\nconst session = new BrowserSession(config?: BrowserSessionConfig);\n```\n\n### BrowserSessionConfig\n\n```typescript\ninterface BrowserSessionConfig {\n  headless?: boolean; // default: true\n  browser?: 'chromium' | 'firefox' | 'webkit'; // default: 'chromium'\n  stealth?: boolean | StealthConfig; // enable stealth mode\n  proxy?: string | ProxyConfig; // proxy server\n  viewport?: { width: number; height: number }; // default: 1280x720\n  userAgent?: string; // custom UA (stealth rotates automatically)\n  locale?: string; // browser locale (e.g., 'en-US')\n  timezone?: string; // timezone ID (e.g., 'America/New_York')\n  geolocation?: { latitude: number; longitude: number };\n  cookies?: BrowserCookie[]; // pre-load cookies\n  timeout?: number; // navigation timeout, default: 30000ms\n  actionTimeout?: number; // action timeout, default: 10000ms\n}\n```\n\n### Lifecycle\n\n```typescript\nawait session.start(); // launch browser, create context and first page\nawait session.close(); // close browser and cleanup\n```\n\n### Properties\n\n```typescript\nsession.page; // active Playwright Page\nsession.tabs; // all open Page[]\nsession.browser; // Playwright Browser instance\nsession.context; // Playwright BrowserContext\nsession.config; // current config\nsession.stealthEnabled; // whether stealth is on\nsession.stealthConfig; // resolved StealthConfig or null\n```\n\n### Tab Management\n\n```typescript\nconst page = await session.newTab('https://example.com'); // open new tab\nsession.switchTab(1); // switch to tab by index\nawait session.closeTab(0); // close tab by index\n```\n\n### Cookie Management\n\n```typescript\nconst cookies = await session.getCookies();\nawait session.setCookies([{ name: 'token', value: 'abc', domain: '.example.com' }]);\nawait session.saveCookies('./cookies.json');\nawait session.loadCookies('./cookies.json');\n```\n\n## Module Selection\n\nLoad only the tool modules you need:\n\n```typescript\n// all 32 tools\nconst tools = browserTools(session);\n\n// only navigation + extraction (14 tools)\nconst tools = browserTools(session, {\n  modules: ['navigation', 'extraction'],\n});\n\n// or use individual factory functions\nimport {\n  createNavigationTools,\n  createExtractionTools,\n  createScreenshotTool,\n} from '@cogitator-ai/browser';\n\nconst tools = [\n  ...createNavigationTools(session),\n  ...createExtractionTools(session),\n  createScreenshotTool(session),\n];\n```\n\nAvailable modules: `navigation`, `interaction`, `extraction`, `vision`, `network`.\n\n## Utility Helpers\n\nStandalone helpers for advanced use cases:\n\n```typescript\nimport {\n  smartSelect,\n  findFormField,\n  getReadableText,\n  getAccessibilityTree,\n  elementToInfo,\n} from '@cogitator-ai/browser';\n\n// smartSelect tries CSS, XPath, then text matching\nconst locator = await smartSelect(page, 'Submit');\n\n// findFormField tries name, placeholder, aria-label, label text\nconst input = await findFormField(page, 'Email');\n\n// getReadableText strips scripts/styles and returns clean text\nconst text = await getReadableText(page);\n\n// getAccessibilityTree returns simplified a11y tree\nconst tree = await getAccessibilityTree(page);\n```\n\n## Stealth Standalone Functions\n\nUse stealth primitives directly outside of BrowserSession:\n\n```typescript\nimport {\n  humanLikeType,\n  humanLikeClick,\n  humanLikeScroll,\n  getRandomUserAgent,\n  getAllUserAgents,\n  getEvasionScripts,\n  applyStealthToContext,\n  getStealthLaunchOptions,\n} from '@cogitator-ai/browser';\n\n// human-like input on any Playwright page\nawait humanLikeType(page, '#search', 'cogitator ai');\nawait humanLikeClick(page, '.submit-btn');\nawait humanLikeScroll(page, 'down', 500);\n\n// get a random UA for a browser type\nconst ua = getRandomUserAgent('chromium');\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}