@akshayram1/omnibrowser-agent 0.2.0

package/dist/types/shared/contracts.d.ts

@@ -0,0 +1,92 @@
+export type AgentMode = "autonomous" | "human-approved";
+export type PlannerKind = "heuristic" | "webllm";
+export type RiskLevel = "safe" | "review" | "blocked";
+export type AgentAction = {
+    type: "click";
+    selector: string;
+    label?: string;
+} | {
+    type: "type";
+    selector: string;
+    text: string;
+    clearFirst?: boolean;
+    label?: string;
+} | {
+    type: "navigate";
+    url: string;
+} | {
+    type: "extract";
+    selector: string;
+    label: string;
+} | {
+    type: "scroll";
+    selector?: string;
+    deltaY: number;
+} | {
+    type: "focus";
+    selector: string;
+} | {
+    type: "wait";
+    ms: number;
+} | {
+    type: "done";
+    reason: string;
+};
+export interface CandidateElement {
+    selector: string;
+    role: string;
+    text: string;
+    placeholder?: string;
+}
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    textPreview: string;
+    candidates: CandidateElement[];
+}
+export interface PlannerInput {
+    goal: string;
+    snapshot: PageSnapshot;
+    history: string[];
+}
+export interface PlannerConfig {
+    kind: PlannerKind;
+    modelId?: string;
+}
+export interface AgentSession {
+    id: string;
+    tabId: number | null;
+    goal: string;
+    mode: AgentMode;
+    planner: PlannerConfig;
+    history: string[];
+    isRunning: boolean;
+    pendingAction?: AgentAction;
+}
+export interface LibraryAgentConfig {
+    goal: string;
+    mode?: AgentMode;
+    planner?: PlannerConfig;
+    maxSteps?: number;
+    stepDelayMs?: number;
+    signal?: AbortSignal;
+}
+export interface LibraryAgentEvents {
+    onStart?: (session: AgentSession) => void;
+    onStep?: (result: ContentResult, session: AgentSession) => void;
+    onApprovalRequired?: (action: AgentAction, session: AgentSession) => void;
+    onDone?: (result: ContentResult, session: AgentSession) => void;
+    onError?: (error: unknown, session: AgentSession) => void;
+    onMaxStepsReached?: (session: AgentSession) => void;
+}
+export type ContentCommand = {
+    type: "AGENT_TICK";
+    session: AgentSession;
+} | {
+    type: "AGENT_STOP";
+};
+export type ContentResult = {
+    status: "executed" | "needs_approval" | "blocked" | "done" | "error";
+    message: string;
+    action?: AgentAction;
+};

package/dist/types/shared/safety.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAction, RiskLevel } from "./contracts";
+export declare function assessRisk(action: AgentAction): RiskLevel;

package/docs/ARCHITECTURE.md

@@ -0,0 +1,56 @@
+# OmniBrowser Agent Architecture (v0.1)
+
+## 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`)
+   - `pageObserver`: 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
+  - 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
+
+## WebLLM Usage
+
+- Planner includes a `webllm` mode contract with a local bridge hook
+- v0.1 bridge entrypoint: `window.__browserAgentWebLLM.plan(input, modelId)`
+- Full in-extension worker integration is planned for v0.2
+
+## Limitations (v0.1)
+
+- No persistent long-term memory yet
+- No task DSL/skills registry yet
+- Risk scoring is simple keyword heuristic
+- No robust selector healing yet

package/docs/EMBEDDING.md

@@ -0,0 +1,72 @@
+# 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 @akshaychame/omnibrowser-agent
+```
+
+## Basic usage
+
+```ts
+import { createBrowserAgent } from "@akshaychame/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`, provide a local bridge in your app:
+
+```ts
+window.__browserAgentWebLLM = {
+  async plan(input, modelId) {
+    // call your local WebLLM engine and return one AgentAction JSON
+    return { type: "done", reason: `Implement bridge with model ${modelId ?? "default"}` };
+  }
+};
+```
+
+Then configure:
+
+```ts
+planner: { kind: "webllm", modelId: "Llama-3.2-1B-Instruct-q4f16_1-MLC" }
+```
+
+## 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.

package/docs/ROADMAP.md

@@ -0,0 +1,27 @@
+# Roadmap
+
+## v0.1 (current)
+
+- Extension runtime loop
+- Shared action contracts
+- Heuristic + WebLLM planner switch
+- Human-approved mode
+
+## v0.2
+
+- Site profile + policy engine (allowlist, blocked domains)
+- Selector healing and fallback strategy
+- Session memory and action replay log
+- Drupal CRM starter skills
+
+## v0.3
+
+- Long-term encrypted memory in IndexedDB
+- Goal decomposition planner (multi-step task graphs)
+- Multi-tab workflows
+
+## v1.0
+
+- Stable plugin API for site skills
+- Validation/eval harness with benchmark tasks
+- Cross-browser packaging (Chromium + Firefox)

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@akshayram1/omnibrowser-agent",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/lib.js",
+  "module": "./dist/lib.js",
+  "types": "./dist/types/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/lib/index.d.ts",
+      "import": "./dist/lib.js"
+    }
+  },
+  "description": "Local-first OmniBrowser Agent (WebLLM + page automation)",
+  "author": "Akshay Chame",
+  "license": "MIT",
+  "scripts": {
+    "build": "node scripts/build.mjs && npm run build:types",
+    "build:types": "tsc -p tsconfig.lib.json",
+    "watch": "node scripts/build.mjs --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/chrome": "^0.0.322",
+    "esbuild": "^0.25.2",
+    "typescript": "^5.8.2"
+  }
+}