@kubb/studio 5.3.15 → 5.3.17

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 { AGENT_INSTANCE_HEADER, AgentApi, AgentCapacity, AgentCloseCode, AgentLoad, AgentPermissions, AgentRegisterInput, AgentRegisterResponse, ConfigEdit, ConnectMessagePayload, GenerateInput, GenerateResult, GenerationEvent, GenerationEventPayloads, GenerationEventType, GenerationRun, PublishSnapshotInput, PublishSnapshotResult, RpcClose, RpcConnection, RpcConnector, StudioApi, generationEventTypes } from "./protocol.js";
 import { Config, Hookable, KubbHooks } from "@kubb/core";
 import { Storage } from "unstorage";
 //#region src/api.d.ts
@@ -11,10 +11,31 @@ import { Storage } from "unstorage";
 export declare class InvalidAgentTokenError extends Error {
   constructor(studioUrl: string, options?: ErrorOptions);
 }
+/**
+ * Thrown when Studio refuses this agent's protocol version (426). Retrying cannot help until the
+ * agent is upgraded, so hosts stop instead of reconnecting.
+ */
+export declare class IncompatibleAgentError extends Error {
+  constructor(studioUrl: string, detail?: string, options?: ErrorOptions);
+}
 /**
  * Status values returned by Studio's jobs API.
  */
 type StudioJobStatus = 'queued' | 'running' | 'success' | 'failed' | 'canceled';
+/** How a snapshot's files differ from an earlier snapshot of the same package, relative to `output.path`. */
+type StudioSnapshotChanges = {
+  /** The snapshot these changes are measured against, `null` when there is none to compare with. */
+  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 +68,10 @@ type StudioSnapshot = {
    * ISO timestamp after which Studio may delete the tarball.
    */
   expiresAt: string;
+  /** What changed since the previous snapshot on the same agent. Absent when Studio or the agent predates it. */
+  changes?: StudioSnapshotChanges;
+  /** What differs from the latest snapshot of the CI agent `baseId` names. Absent without a base. */
+  branchChanges?: StudioSnapshotChanges;
 };
 /**
  * Job record from `POST /api/jobs` and `GET /api/jobs/{id}`.
@@ -75,6 +100,10 @@ type StudioJob = {
  * 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`.
  *
+ * 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.
+ *
  * @example Snapshot job
  * ```ts
  * const job = await createJob({
@@ -88,14 +117,25 @@ 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, baseId, config, timeoutMs, signal }: {
   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;
+  /** The `id` another CI agent's runs register under, such as the base branch's; this snapshot is also compared with its latest one. */
+  baseId?: string;
   config?: Record<string, unknown>;
+  /**
+   * How long to keep retrying a busy or queue-full response before giving up, in milliseconds.
+   *
+   * @default 60000
+   */
+  timeoutMs?: number;
+  signal?: AbortSignal;
 }): Promise<StudioJob>;
 /**
  * Polls `GET /api/jobs/{id}` until the job reaches a terminal status, waiting
@@ -105,7 +145,7 @@ export declare function createJob({ studioUrl, token, type, agentId, name, versi
  * A `failed` job resolves normally. Check `job.status` and `job.error`. Throws only when the
  * deadline passes before Studio finishes.
  */
-export declare function waitForJob({ studioUrl, token, id, timeoutMs }: {
+export declare function waitForJob({ studioUrl, token, id, timeoutMs, signal }: {
   studioUrl: string;
   token: string;
   id: string;
@@ -115,6 +155,7 @@ export declare function waitForJob({ studioUrl, token, id, timeoutMs }: {
    * @default 60000
    */
   timeoutMs?: number;
+  signal?: AbortSignal;
 }): Promise<StudioJob>;
 /**
  * CI agent returned by {@link createAgent}. The token is issued only once, at creation or reuse.
@@ -165,10 +206,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
@@ -176,7 +213,14 @@ type StudioSessionOptions = {
    */
   permissions?: Partial<AgentPermissions>;
   root?: string;
+  /**
+   * Maximum reconnect backoff in milliseconds.
+   */
   retryInterval?: number;
+  /**
+   * Number of consecutive reconnect attempts that already failed.
+   */
+  reconnectAttempt?: number;
   /**
    * Milliseconds between keep-alive pings, clamped to `agentDefaults.maxHeartbeatIntervalMs`.
    * Raise it to halve the traffic and database writes a long-lived agent costs, at the price of
@@ -185,10 +229,16 @@ type StudioSessionOptions = {
    */
   heartbeatInterval?: number;
   /**
-   * Number of pool sessions this agent serves. Read by `createClient`, which opens one
-   * session per slot, and reported to Studio at registration.
+   * What this agent process can take on, reported to Studio at registration. Unset fields come from
+   * `KUBB_AGENT_MAX_CONCURRENT` and `KUBB_AGENT_MEMORY_BUDGET_MB`.
    */
-  poolSize?: number;
+  capacity?: Partial<AgentCapacity>;
+  /**
+   * Names this agent process to Studio, sent at registration and as {@link AGENT_INSTANCE_HEADER}
+   * on the socket. `createClient` sets one per process, so a reconnect is the same instance and a
+   * restart is a new one. Not meant to be set directly by a host.
+   */
+  instanceId?: string;
   /**
    * Aborting this disconnects the session and stops the reconnect loop. Hosts wire it to their own
    * shutdown: Nitro's `close` hook, or `SIGINT`/`SIGTERM` in the CLI.
@@ -200,13 +250,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:
@@ -217,16 +260,11 @@ type StudioSessionOptions = {
 };
 //#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' | 'instanceId' | 'reconnectAttempt'> & {
   /**
-   * 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
-   * only needs to get a replacement token and start a new client.
+   * Called once when the token is rejected during a background reconnect (401: revoked, or the
+   * agent was deleted). The client is already stopped by the time this fires, so a host only needs
+   * to get a replacement token and start a new client.
    *
    * Never fires for a startup rejection, which `connect()` reports by throwing, nor for an ordinary
    * session expiry or revocation, both of which reconnect on their own.
@@ -235,12 +273,12 @@ type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected'> &
 };
 type Client = {
   /**
-   * Registers with Studio and opens the session pool. Resolves once the pool is starting: the
-   * sessions keep running, and reconnect on their own, until `disconnect` is called.
+   * Registers with Studio and opens this process's one socket. Resolves once it is starting: the
+   * connection keeps running, and reconnects on its own, until `disconnect` is called.
    */
   connect: () => Promise<void>;
   /**
-   * Closes every session and stops reconnecting.
+   * Closes the socket and stops reconnecting.
    */
   disconnect: () => void;
 };
@@ -248,7 +286,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 +295,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 +352,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 +374,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 +394,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 +531,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 +544,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 +570,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 +579,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 +622,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 { AGENT_INSTANCE_HEADER, type AgentApi, type AgentCapacity, AgentCloseCode, type AgentLoad, type AgentRegisterInput, type AgentRegisterResponse, 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 RpcClose, type RpcConnection, type RpcConnector, type StudioAgent, type StudioApi, type StudioConnectedContext, type StudioJob, type StudioJobStatus, type StudioSnapshot, type StudioSnapshotChanges, generationEventTypes };
 //# sourceMappingURL=index.d.ts.map