refactor(agents): migrate code to hub (#1397, #1102) (#1421)

## Why this matters

CodeAgent was baked into the core `amd-gaia` wheel, so it could only
ship on the framework's release cycle and `RoutingAgent` hard-imported
the entire code stack at module load. After this change, **CodeAgent
ships as an independent `gaia-agent-code` wheel**
(`hub/agents/python/code/`), discovered via the `gaia.agent` entry-point
group like the other migrated agents. `RoutingAgent` stays in the
framework and now **resolves CodeAgent lazily through the registry**
(`AgentRegistry().create_agent("code", ...)`), so the core no longer
depends on the code package — and fails loudly with an actionable
install hint if the wheel is missing. Completes the `code` row of #1397
(legacy modernization) and #1102 (move production agents to
`hub/agents/`).

## Test plan

- [x] `python util/lint.py --agents` — clean (2 pre-existing docqa/emr
warnings, unrelated)
- [x] `python util/lint.py --black --isort --fix` — clean; `black
--check hub/agents/python/code/` clean
- [x] `uvx pylint src/gaia -E --rcfile .pylintrc --disable
C0103,C0301,W0246,W0221,E1102,R0401,E0401,W0718,W0212` — clean (only the
ignorable Windows `os.geteuid` E1101)
- [x] Framework decoupling: `pytest
tests/unit/agents/test_routing_agent.py
tests/unit/agents/test_registry.py
tests/unit/test_agent_required_connectors.py tests/unit/test_errors.py
tests/unit/test_code_index_mixin.py` — 144 passed
- [x] Migrated package (gated subset, mirrors `test_code_agent.yml`):
`pytest hub/agents/python/code/tests/test_code_agent_mixins.py
hub/agents/python/code/tests/test_code_agent.py::TestCodeAgent -k "not
workflow and not integration and not process_query"` + validators +
guardrails + `TestCodeAgentIntegration` — green
- [x] `gaia_agent_code.build_registration()` returns `id=code,
source=installed, namespaced_agent_id=installed:code`; `gaia-code`
console script resolves to `gaia_agent_code.cli:main`
- [x] `tests/test_api.py` + `tests/mcp/test_agent_mcp_server.py` collect
with no import errors (api_registry change is docstring-only)
- [x] Repo-wide grep: no stale `gaia.agents.code` imports remain (the
two `gaia/agents/code` strings in `errors.py` FRAMEWORK_PATHS are
intentionally kept, matching the jira/blender/docker migrations)

### Notes for the reviewer
- `tests/unit/cli/test_cli_smoke.py` may show a stale `gaia-code ->
gaia.agents.code.cli` entry **only** in a dev environment with a
previously editable-installed `amd-gaia` (the documented worktree
gotcha). A clean install picks up the updated `setup.py` (no
`gaia-code`) and passes.
- A few pre-existing, **non-gated** code tests still fail offline
(Context7 service in `test_external_tools`, `run_npm_command` registry
drift in `test_typescript_tools`, `process_query` LLM tests, and
`hasattr` assertions in the ungated `test_sdk` code-mixin checks). All
were verified to fail identically on `main`; fixing them is out of scope
for this migration.

Co-authored-by: Ovtcharov <kovtchar@amd.com>

Author: kovtcharov-amd

.github/workflows/publish.yml

@@ -442,7 +442,6 @@ jobs:
       - name: Verify CLI entry points
         run: |
           gaia --help
-          gaia-code --help
           gaia-mcp --help
           gaia-emr --help
 

.github/workflows/test_code_agent.yml

@@ -11,18 +11,18 @@ on:
   push:
     branches: [ main ]
     paths:
-      - 'src/gaia/agents/code/**'
+      - 'hub/agents/python/code/**'
       - 'src/gaia/agents/base/**'
-      - 'tests/test_code_agent*.py'
+      - 'src/gaia/agents/routing/**'
       - 'setup.py'
       - '.github/workflows/test_code_agent.yml'
   pull_request:
     branches: [ main ]
     types: [opened, synchronize, reopened, ready_for_review]
     paths:
-      - 'src/gaia/agents/code/**'
+      - 'hub/agents/python/code/**'
       - 'src/gaia/agents/base/**'
-      - 'tests/test_code_agent*.py'
+      - 'src/gaia/agents/routing/**'
       - 'setup.py'
       - '.github/workflows/test_code_agent.yml'
   merge_group:
@@ -59,6 +59,8 @@ jobs:
       - name: Install dependencies
         run: |
           uv pip install --system -e .[dev]
+          # CodeAgent ships as the standalone gaia-agent-code wheel (#1397, #1102)
+          uv pip install --system -e hub/agents/python/code
           # Install optional dependencies for code agent
           uv pip install --system black pylint
 
@@ -71,7 +73,7 @@ jobs:
           echo ""
 
           # Run mixin tests
-          python -m pytest tests/test_code_agent_mixins.py -v --tb=short
+          python -m pytest hub/agents/python/code/tests/test_code_agent_mixins.py -v --tb=short
 
           # Store the result
           MIXIN_TEST_EXIT=$?
@@ -93,9 +95,16 @@ jobs:
           echo ""
 
           # Run with pytest for better output formatting
-          python -m pytest tests/test_code_agent.py::TestCodeAgent -v --tb=short \
+          python -m pytest hub/agents/python/code/tests/test_code_agent.py::TestCodeAgent -v --tb=short \
             -k "not workflow and not integration and not process_query"
 
+          # Validators and write-guardrail tests (moved here from tests/unit and
+          # tests/ root during the hub migration; keep them gated).
+          python -m pytest \
+            hub/agents/python/code/tests/test_code_validators.py \
+            hub/agents/python/code/tests/test_file_io_guardrails.py \
+            -v --tb=short
+
       - name: Run Code Agent Integration Tests
         run: |
           echo ""
@@ -106,7 +115,7 @@ jobs:
           echo ""
 
           # Run integration tests
-          python -m pytest tests/test_code_agent.py::TestCodeAgentIntegration -v --tb=short
+          python -m pytest hub/agents/python/code/tests/test_code_agent.py::TestCodeAgentIntegration -v --tb=short
 
       - name: Run Code Agent Workflow Tests
         # Workflow tests invoke process_query which requires a running LLM.
@@ -122,7 +131,7 @@ jobs:
           echo ""
 
           # Run workflow tests with timeout
-          timeout 300 python -m pytest tests/test_code_agent.py -v --tb=short \
+          timeout 300 python -m pytest hub/agents/python/code/tests/test_code_agent.py -v --tb=short \
             -k "workflow or process_query or complete_workflow"
 
       - name: Test Summary

CLAUDE.md

@@ -463,10 +463,11 @@ Defined in [`setup.py`](setup.py) under `console_scripts`:
 |--------|-------------|---------|
 | `gaia` / `gaia-cli` | `gaia.cli:main` | Main CLI — all `gaia <subcommand>` |
 | `gaia-mcp` | `gaia.mcp.mcp_bridge:main` | Standalone MCP bridge binary |
-| `gaia-code` | `gaia.agents.code.cli:main` | CodeAgent standalone entry (NOT `gaia code`) |
 
 The `gaia-emr` console script now ships with the standalone `gaia-agent-emr` hub package (`hub/agents/python/emr/`), not the core wheel.
 
+`gaia-code` is no longer a core `console_scripts` entry — it ships with the standalone `gaia-agent-code` wheel (`hub/agents/python/code/`, entry point `gaia_agent_code.cli:main`).
+
 ## Architecture
 
 **See [`docs/reference/dev.mdx`](docs/reference/dev.mdx)** for detailed architecture documentation.
@@ -587,7 +588,7 @@ All commands are registered in [`src/gaia/cli.py`](src/gaia/cli.py). Run `gaia -
 - `gaia perf-vis` - Visualize performance results
 
 **Standalone binaries** (separate `console_scripts`, not subcommands):
-- `gaia-code` - CodeAgent entry (`src/gaia/agents/code/cli.py`)
+- `gaia-code` - CodeAgent entry, from the `gaia-agent-code` wheel (`hub/agents/python/code/gaia_agent_code/cli.py`)
 - `gaia-emr` - Medical intake entry (ships with the `gaia-agent-emr` hub package, `hub/agents/python/emr/gaia_agent_emr/cli.py`)
 - `gaia-mcp` - Standalone MCP bridge binary
 

docs/sdk/mixins/code-mixins.mdx

@@ -8,7 +8,7 @@ icon: "code"
 </Info>
 
 <Note>
-**Import:** `from gaia.agents.code.tools.cli_tools import CLIToolsMixin`
+**Import:** `from gaia_agent_code.tools.cli_tools import CLIToolsMixin`
 </Note>
 ---
 
@@ -24,7 +24,7 @@ icon: "code"
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.cli_tools import CLIToolsMixin
+from gaia_agent_code.tools.cli_tools import CLIToolsMixin
 
 class MyDevAgent(Agent, CLIToolsMixin):
     """Agent with CLI capabilities."""
@@ -46,15 +46,15 @@ result = agent.process_query("Run npm install and start the dev server")
 
 ## 13.2 CodeToolsMixin (Code Generation)
 
-**Import:** `from gaia.agents.code.tools.code_tools import CodeToolsMixin`
+**Import:** `from gaia_agent_code.tools.code_tools import CodeToolsMixin`
 
 **Detailed Spec:** [spec/code-tools-mixin](/spec/code-tools-mixin)
 
 **Purpose:** Code generation, scaffolding, and project templates.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.code_tools import CodeToolsMixin
+from gaia_agent_code.tools.code_tools import CodeToolsMixin
 
 class MyCodeAgent(Agent, CodeToolsMixin):
     """Agent with code generation."""
@@ -99,15 +99,15 @@ class MyAgent(Agent, FileIOToolsMixin):
 
 ## 13.4 ValidationToolsMixin (Code Validation)
 
-**Import:** `from gaia.agents.code.tools.validation_tools import ValidationToolsMixin`
+**Import:** `from gaia_agent_code.tools.validation_tools import ValidationToolsMixin`
 
 **Detailed Spec:** [spec/validation-tools-mixin](/spec/validation-tools-mixin)
 
 **Purpose:** Syntax checking, linting, and code quality validation.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.validation_tools import ValidationToolsMixin
+from gaia_agent_code.tools.validation_tools import ValidationToolsMixin
 
 class MyAgent(Agent, ValidationToolsMixin):
     """Agent with validation."""
@@ -124,15 +124,15 @@ class MyAgent(Agent, ValidationToolsMixin):
 
 ## 13.5 ErrorFixingMixin (Error Detection & Fixing)
 
-**Import:** `from gaia.agents.code.tools.error_fixing import ErrorFixingMixin`
+**Import:** `from gaia_agent_code.tools.error_fixing import ErrorFixingMixin`
 
 **Detailed Spec:** [spec/error-fixing-mixin](/spec/error-fixing-mixin)
 
 **Purpose:** Automatic error detection and intelligent fixing using LLM.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.error_fixing import ErrorFixingMixin
+from gaia_agent_code.tools.error_fixing import ErrorFixingMixin
 
 class MyAgent(Agent, ErrorFixingMixin):
     """Agent with error fixing."""
@@ -155,15 +155,15 @@ result = agent.process_query(
 
 ## 13.6 TestingMixin (Test Execution)
 
-**Import:** `from gaia.agents.code.tools.testing import TestingMixin`
+**Import:** `from gaia_agent_code.tools.testing import TestingMixin`
 
 **Detailed Spec:** [spec/testing-mixin](/spec/testing-mixin)
 
 **Purpose:** Test execution, coverage analysis, and test generation.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.testing import TestingMixin
+from gaia_agent_code.tools.testing import TestingMixin
 
 class MyAgent(Agent, TestingMixin):
     """Agent with testing."""
@@ -180,15 +180,15 @@ class MyAgent(Agent, TestingMixin):
 
 ## 13.7 PrismaToolsMixin (Database Setup)
 
-**Import:** `from gaia.agents.code.tools.prisma_tools import PrismaToolsMixin`
+**Import:** `from gaia_agent_code.tools.prisma_tools import PrismaToolsMixin`
 
 **Detailed Spec:** [spec/prisma-tools-mixin](/spec/prisma-tools-mixin)
 
 **Purpose:** Prisma ORM setup, schema generation, and database migrations.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.prisma_tools import PrismaToolsMixin
+from gaia_agent_code.tools.prisma_tools import PrismaToolsMixin
 
 class MyAgent(Agent, PrismaToolsMixin):
     """Agent with Prisma support."""
@@ -205,15 +205,15 @@ class MyAgent(Agent, PrismaToolsMixin):
 
 ## 13.8 TypeScriptToolsMixin (TypeScript Development)
 
-**Import:** `from gaia.agents.code.tools.typescript_tools import TypeScriptToolsMixin`
+**Import:** `from gaia_agent_code.tools.typescript_tools import TypeScriptToolsMixin`
 
 **Detailed Spec:** [spec/typescript-tools-mixin](/spec/typescript-tools-mixin)
 
 **Purpose:** TypeScript project setup, type checking, and compilation.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.typescript_tools import TypeScriptToolsMixin
+from gaia_agent_code.tools.typescript_tools import TypeScriptToolsMixin
 
 class MyAgent(Agent, TypeScriptToolsMixin):
     """Agent with TypeScript support."""
@@ -230,15 +230,15 @@ class MyAgent(Agent, TypeScriptToolsMixin):
 
 ## 13.9 WebToolsMixin (Web Development)
 
-**Import:** `from gaia.agents.code.tools.web_dev_tools import WebToolsMixin`
+**Import:** `from gaia_agent_code.tools.web_dev_tools import WebToolsMixin`
 
 **Detailed Spec:** [spec/web-tools-mixin](/spec/web-tools-mixin)
 
 **Purpose:** Frontend development with React, Vue, Svelte scaffolding and component generation.
 
 ```python
 from gaia.agents.base.agent import Agent
-from gaia.agents.code.tools.web_dev_tools import WebToolsMixin
+from gaia_agent_code.tools.web_dev_tools import WebToolsMixin
 
 class MyAgent(Agent, WebToolsMixin):
     """Agent with web dev tools."""

docs/spec/cli-tools-mixin.mdx

@@ -8,8 +8,8 @@ title: "CLIToolsMixin"
 
 <Note>
 **Component:** CLIToolsMixin
-**Module:** `gaia.agents.code.tools.cli_tools`
-**Import:** `from gaia.agents.code.tools.cli_tools import CLIToolsMixin`
+**Module:** `gaia_agent_code.tools.cli_tools`
+**Import:** `from gaia_agent_code.tools.cli_tools import CLIToolsMixin`
 </Note>
 ---
 
@@ -456,7 +456,7 @@ if not result["success"] and "port" in result:
     print(f"Port {result['port']} is in use by PID {result['blocking_pid']}")
 
     # Kill the blocking process
-    from gaia.agents.code.tools.cli_tools import kill_process_on_port
+    from gaia_agent_code.tools.cli_tools import kill_process_on_port
     if kill_process_on_port(result['port']):
         print("Killed blocking process, retrying...")
         result = agent.run_cli_command(...)
@@ -472,7 +472,7 @@ if not result["success"] and "port" in result:
 
 ```python
 import pytest
-from gaia.agents.code.tools.cli_tools import (
+from gaia_agent_code.tools.cli_tools import (
     CLIToolsMixin,
     is_port_available,
     find_available_port,

docs/spec/code-formatting-mixin.mdx

@@ -8,8 +8,8 @@ title: "CodeFormattingMixin"
 
 <Note>
 **Component:** CodeFormattingMixin
-**Module:** `gaia.agents.code.tools.code_formatting`
-**Import:** `from gaia.agents.code.tools.code_formatting import CodeFormattingMixin`
+**Module:** `gaia_agent_code.tools.code_formatting`
+**Import:** `from gaia_agent_code.tools.code_formatting import CodeFormattingMixin`
 </Note>
 ---
 

docs/spec/code-models.mdx

@@ -8,8 +8,8 @@ title: "Code Agent Models"
 
 <Note>
 **Component:** Code Agent Data Models (7 models)
-**Module:** `gaia.agents.code.models`
-**Import:** `from gaia.agents.code.models import CodeSymbol, ParsedCode, ProjectPlan, ValidationResult, ExecutionResult, ProjectStructure, WorkflowPlan`
+**Module:** `gaia_agent_code.models`
+**Import:** `from gaia_agent_code.models import CodeSymbol, ParsedCode, ProjectPlan, ValidationResult, ExecutionResult, ProjectStructure, WorkflowPlan`
 </Note>
 ---
 
@@ -173,7 +173,7 @@ class LintIssue:
 ### Example 1: Code Symbol Extraction
 
 ```python
-from gaia.agents.code.models import CodeSymbol, ParsedCode
+from gaia_agent_code.models import CodeSymbol, ParsedCode
 
 # Parse Python code
 code = '''
@@ -213,7 +213,7 @@ print(f"Found {len(parsed.symbols)} symbols")
 ### Example 2: Validation Workflow
 
 ```python
-from gaia.agents.code.models import ValidationResult
+from gaia_agent_code.models import ValidationResult
 
 # Validate generated code
 result = ValidationResult(
@@ -233,7 +233,7 @@ if result.file_modified:
 ### Example 3: Project Creation
 
 ```python
-from gaia.agents.code.models import ProjectPlan, ModuleSpec, TestSpec
+from gaia_agent_code.models import ProjectPlan, ModuleSpec, TestSpec
 
 # Create project plan
 plan = ProjectPlan(

docs/spec/code-tools-mixin.mdx

@@ -8,8 +8,8 @@ title: "CodeToolsMixin"
 
 <Note>
 **Component:** CodeToolsMixin
-**Module:** `gaia.agents.code.tools.code_tools`
-**Import:** `from gaia.agents.code.tools.code_tools import CodeToolsMixin`
+**Module:** `gaia_agent_code.tools.code_tools`
+**Import:** `from gaia_agent_code.tools.code_tools import CodeToolsMixin`
 </Note>
 ---
 
@@ -549,7 +549,7 @@ RETRY_MAX_TOKENS = 2048
 
 ```python
 import pytest
-from gaia.agents.code.tools.code_tools import CodeToolsMixin
+from gaia_agent_code.tools.code_tools import CodeToolsMixin
 
 def test_generate_function():
     """Test function generation."""

docs/spec/error-fixing-mixin.mdx

@@ -8,8 +8,8 @@ title: "ErrorFixingMixin"
 
 <Note>
 **Component:** ErrorFixingMixin
-**Module:** `gaia.agents.code.tools.error_fixing`
-**Import:** `from gaia.agents.code.tools.error_fixing import ErrorFixingMixin`
+**Module:** `gaia_agent_code.tools.error_fixing`
+**Import:** `from gaia_agent_code.tools.error_fixing import ErrorFixingMixin`
 </Note>
 ---
 

docs/spec/external-tools-mixin.mdx

@@ -8,8 +8,8 @@ title: "ExternalToolsMixin"
 
 <Note>
 **Component:** ExternalToolsMixin
-**Module:** `gaia.agents.code.tools.external_tools`
-**Import:** `from gaia.agents.code.tools.external_tools import ExternalToolsMixin`
+**Module:** `gaia_agent_code.tools.external_tools`
+**Import:** `from gaia_agent_code.tools.external_tools import ExternalToolsMixin`
 </Note>
 ---