@vostride/agent-qa-plugin-steel 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,193 @@
-# Temporary Holding Version
+# @vostride/agent-qa-plugin-steel
 
-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 [Steel](https://steel.dev) cloud browsers. Before a web test connects, it
+creates a Steel session and answers agent-qa with the session's CDP URL, and after the test it
+releases the session. Steel 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-steel@<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: steel
+    package: "@vostride/agent-qa-plugin-steel"
+    options:
+      apiKey: "{{secret:STEEL_API_KEY}}"
+
+registry:
+  remotes:
+    - name: steel
+      plugin: steel
+      settings:
+        idleMinutes: 5
+```
+
+A test runs there with `use.browser.remote: steel` in the config, a suite or the test.
+
+### Options
+
+Options belong to the `plugins` entry and describe the account.
+
+| Option   | Default                 | Meaning                                                                                                                     |
+| -------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey` | -                       | The Steel API key, a credential. Write it as a `{{secret:<name>}}` reference. Leave it out for a self-hosted steel-browser. |
+| `apiUrl` | `https://api.steel.dev` | Steel's API. It must use `https://` with no user or password, unless it points at this machine.                             |
+
+The key is sent as the `steel-api-key` header and in the connect URL agent-qa receives, which
+agent-qa masks. 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` | `1440`  | Minutes before Steel ends the session (1 to 1440), sent as `timeout` in milliseconds. Your Steel plan may cap it lower. |
+| `idleMinutes`    | `5`     | Minutes with no CDP command before Steel ends the session (1 to 60), sent as `inactivityTimeout` in milliseconds.       |
+| `solveCaptcha`   | `false` | Steel's CAPTCHA solving, sent as `solveCaptcha`.                                                                        |
+| `blockAds`       | `false` | Steel's ad blocking, sent as `blockAds`.                                                                                |
+| `fingerprint`    | `false` | Steel's browser fingerprint injection, sent as `stealthConfig.skipFingerprintInjection`, the opposite value.            |
+| `proxy`          | `false` | Steel's proxy: `true`, or Steel's proxy object. Sent as `useProxy`.                                                     |
+| `proxyUrl`       | -       | Your own proxy, `http(s)://user:password@host:port`, a credential. Sent as `proxyUrl` instead of Steel's proxy.         |
+| `dimensions`     | -       | The browser window, `{ width, height }` in pixels, sent as `dimensions`.                                                |
+| `region`         | -       | The Steel region, for example `us-east`, sent as `region`.                                                              |
+| `profile`        | -       | A Steel profile id, loaded read-only and sent as `profileId`. Needs `context: reuse`.                                   |
+| `extensions`     | -       | Steel extension ids loaded into the browser, sent as `extensionIds`.                                                    |
+| `extra`          | -       | Any other Steel request field, merged last.                                                                             |
+
+`agent-qa plugins describe steel` 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 /v1/sessions`) is built in this order, each part overriding the one
+before:
+
+1. `sessionId`, a UUID the plugin chooses, so it can release the session even when the create
+   answer never arrives;
+2. the lifetimes, `timeout` and `inactivityTimeout`, from `timeoutMinutes` and `idleMinutes`;
+3. the features that change the page: CAPTCHA solving, ad blocking, Steel's fingerprint injection
+   and Steel's proxies. Each is sent off unless a setting turns it on, because a test should see
+   the app the way its users do. Steel injects fingerprints unless it is told not to, so the plugin
+   always tells it, with `stealthConfig: { skipFingerprintInjection: true }` by default;
+4. the other settings above, in Steel's field names. With `proxyUrl` the plugin sends your proxy
+   and no `useProxy`. A remote that sets both `proxyUrl` and `proxy` is refused with path
+   `settings.proxyUrl`;
+5. `extra`, last, so a pass-through key overrides both a default and a setting. It cannot set
+   `sessionId`, which the plugin releases the session by; a remote whose `extra` sets it is refused
+   with path `settings.extra.sessionId`.
+
+For example, `settings: { extra: { solveCaptcha: true, headless: true } }` turns CAPTCHA solving on
+and asks for a headless browser.
+
+## Lifetime
+
+By default the plugin asks for a 1440-minute session that ends after 5 idle minutes.
+
+- Steel's plans cap the session lifetime: Launch at 15 minutes, Scale at 60 minutes and Enterprise
+  at up to 1440 minutes. When Steel refuses the create with `400` or `422` while more than 15
+  minutes were asked for, and its reason mentions a timeout, lifetime, duration, minutes, plan or
+  limit, or gives no reason, the failure line ends
+  `if your Steel plan caps sessions below <n> minutes, set settings.timeoutMinutes to the cap`.
+  Set `timeoutMinutes` to your plan's cap. A refusal whose reason is about another field does not
+  name `timeoutMinutes`.
+- When Steel grants a shorter session than was asked for, the plugin writes
+  `Steel granted a <n>-minute session; <m> minutes were asked for` to its log.
+- Any CDP command resets the idle time. agent-qa's heartbeat keeps a running test from going idle.
+- A session left behind by a killed job, where agent-qa and the plugin die together, ends within
+  the idle time, so it stops billing within minutes.
+
+agent-qa releases every session itself after the test; the lifetimes only bound a session that
+agent-qa could not release.
+
+## Recording
+
+Steel records every session 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. Steel offers no switch
+to turn recording off, so the plugin has no `recording` setting, and a remote that sets one is
+refused.
+
+## Profiles
+
+`profile` loads a Steel profile by id, and the plugin never asks Steel to persist it, 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`.
+
+## Self-hosted steel-browser
+
+The plugin also drives a self-hosted [steel-browser](https://github.com/steel-dev/steel-browser):
+
+```yaml
+plugins:
+  - name: steel-local
+    package: "@vostride/agent-qa-plugin-steel"
+    options:
+      apiUrl: "http://localhost:3000"
+
+registry:
+  remotes:
+    - name: steel-local
+      plugin: steel-local
+
+use:
+  workers: 1
+```
+
+- Point `apiUrl` at it. Plain `http://` is allowed only for this machine.
+- Leave out `apiKey`; the plugin then sends no key.
+- Set `use.workers: 1`. A steel-browser serves one session at a time, and releasing a session ends
+  whatever session is active, so two tests at once would end each other's browser.
+- Its session page is plain `http://`, so the plugin returns no link for it.
+
+## Failures
+
+| Steel 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 Steel's message, with `Retry-After` on
+a `429`. A create refused with `400` or `422` may also name `settings.timeoutMinutes`, as above.
+
+A create Steel refuses with a `4xx` made no session, so it carries no handle and nothing is
+released. Every other create failure (no answer, a `5xx`, or an answer the plugin cannot read)
+carries the session's id, so agent-qa releases whatever Steel may have made.
+
+On release, `2xx` and `404` both count as released. On any other answer the plugin reads the
+session back, and counts it released when Steel no longer has it or no longer reports it live.
+
+## Links and the debug URL
+
+The session link is the session's page in Steel's dashboard, which sits behind Steel's login and
+shows the replay. Steel's debug URL lets anyone who has it watch and drive the session, so it is a
+credential: the plugin adds it, with the connect URL, to the values agent-qa masks, and never
+returns it as the link.
+
+## Account check
+
+`agent-qa doctor` runs the plugin's `check`, which lists sessions with `GET /v1/sessions` and opens
+none:
+
+- An accepted key reads `the API key was accepted`.
+- Without `apiKey`, a steel-browser that answers reads `Steel answered without an API key`, and a
+  Steel that asks for a key warns `Steel asked for an API key; set options.apiKey`.
+- A refused key warns `the API key was refused`.
+- Any other failure warns with its one line, for example
+  `Steel 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-C8AoyB8z.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,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "credential": true,
+      "description": "The Steel API key; leave it out for a self-hosted steel-browser"
+    },
+    "apiUrl": {
+      "default": "https://api.steel.dev",
+      "description": "Steel's API, https:// unless it points at this machine",
+      "type": "string",
+      "format": "uri"
+    }
+  },
+  "additionalProperties": false
+}

package/dist/plugin-C8AoyB8z.js

@@ -0,0 +1,256 @@
+import { PluginError, checkEndpoints, createVendorApi, credential, definePlugin, z } from "@vostride/agent-qa-plugin-kit";
+import { randomUUID } from "node:crypto";
+// src/steel-api.ts
+const SteelSessionSchema = z.object({
+	id: z.string().min(1),
+	websocketUrl: z.string().min(1),
+	debugUrl: z.string().min(1).optional(),
+	sessionViewerUrl: z.string().min(1).optional(),
+	timeout: z.number().optional()
+});
+const SessionStatusSchema = z.object({ status: z.string() });
+var SteelCreateFailure = class extends PluginError {
+	status;
+	constructor(failure, status) {
+		super(failure.message, { kind: failure.kind });
+		this.status = status;
+	}
+};
+function createSteelApi(input) {
+	const api = createVendorApi({
+		vendor: "Steel",
+		baseUrl: input.apiUrl,
+		headers: input.apiKey === void 0 ? {} : { "steel-api-key": input.apiKey }
+	});
+	const sessionPath = (id) => `v1/sessions/${encodeURIComponent(id)}`;
+	async function session(id, signal) {
+		const response = await api.send("GET", sessionPath(id), {
+			headers: { accept: "application/json" },
+			signal
+		});
+		if (response.status === 404) {
+			await response.body?.cancel();
+			return;
+		}
+		if (!response.ok) throw await api.failure(response, "GET /v1/sessions/{id}");
+		return api.json(response);
+	}
+	async function released(id, signal) {
+		let current;
+		try {
+			current = await session(id, signal);
+		} catch {
+			return false;
+		}
+		if (current === void 0) return true;
+		const parsed = SessionStatusSchema.safeParse(current);
+		return parsed.success && parsed.data.status !== "live";
+	}
+	return {
+		async createSession(body) {
+			const response = await api.send("POST", "v1/sessions", {
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json"
+				},
+				body: JSON.stringify(body)
+			});
+			if (!response.ok) throw new SteelCreateFailure(await api.failure(response, "POST /v1/sessions"), response.status);
+			return api.json(response);
+		},
+		async release(id, signal) {
+			const response = await api.send("POST", `${sessionPath(id)}/release`, {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (response.ok || response.status === 404) {
+				await response.body?.cancel();
+				return;
+			}
+			const failure = await api.failure(response, "POST /v1/sessions/{id}/release");
+			if (await released(id, signal)) return;
+			throw failure;
+		},
+		session,
+		async listSessions(signal) {
+			const response = await api.send("GET", "v1/sessions?limit=1", {
+				headers: { accept: "application/json" },
+				signal
+			});
+			if (!response.ok) throw await api.failure(response, "GET /v1/sessions");
+			await response.body?.cancel();
+		}
+	};
+}
+// src/plugin.ts
+const STEEL_API_URL = "https://api.steel.dev";
+const MINUTE_MS = 6e4;
+const LIFETIME_REFUSALS = [400, 422];
+const SMALLEST_PLAN_CAP_MINUTES = 15;
+const LIFETIME_WORDS = /timeout|lifetime|duration|minute|plan|limit/i;
+const options = z.strictObject({
+	apiKey: credential("The Steel API key; leave it out for a self-hosted steel-browser").optional(),
+	apiUrl: z.url().default(STEEL_API_URL).describe("Steel's API, https:// unless it points at this machine")
+});
+const settings = z.strictObject({
+	timeoutMinutes: z.int().min(1).max(1440).default(1440).describe("Minutes before Steel ends the session; your Steel plan may cap it lower"),
+	idleMinutes: z.int().min(1).max(60).default(5).describe("Minutes with no CDP command before Steel ends the session"),
+	solveCaptcha: z.boolean().default(false).describe("Steel's CAPTCHA solving"),
+	blockAds: z.boolean().default(false).describe("Steel's ad blocking"),
+	fingerprint: z.boolean().default(false).describe("Steel's browser fingerprint injection, which changes what pages see"),
+	proxy: z.union([z.boolean(), z.record(z.string(), z.unknown())]).default(false).describe("Steel's proxy, true or Steel's proxy object, sent as useProxy"),
+	proxyUrl: credential("Your own proxy, http(s)://user:password@host:port, sent instead of Steel's").optional(),
+	dimensions: z.strictObject({
+		width: z.int().positive(),
+		height: z.int().positive()
+	}).optional().describe("The browser window size"),
+	region: z.string().min(1).optional().describe("The Steel region, for example us-east"),
+	profile: z.string().min(1).optional().describe("A Steel profile id loaded read-only; needs context: reuse"),
+	extensions: z.array(z.string().min(1)).min(1).optional().describe("Steel 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"
+	});
+	if (input.extra !== void 0 && Object.hasOwn(input.extra, "sessionId")) throw new PluginError("extra cannot set sessionId; the plugin chooses it to release the session.", {
+		kind: "refused",
+		path: "settings.extra.sessionId"
+	});
+	if (input.proxyUrl !== void 0 && input.proxy !== false) throw new PluginError("proxy and proxyUrl both choose a proxy; set one of them.", {
+		kind: "refused",
+		path: "settings.proxyUrl"
+	});
+}
+function createBody(sessionId, input) {
+	return {
+		sessionId,
+		timeout: input.timeoutMinutes * MINUTE_MS,
+		inactivityTimeout: input.idleMinutes * MINUTE_MS,
+		solveCaptcha: input.solveCaptcha,
+		blockAds: input.blockAds,
+		...input.proxyUrl === void 0 ? { useProxy: input.proxy } : {},
+		stealthConfig: { skipFingerprintInjection: !input.fingerprint },
+		...input.proxyUrl === void 0 ? {} : { proxyUrl: input.proxyUrl },
+		...input.dimensions === void 0 ? {} : { dimensions: input.dimensions },
+		...input.region === void 0 ? {} : { region: input.region },
+		...input.profile === void 0 ? {} : { profileId: input.profile },
+		...input.extensions === void 0 ? {} : { extensionIds: input.extensions },
+		...input.extra
+	};
+}
+function mayHaveCreated(error) {
+	return !(error instanceof SteelCreateFailure) || error.status >= 500;
+}
+function lifetimeMayBeRefused(error, timeoutMinutes) {
+	if (!(error instanceof SteelCreateFailure) || !LIFETIME_REFUSALS.includes(error.status)) return false;
+	if (timeoutMinutes <= SMALLEST_PLAN_CAP_MINUTES) return false;
+	const reason = error.message.split(": ").slice(1).join(": ");
+	return reason === "" || LIFETIME_WORDS.test(reason);
+}
+function createFailure(error, sessionId, timeoutMinutes) {
+	const message = error instanceof Error ? error.message : String(error);
+	const kind = error instanceof PluginError ? error.kind : "refused";
+	const text = lifetimeMayBeRefused(error, timeoutMinutes) ? `${message.replace(/[\s.;,]+$/, "")}; if your Steel plan caps sessions below ${String(timeoutMinutes)} minutes, set settings.timeoutMinutes to the cap` : message;
+	return new PluginError(text, {
+		kind,
+		...mayHaveCreated(error) ? { handle: { sessionId } } : {}
+	});
+}
+function minutesOf(ms) {
+	return String(Number((ms / MINUTE_MS).toFixed(1)));
+}
+function noteGrantedLifetime(granted, asked) {
+	if (granted === void 0 || typeof asked !== "number" || granted >= asked) return;
+	process.stderr.write(`Steel granted a ${minutesOf(granted)}-minute session; ${minutesOf(asked)} minutes were asked for\n`);
+}
+function viewerLink(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) });
+function hasId(answer) {
+	if (typeof answer !== "object" || answer === null || !("id" in answer)) return false;
+	return typeof answer.id === "string" && answer.id !== "";
+}
+function refusedKey(error) {
+	return error instanceof PluginError && error.kind === "auth";
+}
+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) {
+		try {
+			await createSteelApi(options).listSessions(ctx.signal);
+		} catch (error) {
+			if (!refusedKey(error)) return {
+				state: "warn",
+				lines: [failureLine(error)]
+			};
+			return {
+				state: "warn",
+				lines: [options.apiKey === void 0 ? "Steel asked for an API key; set options.apiKey" : "the API key was refused"]
+			};
+		}
+		return {
+			state: "ok",
+			lines: [options.apiKey === void 0 ? "Steel answered without an API key" : "the API key was accepted"]
+		};
+	},
+	async acquire({ options, settings, session }) {
+		if (session.platform !== "web" || session.engine !== "chromium") {
+			const what = session.platform === "web" ? session.engine : session.platform;
+			throw new PluginError(`Steel runs Chromium web sessions only, not ${what}.`, { kind: "refused" });
+		}
+		checkSettings(settings, session);
+		const api = createSteelApi(options);
+		const sessionId = randomUUID();
+		const body = createBody(sessionId, settings);
+		let created;
+		try {
+			created = await api.createSession(body);
+		} catch (error) {
+			throw createFailure(error, sessionId, settings.timeoutMinutes);
+		}
+		const answer = SteelSessionSchema.safeParse(created);
+		const url = answer.success ? URL.parse(answer.data.websocketUrl) : null;
+		if (!answer.success || url === null) {
+			const missing = hasId(created) ? "a usable websocketUrl" : "an id";
+			throw new PluginError(`Steel answered a session without ${missing}.`, {
+				kind: "refused",
+				handle: { sessionId: answer.success ? answer.data.id : sessionId }
+			});
+		}
+		const { id, debugUrl, sessionViewerUrl, timeout } = answer.data;
+		noteGrantedLifetime(timeout, body.timeout);
+		if (options.apiKey !== void 0) url.searchParams.set("apiKey", options.apiKey);
+		const link = viewerLink(sessionViewerUrl);
+		return {
+			handle: { sessionId: id },
+			protocol: "cdp",
+			url: url.href,
+			mask: debugUrl === void 0 ? [url.href] : [url.href, debugUrl],
+			...link === void 0 ? {} : { link }
+		};
+	},
+	async release({ options, handle }, ctx) {
+		const parsed = HandleSchema.safeParse(handle);
+		if (!parsed.success) throw new PluginError("A Steel handle names its session by sessionId.", { kind: "refused" });
+		await createSteelApi(options).release(parsed.data.sessionId, ctx.signal);
+	}
+});
+export { plugin_default as t };
+
+//# sourceMappingURL=plugin-C8AoyB8z.js.map

package/dist/plugin-C8AoyB8z.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-C8AoyB8z.js","names":[],"sources":["../src/steel-api.ts","../src/plugin.ts"],"sourcesContent":["import { createVendorApi, PluginError, z } from '@vostride/agent-qa-plugin-kit'\n\nexport const SteelSessionSchema = z.object({\n  id: z.string().min(1),\n  websocketUrl: z.string().min(1),\n  debugUrl: z.string().min(1).optional(),\n  sessionViewerUrl: z.string().min(1).optional(),\n  timeout: z.number().optional(),\n})\n\nconst SessionStatusSchema = z.object({ status: z.string() })\n\n// Keeps the status of a refused create, so the plugin can name the setting that may cause it.\nexport class SteelCreateFailure extends PluginError {\n  constructor(\n    failure: PluginError,\n    readonly status: number,\n  ) {\n    super(failure.message, { kind: failure.kind })\n  }\n}\n\ninterface SteelApiInput {\n  apiUrl: string\n  apiKey?: string | undefined\n}\n\nexport interface SteelApi {\n  createSession(body: Record<string, unknown>): Promise<unknown>\n  release(id: string, signal?: AbortSignal): Promise<void>\n  session(id: string, signal?: AbortSignal): Promise<unknown>\n  listSessions(signal?: AbortSignal): Promise<void>\n}\n\nexport function createSteelApi(input: SteelApiInput): SteelApi {\n  const api = createVendorApi({\n    vendor: 'Steel',\n    baseUrl: input.apiUrl,\n    headers: input.apiKey === undefined ? {} : { 'steel-api-key': input.apiKey },\n  })\n\n  const sessionPath = (id: string) => `v1/sessions/${encodeURIComponent(id)}`\n\n  async function session(id: string, signal?: AbortSignal): Promise<unknown> {\n    const response = await api.send('GET', sessionPath(id), {\n      headers: { accept: 'application/json' },\n      signal,\n    })\n    if (response.status === 404) {\n      await response.body?.cancel()\n      return undefined\n    }\n    if (!response.ok) throw await api.failure(response, 'GET /v1/sessions/{id}')\n    return api.json(response)\n  }\n\n  async function released(id: string, signal?: AbortSignal): Promise<boolean> {\n    let current: unknown\n    try {\n      current = await session(id, signal)\n    } catch {\n      return false\n    }\n    if (current === undefined) return true\n    const parsed = SessionStatusSchema.safeParse(current)\n    return parsed.success && parsed.data.status !== 'live'\n  }\n\n  return {\n    async createSession(body) {\n      const response = await api.send('POST', 'v1/sessions', {\n        headers: { 'content-type': 'application/json', accept: 'application/json' },\n        body: JSON.stringify(body),\n      })\n      if (!response.ok) {\n        const failure = await api.failure(response, 'POST /v1/sessions')\n        throw new SteelCreateFailure(failure, response.status)\n      }\n      return api.json(response)\n    },\n\n    async release(id, signal) {\n      const response = await api.send('POST', `${sessionPath(id)}/release`, {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (response.ok || response.status === 404) {\n        await response.body?.cancel()\n        return\n      }\n      const failure = await api.failure(response, 'POST /v1/sessions/{id}/release')\n      if (await released(id, signal)) return\n      throw failure\n    },\n\n    session,\n\n    async listSessions(signal) {\n      const response = await api.send('GET', 'v1/sessions?limit=1', {\n        headers: { accept: 'application/json' },\n        signal,\n      })\n      if (!response.ok) throw await api.failure(response, 'GET /v1/sessions')\n      await response.body?.cancel()\n    },\n  }\n}\n","import { randomUUID } from 'node:crypto'\nimport {\n  checkEndpoints,\n  credential,\n  definePlugin,\n  PluginError,\n  z,\n  type AcquireInput,\n} from '@vostride/agent-qa-plugin-kit'\nimport { createSteelApi, SteelCreateFailure, SteelSessionSchema } from './steel-api.js'\n\nconst STEEL_API_URL = 'https://api.steel.dev'\nconst MINUTE_MS = 60_000\nconst LIFETIME_REFUSALS: readonly number[] = [400, 422]\nconst SMALLEST_PLAN_CAP_MINUTES = 15\nconst LIFETIME_WORDS = /timeout|lifetime|duration|minute|plan|limit/i\n\nconst options = z.strictObject({\n  apiKey: credential('The Steel API key; leave it out for a self-hosted steel-browser').optional(),\n  apiUrl: z\n    .url()\n    .default(STEEL_API_URL)\n    .describe(\"Steel'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(1440)\n    .default(1440)\n    .describe('Minutes before Steel ends the session; your Steel plan may cap it lower'),\n  idleMinutes: z\n    .int()\n    .min(1)\n    .max(60)\n    .default(5)\n    .describe('Minutes with no CDP command before Steel ends the session'),\n  solveCaptcha: z.boolean().default(false).describe(\"Steel's CAPTCHA solving\"),\n  blockAds: z.boolean().default(false).describe(\"Steel's ad blocking\"),\n  fingerprint: z\n    .boolean()\n    .default(false)\n    .describe(\"Steel's browser fingerprint injection, which changes what pages see\"),\n  proxy: z\n    .union([z.boolean(), z.record(z.string(), z.unknown())])\n    .default(false)\n    .describe(\"Steel's proxy, true or Steel's proxy object, sent as useProxy\"),\n  proxyUrl: credential(\n    \"Your own proxy, http(s)://user:password@host:port, sent instead of Steel's\",\n  ).optional(),\n  dimensions: z\n    .strictObject({ width: z.int().positive(), height: z.int().positive() })\n    .optional()\n    .describe('The browser window size'),\n  region: z.string().min(1).optional().describe('The Steel region, for example us-east'),\n  profile: z\n    .string()\n    .min(1)\n    .optional()\n    .describe('A Steel profile id loaded read-only; needs context: reuse'),\n  extensions: z\n    .array(z.string().min(1))\n    .min(1)\n    .optional()\n    .describe('Steel 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 SteelSettings = z.output<typeof settings>\ntype Session = AcquireInput<unknown, unknown>['session']\n\nfunction checkSettings(input: SteelSettings, 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  if (input.extra !== undefined && Object.hasOwn(input.extra, 'sessionId')) {\n    throw new PluginError(\n      'extra cannot set sessionId; the plugin chooses it to release the session.',\n      { kind: 'refused', path: 'settings.extra.sessionId' },\n    )\n  }\n  if (input.proxyUrl !== undefined && input.proxy !== false) {\n    throw new PluginError('proxy and proxyUrl both choose a proxy; set one of them.', {\n      kind: 'refused',\n      path: 'settings.proxyUrl',\n    })\n  }\n}\n\nfunction createBody(sessionId: string, input: SteelSettings): Record<string, unknown> {\n  return {\n    sessionId,\n    timeout: input.timeoutMinutes * MINUTE_MS,\n    inactivityTimeout: input.idleMinutes * MINUTE_MS,\n    solveCaptcha: input.solveCaptcha,\n    blockAds: input.blockAds,\n    ...(input.proxyUrl === undefined ? { useProxy: input.proxy } : {}),\n    stealthConfig: { skipFingerprintInjection: !input.fingerprint },\n    ...(input.proxyUrl === undefined ? {} : { proxyUrl: input.proxyUrl }),\n    ...(input.dimensions === undefined ? {} : { dimensions: input.dimensions }),\n    ...(input.region === undefined ? {} : { region: input.region }),\n    ...(input.profile === undefined ? {} : { profileId: input.profile }),\n    ...(input.extensions === undefined ? {} : { extensionIds: input.extensions }),\n    ...input.extra,\n  }\n}\n\n// A create Steel refused with a 4xx made no session. Anything else (no answer, a 5xx, an\n// unreadable answer) may have, so it carries the handle that releases it.\nfunction mayHaveCreated(error: unknown): boolean {\n  return !(error instanceof SteelCreateFailure) || error.status >= 500\n}\n\n// How Steel refuses a lifetime above the plan's cap is undocumented, so the hint is added only when\n// the lifetime asked for is above the smallest cap and Steel's reason, if any, may be about it.\nfunction lifetimeMayBeRefused(error: unknown, timeoutMinutes: number): boolean {\n  if (!(error instanceof SteelCreateFailure) || !LIFETIME_REFUSALS.includes(error.status)) {\n    return false\n  }\n  if (timeoutMinutes <= SMALLEST_PLAN_CAP_MINUTES) return false\n  const reason = error.message.split(': ').slice(1).join(': ')\n  return reason === '' || LIFETIME_WORDS.test(reason)\n}\n\nfunction createFailure(error: unknown, sessionId: string, timeoutMinutes: number): PluginError {\n  const message = error instanceof Error ? error.message : String(error)\n  const kind = error instanceof PluginError ? error.kind : 'refused'\n  const text = lifetimeMayBeRefused(error, timeoutMinutes)\n    ? `${message.replace(/[\\s.;,]+$/, '')}; if your Steel plan caps sessions below ${String(timeoutMinutes)} minutes, set settings.timeoutMinutes to the cap`\n    : message\n  return new PluginError(text, {\n    kind,\n    ...(mayHaveCreated(error) ? { handle: { sessionId } } : {}),\n  })\n}\n\nfunction minutesOf(ms: number): string {\n  return String(Number((ms / MINUTE_MS).toFixed(1)))\n}\n\nfunction noteGrantedLifetime(granted: number | undefined, asked: unknown): void {\n  if (granted === undefined || typeof asked !== 'number' || granted >= asked) return\n  process.stderr.write(\n    `Steel granted a ${minutesOf(granted)}-minute session; ${minutesOf(asked)} minutes were asked for\\n`,\n  )\n}\n\nfunction viewerLink(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\nfunction hasId(answer: unknown): boolean {\n  if (typeof answer !== 'object' || answer === null || !('id' in answer)) return false\n  return typeof answer.id === 'string' && answer.id !== ''\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\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    try {\n      await createSteelApi(options).listSessions(ctx.signal)\n    } catch (error) {\n      if (!refusedKey(error)) return { state: 'warn', lines: [failureLine(error)] }\n      const line =\n        options.apiKey === undefined\n          ? 'Steel asked for an API key; set options.apiKey'\n          : 'the API key was refused'\n      return { state: 'warn', lines: [line] }\n    }\n    const line =\n      options.apiKey === undefined\n        ? 'Steel answered without an API key'\n        : 'the API key was accepted'\n    return { state: 'ok', lines: [line] }\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(`Steel runs Chromium web sessions only, not ${what}.`, {\n        kind: 'refused',\n      })\n    }\n    checkSettings(settings, session)\n    const api = createSteelApi(options)\n    const sessionId = randomUUID()\n    const body = createBody(sessionId, settings)\n    let created: unknown\n    // The create is not cancelled: once Steel has a session, the handle must come back to be\n    // released, and the kit releases a handle that arrives after a cancel was answered.\n    try {\n      created = await api.createSession(body)\n    } catch (error) {\n      throw createFailure(error, sessionId, settings.timeoutMinutes)\n    }\n    const answer = SteelSessionSchema.safeParse(created)\n    const url = answer.success ? URL.parse(answer.data.websocketUrl) : null\n    if (!answer.success || url === null) {\n      const missing = hasId(created) ? 'a usable websocketUrl' : 'an id'\n      throw new PluginError(`Steel answered a session without ${missing}.`, {\n        kind: 'refused',\n        handle: { sessionId: answer.success ? answer.data.id : sessionId },\n      })\n    }\n    const { id, debugUrl, sessionViewerUrl, timeout } = answer.data\n    noteGrantedLifetime(timeout, body.timeout)\n    if (options.apiKey !== undefined) url.searchParams.set('apiKey', options.apiKey)\n    const link = viewerLink(sessionViewerUrl)\n    return {\n      handle: { sessionId: id },\n      protocol: 'cdp' as const,\n      url: url.href,\n      mask: debugUrl === undefined ? [url.href] : [url.href, debugUrl],\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 Steel handle names its session by sessionId.', { kind: 'refused' })\n    }\n    await createSteelApi(options).release(parsed.data.sessionId, ctx.signal)\n  },\n})\n"],"mappings":";;;AAEA,MAAa,qBAAqB,EAAE,OAAO;CACzC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACpB,cAAc,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAC9B,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CACrC,kBAAkB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;CAC7C,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS;AAC/B,CAAC;AAED,MAAM,sBAAsB,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAG3D,IAAa,qBAAb,cAAwC,YAAY;CAGvC;CAFX,YACE,SACA,QACA;EACA,MAAM,QAAQ,SAAS,EAAE,MAAM,QAAQ,KAAK,CAAC;EAFpC,KAAA,SAAA;CAGX;AACF;AAcA,SAAgB,eAAe,OAAgC;CAC7D,MAAM,MAAM,gBAAgB;EAC1B,QAAQ;EACR,SAAS,MAAM;EACf,SAAS,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,iBAAiB,MAAM,OAAO;CAC7E,CAAC;CAED,MAAM,eAAe,OAAe,eAAe,mBAAmB,EAAE;CAExE,eAAe,QAAQ,IAAY,QAAwC;EACzE,MAAM,WAAW,MAAM,IAAI,KAAK,OAAO,YAAY,EAAE,GAAG;GACtD,SAAS,EAAE,QAAQ,mBAAmB;GACtC;EACF,CAAC;EACD,IAAI,SAAS,WAAW,KAAK;GAC3B,MAAM,SAAS,MAAM,OAAO;GAC5B;EACF;EACA,IAAI,CAAC,SAAS,IAAI,MAAM,MAAM,IAAI,QAAQ,UAAU,uBAAuB;EAC3E,OAAO,IAAI,KAAK,QAAQ;CAC1B;CAEA,eAAe,SAAS,IAAY,QAAwC;EAC1E,IAAI;EACJ,IAAI;GACF,UAAU,MAAM,QAAQ,IAAI,MAAM;EACpC,QAAQ;GACN,OAAO;EACT;EACA,IAAI,YAAY,KAAA,GAAW,OAAO;EAClC,MAAM,SAAS,oBAAoB,UAAU,OAAO;EACpD,OAAO,OAAO,WAAW,OAAO,KAAK,WAAW;CAClD;CAEA,OAAO;EACL,MAAM,cAAc,MAAM;GACxB,MAAM,WAAW,MAAM,IAAI,KAAK,QAAQ,eAAe;IACrD,SAAS;KAAE,gBAAgB;KAAoB,QAAQ;IAAmB;IAC1E,MAAM,KAAK,UAAU,IAAI;GAC3B,CAAC;GACD,IAAI,CAAC,SAAS,IAEZ,MAAM,IAAI,mBAAmB,MADP,IAAI,QAAQ,UAAU,mBAAmB,GACzB,SAAS,MAAM;GAEvD,OAAO,IAAI,KAAK,QAAQ;EAC1B;EAEA,MAAM,QAAQ,IAAI,QAAQ;GACxB,MAAM,WAAW,MAAM,IAAI,KAAK,QAAQ,GAAG,YAAY,EAAE,EAAE,WAAW;IACpE,SAAS,EAAE,QAAQ,mBAAmB;IACtC;GACF,CAAC;GACD,IAAI,SAAS,MAAM,SAAS,WAAW,KAAK;IAC1C,MAAM,SAAS,MAAM,OAAO;IAC5B;GACF;GACA,MAAM,UAAU,MAAM,IAAI,QAAQ,UAAU,gCAAgC;GAC5E,IAAI,MAAM,SAAS,IAAI,MAAM,GAAG;GAChC,MAAM;EACR;EAEA;EAEA,MAAM,aAAa,QAAQ;GACzB,MAAM,WAAW,MAAM,IAAI,KAAK,OAAO,uBAAuB;IAC5D,SAAS,EAAE,QAAQ,mBAAmB;IACtC;GACF,CAAC;GACD,IAAI,CAAC,SAAS,IAAI,MAAM,MAAM,IAAI,QAAQ,UAAU,kBAAkB;GACtE,MAAM,SAAS,MAAM,OAAO;EAC9B;CACF;AACF;;AC/FA,MAAM,gBAAgB;AACtB,MAAM,YAAY;AAClB,MAAM,oBAAuC,CAAC,KAAK,GAAG;AACtD,MAAM,4BAA4B;AAClC,MAAM,iBAAiB;AAEvB,MAAM,UAAU,EAAE,aAAa;CAC7B,QAAQ,WAAW,iEAAiE,CAAC,CAAC,SAAS;CAC/F,QAAQ,EACL,IAAI,CAAC,CACL,QAAQ,aAAa,CAAC,CACtB,SAAS,wDAAwD;AACtE,CAAC;AAED,MAAM,WAAW,EAAE,aAAa;CAC9B,gBAAgB,EACb,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,IAAI,CAAC,CACT,QAAQ,IAAI,CAAC,CACb,SAAS,yEAAyE;CACrF,aAAa,EACV,IAAI,CAAC,CACL,IAAI,CAAC,CAAC,CACN,IAAI,EAAE,CAAC,CACP,QAAQ,CAAC,CAAC,CACV,SAAS,2DAA2D;CACvE,cAAc,EAAE,QAAQ,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,SAAS,yBAAyB;CAC3E,UAAU,EAAE,QAAQ,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,SAAS,qBAAqB;CACnE,aAAa,EACV,QAAQ,CAAC,CACT,QAAQ,KAAK,CAAC,CACd,SAAS,qEAAqE;CACjF,OAAO,EACJ,MAAM,CAAC,EAAE,QAAQ,GAAG,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CACvD,QAAQ,KAAK,CAAC,CACd,SAAS,+DAA+D;CAC3E,UAAU,WACR,4EACF,CAAC,CAAC,SAAS;CACX,YAAY,EACT,aAAa;EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,SAAS;EAAG,QAAQ,EAAE,IAAI,CAAC,CAAC,SAAS;CAAE,CAAC,CAAC,CACvE,SAAS,CAAC,CACV,SAAS,yBAAyB;CACrC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,uCAAuC;CACrF,SAAS,EACN,OAAO,CAAC,CACR,IAAI,CAAC,CAAC,CACN,SAAS,CAAC,CACV,SAAS,2DAA2D;CACvE,YAAY,EACT,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACxB,IAAI,CAAC,CAAC,CACN,SAAS,CAAC,CACV,SAAS,6CAA6C;CACzD,OAAO,EACJ,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC,CAAC,CAC/B,SAAS,CAAC,CACV,SAAS,yEAAyE;AACvF,CAAC;AAKD,SAAS,cAAc,OAAsB,SAAwB;CACnE,IAAI,MAAM,YAAY,KAAA,MAAc,QAAQ,aAAa,SAAS,QAAQ,YAAY,UACpF,MAAM,IAAI,YACR,+EACA;EAAE,MAAM;EAAW,MAAM;CAAmB,CAC9C;CAEF,IAAI,MAAM,UAAU,KAAA,KAAa,OAAO,OAAO,MAAM,OAAO,WAAW,GACrE,MAAM,IAAI,YACR,6EACA;EAAE,MAAM;EAAW,MAAM;CAA2B,CACtD;CAEF,IAAI,MAAM,aAAa,KAAA,KAAa,MAAM,UAAU,OAClD,MAAM,IAAI,YAAY,4DAA4D;EAChF,MAAM;EACN,MAAM;CACR,CAAC;AAEL;AAEA,SAAS,WAAW,WAAmB,OAA+C;CACpF,OAAO;EACL;EACA,SAAS,MAAM,iBAAiB;EAChC,mBAAmB,MAAM,cAAc;EACvC,cAAc,MAAM;EACpB,UAAU,MAAM;EAChB,GAAI,MAAM,aAAa,KAAA,IAAY,EAAE,UAAU,MAAM,MAAM,IAAI,CAAC;EAChE,eAAe,EAAE,0BAA0B,CAAC,MAAM,YAAY;EAC9D,GAAI,MAAM,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU,MAAM,SAAS;EACnE,GAAI,MAAM,eAAe,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY,MAAM,WAAW;EACzE,GAAI,MAAM,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;EAC7D,GAAI,MAAM,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,MAAM,QAAQ;EAClE,GAAI,MAAM,eAAe,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc,MAAM,WAAW;EAC3E,GAAG,MAAM;CACX;AACF;AAIA,SAAS,eAAe,OAAyB;CAC/C,OAAO,EAAE,iBAAiB,uBAAuB,MAAM,UAAU;AACnE;AAIA,SAAS,qBAAqB,OAAgB,gBAAiC;CAC7E,IAAI,EAAE,iBAAiB,uBAAuB,CAAC,kBAAkB,SAAS,MAAM,MAAM,GACpF,OAAO;CAET,IAAI,kBAAkB,2BAA2B,OAAO;CACxD,MAAM,SAAS,MAAM,QAAQ,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI;CAC3D,OAAO,WAAW,MAAM,eAAe,KAAK,MAAM;AACpD;AAEA,SAAS,cAAc,OAAgB,WAAmB,gBAAqC;CAC7F,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CACrE,MAAM,OAAO,iBAAiB,cAAc,MAAM,OAAO;CACzD,MAAM,OAAO,qBAAqB,OAAO,cAAc,IACnD,GAAG,QAAQ,QAAQ,aAAa,EAAE,EAAE,2CAA2C,OAAO,cAAc,EAAE,oDACtG;CACJ,OAAO,IAAI,YAAY,MAAM;EAC3B;EACA,GAAI,eAAe,KAAK,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC;CAC3D,CAAC;AACH;AAEA,SAAS,UAAU,IAAoB;CACrC,OAAO,OAAO,QAAQ,KAAK,UAAA,CAAW,QAAQ,CAAC,CAAC,CAAC;AACnD;AAEA,SAAS,oBAAoB,SAA6B,OAAsB;CAC9E,IAAI,YAAY,KAAA,KAAa,OAAO,UAAU,YAAY,WAAW,OAAO;CAC5E,QAAQ,OAAO,MACb,mBAAmB,UAAU,OAAO,EAAE,mBAAmB,UAAU,KAAK,EAAE,0BAC5E;AACF;AAEA,SAAS,WAAW,KAA6C;CAC/D,IAAI,QAAQ,KAAA,GAAW,OAAO,KAAA;CAC9B,OAAO,IAAI,MAAM,GAAG,CAAC,EAAE,aAAa,WAAW,MAAM,KAAA;AACvD;AAEA,MAAM,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAE9D,SAAS,MAAM,QAA0B;CACvC,IAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,EAAE,QAAQ,SAAS,OAAO;CAC/E,OAAO,OAAO,OAAO,OAAO,YAAY,OAAO,OAAO;AACxD;AAEA,SAAS,WAAW,OAAyB;CAC3C,OAAO,iBAAiB,eAAe,MAAM,SAAS;AACxD;AAEA,SAAS,YAAY,OAAwB;CAC3C,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;AAEA,IAAA,iBAAe,aAAa;CAC1B;CACA;CACA,QAAQ,CAAC,KAAK;CACd,OAAO;CAEP,WAAW,EAAE,WAAW;EACtB,eAAe,SAAS,CAAC;GAAE,MAAM;GAAU,QAAQ;EAAQ,CAAC,CAAC;CAC/D;CAEA,MAAM,MAAM,EAAE,WAAW,KAAK;EAC5B,IAAI;GACF,MAAM,eAAe,OAAO,CAAC,CAAC,aAAa,IAAI,MAAM;EACvD,SAAS,OAAO;GACd,IAAI,CAAC,WAAW,KAAK,GAAG,OAAO;IAAE,OAAO;IAAQ,OAAO,CAAC,YAAY,KAAK,CAAC;GAAE;GAK5E,OAAO;IAAE,OAAO;IAAQ,OAAO,CAH7B,QAAQ,WAAW,KAAA,IACf,mDACA,yBAC8B;GAAE;EACxC;EAKA,OAAO;GAAE,OAAO;GAAM,OAAO,CAH3B,QAAQ,WAAW,KAAA,IACf,sCACA,0BAC4B;EAAE;CACtC;CAEA,MAAM,QAAQ,EAAE,SAAS,UAAU,WAAW;EAC5C,IAAI,QAAQ,aAAa,SAAS,QAAQ,WAAW,YAAY;GAC/D,MAAM,OAAO,QAAQ,aAAa,QAAQ,QAAQ,SAAS,QAAQ;GACnE,MAAM,IAAI,YAAY,8CAA8C,KAAK,IAAI,EAC3E,MAAM,UACR,CAAC;EACH;EACA,cAAc,UAAU,OAAO;EAC/B,MAAM,MAAM,eAAe,OAAO;EAClC,MAAM,YAAY,WAAW;EAC7B,MAAM,OAAO,WAAW,WAAW,QAAQ;EAC3C,IAAI;EAGJ,IAAI;GACF,UAAU,MAAM,IAAI,cAAc,IAAI;EACxC,SAAS,OAAO;GACd,MAAM,cAAc,OAAO,WAAW,SAAS,cAAc;EAC/D;EACA,MAAM,SAAS,mBAAmB,UAAU,OAAO;EACnD,MAAM,MAAM,OAAO,UAAU,IAAI,MAAM,OAAO,KAAK,YAAY,IAAI;EACnE,IAAI,CAAC,OAAO,WAAW,QAAQ,MAAM;GACnC,MAAM,UAAU,MAAM,OAAO,IAAI,0BAA0B;GAC3D,MAAM,IAAI,YAAY,oCAAoC,QAAQ,IAAI;IACpE,MAAM;IACN,QAAQ,EAAE,WAAW,OAAO,UAAU,OAAO,KAAK,KAAK,UAAU;GACnE,CAAC;EACH;EACA,MAAM,EAAE,IAAI,UAAU,kBAAkB,YAAY,OAAO;EAC3D,oBAAoB,SAAS,KAAK,OAAO;EACzC,IAAI,QAAQ,WAAW,KAAA,GAAW,IAAI,aAAa,IAAI,UAAU,QAAQ,MAAM;EAC/E,MAAM,OAAO,WAAW,gBAAgB;EACxC,OAAO;GACL,QAAQ,EAAE,WAAW,GAAG;GACxB,UAAU;GACV,KAAK,IAAI;GACT,MAAM,aAAa,KAAA,IAAY,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,MAAM,QAAQ;GAC/D,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;EACvC;CACF;CAEA,MAAM,QAAQ,EAAE,SAAS,UAAU,KAAK;EACtC,MAAM,SAAS,aAAa,UAAU,MAAM;EAC5C,IAAI,CAAC,OAAO,SACV,MAAM,IAAI,YAAY,kDAAkD,EAAE,MAAM,UAAU,CAAC;EAE7F,MAAM,eAAe,OAAO,CAAC,CAAC,QAAQ,OAAO,KAAK,WAAW,IAAI,MAAM;CACzE;AACF,CAAC"}

package/dist/plugin.js

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

package/dist/settings.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "timeoutMinutes": {
+      "default": 1440,
+      "description": "Minutes before Steel ends the session; your Steel plan may cap it lower",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1440
+    },
+    "idleMinutes": {
+      "default": 5,
+      "description": "Minutes with no CDP command before Steel ends the session",
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 60
+    },
+    "solveCaptcha": {
+      "default": false,
+      "description": "Steel's CAPTCHA solving",
+      "type": "boolean"
+    },
+    "blockAds": {
+      "default": false,
+      "description": "Steel's ad blocking",
+      "type": "boolean"
+    },
+    "fingerprint": {
+      "default": false,
+      "description": "Steel's browser fingerprint injection, which changes what pages see",
+      "type": "boolean"
+    },
+    "proxy": {
+      "default": false,
+      "description": "Steel's proxy, true or Steel's proxy object, sent as useProxy",
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {}
+        }
+      ]
+    },
+    "proxyUrl": {
+      "type": "string",
+      "credential": true,
+      "description": "Your own proxy, http(s)://user:password@host:port, sent instead of Steel's"
+    },
+    "dimensions": {
+      "description": "The browser window size",
+      "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 Steel region, for example us-east",
+      "type": "string",
+      "minLength": 1
+    },
+    "profile": {
+      "description": "A Steel profile id loaded read-only; needs context: reuse",
+      "type": "string",
+      "minLength": 1
+    },
+    "extensions": {
+      "description": "Steel 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-steel",
-  "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 Steel: creates a Steel browser session before a test connects and releases it after.",
+  "keywords": [
+    "agent-qa",
+    "agent-qa-plugin",
+    "steel"
+  ],
+  "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/steel"
+  },
+  "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-steel
+description: Use when configuring agent-qa web tests to run in Steel cloud browsers through the Steel plugin, or when a Steel remote is refused.
+---
+
+# Steel remotes for agent-qa
+
+The Steel plugin gives an agent-qa web test a Steel browser session. Before the test connects it
+creates a session through Steel's API, and after the test it releases the session. Steel runs
+Chromium only. CAPTCHA solving, ad blocking, Steel's proxies and Steel's fingerprint injection 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: steel
+    package: "@vostride/agent-qa-plugin-steel"
+    options:
+      apiKey: "{{secret:STEEL_API_KEY}}"
+
+registry:
+  remotes:
+    - name: steel
+      plugin: steel
+      settings:
+        idleMinutes: 5
+```
+
+- The `plugins` entry holds the account: `apiKey`, and `apiUrl`, which defaults to
+  `https://api.steel.dev`. 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
+  Steel settings.
+- `use.browser.remote: steel` 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-steel@<agent-qa version>`.
+  `agent-qa plugins list` prints that line when the package is missing or the version differs.
+- For a self-hosted steel-browser, set `apiUrl` to its loopback `http://` address, leave out
+  `apiKey`, and set `use.workers: 1`: it serves one session at a time, and releasing one ends
+  whatever session is active. It returns no session link.
+
+## Settings
+
+- `timeoutMinutes` (default `1440`, 1 to 1440): minutes before Steel ends the session. Steel's
+  plans cap it: Launch at 15, Scale at 60, Enterprise at up to 1440.
+- `idleMinutes` (default `5`, 1 to 60): minutes with no CDP command before Steel ends the session.
+  agent-qa's heartbeat keeps a running test from going idle.
+- `solveCaptcha` (default `false`), `blockAds` (default `false`): Steel's CAPTCHA solving and ad
+  blocking.
+- `fingerprint` (default `false`): Steel's fingerprint injection. The plugin always tells Steel to
+  skip it unless this is `true`.
+- `proxy` (default `false`): `true`, or Steel's proxy object, sent as `useProxy`.
+- `proxyUrl`: your own proxy, `http(s)://user:password@host:port`, a credential. Write it as a
+  `{{secret:<name>}}` reference. It is sent instead of Steel's proxy, so do not also set `proxy`.
+- `dimensions` (`{ width, height }`), `region` (for example `us-east`), `extensions` (extension
+  ids): Steel's own create fields.
+- `profile`: a Steel 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: steel-signed-in
+    plugin: steel
+    context: reuse
+    settings:
+      profile: <Steel profile id>
+  ```
+
+- `extra`: any other Steel request field. It is merged last, so it overrides the settings above.
+  It cannot set `sessionId`, which the plugin chooses to release the session.
+
+## When a remote is refused
+
+- `auth`: Steel refused the API key. Check the secret's value.
+- `capacity`: Steel answered 429. The account has no free sessions, or is rate limited. Wait, or
+  lower the run's concurrency.
+- `refused` whose line ends `set settings.timeoutMinutes to the cap`: Steel refused the create with
+  `400` or `422`, and its reason may be the plan capping sessions below the lifetime asked for. Set
+  `timeoutMinutes` to the plan's cap, for example `15` on Launch. A `400` or `422` whose reason
+  names another field ends without this, so fix the field it names.
+- `refused` with path `settings.profile`: the remote sets `profile` without `context: reuse`. Add
+  `context: reuse` to the remote.
+- `refused` with path `settings.extra.sessionId`: `extra` sets `sessionId`. Remove it.
+- `refused` with path `settings.proxyUrl`: the remote sets both `proxy` and `proxyUrl`. Keep one.
+- `refused` naming a browser or platform: Steel runs Chromium web tests only. Use
+  `use.browser.name: chromium`, or another remote.
+- `refused` with `Unrecognized key: "recording"`: Steel has no switch to turn recording off, so
+  the plugin has no `recording` setting. Remove it.
+- `refused` at `options.apiUrl`: the endpoint must use `https://` with no user or password, unless
+  it points at this machine.
+- `unreachable`: Steel could not be reached. Check the network, or that a self-hosted
+  steel-browser is running.
+
+## Recording
+
+Steel records every session 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. Steel offers no switch
+to turn recording off. The session link opens the session's page in Steel's dashboard. Steel's
+debug URL lets anyone who has it drive the session, so agent-qa masks it and never shows it.
+
+## Check and describe
+
+- `agent-qa doctor` runs the plugin's account check. It lists sessions to prove the key and opens
+  none.
+- `agent-qa plugins describe steel --json` lists every option and setting with its type, default
+  and description.