@kubb/studio 5.3.19 → 5.4.1

package/README.md

@@ -85,7 +85,7 @@ every host.
 
 | Step             | `kubb studio`                           | Docker agent                             | `kubb studio snapshot`                   |
 | ---------------- | --------------------------------------- | ---------------------------------------- | ---------------------------------------- |
-| Machine identity | `setStorage` under `~/.kubb`            | `setStorage` on the Nitro `kubb` mount   | `KUBB_AGENT_SECRET` from the CI identity |
+| Machine identity | `setStorage` under project Kubb home    | `setStorage` on the cache volume         | `KUBB_AGENT_SECRET` from the CI identity |
 | Credentials      | stored, or `pairAgent({ type: 'cli' })` | stored, or `pairAgent({ type: 'user' })` | `createAgent` with the CI API key        |
 | Permissions      | flags and a per-project prompt          | `KUBB_AGENT_ALLOW_*`                     | flags only                               |
 | Connection       | `runConnection`                         | `runConnection`                          | `runConnection`                          |
@@ -128,8 +128,11 @@ come back: `4001` registers and reconnects, `4002` (another instance took over)
 agent is too old or was deleted) stay down. A `426` at registration means the agent is too old for
 that Studio.
 
-The runtime reconnects on its own when the socket drops, and keeps retrying while Studio is
-unreachable. Generation progress is a native Cap'n Web `ReadableStream` on the generation
+`runConnection` owns registration retries, capped reconnect backoff, credential replacement, and
+shutdown. `StudioSession` serves one attempt and waits for canceled generation work to settle before
+the loop reconnects. `createClient` remains a thin compatibility facade over that loop.
+
+The runtime reconnects when the socket drops and keeps retrying while Studio is unreachable. Generation progress is a native Cap'n Web `ReadableStream` on the generation
 capability; durable job status is read through the HTTP job API.
 
 ## Studio job events

package/dist/index.cjs

@@ -27,20 +27,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const require_protocol = require("./protocol.cjs");
 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_timers_promises = require("node:timers/promises");
 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 node_timers_promises = require("node:timers/promises");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
 let ofetch = require("ofetch");
 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 node_os = require("node:os");
+let _kubb_core = require("@kubb/core");
 let magicast = require("magicast");
 let node_fs = require("node:fs");
 let node_module = require("node:module");
@@ -374,9 +374,6 @@ function getElapsedMs(hrStart) {
 	return Math.round(ms * 100) / 100;
 }
 //#endregion
-//#region package.json
-var version = "5.3.19";
-//#endregion
 //#region src/operations/machine.ts
 /**
 * Key-value storage the runtime uses for its machine secret and the last Studio config.
@@ -453,10 +450,6 @@ function responseMessage(data) {
 	]) if (typeof value === "string" && value) return value;
 }
 /**
-* Retries after the first registration attempt, each backing off twice as far as the last.
-*/
-const REGISTER_RETRIES = 3;
-/**
 * 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.
@@ -493,11 +486,11 @@ function registrationError(cause) {
 * identity to the token, reports what the process can take on, and gets back the URL of the one
 * socket it keeps open.
 *
-* Retries a transient failure with backoff. A rejected token (401) throws
+* Makes one bounded attempt; `runConnection` owns retries. 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 }) {
+async function registerAgent({ token, studioUrl, instanceId, capacity, signal }) {
 	const body = {
 		machineToken: await getMachineToken(),
 		instanceId,
@@ -508,8 +501,9 @@ async function registerAgent({ token, studioUrl, instanceId, capacity }) {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` },
 			body,
-			retry: REGISTER_RETRIES,
-			retryDelay: ({ options }) => 2e3 * 2 ** (REGISTER_RETRIES - Number(options.retry))
+			retry: 0,
+			timeout: 1e4,
+			signal
 		});
 	} catch (error) {
 		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
@@ -679,6 +673,60 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 	}
 }
 //#endregion
+//#region src/operations/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`. An unset or invalid value keeps the
+* default: one job at a time.
+*/
+function resolveAgentCapacity(env = process.env) {
+	return { maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)) };
+}
+//#endregion
+//#region package.json
+var version = "5.4.1";
+//#endregion
 //#region src/operations/resolveConfig.ts
 /**
 * Imports a package, falling back to how the user's project would resolve it.
@@ -1414,57 +1462,6 @@ function withTrailingNewline(code, hadTrailingNewline) {
 	return `${code}\n`;
 }
 //#endregion
-//#region src/operations/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`. An unset or invalid value keeps the
-* default: one job at a time.
-*/
-function resolveAgentCapacity(env = process.env) {
-	return { maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)) };
-}
-//#endregion
 //#region src/operations/snapshotPackage.ts
 const gzipAsync = (0, node_util.promisify)(node_zlib.gzip);
 const UPLOAD_TIMEOUT_MS = 12e4;
@@ -2377,39 +2374,13 @@ function applyStudioDefaults(options) {
 }
 /**
 * 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).
+* and with it each other's events, so the connection keeps this limit.
 */
 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;
-	const cancel = () => clearTimeout(timer);
-	const timer = setTimeout(() => {
-		signal?.removeEventListener("abort", cancel);
-		if (signal?.aborted) return;
-		new StudioSession({
-			...options,
-			reconnectAttempt: attempt
-		}).start().catch((error) => {
-			if (error instanceof InvalidAgentTokenError) {
-				onTokenRejected?.(error);
-				return;
-			}
-			if (error instanceof IncompatibleAgentError) return;
-			const nextAttempt = attempt + 1;
-			reconnect(options, backoffDelayMs(nextAttempt, options.retryInterval), nextAttempt);
-		});
-	}, 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.
@@ -2436,7 +2407,7 @@ function planEnd(close) {
 }
 /**
 * 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.
+* `runConnection` owns the lifetime and retry of each attempt.
 */
 var StudioSession = class {
 	#options;
@@ -2465,10 +2436,11 @@ var StudioSession = class {
 	* host does not queue jobs before the agent session is registered.
 	*/
 	#connectAck = Promise.withResolvers();
-	#reconnectAttempt;
-	constructor({ reconnectAttempt, ...options }) {
+	#ended = Promise.withResolvers();
+	closed = this.#ended.promise;
+	#generationResult;
+	constructor(options) {
 		this.#options = applyStudioDefaults(options);
-		this.#reconnectAttempt = reconnectAttempt ?? 0;
 		this.#connectAck.promise.catch(() => {});
 	}
 	/**
@@ -2505,10 +2477,14 @@ var StudioSession = class {
 	async start() {
 		const { token, studioUrl, signal, heartbeatInterval, installLogger, instanceId, capacity } = this.#options;
 		await installLogger?.(this.#hooks);
+		signal?.addEventListener("abort", this.#onAbort, { once: true });
+		this.#unhooks.push(() => signal?.removeEventListener("abort", this.#onAbort));
 		try {
+			signal?.throwIfAborted();
 			await this.#hooks.callHook("studio:connecting", { url: studioUrl });
-			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`);
+			if (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({
+				signal,
 				token,
 				studioUrl,
 				instanceId,
@@ -2517,6 +2493,7 @@ var StudioSession = class {
 					maxConcurrent: Math.min(capacity.maxConcurrent, RUNTIME_MAX_CONCURRENT)
 				}
 			});
+			signal?.throwIfAborted();
 			this.#registration = registration;
 			this.#studioVersion = registration.version;
 			const rpc = await (this.#options.connector ?? connectWebSocketRpc)({
@@ -2527,8 +2504,10 @@ var StudioSession = class {
 			});
 			this.#rpc = rpc;
 			rpc.closed.then(this.#onClose);
-			signal?.addEventListener("abort", this.#onAbort, { once: true });
-			this.#unhooks.push(() => signal?.removeEventListener("abort", this.#onAbort));
+			if (signal?.aborted || this.#disposed) {
+				rpc.close();
+				throw new Error("Connection stopped during startup");
+			}
 			this.#scheduleHeartbeat(heartbeatInterval);
 			await this.#hooks.callHook("studio:connected", {
 				url: studioUrl,
@@ -2541,26 +2520,15 @@ var StudioSession = class {
 				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 || error instanceof IncompatibleAgentError) throw error;
-			await this.#reconnect();
+			await this.dispose();
+			if (!signal?.aborted) await this.#hooks.callHook("studio:error", { error: toError(error) });
+			throw error;
 		}
 	}
-	/**
-	* 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);
+	reportRetry(delayMs) {
+		return this.#hooks.callHook("studio:reconnecting", { delayMs });
 	}
 	#warn(message, permission) {
 		return this.#hooks.callHook("studio:warn", {
@@ -2655,34 +2623,35 @@ var StudioSession = class {
 	#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.
-	*
-	* @internal
-	*/
+	}).catch(() => {});
+	#onClose = (close) => void this.#end(planEnd(close)).catch(() => {});
+	/** Closes this attempt and waits for its generation to stop before another can start. */
 	dispose() {
+		return this.#end({
+			reason: "shutdown",
+			retry: false
+		});
+	}
+	async #end(plan) {
+		if (this.#disposed) {
+			await this.closed;
+			return;
+		}
+		this.#disposed = true;
 		clearTimeout(this.#heartbeatTimer);
-		this.#heartbeatTimer = void 0;
 		this.#rpc?.close();
 		this.#rpc = void 0;
 		this.#connectAck.reject(/* @__PURE__ */ new Error("Session ended before Studio called connect()"));
 		for (const unhook of this.#unhooks) unhook();
 		this.#unhooks.length = 0;
-	}
-	/**
-	* 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({ reason, retry, error }) {
-		if (this.#disposed) return;
-		this.#disposed = true;
-		this.dispose();
-		await this.#hooks.callHook("studio:disconnected", { reason });
-		if (error) await this.#hooks.callHook("studio:error", { error });
-		if (retry) await this.#reconnect();
+		try {
+			await this.#activeJob?.cancel();
+			await this.#generationResult?.catch(() => {});
+			await this.#hooks.callHook("studio:disconnected", { reason: plan.reason });
+			if (plan.error) await this.#hooks.callHook("studio:error", { error: plan.error });
+		} finally {
+			this.#ended.resolve(plan);
+		}
 	}
 	startGeneration(data) {
 		const generationStream = createGenerationStream(this.#hooks, data.jobId, { onGenerationEnd: (result) => {
@@ -2701,6 +2670,7 @@ var StudioSession = class {
 		}).finally(() => {
 			if (this.#activeJob?.cancel === cancelRun) this.#activeJob = void 0;
 		});
+		if (this.#activeJob?.cancel === cancelRun) this.#generationResult = result;
 		result.catch(() => {});
 		return new GenerationRunTarget(generationStream.stream, result, cancelRun, () => {
 			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
@@ -2714,6 +2684,7 @@ var StudioSession = class {
 		if (this.#activeJob?.jobId === jobId) await this.#activeJob.cancel();
 	}
 	async #runGeneration(data, controller, cancelRun) {
+		if (this.#disposed) throw new Error("Connection is closed");
 		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");
 		this.#isGenerating = true;
 		this.#activeJob = {
@@ -2909,114 +2880,92 @@ var StudioSession = class {
 	}
 };
 //#endregion
-//#region src/runtime/client.ts
-/**
-* 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. The machine
-* identity comes from the storage the host installed with `setStorage`, before connecting.
-*
-* @example
-* ```ts
-* const studio = createClient({ token, configPath, version, loadConfig: () => loadMyConfig() })
-* await studio.connect()
-* ```
-*/
-function createClient({ onAuthRequired, ...options }) {
-	const controller = new AbortController();
-	const instanceId = options.instanceId ?? (0, node_crypto.randomUUID)();
-	function notifyAuthRequired(error) {
-		if (controller.signal.aborted) return;
-		controller.abort();
-		onAuthRequired?.(error);
-	}
-	return {
-		async connect() {
-			await new StudioSession({
-				...options,
-				instanceId,
-				signal: controller.signal,
-				onTokenRejected: notifyAuthRequired
-			}).start();
-		},
-		disconnect() {
-			controller.abort();
-		}
-	};
-}
-//#endregion
 //#region src/runtime/runConnection.ts
-/**
-* Waits for whichever comes first: the shutdown signal, or Studio rejecting the token during a
-* background reconnect. Resolves with the rejection, or nothing when the run is being shut down.
-*/
-function waitForRejection(authRequired, signal) {
-	if (!signal) return authRequired;
-	const settled = new AbortController();
-	const shutdown = new Promise((resolve) => {
-		if (signal.aborted) {
-			resolve(void 0);
-			return;
-		}
-		signal.addEventListener("abort", () => resolve(void 0), {
-			once: true,
-			signal: settled.signal
-		});
-	});
-	return Promise.race([shutdown, authRequired]).finally(() => settled.abort());
-}
-/**
-* Keeps a host connected to Studio across token changes: it opens a client, waits until the run
-* ends or Studio rejects the token, and reconnects with whatever credential the host hands back.
-*
-* The host owns everything around that. Where credentials live, whether a rejected token may be
-* replaced, and how any of it is reported are all decisions `onTokenRejected` makes.
-*
-* @example
-* ```ts
-* const outcome = await runConnection({
-*   credentials,
-*   clientOptions: () => ({ studioUrl, configPath, version, loadConfig }),
-*   signal: shutdown.signal,
-*   onTokenRejected: ({ error, live }) => pairAgain(error, live),
-* })
-* ```
-*/
-async function runConnection({ credentials, clientOptions, onTokenRejected, signal }) {
+/** Runs the process's one connection loop, including retries and credential replacement. */
+async function runConnection({ credentials, clientOptions, onTokenRejected, signal, onStarted }) {
 	let current = credentials;
-	while (true) {
-		if (signal?.aborted) return "shutdown";
-		const { promise: authRequired, resolve: notifyAuthRequired } = Promise.withResolvers();
-		const client = createClient({
-			...clientOptions(current),
+	const initialOptions = clientOptions(current);
+	const instanceId = initialOptions.instanceId ?? (0, node_crypto.randomUUID)();
+	let options = initialOptions;
+	let attempt = 0;
+	let live = false;
+	while (!signal?.aborted) {
+		const session = new StudioSession({
+			...options,
+			instanceId,
 			token: current.token,
-			onAuthRequired: notifyAuthRequired
+			signal
 		});
-		let rejection;
 		try {
-			await client.connect();
-			const error = await waitForRejection(authRequired, signal);
-			if (!error) return "shutdown";
-			rejection = {
-				error,
-				credentials: current,
-				live: true
-			};
+			await session.start();
+			live = true;
+			attempt = 0;
+			onStarted?.();
+			if (!(await session.closed).retry) return signal?.aborted ? "shutdown" : "stopped";
 		} catch (error) {
-			if (!(error instanceof InvalidAgentTokenError)) throw error;
-			rejection = {
-				error,
-				credentials: current,
-				live: false
-			};
+			if (signal?.aborted) return "shutdown";
+			if (error instanceof IncompatibleAgentError) throw error;
+			await session.dispose();
+			const end = await session.closed;
+			if (!end.retry && end.reason !== "shutdown") return "stopped";
+			if (error instanceof InvalidAgentTokenError) {
+				const next = await onTokenRejected({
+					error,
+					credentials: current,
+					live
+				});
+				if (!next) return "stopped";
+				current = next;
+				options = clientOptions(current);
+				live = false;
+				attempt = 0;
+				continue;
+			}
 		} finally {
-			client.disconnect();
+			await session.dispose();
+		}
+		onStarted?.();
+		const cap = Math.min(1e3 * 2 ** Math.min(attempt++, 16), options.retryInterval ?? agentDefaults.retryIntervalMs);
+		const delayMs = Math.random() * cap;
+		await session.reportRetry(delayMs);
+		try {
+			await (0, node_timers_promises.setTimeout)(delayMs, void 0, { signal });
+		} catch (error) {
+			if (!signal?.aborted) throw error;
 		}
-		const next = await onTokenRejected(rejection);
-		if (!next) return "stopped";
-		current = next;
 	}
+	return "shutdown";
+}
+//#endregion
+//#region src/runtime/client.ts
+/** Compatibility facade over the shared connection loop. */
+function createClient({ onAuthRequired, ...options }) {
+	const shutdown = new AbortController();
+	const started = Promise.withResolvers();
+	let resolved = false;
+	let running;
+	return {
+		connect() {
+			running ??= runConnection({
+				credentials: { token: options.token },
+				clientOptions: () => options,
+				signal: shutdown.signal,
+				onStarted: () => {
+					resolved = true;
+					started.resolve();
+				},
+				onTokenRejected: async ({ error }) => {
+					if (!resolved) throw error;
+					onAuthRequired?.(error);
+					return null;
+				}
+			}).then(() => started.resolve(), (error) => started.reject(error));
+			return started.promise;
+		},
+		disconnect() {
+			shutdown.abort();
+		}
+	};
 }
 //#endregion
 //#region src/operations/pair.ts