@kubb/studio 5.3.15 → 5.3.17

package/dist/index.cjs

@@ -26,76 +26,32 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_protocol = require("./protocol.cjs");
-let node_util = require("node:util");
-let node_process = require("node:process");
-node_process = __toESM(node_process, 1);
-let node_child_process = require("node:child_process");
+let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
+let node_process = require("node:process");
+node_process = __toESM(node_process, 1);
+let node_child_process = require("node:child_process");
 let _kubb_core = require("@kubb/core");
+let tinyexec = require("tinyexec");
+let node_timers_promises = require("node:timers/promises");
 let ofetch = require("ofetch");
-let node_crypto = require("node:crypto");
+let node_util = require("node:util");
 let unstorage = require("unstorage");
 let unstorage_drivers_fs = require("unstorage/drivers/fs");
 unstorage_drivers_fs = __toESM(unstorage_drivers_fs, 1);
-let tinyexec = require("tinyexec");
 let magicast = require("magicast");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
 let node_url = require("node:url");
 let remeda = require("remeda");
-let node_os = require("node:os");
 let node_zlib = require("node:zlib");
 let tsdown = require("tsdown");
 let capnweb = require("capnweb");
 let ws = require("ws");
 ws = __toESM(ws, 1);
-let node_timers_promises = require("node:timers/promises");
-//#region src/constants.ts
-/**
-* Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
-* not whatever default the client would pick on its own.
-*/
-const defaultStudioUrl = "https://kubb.studio";
-/**
-* Defaults the Studio client uses when a host passes nothing.
-* Config path is left out on purpose: each host discovers that itself.
-*/
-const agentDefaults = {
-	studioUrl: defaultStudioUrl,
-	retryIntervalMs: 3e4,
-	heartbeatIntervalMs: 3e4,
-	/**
-	* Slowest heartbeat a host may ask for. Studio drops an agent from the active list once its
-	* stored ping is older than its liveness window, and it stores a ping at most once a minute, so
-	* a slower cadence would make a healthy agent look dead after a single missed ping.
-	*/
-	maxHeartbeatIntervalMs: 6e4,
-	/** How long a heartbeat ping may take before the session is treated as dead. */
-	heartbeatTimeoutMs: 1e4,
-	poolSize: 1,
-	maxGenerations: 8,
-	maxGenerationsMb: 100,
-	maxSnapshotMb: 50
-};
-function positiveNumber(value) {
-	const parsed = Number(value);
-	return value && Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
-}
-/**
-* How many generations an agent keeps and how large they may get, read from
-* `KUBB_AGENT_MAX_GENERATIONS`, `KUBB_AGENT_MAX_GENERATIONS_MB` and `KUBB_AGENT_MAX_SNAPSHOT_MB`.
-* An unset or invalid value keeps the default.
-*/
-function resolveGenerationLimits(env = process.env) {
-	return {
-		maxCount: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS) ?? agentDefaults.maxGenerations)),
-		maxMb: positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS_MB) ?? agentDefaults.maxGenerationsMb,
-		maxSnapshotMb: positiveNumber(env.KUBB_AGENT_MAX_SNAPSHOT_MB) ?? agentDefaults.maxSnapshotMb
-	};
-}
-//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -418,6 +374,89 @@ function getElapsedMs(hrStart) {
 	return Math.round(ms * 100) / 100;
 }
 //#endregion
+//#region package.json
+var version = "5.3.17";
+//#endregion
+//#region src/hooks.ts
+/**
+* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
+* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
+* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
+*
+* Returns a remover, so a session that runs one generation after another on the same emitter does
+* not stack a listener per run.
+*/
+function setupHookListener(hooks, root, signal) {
+	return hooks.hook("kubb:hook:start", async (ctx) => {
+		const { id, command, args } = ctx;
+		if (!id) return;
+		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
+		try {
+			const proc = (0, tinyexec.x)(command, [...args ?? []], {
+				signal,
+				nodeOptions: {
+					cwd: root,
+					detached: true
+				}
+			});
+			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
+				id,
+				line
+			});
+			const { exitCode } = await proc;
+			if (exitCode !== 0) {
+				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+				await hooks.callHook("kubb:hook:end", {
+					id,
+					command,
+					args,
+					success: false,
+					error
+				});
+				await hooks.callHook("kubb:error", { error });
+				return;
+			}
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: true,
+				error: null
+			});
+		} catch (caughtError) {
+			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
+			error.cause = caughtError;
+			await hooks.callHook("kubb:hook:end", {
+				id,
+				command,
+				args,
+				success: false,
+				error
+			});
+			await hooks.callHook("kubb:error", { error });
+		}
+	});
+}
+/**
+* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
+* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
+* that same listener, so a handler added afterward would already have missed it.
+*/
+function waitForHookEnd(hooks, hookId) {
+	return new Promise((resolve, reject) => {
+		const handleHookEnd = (ctx) => {
+			if (ctx.id !== hookId) return;
+			hooks.removeHook("kubb:hook:end", handleHookEnd);
+			if (ctx.success) {
+				resolve();
+				return;
+			}
+			reject(ctx.error);
+		};
+		hooks.hook("kubb:hook:end", handleHookEnd);
+	});
+}
+//#endregion
 //#region src/machine.ts
 /**
 * Key-value storage the runtime uses for its machine secret and the last Studio config.
@@ -498,10 +537,6 @@ function responseMessage(data) {
 */
 const REGISTER_RETRIES = 3;
 /**
-* Shared in-flight registration so concurrent pool sessions trigger one purge, not N.
-*/
-let registrationInFlight = null;
-/**
 * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
 * revoked, or the agent it belonged to was deleted in the Studio UI. Hosts catch this to forget
 * the stored credential and pair again.
@@ -513,119 +548,87 @@ var InvalidAgentTokenError = class extends Error {
 	}
 };
 /**
+* Thrown when Studio refuses this agent's protocol version (426). Retrying cannot help until the
+* agent is upgraded, so hosts stop instead of reconnecting.
+*/
+var IncompatibleAgentError = class extends Error {
+	constructor(studioUrl, detail, options) {
+		super(`Kubb Studio at ${studioUrl} requires a newer agent${detail ? `: ${detail}` : ""}. Upgrade @kubb/studio or the Kubb agent image.`, options);
+		this.name = "IncompatibleAgentError";
+	}
+};
+/**
 * Whether a thrown value carries `statusCode`. Not narrowed to `FetchError`: a host wrapper can
 * throw its own error shape with the same field.
-*
-* A 401 means the agent token itself was rejected. A 403 from the session create endpoint means
-* the machine token stored in Studio no longer matches this agent (missing or mismatched).
 */
 function rejectedWith(error, statusCode) {
 	return error?.statusCode === statusCode;
 }
-function sessionError(cause) {
+function registrationError(cause) {
 	const detail = (cause instanceof ofetch.FetchError ? responseMessage(cause.data) : void 0) ?? getErrorMessage(cause);
-	return new Error(detail ? `Failed to get agent session from Kubb Studio: ${detail}` : "Failed to get agent session from Kubb Studio", { cause });
+	return new Error(detail ? `Failed to register with Kubb Studio: ${detail}` : "Failed to register with Kubb Studio", { cause });
 }
 /**
-* Performs the raw session create request against Studio.
-*/
-async function requestAgentSession({ token, studioUrl }) {
-	const url = `${studioUrl}/api/agent/sessions`;
-	const data = await (0, ofetch.ofetch)(url, {
-		method: "POST",
-		headers: { Authorization: `Bearer ${token}` },
-		body: { machineToken: await getMachineToken() }
-	});
-	if (!data) throw new Error("No data available for agent session");
-	return data;
-}
-/**
-* Obtain an agent session token from Kubb Studio via HTTP.
+* Registers this agent process with Kubb Studio (`POST /api/agent/connect`): binds the machine
+* identity to the token, reports what the process can take on, and gets back the URL of the one
+* socket it keeps open.
 *
-* When Studio rejects the machine token (403), for example after the agent restarted
-* with a new identity while the startup registration call failed, the agent re-registers
-* and retries once, so a single failed registration can't permanently block session creation.
-*/
-async function createAgentSession({ token, studioUrl }) {
-	try {
-		return await requestAgentSession({
-			token,
-			studioUrl
-		});
-	} catch (error) {
-		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		if (!rejectedWith(error, 403) || !await registerAgent({
-			token,
-			studioUrl
-		})) throw sessionError(error);
-		try {
-			return await requestAgentSession({
-				token,
-				studioUrl
-			});
-		} catch (retryError) {
-			if (rejectedWith(retryError, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: retryError });
-			throw sessionError(retryError);
-		}
-	}
-}
-/**
-* Register this agent with Kubb Studio by sending the machine ID.
-* Called on agent startup before creating a WebSocket session, and again when
-* Studio rejects the machine token during session creation.
-*
-* Retries with backoff because a failed registration leaves Studio with a stale
-* machine token that blocks every subsequent session create call. Registration
-* purges all of the agent's sessions on the Studio side, so concurrent callers
-* (multiple pool sessions hitting a 403 at once) share one in-flight run instead
-* of purging each other's fresh sessions.
-*/
-function registerAgent(props) {
-	registrationInFlight ??= runRegistration(props).finally(() => {
-		registrationInFlight = null;
-	});
-	return registrationInFlight;
-}
-async function runRegistration({ token, studioUrl, poolSize }) {
-	const machineToken = await getMachineToken();
+* Retries a transient failure with backoff. A rejected token (401) throws
+* {@link InvalidAgentTokenError} and an unsupported agent version (426) throws
+* {@link IncompatibleAgentError}, since retrying either cannot help.
+*/
+async function registerAgent({ token, studioUrl, instanceId, capacity }) {
+	const body = {
+		machineToken: await getMachineToken(),
+		instanceId,
+		capacity
+	};
 	try {
-		await (0, ofetch.ofetch)(`${studioUrl}/api/agent/connect`, {
+		return await (0, ofetch.ofetch)(`${studioUrl}/api/agent/connect`, {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` },
-			body: {
-				machineToken,
-				poolSize
-			},
+			body,
 			retry: REGISTER_RETRIES,
 			retryDelay: ({ options }) => 2e3 * 2 ** (REGISTER_RETRIES - Number(options.retry))
 		});
-		return true;
 	} catch (error) {
 		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		console.error((0, node_util.styleText)("red", `Failed to register agent with Studio after 4 attempts`));
-		return false;
+		if (rejectedWith(error, 426)) throw new IncompatibleAgentError(studioUrl, error instanceof ofetch.FetchError ? responseMessage(error.data) : void 0, { cause: error });
+		throw registrationError(error);
 	}
 }
 /**
-* Notify Kubb Studio that this agent is disconnecting.
-* Called on process termination or server close. A failed notify is logged and swallowed: the
-* local socket is already gone, and failing teardown must not block shutdown or reconnect.
+* First wait before `createJob` retries a busy or queue-full response, absent a `Retry-After` hint.
 */
-async function disconnect({ sessionId, token, studioUrl, slug, logLevel }) {
-	const url = `${studioUrl}/api/agent/sessions/${sessionId}/disconnect`;
-	const tag = slug ?? "agent";
-	const canLog = logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent;
-	try {
-		await (0, ofetch.ofetch)(url, {
-			method: "POST",
-			headers: { Authorization: `Bearer ${token}` }
-		});
-		if (canLog) console.error((0, node_util.styleText)("green", `[${tag}] Disconnected from Studio`));
-	} catch (error) {
-		const statusCode = error?.statusCode;
-		if (statusCode !== void 0 && statusCode >= 400 && statusCode < 500) return;
-		if (canLog) console.warn((0, node_util.styleText)("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
-	}
+const CREATE_JOB_INITIAL_DELAY_MS = 1e3;
+/**
+* Slowest `createJob` backs off to between retries.
+*/
+const CREATE_JOB_MAX_INTERVAL_MS = 1e4;
+/**
+* Statuses worth retrying: the agent has no free connection yet (409, a stale conflict a moment
+* later resolves), its queue is momentarily full (429), or it has no live connection at all yet
+* (503, an agent process that is mid-reconnect). Anything else (404 agent not found, 401/403 auth)
+* is thrown straight away, since retrying cannot change the outcome.
+*/
+const CREATE_JOB_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
+	409,
+	429,
+	503
+]);
+/**
+* Reads Studio's `Retry-After` header (seconds) off a thrown `ofetch` error, when present.
+*/
+function retryAfterMs(error) {
+	const seconds = Number(error.response?.headers.get("retry-after"));
+	return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+}
+/**
+* Adds up to 30% jitter, so every CI run queued behind the same busy agent does not retry in
+* lockstep.
+*/
+function withJitter(ms) {
+	return ms + Math.random() * ms * .3;
 }
 /**
 * Queues a generation or snapshot job on Studio (`POST /api/jobs`).
@@ -633,6 +636,10 @@ async function disconnect({ sessionId, token, studioUrl, slug, logLevel }) {
 * Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
 * Authenticates with the organization CI API key via `x-api-key`.
 *
+* A busy agent, a full queue, or a momentary lack of a live connection (409, 429, 503) retries with
+* exponential backoff and jitter, honoring Studio's `Retry-After` header when it sends one, up to
+* `timeoutMs`. Every other failure, including a missing agent (404), throws immediately.
+*
 * @example Snapshot job
 * ```ts
 * const job = await createJob({
@@ -646,19 +653,40 @@ async function disconnect({ sessionId, token, studioUrl, slug, logLevel }) {
 * const finished = await waitForJob({ studioUrl, token, id: job.id })
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, config }) {
-	const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs`, {
-		method: "POST",
-		headers: { "x-api-key": token },
-		body: {
-			type,
-			agentId,
-			name,
-			version,
-			config
+async function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, timeoutMs = 6e4, signal }) {
+	const deadline = Date.now() + timeoutMs;
+	let interval = CREATE_JOB_INITIAL_DELAY_MS;
+	for (;;) {
+		signal?.throwIfAborted();
+		try {
+			const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs`, {
+				method: "POST",
+				headers: { "x-api-key": token },
+				body: {
+					type,
+					agentId,
+					name,
+					version,
+					commit,
+					baseId,
+					config
+				},
+				retry: false,
+				timeout: Math.max(deadline - Date.now(), 1),
+				signal
+			});
+			return job;
+		} catch (error) {
+			signal?.throwIfAborted();
+			const status = error.response?.status;
+			if (!status || !CREATE_JOB_RETRYABLE_STATUSES.has(status) || Date.now() >= deadline) throw error;
+			const wait = Math.min(retryAfterMs(error) ?? withJitter(interval), Math.max(deadline - Date.now(), 0));
+			if (signal) await (0, node_timers_promises.setTimeout)(wait, void 0, { signal });
+			else await new Promise((resolve) => setTimeout(resolve, wait));
+			if (Date.now() >= deadline) throw error;
+			interval = Math.min(interval * 2, CREATE_JOB_MAX_INTERVAL_MS);
 		}
-	});
-	return job;
+	}
 }
 /**
 * A job runs a generation and packs a tarball, so it is never done the instant it is queued.
@@ -677,20 +705,26 @@ const MAX_POLL_INTERVAL_MS = 3e4;
 * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
 * deadline passes before Studio finishes.
 */
-async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4 }) {
+async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4, signal }) {
 	const deadline = Date.now() + timeoutMs;
 	let interval = INITIAL_POLL_DELAY_MS;
 	for (;;) {
-		await new Promise((resolve) => setTimeout(resolve, Math.max(Math.min(interval, deadline - Date.now()), 0)));
+		signal?.throwIfAborted();
+		const wait = Math.max(Math.min(interval, deadline - Date.now()), 0);
+		if (signal) await (0, node_timers_promises.setTimeout)(wait, void 0, { signal });
+		else await new Promise((resolve) => setTimeout(resolve, wait));
 		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
 		interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
 		try {
 			const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs/${id}`, {
 				headers: { "x-api-key": token },
-				retry: false
+				retry: false,
+				timeout: Math.max(deadline - Date.now(), 1),
+				signal
 			});
 			if (job.status === "success" || job.status === "failed" || job.status === "canceled") return job;
 		} catch (error) {
+			signal?.throwIfAborted();
 			const response = error.response;
 			if (response?.status !== 429) throw error;
 			const retryAfter = response._data?.data?.tryAgainIn;
@@ -724,89 +758,6 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 	}
 }
 //#endregion
-//#region package.json
-var version = "5.3.15";
-//#endregion
-//#region src/hooks.ts
-/**
-* Register a `kubb:hook:start` listener that spawns the requested command via tinyexec,
-* streams each stdout line as a `kubb:hook:line` event, and calls `kubb:hook:end` with the result.
-* Streaming the output lets Kubb Studio render live hook progress over the WebSocket connection.
-*
-* Returns a remover, so a session that runs one generation after another on the same emitter does
-* not stack a listener per run.
-*/
-function setupHookListener(hooks, root, signal) {
-	return hooks.hook("kubb:hook:start", async (ctx) => {
-		const { id, command, args } = ctx;
-		if (!id) return;
-		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
-		try {
-			const proc = (0, tinyexec.x)(command, [...args ?? []], {
-				signal,
-				nodeOptions: {
-					cwd: root,
-					detached: true
-				}
-			});
-			for await (const line of proc) await hooks.callHook("kubb:hook:line", {
-				id,
-				line
-			});
-			const { exitCode } = await proc;
-			if (exitCode !== 0) {
-				const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-				await hooks.callHook("kubb:hook:end", {
-					id,
-					command,
-					args,
-					success: false,
-					error
-				});
-				await hooks.callHook("kubb:error", { error });
-				return;
-			}
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: true,
-				error: null
-			});
-		} catch (caughtError) {
-			const error = /* @__PURE__ */ new Error(`Hook execute failed: ${commandWithArgs}`);
-			error.cause = caughtError;
-			await hooks.callHook("kubb:hook:end", {
-				id,
-				command,
-				args,
-				success: false,
-				error
-			});
-			await hooks.callHook("kubb:error", { error });
-		}
-	});
-}
-/**
-* Waits for the `kubb:hook:end` matching `hookId`. Register this before calling `kubb:hook:start`:
-* `callHook` awaits its listeners, and {@link setupHookListener} calls `kubb:hook:end` from inside
-* that same listener, so a handler added afterward would already have missed it.
-*/
-function waitForHookEnd(hooks, hookId) {
-	return new Promise((resolve, reject) => {
-		const handleHookEnd = (ctx) => {
-			if (ctx.id !== hookId) return;
-			hooks.removeHook("kubb:hook:end", handleHookEnd);
-			if (ctx.success) {
-				resolve();
-				return;
-			}
-			reject(ctx.error);
-		};
-		hooks.hook("kubb:hook:end", handleHookEnd);
-	});
-}
-//#endregion
 //#region src/resolveConfig.ts
 /**
 * Imports a package, falling back to how the user's project would resolve it.
@@ -1674,6 +1625,60 @@ async function generate({ config, hooks, signal }) {
 	}
 }
 //#endregion
+//#region src/constants.ts
+/**
+* Hosted Kubb Studio URL. Exported so credential stores can bind tokens to the resolved instance,
+* not whatever default the client would pick on its own.
+*/
+const defaultStudioUrl = "https://kubb.studio";
+/**
+* Defaults the Studio client uses when a host passes nothing.
+* Config path is left out on purpose: each host discovers that itself.
+*/
+const agentDefaults = {
+	studioUrl: defaultStudioUrl,
+	retryIntervalMs: 3e4,
+	heartbeatIntervalMs: 3e4,
+	/**
+	* Slowest heartbeat a host may ask for. Studio drops an agent from the active list once its
+	* stored ping is older than its liveness window, and it stores a ping at most once a minute, so
+	* a slower cadence would make a healthy agent look dead after a single missed ping.
+	*/
+	maxHeartbeatIntervalMs: 6e4,
+	/** How long a heartbeat ping may take before the session is treated as dead. */
+	heartbeatTimeoutMs: 1e4,
+	maxConcurrent: 1,
+	maxGenerations: 8,
+	maxGenerationsMb: 100,
+	maxSnapshotMb: 50
+};
+function positiveNumber(value) {
+	const parsed = Number(value);
+	return value && Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
+}
+/**
+* How many generations an agent keeps and how large they may get, read from
+* `KUBB_AGENT_MAX_GENERATIONS`, `KUBB_AGENT_MAX_GENERATIONS_MB` and `KUBB_AGENT_MAX_SNAPSHOT_MB`.
+* An unset or invalid value keeps the default.
+*/
+function resolveGenerationLimits(env = process.env) {
+	return {
+		maxCount: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS) ?? agentDefaults.maxGenerations)),
+		maxMb: positiveNumber(env.KUBB_AGENT_MAX_GENERATIONS_MB) ?? agentDefaults.maxGenerationsMb,
+		maxSnapshotMb: positiveNumber(env.KUBB_AGENT_MAX_SNAPSHOT_MB) ?? agentDefaults.maxSnapshotMb
+	};
+}
+/**
+* An agent's capacity read from `KUBB_AGENT_MAX_CONCURRENT` and `KUBB_AGENT_MEMORY_BUDGET_MB`. An
+* unset or invalid value keeps the default: one job at a time, and no memory budget.
+*/
+function resolveAgentCapacity(env = process.env) {
+	return {
+		maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)),
+		memoryBudgetMb: positiveNumber(env.KUBB_AGENT_MEMORY_BUDGET_MB)
+	};
+}
+//#endregion
 //#region src/snapshotPackage.ts
 const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
 /**
@@ -1816,7 +1821,7 @@ async function createSnapshotPackage(files, packageInfo) {
 //#endregion
 //#region src/generations.ts
 const READ_CONCURRENCY = 50;
-const MB = 1048576;
+const MB$1 = 1048576;
 const INDEX_KEY = "studio/generations.json";
 const hashOf = (content) => (0, node_crypto.createHash)("sha1").update(content).digest("hex").slice(0, 16);
 /**
@@ -1843,8 +1848,9 @@ async function listDisk({ root, outputPath, maxFiles }) {
 * tenant never reaches another's output. The oldest go past `maxCount` or `maxMb`, but the newest
 * always stays.
 */
-function createGenerationStore({ storage, maxCount, maxMb }) {
+function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now }) {
 	let index;
+	const isLive = (generation) => ttlMs === void 0 || generation.keptAt === void 0 || now() - generation.keptAt < ttlMs;
 	const dirOf = (jobId) => `studio/generations/${hashOf(jobId)}/`;
 	async function load() {
 		if (index) return index;
@@ -1860,7 +1866,7 @@ function createGenerationStore({ storage, maxCount, maxMb }) {
 	* Copies `files` into the store as one set of `jobId`. Above `maxSetMb` only the hashes are kept.
 	*/
 	async function keep({ jobId, source, files, maxSetMb }) {
-		const maxSetBytes = maxSetMb * MB;
+		const maxSetBytes = maxSetMb * MB$1;
 		const hashes = {};
 		let bytes = 0;
 		await inParallel({
@@ -1895,13 +1901,20 @@ function createGenerationStore({ storage, maxCount, maxMb }) {
 	return {
 		keep,
 		drop,
-		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId),
-		latest: async () => (await load()).at(-1),
+		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId && isLive(generation)),
+		latest: async () => (await load()).filter(isLive).at(-1),
+		/** Total bytes of every set the store holds, expired ones too until the next add drops them. */
+		bytes: async () => (await load()).reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0),
 		async add(generation) {
-			const entries = (await load()).filter((entry) => entry.jobId !== generation.jobId);
-			entries.push(generation);
+			const current = await load();
+			for (const expired of current.filter((entry) => !isLive(entry))) await drop(expired.jobId);
+			const entries = current.filter((entry) => entry.jobId !== generation.jobId && isLive(entry));
+			entries.push({
+				...generation,
+				keptAt: now()
+			});
 			const weight = () => entries.reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0);
-			while (entries.length > 1 && (entries.length > maxCount || weight() > maxMb * MB)) await drop(entries.shift().jobId);
+			while (entries.length > 1 && (entries.length > maxCount || weight() > maxMb * MB$1)) await drop(entries.shift().jobId);
 			index = entries;
 			await storage.writeItem(INDEX_KEY, JSON.stringify(entries));
 		},
@@ -2188,6 +2201,9 @@ var AgentRpcTarget = class extends capnweb.RpcTarget {
 	readFiles(input) {
 		return this.api.readFiles(input);
 	}
+	cancel(jobId) {
+		return this.api.cancel(jobId);
+	}
 };
 /**
 * Opens an authenticated Cap'n Web session to Studio over a WebSocket. Rejects an unencrypted URL
@@ -2199,11 +2215,17 @@ var AgentRpcTarget = class extends capnweb.RpcTarget {
 * await rpc.studio.ping()
 * ```
 */
-const connectWebSocketRpc = async ({ url, token, local }) => {
+const connectWebSocketRpc = async ({ url, token, instanceId, local }) => {
 	const { protocol, hostname, host } = new URL(url);
 	if (protocol !== "wss:" && !(protocol === "ws:" && (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]"))) throw new Error(`Refusing unencrypted WebSocket to ${host}`);
-	const socket = createWebsocket(url, { headers: { Authorization: `Bearer ${token}` } });
-	const closed = new Promise((resolve) => socket.once("close", resolve));
+	const socket = createWebsocket(url, { headers: {
+		Authorization: `Bearer ${token}`,
+		[require_protocol.AGENT_INSTANCE_HEADER]: instanceId
+	} });
+	const closed = new Promise((resolve) => socket.once("close", (code, reason) => resolve({
+		code,
+		reason: reason.toString()
+	})));
 	const studio = (0, capnweb.newWebSocketRpcSession)(socket, new AgentRpcTarget(local));
 	studio.onRpcBroken(() => socket.close());
 	return {
@@ -2218,6 +2240,32 @@ const connectWebSocketRpc = async ({ url, token, local }) => {
 * Past this many files in the output directory, no snapshot of it is taken before a run.
 */
 const DISK_SNAPSHOT_MAX_FILES = 1e4;
+/**
+* How long a sandbox keeps a generation readable. Its store is in memory and holds every tenant's
+* runs, so an old one has to go even when count and size leave room. A local agent keeps its runs
+* until count or size pushes them out, so a later run can still diff against the one before it.
+*/
+const SANDBOX_GENERATION_TTL_MS = 9e5;
+/**
+* A fresh root for one sandbox job. Kubb keys its output manifest cache by root, so tenants that
+* shared the agent's own root would read each other's manifest.
+*/
+function createJobRoot() {
+	return (0, node_fs_promises.mkdtemp)(node_path.default.join((0, node_os.tmpdir)(), "kubb-job-"));
+}
+/**
+* Removes a job root and the manifest cache Kubb derived from it. Best effort: a leftover temp
+* directory must not fail a job that already finished.
+*/
+async function removeJobRoot(jobRoot) {
+	await Promise.all([(0, node_fs_promises.rm)(jobRoot, {
+		recursive: true,
+		force: true
+	}), (0, node_fs_promises.rm)((0, _kubb_core.resolveCacheDir)(jobRoot), {
+		recursive: true,
+		force: true
+	})]).catch(() => {});
+}
 var GenerationRunTarget = class extends capnweb.RpcTarget {
 	generationStream;
 	generationResult;
@@ -2264,36 +2312,74 @@ function applyStudioDefaults(options) {
 			...options.permissions
 		},
 		retryInterval: options.retryInterval ?? agentDefaults.retryIntervalMs,
-		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs)
+		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs),
+		capacity: {
+			...resolveAgentCapacity(),
+			...options.capacity
+		},
+		instanceId: options.instanceId ?? (0, node_crypto.randomUUID)()
 	};
 }
 /**
-* Schedules another connection attempt.
-*
-* A free function rather than a method: a pending retry timer reaches whatever it closes over, so
-* closing only over `options` (not a `StudioSession`) keeps a queued retry from pinning a closed
-* socket, its hook emitter, or its session id alive for the length of the retry interval.
+* Jobs one agent process can run at once today. Two runs would share this session's hook emitter,
+* and with it each other's events, until each job runs in its own worker (ADR-0003 slice B2).
 */
-function reconnect(options) {
-	const { signal, retryInterval, onTokenRejected, logLevel } = options;
+const RUNTIME_MAX_CONCURRENT = 1;
+const MB = 1048576;
+function rssMb() {
+	return node_process.default.memoryUsage().rss / MB;
+}
+function backoffDelayMs(attempt, maxMs) {
+	const cap = Math.min(1e3 * 2 ** (attempt - 1), maxMs);
+	return Math.random() * cap;
+}
+function reconnect(options, delayMs, attempt) {
+	const { signal, onTokenRejected } = options;
 	if (signal?.aborted) return;
-	if (logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent) console.error((0, node_util.styleText)("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
 	const cancel = () => clearTimeout(timer);
 	const timer = setTimeout(() => {
 		signal?.removeEventListener("abort", cancel);
 		if (signal?.aborted) return;
-		new StudioSession(options).start().catch((error) => {
-			if (logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent) console.error((0, node_util.styleText)("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
+		new StudioSession({
+			...options,
+			reconnectAttempt: attempt
+		}).start().catch((error) => {
 			if (error instanceof InvalidAgentTokenError) {
 				onTokenRejected?.(error);
 				return;
 			}
-			reconnect(options);
+			if (error instanceof IncompatibleAgentError) return;
+			const nextAttempt = attempt + 1;
+			reconnect(options, backoffDelayMs(nextAttempt, options.retryInterval), nextAttempt);
 		});
-	}, retryInterval);
+	}, delayMs);
 	signal?.addEventListener("abort", cancel, { once: true });
 }
 /**
+* Reads what Studio meant by closing the connection. A code Studio did not send on purpose is an
+* ordinary drop, and the agent reconnects as it always has.
+*/
+function planEnd(close) {
+	const code = close?.code;
+	if (code === require_protocol.AgentCloseCode.REAUTHENTICATE) return {
+		reason: "Kubb Studio asked the agent to register again",
+		retry: true
+	};
+	if (code === require_protocol.AgentCloseCode.SUPERSEDED) return {
+		reason: "another instance of this agent took over",
+		retry: false
+	};
+	if (code === require_protocol.AgentCloseCode.INCOMPATIBLE) return {
+		reason: "this agent is too old for Kubb Studio, or was deleted",
+		retry: false,
+		error: /* @__PURE__ */ new Error("Kubb Studio closed the connection: this agent is too old for it, or was deleted. Upgrade the agent, or pair it again.")
+	};
+	return {
+		reason: "connection closed",
+		retry: true
+	};
+}
+/**
 * One agent-to-Studio RPC transport: opening it, keeping it alive, and serving remote methods.
 * `createClient` opens one per pool slot and is the only caller.
 */
@@ -2306,14 +2392,15 @@ var StudioSession = class {
 	*/
 	#unhooks = [];
 	/**
-	* What `createAgentSession` handed back, and the marker for whether a session exists at all.
-	* Before it resolves there is nothing to disconnect and no sandbox flag to read.
+	* What registration handed back, and the marker for whether the agent registered at all.
+	* Before it resolves there is no sandbox flag to read.
 	*/
-	#session;
+	#registration;
 	#rpc;
 	#studioVersion;
 	#disposed = false;
 	#isGenerating = false;
+	#activeJob;
 	#heartbeatTimer;
 	#lastGeneration;
 	#store;
@@ -2323,15 +2410,17 @@ var StudioSession = class {
 	* host does not queue jobs before the agent session is registered.
 	*/
 	#connectAck = Promise.withResolvers();
-	constructor(options) {
+	#reconnectAttempt;
+	constructor({ reconnectAttempt, ...options }) {
 		this.#options = applyStudioDefaults(options);
+		this.#reconnectAttempt = reconnectAttempt ?? 0;
 		this.#connectAck.promise.catch(() => {});
 	}
 	/**
 	* A sandbox agent runs on Studio's own infrastructure, so it has no user project to touch.
 	*/
 	get #isSandbox() {
-		return this.#session?.isSandbox === true;
+		return this.#registration?.isSandbox === true;
 	}
 	/**
 	* Kept in the project's cache directory, so it survives a restart, except on a sandbox: its pool
@@ -2341,7 +2430,8 @@ var StudioSession = class {
 		this.#store ??= createGenerationStore({
 			storage: this.#isSandbox ? (0, _kubb_core.memoryStorage)() : (0, _kubb_core.cacheStorage)({ root: this.#options.root }),
 			maxCount: this.#limits.maxCount,
-			maxMb: this.#limits.maxMb
+			maxMb: this.#limits.maxMb,
+			ttlMs: this.#isSandbox ? SANDBOX_GENERATION_TTL_MS : void 0
 		});
 		return this.#store;
 	}
@@ -2365,19 +2455,26 @@ var StudioSession = class {
 		return this.#isSandbox || this.#options.permissions.allowRead;
 	}
 	async start() {
-		const { token, studioUrl, signal, heartbeatInterval, installLogger } = this.#options;
+		const { token, studioUrl, signal, heartbeatInterval, installLogger, instanceId, capacity } = this.#options;
 		await installLogger?.(this.#hooks);
 		try {
 			await this.#hooks.callHook("studio:connecting", { url: studioUrl });
-			const session = await createAgentSession({
+			if (this.#reconnectAttempt === 0 && capacity.maxConcurrent > RUNTIME_MAX_CONCURRENT) await this.#warn(`Running ${RUNTIME_MAX_CONCURRENT} job at a time: KUBB_AGENT_MAX_CONCURRENT=${capacity.maxConcurrent} needs per-job workers, which this agent does not have yet`);
+			const registration = await registerAgent({
 				token,
-				studioUrl
+				studioUrl,
+				instanceId,
+				capacity: {
+					...capacity,
+					maxConcurrent: Math.min(capacity.maxConcurrent, RUNTIME_MAX_CONCURRENT)
+				}
 			});
-			this.#session = session;
-			this.#studioVersion = session.version;
+			this.#registration = registration;
+			this.#studioVersion = registration.version;
 			const rpc = await (this.#options.connector ?? connectWebSocketRpc)({
-				url: session.url,
+				url: registration.socketUrl,
 				token,
+				instanceId,
 				local: this
 			});
 			this.#rpc = rpc;
@@ -2392,28 +2489,43 @@ var StudioSession = class {
 					kubb: version,
 					agent: this.#options.version
 				},
-				agentSlug: session.agentSlug,
-				organizationSlug: session.organizationSlug
+				agentSlug: registration.agentSlug,
+				organizationSlug: registration.organizationSlug
 			});
 			await this.#connectAck.promise;
+			this.#reconnectAttempt = 0;
 			await this.#hooks.callHook("studio:ready", {});
 		} catch (error) {
 			this.#disposed = true;
 			this.dispose();
 			await this.#hooks.callHook("studio:error", { error: toError(error) });
-			if (error instanceof InvalidAgentTokenError) throw error;
-			reconnect(this.#options);
+			if (error instanceof InvalidAgentTokenError || error instanceof IncompatibleAgentError) throw error;
+			await this.#reconnect();
 		}
 	}
-	#warn(message) {
-		return this.#hooks.callHook("studio:warn", { message });
+	/**
+	* Tells the host a retry is coming, then schedules it. The host prints the retry, since the
+	* runtime has no output of its own.
+	*/
+	async #reconnect() {
+		if (this.#options.signal?.aborted) return;
+		const attempt = this.#reconnectAttempt + 1;
+		const delayMs = backoffDelayMs(attempt, this.#options.retryInterval);
+		await this.#hooks.callHook("studio:reconnecting", { delayMs });
+		reconnect(this.#options, delayMs, attempt);
+	}
+	#warn(message, permission) {
+		return this.#hooks.callHook("studio:warn", {
+			message,
+			permission
+		});
 	}
 	/**
 	* Declines a request: logs why locally, then tells Studio. The two wordings differ on purpose,
 	* since the log names the request that was ignored and the error names what the caller can do.
 	*/
-	async #refuse(reason, message) {
-		await this.#warn(reason);
+	async #refuse(reason, message, permission) {
+		await this.#warn(reason, permission);
 		throw new Error(message);
 	}
 	#scheduleHeartbeat(interval) {
@@ -2432,10 +2544,31 @@ var StudioSession = class {
 	/**
 	* Races `studio.ping()` against a deadline, so a half-open socket can't hang it forever.
 	* */
-	#ping(rpc) {
+	async #ping(rpc) {
 		const { promise: timedOut, reject: onTimeout } = Promise.withResolvers();
 		const timer = setTimeout(() => onTimeout(/* @__PURE__ */ new Error("Heartbeat ping timed out")), agentDefaults.heartbeatTimeoutMs);
-		return Promise.race([rpc.studio.ping(), timedOut]).finally(() => clearTimeout(timer));
+		try {
+			const load = await Promise.race([this.#load().catch(() => void 0), timedOut]);
+			await Promise.race([rpc.studio.ping(load), timedOut]);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	/**
+	* Whether memory still leaves room for another job. Always, when the host set no budget.
+	*/
+	#isAccepting(memoryMb = rssMb()) {
+		const budget = this.#options.capacity.memoryBudgetMb;
+		return budget === void 0 || memoryMb <= budget * 1.5;
+	}
+	async #load() {
+		const memoryMb = rssMb();
+		return {
+			running: this.#isGenerating ? 1 : 0,
+			rssMb: Math.round(memoryMb),
+			storeBytes: await this.#generations.bytes(),
+			accepting: this.#isAccepting(memoryMb)
+		};
 	}
 	/**
 	* Reads `kubb.config.ts` and reports which plugin options Studio may edit.
@@ -2480,8 +2613,11 @@ var StudioSession = class {
 		this.#connectAck.resolve();
 		return payload;
 	}
-	#onAbort = () => void this.#end({ retry: false });
-	#onClose = () => void this.#end({ retry: true });
+	#onAbort = () => void this.#end({
+		reason: "shutdown",
+		retry: false
+	});
+	#onClose = (close) => void this.#end(planEnd(close));
 	/**
 	* Drops the socket and detaches every listener and timer this session added. Idempotent, and
 	* safe before `connect` opened anything.
@@ -2501,47 +2637,56 @@ var StudioSession = class {
 	* Ends the session: tells Studio it is over, drops the socket, and optionally reconnects.
 	* `#disposed` keeps the close event from running this twice, and a shutdown from reconnecting.
 	*/
-	async #end({ retry }) {
-		const { studioUrl, token, logLevel } = this.#options;
+	async #end({ reason, retry, error }) {
 		if (this.#disposed) return;
 		this.#disposed = true;
 		this.dispose();
-		await this.#hooks.callHook("studio:disconnected", { reason: retry ? "connection closed" : "shutdown" });
-		if (this.#session) await disconnect({
-			sessionId: this.#session.sessionId,
-			studioUrl,
-			token,
-			slug: this.#session.slug,
-			logLevel
-		}).catch(() => {});
-		if (retry) reconnect(this.#options);
+		await this.#hooks.callHook("studio:disconnected", { reason });
+		if (error) await this.#hooks.callHook("studio:error", { error });
+		if (retry) await this.#reconnect();
 	}
 	startGeneration(data) {
 		const generationStream = createGenerationStream(this.#hooks, data.jobId, { onGenerationEnd: (result) => {
 			this.#lastGeneration = result;
 		} });
 		const controller = new AbortController();
-		const result = this.#runGeneration(data, controller).then(async (value) => {
+		const cancelRun = async () => {
+			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
+		};
+		const result = this.#runGeneration(data, controller, cancelRun).then(async (value) => {
 			await generationStream.close();
 			return value;
 		}).catch((error) => {
 			generationStream.fail(error);
 			throw error;
+		}).finally(() => {
+			if (this.#activeJob?.cancel === cancelRun) this.#activeJob = void 0;
 		});
 		result.catch(() => {});
-		return new GenerationRunTarget(generationStream.stream, result, async () => {
-			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
-		}, () => {
+		return new GenerationRunTarget(generationStream.stream, result, cancelRun, () => {
 			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
 			generationStream.dispose();
 		});
 	}
-	async #runGeneration(data, controller) {
+	/**
+	* Cancels the currently running job when its id matches `jobId`.
+	*/
+	async cancel(jobId) {
+		if (this.#activeJob?.jobId === jobId) await this.#activeJob.cancel();
+	}
+	async #runGeneration(data, controller, cancelRun) {
 		if (this.#isGenerating) return this.#refuse("Ignored generate: a generation is already in progress", "A generation is already in progress, please wait for it to finish");
+		if (!this.#isAccepting()) return this.#refuse("Ignored generate: the agent is past its memory budget", "The agent is past its memory budget, try again once it frees memory");
 		this.#isGenerating = true;
+		this.#activeJob = {
+			jobId: data.jobId,
+			cancel: cancelRun
+		};
 		const command = "generate";
-		const { root, loadConfig, permissions, client } = this.#options;
+		const { loadConfig, permissions } = this.#options;
+		let root = this.#options.root;
 		try {
+			if (this.#isSandbox) root = await createJobRoot();
 			await this.#hooks.callHook("studio:command:start", { command });
 			const config = await loadConfig();
 			const patch = data.config;
@@ -2549,10 +2694,7 @@ var StudioSession = class {
 			const adapter = await mergeAdapter(config.adapter, patch?.adapter);
 			const inputOverride = this.#isSandbox ? patch?.input ?? "" : permissions.allowInput && patch?.input || void 0;
 			if (permissions.allowWrite && this.#isSandbox) await this.#warn("Running in a sandbox, so writing files is disabled");
-			if (patch?.input && !this.#canUseInput) {
-				const remedy = client?.kind === "cli" ? "--allowInput, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_INPUT=true";
-				await this.#warn(`Ignored the spec from Studio; set ${remedy} to generate from it`);
-			}
+			if (patch?.input && !this.#canUseInput) await this.#warn("Ignored the spec from Studio: generating from a Studio spec was not granted", "allowInput");
 			const resolvedPlugins = plugins ?? config.plugins;
 			this.#lastGeneration = void 0;
 			const diskFiles = this.#hasProjectOnDisk ? await listDisk({
@@ -2623,6 +2765,7 @@ var StudioSession = class {
 				disk: disk ? { hashes: disk.hashes } : void 0
 			};
 		} finally {
+			if (root !== this.#options.root) await removeJobRoot(root);
 			this.#isGenerating = false;
 		}
 	}
@@ -2732,12 +2875,7 @@ var StudioSession = class {
 	async readFiles(data) {
 		const command = "readFiles";
 		await this.#hooks.callHook("studio:command:start", { command });
-		const { client } = this.#options;
-		if (!this.#canRead) {
-			await this.#warn("Ignored files: reading generated files was not granted");
-			const remedy = client?.kind === "cli" ? "--allow-read, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_READ=true";
-			throw new Error(`The agent was not granted permission to read generated files; set ${remedy} to allow it`);
-		}
+		if (!this.#canRead) return this.#refuse("Ignored files: reading generated files was not granted", "The agent was not granted permission to read generated files", "allowRead");
 		if (!Array.isArray(data.paths)) return this.#refuse("Ignored files: the message carried no paths", "The request carried no paths");
 		const { paths } = data;
 		if (paths.length > 50) return this.#refuse(`Ignored files: requested ${paths.length} paths, more than the 50 allowed per request`, `At most 50 paths may be requested at once`);
@@ -2764,7 +2902,8 @@ var StudioSession = class {
 * Creates the Kubb Studio client: the connection, the command loop, and the generation event
 * stream shared by the `kubb studio` CLI command and the Docker agent.
 *
-* Every permission is off by default. A host that wants more grants it explicitly.
+* Every permission is off by default. A host that wants more grants it explicitly. The machine
+* identity comes from the storage the host installed with `setStorage`, before connecting.
 *
 * @example
 * ```ts
@@ -2772,10 +2911,9 @@ var StudioSession = class {
 * await studio.connect()
 * ```
 */
-function createClient({ storage, onAuthRequired, ...options }) {
-	if (storage) setStorage(storage);
+function createClient({ onAuthRequired, ...options }) {
 	const controller = new AbortController();
-	const poolSize = options.poolSize ?? agentDefaults.poolSize;
+	const instanceId = (0, node_crypto.randomUUID)();
 	function notifyAuthRequired(error) {
 		if (controller.signal.aborted) return;
 		controller.abort();
@@ -2783,16 +2921,12 @@ function createClient({ storage, onAuthRequired, ...options }) {
 	}
 	return {
 		async connect() {
-			await registerAgent({
-				token: options.token,
-				studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
-				poolSize
-			});
-			await Promise.all(Array.from({ length: poolSize }, () => new StudioSession({
+			await new StudioSession({
 				...options,
+				instanceId,
 				signal: controller.signal,
 				onTokenRejected: notifyAuthRequired
-			}).start()));
+			}).start();
 		},
 		disconnect() {
 			controller.abort();
@@ -2874,11 +3008,11 @@ async function runConnection({ credentials, clientOptions, onTokenRejected, sign
 }
 //#endregion
 //#region src/pair.ts
-/**
-* Identifies the CLI to Studio's device authorization endpoint. A label, not a secret: what
-* authorizes a pairing is a signed-in person approving the code in the browser.
-*/
-const CLIENT_ID = "kubb-cli";
+/** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
+const CLIENT_IDS = {
+	cli: "kubb-cli",
+	agent: "kubb-agent"
+};
 /**
 * Thrown when a caller aborts `startPairing` or `pollForPairingToken` through their `signal`, such
 * as a `kubb studio` shutdown mid-pairing. Distinct from a denial or an expired code, so a host can
@@ -2890,21 +3024,35 @@ var PairingCanceledError = class extends Error {
 		this.name = "PairingCanceledError";
 	}
 };
+/** Thrown when the code expired unapproved. A fresh code can still succeed. */
+var PairingExpiredError = class extends Error {
+	constructor(message = "The pairing code expired, pair again") {
+		super(message);
+		this.name = "PairingExpiredError";
+	}
+};
+/** Thrown when the pairing was denied in the browser, including by the organization's agent limit. */
+var PairingDeniedError = class extends Error {
+	constructor(message = "Pairing was denied in the browser") {
+		super(message);
+		this.name = "PairingDeniedError";
+	}
+};
 /**
 * Asks Studio for a pairing code. The machine token travels with the request and is stored against
 * the code, so approval knows which machine it is pairing: the same machine pairing twice rotates
 * one agent's token instead of creating a second agent.
 */
-async function startPairing({ studioUrl = agentDefaults.studioUrl, name, hostname, clientId = CLIENT_ID, agentKind, signal }) {
+async function startPairing({ studioUrl = agentDefaults.studioUrl, type, name, hostname, signal }) {
 	try {
 		return await (0, ofetch.ofetch)(`${studioUrl}/api/auth/device/code`, {
 			method: "POST",
 			body: {
-				client_id: clientId,
+				client_id: type === "cli" ? CLIENT_IDS.cli : CLIENT_IDS.agent,
 				name,
 				hostname,
 				machine_token: await getMachineToken(),
-				agent_kind: agentKind
+				agent_kind: type === "cli" ? void 0 : type
 			},
 			signal
 		});
@@ -2917,15 +3065,16 @@ function isPairingResult(response) {
 	return !!response && typeof response === "object" && "token" in response && typeof response.token === "string";
 }
 /**
-* Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
-* cannot reach Studio is warned about and retried, since the code stays valid either way.
+* Polls until the user approves or denies, honoring the server's `slow_down` back-off.
 *
 * Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
 * Kubb pairing is worth an agent bearer token, not a user session.
 *
-* @throws when the code expires, the user denies it, or Studio returns an unexpected error.
+* @throws {PairingExpiredError} when the code expires before anyone approves it.
+* @throws {PairingDeniedError} when the pairing is denied in the browser.
+* @throws {PairingCanceledError} when `signal` aborts.
 */
-async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal }) {
+async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal, onRetry }) {
 	const deadline = Date.now() + (session.expires_in > 0 ? session.expires_in : 600) * 1e3;
 	let intervalMs = (session.interval > 0 ? session.interval : 5) * 1e3;
 	while (Date.now() < deadline) {
@@ -2945,7 +3094,7 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			});
 		} catch (error) {
 			if (signal?.aborted) throw new PairingCanceledError();
-			console.warn((0, node_util.styleText)("yellow", `Could not reach Kubb Studio while waiting for approval, retrying: ${getErrorMessage(error)}`));
+			onRetry?.(toError(error));
 			continue;
 		}
 		if (isPairingResult(response)) return response;
@@ -2955,15 +3104,39 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			intervalMs += 5e3;
 			continue;
 		}
-		if (response.error === "access_denied") throw new Error(response.error_description ?? "Pairing was denied in the browser");
-		if (response.error === "expired_token" || response.error === "invalid_grant") throw new Error(response.error_description ?? "The pairing code expired, pair again");
+		if (response.error === "access_denied") throw new PairingDeniedError(response.error_description);
+		if (response.error === "expired_token" || response.error === "invalid_grant") throw new PairingExpiredError(response.error_description);
 		throw new Error(response.error_description ?? `Pairing failed (${response.error})`);
 	}
-	throw new Error("The pairing code expired, pair again");
+	throw new PairingExpiredError();
+}
+/**
+* Pairs this machine with Studio: asks for a code, hands it to the host to show, and waits for approval.
+*/
+async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
+	for (let attempt = 1;; attempt++) {
+		const session = await startPairing(options);
+		await onCode(session, attempt);
+		try {
+			return await pollForPairingToken({
+				studioUrl: options.studioUrl,
+				session,
+				signal: options.signal,
+				onRetry
+			});
+		} catch (error) {
+			if (!(error instanceof PairingExpiredError) || attempt >= maxAttempts) throw error;
+		}
+	}
 }
 //#endregion
+exports.AGENT_INSTANCE_HEADER = require_protocol.AGENT_INSTANCE_HEADER;
+exports.AgentCloseCode = require_protocol.AgentCloseCode;
+exports.IncompatibleAgentError = IncompatibleAgentError;
 exports.InvalidAgentTokenError = InvalidAgentTokenError;
 exports.PairingCanceledError = PairingCanceledError;
+exports.PairingDeniedError = PairingDeniedError;
+exports.PairingExpiredError = PairingExpiredError;
 exports.connectWebSocketRpc = connectWebSocketRpc;
 exports.createAgent = createAgent;
 exports.createClient = createClient;
@@ -2972,6 +3145,7 @@ exports.createJob = createJob;
 exports.defaultStudioUrl = defaultStudioUrl;
 exports.generationEventTypes = require_protocol.generationEventTypes;
 exports.machineTokenFrom = machineTokenFrom;
+exports.pairAgent = pairAgent;
 exports.pollForPairingToken = pollForPairingToken;
 exports.runConnection = runConnection;
 exports.setStorage = setStorage;