@vostride/agent-qa-plugin-hyperbrowser 0.0.0-stage → 0.3.2

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Pranshu Chittora
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/NOTICE.md

@@ -0,0 +1,11 @@
+# agent-qa Notice
+
+agent-qa is provided by Pranshu Chittora.
+
+Copyright 2026 Pranshu Chittora
+
+agent-qa is licensed under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). See `LICENSE.md` for the full license terms.
+
+Under the Grant of Future License in `LICENSE.md`, each version of the Software is also granted under the Apache License, Version 2.0 effective on the second anniversary of the date that version was made available.
+
+Third-party dependencies are distributed under their own license terms. This notice covers agent-qa itself and does not replace or modify notices required by third-party dependency owners.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# @vostride/agent-qa-plugin-hyperbrowser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The agent-qa plugin for [Hyperbrowser](https://hyperbrowser.ai) cloud browsers. Before a web test
+connects, it creates a Hyperbrowser session and answers agent-qa with the session's CDP URL, and
+after the test it stops the session. Hyperbrowser runs Chromium only.
+
+## Install
+
+Install the plugin at exactly the version of agent-qa the project runs:
+
+```bash
+npm install --save-dev --save-exact @vostride/agent-qa-plugin-hyperbrowser@<agent-qa version>
+```
+
+`agent-qa plugins list` prints this line, with the version filled in, when the package is missing
+or its version differs from agent-qa's.
+
+## Configure
+
+```yaml
+plugins:
+  - name: hyperbrowser
+    package: "@vostride/agent-qa-plugin-hyperbrowser"
+    options:
+      apiKey: "{{secret:HYPERBROWSER_API_KEY}}"
+
+registry:
+  remotes:
+    - name: hyperbrowser
+      plugin: hyperbrowser
+    - name: hyperbrowser-unrecorded
+      plugin: hyperbrowser
+      settings:
+        recording: false
+```
+
+A test runs there with `use.browser.remote: hyperbrowser` in the config, a suite or the test.
+
+### Options
+
+Options belong to the `plugins` entry and describe the account.
+
+| Option   | Default                       | Meaning                                                                                                |
+| -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `apiKey` | -                             | The Hyperbrowser API key, a credential, required. Write it as a `{{secret:<name>}}` reference.         |
+| `apiUrl` | `https://api.hyperbrowser.ai` | Hyperbrowser's API. It must use `https://` with no user or password, unless it points at this machine. |
+
+The key is sent only as the `x-api-key` header. It never appears in a message, a log or a check
+line.
+
+### Settings
+
+Settings belong to each remote and describe one place.
+
+| Setting          | Default | Meaning                                                                                                                                                                        |
+| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `timeoutMinutes` | `720`   | Minutes before Hyperbrowser stops the session (1 to 720), always sent as `timeoutMinutes`. It overrides the team default in Hyperbrowser's settings.                           |
+| `recording`      | -       | Hyperbrowser's web recording, sent as `enableWebRecording` when set. Unset keeps the account's default, which records. `false` turns it off.                                   |
+| `stealth`        | `false` | Hyperbrowser's stealth mode, sent as `useStealth`.                                                                                                                             |
+| `proxy`          | `false` | Hyperbrowser's proxy: `true`, or `{ country, state, city }` with any of the three. Sent as `useProxy`, with `proxyCountry`, `proxyState` and `proxyCity` for the fields given. |
+| `solveCaptchas`  | `false` | Hyperbrowser's CAPTCHA solving, sent as `solveCaptchas`.                                                                                                                       |
+| `adblock`        | `false` | Hyperbrowser's ad blocking, sent as `adblock`.                                                                                                                                 |
+| `trackers`       | `false` | Hyperbrowser's tracker blocking, sent as `trackers`.                                                                                                                           |
+| `annoyances`     | `false` | Hyperbrowser's annoyance blocking, sent as `annoyances`.                                                                                                                       |
+| `acceptCookies`  | `false` | Hyperbrowser's automatic acceptance of cookie banners, sent as `acceptCookies`.                                                                                                |
+| `screen`         | -       | The browser screen, `{ width, height }` in pixels, sent as `screen`. Unset keeps Hyperbrowser's default.                                                                       |
+| `region`         | -       | The Hyperbrowser region, for example `us-east` or `europe-west`, sent as `region`.                                                                                             |
+| `profile`        | -       | A Hyperbrowser profile id, loaded read-only and sent as `profile: { id, persistChanges: false }`. Needs `context: reuse`.                                                      |
+| `extensions`     | -       | Hyperbrowser extension ids loaded into the browser, sent as `extensionIds`.                                                                                                    |
+| `extra`          | -       | Any other Hyperbrowser request field, merged last.                                                                                                                             |
+
+`agent-qa plugins describe hyperbrowser` prints the same tables from the schemas the package ships,
+and `--json` prints them as JSON.
+
+## How the request body is built
+
+The create request (`POST /api/session`) is built in this order, each part overriding the one
+before:
+
+1. the lifetime, `timeoutMinutes`;
+2. the features that change the page: stealth, proxies, CAPTCHA solving, ad, tracker and annoyance
+   blocking and cookie auto-accept. Each is sent off unless a setting turns it on, because a test
+   should see the app the way its users do;
+3. the proxy fields: `proxy: true` sends `useProxy: true`, and a proxy object also sends
+   `proxyCountry`, `proxyState` and `proxyCity` for the fields it gives;
+4. the other settings above, in Hyperbrowser's field names, each only when it is set;
+5. `extra`, last, so a pass-through key overrides both a default and a setting.
+
+For example, `settings: { extra: { useUltraStealth: true } }` asks for Hyperbrowser's Enterprise
+stealth mode. Hyperbrowser's own proxy servers for Enterprise accounts go through `extra` too.
+agent-qa refuses a password there unless it is a `{{secret:<name>}}` reference:
+
+```yaml
+settings:
+  extra:
+    proxyServer: "http://proxy.example.com:8080"
+    proxyServerUsername: "<proxy user>"
+    proxyServerPassword: "{{secret:HYPERBROWSER_PROXY_PASSWORD}}"
+```
+
+Proxies and CAPTCHA solving need a paid Hyperbrowser plan. When a feature is not on the plan,
+Hyperbrowser refuses the create, as described under Failures.
+
+## Lifetime and disconnects
+
+By default the plugin asks for a 720-minute session, the longest Hyperbrowser allows.
+`timeoutMinutes` lowers it; a value outside 1 to 720 is refused with path
+`settings.timeoutMinutes` before any session is created.
+
+The plugin never asks Hyperbrowser for keep-alive, so Hyperbrowser stops a session whose connection
+drops. A session left behind by a killed job, where agent-qa and the plugin die together, stops
+when its connection does. A session whose create was still in flight when the job was killed was
+never connected and has no idle timeout, so it runs until `timeoutMinutes`; lower
+`timeoutMinutes` to bound it. agent-qa also stops every session itself after the test; the
+lifetime only bounds a session that agent-qa could not stop.
+
+## Recording
+
+Hyperbrowser records sessions by default and keeps the replay on its dashboard, behind its login.
+agent-qa's masking does not reach that replay, so a secret a test types may show in it. Set
+`recording: false` on a remote to turn recording off for its sessions:
+
+```yaml
+registry:
+  remotes:
+    - name: hyperbrowser-unrecorded
+      plugin: hyperbrowser
+      settings:
+        recording: false
+```
+
+Video replay is off unless you ask for it with `extra: { enableVideoWebRecording: true }`. It needs
+web recording, so do not combine it with `recording: false`.
+
+## Profiles
+
+`profile` loads a Hyperbrowser profile by id, and the plugin sends `persistChanges: false`, so
+nothing a test does is saved back. A profile lives in the browser's first context, so the remote
+needs `context: reuse`. Without it, the remote is refused with kind `refused` and path
+`settings.profile`.
+
+## Failures
+
+| Hyperbrowser answer   | Kind          |
+| --------------------- | ------------- |
+| no answer             | `unreachable` |
+| `401`                 | `auth`        |
+| `429`                 | `capacity`    |
+| any other non-success | `refused`     |
+
+Each failure is one line naming the status, the request and Hyperbrowser's reason, with the
+`Retry-After` wait on a `429`. A `403` most often means a feature is not on the plan, for example
+`Hyperbrowser answered 403 to POST /api/session: Proxy usage requires a paid plan`; turn the
+setting off or change the plan.
+
+Hyperbrowser chooses the session id, so a create that fails has no session to stop. When
+Hyperbrowser answers a session without a `wsEndpoint`, the remote is refused and agent-qa stops
+the session by the id it answered.
+
+On release, `2xx` and `404` both count as stopped, so stopping a session Hyperbrowser already
+stopped after a disconnect succeeds.
+
+## Links and the live view
+
+The session link is the session's page in Hyperbrowser's dashboard, which sits behind
+Hyperbrowser's login and shows the replay. The plugin returns it only when it is an `https://` URL.
+
+Hyperbrowser's live view URL and the session token let anyone who has them watch and drive the
+session, so both are credentials: the plugin adds them, with the CDP URL, to the values agent-qa
+masks, and never returns either as the link.
+
+## Account check
+
+`agent-qa doctor` runs the plugin's `check`, which reads the active sessions with
+`GET /api/sessions?status=active&page=1` and opens none:
+
+- An accepted key reads `the API key was accepted`, followed by the number of active sessions
+  when Hyperbrowser gives it, for example `2 active sessions`.
+- A refused key warns `the API key was refused`.
+- Any other failure warns with its one line, for example
+  `Hyperbrowser could not be reached at <apiUrl>`.
+
+## License
+
+FSL-1.1-ALv2. See `LICENSE.md` and `NOTICE.md` in the package.

package/dist/main.js

@@ -0,0 +1,7 @@
+import { t as plugin_default } from "./plugin-6PEkbMWx.js";
+import { runPlugin } from "@vostride/agent-qa-plugin-kit";
+// src/main.ts
+runPlugin(plugin_default);
+export {};
+
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","names":["plugin"],"sources":["../src/main.ts"],"sourcesContent":["import { runPlugin } from '@vostride/agent-qa-plugin-kit'\nimport plugin from './plugin.js'\n\nrunPlugin(plugin)\n"],"mappings":";;;AAGA,UAAUA,cAAM"}

package/dist/options.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "credential": true,
+      "description": "The Hyperbrowser API key"
+    },
+    "apiUrl": {
+      "default": "https://api.hyperbrowser.ai",
+      "description": "Hyperbrowser's API, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "required": [
+    "apiKey"
+  ],
+  "additionalProperties": false
+}

package/dist/plugin-6PEkbMWx.js

@@ -0,0 +1,198 @@
+import { PluginError, checkEndpoints, createVendorApi, credential, definePlugin, z } from "@vostride/agent-qa-plugin-kit";
+// src/hyperbrowser-api.ts
+const HyperbrowserSessionSchema = z.object({
+	id: z.string().min(1),
+	wsEndpoint: z.string().min(1),
+	liveUrl: z.string().min(1).optional(),
+	token: z.string().min(1).optional(),
+	sessionUrl: z.string().min(1).optional()
+});
+function createHyperbrowserApi(input) {
+	const api = createVendorApi({
+		vendor: "Hyperbrowser",
+		baseUrl: input.apiUrl,
+		headers: { "x-api-key": input.apiKey }
+	});
+	return {
+		async createSession(body) {
+			const response = await api.send("POST", "api/session", {
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json"
+				},
+				body: JSON.stringify(body)
+			});
+			if (!response.ok) throw await api.failure(response, "POST /api/session");
+			return api.json(response);
+		},
+		async stop(id, signal) {
+			const response = await api.send("PUT", `api/session/${encodeURIComponent(id)}/stop`, {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (response.ok || response.status === 404) {
+				await response.body?.cancel();
+				return;
+			}
+			throw await api.failure(response, "PUT /api/session/{id}/stop");
+		},
+		async activeSessions(signal) {
+			const response = await api.send("GET", "api/sessions?status=active&page=1", {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (!response.ok) throw await api.failure(response, "GET /api/sessions");
+			return api.json(response);
+		}
+	};
+}
+// src/plugin.ts
+const options = z.strictObject({
+	apiKey: credential("The Hyperbrowser API key"),
+	apiUrl: z.url().default("https://api.hyperbrowser.ai").describe("Hyperbrowser's API, https:// unless it points at this machine")
+});
+const settings = z.strictObject({
+	timeoutMinutes: z.int().min(1).max(720).default(720).describe("Minutes before Hyperbrowser stops the session"),
+	recording: z.boolean().optional().describe("Hyperbrowser's web recording; unset keeps the account's default, which records"),
+	stealth: z.boolean().default(false).describe("Hyperbrowser's stealth mode, which changes what pages see"),
+	proxy: z.union([z.boolean(), z.strictObject({
+		country: z.string().min(1).optional(),
+		state: z.string().min(1).optional(),
+		city: z.string().min(1).optional()
+	})]).default(false).describe("Hyperbrowser's proxy, true or { country, state, city }"),
+	solveCaptchas: z.boolean().default(false).describe("Hyperbrowser's CAPTCHA solving"),
+	adblock: z.boolean().default(false).describe("Hyperbrowser's ad blocking"),
+	trackers: z.boolean().default(false).describe("Hyperbrowser's tracker blocking"),
+	annoyances: z.boolean().default(false).describe("Hyperbrowser's annoyance blocking"),
+	acceptCookies: z.boolean().default(false).describe("Hyperbrowser's automatic acceptance of cookie banners"),
+	screen: z.strictObject({
+		width: z.int().positive(),
+		height: z.int().positive()
+	}).optional().describe("The browser screen size in pixels"),
+	region: z.string().min(1).optional().describe("The Hyperbrowser region the session runs in"),
+	profile: z.string().min(1).optional().describe("A Hyperbrowser profile id loaded read-only; needs context: reuse on the remote"),
+	extensions: z.array(z.string().min(1)).min(1).optional().describe("Hyperbrowser extension ids loaded into the browser"),
+	extra: z.record(z.string(), z.unknown()).optional().describe("Fields merged last into the session create request, overriding the rest")
+});
+function checkSettings(input, session) {
+	if (input.profile !== void 0 && (session.platform !== "web" || session.context !== "reuse")) throw new PluginError("profile loads only into a reused context; set context: reuse on the remote.", {
+		kind: "refused",
+		path: "settings.profile"
+	});
+}
+function proxyBody(proxy) {
+	if (typeof proxy === "boolean") return { useProxy: proxy };
+	return {
+		useProxy: true,
+		...proxy.country === void 0 ? {} : { proxyCountry: proxy.country },
+		...proxy.state === void 0 ? {} : { proxyState: proxy.state },
+		...proxy.city === void 0 ? {} : { proxyCity: proxy.city }
+	};
+}
+function createBody(input) {
+	return {
+		timeoutMinutes: input.timeoutMinutes,
+		useStealth: input.stealth,
+		...proxyBody(input.proxy),
+		solveCaptchas: input.solveCaptchas,
+		adblock: input.adblock,
+		trackers: input.trackers,
+		annoyances: input.annoyances,
+		acceptCookies: input.acceptCookies,
+		...input.recording === void 0 ? {} : { enableWebRecording: input.recording },
+		...input.screen === void 0 ? {} : { screen: input.screen },
+		...input.region === void 0 ? {} : { region: input.region },
+		...input.profile === void 0 ? {} : { profile: {
+			id: input.profile,
+			persistChanges: false
+		} },
+		...input.extensions === void 0 ? {} : { extensionIds: input.extensions },
+		...input.extra
+	};
+}
+function sessionIdOf(answer) {
+	if (typeof answer !== "object" || answer === null || !("id" in answer)) return void 0;
+	const id = answer.id;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function dashboardLink(url) {
+	if (url === void 0) return void 0;
+	return URL.parse(url)?.protocol === "https:" ? url : void 0;
+}
+const HandleSchema = z.object({ sessionId: z.string().min(1) });
+const ActiveSessionsSchema = z.object({ totalCount: z.int().nonnegative() });
+function activeLine(count) {
+	return count === 1 ? "1 active session" : `${String(count)} active sessions`;
+}
+function failureLine(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+var plugin_default = definePlugin({
+	options,
+	settings,
+	serves: ["cdp"],
+	skill: "./skill",
+	initialize({ options }) {
+		checkEndpoints(options, [{
+			path: "apiUrl",
+			scheme: "https"
+		}]);
+	},
+	async check({ options }, ctx) {
+		let answer;
+		try {
+			answer = await createHyperbrowserApi(options).activeSessions(ctx.signal);
+		} catch (error) {
+			if (error instanceof PluginError && error.kind === "auth") return {
+				state: "warn",
+				lines: ["the API key was refused"]
+			};
+			return {
+				state: "warn",
+				lines: [failureLine(error)]
+			};
+		}
+		const count = ActiveSessionsSchema.safeParse(answer);
+		return {
+			state: "ok",
+			lines: ["the API key was accepted", ...count.success ? [activeLine(count.data.totalCount)] : []]
+		};
+	},
+	async acquire({ options, settings, session }) {
+		if (session.platform !== "web" || session.engine !== "chromium") {
+			const what = session.platform === "web" ? session.engine : session.platform;
+			throw new PluginError(`Hyperbrowser runs Chromium web sessions only, not ${what}.`, { kind: "refused" });
+		}
+		checkSettings(settings, session);
+		const created = await createHyperbrowserApi(options).createSession(createBody(settings));
+		const answer = HyperbrowserSessionSchema.safeParse(created);
+		if (!answer.success) {
+			const sessionId = sessionIdOf(created);
+			throw new PluginError(`Hyperbrowser answered a session without ${sessionId === void 0 ? "an id" : "a usable wsEndpoint"}.`, {
+				kind: "refused",
+				...sessionId === void 0 ? {} : { handle: { sessionId } }
+			});
+		}
+		const { id, wsEndpoint, liveUrl, token, sessionUrl } = answer.data;
+		const link = dashboardLink(sessionUrl);
+		return {
+			handle: { sessionId: id },
+			protocol: "cdp",
+			url: wsEndpoint,
+			mask: [
+				wsEndpoint,
+				liveUrl,
+				token
+			].filter((value) => value !== void 0),
+			...link === void 0 ? {} : { link }
+		};
+	},
+	async release({ options, handle }, ctx) {
+		const parsed = HandleSchema.safeParse(handle);
+		if (!parsed.success) throw new PluginError("A Hyperbrowser handle names its session by sessionId.", { kind: "refused" });
+		await createHyperbrowserApi(options).stop(parsed.data.sessionId, ctx.signal);
+	}
+});
+export { plugin_default as t };
+
+//# sourceMappingURL=plugin-6PEkbMWx.js.map

package/dist/plugin-6PEkbMWx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-6PEkbMWx.js","names":[],"sources":["../src/hyperbrowser-api.ts","../src/plugin.ts"],"sourcesContent":["import { createVendorApi, z } from '@vostride/agent-qa-plugin-kit'\n\nexport const HyperbrowserSessionSchema = z.object({\n  id: z.string().min(1),\n  wsEndpoint: z.string().min(1),\n  liveUrl: z.string().min(1).optional(),\n  token: z.string().min(1).optional(),\n  sessionUrl: z.string().min(1).optional(),\n})\n\ninterface HyperbrowserApiInput {\n  apiUrl: string\n  apiKey: string\n}\n\nexport interface HyperbrowserApi {\n  createSession(body: Record<string, unknown>): Promise<unknown>\n  stop(id: string, signal?: AbortSignal): Promise<void>\n  activeSessions(signal?: AbortSignal): Promise<unknown>\n}\n\nexport function createHyperbrowserApi(input: HyperbrowserApiInput): HyperbrowserApi {\n  const api = createVendorApi({\n    vendor: 'Hyperbrowser',\n    baseUrl: input.apiUrl,\n    headers: { 'x-api-key': input.apiKey },\n  })\n\n  return {\n    async createSession(body) {\n      const response = await api.send('POST', 'api/session', {\n        headers: { 'content-type': 'application/json', accept: 'application/json' },\n        body: JSON.stringify(body),\n      })\n      if (!response.ok) throw await api.failure(response, 'POST /api/session')\n      return api.json(response)\n    },\n\n    async stop(id, signal) {\n      const response = await api.send('PUT', `api/session/${encodeURIComponent(id)}/stop`, {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (response.ok || response.status === 404) {\n        await response.body?.cancel()\n        return\n      }\n      throw await api.failure(response, 'PUT /api/session/{id}/stop')\n    },\n\n    async activeSessions(signal) {\n      const response = await api.send('GET', 'api/sessions?status=active&page=1', {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (!response.ok) throw await api.failure(response, 'GET /api/sessions')\n      return api.json(response)\n    },\n  }\n}\n","import {\n  checkEndpoints,\n  credential,\n  definePlugin,\n  PluginError,\n  z,\n  type AcquireInput,\n} from '@vostride/agent-qa-plugin-kit'\nimport { createHyperbrowserApi, HyperbrowserSessionSchema } from './hyperbrowser-api.js'\n\nconst HYPERBROWSER_API_URL = 'https://api.hyperbrowser.ai'\n\nconst options = z.strictObject({\n  apiKey: credential('The Hyperbrowser API key'),\n  apiUrl: z\n    .url()\n    .default(HYPERBROWSER_API_URL)\n    .describe(\"Hyperbrowser's API, https:// unless it points at this machine\"),\n})\n\nconst settings = z.strictObject({\n  timeoutMinutes: z\n    .int()\n    .min(1)\n    .max(720)\n    .default(720)\n    .describe('Minutes before Hyperbrowser stops the session'),\n  recording: z\n    .boolean()\n    .optional()\n    .describe(\"Hyperbrowser's web recording; unset keeps the account's default, which records\"),\n  stealth: z\n    .boolean()\n    .default(false)\n    .describe(\"Hyperbrowser's stealth mode, which changes what pages see\"),\n  proxy: z\n    .union([\n      z.boolean(),\n      z.strictObject({\n        country: z.string().min(1).optional(),\n        state: z.string().min(1).optional(),\n        city: z.string().min(1).optional(),\n      }),\n    ])\n    .default(false)\n    .describe(\"Hyperbrowser's proxy, true or { country, state, city }\"),\n  solveCaptchas: z.boolean().default(false).describe(\"Hyperbrowser's CAPTCHA solving\"),\n  adblock: z.boolean().default(false).describe(\"Hyperbrowser's ad blocking\"),\n  trackers: z.boolean().default(false).describe(\"Hyperbrowser's tracker blocking\"),\n  annoyances: z.boolean().default(false).describe(\"Hyperbrowser's annoyance blocking\"),\n  acceptCookies: z\n    .boolean()\n    .default(false)\n    .describe(\"Hyperbrowser's automatic acceptance of cookie banners\"),\n  screen: z\n    .strictObject({ width: z.int().positive(), height: z.int().positive() })\n    .optional()\n    .describe('The browser screen size in pixels'),\n  region: z.string().min(1).optional().describe('The Hyperbrowser region the session runs in'),\n  profile: z\n    .string()\n    .min(1)\n    .optional()\n    .describe('A Hyperbrowser profile id loaded read-only; needs context: reuse on the remote'),\n  extensions: z\n    .array(z.string().min(1))\n    .min(1)\n    .optional()\n    .describe('Hyperbrowser extension ids loaded into the browser'),\n  extra: z\n    .record(z.string(), z.unknown())\n    .optional()\n    .describe('Fields merged last into the session create request, overriding the rest'),\n})\n\ntype HyperbrowserSettings = z.output<typeof settings>\ntype Session = AcquireInput<unknown, unknown>['session']\n\nfunction checkSettings(input: HyperbrowserSettings, session: Session): void {\n  if (input.profile !== undefined && (session.platform !== 'web' || session.context !== 'reuse')) {\n    throw new PluginError(\n      'profile loads only into a reused context; set context: reuse on the remote.',\n      { kind: 'refused', path: 'settings.profile' },\n    )\n  }\n}\n\nfunction proxyBody(proxy: HyperbrowserSettings['proxy']): Record<string, unknown> {\n  if (typeof proxy === 'boolean') return { useProxy: proxy }\n  return {\n    useProxy: true,\n    ...(proxy.country === undefined ? {} : { proxyCountry: proxy.country }),\n    ...(proxy.state === undefined ? {} : { proxyState: proxy.state }),\n    ...(proxy.city === undefined ? {} : { proxyCity: proxy.city }),\n  }\n}\n\nfunction createBody(input: HyperbrowserSettings): Record<string, unknown> {\n  return {\n    timeoutMinutes: input.timeoutMinutes,\n    useStealth: input.stealth,\n    ...proxyBody(input.proxy),\n    solveCaptchas: input.solveCaptchas,\n    adblock: input.adblock,\n    trackers: input.trackers,\n    annoyances: input.annoyances,\n    acceptCookies: input.acceptCookies,\n    ...(input.recording === undefined ? {} : { enableWebRecording: input.recording }),\n    ...(input.screen === undefined ? {} : { screen: input.screen }),\n    ...(input.region === undefined ? {} : { region: input.region }),\n    ...(input.profile === undefined\n      ? {}\n      : { profile: { id: input.profile, persistChanges: false } }),\n    ...(input.extensions === undefined ? {} : { extensionIds: input.extensions }),\n    ...input.extra,\n  }\n}\n\nfunction sessionIdOf(answer: unknown): string | undefined {\n  if (typeof answer !== 'object' || answer === null || !('id' in answer)) return undefined\n  const id = answer.id\n  return typeof id === 'string' && id !== '' ? id : undefined\n}\n\nfunction dashboardLink(url: string | undefined): string | undefined {\n  if (url === undefined) return undefined\n  return URL.parse(url)?.protocol === 'https:' ? url : undefined\n}\n\nconst HandleSchema = z.object({ sessionId: z.string().min(1) })\n\nconst ActiveSessionsSchema = z.object({ totalCount: z.int().nonnegative() })\n\nfunction activeLine(count: number): string {\n  return count === 1 ? '1 active session' : `${String(count)} active sessions`\n}\n\nfunction failureLine(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nexport default definePlugin({\n  options,\n  settings,\n  serves: ['cdp'],\n  skill: './skill',\n\n  initialize({ options }) {\n    checkEndpoints(options, [{ path: 'apiUrl', scheme: 'https' }])\n  },\n\n  async check({ options }, ctx) {\n    let answer: unknown\n    try {\n      answer = await createHyperbrowserApi(options).activeSessions(ctx.signal)\n    } catch (error) {\n      if (error instanceof PluginError && error.kind === 'auth') {\n        return { state: 'warn', lines: ['the API key was refused'] }\n      }\n      return { state: 'warn', lines: [failureLine(error)] }\n    }\n    const count = ActiveSessionsSchema.safeParse(answer)\n    return {\n      state: 'ok',\n      lines: [\n        'the API key was accepted',\n        ...(count.success ? [activeLine(count.data.totalCount)] : []),\n      ],\n    }\n  },\n\n  async acquire({ options, settings, session }) {\n    if (session.platform !== 'web' || session.engine !== 'chromium') {\n      const what = session.platform === 'web' ? session.engine : session.platform\n      throw new PluginError(`Hyperbrowser runs Chromium web sessions only, not ${what}.`, {\n        kind: 'refused',\n      })\n    }\n    checkSettings(settings, session)\n    // The create is not cancelled: once Hyperbrowser has a session, the handle must come back to\n    // be stopped, and the kit releases a handle that arrives after a cancel was answered.\n    const created = await createHyperbrowserApi(options).createSession(createBody(settings))\n    const answer = HyperbrowserSessionSchema.safeParse(created)\n    if (!answer.success) {\n      const sessionId = sessionIdOf(created)\n      const missing = sessionId === undefined ? 'an id' : 'a usable wsEndpoint'\n      throw new PluginError(`Hyperbrowser answered a session without ${missing}.`, {\n        kind: 'refused',\n        ...(sessionId === undefined ? {} : { handle: { sessionId } }),\n      })\n    }\n    const { id, wsEndpoint, liveUrl, token, sessionUrl } = answer.data\n    const link = dashboardLink(sessionUrl)\n    return {\n      handle: { sessionId: id },\n      protocol: 'cdp' as const,\n      url: wsEndpoint,\n      mask: [wsEndpoint, liveUrl, token].filter((value) => value !== undefined),\n      ...(link === undefined ? {} : { link }),\n    }\n  },\n\n  async release({ options, handle }, ctx) {\n    const parsed = HandleSchema.safeParse(handle)\n    if (!parsed.success) {\n      throw new PluginError('A Hyperbrowser handle names its session by sessionId.', {\n        kind: 'refused',\n      })\n    }\n    await createHyperbrowserApi(options).stop(parsed.data.sessionId, ctx.signal)\n  },\n})\n"],"mappings":"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"}

package/dist/plugin.js

@@ -0,0 +1 @@
+export { t as default } from "./plugin-6PEkbMWx.js";

package/dist/settings.schema.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "timeoutMinutes": {
+      "default": 720,
+      "description": "Minutes before Hyperbrowser stops the session",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 720
+    },
+    "recording": {
+      "description": "Hyperbrowser's web recording; unset keeps the account's default, which records",
+      "type": "boolean"
+    },
+    "stealth": {
+      "default": false,
+      "description": "Hyperbrowser's stealth mode, which changes what pages see",
+      "type": "boolean"
+    },
+    "proxy": {
+      "default": false,
+      "description": "Hyperbrowser's proxy, true or { country, state, city }",
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "country": {
+              "type": "string",
+              "minLength": 1
+            },
+            "state": {
+              "type": "string",
+              "minLength": 1
+            },
+            "city": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "solveCaptchas": {
+      "default": false,
+      "description": "Hyperbrowser's CAPTCHA solving",
+      "type": "boolean"
+    },
+    "adblock": {
+      "default": false,
+      "description": "Hyperbrowser's ad blocking",
+      "type": "boolean"
+    },
+    "trackers": {
+      "default": false,
+      "description": "Hyperbrowser's tracker blocking",
+      "type": "boolean"
+    },
+    "annoyances": {
+      "default": false,
+      "description": "Hyperbrowser's annoyance blocking",
+      "type": "boolean"
+    },
+    "acceptCookies": {
+      "default": false,
+      "description": "Hyperbrowser's automatic acceptance of cookie banners",
+      "type": "boolean"
+    },
+    "screen": {
+      "description": "The browser screen size in pixels",
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "height": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "additionalProperties": false
+    },
+    "region": {
+      "description": "The Hyperbrowser region the session runs in",
+      "type": "string",
+      "minLength": 1
+    },
+    "profile": {
+      "description": "A Hyperbrowser profile id loaded read-only; needs context: reuse on the remote",
+      "type": "string",
+      "minLength": 1
+    },
+    "extensions": {
+      "description": "Hyperbrowser extension ids loaded into the browser",
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "extra": {
+      "description": "Fields merged last into the session create request, overriding the rest",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@vostride/agent-qa-plugin-hyperbrowser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "private": false,
+  "description": "agent-qa plugin for Hyperbrowser: creates a Hyperbrowser browser session before a test connects and stops it after.",
+  "keywords": [
+    "agent-qa",
+    "agent-qa-plugin",
+    "hyperbrowser"
+  ],
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://github.com/vostride/agent-qa#readme",
+  "bugs": {
+    "url": "https://github.com/vostride/agent-qa/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vostride/agent-qa.git",
+    "directory": "plugins/hyperbrowser"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "LICENSE.md",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "build": "tsdown && node scripts/emit.mjs",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@vostride/agent-qa-plugin-kit": "0.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "~24.19.2",
+    "@vostride/agent-qa-arch": "0.3.2",
+    "tsdown": "~0.23.4",
+    "typescript": "~7.0.2",
+    "vitest": "~5.0.5"
+  },
+  "agent-qa": {
+    "plugin": {
+      "kind": "remote",
+      "runs": "process",
+      "protocol": 1,
+      "entry": "./dist/main.js",
+      "serves": [
+        "cdp"
+      ],
+      "methods": [
+        "check"
+      ],
+      "options": "./dist/options.schema.json",
+      "settings": "./dist/settings.schema.json",
+      "skill": "./skill"
+    }
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: agent-qa-plugin-hyperbrowser
+description: Use when configuring agent-qa web tests to run in Hyperbrowser cloud browsers through the Hyperbrowser plugin, or when a Hyperbrowser remote is refused.
+---
+
+# Hyperbrowser remotes for agent-qa
+
+The Hyperbrowser plugin gives an agent-qa web test a Hyperbrowser browser session. Before the test
+connects it creates a session through Hyperbrowser's API, and after the test it stops the session.
+Hyperbrowser runs Chromium only. Stealth, proxies, CAPTCHA solving, ad, tracker and annoyance
+blocking and cookie auto-accept are off unless a setting turns them on, so a test sees the app the
+way its users do.
+
+## Declare the plugin and a remote
+
+```yaml
+plugins:
+  - name: hyperbrowser
+    package: "@vostride/agent-qa-plugin-hyperbrowser"
+    options:
+      apiKey: "{{secret:HYPERBROWSER_API_KEY}}"
+
+registry:
+  remotes:
+    - name: hyperbrowser
+      plugin: hyperbrowser
+    - name: hyperbrowser-unrecorded
+      plugin: hyperbrowser
+      settings:
+        recording: false
+```
+
+- The `plugins` entry holds the account: `apiKey`, which is required, and `apiUrl`, which defaults
+  to `https://api.hyperbrowser.ai`. Write the key as a `{{secret:<name>}}` reference to a name in
+  the file `workspace.secretsFile` names. Never write the key itself in the config.
+- The remote holds one place: `plugin` names the `plugins` entry, and `settings` hold that place's
+  Hyperbrowser settings.
+- `use.browser.remote: hyperbrowser` in the config, a suite or a test runs the test there.
+- Install the package at the exact version of agent-qa the project runs:
+  `npm install --save-dev --save-exact @vostride/agent-qa-plugin-hyperbrowser@<agent-qa version>`.
+  `agent-qa plugins list` prints that line when the package is missing or the version differs.
+
+## Settings
+
+- `timeoutMinutes` (default `720`, 1 to 720): minutes before Hyperbrowser stops the session. It
+  overrides the team default in Hyperbrowser's settings. The plugin never asks for keep-alive, so
+  Hyperbrowser also stops a session whose connection drops, and agent-qa stops every session after
+  its test. A session whose create was in flight when the job was killed was never connected, so
+  it runs until `timeoutMinutes`.
+- `recording` (unset by default): Hyperbrowser's web recording. Unset keeps the account's default,
+  which records. `recording: false` turns it off.
+- `stealth`, `solveCaptchas`, `adblock`, `trackers`, `annoyances`, `acceptCookies` (each default
+  `false`): Hyperbrowser's stealth mode, CAPTCHA solving, ad, tracker and annoyance blocking and
+  automatic acceptance of cookie banners.
+- `proxy` (default `false`): `true`, or `{ country, state, city }` with any of the three. Proxies
+  and CAPTCHA solving need a paid Hyperbrowser plan.
+- `screen` (`{ width, height }` in pixels), `region` (for example `us-east` or `europe-west`),
+  `extensions` (extension ids): Hyperbrowser's own create fields, sent only when set.
+- `profile`: a Hyperbrowser profile id. It loads read-only: nothing the test does is saved back. It
+  needs `context: reuse` on the remote, because the profile lives in the browser's first context:
+
+  ```yaml
+  - name: hyperbrowser-signed-in
+    plugin: hyperbrowser
+    context: reuse
+    settings:
+      profile: <Hyperbrowser profile id>
+  ```
+
+- `extra`: any other Hyperbrowser request field. It is merged last, so it overrides the settings
+  above. Video replay is `extra: { enableVideoWebRecording: true }`, and needs recording on.
+  Enterprise proxy servers go here as `proxyServer`, `proxyServerUsername` and
+  `proxyServerPassword`; write the password as a `{{secret:<name>}}` reference.
+
+## When a remote is refused
+
+- `auth`: Hyperbrowser refused the API key. Check the secret's value.
+- `capacity`: Hyperbrowser answered 429. The account has no free sessions, or is rate limited.
+  Wait, or lower the run's concurrency.
+- `refused` with `Hyperbrowser answered 403 to POST /api/session: <reason>`: a feature the remote
+  turns on is not on the plan, for example `Proxy usage requires a paid plan`. Turn that setting
+  off, or change the plan.
+- `refused` with path `settings.profile`: the remote sets `profile` without `context: reuse`. Add
+  `context: reuse` to the remote.
+- `refused` with path `settings.timeoutMinutes`: the lifetime is outside 1 to 720. Set a value in
+  that range, or leave it out for 720.
+- `refused` naming a browser or platform: Hyperbrowser runs Chromium web tests only. Use
+  `use.browser.name: chromium`, or another remote.
+- `refused` at `options.apiUrl`: the endpoint must use `https://` with no user or password, unless
+  it points at this machine.
+- `unreachable`: Hyperbrowser could not be reached. Check the network and `apiUrl`.
+
+## Recording
+
+Hyperbrowser records sessions by default and keeps the replay on its dashboard, behind its login.
+agent-qa's masking does not reach that replay, so a secret a test types may show in it. Set
+`recording: false` on the remote to turn recording off. The session link opens the session's page
+in Hyperbrowser's dashboard. Hyperbrowser's live view URL and the session token let anyone who has
+them watch and drive the session, so agent-qa masks both and never shows them as the link.
+
+## Check and describe
+
+- `agent-qa doctor` runs the plugin's account check. It reads the active sessions to prove the key,
+  reports how many there are, and opens none.
+- `agent-qa plugins describe hyperbrowser --json` lists every option and setting with its type,
+  default and description.