hermes-agent/apps/desktop/BUILDING.md
ethernet ccc9d422ed fix(tts): install kittentts on python 3.14, opt-in only
KittenTTS 0.8.1 requires misaki[en]>=0.9.4. PyPI's misaki 0.9.4 caps
Python below 3.13. NousResearch/misaki f03fd2be73 is upstream main with
the cap raised to <3.15 and no code change, so the extra declares
misaki[en] at that commit and uv resolves KittenTTS's requirement to it.

misaki[en] also lists spacy-curated-transformers. The newest release
that fits spacy 3.8, 0.3.1, caps Python below 3.14, so PM's `uv pip
check` rejected every 3.14 venv that carried it. Nothing imports it:
only transformer spaCy models use it, and KittenTTS never builds a
misaki G2P. A never-true override marker removes it from the lock.
torch, transformers, spaCy and num2words stay: misaki.en imports them
at module level and KittenTTS imports misaki.en.

Native bundles sync with --all-extras, so un-gating the extra would put
KittenTTS, torch and spaCy in every payload. [tool.hermes] opt-in-extras
names the extras that only an explicit selection installs. PM adds
--no-extra for each of them to an all-extras sync, so bundles and their
recorded feature list leave kittentts out, and setup still installs it
through sync_venv when the user picks it.

The extra is gated on platform instead of Python: onnxruntime has no
Intel macOS wheel and torch has no Windows ARM64 wheel. Nix gets the
hatchling build backend the misaki git source needs.

Verified on macOS arm64 with CPython 3.14.7 and uv 0.12.3:
uv sync --frozen --extra kittentts from this lock, then uv pip check
reports all 126 packages compatible. _generate_kittentts writes a
3.87 s 24 kHz WAV (RMS 3661), and no spaCy model is downloaded. A dry-run
all-extras sync with --no-extra kittentts selects none of kittentts,
misaki, torch, transformers or spaCy. The new build test fails without
the environment change and passes with it.
2026-09-24 16:17:35 -04:00

355 lines
19 KiB
Markdown

# Building the Desktop Installers
Use the complete bundle builder for release artifacts. Ordinary `dist:*`
commands package the current desktop build; they do not stage a fresh runtime.
## Artifact and update ownership
| Target | Artifact | Update owner |
|---|---|---|
| Windows x64 / ARM64, sideload | Signed per-architecture MSIX packages, combined into a universal `.msixbundle`; `.appinstaller` descriptor | Windows App Installer |
| Windows x64 / ARM64, Store | Store-identity MSIX packages and a separate Store bundle | Microsoft Store |
| macOS ARM64 / x64 | Signed, notarized `Hermes.app` in DMG and ZIP artifacts | `electron-updater` with Squirrel.Mac |
| Linux x64 / ARM64 | Local builder can produce AppImage | External replacement; Linux desktop release legs are disabled |
The current MSIX manifest requires Windows 11 22H2 (`10.0.22621.0`).
The source-script Windows support range is separate from this package floor.
Windows desktop packaging uses MSIX, not NSIS or MSI.
`bundled` carries the local runtime. `store` carries the same runtime under
Partner Center's package identity. `light` is a remote-only client without
Python or a local agent. Light has build/feed support but no release matrix leg.
## Payload contents
The bundled payload contains:
- The release's source snapshot without `.git`.
- Pinned CPython and uv, plus a ready Python dependency tree.
- Node.js, npm, supported managed tools, and prebuilt TUI/dashboard assets.
- A manifest, tool facts, the installed feature list, and build provenance.
- Generated CLI launchers from the archived project's script declarations.
`pm/lock.json` owns managed-tool pins. `pyproject.toml` and `uv.lock` own Python
requirements. Native staging uses `--all-extras`, subject to platform markers,
minus the extras `[tool.hermes] opt-in-extras` names (installed only when the
user selects them). This is broader than the source installer's extra named `all`.
The backend runs from app resources. Launchers execute the store interpreter
with the source and dependency paths; they do not boot through a relocated
venv executable. Startup can create user-state records and CLI links.
Provider calls, model downloads, and optional integration setup can still use
the network.
Git is a platform exception: Windows stages Git for Windows with Bash.
POSIX targets use system Git. A Mac without Command Line Tools can therefore
need them for Git-dependent operations.
User data remains outside the package. Optional additions use writable PM
storage and complete Python environment generations, not writes into the app.
See [Package management](../../website/docs/reference/package-management.md).
## Python runtime contract
The PM bundle builder records interpreter and dependency paths in the payload
manifest. `scripts/write-build-stamp.mjs` copies that runtime contract into the
desktop stamp. The desktop build embeds the stamp in Electron.
`electron/payload-backend.ts` reads `runtime.sitePackages` from this stamp.
It does not select a Python version or search for dependency directories.
Staging does not prove native startup or package replacement. Those checks
use the [bundled-update acceptance suite](../../tests/install/BUNDLED_UPDATES.md).
Acceptance requires a native run with the actual signed release artifacts.
Packaged tool facts describe the final bytes, not only the staged archives.
Windows refreshes the tool digests after sanitization and batch signing.
The macOS custom signer retains the builder's entitlements and file selection.
It refreshes digests after child signatures and before the outer app signature.
Unsigned macOS builds refresh them at the end of `afterPack`.
Do not refresh facts in `afterSign`: that changes resources covered by the signature.
## Complete native build
From a clean checkout whose `HEAD` equals the release tag, run:
```sh
python scripts/bundles/desktop.py --tag=vX.Y.Z
```
Replace `vX.Y.Z` with an actual immutable tag. Stable tags must match the
version in `pyproject.toml`. Canary tags use the release script's tag grammar.
Start with host Python 3.11+ and Git. Use `python3` if that is your host's command.
Preparation asks PM for the pinned Python, Node, npm and private installer;
preinstalling a separate Node/npm/uv toolchain is not required. Native dependency
builds still need the platform's compiler, SDK and libraries. Windows ARM64 uses
the shared Visual Studio/Clang/Rust/static OpenSSL preparation provider, which
can require Administrator permissions for missing system components. macOS
requires its native developer tools. This is not a hermetic host SDK.
The builder:
1. Admits the clean source revision and prepares managed tools in isolated build state.
2. Prepares the locked JS workspace union, icon environment, Electron-native bindings,
packaging utilities, and the application/independent PM environments when selected.
3. Compiles icons and the selected TUI, dashboard and desktop products.
4. Assembles the PM payload, places JS assets, relocates links, and generates launchers.
5. Consumes the prepared Electron archive and utilities to package the current OS.
Use `--variant store` with a stable tag on Windows, or `--variant light` for the remote client.
Arguments after `--` go to the prepared wrapper, which rejects overrides of
the admitted target, tools, output and configuration. `electron-builder.config.cjs`
is the sole packaging configuration. The wrapper disables automatic publishing;
the release workflow owns uploads and channel promotion.
`pm bundle --out DIR --ref REF` stages the native runtime only.
`scripts/bundles/stage.py` also builds the TUI/dashboard unless both products
are supplied explicitly. Both generate launchers; neither creates an Electron installer.
The launcher stage checks the payload and records its relative launch paths.
The Electron build bakes these paths into its stamp. Desktop startup does not
inspect, create, or repair a PM payload. Non-bundled builds carry no placeholder payload.
See [shared bundle builds](../../docs/shared-bundle-builds.md) for Termux reuse.
### Prepare once, then build
CI and local builds share the same split interface:
```sh
python scripts/bundles/desktop.py --tag vX.Y.Z --variant bundled --prepare-only \
--work "$PWD/.build/desktop-job" --cache "$PWD/.cache/desktop-inputs"
python scripts/bundles/desktop.py --prepared "$PWD/.build/desktop-job/prepared.json"
```
The displayed paths are the defaults. Use separate build-owned work/cache roots;
do not pre-create the work directory. `prepared.json` is published after every
provider succeeds and contains absolute paths for this job, not a portable cache.
After relocation or a source/lock/tool change, prepare again. Consumption rejects
missing or changed dependencies without repairing or downloading them. Stable
Windows builds can consume one preparation for `--variant bundled` and then
`--variant store`; light and commit preparations cannot switch to Store.
Release jobs restore candidates, prepare, save reusable inputs, and only then
build/sign. Job-local environments, credentials, products and signature results
are not dependency snapshot inputs. The signature cache retains its own lifetime.
Commit jobs request token-enforced read-only cache access; the conditional YAML
mode still needs GitHub acceptance (see the
[cache-policy caveat](../../docs/shared-bundle-builds.md#cache-ownership)). A
separate key or skipped save alone would not protect release caches. Archival remains an independent
prerequisite, and R2 upload credentials are not exposed to desktop preparation.
Strict consumption means no dependency acquisition, not offline signing.
Timestamp services, Azure signing, Apple notarization and publication remain
online operations. Validate unsigned packaging with dependency networking denied
on each target, then verify signed installers and launchers on their native hosts.
macOS packaging retains the caller's login `HOME` for keychain import and signing.
An explicit keychain path does not make Security.framework work under a scratch
home. Dependency preparation and product compilation still use the isolated home.
Hermes state and explicit dependency-cache paths remain build-owned during packaging.
## Commit-only builds
To preview a build for a pushed revision, run:
```sh
python scripts/release.py --build-commit REV --remote origin
```
The command fetches the remote and resolves `REV` to a full commit SHA.
It prints the dispatch command without changing local branches, tags, or releases.
Add `--publish` to dispatch that build. This flag does not publish a release
in commit-build mode.
Use repeatable `--bundle-env NAME=VALUE` options to bake non-secret runtime
defaults into the desktop app, for example:
```sh
python scripts/release.py --build-commit REV --remote fork --publish \
--bundle-env HERMES_GUEST_ONBOARDING=1 \
--bundle-env HERMES_DATA_DIR_SUFFIX=magic-test \
--bundle-unset HERMES_HOME
```
These defaults run before Electron initializes its paths and are inherited by
local backend processes. Explicit runtime environment values win, including
empty values. Do not pass secrets: the values are visible in the workflow inputs
and packaged JavaScript. This option affects desktop bundles, not Termux.
The suffix is appended literally; include a leading hyphen if desired.
`--bundle-unset NAME` explicitly clears an inherited value at app launch, even
if the caller supplied it. Internally it sets the value to an empty string, not
an absent key. Clearing `HERMES_HOME` also disables the Windows registry fallback:
older installers saved that variable permanently, which otherwise takes priority
over the test suffix. It does not edit the registry or the existing install.
For full data-path isolation, also clear `HERMES_DESKTOP_USER_DATA_DIR` if that
machine uses an explicit Electron directory. Ordinary defaults still preserve
runtime overrides; `--bundle-env HERMES_HOME=` is a default, not a forced clear.
For local commit builds, `HERMES_BUNDLE_ENV_JSON` accepts a JSON object whose
string values are defaults and whose `null` values are explicit clears. For example,
`{"HERMES_HOME":null,"HERMES_DATA_DIR_SUFFIX":"magic-test"}`. Only
`HERMES_HOME`, `HERMES_DATA_DIR_SUFFIX`, `HERMES_DESKTOP_USER_DATA_DIR`,
`HERMES_SHARED_AUTH_DIR`, `HERMES_GUEST_ONBOARDING`, and `HERMES_SKIP_INTRO`
are accepted. Process-control variables such as `NODE_OPTIONS` and `PATH`
are rejected. These settings are not applied to the build runner itself.
Commit archive keys still use the SHA, so use a fresh commit for different
defaults: an existing artifact is never overwritten with different bytes.
The workflow must exist on the repository's default branch. Admission requires
a default-branch `workflow_dispatch` and repository write, maintain, or admin
permission for both the original actor and the actor who reruns it.
It rejects mixed tag, release-phase, channel-publication, and upgrade inputs.
Builder jobs check out the admitted SHA. Their artifacts and completion receipts
go to `releases/commit/FULL_SHA/`, separate from tag archives and update channels.
The run summary lists Windows sideload packages and their universal bundle, macOS DMG/ZIP
files, and the Termux package. Linux release legs remain disabled and are listed
as not built. Only receipt-listed artifacts that exist in storage get download
links. Missing receipts show the failed or incomplete leg.
Each commit build also writes a downloads page to
`releases/commit/<FULL_SHA>/index.html` on the R2 public origin; a tag run
writes its channel page instead (`releases/stable/index.html` or
`releases/canary/index.html`). Pages list only objects the build actually
staged, and a re-run of an older tag never replaces a newer channel page.
`release.py --build-commit` prints the commit page URL before dispatching.
Commit builds require the signing credentials used by their release legs.
They do not produce Store packages or submit to Partner Center. No GitHub
release, updater feed, or APT channel is changed.
An identical upload retry can succeed. Different bytes at an existing commit
object key fail rather than replace that object.
For a local native build, check out the exact SHA and run:
```sh
python scripts/bundles/desktop.py --commit=FULL_SHA --variant=bundled
```
The builder uses that commit's project version. Sideload MSIX versions append
`.0`. The shared MSIX version helper can derive Store versions from commit timestamps,
but this desktop preparation interface only admits Store packaging for stable tags.
Commit-built stamps disable automatic release-channel updates. Local command and transport tests do not
replace signed-package installation and update acceptance on each native host.
## Windows signing and App Installer
The signing jobs provide `AZURE_SIGN_ENDPOINT`, `AZURE_SIGN_ACCOUNT`,
`AZURE_SIGN_PROFILE`, `AZURE_SIGN_PUBLISHER`, and `AZURE_CLIENT_ID`, plus
Azure authentication. Do not pass publisher names through shell-split `-c`
arguments. Local unsigned builds are not release-acceptance artifacts.
The packaging hooks sanitize invalid PE certificate tables, then sign and
timestamp payload EXEs/DLLs. The product EXE receives its signature after
resource edits. `scripts/sign-msix.mjs` signs the sideload package envelope.
Store package envelopes remain unsigned for Partner Center to sign.
Unchanged payload files reuse verified signatures from
`${ELECTRON_BUILDER_CACHE}-payload-signatures`. The key binds input bytes,
Azure policy, signing tools, and timestamp policy. Filenames and release
versions do not determine identity. A hit must match executable content and
pass Authenticode publisher/timestamp checks. Invalid entries become misses.
The product EXE and package envelopes still receive fresh signatures.
The `before-build.mjs` hook generates MSIX extensions from payload launcher
names. One execution-alias extension carries the CLI aliases. The manifest
also registers the Copilot hardware-key provider. Its minimum Windows version
is part of the package contract.
The release job combines only matching sideload packages from both architectures.
Store packages never enter the sideload bundle. It publishes bundle bytes before
the channel descriptor at `releases/win32/CHANNEL/CHANNEL.appinstaller`.
Light uses `releases/win32/light/CHANNEL/`.
Windows records the descriptor source at installation. The app checks that
registered source through WinRT and distinguishes an unknown result from no
update. Apply downloads the descriptor before teardown, then opens the local
`.appinstaller` file. It does not require the disabled `ms-appinstaller:` protocol.
The app registers a detached relaunch waiter before handoff.
The build stamp declares `updateMechanism`: `app-installer` for sideload bundles,
`microsoft-store` for Store builds, `electron-updater` for macOS packages, and
`self` for source-built apps. Settings shows Microsoft Store for a Store build.
The runtime does not infer Store ownership from Electron flags or carry a
second Store boolean. Windows Light declares `external` because it has no
bundled Python checker. Its OS-registered App Installer source still owns
automatic updates.
Store builds use `Windows.Services.Store.StoreContext` to check, download,
and request installation inside Hermes. The native consent UI attaches to the
current desktop window. Download finishes before backend shutdown; the existing
relaunch waiter is registered before the install request. Unknown checks,
cancellation and request failures do not count as successful updates. Native
acceptance requires a Store-acquired package or flight, not a sideloaded MSIX.
On Windows bundles, PM copies the verified pinned base Python to its writable
store for uv builds. The app and execution aliases retain their signed bundled
launchers and bundled Python, which load the selected dependency generation.
The new venv's generated console scripts must not replace those launchers:
out-of-package Python cannot launch the packaged tools.
Sideload stable versions are `X.Y.Z.0`. Canary revisions derive from elapsed
minutes after the stable baseline. The release script rejects ambiguous or
overflowing cuts. Store versions use `year.hour-of-year.second-of-hour.0` in UTC,
with the fourth component reserved for Microsoft. App semver and package
version are different facts. `scripts/msix-shared.mjs` owns these derivations.
## macOS signing and updates
`CSC_LINK` and `CSC_KEY_PASSWORD` supply the Developer ID identity.
The notarization hook accepts `APPLE_API_KEY`, `APPLE_API_KEY_ID`, and
`APPLE_API_ISSUER`, or a keychain profile. CI materializes the API key from
`APPLE_API_KEY_P8`.
The app and nested Mach-O binaries, including Chromium, must be signed before
notarization. The existing after-sign hook owns submission and stapling.
Publication checks signatures, the stapled ticket, and Gatekeeper assessment.
Unsigned local builds do not satisfy these gates.
Both DMG and ZIP artifacts are required by the release pipeline. The ZIP is
the update artifact, not an optional duplicate of the download DMG.
See [macOS bundle updates](../../docs/macos-bundle-updates.md) for feed validation
and native-event ordering.
### DMG detach diagnostics
The builder wrapper reports `[dmg-detach]` snapshots when dmgbuild cannot detach
its staging image. It runs `lsof` before the supplier retries or performs forced
cleanup. The snapshot identifies the mounted filesystem, backing image and
devices, then lists process names, PIDs, parent PIDs, users, descriptors and paths.
The queries use noninteractive `sudo` when available. Permission failures and
query timeouts are reported explicitly. Empty output does not prove that the
image has no holder. The shim does not stop processes or change detach results,
retry settings, signing or notarization. Explicit `CUSTOM_DMGBUILD_PATH`
overrides outside the prepared path are not an escape hatch for strict builds.
Prepared packaging supplies the admitted dmgbuild path to the diagnostics shim.
Changes to its preparation provider need native DMG/detach and
signing/notarization acceptance; a successful download is not native execution proof.
## Development, assets, and verification
Prepare and activate the [PM developer environment](../../website/docs/reference/package-management.md#developer-workflow)
first. Use Bash `source ./activate` or PowerShell `. .\activate.ps1`, and keep a
separate development home. Activation supplies the toolchain, not `node_modules`.
From the repository root:
```sh
npm ci
npm run dev --workspace apps/desktop
```
For an ordinary package of that desktop build, use the workspace's
`dist:win`, `dist:mac`, `dist:linux`, or `pack` command. Those commands do not
replace the complete tagged build described above.
Icons are generated from `assets/nous-girl-*.svg` and `assets/backgrounds/`.
`node scripts/generate-icons.mjs` renders them with the Hermes runtime Python
(`HERMES_PYTHON`, else `python` on PATH); Pillow and resvg-py are core
dependencies. Generated PNG/ICO/ICNS files are not source assets.
[Stable release admission](../../docs/stable-releases.md) requires the full
pipeline, not just successful packaging. Native signed-package update tests
live in the [existing install/update family](../../tests/install/BUNDLED_UPDATES.md).
A helper test or unpacked-app smoke is not proof of native install, update,
or automatic relaunch. Historical receipts and current unresolved gates are
separate in [PM audit status](../../docs/pm-audit-status.md).