@kubb/studio 5.4.0 → 5.4.2

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { t as __name } from "./rolldown-runtime-CRm0XQPb.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";
+import { Config, Hookable, KubbHooks } from "@kubb/core";
 //#region src/operations/api.d.ts
 /**
  * Thrown when Studio rejects the agent token itself (401). Retrying cannot help: the token was
@@ -231,10 +231,6 @@ type StudioSessionOptions = {
    * 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
@@ -249,13 +245,13 @@ type StudioSessionOptions = {
   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
+   * on the socket. `runConnection` 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.
+   * shutdown signal, usually `SIGINT` or `SIGTERM`.
    */
   signal?: AbortSignal;
   /**
@@ -264,51 +260,18 @@ type StudioSessionOptions = {
    * default to.
    */
   installLogger?: (hooks: Hookable<KubbHooks>) => void | Promise<void>;
-  /**
-   * 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:
-   * `createClient` wraps it into that deduped, pool-stopping callback. Not meant to be set
-   * directly by a host.
-   */
-  onTokenRejected?: (error: InvalidAgentTokenError) => void;
 };
 //#endregion
 //#region src/runtime/client.d.ts
-type ClientOptions = Omit<StudioSessionOptions, 'signal' | 'onTokenRejected' | 'reconnectAttempt'> & {
-  /**
-   * 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.
-   */
+type ClientOptions = Omit<StudioSessionOptions, 'signal'> & {
+  /** Called once when a background reconnect rejects the credential. */
   onAuthRequired?: (error: InvalidAgentTokenError) => void;
 };
 type Client = {
-  /**
-   * 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 the socket and stops reconnecting.
-   */
   disconnect: () => void;
 };
-/**
- * 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. The machine
- * identity comes from the storage the host installed with `setStorage`, before connecting.
- *
- * @example
- * ```ts
- * const studio = createClient({ token, configPath, version, loadConfig: () => loadMyConfig() })
- * await studio.connect()
- * ```
- */
+/** Compatibility facade over the shared connection loop. */
 export declare function createClient({ onAuthRequired, ...options }: ClientOptions): Client;
 //#endregion
 //#region src/operations/hooks.d.ts
@@ -441,72 +404,27 @@ export declare function createFileStorage(base: string): Storage;
 export declare function machineTokenFrom(secret: string): string;
 //#endregion
 //#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.
- */
 type ConnectionOutcome = 'shutdown' | 'stopped';
-/**
- * A rejected token, and whether it was already serving a live session when Studio rejected it.
- */
 type TokenRejection<TCredentials> = {
   error: InvalidAgentTokenError;
-  /**
-   * The credential Studio rejected, so a host can carry parts of it into the replacement.
-   */
   credentials: TCredentials;
-  /**
-   * `false` when the token was dead before a session ever opened, which is what `connect()` itself
-   * reports. `true` when a live pool's background reconnect was rejected, well after the session
-   * was up. Hosts treat the two differently: only the first has nothing to tear down.
-   */
+  /** Whether this credential already served a ready session. */
   live: boolean;
 };
 type ConnectionOptions<TCredentials extends {
   token: string;
 }> = {
-  /**
-   * The credential to open with. Only its token is read here, so a host keeps whatever else it
-   * stores alongside.
-   */
   credentials: TCredentials;
-  /**
-   * Builds the client options for one attempt. Called again for every reconnect, so a host whose
-   * options depend on which agent approved, such as the permissions it granted, re-derives them
-   * rather than reusing the ones the rejected token was opened with.
-   */
-  clientOptions: (credentials: TCredentials) => Omit<ClientOptions, 'token' | 'onAuthRequired'>;
-  /**
-   * Called when Studio rejects the token. Return the credential to reconnect with, or `null` to
-   * end the run. Throwing fails it, which is what a host does when it cannot pair again.
-   */
+  clientOptions: (credentials: TCredentials) => Omit<StudioSessionOptions, 'token' | 'signal'>;
   onTokenRejected: (rejection: TokenRejection<TCredentials>) => Promise<TCredentials | null>;
-  /**
-   * Aborting this disconnects and ends the run. Hosts wire it to their own shutdown: `SIGINT` in
-   * the CLI, Nitro's `close` hook in the Docker agent.
-   */
   signal?: AbortSignal;
+  /** Used by the client facade once startup succeeds or schedules its first retry. */
+  onStarted?: () => void;
 };
-/**
- * Keeps a host connected to Studio across token changes: it opens a client, waits until the run
- * ends or Studio rejects the token, and reconnects with whatever credential the host hands back.
- *
- * The host owns everything around that. Where credentials live, whether a rejected token may be
- * replaced, and how any of it is reported are all decisions `onTokenRejected` makes.
- *
- * @example
- * ```ts
- * const outcome = await runConnection({
- *   credentials,
- *   clientOptions: () => ({ studioUrl, configPath, version, loadConfig }),
- *   signal: shutdown.signal,
- *   onTokenRejected: ({ error, live }) => pairAgain(error, live),
- * })
- * ```
- */
+/** Runs the process's one connection loop, including retries and credential replacement. */
 export declare function runConnection<TCredentials extends {
   token: string;
-}>({ credentials, clientOptions, onTokenRejected, signal }: ConnectionOptions<TCredentials>): Promise<ConnectionOutcome>;
+}>({ credentials, clientOptions, onTokenRejected, signal, onStarted }: ConnectionOptions<TCredentials>): Promise<ConnectionOutcome>;
 //#endregion
 //#region src/operations/pair.d.ts
 /**