@kubb/studio 5.3.2 → 5.3.3

package/dist/protocol.cjs

@@ -7,7 +7,8 @@ require("./rolldown-runtime-qbf5tadS.cjs");
 const commandTypes = [
 	"studio:generate",
 	"studio:connect",
-	"studio:save"
+	"studio:save",
+	"studio:snapshot"
 ];
 function createJobId() {
 	return crypto.randomUUID();

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.cjs","names":[],"sources":["../src/protocol/index.ts"],"sourcesContent":["/**\n * WebSocket message types for the agent ↔ Studio protocol. Every message name carries the side that\n * sent it, so direction reads off the name instead of the verb's tense:\n *\n * | Direction        | Type                  | Purpose                                                      |\n * | ---------------- | --------------------- | -------------------------------------------------------------|\n * | Studio → agent    | `studio:generate`     | Run a generation. No dedicated reply, the result arrives as an `agent:data` message carrying `kubb:generation:end`, so it stays ordered against the rest of that run's event stream. `studio:save`/`studio:snapshot` reply directly instead, since neither needs that ordering. |\n * | Studio → agent    | `studio:connect`      | Ask the agent to resend its `agent:connect` handshake payload. |\n * | Studio → agent    | `studio:save`         | Edit `kubb.config.ts`. Replied to with `agent:save`. |\n * | Studio → agent    | `studio:snapshot`     | Pack a prior generation's files into a tarball and upload it to a presigned URL. Replied to with `agent:snapshot`. |\n * | Studio → agent    | `studio:pong`         | Reply to an `agent:ping` heartbeat. |\n * | Studio → agent    | `studio:ready`        | Acknowledges `agent:connect`, so the session now counts as available for job dispatch. |\n * | Studio → agent    | `studio:disconnect`   | The session expired or was revoked, so the agent should not reconnect. |\n * | Studio → agent    | `studio:error`        | A failure outside a generation, e.g. a malformed command. |\n * | Agent → Studio    | `agent:connect`       | Handshake sent on open and after every `studio:connect`. |\n * | Agent → Studio    | `agent:save`          | Reply to `studio:save`. |\n * | Agent → Studio    | `agent:snapshot`      | Reply to `studio:snapshot`. The tarball itself already went out via direct upload, so this only carries the integrity hash or an error. |\n * | Agent → Studio    | `agent:data`          | One generation lifecycle event, `payload.type` a {@link KubbHook}. Carries `kubb:generation:end` (the closest thing `studio:generate` has to a reply) among many others. |\n * | Agent → Studio    | `agent:ping`          | Heartbeat, so the connection is not treated as idle. |\n * | Agent → Studio    | `agent:disconnect`    | The agent is shutting down. |\n *\n * `kubb:` stays reserved for generation lifecycle, so the {@link KubbHooks} events relayed inside an\n * `agent:data` payload keep their own names. The envelope says who sent it, the payload says what\n * happened.\n */\n\nimport type { Config } from '@kubb/core'\n\n/**\n * JSON-serializable Kubb config exchanged over the WebSocket. A live `kubb/kit` config holds\n * functions and class instances that cannot survive JSON, so both sides pass this flattened shape\n * and rebuild the real config from it.\n */\nexport type JSONKubbConfig = {\n  /**\n   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)\n   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry\n   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.\n   */\n  plugins?: Array<{\n    name: string\n    options?: object\n    disabled?: boolean\n  }>\n  /**\n   * Raw OpenAPI / Swagger spec content (YAML or JSON string).\n   * Always honored for a 'sandbox' agent. For a non-sandbox agent it is honored only when the\n   * agent opts in with `KUBB_AGENT_ALLOW_INPUT`; otherwise the spec is read from disk and this is ignored.\n   */\n  input?: string\n  /**\n   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options\n   * and re-applied through the same adapter factory, since an adapter instance's functions\n   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.\n   */\n  adapter?: object\n}\n\n/**\n * Which `defineConfig(...)` entry an edit targets, for a config file that exports an array.\n *\n * A number selects by position, a string matches the entry's `name`. Omitted targets the only\n * entry, or the first one when the file exports an array.\n */\nexport type ConfigRef = string | number\n\n/**\n * A value the agent can read out of a plugin option in `kubb.config.ts` and round-trip through JSON.\n */\nexport type OptionValue = string | number | boolean | null | Array<OptionValue> | { [key: string]: OptionValue }\n\n/**\n * One change to a plugin's options in the user's `kubb.config.ts`.\n *\n * `plugin` is the package name (`@kubb/plugin-ts`), the same identity used in {@link JSONKubbConfig}.\n * The agent applies these to the file with an AST patch, so only the targeted values are rewritten.\n *\n * Declared here rather than in `configFile.ts` because this is the wire contract, and the patcher\n * imports it from here. Type-only, so nothing pulls `magicast` into this entry point.\n */\nexport type ConfigEdit =\n  /**\n   * Write a literal option value. `path` walks nested objects, so `['enum', 'type']` targets\n   * `pluginTs({ enum: { type } })`.\n   */\n  | { operation: 'set'; config?: ConfigRef; plugin: string; path: Array<string>; value: unknown }\n  /**\n   * Drop an option so the plugin falls back to its default.\n   */\n  | { operation: 'remove'; config?: ConfigRef; plugin: string; path: Array<string> }\n  /**\n   * Add a plugin factory call and its import to the `plugins` array.\n   */\n  | { operation: 'add-plugin'; config?: ConfigRef; plugin: string; importName?: string; options?: Record<string, unknown> }\n  /**\n   * Comment the plugin call out, keeping its options in the file so enabling it again restores them.\n   */\n  | { operation: 'disable-plugin'; config?: ConfigRef; plugin: string }\n  /**\n   * Uncomment a plugin call a previous `disable-plugin` commented out.\n   */\n  | { operation: 'enable-plugin'; config?: ConfigRef; plugin: string }\n\n/**\n * A plugin factory call the agent found in the `plugins` array of a `defineConfig(...)`.\n */\nexport type PluginView = {\n  /**\n   * Local identifier of the factory in the file, e.g. `pluginTs`. This is the alias when the plugin\n   * was imported under one.\n   */\n  importName: string\n  /**\n   * Module the factory is imported from, e.g. `@kubb/plugin-ts`.\n   */\n  packageName: string\n  /**\n   * Top-level option keys, each flagged with whether the agent may write it and, when it can, the\n   * value found in the file. An option marked `literal: false` holds a function or a reference the\n   * agent will not overwrite, so Studio shows the control disabled rather than hiding it, and\n   * `value` is absent since there is nothing safe to display as the current value.\n   */\n  options: Record<string, { literal: boolean; value?: OptionValue }>\n  /**\n   * Set when the plugin call is commented out in the file. Its options stay on disk but are not\n   * readable, so `options` is empty until it is enabled again.\n   */\n  disabled?: true\n}\n\n/**\n * One `defineConfig(...)` entry. A config file that exports a single object has exactly one.\n */\nexport type ConfigView = {\n  /**\n   * The entry's `name`, when it sets one. Studio labels the config picker with it.\n   */\n  name?: string\n  /**\n   * Each plugin call in the entry, with its top-level option keys.\n   */\n  plugins: Array<PluginView>\n}\n\n/**\n * What the agent found in the user's config file, so Studio knows which controls it may offer.\n * Absent when the agent could not read the file at all.\n */\nexport type ConfigFileView =\n  | {\n      managed: true\n      /**\n       * One entry per config the file exports, in source order. Every {@link ConfigEdit} names\n       * which of these it targets through its `config` field.\n       */\n      configs: Array<ConfigView>\n    }\n  | {\n      managed: false\n      /**\n       * Why the file is outside what the agent edits, for example a default export that is not a\n       * `defineConfig(...)` call. Studio shows this and offers no property-level controls.\n       */\n      reason: string\n    }\n\n/**\n * Outcome of a single {@link ConfigEdit}, returned in a {@link ConfigSavedMessage}.\n */\nexport type ConfigEditOutcome = {\n  edit: ConfigEdit\n  applied: boolean\n  /**\n   * Why the edit was refused, absent when it was applied.\n   */\n  reason?: string\n}\n\n/**\n * Typed events sent by the Kubb agent to Studio over WebSocket.\n * Mirrors the single-context-object tuple style of {@link KubbHooks} in `kubb/kit`,\n * using JSON-serializable shapes (e.g. `sources` as a `Record` instead of `Map`,\n * `error` as `{ message; stack? }` instead of `Error`).\n */\nexport type KubbHooks = {\n  'kubb:plugin:start': [ctx: { plugin: { name: string } }]\n  'kubb:plugin:end': [ctx: { plugin: { name: string }; duration: number; success: boolean }]\n  'kubb:build:start': [ctx: { config: { name?: string }; adapter: { name: string } }]\n  'kubb:build:end': [ctx: { files: Array<{ path: string; name: string }>; outputDir: string }]\n  'kubb:files:processing:start': [ctx: { total: number }]\n  'kubb:files:processing:update': [\n    ctx: {\n      files: Array<{\n        file: string\n        processed: number\n        total: number\n        percentage: number\n      }>\n    },\n  ]\n  'kubb:files:processing:end': [ctx: { total: number }]\n  'kubb:info': [ctx: { message: string; info?: string }]\n  'kubb:success': [ctx: { message: string; info?: string }]\n  'kubb:warn': [ctx: { message: string; info?: string }]\n  'kubb:error': [ctx: { message: string; stack?: string }]\n  'kubb:debug': [ctx: { logs: Array<string>; fileName?: string }]\n  'kubb:generation:start': [ctx: { name?: string; plugins: number }]\n  'kubb:generation:end': [\n    ctx: {\n      config: Config\n      storage: Record<string, string>\n      peerDependencies: Record<string, string>\n      missingDependencies: Array<string>\n    },\n  ]\n  'kubb:generation:summary': [ctx: { duration: number; fileCount: number; failedPlugins: number; status: 'success' | 'failed' }]\n  'kubb:lifecycle:start': []\n  'kubb:lifecycle:end': []\n  'kubb:format:start': []\n  'kubb:format:end': []\n  'kubb:lint:start': []\n  'kubb:lint:end': []\n  'kubb:hooks:start': []\n  'kubb:hooks:end': []\n  'kubb:hook:start': [ctx: { id?: string; command: string; args?: Array<string> }]\n  'kubb:hook:line': [ctx: { id: string; line: string }]\n  'kubb:hook:end': [\n    ctx: {\n      id?: string\n      command: string\n      args?: Array<string>\n      success: boolean\n      error?: { message: string; stack?: string }\n    },\n  ]\n}\n\nexport type KubbHook = keyof KubbHooks\n\n/**\n * Run a generation with the given config. `payload` is the merged config Studio wants generated.\n */\nexport type StudioGenerateMessage = {\n  type: 'studio:generate'\n  jobId: string\n  payload: JSONKubbConfig\n}\n\n/**\n * Ask the agent to send a fresh `agent:connect` payload. Permissions are fixed when the host starts\n * the agent; this message only triggers another read of disk config and saved Studio state.\n */\nexport type StudioConnectMessage = {\n  type: 'studio:connect'\n  jobId?: string\n  /**\n   * Version of the Studio instance asking, which refreshes what the agent picked up when the\n   * session was created. Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Change plugin options in the user's `kubb.config.ts`. Applied only when the agent was granted\n * `allowConfigEdit`; otherwise every edit comes back refused.\n */\nexport type StudioSaveMessage = {\n  type: 'studio:save'\n  jobId: string\n  edits: Array<ConfigEdit>\n}\n\n/**\n * Anything Studio asks the agent to do. Each command is its own `type`, so a handler switches once\n * instead of reading a `type` and then a nested `command` field.\n */\nexport type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage\n\n/**\n * The command names, for a host that needs the list rather than the union.\n */\nexport const commandTypes = ['studio:generate', 'studio:connect', 'studio:save'] as const\n\nexport function createJobId(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Identifies the host running the Kubb runtime. Local to the runtime rather than part of the wire:\n * it picks which remedy a refused-input warning suggests, since the Docker agent and the CLI grant\n * `allowInput` different ways.\n */\nexport type ClientInfo = {\n  /**\n   * `cli` for a `kubb studio` connection from a developer's machine, `docker` for the agent image,\n   * `ci` for a client embedded directly in an automated pipeline (no `kubb studio` process).\n   */\n  kind: 'cli' | 'docker' | 'ci'\n}\n\n/**\n * Payload of the `agent:connect` handshake, sent when the agent attaches to a session. Carries only\n * what Studio renders, with everything about the config under one key.\n */\nexport type ConnectMessagePayload = {\n  /**\n   * Always sent, so a mismatch is visible on both sides: Studio badges the connection with these\n   * and the host prints them.\n   */\n  versions: {\n    /**\n     * The version of the `@kubb/studio` runtime the agent runs.\n     */\n    kubb: string\n    /**\n     * The version of the host itself (the `kubb.agent` package or the `kubb` CLI).\n     */\n    agent: string\n  }\n  /**\n   * The agent's project root (`KUBB_AGENT_ROOT`, or the working directory when unset). This is the\n   * workspace that generation runs against.\n   */\n  root: string\n  /**\n   * The baseline every generation starts from.\n   */\n  config: {\n    /**\n     * The config path as configured (`KUBB_AGENT_CONFIG`), relative to `root` unless absolute.\n     */\n    path: string\n    /**\n     * What the agent read out of the config file itself, so Studio can render the plugin editor\n     * against the real file. Absent when the agent could not read it, or was not granted\n     * `allowConfigEdit`.\n     */\n    file?: ConfigFileView\n    /**\n     * Plugins the config registers, with their serialized options.\n     */\n    plugins?: Array<{\n      name: string\n      options?: object\n    }>\n  }\n  permissions: AgentPermissions\n}\n\n/**\n * What an agent may do in the project it serves. Every one is off unless the host granted it, and\n * a sandbox session narrows them further.\n */\nexport type AgentPermissions = {\n  /**\n   * Whether the agent writes generated files to disk. False for a sandbox agent. For a local\n   * agent it mirrors the agent's `KUBB_AGENT_ALLOW_WRITE`.\n   */\n  allowWrite: boolean\n  /**\n   * Whether the agent will accept and generate from an OpenAPI spec supplied by Studio.\n   * Always true for a sandbox agent, otherwise it mirrors the agent's own opt-in. Studio reads\n   * this to decide whether to send `input`.\n   */\n  allowInput: boolean\n  /**\n   * Whether the agent runs the formatter, the linter, and `output.postGenerate` as child\n   * processes after a generation. Always true for the Docker agent, where the image bounds what\n   * can run. The CLI runs in the user's own project and defaults it off.\n   */\n  allowExec: boolean\n  /**\n   * Whether the agent may change plugin options in the user's `kubb.config.ts`. Separate from\n   * `allowWrite`, which covers generated output: this one edits a hand-authored source file.\n   */\n  allowConfigEdit: boolean\n}\n\n/**\n * Agent → Studio handshake. Sent when the WebSocket opens and again after a `connect` command.\n * Carries the on-disk config baseline, granted permissions, and paths Studio needs to render the editor.\n */\nexport type AgentConnectMessage = {\n  type: 'agent:connect'\n  payload: ConnectMessagePayload\n}\n\n/**\n * Reply to a `save` command: what the agent did to the file on disk.\n */\nexport type AgentSaveMessage = {\n  type: 'agent:save'\n  jobId: string\n  payload: {\n    /**\n     * Per-edit result, in the order the edits were sent.\n     */\n    outcomes: Array<ConfigEditOutcome>\n    /**\n     * Whether the file on disk changed. False when every edit was refused, and when the applied\n     * edits produced the text the file already had.\n     */\n    changed: boolean\n    /**\n     * The config file as it now stands, so Studio can re-render without a round trip. Absent when\n     * nothing was written. Named to match `config.file` in the connect payload.\n     */\n    file?: ConfigFileView\n  }\n}\n\n/**\n * Failure notice from Studio for something that breaks outside a generation, such as a malformed\n * command. The agent's own failures travel as an `agent:data` message carrying a `kubb:error`\n * payload, which keeps them ordered against the generation events around them.\n */\nexport type StudioErrorMessage = {\n  type: 'studio:error'\n  message: string\n}\n\n/**\n * Heartbeat sent by the Agent to Studio so the connection is not treated as idle.\n */\nexport type AgentPingMessage = {\n  type: 'agent:ping'\n}\n\n/**\n * Studio's reply to an `agent:ping`, confirming the connection is still alive.\n */\nexport type StudioPongMessage = {\n  type: 'studio:pong'\n}\n\n/**\n * Studio's acknowledgement that an `agent:connect` handshake was received and the session is\n * fully registered: the connection now counts as available for job dispatch. Distinct from the\n * socket merely being open, which is not yet the same thing.\n */\nexport type StudioReadyMessage = {\n  type: 'studio:ready'\n}\n\n/**\n * Disconnect message sent from Studio to Agent when the session is expired or revoked.\n * The agent should close the connection without reconnecting.\n */\nexport type StudioDisconnectMessage = {\n  type: 'studio:disconnect'\n  reason: 'expired' | 'revoked'\n}\n\n/**\n * The agent going away, so Studio marks the session offline instead of waiting out the heartbeat\n * window. The mirror of {@link StudioDisconnectMessage}.\n *\n * Only sent for a shutdown. An expired or revoked session was Studio's own decision, so echoing it\n * back says nothing new.\n */\nexport type AgentDisconnectMessage = {\n  type: 'agent:disconnect'\n  reason: 'shutdown'\n}\n\n/**\n * Payload of an `agent:data` message: a single Kubb generation event forwarded to Studio in real time.\n * Generic over the hook name so `data` is typed to that hook's context tuple.\n */\nexport type DataMessagePayload<T extends KubbHook = KubbHook> = {\n  /**\n   * The Kubb hook this event is for (e.g. `kubb:plugin:start`).\n   */\n  type: T\n  /**\n   * The hook's context tuple, matching `KubbHooks[type]`.\n   */\n  data: KubbHooks[T]\n  /**\n   * When the agent emitted the event, epoch milliseconds.\n   */\n  timestamp: number\n  /**\n   * Monotonic per-connection counter stamped in the order the agent emits events. Studio orders the\n   * event log by this, since `timestamp` has millisecond resolution and a full generation fires\n   * dozens of events per tick, and the relay can deliver them out of order.\n   */\n  seq: number\n}\n\n/**\n * Envelope for a single generation event streamed from Agent to Studio. Wraps a\n * {@link DataMessagePayload} so both sides can switch on `type: 'agent:data'`.\n */\nexport type DataMessage<T extends KubbHook = KubbHook> = {\n  type: 'agent:data'\n  jobId: string\n  payload: DataMessagePayload<T>\n}\n\n/**\n * Response returned by the Studio `/api/agent/sessions` endpoint.\n */\nexport type AgentConnectResponse = {\n  /**\n   * WebSocket URL the agent opens to reach the session, with the session token embedded.\n   */\n  wsUrl: string\n  /**\n   * When the session expires and the wsUrl stops working (ISO 8601).\n   */\n  expiresAt: string\n  /**\n   * When the session was revoked (ISO 8601), or null while it is still valid.\n   */\n  revokedAt: string | null\n  /**\n   * Opaque session token, also embedded in `wsUrl`. Store it to revoke the session later.\n   */\n  sessionId: string\n  /**\n   * Short readable identifier for this connection, used in logs (e.g. brave-otter).\n   */\n  slug: string | null\n  /**\n   * Whether this session belongs to a shared sandbox agent rather than an owned one.\n   */\n  isSandbox: boolean\n  /**\n   * The Studio instance's own version. Reported here rather than only on `studio:connect`, so the\n   * agent knows it before it announces itself and can name both sides from the first connect.\n   * Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Every message that can cross the agent WebSocket, in either direction. Narrow it with the\n * `is*Message` guards below before reading a variant's fields.\n */\nexport type AgentMessage =\n  | CommandMessage\n  | DataMessage\n  | AgentConnectMessage\n  | AgentSaveMessage\n  | AgentPingMessage\n  | AgentDisconnectMessage\n  | StudioErrorMessage\n  | StudioPongMessage\n  | StudioReadyMessage\n  | StudioDisconnectMessage\n\nexport function isCommandMessage(msg: AgentMessage): msg is CommandMessage {\n  return (commandTypes as ReadonlyArray<string>).includes(msg.type)\n}\n\n/**\n * Type guard to narrow a data message to a specific event type.\n *\n * @example\n * ```ts\n * if (isDataMessage(msg, 'kubb:plugin:start')) {\n *   // msg.payload.data is now typed as [ctx: { plugin: { name: string } }]\n *   const pluginName = msg.payload.data[0].plugin.name\n * }\n * ```\n */\nexport function isDataMessage<T extends KubbHook>(msg: AgentMessage, type?: T): msg is DataMessage<T> {\n  return msg.type === 'agent:data' && (type ? msg.payload.type === type : true)\n}\n\nexport function isStudioPongMessage(msg: AgentMessage): msg is StudioPongMessage {\n  return msg.type === 'studio:pong'\n}\n\nexport function isStudioReadyMessage(msg: AgentMessage): msg is StudioReadyMessage {\n  return msg.type === 'studio:ready'\n}\n\nexport function isDisconnectMessage(msg: AgentMessage): msg is StudioDisconnectMessage {\n  return msg.type === 'studio:disconnect'\n}\n"],"mappings":";;;;;;AAyRA,MAAa,eAAe;CAAC;CAAmB;CAAkB;AAAa;AAE/E,SAAgB,cAAsB;CACpC,OAAO,OAAO,WAAW;AAC3B;AA2QA,SAAgB,iBAAiB,KAA0C;CACzE,OAAQ,aAAuC,SAAS,IAAI,IAAI;AAClE;;;;;;;;;;;;AAaA,SAAgB,cAAkC,KAAmB,MAAiC;CACpG,OAAO,IAAI,SAAS,iBAAiB,OAAO,IAAI,QAAQ,SAAS,OAAO;AAC1E;AAEA,SAAgB,oBAAoB,KAA6C;CAC/E,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,qBAAqB,KAA8C;CACjF,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,oBAAoB,KAAmD;CACrF,OAAO,IAAI,SAAS;AACtB"}
+{"version":3,"file":"protocol.cjs","names":[],"sources":["../src/protocol/index.ts"],"sourcesContent":["/**\n * WebSocket message types for the agent ↔ Studio protocol. Every message name carries the side that\n * sent it, so direction reads off the name instead of the verb's tense:\n *\n * | Direction        | Type                  | Purpose                                                      |\n * | ---------------- | --------------------- | -------------------------------------------------------------|\n * | Studio → agent    | `studio:generate`     | Run a generation. No dedicated reply, the result arrives as an `agent:data` message carrying `kubb:generation:end`, so it stays ordered against the rest of that run's event stream. `studio:save`/`studio:snapshot` reply directly instead, since neither needs that ordering. A CI client omits `storage` from that reply on its own, since it has no UI to render the files for. |\n * | Studio → agent    | `studio:connect`      | Ask the agent to resend its `agent:connect` handshake payload. |\n * | Studio → agent    | `studio:save`         | Edit `kubb.config.ts`. Replied to with `agent:save`. |\n * | Studio → agent    | `studio:snapshot`     | Pack the session's most recent generation into a tarball and upload it to a Studio path, which redirects to storage. Carries no file contents itself. Replied to with `agent:snapshot`. |\n * | Studio → agent    | `studio:pong`         | Reply to an `agent:ping` heartbeat. |\n * | Studio → agent    | `studio:ready`        | Acknowledges `agent:connect`, so the session now counts as available for job dispatch. |\n * | Studio → agent    | `studio:disconnect`   | The session expired or was revoked, so the agent should not reconnect. |\n * | Studio → agent    | `studio:error`        | A failure outside a generation, e.g. a malformed command. |\n * | Agent → Studio    | `agent:connect`       | Handshake sent on open and after every `studio:connect`. |\n * | Agent → Studio    | `agent:save`          | Reply to `studio:save`. |\n * | Agent → Studio    | `agent:snapshot`      | Reply to `studio:snapshot`. The tarball itself already went out to storage, so this only carries the integrity hash or an error. |\n * | Agent → Studio    | `agent:data`          | One generation lifecycle event, `payload.type` a {@link KubbHook}. Carries `kubb:generation:end` (the closest thing `studio:generate` has to a reply) among many others. |\n * | Agent → Studio    | `agent:ping`          | Heartbeat, so the connection is not treated as idle. |\n * | Agent → Studio    | `agent:disconnect`    | The agent is shutting down. |\n *\n * `kubb:` stays reserved for generation lifecycle, so the {@link KubbHooks} events relayed inside an\n * `agent:data` payload keep their own names. The envelope says who sent it, the payload says what\n * happened.\n */\n\nimport type { Config } from '@kubb/core'\n\n/**\n * JSON-serializable Kubb config exchanged over the WebSocket. A live `kubb/kit` config holds\n * functions and class instances that cannot survive JSON, so both sides pass this flattened shape\n * and rebuild the real config from it.\n */\nexport type JSONKubbConfig = {\n  /**\n   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)\n   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry\n   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.\n   */\n  plugins?: Array<{\n    name: string\n    options?: object\n    disabled?: boolean\n  }>\n  /**\n   * Raw OpenAPI / Swagger spec content (YAML or JSON string).\n   * Always honored for a 'sandbox' agent. For a non-sandbox agent it is honored only when the\n   * agent opts in with `KUBB_AGENT_ALLOW_INPUT`; otherwise the spec is read from disk and this is ignored.\n   */\n  input?: string\n  /**\n   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options\n   * and re-applied through the same adapter factory, since an adapter instance's functions\n   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.\n   */\n  adapter?: object\n}\n\n/**\n * Which `defineConfig(...)` entry an edit targets, for a config file that exports an array.\n *\n * A number selects by position, a string matches the entry's `name`. Omitted targets the only\n * entry, or the first one when the file exports an array.\n */\nexport type ConfigRef = string | number\n\n/**\n * A value the agent can read out of a plugin option in `kubb.config.ts` and round-trip through JSON.\n */\nexport type OptionValue = string | number | boolean | null | Array<OptionValue> | { [key: string]: OptionValue }\n\n/**\n * One change to a plugin's options in the user's `kubb.config.ts`.\n *\n * `plugin` is the package name (`@kubb/plugin-ts`), the same identity used in {@link JSONKubbConfig}.\n * The agent applies these to the file with an AST patch, so only the targeted values are rewritten.\n *\n * Declared here rather than in `configFile.ts` because this is the wire contract, and the patcher\n * imports it from here. Type-only, so nothing pulls `magicast` into this entry point.\n */\nexport type ConfigEdit =\n  /**\n   * Write a literal option value. `path` walks nested objects, so `['enum', 'type']` targets\n   * `pluginTs({ enum: { type } })`.\n   */\n  | { operation: 'set'; config?: ConfigRef; plugin: string; path: Array<string>; value: unknown }\n  /**\n   * Drop an option so the plugin falls back to its default.\n   */\n  | { operation: 'remove'; config?: ConfigRef; plugin: string; path: Array<string> }\n  /**\n   * Add a plugin factory call and its import to the `plugins` array.\n   */\n  | { operation: 'add-plugin'; config?: ConfigRef; plugin: string; importName?: string; options?: Record<string, unknown> }\n  /**\n   * Comment the plugin call out, keeping its options in the file so enabling it again restores them.\n   */\n  | { operation: 'disable-plugin'; config?: ConfigRef; plugin: string }\n  /**\n   * Uncomment a plugin call a previous `disable-plugin` commented out.\n   */\n  | { operation: 'enable-plugin'; config?: ConfigRef; plugin: string }\n\n/**\n * A plugin factory call the agent found in the `plugins` array of a `defineConfig(...)`.\n */\nexport type PluginView = {\n  /**\n   * Local identifier of the factory in the file, e.g. `pluginTs`. This is the alias when the plugin\n   * was imported under one.\n   */\n  importName: string\n  /**\n   * Module the factory is imported from, e.g. `@kubb/plugin-ts`.\n   */\n  packageName: string\n  /**\n   * Top-level option keys, each flagged with whether the agent may write it and, when it can, the\n   * value found in the file. An option marked `literal: false` holds a function or a reference the\n   * agent will not overwrite, so Studio shows the control disabled rather than hiding it, and\n   * `value` is absent since there is nothing safe to display as the current value.\n   */\n  options: Record<string, { literal: boolean; value?: OptionValue }>\n  /**\n   * Set when the plugin call is commented out in the file. Its options stay on disk but are not\n   * readable, so `options` is empty until it is enabled again.\n   */\n  disabled?: true\n}\n\n/**\n * One `defineConfig(...)` entry. A config file that exports a single object has exactly one.\n */\nexport type ConfigView = {\n  /**\n   * The entry's `name`, when it sets one. Studio labels the config picker with it.\n   */\n  name?: string\n  /**\n   * Each plugin call in the entry, with its top-level option keys.\n   */\n  plugins: Array<PluginView>\n}\n\n/**\n * What the agent found in the user's config file, so Studio knows which controls it may offer.\n * Absent when the agent could not read the file at all.\n */\nexport type ConfigFileView =\n  | {\n      managed: true\n      /**\n       * One entry per config the file exports, in source order. Every {@link ConfigEdit} names\n       * which of these it targets through its `config` field.\n       */\n      configs: Array<ConfigView>\n    }\n  | {\n      managed: false\n      /**\n       * Why the file is outside what the agent edits, for example a default export that is not a\n       * `defineConfig(...)` call. Studio shows this and offers no property-level controls.\n       */\n      reason: string\n    }\n\n/**\n * Outcome of a single {@link ConfigEdit}, returned in a {@link ConfigSavedMessage}.\n */\nexport type ConfigEditOutcome = {\n  edit: ConfigEdit\n  applied: boolean\n  /**\n   * Why the edit was refused, absent when it was applied.\n   */\n  reason?: string\n}\n\n/**\n * Typed events sent by the Kubb agent to Studio over WebSocket.\n * Mirrors the single-context-object tuple style of {@link KubbHooks} in `kubb/kit`,\n * using JSON-serializable shapes (e.g. `sources` as a `Record` instead of `Map`,\n * `error` as `{ message; stack? }` instead of `Error`).\n */\nexport type KubbHooks = {\n  'kubb:plugin:start': [ctx: { plugin: { name: string } }]\n  'kubb:plugin:end': [ctx: { plugin: { name: string }; duration: number; success: boolean }]\n  'kubb:build:start': [ctx: { config: { name?: string }; adapter: { name: string } }]\n  'kubb:build:end': [ctx: { files: Array<{ path: string; name: string }>; outputDir: string }]\n  'kubb:files:processing:start': [ctx: { total: number }]\n  'kubb:files:processing:update': [\n    ctx: {\n      files: Array<{\n        file: string\n        processed: number\n        total: number\n        percentage: number\n      }>\n    },\n  ]\n  'kubb:files:processing:end': [ctx: { total: number }]\n  'kubb:info': [ctx: { message: string; info?: string }]\n  'kubb:success': [ctx: { message: string; info?: string }]\n  'kubb:warn': [ctx: { message: string; info?: string }]\n  'kubb:error': [ctx: { message: string; stack?: string }]\n  'kubb:debug': [ctx: { logs: Array<string>; fileName?: string }]\n  'kubb:generation:start': [ctx: { name?: string; plugins: number }]\n  'kubb:generation:end': [\n    ctx: {\n      config: Config\n      storage: Record<string, string>\n      peerDependencies: Record<string, string>\n      missingDependencies: Array<string>\n    },\n  ]\n  'kubb:generation:summary': [ctx: { duration: number; fileCount: number; failedPlugins: number; status: 'success' | 'failed' }]\n  'kubb:lifecycle:start': []\n  'kubb:lifecycle:end': []\n  'kubb:format:start': []\n  'kubb:format:end': []\n  'kubb:lint:start': []\n  'kubb:lint:end': []\n  'kubb:hooks:start': []\n  'kubb:hooks:end': []\n  'kubb:hook:start': [ctx: { id?: string; command: string; args?: Array<string> }]\n  'kubb:hook:line': [ctx: { id: string; line: string }]\n  'kubb:hook:end': [\n    ctx: {\n      id?: string\n      command: string\n      args?: Array<string>\n      success: boolean\n      error?: { message: string; stack?: string }\n    },\n  ]\n}\n\nexport type KubbHook = keyof KubbHooks\n\n/**\n * Run a generation with the given config. `payload` is the merged config Studio wants generated.\n */\nexport type StudioGenerateMessage = {\n  type: 'studio:generate'\n  jobId: string\n  payload: JSONKubbConfig\n}\n\n/**\n * Ask the agent to send a fresh `agent:connect` payload. Permissions are fixed when the host starts\n * the agent; this message only triggers another read of disk config and saved Studio state.\n */\nexport type StudioConnectMessage = {\n  type: 'studio:connect'\n  jobId?: string\n  /**\n   * Version of the Studio instance asking, which refreshes what the agent picked up when the\n   * session was created. Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Change plugin options in the user's `kubb.config.ts`. Applied only when the agent was granted\n * `allowConfigEdit`; otherwise every edit comes back refused.\n */\nexport type StudioSaveMessage = {\n  type: 'studio:save'\n  jobId: string\n  edits: Array<ConfigEdit>\n}\n\n/**\n * Ask the agent to pack a previous generation's files into an npm-installable tarball and upload\n * it to Studio directly, rather than returning the bytes over this socket. Packs the files the\n * session's own most recent `studio:generate` produced, so it only works right after that\n * generation and never carries file contents itself. Refused for a sandbox agent, since it holds\n * no generated files worth packing, and refused when no prior generation exists to pack.\n */\nexport type StudioSnapshotMessage = {\n  type: 'studio:snapshot'\n  jobId: string\n  payload: {\n    name: string\n    version: string\n    peerDependencies?: Record<string, string>\n    /**\n     * Studio path the agent `PUT`s the finished tarball to. Studio answers with a redirect to\n     * storage, so the storage URL stays out of this message.\n     */\n    uploadPath: string\n  }\n}\n\n/**\n * Anything Studio asks the agent to do. Each command is its own `type`, so a handler switches once\n * instead of reading a `type` and then a nested `command` field.\n */\nexport type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage | StudioSnapshotMessage\n\n/**\n * The command names, for a host that needs the list rather than the union.\n */\nexport const commandTypes = ['studio:generate', 'studio:connect', 'studio:save', 'studio:snapshot'] as const\n\nexport function createJobId(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Identifies the host running the Kubb runtime. Local to the runtime rather than part of the wire:\n * it picks which remedy a refused-input warning suggests, since the Docker agent and the CLI grant\n * `allowInput` different ways.\n */\nexport type ClientInfo = {\n  /**\n   * `cli` for a `kubb studio` connection from a developer's machine, `docker` for the agent image,\n   * `ci` for a client embedded directly in an automated pipeline (no `kubb studio` process).\n   */\n  kind: 'cli' | 'docker' | 'ci'\n}\n\n/**\n * Payload of the `agent:connect` handshake, sent when the agent attaches to a session. Carries only\n * what Studio renders, with everything about the config under one key.\n */\nexport type ConnectMessagePayload = {\n  /**\n   * Always sent, so a mismatch is visible on both sides: Studio badges the connection with these\n   * and the host prints them.\n   */\n  versions: {\n    /**\n     * The version of the `@kubb/studio` runtime the agent runs.\n     */\n    kubb: string\n    /**\n     * The version of the host itself (the `kubb.agent` package or the `kubb` CLI).\n     */\n    agent: string\n  }\n  /**\n   * The agent's project root (`KUBB_AGENT_ROOT`, or the working directory when unset). This is the\n   * workspace that generation runs against.\n   */\n  root: string\n  /**\n   * The baseline every generation starts from.\n   */\n  config: {\n    /**\n     * The config path as configured (`KUBB_AGENT_CONFIG`), relative to `root` unless absolute.\n     */\n    path: string\n    /**\n     * What the agent read out of the config file itself, so Studio can render the plugin editor\n     * against the real file. Absent when the agent could not read it, or was not granted\n     * `allowConfigEdit`.\n     */\n    file?: ConfigFileView\n    /**\n     * Plugins the config registers, with their serialized options.\n     */\n    plugins?: Array<{\n      name: string\n      options?: object\n    }>\n  }\n  permissions: AgentPermissions\n}\n\n/**\n * What an agent may do in the project it serves. Every one is off unless the host granted it, and\n * a sandbox session narrows them further.\n */\nexport type AgentPermissions = {\n  /**\n   * Whether the agent writes generated files to disk. False for a sandbox agent. For a local\n   * agent it mirrors the agent's `KUBB_AGENT_ALLOW_WRITE`.\n   */\n  allowWrite: boolean\n  /**\n   * Whether the agent will accept and generate from an OpenAPI spec supplied by Studio.\n   * Always true for a sandbox agent, otherwise it mirrors the agent's own opt-in. Studio reads\n   * this to decide whether to send `input`.\n   */\n  allowInput: boolean\n  /**\n   * Whether the agent runs the formatter, the linter, and `output.postGenerate` as child\n   * processes after a generation. Always true for the Docker agent, where the image bounds what\n   * can run. The CLI runs in the user's own project and defaults it off.\n   */\n  allowExec: boolean\n  /**\n   * Whether the agent may change plugin options in the user's `kubb.config.ts`. Separate from\n   * `allowWrite`, which covers generated output: this one edits a hand-authored source file.\n   */\n  allowConfigEdit: boolean\n}\n\n/**\n * Agent → Studio handshake. Sent when the WebSocket opens and again after a `connect` command.\n * Carries the on-disk config baseline, granted permissions, and paths Studio needs to render the editor.\n */\nexport type AgentConnectMessage = {\n  type: 'agent:connect'\n  payload: ConnectMessagePayload\n}\n\n/**\n * Reply to a `save` command: what the agent did to the file on disk.\n */\nexport type AgentSaveMessage = {\n  type: 'agent:save'\n  jobId: string\n  payload: {\n    /**\n     * Per-edit result, in the order the edits were sent.\n     */\n    outcomes: Array<ConfigEditOutcome>\n    /**\n     * Whether the file on disk changed. False when every edit was refused, and when the applied\n     * edits produced the text the file already had.\n     */\n    changed: boolean\n    /**\n     * The config file as it now stands, so Studio can re-render without a round trip. Absent when\n     * nothing was written. Named to match `config.file` in the connect payload.\n     */\n    file?: ConfigFileView\n  }\n}\n\n/**\n * Reply to `studio:snapshot`. The tarball already went to storage, so this only reports whether\n * the upload succeeded.\n */\nexport type AgentSnapshotMessage = {\n  type: 'agent:snapshot'\n  jobId: string\n  payload: { status: 'ok'; integrity: string } | { status: 'error'; message: string }\n}\n\n/**\n * Failure notice from Studio for something that breaks outside a generation, such as a malformed\n * command. The agent's own failures travel as an `agent:data` message carrying a `kubb:error`\n * payload, which keeps them ordered against the generation events around them.\n */\nexport type StudioErrorMessage = {\n  type: 'studio:error'\n  message: string\n}\n\n/**\n * Heartbeat sent by the Agent to Studio so the connection is not treated as idle.\n */\nexport type AgentPingMessage = {\n  type: 'agent:ping'\n}\n\n/**\n * Studio's reply to an `agent:ping`, confirming the connection is still alive.\n */\nexport type StudioPongMessage = {\n  type: 'studio:pong'\n}\n\n/**\n * Studio's acknowledgement that an `agent:connect` handshake was received and the session is\n * fully registered: the connection now counts as available for job dispatch. Distinct from the\n * socket merely being open, which is not yet the same thing.\n */\nexport type StudioReadyMessage = {\n  type: 'studio:ready'\n}\n\n/**\n * Disconnect message sent from Studio to Agent when the session is expired or revoked.\n * The agent should close the connection without reconnecting.\n */\nexport type StudioDisconnectMessage = {\n  type: 'studio:disconnect'\n  reason: 'expired' | 'revoked'\n}\n\n/**\n * The agent going away, so Studio marks the session offline instead of waiting out the heartbeat\n * window. The mirror of {@link StudioDisconnectMessage}.\n *\n * Only sent for a shutdown. An expired or revoked session was Studio's own decision, so echoing it\n * back says nothing new.\n */\nexport type AgentDisconnectMessage = {\n  type: 'agent:disconnect'\n  reason: 'shutdown'\n}\n\n/**\n * Payload of an `agent:data` message: a single Kubb generation event forwarded to Studio in real time.\n * Generic over the hook name so `data` is typed to that hook's context tuple.\n */\nexport type DataMessagePayload<T extends KubbHook = KubbHook> = {\n  /**\n   * The Kubb hook this event is for (e.g. `kubb:plugin:start`).\n   */\n  type: T\n  /**\n   * The hook's context tuple, matching `KubbHooks[type]`.\n   */\n  data: KubbHooks[T]\n  /**\n   * When the agent emitted the event, epoch milliseconds.\n   */\n  timestamp: number\n  /**\n   * Monotonic per-connection counter stamped in the order the agent emits events. Studio orders the\n   * event log by this, since `timestamp` has millisecond resolution and a full generation fires\n   * dozens of events per tick, and the relay can deliver them out of order.\n   */\n  seq: number\n}\n\n/**\n * Envelope for a single generation event streamed from Agent to Studio. Wraps a\n * {@link DataMessagePayload} so both sides can switch on `type: 'agent:data'`.\n */\nexport type DataMessage<T extends KubbHook = KubbHook> = {\n  type: 'agent:data'\n  jobId: string\n  payload: DataMessagePayload<T>\n}\n\n/**\n * Response returned by the Studio `/api/agent/sessions` endpoint.\n */\nexport type AgentConnectResponse = {\n  /**\n   * WebSocket URL the agent opens to reach the session, with the session token embedded.\n   */\n  wsUrl: string\n  /**\n   * When the session expires and the wsUrl stops working (ISO 8601).\n   */\n  expiresAt: string\n  /**\n   * When the session was revoked (ISO 8601), or null while it is still valid.\n   */\n  revokedAt: string | null\n  /**\n   * Opaque session token, also embedded in `wsUrl`. Store it to revoke the session later.\n   */\n  sessionId: string\n  /**\n   * Short readable identifier for this connection, used in logs (e.g. brave-otter).\n   */\n  slug: string | null\n  /**\n   * Whether this session belongs to a shared sandbox agent rather than an owned one.\n   */\n  isSandbox: boolean\n  /**\n   * The Studio instance's own version. Reported here rather than only on `studio:connect`, so the\n   * agent knows it before it announces itself and can name both sides from the first connect.\n   * Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Every message that can cross the agent WebSocket, in either direction. Narrow it with the\n * `is*Message` guards below before reading a variant's fields.\n */\nexport type AgentMessage =\n  | CommandMessage\n  | DataMessage\n  | AgentConnectMessage\n  | AgentSaveMessage\n  | AgentSnapshotMessage\n  | AgentPingMessage\n  | AgentDisconnectMessage\n  | StudioErrorMessage\n  | StudioPongMessage\n  | StudioReadyMessage\n  | StudioDisconnectMessage\n\nexport function isCommandMessage(msg: AgentMessage): msg is CommandMessage {\n  return (commandTypes as ReadonlyArray<string>).includes(msg.type)\n}\n\n/**\n * Type guard to narrow a data message to a specific event type.\n *\n * @example\n * ```ts\n * if (isDataMessage(msg, 'kubb:plugin:start')) {\n *   // msg.payload.data is now typed as [ctx: { plugin: { name: string } }]\n *   const pluginName = msg.payload.data[0].plugin.name\n * }\n * ```\n */\nexport function isDataMessage<T extends KubbHook>(msg: AgentMessage, type?: T): msg is DataMessage<T> {\n  return msg.type === 'agent:data' && (type ? msg.payload.type === type : true)\n}\n\nexport function isStudioPongMessage(msg: AgentMessage): msg is StudioPongMessage {\n  return msg.type === 'studio:pong'\n}\n\nexport function isStudioReadyMessage(msg: AgentMessage): msg is StudioReadyMessage {\n  return msg.type === 'studio:ready'\n}\n\nexport function isDisconnectMessage(msg: AgentMessage): msg is StudioDisconnectMessage {\n  return msg.type === 'studio:disconnect'\n}\n"],"mappings":";;;;;;AA+SA,MAAa,eAAe;CAAC;CAAmB;CAAkB;CAAe;AAAiB;AAElG,SAAgB,cAAsB;CACpC,OAAO,OAAO,WAAW;AAC3B;AAsRA,SAAgB,iBAAiB,KAA0C;CACzE,OAAQ,aAAuC,SAAS,IAAI,IAAI;AAClE;;;;;;;;;;;;AAaA,SAAgB,cAAkC,KAAmB,MAAiC;CACpG,OAAO,IAAI,SAAS,iBAAiB,OAAO,IAAI,QAAQ,SAAS,OAAO;AAC1E;AAEA,SAAgB,oBAAoB,KAA6C;CAC/E,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,qBAAqB,KAA8C;CACjF,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,oBAAoB,KAAmD;CACrF,OAAO,IAAI,SAAS;AACtB"}

package/dist/protocol.d.ts

@@ -314,15 +314,36 @@ export type StudioSaveMessage = {
   jobId: string;
   edits: Array<ConfigEdit>;
 };
+/**
+ * Ask the agent to pack a previous generation's files into an npm-installable tarball and upload
+ * it to Studio directly, rather than returning the bytes over this socket. Packs the files the
+ * session's own most recent `studio:generate` produced, so it only works right after that
+ * generation and never carries file contents itself. Refused for a sandbox agent, since it holds
+ * no generated files worth packing, and refused when no prior generation exists to pack.
+ */
+export type StudioSnapshotMessage = {
+  type: 'studio:snapshot';
+  jobId: string;
+  payload: {
+    name: string;
+    version: string;
+    peerDependencies?: Record<string, string>;
+    /**
+     * Studio path the agent `PUT`s the finished tarball to. Studio answers with a redirect to
+     * storage, so the storage URL stays out of this message.
+     */
+    uploadPath: string;
+  };
+};
 /**
  * Anything Studio asks the agent to do. Each command is its own `type`, so a handler switches once
  * instead of reading a `type` and then a nested `command` field.
  */
-export type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage;
+export type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage | StudioSnapshotMessage;
 /**
  * The command names, for a host that needs the list rather than the union.
  */
-export declare const commandTypes: readonly ["studio:generate", "studio:connect", "studio:save"];
+export declare const commandTypes: readonly ["studio:generate", "studio:connect", "studio:save", "studio:snapshot"];
 export declare function createJobId(): string;
 /**
  * Identifies the host running the Kubb runtime. Local to the runtime rather than part of the wire:
@@ -443,6 +464,21 @@ export type AgentSaveMessage = {
     file?: ConfigFileView;
   };
 };
+/**
+ * Reply to `studio:snapshot`. The tarball already went to storage, so this only reports whether
+ * the upload succeeded.
+ */
+export type AgentSnapshotMessage = {
+  type: 'agent:snapshot';
+  jobId: string;
+  payload: {
+    status: 'ok';
+    integrity: string;
+  } | {
+    status: 'error';
+    message: string;
+  };
+};
 /**
  * Failure notice from Studio for something that breaks outside a generation, such as a malformed
  * command. The agent's own failures travel as an `agent:data` message carrying a `kubb:error`
@@ -563,7 +599,7 @@ export type AgentConnectResponse = {
  * Every message that can cross the agent WebSocket, in either direction. Narrow it with the
  * `is*Message` guards below before reading a variant's fields.
  */
-export type AgentMessage = CommandMessage | DataMessage | AgentConnectMessage | AgentSaveMessage | AgentPingMessage | AgentDisconnectMessage | StudioErrorMessage | StudioPongMessage | StudioReadyMessage | StudioDisconnectMessage;
+export type AgentMessage = CommandMessage | DataMessage | AgentConnectMessage | AgentSaveMessage | AgentSnapshotMessage | AgentPingMessage | AgentDisconnectMessage | StudioErrorMessage | StudioPongMessage | StudioReadyMessage | StudioDisconnectMessage;
 export declare function isCommandMessage(msg: AgentMessage): msg is CommandMessage;
 /**
  * Type guard to narrow a data message to a specific event type.

package/dist/protocol.js

@@ -6,7 +6,8 @@ import "./rolldown-runtime-CRm0XQPb.js";
 const commandTypes = [
 	"studio:generate",
 	"studio:connect",
-	"studio:save"
+	"studio:save",
+	"studio:snapshot"
 ];
 function createJobId() {
 	return crypto.randomUUID();

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","names":[],"sources":["../src/protocol/index.ts"],"sourcesContent":["/**\n * WebSocket message types for the agent ↔ Studio protocol. Every message name carries the side that\n * sent it, so direction reads off the name instead of the verb's tense:\n *\n * | Direction        | Type                  | Purpose                                                      |\n * | ---------------- | --------------------- | -------------------------------------------------------------|\n * | Studio → agent    | `studio:generate`     | Run a generation. No dedicated reply, the result arrives as an `agent:data` message carrying `kubb:generation:end`, so it stays ordered against the rest of that run's event stream. `studio:save`/`studio:snapshot` reply directly instead, since neither needs that ordering. |\n * | Studio → agent    | `studio:connect`      | Ask the agent to resend its `agent:connect` handshake payload. |\n * | Studio → agent    | `studio:save`         | Edit `kubb.config.ts`. Replied to with `agent:save`. |\n * | Studio → agent    | `studio:snapshot`     | Pack a prior generation's files into a tarball and upload it to a presigned URL. Replied to with `agent:snapshot`. |\n * | Studio → agent    | `studio:pong`         | Reply to an `agent:ping` heartbeat. |\n * | Studio → agent    | `studio:ready`        | Acknowledges `agent:connect`, so the session now counts as available for job dispatch. |\n * | Studio → agent    | `studio:disconnect`   | The session expired or was revoked, so the agent should not reconnect. |\n * | Studio → agent    | `studio:error`        | A failure outside a generation, e.g. a malformed command. |\n * | Agent → Studio    | `agent:connect`       | Handshake sent on open and after every `studio:connect`. |\n * | Agent → Studio    | `agent:save`          | Reply to `studio:save`. |\n * | Agent → Studio    | `agent:snapshot`      | Reply to `studio:snapshot`. The tarball itself already went out via direct upload, so this only carries the integrity hash or an error. |\n * | Agent → Studio    | `agent:data`          | One generation lifecycle event, `payload.type` a {@link KubbHook}. Carries `kubb:generation:end` (the closest thing `studio:generate` has to a reply) among many others. |\n * | Agent → Studio    | `agent:ping`          | Heartbeat, so the connection is not treated as idle. |\n * | Agent → Studio    | `agent:disconnect`    | The agent is shutting down. |\n *\n * `kubb:` stays reserved for generation lifecycle, so the {@link KubbHooks} events relayed inside an\n * `agent:data` payload keep their own names. The envelope says who sent it, the payload says what\n * happened.\n */\n\nimport type { Config } from '@kubb/core'\n\n/**\n * JSON-serializable Kubb config exchanged over the WebSocket. A live `kubb/kit` config holds\n * functions and class instances that cannot survive JSON, so both sides pass this flattened shape\n * and rebuild the real config from it.\n */\nexport type JSONKubbConfig = {\n  /**\n   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)\n   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry\n   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.\n   */\n  plugins?: Array<{\n    name: string\n    options?: object\n    disabled?: boolean\n  }>\n  /**\n   * Raw OpenAPI / Swagger spec content (YAML or JSON string).\n   * Always honored for a 'sandbox' agent. For a non-sandbox agent it is honored only when the\n   * agent opts in with `KUBB_AGENT_ALLOW_INPUT`; otherwise the spec is read from disk and this is ignored.\n   */\n  input?: string\n  /**\n   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options\n   * and re-applied through the same adapter factory, since an adapter instance's functions\n   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.\n   */\n  adapter?: object\n}\n\n/**\n * Which `defineConfig(...)` entry an edit targets, for a config file that exports an array.\n *\n * A number selects by position, a string matches the entry's `name`. Omitted targets the only\n * entry, or the first one when the file exports an array.\n */\nexport type ConfigRef = string | number\n\n/**\n * A value the agent can read out of a plugin option in `kubb.config.ts` and round-trip through JSON.\n */\nexport type OptionValue = string | number | boolean | null | Array<OptionValue> | { [key: string]: OptionValue }\n\n/**\n * One change to a plugin's options in the user's `kubb.config.ts`.\n *\n * `plugin` is the package name (`@kubb/plugin-ts`), the same identity used in {@link JSONKubbConfig}.\n * The agent applies these to the file with an AST patch, so only the targeted values are rewritten.\n *\n * Declared here rather than in `configFile.ts` because this is the wire contract, and the patcher\n * imports it from here. Type-only, so nothing pulls `magicast` into this entry point.\n */\nexport type ConfigEdit =\n  /**\n   * Write a literal option value. `path` walks nested objects, so `['enum', 'type']` targets\n   * `pluginTs({ enum: { type } })`.\n   */\n  | { operation: 'set'; config?: ConfigRef; plugin: string; path: Array<string>; value: unknown }\n  /**\n   * Drop an option so the plugin falls back to its default.\n   */\n  | { operation: 'remove'; config?: ConfigRef; plugin: string; path: Array<string> }\n  /**\n   * Add a plugin factory call and its import to the `plugins` array.\n   */\n  | { operation: 'add-plugin'; config?: ConfigRef; plugin: string; importName?: string; options?: Record<string, unknown> }\n  /**\n   * Comment the plugin call out, keeping its options in the file so enabling it again restores them.\n   */\n  | { operation: 'disable-plugin'; config?: ConfigRef; plugin: string }\n  /**\n   * Uncomment a plugin call a previous `disable-plugin` commented out.\n   */\n  | { operation: 'enable-plugin'; config?: ConfigRef; plugin: string }\n\n/**\n * A plugin factory call the agent found in the `plugins` array of a `defineConfig(...)`.\n */\nexport type PluginView = {\n  /**\n   * Local identifier of the factory in the file, e.g. `pluginTs`. This is the alias when the plugin\n   * was imported under one.\n   */\n  importName: string\n  /**\n   * Module the factory is imported from, e.g. `@kubb/plugin-ts`.\n   */\n  packageName: string\n  /**\n   * Top-level option keys, each flagged with whether the agent may write it and, when it can, the\n   * value found in the file. An option marked `literal: false` holds a function or a reference the\n   * agent will not overwrite, so Studio shows the control disabled rather than hiding it, and\n   * `value` is absent since there is nothing safe to display as the current value.\n   */\n  options: Record<string, { literal: boolean; value?: OptionValue }>\n  /**\n   * Set when the plugin call is commented out in the file. Its options stay on disk but are not\n   * readable, so `options` is empty until it is enabled again.\n   */\n  disabled?: true\n}\n\n/**\n * One `defineConfig(...)` entry. A config file that exports a single object has exactly one.\n */\nexport type ConfigView = {\n  /**\n   * The entry's `name`, when it sets one. Studio labels the config picker with it.\n   */\n  name?: string\n  /**\n   * Each plugin call in the entry, with its top-level option keys.\n   */\n  plugins: Array<PluginView>\n}\n\n/**\n * What the agent found in the user's config file, so Studio knows which controls it may offer.\n * Absent when the agent could not read the file at all.\n */\nexport type ConfigFileView =\n  | {\n      managed: true\n      /**\n       * One entry per config the file exports, in source order. Every {@link ConfigEdit} names\n       * which of these it targets through its `config` field.\n       */\n      configs: Array<ConfigView>\n    }\n  | {\n      managed: false\n      /**\n       * Why the file is outside what the agent edits, for example a default export that is not a\n       * `defineConfig(...)` call. Studio shows this and offers no property-level controls.\n       */\n      reason: string\n    }\n\n/**\n * Outcome of a single {@link ConfigEdit}, returned in a {@link ConfigSavedMessage}.\n */\nexport type ConfigEditOutcome = {\n  edit: ConfigEdit\n  applied: boolean\n  /**\n   * Why the edit was refused, absent when it was applied.\n   */\n  reason?: string\n}\n\n/**\n * Typed events sent by the Kubb agent to Studio over WebSocket.\n * Mirrors the single-context-object tuple style of {@link KubbHooks} in `kubb/kit`,\n * using JSON-serializable shapes (e.g. `sources` as a `Record` instead of `Map`,\n * `error` as `{ message; stack? }` instead of `Error`).\n */\nexport type KubbHooks = {\n  'kubb:plugin:start': [ctx: { plugin: { name: string } }]\n  'kubb:plugin:end': [ctx: { plugin: { name: string }; duration: number; success: boolean }]\n  'kubb:build:start': [ctx: { config: { name?: string }; adapter: { name: string } }]\n  'kubb:build:end': [ctx: { files: Array<{ path: string; name: string }>; outputDir: string }]\n  'kubb:files:processing:start': [ctx: { total: number }]\n  'kubb:files:processing:update': [\n    ctx: {\n      files: Array<{\n        file: string\n        processed: number\n        total: number\n        percentage: number\n      }>\n    },\n  ]\n  'kubb:files:processing:end': [ctx: { total: number }]\n  'kubb:info': [ctx: { message: string; info?: string }]\n  'kubb:success': [ctx: { message: string; info?: string }]\n  'kubb:warn': [ctx: { message: string; info?: string }]\n  'kubb:error': [ctx: { message: string; stack?: string }]\n  'kubb:debug': [ctx: { logs: Array<string>; fileName?: string }]\n  'kubb:generation:start': [ctx: { name?: string; plugins: number }]\n  'kubb:generation:end': [\n    ctx: {\n      config: Config\n      storage: Record<string, string>\n      peerDependencies: Record<string, string>\n      missingDependencies: Array<string>\n    },\n  ]\n  'kubb:generation:summary': [ctx: { duration: number; fileCount: number; failedPlugins: number; status: 'success' | 'failed' }]\n  'kubb:lifecycle:start': []\n  'kubb:lifecycle:end': []\n  'kubb:format:start': []\n  'kubb:format:end': []\n  'kubb:lint:start': []\n  'kubb:lint:end': []\n  'kubb:hooks:start': []\n  'kubb:hooks:end': []\n  'kubb:hook:start': [ctx: { id?: string; command: string; args?: Array<string> }]\n  'kubb:hook:line': [ctx: { id: string; line: string }]\n  'kubb:hook:end': [\n    ctx: {\n      id?: string\n      command: string\n      args?: Array<string>\n      success: boolean\n      error?: { message: string; stack?: string }\n    },\n  ]\n}\n\nexport type KubbHook = keyof KubbHooks\n\n/**\n * Run a generation with the given config. `payload` is the merged config Studio wants generated.\n */\nexport type StudioGenerateMessage = {\n  type: 'studio:generate'\n  jobId: string\n  payload: JSONKubbConfig\n}\n\n/**\n * Ask the agent to send a fresh `agent:connect` payload. Permissions are fixed when the host starts\n * the agent; this message only triggers another read of disk config and saved Studio state.\n */\nexport type StudioConnectMessage = {\n  type: 'studio:connect'\n  jobId?: string\n  /**\n   * Version of the Studio instance asking, which refreshes what the agent picked up when the\n   * session was created. Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Change plugin options in the user's `kubb.config.ts`. Applied only when the agent was granted\n * `allowConfigEdit`; otherwise every edit comes back refused.\n */\nexport type StudioSaveMessage = {\n  type: 'studio:save'\n  jobId: string\n  edits: Array<ConfigEdit>\n}\n\n/**\n * Anything Studio asks the agent to do. Each command is its own `type`, so a handler switches once\n * instead of reading a `type` and then a nested `command` field.\n */\nexport type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage\n\n/**\n * The command names, for a host that needs the list rather than the union.\n */\nexport const commandTypes = ['studio:generate', 'studio:connect', 'studio:save'] as const\n\nexport function createJobId(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Identifies the host running the Kubb runtime. Local to the runtime rather than part of the wire:\n * it picks which remedy a refused-input warning suggests, since the Docker agent and the CLI grant\n * `allowInput` different ways.\n */\nexport type ClientInfo = {\n  /**\n   * `cli` for a `kubb studio` connection from a developer's machine, `docker` for the agent image,\n   * `ci` for a client embedded directly in an automated pipeline (no `kubb studio` process).\n   */\n  kind: 'cli' | 'docker' | 'ci'\n}\n\n/**\n * Payload of the `agent:connect` handshake, sent when the agent attaches to a session. Carries only\n * what Studio renders, with everything about the config under one key.\n */\nexport type ConnectMessagePayload = {\n  /**\n   * Always sent, so a mismatch is visible on both sides: Studio badges the connection with these\n   * and the host prints them.\n   */\n  versions: {\n    /**\n     * The version of the `@kubb/studio` runtime the agent runs.\n     */\n    kubb: string\n    /**\n     * The version of the host itself (the `kubb.agent` package or the `kubb` CLI).\n     */\n    agent: string\n  }\n  /**\n   * The agent's project root (`KUBB_AGENT_ROOT`, or the working directory when unset). This is the\n   * workspace that generation runs against.\n   */\n  root: string\n  /**\n   * The baseline every generation starts from.\n   */\n  config: {\n    /**\n     * The config path as configured (`KUBB_AGENT_CONFIG`), relative to `root` unless absolute.\n     */\n    path: string\n    /**\n     * What the agent read out of the config file itself, so Studio can render the plugin editor\n     * against the real file. Absent when the agent could not read it, or was not granted\n     * `allowConfigEdit`.\n     */\n    file?: ConfigFileView\n    /**\n     * Plugins the config registers, with their serialized options.\n     */\n    plugins?: Array<{\n      name: string\n      options?: object\n    }>\n  }\n  permissions: AgentPermissions\n}\n\n/**\n * What an agent may do in the project it serves. Every one is off unless the host granted it, and\n * a sandbox session narrows them further.\n */\nexport type AgentPermissions = {\n  /**\n   * Whether the agent writes generated files to disk. False for a sandbox agent. For a local\n   * agent it mirrors the agent's `KUBB_AGENT_ALLOW_WRITE`.\n   */\n  allowWrite: boolean\n  /**\n   * Whether the agent will accept and generate from an OpenAPI spec supplied by Studio.\n   * Always true for a sandbox agent, otherwise it mirrors the agent's own opt-in. Studio reads\n   * this to decide whether to send `input`.\n   */\n  allowInput: boolean\n  /**\n   * Whether the agent runs the formatter, the linter, and `output.postGenerate` as child\n   * processes after a generation. Always true for the Docker agent, where the image bounds what\n   * can run. The CLI runs in the user's own project and defaults it off.\n   */\n  allowExec: boolean\n  /**\n   * Whether the agent may change plugin options in the user's `kubb.config.ts`. Separate from\n   * `allowWrite`, which covers generated output: this one edits a hand-authored source file.\n   */\n  allowConfigEdit: boolean\n}\n\n/**\n * Agent → Studio handshake. Sent when the WebSocket opens and again after a `connect` command.\n * Carries the on-disk config baseline, granted permissions, and paths Studio needs to render the editor.\n */\nexport type AgentConnectMessage = {\n  type: 'agent:connect'\n  payload: ConnectMessagePayload\n}\n\n/**\n * Reply to a `save` command: what the agent did to the file on disk.\n */\nexport type AgentSaveMessage = {\n  type: 'agent:save'\n  jobId: string\n  payload: {\n    /**\n     * Per-edit result, in the order the edits were sent.\n     */\n    outcomes: Array<ConfigEditOutcome>\n    /**\n     * Whether the file on disk changed. False when every edit was refused, and when the applied\n     * edits produced the text the file already had.\n     */\n    changed: boolean\n    /**\n     * The config file as it now stands, so Studio can re-render without a round trip. Absent when\n     * nothing was written. Named to match `config.file` in the connect payload.\n     */\n    file?: ConfigFileView\n  }\n}\n\n/**\n * Failure notice from Studio for something that breaks outside a generation, such as a malformed\n * command. The agent's own failures travel as an `agent:data` message carrying a `kubb:error`\n * payload, which keeps them ordered against the generation events around them.\n */\nexport type StudioErrorMessage = {\n  type: 'studio:error'\n  message: string\n}\n\n/**\n * Heartbeat sent by the Agent to Studio so the connection is not treated as idle.\n */\nexport type AgentPingMessage = {\n  type: 'agent:ping'\n}\n\n/**\n * Studio's reply to an `agent:ping`, confirming the connection is still alive.\n */\nexport type StudioPongMessage = {\n  type: 'studio:pong'\n}\n\n/**\n * Studio's acknowledgement that an `agent:connect` handshake was received and the session is\n * fully registered: the connection now counts as available for job dispatch. Distinct from the\n * socket merely being open, which is not yet the same thing.\n */\nexport type StudioReadyMessage = {\n  type: 'studio:ready'\n}\n\n/**\n * Disconnect message sent from Studio to Agent when the session is expired or revoked.\n * The agent should close the connection without reconnecting.\n */\nexport type StudioDisconnectMessage = {\n  type: 'studio:disconnect'\n  reason: 'expired' | 'revoked'\n}\n\n/**\n * The agent going away, so Studio marks the session offline instead of waiting out the heartbeat\n * window. The mirror of {@link StudioDisconnectMessage}.\n *\n * Only sent for a shutdown. An expired or revoked session was Studio's own decision, so echoing it\n * back says nothing new.\n */\nexport type AgentDisconnectMessage = {\n  type: 'agent:disconnect'\n  reason: 'shutdown'\n}\n\n/**\n * Payload of an `agent:data` message: a single Kubb generation event forwarded to Studio in real time.\n * Generic over the hook name so `data` is typed to that hook's context tuple.\n */\nexport type DataMessagePayload<T extends KubbHook = KubbHook> = {\n  /**\n   * The Kubb hook this event is for (e.g. `kubb:plugin:start`).\n   */\n  type: T\n  /**\n   * The hook's context tuple, matching `KubbHooks[type]`.\n   */\n  data: KubbHooks[T]\n  /**\n   * When the agent emitted the event, epoch milliseconds.\n   */\n  timestamp: number\n  /**\n   * Monotonic per-connection counter stamped in the order the agent emits events. Studio orders the\n   * event log by this, since `timestamp` has millisecond resolution and a full generation fires\n   * dozens of events per tick, and the relay can deliver them out of order.\n   */\n  seq: number\n}\n\n/**\n * Envelope for a single generation event streamed from Agent to Studio. Wraps a\n * {@link DataMessagePayload} so both sides can switch on `type: 'agent:data'`.\n */\nexport type DataMessage<T extends KubbHook = KubbHook> = {\n  type: 'agent:data'\n  jobId: string\n  payload: DataMessagePayload<T>\n}\n\n/**\n * Response returned by the Studio `/api/agent/sessions` endpoint.\n */\nexport type AgentConnectResponse = {\n  /**\n   * WebSocket URL the agent opens to reach the session, with the session token embedded.\n   */\n  wsUrl: string\n  /**\n   * When the session expires and the wsUrl stops working (ISO 8601).\n   */\n  expiresAt: string\n  /**\n   * When the session was revoked (ISO 8601), or null while it is still valid.\n   */\n  revokedAt: string | null\n  /**\n   * Opaque session token, also embedded in `wsUrl`. Store it to revoke the session later.\n   */\n  sessionId: string\n  /**\n   * Short readable identifier for this connection, used in logs (e.g. brave-otter).\n   */\n  slug: string | null\n  /**\n   * Whether this session belongs to a shared sandbox agent rather than an owned one.\n   */\n  isSandbox: boolean\n  /**\n   * The Studio instance's own version. Reported here rather than only on `studio:connect`, so the\n   * agent knows it before it announces itself and can name both sides from the first connect.\n   * Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Every message that can cross the agent WebSocket, in either direction. Narrow it with the\n * `is*Message` guards below before reading a variant's fields.\n */\nexport type AgentMessage =\n  | CommandMessage\n  | DataMessage\n  | AgentConnectMessage\n  | AgentSaveMessage\n  | AgentPingMessage\n  | AgentDisconnectMessage\n  | StudioErrorMessage\n  | StudioPongMessage\n  | StudioReadyMessage\n  | StudioDisconnectMessage\n\nexport function isCommandMessage(msg: AgentMessage): msg is CommandMessage {\n  return (commandTypes as ReadonlyArray<string>).includes(msg.type)\n}\n\n/**\n * Type guard to narrow a data message to a specific event type.\n *\n * @example\n * ```ts\n * if (isDataMessage(msg, 'kubb:plugin:start')) {\n *   // msg.payload.data is now typed as [ctx: { plugin: { name: string } }]\n *   const pluginName = msg.payload.data[0].plugin.name\n * }\n * ```\n */\nexport function isDataMessage<T extends KubbHook>(msg: AgentMessage, type?: T): msg is DataMessage<T> {\n  return msg.type === 'agent:data' && (type ? msg.payload.type === type : true)\n}\n\nexport function isStudioPongMessage(msg: AgentMessage): msg is StudioPongMessage {\n  return msg.type === 'studio:pong'\n}\n\nexport function isStudioReadyMessage(msg: AgentMessage): msg is StudioReadyMessage {\n  return msg.type === 'studio:ready'\n}\n\nexport function isDisconnectMessage(msg: AgentMessage): msg is StudioDisconnectMessage {\n  return msg.type === 'studio:disconnect'\n}\n"],"mappings":";;;;;AAyRA,MAAa,eAAe;CAAC;CAAmB;CAAkB;AAAa;AAE/E,SAAgB,cAAsB;CACpC,OAAO,OAAO,WAAW;AAC3B;AA2QA,SAAgB,iBAAiB,KAA0C;CACzE,OAAQ,aAAuC,SAAS,IAAI,IAAI;AAClE;;;;;;;;;;;;AAaA,SAAgB,cAAkC,KAAmB,MAAiC;CACpG,OAAO,IAAI,SAAS,iBAAiB,OAAO,IAAI,QAAQ,SAAS,OAAO;AAC1E;AAEA,SAAgB,oBAAoB,KAA6C;CAC/E,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,qBAAqB,KAA8C;CACjF,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,oBAAoB,KAAmD;CACrF,OAAO,IAAI,SAAS;AACtB"}
+{"version":3,"file":"protocol.js","names":[],"sources":["../src/protocol/index.ts"],"sourcesContent":["/**\n * WebSocket message types for the agent ↔ Studio protocol. Every message name carries the side that\n * sent it, so direction reads off the name instead of the verb's tense:\n *\n * | Direction        | Type                  | Purpose                                                      |\n * | ---------------- | --------------------- | -------------------------------------------------------------|\n * | Studio → agent    | `studio:generate`     | Run a generation. No dedicated reply, the result arrives as an `agent:data` message carrying `kubb:generation:end`, so it stays ordered against the rest of that run's event stream. `studio:save`/`studio:snapshot` reply directly instead, since neither needs that ordering. A CI client omits `storage` from that reply on its own, since it has no UI to render the files for. |\n * | Studio → agent    | `studio:connect`      | Ask the agent to resend its `agent:connect` handshake payload. |\n * | Studio → agent    | `studio:save`         | Edit `kubb.config.ts`. Replied to with `agent:save`. |\n * | Studio → agent    | `studio:snapshot`     | Pack the session's most recent generation into a tarball and upload it to a Studio path, which redirects to storage. Carries no file contents itself. Replied to with `agent:snapshot`. |\n * | Studio → agent    | `studio:pong`         | Reply to an `agent:ping` heartbeat. |\n * | Studio → agent    | `studio:ready`        | Acknowledges `agent:connect`, so the session now counts as available for job dispatch. |\n * | Studio → agent    | `studio:disconnect`   | The session expired or was revoked, so the agent should not reconnect. |\n * | Studio → agent    | `studio:error`        | A failure outside a generation, e.g. a malformed command. |\n * | Agent → Studio    | `agent:connect`       | Handshake sent on open and after every `studio:connect`. |\n * | Agent → Studio    | `agent:save`          | Reply to `studio:save`. |\n * | Agent → Studio    | `agent:snapshot`      | Reply to `studio:snapshot`. The tarball itself already went out to storage, so this only carries the integrity hash or an error. |\n * | Agent → Studio    | `agent:data`          | One generation lifecycle event, `payload.type` a {@link KubbHook}. Carries `kubb:generation:end` (the closest thing `studio:generate` has to a reply) among many others. |\n * | Agent → Studio    | `agent:ping`          | Heartbeat, so the connection is not treated as idle. |\n * | Agent → Studio    | `agent:disconnect`    | The agent is shutting down. |\n *\n * `kubb:` stays reserved for generation lifecycle, so the {@link KubbHooks} events relayed inside an\n * `agent:data` payload keep their own names. The envelope says who sent it, the payload says what\n * happened.\n */\n\nimport type { Config } from '@kubb/core'\n\n/**\n * JSON-serializable Kubb config exchanged over the WebSocket. A live `kubb/kit` config holds\n * functions and class instances that cannot survive JSON, so both sides pass this flattened shape\n * and rebuild the real config from it.\n */\nexport type JSONKubbConfig = {\n  /**\n   * Plugins with their serialized options. `name` is the package name (e.g. `@kubb/plugin-ts`)\n   * and `options` is an opaque blob the agent forwards unchanged to the plugin factory. An entry\n   * with `disabled: true` is dropped even when the disk config's `plugins` array still lists it.\n   */\n  plugins?: Array<{\n    name: string\n    options?: object\n    disabled?: boolean\n  }>\n  /**\n   * Raw OpenAPI / Swagger spec content (YAML or JSON string).\n   * Always honored for a 'sandbox' agent. For a non-sandbox agent it is honored only when the\n   * agent opts in with `KUBB_AGENT_ALLOW_INPUT`; otherwise the spec is read from disk and this is ignored.\n   */\n  input?: string\n  /**\n   * Adapter option overrides sent from Studio UI. Merged into the disk config's adapter options\n   * and re-applied through the same adapter factory, since an adapter instance's functions\n   * (`parse`, `getImports`, ...) can't survive JSON serialization over the WebSocket.\n   */\n  adapter?: object\n}\n\n/**\n * Which `defineConfig(...)` entry an edit targets, for a config file that exports an array.\n *\n * A number selects by position, a string matches the entry's `name`. Omitted targets the only\n * entry, or the first one when the file exports an array.\n */\nexport type ConfigRef = string | number\n\n/**\n * A value the agent can read out of a plugin option in `kubb.config.ts` and round-trip through JSON.\n */\nexport type OptionValue = string | number | boolean | null | Array<OptionValue> | { [key: string]: OptionValue }\n\n/**\n * One change to a plugin's options in the user's `kubb.config.ts`.\n *\n * `plugin` is the package name (`@kubb/plugin-ts`), the same identity used in {@link JSONKubbConfig}.\n * The agent applies these to the file with an AST patch, so only the targeted values are rewritten.\n *\n * Declared here rather than in `configFile.ts` because this is the wire contract, and the patcher\n * imports it from here. Type-only, so nothing pulls `magicast` into this entry point.\n */\nexport type ConfigEdit =\n  /**\n   * Write a literal option value. `path` walks nested objects, so `['enum', 'type']` targets\n   * `pluginTs({ enum: { type } })`.\n   */\n  | { operation: 'set'; config?: ConfigRef; plugin: string; path: Array<string>; value: unknown }\n  /**\n   * Drop an option so the plugin falls back to its default.\n   */\n  | { operation: 'remove'; config?: ConfigRef; plugin: string; path: Array<string> }\n  /**\n   * Add a plugin factory call and its import to the `plugins` array.\n   */\n  | { operation: 'add-plugin'; config?: ConfigRef; plugin: string; importName?: string; options?: Record<string, unknown> }\n  /**\n   * Comment the plugin call out, keeping its options in the file so enabling it again restores them.\n   */\n  | { operation: 'disable-plugin'; config?: ConfigRef; plugin: string }\n  /**\n   * Uncomment a plugin call a previous `disable-plugin` commented out.\n   */\n  | { operation: 'enable-plugin'; config?: ConfigRef; plugin: string }\n\n/**\n * A plugin factory call the agent found in the `plugins` array of a `defineConfig(...)`.\n */\nexport type PluginView = {\n  /**\n   * Local identifier of the factory in the file, e.g. `pluginTs`. This is the alias when the plugin\n   * was imported under one.\n   */\n  importName: string\n  /**\n   * Module the factory is imported from, e.g. `@kubb/plugin-ts`.\n   */\n  packageName: string\n  /**\n   * Top-level option keys, each flagged with whether the agent may write it and, when it can, the\n   * value found in the file. An option marked `literal: false` holds a function or a reference the\n   * agent will not overwrite, so Studio shows the control disabled rather than hiding it, and\n   * `value` is absent since there is nothing safe to display as the current value.\n   */\n  options: Record<string, { literal: boolean; value?: OptionValue }>\n  /**\n   * Set when the plugin call is commented out in the file. Its options stay on disk but are not\n   * readable, so `options` is empty until it is enabled again.\n   */\n  disabled?: true\n}\n\n/**\n * One `defineConfig(...)` entry. A config file that exports a single object has exactly one.\n */\nexport type ConfigView = {\n  /**\n   * The entry's `name`, when it sets one. Studio labels the config picker with it.\n   */\n  name?: string\n  /**\n   * Each plugin call in the entry, with its top-level option keys.\n   */\n  plugins: Array<PluginView>\n}\n\n/**\n * What the agent found in the user's config file, so Studio knows which controls it may offer.\n * Absent when the agent could not read the file at all.\n */\nexport type ConfigFileView =\n  | {\n      managed: true\n      /**\n       * One entry per config the file exports, in source order. Every {@link ConfigEdit} names\n       * which of these it targets through its `config` field.\n       */\n      configs: Array<ConfigView>\n    }\n  | {\n      managed: false\n      /**\n       * Why the file is outside what the agent edits, for example a default export that is not a\n       * `defineConfig(...)` call. Studio shows this and offers no property-level controls.\n       */\n      reason: string\n    }\n\n/**\n * Outcome of a single {@link ConfigEdit}, returned in a {@link ConfigSavedMessage}.\n */\nexport type ConfigEditOutcome = {\n  edit: ConfigEdit\n  applied: boolean\n  /**\n   * Why the edit was refused, absent when it was applied.\n   */\n  reason?: string\n}\n\n/**\n * Typed events sent by the Kubb agent to Studio over WebSocket.\n * Mirrors the single-context-object tuple style of {@link KubbHooks} in `kubb/kit`,\n * using JSON-serializable shapes (e.g. `sources` as a `Record` instead of `Map`,\n * `error` as `{ message; stack? }` instead of `Error`).\n */\nexport type KubbHooks = {\n  'kubb:plugin:start': [ctx: { plugin: { name: string } }]\n  'kubb:plugin:end': [ctx: { plugin: { name: string }; duration: number; success: boolean }]\n  'kubb:build:start': [ctx: { config: { name?: string }; adapter: { name: string } }]\n  'kubb:build:end': [ctx: { files: Array<{ path: string; name: string }>; outputDir: string }]\n  'kubb:files:processing:start': [ctx: { total: number }]\n  'kubb:files:processing:update': [\n    ctx: {\n      files: Array<{\n        file: string\n        processed: number\n        total: number\n        percentage: number\n      }>\n    },\n  ]\n  'kubb:files:processing:end': [ctx: { total: number }]\n  'kubb:info': [ctx: { message: string; info?: string }]\n  'kubb:success': [ctx: { message: string; info?: string }]\n  'kubb:warn': [ctx: { message: string; info?: string }]\n  'kubb:error': [ctx: { message: string; stack?: string }]\n  'kubb:debug': [ctx: { logs: Array<string>; fileName?: string }]\n  'kubb:generation:start': [ctx: { name?: string; plugins: number }]\n  'kubb:generation:end': [\n    ctx: {\n      config: Config\n      storage: Record<string, string>\n      peerDependencies: Record<string, string>\n      missingDependencies: Array<string>\n    },\n  ]\n  'kubb:generation:summary': [ctx: { duration: number; fileCount: number; failedPlugins: number; status: 'success' | 'failed' }]\n  'kubb:lifecycle:start': []\n  'kubb:lifecycle:end': []\n  'kubb:format:start': []\n  'kubb:format:end': []\n  'kubb:lint:start': []\n  'kubb:lint:end': []\n  'kubb:hooks:start': []\n  'kubb:hooks:end': []\n  'kubb:hook:start': [ctx: { id?: string; command: string; args?: Array<string> }]\n  'kubb:hook:line': [ctx: { id: string; line: string }]\n  'kubb:hook:end': [\n    ctx: {\n      id?: string\n      command: string\n      args?: Array<string>\n      success: boolean\n      error?: { message: string; stack?: string }\n    },\n  ]\n}\n\nexport type KubbHook = keyof KubbHooks\n\n/**\n * Run a generation with the given config. `payload` is the merged config Studio wants generated.\n */\nexport type StudioGenerateMessage = {\n  type: 'studio:generate'\n  jobId: string\n  payload: JSONKubbConfig\n}\n\n/**\n * Ask the agent to send a fresh `agent:connect` payload. Permissions are fixed when the host starts\n * the agent; this message only triggers another read of disk config and saved Studio state.\n */\nexport type StudioConnectMessage = {\n  type: 'studio:connect'\n  jobId?: string\n  /**\n   * Version of the Studio instance asking, which refreshes what the agent picked up when the\n   * session was created. Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Change plugin options in the user's `kubb.config.ts`. Applied only when the agent was granted\n * `allowConfigEdit`; otherwise every edit comes back refused.\n */\nexport type StudioSaveMessage = {\n  type: 'studio:save'\n  jobId: string\n  edits: Array<ConfigEdit>\n}\n\n/**\n * Ask the agent to pack a previous generation's files into an npm-installable tarball and upload\n * it to Studio directly, rather than returning the bytes over this socket. Packs the files the\n * session's own most recent `studio:generate` produced, so it only works right after that\n * generation and never carries file contents itself. Refused for a sandbox agent, since it holds\n * no generated files worth packing, and refused when no prior generation exists to pack.\n */\nexport type StudioSnapshotMessage = {\n  type: 'studio:snapshot'\n  jobId: string\n  payload: {\n    name: string\n    version: string\n    peerDependencies?: Record<string, string>\n    /**\n     * Studio path the agent `PUT`s the finished tarball to. Studio answers with a redirect to\n     * storage, so the storage URL stays out of this message.\n     */\n    uploadPath: string\n  }\n}\n\n/**\n * Anything Studio asks the agent to do. Each command is its own `type`, so a handler switches once\n * instead of reading a `type` and then a nested `command` field.\n */\nexport type CommandMessage = StudioGenerateMessage | StudioConnectMessage | StudioSaveMessage | StudioSnapshotMessage\n\n/**\n * The command names, for a host that needs the list rather than the union.\n */\nexport const commandTypes = ['studio:generate', 'studio:connect', 'studio:save', 'studio:snapshot'] as const\n\nexport function createJobId(): string {\n  return crypto.randomUUID()\n}\n\n/**\n * Identifies the host running the Kubb runtime. Local to the runtime rather than part of the wire:\n * it picks which remedy a refused-input warning suggests, since the Docker agent and the CLI grant\n * `allowInput` different ways.\n */\nexport type ClientInfo = {\n  /**\n   * `cli` for a `kubb studio` connection from a developer's machine, `docker` for the agent image,\n   * `ci` for a client embedded directly in an automated pipeline (no `kubb studio` process).\n   */\n  kind: 'cli' | 'docker' | 'ci'\n}\n\n/**\n * Payload of the `agent:connect` handshake, sent when the agent attaches to a session. Carries only\n * what Studio renders, with everything about the config under one key.\n */\nexport type ConnectMessagePayload = {\n  /**\n   * Always sent, so a mismatch is visible on both sides: Studio badges the connection with these\n   * and the host prints them.\n   */\n  versions: {\n    /**\n     * The version of the `@kubb/studio` runtime the agent runs.\n     */\n    kubb: string\n    /**\n     * The version of the host itself (the `kubb.agent` package or the `kubb` CLI).\n     */\n    agent: string\n  }\n  /**\n   * The agent's project root (`KUBB_AGENT_ROOT`, or the working directory when unset). This is the\n   * workspace that generation runs against.\n   */\n  root: string\n  /**\n   * The baseline every generation starts from.\n   */\n  config: {\n    /**\n     * The config path as configured (`KUBB_AGENT_CONFIG`), relative to `root` unless absolute.\n     */\n    path: string\n    /**\n     * What the agent read out of the config file itself, so Studio can render the plugin editor\n     * against the real file. Absent when the agent could not read it, or was not granted\n     * `allowConfigEdit`.\n     */\n    file?: ConfigFileView\n    /**\n     * Plugins the config registers, with their serialized options.\n     */\n    plugins?: Array<{\n      name: string\n      options?: object\n    }>\n  }\n  permissions: AgentPermissions\n}\n\n/**\n * What an agent may do in the project it serves. Every one is off unless the host granted it, and\n * a sandbox session narrows them further.\n */\nexport type AgentPermissions = {\n  /**\n   * Whether the agent writes generated files to disk. False for a sandbox agent. For a local\n   * agent it mirrors the agent's `KUBB_AGENT_ALLOW_WRITE`.\n   */\n  allowWrite: boolean\n  /**\n   * Whether the agent will accept and generate from an OpenAPI spec supplied by Studio.\n   * Always true for a sandbox agent, otherwise it mirrors the agent's own opt-in. Studio reads\n   * this to decide whether to send `input`.\n   */\n  allowInput: boolean\n  /**\n   * Whether the agent runs the formatter, the linter, and `output.postGenerate` as child\n   * processes after a generation. Always true for the Docker agent, where the image bounds what\n   * can run. The CLI runs in the user's own project and defaults it off.\n   */\n  allowExec: boolean\n  /**\n   * Whether the agent may change plugin options in the user's `kubb.config.ts`. Separate from\n   * `allowWrite`, which covers generated output: this one edits a hand-authored source file.\n   */\n  allowConfigEdit: boolean\n}\n\n/**\n * Agent → Studio handshake. Sent when the WebSocket opens and again after a `connect` command.\n * Carries the on-disk config baseline, granted permissions, and paths Studio needs to render the editor.\n */\nexport type AgentConnectMessage = {\n  type: 'agent:connect'\n  payload: ConnectMessagePayload\n}\n\n/**\n * Reply to a `save` command: what the agent did to the file on disk.\n */\nexport type AgentSaveMessage = {\n  type: 'agent:save'\n  jobId: string\n  payload: {\n    /**\n     * Per-edit result, in the order the edits were sent.\n     */\n    outcomes: Array<ConfigEditOutcome>\n    /**\n     * Whether the file on disk changed. False when every edit was refused, and when the applied\n     * edits produced the text the file already had.\n     */\n    changed: boolean\n    /**\n     * The config file as it now stands, so Studio can re-render without a round trip. Absent when\n     * nothing was written. Named to match `config.file` in the connect payload.\n     */\n    file?: ConfigFileView\n  }\n}\n\n/**\n * Reply to `studio:snapshot`. The tarball already went to storage, so this only reports whether\n * the upload succeeded.\n */\nexport type AgentSnapshotMessage = {\n  type: 'agent:snapshot'\n  jobId: string\n  payload: { status: 'ok'; integrity: string } | { status: 'error'; message: string }\n}\n\n/**\n * Failure notice from Studio for something that breaks outside a generation, such as a malformed\n * command. The agent's own failures travel as an `agent:data` message carrying a `kubb:error`\n * payload, which keeps them ordered against the generation events around them.\n */\nexport type StudioErrorMessage = {\n  type: 'studio:error'\n  message: string\n}\n\n/**\n * Heartbeat sent by the Agent to Studio so the connection is not treated as idle.\n */\nexport type AgentPingMessage = {\n  type: 'agent:ping'\n}\n\n/**\n * Studio's reply to an `agent:ping`, confirming the connection is still alive.\n */\nexport type StudioPongMessage = {\n  type: 'studio:pong'\n}\n\n/**\n * Studio's acknowledgement that an `agent:connect` handshake was received and the session is\n * fully registered: the connection now counts as available for job dispatch. Distinct from the\n * socket merely being open, which is not yet the same thing.\n */\nexport type StudioReadyMessage = {\n  type: 'studio:ready'\n}\n\n/**\n * Disconnect message sent from Studio to Agent when the session is expired or revoked.\n * The agent should close the connection without reconnecting.\n */\nexport type StudioDisconnectMessage = {\n  type: 'studio:disconnect'\n  reason: 'expired' | 'revoked'\n}\n\n/**\n * The agent going away, so Studio marks the session offline instead of waiting out the heartbeat\n * window. The mirror of {@link StudioDisconnectMessage}.\n *\n * Only sent for a shutdown. An expired or revoked session was Studio's own decision, so echoing it\n * back says nothing new.\n */\nexport type AgentDisconnectMessage = {\n  type: 'agent:disconnect'\n  reason: 'shutdown'\n}\n\n/**\n * Payload of an `agent:data` message: a single Kubb generation event forwarded to Studio in real time.\n * Generic over the hook name so `data` is typed to that hook's context tuple.\n */\nexport type DataMessagePayload<T extends KubbHook = KubbHook> = {\n  /**\n   * The Kubb hook this event is for (e.g. `kubb:plugin:start`).\n   */\n  type: T\n  /**\n   * The hook's context tuple, matching `KubbHooks[type]`.\n   */\n  data: KubbHooks[T]\n  /**\n   * When the agent emitted the event, epoch milliseconds.\n   */\n  timestamp: number\n  /**\n   * Monotonic per-connection counter stamped in the order the agent emits events. Studio orders the\n   * event log by this, since `timestamp` has millisecond resolution and a full generation fires\n   * dozens of events per tick, and the relay can deliver them out of order.\n   */\n  seq: number\n}\n\n/**\n * Envelope for a single generation event streamed from Agent to Studio. Wraps a\n * {@link DataMessagePayload} so both sides can switch on `type: 'agent:data'`.\n */\nexport type DataMessage<T extends KubbHook = KubbHook> = {\n  type: 'agent:data'\n  jobId: string\n  payload: DataMessagePayload<T>\n}\n\n/**\n * Response returned by the Studio `/api/agent/sessions` endpoint.\n */\nexport type AgentConnectResponse = {\n  /**\n   * WebSocket URL the agent opens to reach the session, with the session token embedded.\n   */\n  wsUrl: string\n  /**\n   * When the session expires and the wsUrl stops working (ISO 8601).\n   */\n  expiresAt: string\n  /**\n   * When the session was revoked (ISO 8601), or null while it is still valid.\n   */\n  revokedAt: string | null\n  /**\n   * Opaque session token, also embedded in `wsUrl`. Store it to revoke the session later.\n   */\n  sessionId: string\n  /**\n   * Short readable identifier for this connection, used in logs (e.g. brave-otter).\n   */\n  slug: string | null\n  /**\n   * Whether this session belongs to a shared sandbox agent rather than an owned one.\n   */\n  isSandbox: boolean\n  /**\n   * The Studio instance's own version. Reported here rather than only on `studio:connect`, so the\n   * agent knows it before it announces itself and can name both sides from the first connect.\n   * Absent when Studio predates the field.\n   */\n  version?: string\n}\n\n/**\n * Every message that can cross the agent WebSocket, in either direction. Narrow it with the\n * `is*Message` guards below before reading a variant's fields.\n */\nexport type AgentMessage =\n  | CommandMessage\n  | DataMessage\n  | AgentConnectMessage\n  | AgentSaveMessage\n  | AgentSnapshotMessage\n  | AgentPingMessage\n  | AgentDisconnectMessage\n  | StudioErrorMessage\n  | StudioPongMessage\n  | StudioReadyMessage\n  | StudioDisconnectMessage\n\nexport function isCommandMessage(msg: AgentMessage): msg is CommandMessage {\n  return (commandTypes as ReadonlyArray<string>).includes(msg.type)\n}\n\n/**\n * Type guard to narrow a data message to a specific event type.\n *\n * @example\n * ```ts\n * if (isDataMessage(msg, 'kubb:plugin:start')) {\n *   // msg.payload.data is now typed as [ctx: { plugin: { name: string } }]\n *   const pluginName = msg.payload.data[0].plugin.name\n * }\n * ```\n */\nexport function isDataMessage<T extends KubbHook>(msg: AgentMessage, type?: T): msg is DataMessage<T> {\n  return msg.type === 'agent:data' && (type ? msg.payload.type === type : true)\n}\n\nexport function isStudioPongMessage(msg: AgentMessage): msg is StudioPongMessage {\n  return msg.type === 'studio:pong'\n}\n\nexport function isStudioReadyMessage(msg: AgentMessage): msg is StudioReadyMessage {\n  return msg.type === 'studio:ready'\n}\n\nexport function isDisconnectMessage(msg: AgentMessage): msg is StudioDisconnectMessage {\n  return msg.type === 'studio:disconnect'\n}\n"],"mappings":";;;;;AA+SA,MAAa,eAAe;CAAC;CAAmB;CAAkB;CAAe;AAAiB;AAElG,SAAgB,cAAsB;CACpC,OAAO,OAAO,WAAW;AAC3B;AAsRA,SAAgB,iBAAiB,KAA0C;CACzE,OAAQ,aAAuC,SAAS,IAAI,IAAI;AAClE;;;;;;;;;;;;AAaA,SAAgB,cAAkC,KAAmB,MAAiC;CACpG,OAAO,IAAI,SAAS,iBAAiB,OAAO,IAAI,QAAQ,SAAS,OAAO;AAC1E;AAEA,SAAgB,oBAAoB,KAA6C;CAC/E,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,qBAAqB,KAA8C;CACjF,OAAO,IAAI,SAAS;AACtB;AAEA,SAAgB,oBAAoB,KAAmD;CACrF,OAAO,IAAI,SAAS;AACtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/studio",
-  "version": "5.3.2",
+  "version": "5.3.3",
   "description": "Kubb Studio client runtime. Connects a Kubb project to Kubb Studio over WebSocket and streams code generation events, shared by the `kubb studio` CLI command and the Docker agent.",
   "keywords": [
     "agent",
@@ -62,17 +62,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.3.2",
+    "@kubb/core": "5.3.3",
     "magicast": "^0.5.5",
     "ofetch": "^1.5.1",
     "remeda": "^2.48.0",
     "tinyexec": "^1.3.1",
+    "tsdown": "^0.23.0",
     "unstorage": "^1.17.5",
     "ws": "^8.21.3"
   },
   "devDependencies": {
     "@internals/utils": "0.0.1",
-    "@kubb/adapter-oas": "5.3.2",
+    "@kubb/adapter-oas": "5.3.3",
     "@types/ws": "^8.18.1"
   },
   "engines": {