-
Organize the Studio runtime into protocol, operations, and runtime layers. (#4121,
63f951a) -
kubb studio snapshotruns its snapshot job on the agent process it connected, so two overlapping pipelines of the same CI agent never build each other's checkout. -
Remove
memoryBudgetMbfromAgentCapacity, along with theKUBB_AGENT_MEMORY_BUDGET_MBenvironment variable. An agent no longer refuses a job for memory, and its heartbeat always reportsaccepting: true. (#4117,d3996ef)
Thanks to everyone who contributed to this release:
- Improve Studio agent connections, job isolation, retries, capacity reporting, and close handling. Add GitHub/GitLab branch snapshots and fail-fast token rejection handling to the CLI. (#4110,
327bfe9)
Thanks to everyone who contributed to this release:
- Align how
kubb studio, the Docker agent, andkubb studio snapshotpair, connect, and log. The runtime no longer prints or knows its host, pairing takes atypethrough the newpairAgent, and snapshots report the files changed since the previous one. (#4098,555e057)
Thanks to everyone who contributed to this release:
- Files emitted with
copynow follow the parser'sextensionoption. Parsers can implement the newcopy(file, source)hook to turn a copied file into nodes, andparserTs/parserTsxuse it to lift a template's imports and exports into import and export nodes. (#4096,050f6f9)
Thanks to everyone who contributed to this release:
- Keep a binary response or request body typed as a blob for any non-JSON media type (
application/pdf,image/png, ...), not justapplication/octet-stream. A newer@scalar/openapi-upgraderrelease started emptyingformat: 'binary'schemas for every media type on the OAS 3.1 upgrade, not justapplication/octet-stream, so those bodies fell back toemptySchemaTypeinstead of resolving to a blob. (#4094,cfcb497)
Thanks to everyone who contributed to this release:
- Keep recent generations by job id and snapshot the output directory before each run, so Studio can diff a run against an earlier one or against the files on disk. Agents with a project keep them in
node_modules/.cache/kubb, so they survive a restart, and sandboxes keep them in memory.KUBB_AGENT_MAX_GENERATIONS(default 8),KUBB_AGENT_MAX_GENERATIONS_MB(default 100) andKUBB_AGENT_MAX_SNAPSHOT_MB(default 50) set the limits. Breaking for the Studio connection:readFilesnow takes ajobIdand asource, andGenerateResult.changesis replaced byhashesanddisk.hashes.@kubb/corenow exportscacheStorage. (#4090,7b517b8)
Thanks to everyone who contributed to this release:
-
Report which files a Studio run added, changed, or removed, and serve the previous run's contents so Studio can show a diff.
GenerateResult.changesmaps each path that differs from the session's previous successful run toadded,changed, orremoved. Unchanged files are left out, and the field is absent on a session's first run.readFilestakesrevision: 'previous'to read the run before the latest one, including files the latest run removed. The previous run is read into memory before the next run starts, so a session that writes to disk can still be diffed after its files are overwritten.- A failed run leaves the last successful run as the one to compare against.
FileChangeis exported from@kubb/studio. (#4086,300186d)
Thanks to everyone who contributed to this release:
- Generate
Blobfor multipart binary properties after upgrading an OpenAPI 3.0 document to 3.1. (#4083,95d93a7)
Thanks to everyone who contributed to this release:
- Show sponsor tips again for successful
kubb generateruns and when starting akubb studiosession. (#4077,15c644e)
Thanks to everyone who contributed to this release:
- Scope Kubb Studio help by subcommand and reject flags passed to the wrong Studio command. (#4068,
d88ab19)
- Apply the same adapter, parser, and plugin defaults to programmatic
createKubbbuilds as the CLI configuration. (#4072,4afe194)
Thanks to everyone who contributed to this release:
-
Carry an agent's organization slug through pairing and connecting, so a host can log and trace it alongside the agent's own slug.
PairingResult.agentand thestudio:connectedhook context gain an optionalorganizationSlug, absent for a sandbox or global agent, which has none.studio:connectedalso gainsagentSlug, refreshed on every connect so a rename in Studio shows up without a re-pair. Both fields are additive: a host built against an older type just ignores them. (#4066,eb5fa50)
Thanks to everyone who contributed to this release:
- Fix a snapshot package's
package.jsonpointingmain/module/exports['.']atdist/index.*even when the generation had no top-level barrel, and add a wildcardexports['./*']so individual generated files stay importable by path. (#4064,d2ce0c4)
Thanks to everyone who contributed to this release:
-
Replace the agent WebSocket command protocol with typed Cap'n Web RPC and remove the legacy JSON envelopes. Agents and Studio must upgrade together; mismatched versions cannot communicate. (#4061,
f880342) -
Fix generation and heartbeat lifecycle bugs left over from the Cap'n Web RPC cutover:
- A dropped Studio connection now cancels the in-flight generation instead of letting it finish unwatched.
- Two
startGenerationcalls arriving in the same tick can no longer both start a run. - A heartbeat ping that never settles (a half-open socket) now closes the session instead of hanging it indefinitely.
- Removed an unreachable error path left over from the old JSON transport. (#4061,
f880342)
Thanks to everyone who contributed to this release:
-
Stop holding a whole generation's output in memory for the life of a Studio session.
studio:filesandstudio:snapshotused to read every generated file into oneRecord<string, string>the moment a run finished, and kept that map alive until the next generation. A run producing gigabytes of source meant the agent process held gigabytes in RAM, whether or not anyone ever opened a file or took a snapshot.The agent now keeps the live
Storagea run wrote through, plus the list of paths it produced, and reads a file's content back fromStorageonly whenstudio:filesorstudio:snapshotactually asks for it. A path outside that list is refused before it reaches storage, so this changes nothing about what a session can read, only when the read happens. (#4059,351e3c9) -
Stop streaming generated source over the agent WebSocket by default. Reading it now needs
--allow-read(orKUBB_AGENT_ALLOW_READ=true), matching the other four Studio permissions.Every
kubb studiosession used to send the full text of every generated file onkubb:generation:end, whether or not anyone in the browser opened one. A spec producing hundreds of files could put megabytes of source on the wire per run, and nothing gated it:allowWrite,allowConfigEdit,allowInput, andallowExecall cover what Studio may do to a project, but reading generated output back was never one of the four.kubb:generation:endnow carries nothing. Everything it used to carry moved somewhere better:- The list of generated files is on
kubb:build:end, which already carried every path and fires earlier in a run. Its paths are now relative to the agent's root, matching every other path on the wire, where they used to be absolute. - The file count is on
kubb:generation:summary, which already had it and was always the accurate number (kubb:generation:end's old count went to 0 for a CI connection). - File contents are fetched on demand with a new
studio:filescommand, which the browser sends when someone opens a file. The agent replies withagent:files, refusing unlessallowReadwas granted. - Peer dependency metadata, previously sent on every generation and round-tripped straight back
into
studio:snapshot, now travels with theagent:snapshotreply instead, since the CI snapshot flow is its only consumer.studio:snapshottakesbundledDependenciesin place ofpeerDependencies.
--allow-readis off by default everywhere, like every other permission. A sandbox or global agent is always granted it, since its output is the only thing it has:kubb studio --allow-read # show generated files in the browserAn older Studio instance talking to this version of the agent (or the reverse) can fail: a snapshot build errors because
bundledDependenciesandpeerDependenciesno longer line up between the two ends, and a plain session shows an empty editor with no file contents. Point--urlat a Studio build that matches this version.The in-process
kubb:generation:endhook (kubb.hooks.hook('kubb:generation:end', ...), or a plugin's own listener) is unaffected. It still carriesconfig,storage,diagnostics,status,hrStart, andfilesCreated, exactly as before. Only the payload this event sends over the Studio WebSocket changed. (#4059,351e3c9) - The list of generated files is on
Thanks to everyone who contributed to this release:
-
Back off while polling a Studio job, so a long snapshot stops exhausting the API key rate limit.
waitForJobpolledGET /api/jobs/{id}every second, starting the instant the job was queued. The CLI'skubb studio snapshotwaits up to 10 minutes by default, which is up to 600 requests against a budget of 100 per window. The window only resets after a whole window with no request, so a one-second poll could never escape the limit once it hit it, and every later call failed until the run gave up. The budget belongs to the organization key, so concurrent CI runs share it.The first poll now waits two seconds, since a job runs a generation and packs a tarball before it can possibly finish. From there the interval doubles to a 30 second ceiling, bringing a 10 minute wait down from 600 requests to 22. A 429 pushes the next poll out by the
tryAgainInStudio returns and never pulls it back in, andretry: falsestops ofetch retrying a 429 with no delay. (#4057,52637b6)
Thanks to everyone who contributed to this release:
-
The agent runtime now packs snapshot tarballs itself. A new
studio:snapshotcommand builds the npm-installable tarball from the session's most recent generation and uploads it to a Studio endpoint, instead of Studio building the tarball on its own server. A snapshot request with no prior generation is refused.A CI connection also keeps generated files off every
kubb:generation:endreply, since it has no UI to render them in.kubb studio snapshotand the Studio UI's "Create snapshot" button keep working as before, now backed by this protocol message. (#4052,19e9c2c) -
The background reconnect loop's "Retrying connection" and "Reconnect attempt failed" lines, and the teardown notice
disconnect()prints on the way out, now go throughconsole.errorinstead ofconsole.info/console.log, and only print when a host passes alogLevelabovesilenttoStudioSession. Previously they always printed unconditionally, which a CI runner that only streams a child process's stderr live (such askubb-labs/action) never surfaces, and which contradictedinstallLogger's own "prints nothing when left out" default.kubb studioandkubb studio snapshotnow pass their--log-levelflag through, so these lines respect the same flag as the rest of the command's output. (#4052,19e9c2c)
Thanks to everyone who contributed to this release:
-
CLI flags are now kebab-case, matching the convention used by most command-line tools.
kubb generate --log-levelandkubb generate --dry-runreplace--logLeveland--dryRun.kubb studio --allow-write,--allow-config-edit,--allow-input, and--allow-execreplace--allowWrite,--allowConfigEdit,--allowInput, and--allowExec.kubb init --dry-runreplaces--dryRun.
To upgrade, replace any camelCase flag in a script or CI job with its kebab-case name. The CLI now rejects an unrecognized flag with an error instead of silently ignoring it.
# Before kubb studio --allowWrite --allowExec # After kubb studio --allow-write --allow-exec ``` ([#4046](https://github.com/kubb-labs/kubb/pull/4046), [`e5ecdda`](https://github.com/kubb-labs/kubb/commit/e5ecdda06acbd3b99c2716384b2a8ac56eedfad8))
-
Renamed the
studio:pingheartbeat reply tostudio:pong, matching the ping/pong patternagent:pingalready implies (StudioPingMessageis nowStudioPongMessage,isStudioPingMessageis nowisStudioPongMessage). This is a wire-protocol change: an agent running an older@kubb/studioand a Studio running the new one won't recognize each other's heartbeat reply. Update both sides together.Also documented the full
studio:/agent:message table inpackages/studio/src/protocol/index.ts, including whystudio:generatehas no dedicatedagent:generatereply (its result rides theagent:data/kubb:generation:endevent stream instead, unlikestudio:save/studio:snapshot, which reply directly). (#4053,76dd283)
Thanks to everyone who contributed to this release:
Thanks to everyone who contributed to this release:
Thanks to everyone who contributed to this release:
-
Add
kubb studio snapshotto generate and publish a Kubb Studio snapshot from any CI, not only GitHub Actions.- Registers or reuses a CI agent, connects it, queues a snapshot job, and polls until the tarball is ready.
- Reads the organization CI API key from
--tokenorKUBB_TOKEN. - Detects the calling CI (GitHub Actions, GitLab CI, Bitbucket Pipelines, CircleCI) to reuse one agent per pull or merge request, or takes an explicit
--idon any other CI. - Prints a summary, or one JSON object with
--jsonfor a script to read. @kubb/studionow also exportscreateAgentandmachineTokenFrom, so a host can register a CI agent without hand-rolling the request.
KUBB_TOKEN=$KUBB_TOKEN kubb studio snapshot --json ``` ([#4038](https://github.com/kubb-labs/kubb/pull/4038), [`4cd9f5e`](https://github.com/kubb-labs/kubb/commit/4cd9f5e311e5dc6edb14287c13db0a5466b4e892))
Thanks to everyone who contributed to this release:
- Create a separate Kubb Studio agent connection for each project directory while reusing the same agent within that directory. (
af87dbc)
Thanks to everyone who contributed to this release:
- Add job ID correlation to Studio commands and streamed agent events. (
0a1e553)
Thanks to everyone who contributed to this release:
-
Add a
studio:readyacknowledgement so a host can tell "the socket is open" apart from "Studio has registered this connection and will dispatch jobs to it".A connected socket announces itself with
agent:connectbut never waited for a reply, so a job could arrive at Studio moments before the agent was actually registered.StudioSessionnow waits up to 10 seconds forstudio:readyafter sending that handshake and fires a newstudio:readyhook once it lands, warning instead of failing if an older Studio never sends one.kubb studioprints✓ Ready to receive jobsonce it does. (#4028,b93eb64)
Thanks to everyone who contributed to this release:
-
Report the package a plugin ships from, so
plugin-tsreaches Studio as@kubb/plugin-tswhile a third-party plugin keeps its own name.The connect payload scoped every plugin name under
@kubb/, which claimed a third-party plugin as one of Kubb's. It now follows the same rule the dependency check already used. (#4026,628c98b)
Thanks to everyone who contributed to this release:
kubb generate --watchnow works with URL inputs. A remote document emits no filesystem events, so watch mode polls the URL (every 2 seconds) and regenerates when the response body changes. Each poll request times out after 10 seconds, so a hung server never stalls the watcher. An unreachable server is reported once per outage and polling continues. After recovery, a rebuild only happens when the document actually changed, unless the server was already down at startup, in which case the first successful poll regenerates so the output catches up. Previously--watchwas silently ignored for URL inputs and the CLI exited after a single build. (#4022,5f4fd20)
- Report installed peer dependency versions and missing dependencies with each generation result. (#4021,
6187109)
Thanks to everyone who contributed to this release:
@stijnvanhulle, @tachirodriguez
- A
oneOf/anyOfwithout a declared OpenAPIdiscriminatornow infers one when a property carries a distinct single literal value on every branch.UnionSchemaNode.discriminatorPropertyNameis set from that inference, so every printer that narrows on it (plugin-zod,plugin-faker) picks it up without reimplementing the same scan. (#4019,c89f215)
Thanks to everyone who contributed to this release:
- Keep a binary response body under
application/octet-streamtyped as a blob instead of falling back toemptySchemaType. (#4013,dd9a902)
- Add a
kubb.dev/sponsorsentry to each published package'sfundingfield, alongside the existing GitHub Sponsors and Open Collective links. (#4007,b063738)
-
Trim
@kubb/studio's public API to what thekubb studioCLI command and the Docker agent actually use.- Removed the unused hook context types
StudioCommandStartContext,StudioCommandEndContext,StudioConnectingContext,StudioDisconnectedContext,StudioErrorContext, andStudioWarnContextfrom the package's root export.StudioConnectedContextstays exported. Hook payloads forstudio:connecting,studio:command:start,studio:command:end,studio:disconnected,studio:warn, andstudio:errorstill type-check throughHookable<KubbHooks>['hook'], since the underlying types are still declared, just no longer importable by name. - Removed
ConnectionOutcomeandTokenRejectionfrom the root export. Both stay inferable fromrunConnection's return value andonTokenRejectedcallback.
Neither the CLI nor the Docker agent imports any of these by name, so this does not change their behavior. A consumer that did import one of them by name gets the same type through inference at the call site instead, such as
runConnection's return value or ahooks.hook('studio:warn', ...)callback's parameter. (#4012,109abe8) - Removed the unused hook context types
Thanks to everyone who contributed to this release:
- Add utilities for resolving object properties through references and intersections and for reading
literal values from enum schemas. Plugin authors can use these utilities to handle discriminated
unions without implementing their own schema traversal. (#3989,
a2b5924)
kubb initandkubb generate --watchnow print plain lines when the terminal cannot carry clack's gutter, such as a piped run or CI. They wrote box-drawing and cursor escapes into the output before. Spinner steps print as lines there instead of disappearing with the animation. (#3983,d1b123e)kubb mcpandkubb validatenow load@kubb/mcpand@kubb/adapter-oasonly when their commands run. Every other command, includingkubb --help, no longer touches either optional peer. (#3968,0e4dc40)
- Moved shared-utility logic used by only one package out of
@internals/utilsand into that package (@kubb/core,@kubb/cli,@kubb/kit). No public API or behavior changed. (#3968,0e4dc40)
Thanks to everyone who contributed to this release:
-
Let
dateTypesetdate-time,date, andtimeindependently, instead of one value driving all threePass an object to represent timestamps as a JS
Datewhile keeping date-only and time-only fields as strings, sinceDatecannot round-trip those without inventing a timezone.adapterOas({ dateType: { dateTime: 'date', date: 'string', time: 'string', }, })
The scalar form (
dateType: 'date') still applies one value to all three formats. (#3957,9fca8e9)
- Explicit
typesfields for each package.jsonexportsentry, so that it works with tsconfig.jsonmoduleResolution: 'bundler'(#3964,be4cd17)
Thanks to everyone who contributed to this release:
- Adds
--dryRuntogenerateandinitto preview a run without writing files, installing packages, formatting, linting, or running post-generate commands. When an AI coding agent runs the CLI,generatenow uses the plain logger instead of the interactive one, and anonymous telemetry records the agent's name. (#3951,9849de3)
Thanks to everyone who contributed to this release:
2869e6d- Avoids duplicate filesystem reads during generated file writes and uses native Node.js promise timers in asynchronous tests. (2869e6d)
-
Move
unplugin-kubbpast its squatted npm version range.Versions 5.0.1 through 5.0.30 were already published on npm from
unplugin-kubb's pre-monorepo history and depend on kubb v4, so the package's version was set directly to 5.0.31 to clear that range. This changeset picks up from that 5.0.31 baseline and putsunplugin-kubbback through the normal release process, independent ofkubband@kubb/*. (#3940,b45071e)
Thanks to everyone who contributed to this release:
- Keep every discriminator mapping key that targets the same schema, and apply the discriminant to children declared with
allOf(#3929,58d9625)
Thanks to everyone who contributed to this release:
-
Fix
Url.toPathproducing route masks thatpath-to-regexp(used by MSW/Express) rejects or misparses:- A parameter name starting with a character outside
[A-Za-z0-9_](e.g.{$id}) now sanitizes to a safe capture name instead of keeping the disallowed character. - Distinct parameter names that normalize to the same identifier (e.g.
{group-id}and{group.id}) are now deduplicated with an incrementing suffix (groupId,groupId2) instead of producing two identically named captures. (#3922,56a072c)
- A parameter name starting with a character outside
Thanks to everyone who contributed to this release:
- Fix an OpenAPI 3.1 multi-type array collapsing to one type when paired with
format.type: ["null", "integer", "string"], format: "int32"generatedinteger | null, droppingstring. The multi-type rule now runs beforeformat, so each type parses on its own. (#3916,3d0098c) - Fix an OpenAPI 3.1 multi-type array dropping its other types when
nullcame first.type: ["null", "string"]generatednullinstead ofstring | null, whiletype: ["string", "null"]generated the right type, so the output depended on the order the types happened to be written in. The normalized type now takes the first non-nullentry, andtype: ["null"]stays a null schema. (#3912,331558e)
- Fix
Url.toPathproducing an invalid Express-style route for a hyphenated path parameter (e.g.{point-id}became:point-id).path-to-regexptreats a hyphen as ending the parameter name, so the generated MSW handler matched:pointfollowed by a literal-idand rejected valid values.Url.toPathnow camelCases the parameter name the same wayUrl.toTemplateStringalready does, so{point-id}becomes:pointId. (#3895,bf9bdc8)
Thanks to everyone who contributed to this release:
Kubb v5 rebuilds code generation around adapters, a universal AST, parsers, and storage, and generates code up to 5.4x faster than v4. Config gets shorter, generated client calls change shape, and plugins move to their own repo (kubb-labs/plugins).
Read the release blog post for the highlights, and the migration guide for the full, per-package breaking-change list and upgrade steps.
For prior releases, see GitHub Releases.