feat(installer): custom installer guide, agent export/import, first-launch seeder

[itomek]

Closes #776

Summary

• Custom installer guide (docs/guides/custom-installer.mdx) — step-by-step walkthrough for OEMs/power-users building a branded GAIA installer: project scaffold, embedding a custom agent, electron-builder config, first-launch seeder, and cross-platform packaging.
• Agent export/import (src/gaia/installer/export_import.py) — zip-bundle round-trip for custom agents under ~/.gaia/agents/, with zip-bomb defenses (per-file + aggregate streaming byte counters), symlink rejection, path-traversal guards, and atomic temp-file staging.
• FastAPI endpoints (src/gaia/ui/routers/agents.py) — POST /api/agents/export and POST /api/agents/import behind three security guards: localhost-only, X-Gaia-UI header CSRF check, and tunnel-inactive check (503 when ngrok tunnel active).
• First-launch agent seeder (src/gaia/apps/webui/services/agent-seeder.cjs) — copies <resourcesPath>/agents/<id>/ into ~/.gaia/agents/<id>/ on first launch using atomic rename + .seeded sentinel; symlink-safe, crash-safe, idempotent.
• Settings UI (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx) — Export All / Import buttons in the Settings modal; credentials warning before export; best-effort pre-read of bundle.json from zip to list agent IDs in the trust confirmation modal.
• CLI (src/gaia/cli.py) — gaia agents export and gaia agents import commands.
• Playbook (docs/playbooks/custom-installer/) — annotated reference files for the guide.

Security measures

• Zip-bomb: per-file ≤ 50 MB + total ≤ 500 MB, both via streaming counters during extraction
• Symlink entries rejected (checked via external_attr upper 16 bits)
• Absolute paths and Windows drive letters rejected
• Agent IDs validated against ^[a-z0-9]([a-z0-9-]{0,50}[a-z0-9])?$ plus reserved Windows device names
• Path traversal double-checked on both pre-validation and during extraction
• Bundle manifest capped at 1 MB before pre-read in CLI
• Export/import endpoints require localhost + X-Gaia-UI header + tunnel inactive

Test plan

• tests/unit/test_export_import.py — 14 tests covering round-trip, zip-slip, symlink, absolute path, oversized entry, too-many-entries, invalid agent IDs, zero-agent export, overwrite, atomicity, missing bundle.json, wrong format version
• tests/unit/chat/ui/test_agents_router.py::TestExportImportSecurityGuards — 6 tests covering all three security guards on both endpoints
• tests/electron/agent-seeder.test.cjs — 14 Jest tests covering seeder happy path, skip-if-seeded, user-owned skip, partial cleanup, symlink skip, missing source
• All 1455 unit tests pass (40 pre-existing errors in unrelated test_uninstall_command.py)

[kovtcharov]

@claude review this PR and identify why the tests are failing.

[github-actions]

Claude finished @kovtcharov's task —— View job

---

Reviewing PR #795 — identifying test failures

• Check CI status for failing workflows
• Analyze failing test logs
• Review code changes for correctness
• Post findings

Job run · Branch

[itomek]

Integration test findings (Windows NSIS installer, commit 38a2ceb)

Ran the PR's CI-built installer end-to-end on Windows (Ryzen AI MAX+ 395). Good news: the React/Electron side is wired correctly. Bad news: Export All is broken in this build, and several supporting pieces need attention. Flagging here so Claude Code / a follow-up PR can pick them up.

1. BLOCKER — Python side of the PR never ships in the installer

build/scripts/electron-install (or the equivalent uv install step) pins amd-gaia[ui]==0.17.2 from PyPI at install time. That version on PyPI predates this PR, so none of the new Python code is present in the installed venv.

Verified directly on the installed backend:

POST /api/agents/export → 405 Method Not Allowed
POST /api/agents/import → 405 Method Not Allowed
GET  /openapi.json      → only /api/agents and /api/agents/{agent_id}

And on the CLI:

$ gaia --help
positional arguments:
  {prompt,chat,talk,summarize,blender,sd,jira,docker,api,download,stats,test,
   youtube,kill,llm,groundtruth,create-template,eval,report,visualize,perf-vis,
   generate,batch-experiment,mcp,cache,init,install,uninstall}

No agent subcommand. Running it anyway:

$ gaia agent export bob-the-zookeeper
gaia: error: argument action: invalid choice: 'agent' (choose from prompt, chat,
talk, summarize, ..., uninstall)
$ echo $?
2

Direct import confirms:

$ python -c "import gaia.installer.export_import"
ModuleNotFoundError: No module named 'gaia.installer.export_import'
$ python -c "import importlib.metadata as m; print(m.version('amd-gaia'))"
0.17.2

Installed amd-gaia==0.17.2 from PyPI does not contain the PR's Python tree — no CLI dispatcher, no export_import.py, no FastAPI route handlers.

Fix options, in order of preference:

1. Bundle the wheel with the installer (dist/amd_gaia-*.whl → extraResources, then uv pip install from the local path). Best for reproducibility and offline installs.
2. Publish a new PyPI release (e.g. 0.17.3) and bump the installer pin.
3. uv pip install "git+https://github.com/amd/gaia@<sha>#egg=amd-gaia[ui]" — couples runtime install to GitHub, slow, not ideal.

2. HIGH — Export All fails silently in the UI when backend returns non-2xx

With a custom agent present in ~/.gaia/agents/, clicking Settings → Custom Agents → Export All → OK on the confirmation dialog produces: no native save dialog, no toast, no file written. The request hits the 405 from issue #1 and the UI shows the user nothing.

The React bundle at resources/dist/assets/index-Dhf8N9tu.js does have an error path:

const g = await fetch(`${Q0}/agents/export`, {
  method: "POST",
  headers: { "X-Gaia-UI": "1" }
});
if (!g.ok) {
  const T = await g.text().catch(() => "");
  let b = T;
  try { b = JSON.parse(T); } catch {}
  // ...supposed to surface an error
}

…but whatever it dispatches on !g.ok is not visible to the user. Either the toast portal is clipped by the closing confirmation dialog, the toast duration is too short, or the error dispatch path is broken.

This is a separate bug from #1 — any failure mode (405, 500, network timeout) will look identical to the user after #1 is fixed. Please:

• Log the failing response to the renderer console unconditionally.
• Render error toasts outside the confirmation dialog's portal with a 3–5s duration and a "See details" affordance.
• Add a smoke test: mock POST /agents/export → 500, assert visible error UI.

UI wiring itself is correct — bundle targets exactly POST /agents/export and POST /agents/import with X-Gaia-UI: 1 CSRF header. No front-end rewiring needed once #1 lands.

3. HIGH — Silent install (/S) crashes in NSIS System.dll

Exception 0xC0000005 (access violation) in System.dll @ +0x1581

Reproduced twice with gaia-agent-ui-0.17.2-x64-setup.exe /S. GUI install is fine. Blocks any MDM / CI / unattended deployment. Likely an unchecked System::Call or nsExec::ExecToStack that only materializes a string argument in the UI-mode branch.

4. HIGH — gaia init Lemonade MSI race; failure is swallowed

~/.gaia/electron-install.log shows:

gaia init --profile minimal --yes
❌ Installation failed: Another MSI installation is in progress
Warning: gaia init exited with code 1. Continuing anyway.
state: ready

The installer reports state: ready even though Lemonade wasn't actually installed. First launch then shows the "Run gaia init --profile chat" banner and the user has to remediate manually.

Fixes: serialize on the MSI mutex before invoking gaia init, and/or retry on MSI 1618 with backoff. Do not swallow the failure silently — at minimum surface a dialog saying setup is incomplete.

5. MEDIUM — First-launch seeder is a no-op

~/.gaia/logs/seeder.log:

[INFO] No bundled agents directory at
  C:\Users\<user>\AppData\Local\Programs\gaia-desktop\resources\agents
  — nothing to seed

The seeder cjs is packaged inside app.asar and runs correctly; the resources/agents/ directory just isn't shipped. Either electron-builder.yml is missing an extraResources entry for build/bundled-agents/**, or the source directory is empty in CI.

Fixes:

• Check in a minimal example bundle under build/bundled-agents/ (demonstrates the feature; the docs guide in this PR needs something to point at).
• Add the extraResources entry.
• CI assert: test -d build/bundled-agents && test -n "$(ls build/bundled-agents)".
• When NODE_ENV=production and the directory is absent, log at WARN, not INFO.

6. LOW (pre-emptive) — Route ordering in gaia/ui/routers/agents.py

The existing /api/agents/{agent_id:path} wildcard will shadow the new /export and /import literals if they're registered after it. Please confirm in the router:

1. /export and /import literal routes are registered before {agent_id:path}.
2. Agent-ID validator rejects the reserved words export and import (or constrains to [a-z0-9_-]+ in a way that excludes them).
3. Test coverage includes GET /api/agents/{id} with id ∈ {"export","import"} to catch a future reorder regression.

What did work

• UI copy & conditional rendering (Export All only appears when a custom agent exists — behaving as designed).
• Confirmation dialog's security warning about API keys/tokens in agent.py being included in the bundle is a thoughtful touch.
• Native file picker for Import is correctly wired via showOpenDialog IPC.
• React bundle contains all expected endpoints, CSRF header, and the requires_restart flag handling.

---

Full report with reproduction commands and evidence available on request. Happy to re-test once any of these land.

[kovtcharov]

@claude can you review this PR?

[github-actions]

PR review — #795

CI status: all green. All 50+ checks on the latest commit (8f16d8c) are SUCCESS — there are no failing tests in CI. The earlier "why are tests failing?" was triggered when the pipeline was still running.

The real signal for reviewers in this thread is @itomek's integration report from running the actual NSIS installer end-to-end — CI passing does not mean the shipped installer works for end users.

What this PR does well 🟢

• Zip-bomb defense is correct: per-file cap and aggregate streaming byte counter during extraction (export_import.py:314-346) — a many-small-files bomb can't slip through.
• Three-guard endpoint defense (routers/agents.py:114-159): localhost + X-Gaia-UI CSRF header + tunnel-inactive. All three are independently tested.
• Atomic write protocols: export uses tempfile → os.replace on the same filesystem; import stages each agent in a tempdir then atomically moves with backup-and-restore on failure; seeder writes sentinel last so a partial copy never looks complete (agent-seeder.cjs:176-191).
• CodeQL py/stack-trace-exposure fix (export_import.py:373-386) is done at the source — os.replace exception text logged server-side, only a generic message flows into HTTP response. Clean fix.
• Test coverage is broad: 14 export/import pytests + 6 router security-guard tests + 14 Jest seeder tests.

Issues worth addressing

🟡 Integration findings from @itomek are still open

@itomek's report found 6 issues on the actual installer. Most are real blockers regardless of green CI:

#	Severity	Issue	Status
1	🔴 BLOCKER	Installer pins amd-gaia[ui]==0.17.2 from PyPI — predates this PR, so none of the new Python code ships	Unaddressed
2	🟡 HIGH	Export All fails silently in UI on non-2xx responses	Unaddressed
3	🟡 HIGH	NSIS silent install (/S) crashes in System.dll	Out of scope for this PR but blocks the playbook's unattended-deploy story
4	🟡 HIGH	gaia init swallows MSI 1618 (race); reports state: ready on failure	Out of scope but touches the installer flow this PR showcases
5	🟢 MEDIUM	Seeder is a no-op — build/bundled-agents/ is empty in the built artifact	electron-builder.yml entry exists but no source bundle exists in-repo → playbook's "install → see Zoo Agent" flow won't work out of the box
6	🟢 LOW	Route-ordering concern (see below)	Mostly fine, one small gap

#1 is the big one. Every unit test in this PR runs against source, so none of them catch that the shipped binary doesn't include the new code. Consider a CI step that posts POST /api/agents/export against the installed backend (not a TestClient in source tree) and asserts it isn't 405.

#5 is a gap between the docs and the shipped artifact. The playbook at docs/playbooks/custom-installer/index.mdx promises a preloaded Zoo Agent experience, but without a checked-in example under build/bundled-agents/, or a CI assertion that the directory is populated, the playbook works only for readers who first follow every step to create the staging dir.

🟡 PR description has drifted from code

• Body says gaia agents export / gaia agents import (plural). Actual CLI registered at cli.py:2528 is gaia agent (singular). Docs also use singular. Please update the PR body to match.
• Body still advertises "Custom installer guide" but commit 8f16d8c reverted that file — only the playbook remains. Either rename the PR to feat(installer): agent export/import + first-launch seeder, or note in the body that the guide moved to the playbook.

🟢 Reserved agent IDs (itomek's #6, partial)

_AGENT_ID_RE in export_import.py:48 accepts export and import as valid IDs. Combined with the GET /api/agents/{agent_id:path} wildcard, GET /api/agents/export resolves to a 404 rather than a 405 — a user-created agent named export would silently shadow the endpoint's URL space in GET requests. Suggest adding export/import to the reserved-name set and a small router test that asserts they're rejected.

🟢 Silent except Exception in hot-register

routers/agents.py:215 catches Exception during live_registry.register_from_dir(...). It does log at warning, so the error isn't fully swallowed, but per CLAUDE.md "fail loudly" it should catch a narrower exception type — or if broad catch is intentional here (best-effort per-agent, don't take down the whole import), add a short comment to that effect.

Suggested next steps

1. Update PR description (agent not agents; drop the "Custom installer guide" claim).
2. Decide how to handle @itomek's Update installer and workflows/actions for CI/CD #1 — at minimum, document that the PyPI pin needs a bump in the same cycle as this merge, or switch the installer to install from a locally-built wheel.
3. Ship a minimal example under build/bundled-agents/ so the playbook's Zoo Agent flow actually works on a fresh install, plus a CI assertion that the dir is non-empty in the installer job.
4. Small, low-risk: add export/import to reserved agent IDs with a matching test.

Security + atomicity work is solid. The gaps are mostly delivery/integration, not the core new code.

cc @kovtcharov-amd @itomek

[itomek]

@itomek — thank you for the thorough Windows NSIS walkthrough. All six findings were read. Here's the disposition:

Addressed in commit 853f6a0:

• Use public Lemonade hybrid installer #2 (Export UI silent failure) — CustomAgentsSection.tsx now adds an unconditional console.error in both export and import catches, and the .danger-warning banner auto-scrolls into view when status.kind === 'error'.
• Update Documentation #5 (Bundled agents dir empty) — zoo-agent is now committed into build/bundled-agents/ (gitignore unblocked) so any fresh clone that runs npm run package:* will have a real demo agent seeded on first launch. The seeder also logs WARN (not INFO) when the dir is missing in a packaged build.
• Prevent Users from Installing Hybrid mode on Unsupported Systems #6 (Reserved-word route coverage) — TestRouteShadowing added to test_agents_router.py; assertions verify /export and /import resolve before the {agent_id:path} wildcard.

Out of scope for this PR:

• Update installer and workflows/actions for CI/CD #1 (Installer PyPI pin) — The amd-gaia[ui]==0.17.2 pin is a release-management concern: once this PR merges, cut 0.17.3 to PyPI, and subsequent installer builds pick it up automatically. No CI changes needed here.
• Update Driver Check #3 (NSIS silent-install crash) — Pre-existing bug that predates this PR. Tracked separately.
• Documentation update from v0.7.2 tag. #4 (gaia init MSI race) — Also pre-existing. Tracked separately.

[github-actions]

Summary

Well-executed security-first feature that delivers three tightly-integrated pieces: a gaia agent export/import flow, FastAPI endpoints with three layered guards (localhost + X-Gaia-UI + tunnel-inactive), and a crash-safe Electron first-launch seeder. Zip handling is defence-in-depth (streaming byte caps, per-entry symlink/absolute/traversal checks re-validated during extract, atomic temp-file staging with rollback). Test coverage is thorough — 14 Python bundle tests, 6 router guard tests, 2 route-shadowing tests, and 10+ Jest seeder tests — and the playbook MDX doubles as product documentation and architecture reference. The single most important thing to address before merge: the exporter walks rglob("*") without filtering __pycache__/ or hidden dev artefacts, which will bloat bundles and defeats the "review before sharing" warning for anyone whose agent has been run locally.

Issues Found

🟡 Important

1. Export includes __pycache__/, .pyc, and any other dev artefacts in agent dirs (src/gaia/installer/export_import.py:173)

agent_dir.rglob("*") sweeps everything. A user who ran their agent once will ship compiled bytecode; a user with a .env at ~/.gaia/agents/my-agent/.env ships their API keys. The .gitignore block in the repo blocks __pycache__ for the staged zoo-agent, but end-user ~/.gaia/agents/ has no such protection. This also undercuts the stated 500 MB cap — a heavy .venv/ accidentally left in an agent dir will trip the import limit for the recipient.

Minimal filter aligned with what the seeder would plausibly copy:

    # Skip common dev artefacts so bundles stay small and don't leak
    # bytecode / editor state / dotfiles the user didn't intend to ship.
    _EXPORT_SKIP_DIRS = {"__pycache__", ".git", ".venv", "venv", "node_modules", ".pytest_cache", ".mypy_cache"}
    _EXPORT_SKIP_SUFFIXES = {".pyc", ".pyo"}

    try:
        with zipfile.ZipFile(tmp_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
            zf.writestr(BUNDLE_JSON_NAME, json.dumps(manifest, indent=2))
            for agent_dir in agent_dirs:
                for file_path in sorted(agent_dir.rglob("*")):
                    if not file_path.is_file():
                        continue
                    rel = file_path.relative_to(agent_dir)
                    if any(part in _EXPORT_SKIP_DIRS for part in rel.parts):
                        continue
                    if file_path.suffix in _EXPORT_SKIP_SUFFIXES:
                        continue
                    arcname = f"{agent_dir.name}/{rel.as_posix()}"
                    zf.write(file_path, arcname=arcname)
        os.replace(tmp_path, output_path)

(Hoist the constants to module level — shown inline here for a one-shot diff.)

2. Doc/registry drift: YAML-manifest agents still work, but docs/guides/custom-agent.mdx now says only Python modules are supported (docs/guides/custom-agent.mdx:13, docs/guides/custom-agent.mdx:54)

src/gaia/agents/registry.py:211 still loads agent.yaml, _is_custom_agent_dir at src/gaia/installer/export_import.py:63 still treats YAML-only dirs as valid custom agents, and the YAML-registry tests in tests/ presumably still pass — but the guide was rewritten as if YAML is gone. Either:

• (a) Keep YAML working and restore a short "YAML manifest (legacy/declarative)" section so users with existing YAML agents don't think they're broken, or
• (b) Actually deprecate YAML: tighten _is_custom_agent_dir to agent.py only, add a one-release warning log when YAML is discovered, and note the removal plan in docs/guides/custom-agent.mdx.

The current state — YAML loads silently, docs pretend it doesn't exist, export bundles it anyway — is the worst of both worlds. Discussion-only; no concrete diff since this is a product decision for @kovtcharov-amd.

3. PR description references paths that don't exist in the diff

• "Custom installer guide (docs/guides/custom-installer.mdx)" — the guide is actually at docs/playbooks/custom-installer/index.mdx.
• "gaia agents export and gaia agents import" — the CLI subcommand is singular (gaia agent, see src/gaia/cli.py:2526, docs/reference/cli.mdx:353).

Not a code issue, but worth fixing the PR body before merge so the release-notes generator doesn't pick up wrong paths.

🟢 Minor

4. Redundant double-logging on every failed export/import branch (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx:1261-1264, :1350-1354)

Both console.error(...) and log.api.error(...) fire for the same error. log.api.error already writes to console in addition to the log buffer. Pick one — log.api.error is the project convention (see how refreshAgents at line 1219 uses only log.api.warn).

        } catch (err) {
            const message = err instanceof Error ? err.message : String(err);
            log.api.error('Agent export failed', err);
            flashStatus({ kind: 'error', message: `Export failed: ${message}` });
        }

(And the parallel change at line 1350 for import.)

5. Two sequential window.confirm() dialogs before the import actually happens (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx:1296, and the existing pattern at :1231)

Each window.confirm is a modal browser dialog that blocks the renderer. The Settings modal already uses a proper styled modal idiom elsewhere — consider replacing with an in-app confirm component for consistency. Not blocking, but worth a follow-up issue; native confirm() dialogs look jarring against the rest of the GAIA UI.

6. handle_agent_import CLI error path collapses specific errors into a generic "Error:" (src/gaia/cli.py:5734)

The broad except Exception after the tuple-caught (BadZipFile, KeyError, JSONDecodeError, UnicodeDecodeError) catches ValueError (e.g. the 1 MB manifest cap) and emits Error: {exc} with no context. Minor, since the message itself is user-facing — but print(f"Error: invalid bundle: {exc}", ...) (matching the tuple branch) would read more consistently. Consider adding ValueError to the specific-tuple catch.

7. Hardcoded backend port in API_BASE (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx:1177)

const API_BASE = window.location.protocol === 'file:'
    ? 'http://localhost:4200/api'
    : '/api';

This duplicates the same constant from services/api.ts — grep for localhost:4200 shows this is a convention, so not blocking, but a BACKEND_BASE_URL export from services/api.ts would eliminate one more place to update if the port ever moves.

8. readBundleAgentIds reimplements a zip central-directory parser in ~80 lines (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx:1454-1531)

It works and is annotated well, but browser bundles usually pull in fflate (~8 KB gzipped) or jszip for this. Since this is a best-effort pre-read that already falls back to "unable to read" on any parse error, the cost/risk tradeoff is a fair call — flagging for awareness, not as a blocker.

Strengths

• Security layering is textbook defence-in-depth. Pre-validation of zip entries (size/count/symlink/absolute/traversal) PLUS streaming byte counters during extraction that re-check limits per chunk, PLUS a defensive is_relative_to(staging_root) during extract that doubles up on the pre-check. Agent-ID regex mirrors the existing AgentManifest.validate_id so there's no semantic drift. Three endpoint guards (_require_localhost + _require_ui_header + _require_tunnel_inactive) are each independently necessary and composed cleanly via Depends([…]). Tunnel-inactive guard specifically blocks the data-exfil path that ngrok would otherwise open — good thinking.
• Atomicity across three write paths is consistent. Export uses tempfile.mkstemp + os.replace for crash-safety. Import stages every agent under a temp dir under agents_root (same filesystem → rename is atomic), moves each dir with rollback-via-backup on failure. Seeder uses <id>.partial/ → renameSync(<id>) → write .seeded sentinel last. Same pattern, three layers — easy to reason about.
• Route-shadowing test (tests/unit/chat/ui/test_agents_router.py::TestRouteShadowing) is exactly the right test to have. Catches the footgun where GET /{agent_id:path} could eat the named /export / /import routes — discriminates 403/404 vs 405 to prove resolution order without needing a happy-path fixture.
• Playbook is unusually useful — it's a product doc, an architecture doc, AND a troubleshooting runbook, with per-OS tabs, .seeded sentinel recovery steps, and a clear "when to use Path A vs Path B" table at the end.

Verdict

Approve with suggestions.

Issue 🟡1 (export filter) and 🟡2 (YAML docs drift) should be addressed — the first in this PR, the second either here or in an immediate follow-up. Everything else is minor polish. The core design is sound, the tests are comprehensive, and the security posture is rightly paranoid.

[github-actions]

Summary

Solid, security-conscious implementation of the agent export/import round-trip plus a first-launch bundled-agent seeder for installer builds. The zip hardening (per-file + aggregate streaming caps, symlink reject, path-traversal double-check, agent-id regex, atomic staging+backup), the three-guard HTTP surface (localhost + X-Gaia-UI + tunnel-inactive), and the crash-safe <id>.partial → rename protocol in the seeder are all well thought through and well tested.

Two things worth fixing before merge: (1) the bundled zoo-agent/agent.py diverges from the pattern every other agent uses — it will silently inherit global tool state from any agent loaded earlier; (2) the custom-agent guide now documents only Python agents, but AgentRegistry still loads YAML manifests and validates them through AgentManifest (Pydantic) — users on that code path now have no reference docs.

---

Issues Found

🟡 Important

1. Bundled Zoo Agent's _register_tools breaks the global-registry convention (src/gaia/apps/webui/build/bundled-agents/zoo-agent/agent.py:28)

_TOOL_REGISTRY in src/gaia/agents/base/tools.py:16 is module-global dict state. Every other agent that owns its tool surface (src/gaia/agents/builder/agent.py:157, the builder templates, and the YAML-manifest loader at src/gaia/agents/registry.py:393) clears the registry first so the agent doesn't inherit tools registered by a previously loaded agent in the same process. The bundled Zoo Agent uses pass, which means if another agent was imported first and registered tools (e.g. during registry discovery of multiple custom agents on startup), the Zoo Agent will be handed those tools when its instance spins up.

The guide example in docs/guides/custom-agent.mdx:253 correctly uses _TOOL_REGISTRY.clear(). The bundled code and the guide disagree with each other on this pattern, and the bundled version is the buggy one.

from gaia.agents.base.agent import Agent
from gaia.agents.base.console import AgentConsole
from gaia.agents.base.tools import _TOOL_REGISTRY


class ZooAgent(Agent):
    AGENT_ID = "zoo-agent"
    AGENT_NAME = "Zoo Agent"
    AGENT_DESCRIPTION = "A zookeeper who loves animals"
    CONVERSATION_STARTERS = [
        "Hello! What's happening at the zoo today?",
        "Tell me a fun fact about one of your animals.",
    ]

    def _get_system_prompt(self) -> str:
        return (
            "You are a funny and enthusiastic zookeeper! You work at the world's "
            "best zoo and every response you give includes a fun fact or a playful "
            "reference to one of your beloved zoo animals."
        )

    def _create_console(self) -> AgentConsole:
        return AgentConsole()

    def _register_tools(self) -> None:
        _TOOL_REGISTRY.clear()

Same fix also brings docs/playbooks/custom-installer/index.mdx:67 (the inline example) in line. Both copies of the Zoo Agent should match.

2. Guide removes YAML manifest docs while the feature is still live (docs/guides/custom-agent.mdx)

The rewrite removes the entire "Manual Creation: YAML Manifest" section (the full-manifest reference, tool table, Zoo YAML example, research-agent YAML example, validation-error accordion). But AgentRegistry._load_manifest_agent (src/gaia/agents/registry.py:311), AgentManifest (Pydantic schema), and KNOWN_TOOLS all still exist and are the documented preferred path in CLAUDE.md for agents that only need built-in mixins:

New agents are preferably registered via YAML manifests validated by Pydantic in src/gaia/agents/registry.py

Existing user agents in ~/.gaia/agents/<id>/agent.yaml will keep working, but a user who tries to author one now has no reference for the tools:, models:, mcp_servers:, conversation_starters: schema. Two acceptable paths:

• Keep the YAML section as a shorter reference (tool names, minimal manifest, full example), labelled as "Quickest path for zero-code agents."
• Or formally deprecate YAML: add a deprecation note in the guide, wire a DeprecationWarning into _load_manifest_agent, and leave the removal for a follow-up release so existing authored agents aren't orphaned.

Either is fine, but silently deleting the docs while the code path stays active is the worst of both worlds.

3. pr-files.txt and PR body disagree with the shipped CLI on the command name

The PR description calls out gaia agents export (plural) in the Summary; the actual CLI registered in src/gaia/cli.py:2527 is gaia agent export (singular), and that's what docs/reference/cli.mdx:346 and docs/playbooks/custom-installer/index.mdx:613 document. Code and docs agree — only the PR description is out of date. Update the description before merge so the changelog captures the right name.

🟢 Minor

4. copyDirRecursive has two different symlink policies depending on Node version (src/gaia/apps/webui/services/agent-seeder.cjs:129-152)

The fs.cpSync branch passes dereference: true, which follows symlinks and copies their targets. The hand-rolled fallback skips symlinks entirely (log("WARN", ...)). Both are defensible individually, but they produce different trees for the same input bundle. For a seeder whose stated invariant is "prevent out-of-tree references in ~/.gaia/agents/<id>/," skipping is the safer default everywhere. Since Electron 40 always has cpSync, you can either:

• Replace dereference: true with an explicit pre-walk that rejects/skips symlinks before calling cpSync, or
• Drop the fallback branch entirely (the code comment already says it shouldn't normally hit).

Not a blocker, but the inconsistency will surprise someone eventually.

5. Broad except Exception in the CLI import/export handlers (src/gaia/cli.py:5688, 5708, 5732, 5745)

Four except Exception as exc: # noqa: BLE001 blocks, each catching everything and printing f"Error: {exc}" before sys.exit(1). This is fail-loud enough (the user does see the error), but CLAUDE.md "No Silent Fallbacks" pushes for named exceptions so the traceback hierarchy stays meaningful. Every caller here throws either ValueError or zipfile.BadZipFile (already caught), plus OSError for filesystem issues. A single except (OSError, RuntimeError) after the ValueError branch would cover the realistic failure modes without the catch-all.

6. seeder.log grows unbounded (src/gaia/apps/webui/services/agent-seeder.cjs:99-107)

Every launch appends a line, even when seeding is a no-op ("already seeded — sentinel present"). Over the lifetime of an installed app that's one INFO line per agent per launch, forever. Consider either:

• Truncating seeder.log on each run (it's diagnostic, not audit), or
• Only logging the "seeded complete" summary at INFO and dropping the per-agent "skipping — already seeded" to DEBUG (dropped from the file).

7. .gitignore build/bundled-agents/ re-enable is fragile (.gitignore:8-14)

build/
# Allow committed demo agents in the installer staging dir
!src/gaia/apps/webui/build/
!src/gaia/apps/webui/build/bundled-agents/
!src/gaia/apps/webui/build/bundled-agents/**

Re-enabling a subpath of an ignored directory works, but src/gaia/apps/webui/build/ is also the npm build-output root (see electron-builder.yml's extraResources entries for dist/ under the same parent). A future npm run clean or a webpack config change that empties build/ will wipe the checked-in Zoo Agent. Consider moving bundled agents out of the build/ tree entirely — e.g., src/gaia/apps/webui/bundled-agents/ — and have electron-builder.yml extraResources point at that stable location. The seeder invariant (source = <resourcesPath>/agents) is unaffected.

8. _validate_zip_entries trusts header file_size (src/gaia/installer/export_import.py:1970)

Not a real hole — the extraction loop at src/gaia/installer/export_import.py:2089-2099 re-checks both bytes_written per file and total_written across the whole archive against the same caps, so a header-spoofed size gets caught. Worth a one-line comment above _validate_zip_entries noting it's a fast-reject pass and the extract loop is the authoritative enforcement. Future readers will otherwise wonder why the size check is duplicated.

9. CustomAgentsSection.tsx uses window.confirm for the trust gate (src/gaia/apps/webui/src/components/CustomAgentsSection.tsx:1232, 1296)

Native confirm() can't show an agent-ID list in a styled, scrollable region — if a bundle declares 20 agents the dialog truncates or overflows depending on OS. A proper modal built from the existing settings-modal primitives would read the full list, support per-agent opt-out, and match the rest of the UI. Not blocking for shipping, but flag it for the design backlog.

---

Strengths

• Security posture on the Python side is excellent. Aggregate + per-file zip-bomb caps enforced twice (fast reject on headers, authoritative counter during extraction), path-traversal double-check with is_relative_to, symlink bit check via external_attr >> 16, reserved-Windows-name list, agent-id regex reused from AgentManifest.validate_id, atomic staging + backup+restore on per-agent move failure. The error text change at src/gaia/installer/export_import.py:2132 that keeps OS paths out of HTTP responses while still logging them server-side is exactly the right pattern for CodeQL py/stack-trace-exposure.
• Three-guard HTTP surface is the right model. _require_localhost + _require_ui_header + _require_tunnel_inactive compose cleanly as FastAPI dependencies, each fails loud with a specific status (403/403/503), and TestExportImportSecurityGuards in tests/unit/chat/ui/test_agents_router.py proves every combination. TestRouteShadowing is a nice touch — catches the {agent_id:path} wildcard stealing /export if someone ever reorders the router.
• Seeder crash-safety is carefully designed. <id>.partial sibling → renameSync → .seeded sentinel last means a crash mid-copy leaves no state that future runs misread as either "user-owned" or "complete." The error-isolation loop (one failing agent doesn't block the others) plus the rollback-on-rename-failure branch in seedOneAgent covers the realistic failure modes. Tests at tests/electron/agent-seeder.test.cjs exercise every one of those branches on a real tmpdir sandbox.

---

Verdict

Request changes — Issue #1 (bundled Zoo Agent missing _TOOL_REGISTRY.clear()) is a small but real correctness bug that ships as the reference implementation users copy into their own bundles. Issue #2 (YAML guide deletion while the code path is live) leaves CLAUDE.md's stated preferred authoring path undocumented. Both are quick fixes. Everything else is minor and can follow in a separate PR.

Once #1 and #2 are addressed this is ready to merge.

[itomek]

Integration test: Windows 11, AMD Ryzen AI MAX+ 395 (Strix Halo), Python 3.12.12

Tested against PR source installed as editable package into ~/.gaia/venv, frontend from the PR-built NSIS installer.

✅ First-launch agent seeder

• agent-seeder.cjs ran on every GAIA launch
• Correctly detected zoo-agent/ as user-owned (directory existed without .seeded sentinel), logged WARN, skipped — expected per design
• zoo-agent bundled correctly at resources/agents/zoo-agent/agent.py in the installed app

✅ Export All (via UI)

• Clicked Export All → trust dialog: "Exported bundle contains your agent source files as-is. Any API keys, tokens, or credentials in agent.py will be included in the bundle. Review before sharing. Continue?"
• Clicked OK → native file-save dialog opened with gaia-agents-export.zip pre-filled in Downloads
• Zip saved (3,720 bytes): bundle.json + bob-the-zookeeper/agent.py ✓

✅ Import (via UI)

• Clicked Import → file picker → selected zip → trust dialog: "Importing this bundle will run third-party Python code on your machine when the agent is selected. Only import bundles from sources you trust. Agents to install: bob-the-zookeeper"
• Clicked OK → status: "Installed 1 agent(s): bob-the-zookeeper (replaced: bob-the-zookeeper) — restart required for replaced agents to take full effect" ✓

✅ Error banner (backend down)

• Killed backend → Export All → trust OK → inline error: "⚠ Export failed: Failed to fetch" ✓

---

🐛 Bug: PermissionError in _is_custom_agent_dir on Python 3.12.12 / Windows

export_import.py lines 93-97:

def _is_custom_agent_dir(path: Path) -> bool:
    return path.is_dir() and (
        (path / "agent.py").is_file() or (path / "agent.yaml").is_file()
    )

On Python 3.12.12 (uv-managed), Path.is_file() raises PermissionError: [WinError 5] Access is denied instead of returning False when the path is access-denied. My ~/.gaia/agents/ contained a link/ subdirectory with restricted NTFS permissions, causing every Export attempt to return 500 Internal Server Error.

Fix applied locally before testing could proceed:

def _is_custom_agent_dir(path: Path) -> bool:
    """A directory qualifies as a custom agent if it holds agent.py or agent.yaml."""
    try:
        return path.is_dir() and (
            (path / "agent.py").is_file() or (path / "agent.yaml").is_file()
        )
    except OSError:
        return False

Path.is_file() behaviour on permission-denied paths changed in Python 3.12. Recommend merging this fix before shipping.

[itomek]

Follow-up: seeder happy path verified (fresh ~/.gaia/agents/ directory)

To test the seeder's copy path (not just the skip path), I temporarily moved ~/.gaia/agents/ aside, created a fresh empty one, and relaunched GAIA.

Seeder log on relaunch:

[INFO] Seeded "zoo-agent" from ...resources/agents/zoo-agent to ~/.gaia/agents/zoo-agent
[INFO] Seeding complete — seeded=1 skipped=0 errors=0

Result:

• ~/.gaia/agents/zoo-agent/ created with agent.py ✓
• .seeded sentinel written with seededAt timestamp and source path ✓
• Zoo Agent appeared in the agent selector dropdown alongside Chat Agent ✓

Both seeder paths now confirmed:

• Fresh install (no prior zoo-agent/): seeder copies, writes .seeded, agent visible in UI ✓
• Existing directory without .seeded (user-owned data): seeder skips with WARN ✓

[itomek]

Integration Test Results — PR #795 (Windows 11 / AMD Ryzen AI MAX+ 395)

Test date: 2026-04-20
Tester: @itomek (automated via Claude Cowork)
Platform: Windows 11, AMD Ryzen AI MAX+ 395 w/ Radeon 8060S, 102 GB RAM
Installer built with: npm run package:win → electron-builder --win --config electron-builder.yml
Installer: gaia-agent-ui-0.17.2-x64-setup.exe (297.4 MB installed)

---

✅ NSIS Installer Wizard (fresh per-user install)

Walked through all four wizard pages:

1. License Agreement — MIT License, AMD copyright displayed correctly
2. Installation Options — "Only for me (tomas)" pre-selected; shows "Fresh install for current user only" — no UAC elevation required ✅
3. Choose Install Location — C:\Users\tomas\AppData\Local\Programs\gaia-desktop, 297.4 MB required ✅
4. Completing GAIA Setup — splash screen with GAIA Agent UI branding and AMD RYZEN AI logo; "Run GAIA" checkbox ticked; Finish launches the app ✅

---

✅ First-Launch Seeder — All Four Paths Tested

Scenario	seeder.log result
No resources/agents/ dir (old install)	No bundled agents directory — nothing to seed ✅
Agent present, no .seeded sentinel	Skipping "zoo-agent" — target exists without .seeded sentinel (treating as user-owned data) ✅
Agent absent (fresh user dir)	Seeded "zoo-agent" from resources/agents/zoo-agent to ~/.gaia/agents/zoo-agent ✅
Agent present + .seeded sentinel (reinstall)	Skipping "zoo-agent" — already seeded (sentinel present) ✅

The sentinel-based logic correctly distinguishes user-owned data from seeded data across all paths.

---

✅ Export/Import Round-Trip

Settings UI → Custom Agents section:

• Lists bob-the-zookeeper (custom_python) and zoo-agent (custom_python) ✅

Export All:

• Security warning shown: "Any API keys, tokens, or credentials in agent.py will be included. Review before sharing." ✅
• Save-as dialog pre-fills gaia-agents-export.zip ✅
• bundle.json content verified: format_version: 1, gaia_version: 0.17.2, agent_ids: ["bob-the-zookeeper", "zoo-agent"] ✅

Import:

• File picker filtered to *.zip ✅
• Pre-import security warning: "Importing this bundle will run third-party Python code. Only import bundles from sources you trust." Lists agents to install ✅
• Both agents restored to ~/.gaia/agents/ from zip ✅
• Settings UI reflects imported agents immediately ✅

---

🐛 Bug Found & Fixed: PermissionError in _is_custom_agent_dir (Windows / Python 3.12.x)

File: src/gaia/installer/export_import.py, _is_custom_agent_dir()

On Windows with Python 3.12.12, Path.is_file() raises PermissionError: [WinError 5] Access is denied instead of returning False for NTFS paths with restricted ACLs. Any ~/.gaia/agents/ subdirectory with restricted permissions causes POST /api/agents/export to return HTTP 500.

Fix applied:

def _is_custom_agent_dir(path: Path) -> bool:
    try:
        return path.is_dir() and (
            (path / "agent.py").is_file() or (path / "agent.yaml").is_file()
        )
    except OSError:
        return False

See earlier comment for full details.

---

⚠️ Doc Gap: build-ui-installer.ps1 not updated for Phase C (electron-builder)

installer/scripts/build-ui-installer.ps1 still calls electron-forge package and electron-forge make (steps 4 and 5). Since Phase C (this PR) migrates to electron-builder, the script would fail if run as documented. The script should be updated to call npm run package:win instead, or the README note should be promoted to a clear action item.

The installer README does include a note flagging this, but the script itself still contains the old commands and will fail with electron-forge: command not found.

---

Overall: PASS (with one bug fix needed and one doc gap to address)