@kubb/studio 5.3.16 → 5.3.17

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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";
+import { Storage } from "unstorage";
 //#region src/api.d.ts
 /**
  * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
@@ -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, timeoutMs, signal }: {
   studioUrl: string;
   token: string;
   type: 'generation' | 'snapshot';
@@ -113,7 +126,16 @@ 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>;
+  /**
+   * 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 +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;
@@ -133,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.
@@ -190,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
@@ -199,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`.
+   */
+  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 +257,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'> & {
+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.
@@ -243,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;
 };
@@ -592,5 +622,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