@kubb/studio 5.6.0 → 5.6.2

package/dist/index.js

@@ -1,19 +1,47 @@
 import "./rolldown-runtime-CRm0XQPb.js";
-import { a as resolvePeerDependencies, c as read, i as mergePlugins, r as mergeAdapter, s as toPackageName } from "./resolveConfig-DOUv_Tid.js";
-import { AGENT_INSTANCE_HEADER, AgentCloseCode, GENERATION_GONE_MESSAGE, MAX_PAGE_LINES, generationEventTypes } from "./protocol.js";
-import { t as isLoopbackHost } from "./url-DhFfJpxp.js";
-import { createHash, hash, randomBytes, randomUUID } from "node:crypto";
-import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import process$1 from "node:process";
-import path, { isAbsolute, relative, resolve, sep } from "node:path";
-import { mkdtemp, rm } from "node:fs/promises";
-import { FetchError, ofetch } from "ofetch";
-import { stripVTControlCharacters, styleText } from "node:util";
-import { createStorage } from "unstorage";
-import fsDriver from "unstorage/drivers/fs";
+import { AGENT_INSTANCE_HEADER, AGENT_SOCKET_PATH, AgentCloseCode, GENERATION_GONE_MESSAGE, MAX_PAGE_LINES, MAX_SNAPSHOT_BYTES, generationEventTypes } from "./protocol.js";
+import { createRequire } from "node:module";
+import { createHash, hash, randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import process$1 from "node:process";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
 import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, memoryStorage, resolveCacheDir } from "@kubb/core";
 import { RpcTarget, newWebSocketRpcSession } from "capnweb";
+import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
+import { promisify, stripVTControlCharacters } from "node:util";
+import { ofetch } from "ofetch";
+import { gzip } from "node:zlib";
+//#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.
@@ -42,6 +70,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 readFile(path, { encoding: "utf8" });
+}
+//#endregion
 //#region ../../internals/utils/src/promise.ts
 /**
 * Runs `run` over every item with at most `limit` in flight. Workers share one iterator, so each
@@ -78,360 +191,800 @@ function getElapsedMs(hrStart) {
 	return Math.round(ms * 100) / 100;
 }
 //#endregion
-//#region src/operations/machine.ts
+//#region package.json
+var version = "5.6.2";
+//#endregion
+//#region src/resolveConfig.ts
 /**
-* Key-value storage the runtime uses for its machine secret and the last Studio config.
+* Imports a package, falling back to how the user's project would resolve it.
 *
-* One storage per process, since one process serves one config file. Hosts install their own
-* driver on startup: Nitro passes its `kubb` mount, the CLI an fs driver under `~/.kubb/cache`.
-* The in-memory default keeps the runtime usable without a host, at the cost of a machine
-* identity that changes on every restart.
+* `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.
 */
-let storage = createStorage();
-let hasInstalledStorage = false;
+async function importFromProject(packageName) {
+	try {
+		return await import(packageName);
+	} catch {
+		const resolved = createRequire(pathToFileURL(`${process.cwd()}/`)).resolve(packageName);
+		const esm = resolved.replace(/\.cjs$/, ".js");
+		return await import(pathToFileURL(esm !== resolved && existsSync(esm) ? esm : resolved).href);
+	}
+}
 /**
-* Installs the storage driver the runtime persists to. Call once, before connecting.
+* 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 setStorage(next) {
-	storage = next;
-	hasInstalledStorage = true;
+function toPluginName(packageName) {
+	return packageName.split("/").pop() ?? packageName;
 }
 /**
-* A storage backed by files under `base`, so the machine secret and the last Studio config
-* survive a restart. Repeated pairings of one machine depend on that secret staying put.
+* Adds the `@kubb/` scope a plugin's package carries but its `name` does not, the inverse of
+* {@link toPluginName}. A name outside the `plugin-` convention is left alone, so a third-party
+* plugin is not reported as one of Kubb's.
+*
+* @example
+* ```ts
+* toPackageName('plugin-ts')       // '@kubb/plugin-ts'
+* toPackageName('@acme/my-plugin') // '@acme/my-plugin'
+* ```
 */
-function createFileStorage(base) {
-	return createStorage({ driver: fsDriver({ base }) });
+function toPackageName(name) {
+	return name.startsWith("plugin-") ? `@kubb/${name}` : name;
 }
-let fallbackSecretPromise = null;
 /**
-* Loads the fallback machine secret from the runtime storage.
-* On first use it generates a secret and persists it, so the machine identity stays
-* stable across restarts. An identity that changes on every boot breaks session
-* creation with Studio whenever the startup registration call fails.
+* 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'
+* ```
 */
-async function loadOrCreateFallbackSecret() {
-	if (!hasInstalledStorage) console.warn(styleText("yellow", "Deriving the machine token before a storage driver was installed"), "call setStorage() first, or set KUBB_AGENT_SECRET, to keep a stable machine identity across restarts");
-	const stored = await storage.getItem("machine-secret").catch(() => null);
-	if (typeof stored === "string" && stored) return stored;
-	const secret = randomBytes(32).toString("hex");
-	await storage.setItem("machine-secret", secret).catch(() => {
-		console.warn(styleText("yellow", "Could not persist the generated machine secret"), "set KUBB_AGENT_SECRET to keep a stable machine identity across restarts");
-	});
-	return secret;
+function toExportName(packageName) {
+	return camelCase(toPluginName(packageName));
 }
 /**
-* Hashes a stable secret into the machine token Studio expects, so a host can derive one from its
-* own identity without duplicating `getMachineToken`'s SHA-256 step.
+* 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.
 */
-function machineTokenFrom(secret) {
-	return hash("sha256", secret);
-}
+const KUBB_PLUGIN_SPECIFIER = /^@kubb\/plugin-[\w.-]+$/;
 /**
-* Returns the machine token derived from the `KUBB_AGENT_SECRET` environment variable.
-* Falls back to a generated secret persisted in the runtime storage if the env var is not set.
-* The token is hashed with SHA-256.
+* 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.
 */
-async function getMachineToken() {
-	if (process$1.env.KUBB_AGENT_SECRET) return machineTokenFrom(process$1.env.KUBB_AGENT_SECRET);
-	fallbackSecretPromise ??= loadOrCreateFallbackSecret();
-	return machineTokenFrom(await fallbackSecretPromise);
+function isKubbPluginSpecifier(name) {
+	return KUBB_PLUGIN_SPECIFIER.test(name);
 }
-//#endregion
-//#region src/operations/api.ts
 /**
-* Reads a human-readable message from a Studio JSON error body, when it has one. `FetchError`'s own
-* message stops at the status line, so the detail Studio sends with a failure (an agent limit, a
-* revoked token) would otherwise never reach the user.
+* 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.
 */
-function responseMessage(data) {
-	if (!data || typeof data !== "object") return;
-	const body = data;
-	for (const value of [
-		body.error_description,
-		body.message,
-		body.error
-	]) if (typeof value === "string" && value) return value;
+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".`);
 }
 /**
-* 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.
+* 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' } } }
+* ```
 */
-var InvalidAgentTokenError = class extends Error {
-	constructor(studioUrl, options) {
-		super(`Kubb Studio rejected this agent's token. It was revoked or the agent was deleted in ${studioUrl}.`, options);
-		this.name = "InvalidAgentTokenError";
+async function resolvePlugins(plugins) {
+	return Promise.all(plugins.map(async ({ name, options }) => {
+		return (await loadPluginFactory(name))(options ?? {});
+	}));
+}
+/** The installed version of each plugin's package, plus the names that could not be resolved. */
+async function resolvePeerDependencies(names) {
+	const require = createRequire(import.meta.url);
+	const uniqueNames = [...new Set(names.map(toPackageName))];
+	const peerDependencies = {};
+	const missingDependencies = [];
+	const versions = await Promise.all(uniqueNames.map(async (name) => {
+		try {
+			const path = require.resolve(`${name}/package.json`);
+			return JSON.parse(await readFile(path, "utf8")).version;
+		} catch {
+			return;
+		}
+	}));
+	for (const [index, name] of uniqueNames.entries()) {
+		const version = versions[index];
+		if (version) {
+			peerDependencies[name] = version;
+			continue;
+		}
+		missingDependencies.push(name);
 	}
-};
+	return {
+		peerDependencies,
+		missingDependencies
+	};
+}
 /**
-* Thrown when Studio refuses this agent's protocol version (426). Retrying cannot help until the
-* agent is upgraded, so hosts stop instead of reconnecting.
+* Whether `value` is an object literal or a null-prototype object, not an array or class instance.
 */
-var IncompatibleAgentError = class extends Error {
-	constructor(studioUrl, detail, options) {
-		super(`Kubb Studio at ${studioUrl} requires a newer agent${detail ? `: ${detail}` : ""}. Upgrade @kubb/studio or the Kubb agent image.`, options);
-		this.name = "IncompatibleAgentError";
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+}
+/**
+* Whether `value` survives a JSON round trip, so it can be printed into a config file as a literal.
+* A function, `undefined`, a non-finite number or a class instance comes back from Studio as a
+* lossy copy, so an edit carrying one is refused rather than written into the user's source.
+*/
+function isOptionValue(value) {
+	if (value === null || 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 (isPlainObject(value)) return Object.values(value).every(isOptionValue);
+	return false;
+}
+/**
+* Deep-merges Studio's options over the disk options, with Studio taking priority, except where the
+* disk value cannot survive JSON. Studio only ever saw a lossy copy of such a value, so the disk
+* value is kept rather than replaced by what Studio echoes back. Plain objects merge key by key, so
+* Studio can still change a literal that sits next to a function (e.g. `group.type` beside `group.name`).
+*
+* @example
+* ```ts
+* mergeOptions({ macros: [camelCaseMacro], syntaxType: 'type' }, { macros: [{ name: 'camelCase' }], syntaxType: 'interface' })
+* // { macros: [camelCaseMacro], syntaxType: 'interface' }
+* ```
+*/
+function mergeOptions(disk, studio) {
+	const merged = { ...disk };
+	for (const [key, value] of Object.entries(studio)) {
+		const current = disk[key];
+		if (isPlainObject(current) && isPlainObject(value)) {
+			merged[key] = mergeOptions(current, value);
+			continue;
+		}
+		if (current !== void 0 && !isOptionValue(current)) continue;
+		merged[key] = value;
 	}
-};
+	return merged;
+}
 /**
-* Whether a thrown value carries `statusCode`. Not narrowed to `FetchError`: a host wrapper can
-* throw its own error shape with the same field.
+* Merges studio plugin options with disk config plugins.
+* Studio takes priority: options from studio win over disk (except values only the disk config
+* can express, see {@link mergeOptions}), 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.
 */
-function rejectedWith(error, statusCode) {
-	return error?.statusCode === statusCode;
+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 = mergeOptions(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)];
 }
-function registrationError(cause) {
-	const detail = (cause instanceof FetchError ? responseMessage(cause.data) : void 0) ?? getErrorMessage(cause);
-	return new Error(detail ? `Failed to register with Kubb Studio: ${detail}` : "Failed to register with Kubb Studio", { cause });
+/**
+* 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(mergeOptions(diskAdapter.options ?? {}, studioOptions));
 }
+//#endregion
+//#region src/configFile.ts
 /**
-* Registers this agent process with Kubb Studio (`POST /api/agent/connect`): binds the machine
-* identity to the token, reports what the process can take on, and gets back the URL of the one
-* socket it keeps open.
+* 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.
 *
-* 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.
+* 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.
 */
-async function registerAgent({ token, studioUrl, instanceId, capacity, signal }) {
-	const body = {
-		machineToken: await getMachineToken(),
-		instanceId,
-		capacity
+function literalProperty({ key, value }) {
+	const built = builders.literal({ [key]: value }).properties[0];
+	return {
+		type: "ObjectProperty",
+		key: built.key,
+		value: built.value,
+		computed: false,
+		shorthand: false
 	};
-	try {
-		return await ofetch(`${studioUrl}/api/agent/connect`, {
-			method: "POST",
-			headers: { Authorization: `Bearer ${token}` },
-			body,
-			retry: 0,
-			timeout: 1e4,
-			signal
-		});
-	} catch (error) {
-		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		if (rejectedWith(error, 426)) throw new IncompatibleAgentError(studioUrl, error instanceof FetchError ? responseMessage(error.data) : void 0, { cause: error });
-		throw registrationError(error);
-	}
 }
 /**
-* First wait before `createJob` retries a busy or queue-full response, absent a `Retry-After` hint.
+* 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 CREATE_JOB_INITIAL_DELAY_MS = 1e3;
+const DISABLED_MARKER = "kubb:disabled";
 /**
-* Slowest `createJob` backs off to between retries.
+* The plugin and comment-block length a marker line names, when `line` is one.
 */
-const CREATE_JOB_MAX_INTERVAL_MS = 1e4;
+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;
+}
 /**
-* Statuses worth retrying: the agent has no free connection yet (409, a stale conflict a moment
-* later resolves), its queue is momentarily full (429), or it has no live connection at all yet
-* (503, an agent process that is mid-reconnect). Anything else (404 agent not found, 401/403 auth)
-* is thrown straight away, since retrying cannot change the outcome.
+* 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.
 */
-const CREATE_JOB_RETRYABLE_STATUSES = /* @__PURE__ */ new Set([
-	409,
-	429,
-	503
-]);
+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);
+}
 /**
-* Reads Studio's `Retry-After` header (seconds) off a thrown `ofetch` error, when present.
+* 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 retryAfterMs(error) {
-	const seconds = Number(error.response?.headers.get("retry-after"));
-	return Number.isFinite(seconds) && seconds > 0 ? seconds * 1e3 : void 0;
+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] };
 }
 /**
-* Adds up to 30% jitter, so every CI run queued behind the same busy agent does not retry in
-* lockstep.
+* The config entry an edit names, defaulting to the first when it names none.
 */
-function withJitter(ms) {
-	return ms + Math.random() * ms * .3;
+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;
 }
 /**
-* Queues a generation or snapshot job on Studio (`POST /api/jobs`).
+* 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.
 *
-* Returns as soon as Studio accepts the job (`202`). Poll with {@link waitForJob} until it finishes.
-* Authenticates with the organization CI API key via `x-api-key`.
+* 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.
 *
-* A busy agent, a full queue, or a momentary lack of a live connection (409, 429, 503) retries with
-* exponential backoff and jitter, honoring Studio's `Retry-After` header when it sends one, up to
-* `timeoutMs`. Every other failure, including a missing agent (404), throws immediately.
+* 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 Snapshot job
+* @example
 * ```ts
-* const job = await createJob({
-*   studioUrl: 'https://kubb.studio',
-*   token: process.env.KUBB_TOKEN!,
-*   type: 'snapshot',
-*   agentId: agent.id,
-*   name: '@kubb/demo',
-*   version: '1.0.0',
-* })
-* const finished = await waitForJob({ studioUrl, token, id: job.id })
+* const view = readConfig(await readFile('kubb.config.ts', 'utf8'))
+* if (view.managed) {
+*   view.configs.forEach((config) => console.log(config.name, config.plugins.length))
+* }
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, instanceId, timeoutMs = 6e4, signal }) {
-	const deadline = Date.now() + timeoutMs;
-	let interval = CREATE_JOB_INITIAL_DELAY_MS;
-	for (;;) {
-		signal?.throwIfAborted();
-		try {
-			const { job } = await ofetch(`${studioUrl}/api/jobs`, {
-				method: "POST",
-				headers: { "x-api-key": token },
-				body: {
-					type,
-					agentId,
-					name,
-					version,
-					commit,
-					baseId,
-					config,
-					instanceId
-				},
-				retry: false,
-				timeout: Math.max(deadline - Date.now(), 1),
-				signal
+function readConfig(source) {
+	const parsed = parseConfigs(source);
+	if ("reason" in parsed) return {
+		managed: false,
+		reason: parsed.reason
+	};
+	const { mod, configs } = parsed;
+	const importNames = new Map([...importedFrom(mod)].map(([local, from]) => [from, local]));
+	const disabled = disabledMarkers(source);
+	return {
+		managed: true,
+		configs: 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
+				};
 			});
-			return job;
-		} catch (error) {
-			signal?.throwIfAborted();
-			const status = error.response?.status;
-			if (!status || !CREATE_JOB_RETRYABLE_STATUSES.has(status) || Date.now() >= deadline) throw error;
-			const wait = Math.min(retryAfterMs(error) ?? withJitter(interval), Math.max(deadline - Date.now(), 0));
-			if (signal) await setTimeout$1(wait, void 0, { signal });
-			else await new Promise((resolve) => setTimeout(resolve, wait));
-			if (Date.now() >= deadline) throw error;
-			interval = Math.min(interval * 2, CREATE_JOB_MAX_INTERVAL_MS);
-		}
-	}
+			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
+			};
+		})
+	};
 }
 /**
-* A job runs a generation and packs a tarball, so it is never done the instant it is queued.
+* The options object of a plugin call, when it was called with one.
 */
-const INITIAL_POLL_DELAY_MS = 2e3;
+function getOptions(call) {
+	const options = call.arguments[0];
+	return options?.type === "ObjectExpression" ? options : void 0;
+}
 /**
-* Slowest the poll backs off to. Requests per run are roughly `timeoutMs` divided by this, and
-* every concurrent run on the same organization key draws on one budget.
+* The options object of a plugin call, creating an empty one when the plugin was called bare.
 */
-const MAX_POLL_INTERVAL_MS = 3e4;
+function ensureOptions(call) {
+	if (call.arguments.length === 0) call.arguments.push({
+		type: "ObjectExpression",
+		properties: []
+	});
+	return getOptions(call);
+}
 /**
-* Polls `GET /api/jobs/{id}` until the job reaches a terminal status, waiting
-* {@link INITIAL_POLL_DELAY_MS} first and doubling up to {@link MAX_POLL_INTERVAL_MS} so a long
-* job stays inside the API key's rate limit.
-*
-* A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
-* deadline passes before Studio finishes.
-*/
-async function waitForJob({ studioUrl, token, id, timeoutMs = 6e4, signal }) {
-	const deadline = Date.now() + timeoutMs;
-	let interval = INITIAL_POLL_DELAY_MS;
-	for (;;) {
-		signal?.throwIfAborted();
-		const wait = Math.max(Math.min(interval, deadline - Date.now()), 0);
-		if (signal) await setTimeout$1(wait, void 0, { signal });
-		else await new Promise((resolve) => setTimeout(resolve, wait));
-		if (Date.now() >= deadline) throw new Error("Timed out waiting for the Studio job");
-		interval = Math.min(interval * 2, MAX_POLL_INTERVAL_MS);
-		try {
-			const { job } = await ofetch(`${studioUrl}/api/jobs/${id}`, {
-				headers: { "x-api-key": token },
-				retry: false,
-				timeout: Math.max(deadline - Date.now(), 1),
-				signal
-			});
-			if (job.status === "success" || job.status === "failed" || job.status === "canceled") return job;
-		} catch (error) {
-			signal?.throwIfAborted();
-			const response = error.response;
-			if (response?.status !== 429) throw error;
-			const retryAfter = response._data?.data?.tryAgainIn;
-			interval = Math.max(interval, typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : MAX_POLL_INTERVAL_MS);
-		}
+* 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" };
 }
 /**
-* Creates or reuses a CI agent (`POST /api/agents`), keyed by `(organization, machineToken)`.
-* Authenticates via `x-api-key`. Reusing the same `machineToken` reuses the same agent instead of
-* consuming a new one from the organization's agent limit.
+* 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.
 */
-async function createAgent({ studioUrl, token, name, machineToken }) {
-	try {
-		return await ofetch(`${studioUrl}/api/agents`, {
-			method: "POST",
-			headers: { "x-api-key": token },
-			body: {
-				name,
-				machineToken
-			}
-		});
-	} catch (error) {
-		if (error instanceof FetchError) {
-			const upgradeUrl = error.data?.data?.upgradeUrl;
-			const detail = responseMessage(error.data) ?? getErrorMessage(error);
-			const hint = upgradeUrl ? ` Agent limit reached; upgrade at ${upgradeUrl}.` : "";
-			throw new Error(`Failed to create a Kubb Studio agent: ${detail}${hint}`, { cause: error });
-		}
-		throw error;
+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. Replaying the same add is a no-op, while
+* an import name collision with an unrelated package remains an error.
+*/
+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 { noop: true };
+	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 ? builders.functionCall(importName, options) : 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, `${indent}// ${DISABLED_MARKER} ${plugin} ${commented.length}`, ...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` };
 }
-//#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.
+* Parses `source` and finds the config entries it exports.
 */
-const defaultStudioUrl = "https://kubb.studio";
+function parseConfigs(source) {
+	let mod;
+	try {
+		mod = parseModule(source);
+	} catch {
+		return { reason: "the config file could not be parsed" };
+	}
+	const found = findConfigs(mod);
+	return "reason" in found ? found : {
+		mod,
+		configs: found.configs
+	};
+}
 /**
-* Defaults the Studio client uses when a host passes nothing.
-* Config path is left out on purpose: each host discovers that itself.
+* 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.
 */
-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 persists a ping at most once an hour,
-	* 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;
+function parseTarget(source, ref) {
+	const parsed = parseConfigs(source);
+	if ("reason" in parsed) return parsed;
+	const config = selectConfig(parsed.configs, ref);
+	if (!config) return { reason: `no config entry found for ${JSON.stringify(ref)}` };
+	return {
+		mod: parsed.mod,
+		config
+	};
 }
 /**
-* 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.
+* 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 resolveGenerationLimits(env = process.env) {
+function applyConfigEdits(source, edits) {
+	let current = source;
+	const format = 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
+			};
+			if ("noop" in result) return {
+				edit,
+				applied: true
+			};
+			const afterLine = lastImportEndLine(mod);
+			let next = 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(generateCode(mod, { format }).code, endsWithNewline);
+		return {
+			edit,
+			applied: !reason,
+			reason
+		};
+	});
 	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
+		source: current,
+		outcomes,
+		changed: current !== source
 	};
 }
+async function writeConfigEdits({ filePath, edits }) {
+	const result = applyConfigEdits(await read(filePath), edits);
+	if (result.changed) await writeFile(filePath, result.source, "utf-8");
+	return result;
+}
 /**
-* An agent's capacity read from `KUBB_AGENT_MAX_CONCURRENT`. An unset or invalid value keeps the
-* default: one job at a time.
+* 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 resolveAgentCapacity(env = process.env) {
-	return { maxConcurrent: Math.max(1, Math.floor(positiveNumber(env.KUBB_AGENT_MAX_CONCURRENT) ?? agentDefaults.maxConcurrent)) };
+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 package.json
-var version = "5.6.0";
-//#endregion
-//#region src/operations/generations.ts
+//#region src/generations.ts
 const READ_CONCURRENCY = 50;
 const MB = 1048576;
 const INDEX_KEY = "studio/generations.json";
@@ -441,8 +994,65 @@ const INDEX_KEY = "studio/generations.json";
 function relativeStoragePath({ root, filePath }) {
 	return (isAbsolute(filePath) ? relative(resolve(root), filePath) : filePath).replaceAll("\\", "/");
 }
+/**
+* The content fingerprint Studio compares snapshots by. Agent runs and CI uploads must agree on it.
+*/
 const hashOf = (content) => createHash("sha1").update(content).digest("hex").slice(0, 16);
 const totalBytes = (entries) => entries.reduce((sum, { output, disk }) => sum + output.bytes + (disk?.bytes ?? 0), 0);
+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() {
+	return {
+		maxCount: Math.max(1, Math.floor(positiveNumber(process$1.env.KUBB_AGENT_MAX_GENERATIONS) ?? 8)),
+		maxMb: positiveNumber(process$1.env.KUBB_AGENT_MAX_GENERATIONS_MB) ?? 100,
+		maxSnapshotMb: positiveNumber(process$1.env.KUBB_AGENT_MAX_SNAPSHOT_MB) ?? 50
+	};
+}
+/**
+* Folds error-severity diagnostics into one thrown error so logs name the failing plugin or pass.
+*/
+function generationFailure(diagnostics) {
+	const reasons = diagnostics.filter(Diagnostics.isProblem).filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
+	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
+	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
+}
+/**
+* Runs one generation and returns the files it produced. The formatter, the linter, and
+* `output.postGenerate` only run with `allowExec`. Throws when any plugin reports an error.
+*/
+async function generate({ config, hooks, signal, allowExec }) {
+	const output = allowExec ? config.output : {
+		...config.output,
+		format: false,
+		lint: false,
+		postGenerate: []
+	};
+	const kubb = createKubb({
+		...config,
+		output
+	}, {
+		hooks,
+		signal
+	});
+	const result = await kubb.generate();
+	if (!result.success) throw generationFailure(result.diagnostics);
+	const { storage, root } = kubb.config;
+	return {
+		storage,
+		root,
+		paths: new Set(result.files.map((file) => relativeStoragePath({
+			root,
+			filePath: file.path
+		})))
+	};
+}
 /**
 * What the output directory holds on disk before a run. `undefined` when `outputPath` is not a real
 * subdirectory of `root` (listing the root would take in every source file) or holds more than `maxFiles`.
@@ -521,9 +1131,6 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 		keep,
 		drop,
 		get: async (jobId) => (await load()).find((generation) => generation.jobId === jobId && isLive(generation)),
-		latest: async () => (await load()).filter(isLive).at(-1),
-		/** Total bytes of every set the store holds, expired ones too until the next add drops them. */
-		bytes: async () => totalBytes(await load()),
 		async add(generation) {
 			const current = await load();
 			for (const expired of current.filter((entry) => !isLive(entry))) await drop(expired.jobId);
@@ -570,7 +1177,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 	};
 }
 //#endregion
-//#region src/operations/generationEvents.ts
+//#region src/generationEvents.ts
 const MAX_QUEUED_EVENTS = 1024;
 const RESERVED_EVENTS = 64;
 const isDiscardable = (event) => event.type === "kubb:files:processing:update" || event.type === "kubb:info" || event.type === "kubb:success";
@@ -751,423 +1358,151 @@ function createGenerationStream(hooks, jobId) {
 	};
 }
 //#endregion
-//#region src/operations/rpc.ts
-const CONNECT_TIMEOUT_MS = 5e3;
-/**
-* The only methods Studio may call on an agent. A `StudioSession` carries far more than
-* {@link AgentApi}, so it is wrapped rather than exposed: what Cap'n Web can reach is exactly what
-* this class re-declares.
-*/
-var AgentRpcTarget = class extends RpcTarget {
-	api;
-	constructor(api) {
-		super();
-		this.api = api;
-	}
-	connect() {
-		return this.api.connect();
-	}
-	startGeneration(input) {
-		return this.api.startGeneration(input);
-	}
-	saveConfig(input) {
-		return this.api.saveConfig(input);
-	}
-	publishSnapshot(input) {
-		return this.api.publishSnapshot(input);
-	}
-	readFiles(input) {
-		return this.api.readFiles(input);
-	}
-	cancel(jobId) {
-		return this.api.cancel(jobId);
-	}
-};
+//#region src/url.ts
 /**
-* Opens a Studio WebSocket, closing it when the handshake exceeds {@link CONNECT_TIMEOUT_MS}. Node
-* fires no `close` event when the handshake itself fails, only `error`, so `closed` settles as 1006 there.
+* Hosted Kubb Studio URL, used when a host passes none.
 */
-function openSocket({ url, headers }) {
-	const socket = new WebSocket(url, { headers });
-	return {
-		socket,
-		closed: new Promise((resolve) => {
-			let opened = false;
-			const timer = setTimeout(() => {
-				if (socket.readyState === WebSocket.CONNECTING) socket.close(3008, "Connection timeout");
-			}, CONNECT_TIMEOUT_MS);
-			socket.addEventListener("open", () => {
-				opened = true;
-				clearTimeout(timer);
-			}, { once: true });
-			socket.addEventListener("close", (event) => {
-				clearTimeout(timer);
-				resolve({
-					code: event.code,
-					reason: event.reason
-				});
-			}, { once: true });
-			socket.addEventListener("error", () => {
-				if (opened) return;
-				clearTimeout(timer);
-				resolve({
-					code: 1006,
-					reason: ""
-				});
-			});
-		})
-	};
+const defaultStudioUrl = "https://kubb.studio";
+function isLoopbackHost(hostname) {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
 }
 /**
-* Opens an authenticated Cap'n Web session to Studio over a WebSocket. Rejects an unencrypted URL
-* before opening the socket, so a bearer token never reaches a plaintext host.
+* Appends `path` to the Studio URL and refuses plaintext to anything but this machine, so a token
+* or API key never crosses the network unencrypted. `socket` switches the scheme to `ws:`/`wss:`.
 *
 * @example
 * ```ts
-* const rpc = await connectWebSocketRpc({ url: 'wss://studio.kubb.dev/s/1', token, local: session })
-* await rpc.studio.ping()
+* secureUrl({ studioUrl: 'https://kubb.studio', path: '/api/agent/socket', socket: true }).href // 'wss://kubb.studio/api/agent/socket'
 * ```
 */
-const connectWebSocketRpc = async ({ url, token, instanceId, local }) => {
-	const { protocol, hostname, host } = new URL(url);
-	if (protocol !== "wss:" && !(protocol === "ws:" && isLoopbackHost(hostname))) throw new Error(`Refusing unencrypted WebSocket to ${host}`);
-	const { socket, closed } = openSocket({
-		url,
-		headers: {
-			Authorization: `Bearer ${token}`,
-			[AGENT_INSTANCE_HEADER]: instanceId
-		}
-	});
-	const studio = newWebSocketRpcSession(socket, new AgentRpcTarget(local));
-	studio.onRpcBroken(() => socket.close());
-	return {
-		studio,
-		closed,
-		close: () => studio[Symbol.dispose]()
-	};
-};
+function secureUrl({ studioUrl, path, socket = false }) {
+	const url = new URL(`${studioUrl.replace(/\/+$/, "")}${path}`);
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) throw new Error(`Refusing to reach Kubb Studio at ${url.origin}: use an https:// URL, or a loopback host for local development`);
+	if (socket) url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+	return url;
+}
 //#endregion
-//#region src/runtime/StudioSession.ts
+//#region src/connect.ts
+const HEARTBEAT_INTERVAL_MS = 3e4;
+const MAX_HEARTBEAT_INTERVAL_MS = 6e4;
+const PING_TIMEOUT_MS = 1e4;
+const OPEN_TIMEOUT_MS = 5e3;
+const MAX_RETRY_DELAY_MS = 3e4;
 const DISK_SNAPSHOT_MAX_FILES = 1e4;
+const SANDBOX_GENERATION_TTL_MS = 9e5;
 /**
-* Folds error-severity diagnostics into one thrown error so logs name the failing plugin or pass.
+* Studio closed with {@link AgentCloseCode.UNAUTHORIZED}. Hosts forget the token and pair again.
 */
-function generationFailure(diagnostics) {
-	const reasons = diagnostics.filter(Diagnostics.isProblem).filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.plugin ? `${diagnostic.plugin}: ${diagnostic.message}` : diagnostic.message);
-	if (!reasons.length) return /* @__PURE__ */ new Error("Generation failed");
-	return /* @__PURE__ */ new Error(`Generation failed: ${reasons.length} error${reasons.length === 1 ? "" : "s"}: ${reasons.join("; ")}`);
-}
-/** A sandbox shares one in-memory generation store across tenants, so old generations expire. */
-const SANDBOX_GENERATION_TTL_MS = 9e5;
+var InvalidAgentTokenError = class extends Error {
+	constructor(studioUrl) {
+		super(`Kubb Studio rejected this agent's token. It expired or was revoked, or the agent was deleted in ${studioUrl}.`);
+		this.name = "InvalidAgentTokenError";
+	}
+};
 /**
-* A fresh root for one sandbox job. Kubb keys its output manifest cache by root, so tenants that
-* shared the agent's own root would read each other's manifest.
+* Studio closed with {@link AgentCloseCode.INCOMPATIBLE}. Only an upgrade helps.
 */
-function createJobRoot() {
-	return mkdtemp(path.join(tmpdir(), "kubb-job-"));
+var IncompatibleAgentError = class extends Error {
+	constructor({ studioUrl, detail }) {
+		super(`Kubb Studio at ${studioUrl} requires a newer agent${detail ? `: ${detail}` : ""}. Upgrade kubb or the Kubb agent image.`);
+		this.name = "IncompatibleAgentError";
+	}
+};
+function emit(hooks, name, ...args) {
+	return Promise.resolve(hooks.callHook(name, ...args)).catch(() => {});
 }
-/**
-* Removes a job root and the manifest cache Kubb derived from it. Best effort: a leftover temp
-* directory must not fail a job that already finished.
-*/
-async function removeJobRoot(jobRoot) {
-	await Promise.all([rm(jobRoot, {
-		recursive: true,
-		force: true
-	}), rm(resolveCacheDir(jobRoot), {
-		recursive: true,
-		force: true
-	})]).catch(() => {});
+function isValidPage({ cursor, limit }) {
+	if (limit === void 0) return cursor === void 0;
+	if (cursor !== void 0 && (!Number.isSafeInteger(cursor) || cursor < 0)) return false;
+	return Number.isSafeInteger(limit) && limit >= 1 && limit <= 2e3;
 }
 var GenerationRunTarget = class extends RpcTarget {
-	generationStream;
-	generationResult;
-	cancelGeneration;
-	stopGeneration;
-	constructor(generationStream, generationResult, cancelGeneration, stopGeneration) {
+	#run;
+	constructor(run) {
 		super();
-		this.generationStream = generationStream;
-		this.generationResult = generationResult;
-		this.cancelGeneration = cancelGeneration;
-		this.stopGeneration = stopGeneration;
+		this.#run = run;
 	}
 	async events() {
-		return this.generationStream;
+		return this.#run.stream;
 	}
 	result() {
-		return this.generationResult;
+		return this.#run.result;
 	}
-	cancel() {
-		return this.cancelGeneration();
+	async cancel() {
+		this.#run.stop();
 	}
 	[Symbol.dispose]() {
-		this.stopGeneration();
+		this.#run.stop();
 	}
 };
-/**
-* 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 ?? process$1.cwd();
-	return {
-		...options,
-		studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
-		root,
-		configFile: path.resolve(root, options.configPath),
-		permissions: {
-			allowWrite: false,
-			allowConfigEdit: false,
-			allowExec: false,
-			allowRead: false,
-			...options.permissions
-		},
-		heartbeatInterval: Math.min(options.heartbeatInterval ?? agentDefaults.heartbeatIntervalMs, agentDefaults.maxHeartbeatIntervalMs),
-		capacity: {
-			...resolveAgentCapacity(),
-			...options.capacity
-		},
-		instanceId: options.instanceId ?? randomUUID()
-	};
-}
-/**
-* 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, so the connection keeps this limit.
-*/
-const RUNTIME_MAX_CONCURRENT = 1;
-/**
-* Reads what Studio meant by closing the connection. A code Studio did not send on purpose is an
-* ordinary drop, and the agent reconnects as it always has.
-*/
-function planEnd(close) {
-	const code = close?.code;
-	if (code === AgentCloseCode.REAUTHENTICATE) return {
-		reason: "Kubb Studio asked the agent to register again",
-		retry: true
-	};
-	if (code === AgentCloseCode.SUPERSEDED) return {
-		reason: "another instance of this agent took over",
-		retry: false
-	};
-	if (code === AgentCloseCode.INCOMPATIBLE) return {
-		reason: "this agent is too old for Kubb Studio, or was deleted",
-		retry: false,
-		error: /* @__PURE__ */ new Error("Kubb Studio closed the connection: this agent is too old for it, or was deleted. Upgrade the agent, or pair it again.")
-	};
-	return {
-		reason: "connection closed",
-		retry: true
-	};
-}
-function isValidPage({ cursor, limit }) {
-	if (limit === void 0) return cursor === void 0;
-	if (cursor !== void 0 && (!Number.isSafeInteger(cursor) || cursor < 0)) return false;
-	return Number.isSafeInteger(limit) && limit >= 1 && limit <= 2e3;
-}
-/**
-* One agent-to-Studio RPC transport: opening it, keeping it alive, and serving remote methods.
-* `runConnection` owns the lifetime and retry of each attempt.
-*/
-var StudioSession = class {
+var Agent = class extends RpcTarget {
 	#options;
-	#hooks = new 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 registration handed back, and the marker for whether the agent registered at all.
-	* Before it resolves there is no sandbox flag to read.
-	*/
-	#registration;
-	#rpc;
-	#disposed = false;
-	#isGenerating = false;
-	#activeJob;
-	#heartbeatTimer;
-	#store;
+	#session;
 	#limits = resolveGenerationLimits();
-	/**
-	* Resolves when Studio calls {@link StudioSession.connect}. `studio:ready` waits on this so the
-	* host does not queue jobs before the agent session is registered.
-	*/
-	#connectAck = Promise.withResolvers();
-	#ended = Promise.withResolvers();
-	closed = this.#ended.promise;
-	#generationResult;
-	constructor(options) {
-		this.#options = applyStudioDefaults(options);
-		this.#connectAck.promise.catch(() => {});
+	#store;
+	constructor({ options, session }) {
+		super();
+		this.#options = options;
+		this.#session = session;
 	}
-	/**
-	* A sandbox agent runs on Studio's own infrastructure, so it has no user project to touch.
-	*/
-	get #isSandbox() {
-		return this.#registration?.isSandbox === true;
+	get #sandbox() {
+		return this.#session.info?.sandbox === true;
+	}
+	get #permissions() {
+		const { permissions } = this.#options;
+		return this.#sandbox ? {
+			...permissions,
+			allowWrite: false,
+			allowConfigEdit: false,
+			allowRead: true
+		} : permissions;
 	}
-	/**
-	* Kept in the project's cache directory, so it survives a restart, except on a sandbox: its pool
-	* sessions run every tenant's jobs, so it keeps them in memory. Looked up by job id only.
-	*/
 	get #generations() {
 		this.#store ??= createGenerationStore({
-			storage: this.#isSandbox ? memoryStorage() : cacheStorage({ root: this.#options.root }),
+			storage: this.#sandbox ? memoryStorage() : cacheStorage({ root: this.#options.root }),
 			maxCount: this.#limits.maxCount,
 			maxMb: this.#limits.maxMb,
-			ttlMs: this.#isSandbox ? SANDBOX_GENERATION_TTL_MS : void 0
+			ttlMs: this.#sandbox ? SANDBOX_GENERATION_TTL_MS : void 0
 		});
 		return this.#store;
 	}
-	get #canWrite() {
-		return !this.#isSandbox && this.#options.permissions.allowWrite;
-	}
-	get #canEditConfig() {
-		return !this.#isSandbox && this.#options.permissions.allowConfigEdit;
-	}
-	/**
-	* A sandbox agent always allows reading its output back; a local agent only when opted in.
-	*/
-	get #canRead() {
-		return this.#isSandbox || this.#options.permissions.allowRead;
-	}
-	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 (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,
-				capacity: {
-					...capacity,
-					maxConcurrent: Math.min(capacity.maxConcurrent, RUNTIME_MAX_CONCURRENT)
-				}
-			});
-			signal?.throwIfAborted();
-			this.#registration = registration;
-			const rpc = await (this.#options.connector ?? connectWebSocketRpc)({
-				url: registration.socketUrl,
-				token,
-				instanceId,
-				local: this
-			});
-			this.#rpc = rpc;
-			rpc.closed.then(this.#onClose);
-			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,
-				versions: {
-					studio: registration.version,
-					kubb: version,
-					agent: this.#options.version
-				},
-				agentSlug: registration.agentSlug,
-				organizationSlug: registration.organizationSlug
-			});
-			await this.#connectAck.promise;
-			await this.#hooks.callHook("studio:ready", {});
-		} catch (error) {
-			await this.dispose();
-			if (!signal?.aborted) await this.#hooks.callHook("studio:error", { error: toError(error) });
-			throw error;
-		}
-	}
-	reportRetry(delayMs) {
-		return this.#hooks.callHook("studio:reconnecting", { delayMs });
-	}
-	#warn(message, permission) {
-		return this.#hooks.callHook("studio:warn", {
+	#warn({ message, permission }) {
+		return emit(this.#options.hooks, "studio:warn", {
 			message,
 			permission
 		});
 	}
-	/**
-	* Declines a request: logs why locally, then tells Studio. The two wordings differ on purpose,
-	* since the log names the request that was ignored and the error names what the caller can do.
-	*/
-	async #refuse(reason, message, permission) {
-		await this.#warn(reason, permission);
+	async #refuse({ message, permission }) {
+		await this.#warn({
+			message,
+			permission
+		});
 		throw new Error(message);
 	}
-	/**
-	* Brackets one Studio command with `studio:command:start` and `studio:command:end`. A command
-	* that declined its request reports no `info`, and only the start is heard.
-	*/
 	async #command({ command, run }) {
-		await this.#hooks.callHook("studio:command:start", { command });
+		if (!this.#session.info) throw new Error("Studio must call connect() before any other command");
 		const { value, info } = await run();
-		if (info !== void 0) await this.#hooks.callHook("studio:command:end", {
+		if (info !== void 0) await emit(this.#options.hooks, "studio:command", {
 			command,
 			info
 		});
 		return value;
 	}
-	#scheduleHeartbeat(interval) {
-		const rpc = this.#rpc;
-		if (!rpc) return;
-		this.#heartbeatTimer = setTimeout(async () => {
-			try {
-				await this.#ping(rpc);
-			} catch {
-				if (this.#rpc === rpc) rpc.close();
-				return;
-			}
-			if (this.#rpc === rpc) this.#scheduleHeartbeat(interval);
-		}, interval);
-	}
-	/**
-	* Races `studio.ping()` against a deadline, so a half-open socket can't hang it forever.
-	* */
-	async #ping(rpc) {
-		const { promise: timedOut, reject: onTimeout } = Promise.withResolvers();
-		const timer = setTimeout(() => onTimeout(/* @__PURE__ */ new Error("Heartbeat ping timed out")), agentDefaults.heartbeatTimeoutMs);
-		try {
-			const load = await Promise.race([this.#load().catch(() => void 0), timedOut]);
-			await Promise.race([rpc.studio.ping(load), timedOut]);
-		} finally {
-			clearTimeout(timer);
-		}
-	}
-	async #load() {
-		return {
-			running: this.#isGenerating ? 1 : 0,
-			rssMb: Math.round(process$1.memoryUsage().rss / 1048576),
-			storeBytes: await this.#generations.bytes(),
-			accepting: true
-		};
-	}
-	/**
-	* 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;
+		if (!this.#permissions.allowConfigEdit) return void 0;
 		try {
-			const { readConfig } = await import("./configFile-zhp5DQIe.js");
 			return readConfig(source ?? await read(this.#options.configFile));
 		} catch (error) {
-			await this.#warn(`Could not read ${this.#options.configFile}: ${getErrorMessage(error)}`);
+			await this.#warn({ message: `Could not read ${this.#options.configFile}: ${getErrorMessage(error)}` });
 			return;
 		}
 	}
-	async connect() {
-		const { configPath, root, version: version$1, loadConfig, permissions } = this.#options;
+	async connect(info) {
+		this.#session.info = info;
+		const { configPath, root, version: version$1, loadConfig } = this.#options;
 		const [config, file] = await Promise.all([loadConfig(), this.#readConfigFileView()]);
-		const payload = {
+		this.#session.connected.resolve(info);
+		return {
 			versions: {
 				kubb: version,
 				agent: version$1
@@ -1181,197 +1516,131 @@ var StudioSession = class {
 					options: plugin.options ?? {}
 				}))
 			},
-			permissions: {
-				...permissions,
-				allowWrite: this.#canWrite,
-				allowConfigEdit: this.#canEditConfig,
-				allowRead: this.#canRead
-			}
+			permissions: this.#permissions
 		};
-		this.#connectAck.resolve();
-		return payload;
-	}
-	#onAbort = () => void this.#end({
-		reason: "shutdown",
-		retry: false
-	}).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.#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;
-		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);
+	startGeneration(input) {
+		const stream = createGenerationStream(this.#options.hooks, input.jobId);
 		const controller = new AbortController();
-		const cancelRun = async () => {
-			controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
-		};
-		const result = this.#runGeneration(data, controller, cancelRun).then(async (value) => {
-			await generationStream.close();
-			return value;
-		}).catch((error) => {
-			generationStream.fail(error);
+		const result = this.#runGeneration(input, controller).then((value) => stream.close().then(() => value), (error) => {
+			stream.fail(error);
 			throw error;
-		}).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"));
-			generationStream.dispose();
+		return new GenerationRunTarget({
+			stream: stream.stream,
+			result,
+			stop: () => {
+				controller.abort(/* @__PURE__ */ new Error("Generation canceled"));
+				stream.dispose();
+			}
 		});
 	}
-	/**
-	* Cancels the currently running job when its id matches `jobId`.
-	*/
-	async cancel(jobId) {
-		if (this.#activeJob?.jobId === jobId) await this.#activeJob.cancel();
-	}
-	async #runGeneration(data, controller, cancelRun) {
-		if (this.#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 = {
-			jobId: data.jobId,
-			cancel: cancelRun
+	async #runGeneration(input, controller) {
+		if (this.#session.closed) throw new Error("Connection is closed");
+		if (this.#session.active) return this.#refuse({ message: "A generation is already in progress, please wait for it to finish" });
+		const settled = Promise.withResolvers();
+		this.#session.active = {
+			jobId: input.jobId,
+			abort: () => controller.abort(/* @__PURE__ */ new Error("Generation canceled")),
+			settled: settled.promise
 		};
 		let root = this.#options.root;
 		try {
-			if (this.#isSandbox) root = await createJobRoot();
+			if (this.#sandbox) root = await mkdtemp(path.join(tmpdir(), "kubb-job-"));
 			return await this.#command({
 				command: "generate",
 				run: () => this.#generate({
-					data,
+					input,
 					root,
 					signal: controller.signal
 				})
 			});
 		} finally {
-			if (root !== this.#options.root) await removeJobRoot(root);
-			this.#isGenerating = false;
+			if (root !== this.#options.root) await Promise.all([rm(root, {
+				recursive: true,
+				force: true
+			}), rm(resolveCacheDir(root), {
+				recursive: true,
+				force: true
+			})]).catch(() => {});
+			this.#session.active = void 0;
+			settled.resolve();
 		}
 	}
-	async #generate({ data, root, signal }) {
-		const { loadConfig, permissions } = this.#options;
-		const config = await loadConfig();
-		const patch = data.config;
-		const plugins = await mergePlugins(config.plugins, patch?.plugins);
+	async #generate({ input, root, signal }) {
+		const { jobId, config: patch } = input;
+		const config = await this.#options.loadConfig();
+		const plugins = await mergePlugins(config.plugins, patch?.plugins) ?? config.plugins;
 		const adapter = await mergeAdapter(config.adapter, patch?.adapter);
-		const inputOverride = this.#isSandbox ? 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.#isSandbox) await this.#warn("Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox agent");
-		const resolvedPlugins = plugins ?? config.plugins;
-		const storage = this.#canWrite ? fsStorage() : memoryStorage();
-		const diskFiles = this.#hasProjectOnDisk ? await listDisk({
+		const studioInput = this.#sandbox ? patch?.input ?? "" : void 0;
+		if (patch?.input && !this.#sandbox) await this.#warn({ message: "Ignored the spec from Studio: generating from a Studio spec is only available to a sandbox agent" });
+		const diskFiles = !this.#sandbox && this.#permissions.allowRead ? await listDisk({
 			root,
 			outputPath: config.output.path,
 			maxFiles: DISK_SNAPSHOT_MAX_FILES
 		}) : void 0;
 		const disk = diskFiles ? await this.#generations.keep({
-			jobId: data.jobId,
+			jobId,
 			source: "disk",
 			files: diskFiles,
 			maxSetMb: this.#limits.maxSnapshotMb
 		}) : void 0;
-		const result = await createKubb({
-			...config,
-			root,
-			input: inputOverride ?? config.input,
-			storage,
-			output: permissions.allowExec ? { ...config.output } : {
-				...config.output,
-				format: false,
-				lint: false,
-				postGenerate: []
+		const files = await generate({
+			config: {
+				...config,
+				root,
+				input: studioInput ?? config.input,
+				storage: this.#permissions.allowWrite ? fsStorage() : memoryStorage(),
+				plugins,
+				adapter
 			},
-			plugins: resolvedPlugins,
-			adapter
-		}, {
-			hooks: this.#hooks,
-			signal
-		}).generate().catch(async (error) => {
-			await this.#generations.drop(data.jobId);
+			hooks: this.#options.hooks,
+			signal,
+			allowExec: this.#permissions.allowExec
+		}).catch(async (error) => {
+			await this.#generations.drop(jobId);
 			throw error;
 		});
-		if (!result.success) {
-			await this.#generations.drop(data.jobId);
-			throw generationFailure(result.diagnostics);
-		}
-		const paths = new Set(result.files.map((file) => relativeStoragePath({
-			root,
-			filePath: file.path
-		})));
 		const output = await this.#generations.keep({
-			jobId: data.jobId,
+			jobId,
 			source: "output",
-			files: {
-				storage,
-				root,
-				paths
-			},
+			files,
 			maxSetMb: this.#limits.maxMb
 		});
-		if (!output.paths.length && Object.keys(output.hashes).length) await this.#warn("Kept only the hashes of this generation: its output is too large to keep");
-		const { peerDependencies, missingDependencies } = await resolvePeerDependencies(resolvedPlugins.map(({ name }) => name));
+		if (!output.paths.length && Object.keys(output.hashes).length) await this.#warn({ message: "Kept only the hashes of this generation: its output is too large to keep" });
 		await this.#generations.add({
-			jobId: data.jobId,
+			jobId,
 			output,
-			disk,
-			peerDependencies,
-			missingDependencies
+			disk
 		});
 		return {
 			value: {
 				status: "success",
-				files: [...paths],
-				fileCount: paths.size,
+				files: [...files.paths],
+				fileCount: files.paths.size,
 				hashes: output.hashes,
 				disk: disk ? { hashes: disk.hashes } : void 0
 			},
-			info: `${resolvedPlugins.length} plugin${resolvedPlugins.length === 1 ? "" : "s"}, ${this.#canWrite ? "written to disk" : "in memory"}${inputOverride !== void 0 ? ", from a Studio spec" : ""}`
+			info: `${plugins.length} plugin${plugins.length === 1 ? "" : "s"}, ${this.#permissions.allowWrite ? "written to disk" : "in memory"}${studioInput !== void 0 ? ", from a Studio spec" : ""}`
 		};
 	}
-	saveConfig(data) {
+	saveConfig(input) {
 		return this.#command({
 			command: "saveConfig",
-			run: () => this.#saveConfig(data)
+			run: () => this.#saveConfig(input)
 		});
 	}
-	async #saveConfig(data) {
+	async #saveConfig(input) {
 		const { configPath, configFile } = this.#options;
-		if (!Array.isArray(data.edits)) {
-			await this.#warn("Ignored save: the message carried no edits");
+		if (!Array.isArray(input.edits)) {
+			await this.#warn({ message: "Ignored save: the message carried no edits" });
 			return { value: {
 				outcomes: [],
 				changed: false
 			} };
 		}
-		const edits = data.edits;
+		const edits = input.edits;
 		const refuse = (reason) => ({
 			outcomes: edits.map((edit) => ({
 				edit,
@@ -1380,14 +1649,13 @@ var StudioSession = class {
 			})),
 			changed: false
 		});
-		if (!this.#canEditConfig) {
-			await this.#warn("Ignored save: editing kubb.config.ts was not granted");
+		if (!this.#permissions.allowConfigEdit) {
+			await this.#warn({ message: "Ignored save: editing kubb.config.ts was not granted" });
 			return { value: refuse("the agent was not granted permission to edit kubb.config.ts") };
 		}
-		if (this.#isGenerating) return { value: refuse("a generation is in progress") };
+		if (this.#session.active) return { value: refuse("a generation is in progress") };
 		try {
-			const { writeConfigEdits } = await import("./configFile-zhp5DQIe.js");
-			const { source: patched, outcomes, changed } = await writeConfigEdits({
+			const { source, outcomes, changed } = await writeConfigEdits({
 				filePath: configFile,
 				edits
 			});
@@ -1396,89 +1664,40 @@ var StudioSession = class {
 				value: {
 					outcomes,
 					changed,
-					file: changed ? await this.#readConfigFileView(patched) : void 0
+					file: changed ? await this.#readConfigFileView(source) : void 0
 				},
 				info: `applied ${applied}/${outcomes.length} edits to ${configPath}`
 			};
 		} catch (error) {
-			await this.#hooks.callHook("studio:error", { error: toError(error) });
+			await emit(this.#options.hooks, "studio:error", { error: toError(error) });
 			return { value: refuse(getErrorMessage(error)) };
 		}
 	}
-	publishSnapshot(data) {
-		return this.#command({
-			command: "snapshot",
-			run: () => this.#publishSnapshot(data)
-		});
-	}
-	async #publishSnapshot(data) {
-		if (this.#isSandbox) return this.#refuse("Ignored snapshot: a sandbox agent has no project to build a package from", "A sandbox agent has no project to build a package from");
-		const { name, version, bundledDependencies, uploadPath } = data;
-		if (!name || !version || !uploadPath) return this.#refuse("Ignored snapshot: the message was missing required fields", "The request was missing required fields");
-		const generation = await this.#generations.latest();
-		if (!generation) return this.#refuse("Ignored snapshot: no prior generation to pack", "No prior generation exists to pack, run a generation first");
-		const bundled = new Set(bundledDependencies ?? []);
-		const missing = generation.missingDependencies.filter((dependency) => !bundled.has(dependency));
-		if (missing.length) return this.#refuse(`Ignored snapshot: missing dependencies: ${missing.join(", ")}`, `Missing dependencies: ${missing.join(", ")}`);
-		try {
-			const { createSnapshotPackage, uploadSnapshot } = await import("./snapshotPackage-BwZ8IJX-.js");
-			const { files } = await this.#generations.read({
-				generation,
-				source: "output",
-				paths: generation.output.paths
-			});
-			const { bytes, integrity } = await createSnapshotPackage(files, {
-				name,
-				version,
-				peerDependencies: generation.peerDependencies
-			});
-			const { token, studioUrl, signal } = this.#options;
-			await uploadSnapshot({
-				bytes,
-				uploadPath,
-				studioUrl,
-				token,
-				shutdown: signal
-			});
-			return {
-				value: {
-					integrity,
-					peerDependencies: generation.peerDependencies
-				},
-				info: `packed ${Object.keys(files).length} file${Object.keys(files).length === 1 ? "" : "s"}`
-			};
-		} catch (error) {
-			await this.#hooks.callHook("studio:error", { error: toError(error) });
-			throw error;
-		}
-	}
-	/** A sandbox has no project directory to snapshot. */
-	get #hasProjectOnDisk() {
-		return !this.#isSandbox && this.#canRead;
-	}
-	readFiles(data) {
+	readFiles(input) {
 		return this.#command({
 			command: "readFiles",
-			run: () => this.#readFiles(data)
+			run: () => this.#readFiles(input)
 		});
 	}
-	async #readFiles(data) {
-		if (!this.#canRead) return this.#refuse("Ignored files: reading generated files was not granted", "The agent was not granted permission to read generated files", "allowRead");
-		if (!Array.isArray(data.paths)) return this.#refuse("Ignored files: the message carried no paths", "The request carried no paths");
-		const { paths } = data;
-		if (paths.length > 50) return this.#refuse(`Ignored files: requested ${paths.length} paths, more than the 50 allowed per request`, `At most 50 paths may be requested at once`);
-		if (typeof data.jobId !== "string" || !data.jobId) return this.#refuse("Ignored files: the message named no job", "The request named no generation job");
-		const generation = await this.#generations.get(data.jobId);
-		if (!generation) return this.#refuse(`Ignored files: job ${data.jobId} is not kept on this agent`, GENERATION_GONE_MESSAGE);
-		if (!isValidPage(data)) return this.#refuse("Ignored files: the message carried an invalid page", `The cursor must be a whole line from 0 and come with a limit of 1 to ${MAX_PAGE_LINES} lines`);
-		const source = data.source === "disk" ? "disk" : "output";
-		if (!generation[source]) return this.#refuse("Ignored files: that job has no snapshot of the files on disk", "This agent kept no snapshot of the files on disk for that job");
+	async #readFiles(input) {
+		if (!this.#permissions.allowRead) return this.#refuse({
+			message: "The agent was not granted permission to read generated files",
+			permission: "allowRead"
+		});
+		if (!Array.isArray(input.paths) || typeof input.jobId !== "string" || !input.jobId) return this.#refuse({ message: "The request must name a job and carry paths" });
+		const { paths } = input;
+		if (paths.length > 50) return this.#refuse({ message: `At most 50 paths may be requested at once` });
+		const generation = await this.#generations.get(input.jobId);
+		if (!generation) return this.#refuse({ message: GENERATION_GONE_MESSAGE });
+		if (!isValidPage(input)) return this.#refuse({ message: `The cursor must be a whole line from 0 and come with a limit of 1 to ${MAX_PAGE_LINES} lines` });
+		const source = input.source === "disk" ? "disk" : "output";
+		if (!generation[source]) return this.#refuse({ message: "This agent kept no snapshot of the files on disk for that job" });
 		const result = await this.#generations.read({
 			generation,
 			source,
 			paths,
-			cursor: data.cursor,
-			limit: data.limit
+			cursor: input.cursor,
+			limit: input.limit
 		});
 		return {
 			value: result,
@@ -1486,96 +1705,159 @@ var StudioSession = class {
 		};
 	}
 };
-//#endregion
-//#region src/runtime/runConnection.ts
-/** Runs the process's one connection loop, including retries and credential replacement. */
-async function runConnection({ credentials, clientOptions, onTokenRejected, signal, onStarted }) {
-	let current = credentials;
-	const initialOptions = clientOptions(current);
-	const instanceId = initialOptions.instanceId ?? randomUUID();
-	let options = initialOptions;
-	let attempt = 0;
-	let live = false;
-	while (!signal?.aborted) {
-		const session = new StudioSession({
-			...options,
-			instanceId,
-			token: current.token,
-			signal
+const openWebSocketRpc = ({ url, token, instanceId, agent }) => {
+	const socket = new WebSocket(url, { headers: {
+		Authorization: `Bearer ${token}`,
+		[AGENT_INSTANCE_HEADER]: instanceId
+	} });
+	const timer = setTimeout(() => socket.close(3008, "Connection timeout"), OPEN_TIMEOUT_MS);
+	socket.addEventListener("open", () => clearTimeout(timer), { once: true });
+	const closed = new Promise((resolve) => {
+		socket.addEventListener("close", ({ code, reason }) => resolve({
+			code,
+			reason
+		}), { once: true });
+		socket.addEventListener("error", () => {
+			if (socket.readyState !== WebSocket.OPEN) resolve({
+				code: 1006,
+				reason: ""
+			});
 		});
-		try {
-			await session.start();
-			live = true;
-			attempt = 0;
-			onStarted?.();
-			if (!(await session.closed).retry) return signal?.aborted ? "shutdown" : "stopped";
-		} catch (error) {
-			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 {
-			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 setTimeout$1(delayMs, void 0, { signal });
-		} catch (error) {
-			if (!signal?.aborted) throw error;
+	}).finally(() => clearTimeout(timer));
+	const studio = newWebSocketRpcSession(socket, agent);
+	studio.onRpcBroken(() => socket.close());
+	return {
+		studio,
+		closed,
+		close: () => {
+			studio[Symbol.dispose]();
+			socket.close();
 		}
-	}
-	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;
+	};
+};
+async function runSession({ options, openRpc, url, instanceId }) {
+	const { hooks, signal, heartbeatInterval, token, studioUrl, version: version$2 } = options;
+	const session = {
+		connected: Promise.withResolvers(),
+		closed: false
+	};
+	const rpc = openRpc({
+		url,
+		token,
+		instanceId,
+		agent: new Agent({
+			options,
+			session
+		})
+	});
+	signal?.addEventListener("abort", rpc.close, { once: true });
+	let timer;
+	const heartbeat = async () => {
+		let deadline;
+		const timedOut = new Promise((resolve) => deadline = setTimeout(resolve, PING_TIMEOUT_MS, true));
+		const failed = await Promise.race([Promise.resolve(rpc.studio.ping()).then(() => false, () => true), timedOut]);
+		clearTimeout(deadline);
+		if (failed) return rpc.close();
+		if (!session.closed) timer = setTimeout(heartbeat, heartbeatInterval);
+	};
+	session.connected.promise.then(async (info) => {
+		await emit(hooks, "studio:connected", {
+			...info,
+			url: studioUrl,
+			versions: {
+				studio: info.studioVersion,
+				kubb: version,
+				agent: version$2
+			}
+		});
+		if (!session.closed) timer = setTimeout(heartbeat, heartbeatInterval);
+	}, () => {});
+	const close = await rpc.closed;
+	session.closed = true;
+	clearTimeout(timer);
+	signal?.removeEventListener("abort", rpc.close);
+	session.connected.reject(/* @__PURE__ */ new Error("The socket closed before Studio called connect()"));
+	session.active?.abort();
+	await session.active?.settled;
 	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;
+		...close,
+		connected: session.info !== void 0
+	};
+}
+/**
+* The connection loop with a swappable transport. {@link connectAgent} passes a real WebSocket.
+*/
+async function runAgent({ options, openRpc }) {
+	const root = options.root ?? process$1.cwd();
+	const resolved = {
+		...options,
+		studioUrl: options.studioUrl ?? "https://kubb.studio",
+		root,
+		configFile: path.resolve(root, options.configPath),
+		permissions: {
+			allowWrite: false,
+			allowConfigEdit: false,
+			allowExec: false,
+			allowRead: false,
+			...options.permissions
 		},
-		disconnect() {
-			shutdown.abort();
-		}
+		hooks: options.hooks ?? new Hookable(),
+		maxRetryDelay: options.maxRetryDelay ?? MAX_RETRY_DELAY_MS,
+		heartbeatInterval: Math.min(options.heartbeatInterval ?? HEARTBEAT_INTERVAL_MS, MAX_HEARTBEAT_INTERVAL_MS)
 	};
+	const { studioUrl, hooks, signal, maxRetryDelay } = resolved;
+	const url = secureUrl({
+		studioUrl,
+		path: AGENT_SOCKET_PATH,
+		socket: true
+	});
+	const instanceId = randomUUID();
+	let attempt = 0;
+	while (!signal?.aborted) {
+		const { code, reason, connected } = await runSession({
+			options: resolved,
+			openRpc,
+			url,
+			instanceId
+		});
+		if (signal?.aborted) return;
+		await emit(hooks, "studio:disconnected", {
+			code,
+			reason
+		});
+		if (code === AgentCloseCode.UNAUTHORIZED) throw new InvalidAgentTokenError(studioUrl);
+		if (code === AgentCloseCode.INCOMPATIBLE) throw new IncompatibleAgentError({
+			studioUrl,
+			detail: reason
+		});
+		if (code === AgentCloseCode.SUPERSEDED) return;
+		if (connected) attempt = 0;
+		const delayMs = Math.random() * Math.min(1e3 * 2 ** Math.min(attempt++, 16), maxRetryDelay);
+		await emit(hooks, "studio:reconnecting", { delayMs });
+		await setTimeout$1(delayMs, void 0, { signal }).catch(() => {});
+	}
+}
+/**
+* Connects this project to Kubb Studio and serves its commands until `signal` aborts. Reconnects
+* with jittered backoff, and resolves when another process of the agent takes over. Rejects with
+* {@link InvalidAgentTokenError} so the host can pair again, or {@link IncompatibleAgentError}.
+*
+* @example
+* ```ts
+* const hooks = new Hookable<KubbHooks>()
+* hooks.hook('studio:connected', ({ agentSlug }) => console.log(`Connected as ${agentSlug}`))
+*
+* await connectAgent({ token, configPath: 'kubb.config.ts', loadConfig, version: '1.0.0', hooks, signal })
+* ```
+*/
+function connectAgent(options) {
+	return runAgent({
+		options,
+		openRpc: openWebSocketRpc
+	});
 }
 //#endregion
-//#region src/operations/pair.ts
+//#region src/pair.ts
 /** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
 const CLIENT_IDS = {
 	cli: "kubb-cli",
@@ -1607,30 +1889,33 @@ var PairingDeniedError = class extends Error {
 	}
 };
 /**
-* 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.
+* Asks Studio for a pairing code, sending the hashed machine id with it.
 */
-async function startPairing({ studioUrl = agentDefaults.studioUrl, type, name, hostname, signal }) {
+async function startPairing({ studioUrl = defaultStudioUrl, type, name, hostname, machineId, signal }) {
 	try {
-		return await ofetch(`${studioUrl}/api/auth/device/code`, {
+		const pairing = await ofetch(secureUrl({
+			studioUrl,
+			path: "/api/auth/device/code"
+		}).href, {
 			method: "POST",
 			body: {
 				client_id: type === "cli" ? CLIENT_IDS.cli : CLIENT_IDS.agent,
 				name,
 				hostname,
-				machine_token: await getMachineToken(),
+				machine_token: hash("sha256", machineId),
 				agent_kind: type === "cli" ? void 0 : type
 			},
 			signal
 		});
+		if (typeof pairing?.device_code !== "string") throw new Error("Kubb Studio returned no pairing code");
+		return pairing;
 	} 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";
+	return "token" in response && typeof response.token === "string";
 }
 /**
 * Polls until the user approves or denies, honoring the server's `slow_down` back-off.
@@ -1642,7 +1927,7 @@ function isPairingResult(response) {
 * @throws {PairingDeniedError} when the pairing is denied in the browser.
 * @throws {PairingCanceledError} when `signal` aborts.
 */
-async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal, onRetry }) {
+async function pollForPairingToken({ studioUrl = defaultStudioUrl, session, signal, onRetry }) {
 	const deadline = Date.now() + (session.expires_in > 0 ? session.expires_in : 600) * 1e3;
 	let intervalMs = (session.interval > 0 ? session.interval : 5) * 1e3;
 	while (Date.now() < deadline) {
@@ -1654,19 +1939,24 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 		}
 		let response;
 		try {
-			response = await ofetch(`${studioUrl}/api/agent/token`, {
+			const { status, _data } = await ofetch.raw(secureUrl({
+				studioUrl,
+				path: "/api/agent/token"
+			}).href, {
 				method: "POST",
 				body: { device_code: session.device_code },
-				ignoreResponseError: true,
-				signal
+				signal,
+				ignoreResponseError: true
 			});
+			if (status >= 500 || !_data || typeof _data !== "object") throw new Error(`Kubb Studio answered with status ${status}`);
+			response = _data;
 		} catch (error) {
 			if (signal?.aborted) throw new PairingCanceledError();
 			onRetry?.(toError(error));
 			continue;
 		}
 		if (isPairingResult(response)) return response;
-		if (!response || typeof response !== "object" || !("error" in response) || typeof response.error !== "string") throw new Error("Kubb Studio returned an empty pairing response, pair again");
+		if (!("error" in response) || typeof response.error !== "string") throw new Error("Kubb Studio returned an empty pairing response, pair again");
 		if (response.error === "authorization_pending") continue;
 		if (response.error === "slow_down") {
 			intervalMs += 5e3;
@@ -1698,6 +1988,196 @@ async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
 	}
 }
 //#endregion
-export { AGENT_INSTANCE_HEADER, AgentCloseCode, IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectWebSocketRpc, createAgent, createClient, createFileStorage, createJob, defaultStudioUrl, generationEventTypes, machineTokenFrom, pairAgent, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
+//#region src/snapshot.ts
+const gzipAsync = promisify(gzip);
+const UPLOAD_TIMEOUT_MS = 12e4;
+const BUNDLED_DEPENDENCIES = ["@kubb/plugin-barrel"];
+/**
+* Maps a generated file to its path in the package, from its `src`/`dist` segment on, without `..` parts that could escape it.
+*/
+function packagePath(filePath) {
+	const normalized = filePath.replaceAll("\\", "/");
+	return (normalized.match(/\/(?:src|dist)\/.*$/)?.[0] ?? normalized).split("/").filter((part) => part && part !== "." && part !== "..").join("/");
+}
+/**
+* Splits a tar path into the 100-byte USTAR `name` and the 155-byte `prefix`, and throws for a path that fits neither.
+*/
+function splitEntryPath(path) {
+	if (Buffer.byteLength(path) <= 100) return {
+		name: path,
+		prefix: ""
+	};
+	for (let i = path.lastIndexOf("/"); i > 0; i = path.lastIndexOf("/", i - 1)) {
+		const prefix = path.slice(0, i);
+		const name = path.slice(i + 1);
+		if (Buffer.byteLength(prefix) <= 155 && Buffer.byteLength(name) <= 100) return {
+			name,
+			prefix
+		};
+	}
+	throw new Error(`Snapshot path is too long for a tar entry: ${path}`);
+}
+function header(path, size) {
+	const { name, prefix } = splitEntryPath(path);
+	const value = Buffer.alloc(512);
+	value.write(name);
+	value.write("0000644\0", 100);
+	for (const offset of [
+		108,
+		116,
+		265,
+		297
+	]) value.write("0000000\0", offset);
+	value.write(`${size.toString(8).padStart(11, "0")}\0`, 124);
+	value.write("03560116604\0", 136);
+	value.fill(32, 148, 156);
+	value.write("0", 156);
+	value.write("ustar\0", 257);
+	value.write("00", 263);
+	value.write(prefix, 345);
+	const checksum = value.reduce((sum, byte) => sum + byte, 0);
+	value.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148);
+	return value;
+}
+/**
+* Packs a generation's files into a gzipped, npm-installable tarball: a `package/` root with the
+* generated sources, a `tsdown`-built `dist/` (esm + cjs), and a `package.json` manifest.
+*/
+async function createSnapshotPackage({ files, packageInfo }) {
+	const sources = /* @__PURE__ */ new Map();
+	for (const [name, content] of Object.entries(files)) {
+		const path = packagePath(name);
+		const owner = sources.get(path)?.name;
+		if (owner) throw new Error(`Snapshot has two generated files that sanitize to the same path "package/${path}": "${owner}" and "${name}"`);
+		sources.set(path, {
+			name,
+			content
+		});
+	}
+	const root = await mkdtemp(join(tmpdir(), "kubb-snapshot-"));
+	const dist = join(root, "dist");
+	try {
+		await mkdir(dist);
+		await Promise.all([...sources].map(async ([path, { content }]) => {
+			await mkdir(dirname(join(root, path)), { recursive: true });
+			await writeFile(join(root, path), content);
+		}));
+		const entry = [...sources.keys()].filter((path) => /\.(?:[cm]?[jt]sx?)$/.test(path)).map((path) => join(root, path));
+		if (entry.length) {
+			const { build } = await import("tsdown");
+			await build({
+				entry,
+				outDir: dist,
+				format: ["esm", "cjs"],
+				dts: false,
+				sourcemap: false,
+				unbundle: true,
+				report: false,
+				logLevel: "silent",
+				fixedExtension: true
+			});
+		}
+		const built = await fsStorage().readKeys(dist);
+		const hasBarrel = built.includes("index.mjs") && built.includes("index.cjs");
+		const manifest = {
+			...packageInfo,
+			type: "module",
+			...hasBarrel ? {
+				main: "./dist/index.cjs",
+				module: "./dist/index.mjs"
+			} : {},
+			exports: {
+				...hasBarrel ? { ".": {
+					import: "./dist/index.mjs",
+					require: "./dist/index.cjs"
+				} } : {},
+				"./*": {
+					import: "./dist/*.mjs",
+					require: "./dist/*.cjs"
+				}
+			}
+		};
+		const chunks = [...new Map([
+			["package.json", JSON.stringify(manifest, null, 2)],
+			...[...sources].map(([path, { content }]) => [path, content]),
+			...await Promise.all(built.map(async (key) => [`dist/${key}`, await readFile(join(dist, key), "utf8")]))
+		])].flatMap(([path, content]) => {
+			const bytes = Buffer.from(content);
+			return [
+				header(`package/${path}`, bytes.length),
+				bytes,
+				Buffer.alloc((512 - bytes.length % 512) % 512)
+			];
+		});
+		return await gzipAsync(Buffer.concat([...chunks, Buffer.alloc(1024)]));
+	} finally {
+		await rm(root, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/**
+* Generates the project, packs it as an npm tarball, and publishes it to Studio in one `POST /api/snapshots` request.
+*
+* @example
+* ```ts
+* const { url } = await createSnapshot({ apiKey: process.env.KUBB_TOKEN!, config, id: 'gh:123:pr-4', name: 'acme/api#4', packageName: '@acme/api', version: '1.0.0' })
+* ```
+*/
+async function createSnapshot({ studioUrl = defaultStudioUrl, apiKey, config, hooks, signal, ...metadata }) {
+	const url = secureUrl({
+		studioUrl,
+		path: "/api/snapshots"
+	});
+	const generated = await generate({
+		config,
+		hooks,
+		signal,
+		allowExec: true
+	});
+	const files = Object.fromEntries(await Promise.all([...generated.paths].map(async (path) => {
+		const content = await generated.storage.readItem(resolve(generated.root, path));
+		if (content === null) throw new Error(`The generation listed ${path} but did not keep its content`);
+		return [path, content];
+	})));
+	const { peerDependencies, missingDependencies } = await resolvePeerDependencies(config.plugins.map(({ name }) => name));
+	const missing = missingDependencies.filter((dependency) => !BUNDLED_DEPENDENCIES.includes(dependency));
+	if (missing.length) throw new Error(`Missing dependencies: ${missing.join(", ")}`);
+	const bytes = await createSnapshotPackage({
+		files,
+		packageInfo: {
+			name: metadata.packageName,
+			version: metadata.version,
+			peerDependencies
+		}
+	});
+	if (bytes.length > 52428800) throw new Error(`The snapshot is ${Math.ceil(bytes.length / 1024 / 1024)} MB, over the ${MAX_SNAPSHOT_BYTES / 1024 / 1024} MB limit`);
+	const hashes = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, hashOf(content)]));
+	const body = new FormData();
+	body.set("metadata", JSON.stringify({
+		...metadata,
+		hashes,
+		peerDependencies
+	}));
+	body.set("tarball", new Blob([new Uint8Array(bytes)], { type: "application/gzip" }), "snapshot.tgz");
+	const timeout = AbortSignal.timeout(UPLOAD_TIMEOUT_MS);
+	const { ok, status, _data } = await ofetch.raw(url.href, {
+		method: "POST",
+		headers: { "x-api-key": apiKey },
+		body,
+		redirect: "error",
+		signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+		ignoreResponseError: true
+	});
+	if (!ok) {
+		const upgrade = _data?.data?.upgradeUrl ? ` Upgrade at ${_data.data.upgradeUrl}.` : "";
+		throw new Error(`Kubb Studio refused the snapshot (status ${status})${_data?.message ? `: ${_data.message}` : ""}.${upgrade}`);
+	}
+	if (!_data?.snapshot) throw new Error(`Kubb Studio returned no snapshot (status ${status})`);
+	return _data.snapshot;
+}
+//#endregion
+export { IncompatibleAgentError, InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectAgent, createSnapshot, defaultStudioUrl, pairAgent };
 
 //# sourceMappingURL=index.js.map