GAIA v0.21.2 Release Notes

GAIA v0.21.2 is a feature-packed patch on top of v0.21.1. A new native gaia-bash coding agent joins the lineup, the email agent gets smarter — it learns which senders matter to you and now returns a 5-bucket triage taxonomy with a concrete suggested action per message — and the desktop app now lets you roll back to a previous release whenever you want. Early Agent Hub plumbing also lands as a work in progress. The rest of the release clears a batch of email, connector, UI, and installer bugs.

Why upgrade:

• A new native coding agent — gaia-bash is a fast, self-contained C++ bash agent with an interactive TUI, CLI, REST API, and MCP server, usable on its own or from Claude Code / OpenCode.
• Your inbox, learned and better sorted — gaia email now remembers which senders matter to you and sorts mail into five intuitive buckets, each with a suggested next action.
• Roll back to a previous version anytime — Settings → About now lists published releases and rolls the app back to one you pick, pausing auto-update so it can't silently re-upgrade past your choice.
• Agent Hub — work in progress — the publish pipeline, catalog, and redesigned site are taking shape as the foundation for a hub to browse and install agents. Still in active development and not yet live.

What's New

A native bash coding agent — gaia-bash

gaia-bash joins GAIA's native C++ agents (alongside the WiFi, health, and process agents) as a fully native binary coding agent for the shell. It offers five ways to use it — an interactive TUI, a one-shot CLI query, pipe mode, an OpenAI-compatible REST API server, and an MCP stdio server, so external tools like Claude Code and OpenCode can drive it directly. It ships with file I/O, git, and shell-execution tools on the reusable C++ framework any future native agent can build on (PR #985).

Sharper inbox triage — gaia email

Triage used to return four flat buckets with no next-step. The email agent now sorts mail into five intuitive categories — URGENT, NEEDS_RESPONSE, FYI, PROMOTIONAL, PERSONAL — and attaches a concrete suggested_action (reply, archive, or none) to every message, so the result maps to how you actually clear an inbox. Spam and phishing stay independent flags, kept separate from priority (PRs #1690, #1696). Try it: gaia email.

The email agent learns your inbox — gaia email

gaia email no longer treats every inbox the same. It now profiles your mailbox and learns which senders you actually engage with, prioritizing them in future triage runs — and remembers those preferences across sessions instead of relearning from scratch each time. It all runs locally, so nothing about your mail leaves your machine (PRs #1633, #1642, #1643).

Roll back to a previous version — Agent UI

Switching back to an earlier release used to mean hunting down an old installer yourself. The Agent UI now has Settings → About → "Roll back to a previous version": pick an older published release, confirm, and the app downloads it and restarts into it. After a manual rollback it pauses auto-update so the next scheduled check can't silently re-upgrade past your choice — resume forward updates from the same panel when you're ready (PR #1711).

Recover failed document indexing — Agent UI

Documents that failed to index used to leave you with no detail and no way to retry. Failed documents now persist their last error, and a reindex API lets you retry them without re-adding the file (PR #1749).

Web research via Tavily — connector groundwork

Agents could previously only reach the web through keyless DuckDuckGo scraping. This release adds a Tavily connector and a gaia.web.tavily wrapper — proper search/extract from a single keyring-stored API key, with result caching, a credit budget, and an automatic DuckDuckGo fallback. It's not yet wired into an agent (the Knowledge Agent that consumes it lands in a later phase), so treat this as the plumbing rather than a user-facing feature (PR #1234).

Agent Hub — work in progress

The Agent Hub is moving from code toward a real service for browsing and installing agents. This release lands foundational pieces — a one-command publish pipeline producing immutable, checksummed agent versions, a catalog, and a redesigned website shared across GAIA surfaces, with gaia:// "Open in GAIA" deep links as the intended primary flow. It's still in active development and not yet live; this is the infrastructure it will run on (PRs #1564, #1705).

Bug Fixes

• Agent UI served a stale frontend after an upgrade (PR #1741) — the frontend dist path was cached at startup, so an in-place upgrade could keep serving the old UI; it's now resolved per request.
• MCP couldn't reliably activate an Agent UI session (PR #1750) — MCP→Agent UI session activation is now reliable and errors are normalized into actionable messages.
• Archive-undo dropped messages on multi-mailbox inboxes (PR #1752) — undoing an archive now restores both Outlook and Gmail messages instead of only one.
• One ungranted mailbox aborted the whole scan (PR #1753) — a single mailbox you haven't granted no longer kills triage across all your other connected mailboxes.
• Email actions could hit the wrong mailbox (PR #1735) — multi-mailbox message actions are now routed by each message's recorded source account.
• Calendar picked the wrong backend (PR #1736) — the calendar backend is now chosen by the connected, scoped provider rather than defaulting to Google.
• Quarantine-undo and slot-proposal meetings mishandled (PR #1737) — slot-proposal meetings are now detected, and undoing a quarantine restores the message to INBOX.
• File Browser row-click only previewed (PR #1734) — clicking a row in the File Browser now selects the file, not just previews it.
• Triage hung when Lemonade was down (PR #1678) — email triage now fails fast with an actionable error when Lemonade is unreachable.
• Email summary truncated by a tool docstring (PR #1668) — an oversized pre_scan_inbox docstring no longer eats into the Gemma-4-E4B summary budget.
• Agent UI broke when the hub was unreachable (PR #1698) — the Agent UI stays usable when the hub can't be reached and nothing is cached.
• Backend install failed behind a TLS-inspecting proxy (PRs #1575, #1694) — the network pre-check now trusts system/proxy CAs and honors HTTPS_PROXY, and backend install retries with --native-tls on a TLS trust failure.
• Chat runs died on New Task (PR #1656) — starting a New Task keeps existing chat runs alive and shows a running indicator.
• Forwarded grant agents imported unchecked (PR #1674) — forwarded grant agents are now validated before import.
• API debug logs leaked request bodies (PR #1679) — API debug request logging is now redacted.

Full Changelog

48 commits since v0.21.1:

• 3677a504 — feat(website): Agent Factory homepage redesign (#1730)
• 4ac6a5fd — fix(mcp): post-merge review fixes for #1750 (error envelope + session nav) (#1756)
• 5bedec4a — docs(hub): agent publishing guide + standalone-sidecar example fixes (#1713)
• c3131be0 — fix(mcp): reliable MCP->Agent UI session activation + error normalization (#1750)
• bd155faa — fix(webui): serve frontend dist resolved per-request, not cached at startup (#1741)
• bbe23cf1 — feat(documents): persist last_error + reindex API for failed docs (#1749)
• d78572a9 — fix(email): restore both Outlook and Gmail messages on archive-undo (#1738) (#1752)
• 292f7080 — fix(email): one ungranted mailbox no longer aborts the whole multi-mailbox scan (#1739) (#1753)
• 1304b222 — fix(webui): File Browser row-click selects the file, not just preview (#1734)
• aa6fa7e9 — fix(email): route multi-mailbox message actions by recorded provenance (#1707) (#1735)
• 03f88011 — fix(email): select calendar backend by connected+scoped provider, not a Google default (#1708) (#1736)
• 13bc65cf — fix(email): detect slot-proposal meetings; restore INBOX on quarantine-undo (#1709) (#1737)
• 6876369c — feat(agent-ui): in-app rollback to a previous release (#1711)
• 894d9783 — feat(email): schema 2.0 contract amendments — typed action items, usage metrics, request context (#1538/#1540/#1541) (#1696)
• a1000cfd — ci(windows): run Gemma on a persistent Lemonade server (fix Windows integration jobs) (#1733)
• aa1b4303 — docs(specs): land canonical skill auto-synthesis spec (#887) (#1732)
• d9f929db — ci(windows): pull Gemma via server API, not the lemonade CLI (#1715)
• e334b9e2 — ci(windows): pull Gemma-4-E4B instead of legacy Llama-3.2-3B-Hybrid (#1712)
• 6cc43eaf — feat(hub): auto-populate website from live hub + ship email README (#1705)
• 59359ba8 — chore(deps): bump Lemonade Server to v10.7....

GAIA v0.21.1 Release Notes

GAIA v0.21.1 is a patch release on top of v0.21.0. The headline fix unblocks NPU setup: gaia init --profile npu was failing at the model download with an HTTP 400, so no one on a Ryzen AI NPU could get set up — it now downloads, verifies, and runs inference on the NPU. The release also wires a persistent memory store into the email agent, the foundation the upcoming personalization features build on.

Why upgrade:

• NPU setup works again — gaia init --profile npu was dead on arrival, failing before any NPU user could finish setup. It now pulls the built-in model correctly and runs on the NPU.
• The email agent remembers across sessions — gaia email now boots with a persistent memory store instead of forgetting everything on restart, the groundwork for inbox personalization landing in upcoming releases.

What's New

Persistent memory for the email agent — gaia email

The email agent used to start from scratch every session — anything it learned about your inbox was wiped on restart. It now boots with a persistent memory store and the tools to read and write it, so learned state survives across runs. This is the foundation for the inbox personalization (priority senders, profiling, behavioral learning) coming in upcoming releases — triage behavior itself is unchanged in this release (PR #1632).

Bug Fixes

• gaia init --profile npu failed before any NPU user could finish setup (PR #1658) — the NPU profile pulled its built-in model with a recipe argument, which Lemonade rejects with an HTTP 400 unless you're registering a new user model. The built-in model is now pulled by name only, so the NPU profile downloads, verifies, and runs inference on the NPU. The fix also adds a testing rule so this class of fresh-install bug can't slip past a warm cache and a mocked client again.

Full Changelog

3 commits since v0.21.0:

• cc6f2f39 — docs(plans): email agent packaging milestone (npm + sidecar binaries) (#1644)
• 801a5c1d — feat(email): wire MemoryMixin into the email agent (#1114) (#1632)
• a3e86b02 — fix(init): pull built-in NPU/FLM model by name, not recipe (#1655) (#1658)

Full Changelog: v0.21.0...v0.21.1

Installation

Desktop installer (recommended for end users)

Download the installer for your platform from the assets below:

• Windows — gaia-agent-ui-*-x64-setup.exe (NSIS installer, autostart on by default)
• macOS — gaia-agent-ui-*-arm64.dmg (drag to Applications, Apple Silicon only)
• Linux — gaia-agent-ui-*-amd64.deb (Debian/Ubuntu) or gaia-agent-ui-*-x86_64.AppImage (any distro)

On first launch the app sets up its Python backend automatically (~5–10 minutes for the minimal profile, depends on your internet speed).

See the installation guide for setup details and troubleshooting.

Developer install (Python CLI)

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia

Or via npm:

npm install -g @amd-gaia/agent-ui

GAIA v0.21.0 Release Notes

GAIA v0.21.0 rounds out the email triage agent and adds scheduled tasks to the Agent UI. Email triage is no longer Gmail-only: it now reads whatever mailboxes you've connected — Gmail, Outlook, or both — tags each message with its source, and routes replies and archives back to the right account. The Agent UI gains a Schedule Manager so a prompt like "every morning, summarize my inbox" runs on its own. The rest of the release clears a stack of email, connector, packaging, and UI bugs — a Windows triage hang, crashes on bare and partner installs, hung tools that left the UI thinking forever, and wrong-mailbox routing.

Why upgrade:

• Triage Gmail and Outlook in one pass — the email agent now consolidates every connected mailbox automatically: "triage my inbox" fans out across Gmail and Outlook together, tags each message with its source, and sends from the right account — no per-mailbox picking.
• Run prompts on a schedule — describe a schedule in plain language in the Agent UI and the local agent runs your prompt on time, with each schedule's run history kept in its own chat.
• No more silent triage hang — a connector token call could leave the Agent UI stuck "thinking" with no error; tool calls are now bounded and cancel cleanly, and the underlying event-loop bug behind the Windows hang is fixed.
• gaia connectors and gaia api start on bare and partner installs — both crashed on a missing keyring; the dependency is now declared where it's used and missing it fails with an actionable message.

What's New

Triage Gmail and Outlook in one pass — gaia email

The email agent used to assume Gmail everywhere — an Outlook-only user couldn't send at all, and someone with both accounts connected could only ever scan one, with no way to tell which mailbox a message came from. Now it consolidates every connected mailbox automatically: "triage my inbox" fans out across Gmail and Outlook together, tags each message with its source, splits your message budget across them, and routes every reply, archive, and undo back to the correct account — no per-mailbox picking, and no selector to manage (PRs #1614, #1616, #1635). Sending resolves to the connected mailbox and fails loudly if it's ambiguous instead of guessing. The REST triage API also gains an engine=llm path that escalates low-confidence messages to the local model with the full email body — no more 4,000-character truncation (PR #1590). Try it: gaia email.

Schedule recurring prompts — Agent UI Schedule Manager

Running anything on a schedule used to mean reaching for tools outside GAIA. The Agent UI now has a Schedule Manager: describe the cadence in plain language ("every 30m", "daily at 9pm", "every Monday at 8am"), attach a prompt, and the local agent runs it on time — each schedule keeps its full run history in its own chat session. Malformed schedules fail loudly rather than silently never firing, and the scheduler won't boot with lost tasks (PR #1566).

LiteLLM provider — initial integration (alpha)

Groundwork for an additional LLM provider option behind GAIA's existing client abstraction. The initial LiteLLM integration has landed and registers alongside Lemonade, OpenAI, and Claude, but it is alpha and not yet validated end-to-end — treat it as experimental. Local inference on Lemonade remains the default and the supported path. Contributed by @RheagalFire (PRs #1593, #1626).

Bug Fixes

• Email Triage hung the Agent UI with no error (PRs #1589, #1591) — a connector token call made from a worker thread could leave the UI stuck "thinking" indefinitely; a persistent event-loop bridge fixes the underlying hang and every tool call is now bounded (default 180s) so a stuck tool surfaces an actionable error instead of leaking.
• gaia connectors and gaia api crashed on missing keyring (PRs #1620, #1624, #1622) — keyring was declared only in the [ui]/[dev] extras, so a bare pip install amd-gaia crashed gaia connectors, and the documented [api] partner recipe crashed gaia api at startup. keyring is now a base dependency, also added to [api], and a guarded import fails with an actionable message on stripped installs.
• Email Triage Google connection wouldn't grant (PR #1599) — the Email Triage connector grant for Google was broken; it's repaired and token failures now return actionable errors.
• Microsoft connections were invisible to generic consumers (PR #1616) — connection listing was hardcoded to Google, so the /v1/connections endpoint, the UI connectors list, and the send-budget calc all stayed Outlook-blind even when Microsoft was connected.
• Chat model got evicted by the embedder (PR #1586, by @alexey-tyurin) — a RAG embedder warm-up could unload the resident chat model; the unload is now scoped so chat stays loaded.
• File search scope wasn't shown (PR #1587, by @77652189) — the Agent UI now displays which scope a file search ran against.
• macOS auto-updater kept failing (PR #1553) — the build didn't publish a macOS .zip, so the Electron auto-updater had nothing to fetch; it's published now.
• New Task mirrored the previous session's live stream (PR #1584) — starting a new task could echo the prior session's in-flight output; fixed.
• Repeated mutation tool calls ran twice (PR #1557) — identical mutating tool calls are now deduped early so an action doesn't fire twice.
• Agent UI swallowed non-JSON error bodies (PR #1554) — apiFetch now fails loudly on a non-JSON response instead of hiding the real error.
• Init flagged SD and embedding models as "Context unverified" (PR #1558) — gaia init no longer mislabels non-chat models during setup.
• Model-cleanup command broke on Windows (PR #1559) — the CLI now emits a PowerShell-compatible cleanup command on Windows.
• Backend install gave up on transient PyPI failures (PR #1561) — the installer retries transient PyPI errors instead of failing the whole install.
• Tray icon and policy-block fixes (PRs #1555, #1556) — correctly sized per-platform tray icons that fail loud on a missing asset, and atomic chat policy-block message replacement.

Contributors

Thanks to the community members who contributed to this release:

• @RheagalFire — initial LiteLLM provider integration (alpha) (PR #1593)
• @alexey-tyurin — RAG embedder unload scoping so chat stays resident (PR #1586) and the tool-prompt cost & TTFT baseline harness (PR #1546)
• @GaetanVDB07 — improved Agent UI active-agent context (PR #1578)
• @77652189 — show file search scope in the Agent UI (PR #1587)

Full Changelog

44 commits since v0.20.1:

• dd35c385 — refactor(agent-ui): remove email mailbox selector — consolidate all connected mailboxes (#1635)
• 93755ba4 — fix(llm): correct LiteLLM embed() model override + finish #1593 review items (#1626)
• fb76ccd8 — fix(packaging): add keyring to base install_requires so gaia connectors works on bare install (#1621) (#1624)
• 08ca5aa8 — fix(connectors): actionable error when keyring missing on base install (#1622)
• 881ebcfb — feat(llm): add LiteLLM as AI gateway provider (#1593)
• 9ab7da1c — docs(email): partner-facing Capability & API Spec (v2.0) (#1619)
• 49c26661 — docs: fix stale Agent UI version and broken quickstart anchors (#1623)
• 84214104 — fix(packaging): add keyring to [api] extra so gaia api + email wheel starts (#1620)
• b14e09d6 — fix(email): wire EmailSendRequest.provider fallback + exact pre-scan budget (#1603 review) (#1616)
• f6d81e38 — chore(ci): route build_agent_package version/dist/path through env: for hardening uniformity (#1613)
• 007a486c — feat(email): connector-derived mailbox selection — multi-inbox triage + send (#1603, #1594) (#1614)
• 01cd345c — ci(agents): build & share the email agent package via a GitHub Release (#1601)
• b6726b7a — feat(agent-ui): mailbox-provider selector so Outlook users can triage from the UI (#1596) (#1600)
• e1880154 — fix(connectors): repair Email Triage Google grant + actionable token errors (#1592) (#1599)
• 0fe21871 — Improve Agent UI active agent context (#1578)
• a55e23bd — feat(email): engine=llm triage API + remove body clipping (#1452, #1539) (#1590)
• 8cd5c5cf — fix(agents): bound and cancel tool execution so hung tools fail loudly (#1591)
• 798846d7 — fix(connectors): persistent event-loop bridge to stop Email Triage UI hang (#1579) (#1589)
• d22a8fb2 — fix(e...

Interim GitHub-native share of gaia-agent-email built from 5ecf423 (the GAIA v0.21.0 release commit). This is a stable, no-login download for partner evaluation — not a PyPI release while the PyPI path is paused (#1179).

What this is

gaia-agent-email is GAIA's email triage agent packaged as a standalone wheel. It reads whatever mailboxes you've connected — Gmail, Outlook, or both — triages your inbox locally on AMD hardware, and drafts replies, archives, and undos that route back to the correct account. This 0.1.0 package tracks the email-agent capabilities shipped in GAIA v0.21.0.

What it does

• Multi-mailbox triage in one pass — "triage my inbox" fans out across every connected mailbox (Gmail and Outlook together), tags each message with its source, splits the message budget across accounts, and routes every reply, archive, and undo back to the correct mailbox — no per-mailbox picking (#1614, #1616, #1635).
• Sends resolve to the connected mailbox — sending picks the right account automatically and fails loudly if it's ambiguous rather than guessing.
• engine=llm triage API — the REST triage path can escalate low-confidence messages to the local model with the full email body — no 4,000-character truncation (#1590).
• Local-first — triage decisions run on the local LLM backend; email content stays on your machine.

Install

pip install gaia_agent_email-0.1.0-py3-none-any.whl

Requires a working GAIA install (amd-gaia) and a connected mailbox. After install:

gaia email -q "Triage my inbox"
gaia email -i                       # interactive mode

Email-relevant fixes in this build

• No more silent triage hang — a connector token call could leave the UI stuck "thinking" with no error; a persistent event-loop bridge fixes the hang and every tool call is now bounded (default 180s) so a stuck tool surfaces an actionable error (#1589, #1591).
• Google connection grant repaired — the Email Triage connector grant for Google was broken; it's fixed and token failures now return actionable errors (#1599).
• Outlook connections now visible — connection listing was hardcoded to Google, leaving /v1/connections, the UI connectors list, and the send-budget calc Outlook-blind even when Microsoft was connected (#1616).
• gaia connectors / gaia api start on bare and partner installs — keyring is now a base dependency (also added to the [api] extra) with a guarded import that fails with an actionable message on stripped installs (#1620, #1622, #1624).

Assets

• gaia_agent_email-0.1.0-py3-none-any.whl — wheel (recommended)
• gaia_agent_email-0.1.0.tar.gz — source distribution

See the full GAIA v0.21.0 notes for the complete changelog: https://github.com/amd/gaia/releases/tag/v0.21.0

GAIA v0.20.1 Release Notes

GAIA v0.20.1 is a patch release focused on bug fixes and security hardening on top of v0.20.0. It clears several crashes and regressions — a broken optional dependency that could take down every agent at import, gaia-mcp failing on a clean install, the Windows app not reopening after an auto-upgrade, and agents stopping mid-task on a step cap set too low — and tightens security with an SSRF DNS-rebind fix and a high-severity XSS dependency patch.

Why upgrade:

• No import-time crash from a broken optional dependency — if the optional RAG stack was installed but a native library couldn't load, every agent died at import even when RAG was never used. The import is now guarded.
• gaia-mcp works on a clean install — a missing base dependency made gaia-mcp fail with ModuleNotFoundError right after pip install amd-gaia. Fixed.
• Windows app reopens after auto-upgrade — an orphaned backend held a handle on gaia.exe and broke the upgrade; it's now cleared first.
• Agents don't stall mid-task — the per-step cap was hardcoded low in most places, so agents stopped on routine work; it's raised and centralized on one default.
• Security hardening — SSRF DNS-rebind protection (the IP is now pinned across check and connect) and a patched high-severity XSS dependency in the EMR dashboard.

In Progress

This release also lands groundwork for several larger features that are not yet complete and aren't enabled as headline capabilities: the email agent (phishing detection, Outlook.com mail and calendar, full-thread reading), the Microsoft/Outlook connectors, and a real-model behavior eval harness. That work is in the tree and shows up in the changelog below, but it isn't ready to ship — it will be featured in a future release once it's done.

Key Changes

Every shipped change in v0.20.1 is a bug fix or security/hardening fix on top of v0.20.0.

• Builder silently created nothing ~40% of the time (PR #1430) — The builder returned "Agent Created!" while writing nothing to disk: the model wrapped its create_agent call in a fenced JSON block, and the parser skipped all fenced JSON to avoid grabbing documentation examples, so the tool never ran. Fenced tool-call extraction is now resilient, and four UI sites that swallowed tool errors now surface them.
• Builder MCP-only flow ignored the requested persona (PR #1533, closes #1532) — The MCP-only builder flow always scaffolded the built-in placeholder persona regardless of the request; it now authors the persona the user actually asked for.
• A broken native dependency crashed every agent at import (PR #1534) — If the optional RAG stack was installed but a native library (e.g. an arch-mismatched faiss, or FFmpeg via sentence-transformers) couldn't load, gaia chat and every other agent died at import time even when RAG was never used. The import is now guarded.
• SSRF DNS-rebind hardening (PR #1299) — The pre-flight IP allow-check and the actual TCP connect did separate DNS lookups, so a host could answer the check with a public IP and the connect with an internal one. The resolved IP is now pinned and validated through a single authority.
• Agents ran out of steps mid-task (PR #1389) — The per-step cap was hardcoded low in most places (10, sometimes 5–6) while the CLI used 100, so the browser and other agents would stop on routine work and ask to be re-run with --max-steps. The cap is raised and centralized on one global default.
• Windows app wouldn't open after auto-upgrade (PR #1392) — A previous backend left a handle open on gaia.exe, so the upgrade's uv pip install --refresh failed with os error 32. The orphaned backend is now killed before upgrade.
• Memory reported the old version after upgrade (PR #1390) — System-context refresh was a pure 7-day age check with no upgrade trigger, so the memory system kept reporting the pre-upgrade version. It now refreshes on install/upgrade.
• gaia-mcp crashed on a clean install (PR #1380) — python-multipart was declared only in the api/ui extras, so a bare pip install amd-gaia left gaia-mcp failing with ModuleNotFoundError. It's now a base dependency.
• gaia init failed in uv venvs with doubled text (PR #1527) — Inside a uv-created venv, gaia init printed a garbled pip install pip install "amd-gaia" warning and silently skipped the [rag] extra. Both are fixed.
• Agent UI advertised an unreachable URL on Windows (PR #1519, closes #1471) — gaia chat --ui binds to 127.0.0.1 but advertised localhost, which can resolve to IPv6 ::1 first on Windows and fail to reach the IPv4-only listener. Advertised URLs now match the bind address.
• Two LLMs left resident when building an agent (PR #1383) — Clicking "Build a Custom Agent" loaded the larger model without evicting the pre-loaded chat model, leaving both resident. The resident model is now unloaded before the swap.
• High-severity XSS in the EMR dashboard dependency (PR #1453, closes #1420) — @remix-run/router was pulled in transitively at a version exposed to a high-severity open-redirect XSS advisory; bumped to the patched release.

Tooling, Testing & CI

• Behavior-E2E in CI on a self-hosted Strix Halo runner (PRs #1535, #1431) — the real-model behavior harness runs its steps in PowerShell on the Windows Strix Halo runner.
• Email CI gate + nightly report-mode eval (PR #1362) — a unit-test PR gate, a report-mode nightly eval, and the C++ build scaffold for email.
• Labelled email-triage corpus + baselines (PR #1322) — a 220-message synthetic corpus with ground truth replaces a 10-message stub and a baseline that had been measured against the wrong model.
• Never-auto-send guard consolidated across surfaces (PR #1360) and pre-scan cheap-counts guarantee locked (PR #1356).
• Cleared pre-existing pylint/mypy debt blocking CI (PR #1402) and fixed mcp test library shadowing + a dangling summarizer CI step (PRs #1443, #1445).
• Auto-fix opens a PR by default (PR #1391) instead of posting comment patches.
• Installer repo-root resolution locked in launcher scripts (PR #1395).
• Specs updated — dynamic tool-loader (PR #1447) and the agent skills format (PR #1399).

Full Changelog

84 commits since v0.20.0:

• 568bfc57 — feat(hub): publish agent wheels to PyPI (dual R2 + PyPI) (#1179) (#1454)
• 31c0371f — test(installer): lock repo-root resolution in bash launcher scripts (#1395)
• dcc3d69f — fix(builder): MCP-only flow with reliable persona authoring (#1532) (#1533)
• aab8f41e — ci(behavior-e2e): run steps in PowerShell on the Windows strix-halo runner (#1535)
• cec000eb — chore(deps-dev): bump electron from 42.3.0 to 42.3.3 in /src/gaia/apps/jira/webui in the jira-app-dependencies group across 1 directory (#1424)
• bf0d3e52 — chore(deps-dev): bump electron from 42.3.0 to 42.3.3 in /src/gaia/apps/example/webui in the example-app-dependencies group across 1 directory (#1423)
• 56fd1eb9 — chore(deps): bump electron from 42.2.0 to 42.3.3 in /hub/agents/python/emr/gaia_agent_emr/dashboard/electron in the emr-dashboard-dependencies group across 1 directory (#1422)
• de7c501a — fix(rag): don't let a broken native dep crash every agent import (#1534)
• 8303a1a2 — fix(security,agents): harden SSRF DNS-rebind, fail loudly, cover untested modules (#1299)
• 0721f9fe — fix(agents): raise step limit and centralize on one global default (#1389)
• 020960fa — fix(ui): kill orphaned backend before upgrade to free gaia.exe on Windows (#1392)
• 5a2e6420 — fix(memory): refresh system version facts on upgrade (#1390)
• bbf7062a — fix(deps): make python-multipart a base dependency for gaia-mcp (#1380)
• 5e6f0315 — fix(init): make extras install work in uv venvs and fix doubled pip text (#1527)
• f7fbd316 — fix(cli): advertise 127.0.0.1 for Agent UI to match bind host (#1519)
• f1533ee2 — chore(deps): bump the github-actions group across 1 directory with 4 updates (#1530)
• c477e8e8 — chore(deps): bump the agent-ui-dependencies group across 1 directory with 15 updates (#1531)
• 0c197ef3 — docs(plans): add Agent Hub 22-agent enablement spec (#1457)
• cc1e32eb — fix(deps): bump @remix-run/router to patch XSS in emr dashboard (#1420) (#1453)
• a81dd838 — docs(spec): consolidate and correct the dynamic tool-loader spec (#688) (#1447)
• 91b476e0 — test(eval): behavior-E2E harness — assert tool side-effects against real model (#1431)
• 1bc4f0ea — test+ci: fix tests/unit/mcp library shadowing and dangling summarizer CI invocation (#1443)
• dba18bb3 — ci: remove stale summarizer step from Windows and Linux workflows (#1445)
• 468c8714 — feat(email): phishing detection + reversible quarantine, CI-gated ≥90% precision (...

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.

PR #1338 completes the wiring so the selector isn't just cosmetic: choosing a device now actually switches the model and context window to that device's registered config, and requesting hardware the host doesn't have fails loudly with an actionable remedy instead of silently rebuilding on the GPU.

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.

PR #1310 (issue #1227) widens the "Active for" panel to also list agents that consume MCP servers dynamically — like the chat agent loading servers from ~/.gaia/mcp_servers.json — not only agents that statically declare REQUIRED_CONNECTORS. The chat agent now shows up as an activatable target for MCP-only connectors.

Agent Hub TUI (Alpha)

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.

PR #1366 makes the feature reachable in the Agent UI: the React file picker had kept .pptx on its unsupported-Office blocklist and rejected the upload before it reached the backend that already accepted it (issues #1072, #1291). .pptx is now in the supported set, matching the server allowlist exactly; .doc/.docx/.ppt/.xls stay blocked.

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 L...

GAIA v0.19.0 Release Notes

GAIA v0.19.0 tightens the agent loop against silent-failure regressions and continues the focused-agent split. A new gaia eval agent reliability harness exercises tool selection end-to-end against the local Agent UI MCP backend and surfaced four agent-loop bugs that previously produced silently-wrong "Task completed" answers — all four are fixed in this release. Dedicated BrowserAgent and AnalystAgent replace the ChatAgent-backed web and data profiles. Agents can now declare a REQUIRED_HARDWARE capability tier that is validated at startup against the running Lemonade server. GAIA can connect to a remote Lemonade Server protected by an API key. And a new CI job auto-implements PRs for bulletproof bug issues in parallel with the existing triage path.

Why upgrade:

• MCP tool-calling reliability framework + four framework fixes — gaia eval agent runs a user-simulator + judge against the local MCP backend; the harness uncovered and fixed silent loop-break lies, a ~85-token JSON-envelope leak in tool-calling-model prompts, a missed native-path failure check, and an over-broad eval rubric.
• Specialized agents — BrowserAgent and AnalystAgent ship as dedicated implementations behind the gaia browse and gaia analyze CLIs, replacing the monolithic ChatAgent-backed profiles.
• Hardware-requirement validation — agents can declare REQUIRED_HARDWARE and fail fast at startup when the host's device tier (CPU/iGPU/dGPU/NPU/hybrid) does not satisfy it, instead of silently degrading.
• Remote Lemonade auth — setting LEMONADE_API_KEY threads Authorization: Bearer <key> through every Lemonade-bound HTTP path; wrong/missing key surfaces an actionable error naming the variable.
• CI auto-fix for bulletproof bug issues — bug-labelled issues that meet the "1-2 files, < 50 lines, 100% confidence" bar now get an auto-implemented PR in parallel with the standard triage comment.

What's New

MCP Tool-Calling Reliability Framework

A new end-to-end eval harness lands at src/gaia/eval/runner.py (PR #718) and is invoked via gaia eval agent. The runner spawns a subprocess that acts as user-simulator + LLM judge against the live Agent UI MCP backend, exercises 10 generic scenarios (no-param, single-param, multi-step, conditional, error-handling, "no tool needed"), and produces per-tool failure rollups via analyze_failures.py. The judge rubric in judge_turn.md grades on tool selection alone for verbatim-tagged scenarios — it explicitly does not penalize the agent for underlying-service failures, which had been conflating pipeline correctness with hardware availability.

Running the harness against the agent loop immediately exposed four framework regressions, all fixed in this release:

• Silent loop-break lie. When small local models emitted just the server prefix (mcp_foo_mcp) instead of the full registered tool name, the agent retried four times and then hard-coded "Task completed with mcp_foo_mcp. No further action needed" as the final answer despite zero successful tool calls. Server-name sanitisation now strips redundant mcp tokens before namespacing, and a new Agent._build_loop_break_summary helper branches on whether the last result was an error so the user sees the actual error wording. A new AST guard in tests/unit/agents/test_agent_source_invariants.py prevents the lie-on-loop literal from reappearing.
• JSON envelope leak in tool-calling-model prompts. The {"tool": ..., "tool_args": ...} template was supposed to be suppressed for models that support native tools=[] calling, but self.model_id was assigned after _register_tools() ran, so the suppression check always returned False and ~85 redundant tokens shipped in every prompt. Moving the model_id = model_id assignment ahead of registration closes the gap; a regression test asserts the ==== RESPONSE FORMAT ==== block does not appear in a tool-calling agent's system prompt.
• Loop-break helper missed the native path. The shared helper looked at step_results[-1] to detect a failure streak, but the native-tool-call path appends to previous_outputs instead (wrapper dicts). On native callers the helper saw an empty list, missed every failure, and returned "Task completed". The fix unwraps previous_outputs at the call site; the regression test exercises the helper with a sequence of error results.
• Eval rubric conflated pipeline and hardware. Some MCP services wrap real operation failures in a status: success envelope with the failure buried in data.content[*].text. On dev hardware where vendor-side features don't all work, the judge graded the agent as failing even when it picked the right tool. The new STEP 0 in judge_turn.md overrides the rubric for verbatim-tagged scenarios — correctness = 10 if the right tool was invoked, 0 if the wrong tool was, regardless of underlying op success.

Eight new unit-test files cover the sanitiser matrix, loop-break helper, candidate-list invariant, scenario validation, and --iterations flag.

Dedicated Browser and Analyst Agents

The Agent UI's web and data entries previously routed to ChatAgent profiles, which meant they carried the full monolithic agent surface instead of the focused tool sets the use cases actually need. PR #1070 adds dedicated BrowserAgent and AnalystAgent implementations and wires the built-in web/data registrations (plus their lite variants) to them. Two new CLI subcommands ship alongside: gaia browse for the browser flow and gaia analyze for the analyst flow. Both compose the relevant tool mixins explicitly rather than inheriting everything from the ChatAgent shim.

Hardware-Requirement Validation for Agents

Agents can now declare a hardware capability tier via REQUIRED_HARDWARE = HardwareRequirement(min_device=...) (PR #1057). At agent startup, LemonadeManager.ensure_ready(required_min_device=...) queries the running Lemonade server through LemonadeClient.get_system_info() and raises HardwareRequirementError if the host's reported device tier does not satisfy the declaration. NPU-only or dGPU-only agents fail fast at construction time instead of silently degrading at first inference.

This is Phase 1 — validation only. The resolved recipe is computed and logged for debugging but is not applied to the Lemonade server startup path; a follow-up will wire the resolved recipe through if the project chooses to.

LEMONADE_API_KEY for Authenticated Remote Lemonade

Before this release, GAIA could not connect to a remote Lemonade Server protected by an API key — every request returned 401 regardless of the user's configuration. PR #1149 (closes #1139) threads LEMONADE_API_KEY (from .env or the shell environment) as Authorization: Bearer <key> through every Lemonade-bound HTTP path in GAIA: the central LemonadeClient._send_request, the four requests-bypass sites, both OpenAI-SDK constructor sites, LemonadeProvider, VLMClient, the Agent UI router (system.py), Agent UI chat helpers, the server startup probes, and the base Agent health probe.

Behaviour is fully additive — when the env var is unset, every call path behaves identically to v0.18.1. A wrong or missing key produces a fixed-string error naming LEMONADE_API_KEY (the response body is intentionally not echoed back, to avoid leaking reflected Authorization headers from misconfigured proxies).

CI Auto-Fix for Bulletproof Bug Issues

PR #1159 adds a Claude-powered auto-fix job to .github/workflows/claude.yml that runs in parallel with the existing issue-handler triage. When a new issue lands with the bug label, Claude reads the report, and if the fix passes a strict "bulletproof" bar — 1–2 files touched, fewer than 50 lines changed, 100% confidence, no hardware-dependent verification needed — it implements the change, validates with python util/lint.py and the relevant unit tests, opens a PR, and posts the PR link plus step-by-step verification instructions back on the originating issue. Bug reports that don't meet the bar still get the standard triage comment from issue-handler; the auto-fixer exits silently for the rest.

Bug Fixes

• BrowserAgent and AnalystAgent crashed instantly in the Agent UI (PR #1202) — Selecting either of the new split agents and sending any message raised AttributeError: '<Agent>' object has no attribute '_mcp_manager'. The MCP client mixin's optional attribute was never initialised on the split agents, and get_mcp_status_report() — invoked on every /api/chat/send — hit the undefined dereference. The two-layer fix adds a class-level _mcp_manager: Optional[MCPClientManager] = None on MCPClientMixin (covering every future agent that inherits it) plus explicit per-agent initialisation in the five affected agents (documenting intent at the point of use). CLI paths were unaffected — only the Agent UI's /api/chat/send triggered the bug.
• LEMONADE_BASE_URL env var normalisation (PR #1160) — Setting LEMONADE_BASE_URL to a value without the trailing /api/v1 suffix produced 404s deep in the request pipeline. The variable is now normalised on load so both http://host:8000 and http://host:8000/api/v1 resolve to the same canonical form.
• Custom agents on disk now visible to the Agent UI (PR #1138) — ~/.gaia/agents/ registrations were not surfacing to the Agent UI's agent list because the registry discovery pass skipped the disk source on cold start. The fix lists custom-directory agents alongside th...

GAIA v0.18.1 Release Notes

GAIA v0.18.1 is a patch release covering two regressions reported after v0.18.0. The first is a sweep of broken amd-gaia.ai/... documentation links across connector cards, the Agent UI splash, the agent registry, the installer, and BuilderAgent templates — every link was missing the /docs/ prefix the Mintlify site serves all content under, so 12 in-product "Learn More" / troubleshooting URLs were silently 404'ing. The second is a CSS class typo in the Agent UI ChatView top navbar that broke the right-side flex container, stacking the action icons vertically instead of laying them out horizontally.

Why upgrade:

• Documentation links resolve again — every amd-gaia.ai/... URL surfaced by GAIA (connector catalog, Agent UI server splash, agent registry error guidance, BuilderAgent templates, installer messages, WebUI metadata) now routes through the /docs/ prefix Mintlify expects. Two regression tests prevent the prefix from silently dropping again.
• Agent UI navbar action icons render horizontally — the right-side container of the ChatView top navbar referenced a CSS class that didn't exist (chat-header-right vs the defined task-header-right), so the action icons stacked vertically at all viewport widths. The one-line rename restores display: flex.

Key Changes

Both changes in v0.18.1 are bug fixes targeting regressions reported after v0.18.0 shipped.

• Broken amd-gaia.ai documentation links across multiple surfaces (PR #1061, closes #1058) — Every "Learn More", troubleshooting, and SDK doc link in src/gaia/ was pointing at a bare https://amd-gaia.ai/<path> URL that 404'd, because the Mintlify Documentation tab serves all content under /docs/. The fix inserts the missing /docs/ prefix across all 12 affected locations — the connector catalog, the Agent UI server splash, agent registry error guidance, BuilderAgent template doc-comments, installer messages, and WebUI metadata — and adds tests/unit/test_amd_gaia_urls.py plus tests/unit/connectors/test_catalog_docs_url.py so the prefix can't silently drop again.
• Agent UI top-navbar action icons stacked vertically (PR #1060, fixes #1059) — The right-side container of ChatView's top navbar (<div className="chat-header-right">) referenced a CSS class that didn't exist; the correctly defined rule providing display: flex is .task-header-right. Renaming the one JSX className restores the horizontal layout at all viewport widths without touching any other file.

Full Changelog

2 commits since v0.18.0:

• ae94190a — fix(connectors): route all amd-gaia.ai URLs through /docs/ prefix (#1061)
• 896dc203 — fix(webui): restore flex layout on top navbar right container (#1060)

Full Changelog: v0.18.0...v0.18.1

Installation

Desktop installer (recommended for end users)

Download the installer for your platform from the assets below:

• Windows — gaia-agent-ui-*-x64-setup.exe (NSIS installer, autostart on by default)
• macOS — gaia-agent-ui-*-arm64.dmg (drag to Applications, Apple Silicon only)
• Linux — gaia-agent-ui-*-amd64.deb (Debian/Ubuntu) or gaia-agent-ui-*-x86_64.AppImage (any distro)

On first launch the app sets up its Python backend automatically (~5–10 minutes for the minimal profile, depends on your internet speed).

See the installation guide for setup details and troubleshooting.

Developer install (Python CLI)

Install GAIA using pip:

pip install amd-gaia

Or using uv:

uv pip install amd-gaia

Or via npm:

npm install -g @amd-gaia/agent-ui

GAIA v0.18.0 Release Notes

GAIA v0.18.0 is a minor release centred on agent memory and composability. Agent memory v2 ships a hybrid-search second brain with automatic LLM extraction and a live observability dashboard, so sessions no longer start from blank. The ChatAgent has been decomposed into three independently composable agents — Chat, FileIO, and DocumentQA — each with a narrower surface that is easier to test and reason about. Parallel tool calls reduce multi-tool round-trips, a Telegram adapter scaffold enables Phase 0 of mobile messaging, and the RAG-on-PDF timeout that broke document Q&A with Gemma 4 in v0.17.6 is fixed. CI now enforces RAG quality baselines and prompt-size budgets so similar regressions cannot ship undetected.

Why upgrade:

• Agent memory v2 — sessions retain facts across turns via hybrid (semantic + keyword) search and automatic LLM extraction, surfaced through a live observability dashboard.
• ChatAgent split — ChatAgent, FileIOAgent, and DocumentQAAgent replace the monolithic class; each is independently testable and composable via the tools= parameter.
• RAG-on-PDF timeout fixed — document Q&A with Gemma 4 no longer times out on large PDFs; the production regression introduced in v0.17.6 is resolved.
• Parallel tool calls — agents invoke multiple tools in a single LLM turn, reducing round-trips for multi-tool workflows.
• Telegram scaffold — gaia telegram start|stop|status and per-user session isolation are in place for Phase 1 message handling.

What's New

Agent Memory v2

A second-brain memory system lands at src/gaia/agents/memory/ (PR #606) with hybrid search, automatic LLM extraction, and an observability dashboard. Memories are extracted from conversation turns using a dedicated LLM pass and stored with both semantic and keyword indices, so retrieval works even when the query phrasing differs from the stored fact. The observability dashboard (wired via the SSE streaming progress endpoint added in PR #1032) surfaces memory insertion, retrieval scores, and eviction events in real time.

Per-user memory isolation is enforced at the session layer. Memory extraction runs asynchronously after each turn so it does not add latency to the agent's response.

ChatAgent Split into Chat, FileIO, and DocumentQA

The monolithic ChatAgent has been split into three focused agents (PR #979): ChatAgent handles conversational turns only, FileIOAgent owns file reading and writing, and DocumentQAAgent owns document question-answering with RAG. All three inherit from the same Agent base and compose via the tools= parameter, so consumers that need the full capability set can compose them explicitly rather than taking everything from one class. Tests in tests/unit/test_agents_split.py cover each agent in isolation.

The existing ChatAgent API is preserved as a backward-compatible composition shim. Migration to the split agents is optional for v0.18.0; the shim will be deprecated in a future minor release.

Parallel Tool Calls

Agents now issue multiple tool calls in a single LLM turn for tool-calling models (PR #946). When the model returns an array of tool_calls in one response, the agent executes them concurrently and batches the results into a single context update. This cuts the number of Lemonade round-trips for multi-tool workflows — a file-search and web-lookup pair completes in one pass rather than two sequential turns.

Telegram Adapter Scaffold (Phase 0)

A python-telegram-bot-backed adapter lands at src/gaia/messaging/telegram.py (PR #951), with gaia telegram start|stop|status CLI subcommands and per-user session isolation via _USER_SESSIONS. Shared message ingestion helpers live in src/gaia/messaging/ingest.py. Install with the [telegram] extras group (python-telegram-bot>=20.3).

This is Phase 0 only: the scaffold and session plumbing are in place. Phase 1 will add message handling, VLM/RAG ingestion, and an allowed-users gate (tracked in #889).

Connectors: Per-MCP Toggle and Single-Writer Enforcement

Two connectors-framework improvements land together. PR #1018 adds a per-MCP enable/disable toggle to the Settings UI, letting users pause individual servers without removing them from the catalog. PR #998 enforces single-writer access at the MCP layer — concurrent writes from multiple agent sessions are serialised, and an attempt to write without holding the lock surfaces as an actionable error rather than a silent data race.

File Navigation, Web Browsing, and Write Security

FileSearchToolsMixin, a web browsing tool, and a scratchpad mixin land together in PR #495, composable into any agent via tools=["file_search"]. A write security guardrail is added at the same time: write tools check the requesting agent's allowed_paths before dispatching, so custom agents cannot write outside their declared scope. The KNOWN_TOOLS registry is updated with entries for each new mixin.

Email Agent UI and Policy Alerts

Three Email Triage Agent UI improvements ship in this release: a pre-scan triage card with in-chat Connect and session preference controls (PR #995), a dedicated pre-scan triage card component (PR #1039), and a synthetic .mbox dataset for repeatable eval runs (PR #928). Policy alert cards, notifications, and durable receipts for confirmation-gated actions land in PR #952.

Bug Fixes

• RAG-on-PDF timeouts on Gemma 4 (PR #1034, closes #1030) — Document Q&A timed out on large PDFs when Gemma 4 was the active model. The root cause was a missing prompt-size budget check at the agent level; Lemonade was receiving requests that exceeded the model's context window. The fix adds the budget check at composition time and adds CI gates (PR #1040) that enforce it on every PR.
• Envelope-level parse failure crashed SD recovery (PR #1047, closes #1023) — Malformed LLM responses at the envelope level bypassed the step-1 context in SD recovery, producing an unhandled exception. Envelope-level parse repair now falls through to a clean recovery path with step-1 context preserved.
• Windows-path tool args corrupted by backslash normalisation (PR #1027) — Tool argument paths containing Windows backslashes were double-escaped before dispatch, causing file-not-found errors for agents on Windows.
• Blender send_command hung against a persistent-connection server (PR #1026, closes #1022) — The Blender MCP adapter blocked indefinitely when the remote Blender instance kept the connection alive. A read timeout is now applied.
• gaia chat init in post-install banner (PR #1029, closes #1024) — The installer banner printed gaia chat init as the suggested first command, but that subcommand does not exist. Replaced with gaia init.
• Keyring treated as a required dependency (PR #1028) — _resolve_keyring_refs raised ImportError on systems without keyring installed, even for agents that do not use it. The import is now guarded.
• electron-builder download URLs stale (PR #953) — URLs in docs/deployment/code-signing.mdx, docs/plans/desktop-installer.mdx, and installer/nsis/installer.nsh returned 404 after electron-builder reorganised its download paths.

Tooling & Docs

• RAG eval CI gates (PR #1040, closes #1033) — Every PR now runs RAG quality baselines and a prompt-size budget check. The gates encode the lessons from the Gemma 4 RAG regression directly into the pipeline.
• Fork-PR authors now receive Claude review (PR #932) — allowed_non_write_users: "*" is set for pr-review and issue-handler jobs; prompt-injection mitigations are documented in a header comment.
• Eval runs mandated before merging LLM-affecting changes (PR #1036) — CLAUDE.md requires gaia eval agent runs against the affected category for any change touching system prompts, tool docstrings, error classification, or the default model.
• GAIA website (PR #369) — amd-gaia.ai goes live, consolidating all documentation, SDK references, and guides under a single public URL.
• Custom agent guide reorganised (PR #997) — Connectors section moved to a dedicated page; export/import workflow documented.
• Lemonade PPA docs (PR #801) — Linux install instructions now reference the Launchpad PPA and fix the v10.2.0 navbar label.
• Broken Lemonade CLI URL fixed (PR #996) — URL in docs/guides/docker.mdx was returning 404 after the Lemonade docs reorganised.
• WhatsApp adapter evaluation (PR #950) — Decision document and evalu...

GAIA v0.17.6 Release Notes

GAIA v0.17.6 is a patch release covering two new agent-side capabilities (the Email Triage Agent with Gmail, and the OAuth PKCE foundation it builds on), a settings UI card layout, and a sweep of installer fixes across Windows, macOS, and Linux that close the remaining first-launch failure modes uncovered after v0.17.5.

Why upgrade:

• Email Triage Agent with Gmail — A new EmailTriageAgent ships with 25 tools across read, organize, reply, delete, and calendar mixins; every email body stays on local Lemonade hardware, and seven destructive actions are confirmation-gated.
• OAuth PKCE foundation for connections — Self-contained gaia.connections module drives OAuth 2.0 PKCE for Google. Refresh tokens land in the OS keychain; per-agent grants live in ~/.gaia/connections/grants.json; agents can only get_access_token for scopes the user explicitly granted.
• Installer first-launch reliability — Windows and macOS installers now ship a bundled uv binary so a clean machine no longer hard-fails at ensure-uv; the AppImage adds a ~/.local/bin/gaia shim so gaia is on PATH after first launch; the Windows default-model resolution bug that fell back to Qwen instead of Gemma is fixed.
• Custom Python agents work in the Agent UI — python_factory now introspects the target class's __init__ chain and only forwards kwargs the chain accepts, so the bare super().__init__(**kwargs) pattern shipped by the agent template no longer crashes on the first message with unexpected keyword argument 'rag_documents'.

What's New

Email Triage Agent with Gmail

A new EmailTriageAgent (PR #965) lands at src/gaia/agents/email/ with 25 registered tools across five mixin layers — read (triage / list / search), organize (archive / label / star), reply (draft / send), delete (trash / restore / permanent), and calendar (RSVP / create). The agent inherits DatabaseMixin for a local SQLite undo log, so destructive actions can be reversed.

Three layers of prompt-injection defense ship together: I1 system-prompt hardening with untrusted-input delimiters, I3 per-turn batch thresholds (>5 ops or >3 senders), and I4 attack-scenario fixtures. Seven destructive tools are confirmation-gated via TOOLS_REQUIRING_CONFIRMATION. Privacy is enforced architecturally — EmailAgentConfig has no cloud-LLM field, and base_url must be local or a LEMONADE host, so every email body is processed on Lemonade.

For the eval suite, GmailBackend and CalendarBackend Protocols let the eval harness inject FakeGmailBackend(mbox_path) without touching OAuth, returning Gmail API v1 JSON shape (not stdlib email.Message). Gmail integration is the first connector to ship on the new OAuth path; Outlook/Exchange via Power Automate is planned for v0.17.7 (see docs/plans/ for the enterprise-bypass spec landed in PR #954).

OAuth PKCE Foundation for Google Connections

A self-contained gaia.connections module (PR #926) lets any GAIA caller — SDK, CLI, or AgentUI — drive the OAuth 2.0 PKCE flow for Google. Refresh tokens land in the OS keychain (macOS Keychain, Windows DPAPI, Linux SecretService); per-agent grants live in ~/.gaia/connections/grants.json; an agent can only get_access_token for scopes the user explicitly granted it.

The module is provider-agnostic by design: errors, providers (Google), pkce, store (keyring with backend allowlist + tripwire), grants ledger, async token cache (double-checked locking, 60 s expiry buffer, refresh-token rotation), aiohttp loopback flow, events Protocol, and a public API/CLI. Agent.REQUIRED_CONNECTIONS is a new ClassVar; process_query wraps tool execution in a private _agent_context contextvar so every tool body knows its agent identity. 157 tests cover the surface.

This module is the baseline for the larger Connectors framework (#927, rolling to v0.17.7) that will rename gaia.connections → gaia.connectors, add a tile UI, and unify the MCP catalog into the same surface.

Settings UI Card Layout

Settings sections in the Agent UI are now distinct outlined cards (PR #969) — 1 px border, 10 px radius, inner padding — instead of margin-separated blocks. Section headings move from 11 px to 13 px, switch from --text-muted to --text-secondary, and gain a 2 px --accent left stripe flush with the card body text, so heading and body share the same left edge. Applies to System Status, Active Model, Context Size, Custom Agents, Connectors, About, and Privacy & Data. Light and dark themes both updated.

Bug Fixes

• Custom Python agents crashed on first message (PR #974, closes #973) — Custom agents under ~/.gaia/agents/<name>/agent.py using the bare super().__init__(**kwargs) pattern from the template crashed with Agent.__init__() got an unexpected keyword argument 'rag_documents' on the first turn in the Agent UI. The UI session layer always injects four session-context kwargs (rag_documents, library_documents, allowed_paths, ui_session_id), and python_factory was forwarding them blindly to the base Agent.__init__. python_factory now introspects the target class's __init__ chain over its MRO and only forwards kwargs the chain accepts. Drops of security-relevant kwargs like allowed_paths log at WARNING per the no-silent-fallback rule.
• Windows installer failed at ensure-uv for users without uv on PATH (PR #968, by @theonlychant, closes #966) — No uv binary was ever bundled for win-x64, so the installer hard-failed on a clean machine. Windows builds now ship the pinned uv binary in vendor/uv/win-x64/, backend-installer.cjs resolves and invokes the packaged binary, and a packaged Windows rescue installer is included for recovery from a broken state.
• macOS installer failed at ensure-uv on clean Apple Silicon (PR #967, closes #941) — bundledUvPlatformKey() claimed mac-arm64 support but no CI step fetched the binary. The macOS build job now downloads pinned uv v0.5.14 (aarch64-apple-darwin), verifies the archive SHA, and places it at build/vendor/uv/mac-arm64/uv. A new dmg-structural-smoke CI job mounts the built DMG, asserts the binary is present + executable + SHA-pinned + actually runs (uv --version), and is wired into the build-complete gate so future drift fails at smoke time, not on a user's first launch.
• AppImage users hit gaia: command not found after install (PR #942, by @theonlychant, closes #782 — reported by @BlueriteSoul) — AppImage installs prompted users to run gaia init but did not place a binary on PATH. Startup now writes a gaia shell shim to $XDG_BIN_HOME or ~/.local/bin/gaia pointing to the verified gaia binary. Skips creation if gaia already exists or the shim is already present, so it never clobbers a system package.
• Windows fell back to Qwen instead of the new Gemma 4 default (PR #949, by @theonlychant, closes #948 — reported by @nuts23) — After v0.17.5 made Gemma-4-E4B the default model, the Windows model-selection logic still attempted to load Qwen, leaving the new default effectively unreachable for users who hadn't manually configured a model. Resolution logic fixed so Gemma loads correctly on Windows.

Tooling & Docs

• gaia-release skill (PR #939) — Project-local Claude skill at .claude/skills/gaia-release/SKILL.md that walks through a GAIA release end-to-end as a phased checklist with hard gates before every irreversible step (open PR, push tag, rerun CI job, post announcement). The pre-tag verification phase encodes the manual pass that caught two release-blocking bugs in v0.17.4.
• Internal-task issue template (PR #906) — Third issue template alongside bug_report.yaml and feature_request.yaml, specifically for team-internal feature work and tasks intended for coding-agent assignment. Captures Goal / Scope / Acceptance criteria / Attribution / Failure modes plus a domain dropdown matching the new domain:* label taxonomy.
• Outlook via Power Automate plan (PR #954) — Specification for an enterprise-bypass path that lets the Email Triage Agent reach Outlook/Exchange without Microsoft Graph admin gates. Implementation tracked under #961/#963 for v0.17.7.
• PR description guidance sharpened (PR #947) — CLAUDE.md now spells out the "tight and value-focused" PR description rule with anti-patterns, so AI-generated PR bodies stop copy-pasting the commit log.
• Stale macOS uv fetch removed orphan comment removed (PR #975) — Build-installers workflow cleanup.

Full Changelog

14 commits since v0.17.5:

• 7ad2efc1 — fix(agents): filter session kwargs in python_factory (#973) (#974)
• 0147c947 — ci(installer): remove stale 'macOS uv fetch removed' orphan comment (#975)
• 7df8f945 — fix(installer): bundle uv for win-x64; packaged Windows rescue installer (#968)
• fd9fc60d — fix(installer): create gaia shim in ~/.local/bin for AppImage users (#942)
• `5935bc...