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

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