@kubb/studio 5.1.0 → 5.2.1

package/dist/index.cjs

@@ -1,6 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("./rolldown-runtime-qbf5tadS.cjs");
-const require_resolveConfig = require("./resolveConfig-Ci-BVhN_.cjs");
 const require_protocol = require("./protocol.cjs");
 let node_util = require("node:util");
 let node_fs_promises = require("node:fs/promises");
@@ -16,6 +15,11 @@ let unstorage_drivers_fs = require("unstorage/drivers/fs");
 unstorage_drivers_fs = require_rolldown_runtime.__toESM(unstorage_drivers_fs, 1);
 let _kubb_core = require("@kubb/core");
 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 ws = require("ws");
 ws = require_rolldown_runtime.__toESM(ws, 1);
 let node_timers_promises = require("node:timers/promises");
@@ -32,14 +36,43 @@ const defaultStudioUrl = "https://kubb.studio";
 const agentDefaults = {
 	studioUrl: defaultStudioUrl,
 	retryIntervalMs: 3e4,
+	heartbeatIntervalMs: 3e4,
 	/**
-	* Maximum heartbeat interval. Studio drops agents from the active list after ~90s without a ping,
-	* so a slower override would make a healthy agent look dead.
+	* 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.
 	*/
-	heartbeatIntervalMs: 3e4,
+	maxHeartbeatIntervalMs: 6e4,
 	poolSize: 1
 };
 //#endregion
+//#region ../../internals/utils/src/casing.ts
+/**
+* Shared implementation for camelCase and PascalCase conversion.
+* Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
+* and capitalizes each word according to `pascal`.
+*
+* When `pascal` is `true` the first word is also capitalized (PascalCase), otherwise only subsequent words are.
+*/
+function toCamelOrPascal(text, pascal) {
+	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
+		if (word.length > 1 && word === word.toUpperCase()) return word;
+		return (i === 0 && !pascal ? word.charAt(0).toLowerCase() : word.charAt(0).toUpperCase()) + word.slice(1);
+	}).join("").replace(/[^a-zA-Z0-9]/g, "");
+}
+/**
+* Converts `text` to camelCase.
+*
+* @example Word boundaries
+* `camelCase('hello-world') // 'helloWorld'`
+*
+* @example With a prefix
+* `camelCase('tag', { prefix: 'create' }) // 'createTag'`
+*/
+function camelCase(text, { prefix = "", suffix = "" } = {}) {
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
+}
+//#endregion
 //#region ../../internals/utils/src/errors.ts
 /**
 * Coerces an unknown thrown value to an `Error` instance.
@@ -68,6 +101,91 @@ function getErrorMessage(value) {
 	return value instanceof Error ? value.message : String(value);
 }
 //#endregion
+//#region ../../internals/utils/src/runtime.ts
+/**
+* Detects the JavaScript runtime executing the current process and exposes its name and version.
+*
+* Prefer the shared {@link runtime} instance over constructing your own.
+*/
+var Runtime = class {
+	/**
+	* `true` when the current process is running under Bun.
+	*
+	* Detection keys off the global `Bun` object rather than `process.versions`,
+	* because Bun polyfills `process.versions.node` for Node compatibility and would
+	* otherwise look like Node.
+	*
+	* @example
+	* ```ts
+	* if (runtime.isBun) {
+	*   await Bun.write(path, data)
+	* }
+	* ```
+	*/
+	get isBun() {
+		return typeof Bun !== "undefined";
+	}
+	/**
+	* `true` when the current process is running under Deno.
+	*/
+	get isDeno() {
+		return typeof globalThis.Deno !== "undefined";
+	}
+	/**
+	* `true` when the current process is running under Node.
+	*
+	* Bun and Deno are excluded first so a polyfilled `process` does not register as Node.
+	*/
+	get isNode() {
+		return !this.isBun && !this.isDeno && typeof process !== "undefined" && process.versions?.node != null;
+	}
+	/**
+	* Name of the runtime executing the current process.
+	*
+	* @example
+	* ```ts
+	* runtime.name // 'bun' when run with `bun kubb`, 'node' otherwise
+	* ```
+	*/
+	get name() {
+		if (this.isBun) return "bun";
+		if (this.isDeno) return "deno";
+		return "node";
+	}
+	/**
+	* Version of the active runtime, or an empty string when it cannot be read.
+	*
+	* @example
+	* ```ts
+	* runtime.version // '1.3.11' under Bun, '22.22.2' under Node
+	* ```
+	*/
+	get version() {
+		if (this.isBun) return process.versions.bun ?? "";
+		if (this.isDeno) return globalThis.Deno?.version?.deno ?? "";
+		return process.versions?.node ?? "";
+	}
+};
+/**
+* Shared {@link Runtime} instance describing the JavaScript runtime executing the current process.
+*/
+const runtime = new Runtime();
+//#endregion
+//#region ../../internals/utils/src/fs.ts
+/**
+* Reads the file at `path` as a UTF-8 string.
+* Uses `Bun.file().text()` when running under Bun, `fs.readFile` otherwise.
+*
+* @example
+* ```ts
+* const source = await read('./src/Pet.ts')
+* ```
+*/
+async function read(path) {
+	if (runtime.isBun) return Bun.file(path).text();
+	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
+}
+//#endregion
 //#region ../../internals/utils/src/promise.ts
 /**
 * Wraps `factory` with a keyed cache backed by the provided store.
@@ -451,16 +569,19 @@ async function disconnect({ sessionId, token, studioUrl, slug }) {
 }
 //#endregion
 //#region package.json
-var version = "5.1.0";
+var version = "5.2.1";
 //#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) {
-	hooks.hook("kubb:hook:start", async (ctx) => {
+	return hooks.hook("kubb:hook:start", async (ctx) => {
 		const { id, command, args } = ctx;
 		if (!id) return;
 		const commandWithArgs = args?.length ? `${command} ${args.join(" ")}` : command;
@@ -524,6 +645,718 @@ function waitForHookEnd(hooks, hookId) {
 	});
 }
 //#endregion
+//#region src/resolveConfig.ts
+/**
+* Imports a package, falling back to how the user's project would resolve it.
+*
+* `import()` resolves from this file, so a linked or globally installed Studio (`pnpm link`,
+* `npm i -g`) only sees its own `node_modules` and misses the plugins installed next to the user's
+* config. The retry resolves from `process.cwd()` instead.
+*/
+async function importFromProject(packageName) {
+	try {
+		return await import(packageName);
+	} catch {
+		const resolved = (0, node_module.createRequire)((0, node_url.pathToFileURL)(`${process.cwd()}/`)).resolve(packageName);
+		const esm = resolved.replace(/\.cjs$/, ".js");
+		return await import((0, node_url.pathToFileURL)(esm !== resolved && (0, node_fs.existsSync)(esm) ? esm : resolved).href);
+	}
+}
+/**
+* Strips the `@kubb/` scope from a plugin package name, matching the `name` convention Kubb
+* plugin factories use internally.
+*
+* @example
+* ```ts
+* toPluginName('@kubb/plugin-ts') // 'plugin-ts'
+* ```
+*/
+function toPluginName(packageName) {
+	return packageName.split("/").pop() ?? packageName;
+}
+/**
+* Derives the conventional named export for a `@kubb/*` plugin package from its package name.
+*
+* @example
+* ```ts
+* toExportName('@kubb/plugin-react-query') // 'pluginReactQuery'
+* toExportName('@kubb/plugin-ts')          // 'pluginTs'
+* ```
+*/
+function toExportName(packageName) {
+	return camelCase(toPluginName(packageName));
+}
+/**
+* A `@kubb/plugin-*` package specifier. Nothing else may reach `import()`: only Kubb's own
+* plugins are supported, so a payload naming anything else, a third-party package or a path, is
+* refused before it can execute.
+*/
+const KUBB_PLUGIN_SPECIFIER = /^@kubb\/plugin-[\w.-]+$/;
+/**
+* Whether `name` is a `@kubb/plugin-*` specifier. Exported so `configFile.ts` can refuse the same
+* shape before printing a Studio-supplied plugin name into the config file's source text.
+*/
+function isKubbPluginSpecifier(name) {
+	return KUBB_PLUGIN_SPECIFIER.test(name);
+}
+/**
+* Dynamically imports a `@kubb/plugin-*` package and returns its factory function.
+*
+* Packages must be pre-installed in the Docker image at build time via the `KUBB_PACKAGES`
+* build ARG, no runtime installation is possible in the distroless container.
+*
+* Resolution order: the camelCase named export the package name implies (e.g. `pluginTs`), then
+* the default export.
+*
+* @throws if the package cannot be imported or exports no callable factory.
+*/
+async function loadPluginFactory(packageName) {
+	if (!isKubbPluginSpecifier(packageName)) throw new Error(`Plugin "${packageName}" is not a @kubb/plugin-* package. Kubb Studio only supports Kubb's own plugins.`);
+	let mod;
+	try {
+		mod = await importFromProject(packageName);
+	} catch (cause) {
+		throw new Error(`Plugin "${packageName}" could not be loaded. Make sure it is installed: \`npm install ${packageName}\``, { cause });
+	}
+	const exportName = toExportName(packageName);
+	if (typeof mod[exportName] === "function") return mod[exportName];
+	if (typeof mod["default"] === "function") return mod["default"];
+	throw new Error(`Plugin "${packageName}" does not export a callable factory. Tried the named export "${exportName}" and "default".`);
+}
+/**
+* Resolves each plugin entry by dynamically importing the `@kubb/plugin-*` package and
+* calling its factory with the provided options.
+*
+* Packages must be pre-installed in the Docker image at build time, use the `KUBB_PACKAGES`
+* build ARG to control which ones are available at runtime.
+*
+* @example
+* ```ts
+* { name: '@kubb/plugin-react-query', options: { output: { path: './hooks' } } }
+* { name: '@kubb/plugin-ts', options: { output: { path: './types' } } }
+* ```
+*/
+async function resolvePlugins(plugins) {
+	return Promise.all(plugins.map(async ({ name, options }) => {
+		return (await loadPluginFactory(name))(options ?? {});
+	}));
+}
+/**
+* Merges studio plugin options with disk config plugins.
+* Studio takes priority: options from studio win over disk, and a plugin Studio explicitly
+* disabled is dropped even when the disk config still lists it. Disk plugins without a studio
+* counterpart are kept as-is. Studio plugins not present on disk are appended.
+*
+* For plugins present in both configs, the plugin is re-instantiated with merged options
+* so that all internal closures correctly reference the merged values.
+*/
+async function mergePlugins(diskPlugins, studioPlugins) {
+	const disabledNames = new Set((studioPlugins ?? []).filter((entry) => entry.disabled).map((entry) => toPluginName(entry.name)));
+	const activeDiskPlugins = disabledNames.size ? diskPlugins?.filter((plugin) => !disabledNames.has(plugin.name)) : diskPlugins;
+	const activeStudioPlugins = studioPlugins?.filter((entry) => !entry.disabled);
+	if (!activeDiskPlugins && !activeStudioPlugins?.length) return void 0;
+	if (!activeStudioPlugins?.length) return activeDiskPlugins;
+	if (!activeDiskPlugins) return resolvePlugins(activeStudioPlugins);
+	const studioEntryByName = new Map(activeStudioPlugins.map((entry) => [toPluginName(entry.name), entry]));
+	const diskNames = new Set(activeDiskPlugins.map((plugin) => plugin.name));
+	const merged = await Promise.all(activeDiskPlugins.map(async (diskPlugin) => {
+		const studioEntry = studioEntryByName.get(diskPlugin.name);
+		if (!studioEntry) return diskPlugin;
+		const options = (0, remeda.mergeDeep)(diskPlugin.options ?? {}, studioEntry.options ?? {});
+		const [resolved] = await resolvePlugins([{
+			name: studioEntry.name,
+			options
+		}]);
+		return resolved ?? diskPlugin;
+	}));
+	const studioOnly = activeStudioPlugins.filter((entry) => !diskNames.has(toPluginName(entry.name)));
+	return [...merged, ...await resolvePlugins(studioOnly)];
+}
+/**
+* Merges Studio-provided adapter option overrides into the disk config's adapter.
+*
+* Adapter instances carry live functions (`parse`, `getImports`, ...) that can't survive
+* JSON serialization over the WebSocket, so `studioOptions` is treated as an options patch
+* rather than a replacement adapter. Re-invokes the same `@kubb/adapter-<name>` factory the
+* disk config used, with the merged options, so the resulting instance has fresh closures
+* over the merged values instead of a plain object missing `parse`.
+*/
+async function mergeAdapter(diskAdapter, studioOptions) {
+	if (!studioOptions || !diskAdapter) return diskAdapter;
+	const packageName = `@kubb/adapter-${diskAdapter.name}`;
+	const factory = (await importFromProject(packageName))[toExportName(packageName)];
+	if (typeof factory !== "function") return diskAdapter;
+	return factory((0, remeda.mergeDeep)(diskAdapter.options ?? {}, studioOptions));
+}
+//#endregion
+//#region src/configFile.ts
+/**
+* A valid JavaScript identifier, so an import name can only ever print as `import { name } from`,
+* never as source that breaks out of the import statement.
+*/
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/**
+* `key: value` as an object literal property, in the file's quote and key style.
+*
+* Uses magicast's literal builder for the key/value nodes, then wraps them as a Babel
+* `ObjectProperty`, the type the rest of this file reads.
+*/
+function literalProperty({ key, value }) {
+	const built = magicast.builders.literal({ [key]: value }).properties[0];
+	return {
+		type: "ObjectProperty",
+		key: built.key,
+		value: built.value,
+		computed: false,
+		shorthand: false
+	};
+}
+/**
+* Marks the comment block a `disable-plugin` leaves behind, so `enable-plugin` can find its way
+* back to the exact lines it commented out. Carries the block's line count, so `enable-plugin`
+* restores exactly those lines instead of scanning forward through whatever comments follow.
+*/
+const DISABLED_MARKER = "kubb:disabled";
+/**
+* The one line `disable-plugin` writes above the comment block it produces for `plugin`.
+*/
+function formatMarker(plugin, lineCount, indent = "") {
+	return `${indent}// ${DISABLED_MARKER} ${plugin} ${lineCount}`;
+}
+/**
+* The plugin and comment-block length a marker line names, when `line` is one.
+*/
+function parseMarker(line) {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith(`// ${DISABLED_MARKER} `)) return;
+	const match = trimmed.slice(`// ${DISABLED_MARKER} `.length).match(/^(.+)\s+(\d+)$/);
+	return match ? {
+		plugin: match[1],
+		lineCount: Number(match[2])
+	} : void 0;
+}
+/**
+* Steps through a config's wrappers to the object literal underneath: a `satisfies`/`as`
+* assertion, a `() => ...` factory, or a factory whose block body returns the config.
+*/
+function unwrap(node) {
+	if (!node) return;
+	if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") return unwrap(node.expression);
+	if (node.type !== "ArrowFunctionExpression" && node.type !== "FunctionExpression") return node;
+	if (node.body.type !== "BlockStatement") return unwrap(node.body);
+	return unwrap(node.body.body.find((statement) => statement.type === "ReturnStatement")?.argument);
+}
+/**
+* Every config object in `export default defineConfig(...)`, or why the file is unmanaged.
+*
+* An array export gets one entry per element, matching {@link ConfigRef}'s numeric index.
+*
+* Walks the parsed AST rather than magicast's proxies, which throw on node types they cannot
+* cast, most of what an unmanaged config file is made of.
+*/
+function findConfigs(mod) {
+	const exported = unwrap((mod.$ast.type === "Program" ? mod.$ast.body : []).find((node) => node.type === "ExportDefaultDeclaration")?.declaration);
+	if (!exported) return { reason: "no default export found" };
+	if (exported.type !== "CallExpression" || exported.callee.type !== "Identifier" || exported.callee.name !== "defineConfig") return { reason: "default export is not a defineConfig(...) call" };
+	const argument = unwrap(exported.arguments[0]);
+	if (!argument) return { reason: "defineConfig(...) was called without a config" };
+	if (argument.type === "ArrayExpression") {
+		const configs = [];
+		for (const element of argument.elements) {
+			const entry = unwrap(element);
+			if (entry?.type !== "ObjectExpression") return { reason: "config is not an object literal" };
+			configs.push(entry);
+		}
+		return { configs };
+	}
+	if (argument.type !== "ObjectExpression") return { reason: "config is not an object literal" };
+	return { configs: [argument] };
+}
+/**
+* The config entry an edit names, defaulting to the first when it names none.
+*/
+function selectConfig(configs, ref) {
+	if (ref === void 0) return configs[0];
+	if (typeof ref === "number") return configs[ref];
+	return configs.find((config) => configName(config) === ref);
+}
+function configName(config) {
+	const name = property(config, "name");
+	return name?.type === "StringLiteral" ? name.value : void 0;
+}
+/**
+* The name of an object literal property, for the two key shapes a config uses: `key: value` and
+* `'key': value`. `undefined` for a computed key, which the patcher never touches.
+*/
+function propertyKey(entry) {
+	if (entry.key.type === "Identifier") return entry.key.name;
+	if (entry.key.type === "StringLiteral") return entry.key.value;
+}
+/**
+* The index of an object literal's own property named `key`, `-1` when it has none.
+*/
+function entryIndex({ node, key }) {
+	return node.properties.findIndex((entry) => entry.type === "ObjectProperty" && propertyKey(entry) === key);
+}
+/**
+* The value node of an object literal's own property.
+*/
+function property(node, key) {
+	const index = entryIndex({
+		node,
+		key
+	});
+	return index === -1 ? void 0 : node.properties[index].value;
+}
+/**
+* Writes `key: value` on an object literal, replacing the value when the property is already there.
+*
+* An existing property has its value swapped in place rather than being replaced whole, so recast
+* reprints only that value and leaves the object's own layout alone.
+*/
+function setProperty({ node, key, value }) {
+	const entry = literalProperty({
+		key,
+		value
+	});
+	const index = entryIndex({
+		node,
+		key
+	});
+	if (index === -1) {
+		node.properties.push(entry);
+		return;
+	}
+	node.properties[index].value = entry.value;
+}
+/**
+* Drops `key` from an object literal.
+*/
+function removeProperty({ node, key }) {
+	const index = entryIndex({
+		node,
+		key
+	});
+	if (index !== -1) node.properties.splice(index, 1);
+}
+/**
+* Reads a literal node's value: a primitive, or an object/array built only from primitives.
+* `undefined` for anything else, so a caller can use this both to read a value and to check
+* whether a node is a literal at all.
+*/
+function readLiteral(node) {
+	if (!node) return;
+	if (node.type === "StringLiteral" || node.type === "NumericLiteral" || node.type === "BooleanLiteral") return node.value;
+	if (node.type === "NullLiteral") return null;
+	if (node.type === "TemplateLiteral") return node.expressions.length === 0 ? node.quasis[0]?.value.cooked ?? "" : void 0;
+	if (node.type === "UnaryExpression") {
+		const value = readLiteral(node.argument);
+		if (typeof value !== "number") return;
+		if (node.operator === "-") return -value;
+		if (node.operator === "+") return value;
+		return;
+	}
+	if (node.type === "ArrayExpression") {
+		const values = node.elements.map((element) => element ? readLiteral(element) : void 0);
+		return values.every((value) => value !== void 0) ? values : void 0;
+	}
+	if (node.type === "ObjectExpression") {
+		const entries = {};
+		for (const entry of node.properties) {
+			if (entry.type !== "ObjectProperty") return;
+			const key = propertyKey(entry);
+			const value = readLiteral(entry.value);
+			if (key === void 0 || value === void 0) return;
+			entries[key] = value;
+		}
+		return entries;
+	}
+}
+/**
+* Maps a factory identifier in the file back to the module it was imported from.
+*/
+function importedFrom(mod) {
+	return new Map(mod.imports.$items.map((item) => [item.local, item.from]));
+}
+/**
+* Every `pluginX(...)` element of a config's plugins array that resolves to an import.
+*/
+function pluginCalls(mod, config) {
+	const plugins = property(config, "plugins");
+	if (plugins?.type !== "ArrayExpression") return [];
+	const imports = importedFrom(mod);
+	return plugins.elements.flatMap((element) => {
+		if (element?.type !== "CallExpression" || element.callee.type !== "Identifier") return [];
+		const packageName = imports.get(element.callee.name);
+		return packageName ? [{
+			importName: element.callee.name,
+			packageName,
+			call: element
+		}] : [];
+	});
+}
+/**
+* Plugins a previous `disable-plugin` commented out of this config, keyed by package name.
+*
+* Read from the marker lines rather than the AST, since a commented-out call is no longer a node.
+*/
+function disabledMarkers(source) {
+	return source.split("\n").flatMap((line, index) => {
+		const marker = parseMarker(line);
+		return marker ? [{
+			packageName: marker.plugin,
+			line: index + 1
+		}] : [];
+	});
+}
+/**
+* Reads which plugins the file declares and which of their options Studio may write.
+*
+* @example
+* ```ts
+* const view = readConfig(await readFile('kubb.config.ts', 'utf8'))
+* if (view.managed) {
+*   view.configs.forEach((config) => console.log(config.name, config.plugins.length))
+* }
+* ```
+*/
+function readConfig(source) {
+	let mod;
+	try {
+		mod = (0, magicast.parseModule)(source);
+	} catch {
+		return {
+			managed: false,
+			reason: "the config file could not be parsed"
+		};
+	}
+	const found = findConfigs(mod);
+	if ("reason" in found) return {
+		managed: false,
+		reason: found.reason
+	};
+	const importNames = new Map([...importedFrom(mod)].map(([local, from]) => [from, local]));
+	const disabled = disabledMarkers(source);
+	return {
+		managed: true,
+		configs: found.configs.map((config) => {
+			const plugins = pluginCalls(mod, config).map(({ importName, packageName, call }) => {
+				const entries = {};
+				const options = call.arguments[0];
+				if (options?.type === "ObjectExpression") for (const entry of options.properties) {
+					if (entry.type !== "ObjectProperty") continue;
+					const key = propertyKey(entry);
+					if (key === void 0) continue;
+					const value = readLiteral(entry.value);
+					entries[key] = value === void 0 ? { literal: false } : {
+						literal: true,
+						value
+					};
+				}
+				return {
+					importName,
+					packageName,
+					options: entries
+				};
+			});
+			const start = config.loc?.start.line ?? 0;
+			const end = config.loc?.end.line ?? Number.POSITIVE_INFINITY;
+			for (const { packageName } of disabled.filter((entry) => entry.line >= start && entry.line <= end)) plugins.push({
+				importName: importNames.get(packageName) ?? toExportName(packageName),
+				packageName,
+				options: {},
+				disabled: true
+			});
+			return {
+				name: configName(config),
+				plugins
+			};
+		})
+	};
+}
+/**
+* Whether a value can be written into a config file as a literal.
+*
+* This is the trust boundary for edits that arrive over the agent WebSocket: a function, `undefined`,
+* or a non-finite number is refused rather than printed into the user's source.
+*/
+function isOptionValue(value) {
+	if (value === null) return true;
+	if (typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isOptionValue);
+	if (typeof value === "object") return Object.values(value).every(isOptionValue);
+	return false;
+}
+/**
+* The options object of a plugin call, when it was called with one.
+*/
+function getOptions(call) {
+	const options = call.arguments[0];
+	return options?.type === "ObjectExpression" ? options : void 0;
+}
+/**
+* The options object of a plugin call, creating an empty one when the plugin was called bare.
+*/
+function ensureOptions(call) {
+	if (call.arguments.length === 0) call.arguments.push({
+		type: "ObjectExpression",
+		properties: []
+	});
+	return getOptions(call);
+}
+/**
+* Walks `path` down to the object holding its last key, descending only through object literals.
+*/
+function optionParent(options, path) {
+	let object = options;
+	for (const [index, key] of path.entries()) {
+		if (index === path.length - 1) return {
+			object,
+			key
+		};
+		if (property(object, key) === void 0) setProperty({
+			node: object,
+			key,
+			value: {}
+		});
+		const next = property(object, key);
+		if (next?.type !== "ObjectExpression") return { reason: `${key} is not an object, so ${path.join(".")} cannot be reached` };
+		object = next;
+	}
+	return { reason: "no option path given" };
+}
+/**
+* Writes `value` at `path` inside a plugin call's options, creating the options object and any
+* intermediate object along the path as needed. Refuses when the current value at `path` is
+* something other than a literal, so an option customized in code is never overwritten.
+*/
+function applySet(call, path, value) {
+	if (!isOptionValue(value)) return "the value is not a literal that can be written to a config file";
+	const options = ensureOptions(call);
+	if (!options) return "the plugin was not called with an object literal";
+	const target = optionParent(options, path);
+	if ("reason" in target) return target.reason;
+	const current = property(target.object, target.key);
+	if (current !== void 0 && readLiteral(current) === void 0) return `${path.join(".")} is customized in code`;
+	setProperty({
+		node: target.object,
+		key: target.key,
+		value
+	});
+}
+/**
+* Deletes the property at `path` inside a plugin call's options, falling the plugin back to its
+* default for that option. Refuses when the value at `path` is not a literal, for the same reason
+* `applySet` does.
+*/
+function applyRemove(call, path) {
+	const options = getOptions(call);
+	if (!options) return "the plugin has no options to remove";
+	const target = optionParent(options, path);
+	if ("reason" in target) return target.reason;
+	const current = property(target.object, target.key);
+	if (current === void 0) return `${path.join(".")} is not set`;
+	if (readLiteral(current) === void 0) return `${path.join(".")} is customized in code`;
+	removeProperty({
+		node: target.object,
+		key: target.key
+	});
+}
+/**
+* Adds a `pluginX(...)` call to a config's plugins array. Refuses when the plugin is already
+* present, or when its import name collides with an unrelated existing import.
+*/
+function applyAddPlugin(mod, config, edit) {
+	if (!isKubbPluginSpecifier(edit.plugin)) return { reason: `"${edit.plugin}" is not a @kubb/plugin-* package` };
+	const importName = edit.importName ?? toExportName(edit.plugin);
+	if (!IDENTIFIER.test(importName)) return { reason: `"${importName}" is not a valid import name` };
+	if (pluginCalls(mod, config).some((plugin) => plugin.packageName === edit.plugin)) return { reason: `${edit.plugin} is already in the plugins array` };
+	const taken = importedFrom(mod).get(importName);
+	if (taken && taken !== edit.plugin) return { reason: `${importName} is already imported from ${taken}` };
+	const options = edit.options ?? {};
+	if (!isOptionValue(options)) return { reason: "the options are not literals that can be written to a config file" };
+	const plugins = property(config, "plugins");
+	if (plugins?.type !== "ArrayExpression") return { reason: "plugins is not an array literal" };
+	const call = Object.keys(options).length ? magicast.builders.functionCall(importName, options) : magicast.builders.functionCall(importName);
+	plugins.elements.push(call.$ast);
+	return taken ? {} : { addImport: {
+		importName,
+		moduleSpecifier: edit.plugin
+	} };
+}
+/**
+* Comments out a plugin call in place, keeping its options on disk so `enable-plugin` can restore
+* them exactly. Operates on `source` text rather than the AST: a commented-out call is no longer a
+* node magicast can address, and the surrounding array must not reflow when its element count
+* never actually changes.
+*/
+function disablePlugin(source, mod, config, plugin) {
+	const target = pluginCalls(mod, config).find((entry) => entry.packageName === plugin);
+	if (!target) return { reason: `${plugin} is not in the plugins array` };
+	const loc = target.call.loc;
+	if (!loc?.start || !loc.end) return { reason: `${plugin} has no source location to comment out` };
+	const lines = source.split("\n");
+	const from = loc.start.line - 1;
+	const to = loc.end.line - 1;
+	const firstLine = lines[from] ?? "";
+	const lastLine = lines[to] ?? "";
+	if (firstLine.slice(0, loc.start.column).trim() !== "" || !/^,?\s*$/.test(lastLine.slice(loc.end.column))) return { reason: `${plugin} shares a line with other code, so it cannot be commented out safely` };
+	const indent = firstLine.match(/^\s*/)?.[0] ?? "";
+	const commented = lines.slice(from, to + 1).map((line) => line.trim() ? `${indent}// ${line.slice(indent.length)}` : indent ? `${indent}//` : "//");
+	lines.splice(from, to - from + 1, formatMarker(plugin, commented.length, indent), ...commented);
+	return { source: lines.join("\n") };
+}
+/**
+* Uncomments the block a previous `disable-plugin` left behind for `plugin`.
+*/
+function enablePlugin(source, plugin) {
+	const lines = source.split("\n");
+	for (const [index, line] of lines.entries()) {
+		const marker = parseMarker(line);
+		if (marker?.plugin !== plugin) continue;
+		const end = index + 1 + marker.lineCount;
+		const restored = lines.slice(index + 1, end).map((commented) => commented.replace(/^(\s*)\/\/ ?/, "$1"));
+		lines.splice(index, end - index, ...restored);
+		return { source: lines.join("\n") };
+	}
+	return { reason: `${plugin} is not disabled` };
+}
+/**
+* Re-parses `source` and resolves the config entry an edit targets. Every edit re-parses rather
+* than sharing one module across the batch, since the disable/enable edits rewrite `source` as
+* text and would otherwise leave the others working from a stale tree.
+*/
+function parseTarget(source, ref) {
+	let mod;
+	try {
+		mod = (0, magicast.parseModule)(source);
+	} catch {
+		return { reason: "the config file could not be parsed" };
+	}
+	const found = findConfigs(mod);
+	if ("reason" in found) return { reason: found.reason };
+	const config = selectConfig(found.configs, ref);
+	if (!config) return { reason: `no config entry found for ${JSON.stringify(ref)}` };
+	return {
+		mod,
+		config
+	};
+}
+/**
+* Applies edits to a `kubb.config.ts` in place. Every node the edits do not touch keeps its
+* original text, so comments, formatting, and hand-written code around the config survive.
+*
+* Edits are independent: one that cannot be applied is reported in `outcomes` and the rest still run.
+*
+* @example
+* ```ts
+* const { source, outcomes } = applyConfigEdits(current, [
+*   { operation: 'set', plugin: '@kubb/plugin-ts', path: ['enum', 'type'], value: 'enum' },
+* ])
+* ```
+*
+* @note recast always reprints a semicolon on a reprinted statement, so editing a block-body
+* `defineConfig` in a semicolon-free file adds one to the `return` line. This is a known gap.
+* Strip it when `detectCodeFormat` reports `useSemi: false`, if it turns out to matter in practice.
+*/
+function applyConfigEdits(source, edits) {
+	let current = source;
+	const format = (0, magicast.detectCodeFormat)(source);
+	const endsWithNewline = source.endsWith("\n");
+	const outcomes = edits.map((edit) => {
+		const target = parseTarget(current, edit.config);
+		if ("reason" in target) return {
+			edit,
+			applied: false,
+			reason: target.reason
+		};
+		const { mod, config } = target;
+		if (edit.operation === "disable-plugin" || edit.operation === "enable-plugin") {
+			const result = edit.operation === "disable-plugin" ? disablePlugin(current, mod, config, edit.plugin) : enablePlugin(current, edit.plugin);
+			if ("reason" in result) return {
+				edit,
+				applied: false,
+				reason: result.reason
+			};
+			current = result.source;
+			return {
+				edit,
+				applied: true
+			};
+		}
+		if (edit.operation === "add-plugin") {
+			const result = applyAddPlugin(mod, config, edit);
+			if ("reason" in result) return {
+				edit,
+				applied: false,
+				reason: result.reason
+			};
+			const afterLine = lastImportEndLine(mod);
+			let next = (0, magicast.generateCode)(mod, { format }).code;
+			if (result.addImport) next = insertImportLine({
+				source: next,
+				afterLine,
+				...result.addImport
+			});
+			current = withTrailingNewline(next, endsWithNewline);
+			return {
+				edit,
+				applied: true
+			};
+		}
+		const pluginCall = pluginCalls(mod, config).find((plugin) => plugin.packageName === edit.plugin);
+		if (!pluginCall) return {
+			edit,
+			applied: false,
+			reason: `${edit.plugin} is not in the plugins array`
+		};
+		const reason = edit.operation === "set" ? applySet(pluginCall.call, edit.path, edit.value) : applyRemove(pluginCall.call, edit.path);
+		if (!reason) current = withTrailingNewline((0, magicast.generateCode)(mod, { format }).code, endsWithNewline);
+		return {
+			edit,
+			applied: !reason,
+			reason
+		};
+	});
+	return {
+		source: current,
+		outcomes,
+		changed: current !== source
+	};
+}
+/**
+* The 1-based line where the file's last import declaration ends, or `0` when it has none. Read
+* off the parsed module, so a multi-line `import {\n  x,\n} from '...'` reports its closing line
+* rather than the `import` keyword.
+*/
+function lastImportEndLine(mod) {
+	return (mod.$ast.type === "Program" ? mod.$ast.body : []).filter((node) => node.type === "ImportDeclaration").at(-1)?.loc?.end.line ?? 0;
+}
+/**
+* Writes an import after the last one already in the file, matching its quote style and whether it
+* ends in a semicolon. `afterLine` is where that last import ends, `0` for a file with none.
+*
+* Written as plain text rather than through magicast's import builder, which prints a brand-new
+* import declaration with its own default spacing and a semicolon regardless of `format`, since
+* that formatting only governs nodes recast can diff against the original source.
+*/
+function insertImportLine({ source, importName, moduleSpecifier, afterLine }) {
+	const lines = source.split("\n");
+	const lastImportLine = afterLine > 0 ? lines[afterLine - 1] : void 0;
+	const quote = lastImportLine?.includes(`"`) ? `"` : `'`;
+	const line = `import { ${importName} } from ${quote}${moduleSpecifier}${quote}${lastImportLine?.trimEnd().endsWith(";") ? ";" : ""}`;
+	lines.splice(afterLine, 0, ...afterLine > 0 ? [line] : [line, ""]);
+	return lines.join("\n");
+}
+/**
+* `generateCode` always drops the file's trailing newline. Restore it when the input had one.
+*/
+function withTrailingNewline(code, hadTrailingNewline) {
+	if (!hadTrailingNewline || code.endsWith("\n")) return code;
+	return `${code}\n`;
+}
+//#endregion
 //#region src/generate.ts
 /**
 * `isToolAvailable` spawns a process, and a long-lived connection generates repeatedly, so each
@@ -724,6 +1557,14 @@ function sendErrorMessage(ws$4, error) {
 * Forwards selected Kubb lifecycle events to Studio as data messages for the active session.
 */
 function setupEventsStream(ws$5, hooks) {
+	const unhooks = [];
+	/**
+	* Registers a listener and keeps its remover, so one generation's listeners come off the session
+	* emitter again when that generation ends.
+	*/
+	function on(name, handler) {
+		unhooks.push(hooks.hook(name, handler));
+	}
 	function sendDataMessage(payload) {
 		sendAgentMessage(ws$5, {
 			type: "agent:data",
@@ -734,13 +1575,13 @@ function setupEventsStream(ws$5, hooks) {
 			}
 		});
 	}
-	hooks.hook("kubb:plugin:start", (ctx) => {
+	on("kubb:plugin:start", (ctx) => {
 		sendDataMessage({
 			type: "kubb:plugin:start",
 			data: [{ plugin: ctx.plugin }]
 		});
 	});
-	hooks.hook("kubb:plugin:end", (ctx) => {
+	on("kubb:plugin:end", (ctx) => {
 		sendDataMessage({
 			type: "kubb:plugin:end",
 			data: [{
@@ -750,7 +1591,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:build:start", ({ config, adapter }) => {
+	on("kubb:build:start", ({ config, adapter }) => {
 		sendDataMessage({
 			type: "kubb:build:start",
 			data: [{
@@ -759,7 +1600,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:build:end", ({ files, outputDir }) => {
+	on("kubb:build:end", ({ files, outputDir }) => {
 		sendDataMessage({
 			type: "kubb:build:end",
 			data: [{
@@ -771,13 +1612,13 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:files:processing:start", ({ files }) => {
+	on("kubb:files:processing:start", ({ files }) => {
 		sendDataMessage({
 			type: "kubb:files:processing:start",
 			data: [{ total: files.length }]
 		});
 	});
-	hooks.hook("kubb:files:processing:update", ({ files }) => {
+	on("kubb:files:processing:update", ({ files }) => {
 		sendDataMessage({
 			type: "kubb:files:processing:update",
 			data: [{ files: files.map(({ file, processed, total, percentage }) => ({
@@ -788,7 +1629,7 @@ function setupEventsStream(ws$5, hooks) {
 			})) }]
 		});
 	});
-	hooks.hook("kubb:files:processing:end", ({ files }) => {
+	on("kubb:files:processing:end", ({ files }) => {
 		sendDataMessage({
 			type: "kubb:files:processing:end",
 			data: [{ total: files.length }]
@@ -798,7 +1639,7 @@ function setupEventsStream(ws$5, hooks) {
 		"kubb:info",
 		"kubb:success",
 		"kubb:warn"
-	]) hooks.hook(type, ({ message, info }) => {
+	]) on(type, ({ message, info }) => {
 		sendDataMessage({
 			type,
 			data: [{
@@ -807,7 +1648,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:generation:start", ({ config }) => {
+	on("kubb:generation:start", ({ config }) => {
 		sendDataMessage({
 			type: "kubb:generation:start",
 			data: [{
@@ -816,7 +1657,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:generation:end", async ({ config, storage, diagnostics = [], status, hrStart, filesCreated }) => {
+	on("kubb:generation:end", async ({ config, storage, diagnostics = [], status, hrStart, filesCreated }) => {
 		const paths = await storage.readKeys();
 		const files = {};
 		await inParallel({
@@ -845,7 +1686,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:error", ({ error }) => {
+	on("kubb:error", ({ error }) => {
 		sendDataMessage({
 			type: "kubb:error",
 			data: [{
@@ -863,13 +1704,13 @@ function setupEventsStream(ws$5, hooks) {
 		"kubb:lint:end",
 		"kubb:hooks:start",
 		"kubb:hooks:end"
-	]) hooks.hook(type, () => {
+	]) on(type, () => {
 		sendDataMessage({
 			type,
 			data: []
 		});
 	});
-	hooks.hook("kubb:hook:start", ({ id, command, args }) => {
+	on("kubb:hook:start", ({ id, command, args }) => {
 		sendDataMessage({
 			type: "kubb:hook:start",
 			data: [{
@@ -879,7 +1720,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:hook:line", ({ id, line }) => {
+	on("kubb:hook:line", ({ id, line }) => {
 		sendDataMessage({
 			type: "kubb:hook:line",
 			data: [{
@@ -888,7 +1729,7 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
-	hooks.hook("kubb:hook:end", ({ id, command, args, success, error }) => {
+	on("kubb:hook:end", ({ id, command, args, success, error }) => {
 		sendDataMessage({
 			type: "kubb:hook:end",
 			data: [{
@@ -903,321 +1744,423 @@ function setupEventsStream(ws$5, hooks) {
 			}]
 		});
 	});
+	return () => {
+		for (const unhook of unhooks) unhook();
+	};
 }
 //#endregion
-//#region src/connectStudio.ts
+//#region src/StudioSession.ts
+/**
+* Fills in a host's options: the hosted Studio URL, the current working directory, and every
+* permission off unless granted. Idempotent, so a reconnect can pass an already-resolved bag
+* back in.
+*/
+function applyStudioDefaults(options) {
+	const root = options.root ?? node_process.default.cwd();
+	return {
+		...options,
+		studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
+		root,
+		configFile: node_path.default.resolve(root, options.configPath),
+		permissions: {
+			allowWrite: false,
+			allowConfigEdit: false,
+			allowInput: false,
+			allowExec: false,
+			...options.permissions
+		},
+		retryInterval: options.retryInterval ?? agentDefaults.retryIntervalMs,
+		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs)
+	};
+}
 /**
 * Schedules another connection attempt.
 *
-* Hoisted out of `connectToStudio` on purpose: a pending retry timer reaches its whole enclosing
-* scope, so keeping it inside would pin the closed socket, the hook emitter, and the session id
-* alive for the length of every retry interval.
+* 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.
 */
 function reconnect(options) {
-	const { signal, retryInterval = agentDefaults.retryIntervalMs } = options;
+	const { signal, retryInterval, onTokenRejected } = options;
 	if (signal?.aborted) return;
 	console.info((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;
-		connectToStudio(options).catch((error) => {
+		new StudioSession(options).connect().catch((error) => {
 			console.error((0, node_util.styleText)("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
-			if (error instanceof InvalidAgentTokenError) return;
+			if (error instanceof InvalidAgentTokenError) {
+				onTokenRejected?.(error);
+				return;
+			}
 			reconnect(options);
 		});
 	}, retryInterval);
 	signal?.addEventListener("abort", cancel, { once: true });
 }
-async function connectToStudio(options) {
-	const { token, studioUrl = agentDefaults.studioUrl, configPath, loadConfig, version: version$1, client, allowWrite = false, allowConfigEdit = false, allowInput = false, allowExec = false, root = node_process.default.cwd(), heartbeatInterval: requestedHeartbeatInterval = agentDefaults.heartbeatIntervalMs, signal, installLogger } = options;
-	const heartbeatInterval = Math.min(requestedHeartbeatInterval, agentDefaults.heartbeatIntervalMs);
-	const hooks = new _kubb_core.Hookable();
-	await installLogger?.(hooks);
-	try {
-		await hooks.callHook("studio:connecting", { url: studioUrl });
-		const { sessionId, slug, wsUrl, isSandbox, version: sessionStudioVersion } = await createAgentSession({
-			token,
-			studioUrl
+/**
+* One WebSocket session with Studio: opening it, keeping it alive, and running the commands it
+* sends. `createClient` opens one per pool slot and is the only caller.
+*/
+var StudioSession = class {
+	#options;
+	#hooks = new _kubb_core.Hookable();
+	/**
+	* Removers for every listener this session added (socket, shutdown signal, hooks) so `dispose`
+	* detaches them in one pass. Listeners a host attached itself through `installLogger` survive.
+	*/
+	#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.
+	*/
+	#session;
+	#ws;
+	#studioVersion;
+	#disposed = false;
+	#isGenerating = false;
+	#heartbeatTimer;
+	#lastPongAt = Date.now();
+	constructor(options) {
+		this.#options = applyStudioDefaults(options);
+	}
+	/**
+	* A sandbox agent runs on Studio's own infrastructure, so it has no user project to touch.
+	*/
+	get #isSandbox() {
+		return this.#session?.isSandbox === true;
+	}
+	get #canWrite() {
+		return !this.#isSandbox && this.#options.permissions.allowWrite;
+	}
+	get #canEditConfig() {
+		return !this.#isSandbox && this.#options.permissions.allowConfigEdit;
+	}
+	/**
+	* A sandbox agent always generates from the spec Studio supplies. A local agent only when the
+	* host opted in.
+	*/
+	get #canUseInput() {
+		return this.#isSandbox || this.#options.permissions.allowInput;
+	}
+	async connect() {
+		const { token, studioUrl, signal, heartbeatInterval, installLogger } = this.#options;
+		await installLogger?.(this.#hooks);
+		try {
+			await this.#hooks.callHook("studio:connecting", { url: studioUrl });
+			const session = await createAgentSession({
+				token,
+				studioUrl
+			});
+			this.#session = session;
+			this.#studioVersion = session.version;
+			const ws = createWebsocket(session.wsUrl, { headers: { Authorization: `Bearer ${token}` } });
+			this.#ws = ws;
+			this.#listen(ws, "open", this.#onOpen);
+			this.#listen(ws, "close", this.#onClose);
+			this.#listen(ws, "error", this.#onError);
+			this.#listen(ws, "message", this.#onMessage);
+			signal?.addEventListener("abort", this.#onAbort, { once: true });
+			this.#unhooks.push(() => signal?.removeEventListener("abort", this.#onAbort));
+			this.#heartbeatTimer = setInterval(() => this.#sendHeartbeat(), heartbeatInterval);
+			this.#unhooks.push(this.#hooks.hook("kubb:error", ({ error }) => sendErrorMessage(ws, error)));
+		} catch (error) {
+			await this.#hooks.callHook("studio:error", { error: toError(error) });
+			if (error instanceof InvalidAgentTokenError) throw error;
+			reconnect(this.#options);
+		}
+	}
+	/**
+	* Adds a socket listener and tracks its remover, so `dispose` detaches every listener at once.
+	*/
+	#listen(ws, event, listener) {
+		ws.addEventListener(event, listener);
+		this.#unhooks.push(() => ws.removeEventListener(event, listener));
+	}
+	#warn(message) {
+		return this.#hooks.callHook("studio:warn", { message });
+	}
+	/**
+	* Forwards a failure to Studio over the connection emitter, which `connect` wired to this
+	* socket. Swallows a listener's own failure, since this is already the error path.
+	*/
+	#emitError(error) {
+		return Promise.resolve(this.#hooks.callHook("kubb:error", { error })).catch(() => {});
+	}
+	#sendHeartbeat() {
+		if (Date.now() - this.#lastPongAt > this.#options.heartbeatInterval * 2) {
+			this.#warn("No reply from Kubb Studio, terminating the stale connection");
+			clearInterval(this.#heartbeatTimer);
+			this.#heartbeatTimer = void 0;
+			this.#ws?.terminate();
+			return;
+		}
+		if (this.#ws) sendAgentMessage(this.#ws, { type: "agent:ping" });
+	}
+	/**
+	* Reads `kubb.config.ts` and reports which plugin options Studio may edit.
+	*
+	* Skipped when the host did not grant `allowConfigEdit`. Not cached: the user can edit the file
+	* between two Studio actions.
+	*/
+	async #readConfigFileView(source) {
+		if (!this.#canEditConfig) return;
+		try {
+			return readConfig(source ?? await read(this.#options.configFile));
+		} catch (error) {
+			await this.#warn(`Could not read ${this.#options.configFile}: ${getErrorMessage(error)}`);
+			return;
+		}
+	}
+	async #sendConnectedPayload() {
+		const { configPath, root, version: version$1, loadConfig, permissions } = this.#options;
+		if (!this.#ws) return;
+		const config = await loadConfig();
+		sendAgentMessage(this.#ws, {
+			type: "agent:connect",
+			payload: {
+				versions: {
+					kubb: version,
+					agent: version$1
+				},
+				root,
+				config: {
+					path: configPath,
+					file: await this.#readConfigFileView(),
+					plugins: config.plugins.map((plugin) => ({
+						name: `@kubb/${plugin.name}`,
+						options: plugin.options ?? {}
+					}))
+				},
+				permissions: {
+					...permissions,
+					allowWrite: this.#canWrite,
+					allowInput: this.#canUseInput,
+					allowConfigEdit: this.#canEditConfig
+				}
+			}
 		});
-		let studioVersion = sessionStudioVersion;
-		const ws = createWebsocket(wsUrl, { headers: { Authorization: `Bearer ${token}` } });
-		const canWrite = isSandbox ? false : allowWrite;
-		const canEditConfig = isSandbox ? false : allowConfigEdit;
-		const configFilePath = node_path.default.resolve(root, configPath);
-		const canUseInput = isSandbox || allowInput;
-		let serverDisconnected = false;
-		let isGenerating = false;
-		let heartbeatTimer;
-		let lastPongAt = Date.now();
-		const onAbort = () => void teardown({
-			reason: "shutdown",
-			retry: false
+	}
+	async #handleOpen() {
+		this.#lastPongAt = Date.now();
+		await this.#hooks.callHook("studio:connected", {
+			url: this.#options.studioUrl,
+			versions: {
+				studio: this.#studioVersion,
+				kubb: version,
+				agent: this.#options.version
+			}
 		});
-		function cleanup(reason = "cleanup") {
-			clearInterval(heartbeatTimer);
-			heartbeatTimer = void 0;
-			signal?.removeEventListener("abort", onAbort);
-			hooks.removeAllHooks();
-			try {
-				ws.close(1e3, reason);
-			} catch {}
-			ws.removeEventListener("open", onOpen);
-			ws.removeEventListener("close", onClose);
-			ws.removeEventListener("error", onError);
-			ws.removeEventListener("message", onMessage);
+		try {
+			await this.#sendConnectedPayload();
+		} catch (error) {
+			await this.#warn(`Failed to send the connect payload: ${getErrorMessage(error)}`);
 		}
-		/**
-		* Reads `kubb.config.ts` and reports which plugin options Studio may edit.
-		*
-		* Skipped when the host did not grant `allowConfigEdit`. The patcher pulls in `magicast`
-		* (~25ms, ~55MB RSS), so read-only agents never import it.
-		*
-		* Not cached: the user can edit the file between two Studio actions.
-		*/
-		async function readConfigFileView(source) {
-			if (!canEditConfig) return;
-			try {
-				const { readConfig } = await Promise.resolve().then(() => require("./configFile-DjzP1_Ln.cjs"));
-				return readConfig(source ?? await (0, node_fs_promises.readFile)(configFilePath, "utf-8"));
-			} catch (error) {
-				await hooks.callHook("studio:warn", { message: `Could not read ${configFilePath}: ${getErrorMessage(error)}` });
+	}
+	#onOpen = () => void this.#handleOpen().catch(() => {});
+	#onAbort = () => void this.#end({
+		reason: "shutdown",
+		retry: false
+	});
+	#onClose = () => void this.#end({ retry: true });
+	#onError = () => {
+		this.#hooks.callHook("studio:error", { error: /* @__PURE__ */ new Error("Failed to connect to Kubb Studio") });
+		this.#onClose();
+	};
+	/**
+	* Drops the socket and detaches every listener and timer this session added. Idempotent, and
+	* safe before `connect` opened anything.
+	*
+	* @internal
+	*/
+	dispose(reason = "cleanup") {
+		clearInterval(this.#heartbeatTimer);
+		this.#heartbeatTimer = void 0;
+		try {
+			this.#ws?.close(1e3, reason);
+		} catch {}
+		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 }) {
+		const { studioUrl, token } = this.#options;
+		if (this.#disposed) return;
+		this.#disposed = true;
+		if (reason === "shutdown" && this.#ws) sendAgentMessage(this.#ws, {
+			type: "agent:disconnect",
+			reason: "shutdown"
+		});
+		this.dispose(reason);
+		if (this.#session) await disconnect({
+			sessionId: this.#session.sessionId,
+			studioUrl,
+			token,
+			slug: this.#session.slug
+		}).catch(() => {});
+		if (retry) reconnect(this.#options);
+	}
+	#onMessage = async (message) => {
+		try {
+			const data = JSON.parse(message.data);
+			if (require_protocol.isStudioPingMessage(data)) {
+				this.#lastPongAt = Date.now();
 				return;
 			}
+			if (require_protocol.isDisconnectMessage(data)) {
+				await this.#handleDisconnect(data.reason);
+				return;
+			}
+			if (require_protocol.isCommandMessage(data)) {
+				await this.#handleCommand(data);
+				return;
+			}
+			await this.#warn(`Ignored an unknown message from Kubb Studio: ${data.type}`);
+		} catch (error) {
+			await this.#hooks.callHook("studio:error", { error: toError(error) });
+			await this.#emitError(toError(error));
 		}
-		async function sendConnectedPayload() {
+	};
+	/**
+	* Studio ended the session itself. A revoked one stays ended, an expired one gets a fresh
+	* session, and anything else is left to the socket's own close event.
+	*/
+	async #handleDisconnect(reason) {
+		await this.#hooks.callHook("studio:disconnected", { reason });
+		if (reason !== "revoked" && reason !== "expired") return;
+		this.#disposed = true;
+		this.dispose(`session_${reason}`);
+		if (reason === "expired") reconnect(this.#options);
+	}
+	async #handleCommand(data) {
+		const ws = this.#ws;
+		if (!ws) return;
+		const command = data.type.slice(7);
+		await this.#hooks.callHook("studio:command:start", { command });
+		switch (data.type) {
+			case "studio:generate":
+				await this.#handleGenerate(ws, data, command);
+				return;
+			case "studio:connect":
+				this.#studioVersion = data.version ?? this.#studioVersion;
+				await this.#sendConnectedPayload();
+				await this.#hooks.callHook("studio:command:end", { command });
+				return;
+			case "studio:save":
+				await this.#handleSave(ws, data, command);
+				return;
+		}
+	}
+	async #handleGenerate(ws, data, command) {
+		const { root, loadConfig, permissions, client } = this.#options;
+		if (this.#isGenerating) {
+			await this.#warn("Ignored generate: a generation is already in progress");
+			await this.#emitError(/* @__PURE__ */ new Error("A generation is already in progress, please wait for it to finish"));
+			return;
+		}
+		this.#isGenerating = true;
+		try {
 			const config = await loadConfig();
-			sendAgentMessage(ws, {
-				type: "agent:connect",
-				payload: {
-					versions: {
-						kubb: version,
-						agent: version$1
-					},
-					root,
+			const patch = data.payload;
+			const plugins = await mergePlugins(config.plugins, patch?.plugins);
+			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`);
+			}
+			const resolvedPlugins = plugins ?? config.plugins;
+			const detach = [setupHookListener(this.#hooks, root), setupEventsStream(ws, this.#hooks)];
+			try {
+				await generate({
 					config: {
-						path: configPath,
-						file: await readConfigFileView(),
-						plugins: config.plugins.map((plugin) => ({
-							name: `@kubb/${plugin.name}`,
-							options: plugin.options ?? {}
-						}))
+						...config,
+						root,
+						input: inputOverride ?? config.input,
+						storage: this.#canWrite ? (0, _kubb_core.fsStorage)() : (0, _kubb_core.memoryStorage)(),
+						output: permissions.allowExec ? { ...config.output } : {
+							...config.output,
+							format: false,
+							lint: false,
+							postGenerate: []
+						},
+						plugins: resolvedPlugins,
+						adapter
 					},
-					permissions: {
-						allowWrite: canWrite,
-						allowInput: canUseInput,
-						allowExec,
-						allowConfigEdit: canEditConfig
-					}
-				}
+					hooks: this.#hooks
+				});
+			} finally {
+				for (const remove of detach) remove();
+			}
+			await this.#hooks.callHook("studio:command:end", {
+				command,
+				info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${this.#canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
 			});
+		} finally {
+			this.#isGenerating = false;
 		}
-		async function handleOpen() {
-			lastPongAt = Date.now();
-			await hooks.callHook("studio:connected", {
-				url: studioUrl,
-				versions: {
-					studio: studioVersion,
-					kubb: version,
-					agent: version$1
+	}
+	async #handleSave(ws, data, command) {
+		const { configPath, configFile } = this.#options;
+		if (!Array.isArray(data.edits)) {
+			await this.#warn("Ignored save: the message carried no edits");
+			sendAgentMessage(ws, {
+				type: "agent:save",
+				payload: {
+					outcomes: [],
+					changed: false
 				}
 			});
-			try {
-				await sendConnectedPayload();
-			} catch (error) {
-				await hooks.callHook("studio:warn", { message: `Failed to send the connect payload: ${getErrorMessage(error)}` });
+			return;
+		}
+		const edits = data.edits;
+		const refuse = (reason) => sendAgentMessage(ws, {
+			type: "agent:save",
+			payload: {
+				outcomes: edits.map((edit) => ({
+					edit,
+					applied: false,
+					reason
+				})),
+				changed: false
 			}
+		});
+		if (!this.#canEditConfig) {
+			await this.#warn("Ignored save: editing kubb.config.ts was not granted");
+			refuse("the agent was not granted permission to edit kubb.config.ts");
+			return;
 		}
-		const onOpen = () => void handleOpen().catch(() => {});
-		/**
-		* Drops the socket and tells Studio the session is over. `serverDisconnected` guards against
-		* the close event running this a second time, and against a shutdown reconnecting.
-		*/
-		async function teardown({ reason, retry }) {
-			if (serverDisconnected) return;
-			serverDisconnected = true;
-			if (reason === "shutdown") sendAgentMessage(ws, {
-				type: "agent:disconnect",
-				reason: "shutdown"
-			});
-			cleanup(reason);
-			await disconnect({
-				sessionId,
-				studioUrl,
-				token,
-				slug
-			}).catch(() => {});
-			if (retry) reconnect(options);
+		if (this.#isGenerating) {
+			refuse("a generation is in progress");
+			return;
 		}
-		const onClose = () => teardown({ retry: true });
-		const onError = () => {
-			hooks.callHook("studio:error", { error: /* @__PURE__ */ new Error("Failed to connect to Kubb Studio") });
-			return onClose();
-		};
-		ws.addEventListener("open", onOpen);
-		ws.addEventListener("close", onClose);
-		ws.addEventListener("error", onError);
-		signal?.addEventListener("abort", onAbort, { once: true });
-		heartbeatTimer = setInterval(() => {
-			if (Date.now() - lastPongAt > heartbeatInterval * 2) {
-				hooks.callHook("studio:warn", { message: "No reply from Kubb Studio, terminating the stale connection" });
-				clearInterval(heartbeatTimer);
-				heartbeatTimer = void 0;
-				ws.terminate();
-				return;
-			}
-			sendAgentMessage(ws, { type: "agent:ping" });
-		}, heartbeatInterval);
-		hooks.hook("kubb:error", ({ error }) => sendErrorMessage(ws, error));
-		const onMessage = async (message) => {
-			try {
-				const data = JSON.parse(message.data);
-				if (require_protocol.isStudioPingMessage(data)) {
-					lastPongAt = Date.now();
-					return;
-				}
-				if (require_protocol.isDisconnectMessage(data)) {
-					await hooks.callHook("studio:disconnected", { reason: data.reason });
-					if (data.reason === "revoked") {
-						cleanup(`session_${data.reason}`);
-						return;
-					}
-					if (data.reason === "expired") {
-						cleanup();
-						reconnect(options);
-						return;
-					}
-					return;
-				}
-				if (require_protocol.isCommandMessage(data)) {
-					const command = data.type.slice(7);
-					await hooks.callHook("studio:command:start", { command });
-					if (data.type === "studio:generate") {
-						if (isGenerating) {
-							await hooks.callHook("studio:warn", { message: "Ignored generate: a generation is already in progress" });
-							await Promise.resolve(hooks.callHook("kubb:error", { error: /* @__PURE__ */ new Error("A generation is already in progress, please wait for it to finish") })).catch(() => {});
-							return;
-						}
-						isGenerating = true;
-						try {
-							const config = await loadConfig();
-							const patch = data.payload;
-							const plugins = await require_resolveConfig.mergePlugins(config.plugins, patch?.plugins);
-							const adapter = await require_resolveConfig.mergeAdapter(config.adapter, patch?.adapter);
-							const inputOverride = isSandbox ? patch?.input ?? "" : allowInput && patch?.input || void 0;
-							if (allowWrite && isSandbox) await hooks.callHook("studio:warn", { message: "Running in a sandbox, so writing files is disabled" });
-							if (patch?.input && !canUseInput) {
-								const remedy = client?.kind === "cli" ? "--allowInput, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_INPUT=true";
-								await hooks.callHook("studio:warn", { message: `Ignored the spec from Studio; set ${remedy} to generate from it` });
-							}
-							const generationHooks = new _kubb_core.Hookable();
-							await installLogger?.(generationHooks);
-							setupHookListener(generationHooks, root);
-							setupEventsStream(ws, generationHooks);
-							const resolvedPlugins = plugins ?? config.plugins;
-							await generate({
-								config: {
-									...config,
-									root,
-									input: inputOverride ?? config.input,
-									storage: canWrite ? (0, _kubb_core.fsStorage)() : (0, _kubb_core.memoryStorage)(),
-									output: allowExec ? { ...config.output } : {
-										...config.output,
-										format: false,
-										lint: false,
-										postGenerate: []
-									},
-									plugins: resolvedPlugins,
-									adapter
-								},
-								hooks: generationHooks
-							});
-							await hooks.callHook("studio:command:end", {
-								command,
-								info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
-							});
-						} finally {
-							isGenerating = false;
-						}
-						return;
-					}
-					if (data.type === "studio:connect") {
-						studioVersion = data.version ?? studioVersion;
-						await sendConnectedPayload();
-						await hooks.callHook("studio:command:end", { command });
-						return;
-					}
-					if (data.type === "studio:save") {
-						if (!Array.isArray(data.edits)) {
-							await hooks.callHook("studio:warn", { message: "Ignored save: the message carried no edits" });
-							sendAgentMessage(ws, {
-								type: "agent:save",
-								payload: {
-									outcomes: [],
-									changed: false
-								}
-							});
-							return;
-						}
-						const edits = data.edits;
-						const refuse = (reason) => sendAgentMessage(ws, {
-							type: "agent:save",
-							payload: {
-								outcomes: edits.map((edit) => ({
-									edit,
-									applied: false,
-									reason
-								})),
-								changed: false
-							}
-						});
-						if (!canEditConfig) {
-							await hooks.callHook("studio:warn", { message: "Ignored save: editing kubb.config.ts was not granted" });
-							refuse("the agent was not granted permission to edit kubb.config.ts");
-							return;
-						}
-						if (isGenerating) {
-							refuse("a generation is in progress");
-							return;
-						}
-						try {
-							const { applyConfigEdits } = await Promise.resolve().then(() => require("./configFile-DjzP1_Ln.cjs"));
-							const { source: patched, outcomes, changed } = applyConfigEdits(await (0, node_fs_promises.readFile)(configFilePath, "utf-8"), edits);
-							if (changed) await (0, node_fs_promises.writeFile)(configFilePath, patched, "utf-8");
-							sendAgentMessage(ws, {
-								type: "agent:save",
-								payload: {
-									outcomes,
-									changed,
-									file: changed ? await readConfigFileView(patched) : void 0
-								}
-							});
-							const applied = outcomes.filter((outcome) => outcome.applied).length;
-							await hooks.callHook("studio:command:end", {
-								command,
-								info: `applied ${applied}/${outcomes.length} edits to ${configPath}`
-							});
-						} catch (error) {
-							await hooks.callHook("studio:error", { error: toError(error) });
-							refuse(getErrorMessage(error));
-						}
-						return;
-					}
-					return;
+		try {
+			const { source: patched, outcomes, changed } = applyConfigEdits(await read(configFile), edits);
+			if (changed) await (0, node_fs_promises.writeFile)(configFile, patched, "utf-8");
+			sendAgentMessage(ws, {
+				type: "agent:save",
+				payload: {
+					outcomes,
+					changed,
+					file: changed ? await this.#readConfigFileView(patched) : void 0
 				}
-				await hooks.callHook("studio:warn", { message: `Ignored an unknown message from Kubb Studio: ${data.type}` });
-			} catch (error) {
-				await hooks.callHook("studio:error", { error: toError(error) });
-				await Promise.resolve(hooks.callHook("kubb:error", { error: toError(error) })).catch(() => {});
-			}
-		};
-		ws.addEventListener("message", onMessage);
-	} catch (error) {
-		await hooks.callHook("studio:error", { error: toError(error) });
-		if (error instanceof InvalidAgentTokenError) throw error;
-		reconnect(options);
+			});
+			const applied = outcomes.filter((outcome) => outcome.applied).length;
+			await this.#hooks.callHook("studio:command:end", {
+				command,
+				info: `applied ${applied}/${outcomes.length} edits to ${configPath}`
+			});
+		} catch (error) {
+			await this.#hooks.callHook("studio:error", { error: toError(error) });
+			refuse(getErrorMessage(error));
+		}
 	}
-}
+};
 //#endregion
 //#region src/client.ts
 /**
@@ -1232,10 +2175,15 @@ async function connectToStudio(options) {
 * await studio.connect()
 * ```
 */
-function createClient({ storage, ...options }) {
+function createClient({ storage, onAuthRequired, ...options }) {
 	if (storage) setStorage(storage);
 	const controller = new AbortController();
 	const poolSize = options.poolSize ?? agentDefaults.poolSize;
+	function notifyAuthRequired(error) {
+		if (controller.signal.aborted) return;
+		controller.abort();
+		onAuthRequired?.(error);
+	}
 	return {
 		async connect() {
 			await registerAgent({
@@ -1243,10 +2191,11 @@ function createClient({ storage, ...options }) {
 				studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
 				poolSize
 			});
-			await Promise.all(Array.from({ length: poolSize }, () => connectToStudio({
+			await Promise.all(Array.from({ length: poolSize }, () => new StudioSession({
 				...options,
-				signal: controller.signal
-			})));
+				signal: controller.signal,
+				onTokenRejected: notifyAuthRequired
+			}).connect()));
 		},
 		disconnect() {
 			controller.abort();
@@ -1254,6 +2203,79 @@ function createClient({ storage, ...options }) {
 	};
 }
 //#endregion
+//#region src/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 }) {
+	let current = credentials;
+	while (true) {
+		if (signal?.aborted) return "shutdown";
+		const { promise: authRequired, resolve: notifyAuthRequired } = Promise.withResolvers();
+		const client = createClient({
+			...clientOptions(current),
+			token: current.token,
+			onAuthRequired: notifyAuthRequired
+		});
+		let rejection;
+		try {
+			await client.connect();
+			const error = await waitForRejection(authRequired, signal);
+			if (!error) return "shutdown";
+			rejection = {
+				error,
+				credentials: current,
+				live: true
+			};
+		} catch (error) {
+			if (!(error instanceof InvalidAgentTokenError)) throw error;
+			rejection = {
+				error,
+				credentials: current,
+				live: false
+			};
+		} finally {
+			client.disconnect();
+		}
+		const next = await onTokenRejected(rejection);
+		if (!next) return "stopped";
+		current = next;
+	}
+}
+//#endregion
 //#region src/pair.ts
 /**
 * Identifies the CLI to Studio's device authorization endpoint. A label, not a secret: what
@@ -1261,21 +2283,38 @@ function createClient({ storage, ...options }) {
 */
 const CLIENT_ID = "kubb-cli";
 /**
+* 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
+* exit quietly instead of reporting a pairing failure.
+*/
+var PairingCanceledError = class extends Error {
+	constructor() {
+		super("Pairing was canceled");
+		this.name = "PairingCanceledError";
+	}
+};
+/**
 * 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 }) {
-	return (0, ofetch.ofetch)(`${studioUrl}/api/auth/device/code`, {
-		method: "POST",
-		body: {
-			client_id: clientId,
-			name,
-			hostname,
-			machine_token: await getMachineToken(),
-			agent_kind: agentKind
-		}
-	});
+async function startPairing({ studioUrl = agentDefaults.studioUrl, name, hostname, clientId = CLIENT_ID, agentKind, signal }) {
+	try {
+		return await (0, ofetch.ofetch)(`${studioUrl}/api/auth/device/code`, {
+			method: "POST",
+			body: {
+				client_id: clientId,
+				name,
+				hostname,
+				machine_token: await getMachineToken(),
+				agent_kind: agentKind
+			},
+			signal
+		});
+	} catch (error) {
+		if (signal?.aborted) throw new PairingCanceledError();
+		throw error;
+	}
 }
 function isPairingResult(response) {
 	return !!response && typeof response === "object" && "token" in response && typeof response.token === "string";
@@ -1289,19 +2328,26 @@ function isPairingResult(response) {
 *
 * @throws when the code expires, the user denies it, or Studio returns an unexpected error.
 */
-async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session }) {
+async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal }) {
 	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) {
-		await (0, node_timers_promises.setTimeout)(intervalMs);
+		if (signal?.aborted) throw new PairingCanceledError();
+		try {
+			await (0, node_timers_promises.setTimeout)(intervalMs, void 0, { signal });
+		} catch {
+			throw new PairingCanceledError();
+		}
 		let response;
 		try {
 			response = await (0, ofetch.ofetch)(`${studioUrl}/api/agent/token`, {
 				method: "POST",
 				body: { device_code: session.device_code },
-				ignoreResponseError: true
+				ignoreResponseError: true,
+				signal
 			});
 		} 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)}`));
 			continue;
 		}
@@ -1320,10 +2366,12 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 }
 //#endregion
 exports.InvalidAgentTokenError = InvalidAgentTokenError;
+exports.PairingCanceledError = PairingCanceledError;
 exports.createClient = createClient;
 exports.createFileStorage = createFileStorage;
 exports.defaultStudioUrl = defaultStudioUrl;
 exports.pollForPairingToken = pollForPairingToken;
+exports.runConnection = runConnection;
 exports.setStorage = setStorage;
 exports.startPairing = startPairing;