Release v0.20.0

[kovtcharov-amd]

GAIA v0.20.0 Release Notes

GAIA v0.20.0 is a feature release centered on giving agents a choice of hardware and giving users finer control over what each agent can see and do. Agents can now run on CPU, GPU, or the Ryzen AI NPU, selectable per-agent from the Agent UI or the CLI. MCP connectors gain a second control axis — activations — so a granted connector's tools only land in an agent's prompt when explicitly switched on, keeping small-model tool selection sharp. A new terminal-native Agent Hub opens when you run gaia with no arguments. The email agent gets batch organize tools that turn bulk inbox work from minutes into seconds, and RAG now indexes PowerPoint files natively. Underneath the features, this release lands a large security, first-boot-robustness, and test-coverage hardening pass.

Why upgrade:

• Multi-device per-agent selection (CPU / GPU / NPU) — each agent declares the devices it supports; users pick one via the Agent UI dropdown or --device {cpu,gpu,npu}, with gaia init --profile npu handling NPU detection, FLM backend install, and model download. GPU stays the default.
• Per-agent MCP tool-visibility activations — granted connectors no longer dump every tool into every agent's prompt; activations are explicit opt-in per (connector, agent), and CLI/SDK toggles now emit the same live connector.activation.changed SSE update the UI already used.
• Agent Hub TUI — running gaia with no args opens a terminal-native hub to browse, search, launch, and manage agents in a ~21MB standalone binary with sub-200ms startup.
• 10x faster email organization — seven new batch organize tools cut bulk inbox operations from ~13 LLM round-trips to 2–3 steps (~488s → ~30–60s, ~12K → ~1.2K tokens).
• Native PowerPoint (.pptx) RAG — .pptx uploads are indexed directly (text, tables, speaker notes, plus VLM analysis of embedded images) instead of telling users to "save as PDF first."
• Security & first-boot robustness — symlink write-guard bypass closed on Python 3.10/3.11, write guardrails extended to four more file tools, and a corrupt-model misdiagnosis that triggered a destructive ~25 GB re-download is fixed.

What's New

Multi-Device Support — CPU, GPU, and Ryzen AI NPU

Before this release, GAIA inference defaulted to GPU via llama.cpp with no way to target an alternative device — users with XDNA2 NPUs had no path to power-efficient local inference, and there was no framework for per-agent device selection. PR #1252 adds that framework: each agent declares which devices it supports via DeviceConfig tuples, and users select a device per-agent through an Agent UI dropdown or the --device {cpu,gpu,npu} CLI flag.

GPU remains the default. The NPU path uses the FLM backend (gemma4-it-e2b-FLM); CPU falls back automatically with a latency warning. gaia init --profile npu handles NPU detection, FLM backend installation, and model download. Eval-verified on a Ryzen AI MAX+ PRO 395, the NPU matches or exceeds GPU output quality (personality 3/3 @ 9.5/10, context retention 4/4 @ 9.8/10) at ~24 tok/s.

Per-Agent MCP Tool-Visibility Activations

Layered on the connectors framework, PR #1219 (issue #1005) splits connector control into two independent axes: grants (credential access, already shipped) and activations (which of a connector's MCP tools land in an agent's prompt). Previously, every granted connector surfaced all of its tools to every agent that held the grant — a ChatAgent with several MCP servers granted could carry ~30 extra tool descriptions in its system prompt, bloating context and degrading small-model tool selection. Activations default to off and are opt-in per (connector, agent) pair.

PR #1309 (issue #1226) closes the loop for non-UI writes: activation toggles from gaia connectors activations activate/deactivate and direct SDK calls now emit the same live connector.activation.changed SSE update the HTTP router already sent, so the Agent UI's "Active for" panel reflects CLI/SDK changes without a manual refresh.

Agent Hub TUI

Running gaia with no arguments now opens the Agent Hub — a terminal-native hub for discovering, searching, and launching GAIA agents (PR #1186). Previously the Go TUI only supported gaia chat --subprocess <binary>; now users get a full agent browser with a dashboard, fuzzy search, voting, and agent lifecycle management in a ~21MB standalone binary that starts in under 200ms.

Faster Email Agent — Batch Organize Tools

Bulk inbox work in the email agent was expensive: marking 9 emails read took ~13 LLM round-trips (~488s, ~12K tokens) because each tool operated on a single message ID, and parallel tool-call attempts hit a generic retry prompt that could loop until max_steps exhaustion. PR #1067 adds seven batch organize tools that reduce bulk operations to 2–3 steps (~30–60s, ~1.2K tokens) — roughly 10x faster and 10x cheaper. Parallel tool-call failures now get a targeted retry prompt, the --trace/--show_stats CLI flags pass through correctly, and a new force_llm config flag enables full LLM triage of every email.

PowerPoint (.pptx) Extraction for RAG

Uploading a .pptx previously told users to save it as PDF first. PR #1224 indexes PowerPoint natively — extracting text from shapes, tables, and speaker notes, with VLM analysis of embedded images when a vision model is available. The implementation mirrors the existing PDF pipeline (same VLMClient integration, [Page N] markers, merge strategy, and metadata structure) so downstream chunking and retrieval are unchanged. A zip-bomb guard checks uncompressed size before opening (500 MB limit), and WMF/EMF metafiles are skipped gracefully since PIL cannot decode them.

Bug Fixes

• Corrupt-download misdiagnosis triggered a destructive re-download (PR #1300, closes #1294) — Ordinary model-load failures (resource limits, ctx_size, GPU/backend startup, port conflicts) all surface from Lemonade as "llama-server failed to start", and the classifier treated that generic string as file corruption. On a fresh install it sent first-boot into a destructive delete + ~25 GB re-download that couldn't fix the real problem. The bare failure is no longer mistaken for corruption — it surfaces as an actionable LemonadeClientError and the model cache is left intact.
• First-boot dead-end on a genuinely corrupt model (PR #1302, closes #1293) — When the Agent UI backend detected a corrupt model on first boot it called input("[y/N]") inside the FastAPI lifespan threadpool, which has no TTY; input() raised EOFError and left users with a broken UI requiring a manual force-redownload. The repair path is now fully non-interactive in the boot context.
• Symlink write-guard bypass on Python 3.10/3.11 (PR #1256) — Symlinks pointing into blocked directories (.ssh, C:\Windows, /etc, …) were not detected by is_write_blocked() on Python < 3.12. Surfaced by the new Python version matrix, the fix drops a redundant .resolve() so os.path.realpath is the single source of truth across versions.
• Write guardrails extended to four unprotected file tools (PR #1188, closes #955) — write_python_file, write_markdown_file, and two more tools only had basic path checks; they now enforce the same validate_write() blocklist/size validation, pre-overwrite backups, and audit logging as write_file/edit_file.
• Spinner clobbered interactive security prompts (PR #1208, issue #1089) — The CLI progress spinner kept writing on a background thread during path-access confirmation prompts, eating the first character of option labels (es / o / lways). The spinner is now paused before prompting.
• gaia init failed on Arch/Fedora and crashed on Wayland (PR #1218) — gaia init hardcoded an add-apt-repository path that fails on non-Debian distros; it now skips the PPA install when a Lemonade server is already reachable, and disables the Chromium WaylandColorManagement feature to prevent a SIGTRAP crash on Wayland compositors.
• TLS hostname preserved in pinned-IP HTTPS requests (PR #1209, issue #1207) — PinnedIPAdapter now carries the original hostname through for SNI/cert validation instead of validating against the pinned IP.
• Agent UI memory API on random backend ports (PR #1257) — memoryApi now uses the dynamic API base so it works when the backend binds a non-default port.
• Agent export no longer aborts on an unreadable directory (PR #1221) — Unreadable agent directories are skipped during export rather than failing the whole pass.
• faiss AVX fallback log noise suppressed (PR #1222) — The AVX2/AVX-512 fallback chatter faiss prints on import is now quieted.

Tooling, Testing & CI

This release lands a large test-infrastructure and CI-hardening pass:

• Codecov integration with coverage gates (PR #1245) — Unit-test runs now upload coverage.xml (py3.12 leg only) with a 60% project / 70% patch target so regressions surface before merge.
• Python version matrix + macOS smoke lane (PR #1247) — CI now exercises Python 3.10/3.11/3.12 and a macOS smoke leg, with path-filter fixes; this matrix surfaced the symlink guard bug above.
• New test coverage across the stack — Vitest + React Testing Library component infrastructure (PR #1249), llama.cpp backend integration paths (PR #1248), eval scorecard/audit/runner/judge (PR #1243), RoutingAgent/code validators/OpenAI provider (PR #1244), and doc code-example extraction + syntax validation (PR #1250).
• Installer test hardening (PR #1251) — Artifact validation and scenario parametrization for the installer suite.
• Post-publish PyPI smoke test (PR #1239) — The publish pipeline now installs the freshly published wheel from PyPI and verifies gaia --version and the console entry points.
• Dependency review scanning (PR #1246) and stricter test workflows (PR #1240, which removes || true masking and adds timeouts + log uploads).
• test_jira.py made collectable (PR #1241) and stale electron test assertions updated (PR #1210).
• mypy errors resolved across the codebase (PRs #1253 and #1296).
• Value-prop-first release notes via the gaia-release skill (PR #1330).
• Installer repo-root resolution fixed (PRs #1326 and #1332) and .claude/launch.json symlink replaced with a repo-local definition (PR #1228).

Full Changelog

44 commits since v0.19.0:

• bb9f43fa — fix(types): resolve remaining mypy errors missed by fix(types): resolve pre-existing mypy errors across 7 modules #1253 (fix(types): resolve remaining mypy errors missed by #1253 #1296)
• e8c501b0 — fix(installer): resolve repo root correctly in bash scripts under installer/ (fix(installer): resolve repo root correctly in bash scripts under installer/ #1332)
• 83255cfd — fix(installer): resolve repo root correctly in scripts under installer/ (fix(installer): resolve repo root correctly in scripts under installer/ #1326)
• 62b47c4e — docs(release): generate value-prop-first release notes from the gaia-release skill (docs(release): generate value-prop-first release notes from the gaia-release skill #1330)
• 6f8d25d2 — test(installer): add artifact validation and scenario parametrization (test(installer): add artifact validation and scenario parametrization #1251)
• 72390d82 — feat(connectors): emit connector.activation.changed for CLI/SDK activation writes (feat(connectors): emit connector.activation.changed for CLI/SDK activation writes #1226) (feat(connectors): emit connector.activation.changed for CLI/SDK activation writes (#1226) #1309)
• a12c72a2 — ci: add Python version matrix, macOS smoke lane, and path-filter fixes (ci: add Python version matrix, macOS smoke lane, and path-filter fixes #1247)
• 1f2f7ad3 — feat(rag): add PowerPoint (.pptx) extraction with VLM image support (feat(rag): add PowerPoint (.pptx) extraction with VLM image support #1224)
• cbc1af97 — test(ui): add Vitest + RTL component test infrastructure (test(ui): add Vitest + RTL component test infrastructure #1249)
• 6a29767a — test(llm): cover llama.cpp backend integration paths (test(llm): cover llama.cpp backend integration paths #1248)
• 03b98e60 — ci(coverage): add Codecov integration with 60% project gate (ci(coverage): add Codecov integration with 60% project gate #1245)
• 6c83a834 — test(agents,llm): cover RoutingAgent, code validators, OpenAI provider (test(agents,llm): cover RoutingAgent, code validators, OpenAI provider #1244)
• b5f887d1 — test(eval): cover scorecard, audit, runner, and claude judge (test(eval): cover scorecard, audit, runner, and claude judge #1243)
• 81b81f4a — fix(lemonade): auto-heal corrupt model on non-interactive boot without prompting (fix(lemonade): auto-heal corrupt model on non-interactive boot without prompting #1302)
• b10280f1 — ci(eval): disable RAG eval gate on PRs pending rebuild (ci(eval): disable RAG eval gate on PRs pending rebuild #1316)
• 2d462ef9 — fix(security): pause progress spinner during interactive security prompts (gaia docker security prompt eats first character of each option label #1089) (fix(security): pause progress spinner during interactive security prompts (#1089) #1208)
• 3ed27c31 — fix(lemonade): don't classify generic "llama-server failed to start" as a corrupt download (fix(lemonade): don't classify generic "llama-server failed to start" as a corrupt download #1300)
• b083db48 — ci(security): add dependency review scanning (ci(security): add dependency review scanning #1246)
• 29b6dcd0 — chore(deps): bump the root-npm-dependencies group across 1 directory with 6 updates (chore(deps): bump the root-npm-dependencies group across 1 directory with 6 updates #1259)
• 6d4711d2 — test(docs): add code example extraction and syntax validation (test(docs): add code example extraction and syntax validation #1250)
• 10740b9f — fix(security): resolve symlink write-guard bypass on Python 3.10 (fix(security): resolve symlink write-guard bypass on Python 3.10 #1256)
• d12c79f9 — feat(agents): multi-device support — CPU, GPU, NPU per-agent selection (feat(agents): multi-device support — CPU, GPU, NPU per-agent selection #1252)
• b068f016 — fix(tests): make test_jira.py collectable, add xdist/rerunfailures deps, add shared fixture (fix(tests): make test_jira.py collectable, add xdist/rerunfailures deps, add shared fixture #1241)
• 6980f397 — fix(ci): remove || true from test workflows, add timeouts and log uploads (fix(ci): remove || true from test workflows, add timeouts and log uploads #1240)
• f8ff144c — feat(ci): add post-publish smoke test to validate PyPI install (feat(ci): add post-publish smoke test to validate PyPI install #1239)
• 905036c5 — fix(security): apply write guardrails to four unprotected file tools (fix(security): apply write guardrails to four unprotected file tools #1188)
• 8dca462f — fix(tests): update stale electron test assertions after feat(memory): agent memory v2 — second brain with hybrid search, LLM extraction, and observability dashboard #606 UX rework (ci(electron): Test Electron Framework permanently red on main since #606 — stale chat-app assertions #1204) (fix(tests): update stale electron test assertions after #606 UX rework (#1204) #1210)
• 6de34fcd — fix(types): resolve pre-existing mypy errors across 7 modules (fix(types): resolve pre-existing mypy errors across 7 modules #1253)
• 9c7679c1 — fix(web): preserve TLS hostname in PinnedIPAdapter for HTTPS requests ([Bug]: SEARCH_WEB tool has SSLCert error #1207) (fix(web): preserve TLS hostname in PinnedIPAdapter for HTTPS requests (#1207) #1209)
• ea9de561 — fix(webui): use dynamic API base for memoryApi to support random backend ports (fix(webui): use dynamic API base for memoryApi to support random back… #1257)
• fa64caf9 — fix(logging): suppress faiss AVX2/AVX-512 fallback noise (fix(logging): suppress faiss AVX2/AVX-512 fallback noise #1222)
• d05ddc52 — Skip unreadable agent dirs during export (Skip unreadable agent dirs during export #1221)
• 4ee10b07 — ci(claude): upgrade Opus jobs from 4.7 to 4.8 (ci(claude): upgrade Opus jobs from 4.7 to 4.8 #1225)
• 459d3a63 — fix(dev): replace .claude/launch.json symlink with repo-local definition (fix(dev): replace .claude/launch.json symlink with repo-local definition #1228)
• aa2ca33f — feat(tui): Agent Hub TUI — browse, search, launch, and manage agents (feat(tui): Agent Hub TUI — browse, search, launch, and manage agents #1186)
• 1d45d896 — gaia-init-arch-wayland (gaia-init-arch-wayland #1218)
• d0e7b592 — chore(deps): bump anthropics/claude-code-action from 1.0.128 to 1.0.133 in the github-actions group (chore(deps): bump anthropics/claude-code-action from 1.0.128 to 1.0.133 in the github-actions group #1215)
• 97948f7d — feat(connectors): per-agent MCP tool-visibility activations (feat(connectors): bind MCP connectors to specific agents (per-agent activation) #1005) (feat(connectors): per-agent MCP tool-visibility activations (#1005) #1219)
• 4f2e6e5f — feat(email-agent): carry forward batch tools, force_llm, CLI wiring, and parallel-retry prompt (feat(email-agent): carry forward batch tools, force_llm, CLI wiring, … #1067)
• 74c14122 — chore(deps): bump the jira-app-dependencies group in /src/gaia/apps/jira/webui with 8 updates (chore(deps): bump the jira-app-dependencies group in /src/gaia/apps/jira/webui with 8 updates #1196)
• 7e95f5fb — chore(deps): bump the example-app-dependencies group in /src/gaia/apps/example/webui with 5 updates (chore(deps): bump the example-app-dependencies group in /src/gaia/apps/example/webui with 5 updates #1195)
• 99e73a6b — chore(deps): bump the github-actions group with 11 updates (chore(deps): bump the github-actions group with 11 updates #1200)
• 0b1b6be5 — chore(deps-dev): bump the python-dependencies group with 3 updates (chore(deps-dev): bump the python-dependencies group with 3 updates #1197)
• 298d7bd4 — chore(deps): bump electron from 35.7.5 to 42.2.0 in /src/gaia/agents/emr/dashboard/electron in the emr-dashboard-dependencies group (chore(deps): bump electron from 35.7.5 to 42.2.0 in /src/gaia/agents/emr/dashboard/electron in the emr-dashboard-dependencies group #1194)

Full Changelog: v0.19.0...v0.20.0

---

Release checklist

• util/validate_release_notes.py docs/releases/v0.20.0.mdx passes
• src/gaia/version.py → 0.20.0
• src/gaia/apps/webui/package.json → 0.20.0
• Navbar label in docs/docs.json → v0.20.0 · Lemonade 10.2.0
• All 44 commits in range (v0.19.0..HEAD) are represented in the notes
• Review from @kovtcharov-amd addressed

[github-actions]

Summary

This is a clean, well-executed release documentation PR that correctly bumps the version to 0.20.0 across all three required locations and ships accurate, value-prop-first release notes covering all 44 commits in the range. The notes follow GAIA's "lead with impact, not implementation" style consistently and the navigation wiring in docs/docs.json is correct.

Issues Found

🟢 Minor — One changelog entry lacks conventional-commits prefix (docs/releases/v0.20.0.mdx:154)

The Full Changelog entry for PR #1221 reads:

d05ddc52 — Skip unreadable agent dirs during export (#1221)

Every other entry follows type(scope): description format. This is the original commit message (this PR can't change it), so flagging it only for awareness — future commits should follow the convention.

---

🟢 Minor — Frontmatter description is 233 characters (docs/releases/v0.20.0.mdx:2)

Mintlify uses this field for SEO meta-description; most search engines truncate at ~160 characters. The v0.19.0 notes have a similarly long description (255 chars), so this is a project-wide pattern rather than an error. Trimming to ≤160 chars would improve SEO, but it's not blocking.

description: "Per-agent CPU/GPU/NPU selection, MCP tool-visibility activations, Agent Hub TUI, 10x faster email batch tools, native .pptx RAG, and a broad security and test-infrastructure hardening pass."

Strengths

• Version consistency — src/gaia/version.py, src/gaia/apps/webui/package.json, and the docs/docs.json navbar label are all bumped together; no drift between the three locations.
• Accurate changelog coverage — the Full Changelog section accounts for all 44 commits in the v0.19.0..v0.20.0 range, including the two installers fixes (fix(installer): resolve repo root correctly in scripts under installer/ #1326, fix(installer): resolve repo root correctly in bash scripts under installer/ #1332) that landed late in the cycle.
• Release notes prose quality — each section leads with the user-observable before/after state ("previously told users to save it as PDF first", "sent first-boot into a destructive delete + ~25 GB re-download"), with PR and issue links for every change, no Claude attribution anywhere, and no padded "what changed" enumeration.

Verdict

Approve. No blocking issues. The single actionable suggestion (trimming the frontmatter description) is optional. The PR is ready to merge.