@kubb/studio 5.3.14 → 5.3.16

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-import { AgentApi, AgentPermissions, ClientInfo, ConfigEdit, ConnectMessagePayload, GenerateInput, GenerateResult, GenerationEvent, GenerationEventPayloads, GenerationEventType, GenerationRun, PublishSnapshotInput, PublishSnapshotResult, RpcConnection, RpcConnector, StudioApi, generationEventTypes } from "./protocol.js";
-import { Config, Hookable, KubbHooks } from "@kubb/core";
+import { AgentApi, AgentPermissions, ConfigEdit, ConnectMessagePayload, GenerateInput, GenerateResult, GenerationEvent, GenerationEventPayloads, GenerationEventType, GenerationRun, PublishSnapshotInput, PublishSnapshotResult, RpcConnection, RpcConnector, StudioApi, generationEventTypes } from "./protocol.js";
 import { Storage } from "unstorage";
+import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/api.d.ts
 /**
  * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
@@ -15,6 +15,20 @@ export declare class InvalidAgentTokenError extends Error {
  * Status values returned by Studio's jobs API.
  */
 type StudioJobStatus = 'queued' | 'running' | 'success' | 'failed' | 'canceled';
+/** How a snapshot's files differ from the previous one of the same package and agent, relative to `output.path`. */
+type StudioSnapshotChanges = {
+  /** The snapshot these changes are measured against, `null` for the first one. */
+  base: {
+    id: string;
+    version: string | null;
+    /** The commit the base snapshot was built from, when reported. */
+    commit?: string;
+    createdAt: string;
+  } | null;
+  added: Array<string>;
+  changed: Array<string>;
+  removed: Array<string>;
+};
 /**
  * Package view returned on a successful snapshot job from Studio.
  */
@@ -47,6 +61,8 @@ type StudioSnapshot = {
    * ISO timestamp after which Studio may delete the tarball.
    */
   expiresAt: string;
+  /** What changed since the previous snapshot. Absent when Studio or the agent predates it. */
+  changes?: StudioSnapshotChanges;
 };
 /**
  * Job record from `POST /api/jobs` and `GET /api/jobs/{id}`.
@@ -88,13 +104,15 @@ type StudioJob = {
  * const finished = await waitForJob({ studioUrl, token, id: job.id })
  * ```
  */
-export declare function createJob({ studioUrl, token, type, agentId, name, version, config }: {
+export declare function createJob({ studioUrl, token, type, agentId, name, version, commit, config }: {
   studioUrl: string;
   token: string;
   type: 'generation' | 'snapshot';
   agentId: string;
   name?: string;
   version?: string;
+  /** The commit this snapshot is built from, so the next one can diff against it. */
+  commit?: string;
   config?: Record<string, unknown>;
 }): Promise<StudioJob>;
 /**
@@ -165,10 +183,6 @@ type StudioSessionOptions = {
    * The runtime's own version, reported to Studio next to the `kubb` version.
    */
   version: string;
-  /**
-   * Identifies the host to Studio, so the UI can badge a CLI connection and show the real project.
-   */
-  client?: ClientInfo;
   /**
    * What Studio may do in this project, off unless the host grants it. A sandbox session narrows
    * them further: it never writes to disk and never edits a config file, and it always generates
@@ -200,13 +214,6 @@ type StudioSessionOptions = {
    * default to.
    */
   installLogger?: (hooks: Hookable<KubbHooks>) => void | Promise<void>;
-  /**
-   * Threshold for the reconnect loop's own `console.error` lines, using the numeric constants
-   * `@kubb/core` exports as `logLevel`. Left out, those lines never print, the same silent default
-   * as an unset `installLogger` — a reconnect happens outside any one session's hooks, so it has no
-   * other way to ask a host how loud to be.
-   */
-  logLevel?: number;
   /**
    * Called when this session's background reconnect is rejected with an invalid token. Unlike
    * `ClientOptions.onAuthRequired`, this fires once per session rather than once per pool:
@@ -214,15 +221,16 @@ type StudioSessionOptions = {
    * directly by a host.
    */
   onTokenRejected?: (error: InvalidAgentTokenError) => void;
+  /**
+   * Sent as `studio:warn` once the host's logger is installed. `createClient` uses it to report a
+   * failed registration, which happens before any session has hooks to report through. Not meant
+   * to be set directly by a host, and dropped on reconnect so it is reported once.
+   */
+  startupWarning?: string;
 };
 //#endregion
 //#region src/client.d.ts
-type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected'> & {
-  /**
-   * Where the machine secret and the last Studio config are persisted. Defaults to in-memory,
-   * which gives up a stable machine identity across restarts.
-   */
-  storage?: Storage;
+type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected' | 'startupWarning'> & {
   /**
    * Called once when a live pool's token is rejected during background reconnect (401: revoked, or
    * the agent was deleted). The whole pool is already stopped by the time this fires, so a host
@@ -248,7 +256,8 @@ type Client = {
  * Creates the Kubb Studio client: the connection, the command loop, and the generation event
  * stream shared by the `kubb studio` CLI command and the Docker agent.
  *
- * Every permission is off by default. A host that wants more grants it explicitly.
+ * Every permission is off by default. A host that wants more grants it explicitly. The machine
+ * identity comes from the storage the host installed with `setStorage`, before connecting.
  *
  * @example
  * ```ts
@@ -256,7 +265,7 @@ type Client = {
  * await studio.connect()
  * ```
  */
-export declare function createClient({ storage, onAuthRequired, ...options }: ClientOptions): Client;
+export declare function createClient({ onAuthRequired, ...options }: ClientOptions): Client;
 //#endregion
 //#region src/hooks.d.ts
 /**
@@ -313,6 +322,10 @@ type StudioDisconnectedContext = {
    */
   reason: string;
 };
+type StudioReconnectingContext = {
+  /** Milliseconds until the next connection attempt. */
+  delayMs: number;
+};
 type StudioCommandStartContext = {
   /**
    * The command Studio sent, without its `studio:` prefix: `generate`, `connect` or `save`.
@@ -331,9 +344,11 @@ type StudioCommandEndContext = {
 };
 type StudioWarnContext = {
   /**
-   * What was refused or ignored, and what would change it.
+   * What was refused or ignored.
    */
   message: string;
+  /** The missing permission, if that is why, so the host can append its own remedy. */
+  permission?: keyof AgentPermissions;
 };
 type StudioErrorContext = {
   /**
@@ -349,6 +364,7 @@ declare global {
       'studio:connected': [ctx: StudioConnectedContext];
       'studio:ready': [ctx: StudioReadyContext];
       'studio:disconnected': [ctx: StudioDisconnectedContext];
+      'studio:reconnecting': [ctx: StudioReconnectingContext];
       'studio:command:start': [ctx: StudioCommandStartContext];
       'studio:command:end': [ctx: StudioCommandEndContext];
       'studio:warn': [ctx: StudioWarnContext];
@@ -485,6 +501,11 @@ type PairingResult = {
     organizationSlug?: string;
   };
 };
+/**
+ * What this machine registers as. Any member may approve `cli` (`kubb studio`); only an admin may
+ * approve `user` and `sandbox` (the Docker image). A `ci` agent never pairs.
+ */
+type PairingAgentType = 'cli' | 'user' | 'sandbox';
 /**
  * Thrown when a caller aborts `startPairing` or `pollForPairingToken` through their `signal`, such
  * as a `kubb studio` shutdown mid-pairing. Distinct from a denial or an expired code, so a host can
@@ -493,23 +514,22 @@ type PairingResult = {
 export declare class PairingCanceledError extends Error {
   constructor();
 }
+/** Thrown when the code expired unapproved. A fresh code can still succeed. */
+export declare class PairingExpiredError extends Error {
+  constructor(message?: string);
+}
+/** Thrown when the pairing was denied in the browser, including by the organization's agent limit. */
+export declare class PairingDeniedError extends Error {
+  constructor(message?: string);
+}
 type StartPairingOptions = {
   studioUrl?: string;
+  type: PairingAgentType;
   /**
    * Display name for the agent, usually the project or machine name.
    */
   name: string;
   hostname: string;
-  /**
-   * Which client is pairing. Defaults to the CLI, where any signed-in member may approve their own
-   * machine. The Docker image passes `kubb-agent`, whose codes only an admin can approve.
-   */
-  clientId?: string;
-  /**
-   * What a `kubb-agent` pairing asks to be registered as. Studio rejects the request without it,
-   * and ignores it for the CLI.
-   */
-  agentKind?: 'user' | 'sandbox';
   /**
    * Aborting this cancels the request in flight and rejects with {@link PairingCanceledError}.
    */
@@ -520,7 +540,7 @@ type StartPairingOptions = {
  * 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.
  */
-export declare function startPairing({ studioUrl, name, hostname, clientId, agentKind, signal }: StartPairingOptions): Promise<PairingSession>;
+export declare function startPairing({ studioUrl, type, name, hostname, signal }: StartPairingOptions): Promise<PairingSession>;
 type PollOptions = {
   studioUrl?: string;
   session: PairingSession;
@@ -529,17 +549,35 @@ type PollOptions = {
    * lands between polls or during the wait for the next one.
    */
   signal?: AbortSignal;
+  /** Called when a poll could not reach Studio. Polling carries on. */
+  onRetry?: (error: Error) => void;
 };
 /**
- * Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
- * cannot reach Studio is warned about and retried, since the code stays valid either way.
+ * Polls until the user approves or denies, honoring the server's `slow_down` back-off.
  *
  * Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
  * Kubb pairing is worth an agent bearer token, not a user session.
  *
- * @throws when the code expires, the user denies it, or Studio returns an unexpected error.
+ * @throws {PairingExpiredError} when the code expires before anyone approves it.
+ * @throws {PairingDeniedError} when the pairing is denied in the browser.
+ * @throws {PairingCanceledError} when `signal` aborts.
+ */
+export declare function pollForPairingToken({ studioUrl, session, signal, onRetry }: PollOptions): Promise<PairingResult>;
+type PairAgentOptions = StartPairingOptions & {
+  /** Shows the code to whoever approves it. Called again for each fresh code. */
+  onCode: (session: PairingSession, attempt: number) => void | Promise<void>;
+  /** Called when a poll could not reach Studio. Polling carries on. */
+  onRetry?: (error: Error) => void;
+  /**
+   * Codes to ask for in total when one expires unapproved. A denial or abort ends it at once.
+   * @default 1
+   */
+  maxAttempts?: number;
+};
+/**
+ * Pairs this machine with Studio: asks for a code, hands it to the host to show, and waits for approval.
  */
-export declare function pollForPairingToken({ studioUrl, session, signal }: PollOptions): Promise<PairingResult>;
+export declare function pairAgent({ onCode, onRetry, maxAttempts, ...options }: PairAgentOptions): Promise<PairingResult>;
 //#endregion
 //#region src/rpc.d.ts
 /**
@@ -554,5 +592,5 @@ export declare function pollForPairingToken({ studioUrl, session, signal }: Poll
  */
 export declare const connectWebSocketRpc: RpcConnector;
 //#endregion
-export { type AgentApi, type Client, type ClientOptions, type ConfigEdit, type ConnectMessagePayload, type ConnectionOptions, type GenerateInput, type GenerateResult, type GenerationEvent, type GenerationEventPayloads, type GenerationEventType, type GenerationRun, type PublishSnapshotInput, type PublishSnapshotResult, type RpcConnection, type RpcConnector, type StudioAgent, type StudioApi, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, generationEventTypes };
+export { type AgentApi, type Client, type ClientOptions, type ConfigEdit, type ConnectMessagePayload, type ConnectionOptions, type GenerateInput, type GenerateResult, type GenerationEvent, type GenerationEventPayloads, type GenerationEventType, type GenerationRun, type PairingAgentType, type PairingResult, type PairingSession, type PublishSnapshotInput, type PublishSnapshotResult, type RpcConnection, type RpcConnector, type StudioAgent, type StudioApi, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, type StudioSnapshotChanges, generationEventTypes };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,16 +1,16 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
 import { GENERATION_GONE_MESSAGE, generationEventTypes } from "./protocol.js";
 import { createRequire } from "node:module";
-import { promisify, styleText } from "node:util";
 import process$1 from "node:process";
 import { spawn } from "node:child_process";
 import { glob, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import path, { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, logLevel, memoryStorage } from "@kubb/core";
 import { FetchError, ofetch } from "ofetch";
 import { createHash, hash, randomBytes } from "node:crypto";
+import { promisify, styleText } from "node:util";
 import { createStorage } from "unstorage";
 import fsDriver from "unstorage/drivers/fs";
+import { Diagnostics, Hookable, cacheStorage, createKubb, fsStorage, memoryStorage } from "@kubb/core";
 import { x } from "tinyexec";
 import { builders, detectCodeFormat, generateCode, parseModule } from "magicast";
 import { existsSync } from "node:fs";
@@ -572,29 +572,27 @@ async function runRegistration({ token, studioUrl, poolSize }) {
 		return true;
 	} catch (error) {
 		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		console.error(styleText("red", `Failed to register agent with Studio after 4 attempts`));
 		return false;
 	}
 }
 /**
 * Notify Kubb Studio that this agent is disconnecting.
-* Called on process termination or server close. A failed notify is logged and swallowed: the
-* local socket is already gone, and failing teardown must not block shutdown or reconnect.
+* Called on process termination or server close. Never throws: the local socket is already gone,
+* and failing teardown must not block shutdown or reconnect.
+*
+* @returns `false` when Studio could not be reached or rate limited the call. Any other 4xx
+* counts as notified, since it means Studio already dropped the session.
 */
-async function disconnect({ sessionId, token, studioUrl, slug, logLevel: logLevel$2 }) {
-	const url = `${studioUrl}/api/agent/sessions/${sessionId}/disconnect`;
-	const tag = slug ?? "agent";
-	const canLog = logLevel$2 !== void 0 && logLevel$2 > logLevel.silent;
+async function disconnect({ sessionId, token, studioUrl }) {
 	try {
-		await ofetch(url, {
+		await ofetch(`${studioUrl}/api/agent/sessions/${sessionId}/disconnect`, {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` }
 		});
-		if (canLog) console.error(styleText("green", `[${tag}] Disconnected from Studio`));
+		return true;
 	} catch (error) {
 		const statusCode = error?.statusCode;
-		if (statusCode !== void 0 && statusCode >= 400 && statusCode < 500) return;
-		if (canLog) console.warn(styleText("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
+		return statusCode !== void 0 && statusCode !== 429 && statusCode >= 400 && statusCode < 500;
 	}
 }
 /**
@@ -616,7 +614,7 @@ async function disconnect({ sessionId, token, studioUrl, slug, logLevel: logLeve
 * const finished = await waitForJob({ studioUrl, token, id: job.id })
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, config }) {
+async function createJob({ studioUrl, token, type, agentId, name, version, commit, config }) {
 	const { job } = await ofetch(`${studioUrl}/api/jobs`, {
 		method: "POST",
 		headers: { "x-api-key": token },
@@ -625,6 +623,7 @@ async function createJob({ studioUrl, token, type, agentId, name, version, confi
 			agentId,
 			name,
 			version,
+			commit,
 			config
 		}
 	});
@@ -695,7 +694,7 @@ async function createAgent({ studioUrl, token, name, machineToken }) {
 }
 //#endregion
 //#region package.json
-var version = "5.3.14";
+var version = "5.3.16";
 //#endregion
 //#region src/hooks.ts
 /**
@@ -2245,15 +2244,13 @@ function applyStudioDefaults(options) {
 * socket, its hook emitter, or its session id alive for the length of the retry interval.
 */
 function reconnect(options) {
-	const { signal, retryInterval, onTokenRejected, logLevel: logLevel$1 } = options;
+	const { signal, retryInterval, onTokenRejected } = options;
 	if (signal?.aborted) return;
-	if (logLevel$1 !== void 0 && logLevel$1 > logLevel.silent) console.error(styleText("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
 	const cancel = () => clearTimeout(timer);
 	const timer = setTimeout(() => {
 		signal?.removeEventListener("abort", cancel);
 		if (signal?.aborted) return;
 		new StudioSession(options).start().catch((error) => {
-			if (logLevel$1 !== void 0 && logLevel$1 > logLevel.silent) console.error(styleText("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
 			if (error instanceof InvalidAgentTokenError) {
 				onTokenRejected?.(error);
 				return;
@@ -2293,8 +2290,10 @@ var StudioSession = class {
 	* host does not queue jobs before the agent session is registered.
 	*/
 	#connectAck = Promise.withResolvers();
-	constructor(options) {
+	#startupWarning;
+	constructor({ startupWarning, ...options }) {
 		this.#options = applyStudioDefaults(options);
+		this.#startupWarning = startupWarning;
 		this.#connectAck.promise.catch(() => {});
 	}
 	/**
@@ -2337,6 +2336,7 @@ var StudioSession = class {
 	async start() {
 		const { token, studioUrl, signal, heartbeatInterval, installLogger } = this.#options;
 		await installLogger?.(this.#hooks);
+		if (this.#startupWarning) await this.#warn(this.#startupWarning);
 		try {
 			await this.#hooks.callHook("studio:connecting", { url: studioUrl });
 			const session = await createAgentSession({
@@ -2372,18 +2372,30 @@ var StudioSession = class {
 			this.dispose();
 			await this.#hooks.callHook("studio:error", { error: toError(error) });
 			if (error instanceof InvalidAgentTokenError) throw error;
-			reconnect(this.#options);
+			await this.#reconnect();
 		}
 	}
-	#warn(message) {
-		return this.#hooks.callHook("studio:warn", { message });
+	/**
+	* Tells the host a retry is coming, then schedules it. The host prints the retry, since the
+	* runtime has no output of its own.
+	*/
+	async #reconnect() {
+		if (this.#options.signal?.aborted) return;
+		await this.#hooks.callHook("studio:reconnecting", { delayMs: this.#options.retryInterval });
+		reconnect(this.#options);
+	}
+	#warn(message, permission) {
+		return this.#hooks.callHook("studio:warn", {
+			message,
+			permission
+		});
 	}
 	/**
 	* Declines a request: logs why locally, then tells Studio. The two wordings differ on purpose,
 	* since the log names the request that was ignored and the error names what the caller can do.
 	*/
-	async #refuse(reason, message) {
-		await this.#warn(reason);
+	async #refuse(reason, message, permission) {
+		await this.#warn(reason, permission);
 		throw new Error(message);
 	}
 	#scheduleHeartbeat(interval) {
@@ -2472,19 +2484,17 @@ var StudioSession = class {
 	* `#disposed` keeps the close event from running this twice, and a shutdown from reconnecting.
 	*/
 	async #end({ retry }) {
-		const { studioUrl, token, logLevel } = this.#options;
+		const { studioUrl, token } = this.#options;
 		if (this.#disposed) return;
 		this.#disposed = true;
 		this.dispose();
 		await this.#hooks.callHook("studio:disconnected", { reason: retry ? "connection closed" : "shutdown" });
-		if (this.#session) await disconnect({
+		if (this.#session && !await disconnect({
 			sessionId: this.#session.sessionId,
 			studioUrl,
-			token,
-			slug: this.#session.slug,
-			logLevel
-		}).catch(() => {});
-		if (retry) reconnect(this.#options);
+			token
+		})) await this.#warn("Could not notify Kubb Studio of the disconnect");
+		if (retry) await this.#reconnect();
 	}
 	startGeneration(data) {
 		const generationStream = createGenerationStream(this.#hooks, data.jobId, { onGenerationEnd: (result) => {
@@ -2510,7 +2520,7 @@ var StudioSession = class {
 		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;
 		const command = "generate";
-		const { root, loadConfig, permissions, client } = this.#options;
+		const { root, loadConfig, permissions } = this.#options;
 		try {
 			await this.#hooks.callHook("studio:command:start", { command });
 			const config = await loadConfig();
@@ -2519,10 +2529,7 @@ var StudioSession = class {
 			const adapter = await mergeAdapter(config.adapter, patch?.adapter);
 			const inputOverride = this.#isSandbox ? patch?.input ?? "" : permissions.allowInput && patch?.input || void 0;
 			if (permissions.allowWrite && this.#isSandbox) await this.#warn("Running in a sandbox, so writing files is disabled");
-			if (patch?.input && !this.#canUseInput) {
-				const remedy = client?.kind === "cli" ? "--allowInput, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_INPUT=true";
-				await this.#warn(`Ignored the spec from Studio; set ${remedy} to generate from it`);
-			}
+			if (patch?.input && !this.#canUseInput) await this.#warn("Ignored the spec from Studio: generating from a Studio spec was not granted", "allowInput");
 			const resolvedPlugins = plugins ?? config.plugins;
 			this.#lastGeneration = void 0;
 			const diskFiles = this.#hasProjectOnDisk ? await listDisk({
@@ -2702,12 +2709,7 @@ var StudioSession = class {
 	async readFiles(data) {
 		const command = "readFiles";
 		await this.#hooks.callHook("studio:command:start", { command });
-		const { client } = this.#options;
-		if (!this.#canRead) {
-			await this.#warn("Ignored files: reading generated files was not granted");
-			const remedy = client?.kind === "cli" ? "--allow-read, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_READ=true";
-			throw new Error(`The agent was not granted permission to read generated files; set ${remedy} to allow it`);
-		}
+		if (!this.#canRead) return this.#refuse("Ignored files: reading generated files was not granted", "The agent was not granted permission to read generated files", "allowRead");
 		if (!Array.isArray(data.paths)) return this.#refuse("Ignored files: the message carried no paths", "The request carried no paths");
 		const { paths } = data;
 		if (paths.length > 50) return this.#refuse(`Ignored files: requested ${paths.length} paths, more than the 50 allowed per request`, `At most 50 paths may be requested at once`);
@@ -2734,7 +2736,8 @@ var StudioSession = class {
 * Creates the Kubb Studio client: the connection, the command loop, and the generation event
 * stream shared by the `kubb studio` CLI command and the Docker agent.
 *
-* Every permission is off by default. A host that wants more grants it explicitly.
+* Every permission is off by default. A host that wants more grants it explicitly. The machine
+* identity comes from the storage the host installed with `setStorage`, before connecting.
 *
 * @example
 * ```ts
@@ -2742,8 +2745,7 @@ var StudioSession = class {
 * await studio.connect()
 * ```
 */
-function createClient({ storage, onAuthRequired, ...options }) {
-	if (storage) setStorage(storage);
+function createClient({ onAuthRequired, ...options }) {
 	const controller = new AbortController();
 	const poolSize = options.poolSize ?? agentDefaults.poolSize;
 	function notifyAuthRequired(error) {
@@ -2753,15 +2755,18 @@ function createClient({ storage, onAuthRequired, ...options }) {
 	}
 	return {
 		async connect() {
-			await registerAgent({
+			const registered = await registerAgent({
 				token: options.token,
 				studioUrl: options.studioUrl ?? agentDefaults.studioUrl,
 				poolSize
 			});
-			await Promise.all(Array.from({ length: poolSize }, () => new StudioSession({
+			if (controller.signal.aborted) return;
+			const startupWarning = registered ? void 0 : "Could not register with Kubb Studio, continuing";
+			await Promise.all(Array.from({ length: poolSize }, (_, slot) => new StudioSession({
 				...options,
 				signal: controller.signal,
-				onTokenRejected: notifyAuthRequired
+				onTokenRejected: notifyAuthRequired,
+				startupWarning: slot === 0 ? startupWarning : void 0
 			}).start()));
 		},
 		disconnect() {
@@ -2844,11 +2849,11 @@ async function runConnection({ credentials, clientOptions, onTokenRejected, sign
 }
 //#endregion
 //#region src/pair.ts
-/**
-* Identifies the CLI to Studio's device authorization endpoint. A label, not a secret: what
-* authorizes a pairing is a signed-in person approving the code in the browser.
-*/
-const CLIENT_ID = "kubb-cli";
+/** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
+const CLIENT_IDS = {
+	cli: "kubb-cli",
+	agent: "kubb-agent"
+};
 /**
 * Thrown when a caller aborts `startPairing` or `pollForPairingToken` through their `signal`, such
 * as a `kubb studio` shutdown mid-pairing. Distinct from a denial or an expired code, so a host can
@@ -2860,21 +2865,35 @@ var PairingCanceledError = class extends Error {
 		this.name = "PairingCanceledError";
 	}
 };
+/** Thrown when the code expired unapproved. A fresh code can still succeed. */
+var PairingExpiredError = class extends Error {
+	constructor(message = "The pairing code expired, pair again") {
+		super(message);
+		this.name = "PairingExpiredError";
+	}
+};
+/** Thrown when the pairing was denied in the browser, including by the organization's agent limit. */
+var PairingDeniedError = class extends Error {
+	constructor(message = "Pairing was denied in the browser") {
+		super(message);
+		this.name = "PairingDeniedError";
+	}
+};
 /**
 * Asks Studio for a pairing code. The machine token travels with the request and is stored against
 * the code, so approval knows which machine it is pairing: the same machine pairing twice rotates
 * one agent's token instead of creating a second agent.
 */
-async function startPairing({ studioUrl = agentDefaults.studioUrl, name, hostname, clientId = CLIENT_ID, agentKind, signal }) {
+async function startPairing({ studioUrl = agentDefaults.studioUrl, type, name, hostname, signal }) {
 	try {
 		return await ofetch(`${studioUrl}/api/auth/device/code`, {
 			method: "POST",
 			body: {
-				client_id: clientId,
+				client_id: type === "cli" ? CLIENT_IDS.cli : CLIENT_IDS.agent,
 				name,
 				hostname,
 				machine_token: await getMachineToken(),
-				agent_kind: agentKind
+				agent_kind: type === "cli" ? void 0 : type
 			},
 			signal
 		});
@@ -2887,15 +2906,16 @@ function isPairingResult(response) {
 	return !!response && typeof response === "object" && "token" in response && typeof response.token === "string";
 }
 /**
-* Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
-* cannot reach Studio is warned about and retried, since the code stays valid either way.
+* Polls until the user approves or denies, honoring the server's `slow_down` back-off.
 *
 * Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
 * Kubb pairing is worth an agent bearer token, not a user session.
 *
-* @throws when the code expires, the user denies it, or Studio returns an unexpected error.
+* @throws {PairingExpiredError} when the code expires before anyone approves it.
+* @throws {PairingDeniedError} when the pairing is denied in the browser.
+* @throws {PairingCanceledError} when `signal` aborts.
 */
-async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal }) {
+async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal, onRetry }) {
 	const deadline = Date.now() + (session.expires_in > 0 ? session.expires_in : 600) * 1e3;
 	let intervalMs = (session.interval > 0 ? session.interval : 5) * 1e3;
 	while (Date.now() < deadline) {
@@ -2915,7 +2935,7 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			});
 		} catch (error) {
 			if (signal?.aborted) throw new PairingCanceledError();
-			console.warn(styleText("yellow", `Could not reach Kubb Studio while waiting for approval, retrying: ${getErrorMessage(error)}`));
+			onRetry?.(toError(error));
 			continue;
 		}
 		if (isPairingResult(response)) return response;
@@ -2925,13 +2945,32 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			intervalMs += 5e3;
 			continue;
 		}
-		if (response.error === "access_denied") throw new Error(response.error_description ?? "Pairing was denied in the browser");
-		if (response.error === "expired_token" || response.error === "invalid_grant") throw new Error(response.error_description ?? "The pairing code expired, pair again");
+		if (response.error === "access_denied") throw new PairingDeniedError(response.error_description);
+		if (response.error === "expired_token" || response.error === "invalid_grant") throw new PairingExpiredError(response.error_description);
 		throw new Error(response.error_description ?? `Pairing failed (${response.error})`);
 	}
-	throw new Error("The pairing code expired, pair again");
+	throw new PairingExpiredError();
+}
+/**
+* Pairs this machine with Studio: asks for a code, hands it to the host to show, and waits for approval.
+*/
+async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
+	for (let attempt = 1;; attempt++) {
+		const session = await startPairing(options);
+		await onCode(session, attempt);
+		try {
+			return await pollForPairingToken({
+				studioUrl: options.studioUrl,
+				session,
+				signal: options.signal,
+				onRetry
+			});
+		} catch (error) {
+			if (!(error instanceof PairingExpiredError) || attempt >= maxAttempts) throw error;
+		}
+	}
 }
 //#endregion
-export { InvalidAgentTokenError, PairingCanceledError, connectWebSocketRpc, createAgent, createClient, createFileStorage, createJob, defaultStudioUrl, generationEventTypes, machineTokenFrom, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
+export { InvalidAgentTokenError, PairingCanceledError, PairingDeniedError, PairingExpiredError, connectWebSocketRpc, createAgent, createClient, createFileStorage, createJob, defaultStudioUrl, generationEventTypes, machineTokenFrom, pairAgent, pollForPairingToken, runConnection, setStorage, startPairing, waitForJob };
 
 //# sourceMappingURL=index.js.map