AgentKit Studio
Releases and migration

Desktop update channels

Four channels × two feed targets × two layouts — how updates ship, why nightly is the default, and what the compatibility lane does.

A release is not one file; it is a matrix of eight feed keys. A client only trusts the channel sealed into its own app-update.yml, and that cannot be changed remotely — so every publication must maintain several lanes at once.

Channels (4)

ChannelKindAccepts prereleaseDefaultNotes
nightlyNative✅YesProduct default lane, allowPrerelease = true
latestNative❌—GA lane; three-segment releases only
previewCompatibility✅—Historical lane, mirrored on every publication
stableCompatibility❌—Historical lane, same comparison rule as latest

Source: src/desktop-release-channels.mjs:20-26,59.

Why nightly is the default

FactConsequence
The pinned DSH version carries an -rc.N suffixThe desktop version <DSH version>.<date>.<ordinal> inherits it
Every Studio build is therefore a prereleaselatest / stable reject it
The DSH update coordinator sets allowPrerelease = channel === 'nightly'Only nightly accepts prereleases

Source: src/desktop-release-channels.mjs:10-16,51-58.

A prerelease feed on latest breaks updates for every client

The DSH update coordinator throws on a prerelease version in the latest lane, and the client cannot even run an update check. Packaging therefore refuses up front: assertChannelSupportsVersion fails while the plan is built. Source: src/desktop-release-channels.mjs:108-124.

Feed targets (2)

TargetPlatformChannel metadata filename
mac-arm64macOS Apple Silicon<channel>-mac.yml
win-x64Windows x64<channel>.yml

Source: src/desktop-release-channels.mjs:49,127-134.

There is no third target

RELEASE_FEED_TARGETS has exactly two entries. product.json lists a second macOS architecture's icon configuration, but that only feeds packaging input validation — there is no corresponding feed.

Feed layouts (2)

LayoutObject rootAllowed binary prefixesPurpose
studiostudio//studio/Current canonical layout
legacydsh-desk//studio/ or /dsh-desk/bin/Historical dsh-desk/feeds/... entry

Source: src/desktop-release-feed.mjs:25-42.

Layout and binary location are validated separately: a legacy feed legitimately points at the canonical studio/<version>/ bytes, while feeds written by pre-Studio builds point at dsh-desk/bin/.... Both prefixes are accepted.

The eight feed keys

<object root>/feeds/<target>/<channel metadata filename>
TargetNative lanes (studio layout)Compatibility lanes (legacy layout)
mac-arm64studio/feeds/mac-arm64/{nightly,latest}-mac.ymldsh-desk/feeds/mac-arm64/{preview,stable}-mac.yml
win-x64studio/feeds/win-x64/{nightly,latest}.ymldsh-desk/feeds/win-x64/{preview,stable}.yml

Source: src/desktop-release-feed.mjs:71-76.

Artifact paths

macOS publication layout:

AssetPath
DMGstudio/<version>/AgentKit-Studio-mac-arm64.dmg
ZIP (incremental)studio/<version>/AgentKit-Studio-mac-arm64.zip
ZIP (full)studio/<version>/full/AgentKit-Studio-mac-arm64.zip
Blockmapstudio/<version>/AgentKit-Studio-mac-arm64.zip.blockmap
Feedstudio/feeds/mac-arm64/<channel>-mac.yml
Release recordstudio/feeds/mac-arm64/mac-arm64-release.json

Source: src/desktop-release-metadata.mjs:16-32.

Two publication modes

mode is either incremental or full. Full mode places the ZIP under full/ while the blockmap still points at the version root — differential and full updates share one metadata document.

Compatibility mirroring

After every successful publication, the same feed bytes are copied onto the compatibility lane:

PropertyValue
Compatibility lanepreview (COMPATIBILITY_RELEASE_CHANNELS)
Copy methodByte-for-byte; no re-signing, no binary re-upload
IdempotencyRecords unchanged when already identical; no duplicate upload
PurposeHistorical installs jump straight to the newest release instead of first hopping to whatever version the lane froze at

Source: src/desktop-release-feed.mjs:82-220, src/desktop-release-channels.mjs:35-46.

Mirror evidence is recorded in the publication report with fixed fields: version, sourceChannel, targetChannel, targetLayout, objectKey, feedUrl, feedBytes, feedSha512, status. status is either updated or unchanged. Source: src/desktop-release-feed.mjs:82-101.

Release flow

make desktop-package-preflight            # 1. refuse invalid channel × version
make desktop-package-mac-arm64            # 2. package; artifacts land in .artifacts/
make desktop-package-win-x64
node scripts/desktop-release.mjs publish  # 3. immutable assets first, then advance the feed
OrderActionWhy it cannot be reversed
1PreflightCalls assertChannelSupportsVersion: latest / stable with a prerelease version fails immediately
2PackageArtifacts land in .artifacts/
3Upload DMG / ZIP / blockmapURLs are immutable, so re-uploading is harmless
4Advance the feedThe feed is the only mutable object — an absolute URL to an immutable binary plus the digest electron-updater checks; reversing hands clients a 404
5Mirror the compatibility laneThe publisher writes the same feed bytes onto preview automatically

Configuration

SettingLocationCurrent value
Default environmentproduct.json#desktop.updates.environmentproduction
Default channelproduct.json#desktop.updates.channelnightly
Update originproduct.json#desktop.updates.originInjected by the build (never documented)
Allowed environmentsscripts/product-config.mjs:47production / test

Common errors

ErrorCauseFix
channel is requiredEmpty channelPass --channel or keep the product default
channel must be one of …Channel is not one of the fourUse nightly / latest / preview / stable
latest channel requires a stable three-segment versionPrerelease on a stable laneShip on nightly
feed layout must be one of …Layout is neither studio nor legacyCheck --compat-layouts
feed target must be one of …Target is neither mac-arm64 nor win-x64Check --target
Studio storage must be an HTTPS originUpdate origin is not a bare HTTPS originRemove path / query / credentials
release metadata does not identify its signed ZIPFilename in the feed does not matchRegenerate metadata

Source: src/desktop-release-channels.mjs:77-124, src/desktop-release-feed.mjs:51-68, src/desktop-release-metadata.mjs:4-13.

On this page