@framers/agentos-ext-stealth-browser 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,127 @@
+# Stealth browser
+
+This pack gives an agent browser navigation, scraping, clicking, typing, screenshot and DOM snapshot tools. It uses `puppeteer-extra`, `puppeteer-extra-plugin-stealth`, `puppeteer-core` and `cheerio` with a local Chrome executable.
+
+## Installation
+
+```bash
+npm install @framers/agentos-ext-stealth-browser
+```
+
+Peer dependency: `@framers/agentos` with range `>=0.10.40`.
+
+## Usage
+
+```ts
+import { AgentOS } from '@framers/agentos';
+
+const agentos = await AgentOS.create({
+  extensionManifest: {
+    packs: [
+      {
+        package: '@framers/agentos-ext-stealth-browser',
+        options: {
+          headless: true,
+          timeout: 30000,
+          viewport: { width: 1920, height: 1080 },
+        },
+      },
+    ],
+  },
+});
+```
+
+## Configuration
+
+| Option | Secret id | Environment variable | Required | Default |
+| --- | --- | --- | --- | --- |
+| `headless` | None | None | no | Unset through factory; launches headed |
+| `timeout` | None | None | no | Unset through factory; passed to Puppeteer |
+| `userAgent` | None | None | no | Random selection from the built-in pool |
+| `viewport` (object with `width` and `height`) | None | None | no | Unset through factory; no viewport override |
+| `executablePath` | None | None | no | OS-specific Chrome path |
+| `enableEvasions` | None | None | no | Enabled unless `false` |
+| `priority` | None | None | no | `50`; a falsy value also uses this default |
+| Context `logger` | None | None | no | Unset |
+| Context `onActivate` | None | None | no | Unset |
+| Context `onDeactivate` | None | None | no | Unset |
+
+Set `headless`, `timeout` and `viewport` explicitly to use the values in the example. The factory passes undefined properties that overwrite the service constructor's defaults. Use these flat option names rather than the manifest's dotted configuration names.
+
+`logger.info` receives lifecycle messages. The context callbacks run on activation and deactivation; deactivation closes the browser before invoking the callback.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `stealth_navigate` | Navigates with anti-detection enabled and returns page text, links and optional HTML. |
+| `stealth_scrape` | Extracts content from the current page using a CSS selector. |
+| `stealth_click` | Waits for an element to become visible and clicks it. |
+| `stealth_type` | Types into an input field with a default keystroke delay. |
+| `stealth_screenshot` | Captures the current page or a selected element. |
+| `stealth_snapshot` | Returns a DOM snapshot of interactive elements, links and forms. |
+
+### `stealth_navigate`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `url` | string | yes | The URL to navigate to |
+| `waitFor` | string, enum: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`; default: `networkidle2` | no | When to consider navigation complete |
+| `returnHtml` | boolean, default `false` | no | Include full HTML in response |
+| `returnText` | boolean, default `true` | no | Include extracted text in response |
+| `returnLinks` | boolean, default `true` | no | Include all links found on the page (text + href) |
+| `maxTextLength` | number, default `50000` | no | Maximum characters of page text to return (default `50000`) |
+
+### `stealth_scrape`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `selector` | string | yes | CSS selector to match elements |
+| `limit` | number, minimum one | no | Maximum number of elements to return |
+| `attributes` | array of strings | no | Specific attributes to extract |
+
+### `stealth_click`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `selector` | string | yes | CSS selector for the element to click |
+| `waitForNavigation` | boolean, default `false` | no | Wait for page navigation after click |
+
+### `stealth_type`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `selector` | string | yes | CSS selector for the input element |
+| `text` | string | yes | Text to type |
+| `delay` | number, default `50` | no | Delay between keystrokes (ms). Defaults to `50` for human-like typing. |
+| `clear` | boolean, default `false` | no | Clear existing text before typing |
+
+### `stealth_screenshot`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fullPage` | boolean, default `false` | no | Capture full scrollable page |
+| `selector` | string | no | CSS selector for specific element to capture |
+| `format` | string, enum: `png`, `jpeg`, `webp`; default: `png` | no | Image format |
+| `quality` | number, minimum zero, maximum `100`, default `80` | no | Quality for jpeg/webp (`0` to `100`) |
+
+### `stealth_snapshot`
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `includeLinks` | boolean, default `true` | no | Include links in snapshot |
+| `includeForms` | boolean, default `true` | no | Include forms in snapshot |
+
+## Notes
+
+The browser launches lazily when a tool first uses it and remains shared across the pack's tools until deactivation. The default executable paths are `C:\Program Files\Google\Chrome\Application\chrome.exe` on Windows, `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` on macOS and `/usr/bin/google-chrome` on Linux. Set `executablePath` for another location.
+
+Clicking and typing change the page and can trigger its actions. Launch flags disable the browser sandbox and web security and allow insecure content. `enableEvasions: false` skips applying the stealth plugin for that service, but the service still applies launch flags, HTTP headers and page-level overrides.
+
+Navigation failures return partial content with a zero status and an error console message; the navigation tool still returns `success: true` for that result. Scrape failures return an empty element list. Click and type failures return `success: false`.
+
+Navigation text is truncated to `maxTextLength`, with truncation metadata. The service retains at most `100` console messages. Screenshots return base64 image data; reported dimensions come from the viewport. A zero screenshot `quality` falls back to `80`.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  *
  * @module @framers/agentos-ext-stealth-browser
  * @version 1.0.0
- * @license MIT
+ * @license Apache-2.0
  */
 import { StealthNavigateTool } from './tools/navigate.js';
 import { StealthScrapeTool } from './tools/scrape.js';

package/dist/index.js

@@ -16,7 +16,7 @@
  *
  * @module @framers/agentos-ext-stealth-browser
  * @version 1.0.0
- * @license MIT
+ * @license Apache-2.0
  */
 import { StealthBrowserService } from './StealthBrowserService.js';
 import { StealthNavigateTool } from './tools/navigate.js';

package/manifest.json

@@ -2,16 +2,16 @@
   "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
   "id": "com.framers.research.stealth-browser",
   "name": "Stealth Browser Extension",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Stealth browser automation with anti-detection — bypasses bot protection on sites like Amazon, eBay, LinkedIn using puppeteer-extra with stealth plugin",
   "author": {
     "name": "Frame.dev",
     "email": "support@frame.dev",
     "url": "https://github.com/framerslab"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "keywords": ["browser", "stealth", "anti-detection", "scraping", "puppeteer-extra", "bot-bypass", "automation"],
-  "agentosVersion": "^2.0.0",
+  "agentosVersion": ">=0.10.40",
   "categories": ["productivity", "research", "automation"],
   "repository": {
     "type": "git",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos-ext-stealth-browser",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Stealth browser extension — puppeteer-extra with anti-detection for bot-protected sites",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,7 +38,7 @@
       "url": "https://github.com/jddunn"
     }
   ],
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/framerslab/agentos-extensions.git",
@@ -54,7 +54,7 @@
     "cheerio": "^1.0.0-rc.12"
   },
   "devDependencies": {
-    "@framers/agentos": "^0.10.40",
+    "@framers/agentos": "^0.13.47",
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0",
     "vitest": "^3.2.7"