@kubb/studio 5.3.16 → 5.3.18

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.js";
-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 { 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";
-//#region src/api.d.ts
+import { Storage } from "unstorage";
+//#region src/operations/api.d.ts
 /**
  * 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
@@ -11,13 +11,20 @@ import { Config, Hookable, KubbHooks } from "@kubb/core";
 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 the previous one of the same package and agent, relative to `output.path`. */
+/** 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` for the first one. */
+  /** The snapshot these changes are measured against, `null` when there is none to compare with. */
   base: {
     id: string;
     version: string | null;
@@ -61,8 +68,10 @@ 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. */
+  /** 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}`.
@@ -91,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({
@@ -104,7 +117,7 @@ type StudioJob = {
  * const finished = await waitForJob({ studioUrl, token, id: job.id })
  * ```
  */
-export declare function createJob({ studioUrl, token, type, agentId, name, version, commit, config }: {
+export declare function createJob({ studioUrl, token, type, agentId, name, version, commit, baseId, config, instanceId, timeoutMs, signal }: {
   studioUrl: string;
   token: string;
   type: 'generation' | 'snapshot';
@@ -113,7 +126,21 @@ export declare function createJob({ studioUrl, token, type, agentId, name, versi
   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>;
+  /**
+   * The agent process to run the job on, the `instanceId` its client connected with. A CI run passes
+   * its own, so an overlapping pipeline under the same CI agent never builds its checkout.
+   */
+  instanceId?: string;
+  /**
+   * 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
@@ -123,7 +150,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;
@@ -133,6 +160,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.
@@ -167,7 +195,7 @@ export declare function createAgent({ studioUrl, token, name, machineToken }: {
   machineToken: string;
 }): Promise<StudioAgent>;
 //#endregion
-//#region src/StudioSession.d.ts
+//#region src/runtime/StudioSession.d.ts
 type StudioSessionOptions = {
   connector?: RpcConnector;
   token: string;
@@ -190,7 +218,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
@@ -199,10 +234,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`.
+   */
+  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.
    */
-  poolSize?: number;
+  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.
@@ -221,20 +262,14 @@ 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' | 'startupWarning'> & {
+//#region src/runtime/client.d.ts
+type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected' | '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.
@@ -243,12 +278,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;
 };
@@ -267,7 +302,7 @@ type Client = {
  */
 export declare function createClient({ onAuthRequired, ...options }: ClientOptions): Client;
 //#endregion
-//#region src/hooks.d.ts
+//#region src/operations/hooks.d.ts
 /**
  * Events a host emits about its Kubb Studio session, as opposed to a generation. `kubb:` stays
  * reserved for generation lifecycle.
@@ -373,14 +408,14 @@ declare global {
   }
 }
 //#endregion
-//#region src/constants.d.ts
+//#region src/operations/constants.d.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.
  */
 export declare const defaultStudioUrl = "https://kubb.studio";
 //#endregion
-//#region src/machine.d.ts
+//#region src/operations/machine.d.ts
 /**
  * Installs the storage driver the runtime persists to. Call once, before connecting.
  */
@@ -396,7 +431,7 @@ export declare function createFileStorage(base: string): Storage;
  */
 export declare function machineTokenFrom(secret: string): string;
 //#endregion
-//#region src/runConnection.d.ts
+//#region src/runtime/runConnection.d.ts
 /**
  * Why a connection ended: the host asked it to stop through its `signal`, or the host declined to
  * replace a rejected token.
@@ -464,7 +499,7 @@ export declare function runConnection<TCredentials extends {
   token: string;
 }>({ credentials, clientOptions, onTokenRejected, signal }: ConnectionOptions<TCredentials>): Promise<ConnectionOutcome>;
 //#endregion
-//#region src/pair.d.ts
+//#region src/operations/pair.d.ts
 /**
  * RFC 8628 device-authorization response from Studio's `/api/auth/device/code` endpoint.
  * Field names match the RFC; the CLI polls with `device_code` and shows `user_code` to the user.
@@ -579,7 +614,7 @@ type PairAgentOptions = StartPairingOptions & {
  */
 export declare function pairAgent({ onCode, onRetry, maxAttempts, ...options }: PairAgentOptions): Promise<PairingResult>;
 //#endregion
-//#region src/rpc.d.ts
+//#region src/operations/rpc.d.ts
 /**
  * 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.
@@ -592,5 +627,5 @@ export declare function pairAgent({ onCode, onRetry, maxAttempts, ...options }:
  */
 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 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 };
+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