@kubb/studio 5.3.14 → 5.3.16

package/README.md

@@ -40,32 +40,67 @@ npm install @kubb/studio
 ## Usage
 
 ```typescript
-import { createClient, createFileStorage } from '@kubb/studio'
-
-const client = createClient({
-  token: process.env.KUBB_AGENT_TOKEN!,
-  configPath: 'kubb.config.ts',
-  version: '1.0.0',
-  loadConfig: () => loadMyKubbConfig(),
-  storage: createFileStorage('./.kubb-cache'),
+import { createFileStorage, runConnection, setStorage } from '@kubb/studio'
+
+// The machine identity lives in this storage, so install it before anything pairs or connects.
+setStorage(createFileStorage('./.kubb-cache'))
+
+const outcome = await runConnection({
+  credentials: { token: process.env.KUBB_AGENT_TOKEN! },
+  clientOptions: () => ({
+    configPath: 'kubb.config.ts',
+    version: '1.0.0',
+    loadConfig: () => loadMyKubbConfig(),
+    installLogger: (hooks) => {
+      hooks.hook('studio:connected', ({ url }) => console.log(`Connected to ${url}`))
+      hooks.hook('studio:reconnecting', ({ delayMs }) => console.log(`Retrying in ${delayMs}ms`))
+      hooks.hook('studio:warn', ({ message }) => console.warn(message))
+      hooks.hook('studio:error', ({ error }) => console.error(error.message))
+    },
+  }),
+  signal: shutdown.signal,
+  // Return a new credential to reconnect with, `null` to stop, or throw to fail the run.
+  onTokenRejected: async () => null,
 })
-
-await client.connect()
 ```
 
 The runtime discovers nothing on its own: the host injects the config loader, the storage, and its
 own version. That is what lets one runtime serve a CLI running in a developer's project and a
 container running a fixed plugin set.
 
+## Hosts and the runtime
+
+Three hosts run this package: `kubb studio`, the `kubblabs/kubb-agent` Docker image, and
+`kubb studio snapshot` in CI. All three follow the steps below. The runtime owns only the
+connection: it doesn't read CI environment variables or print anything, and behaves the same in
+every host.
+
+| Step             | `kubb studio`                           | Docker agent                             | `kubb studio snapshot`                   |
+| ---------------- | --------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| Machine identity | `setStorage` under `~/.kubb`            | `setStorage` on the Nitro `kubb` mount   | `KUBB_AGENT_SECRET` from the CI identity |
+| Credentials      | stored, or `pairAgent({ type: 'cli' })` | stored, or `pairAgent({ type: 'user' })` | `createAgent` with the CI API key        |
+| Permissions      | flags and a per-project prompt          | `KUBB_AGENT_ALLOW_*`                     | flags only                               |
+| Connection       | `runConnection`                         | `runConnection`                          | `runConnection`                          |
+| Token rejected   | pair again once                         | pair again once                          | fail the run                             |
+| Output           | renders the `studio:*` hooks            | renders the `studio:*` hooks             | renders the `studio:*` hooks             |
+
+Everything the runtime has to say goes through hooks on the emitter `installLogger` receives:
+`studio:connecting`, `studio:connected`, `studio:ready`, `studio:reconnecting`,
+`studio:disconnected`, `studio:command:start`, `studio:command:end`, `studio:warn`, and
+`studio:error`. When a request is refused for a missing permission, `studio:warn` carries it as
+`permission`, and the host adds its own remedy, a CLI flag or an environment variable.
+
 ## Permissions
 
 Every permission is off by default, and each covers one trust boundary:
 
-| Option       | What it grants                                                                                 |
-| ------------ | ---------------------------------------------------------------------------------------------- |
-| `allowWrite` | Generated files are written to disk. Off means they exist only in memory and stream to Studio. |
-| `allowInput` | An OpenAPI spec sent by Studio replaces the one on disk.                                       |
-| `allowExec`  | The formatter, the linter, and `output.postGenerate` run as child processes.                   |
+| Option            | What it grants                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| `allowWrite`      | Generated files are written to disk. Off means they exist only in memory and stream to Studio. |
+| `allowInput`      | An OpenAPI spec sent by Studio replaces the one on disk.                                       |
+| `allowExec`       | The formatter, the linter, and `output.postGenerate` run as child processes.                   |
+| `allowConfigEdit` | Studio may change plugin options in `kubb.config.ts`.                                          |
+| `allowRead`       | Studio may read back the files a generation produced.                                          |
 
 ## Connection flow
 
@@ -107,9 +142,23 @@ No host starts with a token, so each one pairs over
 `POST /api/agent/token` until someone approves in the browser. Studio mints the token once and stores only its hash, so
 nothing can read it back.
 
-`startPairing` defaults to the `kubb-cli` client, which `kubb studio login` uses and any signed-in
-member can approve. A host that pairs a shared or tier-limited agent passes `clientId: 'kubb-agent'`
-and an `agentKind`, whose codes only an admin can approve.
+`pairAgent` runs that whole flow and hands each code to the host's `onCode` to show. The `type` is
+what Studio registers the machine as: `cli` is a `kubb studio` machine any signed-in member can
+approve, and `user` or `sandbox` is the Docker image, whose codes only an admin can approve. With
+`maxAttempts` above 1 it asks for a fresh code when one expires unapproved. A denial throws
+`PairingDeniedError`, an expired code `PairingExpiredError`, and an aborted `signal`
+`PairingCanceledError`.
+
+```typescript
+import { pairAgent } from '@kubb/studio'
+
+const { token, agent } = await pairAgent({
+  type: 'cli',
+  name: 'my-project',
+  hostname: os.hostname(),
+  onCode: (session) => console.log(`Approve ${session.user_code} at ${session.verification_uri}`),
+})
+```
 
 ## Asynchronous jobs
 
@@ -144,6 +193,10 @@ if (finished.status === 'canceled') throw new Error('Studio job was canceled')
 const snapshot = finished.snapshot
 ```
 
+Pass `commit` with a snapshot job, and the finished snapshot carries `changes`: the files added,
+changed, and removed since the previous snapshot of the same package on the same agent, and which
+snapshot (and commit) that was. `base` is `null` on the first one.
+
 A snapshot job packs the tarball on the agent, not on Studio. The agent `PUT`s an empty request to
 a path Studio provides, gets back a redirect to a short-lived storage URL, and uploads the tarball
 there. The storage URL never crosses the RPC socket.

package/dist/index.cjs

@@ -26,19 +26,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_protocol = require("./protocol.cjs");
-let node_util = require("node:util");
 let node_process = require("node:process");
 node_process = __toESM(node_process, 1);
 let node_child_process = require("node:child_process");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
-let _kubb_core = require("@kubb/core");
 let ofetch = require("ofetch");
 let node_crypto = require("node:crypto");
+let node_util = require("node:util");
 let unstorage = require("unstorage");
 let unstorage_drivers_fs = require("unstorage/drivers/fs");
 unstorage_drivers_fs = __toESM(unstorage_drivers_fs, 1);
+let _kubb_core = require("@kubb/core");
 let tinyexec = require("tinyexec");
 let magicast = require("magicast");
 let node_fs = require("node:fs");
@@ -602,29 +602,27 @@ async function runRegistration({ token, studioUrl, poolSize }) {
 		return true;
 	} catch (error) {
 		if (rejectedWith(error, 401)) throw new InvalidAgentTokenError(studioUrl, { cause: error });
-		console.error((0, node_util.styleText)("red", `Failed to register agent with Studio after 4 attempts`));
 		return false;
 	}
 }
 /**
 * 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 }) {
-	const url = `${studioUrl}/api/agent/sessions/${sessionId}/disconnect`;
-	const tag = slug ?? "agent";
-	const canLog = logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent;
+async function disconnect({ sessionId, token, studioUrl }) {
 	try {
-		await (0, ofetch.ofetch)(url, {
+		await (0, ofetch.ofetch)(`${studioUrl}/api/agent/sessions/${sessionId}/disconnect`, {
 			method: "POST",
 			headers: { Authorization: `Bearer ${token}` }
 		});
-		if (canLog) console.error((0, node_util.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((0, node_util.styleText)("yellow", `[${tag}] Failed to notify Studio of disconnection: ${getErrorMessage(error)}`));
+		return statusCode !== void 0 && statusCode !== 429 && statusCode >= 400 && statusCode < 500;
 	}
 }
 /**
@@ -646,7 +644,7 @@ async function disconnect({ sessionId, token, studioUrl, slug, logLevel }) {
 * const finished = await waitForJob({ studioUrl, token, id: job.id })
 * ```
 */
-async function createJob({ studioUrl, token, type, agentId, name, version, config }) {
+async function createJob({ studioUrl, token, type, agentId, name, version, commit, config }) {
 	const { job } = await (0, ofetch.ofetch)(`${studioUrl}/api/jobs`, {
 		method: "POST",
 		headers: { "x-api-key": token },
@@ -655,6 +653,7 @@ async function createJob({ studioUrl, token, type, agentId, name, version, confi
 			agentId,
 			name,
 			version,
+			commit,
 			config
 		}
 	});
@@ -725,7 +724,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
 /**
@@ -2275,15 +2274,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 } = options;
+	const { signal, retryInterval, onTokenRejected } = options;
 	if (signal?.aborted) return;
-	if (logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent) console.error((0, node_util.styleText)("dim", `Retrying connection in ${retryInterval}ms to Kubb Studio ...`));
 	const cancel = () => clearTimeout(timer);
 	const timer = setTimeout(() => {
 		signal?.removeEventListener("abort", cancel);
 		if (signal?.aborted) return;
 		new StudioSession(options).start().catch((error) => {
-			if (logLevel !== void 0 && logLevel > _kubb_core.logLevel.silent) console.error((0, node_util.styleText)("red", `Reconnect attempt to Kubb Studio failed: ${getErrorMessage(error)}`));
 			if (error instanceof InvalidAgentTokenError) {
 				onTokenRejected?.(error);
 				return;
@@ -2323,8 +2320,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(() => {});
 	}
 	/**
@@ -2367,6 +2366,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({
@@ -2402,18 +2402,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) {
@@ -2502,19 +2514,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) => {
@@ -2540,7 +2550,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();
@@ -2549,10 +2559,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({
@@ -2732,12 +2739,7 @@ var StudioSession = class {
 	async readFiles(data) {
 		const command = "readFiles";
 		await this.#hooks.callHook("studio:command:start", { command });
-		const { client } = this.#options;
-		if (!this.#canRead) {
-			await this.#warn("Ignored files: reading generated files was not granted");
-			const remedy = client?.kind === "cli" ? "--allow-read, or answer yes when kubb studio asks," : "KUBB_AGENT_ALLOW_READ=true";
-			throw new Error(`The agent was not granted permission to read generated files; set ${remedy} to allow it`);
-		}
+		if (!this.#canRead) return this.#refuse("Ignored files: reading generated files was not granted", "The agent was not granted permission to read generated files", "allowRead");
 		if (!Array.isArray(data.paths)) return this.#refuse("Ignored files: the message carried no paths", "The request carried no paths");
 		const { paths } = data;
 		if (paths.length > 50) return this.#refuse(`Ignored files: requested ${paths.length} paths, more than the 50 allowed per request`, `At most 50 paths may be requested at once`);
@@ -2764,7 +2766,8 @@ var StudioSession = class {
 * Creates the Kubb Studio client: the connection, the command loop, and the generation event
 * stream shared by the `kubb studio` CLI command and the Docker agent.
 *
-* Every permission is off by default. A host that wants more grants it explicitly.
+* Every permission is off by default. A host that wants more grants it explicitly. The machine
+* identity comes from the storage the host installed with `setStorage`, before connecting.
 *
 * @example
 * ```ts
@@ -2772,8 +2775,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) {
@@ -2783,15 +2785,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() {
@@ -2874,11 +2879,11 @@ async function runConnection({ credentials, clientOptions, onTokenRejected, sign
 }
 //#endregion
 //#region src/pair.ts
-/**
-* Identifies the CLI to Studio's device authorization endpoint. A label, not a secret: what
-* authorizes a pairing is a signed-in person approving the code in the browser.
-*/
-const CLIENT_ID = "kubb-cli";
+/** Labels, not secrets: a person approving the code in the browser is what authorizes a pairing. */
+const CLIENT_IDS = {
+	cli: "kubb-cli",
+	agent: "kubb-agent"
+};
 /**
 * Thrown when a caller aborts `startPairing` or `pollForPairingToken` through their `signal`, such
 * as a `kubb studio` shutdown mid-pairing. Distinct from a denial or an expired code, so a host can
@@ -2890,21 +2895,35 @@ var PairingCanceledError = class extends Error {
 		this.name = "PairingCanceledError";
 	}
 };
+/** Thrown when the code expired unapproved. A fresh code can still succeed. */
+var PairingExpiredError = class extends Error {
+	constructor(message = "The pairing code expired, pair again") {
+		super(message);
+		this.name = "PairingExpiredError";
+	}
+};
+/** Thrown when the pairing was denied in the browser, including by the organization's agent limit. */
+var PairingDeniedError = class extends Error {
+	constructor(message = "Pairing was denied in the browser") {
+		super(message);
+		this.name = "PairingDeniedError";
+	}
+};
 /**
 * Asks Studio for a pairing code. The machine token travels with the request and is stored against
 * the code, so approval knows which machine it is pairing: the same machine pairing twice rotates
 * one agent's token instead of creating a second agent.
 */
-async function startPairing({ studioUrl = agentDefaults.studioUrl, name, hostname, clientId = CLIENT_ID, agentKind, signal }) {
+async function startPairing({ studioUrl = agentDefaults.studioUrl, type, name, hostname, signal }) {
 	try {
 		return await (0, ofetch.ofetch)(`${studioUrl}/api/auth/device/code`, {
 			method: "POST",
 			body: {
-				client_id: clientId,
+				client_id: type === "cli" ? CLIENT_IDS.cli : CLIENT_IDS.agent,
 				name,
 				hostname,
 				machine_token: await getMachineToken(),
-				agent_kind: agentKind
+				agent_kind: type === "cli" ? void 0 : type
 			},
 			signal
 		});
@@ -2917,15 +2936,16 @@ function isPairingResult(response) {
 	return !!response && typeof response === "object" && "token" in response && typeof response.token === "string";
 }
 /**
-* Polls until the user approves or denies, honoring the server's `slow_down` back-off. A poll that
-* cannot reach Studio is warned about and retried, since the code stays valid either way.
+* Polls until the user approves or denies, honoring the server's `slow_down` back-off.
 *
 * Studio's own endpoint is used rather than the auth layer's `/device/token`, because an approved
 * Kubb pairing is worth an agent bearer token, not a user session.
 *
-* @throws when the code expires, the user denies it, or Studio returns an unexpected error.
+* @throws {PairingExpiredError} when the code expires before anyone approves it.
+* @throws {PairingDeniedError} when the pairing is denied in the browser.
+* @throws {PairingCanceledError} when `signal` aborts.
 */
-async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal }) {
+async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, session, signal, onRetry }) {
 	const deadline = Date.now() + (session.expires_in > 0 ? session.expires_in : 600) * 1e3;
 	let intervalMs = (session.interval > 0 ? session.interval : 5) * 1e3;
 	while (Date.now() < deadline) {
@@ -2945,7 +2965,7 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			});
 		} catch (error) {
 			if (signal?.aborted) throw new PairingCanceledError();
-			console.warn((0, node_util.styleText)("yellow", `Could not reach Kubb Studio while waiting for approval, retrying: ${getErrorMessage(error)}`));
+			onRetry?.(toError(error));
 			continue;
 		}
 		if (isPairingResult(response)) return response;
@@ -2955,15 +2975,36 @@ async function pollForPairingToken({ studioUrl = agentDefaults.studioUrl, sessio
 			intervalMs += 5e3;
 			continue;
 		}
-		if (response.error === "access_denied") throw new Error(response.error_description ?? "Pairing was denied in the browser");
-		if (response.error === "expired_token" || response.error === "invalid_grant") throw new Error(response.error_description ?? "The pairing code expired, pair again");
+		if (response.error === "access_denied") throw new PairingDeniedError(response.error_description);
+		if (response.error === "expired_token" || response.error === "invalid_grant") throw new PairingExpiredError(response.error_description);
 		throw new Error(response.error_description ?? `Pairing failed (${response.error})`);
 	}
-	throw new Error("The pairing code expired, pair again");
+	throw new PairingExpiredError();
+}
+/**
+* Pairs this machine with Studio: asks for a code, hands it to the host to show, and waits for approval.
+*/
+async function pairAgent({ onCode, onRetry, maxAttempts = 1, ...options }) {
+	for (let attempt = 1;; attempt++) {
+		const session = await startPairing(options);
+		await onCode(session, attempt);
+		try {
+			return await pollForPairingToken({
+				studioUrl: options.studioUrl,
+				session,
+				signal: options.signal,
+				onRetry
+			});
+		} catch (error) {
+			if (!(error instanceof PairingExpiredError) || attempt >= maxAttempts) throw error;
+		}
+	}
 }
 //#endregion
 exports.InvalidAgentTokenError = InvalidAgentTokenError;
 exports.PairingCanceledError = PairingCanceledError;
+exports.PairingDeniedError = PairingDeniedError;
+exports.PairingExpiredError = PairingExpiredError;
 exports.connectWebSocketRpc = connectWebSocketRpc;
 exports.createAgent = createAgent;
 exports.createClient = createClient;
@@ -2972,6 +3013,7 @@ exports.createJob = createJob;
 exports.defaultStudioUrl = defaultStudioUrl;
 exports.generationEventTypes = require_protocol.generationEventTypes;
 exports.machineTokenFrom = machineTokenFrom;
+exports.pairAgent = pairAgent;
 exports.pollForPairingToken = pollForPairingToken;
 exports.runConnection = runConnection;
 exports.setStorage = setStorage;