@akshayram1/omnibrowser-agent 0.2.29 → 0.2.32

package/README.npm.md

@@ -0,0 +1,220 @@
+# omnibrowser-agent
+
+[![npm](https://img.shields.io/npm/v/@akshayram1/omnibrowser-agent)](https://www.npmjs.com/package/@akshayram1/omnibrowser-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Local-first browser AI operator. Plans and executes DOM actions entirely in the browser — no API keys, no cloud costs, no data leaving your machine.
+
+[Live Demo](https://omnibrowser-agent.vercel.app/examples/chatbot/) · [GitHub](https://github.com/akshayram1/omnibrowser-agent) · [Embedding Guide](https://github.com/akshayram1/omnibrowser-agent/blob/main/docs/EMBEDDING.md) · [Roadmap](https://github.com/akshayram1/omnibrowser-agent/blob/main/docs/ROADMAP.md)
+
+---
+
+## Architecture
+
+```
+  Chrome Extension          npm Library
+  (popup + bg worker)       createBrowserAgent()
+         |                        |
+         +----------+-------------+
+                    |
+             Orchestration
+          (session & tick loop)
+                    |
+         +----------+----------+
+         |          |          |
+     observer   planner    executor
+    (DOM snap) (heuristic  (click/type/
+               /webllm)    navigate...)
+         |          |          |
+         +----------+----------+
+                    |
+                 safety
+           (safe/review/blocked)
+```
+
+### One tick
+
+```
+goal + history + memory
+        |
+        v
+observer.collectSnapshot()  -->  PageSnapshot (url, title, candidates[])
+        |
+        v
+planner.planNextAction()    -->  PlannerResult { action, evaluation?, memory?, nextGoal? }
+        |
+        v
+safety.assessRisk(action)   -->  safe | review | blocked
+        |
+   blocked --> stop
+   review  --> pause (human-approved) --> user calls resume()
+   safe    --> executor.executeAction()
+        |
+        v
+   session.history.push(result) --> next tick
+```
+
+---
+
+## Install
+
+```bash
+npm install @akshayram1/omnibrowser-agent
+```
+
+---
+
+## Quick start
+
+```ts
+import { createBrowserAgent } from "@akshayram1/omnibrowser-agent";
+
+const agent = createBrowserAgent({
+  goal: "Search for contact Jane Doe and open her profile",
+  mode: "human-approved",        // or "autonomous"
+  planner: { kind: "heuristic" } // or "webllm"
+}, {
+  onStep:             (result, session) => console.log(result.message),
+  onApprovalRequired: (action, session) => console.log("Review:", action),
+  onDone:             (result, session) => console.log("Done:", result.message),
+  onError:            (err,    session) => console.error(err),
+  onMaxStepsReached:  (session)         => console.log("Max steps hit"),
+});
+
+await agent.start();
+
+// After onApprovalRequired fires:
+await agent.resume();
+
+// Cancel at any time:
+agent.stop();
+```
+
+---
+
+## Planner modes
+
+| Mode        | Description                                         | When to use                                   |
+|-------------|-----------------------------------------------------|-----------------------------------------------|
+| `heuristic` | Zero-dependency regex planner. Works fully offline. | Simple, predictable goals — navigate, fill, click |
+| `webllm`    | On-device LLM via WebGPU. Fully private, no API calls. | Open-ended, multi-step, language-heavy goals |
+
+### WebLLM with a custom system prompt
+
+```ts
+const agent = createBrowserAgent({
+  goal: "Fill the checkout form",
+  planner: {
+    kind: "webllm",
+    systemPrompt: "You are a careful checkout assistant. Never submit before all required fields are filled."
+  }
+});
+```
+
+### Recommended WebLLM models
+
+| Model ID | Size | Notes |
+|----------|------|-------|
+| `Llama-3.2-1B-Instruct-q4f16_1-MLC` | ~600 MB | fastest |
+| `Llama-3.2-3B-Instruct-q4f16_1-MLC` | ~1.5 GB | fast |
+| `Phi-3.5-mini-instruct-q4f16_1-MLC` | ~2 GB | quality |
+| `Mistral-7B-Instruct-v0.3-q4f16_1-MLC` | ~4.1 GB | balanced |
+| `Qwen2.5-7B-Instruct-q4f16_1-MLC` | ~4.3 GB | strong |
+| `Llama-3.1-8B-Instruct-q4f16_1-MLC` | ~4.8 GB | strong |
+| `Qwen3-8B-q4f16_1-MLC` | ~5 GB | latest Qwen |
+| `gemma-2-9b-it-q4f16_1-MLC` | ~5.5 GB | Google Gemma |
+| `DeepSeek-R1-Distill-Llama-8B-q4f16_1-MLC` | ~5 GB | reasoning |
+| `Llama-3.1-70B-Instruct-q3f16_1-MLC` | ~35 GB | most capable (needs 24+ GB VRAM) |
+
+---
+
+## Agent modes
+
+| Mode             | Behaviour                                                                 |
+|------------------|---------------------------------------------------------------------------|
+| `autonomous`     | All `safe` and `review` actions execute without pause                     |
+| `human-approved` | `review`-rated actions pause and emit `onApprovalRequired` — call `resume()` to continue |
+
+---
+
+## Supported actions
+
+| Action     | Description                        | Risk           |
+|------------|------------------------------------|----------------|
+| `navigate` | Navigate to a URL (http/https only) | safe           |
+| `click`    | Click an element by CSS selector   | safe / review  |
+| `type`     | Type text into an input            | safe / review  |
+| `scroll`   | Scroll a container or the page     | safe           |
+| `focus`    | Focus an element                   | safe           |
+| `wait`     | Pause for N milliseconds           | safe           |
+| `extract`  | Extract text from an element       | review         |
+| `done`     | Signal task completion             | safe           |
+
+---
+
+## AbortSignal support
+
+```ts
+const controller = new AbortController();
+const agent = createBrowserAgent({ goal: "...", signal: controller.signal });
+agent.start();
+
+controller.abort(); // cancel from outside
+```
+
+---
+
+## WebLLM bridge wiring
+
+```ts
+import * as webllm from "@mlc-ai/web-llm";
+import { createBrowserAgent, parsePlannerResult } from "@akshayram1/omnibrowser-agent";
+
+const engine = await webllm.CreateMLCEngine("Phi-3.5-mini-instruct-q4f16_1-MLC");
+
+window.__browserAgentWebLLM = {
+  async plan(input) {
+    const { goal, history, lastError, memory, systemPrompt } = input;
+    const resp = await engine.chat.completions.create({
+      messages: [
+        { role: "system", content: systemPrompt || "You are a browser automation agent. Output only JSON." },
+        { role: "user",   content: `Goal: "${goal}"\nHistory: ${history.slice(-4).join(" -> ")}${memory ? "\nMemory: " + memory : ""}${lastError ? "\nLast error: " + lastError : ""}` }
+      ],
+      temperature: 0,
+      max_tokens: 200
+    });
+    return parsePlannerResult(resp.choices[0].message.content);
+  }
+};
+
+const agent = createBrowserAgent({ goal: "Fill the checkout form", planner: { kind: "webllm" } });
+await agent.start();
+```
+
+---
+
+## Chrome Extension
+
+1. `npm run build`
+2. Open `chrome://extensions`, enable **Developer Mode**, click **Load unpacked**, select `dist/`.
+3. Open any tab, enter a goal in the popup, pick a mode, and click **Start**.
+
+---
+
+## Project structure
+
+```
+src/
+├── background/      Extension service worker — session management
+├── content/         Extension content script — runs in page context
+├── core/            Shared engine (planner, observer, executor)
+├── lib/             npm library entry — createBrowserAgent()
+├── popup/           Extension popup UI
+└── shared/          Types, safety, and parse utilities
+```
+
+---
+
+## License
+
+MIT © Akshay Chame

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akshayram1/omnibrowser-agent",
-  "version": "0.2.29",
+  "version": "0.2.32",
   "private": false,
   "type": "module",
   "main": "./dist/lib.js",
@@ -20,7 +20,9 @@
     "build:types": "tsc -p tsconfig.lib.json",
     "watch": "node scripts/build.mjs --watch",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "node --experimental-strip-types --test src/shared/safety.test.ts src/core/planner.test.ts"
+    "test": "node --experimental-strip-types --test src/shared/safety.test.ts src/core/planner.test.ts",
+    "prepack": "cp README.md README.github.md && cp README.npm.md README.md",
+    "postpack": "mv README.github.md README.md"
   },
   "devDependencies": {
     "@types/chrome": "^0.0.322",

package/.github/workflows/ci.yml

@@ -1,41 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Run tests
-        run: npm test
-
-      - name: Bump patch version
-        id: bump
-        run: |
-          NEW_VERSION=$(npm version patch --no-git-tag-version)
-          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Commit version bump
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add package.json
-          git commit -m "chore: bump version to ${{ steps.bump.outputs.version }} [skip ci]"
-          git push

package/docs/ARCHITECTURE.md

@@ -1,64 +0,0 @@
-# OmniBrowser Agent Architecture (v0.2)
-
-## Goals
-
-- Local-first runtime in browser
-- Privacy-first defaults
-- Open-source composable planner/executor contracts
-- Human-approved mode for risky actions
-
-## Runtime Components
-
-1. Popup UI (`src/popup`)
-   - Starts/stops sessions
-   - Picks mode (`autonomous`, `human-approved`)
-   - Picks planner (`heuristic`, `webllm`)
-
-2. Background Service Worker (`src/background`)
-   - Session state machine per tab
-   - Tick loop orchestration
-   - Approval handling
-
-3. Content Agent (`src/content`)
-   - `observer`: page snapshot extraction
-   - `planner`: next-action decision (heuristic / WebLLM)
-   - `safety`: risk gating (`safe`, `review`, `blocked`)
-   - `executor`: DOM action execution
-
-## Contracts
-
-- Shared in `src/shared/contracts.ts`
-- Action protocol:
-  - click
-  - type
-  - navigate
-  - extract
-  - scroll
-  - focus
-  - wait
-  - done
-
-## Safety Model
-
-- Block invalid URL protocols
-- Review risky actions (submit/delete/pay-like selectors)
-- In `human-approved` mode, review-level actions require manual approval
-
-## Planner Bridges
-
-All planner bridges follow the same pattern: an object attached to `window` that implements a `plan()` method returning an `AgentAction`. The core library has zero runtime dependencies — bridge implementations are provided by the consumer.
-
-### WebLLM bridge
-
-```ts
-window.__browserAgentWebLLM = {
-  async plan(input, modelId) { /* call local WebLLM engine, return AgentAction */ }
-};
-```
-
-## Limitations (v0.2)
-
-- No persistent long-term memory yet
-- No task DSL/skills registry yet
-- Risk scoring is simple keyword heuristic
-- Selector healing is basic (attribute fallback + single-element shortcut)

package/docs/DEPLOYMENT.md

@@ -1,67 +0,0 @@
-# Deployment Guide
-
-## npm Package
-
-### Publish a new version manually
-
-```bash
-npm run build
-npm publish --access public
-```
-
-The CI pipeline auto-bumps the patch version on every push to `main`, so manual version bumps are only needed for minor/major releases:
-
-```bash
-npm version minor   # 0.2.x → 0.3.0
-npm version major   # 0.x.y → 1.0.0
-npm run build
-npm publish --access public
-```
-
-### Required secret
-
-Add `NPM_TOKEN` to your GitHub repository secrets if you want the pipeline to publish automatically (not enabled by default).
-
----
-
-## Vercel (Static Site / Chatbot Demo)
-
-The homepage and chatbot demo are static files served from the repo root.
-
-1. Import the repository at [vercel.com/new](https://vercel.com/new).
-2. Vercel picks up `vercel.json` automatically — no extra configuration needed.
-3. Every push to `main` triggers a new deployment.
-
-`vercel.json` key settings:
-```json
-{
-  "buildCommand": null,
-  "outputDirectory": "."
-}
-```
-
----
-
-## Chrome Extension (local / sideload)
-
-1. Build the extension bundle:
-   ```bash
-   npm run build
-   ```
-2. Open `chrome://extensions` and enable **Developer mode**.
-3. Click **Load unpacked** and select the `public/` folder.
-
-To update after code changes, rebuild and click the refresh icon on the extension card.
-
----
-
-## CI Pipeline
-
-The GitHub Actions workflow (`.github/workflows/ci.yml`) runs on every push to `main`:
-
-1. Installs dependencies.
-2. Runs `npm test` (Node built-in test runner, no extra deps).
-3. Bumps the patch version in `package.json` via `npm version patch`.
-4. Commits and pushes the version bump with `[skip ci]` to avoid a second run.
-
-The commit is made by `github-actions[bot]` using the built-in `GITHUB_TOKEN` — no extra secrets required.

package/docs/EMBEDDING.md

@@ -1,74 +0,0 @@
-# Embedding OmniBrowser Agent in Your Website
-
-You can keep the extension flow and also embed OmniBrowser Agent as a library in your own web app.
-
-## Install
-
-```bash
-npm install @akshayram1/omnibrowser-agent
-```
-
-## Basic usage
-
-```ts
-import { createBrowserAgent } from "@akshayram1/omnibrowser-agent";
-
-const agent = createBrowserAgent(
-  {
-    goal: "Search contact Jane Doe and open profile",
-    mode: "human-approved",
-    planner: { kind: "heuristic" },
-    maxSteps: 15,
-    stepDelayMs: 400
-  },
-  {
-    onStep: (result) => console.log("step", result),
-    onApprovalRequired: (action) => {
-      console.log("approval required", action);
-      // Show your own modal/button then call approvePendingAction()
-    },
-    onDone: (result) => console.log("done", result),
-    onError: (error) => console.error(error)
-  }
-);
-
-await agent.start();
-```
-
-## Approve a pending action
-
-```ts
-await agent.approvePendingAction();
-```
-
-## Stop running session
-
-```ts
-agent.stop();
-```
-
-## WebLLM mode in embedded app
-
-To use planner mode `webllm`, load the WebLLM engine and wire the bridge before starting the agent:
-
-```ts
-import * as webllm from "@mlc-ai/web-llm";
-import { createBrowserAgent, createWebLLMBridge } from "@akshayram1/omnibrowser-agent";
-
-const engine = await webllm.CreateMLCEngine("Llama-3.2-1B-Instruct-q4f16_1-MLC");
-
-window.__browserAgentWebLLM = createWebLLMBridge(engine);
-
-const agent = createBrowserAgent({
-  goal: "Fill the contact form",
-  planner: { kind: "webllm", modelId: "Llama-3.2-1B-Instruct-q4f16_1-MLC" }
-});
-
-await agent.start();
-```
-
-## Notes
-
-- For production, mount this inside an authenticated app shell and add your own permission checks.
-- `human-approved` mode is recommended for CRM/finance/admin actions.
-- Bring your own WebLLM engine instance, then wire `createWebLLMBridge(engine)` to `window.__browserAgentWebLLM`.

package/docs/ROADMAP.md

@@ -1,29 +0,0 @@
-# Roadmap
-
-## v0.1
-
-- Extension runtime loop
-- Shared action contracts
-- Heuristic + WebLLM planner switch
-- Human-approved mode
-
-## v0.2 (current)
-
-- New actions: `scroll`, `focus`
-- Improved heuristic planner with regex goal patterns
-- Better page observation (visibility filtering, placeholder capture)
-- Library API: `resume()`, `isRunning`, `hasPendingAction`, `AbortSignal`, `onMaxStepsReached`
-
-## v0.3
-
-- Expanded WebLLM model catalog (new 7B/8B options + compatibility matrix)
-- Improved model loading UX (recommended presets by speed/quality and device memory)
-- Enhanced default system prompts for safer, clearer multi-step planning
-- Prompt presets for common workflows (docs navigation, CRM form fill, task automation)
-
-## v1.0
-
-- Advanced prompt orchestration (goal-aware system prompt routing and contextual guardrails)
-- Functionality expansion: richer action toolkit and stronger extraction/navigation reliability
-- Adaptive planner behaviour (model-aware retries, fallback strategies, and recovery flows)
-- Evaluation suite for prompt and model quality across benchmark browser tasks