Skip to content

feat(installer): bundle Lemonade Server MSI into Windows installer (#774) - #781

Merged
itomek merged 3 commits into
mainfrom
feat/issue-774-bundle-lemonade-msi
Apr 16, 2026
Merged

itomek merged 3 commits into
mainfrom
feat/issue-774-bundle-lemonade-msi

Conversation

@itomek

@itomek itomek commented Apr 15, 2026

Copy link
Copy Markdown
Collaborator

Changes

  • NSIS (installer/nsis/installer.nsh): customInstall macro now embeds lemonade-server-minimal.msi into \$PLUGINSDIR (auto-cleaned on exit) and runs msiexec /i ... /qn /norestart. Exit codes 0/1638/3010 are logged as success; any other code is logged via DetailPrint but the GAIA install is never aborted. Includes LogicLib.nsh and the generated installer/version.nsh at file scope (using \${BUILD_RESOURCES_DIR} since electron-builder runs makensis from a temp directory).
  • CI (.github/workflows/build-installers.yml): three new Windows-only steps — generate installer/version.nsh from src/gaia/version.py, download the pinned Lemonade MSI from GitHub Releases (version parsed via shell grep; size sanity-checked ≥50MB), and post-build verify-bundled step that is warn-only when 7z can't list (NSIS solid compression) and only fails when 7z succeeds but the MSI is absent. src/gaia/version.py added to the path filter so CI re-runs when LEMONADE_VERSION is bumped.
  • Tests: TestEnsureLemonadeInstalledSkipsWhenPresent (4 cases: target / newer / older-above-min / older-below-min) and TestLegacyFallback lock in gaia init's skip-when-installed behavior for AC4/AC5. TestLemonadeProductCodeUninstall verifies --purge-lemonade uses registry-based msiexec /x {ProductCode} regardless of install origin (AC6).
  • Drive-by Linux fix (src/gaia/installer/lemonade_installer.py): _uninstall_linux was calling apt remove lemonade but the v10.0.0+ DEB installs as lemonade-server. Found via live end-to-end testing on Ubuntu 24.04; fixed in a separate commit.
  • .gitignore: ignore installer/lemonade-server-minimal.msi (downloaded at build time, never committed).

Why

Issue #774: first-run on a fresh Windows machine should install Lemonade Server automatically so users don't hit "Lemonade not found" on first gaia chat. Keeps MSI out of the repo (downloaded per-build from upstream, pinned to LEMONADE_VERSION), uses \$PLUGINSDIR so the 150MB MSI doesn't persist on disk, and keeps GAIA install robust when Lemonade install misbehaves (graceful failure, not abort).

Acceptance criteria verified on Ubuntu 24.04

AC Status
AC1 — fresh gaia init installs Lemonade v10.0.0 ✅ DEB downloaded, lemonade-server version 10.0.0
AC4 — second gaia init detects v10.0.0 and skips ✅ "Lemonade Server found: v10.0.0 / Version is compatible"
AC6 — gaia uninstall --purge --purge-lemonade --yes removes Lemonade ✅ "uninstalled via LemonadeInstaller"; lemonade-server no longer on PATH
Unit tests 105/105 ✅
Lint (black, isort, pylint, flake8, import validation, doc version) ✅ all pass

Still to verify (joint Windows session)

  • AC2 — built .exe embeds lemonade-server-minimal.msi
  • AC3 — silent install produces lemonade-server --version → 10.0.0 on PATH
  • AC5 — already-newer Lemonade: MSI returns 1638 and GAIA continues (visible DetailPrint)
  • msiexec /x {ProductCode} uninstall path end-to-end on Windows

Notes for reviewers

  • The post-build 7z check is intentionally warn-only when 7z l itself fails — NSIS solid compression can prevent entry listing, which would otherwise produce false-negative CI failures. Compile-time guarantee is the NSIS File directive: if the MSI wasn't present at build time, makensis would have aborted the build.
  • \${BUILD_RESOURCES_DIR} is the right include path, not a bare relative path. electron-builder runs makensis from a generated temp directory, so bare installer\version.nsh would fail to resolve — this macro is what the existing File directive also uses and is documented in electron-builder's NsisTarget.
  • No Python production code changes were needed for the skip-when-installed behavior — _ensure_lemonade_installed() + _check_version_compatibility() already handled all four states correctly. The new tests lock that in.

Resolves #774

itomek added 2 commits April 15, 2026 09:47
)

- CI (Windows only): download pinned lemonade-server-minimal.msi from
  upstream GitHub Releases before the electron-builder NSIS build.
  Version is read from LEMONADE_VERSION in src/gaia/version.py via shell
  grep; installer/version.nsh is generated first so NSIS can reference
  ${LEMONADE_VERSION} in DetailPrint messages.

- NSIS (installer/nsis/installer.nsh): extend customInstall to embed the
  MSI via File directive (extracted to $PLUGINSDIR — auto-cleaned on exit)
  and run msiexec /i /qn /norestart with graceful failure semantics:
  exit codes 0/1638/3010 are logged as success; any other code is logged
  via DetailPrint but Abort is never called so GAIA always installs.

- Tests: verify the existing LemonadeInstaller skip-when-installed logic
  covers all four states (not installed / target / older / newer version),
  lock in the gaia init fallback path (AC5), and confirm --purge-lemonade
  uses registry-based msiexec /x regardless of install origin (AC6).

Resolves #774
…n Linux

The DEB package installs as 'lemonade-server' (v10.0.0+ naming), but
_uninstall_linux was trying to remove 'lemonade' — causing apt to fail
with "Unable to locate package lemonade" on gaia uninstall --purge-lemonade.

Caught during live end-to-end testing on Ubuntu 24.04.
@github-actions github-actions Bot added installer Installer changes devops DevOps/infrastructure changes tests Test changes labels Apr 15, 2026
…trap)

The -minimal MSI is a small bootstrap installer (~4.5MB for v10.0.0) that
fetches the Lemonade runtime on first use; my original 50MB threshold and
"~150MB" comment were wrong and failed the Windows build. Guard against
truly-truncated downloads (<1MB = not even an MSI header, could be a 404
HTML body) instead of pinning to a specific upstream size that varies
between minor releases. Also corrected the NSIS comment.

Caught by CI on PR #781 first run.
@itomek
itomek marked this pull request as ready for review April 15, 2026 19:13
@itomek
itomek requested a review from kovtcharov-amd as a code owner April 15, 2026 19:13
@itomek itomek self-assigned this Apr 15, 2026
@itomek
itomek enabled auto-merge April 16, 2026 17:11
@itomek
itomek added this pull request to the merge queue Apr 16, 2026
Merged via the queue into main with commit 52946a7 Apr 16, 2026
36 checks passed
@itomek
itomek deleted the feat/issue-774-bundle-lemonade-msi branch April 16, 2026 17:12
kovtcharov added a commit that referenced this pull request Apr 17, 2026
Two plan documents described work that has since shipped — they were
creating confusion about what's current vs what's still planned.

Deleted
- docs/plans/installer.mdx — `gaia init`, `gaia uninstall --purge*`, and
  the bundled Lemonade MSI installer (#774, #781) have all shipped in
  v0.17.x. The remaining aspirational pieces (`gaia update`, one-liner
  install scripts) are better tracked in the active
  [desktop-installer.mdx](./desktop-installer.mdx) plan.
- docs/plans/mcp-client.mdx — the MCP Client Mixin shipped in v0.15.4
  (see `src/gaia/mcp/mixin.py`). Tracked on the roadmap as "shipped".

Navigation + cross-refs updated
- docs.json: removed the two orphan pages from Roadmap → Infrastructure.
- docs/plans/desktop-installer.mdx: replaced four references to the deleted
  installer.mdx with generic pointers to the CLI install path / dev.mdx.
- docs/plans/cua.mdx: "MCP Client Mixin Plan" link → /sdk/infrastructure/mcp
  with a note that the base mixin shipped in v0.15.4.
- docs/plans/setup-wizard.mdx: "Desktop installer via NSIS" link now points
  to desktop-installer.mdx (was installer.mdx).
- docs/plans/oem-bundling.mdx: related-plans pointer updated.
- docs/roadmap.mdx: "Detailed plan: Installer" → desktop-installer.
- docs/sdk/packaging.mdx: "Lightweight Installer Plan" → desktop-installer.
- docs/guides/install.mdx: "Python CLI install plan" pointer → dev.mdx.

Link check passes (751/751).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@itomek itomek mentioned this pull request Apr 20, 2026
5 of 6 tasks
github-merge-queue Bot pushed a commit that referenced this pull request Apr 20, 2026
# GAIA v0.17.3 Release Notes

GAIA v0.17.3 is an extensibility and resilience release. You can now
package your own agents into a custom GAIA installer and seed them on
first launch, point GAIA at alternative OpenAI-compatible inference
servers from the C++ library (Ollama, for example), and start from three
new reference agents (weather, RAG Q&A, HTML mockup) that execute
against real Lemonade hardware in CI. It also hardens the RAG cache
against an insecure-deserialization class of bug (CWE-502) — all users
should upgrade.

**Why upgrade:**
- **Ship your own GAIA** — Export and import agents between machines,
follow a new guide to produce a custom installer that seeds your agents
on first launch, and on Windows install everything in one step because
the installer now includes the Lemonade Server MSI.
- **Work with alternative inference backends** — The C++ library now
preserves OpenAI-compatible `/v1` base URLs instead of rewriting them to
`/api/v1`, so servers that expose the standard `/v1` path (Ollama, for
example) work out of the box.
- **Start from a working example** — Three new reference agents (weather
via MCP, RAG document Q&A, HTML landing-page generator) with integration
tests that actually execute against Lemonade on a Strix CI runner.
- **Safer RAG cache** — Replaces `pickle` deserialization with JSON +
HMAC-SHA256 (CWE-502). Unsigned or tampered caches are rejected and
transparently rebuilt on the next query.
- **Better document handling** — Encrypted or corrupted PDFs now produce
distinct, actionable errors (`EncryptedPDFError`, `CorruptedPDFError`)
instead of generic failures, and the RAG index is hardened for
concurrent queries.

---

## What's New

### Custom Installers and Agent Portability

You can now package a custom GAIA installer that ships with your own
agents pre-loaded, and move agents between machines with export/import
(PR #795). On Windows, the official installer now includes the Lemonade
Server MSI and runs it during install, so a fresh machine has the
complete local-LLM stack after a single download (PR #781).

**What you can do:**
- Export an agent from `~/.gaia/agents/` to a portable bundle with `gaia
agents export` and import it on another machine with `gaia agents
import`
- Follow the new custom-installer playbook at
[`docs/playbooks/custom-installer/index.mdx`](/playbooks/custom-installer)
to distribute GAIA with your agents pre-loaded — useful for workshops,
team deployments, and internal tooling
- On Windows, the installer now includes Lemonade Server — no separate
download for a complete first-run experience

**Under the hood:**
- `gaia agents export` / `gaia agents import` CLI commands round-trip
agents between machines as portable bundles
- First-launch agent seeder
(`src/gaia/apps/webui/services/agent-seeder.cjs`) copies
`<resourcesPath>/agents/<id>/` into `~/.gaia/agents/<id>/` the first
time the app starts
- Windows NSIS installer embeds `lemonade-server-minimal.msi` into
`$PLUGINSDIR` and runs it via `msiexec /i ... /qn /norestart` during
install (auto-cleaned on exit)

---

### Broader Backend Compatibility in the C++ Library

The C++ library now preserves OpenAI-compatible `/v1` base URLs (PR
#773) instead of rewriting them to `/api/v1`. That means inference
servers that expose the standard OpenAI `/v1` path — for example, Ollama
at `http://localhost:11434/v1` — work out of the box without needing a
special adapter.

---

### Reference Agents and Real-Hardware Integration Tests

Three new example agents and a Strix-runner CI workflow land together
(PR #340).

**What you can do:**
- Copy `examples/weather_agent.py`, `examples/rag_doc_agent.py`, or
`examples/product_mockup_agent.py` as a starting point for your own
agents
- Run the new integration tests locally against Lemonade to validate
agents end-to-end, not just structurally

**Under the hood:**
- `tests/integration/test_example_agents.py` executes agents and
validates responses with a 5-minute-per-test timeout
- `.github/workflows/test_examples.yml` runs on the self-hosted Strix
runner (`stx` label) with Lemonade serving `Qwen3-4B-Instruct-2507-GGUF`
- Docs homepage refreshed with a technical value prop ("Agent SDK for
AMD Ryzen AI") and MCP / CUA added to the capabilities list

---

### Smarter PDF Handling in RAG

Encrypted and corrupted PDFs now surface as distinct, actionable errors
(`EncryptedPDFError`, `CorruptedPDFError`, `EmptyPDFError`) instead of
generic failures or silent 0-chunk indexes (PR #784, closes #451).
Encrypted PDFs are detected before extraction; corrupted PDFs are caught
during extraction with a clear message. Combined with the
indexing-failure surfacing in PR #723, you get a visible indexing-failed
status the moment a document fails — and the RAG index itself is now
thread-safe under concurrent queries (PR #746).

---

## Security

### RAG Cache Deserialization Replaced with JSON + HMAC

Fixes an insecure-deserialization issue in the RAG cache (CWE-502, PR
#768). Previously, cached document indexes were serialized with Python
`pickle`; if an attacker could write to `~/.gaia/` — via a shared drive,
a sync conflict, or a malicious extension — loading that cache could
execute arbitrary code.

v0.17.3 replaces `pickle` with signed JSON: caches are now serialized as
JSON and authenticated with HMAC-SHA256 using a per-install key stored
at `~/.gaia/cache/hmac.key`. Unsigned or tampered caches are rejected
and transparently rebuilt on the next query. Old `.pkl` caches from
previous GAIA versions are ignored and re-indexed the next time you
query a document.

**You should upgrade if you** share `~/.gaia/` across machines (Dropbox,
iCloud, network home directories), run GAIA in a multi-user environment,
or have ever imported RAG caches from another source.

---

## Bug Fixes

- **Ask Agent attaches files before sending to chat** (PR #725) —
Dropped files are indexed into RAG and attached to the active session
before the prompt is consumed, so the model sees the document on the
first turn instead of the second.
- **Document indexing failures are surfaced** (PR #723) — A document
that produces 0 chunks now raises `RuntimeError` in the SDK and surfaces
as `indexing_status: failed` in the UI, instead of looking like a silent
success. Covers RAG SDK, background indexing, and re-index paths.
- **Encrypted or corrupted PDFs produce actionable errors** (PR #784,
closes #451) — RAG now raises distinct `EncryptedPDFError` and
`CorruptedPDFError` exceptions instead of generic failures, so you see
exactly what went wrong.
- **RAG index thread safety hardened** (PR #746) — Adds `RLock`
protection around index mutation paths and rebuilds chunk/index state
atomically before publishing it, so concurrent queries read consistent
snapshots and failed rebuilds no longer leak partial state.
- **MCP JSON-RPC handler guards against non-dict bodies** (PR #803) — A
malformed JSON-RPC payload (array, string, null) now returns HTTP 400
`Invalid Request: expected JSON object` instead of an HTTP 500 from a
`TypeError`.
- **File-search count aligned with accessible results** (PR #754) — The
returned count now matches the number of files the tool actually
surfaces, instead of a pre-filter total that over-reported results the
caller could not access.
- **Tracked block cursor replaces misplaced decorative cursor** (PR
#727) — Fixes the mis-positioned blinking cursor in the chat input box,
which now tracks the actual caret position via a mirror-div technique.
- **Ad-hoc sign the macOS app bundle instead of skipping code signing**
(PR #765) — The `.app` bundle inside the DMG now carries an ad-hoc
signature, so Gatekeeper presents a single "Open Anyway" bypass in
System Settings instead of the unrecoverable "is damaged" error. Full
Apple Developer ID signing is still being finalized.

---

## Release & CI

- **Publish workflow: single approval gate, no legacy Electron apps**
(PR #758) — Removed the legacy jira and example standalone Electron apps
from the publish pipeline; a single `publish` environment gate governs
PyPI, npm, and installer publishing.
- **Claude CI modernization** (PR #797, PR #799, PR #783) — Migrated all
four `claude-code-action` call sites to `v1.0.99` (pinned by SHA, fixes
an issue-handler hang), bumped `--max-turns` from 20 to 50 on both
`pr-review` and `pr-comment` for deeper analysis, upgraded to Opus 4.7,
standardized 23 subagent definitions with explicit when-to-use sections
and tool allowlists, and added agent-builder tooling (manifest schema,
`lint.py --agents`, BuilderAgent mixins).

---

## Docs

- **Roadmap overhaul** (PR #710) — Milestone-aligned plans with
voice-first as P0 and 9 new plan documents for upcoming initiatives.
- **Plan: email triage agent** (PR #796) — Specification for an upcoming
email triage agent.
- **Docs/source drift resolved** (PR #794) — Fixed broken SDK examples
across 15 docs, rewrote 5 spec files against the current source
(including two that documented entire APIs that don't exist in code),
added 20+ missing CLI flags to the CLI reference, and removed 2
already-shipped plan documents (installer, mcp-client).
- **FAQ: data-privacy answer clarified for external LLM providers** (PR
#798) — Sharper guidance on what leaves your machine when you point GAIA
at Claude or OpenAI.

---

## Full Changelog

**21 commits** since v0.17.2:

- `6d3f3f71` — fix: replace misplaced decorative cursor with tracked
terminal block cursor (#727)
- `874cf2a3` — fix: Ask Agent indexes and attaches files before sending
to chat (#725)
- `4fa121e2` — fix: surface document indexing failures instead of silent
0-chunk success (#723)
- `34b1d06e` — fix(ci): ad-hoc sign macOS DMG instead of skipping code
signing (#765)
- `7188b83c` — Roadmap overhaul: milestone-aligned plans with
voice-first P0 and 9 new plan documents (#710)
- `1beddac5` — cpp: support Ollama-compatible /v1 endpoints (#773)
- `cf9ac995` — fix: harden rag index thread safety (#746)
- `1c55c31b` — fix(ci): remove legacy electron apps from publish, single
approval gate (#758)
- `52946a7a` — feat(installer): bundle Lemonade Server MSI into Windows
installer (#774) (#781)
- `e96b3686` — ci(claude): review infra + conventions + subagent
overhaul + agent-builder tooling (#783)
- `058674b5` — fix(rag): detect encrypted and corrupted PDFs with
actionable errors (#451) (#784)
- `7bcb5d51` — fix: replace insecure pickle deserialization with JSON +
HMAC in RAG cache (CWE-502) (#768)
- `a5167e5f` — fix: keep file-search count aligned with accessible
results (#754)
- `da5ba458` — ci(claude): migrate to claude-code-action v1.0.99 + fix
issue-handler hang (#797)
- `03f546b9` — ci(claude): bump pr-review and pr-comment --max-turns 20
-> 50 (#799)
- `4119d564` — docs(faq): clarify data-privacy answer re: external LLM
providers (#798)
- `0cfbcf41` — Add example agents and integration test workflow (#340)
- `c4bd15fb` — docs: fix drift between docs and source (docs review pass
1 + 2) (#794)
- `407ed5b8` — docs(plans): add email triage agent spec (#796)
- `06fb04a4` — fix(mcp): guard JSON-RPC handler against non-dict body
(#803)
- `880ad603` — feat(installer): custom installer guide, agent
export/import, first-launch seeder (#795)

Full Changelog:
[v0.17.2...v0.17.3](v0.17.2...v0.17.3)

---

## Release checklist
- [x] `util/validate_release_notes.py docs/releases/v0.17.3.mdx --tag
v0.17.3` passes
- [x] `src/gaia/version.py` → `0.17.3`
- [x] `src/gaia/apps/webui/package.json` → `0.17.3`
- [x] Navbar label in `docs/docs.json` → `v0.17.3 · Lemonade 10.0.0`
- [x] All 21 PRs in the range (v0.17.2..HEAD) are represented in the
notes
- [ ] Review from @kovtcharov-amd addressed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

devops DevOps/infrastructure changes installer Installer changes tests Test changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Installer: Bundle Lemonade Server into GAIA installer

2 participants