@praveen-palanisamy/agent-browser-runtime 0.1.0

package/dist/service/server.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Minimal HTTP layer for the agent runner (no framework: `node:http` only).
+ *
+ * - Bearer-token auth on every /v1 route
+ * - JSON bodies, size-capped
+ * - /live/{captureId}/... proxies the provider live view (no token: the
+ *   capture id is the credential, scoped to an active capture)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = void 0;
+exports.isAuthorized = isAuthorized;
+exports.createRunnerServer = createRunnerServer;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const attribution_1 = require("../attribution");
+const protocol_1 = require("../protocol");
+const live_proxy_1 = require("./live-proxy");
+const MAX_BODY_BYTES = 8 * 1024 * 1024; // sessions with localStorage can be large
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+exports.HttpError = HttpError;
+function json(res, status, body) {
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        Server: (0, attribution_1.userAgentString)(),
+    });
+    res.end(JSON.stringify(body));
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            throw new HttpError(413, 'Request body too large');
+        }
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0) {
+        return {};
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new HttpError(400, 'Invalid JSON body');
+    }
+}
+function isAuthorized(header, token) {
+    const presented = header?.startsWith('Bearer ') ? header.slice(7) : '';
+    const a = Buffer.from(presented);
+    const b = Buffer.from(token);
+    return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+function requireFields(body, fields) {
+    for (const f of fields) {
+        if (body[f] === undefined || body[f] === null || body[f] === '') {
+            throw new HttpError(400, `Missing required field: ${f}`);
+        }
+    }
+}
+function createRunnerServer(runner) {
+    const { config } = runner;
+    const liveDeps = {
+        resolve: (captureId) => runner.capture.liveViewUrlFor(captureId),
+        publicUrl: config.publicUrl,
+        livePrefix: protocol_1.RUNNER_ROUTES.live,
+    };
+    const server = (0, node_http_1.createServer)(async (req, res) => {
+        const url = new URL(req.url || '/', 'http://runner');
+        try {
+            if (req.method === 'GET' && url.pathname === protocol_1.RUNNER_ROUTES.health) {
+                json(res, 200, {
+                    ok: true,
+                    name: attribution_1.PROJECT.name,
+                    version: (0, attribution_1.packageVersion)(),
+                    repository: attribution_1.PROJECT.repository,
+                    jobProvider: config.jobProvider,
+                    captureProvider: config.captureProvider,
+                    activeCaptures: runner.capture.size,
+                });
+                return;
+            }
+            if ((0, live_proxy_1.handleLiveHttp)(req, res, liveDeps)) {
+                return;
+            }
+            if (!url.pathname.startsWith('/v1/')) {
+                throw new HttpError(404, 'Not found');
+            }
+            if (!isAuthorized(req.headers.authorization, config.token)) {
+                throw new HttpError(401, 'Unauthorized');
+            }
+            if (req.method !== 'POST') {
+                throw new HttpError(405, 'Method not allowed');
+            }
+            const body = await readJson(req);
+            switch (url.pathname) {
+                case protocol_1.RUNNER_ROUTES.post:
+                    requireFields(body, [
+                        'jobId',
+                        'workspaceId',
+                        'accountId',
+                        'platform',
+                        'content',
+                        'session',
+                    ]);
+                    json(res, 200, await runner.post(body));
+                    return;
+                case protocol_1.RUNNER_ROUTES.probe:
+                    requireFields(body, [
+                        'workspaceId',
+                        'accountId',
+                        'platform',
+                        'session',
+                    ]);
+                    json(res, 200, await runner.probe(body));
+                    return;
+                case protocol_1.RUNNER_ROUTES.captureStart:
+                    requireFields(body, ['platform']);
+                    json(res, 200, await runner.captureStart(body));
+                    return;
+                case protocol_1.RUNNER_ROUTES.captureFinish:
+                    requireFields(body, ['captureId']);
+                    json(res, 200, await runner.captureFinish(body));
+                    return;
+                case protocol_1.RUNNER_ROUTES.captureCancel:
+                    requireFields(body, ['captureId']);
+                    json(res, 200, await runner.captureCancel(body));
+                    return;
+                default:
+                    throw new HttpError(404, 'Not found');
+            }
+        }
+        catch (e) {
+            if (e instanceof HttpError) {
+                json(res, e.status, { error: e.message });
+                return;
+            }
+            console.error('[agent-runner] request failed', url.pathname, e);
+            json(res, 500, {
+                error: e instanceof Error ? e.message : 'Internal error',
+            });
+        }
+    });
+    server.on('upgrade', (req, socket, head) => {
+        if (!(0, live_proxy_1.handleLiveUpgrade)(req, socket, head, liveDeps)) {
+            socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+            socket.destroy();
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/service/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/service/server.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;AAEH,6CAA8C;AAC9C,yCAKmB;AACnB,gDAA0E;AAC1E,0CAA4C;AAC5C,6CAAiE;AAGjE,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,0CAA0C;AAElF,eAAuB,SAAQ,KAAK;IAEvB,MAAM;IADjB,YACW,MAAc,EACvB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;sBAHN,MAAM;IAIjB,CAAC;CACF;;AAED,SAAS,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IAC9D,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,kBAAkB;QAClC,MAAM,EAAE,IAAA,6BAAe,GAAE;KAC1B,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,QAAQ,CAAI,GAAoB;IAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QAC9B,IAAI,IAAK,KAAgB,CAAC,MAAM,CAAC;QACjC,IAAI,IAAI,GAAG,cAAc,EAAE,CAAC;YAC1B,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QACrD,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAe,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAO,CAAC;IACjB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAM,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;IAChD,CAAC;AACH,CAAC;AAED,sBACE,MAA0B,EAC1B,KAAa;IAEb,MAAM,SAAS,GAAG,MAAM,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,IAAA,6BAAe,EAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,aAAa,CAAC,IAA6B,EAAE,MAAgB;IACpE,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;YAChE,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,2BAA2B,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;AACH,CAAC;AAED,4BAAmC,MAAmB;IACpD,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC1B,MAAM,QAAQ,GAAG;QACf,OAAO,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,SAAS,CAAC;QACxE,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,UAAU,EAAE,wBAAa,CAAC,IAAI;KAC/B,CAAC;IAEF,MAAM,MAAM,GAAG,IAAA,wBAAY,EAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC7C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,eAAe,CAAC,CAAC;QACrD,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,QAAQ,KAAK,wBAAa,CAAC,MAAM,EAAE,CAAC;gBAClE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE;oBACb,EAAE,EAAE,IAAI;oBACR,IAAI,EAAE,qBAAO,CAAC,IAAI;oBAClB,OAAO,EAAE,IAAA,4BAAc,GAAE;oBACzB,UAAU,EAAE,qBAAO,CAAC,UAAU;oBAC9B,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,eAAe,EAAE,MAAM,CAAC,eAAe;oBACvC,cAAc,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI;iBACpC,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YACD,IAAI,IAAA,2BAAc,EAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACvC,OAAO;YACT,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YACxC,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3D,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAC3C,CAAC;YACD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC1B,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;YACjD,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAA0B,GAAG,CAAC,CAAC;YAC1D,QAAQ,GAAG,CAAC,QAAQ,EAAE,CAAC;gBACrB,KAAK,wBAAa,CAAC,IAAI;oBACrB,aAAa,CAAC,IAAI,EAAE;wBAClB,OAAO;wBACP,aAAa;wBACb,WAAW;wBACX,UAAU;wBACV,SAAS;wBACT,SAAS;qBACV,CAAC,CAAC;oBACH,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,IAAa,CAAC,CAAC,CAAC;oBACjD,OAAO;gBACT,KAAK,wBAAa,CAAC,KAAK;oBACtB,aAAa,CAAC,IAAI,EAAE;wBAClB,aAAa;wBACb,WAAW;wBACX,UAAU;wBACV,SAAS;qBACV,CAAC,CAAC;oBACH,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,KAAK,CAAC,IAAa,CAAC,CAAC,CAAC;oBAClD,OAAO;gBACT,KAAK,wBAAa,CAAC,YAAY;oBAC7B,aAAa,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;oBAClC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,YAAY,CAAC,IAAa,CAAC,CAAC,CAAC;oBACzD,OAAO;gBACT,KAAK,wBAAa,CAAC,aAAa;oBAC9B,aAAa,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;oBACnC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,aAAa,CAAC,IAAa,CAAC,CAAC,CAAC;oBAC1D,OAAO;gBACT,KAAK,wBAAa,CAAC,aAAa;oBAC9B,aAAa,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;oBACnC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC,aAAa,CAAC,IAAa,CAAC,CAAC,CAAC;oBAC1D,OAAO;gBACT;oBACE,MAAM,IAAI,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC1C,OAAO;YACT,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YAChE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE;gBACb,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB;aACzD,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;QACzC,IAAI,CAAC,IAAA,8BAAiB,EAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;YAC/C,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/docs/AGENTS.md

@@ -0,0 +1,46 @@
+# Notes for coding agents and LLM tool builders
+
+This file is written for AI agents (Cursor, Claude Code, Codex, custom MCP tools) that integrate or extend `agent-browser-runtime`.
+
+## What this package is, in one sentence
+
+A runtime that lets software act inside a user's authenticated browser session, unattended, on infrastructure the operator controls, with explicit verification and re-auth signalling.
+
+## When to reach for it
+
+- You need to perform actions on a website **as a specific user** and there is no API, the API is metered, or the API lacks the capability.
+- The action must run **later** (cron, queue) without the user present.
+- You need a **safe outcome model**: confirmed / uncertain / needs re-auth, so you never double-act.
+
+## When not to
+
+- Scraping public pages (use a plain headless browser).
+- Anything that violates the target site's terms or acts without the user's explicit instruction.
+
+## Integration recipe
+
+1. **Implement a `WebPostStrategy`** for the target site: `validate(content)`, `isAuthenticated(ctx)`, `post(ctx, content)`. Verify inside `post` (read back the UI or find the permalink); return `uncertain: true` if you submitted but could not confirm.
+2. **Run the service**: `startRunner({ strategies })` or `agent-browser-runtime serve --strategies ./strategies.js` with `AGENT_RUNNER_TOKEN`.
+3. **Capture once**: `captureStart` → embed `liveViewUrl` → user signs in → `captureFinish` → encrypt and store `state`.
+4. **Act unattended**: `post` / `probe` with the decrypted session; persist `refreshedSession`; honour `needsReauth` and `uncertain`.
+
+## Public API surface (stable)
+
+- `@praveen-palanisamy/agent-browser-runtime` — contracts (`SessionStore`, `SessionProvider`, `WebPostStrategy`, `AgentSessionState`, `AgentPostResult`), `AgentPoster`, `SessionCaptureManager`, providers, `AgentRunnerClient`, protocol types.
+- `…/client` — `AgentRunnerClient` + protocol only (no Playwright).
+- `…/service` — `startRunner`, `AgentRunner`, `loadConfig`, `createRunnerServer`.
+- CLI `agent-browser-runtime` — `serve`, `health`, `probe`, `post`; `--local` runs probe/post in-process (no service). Exit codes: `0` ok · `2` not authenticated / failed · `3` uncertain.
+- GitHub Action `praveen-palanisamy/agent-browser-runtime@v0` — `command: probe|post`, outputs `ok`, `authenticated`, `needs-reauth`, `uncertain`, `result-file`, `session-file` (see `docs/GITHUB_ACTION.md`).
+- `GET /healthz` returns `{ name, version, repository, jobProvider, captureProvider, activeCaptures }`; every JSON response carries a `Server: agent-browser-runtime/<version> (+repo)` header.
+
+Wire protocol routes and request/response shapes live in `src/protocol.ts`; treat them as the contract when generating client code in other languages.
+
+## Extending
+
+- **New provider**: implement `SessionProvider.acquire({ platform, state, interactive })` returning an `AgentSessionHandle` (`context`, `exportState`, `dispose`, optional `liveViewUrl`). Use `attachOverCdp` for any CDP-speaking backend. Add a unit test with a fake `fetch` (see `__tests__/kernel-provider.test.ts`).
+- **New strategy**: keep it in your application; the runtime never hard-codes platforms.
+
+## Testing conventions
+
+- `npm test` must stay browser-free and fast; anything that launches Chromium goes under `__tests__/browser/*.browser.test.ts`.
+- Fake providers/handles are sufficient for orchestration tests (`__tests__/runner.test.ts`).

package/docs/ARCHITECTURE.md

@@ -0,0 +1,73 @@
+# Architecture
+
+## Layers
+
+```mermaid
+flowchart TB
+  Client[client/ AgentRunnerClient<br/>no Playwright] -->|HTTP + bearer| Server[service/server.ts]
+  Server --> Runner[service/runner.ts AgentRunner]
+  Runner --> Poster[core/poster.ts AgentPoster]
+  Runner --> Capture[core/capture.ts SessionCaptureManager]
+  Poster --> Store[core/stores.ts InMemorySessionStore]
+  Poster --> Prov[SessionProvider]
+  Capture --> Prov
+  Prov --> Local[providers/playwright.ts<br/>LocalBrowserSessionProvider]
+  Prov --> Cdp[providers/playwright.ts<br/>CdpSessionProvider]
+  Prov --> Steel[providers/steel.ts]
+  Prov --> Kernel[providers/kernel.ts]
+  Server --> Live[service/live-proxy.ts]
+```
+
+- **core** — pure orchestration over the three contracts. No HTTP, no env.
+- **providers** — turn a stored session into a live `BrowserContext`. Remote providers create a browser via REST, connect over CDP, inject `storageState`, and dispose/release on close.
+- **service** — env-driven runner: chooses providers per job type, registers the caller's strategies, exposes typed handlers and the HTTP server; proxies Steel's live view.
+- **client / protocol** — the wire contract. Everything an orchestrator needs without pulling Playwright into its bundle.
+
+## Session lifecycle
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant A as Your app
+  participant R as Runner
+  participant B as Browser (Steel/Kernel/local)
+  A->>R: POST /v1/capture/start {platform}
+  R->>B: acquire(interactive)
+  R-->>A: captureId, liveViewUrl
+  A->>U: iframe liveViewUrl
+  U->>B: signs in
+  A->>R: POST /v1/capture/finish {captureId}
+  R->>B: isAuthenticated? exportState
+  R-->>A: AgentSessionState
+  A->>A: encrypt + persist
+  Note over A,R: later, unattended
+  A->>R: POST /v1/post {session, content}
+  R->>B: acquire(state) → strategy.isAuthenticated → strategy.post
+  R-->>A: AgentPostResult + refreshedSession
+  A->>A: persist refreshed session
+```
+
+## Verification model
+
+A strategy is responsible for proving the action happened. `AgentPostResult` encodes three distinct outcomes so orchestrators can act safely:
+
+| Result | Meaning | Recommended orchestrator behaviour |
+|--------|---------|-------------------------------------|
+| `ok: true` + `verification` | Action confirmed (toast/permalink or read-back) | Mark done, persist `refreshedSession` |
+| `ok: false`, `uncertain: true` | Submit happened but nothing confirmed it | Flag for manual review; **do not** retry or fall back automatically |
+| `ok: false`, `needsReauth: true` | Session invalid | Mark account needs re-auth, notify user, optional fallback |
+| `ok: false`, `failureStage` ∈ precheck/compose/media | Aborted **before** submitting | Safe to retry or fall back |
+| `ok: false`, `failureStage: submit/verify` (not uncertain) | Failed with evidence nothing was posted | Safe to retry/fallback; inspect screenshot |
+
+## Pacing
+
+`AgentPoster` applies a small randomized delay before acting (`pacing: true`) to look human-scale. Per-account rate limits (minimum spacing, hourly caps) belong in the orchestrator where account state lives; the runner is stateless.
+
+## Provider selection
+
+`RunnerConfig.jobProvider` and `captureProvider` are independent. Typical production layout:
+
+- jobs → `local` (parallel, fresh Chromium per job inside the runner container)
+- capture → `steel` (live view) or `kernel` (headful browser with live view URL)
+
+`SerializedProvider` wraps single-session backends (Steel OSS) with a mutex so concurrent requests queue instead of failing.

package/docs/DEPLOY.md

@@ -0,0 +1,61 @@
+# Deploying and integrating ABR
+
+## Environment
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| `AGENT_RUNNER_TOKEN` | yes | ≥ 16 chars; shared with orchestrators |
+| `AGENT_RUNNER_PUBLIC_URL` | for capture | Absolute URL users reach the runner at (live view links) |
+| `PORT` | no | default 8080 |
+| `AGENT_RUNNER_JOB_PROVIDER` | no | `local` (default) · `steel` · `kernel` |
+| `AGENT_RUNNER_CAPTURE_PROVIDER` | no | `steel` when `STEEL_API_URL` is set, else `local` |
+| `STEEL_API_URL` / `STEEL_API_KEY` | for steel | e.g. `http://steel:3000`; key only for Steel Cloud |
+| `KERNEL_API_KEY` / `KERNEL_API_URL` | for kernel | default `https://api.onkernel.com` |
+| `AGENT_RUNNER_CAPTURE_TTL_MS` | no | default 20 min |
+| `AGENT_RUNNER_PACING` | no | `false` disables human-pace jitter (tests) |
+
+## Local (Docker Compose)
+
+```bash
+AGENT_RUNNER_TOKEN=$(openssl rand -base64 32) STRATEGIES_DIR=$PWD/examples/demo-strategy docker compose up --build
+curl -H "authorization: Bearer $AGENT_RUNNER_TOKEN" localhost:8080/healthz
+```
+
+Steel is exposed on `:3000` (API + live view) and `:9223` (CDP). Only the runtime should reach them in production.
+
+## Container image
+
+`ghcr.io/praveen-palanisamy/agent-browser-runtime:<version>` bundles Node, Playwright's Chromium and the runtime CLI. Extend it with your strategies:
+
+```dockerfile
+FROM ghcr.io/praveen-palanisamy/agent-browser-runtime:latest
+COPY dist/strategies.js /app/strategies.js
+CMD ["serve", "--strategies", "/app/strategies.js"]
+```
+
+The image pins `playwright-core` to the base image's Playwright version (`ARG PLAYWRIGHT_VERSION`), verified in CI by `scripts/check-playwright-pin.mjs`, so no browser download happens at runtime.
+
+## Cloud Run (runtime + Steel sidecar)
+
+- One service, two containers: the runtime (ingress) and `ghcr.io/steel-dev/steel-browser-api` on `localhost:3000`.
+- Set `STEEL_API_URL=http://127.0.0.1:3000`, `AGENT_RUNNER_CAPTURE_PROVIDER=steel`, `AGENT_RUNNER_JOB_PROVIDER=local`.
+- Interactive captures are stateful (a browser stays open while the user signs in), so pin `minScale = maxScale = 1` or add sticky routing. Headless jobs are parallel inside the instance.
+- Ingress must be public for the live view; every API route is still token-protected. Store `AGENT_RUNNER_TOKEN` in Secret Manager.
+- Give the Steel container ≥ 2 GiB memory and mount an in-memory volume at `/app/.cache`; nothing durable lives there.
+
+The same shape works on ECS/Fargate task definitions or a Nomad group.
+
+## Scaling beyond one instance
+
+- Move captures to **Kernel** (`AGENT_RUNNER_CAPTURE_PROVIDER=kernel`): each capture gets its own microVM with a live view URL, so instances become interchangeable.
+- Or run several runner instances and route `/v1/capture/finish|cancel` and `/live/{captureId}` by capture id (hash or header) at the load balancer.
+
+## Ways to consume ABR
+
+| Channel | Best for | Pin |
+|---------|----------|-----|
+| [npm `@praveen-palanisamy/agent-browser-runtime`](https://www.npmjs.com/package/@praveen-palanisamy/agent-browser-runtime) | embedding the library or client in your app | `^0.1` |
+| [GHCR `ghcr.io/praveen-palanisamy/agent-browser-runtime`](https://github.com/praveen-palanisamy/agent-browser-runtime/pkgs/container/agent-browser-runtime) | running the runner service (Chromium included) | `:0.1`, `:latest` |
+| [GitHub Action](GITHUB_ACTION.md) | probes and jobs from CI without a service | `@v0` |
+
+Releases are cut automatically from `main`; every semver tag publishes all three channels with provenance. Follow the [Releases page](https://github.com/praveen-palanisamy/agent-browser-runtime/releases) or watch the [changelog](../CHANGELOG.md).

package/docs/GITHUB_ACTION.md

@@ -0,0 +1,92 @@
+# GitHub Action
+
+ABR ships as a composite action so you can run authenticated browser jobs from any workflow — no runner service to deploy. It installs the runtime and Chromium on the job runner and executes the CLI in-process (`--local`).
+
+```yaml
+- uses: praveen-palanisamy/agent-browser-runtime@v0
+  with:
+    command: probe                      # or: post
+    platform: expense-portal
+    strategies: ./automation/strategies.js
+    session: ${{ secrets.EXPENSE_PORTAL_SESSION }}
+```
+
+## Typical workflows
+
+### Nightly session health check
+
+Tell users *before* a scheduled job fails that they need to sign in again.
+
+```yaml
+name: session-health
+on:
+  schedule: [{ cron: "0 6 * * *" }]
+jobs:
+  probe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - id: abr
+        uses: praveen-palanisamy/agent-browser-runtime@v0
+        with:
+          command: probe
+          platform: expense-portal
+          strategies: ./automation/strategies.js
+          session: ${{ secrets.EXPENSE_PORTAL_SESSION }}
+          fail-on-reauth: "false"
+      - if: steps.abr.outputs.needs-reauth == 'true'
+        run: ./notify.sh "Expense portal session expired — please sign in again"
+```
+
+### Run a job with the stored session
+
+```yaml
+      - id: abr
+        uses: praveen-palanisamy/agent-browser-runtime@v0
+        with:
+          command: post
+          platform: expense-portal
+          strategies: ./automation/strategies.js
+          session: ${{ secrets.EXPENSE_PORTAL_SESSION }}
+          text: "March travel — client onsite"
+          media: https://files.example/receipt-1.jpg,https://files.example/receipt-2.jpg
+      - name: Persist rotated cookies
+        if: always()
+        run: ./vault put expense-portal-session "${{ steps.abr.outputs.session-file }}"
+      - name: Never retry blindly
+        if: steps.abr.outputs.uncertain == 'true'
+        run: ./open-review-ticket.sh "${{ steps.abr.outputs.result-file }}"
+```
+
+## Inputs
+
+| Input | Default | Notes |
+|-------|---------|-------|
+| `command` | `probe` | `probe` or `post` |
+| `platform` | — | must match a strategy's `platform` |
+| `session` / `session-file` | — | `AgentSessionState` JSON; pass a secret or a file path |
+| `strategies` | bundled demo | module exporting `WebPostStrategy[]` |
+| `text`, `media`, `link`, `content-file` | — | job content (`post`) |
+| `workspace`, `account` | `github-actions` / `default` | job identity |
+| `session-out` | `.abr/session.refreshed.json` | refreshed session written here |
+| `result-out` | `.abr/result.json` | JSON result written here |
+| `fail-on-reauth` | `true` | fail the step when re-auth is needed |
+| `pacing` | `true` | human-pace jitter before acting |
+| `node-version` | `24` | |
+
+## Outputs
+
+`ok`, `authenticated`, `needs-reauth`, `uncertain`, `result-file`, `session-file`.
+
+Exit codes of the underlying CLI: `0` success · `2` not authenticated / failed · `3` uncertain (ran, unverified).
+
+## Security notes
+
+- Store sessions as **encrypted secrets**; the action writes the secret to a temp file and deletes it after the run.
+- Refreshed sessions are written to `session-out` in the workspace — persist them back to your vault and do not upload them as public artifacts.
+- The action runs on GitHub's runner IPs. Sites that fingerprint location may still ask for re-auth; for stable egress, run the [HTTP runner service](DEPLOY.md) instead.
+- Use ABR only with the user's explicit authorization and within each site's terms of service.
+
+## Versioning
+
+`@v0` tracks the latest green commit on `main` (moved automatically); pin `@v0.1.0` for immutable builds.

package/examples/demo-strategy/index.js

@@ -0,0 +1,53 @@
+// Minimal WebPostStrategy module for `agent-browser-runtime serve --strategies`.
+// It drives example.com so it works anywhere without credentials; real
+// strategies implement the same three methods against a platform's UI.
+//
+//   AGENT_RUNNER_TOKEN=... npx agent-browser-runtime serve --strategies ./examples/demo-strategy/index.js
+
+/** @type {import('@praveen-palanisamy/agent-browser-runtime').WebPostStrategy} */
+const demoStrategy = {
+  platform: 'demo',
+  loginUrl: 'https://example.com/',
+
+  validate(content) {
+    if (!content.text?.trim()) return 'Text is required';
+    if (content.text.length > 280) return 'Text exceeds 280 characters';
+    return null;
+  },
+
+  async isAuthenticated(context) {
+    // A real strategy checks for a logged-in marker (avatar, compose button…).
+    const page = await context.newPage();
+    try {
+      await page.goto('https://example.com/', {
+        waitUntil: 'domcontentloaded',
+      });
+      return (await page.title()).length > 0;
+    } finally {
+      await page.close();
+    }
+  },
+
+  async post(context, _content) {
+    const page = await context.newPage();
+    try {
+      await page.goto('https://example.com/', {
+        waitUntil: 'domcontentloaded',
+      });
+      // Verification is the strategy's job: read back what the UI shows and
+      // only report ok when it matches `content`.
+      const heading = await page.textContent('h1');
+      return heading
+        ? {
+            ok: true,
+            platformPostId: `demo-${Date.now()}`,
+            verification: 'toast',
+          }
+        : { ok: false, failureStage: 'verify', error: 'no heading rendered' };
+    } finally {
+      await page.close();
+    }
+  },
+};
+
+module.exports = [demoStrategy];

package/examples/demo-strategy/session.json

@@ -0,0 +1,5 @@
+{
+  "platform": "demo",
+  "storageState": { "cookies": [], "origins": [] },
+  "capturedAt": "2026-01-01T00:00:00.000Z"
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@praveen-palanisamy/agent-browser-runtime",
+  "version": "0.1.0",
+  "description": "Stateful, secure browser-session execution for agents: pluggable browser providers (local Chromium, CDP, Steel, Kernel), post/probe/capture orchestration, an HTTP runner service and a Playwright-free client",
+  "keywords": [
+    "agents",
+    "ai-agents",
+    "authenticated-sessions",
+    "browser-agent",
+    "browser-automation",
+    "cdp",
+    "github-action",
+    "headless-chrome",
+    "kernel",
+    "kernel-browsers",
+    "playwright",
+    "rpa",
+    "self-hosted",
+    "session",
+    "steel",
+    "steel-browser",
+    "storage-state",
+    "web-automation"
+  ],
+  "license": "MIT",
+  "author": "Praveen Palanisamy",
+  "homepage": "https://praveen-palanisamy.github.io/agent-browser-runtime/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/praveen-palanisamy/agent-browser-runtime.git"
+  },
+  "bugs": {
+    "url": "https://github.com/praveen-palanisamy/agent-browser-runtime/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agent-browser-runtime": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./service": {
+      "types": "./dist/service/index.d.ts",
+      "default": "./dist/service/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "action.yml"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "test:browser": "ABR_TEST_SUITE=browser vitest run",
+    "browsers:install": "npx playwright-core install chromium",
+    "ci:check": "npm run lint && npm run typecheck && npm test && node scripts/check-playwright-pin.mjs && node scripts/check-action-manifest.mjs",
+    "pack:check": "npm pack --dry-run",
+    "release:prepare": "node scripts/release.mjs",
+    "prepublishOnly": "npm run build",
+    "site:build": "node scripts/site-build.mjs",
+    "site:serve": "node scripts/site-build.mjs && npx -y serve site/dist",
+    "site:demos": "node scripts/site-demos.mjs"
+  },
+  "dependencies": {
+    "playwright-core": "^1.57.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@types/node": "^26.4.1",
+    "marked": "^18.0.11",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "funding": "https://github.com/sponsors/praveen-palanisamy"
+}