@vostride/agent-qa-plugin-kernel 0.0.1 → 0.3.0

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

@@ -0,0 +1,137 @@
+# @vostride/agent-qa-plugin-kernel
+
+The agent-qa plugin for [Kernel](https://www.kernel.sh) cloud browsers. Before a web test connects,
+it creates a Kernel browser or takes one from a browser pool, and answers agent-qa with the
+browser's CDP URL. After the test it deletes the browser, or returns it to the pool. Kernel 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-kernel@<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: kernel
+    package: "@vostride/agent-qa-plugin-kernel"
+    options:
+      apiKey: "{{secret:KERNEL_API_KEY}}"
+
+registry:
+  remotes:
+    - name: kernel
+      plugin: kernel
+      settings:
+        headless: true
+        timeoutSeconds: 60
+```
+
+A test runs there with `use.browser.remote: kernel` in the config, a suite or the test.
+
+### Options
+
+Options belong to the `plugins` entry and describe the account.
+
+| Option   | Default                    | Meaning                                                                        |
+| -------- | -------------------------- | ------------------------------------------------------------------------------ |
+| `apiKey` | required                   | The Kernel API key, a credential. Write it as a `{{secret:<name>}}` reference. |
+| `apiUrl` | `https://api.onkernel.com` | Kernel's API. It must use `https://` unless it points at this machine.         |
+
+The key is sent only as the `Authorization: Bearer` header. It never appears in a message, a log or
+an answer.
+
+### Settings
+
+Settings belong to each remote and describe one place.
+
+| Setting          | Default | Meaning                                                                                |
+| ---------------- | ------- | -------------------------------------------------------------------------------------- |
+| `headless`       | `true`  | `false` gives a headful browser. Kernel's own default is headful.                      |
+| `timeoutSeconds` | `60`    | Seconds Kernel keeps the browser after agent-qa's connection drops (10 to 259200).     |
+| `stealth`        | -       | Kernel's stealth mode.                                                                 |
+| `region`         | -       | The Kernel region, for example `eu-west`.                                              |
+| `proxy`          | -       | Kernel's proxy object, sent as given.                                                  |
+| `viewport`       | -       | `width`, `height` and optional `refreshRate`, sent as `refresh_rate`.                  |
+| `pool`           | -       | A browser pool's id or name to acquire from instead of creating a browser.             |
+| `profile`        | -       | A profile's name, or `{ id: <profile id> }`, loaded read-only. Needs `context: reuse`. |
+| `extra`          | -       | Any other Kernel request field, merged last.                                           |
+
+`agent-qa plugins describe kernel` 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 /browsers`) is built in three layers, each overriding the one before:
+
+1. the defaults: `headless: true` and `timeout_seconds: 60`;
+2. the curated settings above, in Kernel's field names (`timeoutSeconds` becomes
+   `timeout_seconds`, `viewport.refreshRate` becomes `viewport.refresh_rate`, and `profile`
+   becomes `profile: { name | id, save_changes: false }`);
+3. `extra`, last, so a pass-through key overrides both a default and a curated setting.
+
+For example, `settings: { headless: true, extra: { headless: false, kiosk_mode: true } }` creates a
+headful browser in kiosk mode.
+
+## Pools
+
+With `pool`, the plugin acquires a browser with `POST /browser_pools/{pool}/acquire`. Kernel holds
+that request open while the pool is empty and answers `204` when it times out. The plugin then asks
+again, and reports `waiting for pool <pool>` to agent-qa after each `204`. Asks are at least a
+second apart, so a short `acquire_timeout_seconds` in `extra` does not become a busy loop. The wait
+ends when a browser is free or when agent-qa cancels it at the remote's `connectTimeout`.
+
+- The acquire body holds only `profile` and `extra`. The pool's own configuration sets the browser,
+  so `stealth`, `region`, `proxy` and `viewport` are refused on a remote with `pool`, and
+  `headless` and `timeoutSeconds` do not apply.
+- On release the plugin posts `{ session_id, reuse }` to `POST /browser_pools/{pool}/release`.
+  `reuse` is `true` after a test in a new context, so the browser goes back to the pool. It is
+  `false` after a test with `context: reuse`, so the browser is discarded.
+- A browser the pool no longer has counts as released.
+
+## Profiles
+
+`profile` loads a Kernel profile with `save_changes: 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`. With `pool`, the profile goes
+into the acquire body, and Kernel discards such a browser after use.
+
+## Failures
+
+| Kernel answer         | Kind          |
+| --------------------- | ------------- |
+| `401`, `403`          | `auth`        |
+| `429`, `529`          | `capacity`    |
+| no answer             | `unreachable` |
+| any other non-success | `refused`     |
+
+Each failure is one line naming the status, the request and Kernel's message, with `Retry-After`
+on a `429`. A browser that is already gone when the plugin deletes it counts as released.
+
+## Links and the live view
+
+Kernel documents no per-session page, so the plugin returns no session link. A headful browser's
+live view URL carries a token, so it is a credential: the plugin adds it, with the CDP URL, to the
+values agent-qa masks, and never returns it as a link.
+
+## Account check
+
+`agent-qa doctor` runs the plugin's `check`, which creates no browser:
+
+- `GET /browsers?limit=1` proves the key. A refused key warns `the API key was refused`.
+- `GET /org/limits` reports free sessions, for example `3 of 5 concurrent sessions free`. A key
+  that may not read them reads `organization limits not readable with this key`, which does not
+  warn.
+- `GET /browser_pools/{pool}` for each pool a remote names reads `pool <pool> found`, or warns
+  `pool <pool> not found`.
+
+## 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-C2raYjWg.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 Kernel API key"
+    },
+    "apiUrl": {
+      "default": "https://api.onkernel.com",
+      "description": "Kernel's API, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "required": [
+    "apiKey"
+  ],
+  "additionalProperties": false
+}

package/dist/plugin-C2raYjWg.js

@@ -0,0 +1,372 @@
+import { PluginError, credential, definePlugin, z } from "@vostride/agent-qa-plugin-kit";
+import { setTimeout } from "node:timers/promises";
+// src/kernel-api.ts
+const KernelBrowserSchema = z.object({
+	session_id: z.string().min(1),
+	cdp_ws_url: z.string().min(1),
+	browser_live_view_url: z.string().min(1).optional()
+});
+function kernelFailureKind(status) {
+	if (status === void 0) return "unreachable";
+	if (status === 401 || status === 403) return "auth";
+	if (status === 429 || status === 529) return "capacity";
+	return "refused";
+}
+const MAX_REASON_LENGTH = 200;
+function oneLine(text) {
+	const line = text.replace(/\s+/g, " ").trim();
+	return line.length > MAX_REASON_LENGTH ? `${line.slice(0, MAX_REASON_LENGTH)}…` : line;
+}
+async function vendorReason(response) {
+	const text = await response.text().catch(() => "");
+	try {
+		const body = JSON.parse(text);
+		if (typeof body === "object" && body !== null && "message" in body) {
+			const { message } = body;
+			if (typeof message === "string" && message.trim() !== "") return `: ${oneLine(message)}`;
+		}
+	} catch {}
+	return "";
+}
+async function statusFailure(response, request) {
+	const retryAfter = response.headers.get("retry-after");
+	const wait = response.status === 429 && retryAfter !== null ? `, retry after ${retryAfter} s` : "";
+	const reason = await vendorReason(response);
+	return new PluginError(`Kernel answered ${response.status} to ${request}${reason}${wait}`, { kind: kernelFailureKind(response.status) });
+}
+async function jsonOf(response) {
+	const text = await response.text();
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+function causeText(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause;
+	if (cause instanceof Error) return oneLine("code" in cause && typeof cause.code === "string" ? cause.code : cause.message);
+	return oneLine(error.message);
+}
+function createKernelApi(input) {
+	const base = input.apiUrl.endsWith("/") ? input.apiUrl : `${input.apiUrl}/`;
+	const authorization = `Bearer ${input.apiKey}`;
+	const send = async (method, path, init) => {
+		const url = new URL(path, base);
+		try {
+			return await fetch(url, {
+				method,
+				headers: {
+					...init.headers,
+					authorization
+				},
+				...init.body === void 0 ? {} : { body: init.body },
+				...init.signal === void 0 ? {} : { signal: init.signal }
+			});
+		} catch (error) {
+			if (init.signal?.aborted === true) throw error;
+			throw new PluginError(`Kernel could not be reached at ${url.origin}: ${causeText(error)}`, { kind: "unreachable" });
+		}
+	};
+	const jsonHeaders = {
+		"content-type": "application/json",
+		accept: "application/json"
+	};
+	const poolPath = (pool, action = "") => `browser_pools/${encodeURIComponent(pool)}${action === "" ? "" : `/${action}`}`;
+	return {
+		async createBrowser(body, signal) {
+			const response = await send("POST", "browsers", {
+				headers: jsonHeaders,
+				body: JSON.stringify(body),
+				signal
+			});
+			if (!response.ok) throw await statusFailure(response, "POST /browsers");
+			return jsonOf(response);
+		},
+		async deleteBrowser(id, signal) {
+			const response = await send("DELETE", `browsers/${encodeURIComponent(id)}`, { signal });
+			if (response.ok || response.status === 404) {
+				await response.body?.cancel();
+				return;
+			}
+			throw await statusFailure(response, "DELETE /browsers/{id}");
+		},
+		async acquireFromPool(pool, body, signal) {
+			const response = await send("POST", poolPath(pool, "acquire"), {
+				headers: jsonHeaders,
+				body: JSON.stringify(body),
+				signal
+			});
+			if (response.status === 204) {
+				await response.body?.cancel();
+				return { acquired: false };
+			}
+			if (!response.ok) throw await statusFailure(response, "POST /browser_pools/{pool}/acquire");
+			return {
+				acquired: true,
+				browser: await jsonOf(response)
+			};
+		},
+		async releaseToPool(pool, sessionId, reuse, signal) {
+			const response = await send("POST", poolPath(pool, "release"), {
+				headers: jsonHeaders,
+				body: JSON.stringify({
+					session_id: sessionId,
+					reuse
+				}),
+				signal
+			});
+			if (response.ok || response.status === 404) {
+				await response.body?.cancel();
+				return;
+			}
+			throw await statusFailure(response, "POST /browser_pools/{pool}/release");
+		},
+		async listBrowsers(limit, signal) {
+			const response = await send("GET", `browsers?limit=${String(limit)}`, {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (!response.ok) throw await statusFailure(response, "GET /browsers");
+			await response.body?.cancel();
+		},
+		async orgLimits(signal) {
+			const response = await send("GET", "org/limits", {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (!response.ok) throw await statusFailure(response, "GET /org/limits");
+			return jsonOf(response);
+		},
+		async getPool(pool, signal) {
+			const response = await send("GET", poolPath(pool), {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (response.status === 404) {
+				await response.body?.cancel();
+				return false;
+			}
+			if (!response.ok) throw await statusFailure(response, "GET /browser_pools/{pool}");
+			await response.body?.cancel();
+			return true;
+		}
+	};
+}
+// src/plugin.ts
+const KERNEL_API_URL = "https://api.onkernel.com";
+const POOL_POLL_FLOOR_MS = 1e3;
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "[::1]"]);
+const options = z.strictObject({
+	apiKey: credential("The Kernel API key"),
+	apiUrl: z.url().default(KERNEL_API_URL).describe("Kernel's API, https:// unless it points at this machine")
+});
+const settings = z.strictObject({
+	headless: z.boolean().default(true).describe("Run a headless browser; Kernel offers a live view only for a headful one"),
+	timeoutSeconds: z.int().min(10).max(259200).default(60).describe("Seconds with no connection before Kernel deletes the browser"),
+	stealth: z.boolean().optional().describe("Kernel's stealth mode"),
+	region: z.string().min(1).optional().describe("The Kernel region, for example eu-west"),
+	proxy: z.record(z.string(), z.unknown()).optional().describe("Kernel's proxy, sent as given"),
+	viewport: z.strictObject({
+		width: z.int().positive(),
+		height: z.int().positive(),
+		refreshRate: z.int().positive().optional()
+	}).optional().describe("The browser window size"),
+	pool: z.string().min(1).optional().describe("A Kernel browser pool, by id or name, to acquire from instead of creating a browser"),
+	profile: z.union([z.string().min(1), z.strictObject({ id: z.string().min(1) })]).optional().describe("A Kernel profile loaded read-only, by name or as { id }; needs context: reuse"),
+	extra: z.record(z.string(), z.unknown()).optional().describe("Fields merged last into the create or pool acquire request, overriding the rest")
+});
+function apiUrlAllowed(value) {
+	const url = new URL(value);
+	if (url.username !== "" || url.password !== "") return false;
+	if (url.protocol === "https:") return true;
+	if (url.protocol !== "http:") return false;
+	return LOOPBACK_HOSTS.has(url.hostname) || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+}
+const CREATE_ONLY_SETTINGS = [
+	"stealth",
+	"region",
+	"proxy",
+	"viewport"
+];
+function profileBody(input, session) {
+	const { profile } = input;
+	if (profile === void 0) return void 0;
+	if (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"
+	});
+	return {
+		...typeof profile === "string" ? { name: profile } : { id: profile.id },
+		save_changes: false
+	};
+}
+function createBody(input, profile) {
+	const { viewport } = input;
+	return {
+		headless: input.headless,
+		timeout_seconds: input.timeoutSeconds,
+		...input.stealth === void 0 ? {} : { stealth: input.stealth },
+		...input.region === void 0 ? {} : { region: input.region },
+		...input.proxy === void 0 ? {} : { proxy: input.proxy },
+		...viewport === void 0 ? {} : { viewport: {
+			width: viewport.width,
+			height: viewport.height,
+			...viewport.refreshRate === void 0 ? {} : { refresh_rate: viewport.refreshRate }
+		} },
+		...profile === void 0 ? {} : { profile },
+		...input.extra
+	};
+}
+const HandleSchema = z.object({
+	sessionId: z.string().min(1),
+	pool: z.string().min(1).optional(),
+	reuse: z.boolean().optional()
+});
+function sessionIdOf(answer) {
+	if (typeof answer !== "object" || answer === null || !("session_id" in answer)) return void 0;
+	const id = answer.session_id;
+	return typeof id === "string" && id !== "" ? id : void 0;
+}
+function cdpAnswer(answer, place) {
+	const sessionId = sessionIdOf(answer);
+	const handle = sessionId === void 0 ? void 0 : {
+		sessionId,
+		...place
+	};
+	const browser = KernelBrowserSchema.safeParse(answer);
+	if (!browser.success) throw new PluginError("Kernel answered a browser without a session_id and a cdp_ws_url.", {
+		kind: "refused",
+		...handle === void 0 ? {} : { handle }
+	});
+	const { cdp_ws_url: url, browser_live_view_url: liveView } = browser.data;
+	return {
+		handle: {
+			sessionId: browser.data.session_id,
+			...place
+		},
+		protocol: "cdp",
+		url,
+		mask: liveView === void 0 ? [url] : [url, liveView]
+	};
+}
+async function acquireFromPool(api, pool, body, reuse, ctx) {
+	const stopped = () => new PluginError(`stopped waiting for pool ${pool}`, { kind: "timeout" });
+	for (;;) {
+		const began = Date.now();
+		let answer;
+		try {
+			answer = await api.acquireFromPool(pool, body, ctx.signal);
+		} catch (error) {
+			if (ctx.signal.aborted) throw stopped();
+			throw error;
+		}
+		if (answer.acquired) return cdpAnswer(answer.browser, {
+			pool,
+			reuse
+		});
+		if (ctx.signal.aborted) throw stopped();
+		ctx.progress({ message: `waiting for pool ${pool}` });
+		const rest = POOL_POLL_FLOOR_MS - (Date.now() - began);
+		if (rest > 0) await setTimeout(rest, void 0, { signal: ctx.signal }).catch(() => {});
+		if (ctx.signal.aborted) throw stopped();
+	}
+}
+const OrgLimitsSchema = z.object({
+	concurrent_sessions_available: z.int().nonnegative(),
+	concurrent_sessions_used: z.int().nonnegative()
+});
+function refusedKey(error) {
+	return error instanceof PluginError && error.kind === "auth";
+}
+function failureLine(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function limitsLine(api, signal) {
+	let answer;
+	try {
+		answer = await api.orgLimits(signal);
+	} catch (error) {
+		if (refusedKey(error)) return "organization limits not readable with this key";
+		return `organization limits not readable: ${failureLine(error)}`;
+	}
+	const limits = OrgLimitsSchema.safeParse(answer);
+	if (!limits.success) return "organization limits not readable: Kernel answered another shape";
+	const { concurrent_sessions_available: free, concurrent_sessions_used: used } = limits.data;
+	return `${String(free)} of ${String(free + used)} concurrent sessions free`;
+}
+var plugin_default = definePlugin({
+	options,
+	settings,
+	serves: ["cdp"],
+	skill: "./skill",
+	initialize({ options }) {
+		if (!apiUrlAllowed(options.apiUrl)) throw new PluginError("apiUrl must use https:// unless it points at this machine.", {
+			kind: "refused",
+			path: "apiUrl"
+		});
+	},
+	async check({ options, remotes }, ctx) {
+		const api = createKernelApi(options);
+		try {
+			await api.listBrowsers(1, ctx.signal);
+		} catch (error) {
+			return {
+				state: "warn",
+				lines: [refusedKey(error) ? "the API key was refused" : failureLine(error)]
+			};
+		}
+		const lines = ["the API key was accepted", await limitsLine(api, ctx.signal)];
+		let state = "ok";
+		const pools = new Set(remotes.flatMap(({ settings }) => settings.pool ?? []));
+		for (const pool of pools) {
+			let found;
+			try {
+				found = await api.getPool(pool, ctx.signal);
+			} catch (error) {
+				state = "warn";
+				lines.push(`pool ${pool} not readable: ${failureLine(error)}`);
+				continue;
+			}
+			if (!found) state = "warn";
+			lines.push(found ? `pool ${pool} found` : `pool ${pool} not found`);
+		}
+		return {
+			state,
+			lines
+		};
+	},
+	async acquire({ options, settings, session }, ctx) {
+		if (session.platform !== "web" || session.engine !== "chromium") {
+			const what = session.platform === "web" ? session.engine : session.platform;
+			throw new PluginError(`Kernel runs Chromium web sessions only, not ${what}.`, { kind: "refused" });
+		}
+		const profile = profileBody(settings, session);
+		const api = createKernelApi(options);
+		if (settings.pool !== void 0) {
+			const fromCreate = CREATE_ONLY_SETTINGS.find((name) => settings[name] !== void 0);
+			if (fromCreate !== void 0) throw new PluginError(`${fromCreate} comes from the pool's own configuration; remove it from a remote with pool.`, {
+				kind: "refused",
+				path: `settings.${fromCreate}`
+			});
+			const body = {
+				...profile === void 0 ? {} : { profile },
+				...settings.extra
+			};
+			const reuse = session.context !== "reuse";
+			return acquireFromPool(api, settings.pool, body, reuse, ctx);
+		}
+		return cdpAnswer(await api.createBrowser(createBody(settings, profile)), {});
+	},
+	async release({ options, handle }, ctx) {
+		const parsed = HandleSchema.safeParse(handle);
+		if (!parsed.success) throw new PluginError("A Kernel handle names its browser by sessionId.", { kind: "refused" });
+		const { sessionId, pool, reuse } = parsed.data;
+		const api = createKernelApi(options);
+		if (pool === void 0) await api.deleteBrowser(sessionId, ctx.signal);
+		else await api.releaseToPool(pool, sessionId, reuse ?? false, ctx.signal);
+	}
+});
+export { plugin_default as t };
+
+//# sourceMappingURL=plugin-C2raYjWg.js.map

package/dist/plugin-C2raYjWg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-C2raYjWg.js","names":["delay"],"sources":["../src/kernel-api.ts","../src/plugin.ts"],"sourcesContent":["import { PluginError, z } from '@vostride/agent-qa-plugin-kit'\n\ntype KernelFailureKind = 'auth' | 'capacity' | 'refused' | 'unreachable'\n\nexport const KernelBrowserSchema = z.object({\n  session_id: z.string().min(1),\n  cdp_ws_url: z.string().min(1),\n  browser_live_view_url: z.string().min(1).optional(),\n})\n\ninterface KernelApiInput {\n  apiUrl: string\n  apiKey: string\n}\n\nexport type PoolAcquireAnswer = { acquired: true; browser: unknown } | { acquired: false }\n\nexport interface KernelApi {\n  createBrowser(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>\n  deleteBrowser(id: string, signal?: AbortSignal): Promise<void>\n  acquireFromPool(\n    pool: string,\n    body: Record<string, unknown>,\n    signal?: AbortSignal,\n  ): Promise<PoolAcquireAnswer>\n  releaseToPool(pool: string, sessionId: string, reuse: boolean, signal?: AbortSignal): Promise<void>\n  listBrowsers(limit: number, signal?: AbortSignal): Promise<void>\n  orgLimits(signal?: AbortSignal): Promise<unknown>\n  getPool(pool: string, signal?: AbortSignal): Promise<boolean>\n}\n\nexport function kernelFailureKind(status: number | undefined): KernelFailureKind {\n  if (status === undefined) return 'unreachable'\n  if (status === 401 || status === 403) return 'auth'\n  if (status === 429 || status === 529) return 'capacity'\n  return 'refused'\n}\n\ninterface SendInit {\n  headers?: Record<string, string>\n  body?: string\n  signal?: AbortSignal | undefined\n}\n\nconst MAX_REASON_LENGTH = 200\n\nfunction oneLine(text: string): string {\n  const line = text.replace(/\\s+/g, ' ').trim()\n  return line.length > MAX_REASON_LENGTH ? `${line.slice(0, MAX_REASON_LENGTH)}…` : line\n}\n\nasync function vendorReason(response: Response): Promise<string> {\n  const text = await response.text().catch(() => '')\n  try {\n    const body: unknown = JSON.parse(text)\n    if (typeof body === 'object' && body !== null && 'message' in body) {\n      const { message } = body\n      if (typeof message === 'string' && message.trim() !== '') return `: ${oneLine(message)}`\n    }\n  } catch {\n    // a body that is not JSON carries no reason worth showing\n  }\n  return ''\n}\n\nasync function statusFailure(response: Response, request: string): Promise<PluginError> {\n  const retryAfter = response.headers.get('retry-after')\n  const wait = response.status === 429 && retryAfter !== null ? `, retry after ${retryAfter} s` : ''\n  const reason = await vendorReason(response)\n  return new PluginError(`Kernel answered ${response.status} to ${request}${reason}${wait}`, {\n    kind: kernelFailureKind(response.status),\n  })\n}\n\nasync function jsonOf(response: Response): Promise<unknown> {\n  const text = await response.text()\n  try {\n    return JSON.parse(text) as unknown\n  } catch {\n    return undefined\n  }\n}\n\nfunction causeText(error: unknown): string {\n  if (!(error instanceof Error)) return String(error)\n  const cause = error.cause\n  if (cause instanceof Error) {\n    const code = 'code' in cause && typeof cause.code === 'string' ? cause.code : cause.message\n    return oneLine(code)\n  }\n  return oneLine(error.message)\n}\n\nexport function createKernelApi(input: KernelApiInput): KernelApi {\n  const base = input.apiUrl.endsWith('/') ? input.apiUrl : `${input.apiUrl}/`\n  const authorization = `Bearer ${input.apiKey}`\n\n  const send = async (method: string, path: string, init: SendInit): Promise<Response> => {\n    const url = new URL(path, base)\n    try {\n      return await fetch(url, {\n        method,\n        headers: { ...init.headers, authorization },\n        ...(init.body === undefined ? {} : { body: init.body }),\n        ...(init.signal === undefined ? {} : { signal: init.signal }),\n      })\n    } catch (error) {\n      if (init.signal?.aborted === true) throw error\n      throw new PluginError(`Kernel could not be reached at ${url.origin}: ${causeText(error)}`, {\n        kind: 'unreachable',\n      })\n    }\n  }\n\n  const jsonHeaders = { 'content-type': 'application/json', accept: 'application/json' }\n  const poolPath = (pool: string, action = '') =>\n    `browser_pools/${encodeURIComponent(pool)}${action === '' ? '' : `/${action}`}`\n\n  return {\n    async createBrowser(body, signal) {\n      const response = await send('POST', 'browsers', {\n        headers: jsonHeaders,\n        body: JSON.stringify(body),\n        signal,\n      })\n      if (!response.ok) throw await statusFailure(response, 'POST /browsers')\n      return jsonOf(response)\n    },\n\n    async deleteBrowser(id, signal) {\n      const response = await send('DELETE', `browsers/${encodeURIComponent(id)}`, { signal })\n      if (response.ok || response.status === 404) {\n        await response.body?.cancel()\n        return\n      }\n      throw await statusFailure(response, 'DELETE /browsers/{id}')\n    },\n\n    async acquireFromPool(pool, body, signal) {\n      const response = await send('POST', poolPath(pool, 'acquire'), {\n        headers: jsonHeaders,\n        body: JSON.stringify(body),\n        signal,\n      })\n      if (response.status === 204) {\n        await response.body?.cancel()\n        return { acquired: false }\n      }\n      if (!response.ok) throw await statusFailure(response, 'POST /browser_pools/{pool}/acquire')\n      return { acquired: true, browser: await jsonOf(response) }\n    },\n\n    async releaseToPool(pool, sessionId, reuse, signal) {\n      const response = await send('POST', poolPath(pool, 'release'), {\n        headers: jsonHeaders,\n        body: JSON.stringify({ session_id: sessionId, reuse }),\n        signal,\n      })\n      if (response.ok || response.status === 404) {\n        await response.body?.cancel()\n        return\n      }\n      throw await statusFailure(response, 'POST /browser_pools/{pool}/release')\n    },\n\n    async listBrowsers(limit, signal) {\n      const response = await send('GET', `browsers?limit=${String(limit)}`, {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (!response.ok) throw await statusFailure(response, 'GET /browsers')\n      await response.body?.cancel()\n    },\n\n    async orgLimits(signal) {\n      const response = await send('GET', 'org/limits', {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (!response.ok) throw await statusFailure(response, 'GET /org/limits')\n      return jsonOf(response)\n    },\n\n    async getPool(pool, signal) {\n      const response = await send('GET', poolPath(pool), {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (response.status === 404) {\n        await response.body?.cancel()\n        return false\n      }\n      if (!response.ok) throw await statusFailure(response, 'GET /browser_pools/{pool}')\n      await response.body?.cancel()\n      return true\n    },\n  }\n}\n","import { setTimeout as delay } from 'node:timers/promises'\nimport {\n  credential,\n  definePlugin,\n  PluginError,\n  z,\n  type AcquireInput,\n  type PluginCallContext,\n} from '@vostride/agent-qa-plugin-kit'\nimport {\n  createKernelApi,\n  KernelBrowserSchema,\n  type KernelApi,\n  type PoolAcquireAnswer,\n} from './kernel-api.js'\n\nconst KERNEL_API_URL = 'https://api.onkernel.com'\n// Kernel answers 204 at once when the acquire timeout is short, so a poll waits at least this long.\nconst POOL_POLL_FLOOR_MS = 1_000\nconst LOOPBACK_HOSTS = new Set(['localhost', '[::1]'])\n\nconst options = z.strictObject({\n  apiKey: credential('The Kernel API key'),\n  apiUrl: z\n    .url()\n    .default(KERNEL_API_URL)\n    .describe(\"Kernel's API, https:// unless it points at this machine\"),\n})\n\nconst settings = z.strictObject({\n  headless: z\n    .boolean()\n    .default(true)\n    .describe('Run a headless browser; Kernel offers a live view only for a headful one'),\n  timeoutSeconds: z\n    .int()\n    .min(10)\n    .max(259_200)\n    .default(60)\n    .describe('Seconds with no connection before Kernel deletes the browser'),\n  stealth: z.boolean().optional().describe(\"Kernel's stealth mode\"),\n  region: z.string().min(1).optional().describe('The Kernel region, for example eu-west'),\n  proxy: z.record(z.string(), z.unknown()).optional().describe(\"Kernel's proxy, sent as given\"),\n  viewport: z\n    .strictObject({\n      width: z.int().positive(),\n      height: z.int().positive(),\n      refreshRate: z.int().positive().optional(),\n    })\n    .optional()\n    .describe('The browser window size'),\n  pool: z\n    .string()\n    .min(1)\n    .optional()\n    .describe('A Kernel browser pool, by id or name, to acquire from instead of creating a browser'),\n  profile: z\n    .union([z.string().min(1), z.strictObject({ id: z.string().min(1) })])\n    .optional()\n    .describe('A Kernel profile loaded read-only, by name or as { id }; needs context: reuse'),\n  extra: z\n    .record(z.string(), z.unknown())\n    .optional()\n    .describe('Fields merged last into the create or pool acquire request, overriding the rest'),\n})\n\ntype KernelSettings = z.output<typeof settings>\ntype Session = AcquireInput<unknown, unknown>['session']\n\nfunction apiUrlAllowed(value: string): boolean {\n  const url = new URL(value)\n  if (url.username !== '' || url.password !== '') return false\n  if (url.protocol === 'https:') return true\n  if (url.protocol !== 'http:') return false\n  return LOOPBACK_HOSTS.has(url.hostname) || /^127(?:\\.\\d{1,3}){3}$/.test(url.hostname)\n}\n\nconst CREATE_ONLY_SETTINGS = ['stealth', 'region', 'proxy', 'viewport'] as const\n\nfunction profileBody(input: KernelSettings, session: Session) {\n  const { profile } = input\n  if (profile === undefined) return undefined\n  if (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  const named = typeof profile === 'string' ? { name: profile } : { id: profile.id }\n  return { ...named, save_changes: false }\n}\n\nfunction createBody(input: KernelSettings, profile: object | undefined): Record<string, unknown> {\n  const { viewport } = input\n  return {\n    headless: input.headless,\n    timeout_seconds: input.timeoutSeconds,\n    ...(input.stealth === undefined ? {} : { stealth: input.stealth }),\n    ...(input.region === undefined ? {} : { region: input.region }),\n    ...(input.proxy === undefined ? {} : { proxy: input.proxy }),\n    ...(viewport === undefined\n      ? {}\n      : {\n          viewport: {\n            width: viewport.width,\n            height: viewport.height,\n            ...(viewport.refreshRate === undefined ? {} : { refresh_rate: viewport.refreshRate }),\n          },\n        }),\n    ...(profile === undefined ? {} : { profile }),\n    ...input.extra,\n  }\n}\n\nconst HandleSchema = z.object({\n  sessionId: z.string().min(1),\n  pool: z.string().min(1).optional(),\n  reuse: z.boolean().optional(),\n})\ntype KernelHandle = z.output<typeof HandleSchema>\n\nfunction sessionIdOf(answer: unknown): string | undefined {\n  if (typeof answer !== 'object' || answer === null || !('session_id' in answer)) return undefined\n  const id = answer.session_id\n  return typeof id === 'string' && id !== '' ? id : undefined\n}\n\nfunction cdpAnswer(answer: unknown, place: Omit<KernelHandle, 'sessionId'>) {\n  const sessionId = sessionIdOf(answer)\n  const handle = sessionId === undefined ? undefined : { sessionId, ...place }\n  const browser = KernelBrowserSchema.safeParse(answer)\n  if (!browser.success) {\n    throw new PluginError('Kernel answered a browser without a session_id and a cdp_ws_url.', {\n      kind: 'refused',\n      ...(handle === undefined ? {} : { handle }),\n    })\n  }\n  const { cdp_ws_url: url, browser_live_view_url: liveView } = browser.data\n  return {\n    handle: { sessionId: browser.data.session_id, ...place },\n    protocol: 'cdp' as const,\n    url,\n    mask: liveView === undefined ? [url] : [url, liveView],\n  }\n}\n\nasync function acquireFromPool(\n  api: KernelApi,\n  pool: string,\n  body: Record<string, unknown>,\n  reuse: boolean,\n  ctx: PluginCallContext,\n) {\n  const stopped = () => new PluginError(`stopped waiting for pool ${pool}`, { kind: 'timeout' })\n  // Unlike a create, a wait that ends in 204 holds no browser, so the cancel stops the wait.\n  for (;;) {\n    const began = Date.now()\n    let answer: PoolAcquireAnswer\n    try {\n      answer = await api.acquireFromPool(pool, body, ctx.signal)\n    } catch (error) {\n      if (ctx.signal.aborted) throw stopped()\n      throw error\n    }\n    if (answer.acquired) return cdpAnswer(answer.browser, { pool, reuse })\n    if (ctx.signal.aborted) throw stopped()\n    ctx.progress({ message: `waiting for pool ${pool}` })\n    const rest = POOL_POLL_FLOOR_MS - (Date.now() - began)\n    if (rest > 0) await delay(rest, undefined, { signal: ctx.signal }).catch(() => {})\n    if (ctx.signal.aborted) throw stopped()\n  }\n}\n\nconst OrgLimitsSchema = z.object({\n  concurrent_sessions_available: z.int().nonnegative(),\n  concurrent_sessions_used: z.int().nonnegative(),\n})\n\nfunction refusedKey(error: unknown): boolean {\n  return error instanceof PluginError && error.kind === 'auth'\n}\n\nfunction failureLine(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nasync function limitsLine(api: KernelApi, signal: AbortSignal): Promise<string> {\n  let answer: unknown\n  try {\n    answer = await api.orgLimits(signal)\n  } catch (error) {\n    if (refusedKey(error)) return 'organization limits not readable with this key'\n    return `organization limits not readable: ${failureLine(error)}`\n  }\n  const limits = OrgLimitsSchema.safeParse(answer)\n  if (!limits.success) return 'organization limits not readable: Kernel answered another shape'\n  const { concurrent_sessions_available: free, concurrent_sessions_used: used } = limits.data\n  return `${String(free)} of ${String(free + used)} concurrent sessions free`\n}\n\nexport default definePlugin({\n  options,\n  settings,\n  serves: ['cdp'],\n  skill: './skill',\n\n  initialize({ options }) {\n    if (!apiUrlAllowed(options.apiUrl)) {\n      throw new PluginError('apiUrl must use https:// unless it points at this machine.', {\n        kind: 'refused',\n        path: 'apiUrl',\n      })\n    }\n  },\n\n  async check({ options, remotes }, ctx) {\n    const api = createKernelApi(options)\n    try {\n      await api.listBrowsers(1, ctx.signal)\n    } catch (error) {\n      const line = refusedKey(error) ? 'the API key was refused' : failureLine(error)\n      return { state: 'warn', lines: [line] }\n    }\n    const lines = ['the API key was accepted', await limitsLine(api, ctx.signal)]\n    let state: 'ok' | 'warn' = 'ok'\n    const pools = new Set(remotes.flatMap(({ settings }) => settings.pool ?? []))\n    for (const pool of pools) {\n      let found: boolean\n      try {\n        found = await api.getPool(pool, ctx.signal)\n      } catch (error) {\n        state = 'warn'\n        lines.push(`pool ${pool} not readable: ${failureLine(error)}`)\n        continue\n      }\n      if (!found) state = 'warn'\n      lines.push(found ? `pool ${pool} found` : `pool ${pool} not found`)\n    }\n    return { state, lines }\n  },\n\n  async acquire({ options, settings, session }, ctx) {\n    if (session.platform !== 'web' || session.engine !== 'chromium') {\n      const what = session.platform === 'web' ? session.engine : session.platform\n      throw new PluginError(`Kernel runs Chromium web sessions only, not ${what}.`, {\n        kind: 'refused',\n      })\n    }\n    const profile = profileBody(settings, session)\n    const api = createKernelApi(options)\n    if (settings.pool !== undefined) {\n      const fromCreate = CREATE_ONLY_SETTINGS.find((name) => settings[name] !== undefined)\n      if (fromCreate !== undefined) {\n        throw new PluginError(\n          `${fromCreate} comes from the pool's own configuration; remove it from a remote with pool.`,\n          { kind: 'refused', path: `settings.${fromCreate}` },\n        )\n      }\n      const body = { ...(profile === undefined ? {} : { profile }), ...settings.extra }\n      const reuse = session.context !== 'reuse'\n      return acquireFromPool(api, settings.pool, body, reuse, ctx)\n    }\n    // The create is not cancelled: once Kernel has a browser, the handle must come back to be\n    // deleted, and the kit releases a handle that arrives after a cancel was answered.\n    return cdpAnswer(await api.createBrowser(createBody(settings, profile)), {})\n  },\n\n  async release({ options, handle }, ctx) {\n    const parsed = HandleSchema.safeParse(handle)\n    if (!parsed.success) {\n      throw new PluginError('A Kernel handle names its browser by sessionId.', { kind: 'refused' })\n    }\n    const { sessionId, pool, reuse } = parsed.data\n    const api = createKernelApi(options)\n    if (pool === undefined) await api.deleteBrowser(sessionId, ctx.signal)\n    else await api.releaseToPool(pool, sessionId, reuse ?? false, ctx.signal)\n  },\n})\n"],"mappings":"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"}

package/dist/plugin.js

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

package/dist/settings.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "headless": {
+      "default": true,
+      "description": "Run a headless browser; Kernel offers a live view only for a headful one",
+      "type": "boolean"
+    },
+    "timeoutSeconds": {
+      "default": 60,
+      "description": "Seconds with no connection before Kernel deletes the browser",
+      "type": "integer",
+      "minimum": 10,
+      "maximum": 259200
+    },
+    "stealth": {
+      "description": "Kernel's stealth mode",
+      "type": "boolean"
+    },
+    "region": {
+      "description": "The Kernel region, for example eu-west",
+      "type": "string",
+      "minLength": 1
+    },
+    "proxy": {
+      "description": "Kernel's proxy, sent as given",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
+    "viewport": {
+      "description": "The browser window size",
+      "type": "object",
+      "properties": {
+        "width": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "height": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "refreshRate": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "width",
+        "height"
+      ],
+      "additionalProperties": false
+    },
+    "pool": {
+      "description": "A Kernel browser pool, by id or name, to acquire from instead of creating a browser",
+      "type": "string",
+      "minLength": 1
+    },
+    "profile": {
+      "description": "A Kernel profile loaded read-only, by name or as { id }; needs context: reuse",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "id"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "extra": {
+      "description": "Fields merged last into the create or pool acquire request, overriding the rest",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@vostride/agent-qa-plugin-kernel",
-  "version": "0.0.1",
-  "main": "index.js",
-  "files": []
+  "version": "0.3.0",
+  "private": false,
+  "description": "agent-qa plugin for Kernel: creates a Kernel browser before a test connects and deletes it after.",
+  "keywords": [
+    "agent-qa",
+    "agent-qa-plugin",
+    "kernel"
+  ],
+  "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/kernel"
+  },
+  "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.0"
+  },
+  "devDependencies": {
+    "@types/node": "~24.19.2",
+    "@vostride/agent-qa-arch": "0.3.0",
+    "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,86 @@
+---
+name: agent-qa-plugin-kernel
+description: Use when configuring agent-qa web tests to run in Kernel cloud browsers through the Kernel plugin, or when a Kernel remote is refused.
+---
+
+# Kernel remotes for agent-qa
+
+The Kernel plugin gives an agent-qa web test a Kernel cloud browser. Before the test connects it
+creates a browser, or takes one from a browser pool. After the test it deletes the browser, or
+returns it to the pool. Kernel runs Chromium only.
+
+## Declare the plugin and a remote
+
+```yaml
+plugins:
+  - name: kernel
+    package: "@vostride/agent-qa-plugin-kernel"
+    options:
+      apiKey: "{{secret:KERNEL_API_KEY}}"
+
+registry:
+  remotes:
+    - name: kernel
+      plugin: kernel
+      settings:
+        headless: true
+        timeoutSeconds: 60
+```
+
+- The `plugins` entry holds the account: `apiKey`, and `apiUrl`, which defaults to Kernel's API.
+  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
+  Kernel settings.
+- `use.browser.remote: kernel` 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-kernel@<agent-qa version>`.
+  `agent-qa plugins list` prints that line when the package is missing or the version differs.
+
+## Settings
+
+- `headless` (default `true`): `false` gives a headful browser.
+- `timeoutSeconds` (default `60`, 10 to 259200): how long Kernel keeps the browser once agent-qa's
+  connection drops.
+- `stealth`, `region`, `proxy`, `viewport` (`width`, `height`, `refreshRate`): Kernel's own create
+  fields.
+- `pool`: a browser pool's id or name. The remote then takes a warm browser from the pool instead
+  of creating one, and waits while the pool is empty. The pool's configuration sets the browser,
+  so `stealth`, `region`, `proxy` and `viewport` are refused on a remote with `pool`.
+- `profile`: a Kernel profile's name, or `{ id: <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: kernel-signed-in
+    plugin: kernel
+    context: reuse
+    settings:
+      profile: shop-test-user
+  ```
+
+- `extra`: any other Kernel request field. It is merged last, so it overrides the settings above.
+
+After a test in a new context, a pooled browser goes back to the pool for reuse. After a test with
+`context: reuse`, it is discarded, so the next test gets a clean one.
+
+Kernel has no session page, so a Kernel test shows no session link. The live view URL of a headful
+browser carries a credential, so agent-qa masks it and never shows it.
+
+## When a remote is refused
+
+- `auth`: Kernel refused the API key. Check the secret's value.
+- `capacity`: Kernel answered 429 or 529. The account has no free sessions, or is rate limited.
+  Wait, lower the run's concurrency, or use a pool.
+- `refused` with path `settings.profile`: the remote sets `profile` without `context: reuse`.
+- `refused` with another `settings.<field>` path: that field is wrong for this remote. The line
+  says why.
+- `unreachable`: Kernel could not be reached. Check the network.
+
+## Check and describe
+
+- `agent-qa doctor` runs the plugin's account check. It reads the browser list to prove the key,
+  the organization's free sessions when the key may read them, and each pool a remote names. It
+  creates no browser.
+- `agent-qa plugins describe <entry> --json` lists every option and setting with its type,
+  default and description.