@praveen-palanisamy/agent-browser-runtime 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## Unreleased
+
+- **CLI**: new `post` command; `--local` runs `probe`/`post` in-process with local Chromium (no service needed); `--session-out`, `--out`, `--content`, `version`.
+- **GitHub Action**: `praveen-palanisamy/agent-browser-runtime@v0` composite action (`command: probe|post`) with `ok` / `authenticated` / `needs-reauth` / `uncertain` outputs; floating major tag maintained by `release-on-green`.
+- **Attribution**: `/healthz` reports `name`, `version`, `repository`; `Server` header on all JSON responses.
+- **Toolchain**: Node 24 everywhere (`.node-version`, CI, Pages, Action default); `engines.node >= 22`. Biome 2, TypeScript 7 (`module`/`moduleResolution: node16`, still CommonJS output), Vitest 5, `@types/node` 26. GitHub Actions bumped to Node 24-compatible majors (checkout v7, setup-node v7, docker/* v4/v7, pages v5/v6); grouped Dependabot updates for actions.
+- **Fix**: container build keeps optional dependencies (TypeScript 7 ships its compiler as platform-specific optional packages).
+- **Fix**: `action.yml` input description contained a `${{ … }}` expression, which made the runner reject the manifest.
+- **Docs & site**: project website on GitHub Pages (auto-deployed on releases), `docs/GITHUB_ACTION.md`, distribution-channel table in `docs/DEPLOY.md`; README use cases and examples reworked around an expense-portal assistant.
+
+## v0.1.0 — 2026-09-06
+
+First public release.
+
+- **Contracts**: `SessionStore`, `SessionProvider`, `WebPostStrategy`; rich `AgentPostResult` (`verification`, `uncertain`, `needsReauth`, `failureStage`, redacted screenshot).
+- **Orchestration**: `AgentPoster` (load → acquire → auth probe → pacing → post → persist rotated cookies), `SessionCaptureManager` (interactive sign-in with TTL and unguessable ids).
+- **Providers**: local Chromium, any CDP endpoint, self-hosted/cloud Steel, Kernel microVMs; `SerializedProvider` for single-session backends.
+- **Runner service**: bearer-protected HTTP API (`/v1/post`, `/v1/probe`, `/v1/capture/*`), Steel live-view proxy (HTTP + WebSocket, iframe-safe), `/healthz`.
+- **Client**: Playwright-free `AgentRunnerClient` with transient/permanent error classification.
+- **CLI**: `serve --strategies <module>`, `health`, `probe`.
+- **Packaging**: `.`, `./client`, `./service` entry points; container image on GHCR; npm Trusted Publishing with provenance; GitHub Packages mirror.

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Praveen Palanisamy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,261 @@
+# ABR: Agent Browser Runtime
+
+**Let your agent act as the user - in their own logged-in browser session - on infrastructure you control.**
+
+[![ci](https://github.com/praveen-palanisamy/agent-browser-runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/praveen-palanisamy/agent-browser-runtime/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@praveen-palanisamy/agent-browser-runtime)](https://www.npmjs.com/package/@praveen-palanisamy/agent-browser-runtime)
+[![ghcr](https://img.shields.io/badge/ghcr.io-agent--browser--runtime-blue?logo=docker)](https://github.com/praveen-palanisamy/agent-browser-runtime/pkgs/container/agent-browser-runtime)
+[![action](https://img.shields.io/badge/GitHub%20Action-%40v0-2088FF?logo=githubactions&logoColor=white)](docs/GITHUB_ACTION.md)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Website:** [praveen-palanisamy.github.io/agent-browser-runtime](https://praveen-palanisamy.github.io/agent-browser-runtime/) · **Source:** [github.com/praveen-palanisamy/agent-browser-runtime](https://github.com/praveen-palanisamy/agent-browser-runtime)
+
+`agent-browser-runtime` is a small, self-hostable runtime for **stateful, secure browser-session execution**. You capture a user's authenticated session once (they sign in inside a live view; you never see a password), store it encrypted in *your* database, and from then on any scheduled or event-driven job can open a fresh isolated browser, inject that session, drive the site's real UI with verification, and hand back the rotated cookies — without the user's laptop being online and without a developer API.
+
+It is the missing layer between "I have Playwright" and "I can run unattended, per-user, authenticated browser jobs in production":
+
+| Problem | What ABR gives you |
+|---------|----------------------------|
+| Platforms without a (usable/affordable) API | Ability to drive the real web UI with the user's own session |
+| Sessions live on the user's machine | Portable `storageState` you persist encrypted; runs on your servers |
+| Cookies rotate, sessions expire | Every job returns the refreshed session; `needsReauth` is a first-class outcome |
+| "Did the action actually happen?" | Strategies must verify; `uncertain` results are separated from failures so you never double-act |
+| Browser infra is painful | One `SessionProvider` contract over local Chromium, any CDP endpoint, self-hosted [Steel](https://github.com/steel-dev/steel-browser), or [Kernel](https://www.kernel.sh) microVMs |
+| Serverless can't run Chromium | An HTTP runner service + a Playwright-free client for functions, queues, and cron |
+| Users need to sign in somewhere safe | Interactive capture with an embeddable, proxied live view and unguessable, expiring capture ids |
+
+No browser engine is reinvented here: the runtime orchestrates proven engines (Playwright, Steel, Kernel) and owns the parts they leave to you — session lifecycle, verification contracts, pacing, isolation per job, and a stable wire protocol.
+
+## Use cases
+
+- **Autonomous assistants** that file expense reports, submit timesheets, update CRMs, or fetch statements from portals that have no API.
+- **Back-office automation for SaaS** — act inside each customer's vendor, bank, marketplace, or government portal with that customer's own session, isolated and encrypted under your keys.
+- **Agent frameworks / MCP tools** that need a durable "act on behalf of this user" primitive with re-auth signalling instead of silent failures.
+- **Scheduled, user-authorized publishing** to systems that expose no automation surface — where the user has explicitly authorized each action and the platform's terms permit it; fall back to an official API when one exists and the session is gone.
+- **Health probes** that tell users *before* a scheduled job fails that they need to sign in again.
+
+ABR gives you the execution primitive; you remain responsible for using it only with the user's explicit authorization and within each target site's terms of service.
+
+## How it fits together
+
+```mermaid
+flowchart LR
+  subgraph app [Your application]
+    Orch[Orchestrator<br/>cron · queue · serverless]
+    Vault[(Encrypted session store<br/>your database)]
+    Strat[WebPostStrategy implementations]
+  end
+  subgraph rt [agent-browser-runtime]
+    HTTP[HTTP runner<br/>/v1/post · /v1/probe · /v1/capture/*]
+    Core[AgentPoster · SessionCaptureManager]
+    Prov[SessionProvider<br/>local · cdp · steel · kernel]
+  end
+  Orch -->|client, bearer token,<br/>decrypted session in / refreshed out| HTTP
+  Vault <--> Orch
+  Strat --> Core
+  HTTP --> Core --> Prov
+  Prov --> Steel[Steel — self-hosted]
+  Prov --> Kernel[Kernel — microVMs]
+  Prov --> Local[Local Chromium]
+```
+
+The runtime is **stateless between requests**: sessions are never persisted by it, every job runs in a fresh browser context that is closed afterwards, and the only in-memory state is an in-flight interactive capture.
+
+## Quick start
+
+```bash
+npm i @praveen-palanisamy/agent-browser-runtime
+npx playwright-core install chromium        # local provider
+```
+
+### 1. Describe a platform (`WebPostStrategy`)
+
+Example: an AI finance assistant files expense reports in a corporate portal that has no API. The user signed in once; every month the assistant submits the report with receipts attached and only reports success when the portal shows a claim number.
+
+```ts
+import type { WebPostStrategy } from '@praveen-palanisamy/agent-browser-runtime';
+
+export const expensePortal: WebPostStrategy = {
+  platform: 'expense-portal',
+  loginUrl: 'https://expenses.corp.example/login',
+
+  validate: (c) =>
+    !c.text ? 'Description required'
+    : (c.mediaUrls?.length ?? 0) === 0 ? 'At least one receipt required'
+    : null,
+
+  async isAuthenticated(ctx) {
+    const page = await ctx.newPage();
+    await page.goto('https://expenses.corp.example/');
+    return page.getByRole('button', { name: 'New claim' }).isVisible();
+  },
+
+  async post(ctx, content) {
+    const page = await ctx.newPage();
+    await page.goto('https://expenses.corp.example/claims/new');
+    await page.getByLabel('Description').fill(content.text);
+    for (const receipt of content.mediaUrls ?? []) {
+      await page.getByLabel('Receipt').setInputFiles(await download(receipt));
+    }
+    // Pre-submit assert: the form shows exactly what we intend to file.
+    if ((await page.getByLabel('Description').inputValue()) !== content.text) {
+      return { ok: false, failureStage: 'compose', error: 'Description mismatch' };
+    }
+    await page.getByRole('button', { name: 'Submit claim' }).click();
+    const claim = await page.getByTestId('claim-number').textContent({ timeout: 15_000 }).catch(() => null);
+    return claim
+      ? { ok: true, platformPostId: claim, platformPostUrl: page.url(), verification: 'toast' }
+      : { ok: false, uncertain: true, failureStage: 'verify', error: 'No claim number shown' };
+  },
+};
+```
+
+### 2. Run it as a service
+
+```ts
+import { startRunner } from '@praveen-palanisamy/agent-browser-runtime/service';
+startRunner({ strategies: [expensePortal] });
+```
+
+or with the CLI and a module exporting `WebPostStrategy[]` (see [`examples/demo-strategy`](examples/demo-strategy/index.js)):
+
+```bash
+AGENT_RUNNER_TOKEN=$(openssl rand -base64 32) \
+  npx agent-browser-runtime serve --strategies ./strategies.js
+```
+
+No service at all? The CLI can run a single job in-process with local Chromium — the same path the [GitHub Action](docs/GITHUB_ACTION.md) uses:
+
+```bash
+npx agent-browser-runtime post --local --strategies ./strategies.js \
+  --platform expense-portal --session ./session.json \
+  --text "March travel" --session-out ./session.json      # refreshed cookies written back
+```
+
+### 3. Call it from anywhere (no Playwright needed)
+
+The orchestrator can be a cron job, a queue worker, or a serverless function — it never loads Playwright.
+
+```ts
+import { AgentRunnerClient } from '@praveen-palanisamy/agent-browser-runtime/client';
+
+const runner = new AgentRunnerClient({ baseUrl, token });
+
+// One-time: the employee signs in inside the live view you embed in your app.
+const { captureId, liveViewUrl } = await runner.captureStart({ platform: 'expense-portal' });
+// ... show liveViewUrl in an iframe; the user completes login (and MFA) ...
+const done = await runner.captureFinish({ captureId });
+if (done.ok) await vault.save(userId, encrypt(done.state));   // your encrypted store
+
+// Monthly, unattended: file the report the assistant prepared.
+const res = await runner.post({
+  workspaceId: orgId, accountId: userId, platform: 'expense-portal', jobId,
+  session: decrypt(await vault.load(userId)),
+  content: {
+    text: 'March travel — client onsite, 3 nights',
+    mediaUrls: receipts.map((r) => r.signedUrl),
+  },
+});
+
+if (res.refreshedSession) await vault.save(userId, encrypt(res.refreshedSession)); // rotated cookies
+if (res.ok) ledger.record({ claim: res.platformPostId, url: res.platformPostUrl });
+if (res.needsReauth) notify(userId, 'Please sign in to the expense portal again');
+if (res.uncertain) queueManualReview(jobId);   // submitted but unconfirmed — never retry blindly
+```
+
+### Library-only (no HTTP)
+
+```ts
+import { AgentPoster, SteelSessionProvider } from '@praveen-palanisamy/agent-browser-runtime';
+
+const poster = new AgentPoster(
+  new SteelSessionProvider({ baseUrl: 'http://steel:3000' }),
+  myEncryptedStore
+).register(expensePortal);
+await poster.post({ workspaceId, accountId, platform: 'expense-portal', content: { text, mediaUrls } });
+```
+
+## Contracts
+
+| Contract | Responsibility | Provided implementations |
+|----------|----------------|--------------------------|
+| `SessionStore` | Persist/load `AgentSessionState` (Playwright `storageState` + UA + timestamps) | `InMemorySessionStore`; you implement the encrypted one |
+| `SessionProvider` | Turn a stored state into a live `BrowserContext` | `LocalBrowserSessionProvider`, `CdpSessionProvider`, `SteelSessionProvider`, `KernelSessionProvider` |
+| `WebPostStrategy` | Drive one platform: `validate`, `isAuthenticated`, `post` | yours (`examples/demo-strategy`) |
+
+`AgentPostResult` is deliberately rich: `ok`, `platformPostId/Url`, `verification: 'toast' | 'timeline'`, `needsReauth`, `uncertain`, `failureStage: 'precheck' | 'auth' | 'compose' | 'media' | 'submit' | 'verify'`, and an optional redacted `screenshotBase64` for your private artifact storage.
+
+## Runner service
+
+| Route | Purpose |
+|-------|---------|
+| `POST /v1/post` | Publish with an injected session → result + `refreshedSession` |
+| `POST /v1/probe` | Cheap auth check; refreshes cookies |
+| `POST /v1/capture/start` | Open an interactive browser → `captureId`, `liveViewUrl`, `expiresAt` |
+| `POST /v1/capture/finish` · `/cancel` | Export the session / discard |
+| `GET /live/{captureId}/…` | Proxied Steel live view (HTTP + WebSocket, iframe-safe) |
+| `GET /healthz` | Liveness |
+
+All `/v1/*` routes require `Authorization: Bearer $AGENT_RUNNER_TOKEN`. Live-view paths are guarded by the unguessable capture id and TTL.
+
+Configuration is environment-driven ([`.env.example`](.env.example)). Job and capture providers are independent: run headless jobs in parallel on local Chromium while captures use Steel's live view, or route everything to Kernel for burst capacity. Steel OSS serves one session at a time; `SerializedProvider` queues instead of failing.
+
+## Deploy
+
+Pick the channel that fits your stack — all three are published from every release:
+
+| Channel | Use it when |
+|---------|-------------|
+| **npm** `@praveen-palanisamy/agent-browser-runtime` | you embed the library or the Playwright-free client in your app |
+| **GHCR** `ghcr.io/praveen-palanisamy/agent-browser-runtime` | you run the HTTP runner service (Chromium included) |
+| **GitHub Action** `praveen-palanisamy/agent-browser-runtime@v0` | you want session probes or jobs straight from CI — see [`docs/GITHUB_ACTION.md`](docs/GITHUB_ACTION.md) |
+
+```yaml
+- uses: praveen-palanisamy/agent-browser-runtime@v0
+  with:
+    command: probe
+    platform: expense-portal
+    strategies: ./automation/strategies.js
+    session: ${{ secrets.EXPENSE_PORTAL_SESSION }}
+```
+
+- **Local**: `docker compose up` (Steel + runtime; mount strategies via `STRATEGIES_DIR`).
+- **Container**: `ghcr.io/praveen-palanisamy/agent-browser-runtime` — extend it with your strategies module (see [`Dockerfile`](Dockerfile)). The Playwright base image and `playwright-core` are pinned to the same version so no browser downloads happen at runtime.
+- **Cloud Run / ECS / Nomad**: run the runtime with Steel as a sidecar; pin to one instance per active interactive capture (captures are stateful), scale headless jobs freely. See [`docs/DEPLOY.md`](docs/DEPLOY.md).
+
+## Security posture
+
+- The runtime never persists sessions; your encrypted store is the source of truth. Steel/Kernel profiles are disposable caches.
+- Fresh browser context per job, disposed after use; no cross-tenant state.
+- Bearer-token auth on every API route; live view requires an active capture id and expires.
+- Failure screenshots are returned to the caller for private storage — never served to end users by the runtime.
+- Treat `AgentSessionState` with password-equivalent sensitivity. See [`SECURITY.md`](SECURITY.md).
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — contracts, lifecycle, verification model
+- [`docs/DEPLOY.md`](docs/DEPLOY.md) — providers, environment, Cloud Run / compose patterns, distribution channels
+- [`docs/GITHUB_ACTION.md`](docs/GITHUB_ACTION.md) — run probes and jobs from GitHub Actions
+- [`docs/AGENTS.md`](docs/AGENTS.md) — notes for coding agents and LLM tool builders
+- [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Development
+
+```bash
+npm install
+npm run ci:check       # lint + typecheck + unit tests + pin check (what CI runs)
+npm run test:browser   # real Chromium smoke (npm run browsers:install first)
+```
+
+## License & attribution
+
+MIT © [Praveen Palanisamy](https://github.com/praveen-palanisamy). If ABR is useful to you, keep the link back to the [source repository](https://github.com/praveen-palanisamy/agent-browser-runtime) in your forks and derived work, and cite it as:
+
+```bibtex
+@software{palanisamy_agent_browser_runtime,
+  author = {Palanisamy, Praveen},
+  title  = {Agent Browser Runtime (ABR): stateful, secure browser-session execution for agents},
+  url    = {https://github.com/praveen-palanisamy/agent-browser-runtime},
+  license = {MIT}
+}
+```

package/action.yml

@@ -0,0 +1,185 @@
+name: "Agent Browser Runtime (ABR)"
+description: >-
+  Run authenticated browser jobs as the user from CI: probe a stored session or
+  execute a WebPostStrategy with it. Self-hosted.
+author: "Praveen Palanisamy"
+branding:
+  icon: "globe"
+  color: "purple"
+
+inputs:
+  command:
+    description: "`probe` (is the session still authenticated?) or `post` (run a job)"
+    required: false
+    default: "probe"
+  platform:
+    description: "Platform id handled by one of the strategies in `strategies`"
+    required: true
+  session:
+    description: >-
+      Serialized AgentSessionState JSON. Store it as a repository secret and
+      pass the secret here; alternatively set `session-file`.
+    required: false
+    default: ""
+  session-file:
+    description: "Path to a file containing AgentSessionState JSON (alternative to `session`)"
+    required: false
+    default: ""
+  strategies:
+    description: >-
+      Path (relative to the workspace) of a CommonJS/ESM module exporting
+      WebPostStrategy[]. Defaults to the bundled example strategy.
+    required: false
+    default: ""
+  text:
+    description: "Post text (`post` only)"
+    required: false
+    default: ""
+  media:
+    description: "Comma-separated media URLs (`post` only)"
+    required: false
+    default: ""
+  link:
+    description: "Link to attach (`post` only)"
+    required: false
+    default: ""
+  content-file:
+    description: "Path to an AgentPostContent JSON file (overrides text/media/link)"
+    required: false
+    default: ""
+  workspace:
+    description: "Workspace id used for the job identity"
+    required: false
+    default: "github-actions"
+  account:
+    description: "Account id used for the job identity"
+    required: false
+    default: "default"
+  session-out:
+    description: "Where to write the refreshed session state (persist it back to your vault)"
+    required: false
+    default: ".abr/session.refreshed.json"
+  result-out:
+    description: "Where to write the JSON result"
+    required: false
+    default: ".abr/result.json"
+  fail-on-reauth:
+    description: "Fail the step when the session needs re-authentication"
+    required: false
+    default: "true"
+  pacing:
+    description: "Apply human-pace jitter before acting (`true`/`false`)"
+    required: false
+    default: "true"
+  node-version:
+    description: "Node.js version to run the runtime with"
+    required: false
+    default: "24"
+
+outputs:
+  result-file:
+    description: "Path of the JSON result"
+    value: ${{ steps.run.outputs.result-file }}
+  session-file:
+    description: "Path of the refreshed session (may not exist if nothing changed)"
+    value: ${{ steps.run.outputs.session-file }}
+  ok:
+    description: "`true` when a `post` job verified success"
+    value: ${{ steps.run.outputs.ok }}
+  authenticated:
+    description: "`true` when the session is still signed in (`probe`, or auth stage of `post`)"
+    value: ${{ steps.run.outputs.authenticated }}
+  needs-reauth:
+    description: "`true` when the user must sign in again"
+    value: ${{ steps.run.outputs.needs-reauth }}
+  uncertain:
+    description: "`true` when the action ran but could not be verified — never retry blindly"
+    value: ${{ steps.run.outputs.uncertain }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v7
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    - name: Install Agent Browser Runtime (from this action's ref)
+      shell: bash
+      run: |
+        set -euo pipefail
+        cd "${GITHUB_ACTION_PATH}"
+        npm ci --no-audit --no-fund --ignore-scripts
+        npm run build
+        npx playwright-core install --with-deps chromium
+
+    - name: Run ABR job
+      id: run
+      shell: bash
+      env:
+        ABR_SESSION_JSON: ${{ inputs.session }}
+        AGENT_RUNNER_PACING: ${{ inputs.pacing }}
+      run: |
+        set -euo pipefail
+        ABR="node ${GITHUB_ACTION_PATH}/dist/cli.js"
+        mkdir -p "$(dirname "${{ inputs.session-out }}")" "$(dirname "${{ inputs.result-out }}")"
+
+        if [ -n "${{ inputs.session-file }}" ]; then
+          SESSION_FILE="${{ inputs.session-file }}"
+        elif [ -n "$ABR_SESSION_JSON" ]; then
+          SESSION_FILE="$(mktemp)"
+          printf '%s' "$ABR_SESSION_JSON" > "$SESSION_FILE"
+        else
+          echo "::error::Provide either 'session' or 'session-file'"; exit 1
+        fi
+
+        STRATEGIES="${{ inputs.strategies }}"
+        if [ -z "$STRATEGIES" ]; then
+          STRATEGIES="${GITHUB_ACTION_PATH}/examples/demo-strategy/index.js"
+        fi
+
+        CONTENT_FLAGS=()
+        if [ "${{ inputs.command }}" = "post" ]; then
+          if [ -n "${{ inputs.content-file }}" ]; then
+            CONTENT_FLAGS=(--content "${{ inputs.content-file }}")
+          else
+            CONTENT_FLAGS=(--text "${{ inputs.text }}")
+            [ -n "${{ inputs.media }}" ] && CONTENT_FLAGS+=(--media "${{ inputs.media }}")
+            [ -n "${{ inputs.link }}" ] && CONTENT_FLAGS+=(--link "${{ inputs.link }}")
+          fi
+        fi
+
+        set +e
+        $ABR "${{ inputs.command }}" --local \
+          --strategies "$STRATEGIES" \
+          --platform "${{ inputs.platform }}" \
+          --session "$SESSION_FILE" \
+          --workspace "${{ inputs.workspace }}" --account "${{ inputs.account }}" \
+          --session-out "${{ inputs.session-out }}" \
+          --out "${{ inputs.result-out }}" \
+          "${CONTENT_FLAGS[@]}"
+        CODE=$?
+        set -e
+
+        [ -n "$ABR_SESSION_JSON" ] && rm -f "$SESSION_FILE"
+
+        RESULT="${{ inputs.result-out }}"
+        echo "result-file=$RESULT" >> "$GITHUB_OUTPUT"
+        echo "session-file=${{ inputs.session-out }}" >> "$GITHUB_OUTPUT"
+        if [ -f "$RESULT" ]; then
+          node -e '
+            const r = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+            const out = [
+              ["ok", r.ok === true],
+              ["authenticated", r.authenticated === true || (r.ok === true) || (r.ok === false && r.failureStage && r.failureStage !== "auth" && r.failureStage !== "precheck")],
+              ["needs-reauth", r.needsReauth === true || (r.authenticated === false)],
+              ["uncertain", r.uncertain === true],
+            ];
+            require("fs").appendFileSync(process.env.GITHUB_OUTPUT, out.map(([k, v]) => `${k}=${v}\n`).join(""));
+          ' "$RESULT"
+        fi
+
+        if [ "$CODE" -eq 2 ] && [ "${{ inputs.fail-on-reauth }}" != "true" ] && grep -q '"needsReauth": true\|"authenticated": false' "$RESULT" 2>/dev/null; then
+          echo "::warning::Session needs re-authentication (fail-on-reauth=false)"; exit 0
+        fi
+        exit $CODE

package/dist/attribution.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project identity. Surfaced in the CLI banner, the runner's `Server` header
+ * and `/healthz` so deployments (and forks) always point back to the source.
+ */
+export declare const PROJECT: {
+    readonly name: 'agent-browser-runtime';
+    readonly shortName: 'ABR';
+    readonly npm: '@praveen-palanisamy/agent-browser-runtime';
+    readonly author: 'Praveen Palanisamy';
+    readonly repository: 'https://github.com/praveen-palanisamy/agent-browser-runtime';
+    readonly homepage: 'https://praveen-palanisamy.github.io/agent-browser-runtime/';
+    readonly image: 'ghcr.io/praveen-palanisamy/agent-browser-runtime';
+    readonly license: 'MIT';
+};
+/**
+ * Version from the nearest package.json (works from src/ and dist/, and from
+ * vendored/forked copies where the package name differs).
+ */
+export declare function packageVersion(): string;
+/** e.g. `agent-browser-runtime/0.1.0 (+https://github.com/...)` */
+export declare function userAgentString(): string;
+//# sourceMappingURL=attribution.d.ts.map

package/dist/attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,eAAO,MAAM,OAAO;aAClB,IAAI,EAAE,uBAAuB;aAC7B,SAAS,EAAE,KAAK;aAChB,GAAG,EAAE,2CAA2C;aAChD,MAAM,EAAE,oBAAoB;aAC5B,UAAU,EAAE,6DAA6D;aACzE,QAAQ,EAAE,6DAA6D;aACvE,KAAK,EAAE,kDAAkD;aACzD,OAAO,EAAE,KAAK;CACN,CAAC;AAIX;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAmBvC;AAED,mEAAmE;AACnE,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/attribution.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Project identity. Surfaced in the CLI banner, the runner's `Server` header
+ * and `/healthz` so deployments (and forks) always point back to the source.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT = void 0;
+exports.packageVersion = packageVersion;
+exports.userAgentString = userAgentString;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+exports.PROJECT = {
+    name: 'agent-browser-runtime',
+    shortName: 'ABR',
+    npm: '@praveen-palanisamy/agent-browser-runtime',
+    author: 'Praveen Palanisamy',
+    repository: 'https://github.com/praveen-palanisamy/agent-browser-runtime',
+    homepage: 'https://praveen-palanisamy.github.io/agent-browser-runtime/',
+    image: 'ghcr.io/praveen-palanisamy/agent-browser-runtime',
+    license: 'MIT',
+};
+let cachedVersion;
+/**
+ * Version from the nearest package.json (works from src/ and dist/, and from
+ * vendored/forked copies where the package name differs).
+ */
+function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    let fallback;
+    for (const rel of ['../package.json', '../../package.json']) {
+        try {
+            const raw = (0, node_fs_1.readFileSync)(node_path_1.default.join(__dirname, rel), 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed.version)
+                continue;
+            if (parsed.name === exports.PROJECT.npm) {
+                cachedVersion = parsed.version;
+                return cachedVersion;
+            }
+            fallback ??= parsed.version;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    cachedVersion = fallback ?? '0.0.0';
+    return cachedVersion;
+}
+/** e.g. `agent-browser-runtime/0.1.0 (+https://github.com/...)` */
+function userAgentString() {
+    return `${exports.PROJECT.name}/${packageVersion()} (+${exports.PROJECT.repository})`;
+}
+//# sourceMappingURL=attribution.js.map

package/dist/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;AAEH,qCAAuC;AACvC,0DAA6B;AAEhB,QAAA,OAAO,GAAG;IACrB,IAAI,EAAE,uBAAuB;IAC7B,SAAS,EAAE,KAAK;IAChB,GAAG,EAAE,2CAA2C;IAChD,MAAM,EAAE,oBAAoB;IAC5B,UAAU,EAAE,6DAA6D;IACzE,QAAQ,EAAE,6DAA6D;IACvE,KAAK,EAAE,kDAAkD;IACzD,OAAO,EAAE,KAAK;CACN,CAAC;AAEX,IAAI,aAAiC,CAAC;AAEtC;;;GAGG;AACH;IACE,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,QAA4B,CAAC;IACjC,KAAK,MAAM,GAAG,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAA,sBAAY,EAAC,mBAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;YAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwC,CAAC;YACtE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,SAAS;YAC9B,IAAI,MAAM,CAAC,IAAI,KAAK,QAAA,OAAO,CAAC,GAAG,EAAE,CAAC;gBAChC,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC;gBAC/B,OAAO,aAAa,CAAC;YACvB,CAAC;YACD,QAAQ,KAAK,MAAM,CAAC,OAAO,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,qBAAqB;QACvB,CAAC;IACH,CAAC;IACD,aAAa,GAAG,QAAQ,IAAI,OAAO,CAAC;IACpC,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,mEAAmE;AACnE;IACE,OAAO,GAAG,QAAA,OAAO,CAAC,IAAI,IAAI,cAAc,EAAE,MAAM,QAAA,OAAO,CAAC,UAAU,GAAG,CAAC;AACxE,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * agent-browser-runtime (ABR) CLI
+ *
+ *   agent-browser-runtime serve  --strategies ./dist/strategies.js
+ *   agent-browser-runtime health [--url http://localhost:8080]
+ *   agent-browser-runtime probe  --platform <id> --session ./session.json [--url … --token … | --local --strategies …]
+ *   agent-browser-runtime post   --platform <id> --session ./session.json --text "…" [--media url,…] [--link url]
+ *                                [--url … --token … | --local --strategies …] [--session-out file] [--out file]
+ *
+ * `serve` loads a CommonJS/ESM module whose default export (or `strategies`
+ * export) is an array of WebPostStrategy instances, then starts the runner
+ * using environment configuration (see service/config.ts).
+ *
+ * `probe` / `post` talk to a running runner by default. With `--local` they
+ * run in-process against local Chromium instead (used by the GitHub Action
+ * and for one-off jobs), which requires `--strategies`.
+ */
+import type { WebPostStrategy } from './core/types';
+export declare function loadStrategies(spec: string): Promise<WebPostStrategy[]>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,KAAK,EAIV,eAAe,EAChB,MAAM,cAAc,CAAC;AA8BtB,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAiB7E"}