agentic-browser 0.1.0

package/AGENTS.md

@@ -0,0 +1,128 @@
+# Agent Instructions
+
+## Quick Reference
+
+```bash
+npm run build        # tsdown (~20ms)
+npm run typecheck    # tsc --noEmit
+npm run lint         # oxlint
+npm run lint:fix     # oxlint --fix
+npm run format       # oxfmt --write
+npm test             # vitest run
+npm run test:watch   # vitest
+npm run docs:dev     # vocs dev server
+```
+
+## Architecture
+
+AI-driven browser automation via Chrome DevTools Protocol (CDP). Three interfaces: CLI, MCP server, programmatic API.
+
+### Module Map
+
+```
+src/
+  index.ts                — Public API exports (AgenticBrowserCore + types)
+  cli/
+    index.ts              — CLI entry (Commander.js, colon-namespaced commands)
+    runtime.ts            — AgenticBrowserCore class + factory functions
+    app.ts                — AppContext DI container (config, logger, eventStore, tokenService, memoryService)
+    commands/agent.ts     — Stateful agent commands (auto-restart, retry, session persistence)
+    commands/*.ts         — Low-level CLI command handlers
+  mcp/
+    index.ts              — MCP server (stdio transport, 7 tools wrapping AgenticBrowserCore)
+  session/
+    browser-controller.ts — BrowserController interface + ChromeCdpBrowserController (CDP WebSocket)
+    session-manager.ts    — Orchestrates sessions, commands, memory recording
+    session-state.ts      — In-memory state tracking
+    chrome-launcher.ts    — Chrome executable discovery & launch
+  transport/
+    control-api.ts        — ControlApi facade (delegates to SessionManager)
+    ws-server.ts          — Authenticated WebSocket server
+  memory/
+    memory-service.ts     — Task memory coordination
+    memory-index.ts       — Search/ranking (fuzzy match + freshness + domain)
+    task-insight-store.ts — JSON file persistence
+    staleness-detector.ts — Freshness state machine (fresh → suspect → stale)
+    memory-schemas.ts     — Zod v4 schemas for memory domain
+  auth/                   — Token-based session auth
+  lib/
+    config.ts             — loadConfig() from env vars
+    domain-schemas.ts     — Zod v4 schemas (Session, Command, ConnectionState, etc.)
+  observability/          — Logger + EventStore
+```
+
+### Key Flow
+
+```
+AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
+                                              → MemoryService (record evidence)
+```
+
+1. `createAgenticBrowserCore()` builds AppContext + ChromeCdpBrowserController
+2. Commands execute via CDP `Runtime.evaluate` on the browser page
+3. Results are recorded as evidence, indexed per-domain for memory search
+
+## Code Conventions
+
+- **ESM-only**: `"type": "module"`, use `.js` extensions in all TypeScript imports
+- **Zod v4**: `import { z } from "zod"` — `z.record()` requires key+value args
+- **Commander.js v14**: colon-namespaced commands (`session:start`, `memory:search`)
+- **CLI output**: exactly one JSON line to `stdout`, errors to `stderr`
+- **Types**: interfaces for public contracts, type aliases for unions/inferred
+- **No console.log in MCP server**: use `process.stderr.write()` for debug output
+
+## How to Add a New CLI Command
+
+1. Create handler in `src/cli/commands/<name>.ts`
+   ```ts
+   export async function myCommand(runtime: Runtime, input: { ... }) {
+     return runtime.api.doSomething(input);
+   }
+   ```
+2. Register in `src/cli/index.ts` with `program.command("<name>").action(...)`
+3. Optionally add agent wrapper in `src/cli/commands/agent.ts`
+
+## How to Add a New BrowserController Method
+
+1. Add to `BrowserController` interface in `src/session/browser-controller.ts`
+2. Implement in `ChromeCdpBrowserController` (CDP `Runtime.evaluate` pattern)
+3. Add stub in `MockBrowserController`
+4. Propagate: `SessionManager` → `ControlApi` → `AgenticBrowserCore`
+
+## How to Add a New MCP Tool
+
+1. Add `server.tool()` call in `src/mcp/index.ts`
+2. Use Zod v4 schemas for tool parameters
+3. Call `AgenticBrowserCore` methods directly
+4. Return `{ content: [{ type: "text", text: JSON.stringify(result) }] }`
+
+## Testing
+
+- **Unit**: `tests/unit/*.unit.test.ts` — pure logic with mocks
+- **Contract**: `tests/contract/*.contract.test.ts` — API contract validation
+- **Integration**: `tests/integration/*.integration.test.ts` — full lifecycle with MockBrowserController
+- Factory: `createMockAgenticBrowserCore(env)` — never launches real Chrome
+- Framework: Vitest, no special setup needed
+
+## Environment Variables
+
+- `AGENTIC_BROWSER_LOG_DIR` — base dir for sessions/memory/events (default: `.agentic-browser`)
+- `AGENTIC_BROWSER_CHROME_EXECUTABLE_PATH` — explicit Chrome path (auto-discovered if not set)
+
+## MCP Server
+
+Subcommand: `agentic-browser mcp` (stdio transport). Setup: `agentic-browser setup`. Tools:
+
+| Tool                    | Purpose                        |
+| ----------------------- | ------------------------------ |
+| `browser_start_session` | Start Chrome, return sessionId |
+| `browser_navigate`      | Navigate to URL                |
+| `browser_interact`      | click / type / press / waitFor |
+| `browser_get_content`   | Get page title / text / html   |
+| `browser_get_elements`  | Discover interactive elements  |
+| `browser_search_memory` | Search task memory             |
+| `browser_stop_session`  | Stop Chrome session            |
+
+## For Browser Automation Tasks
+
+See the [MCP Server](/mcp-server) docs for tool details and the README for CLI usage.

package/README.md

@@ -0,0 +1,226 @@
+# agentic-browser
+
+CLI and MCP server to control a local Chrome session for AI agents.
+
+## Purpose
+
+- Starts a managed Chrome session.
+- Accepts commands (for example `navigate`).
+- Returns structured JSON output that an LLM can parse directly.
+- Optimized for low-latency command execution by reusing CDP connections.
+
+## Requirements
+
+- Node.js 20+
+- Installed Chrome
+
+## Install
+
+```bash
+npm install agentic-browser
+```
+
+## Build (Development)
+
+```bash
+npm install
+npm run build
+```
+
+## Quality Checks
+
+```bash
+npm run format
+npm run lint
+npm test
+```
+
+## Agent Commands (Recommended for LLMs)
+
+The `agent` subcommand manages session state, auto-restarts on disconnect, generates command IDs, and retries failed commands automatically:
+
+```bash
+agentic-browser agent start
+agentic-browser agent status
+agentic-browser agent run navigate '{"url":"https://example.com"}'
+agentic-browser agent run interact '{"action":"click","selector":"#login"}'
+agentic-browser agent content --mode text
+agentic-browser agent content --mode html --selector main
+agentic-browser agent elements
+agentic-browser agent elements --roles button,link --limit 20
+agentic-browser agent memory-search "navigate:example.com" --domain example.com
+agentic-browser agent stop
+agentic-browser agent cleanup --dry-run --max-age-days 7
+```
+
+### Discover Interactive Elements
+
+List all clickable/interactive elements on the current page:
+
+```bash
+agentic-browser agent elements
+agentic-browser agent elements --roles button,link,input --visible-only --limit 30
+agentic-browser agent elements --selector "#main-content"
+```
+
+Returns a JSON array of elements with CSS selectors usable in `agent run interact`:
+
+```json
+{
+  "ok": true,
+  "action": "elements",
+  "elements": [
+    {
+      "selector": "#login-btn",
+      "role": "button",
+      "tagName": "button",
+      "text": "Login",
+      "actions": ["click"],
+      "visible": true,
+      "enabled": true
+    }
+  ],
+  "totalFound": 42,
+  "truncated": true
+}
+```
+
+## MCP Server
+
+### Quick Setup
+
+```bash
+npx agentic-browser setup
+```
+
+Detects your AI tools (Claude Code, Cursor) and writes the MCP config automatically.
+
+### Manual Configuration
+
+Add to your MCP config (`.mcp.json`, `.cursor/mcp.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "agentic-browser": {
+      "command": "npx",
+      "args": ["agentic-browser", "mcp"]
+    }
+  }
+}
+```
+
+## Low-Level CLI Commands
+
+For direct control without session state management:
+
+### 1. Start a Session
+
+```bash
+agentic-browser session:start
+```
+
+### 2. Read Session Status
+
+```bash
+agentic-browser session:status <sessionId>
+```
+
+### 3. Run a Command (`navigate` / `interact`)
+
+```bash
+agentic-browser command:run <sessionId> <commandId> navigate '{"url":"https://example.com"}'
+agentic-browser command:run <sessionId> cmd-2 interact '{"action":"click","selector":"a"}'
+```
+
+More `interact` actions:
+
+- `{"action":"type","selector":"input[name=q]","text":"innoq"}`
+- `{"action":"press","key":"Enter"}`
+- `{"action":"waitFor","selector":"main","timeoutMs":4000}`
+
+### 4. Read Page Content
+
+```bash
+agentic-browser page:content <sessionId> --mode title
+agentic-browser page:content <sessionId> --mode text
+agentic-browser page:content <sessionId> --mode html --selector main
+```
+
+### 5. Rotate Session Token
+
+```bash
+agentic-browser session:auth <sessionId>
+```
+
+### 6. Restart / Stop / Cleanup
+
+```bash
+agentic-browser session:restart <sessionId>
+agentic-browser session:stop <sessionId>
+agentic-browser session:cleanup --max-age-days 7
+```
+
+### 7. Task Memory
+
+```bash
+agentic-browser memory:search "navigate:example.com" --domain example.com --limit 5
+agentic-browser memory:inspect <insightId>
+agentic-browser memory:verify <insightId>
+agentic-browser memory:stats
+```
+
+## Recommended Agent Flow
+
+1. `agent start` — launch Chrome and persist session.
+2. `agent elements` — discover what's on the page.
+3. `agent run navigate/interact` — execute actions using discovered selectors.
+4. `agent content` — read page content after actions.
+5. `agent memory-search` — reuse known selectors for repeated tasks.
+6. `agent stop` — terminate when done.
+
+## Important Notes for LLMs
+
+- Exactly **one** managed session is supported at a time.
+- Session state is persisted in `.agentic-browser/`.
+- All commands print exactly one JSON line to `stdout`.
+- `payloadJson` must be valid JSON.
+- Parse only `stdout` as result object and use exit code for success/failure.
+
+## Programmatic API
+
+```ts
+import { createAgenticBrowserCore } from "agentic-browser";
+
+const core = createAgenticBrowserCore();
+const session = await core.startSession();
+
+await core.runCommand({
+  sessionId: session.sessionId,
+  commandId: "cmd-1",
+  type: "navigate",
+  payload: { url: "https://example.com" },
+});
+
+const elements = await core.getInteractiveElements({
+  sessionId: session.sessionId,
+  roles: ["button", "link"],
+  visibleOnly: true,
+  limit: 30,
+});
+
+const memory = core.searchMemory({
+  taskIntent: "navigate:example.com",
+  siteDomain: "example.com",
+  limit: 3,
+});
+
+await core.stopSession(session.sessionId);
+```
+
+## Documentation
+
+```bash
+npm run docs:dev     # Dev server at localhost:5173
+npm run docs:build   # Static build
+```