refactor(hub): agent-first layout — hub/agents/<id>/<lang>

[kovtcharov-amd]

Closes #2019. Part of the Agent UI v2 milestone.

One agent's artifacts are scattered across language-first trees (email lives in both hub/agents/python/email/ and hub/agents/npm/agent-email/). This flips to agent-first — hub/agents/<id>/{python,npm}/ — so an agent's contract, binaries lock, clients, and specs travel together, and CI needs one path filter per agent instead of one per language×agent. Landing it now avoids every new per-agent v2 workflow hard-coding the old layout and widening the diff later.

History-preserving git mv of the python agents + npm/agent-email into hub/agents/<id>/<lang>/, with every live path reference updated (CI workflows/path filters, packaging/freeze scripts, the email sidecar lock-path resolution, tests, docs, .claude/skills/, CLAUDE.md). The npm package name @amd-gaia/agent-email and the gaia-agent-email wheel name are unchanged — only on-disk paths move.

Test plan

• git grep -nE 'hub/agents/(python|npm|cpp)' -- ':!*.lock' returns no live references.
• Release + publish CI green on a no-op agent change (proves the new path filters actually fire).
• Email sidecar still resolves its binaries lock from the new path.

Note: the breakdown-doc path rewrites are handled in #2058 (#2017) to avoid a same-file conflict, so this PR deliberately does not touch agent-ui-v2-implementation-breakdown.md.

[github-actions]

Verdict: Approve ✅

This is a clean, mechanical refactor that flips the hub layout from language-first (hub/agents/python/<id>/) to agent-first (hub/agents/<id>/python|npm/) via history-preserving git mv, so each agent's Python source, npm client, binaries lock, and docs live together. No behavior changes — only on-disk paths move; the npm package name and wheel name are unchanged.

The one thing that matters for a rename like this is completeness — a single missed path filter would silently stop a CI job from firing. I checked the committed head end-to-end and it's complete: zero stale hub/agents/{python,npm,cpp}/ references remain anywhere except the breakdown doc the description explicitly defers to #2058. CI path filters, install steps, packaging scripts, the email sidecar's runtime path resolution, and the stale-path guard test all moved together. Safe to merge.

🔍 Technical details

Completeness verification (on the PR head, not the dirty working tree):

• git grep -nE 'hub/agents/(python|npm|cpp)/' over the whole tree (excluding *.lock*) → 0 hits, save 3 in agent-ui-v2-implementation-breakdown.md, which the PR description intentionally leaves to docs(plans): superseded-model banners on sibling plans + v2 breakdown refresh #2058 to avoid a same-file conflict. ✔
• git mv landed: old hub/agents/{python,npm}/ top-level trees are gone; hub/agents/<id>/{python,npm}/ exist for email/chat/summarize/etc. ✔

Live surfaces correctly updated (spot-checked):

• CI path filters + working-directory + cache-dependency-path across all test_*_agent.yml, test_api.yml, test_electron.yml, test_security.yml, email_scorecard_refresh.yml, release_agent_email.yml (PKG_DIR/MANIFEST/README/SPEC/SKILL/FREEZE_DIST env + every python hub/agents/email/python/packaging/*.py invocation).
• Runtime path resolution: src/gaia/ui/email_sidecar/manager.py:83 (_default_email_src_dir) and platform.py:70 (default_lock_path) — parents[4] depth unchanged, only trailing components moved. ✔
• .github/dependabot.yml, .github/labeler.yml, util/list_agent_packages.py (AGENTS_DIR / id / "python"), and the test_no_stale_agent_paths / test_agent_pypi_publish guards all updated to match.

Minor note (non-blocking, no change requested): src/gaia/agents/base/errors.py:24 broadens the FRAMEWORK_PATHS entry from hub/agents/python/ to hub/agents/. That's correct for the new layout and the comment is updated; it now also matches hub/agents/<id>/npm/, which is harmless since those paths never appear in Python tracebacks.

Strengths:

• Genuinely complete — the hard part of a bulk rename is the long tail of path filters, and every one moved with the source. Verified by the repo's own test_no_stale_agent_paths guard, which was itself updated in lockstep.
• Docs, .claude/agents, .claude/skills, and CLAUDE.md were swept too, not just code — including the integrate-hub-agent skill's discovery instructions rewritten for the new <name>/<runtime> shape.
• Deferred the one conflicting doc to docs(plans): superseded-model banners on sibling plans + v2 breakdown refresh #2058 rather than forcing a same-file merge conflict, and called it out in the description.

[github-actions]

Dependency Review

The following issues were found:

• ❌ 1 vulnerable package(s)
• ✅ 0 package(s) with incompatible licenses
• ✅ 0 package(s) with invalid SPDX license definitions
• ⚠️ 22 package(s) with unknown licenses.
• ⚠️ 12 packages with OpenSSF Scorecard issues.

View full job summary

[github-actions]

🟡 The gaia agent init scaffold command was removed from the build-agent skill without a working replacement.

The .claude/skills/gaia-build-agent/SKILL.md previously gave a concrete, working command to scaffold a new hub agent into the old layout:

gaia agent init <id> -o hub/agents/python/

This PR correctly removes that command (it would now scaffold into the wrong location). But nothing replaces it. With the new hub/agents/<id>/python/ layout, there is no single gaia agent init invocation that produces the correct structure:

• gaia agent init <id> -o hub/agents/<id>/ → creates hub/agents/<id>/<id>/ (agent name repeated — wrong)
• gaia agent init python -o hub/agents/<id>/ → creates hub/agents/<id>/python/ but sets agent_id: python in all manifests (wrong id)

cmd_init (src/gaia/cli_agent.py:339) always appends names.id to the --output path, so the new layout can't be produced in one shot. Any Claude session following the gaia-build-agent skill to create a new hub agent will now silently scaffold in the wrong place.

The SKILL should document a working workaround until gaia agent init is updated (e.g., run gaia agent init <id> in a temp location, then mv <id>/ hub/agents/<id>/python/), or cmd_init needs a --subdir flag so gaia agent init <id> -o hub/agents/<id>/ --subdir python creates the correct tree.

🔍 Technical details

src/gaia/cli_agent.py:339-340:

parent = Path(args.output).expanduser().resolve()
pkg_dir = parent / names.id   # always <output>/<id>, never <output>/python

The SKILL change (-3/+1 at .claude/skills/gaia-build-agent/SKILL.md:31) removes:

`gaia agent init <id> -o hub/agents/python/` — and mirror an existing one

and replaces it with:

so the package lands at `hub/agents/<id>/python/` — and mirror an existing one

The description is correct but not actionable — there's no gaia agent init invocation that produces hub/agents/<id>/python/ with the right agent_id. The cleanest short-term fix is to add a workaround note to the SKILL pointing to an existing agent as a copy target (e.g., cp -r hub/agents/hello-world/python hub/agents/<id>/python && sed -i 's/hello-world/<id>/g' …), or open a follow-up to add --subdir to cmd_init.